fix(#4218): stop the orchestrator steering an executor that is still working (#4391)

* fix(#4218): stop the orchestrator steering an executor that is still working

An executor with recent RED/GREEN/REFACTOR commits and passing verification had
not yet written its SUMMARY because it was finishing closeout. The parent saw no
local OS test/build process, inferred an "idle tail", and sent "Finalize
immediately" into a working child; in CLI runs the same inference interrupted an
executor before GREEN, leaving a RED commit and an uncommitted edit.

The stall block said only "if no completion signal, no SUMMARY.md, and no
expected-branch commits appear for N minutes" — it never said what to do when
commits DO exist and only the SUMMARY is outstanding, never defined the
threshold as a period without progress rather than a total runtime, and never
ruled out a process listing as an idleness signal. Four rules close that:

- the threshold measures a period WITHOUT MEANINGFUL PROGRESS, from the last
  sign of progress, not from dispatch — a long verification tail is not a stall;
- commits + missing SUMMARY + recent activity resolves to KEEP WAITING, with
  steering, interrupting and re-dispatching each named and forbidden;
- urgency/finalization messages ("Finalize immediately" and family) are
  forbidden outright — they arrive mid-verification and truncate a correct run.
  The existing user-facing pause is the only sanctioned stop, and `kill and
  retry` is a clean restart, not a nudge;
- the absence of a local OS test/build process is NOT idleness: a native
  subagent runs in the runtime's own session, and an executor between two tool
  calls shows no process at all. Progress is judged only by the signals this
  workflow names.

Five prose-contract assertions in tests/execute-phase-wave.test.cjs, all red on
next.

* fix(#4218): extract the progress policy to a step fragment

CI's #1168 gate caught it: execute-phase.md sits 77 bytes under a frozen 93600
ceiling and the four rules added ~2.3 KB. "Extract, not bump" is the repo's
stated remedy, and this workflow already carries policy detail that way.

execute-phase/steps/executor-progress-policy.md owns the policy. The
worktree-recovery arm moved with it — `kill and switch to inline execution`
qualifies the stop this policy governs, so it belongs beside the rule about when
stopping is sanctioned at all, not stranded in the host. The #3212 recovery
OPTIONS stay in the host, where tests/config.test.cjs pins them.

The host keeps what must be read before the orchestrator acts: the verdict, the
threshold definition, and a pointer that fires before any message is sent to the
child. execute-phase.md is now 93475 bytes — 48 SMALLER than next.

* chore: add changeset for #4218

* chore(#4218): regenerate the inventory manifest for the new step fragment

docs/INVENTORY-MANIFEST.json is the authoritative per-file list behind
INVENTORY.md's `<workflow>/steps/*.md` row, so a new fragment has to appear
there or gen-inventory-manifest --check reds the lint-tests lane.

* chore(#4218): restore the issue ref on the allow-test-rule marker

ADR-456 requires a #NNN on a new exemption; the block rewrite that moved the
policy into the fragment dropped it.

* chore(#4218): regenerate the install-tree fixtures for the new step fragment

The fragment ships with the workflow, so every runtime's golden install tree
gains one path — gen:install-tree is the generator that owns those fixtures.

---------

Co-authored-by: Tom Boucher <trekkie@nomorestars.com>

.changeset/fierce-koalas-climb.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 4391
+---
+**A working executor is no longer interrupted or told to "Finalize immediately"** — execute-phase's stall threshold now measures time without progress rather than total runtime, an executor with commits and recent activity is left alone until its SUMMARY lands, and a missing local test/build process no longer counts as idleness. (#4218)

docs/INVENTORY-MANIFEST.json

@@ -617,6 +617,7 @@
       "docs-update/steps/dispatch-monorepo-packages.md",
       "execute-phase/steps/codebase-drift-gate.md",
       "execute-phase/steps/executor-isolation-dispatch.md",
+      "execute-phase/steps/executor-progress-policy.md",
       "execute-phase/steps/gap-closure-artifacts.md",
       "execute-phase/steps/partial-wave.md",
       "execute-phase/steps/per-plan-executor-routing.md",

gsd-core/workflows/execute-phase.md

@@ -878,7 +878,9 @@ increases monotonically across waves. `{status}` is `complete` (success),
    ask for one recovery path: `continue waiting`, `kill and retry`, or
    `kill and switch to inline execution`.
 
-   If the stalled executor ran in an isolated worktree, `kill and switch to inline execution` edits the primary checkout — see worktree recovery policy (`execute-phase/steps/worktree-recovery-policy.md`). Prefer `kill and retry` in a fresh worktree; inline execution requires explicit confirmation, never the default.
+   **A working executor is never steered (#4218).** The threshold measures time WITHOUT
+   PROGRESS, not total runtime. Before treating an executor as stalled — and before sending it
+   any message — read and execute `execute-phase/steps/executor-progress-policy.md`.
 
    **This fallback applies to all runtimes.** Claude Code's Agent() backgrounds by
    default: the completion signal may never arrive. Verify, never wait.

gsd-core/workflows/execute-phase/steps/executor-progress-policy.md

@@ -0,0 +1,43 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
+# Executor Progress Policy (#4218)
+
+Read this before treating any executor as stalled.
+
+## A working executor is never steered
+
+The stall threshold measures a period **without meaningful progress**. It is not a maximum
+total runtime, and it is not a budget the executor has to finish inside. A plan with a long
+verification or closeout tail legitimately spends many minutes between its last commit and
+its SUMMARY.
+
+Reconcile activity as well as artifacts:
+
+- **Commits exist and SUMMARY.md is missing, with recent meaningful activity → KEEP
+  WAITING.** Do not steer it, do not interrupt it, do not re-dispatch it. Recent
+  RED/GREEN/REFACTOR commits, passing verification, or ongoing reasoning/tool telemetry
+  from the child are all meaningful activity.
+- **Only after `${EXECUTOR_STALL_THRESHOLD_MINUTES}` of no meaningful progress** — measured
+  from the LAST sign of progress, not from dispatch — may the pause in step 3 fire, and it
+  asks the user; it does not act on its own.
+
+## Never inject urgency or finalization instructions into a live executor
+
+Messages of the "Finalize immediately", "wrap up now", "you are taking too long" family are
+forbidden: they arrive mid-verification and turn a correct run into a truncated one. If an
+executor must be stopped, the pause in step 3 is the only route, and `kill and retry` is a
+clean restart — not a nudge.
+
+## The absence of a local OS test/build process is NOT idleness
+
+The orchestrator cannot see the child's work that way. A native subagent runs in the
+runtime's own session, not as a visible local process, and an executor between two tool
+calls — reasoning, reading a file, waiting on a runtime round-trip — shows no process at
+all. Judge progress ONLY by the signals this workflow names: commits on the expected
+branch, the SUMMARY, and the child's own activity. A process listing is not one of them.
+
+## If a stalled executor ran in an isolated worktree
+
+`kill and switch to inline execution` edits the primary checkout — see worktree recovery
+policy (`execute-phase/steps/worktree-recovery-policy.md`). Prefer `kill and retry` in a
+fresh worktree; inline execution requires explicit confirmation, never the default.

tests/execute-phase-wave.test.cjs

@@ -1182,3 +1182,88 @@ describe('execute-phase workflow: #3684 review findings — join normalization',
     }
   });
 });
+
+// ── #4218: a live executor must not be steered or cut short ──────────────────
+//
+// allow-test-rule: source-text-is-the-product (#4218) — the workflow .md IS
+// the instruction the orchestrator executes; its text is the artifact under test.
+//
+// Reported on Codex: an executor with recent RED/GREEN/REFACTOR commits and
+// passing verification had not yet written its SUMMARY because it was finishing
+// closeout. The parent saw no local OS test/build process, inferred an "idle
+// tail", and sent "Finalize immediately" into a working child. In CLI runs the
+// same inference interrupted an executor before GREEN, leaving a RED commit and
+// an uncommitted edit.
+//
+// The policy lives in a step fragment: execute-phase.md is 77 bytes under the
+// frozen #1168 ceiling, and "extract, not bump" is the repo's stated remedy.
+describe('execute-phase: stall surveillance must not steer a working executor (#4218)', () => {
+  const workflow = fs.readFileSync(WORKFLOW_PATH, 'utf-8');
+  const FRAGMENT_PATH = path.join(
+    __dirname, '..', 'gsd-core', 'workflows', 'execute-phase', 'steps', 'executor-progress-policy.md');
+  const fragment = fs.existsSync(FRAGMENT_PATH) ? fs.readFileSync(FRAGMENT_PATH, 'utf-8') : '';
+
+  test('the host routes to the policy before treating an executor as stalled', () => {
+    assert.match(workflow, /A working executor is never steered \(#4218\)/,
+      'the verdict must be visible where the orchestrator decides, not only in the fragment');
+    assert.match(workflow, /time WITHOUT\s{1,10}PROGRESS, not total runtime/,
+      'the threshold definition is the correction — it belongs in the host');
+    assert.match(workflow, /before sending it\s{1,10}any message/,
+      'the steering prohibition must be reachable before a message is sent, not after');
+    assert.match(workflow, /execute-phase\/steps\/executor-progress-policy\.md/,
+      'the host must point at the policy fragment');
+  });
+
+  test('the stall threshold is a period without progress, not a maximum runtime', () => {
+    assert.ok(fragment.length > 0, 'execute-phase/steps/executor-progress-policy.md must exist');
+    assert.match(fragment, /period \*\*without meaningful progress\*\*/,
+      'the threshold must be defined by absence of progress');
+    assert.match(fragment, /not a maximum\s{1,10}total runtime/,
+      'a long-but-progressing plan must not be treated as stalled');
+    assert.match(fragment, /from the LAST sign of progress, not from dispatch/,
+      'measuring from dispatch is what turns a slow plan into a false stall');
+  });
+
+  test('commits + missing SUMMARY + recent activity resolves to KEEP WAITING', () => {
+    assert.match(fragment, /KEEP\s{1,10}WAITING/, 'the verdict for a working executor must be explicit');
+    assert.match(fragment, /Do not steer it, do not interrupt it, do not re-dispatch it/,
+      'all three interventions the report describes must be named and forbidden');
+  });
+
+  test('urgency and finalization messages are forbidden outright', () => {
+    assert.match(fragment, /Never inject urgency or finalization instructions into a live executor/,
+      'the prohibition must be stated as a rule, not implied');
+    assert.match(fragment, /Finalize immediately/,
+      'the reported message must be named so it cannot be read as permitted');
+  });
+
+  test('a missing local OS process is not evidence of idleness', () => {
+    assert.match(fragment, /absence of a local OS test\/build process is NOT idleness/,
+      'the false signal the orchestrator acted on must be ruled out by name');
+    assert.match(fragment, /A process listing is not one of them/,
+      'the workflow must say which signals DO count, and that a process listing is not one');
+  });
+
+  test('the only sanctioned stop is the existing user-facing pause', () => {
+    assert.match(fragment, /the pause in step 3 is the only route/,
+      'stopping an executor must stay a user decision, not an orchestrator nudge');
+    assert.match(fragment, /`kill and retry` is a\s{1,10}clean restart — not a nudge/,
+      'the distinction between restarting and steering must be explicit');
+  });
+
+  test('the worktree-recovery arm moved with the policy, not left duplicated', () => {
+    assert.match(fragment, /If a stalled executor ran in an isolated worktree/,
+      'the recovery arm belongs with the stop policy it qualifies');
+    assert.match(fragment, /worktree-recovery-policy\.md/,
+      'it must still hand off to the worktree policy');
+    assert.ok(
+      !/kill and switch to inline execution` edits the primary checkout/.test(workflow),
+      'the host must not keep a second copy of the arm that moved',
+    );
+    // The #3212 recovery options themselves stay in the host — tests/config.test.cjs
+    // pins them there.
+    for (const option of ['continue waiting', 'kill and retry', 'kill and switch to inline execution']) {
+      assert.ok(workflow.includes(option), `the host must still offer "${option}"`);
+    }
+  });
+});

tests/fixtures/install-tree/antigravity.json

@@ -384,6 +384,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/augment.json

@@ -456,6 +456,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/claude-local.json

@@ -349,6 +349,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/claude.json

@@ -384,6 +384,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/cline.json

@@ -386,6 +386,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/codebuddy.json

@@ -456,6 +456,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/codex.json

@@ -420,6 +420,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/copilot.json

@@ -385,6 +385,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/cursor.json

@@ -384,6 +384,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/hermes.json

@@ -384,6 +384,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/kilo.json

@@ -456,6 +456,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/kimi-code.json

@@ -385,6 +385,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/kimi.json

@@ -421,6 +421,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/opencode.json

@@ -456,6 +456,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/pi.json

@@ -244,6 +244,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/qwen.json

@@ -384,6 +384,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/trae.json

@@ -384,6 +384,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/windsurf.json

@@ -312,6 +312,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",

tests/fixtures/install-tree/zcode.json

@@ -456,6 +456,7 @@
   "gsd-core/workflows/execute-phase.md",
   "gsd-core/workflows/execute-phase/steps/codebase-drift-gate.md",
   "gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md",
+  "gsd-core/workflows/execute-phase/steps/executor-progress-policy.md",
   "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md",
   "gsd-core/workflows/execute-phase/steps/partial-wave.md",
   "gsd-core/workflows/execute-phase/steps/per-plan-executor-routing.md",