sequant 2.6.2 → 2.8.0

package/dist/src/lib/workflow/phase-executor.js

@@ -12,7 +12,7 @@ import { execSync, execFileSync } from "child_process";
 import { readAgentsMd } from "../agents-md.js";
 import { getDriver } from "./drivers/index.js";
 import { classifyError } from "./error-classifier.js";
-import { ApiError } from "../errors.js";
+import { ApiError, BillingError } from "../errors.js";
 import { phaseRegistry } from "./phase-registry.js";
 import { bracketedConsoleLog } from "./notice.js";
 /**
@@ -408,6 +408,43 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
         ...tails,
     };
 }
+/**
+ * Map a failed driver result to a `PhaseResult`.
+ *
+ * Symmetric to {@link mapAgentSuccessToPhaseResult}; extracted so the
+ * failure-path mapping (notably the #739 capped/output gating) is unit-testable
+ * without spawning a driver.
+ *
+ * `output` is propagated **only** for a capped phase (#739): a capped result is
+ * incomplete-but-not-hard-failed, so its partial work must survive downstream.
+ * A genuine (non-capped) failure keeps the historical behaviour of dropping
+ * `output`, leaving the `/loop` fix-context (`formatFailureContext`) unchanged.
+ *
+ * @internal Exported for testing only
+ */
+export function mapAgentFailureToPhaseResult(phase, agentResult, durationSeconds) {
+    return {
+        phase,
+        success: false,
+        durationSeconds,
+        error: agentResult.error,
+        // Propagate the driver's typed cause (#732) so the retry logic can prefer
+        // it over stderr-regex classification and gate the MCP fallback.
+        structuredError: agentResult.structuredError,
+        // Propagate the turn-cap flag and the partial output (#739). On the failure
+        // path `output` was previously dropped entirely — for a capped phase the
+        // partial work is usable and must be preserved, mirroring the driver/skill
+        // slice from #733. Gating `output` on `capped` keeps non-capped failures
+        // byte-for-byte identical to pre-#739 behaviour.
+        capped: agentResult.capped,
+        output: agentResult.capped ? agentResult.output : undefined,
+        sessionId: agentResult.sessionId,
+        resumeHandle: agentResult.resumeHandle,
+        stderrTail: agentResult.stderrTail,
+        stdoutTail: agentResult.stdoutTail,
+        exitCode: agentResult.exitCode,
+    };
+}
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.
@@ -642,17 +679,7 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
     if (agentResult.success) {
         return mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds, cwd);
     }
