Skip to content

Commit 985a836

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(fork-sync): a stopped sync workspace builds and its report keeps every stop (#1501)
## Problem A stopped sync left `.t3/fork-sync/worktree` without dependencies, so `tsc` was missing mid-conflict. A rerun that adopted a hand-finished rebase reported `conflicts: []`, losing every stop's rows. The report also carried a `rerere` block hard-coded to `false`. ## Change | Part | Change | | --- | --- | | Setup | a new sync worktree runs the `t3.json` `runOnWorktreeCreate` step (`scripts/setup-worktree.ts`) | | Setup env | the battery's scrubbed env plus `T3CODE_PROJECT_ROOT` and `T3CODE_WORKTREE_PATH` | | Skip done work | an adopted worktree never reruns setup | | Battery install | only when the tip changed the dependency set setup installed, or nothing was installed | | Linking | `linkInstalledModules` removed; setup's real install replaces it | | Stop rows | persist in `.t3/fork-sync/worktree.json` after each run | | Report | `conflicts[]` carries every stop on the kept worktree, in stop order | | Block issue | the subject line follows the blocking commit's row | | Schema | `rerere` removed from the report and the run | | Docs | fork-sync guide and skill | Stop rows live in the worktree state file, not the report. It shares the worktree's tag, target, and lease key and its lifetime. A crash run rewrites the report with `conflicts: []`, but leaves the state file. Rebased on #1500; its routes are unchanged. Its held-lockfile test now expects the carried `shared.txt` manual row. Two route-tree comments no longer claim the sync worktree has no `node_modules`. #1495 is not addressed. ## Scope and approval Closes #1490. Its Decision table sets the scope. ## Close conditions - [ ] **Setup test:** deps exist at the first stop - [ ] **Report test:** adopted stop keeps its rows - [ ] **Schema:** no `rerere` field ## Verification | Condition | Test | | --- | --- | | Setup | `runs the repo's worktree setup once, so the first stop already has its dependencies` | | Report | `stops at a conflict rerere and hooks cannot resolve, then applies after a hand resolution` | | Schema | `writes no rerere field and still reads a report that carries one` | | Install skip | `skips a second install when the tip kept the dependency set setup installed` | The real setup command in a detached `origin/hyprws` worktree exited 0 in 13.5s, leaving `node_modules/.bin/tsc`. In a set-up worktree, both generator routes exit 0: `vp install --lockfile-only` there, and `fork:regenerate-route-tree` from the root. <details><summary>Commands</summary> ```text vp run fork:ci → exit 0 vp run fork:delta --check → exit 0 vp run --filter @t3tools/scripts typecheck → exit 0 vp test run fork-sync.test.ts → exit 0 (57 passed) ``` </details> Claude Opus 5.5 in Claude Code. ## Fork trailers Squashes: - 982fe93 fix(fork-sync): a stopped sync workspace builds and its report keeps every stop (#1501) (#1501) - 63dae4d fixup! fix(fork-sync): a stopped sync workspace builds and its report keeps every stop (#1501) (#1501) Fork-Domain: fork-meta Fork-Tier: core Fork-Upstreamable: no Co-authored-by: donjor <[email protected]>
1 parent 61f197e commit 985a836

5 files changed

Lines changed: 274 additions & 139 deletions

File tree

‎.agents/skills/fork-sync/SKILL.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Post-push recovery reads this file, never a comment.
3131
| `target` | The tag and its sha |
3232
| `lease` | The `origin/hyprws` sha the push is leased against |
3333
| `trunk` | Trunk before and after the run |
34-
| `conflicts[]` | Path, fork commit, upstream commit, resolution route |
34+
| `conflicts[]` | Every stop's path, fork and upstream commit, route |
3535
| `checks[]` | Each battery command and its result |
3636
| `decision` | A stopped run's worktree, paths, and exact resume commands |
3737
| `decision.tip` | A red check's rebased tip, kept in the worktree |
@@ -103,6 +103,8 @@ Adaptation lands once, in one `Fork-Repair` commit at the tip; [`/fork-fold`](..
103103
5. Commit any adaptation there as one `Fork-Repair` commit at the tip.
104104
6. Rerun `vp run fork:sync <tag>`.
105105

106+
The worktree ran the `t3.json` setup step, so it builds and tests.
107+
If `rebase --continue` stops again, rerun first: the report keeps only stops a run saw.
106108
The rerun adopts the kept worktree and checks its HEAD.
107109
A resolved rebase still in progress continues; an unresolved one blocks again.
108110
A new tag or a moved lease recreates the worktree.

‎docs/fork/operations/fork-sync.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ A sync pushes the trunk directly, so no pull request runs `hyprws CI` before the
4040
| Push | only when every row is green; a red row leaves `hyprws` unmoved |
4141
| Report | each row names its CI job; the run's error lists every red one |
4242
| Env | umask `022`; no `T3_*` or `T3CODE_*` variable reaches a check |
43+
| Install | only when the tip changed the set the setup step installed |
4344

4445
`fork-fold` publishes only a tree-equal fold, so it inherits the same guarantee.
4546

@@ -67,7 +68,7 @@ Issue comments are projections of it: never parse one, and never treat an edit t
6768
| `target` | The tag and its sha |
6869
| `lease` | The fetched `origin/hyprws` sha the push is leased against |
6970
| `trunk` | Trunk before and after |
70-
| `conflicts[]` | Path, fork commit, upstream commit, how the row resolved |
71+
| `conflicts[]` | Every stop's path, fork and upstream commit, resolution |
7172
| `checks[]` | The check battery and each verdict |
7273
| `decision` | A blocked run's worktree, paths, and resume commands |
7374

@@ -111,7 +112,7 @@ Never post a block to `pingdotgg/t3code`.
111112
2. Open that worktree.
112113
3. Resolve per [the rule](#automatic-resolution).
113114
4. `git add` the resolved paths.
114-
5. `git rebase --continue`.
115+
5. `git rebase --continue` once.
115116
6. Rerun `vp run fork:sync <tag>`.
116117

117118
A pending regenerable file refuses step 5; skip it, and the rerun regenerates the file and continues.
@@ -123,6 +124,10 @@ Adaptation never lands inside a replayed commit; the hook guard (`scripts/lib/fo
123124
Commit it once, as one `Fork-Repair` commit at the tip of the kept sync worktree; a rerun on the same tag and lease adopts it.
124125
After the sync, the [`fork-fold`](../../../.agents/skills/fork-fold/SKILL.md) repair split dissolves it into its owners.
125126

127+
**Kept sync worktree.** Created through the `t3.json` setup step, so a stop has dependencies installed.
128+
It carries every stop's rows between runs, so the report keeps them.
129+
Rerun after each stop: the report records only the stops a run saw.
130+
126131
## Failure lifecycle
127132

128133
A run that fails on a non-blocked step (target, fetch, rebase, check, push, or a crash) rewrites one standing failure issue the same way a block does, through the same `gh` route.

‎scripts/fork-sync.test.ts‎

Lines changed: 92 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ const fixture = (options: {
9393
/** The fork branches from the tagged upstream commit instead of its base. */
9494
readonly forkOnTag?: boolean;
9595
readonly nightlyTag?: boolean;
96+
/** The base commit's t3.json worktree setup command; a no-op by default, as every fork checkout declares one. */
97+
readonly setup?: string;
9698
}): Fixture => {
9799
const base = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "fork-sync-test-"));
98100
const git = (args: ReadonlyArray<string>, cwd = base): string => {
@@ -116,6 +118,14 @@ const fixture = (options: {
116118
NodePath.join(repo, "shared.txt"),
117119
options.baseContent ?? "line1\nline2\nline3\n",
118120
);
121+
NodeFS.writeFileSync(
122+
NodePath.join(repo, "t3.json"),
123+
JSON.stringify({
124+
scripts: [
125+
{ name: "Setup Worktree", command: options.setup ?? "true", runOnWorktreeCreate: true },
126+
],
127+
}),
128+
);
119129
writeWorkflow(repo);
120130
for (const [path, content] of Object.entries(options.baseFiles ?? {}))
121131
NodeFS.writeFileSync(NodePath.join(repo, path), content);
@@ -293,13 +303,79 @@ it("stops at a conflict rerere and hooks cannot resolve, then applies after a ha
293303
assert.strictEqual(report.trunk.before, blocked.trunk.before);
294304
assert.notStrictEqual(report.trunk.after, report.trunk.before);
295305
assert.strictEqual(report.push.pushed, false);
296-
assert.strictEqual(report.conflicts.length, 0);
306+
// the hand-finished stop still reports its row
307+
assert.deepEqual(report.conflicts, blocked.conflicts);
297308
assert.strictEqual(report.checks.length, BATTERY_ROWS);
298309
for (const check of report.checks) assert.strictEqual(check.status, "passed");
299310
},
300311
);
301312
});
302313

314+
it("runs the repo's worktree setup once, so the first stop already has its dependencies", () => {
315+
withFixture(
316+
{
317+
forkContent: "line1\nline2 fork\nline3\n",
318+
upstreamContent: "line1\nline2 upstream\nline3\n",
319+
setup: "mkdir -p node_modules/.bin && touch node_modules/.bin/tsc",
320+
},
321+
(f) => {
322+
const shas = forkShas(f);
323+
const first = exec();
324+
capture(() => run(["v1.0.0"], { runner: first.runner, root: f.root }));
325+
assert.strictEqual(readReport(f.root, "v1.0.0").outcome, "blocked");
326+
assert.strictEqual(first.calls.filter(({ command }) => command === "sh").length, 1);
327+
assert.strictEqual(
328+
NodeFS.existsSync(NodePath.join(f.worktree, "node_modules/.bin/tsc")),
329+
true,
330+
);
331+
const state = JSON.parse(
332+
NodeFS.readFileSync(NodePath.join(NodePath.dirname(f.worktree), "worktree.json"), "utf8"),
333+
);
334+
assert.strictEqual(state.installed, shas.fork);
335+
336+
NodeFS.writeFileSync(
337+
NodePath.join(f.worktree, "shared.txt"),
338+
"line1\nline2 resolved\nline3\n",
339+
);
340+
f.git(["add", "shared.txt"], f.worktree);
341+
f.git(["-c", "core.editor=true", "rebase", "--continue"], f.worktree);
342+
343+
// the adopted rerun neither repeats the setup nor installs a second time
344+
const second = exec();
345+
const applied = capture(() =>
346+
run(["v1.0.0", "--dry-run"], { runner: second.runner, root: f.root }),
347+
);
348+
assert.strictEqual(applied.value, 0);
349+
assert.strictEqual(
350+
second.calls.some(
351+
({ command, args }) => command === "sh" || (command === "vp" && args[0] === "i"),
352+
),
353+
false,
354+
);
355+
},
356+
);
357+
});
358+
359+
it("writes no rerere field and still reads a report that carries one", () => {
360+
withFixture(
361+
{
362+
forkContent: "line1\nline2 fork\nline3\n",
363+
upstreamContent: "line1\nline2 upstream\nline3\n",
364+
},
365+
(f) => {
366+
capture(() => run(["v1.0.0"], { runner: exec().runner, root: f.root }));
367+
const path = reportPath(f.root, "v1.0.0");
368+
const written = JSON.parse(NodeFS.readFileSync(path, "utf8"));
369+
assert.notProperty(written, "rerere");
370+
NodeFS.writeFileSync(
371+
path,
372+
JSON.stringify({ ...written, rerere: { restored: false, saved: false, published: false } }),
373+
);
374+
assert.strictEqual(readReport(f.root, "v1.0.0").outcome, "blocked");
375+
},
376+
);
377+
});
378+
303379
it("refuses the push when the check battery is red and records the failing command", () => {
304380
withFixture(
305381
{
@@ -746,7 +822,10 @@ it("holds a generated path until the stop's manual paths resolve, then regenerat
746822
const applied = readReport(f.root, "v2.0.0");
747823
assert.deepStrictEqual(
748824
applied.conflicts.map(({ path, via }) => ({ path, via })),
749-
[{ path: LOCKFILE, via: "regenerate" }],
825+
[
826+
{ path: "shared.txt", via: "manual" },
827+
{ path: LOCKFILE, via: "regenerate" },
828+
],
750829
);
751830
assert.strictEqual(
752831
f.git(["show", `${applied.trunk.after}:${LOCKFILE}`], f.root),
@@ -937,7 +1016,6 @@ const blockedReport = (blockingSha: string): ForkSyncReport => ({
9371016
lease: { expectedOld: "2".repeat(40) },
9381017
trunk: { before: "2".repeat(40), after: null },
9391018
base: "3".repeat(40),
940-
rerere: { restored: false, saved: false, published: false },
9411019
conflicts: [
9421020
{
9431021
path: "apps/web/src/page.tsx",
@@ -979,7 +1057,6 @@ const failedReport = (step: string, key: string): ForkSyncReport => ({
9791057
lease: { expectedOld: "2".repeat(40) },
9801058
trunk: { before: "2".repeat(40), after: null },
9811059
base: "3".repeat(40),
982-
rerere: { restored: false, saved: false, published: false },
9831060
conflicts: [],
9841061
checks: [{ command: "vp run fork:delta --check", status: "failed", detail: "red" }],
9851062
decision: { worktree: "", paths: [], resume: "" },
@@ -1861,7 +1938,7 @@ it("records a non-empty detail tail when a streamed battery check fails", () =>
18611938
});
18621939

18631940
// ---------------------------------------------------------------------------
1864-
// linkInstalledModules vs a fresh install: the dependency-set skew guard
1941+
// The setup step's install vs a second one: the dependency-set skew guard
18651942
// ---------------------------------------------------------------------------
18661943

18671944
/** A minimal repo (no upstream/origin remotes) for the dependency-diff guard. */
@@ -1884,7 +1961,7 @@ const dependencyRepo = (): { readonly root: string; readonly worktree: string }
18841961
return { root, worktree };
18851962
};
18861963

1887-
it("installs fresh in the replay worktree when the target changed the lockfile", () => {
1964+
it("installs again in the replay worktree when the tip changed the lockfile since setup", () => {
18881965
const repo = dependencyRepo();
18891966
try {
18901967
const trunkSha = runCommand("git", ["rev-parse", "HEAD"], { cwd: repo.root }).stdout.trim();
@@ -1905,18 +1982,16 @@ it("installs fresh in the replay worktree when the target changed the lockfile",
19051982
const target: ReleaseTag = { tag: "v1.0.0", sha: targetSha };
19061983
const printed = capture(() => runChecks(runner, repo.root, repo.worktree, target, trunkSha));
19071984

1908-
assert.match(printed.output, /sync: dependency set changed on/);
1985+
assert.match(printed.output, /sync: dependency set changed since/);
19091986
const install = calls.find((call) => call.command === "vp" && call.args[0] === "i");
19101987
assert.notStrictEqual(install, undefined);
19111988
assert.deepStrictEqual(install!.args, ["i", "--frozen-lockfile"]);
1912-
// Neither module-linking side effect ran: the fresh install owns node_modules.
1913-
assert.strictEqual(NodeFS.existsSync(NodePath.join(repo.worktree, "node_modules")), false);
19141989
} finally {
19151990
NodeFS.rmSync(repo.root, { recursive: true, force: true });
19161991
}
19171992
});
19181993

1919-
it("links the trunk's install when the target left the dependency set alone", () => {
1994+
it("skips a second install when the tip kept the dependency set setup installed", () => {
19201995
const repo = dependencyRepo();
19211996
try {
19221997
const trunkSha = runCommand("git", ["rev-parse", "HEAD"], { cwd: repo.root }).stdout.trim();
@@ -1927,7 +2002,6 @@ it("links the trunk's install when the target left the dependency set alone", ()
19272002

19282003
assert.strictEqual(dependencySetChanged(realRunner, repo.root, trunkSha, targetSha), false);
19292004

1930-
NodeFS.mkdirSync(NodePath.join(repo.root, "node_modules"), { recursive: true });
19312005
const calls: Array<{ readonly command: string; readonly args: ReadonlyArray<string> }> = [];
19322006
const runner: CommandRunner = {
19332007
run: (command, args, spec) => {
@@ -1939,13 +2013,16 @@ it("links the trunk's install when the target left the dependency set alone", ()
19392013
const target: ReleaseTag = { tag: "v1.0.0", sha: targetSha };
19402014
const printed = capture(() => runChecks(runner, repo.root, repo.worktree, target, trunkSha));
19412015

1942-
assert.notMatch(printed.output, /sync: dependency set changed/);
2016+
assert.notMatch(printed.output, /installing/);
19432017
const install = calls.find((call) => call.command === "vp" && call.args[0] === "i");
19442018
assert.strictEqual(install, undefined);
1945-
// linkInstalledModules ran: the worktree's node_modules is now a symlink to the trunk's.
2019+
2020+
// a worktree no setup step installed gets the battery's own install
2021+
const bare = capture(() => runChecks(runner, repo.root, repo.worktree, target, null));
2022+
assert.match(bare.output, /nothing installed in the replay worktree/);
19462023
assert.strictEqual(
1947-
NodeFS.lstatSync(NodePath.join(repo.worktree, "node_modules")).isSymbolicLink(),
1948-
true,
2024+
calls.filter((call) => call.command === "vp" && call.args[0] === "i").length,
2025+
1,
19492026
);
19502027
} finally {
19512028
NodeFS.rmSync(repo.root, { recursive: true, force: true });

0 commit comments

Comments
 (0)