Skip to content

Commit 978268a

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(fork-sync): wait for setup, follow the trunk, root at the main checkout (#1835)
## Problem The latest `/fork-sync` audit lane hit snags that cost hand work. 1. A fresh worktree ran before setup finished 2. Local `hyprws` stayed behind after a push 3. Reruns from other checkouts lost sync state 4. `fork:fixup-fold` broke once upstream moved on 5. The skill missed two steps ## Change ### 1. Setup wait - **Preload:** `scripts/lib/await-setup.ts` - **Running:** waits on `.t3/setup-running` - **Failed:** exits 1 with the `setup-failed` tail ### 2. Trunk follow - **Clean checkout:** `reset --keep` to the tip - **No checkout:** `update-ref` - **Otherwise:** prints why, plus the sha Acts only when local `hyprws` sits at the lease. ### 3. Main checkout root The run resolves its root to the main checkout, so reports and the kept worktree live in one place for every lane. ### 4. Fixup fold base Replays from the merge base of `--base` (still `upstream/main`) and the head. ### 5. Skill and doc - Grep the lease sha before keeping a deletion - Run tests inside the package - Document the state home and trunk follow **Corrections:** the audit's `ci.url` finding was wrong: the field is `ci.run`, and it is set. **Cut as overbuilt:** an insertion resolver and a run lock; hook re-apply already covers reshaped owners. ## Scope and approval Fork tooling only, from the fork-sync audit; no app code changes. ## Verification | Command | Result | | --- | --- | | `vp test run` sync, setup, fixup-fold tests | 86 passed | | `vp run typecheck` | exit 0 | | `vp run fork:ci` | exit 0 | | `vp run check:changed` | exit 1, unrelated | **Unrelated failure:** `GitManager.test.ts` "includes CLAUDE.md for Claude writers only when it differs from AGENTS.md" fails alone on this base; no server code changed. New tests cover both trunk-follow paths, a rerun from inside the kept worktree, the setup wait, and the moved upstream base. Claude Opus 5.5, Claude Code in T3 Code. ## Fork trailers Squashes: - 78707fa fix(fork-sync): wait for setup, follow the trunk, root at the main checkout (#1835) (#1835) - 50ef483 fixup! fix(fork-sync): wait for setup, follow the trunk, root at the main checkout (#1835) (#1835) Fork-Domain: fork-meta Fork-Tier: bugfix Fork-Upstreamable: no Co-authored-by: donjor <[email protected]>
1 parent 3f3567c commit 978268a

9 files changed

Lines changed: 199 additions & 25 deletions

File tree

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

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ vp run fork:sync <tag> --dry-run
1919
```
2020

2121
`--dry-run` rebases and runs candidate CI, then stops: no trunk push, no issue, no publication.
22+
The run waits for the checkout's own worktree setup first.
2223
Any other flag is a defect.
2324
Name a tag only when the user names one; otherwise run with no tag.
2425

@@ -33,7 +34,8 @@ A moved lease or a new tag rebases again instead.
3334

3435
## Read the report
3536

36-
`.t3/fork-sync/<tag>.json` is the only run authority; the printed Markdown is output.
37+
`.t3/fork-sync/<tag>.json` in the main checkout is the only run authority; the printed Markdown is output.
38+
The kept sync worktree lives there too, whichever checkout runs the sync.
3739
Post-push recovery reads this file, never a comment.
3840

3941
Fields: [the report](../../../docs/fork/operations/fork-sync.md#the-report).
@@ -76,6 +78,8 @@ Resolve each seam by verdict, then follow Unblock.
7678
- **Red job**: `ci.jobs` names it
7779
- **Wait**: ends at the first failed job
7880
- **Real failure**: fix in the kept worktree
81+
- **Tests**: `vp test run` inside the package
82+
- **Fixup owner**: `vp run fork:fixup-fold`
7983
- **Flake**: `gh run rerun` after the run ends
8084
- **Never started**: check the mirror token
8185
- **Rerun**: the same command
@@ -96,6 +100,7 @@ Only a `manual` row stops the run.
96100

97101
In the rebase, resolve minimally: upstream's text stands, and a marked fork hook goes back verbatim.
98102
Upstream deleted and the fork edit is net-zero: the deletion stands.
103+
Before keeping an upstream deletion, grep the old trunk (`git grep <name> <lease sha>`): later fork commits are not replayed yet.
99104
A [regenerable file](../../../docs/fork/operations/fork-sync.md#regenerable-files) regenerates on the rerun.
100105
Never adapt inside a replayed commit: the hook guard refuses it.
101106
Adaptation lands at the tip, one commit per owner, per [Reshape](../../../docs/fork/operations/fork-sync.md#unblocking-by-hand).

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

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ The rebase refuses a rebased tip that dropped any PR link, except from a commit
2323
| ci | [candidate CI](#candidate-ci) on the rebased tip | the run is not green |
2424
| push | `--force-with-lease=hyprws:<fetched sha>` | lease refused |
2525
| blocked | one attention issue for any red run, via `gh` | `gh` refuses the write |
26-
| report | `.t3/fork-sync/<tag>.json`, typed, written before any post | |
26+
| report | the main checkout's `.t3/fork-sync/<tag>.json`, typed, before any post | |
2727

2828
A tag the fork already sits on reports `already applied`, after closing the open sync attention issue.
2929
`--dry-run` rebases and runs candidate CI, then stops: no trunk push, no issue, no close.
@@ -54,8 +54,9 @@ A candidate replays every fork commit, so stale-delete has nothing new to judge.
5454

5555
## Local trunk
5656

57-
A run publishes the rebased stack by force push to `origin/hyprws` under a lease; local clones see the rewrite only after `git fetch origin hyprws`.
58-
The local `hyprws` cannot follow a rewrite: `git pull --ff-only` refuses and leaves the stale branch in place.
57+
A run publishes the rebased stack by force push to `origin/hyprws` under a lease.
58+
After the push, local `hyprws` moves to the new tip when it still sits at the lease and its checkout has no tracked changes (`git reset --keep`).
59+
Otherwise the run prints why it kept the branch; `git pull --ff-only` cannot follow a rewrite.
5960
Reset it in the canonical checkout, then rerun whatever refused:
6061

6162
```bash
@@ -138,7 +139,9 @@ Commit it at the tip of the kept sync worktree; a rerun on the same tag and leas
138139
The next sync's rebase folds each fixup into its owner, and `fork:ci` proves it folds there, naming the owner when the fixup names the wrong one.
139140
Autosquash discards a fixup's body, so a reason worth keeping goes in its own commit.
140141

141-
**Kept sync worktree.** Created through the `t3.json` setup step, so a stop has dependencies installed; the local gate reinstalls the frozen lockfile first, since the rebase can move it.
142+
**Kept sync worktree.** Lives in the main checkout's `.t3/fork-sync`, whichever checkout runs the sync.
143+
`vp run fork:sync` first waits for the invoking checkout's own setup, so a fresh lane never races its install.
144+
Created through the `t3.json` setup step, so a stop has dependencies installed; the local gate reinstalls the frozen lockfile first, since the rebase can move it.
142145
It carries every stop's rows between runs, so the report keeps them.
143146
A red candidate, a green dry run, or a refused push keeps it, so its tip and tip fixups reach the next run.
144147
A new tag or moved lease rebases from scratch, then cherry-picks the old tip commits onto it.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@
5858
"fork:stale-delete": "node scripts/lib/fork-stale-delete.ts",
5959
"fork:fixup-fold": "node scripts/fork-fixup-fold.ts",
6060
"fork:ci": "node scripts/fork-ci.ts",
61-
"fork:sync": "node scripts/fork-sync.ts",
61+
"fork:sync": "node --import ./scripts/lib/await-setup.ts scripts/fork-sync.ts",
6262
"fork:regenerate-route-tree": "node scripts/lib/regenerate-route-tree.ts",
6363
"fork:upstream-refs": "node scripts/fork-upstream-refs.ts",
6464
"clean": "rm -rf node_modules apps/*/node_modules packages/*/node_modules apps/*/dist apps/*/dist-electron packages/*/dist .vite-plus apps/*/.vite-plus packages/*/.vite-plus",

‎scripts/fork-fixup-fold.test.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,13 @@ it("passes a stack whose fixups fold at their owners, squash suffix included", (
3737
commit(root, "later edit", { "file.txt": "ONE\ntwo\nTHREE\n" });
3838
commit(root, "fixup! owner edit (#2)", { "file.txt": "ONE!\ntwo\nTHREE\n" });
3939
assert.deepStrictEqual(fixupFoldFailures(root, base, "HEAD"), []);
40+
// Upstream moved past the stack's base: the default base still replays from the merge base.
41+
const tip = git(root, ["rev-parse", "HEAD"]);
42+
git(root, ["checkout", "--quiet", "--detach", base]);
43+
commit(root, "upstream later", { "file.txt": "uno\ntwo\nthree\n" });
44+
git(root, ["update-ref", "refs/remotes/upstream/main", "HEAD"]);
45+
git(root, ["checkout", "--quiet", "--detach", tip]);
46+
assert.deepStrictEqual(fixupFoldFailures(root, "upstream/main", "HEAD"), []);
4047
} finally {
4148
NodeFS.rmSync(root, { recursive: true, force: true });
4249
}

‎scripts/fork-fixup-fold.ts‎

Lines changed: 16 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,9 @@ const HELP = `Usage: vp run fork:fixup-fold [--base <ref>] [--head <ref>]
2222
Proves every fixup! commit in <base>..<head> folds into the commit it names.
2323
The sync rebase folds each fixup into its owner, so a fixup that only applies
2424
at the branch tip lands green in pull-request CI and then blocks the next
25-
sync (RSI-Software/t3code-hyprws#1554). The replay runs the stack from
26-
<base> in a throwaway repository with the sync's own fixup placement and
25+
sync (RSI-Software/t3code-hyprws#1554). The replay runs the stack from the
26+
merge base of <base> and <head> in a throwaway repository with the sync's own
27+
fixup placement and
2728
requires no stops and a tree equal to the unfolded tip. A stack without
2829
fixups skips the replay.
2930
`;
@@ -187,22 +188,20 @@ export const fixupFoldFailures = (
187188
git.run(["rev-parse", "--verify", `${ref}^{commit}`]).trim();
188189
const replay = new SystemGit(repo);
189190
replay.run(["checkout", "--quiet", "--detach", resolve(head)]);
190-
const result = runCommand(
191-
"git",
192-
[...REPLAY_CONFIG, "rebase", "-i", "--autosquash", resolve(base)],
193-
{
194-
cwd: repo,
195-
env: {
196-
...process.env,
197-
// Only the discarded replay commits need an identity; preserve the original authors.
198-
GIT_COMMITTER_NAME: "Fork Fixup Fold",
199-
GIT_COMMITTER_EMAIL: "[email protected]",
200-
GIT_EDITOR: "true",
201-
GIT_SEQUENCE_EDITOR: sequenceEditor(),
202-
[FIXUP_OWNERS_ENV]: JSON.stringify(fixups.owners),
203-
},
191+
// The merge base, not `base` itself: upstream may have moved past the commit the stack sits on.
192+
const onto = git.run(["merge-base", resolve(base), resolve(head)]).trim();
193+
const result = runCommand("git", [...REPLAY_CONFIG, "rebase", "-i", "--autosquash", onto], {
194+
cwd: repo,
195+
env: {
196+
...process.env,
197+
// Only the discarded replay commits need an identity; preserve the original authors.
198+
GIT_COMMITTER_NAME: "Fork Fixup Fold",
199+
GIT_COMMITTER_EMAIL: "[email protected]",
200+
GIT_EDITOR: "true",
201+
GIT_SEQUENCE_EDITOR: sequenceEditor(),
202+
[FIXUP_OWNERS_ENV]: JSON.stringify(fixups.owners),
204203
},
205-
);
204+
});
206205
if (result.status !== 0) {
207206
const stopped = replay.runResult(["rev-parse", "--verify", "REBASE_HEAD"]);
208207
const stoppedSha = stopped.status === 0 ? stopped.stdout.trim() : "";

‎scripts/fork-sync.test.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -774,6 +774,9 @@ it("pushes the candidate, waits for hyprws CI, then lease-pushes the same sha",
774774
const lease = recording.calls.find(isLeasePush);
775775
assert.include(lease!.args, `${tip}:hyprws`);
776776
assert.strictEqual(f.git(["rev-parse", "origin/hyprws"], f.root), tip);
777+
// The clean local trunk follows, checkout included.
778+
assert.strictEqual(f.git(["rev-parse", "hyprws"], f.root), tip);
779+
assert.strictEqual(f.git(["status", "--porcelain", "--untracked-files=no"], f.root), "");
777780
},
778781
);
779782
});
@@ -806,12 +809,20 @@ it("keeps the green tip on a refused push, and a rerun on the same lease publish
806809
assert.strictEqual(f.git(["rev-parse", "HEAD"], f.worktree), tip);
807810
assert.strictEqual(f.git(["rev-parse", "origin/hyprws"], f.root), shas.fork);
808811

809-
const code = capture(() => run(["v1.0.0"], { runner: exec().runner, root: f.root })).value;
812+
// A dirty trunk checkout keeps local hyprws where it was and says so. The
813+
// rerun starts inside the kept worktree it then drops.
814+
NodeFS.writeFileSync(NodePath.join(f.root, "shared.txt"), "local edit\n");
815+
const { output, value: code } = capture(() =>
816+
run(["v1.0.0"], { runner: exec().runner, root: f.worktree }),
817+
);
810818
assert.strictEqual(code, 0);
811819
const pushed = readReport(f.root, "v1.0.0");
812820
assert.strictEqual(pushed.outcome, "applied");
813821
assert.strictEqual(pushed.trunk.after, tip);
814822
assert.strictEqual(f.git(["rev-parse", "origin/hyprws"], f.root), tip);
823+
assert.strictEqual(f.git(["rev-parse", "hyprws"], f.root), shas.fork);
824+
assert.match(output, /local hyprws kept at .*: its checkout .* has local changes/);
825+
assert.isFalse(NodeFS.existsSync(f.worktree));
815826
},
816827
);
817828
});