-    return {
-        phase,
-        success: false,
-        durationSeconds,
-        error: agentResult.error,
-        sessionId: agentResult.sessionId,
-        resumeHandle: agentResult.resumeHandle,
-        stderrTail: agentResult.stderrTail,
-        stdoutTail: agentResult.stdoutTail,
-        exitCode: agentResult.exitCode,
-    };
+    return mapAgentFailureToPhaseResult(phase, agentResult, durationSeconds);
 }
 /**
  * Execute a phase with automatic retry for cold-start failures and MCP fallback.
@@ -693,6 +720,14 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
         if (lastResult.success) {
             return lastResult;
         }
+        // Turn-capped phase (#739): incomplete-but-not-hard-failed. A retry cannot
+        // un-cap a turn limit, so short-circuit before any fallback — same rationale
+        // as the billing skip (#732), but capped must skip *all* retries (incl.
+        // cold-start), so an explicit early return is required, not just a guard
+        // flag at the MCP gate.
+        if (lastResult.capped) {
+            return lastResult;
+        }
     }
     else {
         // Phase 1: Cold-start retry attempts (with MCP enabled if configured)
@@ -703,11 +738,23 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
             if (lastResult.success) {
                 return lastResult;
             }
+            // Turn-capped phase (#739): short-circuit before cold-start retries, the
+            // MCP fallback, and the spec-extra retry — a retry cannot un-cap a turn
+            // limit. The early return here (rather than a guard at the MCP gate alone)
+            // is what skips the cold-start re-spawns, unlike the billing case which
+            // still cold-start-retries in the <60s window.
+            if (lastResult.capped) {
+                return lastResult;
+            }
             // Genuine failure (took long enough to be real work) → skip cold-start retries.
             // Use error classification (AC-9): if the error is retryable (e.g., API
             // rate limit, transient 503), allow one more attempt even for genuine failures.
             if (duration >= COLD_START_THRESHOLD_SECONDS) {
-                const typedError = classifyError(lastResult.stderrTail ?? [], lastResult.exitCode);
+                // Prefer the driver's structured cause (#732) — it reflects the real
+                // SDK rate-limit/billing signal — over stderr-regex classification,
+                // which only sees text and never the structured data.
+                const typedError = lastResult.structuredError ??
+                    classifyError(lastResult.stderrTail ?? [], lastResult.exitCode);
                 if (typedError.isRetryable && attempt < COLD_START_MAX_RETRIES) {
                     if (config.verbose) {
                         const label = typedError instanceof ApiError
@@ -735,7 +782,22 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     // Phase 2: MCP fallback - if MCP is enabled and we're still failing, try without MCP
     // This handles npx-based MCP servers that fail on first run due to cold-cache issues.
     // Skip for `loop` phase — MCP is never the cause of loop failures (#488).
-    if (config.mcp && !lastResult.success && !skipColdStartRetry) {
+    //
+    // Also skip when the failure is a billing/credits error (#732): a no-MCP
+    // retry cannot refill credits, so the misleading "retrying without MCP"
+    // noise (#592) would only mask the real cause. The accurate structured
+    // message (e.g. "Out of credits") is surfaced instead.
+    const failureIsBilling = lastResult.structuredError instanceof BillingError;
+    // Belt-and-suspenders (#739): the capped early-returns above already exit
+    // before reaching here, but gate the MCP fallback on `!failureIsCapped` too so
+    // intent is documented and future code paths can't accidentally re-spawn a
+    // capped phase without MCP.
+    const failureIsCapped = lastResult.capped === true;
+    if (config.mcp &&
+        !lastResult.success &&
+        !skipColdStartRetry &&
+        !failureIsBilling &&
+        !failureIsCapped) {
         bracketedConsoleLog(spinner, chalk.yellow(`\n    ! Phase failed with MCP enabled, retrying without MCP...`));
         // Create config copy with MCP disabled
         const configWithoutMcp = {

package/dist/src/lib/workflow/run-log-schema.d.ts

@@ -125,6 +125,7 @@ export declare const PhaseLogSchema: z.ZodObject<{
         timeout: "timeout";
     }>;
     error: z.ZodOptional<z.ZodString>;
+    capped: z.ZodOptional<z.ZodBoolean>;
     iterations: z.ZodOptional<z.ZodNumber>;
     filesModified: z.ZodOptional<z.ZodArray<z.ZodString>>;
     testsRun: z.ZodOptional<z.ZodNumber>;
@@ -201,6 +202,7 @@ export declare const IssueLogSchema: z.ZodObject<{
             timeout: "timeout";
         }>;
         error: z.ZodOptional<z.ZodString>;
+        capped: z.ZodOptional<z.ZodBoolean>;
         iterations: z.ZodOptional<z.ZodNumber>;
         filesModified: z.ZodOptional<z.ZodArray<z.ZodString>>;
         testsRun: z.ZodOptional<z.ZodNumber>;
@@ -318,6 +320,7 @@ export declare const RunLogSchema: z.ZodObject<{
                 timeout: "timeout";
             }>;
             error: z.ZodOptional<z.ZodString>;
+            capped: z.ZodOptional<z.ZodBoolean>;
             iterations: z.ZodOptional<z.ZodNumber>;
             filesModified: z.ZodOptional<z.ZodArray<z.ZodString>>;
             testsRun: z.ZodOptional<z.ZodNumber>;

package/dist/src/lib/workflow/run-log-schema.js

@@ -130,6 +130,13 @@ export const PhaseLogSchema = z.object({
     status: PhaseStatusSchema,
     /** Error message if failed */
     error: z.string().optional(),
+    /**
+     * Set when the phase hit its turn cap (`error_max_turns`) (#739). Distinguishes
+     * an incomplete-but-not-hard-failed phase (partial output preserved) from a
+     * genuine failure. Reuses the `"failure"` status — additive boolean rather than
+     * a new `PhaseStatus` enum value, to keep the persisted-log schema stable.
+     */
+    capped: z.boolean().optional(),
     /** Number of iterations (for loop phase) */
     iterations: z.number().int().nonnegative().optional(),
     /** Files modified during this phase */

package/dist/src/lib/workflow/state-manager.d.ts

