Skip to content

The lander must accept each owner-approved gate change before a PR merges (GST-2491) - #4304

Merged
capy-ai[bot] merged 9 commits into
mainfrom
merger-accepts-owner-gate-dispositions
Nov 12, 2026
Merged

capy-ai[bot] merged 9 commits into
mainfrom
merger-accepts-owner-gate-dispositions

Conversation

@garrytan

@garrytan garrytan commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

An unattended /ship can now finish a PR whose gate change the owner approved, and the person who lands the PR has to accept each such approval by id before it merges. This keeps crews shipping without a human in the loop while the merge decision stays with a separate actor, which is what Founderstar's lander asked for.

This supersedes #4302 and #4299 and builds on both. #4299 added gstack-approvals gate, the owner's recorded answer that closes one gate finding; credit to it for the recorder, the matcher and the disclosure lines. #4302 added the lander's acceptance, verify --pin, the writer hardening and the receipt's always-recorded set; credit to it for all of that. This PR carries #4302's head unchanged and adds the two fixes its last review found.

What changed

  • The lander decides. gstack-ship-queue land --pin works out the gate dispositions the approval store applies at the pin, prints each as a GATE_DISPOSITION: line, and merges only when the lander passes --accept-gate-disposition <approval id> for every one. It refuses with QUEUE_GATE_DISPOSITION when one isn't accepted, when an accepted id names nothing, or when the receipt or PR body leaves one out, changes one or invents one. It never trusts the receipt for this.
  • A check for landers that merge another way. gstack-ship-queue verify --pr <n> --pin <sha> [--accept-gate-disposition <id>]... runs the same function as land, read-only, and exits 0 only when every disposition is accepted.
  • The receipt always carries the applied set. gate_dispositions is always written, as [] when none applies, so a merger reading another state root, or a store that lost a row after the receipt, refuses instead of reading as nothing to accept. ready prints the dispositions it works out and refuses the same mismatches.
  • A rewritten branch no longer strands itself. In a full clone, a row whose head commit is gone (the branch was rewritten and garbage-collected, or the name reused) just doesn't apply, because the pin's history is all present and can't contain it. A pin missing from the clone refuses, and a shallow clone that can't prove a row's ancestry refuses and says to deepen it.
  • The writer is harder to misuse. gstack-approvals gate refuses while a /ship run is open on the branch in any worktree, checks and appends under a lock in the git common dir that /ship's preflight also takes, and refuses --gate-id undefined.
  • Hand-made rows are ignored. A disposition counts only with every field the writer writes, source: gate, the store's own branch and a digest over those fields. The digest catches edits; it isn't authentication.
  • Disclosure can't be skipped. gstack-ship-receipt write refuses while a disposition applies at HEAD unless --body carries each line.

Why

A lane runs as the same user as everything else on its machine, so it could write a disposition row itself. The real boundary is the separate actor who lands the PR: the hardening makes casual self-approval fail, and the lander's explicit acceptance authorizes the rest.

Blast radius

Only PRs with an owner gate disposition are affected; land, verify and ready print nothing new when the store holds none. A store that can't be read stops ready and land instead of reading as empty. A lander that merges through the REST API runs verify --pin first.

Test Coverage

test/ship-gate-dispositions.test.ts and test/ship-queue-land-direct.test.ts cover the writer, malformed rows, the receipt's disclosure and the lander's acceptance end to end. New here: a branch rewritten and garbage-collected so a recorded row's head is gone, where ready, verify, land and receipt write keep working with that row not applied; a pin missing from the clone refuses; a shallow clone refuses and says to deepen. test/gstack-ship-receipt-docs.test.ts now expects gate_dispositions as the receipt's last key.

Pre-Landing Review

Review notes (below the blocking floor)

  • Outside voice docs: add README and CLAUDE.md #1 (deferred): under train or legacy merge routes a disposition still clears a gate finding, but only land --pin and verify --pin enforce --accept-gate-disposition. gstack runs merge: direct, so this repository is not exposed; repositories on trains are.
  • Receipt write now refuses on a detached HEAD (no approval-store branch), where ruled notes treat it as none.
  • verify --pin does not check that --pr is numeric the way land does.
  • Acceptance trusts text the lane can write (design question; the docs already say the digest is not authentication).
  • The open-run refusal is reported under APPROVAL_RECORD_INVALID, whose summary talks about a missing field.
  • Coverage gaps: stale-lock reclaim, lock timeout, a malformed accept id, a missing pin.
  • Pass 2: a live /ship run past its 120-minute lease, or one resumed after a Capy machine sleep (capy-server restarts, so the lease reads stale), no longer counts as open, so its own runner could record a disposition; the lander's acceptance stays the boundary.
  • Pass 2: the 60 s lease-check timeout under the gate lock can outlast the lock's 60 s stale window.
  • Pass 2: the released-lease, dead-holder and failing-lease-check branches are untested; openRun leaves a live lease in the test run's shared GSTACK_LEASE_DIR.
  • Rulings (gstack-approvals rule) still refuse on any marker, so a parked run now blocks rulings but not gate dispositions.
  • Docs debt: crew/docs/captain.md's land table has no QUEUE_GATE_DISPOSITION row (an agent-loaded file, so adding it needs its own review).

Test change: the two existing marker tests in test/ship-gate-dispositions.test.ts now open a live lease (openRun) as well as writing the marker, because the fix counts a marker as an open /ship run only while its lease is open, the same test preflight uses; a marker alone now models a parked run, which a new test covers.

