release: v1.79.0.0 — CHANGELOG, VERSION, TODOS follow-ups

Queue-advanced to 1.79.0.0 (1.78.0.0 claimed in the workspace queue; same MINOR level per the versioning invariant). Entry references the class history (#497 → #2440 → Step 18). Three TODOS filed: PreToolUse hook enforcement, structural ship-mode for document-release, cross-host dispatch semantics audit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-09 14:38:59 +02:00 · 2026-09-01 17:33:59 +00:00
parent da8733fe0c
commit 4bce28d752
6 changed files with 90 additions and 10 deletions
@@ -1,5 +1,49 @@
 # Changelog

+## [1.79.0.0] - 2026-09-01
+
+**/ship can no longer be stranded by a backgrounded subagent.**
+**The bug class that came back twice is pinned everywhere it lives.**
+
+Claude Code v2.1.198 made Agent-tool subagents launch in the background by default. Four /ship steps (7, 8, 10, 18) hand work to a subagent and parse its final line as JSON, and none of them passed `run_in_background: false`, so a ship run could park forever on Step 18 waiting for doc-sync output that was never coming. This is the third time this class has bitten (#497 fixed it, #2440 regressed it, Step 18 rediscovered it). Every synchronous dispatch site in the skill tree now carries the explicit flag, and the flag is test-pinned per file so a fourth recurrence fails CI the moment it lands.
+
+The doc-sync dispatch also got real failure handling. If the dispatch gets backgrounded anyway, the parent polls for about 10 minutes, stops the runaway task, reconciles any commit the subagent made against the pre-dispatch HEAD, and ships the PR without the Documentation section instead of hanging. The subagent itself is scope-guarded to docs only: it never changes VERSION, never merges the base branch, skips the Codex doc review (the parent owns review passes), and reports a rejected push as `pushed:false` for the parent to reconcile.
+
+### The numbers that matter
+
+Source: `test/run-in-background-guidance.test.ts` (the pin list) and `grep -rl 'run_in_background: false' --include='*.md'` against this tree.
+
+| Metric | Before | After | Δ |
+|---|---|---|---|
+| Generated files pinned to carry the flag | 2 | 24 | every sync dispatch site |
+| /ship dispatch steps with a deadline + recovery branch | 0 of 4 | 4 of 4 | Steps 7/8/10/18 |
+| /ship Step 18 worst-case wait | unbounded | ~10 min | then documented recovery |
+| Codex doc review inside a ship-dispatched doc-sync | ~5-10 min per ship | skipped | parent owns reviews |
+| Headless gates that could mutate VERSION mid-ship | 2 | 0 | Step 8.3/8.4d resolve to Skip |
+
+The unbounded-to-10-minutes number is the one you feel: the failure mode changes from "my ship run has been sitting there for an hour" to a printed recovery line and a PR that still lands.
+
+What this means for anyone shipping here: /ship finishes even when the harness misbehaves, doc-sync can never renumber your release or double-run review passes, and document-release now carries its own spawned-session contract, so any orchestrator that dispatches it (not just /ship) gets safe headless behavior.
+
+### Itemized changes
+
+#### Added
+- **Deadline + recovery on every /ship dispatch step.** Steps 7 and 8 fall back to the inline audit if the subagent never completes (~10 min); Step 10 records Greptile triage as UNAVAILABLE rather than pretending zero comments; Step 18 stops the runaway task, pushes any orphaned docs commit (with an explicit second-failure branch when the remote moved), surfaces stray staged edits, and proceeds without the Documentation section. No step ever silently parks the run.
+- **A spawned-dispatch contract in document-release itself.** Detected strictly from the dispatch prompt or the preamble's `SESSION_KIND: spawned` echo (never from file content, which is treated as prompt injection). Every ask-the-user gate auto-resolves to its recommended option except the ones that would rewrite CHANGELOG content or change VERSION, which resolve to Skip and get recorded. Step 8.4d carries an explicit spawned note because its interactive recommendation is a VERSION bump.
+- **Docs-sync scope guard in /ship's dispatch prompt**: docs only, no base-branch merges, no version renumbering, no Codex doc review, push rejections reported instead of resolved.
+- Three follow-ups filed in TODOS.md: PreToolUse hook enforcement of the flag (structural fix), a capability-narrowed ship-mode for document-release, and a cross-host dispatch semantics audit.
+
+#### Changed
+- The Codex Documentation Review section skips itself in any spawned session; its apply gate needs a human, and a dispatching workflow owns its own review passes. Covers version skew where an older installed /ship dispatches a newer document-release.
+- Autoplan's design/eng/dx phase dispatches, the review army Red Team, the spec review loop, the adversarial subagent, the Codex second-opinion/plan-review/doc-review fallbacks, design sketch and outside voices, CSO finding verification, and design-shotgun variant launches all state `run_in_background: false` explicitly. Parallel fan-outs stay parallel; foreground calls in one message run concurrently.
+
+#### Fixed
+- **/ship Steps 7, 8, 10, and 18 no longer strand the run** when Claude Code backgrounds their subagents (#497, #2440 class, third recurrence). The four dispatch specs share one resolver-sourced foreground note, so the phrasing cannot drift per site again.
+
+#### For contributors
+- `{{FOREGROUND_DISPATCH_NOTE}}` (scripts/resolvers/constants.ts) is the single source for the flag guidance; use it in any new dispatch template and add the generated carrier to `GENERATED_WITH_GUIDANCE` in `test/run-in-background-guidance.test.ts` in the same commit. The test's pin list is the census of synchronous dispatch sites.
+- Seven carved-skill skeleton ceilings re-measured and ratcheted in `test/helpers/carve-guards.ts`; codex/factory ship goldens re-rendered.
+
 ## [1.77.0.0] - 2026-08-31

 **Every PR stops paying for evals twice.**
@@ -2338,6 +2338,42 @@ Linux cookie import shipped in v0.11.11.0 (Wave 3). Supports Chrome, Chromium, B

 ## Ship

+### Runtime enforcement of foreground dispatch (PreToolUse hook)
+
+**What:** A PreToolUse hook (settings.json) that forces or verifies `run_in_background: false` on Agent tool calls made inside gstack workflows, making the #497/#2440 bug class structurally impossible on Claude Code instead of prose-pinned.
+
+**Why:** v1.79.0.0 fixed the class at the prose+test layer (every synchronous dispatch site carries the flag, pinned by `test/run-in-background-guidance.test.ts`), but phrase-presence pins are file-level, not call-level, and a genuinely blocking foreground call still can't be interrupted by prose. Runtime enforcement is the structural fix; prose guidance can't survive a model that ignores it.
+
+**Context:** Third recurrence of the class (#497 → #2440 → /ship Step 18 stranding). The hook must scope to gstack skill sessions (never break legitimate background Agent use elsewhere), is Claude-host only (other hosts get nothing from it), and mirrors the existing question-preference PreToolUse hook wiring in `bin/gstack-settings-hook*`. Filed from the v1.79.0.0 CEO plan review (approach C, deliberately split out for bake time).
+
+**Effort:** M (human) / S (CC)
+**Priority:** P2
+**Depends on:** None
+
+### Structural ship-mode for document-release
+
+**What:** A capability-narrowed dispatch mode for /document-release (cannot bump VERSION, run review passes, or push) instead of narrowing the full workflow through prose in /ship's dispatch prompt; the parent /ship owns all git operations.
+
+**Why:** The v1.79.0.0 scope guard works by telling the subagent what not to do; a structural mode makes the forbidden operations unavailable rather than discouraged. Codex outside voice (v1.79.0.0 eng review) called the current shape "runs a large workflow and then disables half of it through prose" — correct long-term, wrong to fold into a regression fix.
+
+**Context:** Redesigns the #2733 JSON contract (files_updated/commit_sha/pushed/documentation_section/decisions), so it needs its own PR with bake time. Start from `ship/sections/pr-body.md.tmpl` Step 18 and `document-release/SKILL.md.tmpl`'s spawned contract; decide whether the mode is a dispatch-prompt parameter or a `GSTACK_DOC_RELEASE_MODE` env the preamble echoes.
+
+**Effort:** L (human) / M (CC)
+**Priority:** P3
+**Depends on:** None
+
+### Cross-host dispatch semantics audit
+
+**What:** Audit every subagent-dispatch site's rendering on non-Claude hosts (codex, factory, openclaw, hermes) and decide per host: rewrite to the host's native delegation primitive, inline-execute the step, or skip it.
+
+**Why:** The codex-host ship render inlines Step 18 instructing an Agent-tool dispatch that Codex cannot perform (no Agent tool, no run_in_background). Pre-existing (predates v1.79.0.0), surfaced by the eng-review outside voice. Host rewrites currently key on the exact string 'use the Agent tool', which none of the ship dispatch openers match, so Claude-specific instructions pass through verbatim.
+
+**Context:** See `hosts/define-host.ts:55`, `hosts/factory.ts:34`, `hosts/hermes.ts:15` for the existing rewrite mechanism, and `test/fixtures/golden/codex-ship-SKILL.md` for what codex actually receives today. The v1.79.0.0 `{{FOREGROUND_DISPATCH_NOTE}}` resolver is a natural place to start host-branching.
+
+**Effort:** M (human) / S (CC)
+**Priority:** P3
+**Depends on:** None
+
 ### /ship Step 12 test harness should exec the actual template bash, not a reimplementation

 **What:** `test/ship-version-sync.test.ts` currently reimplements the bash from `ship/SKILL.md.tmpl` Step 12 inside template literals. When the template changes, both sides must be updated — exactly the drift-risk pattern the Step 12 fix is meant to prevent, applied to our own testing strategy. Replace with a helper that extracts the fenced bash blocks from the template at test time and runs them verbatim (similar to the `skill-parser.ts` pattern).
@@ -1 +1 @@
-1.77.0.0
+1.79.0.0
@@ -1,6 +1,6 @@
 {
  "name": "gstack",
-  "version": "1.77.0",
+  "version": "1.79.0",
  "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
  "license": "MIT",
  "type": "module",
@@ -181,7 +181,7 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
    // v1.65 merge: provisional larger-of-both-waves budget; re-measured below.
        // Fork port wave 2 (#703): the repo-doc-preference block in the design
    // check grew every plan-review skeleton ~0.7KB. Measured values noted.
-    maxSkeletonBytes: 75_900, // + v1.78 foreground-dispatch sweep (#497/#2440 third recurrence); measured 75_529
+    maxSkeletonBytes: 75_900, // + v1.79 foreground-dispatch sweep (#497/#2440 third recurrence); measured 75_529
    minUnionBytes: 123_600, // token-reduction Phases 1-2 (v1.69.x branch): preamble bash -> bin/gstack-skill-start, onboarding -> gated emission; measured union 137,346
    mustContain: ['SCOPE EXPANSION', 'SELECTIVE EXPANSION', 'HOLD SCOPE', 'SCOPE REDUCTION'],
    // Default-on Codex outside-voice (codexPreflight block + CODEX_MODE branch
@@ -240,7 +240,7 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
    // tier-2+ skeleton (measured 89,184). Main's v1.64.0.0 adds ~340 B more
    // (telemetry --error-message/--failed-step preamble prose, PR #769).
    // Budget covers the sum of both waves.
-    maxSkeletonBytes: 73_750, // + v1.78 foreground-dispatch sweep (#497/#2440 third recurrence); measured 73_341
+    maxSkeletonBytes: 73_750, // + v1.79 foreground-dispatch sweep (#497/#2440 third recurrence); measured 73_341
    minUnionBytes: 99_200, // token-reduction Phases 1-2 (v1.69.x branch); measured union 110,293
    mustContain: ['design', 'visual'],
    maxSizeRatio: 1.12, // D1 1.104 + main's ~0.008
@@ -295,7 +295,7 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
    // the #538 opt-out + D1 evidence directive — ratio 1.104 measured.
    // #2499 project-scope MCP jq in the brain-sync block grew every tier-2+
    // skeleton ~1.5KB (entry resolution emitted once per SKILL.md).
-    maxSkeletonBytes: 73_300, // + v1.78 foreground-dispatch sweep (#497/#2440 third recurrence); measured 72_892
+    maxSkeletonBytes: 73_300, // + v1.79 foreground-dispatch sweep (#497/#2440 third recurrence); measured 72_892
    minUnionBytes: 115_800, // Phase 4 wave 4; measured union 118,175
    mustContain: ['design doc', 'problem statement'],
    maxSizeRatio: 1.12,
@@ -316,7 +316,7 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
    // +Conductor AUQ-default-prose rule + one-way/continuation safety in the
    // always-loaded AskUserQuestion Format section.
    // v1.2.0 activation lift: first-run-guidance section in the shared preamble.
-    maxSkeletonBytes: 40_200, // + v1.78 spawned-dispatch contract (#497/#2440 third recurrence); measured 39_812
+    maxSkeletonBytes: 40_200, // + v1.79 spawned-dispatch contract (#497/#2440 third recurrence); measured 39_812
    minUnionBytes: 56_700, // token-reduction Phases 1-2 (v1.69.x branch): preamble bash -> bin/gstack-skill-start, onboarding -> gated emission; measured union 63,018
    mustContain: ['CHANGELOG', 'Diataxis', 'coverage'],
    // Two intentional additions stack on this small skill: the AUQ-failure prose
@@ -347,7 +347,7 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
    // v1.65 merge: provisional larger-of-both-waves budget; re-measured below.
    // v1.64.1.0: shared-preamble prose from the two parallel v1.64 waves lands
    // the skeleton at 69,022 B; +~1 KB headroom.
-    maxSkeletonBytes: 53_700, // + v1.78 foreground-dispatch sweep (#497/#2440 third recurrence); measured 53_285
+    maxSkeletonBytes: 53_700, // + v1.79 foreground-dispatch sweep (#497/#2440 third recurrence); measured 53_285
    minUnionBytes: 65_000, // token-reduction Phases 1-2 (v1.69.x branch): preamble bash -> bin/gstack-skill-start, onboarding -> gated emission; measured union 72,252
    mustContain: ['Typography', 'Color', 'Aesthetic Direction'],
    // Cross-cutting preamble growth (v1.57.2.0 AUQ-failure prose fallback ~2KB +
@@ -387,7 +387,7 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
    // +Conductor AUQ-default-prose rule + one-way/continuation safety in the
    // always-loaded AskUserQuestion Format section.
    // v1.2.0 activation lift: first-run-guidance section in the shared preamble.
-    maxSkeletonBytes: 58_700, // + v1.78 foreground-dispatch sweep (#497/#2440 third recurrence); measured 58_307
+    maxSkeletonBytes: 58_700, // + v1.79 foreground-dispatch sweep (#497/#2440 third recurrence); measured 58_307
    minUnionBytes: 64_200, // token-reduction Phases 1-2 (v1.69.x branch); measured union 71,379
    mustContain: ['OWASP', 'STRIDE', 'daily', 'comprehensive', 'verif'],
    // cso keeps its mode-dispatch + FP-filtering phases always-loaded, so the
@@ -701,7 +701,7 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
      gateAfterStop: undefined,
    },
    behavioral: 'prompt',
-    maxSkeletonBytes: 52_950, // + v1.78 foreground-dispatch sweep (#497/#2440 third recurrence); measured 52_628
+    maxSkeletonBytes: 52_950, // + v1.79 foreground-dispatch sweep (#497/#2440 third recurrence); measured 52_628
    minUnionBytes: 53_200, // Phase 4 wave 4; measured union 54,290
    mustContain: ["Don't make me think", "Users scan, they don't read", 'trunk test', '44px minimum'],
  },
@@ -35,7 +35,7 @@ const GENERATED_WITH_GUIDANCE = [
  'ship/sections/test-coverage.md',
  'ship/sections/plan-completion.md',
  'ship/sections/greptile.md',
-  // Sweep carriers (v1.78): every remaining synchronous Agent-dispatch site.
+  // Sweep carriers (v1.79): every remaining synchronous Agent-dispatch site.
  'autoplan/sections/design-phase.md',
  'autoplan/sections/eng-phase.md',
  'autoplan/sections/dx-phase.md',
@@ -1 +1 @@
 .77.0.0
 .79.0.0