‎scripts/fork-sync.ts‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,20 @@ export interface ForkSyncReport extends Schema.Schema.Type<typeof ForkSyncReport
291291

292292
const emptyDecision = (): DecisionRoute => ({ worktree: "", paths: [], resume: "" });
293293

294+
/**
295+
* The main checkout of the repository `cwd` belongs to. The sync runs from
296+
* there and keeps its state there, so a rerun from another lane, or from inside
297+
* the kept worktree it may drop, adopts the same state.
298+
*/
299+
const mainCheckout = (runner: CommandRunner, cwd: string): string => {
300+
const common = gitResult(runner, cwd, [
301+
"rev-parse",
302+
"--path-format=absolute",
303+
"--git-common-dir",
304+
]);
305+
return common.status === 0 ? NodePath.dirname(common.stdout.trim()) : cwd;
306+
};
307+
294308
export const reportPath = (root: string, tag: string): string =>
295309
NodePath.join(root, SYNC_DIR, `${tag}.json`);
296310

@@ -543,6 +557,36 @@ const dropWorktree = (runner: CommandRunner, root: string): void => {
543557
gitAllow(runner, root, ["worktree", "remove", "--force", worktreePath(root)]);
544558
};
545559

560+
/**
561+
* Move local hyprws to the pushed tip when it still sits at the lease, so the
562+
* next worktree does not start from a trunk the sync replaced. Checked out
563+
* somewhere (usually the main checkout), `reset --keep` moves that tree too
564+
* and only when its tracked files are clean. Anything else keeps the branch and
565+
* prints why: the push already succeeded, so this never fails the run.
566+
*/
567+
const followTrunk = (runner: CommandRunner, root: string, old: string, next: string): void => {
568+
const keep = (why: string): void => {
569+
process.stdout.write(`sync: local ${HYPRWS_BRANCH} kept at ${why}; reset it to ${next}\n`);
570+
};
571+
const local = gitResult(runner, root, ["rev-parse", "--verify", `refs/heads/${HYPRWS_BRANCH}`]);
572+
if (local.status !== 0) return;
573+
if (local.stdout.trim() !== old) return keep(`${local.stdout.trim()}, not the lease`);
574+
const checkout = git(runner, root, ["worktree", "list", "--porcelain"])
575+
.split("\n\n")
576+
.map((block) => block.split("\n"))
577+
.find((block) => block.includes(`branch refs/heads/${HYPRWS_BRANCH}`))?.[0]
578+
?.slice("worktree ".length);
579+
if (checkout === undefined) {
580+
gitAllow(runner, root, ["update-ref", `refs/heads/${HYPRWS_BRANCH}`, next, old]);
581+
return;
582+
}
583+
const status = gitResult(runner, checkout, ["status", "--porcelain", "--untracked-files=no"]);
584+
if (status.status !== 0 || status.stdout.trim() !== "")
585+
return keep(`${old}: its checkout ${checkout} has local changes`);
586+
const moved = gitResult(runner, checkout, ["reset", "--quiet", "--keep", next]);
587+
if (moved.status !== 0) keep(`${old}: ${moved.stderr.trim() || "reset --keep refused"}`);
588+
};
589+
546590
const stageContent = (
547591
runner: CommandRunner,
548592
worktree: string,
@@ -1760,7 +1804,6 @@ const USAGE = "usage: vp run fork:sync [<tag>] [--dry-run]";
17601804

17611805
export const run = (argv: ReadonlyArray<string>, options: RunOptions = {}): number => {
17621806
const runner = options.runner ?? realRunner;
1763-
const root = options.root ?? process.cwd();
17641807
const now = options.now ?? (() => new Date());
17651808
const startedAt = now();
17661809
let parsed;
@@ -1770,6 +1813,7 @@ export const run = (argv: ReadonlyArray<string>, options: RunOptions = {}): numb
17701813
process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n${USAGE}\n`);
17711814
return 1;
17721815
}
1816+
const root = mainCheckout(runner, options.root ?? process.cwd());
17731817
const dryRun = parsed.flags.has("--dry-run");
17741818
const explicit = parsed.positionals[0] ?? null;
17751819
// The failing step names the failure issue; it advances as the run does.
@@ -2019,6 +2063,7 @@ export const run = (argv: ReadonlyArray<string>, options: RunOptions = {}): numb
20192063
});
20202064
}
20212065
dropWorktree(runner, root);
2066+
followTrunk(runner, root, expectedOld, newSha);
20222067

20232068
// a clean run closes the block issues it made stale, whether the rebase
20242069
// moved the trunk or the trunk already sat on the target

‎scripts/lib/await-setup.test.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// @effect-diagnostics nodeBuiltinImport:off - the preload runs as its own Node process; fixtures need real ones.
2+
3+
import * as NodeChildProcess from "node:child_process";
4+
import * as NodeFS from "node:fs";
5+
import * as NodeOS from "node:os";
6+
import * as NodePath from "node:path";
7+
8+
import { assert, it } from "@effect/vitest";
9+
10+
const preload = NodePath.join(import.meta.dirname, "await-setup.ts");
11+
12+
/** The preload ahead of an entry that prints `entry ran`, in `cwd`. */
13+
const entry = (cwd: string) =>
14+
NodeChildProcess.spawn(
15+
process.execPath,
16+
["--import", preload, "-e", "console.log('entry ran')"],
17+
{ cwd, stdio: ["ignore", "pipe", "pipe"] },
18+
);
19+
20+
const finished = async (child: NodeChildProcess.ChildProcess) => {
21+
let stdout = "";
22+
let stderr = "";
23+
child.stdout?.on("data", (chunk) => (stdout += chunk));
24+
child.stderr?.on("data", (chunk) => (stderr += chunk));
25+
const code = await new Promise<number | null>((resolve) => child.on("close", resolve));
26+
return { code, stdout, stderr };
27+
};
28+
29+
it("holds the entry until a running setup exits", async () => {
30+
const cwd = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "await-setup-"));
31+
const setup = NodeChildProcess.spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"]);
32+
try {
33+
NodeFS.mkdirSync(NodePath.join(cwd, ".t3"));
34+
NodeFS.writeFileSync(NodePath.join(cwd, ".t3", "setup-running"), `${setup.pid}\n`);
35+
const waiter = entry(cwd);
36+
const result = finished(waiter);
37+
// The preload announces the wait while setup lives; only then does setup end.
38+
await new Promise((resolve) => waiter.stderr.once("data", resolve));
39+
setup.kill();
40+
const { code, stdout, stderr } = await result;
41+
assert.strictEqual(code, 0);
42+
assert.match(stderr, /waiting for worktree setup/);
43+
assert.strictEqual(stdout, "entry ran\n");
44+
} finally {
45+
setup.kill();
46+
NodeFS.rmSync(cwd, { recursive: true, force: true });
47+
}
48+
});
49+
50+
it("refuses the entry after a failed setup", async () => {
51+
const cwd = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "await-setup-"));
52+
try {
53+
NodeFS.mkdirSync(NodePath.join(cwd, ".t3"));
54+
NodeFS.writeFileSync(NodePath.join(cwd, ".t3", "setup-failed"), "vp i: exit 1\n");
55+
const { code, stdout, stderr } = await finished(entry(cwd));
56+
assert.strictEqual(code, 1);
57+
assert.match(stderr, /worktree setup failed[\s\S]*vp i: exit 1/);
58+
assert.strictEqual(stdout, "");
59+
} finally {
60+
NodeFS.rmSync(cwd, { recursive: true, force: true });
61+
}
62+
});

‎scripts/lib/await-setup.ts‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// @effect-diagnostics nodeBuiltinImport:off - preloaded before the entry's imports resolve, so only Node built-ins exist.
2+
3+
// A preload (`node --import`) that waits for the background worktree setup of the checkout it runs
4+
// in (`vp run` starts at the repo root). T3 marks a workspace ready while `scripts/setup-worktree.ts`
5+
// still installs, and an entry started then fails on unresolved imports without naming the cause.
6+
7+
import * as NodeFS from "node:fs";
8+
import * as NodePath from "node:path";
9+
import * as NodeTimersPromises from "node:timers/promises";
10+
11+
const markers = NodePath.join(process.cwd(), ".t3");
12+
const running = NodePath.join(markers, "setup-running");
13+
const failed = NodePath.join(markers, "setup-failed");
14+
15+
const runningPid = (): number | undefined => {
16+
let pid: number;
17+
try {
18+
pid = Number(NodeFS.readFileSync(running, "utf8").trim());
19+
} catch {
20+
return undefined;
21+
}
22+
try {
23+
process.kill(pid, 0);
24+
return pid;
25+
} catch {
26+
// A setup killed without its exit handler leaves a stale marker.
27+
return undefined;
28+
}
29+
};
30+
31+
let announced = false;
32+
for (let pid = runningPid(); pid !== undefined; pid = runningPid()) {
33+
if (!announced) process.stderr.write(`waiting for worktree setup (pid ${pid}) to finish\n`);
34+
announced = true;
35+
await NodeTimersPromises.setTimeout(1_000);
36+
}
37+
if (NodeFS.existsSync(failed)) {
38+
process.stderr.write(
39+
`worktree setup failed; fix it and rerun setup first:\n${NodeFS.readFileSync(failed, "utf8")}`,
40+
);
41+
process.exit(1);
42+
}

0 commit comments

Comments
 (0)