Documentation

Status: current. The docs match the code and no edits were needed (read-only audit).

Scope: 28 committed files from base 0ead11c to head 144fc4e (9 commits); nothing staged, unstaged or new. Read in full: the docs/ship-policy.md gate-dispositions and acceptance sections and the landing-checks row, the docs/troubleshooting.md QUEUE_GATE_DISPOSITION and gate-finding-open-unattended entries, ship/sections/pr-body.md and its .tmpl, the changelog.d fragment, and the source behind them (bin/gstack-approvals, bin/gstack-ship-queue, lib/gate-dispositions.ts).

Documentation health:

  • docs/ship-policy.md: current. The gate and dispositions commands, what they refuse, lander acceptance, verify and the receipt rules match the code.
  • docs/troubleshooting.md: current. Both anchors exist and match the code's fix text.
  • ship/sections/pr-body.md and pr-body.md.tmpl: current. The Gate disposition line is listed and the two copies match.
  • changelog.d/owner-approved-gate-changes-finish-unattended-ship.md: current (fragment; CHANGELOG was not touched).

Coverage debt: gstack-approvals gate, gstack-approvals dispositions and gstack-ship-queue land|verify --accept-gate-disposition are documented only as reference (ship-policy and troubleshooting). No how-to or captain landing guide (docs/captain.md, captain/SKILL.md.tmpl) mentions the acceptance step yet; consider /document-generate for these.

Diagram drift: none found.

Issues

Refs #4299
Refs #4302

Agent notes

GST-2491. Finish lane GSTA-523 (GStack Minder crew), successor to GSTA-518 and GSTA-520. Docs: docs/ship-policy.md#gate-disposition-acceptance, docs/troubleshooting.md#queue-gate-disposition.

Agent notes
{
  "schema_version": 1,
  "pr": 4304,
  "head": "144fc4e8e5930197bab2d2b4d4f2d03b33690dbd",
  "version": "1.99.1.0",
  "base": "main",
  "ci_carried": [
    {
      "lane": "tests",
      "run": 43134761001,
      "attempt": 1,
      "tree": "56a2db1f1073619a723e45803c13889a561b2cac"
    }
  ],
  "session_kind": "unattended",
  "head_tree": "56a2db1f1073619a723e45803c13889a561b2cac",
  "product_patch_id": "8c5ae706f6860b072e6f13ad443743e8af4e7f17",
  "gstack_version": "1.99.1.0",
  "review_depth": {
    "depth": "full",
    "class": "gate",
    "runtime_lines": 526,
    "rules": "66e5174161eecc2c",
    "base": "842fef1f958f72e0388c0a6b2bba0ffbb7e68aaa",
    "registry": "842fef1f958f72e0388c0a6b2bba0ffbb7e68aaa",
    "gate_scan": {
      "tagged": 0,
      "head": "144fc4e8e5930197bab2d2b4d4f2d03b33690dbd"
    },
    "reasons": [
      "gate-class",
      "risk:security",
      "runtime=526"
    ],
    "risk": [
      "security"
    ],
    "mode": "panel"
  }
}

garrytan and others added 8 commits November 11, 2026 20:59
…p (GST-2491)

An unattended /ship logs every gate finding open and nothing could close it, so a PR with an owner-approved gate change could never finish. gstack-approvals gate records the owner disposition outside the run; it closes only that fingerprint on a review row whose range holds the head, and finish, the receipt, the PR body and READY all carry it.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
… a dispositioned gate finding (GST-2491)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
… rest of /ship (GST-2491)

A disposition now names the finding's gate_id as well as its fingerprint, so a later loosening of the same line stays open. gstack-review-read shows a closed gate finding as kept with the disposition's approval id, so the existing --blocking-open, --gate-open, draft and Gate edits rules carry it without prose changes, and an unreadable approval record applies no disposition instead of failing the reader.

Review-Finding: p1/red-team#1 reader=red-team
Review-Finding: s11/outside-voice#1 reader=outside-voice
Review-Finding: s11/outside-voice#2 reader=outside-voice
Review-Finding: s11/adversarial-native#1 reader=adversarial-native
Review-Finding: s11/adversarial-native#2 reader=adversarial-native
Review-Finding: s11/adversarial-native#4 reader=adversarial-native
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…ng entries (GST-2491)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…ng (GST-2491)

Land and a new read-only verify --pin re-derive the dispositions the approval store applies at the pin and merge only with --accept-gate-disposition for each one. The gate writer refuses while any worktree holds an open /ship run on the branch, under a lock; a row counts only in the writer's full shape with its digest; receipt write needs --body when a disposition applies; ready and land cross-check the receipt and body against the store. Supersedes #4299.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…GST-2491)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
… disagrees at merge (GST-2491)

The receipt always carries gate_dispositions (an empty list when none apply) and write refuses on an unreadable store or a git error. Land, verify and ready refuse a receipt id the merge-time store lacks, naming the likely wrong state root or mirror, and a field-less receipt beside an applied row. A git ancestry error while deriving dispositions refuses instead of reading as not applied.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…expect the receipt to end with gate_dispositions (GST-2491)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@trunk-io

trunk-io Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

…un's ended lease stop blocking it (GST-2491)

Review-Finding: s11/outside-voice#3 reader=outside-voice
Review-Finding: s11/outside-voice#2 reader=outside-voice
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@capy-ai
capy-ai Bot merged commit b1f7830 into main Nov 12, 2026
82 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant