agent-afk 5.301.2 → 5.302.0

package/dist/agent/providers/anthropic-direct/query/repair-orphan-tool-uses.d.ts

@@ -1,2 +1,10 @@
 import type { MessageParam } from '@anthropic-ai/sdk/resources';
-export declare function repairOrphanToolUses(messages: MessageParam[]): void;
+export interface OrphanRepairReport {
+    hoistedMessageIndices: number[];
+    orphanToolUseIds: string[];
+    orphanAssistantIndices: number[];
+    bridgedIndices: number[];
+    messageCountBefore: number;
+    shapeBefore: string;
+}
+export declare function repairOrphanToolUses(messages: MessageParam[]): OrphanRepairReport | null;

package/dist/agent/trace/background-agent-schema.d.ts

@@ -1,4 +1,26 @@
 import { z } from 'zod';
+export declare const BackgroundAgentStartedPayloadSchema: z.ZodObject<{
+    transition: z.ZodLiteral<"started">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    label: z.ZodString;
+    model: z.ZodString;
+}, z.core.$strip>;
+export declare const BackgroundAgentCompletedPayloadSchema: z.ZodObject<{
+    transition: z.ZodLiteral<"completed">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    durationMs: z.ZodNumber;
+    outputBytes: z.ZodNumber;
+}, z.core.$strip>;
+export declare const BackgroundAgentFailedPayloadSchema: z.ZodObject<{
+    transition: z.ZodLiteral<"failed">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    durationMs: z.ZodNumber;
+    errorClass: z.ZodString;
+    errorMessage: z.ZodString;
+}, z.core.$strip>;
 export declare const BackgroundAgentCancelledPayloadSchema: z.ZodObject<{
     transition: z.ZodLiteral<"cancelled">;
     jobId: z.ZodString;
@@ -10,3 +32,71 @@ export declare const BackgroundAgentCancelledPayloadSchema: z.ZodObject<{
     cancelledBy: z.ZodOptional<z.ZodLiteral<"model">>;
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const BackgroundAgentJoinedPayloadSchema: z.ZodObject<{
+    transition: z.ZodLiteral<"joined">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    jobStatus: z.ZodEnum<{
+        failed: "failed";
+        completed: "completed";
+        cancelled: "cancelled";
+    }>;
+}, z.core.$strip>;
+export declare const BackgroundAgentDeliveredPayloadSchema: z.ZodObject<{
+    transition: z.ZodLiteral<"delivered">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    jobStatus: z.ZodEnum<{
+        failed: "failed";
+        completed: "completed";
+        cancelled: "cancelled";
+    }>;
+}, z.core.$strip>;
+export declare const BackgroundAgentPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    transition: z.ZodLiteral<"started">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    label: z.ZodString;
+    model: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    transition: z.ZodLiteral<"completed">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    durationMs: z.ZodNumber;
+    outputBytes: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    transition: z.ZodLiteral<"failed">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    durationMs: z.ZodNumber;
+    errorClass: z.ZodString;
+    errorMessage: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    transition: z.ZodLiteral<"cancelled">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    source: z.ZodEnum<{
+        explicit: "explicit";
+        cascade: "cascade";
+    }>;
+    cancelledBy: z.ZodOptional<z.ZodLiteral<"model">>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    transition: z.ZodLiteral<"joined">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    jobStatus: z.ZodEnum<{
+        failed: "failed";
+        completed: "completed";
+        cancelled: "cancelled";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    transition: z.ZodLiteral<"delivered">;
+    jobId: z.ZodString;
+    subagentId: z.ZodString;
+    jobStatus: z.ZodEnum<{
+        failed: "failed";
+        completed: "completed";
+        cancelled: "cancelled";
+    }>;
+}, z.core.$strip>], "transition">;

package/dist/agent/trace/events.d.ts

@@ -774,6 +774,7 @@ export declare const TraceEventInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject
             stop_inject_dropped: "stop_inject_dropped";
             stop_hook_continuation: "stop_hook_continuation";
             stop_hook_cap_reached: "stop_hook_cap_reached";
+            orphan_repair: "orphan_repair";
         }>;
         durationMs: z.ZodOptional<z.ZodNumber>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
