commandmate 0.25.0 → 0.26.1

package/dist/cli/commands/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/task.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC,wBAAgB,iBAAiB,IAAI,OAAO,CAyH3C"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/task.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC,wBAAgB,iBAAiB,IAAI,OAAO,CA4H3C"}

package/dist/cli/commands/task.js

@@ -108,7 +108,8 @@ function createTaskCommand() {
             // — verify.yaml can be opened, this cannot. Printing the id alone would
             // leave a reader unable to tell which criterion the run was judged by.
             for (const gate of task.contract.verify.gateDefinitions ?? []) {
-                console.log(`GATE-DEF:  ${gate.id}  ${gate.command}  (timeoutSec=${gate.timeoutSec})`);
+                const mutex = gate.mutex ? `, mutex=${gate.mutex}` : '';
+                console.log(`GATE-DEF:  ${gate.id}  ${gate.command}  (timeoutSec=${gate.timeoutSec}${mutex})`);
             }
             console.log(`AUTO-YES:  ${task.contract.autoYes.mode ?? 'unset'}`);
             console.log(`CREATED:   ${task.createdAt}`);

package/dist/cli/commands/verify.d.ts

@@ -15,5 +15,19 @@
  * succeeds exits 0 even when it finds nothing.
  */
 import { Command } from 'commander';
+import type { VerificationScopeDetail } from '../types/api-responses';
+/**
+ * Read the scope gate's report back into structured evidence.
+ *
+ * Parsing the gate's own prose is not the shape anyone would choose, but it is
+ * the only one available: `verification_gate_results` has no column for
+ * structured detail, and the CLI's `formatDetail` already reads work-evidence's
+ * counts out of `logTail` the same way (src/cli/utils/verify-runner.ts).
+ *
+ * Returns null when the tail is not a report — a skip, an error, or a gate that
+ * was never entered all write a sentence — because an empty `admitted` on those
+ * would claim the gate looked and found nothing.
+ */
+export declare function parseScopeEvidence(logTail: string | null | undefined): VerificationScopeDetail | null;
 export declare function createVerifyCommand(): Command;
 //# sourceMappingURL=verify.d.ts.map

package/dist/cli/commands/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoDpC,wBAAgB,mBAAmB,IAAI,OAAO,CA0D7C"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,KAAK,EAMV,uBAAuB,EAExB,MAAM,wBAAwB,CAAC;AAmChC;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,uBAAuB,GAAG,IAAI,CA8BrG;AAyED,wBAAgB,mBAAmB,IAAI,OAAO,CA0D7C"}

package/dist/cli/commands/verify.js

@@ -16,6 +16,7 @@
  * succeeds exits 0 even when it finds nothing.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseScopeEvidence = parseScopeEvidence;
 exports.createVerifyCommand = createVerifyCommand;
 const commander_1 = require("commander");
 const types_1 = require("../types");
@@ -27,6 +28,103 @@ const MAX_HISTORY_DAYS = 90;
 const MAX_HISTORY_LIMIT = 500;
 /** Gate statuses that mean the gate did not pass. `skipped` is not a failure. */
 const FAILED_GATE_STATUSES = new Set(['failed', 'timeout', 'error']);
