Skip to content

Commit 2cb66a3

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(fork-sync): reruns continue the rebase, fork:ci gates the candidate, tip commits survive a recreate (#1833)
## Problem The `v0.1.3-nightly` sync that landed `a4050c5` needed extra reruns and hand steps. ## Change | Snag | Fix | | --- | --- | | Hand `rebase --continue` skipped regeneration | Rerun continues the rebase | | Issue title renamed across reruns | Title names step and tag only | | Lint red found after an hour of remote CI | Local `fork:ci` gates the push | | Wait ran past a failed job | Returns at the first failed job | | Recreate dropped tip commits | Tip commits cherry-pick over | | Failed setup or pick lost the carry | Carry refs hold it until it lands | | Killed removal left state; reruns crashed | State goes first; ancestry check runs first | | Gate ran on pre-rebase deps | Frozen install runs before the gate | | Fixup owner rule unstated | Docs and skill name it | | CI `fork:fixup-fold` red on a blobless clone | Replay runs in a scratch repository | Unblock drops from six steps to five; a lease refusal is a plain rerun. ### Fixup-fold in CI CI's `blob:none` clone also fetches `sync/candidate`, which holds already-folded blobs. In a promisor clone, merge-ort skips writing a folded blob another ref already names, then the checkout lazy-fetches it; `GIT_NO_LAZY_FETCH=1` makes that fatal. The replay now runs in a throwaway `git init` that borrows the objects through `alternates` and has no promisor remote, so git writes the blob. No fixture reproduces the dedupe; proof is a runtime transcript on a fresh blobless clone of the failing head: | Code | Result | | --- | --- | | Before | fatal lazy fetch at `Rebasing (12/279)` | | After | exit 0 | `#1834` hits the same CI failure and goes green once this lands. ## Scope and approval Maintainer request: fix that sync's snags with fewer rounds and steps. ## Verification | Check | Exit | | --- | --- | | `vp test run scripts/fork-sync.test.ts` | 0 (77 passed) | | `vp run typecheck` in `scripts` | 0 | | `vp test run scripts/fork-fixup-fold.test.ts` | 0 (8 passed) | | `vp run fork:ci` | 0 | - **New test:** red local `fork:ci` refuses the push - **Recreate test:** both tip kinds carry - **Carry tests:** conflict, setup, killed removal - **Old driver:** fails all 5 new or changed tests - **Not run live:** the gate in a real sync worktree Claude Opus 5.5, Claude Code in T3 Code. ## Fork trailers Squashes: - d3d29df fix(fork-sync): reruns continue the rebase, fork:ci gates the candidate, tip commits survive a recreate (#1833) (#1833) - 436ae20 fixup! fix(fork-sync): reruns continue the rebase, fork:ci gates the candidate, tip commits survive a recreate (#1833) (#1833) Fork-Domain: fork-meta Fork-Tier: bugfix Fork-Upstreamable: no Co-authored-by: donjor <[email protected]>
1 parent 80b6e0f commit 2cb66a3

6 files changed

Lines changed: 441 additions & 176 deletions

File tree

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

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -72,22 +72,22 @@ Resolve each seam by verdict, then follow Unblock.
7272

7373
`hyprws CI` is not green on the candidate; the worktree keeps the tip.
7474

75+
- **Local gate**: `fork:ci` red; nothing pushed
7576
- **Red job**: `ci.jobs` names it
77+
- **Wait**: ends at the first failed job
7678
- **Real failure**: fix in the kept worktree
77-
- **Flake**: `gh run rerun` from `decision.resume`
79+
- **Flake**: `gh run rerun` after the run ends
7880
- **Never started**: check the mirror token
7981
- **Rerun**: the same command
8082
- **Never**: weaken a check
8183

8284
### Lease refusal
8385

8486
The expected-old lease lost; someone landed first.
85-
The worktree keeps the green tip; `decision.tip` names it.
8687

87-
- **Inspect**: the trunk
88-
- **Carry**: tip fixups from `decision.tip`
89-
- **Moved lease**: the rerun rebases again
90-
- **Rerun**: never `--force`
88+
- **Rerun**: it rebases the new trunk
89+
- **Carry**: automatic; tip commits cherry-pick
90+
- **Never**: `--force`
9191

9292
## Unblock
9393

@@ -96,9 +96,11 @@ Only a `manual` row stops the run.
9696

9797
In the rebase, resolve minimally: upstream's text stands, and a marked fork hook goes back verbatim.
9898
Upstream deleted and the fork edit is net-zero: the deletion stands.
99-
A [regenerable file](../../../docs/fork/operations/fork-sync.md#regenerable-files) regenerates; when one is pending, skip `git rebase --continue` and rerun.
99+
A [regenerable file](../../../docs/fork/operations/fork-sync.md#regenerable-files) regenerates on the rerun.
100100
Never adapt inside a replayed commit: the hook guard refuses it.
101101
Adaptation lands at the tip, one commit per owner, per [Reshape](../../../docs/fork/operations/fork-sync.md#unblocking-by-hand).
102+
The owner is the newest fork commit touching those lines; `fork:fixup-fold` names it.
103+
A fixup that edits an unmarked fork line marks it.
102104

103105
**Second block:** the same seam stops a second sync.
104106

@@ -114,15 +116,15 @@ Adaptation lands at the tip, one commit per owner, per [Reshape](../../../docs/f
114116
1. Read `decision`: worktree, paths, resume commands.
115117
2. Open that worktree.
116118
3. Resolve each path by the rule above.
117-
4. `git add` them; `git rebase --continue`.
118-
5. Commit any adaptation at the tip.
119-
6. Rerun `vp run fork:sync <tag>`.
119+
4. `git add` them.
120+
5. Rerun `vp run fork:sync <tag>`.
120121

122+
Never `git rebase --continue` or script a resolver: the rerun continues the rebase with every automatic resolver, and the report keeps only stops a run saw.
123+
Adaptation the candidate needs surfaces as a `ci` failure; commit it at the tip, then rerun.
124+
Watch the run's output live; candidate CI can take most of an hour.
121125
The worktree ran the `t3.json` setup step, so it builds and tests.
122-
If `rebase --continue` stops again, rerun first: the report keeps only stops a run saw.
123-
The rerun adopts the kept worktree and checks its HEAD.
124-
A resolved rebase still in progress continues; an unresolved one blocks again.
125-
A new tag or a moved lease recreates the worktree.
126+
A new tag or a moved lease recreates the worktree and carries its tip commits.
127+
A carried commit that conflicts stops like a rebase seam: resolve, `git add`, rerun.
126128

127129
Every blocked or failed run rewrites one standing sync attention issue (label `ci`).
128130
The newest open issue of either legacy title (`hyprws sync blocked` or `hyprws sync failed`) is adopted; surplus issues close with a pointer to it.

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

Lines changed: 27 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -36,15 +36,17 @@ The release gate needs the current `origin/hyprws` tip with a green `hyprws CI`
3636

3737
A sync pushes the trunk directly, so no pull request runs `hyprws CI` before the push; the candidate branch does.
3838

39-
| Rule | Contract |
40-
| ------ | --------------------------------------------------------- |
41-
| Branch | `sync/candidate`, force-pushed with the tip; unprotected |
42-
| Run | the full `hyprws CI` push run on that sha |
43-
| Reuse | a sha that already has a run reuses it; no second push |
44-
| Wait | gives up if no run starts in 5 minutes or ends in an hour |
45-
| Push | only the sha the run passed, under the lease |
46-
| Red | `hyprws` stays put; `ci.jobs` names each red job |
47-
| Scope | `fork:ci` scans from the new base and skips stale-delete |
39+
| Rule | Contract |
40+
| ------ | -------------------------------------------------------- |
41+
| Branch | `sync/candidate`, force-pushed with the tip; unprotected |
42+
| Run | the full `hyprws CI` push run on that sha |
43+
| Reuse | a sha that already has a run reuses it; no second push |
44+
| Gate | a new sha passes local `vp run fork:ci` before its push |
45+
| Wait | returns at the first failed job |
46+
| Limit | no run in 5 minutes, or none ending in an hour, is red |
47+
| Push | only the sha the run passed, under the lease |
48+
| Red | `hyprws` stays put; `ci.jobs` names each red job |
49+
| Scope | `fork:ci` scans from the new base and skips stale-delete |
4850

4951
A candidate replays every fork commit, so stale-delete has nothing new to judge.
5052

@@ -100,7 +102,7 @@ There is no "upstream superseded this" rule: retirement is a traced verdict writ
100102
## Attention issue lifecycle
101103

102104
Every red run (blocked or failed) rewrites one standing sync attention issue through plain `gh`, after writing its report.
103-
Its title reflects the latest stop; its body carries conflict and resume details or the failure and red jobs, plus the open-since date, target count, and last five runs.
105+
Its title names the step and target, so reruns never rename it; its body carries conflict and resume details or the failure and red jobs, plus the open-since date, target count, and last five runs.
104106

105107
The newest open `ci` issue matching `hyprws sync blocked` or `hyprws sync failed` is adopted, including legacy issues.
106108
Older matches close with a one-line pointer to the kept issue; only no match files a new one.
@@ -116,10 +118,9 @@ Never post a sync issue to `pingdotgg/t3code`.
116118
2. Open that worktree.
117119
3. Resolve per [the rule](#automatic-resolution).
118120
4. `git add` the resolved paths.
119-
5. `git rebase --continue` once.
120-
6. Rerun `vp run fork:sync <tag>`.
121+
5. Rerun `vp run fork:sync <tag>`.
121122

122-
A pending regenerable file refuses step 5; skip it, and the rerun regenerates the file and continues.
123+
Never continue the rebase by hand: the rerun continues it, so each later stop still gets every [automatic resolution](#automatic-resolution).
123124

124125
Rerere replays content resolutions but records nothing for a delete/modify: the fix is a driver rule or a pre-adopt commit on `hyprws` (precedent `72666ffe19`, RSI-Software/t3code-hyprws#1227).
125126

@@ -130,15 +131,19 @@ Commit it at the tip of the kept sync worktree; a rerun on the same tag and leas
130131
| Change | Commit |
131132
| ---------------- | -------------------------------------------------------- |
132133
| Owner adaptation | `fixup! <owner subject>` with the owner's trailers |
134+
| Owner | the newest fork commit touching those lines |
133135
| No single owner | one standalone `upstream-fixes` commit naming the change |
134136
| Retirement | its own commit, never inside a fixup body |
135137

136-
The next sync's rebase folds each fixup into its owner, and `fork:ci` proves it folds there.
138+
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.
137139
Autosquash discards a fixup's body, so a reason worth keeping goes in its own commit.
138140

139-
**Kept sync worktree.** Created through the `t3.json` setup step, so a stop has dependencies installed.
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.
140142
It carries every stop's rows between runs, so the report keeps them.
141143
A red candidate, a green dry run, or a refused push keeps it, so its tip and tip fixups reach the next run.
144+
A new tag or moved lease rebases from scratch, then cherry-picks the old tip commits onto it.
145+
`refs/fork-sync/carry/*` holds them until they land, so a failed setup or killed run loses none.
146+
A conflicting pick stays stopped in the worktree: resolve, `git add`, rerun.
142147
Rerun after each stop: the report records only the stops a run saw.
143148

144149
## Regenerable files
@@ -237,13 +242,13 @@ T3 Connect stays dark unless all four repository variables exist:
237242

238243
## Failure handling
239244

240-
| Failure | Response |
241-
| --------------------------- | ------------------------------------------------------------- |
242-
| **Mirror fails** | Recreate the token. Someone wrote `main`; never force |
243-
| **Trunk lease rejected** | `decision.tip` keeps the tip; inspect, rerun; never `--force` |
244-
| **Attention issue remains** | Resolve the reported stop; green closes it |
245-
| **Candidate CI red** | Fix in the kept worktree, or `gh run rerun --failed` a flake |
246-
| **Stable release fails** | Fix and rerun. Never move a published tag |
245+
| Failure | Response |
246+
| --------------------------- | ------------------------------------------------------------ |
247+
| **Mirror fails** | Recreate the token. Someone wrote `main`; never force |
248+
| **Trunk lease rejected** | Rerun; tip commits carry over; never `--force` |
249+
| **Attention issue remains** | Resolve the reported stop; green closes it |
250+
| **Candidate CI red** | Fix in the kept worktree, or `gh run rerun --failed` a flake |
251+
| **Stable release fails** | Fix and rerun. Never move a published tag |
247252

248253
## Version ordering caveat
249254

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

Lines changed: 8 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,6 @@ const commit = (root: string, subject: string, files: Record<string, string>): v
2525
git(root, ["commit", "--quiet", "--allow-empty", "-m", subject]);
2626
};
2727

28-
const worktreeCount = (root: string): number =>
29-
git(root, ["worktree", "list", "--porcelain"])
30-
.split("\n")
31-
.filter((line) => line.startsWith("worktree ")).length;
32-
3328
it("passes a stack whose fixups fold at their owners, squash suffix included", () => {
3429
const root = NodeFS.mkdtempSync(NodeOS.tmpdir() + "/fork-fixup-fold-");
3530
try {
@@ -42,8 +37,6 @@ it("passes a stack whose fixups fold at their owners, squash suffix included", (
4237
commit(root, "later edit", { "file.txt": "ONE\ntwo\nTHREE\n" });
4338
commit(root, "fixup! owner edit (#2)", { "file.txt": "ONE!\ntwo\nTHREE\n" });
4439
assert.deepStrictEqual(fixupFoldFailures(root, base, "HEAD"), []);
45-
// The throwaway replay worktree is gone again.
46-
assert.strictEqual(worktreeCount(root), 1);
4740
} finally {
4841
NodeFS.rmSync(root, { recursive: true, force: true });
4942
}
@@ -66,7 +59,6 @@ it("folds without configured Git identity and leaves the live repository unchang
6659
assert.strictEqual(git(root, ["rev-parse", "HEAD"]), tip);
6760
assert.strictEqual(git(root, ["config", "user.name"]), "");
6861
assert.strictEqual(git(root, ["config", "user.email"]), "");
69-
assert.strictEqual(worktreeCount(root), 1);
7062
} finally {
7163
NodeFS.rmSync(root, { recursive: true, force: true });
7264
}
@@ -86,10 +78,9 @@ it("hydrates a blob:none clone up front, so the replay never lazy-fetches", () =
8678
commit(origin, "fixup! owner edit", { "file.txt": "ONE!\ntwo\n" });
8779
git(root, ["clone", "--quiet", "--filter=blob:none", "--no-checkout", `file://${origin}`, "."]);
8880
identity(root);
89-
// The replay runs with lazy fetches off: every blob it reads, the base
90-
// tree's included, must already be local.
81+
// The replay repository has no promisor remote: every blob it reads, the
82+
// base tree's included, must already be local.
9183
assert.deepStrictEqual(fixupFoldFailures(root, base, "origin/main"), []);
92-
assert.strictEqual(worktreeCount(root), 1);
9384
} finally {
9485
NodeFS.rmSync(origin, { recursive: true, force: true });
9586
NodeFS.rmSync(root, { recursive: true, force: true });
@@ -112,12 +103,15 @@ it("reports Git's error when the replay fails before applying a commit", () => {
112103
"#!/bin/sh\necho 'fixture refuses replay' >&2\nexit 1\n",
113104
{ mode: 0o755 },
114105
);
115-
git(root, ["config", "core.hooksPath", hooks]);
106+
// The replay repository reads no live repository config, so the hook arrives through the environment.
107+
vi.stubEnv("GIT_CONFIG_COUNT", "1");
108+
vi.stubEnv("GIT_CONFIG_KEY_0", "core.hooksPath");
109+
vi.stubEnv("GIT_CONFIG_VALUE_0", hooks);
116110
const [failure] = fixupFoldFailures(root, base, "HEAD");
117111
assert.ok(failure?.includes("the replay failed before applying a commit"), failure);
118112
assert.ok(failure?.includes("fixture refuses replay"), failure);
119-
assert.strictEqual(worktreeCount(root), 1);
120113
} finally {
114+
vi.unstubAllEnvs();
121115
NodeFS.rmSync(root, { recursive: true, force: true });
122116
}
123117
});
@@ -145,7 +139,6 @@ it("keeps both Git stderr and a subprocess timeout error", () => {
145139
const [failure] = fixupFoldFailures(root, base, "HEAD");
146140
assert.ok(failure?.includes("replay progress"), failure);
147141
assert.ok(failure?.includes("spawnSync git ETIMEDOUT"), failure);
148-
assert.strictEqual(worktreeCount(root), 1);
149142
} finally {
150143
vi.restoreAllMocks();
151144
NodeFS.rmSync(root, { recursive: true, force: true });
@@ -169,9 +162,8 @@ it("refuses a fixup that only folds at the tip, naming fixup and owner", () => {
169162
assert.ok(failure?.includes('fixup "fixup! owner edit"'), failure);
170163
assert.ok(failure?.includes('owner "owner edit"'), failure);
171164
assert.ok(failure?.includes('name "later edit"'), failure);
172-
// The live checkout is untouched: the tip stands and the replay worktree is gone.
165+
// The live checkout is untouched: the tip stands.
173166
assert.strictEqual(git(root, ["rev-parse", "HEAD"]), git(root, ["rev-parse", "main"]));
174-
assert.strictEqual(worktreeCount(root), 1);
175167
} finally {
176168
NodeFS.rmSync(root, { recursive: true, force: true });
177169
}
@@ -204,7 +196,6 @@ it("skips the replay when the stack has no fixups", () => {
204196
const base = git(root, ["rev-parse", "main"]);
205197
commit(root, "plain fork commit", { "file.txt": "b\n" });
206198
assert.deepStrictEqual(fixupFoldFailures(root, base, "HEAD"), []);
207-
assert.strictEqual(worktreeCount(root), 1);
208199
} finally {
209200
NodeFS.rmSync(root, { recursive: true, force: true });
210201
}

0 commit comments

Comments
 (0)