@@ -116,6 +116,7 @@ export declare class StateManager {
     updatePhaseStatus(issueNumber: number, phase: Phase, status: PhaseStatus, options?: {
         error?: string;
         iteration?: number;
+        capped?: boolean;
     }): Promise<void>;
     /**
      * Update the overall issue status

package/dist/src/lib/workflow/state-manager.js

@@ -300,6 +300,12 @@ export class StateManager {
             if (options?.iteration !== undefined) {
                 phaseState.iteration = options.iteration;
             }
+            // Persist the turn-cap marker (#739) so a halted-on-cap phase is
+            // distinguishable from a genuine failure in state, not just the run-log —
+            // this is what makes the "reversible later" resume path first-class.
+            if (options?.capped !== undefined) {
+                phaseState.capped = options.capped;
+            }
             // Preserve startedAt if already set
             const existingPhase = issueState.phases[phase];
             if (existingPhase?.startedAt && status !== "pending") {

package/dist/src/lib/workflow/state-schema.d.ts

@@ -88,6 +88,7 @@ export declare const PhaseStateSchema: z.ZodObject<{
     startedAt: z.ZodOptional<z.ZodString>;
     completedAt: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodString>;
+    capped: z.ZodOptional<z.ZodBoolean>;
     iteration: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type PhaseState = z.infer<typeof PhaseStateSchema>;
@@ -242,6 +243,7 @@ export declare const IssueStateSchema: z.ZodObject<{
         startedAt: z.ZodOptional<z.ZodString>;
         completedAt: z.ZodOptional<z.ZodString>;
         error: z.ZodOptional<z.ZodString>;
+        capped: z.ZodOptional<z.ZodBoolean>;
         iteration: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     pr: z.ZodOptional<z.ZodObject<{
@@ -381,6 +383,7 @@ export declare const WorkflowStateSchema: z.ZodObject<{
             startedAt: z.ZodOptional<z.ZodString>;
             completedAt: z.ZodOptional<z.ZodString>;
             error: z.ZodOptional<z.ZodString>;
+            capped: z.ZodOptional<z.ZodBoolean>;
             iteration: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
         pr: z.ZodOptional<z.ZodObject<{

package/dist/src/lib/workflow/state-schema.js

@@ -85,6 +85,13 @@ export const PhaseStateSchema = z.object({
     completedAt: z.string().datetime().optional(),
     /** Error message if phase failed */
     error: z.string().optional(),
+    /**
+     * Set when the phase halted on its turn cap (`error_max_turns`) (#739).
+     * Distinguishes a recoverable cap (partial output preserved, resume to
+     * continue) from a genuine failure while keeping `status: "failed"`.
+     * Additive/optional — existing persisted state is unaffected.
+     */
+    capped: z.boolean().optional(),
     /** Number of loop iterations (for loop phase) */
     iteration: z.number().int().nonnegative().optional(),
 });

package/dist/src/lib/workflow/types.d.ts

@@ -7,6 +7,7 @@ import type { LogWriter } from "./log-writer.js";
 import type { StateManager } from "./state-manager.js";
 import type { ShutdownManager } from "../shutdown.js";
 import type { WorktreeInfo } from "./worktree-manager.js";
+import type { SequantError } from "../errors.js";
 export type { WorkflowEventEmitter, WorkflowEvents, WorkflowEventListener, IssueEventStatus, BaseEventPayload, RunEventPayload, PhaseStartedPayload, PhaseCompletedPayload, PhaseFailedPayload, IssueStatusChangedPayload, QaVerdictPayload, ProgressPayload, } from "./event-emitter.js";
 /**
  * Canonical Zod schema for all workflow phases.
@@ -160,6 +161,22 @@ export interface PhaseResult {
     success: boolean;
     durationSeconds?: number;
     error?: string;
+    /**
+     * Typed error with structured cause data, propagated from the driver's
+     * `AgentPhaseResult.structuredError` (#732). When present, the retry logic
+     * prefers it over stderr-regex classification and uses its type to gate the
+     * MCP fallback (a `BillingError` skips the misleading retry — #592).
+     */
+    structuredError?: SequantError;
+    /**
+     * Set when the phase hit its turn cap (`error_max_turns`), propagated from the
+     * driver's `AgentPhaseResult.capped` (#733/#739). A capped phase is
+     * incomplete-but-not-hard-failed: the partial work in `output` is preserved
+     * rather than discarded, and the retry logic treats it like the `BillingError`
+     * skip (#732) — a retry cannot un-cap a turn limit. Additive/optional, same
+     * shape as `structuredError?`; existing consumers are unaffected.
+     */
+    capped?: boolean;
     /** Captured output from the phase (used for parsing spec recommendations) */
     output?: string;
     /** Parsed QA verdict (only for qa phase) */