+// =============================================================================
+// Scope-gate evidence (Issue #1841)
+// =============================================================================
+/** Built-in gate id; mirrors SCOPE_GATE_ID in lib/verification/verify-config.ts. */
+const SCOPE_GATE_ID = 'scope';
+/**
+ * Separator the scope gate puts between a path and the rule that decided it.
+ *
+ * Mirrors SCOPE_PATTERN_ARROW in `src/lib/verification/scope-gate.ts`. The two
+ * cannot import each other — tsconfig.cli.json compiles `src/cli/**` alone,
+ * with no path aliases, so the CLI bundle never pulls in the server's
+ * dependency graph — so a round-trip test feeds a real gate report through this
+ * parser instead of trusting the constants to be edited together.
+ */
+const SCOPE_PATTERN_ARROW = '  \u2190 ';
+/**
+ * Read the scope gate's report back into structured evidence.
+ *
+ * Parsing the gate's own prose is not the shape anyone would choose, but it is
+ * the only one available: `verification_gate_results` has no column for
+ * structured detail, and the CLI's `formatDetail` already reads work-evidence's
+ * counts out of `logTail` the same way (src/cli/utils/verify-runner.ts).
+ *
+ * Returns null when the tail is not a report — a skip, an error, or a gate that
+ * was never entered all write a sentence — because an empty `admitted` on those
+ * would claim the gate looked and found nothing.
+ */
+function parseScopeEvidence(logTail) {
+    if (!logTail)
+        return null;
+    const summary = /^scope: baseRef=.* changed=(\d+) violations=(\d+)$/m.exec(logTail);
+    if (!summary)
+        return null;
+    const changed = Number(summary[1]);
+    const violationTotal = Number(summary[2]);
+    const admitted = [];
+    const violations = [];
+    for (const line of logTail.split('\n')) {
+        if (line.startsWith('  + ')) {
+            const [path, pattern] = splitAtArrow(line.slice(4));
+            // The gate always names the admitting rule; a `+` line without one is
+            // output this parser does not understand, and inventing an empty pattern
+            // for it would put a claim in the JSON that nothing made.
+            if (pattern !== null)
+                admitted.push({ path, pattern });
+        }
+        else if (line.startsWith('  - ')) {
+            violations.push(splitAtArrow(line.slice(4))[0]);
+        }
+    }
+    return {
+        admitted,
+        violations,
+        // From the summary line, not from the lists: both are capped at 100 by the
+        // report, and `changed` counts every path either way. Admitted is the
+        // remainder because the gate classifies each changed path exactly once.
+        totals: { changed, admitted: changed - violationTotal, violations: violationTotal },
+    };
+}
+/**
+ * Split `<path>  \u2190 <pattern>`, keeping the whole line as the path when no
+ * arrow is present (an allow-miss violation has no rule to name).
+ *
+ * Split at the *last* arrow so a path containing the sequence still yields the
+ * pattern the gate wrote.
+ */
+function splitAtArrow(text) {
+    const at = text.lastIndexOf(SCOPE_PATTERN_ARROW);
+    if (at === -1)
+        return [text, null];
+    return [text.slice(0, at), text.slice(at + SCOPE_PATTERN_ARROW.length)];
+}
+/**
+ * Attach the evidence the CLI parses out of gate logs before a run is printed
+ * as JSON: {@link parseScopeEvidence} on the scope gate (Issue #1841), and the
+ * retry record on any gate that was re-run (Issue #1772).
+ *
+ * Copies rather than mutates: the run object is also what the polling loop
+ * reported from, and a JSON-only field has no business appearing in it.
+ */
+function withGateEvidence(run) {
+    const gates = run.gates ?? [];
+    return {
+        ...run,
+        gates: gates.map((gate) => {
+            const scope = gate.gateId === SCOPE_GATE_ID ? parseScopeEvidence(gate.logTail) : null;
+            const flaky = (0, verify_runner_1.parseFlakyMarker)(gate.logTail);
+            if (!scope && !flaky)
+                return gate;
+            return {
+                ...gate,
+                ...(scope ? { scope } : {}),
+                ...(flaky ? { flaky } : {}),
+            };
+        }),
+    };
+}
 function formatSeconds(durationMs) {
     return durationMs === null ? 'n/a' : `${(durationMs / 1000).toFixed(1)}s`;
 }
@@ -96,7 +194,7 @@ function createVerifyCommand() {
                 suppressResultLine: options.json,
             });
             if (options.json && outcome.run) {
-                console.log(JSON.stringify(outcome.run));
+                console.log(JSON.stringify(withGateEvidence(outcome.run)));
             }
             process.exit(outcome.exitCode);
         }
@@ -206,7 +304,11 @@ function addShowCommand(parent) {
             }
             const run = data.run;
             if (json) {
-                console.log(JSON.stringify(run, null, 2));
+                // `show` is the forensic surface — the one a reader reaches for to
+                // reconstruct a run days later — so the scope evidence and the retry
+                // record have to be readable here too, not only on the run that
+                // produced them.
+                console.log(JSON.stringify(withGateEvidence(run), null, 2));
                 return;
             }
             console.log(`run #${run.id}  ${run.status}  worktree=${run.worktreeId}  trigger=${run.trigger}`);
