Skip to content

Commit de9176b

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(fork-sync): the trunk moves only to a sha hyprws CI passed on sync/candidate (#1701)
## Problem A sync lease-pushed its rebased tip straight to `hyprws` after a local check battery. The battery approximated `hyprws CI` but never equalled it, so a green sync could still leave the trunk red and block the nightly. ## Change The sync driver now moves the trunk only to a sha that `hyprws CI` already passed. 1. Force-push the rebased tip to `sync/candidate` 2. Poll that sha's `hyprws CI` push run 3. Green: lease-push the same sha to `hyprws` 4. Red: `hyprws` stays; the worktree keeps the tip ### Driver - **Battery**: deleted, with `fork-ci-jobs.ts` - **Report**: `checks[]` becomes `ci` (schema v2) - **Reuse**: a sha's run, e.g. a dry run's green - **Flake**: resume names `gh run rerun --failed` - **Give-up**: no run in 5 min, or 1 h; wall time - **Retry**: same sha recreates the candidate ref ### CI and workflows - **Candidate `fork:ci`**: scans from the new base - **Stale-delete**: skipped; all commits replay - **`hyprws CI`**: runs on `sync/candidate` pushes - **Sync job**: gains `actions: read` - **Release**: unchanged; trigger filters `hyprws` ### Fixup-fold check Closes #1700: every `hyprws` PR's `Check` went red here. - **Cause**: lazy blob fetch mid-replay - **Symptom**: GitHub refuses it, `not our ref` - **Fix**: fetch the replay's blobs in one batch - **Replay**: runs with lazy fetches off ## Scope and approval Maintainer-directed in session: option A of the fork-sync audit (candidate branch, CI green, then trunk push). ## Verification - [x] **Focused tests**: 5 files, 92 passed - [x] **Driver**: order, reuse, retry, red, slow reads - [x] **Checks**: scripts typecheck, `fork:ci` exit 0 - [x] **Ledger**: synthetic candidate `rebased=true` - [x] **Fold**: CI-shaped clone, git 2.56, exit 0 twice - [ ] **Live**: candidate dry run after merge Claude Opus 5.5 via Claude Code in T3 Code. ## Fork trailers Squashes: - db464ee fix(fork-sync): the trunk moves only to a sha hyprws CI passed on sync/candidate (#1701) (#1701) - 88209b0 fixup! fix(fork-sync): the trunk moves only to a sha hyprws CI passed on sync/candidate (#1701) (#1701) Fork-Domain: fork-meta Fork-Tier: core Fork-Upstreamable: no Co-authored-by: donjor <[email protected]>
1 parent 287c2d7 commit de9176b

19 files changed

Lines changed: 698 additions & 1039 deletions

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

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ description: Sync RSI-Software/t3code-hyprws with upstream: pick a release tag,
55

66
# Fork sync
77

8-
One driver walks one upstream release tag end to end: fetch, rebase, check, push, blocked, report.
8+
One driver walks one upstream release tag end to end: fetch, rebase, ci, push, blocked, report.
9+
The trunk moves only to a sha `hyprws CI` passed on the `sync/candidate` branch.
910
A run has one exit code and one typed report.
1011
No modes, no gates, no lanes: a rerun of the same command is always the next move.
1112

@@ -17,7 +18,7 @@ vp run fork:sync <tag> # one named v… tag
1718
vp run fork:sync <tag> --dry-run
1819
```
1920

20-
`--dry-run` rebases and checks, then stops: no push, no issue, no publication.
21+
`--dry-run` rebases and runs candidate CI, then stops: no trunk push, no issue, no publication.
2122
Any other flag is a defect.
2223
Name a tag only when the user names one; otherwise run with no tag.
2324

@@ -26,7 +27,7 @@ A green dry run keeps its tip in the sync worktree for the real run:
2627
1. Dry run reaches `applied`
2728
2. `decision.tip` names the kept tip
2829
3. `vp run fork:sync <tag>` adopts it
29-
4. The battery reruns; the tip pushes
30+
4. Its green run is reused; the tip pushes
3031

3132
A moved lease or a new tag rebases again instead.
3233

@@ -42,9 +43,9 @@ Post-push recovery reads this file, never a comment.
4243
| `lease` | The `origin/hyprws` sha the push is leased against |
4344
| `trunk` | Trunk before and after the run |
4445
| `conflicts[]` | Every stop's path, fork and upstream commit, route |
45-
| `checks[]` | Each battery command and its result |
46+
| `ci` | The candidate's `hyprws CI` run, conclusion, and jobs |
4647
| `decision` | A stopped run's worktree, paths, and exact resume commands |
47-
| `decision.tip` | A red check's or green dry run's tip, kept in the worktree |
48+
| `decision.tip` | A red candidate's or green dry run's tip, in the worktree |
4849

4950
Never edit a report; a rerun supersedes it.
5051

@@ -54,7 +55,7 @@ Never edit a report; a rerun supersedes it.
5455
| ------------------------------- | ------------------------------- |
5556
| `failed` at `fetch` or `target` | [Environment](#environment) |
5657
| `blocked` with `manual` rows | [Conflict](#conflict) |
57-
| `failed` at `check` | [Check battery](#check-battery) |
58+
| `failed` at `ci` | [Candidate CI](#candidate-ci) |
5859
| `failed` at `push` | [Lease refusal](#lease-refusal) |
5960

6061
### Environment
@@ -75,14 +76,15 @@ Resolve each seam by verdict, then follow Unblock.
7576
| Reshape | Fork side moved too; resolve minimally, adapt at the tip |
7677
| Retire | Upstream owns it now; its own commit, never inside a fixup |
7778

78-
### Check battery
79+
### Candidate CI
7980

80-
The battery is red; the worktree keeps the rebased tip.
81-
A red `fork:ci` skips every later row.
81+
`hyprws CI` is not green on the candidate; the worktree keeps the tip.
8282

83-
- **Red job**: `checks[].job` names it
84-
- **Trunk-green fix**: by pull request
85-
- **Sync-only fix**: commit in the kept worktree
83+
- **Red job**: `ci.jobs` names it
84+
- **Real failure**: fix in the kept worktree
85+
- **Flake**: `gh run rerun` from `decision.resume`
86+
- **Never started**: check the mirror token
87+
- **Rerun**: the same command
8688
- **Never**: weaken a check
8789

8890
### Lease refusal

‎.github/workflows/hyprws-ci.yml‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,14 +20,17 @@ on:
2020
# workflow, so without this trigger a queued entry reports nothing and sits
2121
# until it times out.
2222
merge_group:
23+
# `fork:sync` pushes each rebased tip to `sync/candidate` and moves the
24+
# trunk only once this workflow is green on that exact sha.
2325
push:
2426
branches:
2527
- hyprws
2628
- "release/**"
29+
- sync/candidate
2730

2831
concurrency:
2932
group: hyprws-ci-${{ github.event.pull_request.number || github.ref }}
30-
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
33+
cancel-in-progress: ${{ github.event_name == 'pull_request' || github.ref == 'refs/heads/sync/candidate' }}
3134

3235
permissions:
3336
contents: read
@@ -71,8 +74,10 @@ jobs:
7174
node scripts/lib/fork-ci-flags.ts ledger --head "$HEAD_SHA" >> "$GITHUB_OUTPUT"
7275
7376
# Judge only this branch's commits: `since` is the ledger's trunk
74-
# merge base, so the stack below it stays out of scope.
77+
# merge base, so the stack below it stays out of scope. A sync
78+
# candidate authors none; every commit on it is replayed.
7579
- name: Fork stale-delete check
80+
if: steps.fork_ledger.outputs.rebased != 'true'
7681
env:
7782
HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
7883
SINCE: ${{ steps.fork_ledger.outputs.since }}
@@ -189,10 +194,6 @@ jobs:
189194
fi
190195
echo "merge-tree clean: no head-only conflicts"
191196
192-
# `fork:sync` runs every `test*` job below before it pushes the trunk,
193-
# reading each `vp` step from this file (scripts/lib/fork-ci-jobs.ts). Keep
194-
# a test step one plain `vp` command; any other shape stops the sync.
195-
#
196197
# Everything except `t3` (apps/server), `web`, and the fork's own
197198
# scripts suite; see upstream ci.yml for why `--parallel` is safe here.
198199
# Four pooled suites share a GitHub-hosted runner, so the fork widens the

‎.github/workflows/hyprws-release.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,7 @@ jobs:
182182
# the cut without failing the step, since the CI run being red is the
183183
# expected reason not to release, not a gate malfunction.
184184
- id: release_gate
185-
name: Gate the cut on the lease push and a green battery
185+
name: Gate the cut on the lease push and a green hyprws CI
186186
uses: actions/github-script@v8
187187
env:
188188
RELEASE_SHA: ${{ steps.release_ref.outputs.sha }}

‎.github/workflows/hyprws-upstream-sync.yml‎

Lines changed: 17 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
name: hyprws upstream sync
22

3-
# One driver runs one upstream release tag end to end: fetch, rebase, check,
4-
# push, blocked-issue and failure-issue publication, report. `fork:sync` is the
3+
# One driver runs one upstream release tag end to end: fetch, rebase, candidate
4+
# CI, push, blocked-issue and failure-issue publication, report. `fork:sync` is the
55
# whole state machine; this workflow only gives it credentials and a checkout.
66
# The push goes out under the documented expected-old lease, and a clean run
77
# closes the stale sync issues — block and failure alike — it made stale. A
88
# failed run files its issue inside the driver before it exits non-zero, so no
99
# `if: failure()` step exists here.
1010
#
11-
# The sync job's own push (the trunk) needs the
12-
# mirror PAT, because upstream commits touch .github/workflows, which
13-
# GITHUB_TOKEN may never push. The PAT reaches Git only through GIT_CONFIG_*,
14-
# exported around the driver step: check commands run rebased code, and the
15-
# driver scrubs those keys from everything it spawns there. The same PAT
16-
# checks out the trunk; the scrub step below removes it before any rebased
17-
# code can run.
11+
# The sync job's pushes (the candidate, then the trunk) need the mirror PAT:
12+
# upstream commits touch .github/workflows, which GITHUB_TOKEN may never push,
13+
# and only a PAT push starts hyprws CI on the candidate. The PAT reaches Git
14+
# only through GIT_CONFIG_*, exported around the driver step: the worktree
15+
# setup and regenerators run rebased code, and the driver scrubs those keys
16+
# from everything it spawns there. The same PAT checks out the trunk; the
17+
# scrub step below removes it before any rebased code can run.
1818

1919
on:
2020
push:
@@ -71,9 +71,11 @@ jobs:
7171
name: Sync
7272
needs: [mirror]
7373
runs-on: ubuntu-latest
74-
# The battery runs every hyprws CI test job one after another.
74+
# The driver waits up to an hour on hyprws CI for the candidate.
7575
timeout-minutes: 90
7676
permissions:
77+
# gh run list/view: the candidate's hyprws CI run
78+
actions: read
7779
contents: read
7880
issues: write
7981
steps:
@@ -137,12 +139,10 @@ jobs:
137139
git config rerere.enabled true
138140
git config rerere.autoupdate false
139141
140-
# The driver pushes the trunk with the mirror
141-
# PAT, built here so the token never lands in .git/config or a workflow
142-
# env block the check battery inherits. Its issue writes go through gh
143-
# with the job's own token (issues: write) and name the repository
144-
# themselves. No GH_REPO here: the battery inherits this env, and the
145-
# server's GitHub code under test defers to gh whenever GH_REPO is set.
142+
# The driver pushes the candidate and the trunk with the mirror PAT, built
143+
# here so the token never lands in .git/config or a workflow env block
144+
# rebased code inherits. Its CI reads and issue writes go through gh with
145+
# the job's own token and name the repository themselves.
146146
- name: Run the sync driver
147147
env:
148148
GH_TOKEN: ${{ github.token }}
@@ -158,23 +158,13 @@ jobs:
158158
set -e
159159
exit "$code"
160160
161-
# GitHub rejects a step summary over 1024k, and a run that reaches the
162-
# battery logs more. The driver prints its rendered report last, so the
163-
# log's tail carries the outcome, target, and battery rows.
164161
- name: Summarize the run
165162
if: always()
166163
run: |
167164
log="$RUNNER_TEMP/fork-sync.log"
168-
limit=900000
169165
{
170166
printf '## hyprws upstream sync\n\n'
171-
if [ -f "$log" ] && [ "$(stat -c %s "$log")" -gt "$limit" ]; then
172-
printf 'Log tail only; the step output keeps the full log.\n\n'
173-
printf '```\n'
174-
# Drop the tail's first line: the byte cut can split it.
175-
tail -c "$limit" "$log" | tail -n +2
176-
printf '```\n'
177-
elif [ -f "$log" ]; then
167+
if [ -f "$log" ]; then
178168
printf '```\n'
179169
cat "$log"
180170
printf '```\n'

‎docs/fork/internals/fork-delta.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,10 @@ vp run fork:scan --target vX.Y.Z # the same walk pinned to a tag
2727
`fork:scan` fails when a domain's own commits change a file its table omits and upstream also changed.
2828
Every code span in a Path cell is one pattern: `*` stays inside a segment, `**` spans them.
2929

30-
| Where | Mode | Against |
31-
| --------------------------------------------------------- | -------------------- | ----------------------- |
32-
| Fork CI | Blocking, every push | its upstream merge base |
33-
| The sync driver's check step (`hyprws-upstream-sync.yml`) | Blocking | the target tag |
30+
| Where | Mode | Against |
31+
| --------------------------- | ----------------------- | ----------------------- |
32+
| Fork CI | Blocking, every push | its upstream merge base |
33+
| Fork CI on `sync/candidate` | Blocking, before a sync | the target tag |
3434

3535
## Why the fork exists
3636

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

Lines changed: 24 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -19,33 +19,33 @@ The rebase refuses a rebased tip that dropped any PR link.
1919
| target | the named tag, or the newest release tag on `upstream` | the target is not a release tag |
2020
| fetch | `git fetch --tags upstream`, `git fetch origin hyprws` | fetch error |
2121
| rebase | detached worktree, `git rebase -i --autosquash --rerere-autoupdate <tag>` | a conflict rerere and hook re-apply cannot resolve |
22-
| check | the [check battery](#check-battery), in the worktree | any red |
22+
| ci | [candidate CI](#candidate-ci) on the rebased tip | the run is not green |
2323
| push | `--force-with-lease=hyprws:<fetched sha>` | lease refused |
2424
| blocked | one standing block issue, rewritten per run, through `gh` | `gh` refuses the write |
2525
| report | `.t3/fork-sync/<tag>.json`, typed, written before any post | |
2626

2727
A tag the fork already sits on reports `already applied`, after closing any open block or failure issue.
28-
`--dry-run` rebases and checks, then stops: no push, no issue, no close.
28+
`--dry-run` rebases and runs candidate CI, then stops: no trunk push, no issue, no close.
2929
A green dry run keeps its tip in the [sync worktree](#unblocking-by-hand); `decision.tip` names it.
30-
The real run on the same tag and lease adopts that tip, reruns the battery, and pushes it, with no second rebase.
30+
The real run on the same tag and lease adopts that tip, reuses its green run, and pushes it, with no second rebase.
3131
An applied run cuts the nightly by itself: `hyprws-ci.yml` completion triggers `hyprws-release.yml` through `workflow_run`.
32-
The release gate needs the current `origin/hyprws` tip with a green `hyprws CI`; a red battery cuts no release (RSI-Software/t3code-hyprws#1181).
32+
The release gate needs the current `origin/hyprws` tip with a green `hyprws CI` (RSI-Software/t3code-hyprws#1181).
3333

34-
## Check battery
34+
## Candidate CI
3535

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

38-
| Rule | Contract |
39-
| --------- | ----------------------------------------------------------------- |
40-
| Check job | `fork:ci`, then the Check job's own steps |
41-
| Test jobs | every `test*` job in `hyprws-ci.yml`, one row per matrix cell |
42-
| Derived | read from the replayed workflow; an unreadable step stops the run |
43-
| No skip | no flag drops a row |
44-
| Fail fast | a red `fork:ci` marks every later row `skipped` |
45-
| Push | only when every row is green; a red row leaves `hyprws` unmoved |
46-
| Report | each row names its CI job; the run's error lists every red one |
47-
| Env | umask `022`; no `T3_*` or `T3CODE_*` variable reaches a check |
48-
| Install | only when the tip changed the set the setup step installed |
38+
| Rule | Contract |
39+
| ------ | --------------------------------------------------------- |
40+
| Branch | `sync/candidate`, force-pushed with the tip; unprotected |
41+
| Run | the full `hyprws CI` push run on that sha |
42+
| Reuse | a sha that already has a run reuses it; no second push |
43+
| Wait | gives up if no run starts in 5 minutes or ends in an hour |
44+
| Push | only the sha the run passed, under the lease |
45+
| Red | `hyprws` stays put; `ci.jobs` names each red job |
46+
| Scope | `fork:ci` scans from the new base and skips stale-delete |
47+
48+
A candidate replays every fork commit, so stale-delete has nothing new to judge.
4949

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

@@ -74,7 +74,7 @@ Issue comments are projections of it: never parse one, and never treat an edit t
7474
| `lease` | The fetched `origin/hyprws` sha the push is leased against |
7575
| `trunk` | Trunk before and after |
7676
| `conflicts[]` | Every stop's path, fork and upstream commit, resolution |
77-
| `checks[]` | The check battery and each verdict |
77+
| `ci` | The candidate's `hyprws CI` run, conclusion, and jobs |
7878
| `decision` | A blocked run's or kept tip's worktree, paths, and resume |
7979

8080
Decisions persist to the report before any comment posts.
@@ -139,12 +139,12 @@ Autosquash discards a fixup's body, so a reason worth keeping goes in its own co
139139

140140
**Kept sync worktree.** Created through the `t3.json` setup step, so a stop has dependencies installed.
141141
It carries every stop's rows between runs, so the report keeps them.
142-
A green dry run or a refused push keeps it, so its tip and tip fixups reach the next run.
142+
A red candidate, a green dry run, or a refused push keeps it, so its tip and tip fixups reach the next run.
143143
Rerun after each stop: the report records only the stops a run saw.
144144

145145
## Failure lifecycle
146146

147-
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.
147+
A run that fails on a non-blocked step (target, fetch, rebase, ci, push, or a crash) rewrites one standing failure issue the same way a block does, through the same `gh` route.
148148

149149
| Rule | Detail |
150150
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -185,13 +185,14 @@ Conflict tables live in the block issue.
185185

186186
Create a fine-grained token owned by the automation actor, scoped to this repository, with read-and-write **Contents** and **Workflows**.
187187
Store it as the `HYPRWS_MIRROR_TOKEN` Actions secret.
188-
The workflow uses its own `GITHUB_TOKEN` with `issues: write`; never widen the token.
188+
Only its push of `sync/candidate` starts `hyprws CI`; a `GITHUB_TOKEN` push starts no workflow.
189+
The workflow uses its own `GITHUB_TOKEN` with `actions: read` and `issues: write`; never widen the token.
189190

190191
### Which events run the fork matrix
191192

192193
`hyprws-ci.yml` produces every context the `hyprws` ruleset requires: `Check`, `Test`, `Test Scripts`, `Test Web`, `merge-tree`, and three `Test Server` shards.
193194
`hyprws-body.yml` stays advisory: no ruleset requires its `Body` context.
194-
It runs on a pull request opened, pushed to, or reopened, on a push to a fork trunk or release branch, and on `merge_group`.
195+
It runs on a pull request opened, pushed to, or reopened, on a push to a fork trunk, release branch, or `sync/candidate`, and on `merge_group`.
195196

196197
It skips `ready_for_review`, already covered on that draft head.
197198
Add the `merge_group` trigger before requiring a queue in the ruleset.
@@ -253,7 +254,7 @@ T3 Connect stays dark unless all four repository variables exist:
253254
| **Trunk lease rejected** | `decision.tip` keeps the tip; inspect, rerun; never `--force` |
254255
| **A blocked issue remains** | Unblock by hand. Retirement needs a traced decision |
255256
| **A failure issue remains** | Inspect the report, fix, and rerun; the next clean run closes it |
256-
| **Check battery red** | Fix by pull request; never weaken a check |
257+
| **Candidate CI red** | Fix in the kept worktree, or `gh run rerun --failed` a flake |
257258
| **Stable release fails** | Fix and rerun. Never move a published tag |
258259

259260
## Version ordering caveat

0 commit comments

Comments
 (0)