package/dist/src/ui/tui/theme.d.ts

@@ -12,8 +12,10 @@ import type { IssueStatus, PhaseStatus } from "../../lib/workflow/run-state.js";
  *   - `BRAND_GREEN` is the accent/success green (`--color-accent`).
  *
  * Used to brand the two color signals that matter most at a glance — the
- * live/active phase and success — while issue-distinction (border rotation),
- * failure (red), and dividers (gray) stay on robust named ANSI colors.
+ * live/active phase and success — while issue-distinction (border rotation)
+ * and failure (red) stay on robust named ANSI colors. The muted gray for
+ * secondary chrome is a fixed mid-gray (`DIVIDER_COLOR`) chosen for WCAG
+ * contrast rather than the too-dim ANSI bright-black.
  *
  * Ink/chalk auto-downsamples hex to the nearest ANSI color on terminals
  * without truecolor, and `NO_COLOR` still strips all color, so these degrade
@@ -24,8 +26,20 @@ export declare const BRAND_GREEN: "#10b981";
 /** Border-color palette rotated by issue start order. */
 export declare const BORDER_ROTATION: readonly ["cyan", "magenta", "blue", "yellow"];
 export type BorderColor = (typeof BORDER_ROTATION)[number] | typeof BRAND_GREEN | typeof BRAND_ORANGE | "red" | "gray";
-/** Gray used for horizontal dividers inside each box. */
-export declare const DIVIDER_COLOR: "gray";
+/**
+ * Muted gray for secondary chrome: dividers, field labels (`branch`/`now`/
+ * `log`), the `phase N/total` + elapsed line, the `last activity` stamp, and
+ * the terminal status line.
+ *
+ * Lifted off ANSI `"gray"` (bright-black), which the brand's own dark theme
+ * renders at ~2.4:1 — below WCAG AA (4.5) and even the 3.0 large-text/UI floor.
+ * This fixed mid-gray clears AA (~4.9:1) on the dark theme while staying above
+ * 3.0 on light terminals (~3.4:1). It still degrades gracefully: chalk
+ * downsamples the hex to the nearest ANSI color on non-truecolor terminals, and
+ * `NO_COLOR` strips it entirely. The not-yet-started phase glyph stays on ANSI
+ * `"gray"` (see `phaseStatusColor`) so pending work remains the most recessed.
+ */
+export declare const DIVIDER_COLOR: "#8B8B9A";
 /** Brand orange for the live/active phase spinner — the one element the eye
  *  tracks. Border rotation still distinguishes concurrent issues. */
 export declare const ACTIVE_PHASE_COLOR: "#FF8012";

package/dist/src/ui/tui/theme.js

@@ -11,8 +11,10 @@
  *   - `BRAND_GREEN` is the accent/success green (`--color-accent`).
  *
  * Used to brand the two color signals that matter most at a glance — the
- * live/active phase and success — while issue-distinction (border rotation),
- * failure (red), and dividers (gray) stay on robust named ANSI colors.
+ * live/active phase and success — while issue-distinction (border rotation)
+ * and failure (red) stay on robust named ANSI colors. The muted gray for
+ * secondary chrome is a fixed mid-gray (`DIVIDER_COLOR`) chosen for WCAG
+ * contrast rather than the too-dim ANSI bright-black.
  *
  * Ink/chalk auto-downsamples hex to the nearest ANSI color on terminals
  * without truecolor, and `NO_COLOR` still strips all color, so these degrade
@@ -22,8 +24,20 @@ export const BRAND_ORANGE = "#FF8012";
 export const BRAND_GREEN = "#10b981";
 /** Border-color palette rotated by issue start order. */
 export const BORDER_ROTATION = ["cyan", "magenta", "blue", "yellow"];