@@ -219,7 +321,11 @@ function addShowCommand(parent) {
                 // judged, so "which of these was the repository's own definition of
                 // passing" should not have to be inferred from an absent marker.
                 const source = gate.source ? `  src=${gate.source}` : '';
-                console.log(`  ${gate.gateId}  ${gate.status}  exit=${exit}  ${formatSeconds(gate.durationMs)}${source}`);
+                // Appended rather than replacing `status`, which is the stored column
+                // this view exists to show verbatim (#1772). The marker in the log
+                // tail below carries both runs' numbers.
+                const flaky = (0, verify_runner_1.parseFlakyMarker)(gate.logTail)?.outcome === 'flaky' ? `  ${verify_runner_1.FLAKY_GATE_LABEL}` : '';
+                console.log(`  ${gate.gateId}  ${gate.status}  exit=${exit}  ${formatSeconds(gate.durationMs)}${source}${flaky}`);
                 if (gate.logTail) {
                     for (const line of gate.logTail.split('\n')) {
                         console.log(`    | ${line}`);

package/dist/cli/commands/wait.d.ts

@@ -9,6 +9,8 @@
  *       layer could not classify at all — Issue #1708. Both are reported as
  *       exit 10 with a distinguishing `type` rather than a new exit code, so
  *       callers that already branch on 10 keep working.)
+ * - 11: UPSTREAM_FAULT (--fail-on-upstream-fault only, Issue #1839: the agent
+ *       came back to its composer with an upstream API failure on the frame)
  * - 124: TIMEOUT (--timeout exceeded)
  * Issue #1544 adds --verify / --require-work, which can turn a detected
  * completion into 20 (VERIFY_FAILED) or 21 (NOT_STARTED).

package/dist/cli/commands/wait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmepC,wBAAgB,iBAAiB,IAAI,OAAO,CA6G3C"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsqBpC,wBAAgB,iBAAiB,IAAI,OAAO,CA8G3C"}

package/dist/cli/commands/wait.js

@@ -10,6 +10,8 @@
  *       layer could not classify at all — Issue #1708. Both are reported as
  *       exit 10 with a distinguishing `type` rather than a new exit code, so
  *       callers that already branch on 10 keep working.)
+ * - 11: UPSTREAM_FAULT (--fail-on-upstream-fault only, Issue #1839: the agent
+ *       came back to its composer with an upstream API failure on the frame)
  * - 124: TIMEOUT (--timeout exceeded)
  * Issue #1544 adds --verify / --require-work, which can turn a detected
  * completion into 20 (VERIFY_FAILED) or 21 (NOT_STARTED).
@@ -47,6 +49,65 @@ const SELECTION_LIST_PROMPT_TYPE = 'selection_list';
  * whereas a new exit code reads as an infrastructure error to all of them.
  */
 const UNCLASSIFIED_PROMPT_TYPE = 'unclassified';
