@oh-my-pi/pi-coding-agent 17.0.4 → 17.0.6

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

@@ -13,7 +13,7 @@
  * Modes use this class and add their own I/O layer on top.
  */
 import type { InMemorySnapshotStore } from "@oh-my-pi/hashline";
-import { Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, type StreamFn, ThinkingLevel, type ToolChoiceDirective } from "@oh-my-pi/pi-agent-core";
+import { Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, type AgentToolResult, type StreamFn, ThinkingLevel, type ToolChoiceDirective } from "@oh-my-pi/pi-agent-core";
 import { type CompactionResult, type ShakeConfig } from "@oh-my-pi/pi-agent-core/compaction";
 import type { AssistantMessage, Context, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ResetCreditAccountStatus, ResetCreditRedeemOutcome, ResetCreditTarget, ServiceTier, ServiceTierByFamily, ServiceTierFamily, SimpleStreamOptions, TextContent, ToolChoice, UsageReport } from "@oh-my-pi/pi-ai";
 import { Effort } from "@oh-my-pi/pi-ai";
@@ -41,6 +41,7 @@ import type { Goal, GoalModeState } from "../goals/state.js";
 import type { HindsightSessionState } from "../hindsight/state.js";
 import { type IrcMessage } from "../irc/bus.js";
 import { type MnemopiSessionState } from "../mnemopi/state.js";
+import { type PlanApprovalDetails } from "../plan-mode/approved-plan.js";
 import type { PlanModeState } from "../plan-mode/state.js";
 import { type SecretObfuscator } from "../secrets/obfuscator.js";
 import { type ConfiguredThinkingLevel } from "../thinking.js";