@@ -1183,6 +1184,7 @@ export declare const TraceEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             stop_inject_dropped: "stop_inject_dropped";
             stop_hook_continuation: "stop_hook_continuation";
             stop_hook_cap_reached: "stop_hook_cap_reached";
+            orphan_repair: "orphan_repair";
         }>;
         durationMs: z.ZodOptional<z.ZodNumber>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;

package/dist/agent/trace/events.session-phase.d.ts

@@ -36,6 +36,7 @@ export declare const SessionPhaseNameSchema: z.ZodEnum<{
     stop_inject_dropped: "stop_inject_dropped";
     stop_hook_continuation: "stop_hook_continuation";
     stop_hook_cap_reached: "stop_hook_cap_reached";
+    orphan_repair: "orphan_repair";
 }>;
 export declare const SessionPhasePayloadSchema: z.ZodObject<{
     phase: z.ZodEnum<{
@@ -75,6 +76,7 @@ export declare const SessionPhasePayloadSchema: z.ZodObject<{
         stop_inject_dropped: "stop_inject_dropped";
         stop_hook_continuation: "stop_hook_continuation";
         stop_hook_cap_reached: "stop_hook_cap_reached";
+        orphan_repair: "orphan_repair";
     }>;
     durationMs: z.ZodOptional<z.ZodNumber>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;

package/dist/agent/trace/events.subagent-lifecycle.d.ts

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+export declare const ToolFailureClassSchema: z.ZodEnum<{
+    budget: "budget";
+    abort: "abort";
+    "policy-refusal": "policy-refusal";
+    timeout: "timeout";
+    "permission-denied": "permission-denied";
+    "hook-block": "hook-block";
+    "elicitation-declined": "elicitation-declined";
+    "denial-breaker": "denial-breaker";
+    "repeat-failure": "repeat-failure";
+    "no-such-target": "no-such-target";
+}>;
+export declare const SubagentStartedPayloadSchema: z.ZodObject<{
+    transition: z.ZodLiteral<"started">;
+    subagentId: z.ZodString;
+    parentId: z.ZodString;
+    model: z.ZodString;
+    allowedTools: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    systemPromptHash: z.ZodOptional<z.ZodString>;
+    promptHead: z.ZodOptional<z.ZodString>;
+    agentType: z.ZodOptional<z.ZodString>;
+    resolvedAgentType: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SubagentSucceededPayloadSchema: z.ZodObject<{
+    transition: z.ZodLiteral<"succeeded">;
+    subagentId: z.ZodString;
+    durationMs: z.ZodNumber;
+    turnCount: z.ZodNumber;
+    totalCostUsd: z.ZodOptional<z.ZodNumber>;
+    outputBytes: z.ZodNumber;
+    stopReason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SubagentFailedPayloadSchema: z.ZodObject<{
+    transition: z.ZodLiteral<"failed">;
+    subagentId: z.ZodString;
+    errorClass: z.ZodString;
+    errorMessage: z.ZodString;
+    partialOutputBytes: z.ZodNumber;
+    failureClass: z.ZodOptional<z.ZodEnum<{
+        budget: "budget";
+        abort: "abort";
+        "policy-refusal": "policy-refusal";
+        timeout: "timeout";
+        "permission-denied": "permission-denied";
+        "hook-block": "hook-block";
+        "elicitation-declined": "elicitation-declined";
+        "denial-breaker": "denial-breaker";
+        "repeat-failure": "repeat-failure";
+        "no-such-target": "no-such-target";
+    }>>;
+}, z.core.$strip>;
+export declare const SubagentCancelledPayloadSchema: z.ZodObject<{
+    transition: z.ZodLiteral<"cancelled">;
+    subagentId: z.ZodString;
+    source: z.ZodEnum<{
+        explicit: "explicit";
+        cascade: "cascade";
+    }>;
+    timeout: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const SubagentLifecyclePayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    transition: z.ZodLiteral<"started">;
+    subagentId: z.ZodString;
+    parentId: z.ZodString;
+    model: z.ZodString;
+    allowedTools: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    systemPromptHash: z.ZodOptional<z.ZodString>;
+    promptHead: z.ZodOptional<z.ZodString>;
+    agentType: z.ZodOptional<z.ZodString>;
+    resolvedAgentType: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    transition: z.ZodLiteral<"succeeded">;
+    subagentId: z.ZodString;
+    durationMs: z.ZodNumber;
+    turnCount: z.ZodNumber;
+    totalCostUsd: z.ZodOptional<z.ZodNumber>;
+    outputBytes: z.ZodNumber;
+    stopReason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    transition: z.ZodLiteral<"failed">;
+    subagentId: z.ZodString;
+    errorClass: z.ZodString;
+    errorMessage: z.ZodString;
+    partialOutputBytes: z.ZodNumber;
+    failureClass: z.ZodOptional<z.ZodEnum<{
+        budget: "budget";
+        abort: "abort";
+        "policy-refusal": "policy-refusal";
+        timeout: "timeout";
+        "permission-denied": "permission-denied";
+        "hook-block": "hook-block";
+        "elicitation-declined": "elicitation-declined";
+        "denial-breaker": "denial-breaker";
+        "repeat-failure": "repeat-failure";
+        "no-such-target": "no-such-target";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    transition: z.ZodLiteral<"cancelled">;
+    subagentId: z.ZodString;
+    source: z.ZodEnum<{
+        explicit: "explicit";
+        cascade: "cascade";
+    }>;
+    timeout: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>], "transition">;

package/dist/agent/trace/types.session-phase.d.ts

@@ -1,4 +1,4 @@
-export type SessionPhaseName = 'bootstrap_start' | 'bootstrap_done' | 'session_init_start' | 'session_init_done' | 'mcp_connect_start' | 'mcp_connect_done' | 'mcp_server_start' | 'mcp_server_done' | 'loop_start' | 'loop_end' | 'model_ttfb' | 'interrupt_halt' | 'rate_limit' | 'ttfb_timeout' | 'usage_limit_pause' | 'usage_limit_resume' | 'overload_pause' | 'overload_resume' | 'idle_watchdog_fired' | 'pause_extension_granted' | 'suspected_loop' | 'compaction_disabled' | 'boot_warning' | 'workspace_subscribed' | 'workspace_delivery' | 'gate_shape' | 'session_id_assigned' | 'many_image_degraded' | 'stream_accepted_after_drop' | 'connection_retry' | 'usage_notice' | 'tool_degraded' | 'strategy_nudge_fired' | 'stop_inject_dropped' | 'stop_hook_continuation' | 'stop_hook_cap_reached';
+export type SessionPhaseName = 'bootstrap_start' | 'bootstrap_done' | 'session_init_start' | 'session_init_done' | 'mcp_connect_start' | 'mcp_connect_done' | 'mcp_server_start' | 'mcp_server_done' | 'loop_start' | 'loop_end' | 'model_ttfb' | 'interrupt_halt' | 'rate_limit' | 'ttfb_timeout' | 'usage_limit_pause' | 'usage_limit_resume' | 'overload_pause' | 'overload_resume' | 'idle_watchdog_fired' | 'pause_extension_granted' | 'suspected_loop' | 'compaction_disabled' | 'boot_warning' | 'workspace_subscribed' | 'workspace_delivery' | 'gate_shape' | 'session_id_assigned' | 'many_image_degraded' | 'stream_accepted_after_drop' | 'connection_retry' | 'usage_notice' | 'tool_degraded' | 'strategy_nudge_fired' | 'stop_inject_dropped' | 'stop_hook_continuation' | 'stop_hook_cap_reached' | 'orphan_repair';
 export interface SessionPhasePayload {
     phase: SessionPhaseName;
     durationMs?: number;

package/dist/bundled-plugins/awa-bundled/skills/automate/SKILL.md

@@ -1,13 +1,72 @@
 ---
 name: automate
-description: "Set up a scheduled headless afk run that pushes a summary to Telegram. Use when the user wants to automate a recurring task via the afk daemon scheduler (cron) with push-notified results."
+description: "Set up a scheduled headless afk run that pushes a summary to Telegram. Accepts a task description, directory path, or session ID — for session IDs, runs an isolation-contamination probe via read_witness to assess automation fit before gating on an explicit APPROVE token. Use when the user wants to automate a recurring task via the afk daemon scheduler (cron) with push-notified results."
 disable-model-invocation: true
 context: load
+failure_modes:
+  - contaminated fit verdict (probe sub-agent receives original session rationale)
+  - APPROVE token accepted without presenting command sequence preview
+  - schedule created without confirming Telegram end-to-end
 ---
 
 Set up a recurring headless task using afk's **native** scheduler. Do NOT hand-roll launchd plists or shell scripts — afk has first-class scheduling: the `create_schedule` tool writes `~/.afk/config/schedules.json` entries that `afk daemon` runs on cron.
 
+## Input routing
+
+The argument is one of three forms:
+- **Task description / directory path** — proceed directly to the Scout + Prompt designer wave below.
+- **Session ID** — run the fit-assessment flow first (Waves 0–1 + authorization gate) to determine whether the session is automatable before building a schedule.
+
+---
+
+## Session ID path: fit-assessment
+
+### Wave 0 — Signal extraction (orchestrator, synchronous)
+
+Read the session facet with `get_facet` (pass `fields: ["duration_minutes", "user_message_count"]` so the goal and first prompt never enter the extraction) and the session's tool calls with `read_witness` (`kinds: ["tool_call"]`), then extract four flat signals:
+
+- `duration` — the facet's `duration_minutes`
+- `user_messages` — the facet's `user_message_count`. Do not count witness events for this: the trace records no user turns, and its `queued_user_message` events cover only messages typed mid-turn, so they undercount.
+- `llm_branch_steps` — count of tool calls whose branch condition is model output rather than exit code (i.e., tool calls following a reasoning step that is not mechanically determined)
+- `command_sequence` — ordered list of distinct bash/shell commands issued, with item count
+
+Emit **Artifact 1**: `duration=Xm, user_messages=N, llm_branch_steps=M, command_sequence=[cmd1, cmd2, …] (K distinct commands)`. This is the only input forwarded to Wave 1 — the session ID, original user message, and any rationale are withheld.
+
+### Wave 1 — Automation-fit probe (isolated sub-agent)
+
+Receives Artifact 1 **only**. Denied: session ID, original user message, any framing about why the task was run manually. Denied write tools.
+
+Applies the five-point rubric:
+
+| Criterion | Points |
+|---|---|
+| `duration ≤ 10m` | +1 |
+| `user_messages ≤ 2` | +1 |
+| `llm_branch_steps == 0` | +1 |
+| Command sequence is idempotent with no destructive commands lacking a guard | +1 |
+| No step requires live user judgment | +1 |
+
+Emits one of:
+- `FIT [score=N]` (≥ 4) — proceed to gate
+- `PARTIAL [score=N, guard=<exact modification required>]` (2–3) — surface the guard to the user before the gate; do not proceed until acknowledged
+- `UNFIT [score=N]` (≤ 1) — halt with explanation; do not generate a schedule
+
+### Authorization gate
+
+For FIT or acknowledged-PARTIAL verdicts, the orchestrator presents the proposed schedule: name, cron expression, and command sequence preview. Waits for an explicit token:
+
+- `APPROVE` (or bare "yes") — proceed to Scout + schedule creation
+- `MODIFY <field> <value>` — adjust one parameter and re-present
+- `ABORT` — exit with `AUTOMATED_NOTHING`
+
+Do not proceed to schedule creation until APPROVE is recorded.
+
+---
+
+## Schedule creation (all paths)
+
 Dispatch two sub-agents in parallel:
+
 1. **Scout** — call `list_schedules` and inspect `~/.afk/config/schedules.json` for existing or overlapping jobs, run `afk service status` to see whether the daemon is installed as a launchd service and running, confirm Telegram is configured (`TELEGRAM_BOT_TOKEN` + `AFK_TELEGRAM_ALLOWED_CHAT_IDS`), and scan the target project folder for conventions. Report conflicts, daemon/service state, and any missing prerequisite.
 2. **Prompt designer** — draft the recurring task's `command` string: a self-contained prompt (or `/skill --flags` invocation) sent verbatim into a freshly spawned session each run. The daemon session starts cold, so encode all input context explicitly, and require the run to END by calling the `send_telegram` tool with a concise, push-ready summary.
 
@@ -17,3 +76,13 @@ When both return:
 - Schedules only fire while the daemon is running, so make it survive reboot/crash: if `afk service status` shows the daemon isn't installed, run `afk service install daemon` (launchd `RunAtLoad` + `KeepAlive` on macOS).
 
 Dispatch a **verification** sub-agent to confirm the job registered (`list_schedules`), the daemon is running (`afk service status`), and — by running the task's `command` once as a one-shot (`afk chat "<command>"`) — that the Telegram summary actually arrives. On failure, diagnose (Telegram config, daemon not running, cron syntax, prompt shape) and fix before exiting. Report the schedule id, cron, `notifyOn`, daemon/service status, and the next scheduled run.
+
+## Completeness contract (session ID path only)
+
+Before claiming Done, confirm all five items are present in the terminal report:
+
+1. **Wave 0 signal report** — duration, user-message count, LLM-branch count, command sequence with item count stated
+2. **Wave 1 fit verdict** — score and tier (FIT / PARTIAL / UNFIT) stated
+3. **Authorization token** — APPROVE, MODIFY \<field\> \<value\>, or ABORT recorded
+4. **Schedule artifact** — schedule ID and cron expression stated
+5. **PARTIAL guard** — if applicable, exact guard surfaced to user before the gate

package/dist/bundled-plugins/awa-bundled/skills/shadow-verify/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: shadow-verify
-description: "Dispatch a parallel adversarial verifier wave after any high-stakes sub-agent investigation (code reviews, audits, findings reports, large refactors, gap analyses) — or whenever a sub-agent asserts a claim with high-confidence language (\"confident\", \"certain\", \"clearly\", ≥80%), since confidence is a trigger, not a verdict. Shadow verifiers independently re-derive 2–3 key claims from scratch using tool calls only, returning CONFIRMED/REFUTED/STALE/UNVERIFIABLE, and flag disagreements before the user acts. Use when sub-agent output will drive decisions, file changes, commits, or external side-effects."
+description: "Dispatch a parallel adversarial verifier wave after any high-stakes sub-agent investigation (code reviews, audits, findings reports, large refactors, gap analyses) — or whenever a sub-agent asserts a claim with high-confidence language (\"confident\", \"certain\", \"clearly\", ≥80%), since confidence is a trigger, not a verdict. Default mode: shadow verifiers independently re-derive 2–3 key claims from scratch using tool calls only. --findings-list mode: exhaustively verifies every finding in a pre-existing findings document before any action phase is dispatched, producing a numbered completeness checklist and a terminal gate verdict (VERIFIED/PARTIAL/BLOCKED). Both modes return CONFIRMED/REFUTED/STALE/UNVERIFIABLE verdicts and flag disagreements before the user acts."
+argument-hint: "[--findings-list <file | inline-findings>] [--goal <session-goal>] [--action <planned-action>]"
 context: load
 ---
 
@@ -9,29 +10,43 @@ context: load
 
 When a sub-agent (or wave) returns investigation findings, code-review conclusions, audit claims, refactor plans, gap-analysis results, or counts that will drive user decisions or file changes, do NOT surface the report. Instead, run a shadow verification wave **before** merging.
 
+---
+
+## Invocation modes
+
+This skill has two invocation modes that share the same verifier machinery, normalization pre-flight, merge rules, gate logic, and composition-axis guard — but differ in scope and output shape.
+
+**Default mode (no flag):** Sample 2–3 highest-stakes claims from a sub-agent's live output and verify them before surfacing the report. Optimized for latency — catches critical errors without blocking on exhaustive coverage.
+
+**`--findings-list` mode:** Exhaustively verify every finding in a pre-existing findings document (a file path or inline text) before any downstream action phase is dispatched. Every finding 1–N must appear in the output checklist — no finding may be omitted or left blank. Produces a terminal gate verdict (`VERIFIED` / `PARTIAL` / `BLOCKED`) that controls whether a downstream action phase may proceed. Use this when an operator supplies a research-phase output and wants a completeness guarantee before committing to action.
+
+---
+
 ### Pre-flight: claim normalization and scale guard
 
-Before dispatching verifiers, the coordinating agent normalizes each claim to a canonical form:
+Before dispatching any verifiers (in either mode), the coordinating agent normalizes each finding/claim to a canonical tuple:
 
 ```
-[CLAIM_ID] <subject> :: <predicate> :: <evidence_ref>
+[FINDING_ID] <subject> :: <predicate> :: <evidence_ref>
 ```
 
-`evidence_ref` must be a concrete pointer — a file path, line number, git ref, config key, or API endpoint. Claims that cannot be anchored to a concrete `evidence_ref` are classified **`UNVERIFIABLE`** immediately and removed from the verification queue. They are preserved in the final output under a dedicated section with the reason they could not be anchored (no re-derivation sub-agent is dispatched for them).
+`evidence_ref` must be a concrete pointer — a file path, line number, git ref, config key, or API endpoint. Claims that cannot be anchored to a concrete `evidence_ref` are classified **`UNVERIFIABLE`** immediately and removed from the verification queue. They are preserved in the final output under a **dedicated UNVERIFIABLE section** with the reason they could not be anchored (no re-derivation sub-agent is dispatched for them).
 
-**Scale cap:** if the normalized claim list exceeds 50 items, the coordinating agent halts and asks the operator to scope the investigation before proceeding. Verification at scale degrades into noise; a 50-item cap prevents a finding flood from becoming an echo-chamber rubber-stamp.
+**Scale cap:**
+- *Default mode:* if the normalized claim list exceeds 50 items, the coordinating agent halts and asks the operator to scope the investigation before proceeding. Verification at scale degrades into noise; a 50-item cap prevents a finding flood from becoming an echo-chamber rubber-stamp.
+- *`--findings-list` mode:* if the normalized findings list exceeds 30 items, the orchestrator halts and asks the operator to scope before proceeding. Exhaustive verification is more expensive per item; a tighter cap prevents runaway fan-out.
 
-Select 2–3 of the highest-stakes normalized claims to send to the verifier wave. Prefer claims that are (a) decision-driving, (b) expressed with high-confidence language, or (c) hard to re-derive from a single artifact.
+**Claim selection (default mode only):** After normalization, select 2–3 of the highest-stakes normalized claims to send to the verifier wave. Prefer claims that are (a) decision-driving, (b) expressed with high-confidence language, or (c) hard to re-derive from a single artifact. In `--findings-list` mode, every finding after normalization enters the queue — no sampling.
 
 ---
 
 **Wave 2 — Adversarial verifiers (parallel, independent):**
-1. Extract 2–3 concrete, re-checkable claims from the returned report (e.g., "X function is unused", "file Y exceeds 300 lines", "PR targets main", "no tests cover Z") and normalize them to `[CLAIM_ID] subject :: predicate :: evidence_ref` form as described above.
+1. Normalize claims as described above. In default mode, extract 2–3 concrete, re-checkable claims from the returned report (e.g., "X function is unused", "file Y exceeds 300 lines", "PR targets main", "no tests cover Z"). In `--findings-list` mode, all normalized findings enter the queue.
 2. Dispatch one shadow sub-agent per claim, in parallel. Each receives the normalized claim text + the user's original goal + **the search surface** — the inventory of files, directories, or URLs the original investigation touched. It must NOT receive the original agent's reasoning, verdict, confidence language, or the specific line/region it concluded from. **Withhold the conclusion, not the map.** Withholding the map too does not buy extra independence — the verifier still has to reach the same evidence, it just spends its budget guessing paths to get there. Measured: one verifier denied the inventory spent 70 `grep` + 18 `read_file` calls re-locating files the parent already had paths for, guessed 5 nonexistent paths on the way, and hit its tool-loop ceiling before finishing. The independence that matters is epistemic (re-deriving the verdict), not navigational.
    - The inventory is a **starting surface, not a boundary**: it does not satisfy the composition-axis guard below, and a verifier that reads only inside it still returns `evidence_base: artifact-internal`. At least one primary source outside that surface is still required for `independent-rederivation`.
    - **Default to `subagent_type: "research-agent"` (mechanically locked to Read/Grep/Glob/WebFetch/WebSearch — cannot Edit/commit/push).** If the claim requires Bash to verify (running a failing test, `gh pr view`, `git log origin/...`), fall back to a Bash-capable subagent type with `isolation: "worktree"` and prepend this prefix to the prompt: *"Verifier sub-agent — do not Edit, Write, commit, push, `gh pr create`, or `curl`. Return findings only."*
    - **Set `id_prefix`** to a short label identifying the claim being verified, e.g. `"verify: unused export"` or `"verify: missing null check"`, so the live TUI shows which claim each verifier is checking.
-   - **Every verifier dispatch carries an explicit budget** — `max_tool_use_iterations` (a wave of 2–3 claim checks needs ~15–25 rounds each, not 50) plus the cheapest sufficient model. An unbudgeted verifier does not fail loudly: it exhausts the default tool-round ceiling, terminates `stopReason: "tool_use_loop_capped"`, and emits its verdict from a tools-stripped wind-down round built on partial evidence. A `CONFIRMED` produced that way is indistinguishable from a real one and silently defeats the entire point of the wave. Check each returned verifier's stop reason before merging its verdict; treat a capped or wind-down verifier as `UNVERIFIABLE`, not as a verdict.
+   - **Every verifier dispatch carries an explicit budget** — `max_tool_use_iterations` (a wave of 2–3 claim checks needs ~15–25 rounds each, not 50; `--findings-list` waves with many findings should budget proportionally but cap individual verifiers at 12 rounds each) plus the cheapest sufficient model. An unbudgeted verifier does not fail loudly: it exhausts the default tool-round ceiling, terminates `stopReason: "tool_use_loop_capped"`, and emits its verdict from a tools-stripped wind-down round built on partial evidence. A `CONFIRMED` produced that way is indistinguishable from a real one and silently defeats the entire point of the wave. Check each returned verifier's stop reason before merging its verdict; treat a capped or wind-down verifier as `UNVERIFIABLE`, not as a verdict.
 3. Each verifier re-derives the verdict independently using tool calls only — never re-reading the original report's reasoning. Returns `{claim_id, verifier_verdict, evidence_pointer, evidence_base}`, where `verifier_verdict` is one of `CONFIRMED`, `REFUTED`, `STALE`, or `UNVERIFIABLE`, and `evidence_base` is `independent-rederivation` (read primary sources *outside* the cited artifact's boundary) or `artifact-internal` (re-read only the cited file/region). On `REFUTED` or `STALE`, the verifier also emits a corrected or updated finding.
 
 ---
@@ -53,7 +68,9 @@ Bound the loop: at most 3 verification rounds per session. Claims still unresolv
 
 **Gate verdict:**
 
-After all verifier results are merged, the coordinating agent emits a single gate verdict before surfacing findings downstream:
+After all verifier results are merged, the coordinating agent emits a single gate verdict before surfacing findings downstream. The verdict shape differs by mode:
+
+*Default mode:*
 
 | Verdict | Condition |
 |---|---|
@@ -61,7 +78,31 @@ After all verifier results are merged, the coordinating agent emits a single gat
 | `WARN` | One or more claims are `STALE`, `UNVERIFIABLE`, or `UNVERIFIED-COMPOSITION`/`UNVERIFIED-ECHO-CHAMBER`; proceed only with explicit caveats attached |
 | `FAIL` | One or more claims `REFUTED`; findings must not be forwarded until re-investigated |
 
-A `FAIL` verdict blocks downstream use. The coordinating agent surfaces the specific refuted claims and their contradicting evidence to the operator before any remediation work begins. A `WARN` may proceed but must carry the flagged claims and their tags — stripping the caveats before forwarding is a protocol violation.
+*`--findings-list` mode* — emit a numbered completeness checklist followed by a terminal gate verdict:
+
+```
+Verification checklist (N findings total):
+[1] <finding summary> → CONFIRMED (file:line)
+[2] <finding summary> → REFUTED (contradicting_pointer) [was: confident, now: refuted]
+[3] <finding summary> → STALE (updated_pointer) [was true, now stale]
+[4] <finding summary> → UNVERIFIABLE (reason: no concrete evidence_ref) [needs-human-review]
+...
+
+UNVERIFIABLE findings (pre-flight, no verifier dispatched):
+[5] <finding summary> → UNVERIFIABLE (reason: file not found)
+
+Gate verdict: BLOCKED — finding [2] refuted; do not proceed to action phase.
+```
+
+Terminal gate verdicts for `--findings-list` mode:
+
+| Verdict | Condition |
+|---|---|
+| `VERIFIED` | All findings are `CONFIRMED` or `UNVERIFIABLE` with annotation; action phase may proceed |
+| `PARTIAL` | ≥1 finding is `STALE` or `UNVERIFIABLE [budget-exhausted]`; proceed with explicit caveats |
+| `BLOCKED` | ≥1 finding is `REFUTED`; action phase must not be dispatched until the operator resolves the conflict or re-scopes the finding list |
+
+In both modes: a `FAIL` / `BLOCKED` verdict blocks downstream use. The coordinating agent surfaces the specific refuted claims and their contradicting evidence to the operator before any remediation work begins. A `WARN` / `PARTIAL` may proceed but must carry the flagged claims and their tags — stripping the caveats before forwarding is a protocol violation.
 
 ---
 
@@ -78,6 +119,8 @@ A verifier that re-derives a claim by re-reading the *same* file/region the orig
 **When to invoke:**
 Any time sub-agent output will drive user decisions, file edits, commits, external side-effects, or is the basis of a user-facing summary — including gap analyses, audit findings, and issue lists that will be forwarded to a downstream session. Treat **high-confidence language as a trigger in its own right**: when a review/audit sub-agent asserts a claim with markers like "confident", "certain", "clearly", "obviously", "must be", or a stated probability ≥ 80%, verify it as if it were decision-driving regardless of stakes. Confidence is a trigger, not a verdict.
 
+Use `--findings-list` when the operator supplies a pre-existing findings document (from a prior research session, a handed-off report, or an audit output) and needs a completeness guarantee — a numbered checklist with every finding accounted for — before an action phase is dispatched.
+
 **Skip when:**
 Sub-agent ran inside an orchestrator skill that already verifies (`resolve`, `diagnose`, `appmap`); sub-agent returned explicit failure; work was purely exploratory and no decision follows; or the session is **text-terminal** — a pure explanation, architecture walkthrough, onboarding Q&A, or capability map that names no mutated artifact (file/PR/commit/test), where there are no re-checkable state claims for adversarial verifiers to re-derive (assess coverage, coherence, and citation density instead of dispatching re-derivation sub-agents).
 

package/dist/cli/commands/doctor-checks.d.ts

@@ -11,6 +11,7 @@ export declare function checkXaiAuth(): Promise<Check>;
 export interface NpmBinOnPathDeps {
     platform?: NodeJS.Platform;
     pathDelimiter?: string;
+    execSync?: typeof import('child_process').execSync;
 }
 export declare function checkNpmBinOnPath(deps?: NpmBinOnPathDeps): Promise<Check>;
 export declare function checkDirWritable(name: string, getDir: () => string): Promise<Check>;