+/**
+ * Why `wait` decided the agent was done, printed on the completion line
+ * (Issue #1839).
+ *
+ * `Completed: <id>` used to be the whole story, which made two very different
+ * situations indistinguishable in a log: the agent's own `Stop` hook arrived, or
+ * nothing but the screen said so. The measurement behind this Issue is exactly
+ * that difference — a 529 storm returns Claude to its composer in ~3 s with the
+ * scraper reporting `ready`/`input_prompt` and no `Stop` ever sent — so the
+ * basis belongs next to the verdict rather than in a triage session afterwards.
+ */
+const COMPLETION_BASIS = {
+    /** The agent reported the turn ended, and the report postdates this wait's turn. */
+    HOOK_STOP: 'hook_stop',
+    /** The tmux session went away after we had seen it alive. */
+    SESSION_GONE: 'session_gone',
+    /** The terminal frame says the agent is back at its composer. Nothing corroborated it. */
+    SCRAPER_READY: 'scraper_ready',
+};
+/**
+ * Structured event types that mean "a turn is under way" (Issue #1839).
+ *
+ * Mirrors AGENT_EVENT_TYPES in src/lib/hooks/agent-event-types.ts; duplicated
+ * rather than imported because the CLI bundle keeps its own copy of the API
+ * shapes (see api-responses.ts).
+ *
+ * `notification` is deliberately absent, and that is the one measured deviation
+ * from the design sketched in Issue #1839. The Issue proposed accepting
+ * `stop` **or** `idle_prompt` as the end of a turn; the live capture of
+ * 2026-08-20 (see docs/design/upstream-fault-turn-boundary-1839.md) shows
+ * Claude 2.1.236 emitting `Notification(idle_prompt)` 62 s into a turn that
+ * ran nothing at all, because the composer had been idle for a minute. Reading
+ * it as a turn boundary would have re-created the false completion this gate
+ * exists to stop, one minute later. Only `Stop` ends a turn.
+ */
+const TURN_OPENING_EVENT_TYPES = new Set([
+    'user_prompt_submit',
+    'pre_tool_use',
+    'post_tool_use',
+]);
+/**
+ * How far *before* this wait started a turn-opening event may sit and still be
+ * read as the turn this wait is about (Issue #1839).
+ *
+ * `wait` does not know when `send` ran, and the honest proxy is its own start:
+ * an orchestrator sends and then waits, so the turn's `UserPromptSubmit` lands
+ * after `wait` is already polling (measured at +0.6 s from the send). One poll
+ * interval of slack covers a `wait` that starts a moment late.
+ *
+ * The bound is what keeps this from being a new way to hang. Structured events
+ * live in a server-side Map keyed by (worktree, tool, instance) and are NOT
+ * fenced by generation on the way into `structuredEvents` — a stale
+ * `user_prompt_submit` from a previous agent process can still be the last event
+ * on the wire. Refusing to adopt anything older than this wait means such a
+ * record cannot gate it: a `wait` on an already-idle session sees no fresh
+ * turn-opening event, keeps `turnStartedAt` null, and behaves exactly as it did
+ * before this Issue.
+ */
+const TURN_ADOPTION_GRACE_MS = POLL_INTERVAL_MS;
 /**
  * How long `isUnclassifiedActive` must hold before `wait` treats it as a stop
  * reason (Issue #1708).
@@ -88,13 +149,57 @@ function activeSuppression(data, now) {
         return null;
     return { suppression, ageSeconds: Math.max(0, Math.round(ageMs / 1000)) };
 }
+/** The wording for the four reasons a contract's `autoYes` block really authors. */
+const CONTRACT_POLICY_CAUSE = 'by contract policy';
 /**
- * One stderr line naming the policy that is holding this prompt (Issue #1699).
+ * What withheld the answer, in the words `wait` puts on stderr (Issue #1843).
+ *
+ * A Record over the whole reason union rather than one fixed phrase: adding a
+ * reason to {@link AutoYesSuppressionReason} without deciding what `wait` should
+ * say about it is a compile error here, which is the point. Until #1843 the
+ * notice hard-coded "by contract policy" for every reason, so #1829's
+ * `agent-launch-dialog` — a product-side decision the poller makes with no
+ * contract in sight (`src/lib/auto-yes-poller.ts`, the `getCodexLifecycleDialog`
+ * branch) — sent operators of contract-less worktrees hunting for a
+ * `denyPatterns` entry that did not exist.
+ *
+ * The three sites that record a suppression are covered: the poller's launch-dialog
+ * branch (`agent-launch-dialog`), the poller's policy branch and
+ * `lib/hooks/permission-decision-service.ts` (both the four `evaluatePolicyAgainstTexts`
+ * verdicts, which is why those four keep the pre-#1843 wording exactly).
+ */
+const SUPPRESSION_CAUSE = {
+    'mode-off': CONTRACT_POLICY_CAUSE,
+    'deny-pattern': CONTRACT_POLICY_CAUSE,
+    'deny-pattern-unusable': CONTRACT_POLICY_CAUSE,
+    'type-not-allowed': CONTRACT_POLICY_CAUSE,
+    'agent-launch-dialog': "while the agent's launch dialog was on screen",
+};
+/**
+ * {@link SUPPRESSION_CAUSE} for a reason that arrived over the wire.
+ *
+ * `reason` is a server-supplied string, so a server newer than this CLI can name
+ * a reason the union does not have. Naming it verbatim is the only honest answer:
+ * quietly folding an unknown reason into "by contract policy" is the same
+ * misattribution #1843 exists to remove, just for a future reason instead of
+ * `agent-launch-dialog`.
+ */
+function suppressionCause(reason) {
+    return Object.prototype.hasOwnProperty.call(SUPPRESSION_CAUSE, reason)
+        ? SUPPRESSION_CAUSE[reason]
+        : `for a reason this CLI does not recognise (${reason})`;
+}
+/**
+ * One stderr line naming what is holding this prompt (Issue #1699).
  *
  * `wait` used to print only "Waiting for human response...", which reads the
  * same whether a human was always going to answer or whether Auto-Yes silently
  * refused to. That ambiguity is what let a deny pattern matching a finished turn
  * stall two workers unnoticed; the pattern and the reason code belong on screen.
+ *
+ * Issue #1843: the cause is chosen per reason rather than asserted. `reason=` is
+ * in the payload either way, so the prefix is the only part that can lie — and it
+ * did, for every non-contract suppression.
  */
 function formatSuppressionNotice(suppression, ageSeconds) {
     const parts = [
@@ -105,7 +210,38 @@ function formatSuppressionNotice(suppression, ageSeconds) {
     if (suppression.pattern !== undefined) {
         parts.push(`pattern=${JSON.stringify(suppression.pattern)}`);
     }
-    return `  auto-yes suppressed this prompt by contract policy: ${parts.join(' ')} (${ageSeconds}s ago)`;
+    const cause = suppressionCause(suppression.reason);
+    return `  auto-yes suppressed this prompt ${cause}: ${parts.join(' ')} (${ageSeconds}s ago)`;
+}
+/**
+ * Adopt the turn this wait is about, if this poll shows one opening.
+ *
+ * @param previous - the turn start adopted so far, or null
+ * @returns the newest adopted turn start, or `previous` when nothing qualified
+ */
+function adoptTurnStart(data, waitStartedAt, previous) {
+    const events = data.structuredEvents;
+    if (!events || events.lastEventAt == null || events.lastEventType == null)
+        return previous;
+    if (!TURN_OPENING_EVENT_TYPES.has(events.lastEventType))
+        return previous;
+    if (events.lastEventAt < waitStartedAt - TURN_ADOPTION_GRACE_MS)
+        return previous;
+    return previous === null || events.lastEventAt > previous ? events.lastEventAt : previous;
+}
+/**
+ * Whether the agent has reported the end of the turn this wait adopted
+ * (Issue #1839).
+ *
+ * True when no turn was adopted at all, which is the whole of the unchanged
+ * path: a session whose agent posts no hooks never adopts one, so every caller
+ * on a machine without hook injection sees precisely the pre-#1839 behaviour.
+ */
+function turnSettled(data, turnStartedAt) {
+    if (turnStartedAt === null)
+        return true;
+    const stoppedAt = data.lastStopEventAt;
+    return stoppedAt != null && stoppedAt >= turnStartedAt;
 }
 /**
  * Poll a single worktree until completion, prompt, or timeout.
@@ -128,6 +264,12 @@ async function pollWorktree(client, worktreeId, options) {
      * (Issue #1708).
      */
     let unclassifiedSince = null;
+    /**
+     * Epoch ms of the `user_prompt_submit` / `pre_tool_use` / `post_tool_use` this
+     * wait adopted as "the turn I am waiting on", or null when the agent has
+     * reported none (Issue #1839). See {@link adoptTurnStart}.
+     */
+    let turnStartedAt = null;
     while (true) {
         // Check timeout
         if (options.timeout) {
@@ -159,6 +301,10 @@ async function pollWorktree(client, worktreeId, options) {
             if (data.isRunning) {
                 everRunning = true;
             }
+            // Issue #1839: done before any exit path so the turn is adopted even on a
+            // poll that ends in a prompt — the same turn is still open when the human
+            // answers and `--on-prompt human` resumes polling.
+            turnStartedAt = adoptTurnStart(data, startTime, turnStartedAt);
             // Prompt detected
             if (data.isPromptWaiting && data.promptData) {
                 // Issue #1699: report a policy suppression on both exits — the human one
@@ -314,8 +460,41 @@ async function pollWorktree(client, worktreeId, options) {
             // of an unreadable overlay (see the note above), and reporting it as
             // `Completed` is how a stalled worker gets merged. Path A is untouched — a
             // session that went away really is finished, and carries no flag anyway.
-            if (!data.isRunning || (data.sessionStatus === 'ready' && data.isUnclassifiedActive !== true)) {
-                console.error(`Completed: ${worktreeId}`);
+            if (!data.isRunning) {
+                console.error(`Completed: ${worktreeId} (basis=${COMPLETION_BASIS.SESSION_GONE})`);
+                return { exitCode: types_1.WaitExitCode.SUCCESS };
+            }
+            if (data.sessionStatus === 'ready' && data.isUnclassifiedActive !== true) {
+                // Issue #1839: the agent is back at its composer with an upstream
+                // failure on the frame. Checked BEFORE the turn-boundary gate below,
+                // because it is the answer to the question that gate can only ask: the
+                // turn did not end, and this is why. Without it the same session runs
+                // to --timeout and reports 124, which says nothing about the cause.
+                const fault = data.upstreamFault ?? null;
+                if (options.failOnUpstreamFault && fault) {
+                    console.error(`Upstream fault on ${worktreeId}: id=${fault.id} — the agent is back at its ` +
+                        'composer with an upstream API failure on screen, so this turn did not run. ' +
+                        `Matched: ${JSON.stringify(fault.matchedText)}`);
+                    return { exitCode: types_1.WaitExitCode.UPSTREAM_FAULT };
+                }
+                // Issue #1839: `ready` off the terminal frame is the agent's composer,
+                // not the agent's verdict. Measured 2026-08-20 against a stub upstream
+                // answering 529: Claude returns to the composer ~3 s after the send
+                // having executed nothing, and never sends `Stop`. When this instance's
+                // hooks ARE reporting — the only case in which `turnStartedAt` is
+                // non-null — that missing `Stop` is the difference between "finished"
+                // and "never ran", and it is the only signal that carries it.
+                if (!turnSettled(data, turnStartedAt)) {
+                    console.error(`Waiting: ${worktreeId} is back at its composer, but its agent has not reported ` +
+                        `the end of this turn (turnStartedAt=${turnStartedAt}, ` +
+                        `lastStopEventAt=${data.lastStopEventAt ?? 'none'}). ` +
+                        'Not reporting completion; inspect with ' +
+                        `\`commandmate capture ${worktreeId} --json\`.`);
+                    await sleep(POLL_INTERVAL_MS);
+                    continue;
+                }
+                const basis = turnStartedAt === null ? COMPLETION_BASIS.SCRAPER_READY : COMPLETION_BASIS.HOOK_STOP;
+                console.error(`Completed: ${worktreeId} (basis=${basis})`);
                 return { exitCode: types_1.WaitExitCode.SUCCESS };
             }
             // Progress indicator on stderr [DR1-05]
@@ -454,6 +633,7 @@ function createWaitCommand() {
         .option('--instance <id>', agent_target_options_1.WAIT_INSTANCE_OPTION_DESCRIPTION)
         .option('--verify', 'After completion, run every verification gate; exit 20 when a gate fails, 21 when there is nothing to verify')
         .option('--require-work', 'After completion, run only the work-evidence gate; exit 21 when the worktree has no commits and no uncommitted changes')
+        .option('--fail-on-upstream-fault', 'Exit 11 instead of 0 when the agent returns to its composer with an upstream API failure (529/limit/API Error) on the frame')
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
         .action(async (worktreeIds, options) => {
         try {