@@ -542,6 +543,8 @@ export declare class AgentSession {
      * is already armed and waiting.
      */
     armPrewalk(target: Model, thinkingLevel?: ConfiguredThinkingLevel): void;
+    /** Validate the active plan artifact and shape an `xd://propose` result for review-mode hosts. */
+    preparePlanForReview(title: string): Promise<AgentToolResult<PlanApprovalDetails>>;
     constructor(config: AgentSessionConfig);
     /** Model registry for API key resolution and model discovery */
     get modelRegistry(): ModelRegistry;
@@ -657,10 +660,26 @@ export declare class AgentSession {
     get isAborting(): boolean;
     /** Wait until streaming and deferred recovery work are fully settled. */
     waitForIdle(): Promise<void>;
+    /**
+     * Prevent advisor notes from starting hidden primary turns while a headless
+     * caller prints and drains the final primary response.
+     */
+    prepareForHeadlessAdvisorDrain(): void;
+    /**
+     * Wait for active advisor reviews and their emitted card events before a
+     * headless caller disposes the session. Returns `false` and logs work disposal
+     * will abandon when the shared deadline expires or an advisor fails.
+     */
+    waitForAdvisorCatchup(timeoutMs: number): Promise<boolean>;
     drainAsyncJobDeliveriesForAcp(options?: {
         timeoutMs?: number;
     }): Promise<boolean>;
-    /** Most recent assistant message in agent state. */
+    /**
+     * Most recent settled assistant message. A classifier-refusal turn pruned
+     * from active context at settle is still reported until the next run
+     * starts, so terminal-outcome consumers (print mode, task executor) see
+     * the refusal error rather than the previous turn — or nothing.
+     */
     getLastAssistantMessage(): AssistantMessage | undefined;
     /** Current effective system prompt blocks (includes any per-turn extension modifications) */
     get systemPrompt(): string[];
@@ -714,6 +733,21 @@ export declare class AgentSession {
      * Changes take effect before the next model call.
      */
     setActiveToolsByName(toolNames: string[]): Promise<void>;
+    /**
+     * Restore an enabled tool set with its exact top-level versus `xd://` partition.
+     *
+     * Both inputs are required because {@link setActiveToolsByName} only receives the
+     * enabled name list and classifies mounts from the *current* `#mountedXdevToolNames`.
+     * Rollback/restore callers must pass the snapshotted mounted subset so names that
+     * were top-level stay pinned (`#runtimeSelectedToolNames`) and names that were under
+     * `xd://` remain mount-eligible, even when the live mount set has drifted.
+     *
+     * Names outside `mountedToolNames` are pinned top-level for this application;
+     * names in the mounted subset remain eligible for xdev mounting. Delegates the
+     * actual apply through `#applyActiveToolsByName` and restores the prior runtime
+     * selection if that apply throws.
+     */
+    setActiveToolPresentation(toolNames: string[], mountedToolNames: string[]): Promise<void>;
     /** Rebuild the base system prompt using the current active tool set. */
     refreshBaseSystemPrompt(): Promise<void>;
     /**
@@ -738,6 +772,8 @@ export declare class AgentSession {
      * to avoid racing against the delivery turn.
      */
     get hasPostPromptWork(): boolean;
+    /** Register post-prompt work in tests without driving a full agent turn. */
+    trackPostPromptTaskForTests(task: Promise<unknown>): void;
     /** All messages including custom types like BashExecutionMessage */
     get messages(): AgentMessage[];
     /** Latest image attachments addressable by tools as `Image #N` or `attachment://N`. */
@@ -1036,10 +1072,10 @@ export declare class AgentSession {
      */
     getAvailableModels(): Model[];
     /**
-     * Set the thinking level. `auto` enables per-turn classification; the selector
-     * itself is never written to the session log, but resolved concrete levels are
-     * persisted when real user turns are classified so resumed sessions keep the
-     * last resolved effort instead of reverting to pending auto.
+     * Set the thinking level. `auto` enables per-turn classification. Entering
+     * auto writes its provisional level plus `configured: "auto"` immediately,
+     * giving external readers an authoritative selection receipt before the next
+     * user turn. Later classifications persist only changed concrete resolutions.
      */
     setThinkingLevel(level: ConfiguredThinkingLevel | undefined, persist?: boolean): void;
     /**

package/dist/types/session/messages.d.ts

@@ -250,5 +250,11 @@ export declare function sanitizeRehydratedOpenAIResponsesAssistantMessage(messag
  * - Agent's transormToLlm option (for prompt calls and queued messages)
  * - Compaction's generateSummary (for summarization)
  * - Custom extensions and tools
+ *
+ * Settled history converts once and is reused per message identity: an
+ * append-only turn on the same array re-pays only the new suffix, and an
+ * unchanged re-convert of the same array hands back the same outer `Message[]`.
+ * Owner mutations (prune/shake/strip-images) invalidate the affected message
+ * through the shared registry before the next pass.
  */
 export declare function convertToLlm(messages: AgentMessage[]): Message[];

package/dist/types/session/session-paths.d.ts

@@ -10,16 +10,33 @@ export declare function computeDefaultSessionDir(cwd: string, storage: SessionSt
  * Write a breadcrumb linking the current terminal to a session file.
  * The breadcrumb contains the cwd and session path so --continue can
  * find "this terminal's last session" even when running concurrent instances.
+ *
+ * `fresh` marks a `/new` (or freshly-minted) session boundary whose JSONL is
+ * not yet materialized (new-session persistence is lazy until assistant output
+ * exists). A fresh breadcrumb is honored by {@link readTerminalBreadcrumbEntry}
+ * even when its target file is still absent, so relaunch/auto-resume reopens the
+ * post-`/new` session instead of falling back to the pre-`/new` transcript. Once
+ * the session materializes the caller rewrites the breadcrumb with `fresh:false`
+ * so a later external delete is still treated as a genuinely stale crumb.
  */
-export declare function writeTerminalBreadcrumb(cwd: string, sessionFile: string): void;
+export declare function writeTerminalBreadcrumb(cwd: string, sessionFile: string, fresh?: boolean): void;
 export interface TerminalBreadcrumb {
     cwd: string;
     sessionFile: string;
+    /** The recorded session file exists on disk right now. */
+    exists: boolean;
+    /** Recorded as a `/new` fresh-session boundary whose JSONL may not exist yet. */
+    fresh: boolean;
 }
 /**
  * Read the raw terminal breadcrumb for the current terminal.
- * Returns the recorded cwd + session file (verified to exist) regardless of
- * whether the recorded cwd still matches the current one. Callers decide how
- * to interpret a cwd mismatch (e.g. a moved/renamed worktree).
+ * Returns the recorded cwd + session file regardless of whether the recorded
+ * cwd still matches the current one. Callers decide how to interpret a cwd
+ * mismatch (e.g. a moved/renamed worktree).
+ *
+ * A missing target file yields `null` UNLESS the breadcrumb is a `fresh`
+ * boundary — a lazy `/new` session whose JSONL was never written — in which case
+ * the entry is returned with `exists:false` so the caller can distinguish it
+ * from a genuinely stale/deleted breadcrumb.
  */
 export declare function readTerminalBreadcrumbEntry(): Promise<TerminalBreadcrumb | null>;

package/dist/types/tools/browser/aria/aria-snapshot.d.ts

@@ -19,13 +19,23 @@ export declare function captureAriaSnapshot(page: Page, root: ElementHandle | nu
  */
 export declare function resolveAriaRefHandle(page: Page, ref: string): Promise<ElementHandle | null>;
 /**
- * Recognize the explicit `[ref=eN]` selector forms and return the bare ref id,
- * else null. Accepts `aria-ref=e5` (Playwright-MCP style), `aria-ref/e5`, and
- * `ariaref/e5` — lets `tab.click("aria-ref=e5")` etc. act on snapshot refs. A
- * bare `e5` is intentionally NOT a ref selector: the cmux backend already uses
- * bare `eN`/`@eN` for its own observe ids, so requiring the prefix keeps action
- * selectors meaning the same thing on both backends. (`tab.ref("e5")` still
- * accepts a bare id directly.)
+ * Guard the selector funnels: `tab.click`/`type`/`fill`/`waitFor*`/`scrollIntoView`
+ * take string selectors only, but user `run` code routinely passes the ElementHandle
+ * from `tab.id(n)`/`tab.ref(...)` (or an un-awaited Promise of one) straight in.
+ * Without this the value reaches `.trim()`/`.startsWith()` and throws the opaque,
+ * minified `A.trim is not a function` instead of a recovery-naming ToolError.
+ */
+export declare function assertSelectorString(selector: unknown): asserts selector is string;
+/**
+ * Recognize a snapshot-ref selector and return the bare ref id, else null.
+ * Accepts `aria-ref=e5` (Playwright-MCP style), `aria-ref/e5`, `ariaref/e5`,
+ * and bare `e5`/`@e5`: agents copy ids straight out of the snapshot YAML
+ * (`[ref=e5]`), so `tab.click("e5")` must act on the ref instead of falling
+ * through to a CSS tag selector that can never match. Bare ids are safe to
+ * claim here — an eN tag name is not real HTML, and the tab-worker backend's
+ * observe ids are numeric (`tab.id(7)`), so refs are its only eN namespace.
+ * (The cmux backend parses selectors itself and routes bare `eN` to its own
+ * observe ids; either way `eN` means "the id from the last page dump".)
  */
 export declare function parseAriaRefSelector(selector: string): string | null;
 /**

package/dist/types/tools/browser/cmux/socket-client.d.ts

@@ -9,6 +9,8 @@ export declare class CmuxSocketClient {
     constructor(opts: {
         socketPath: string;
         password?: string;
+        relayId?: string;
+        relayToken?: string;
     });
     connect(): Promise<void>;
     request(method: string, params: Record<string, unknown>, opts?: {

package/dist/types/tools/browser/tab-protocol.d.ts

@@ -115,6 +115,8 @@ export interface RunErrorPayload {
     stack?: string;
     isToolError: boolean;
     isAbort: boolean;
+    /** The worker could not restore tab-scoped browser state and must be recycled. */
+    recoverTab?: boolean;
 }
 export type WorkerOutbound = {
     type: "ready";

package/dist/types/tools/browser/tab-worker.d.ts

@@ -27,6 +27,8 @@ export interface OpTimeouts {
 }
 /** Resolve the per-op fail-fast ceilings for a given cell budget. */
 export declare function resolveOpTimeouts(cellTimeoutMs: number): OpTimeouts;
+/** Queue a wheel event without treating a delayed renderer acknowledgement as dispatch failure. */
+export declare function dispatchScroll(dispatch: () => Promise<void>, ackTimeoutMs?: number): Promise<void>;
 /**
  * Effective timeout for a wait helper (`waitFor*`). A positive explicit `{ timeout }` is
  * honored but clamped to the cell budget so it still fails fast + named; raising the tool

package/dist/types/tools/gh.d.ts

@@ -7,9 +7,10 @@ import type { OutputMeta } from "./output-meta.js";
 /** Runs `gh --json` for issue data, retrying without optional stateReason on older gh releases. */
 export declare function githubIssueJsonWithStateReasonFallback<T>(cwd: string, args: readonly string[], signal: AbortSignal | undefined, options?: git.GhCommandOptions): Promise<T>;
 declare const githubSchema: import("arktype/internal/variants/object.ts").ObjectType<{
-    op: "pr_checkout" | "pr_create" | "pr_push" | "repo_view" | "run_watch" | "search_code" | "search_commits" | "search_issues" | "search_prs" | "search_repos";
+    op: "file_read" | "pr_checkout" | "pr_create" | "pr_push" | "repo_view" | "run_watch" | "search_code" | "search_commits" | "search_issues" | "search_prs" | "search_repos";
     repo?: string | undefined;
     branch?: string | undefined;
+    path?: string | undefined;
     pr?: string | string[] | undefined;
     force?: boolean | undefined;
     forceWithLease?: boolean | undefined;
@@ -219,14 +220,15 @@ export declare class GithubTool implements AgentTool<typeof githubSchema, GhTool
     private readonly session;
     readonly name = "github";
     readonly approval: (args: unknown) => ToolApprovalDecision;
-    readonly summary = "Interact with GitHub issues, pull requests, and repositories";
+    readonly summary = "Interact with GitHub repositories, files, pull requests, and Actions";
     readonly loadMode = "discoverable";
     readonly label = "GitHub";
     readonly description: string;
     readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
-        op: "pr_checkout" | "pr_create" | "pr_push" | "repo_view" | "run_watch" | "search_code" | "search_commits" | "search_issues" | "search_prs" | "search_repos";
+        op: "file_read" | "pr_checkout" | "pr_create" | "pr_push" | "repo_view" | "run_watch" | "search_code" | "search_commits" | "search_issues" | "search_prs" | "search_repos";
         repo?: string | undefined;
         branch?: string | undefined;
+        path?: string | undefined;
         pr?: string | string[] | undefined;
         force?: boolean | undefined;
         forceWithLease?: boolean | undefined;

package/dist/types/tools/hub/index.d.ts

@@ -117,7 +117,7 @@ export declare class HubTool implements AgentTool<typeof hubSchema, HubDetails>
         timeout?: number | undefined;
     }, {}>;
     readonly strict = true;
-    readonly interruptible = true;
+    readonly interruptible: (params: Partial<HubParams>) => boolean;
     readonly loadMode = "essential";
     readonly examples: readonly ToolExample<typeof hubSchema.infer>[];
     constructor(session: ToolSession);

package/dist/types/tools/hub/jobs.d.ts

@@ -44,6 +44,7 @@ interface TrackedJobLike {
     status: string;
     label: string;
     startTime: number;
+    latestDetails?: Record<string, unknown>;
     resultText?: string;
     errorText?: string;
 }

package/dist/types/tools/hub/types.d.ts

@@ -30,6 +30,8 @@ export interface JobSnapshot {
     status: "running" | "completed" | "failed" | "cancelled";
     label: string;
     durationMs: number;
+    /** Effective task model selector, including an explicit reasoning suffix when configured. */
+    resolvedModel?: string;
     resultText?: string;
     errorText?: string;
 }

package/dist/types/tools/tool-timeouts.d.ts

@@ -35,7 +35,7 @@ export declare const TOOL_TIMEOUTS: {
     readonly lsp: {
         readonly default: 20;
         readonly min: 5;
-        readonly max: 60;
+        readonly max: 300;
     };
     readonly debug: {
         readonly default: 30;

package/dist/types/tools/xdev.d.ts

@@ -32,9 +32,11 @@ import type { ToolRenderer } from "./renderers.js";
 /**
  * Discoverable built-ins that must stay top-level even when xdev mounting is
  * active: `todo` feeds the todo prelude/prewalk machinery, `ask` is the
- * model's user-interaction affordance, and `grep` is the redirect target of
- * the bash interceptor rules — each loses its harness integration if hidden
- * behind dispatch.
+ * model's user-interaction affordance, `grep` is the redirect target of the
+ * bash interceptor rules, and `web_search` is invoked directly by most models
+ * (which have no notion of the `xd://` protocol) so hiding it behind dispatch
+ * makes it unreachable in practice (issue #5973) — each loses its harness
+ * integration or usability if hidden behind dispatch.
  */
 export declare const XDEV_KEEP_TOP_LEVEL: Record<string, true>;
 /**

package/dist/types/utils/git.d.ts

@@ -219,6 +219,39 @@ export declare function fetch(cwd: string, remote: string, source: string, targe
 export declare function readTree(cwd: string, treeish: string, options?: Pick<CommandOptions, "env" | "signal">): Promise<void>;
 /** Write the current index as a tree and return its object id. */
 export declare function writeTree(cwd: string, options?: Pick<CommandOptions, "env" | "signal">): Promise<string>;
+/** Outcome of {@link detachGitDir}. */
+export type DetachGitDirResult = 
+/** `worktreeRoot` had no `.git`; nothing to detach. */
+"no-git"
+/** `.git` already resolves to an independent object DB — left untouched. */
+ | "independent"
+/** Detached into a standalone repo borrowing `sourceCommonDir`'s objects. */
+ | "detached";
+/**
+ * Sever a copied/mounted working tree from the git metadata it shares with a
+ * source checkout, turning it into a standalone repository that borrows the
+ * source object database through `objects/info/alternates`.
+ *
+ * Isolation backends (reflink/apfs/btrfs/rcopy…) materialise `merged` by
+ * copying `worktreeRoot` byte-for-byte. When `worktreeRoot` is a **linked git
+ * worktree** its `.git` is a pointer file (`gitdir: …/worktrees/<name>`), so
+ * the copy still resolves HEAD/index/refs through the source repo — a task's
+ * `git checkout`/`commit` inside the isolation then mutates the *parent*
+ * checkout. The rcopy `git worktree add` path leaks the other way: task
+ * branches land in the shared ref namespace and stack on each other.
+ *
+ * After detaching, the working tree keeps its files verbatim while:
+ * - HEAD, refs, and the index are frozen to the snapshot at call time;
+ * - all commits/branches the task creates stay private to the isolation;
+ * - objects resolve against `sourceCommonDir` via alternates, so history reads
+ *   and later `git fetch <merged>` object transfer keep working;
+ * - the source checkout's HEAD, branch, index, and working tree are untouched.
+ *
+ * A full-copy `.git` (non-worktree source) already owns its object DB and is
+ * returned as `"independent"` without modification. `worktreeRoot` without a
+ * `.git` yields `"no-git"`.
+ */
+export declare function detachGitDir(worktreeRoot: string, sourceCommonDir: string): Promise<DetachGitDirResult>;
 /** Run `git show` on a revision. */
 export declare const show: ((cwd: string, revision: string, options?: {
     format?: string;

package/dist/types/vibe/__tests__/token-rate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/vibe/runtime.d.ts

@@ -83,6 +83,17 @@ export declare class VibeSessionRegistry {
     static global(): VibeSessionRegistry;
     /** Reset the global registry. Test-only. */
     static resetGlobalForTests(): void;
+    /**
+     * Insert a bare worker record without the spawn/job machinery. Test-only —
+     * lets {@link aggregateVibeWorkerTokensPerSecond} be exercised against a
+     * fake roster + AgentRegistry session without driving a real turn.
+     */
+    registerRecordForTests(record: {
+        id: string;
+        cli?: VibeCli;
+        ownerId: string;
+        state?: VibeSessionState;
+    }): void;
     listIds(owner: string): string[];
     /**
      * Live screen snapshots for rich rendering (the "TV wall"): one entry per
@@ -122,3 +133,15 @@ export declare class VibeSessionRegistry {
     /** Kill every session belonging to `owner` (vibe-mode exit / teardown). Returns the number killed. */
     killAll(owner: string, manager?: AsyncJobManager): Promise<number>;
 }
+/**
+ * Aggregate tok/s across every live vibe worker session owned by `ownerId`.
+ * Returns null when no workers are streaming (so callers can fall back to
+ * their own rate unchanged). The director is often idle while workers stream,
+ * so without this aggregation the status-line tok/s badge would show a stale
+ * value while parallel work is actively generating tokens.
+ *
+ * Reads each worker's last assistant message via {@link calculateTokensPerSecond}
+ * — the same leaf calculator the main status line uses — so worker rates are
+ * computed identically to the main session's rate.
+ */
+export declare function aggregateVibeWorkerTokensPerSecond(ownerId: string): number | null;

package/dist/types/web/search/providers/codex.d.ts

@@ -25,7 +25,7 @@ export interface CodexSearchParams {
  */
 export declare function searchCodex(params: SearchParams): Promise<SearchResponse>;
 /**
- * Checks if Codex web search is available.
+ * Checks whether Codex web search has an API key or OAuth credential.
  */
 export declare function hasCodexSearch(authStorage: AuthStorage): Promise<boolean>;
 /** Search provider for OpenAI Codex web search. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "17.0.4",
+	"version": "17.0.6",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -52,17 +52,17 @@
 		"@agentclientprotocol/sdk": "1.2.1",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "17.0.4",
-		"@oh-my-pi/omp-stats": "17.0.4",
-		"@oh-my-pi/pi-agent-core": "17.0.4",
-		"@oh-my-pi/pi-ai": "17.0.4",
-		"@oh-my-pi/pi-catalog": "17.0.4",
-		"@oh-my-pi/pi-mnemopi": "17.0.4",
-		"@oh-my-pi/pi-natives": "17.0.4",
-		"@oh-my-pi/pi-tui": "17.0.4",
-		"@oh-my-pi/pi-utils": "17.0.4",
-		"@oh-my-pi/pi-wire": "17.0.4",
-		"@oh-my-pi/snapcompact": "17.0.4",
+		"@oh-my-pi/hashline": "17.0.6",
+		"@oh-my-pi/omp-stats": "17.0.6",
+		"@oh-my-pi/pi-agent-core": "17.0.6",
+		"@oh-my-pi/pi-ai": "17.0.6",
+		"@oh-my-pi/pi-catalog": "17.0.6",
+		"@oh-my-pi/pi-mnemopi": "17.0.6",
+		"@oh-my-pi/pi-natives": "17.0.6",
+		"@oh-my-pi/pi-tui": "17.0.6",
+		"@oh-my-pi/pi-utils": "17.0.6",
+		"@oh-my-pi/pi-wire": "17.0.6",
+		"@oh-my-pi/snapcompact": "17.0.6",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/api-logs": "^0.220.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",

package/src/advisor/__tests__/advisor.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from "bun:test";
 import type { AgentMessage, AgentTelemetryConfig } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage } from "@oh-my-pi/pi-ai";
 import * as AIError from "@oh-my-pi/pi-ai/error";
+import { kCursorExecResolved } from "@oh-my-pi/pi-ai/utils/block-symbols";
 import type { TUI } from "@oh-my-pi/pi-tui";
 import { type } from "arktype";
 import type { ModelRegistry } from "../../config/model-registry";
@@ -519,6 +520,58 @@ describe("advisor", () => {
 			expect(message.content).toBe(originalContent);
 		});
 
+		it("keeps advise when Cursor emits exec-resolved native tools outside the grant (issue #5900)", () => {
+			const message = {
+				role: "assistant",
+				content: [
+					{ type: "text", text: "Investigating the networking design." },
+					{
+						type: "toolCall",
+						id: "tc-grep",
+						name: "grep",
+						arguments: { pattern: "backoff" },
+						[kCursorExecResolved]: true,
+					},
+					{
+						type: "toolCall",
+						id: "tc-bash",
+						name: "bash",
+						arguments: { command: "ls" },
+						[kCursorExecResolved]: true,
+					},
+					{
+						type: "toolCall",
+						id: "tc-advise",
+						name: "advise",
+						arguments: { note: "The retry backoff looks unbounded." },
+					},
+				],
+				stopReason: "toolUse",
+			} as unknown as AssistantMessage;
+			const originalContent = message.content;
+
+			// Grant is `advise` only (WATCHDOG.yml `tools: []`). The native grep/bash
+			// frames already ran server-side through the advisor-scoped bridge, which
+			// rejected them in-band; they must not discard the legitimate advise.
+			expect(quarantineAdvisorUnsafeOutput(message, new Set(["advise"]))).toBeUndefined();
+			expect(message.stopReason).toBe("toolUse");
+			expect(message.content).toBe(originalContent);
+			expect(JSON.stringify(message)).toContain("unbounded");
+		});
+
+		it("still quarantines an ungranted native tool that was not exec-resolved", () => {
+			const message = {
+				role: "assistant",
+				content: [{ type: "toolCall", id: "tc-bash", name: "bash", arguments: { command: "ls" } }],
+				stopReason: "toolUse",
+			} as unknown as AssistantMessage;
+
+			expect(quarantineAdvisorUnsafeOutput(message, new Set(["advise"]))).toBe(
+				"Advisor response quarantined: requested unavailable tool bash",
+			);
+			expect(message.stopReason).toBe("error");
+		});
+
 		it("sanitizes destructive advise notes even when advise is an allowed tool", () => {
 			const message = {
 				role: "assistant",
@@ -865,6 +918,65 @@ describe("advisor", () => {
 			expect(promptInputs[1]).toContain("second");
 		});
 
+		it("waits for an in-flight review within the catch-up deadline", async () => {
+			const promptStarted = Promise.withResolvers<void>();
+			const releasePrompt = Promise.withResolvers<void>();
+			const messages: AgentMessage[] = [{ role: "user", content: "first", timestamp: 1 } as AgentMessage];
+			const agent: AdvisorAgent = {
+				prompt: async () => {
+					promptStarted.resolve();
+					await releasePrompt.promise;
+				},
+				abort: () => {},
+				reset: () => {},
+				state: { messages: [] },
+			};
+			const runtime = new AdvisorRuntime(agent, {
+				snapshotMessages: () => messages,
+				enqueueAdvice: () => {},
+			});
+
+			runtime.onTurnEnd();
+			await promptStarted.promise;
+			let settled = false;
+			const catchup = runtime.waitForCatchup(1000, 1).then(caughtUp => {
+				settled = true;
+				return caughtUp;
+			});
+			await Promise.resolve();
+			expect(settled).toBe(false);
+
+			releasePrompt.resolve();
+			expect(await catchup).toBe(true);
+		});
+
+		it("reports an in-flight review that exceeds the catch-up deadline", async () => {
+			const promptStarted = Promise.withResolvers<void>();
+			const releasePrompt = Promise.withResolvers<void>();
+			const messages: AgentMessage[] = [{ role: "user", content: "first", timestamp: 1 } as AgentMessage];
+			const agent: AdvisorAgent = {
+				prompt: async () => {
+					promptStarted.resolve();
+					await releasePrompt.promise;
+				},
+				abort: () => {},
+				reset: () => {},
+				state: { messages: [] },
+			};
+			const runtime = new AdvisorRuntime(agent, {
+				snapshotMessages: () => messages,
+				enqueueAdvice: () => {},
+			});
+
+			runtime.onTurnEnd();
+			await promptStarted.promise;
+			expect(await runtime.waitForCatchup(20, 1)).toBe(false);
+			expect(runtime.backlog).toBe(1);
+
+			releasePrompt.resolve();
+			await settleUntil(() => runtime.backlog === 0);
+		});
+
 		it("preserves the next user turn when an accepted empty stop is pruned", async () => {
 			const promptInputs: string[] = [];
 			const agent = makeAgent(promptInputs);
@@ -3779,6 +3891,44 @@ describe("advisor", () => {
 	// or it strands and #drainStrandedQueuedMessages auto-resumes it. Do not swap
 	// the call site back to session `isStreaming`.
 	describe("resolveAdvisorDeliveryChannel", () => {
+		it("preserves every severity when a headless drain forbids primary turns", () => {
+			for (const severity of [undefined, "nit", "concern", "blocker"] as const) {
+				expect(
+					resolveAdvisorDeliveryChannel({
+						severity,
+						autoResumeSuppressed: false,
+						streaming: false,
+						aborting: false,
+						terminalAnswerNoQueuedWork: true,
+						preserveOnly: true,
+					}),
+				).toBe("preserve");
+			}
+		});
+
+		it("keeps live headless advice on normal delivery channels until the primary finishes", () => {
+			expect(
+				resolveAdvisorDeliveryChannel({
+					severity: "nit",
+					autoResumeSuppressed: false,
+					streaming: true,
+					aborting: false,
+					preserveOnly: true,
+				}),
+			).toBe("aside");
+			for (const severity of ["concern", "blocker"] as const) {
+				expect(
+					resolveAdvisorDeliveryChannel({
+						severity,
+						autoResumeSuppressed: false,
+						streaming: true,
+						aborting: false,
+						preserveOnly: true,
+					}),
+				).toBe("steer");
+			}
+		});
+
 		it("routes a non-interrupting nit to the aside queue regardless of state", () => {
 			expect(
 				resolveAdvisorDeliveryChannel({

package/src/advisor/advise-tool.ts

@@ -101,6 +101,8 @@ export function isAdvisorInterruptImmuneTurnActive(opts: {
 /**
  * Decide how one advisor note reaches the primary agent.
  *
+ * - A `preserveOnly` caller records every note that arrives while the primary
+ *   is idle as a visible card and never starts a new primary turn.
  * - A non-interrupting `nit` always rides the non-interrupting aside queue.
  * - An interrupting `concern`/`blocker` is normally steered into the agent: into
  *   the live turn while one is streaming, or (when idle) a triggered turn so the
@@ -129,7 +131,9 @@ export function resolveAdvisorDeliveryChannel(opts: {
 	aborting: boolean;
 	terminalAnswerNoQueuedWork?: boolean;
 	interruptImmuneTurnActive?: boolean;
+	preserveOnly?: boolean;
 }): AdvisorDeliveryChannel {
+	if (opts.preserveOnly && !opts.streaming) return "preserve";
 	if (!isInterruptingSeverity(opts.severity)) return "aside";
 	if (opts.autoResumeSuppressed && (opts.aborting || !opts.streaming)) return "preserve";
 	if (opts.terminalAnswerNoQueuedWork && opts.severity !== "blocker" && !opts.streaming && !opts.aborting)