-/** Gray used for horizontal dividers inside each box. */
-export const DIVIDER_COLOR = "gray";
+/**
+ * Muted gray for secondary chrome: dividers, field labels (`branch`/`now`/
+ * `log`), the `phase N/total` + elapsed line, the `last activity` stamp, and
+ * the terminal status line.
+ *
+ * Lifted off ANSI `"gray"` (bright-black), which the brand's own dark theme
+ * renders at ~2.4:1 — below WCAG AA (4.5) and even the 3.0 large-text/UI floor.
+ * This fixed mid-gray clears AA (~4.9:1) on the dark theme while staying above
+ * 3.0 on light terminals (~3.4:1). It still degrades gracefully: chalk
+ * downsamples the hex to the nearest ANSI color on non-truecolor terminals, and
+ * `NO_COLOR` strips it entirely. The not-yet-started phase glyph stays on ANSI
+ * `"gray"` (see `phaseStatusColor`) so pending work remains the most recessed.
+ */
+export const DIVIDER_COLOR = "#8B8B9A";
 /** Brand orange for the live/active phase spinner — the one element the eye
  *  tracks. Border rotation still distinguishes concurrent issues. */
 export const ACTIVE_PHASE_COLOR = BRAND_ORANGE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "2.6.2",
+  "version": "2.8.0",
   "description": "AI coding agent orchestrator — resolve GitHub issues end-to-end with isolated git worktrees, quality gates, and an MCP server. Works with Claude Code or Aider.",
   "type": "module",
   "bin": {
@@ -25,10 +25,11 @@
     "dev": "tsx bin/cli.ts",
     "test": "vitest run",
     "lint": "eslint src/ bin/ --max-warnings 0",
-    "sync:skills": "cp -r templates/skills/* .claude/skills/",
+    "sync:skills": "npx tsx scripts/check-skill-sync.ts --fix",
     "sync:hooks": "bash scripts/sync-hooks.sh",
-    "validate:skills": "for skill in templates/skills/*/; do npx skills-ref validate \"$skill\"; done",
+    "validate:skills": "for skill in templates/skills/*/; do case \"$skill\" in *_shared*|*/references/*) continue;; esac; npx skills-ref validate \"$skill\"; done",
     "lint:skill-calls": "npx tsx scripts/lint-skill-calls.ts",
+    "lint:skill-sync": "npx tsx scripts/check-skill-sync.ts",
     "prepare:marketplace": "npx tsx scripts/prepare-marketplace.ts",
     "validate:marketplace": "npx tsx scripts/prepare-marketplace.ts --validate-only",
     "prepublishOnly": "npm run build"

package/templates/skills/_shared/references/force-push.md

@@ -0,0 +1,34 @@
+# Force-push handoff pattern
+
+When you encounter `HOOK_BLOCKED: Force push` from `.claude/hooks/pre-tool.sh:106-111`, **do not attempt to bypass the hook**. The block is intentional — force-pushing rewrites history and can destroy work for others sharing the branch.
+
+## The pattern: hand the command to the user
+
+When a force push is genuinely required (e.g., cleaning contamination off a feature branch after a clean rebase), present the exact command to the user prefixed with `!` so they execute it in-session:
+
+```
+! git push --force-with-lease origin feature/<branch>
+```
+
+The user pastes that into the prompt; the `!` runs it in their shell, output streams back into the conversation, and you continue from there.
+
+**Always prefer `--force-with-lease` over raw `--force`.** `--force-with-lease` refuses to overwrite the remote ref if someone else pushed in the meantime, turning a silent stomp into a clean error.
+
+## Why bypass attempts fail
+
+`CLAUDE_HOOKS_DISABLED=true git push --force ...` does **not** work. The hook reads `CLAUDE_HOOKS_DISABLED` at the harness level *before* Bash executes the command, so prefixing the env var inside the command line has no effect. Setting it via `export` in a prior tool call doesn't help either — each Bash tool call is a fresh subprocess.
+
+## When force push is legitimate vs. not
+
+| Legitimate | Not legitimate |
+|------------|----------------|
+| Cleaning rebase contamination off your own feature branch before PR | Rewriting history on `main`/`master` |
+| Removing accidentally-committed secrets after rotation | "Squashing for cleanliness" on a shared branch |
+| Recovering from a mistakenly-pushed merge commit | Force-pushing over someone else's work |
+
+For shared branches, prefer `git revert` over force push.
+
+## Reference
+
+- Block definition: `.claude/hooks/pre-tool.sh:106-111`
+- Regex: `git push.*(--force| -f($| ))` — note this can also match the literal strings inside quoted `gh issue/pr` bodies (workaround: write the body to a file first)

package/templates/skills/assess/SKILL.md

@@ -69,6 +69,20 @@ If the output is non-empty, paste every line verbatim above the dashboard table
 
 The orchestrator/MCP mode (`SEQUANT_ORCHESTRATOR` set) returns no output, so the call is safe to make unconditionally.
 
+**Command prefix (#740, read-only):**
+
+Probe once here for a global/PATH `sequant`, and reuse the result for every emitted run command below. `npx sequant` is the invocation most prone to version skew (a dual node prefix plus npx cache reuse can silently run a *stale* binary while a directly-installed `sequant` on PATH is current), so prefer a resolvable global install when one exists.
+
+```bash
+# Resolve CMD_PREFIX once here; reuse it for every emitted run command below.
+command -v sequant >/dev/null 2>&1 && CMD_PREFIX="sequant" || CMD_PREFIX="npx sequant"
+```
+
+- Global install on PATH → `CMD_PREFIX="sequant"` → emit `sequant run …`
+- No global install (npx-only) → `CMD_PREFIX="npx sequant"` → emit `npx sequant run …` (unchanged default — zero behavior change for npx-only users)
+
+The probe is read-only and side-effect-free, so it runs unconditionally, including in orchestrator/MCP mode (`SEQUANT_ORCHESTRATOR` set).
+
 **From GitHub (parallel for all issues):**
 
 ```bash
@@ -182,7 +196,7 @@ Triggers (any one):
 - Issue body or comments mention `"depends on #N"`, `"blocked by #N"`, or `"after #N"`
 - One issue's described output is another issue's input (e.g., A changes a function signature that B consumes)
 
-Format: `Chain: npx sequant run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <one-line reason>`
+Format: `Chain: <CMD_PREFIX> run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <one-line reason>` (`<CMD_PREFIX>` resolved in Step 1)
 
 Flag references:
 - `--chain` chains issues (each branches from previous; implies `--sequential`)
@@ -233,15 +247,15 @@ False-positive guards and tunables (excluded paths, the path regex, the slash-co
 ...
 ────────────────────────────────────────────────────────────────
 Commands:
-  npx sequant run <N1> <N2> <flags>
-  npx sequant run <N3> <flags>              # resume
+  <CMD_PREFIX> run <N1> <N2> <flags>
+  <CMD_PREFIX> run <N3> <flags>              # resume
 ────────────────────────────────────────────────────────────────
 Order: <N> → <N> (<dependency reason>)
 
 ⚠ #<N>  <warning>
 ⚠ #<N>  <warning>
 
-Chain: npx sequant run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <reason>
+Chain: <CMD_PREFIX> run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <reason>
 
 Flags:
   <flag>                <one-line reason>
@@ -286,6 +300,7 @@ The commands block is headed by `Commands:` — no box-drawing, no character cou
 6. If ALL issues share the same workflow, emit a single command
 7. **Line splitting:** When a single command would contain more than 6 issue numbers, split into multiple commands of at most 6 issues each, grouped by compatible workflow. Example: 11 issues → two commands (6 + 5)
 8. **Minimal flags:** Omit `--phases` when the resulting workflow equals the CLI default (registered at `bin/cli.ts:186`, defined as `DEFAULT_PHASES` in `src/lib/workflow/types.ts`). Prefer additive flags over restating phases — additive flags: `--testgen` and `--security-review` (`bin/cli.ts:208-209`). Use `--testgen` instead of `--phases spec,testgen,exec,qa` (or `…,testgen,…,test,qa` for ui-labelled issues, since `phase-mapper.determinePhasesForIssue` auto-adds `test` from the ui label). Use `--security-review` instead of `--phases spec,security-review,exec,qa`. The posted marker (`<!-- assess:phases=… -->`) records the full resolved workflow regardless — markers are machine-readable, displayed commands are human shorthand. This intentional divergence is fine: parsers consume markers, humans copy commands.
+9. **Command prefix:** Substitute the Step-1 `CMD_PREFIX` for **every** emitted `sequant run` command — the Commands block, the `Chain:` line, and both single-issue detail-mode commands (PROCEED and the REWRITE "fresh start"). `Cleanup:` commands are `git`/`gh`, not `sequant`, so they are unaffected. A resolvable global `sequant` on PATH yields `sequant run …`; npx-only yields `npx sequant run …` (the default). Never mix prefixes within a single assessment.
 
 #### Annotation Rules
 
@@ -303,7 +318,7 @@ Emit annotations in this order between the separators that follow `Commands:`:
   - `⚠ #412  bug + auth labels — domain label (auth) takes priority over bug`
 
 - **`Chain:`** — Only when 2+ PROCEED issues have a detected dependency (see "Chain detection" in Step 4). Suggests an alternative execution topology. Does not replace the default per-issue commands. Format:
-  `Chain: npx sequant run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <one-line reason>`
+  `Chain: <CMD_PREFIX> run <N1> <N2> --chain --qa-gate -Q <phases>   # alternative — <one-line reason>` (`<CMD_PREFIX>` resolved in Step 1)
 
 - **`Flags:`** — Only when non-default flags appear in the commands and the reason isn't obvious. One line per **distinct** flag used across all commands. Omit entire section when `-Q` is the only non-default flag AND its reason is obvious (e.g., all issues are enhancements). Format:
   ```
@@ -321,6 +336,8 @@ Emit annotations in this order between the separators that follow `Commands:`:
 
 Not all issues have explicit `- [ ]` checkboxes, so the `ACs` column is omitted.
 
+> **Prefix in examples:** The worked examples in this doc show the `npx sequant` default (the zero-install path). When the Step-1 probe resolves a global `sequant` on PATH, `CMD_PREFIX="sequant"` and every emitted command uses `sequant run …` instead — consistently within one assessment (see Commands Block Rule #9).
+
 ```
  #    Action     Reason                              Run
  462  PARK       Manual measurement task              ‖
@@ -485,7 +502,7 @@ More context since you're focused on one issue. Separators between every section
 → PROCEED — <one-line reason>
 
 Commands:
-  npx sequant run <N> <flags>
+  <CMD_PREFIX> run <N> <flags>
 
 <phases> · <N> ACs
 
@@ -617,7 +634,7 @@ Need: <specific information required>
 → REWRITE — <reason>
 
 Commands:
-  npx sequant run <N> <flags>                 # fresh start
+  <CMD_PREFIX> run <N> <flags>                 # fresh start
 
 <phases> · <N> ACs
 ────────────────────────────────────────────────────────────────

package/templates/skills/exec/SKILL.md

@@ -1657,6 +1657,35 @@ Parse the agent's output text for these patterns to detect failures:
 | `blocked by hook` | Operation was blocked by pre-tool hook |
 | `I'm unable to` | Agent hit a blocking constraint |
 
+### 4b2. Detecting Turn-Capped Implementers (Incomplete, not Failed)
+
+Every spawned implementer runs under a `maxTurns` cap (live since #484). Hitting the cap is **not** a failure — the agent did real, partial work before running out of turns, and that work is preserved (driver returns it flagged `capped: true` and warns rather than erroring, #733). Treat a capped implementer as **incomplete**, distinct from the hook-block failures in Section 4b.
+
+**Turn-cap detection keywords** (parse the agent's output text):
+
+| Pattern | Meaning |
+|---------|---------|
+| `error_max_turns` | Agent hit its turn cap |
+| `turn cap` / `Returning partial results` | Driver-emitted turn-cap warning |
+| Output ends mid-task with no completion report | Likely capped |
+
+**How to handle a capped implementer:**
+
+- Do **not** discard its changes or roll back the group — keep the partial work it committed.
+- Record, per task, **which tasks finished vs. which were capped**. A capped task is incomplete, not done.
+- Continue with the remaining (non-capped) tasks normally; one cap does not abort the whole `/exec` run.
+- The next `/exec` iteration (or a resumed session) picks up the capped task to finish it — note it explicitly so it is not mistaken for complete.
+- Reflect capped tasks honestly in the AC verification table (⚠️ Partial) and the progress update, rather than reporting the AC as fully satisfied.
+
+```markdown
+### Parallel Group Results
+
+| Task | Status |
+|------|--------|
+| Create types/metrics.ts | ✅ Finished |
+| Refactor batch-executor | ⚠️ Capped (incomplete — resume next iteration) |
+```
+
 ### 4c. Prompt Templates for Sub-Agents
 
 When spawning sub-agents for implementation tasks, use task-specific prompt templates for better results. See [prompt-templates.md](../_shared/references/prompt-templates.md) for the full reference.