@selesai/code 0.8.5 → 0.8.7

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to `@selesai/code` will be documented in this file.
 
 ## [Unreleased]
 
+## [0.8.7] - 2026-08-17
+
+### Added
+- **Pi Subagents updated through upstream 0.50.0.** The bundled extension advances through upstream 0.49/0.50 (single-child `{ agent, task }` runs, per-tool-call `toolTimeoutMs` with config/env precedence, `debug.run` inspection, builtin role overrides with `tools: "inherit"`, resumable retained-child listings, indexed async result inboxes) with the Selesai fork layers on top: branding, `.selesai` config routing, `SELESAI_SUBAGENT*` env vars, declarative `chain`/`tasks`/`clarify` modes, workflow auto-relaunch wiring, and same-model retry for transient provider errors.
+- **`model-prompt-injector` extension.** Bundled and registered in the extensions manifest, it injects model-specific prompts into the system prompt when the active model matches a configured rule (provider/model globs, bare id/name patterns, first-match-wins, enabled toggle). Modes: `prepend`, `append`, or `replace`.
+- **Wire-level tool schema pruning.** `pruneToolDescriptions` (default `true`) strips every per-field `description` from tool input schemas before they reach the model, keeping one-line tool descriptions. Stripped schemas are memoized and never mutated; UI/docs definitions keep full descriptions; `keepParameterDescriptions` opts a tool out.
+- **Compact subagent tool description by default.** `toolDescriptionMode` now defaults to `"compact"` (~3.2 KB vs ~6.3 KB per model turn), and a missing/invalid custom description file falls back to compact.
+
+### Changed
+- **Slimmer default system prompt.** The always-on Pi-docs block shrank from 8 lines to 2 (paths only); docs are still read on demand when the user asks about pi.
+- **Bundled defaults** now set `pruneToolDescriptions: true`.
+- **Test coverage.** `src/extensions` (pi-* excluded) now enforces 100% stmt/branch/func/line coverage via vitest thresholds; `safeMaxTokens()` clamps missing/oversized context-window metadata to a sane default.
+
+### Fixed
+- **Subagent prompt-runtime suite passes inside subagent child environments.** The watchdog-lifecycle test now scrubs the steer env vars (`SELESAI_SUBAGENT_STEER_*`) before registering, so the steering inbox's extra `agent_end` handler cannot skew the handler count.
+
+## [0.8.6] - 2026-08-15
+
+### Added
+- **Auto-relaunching workflows.** The four `/workflow-*` modes (task, prototype, quicktype, loop) now run fully unattended: when a scripted workflow exhausts its per-run fan-out budget before the goal is clean, the async executor mints a fresh budget and re-runs the same script with the same mission and progress file, up to `config.maxWorkflowAutoRelaunches` (default 12; `0` = unlimited). Only `budget` results relaunch — real child failures still surface immediately. `AsyncStatus` gained `workflowRelaunchCount`.
+- **Packaged prompts now load.** The pi-subagents extension registers `resources_discover`, so the bundled prompts (`review-loop.md`, `parallel-*.md`, `gather-context-and-clarify.md`) are actually discoverable. The `workflow-drive.md` prompt was removed as superseded by auto-relaunch.
+- **Goal visibility on workflow launches.** Each `/workflow-*` launch emits its goal at start (visible in `subagent status` workflow emits) and names the auto-created mission after the goal (`mission.list` / `mission.show`).
+
+### Changed
+- **Bounded build→review→fix rounds.** The workflow auto-loop now instructs the builder to implement one small, self-contained slice per round ("do not attempt the whole plan") instead of the entire plan at once, with per-run timeouts (build/fix 45m, review 15m).
+- **Progress-file scoped reviews.** Builder appends a `## Round N` ledger entry (files, summary, validation) to `.pi-subagents/progress/<mode>.md`; the commentator scopes its review to the latest round entry plus the immediately preceding fix entry, falling back to the full uncommitted diff when the file is missing or empty. Blocking reviews must list a `Remaining work:` section; the next build round picks up from it.
+- **Previous review feedback now reaches the next builder round** (previously it was dropped).
+
 ## [0.8.5] - 2026-08-14
 
 ### Added

package/dist/core/agent-session.js

@@ -35,7 +35,7 @@ import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-man
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
-import { createAllToolDefinitions } from "./tools/index.js";
+import { createAllToolDefinitions, stripToolParameterDescriptions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
 /** Parse consecutive skill blocks at the start of a user message. */
@@ -2056,6 +2056,18 @@ export class AgentSession {
             toolRegistry.set(tool.name, tool);
         }
         this._toolRegistry = toolRegistry;
+        if (this.settingsManager.getPruneToolDescriptions()) {
+            const keepDescriptions = new Set();
+            for (const [name, entry] of definitionRegistry) {
+                if (entry.definition.keepParameterDescriptions)
+                    keepDescriptions.add(name);
+            }
+            for (const [name, tool] of toolRegistry) {
+                if (!keepDescriptions.has(name)) {
+                    toolRegistry.set(name, stripToolParameterDescriptions(tool));
+                }
+            }
+        }
         const nextActiveToolNames = (options?.activeToolNames ? [...options.activeToolNames] : [...previousActiveToolNames]).filter((name) => isAllowedTool(name));
         if (allowedToolNames) {
             for (const toolName of this._toolRegistry.keys()) {

package/dist/core/extensions/types.d.ts

@@ -353,6 +353,8 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
     promptGuidelines?: string[];
     /** Parameter schema (TypeBox) */
     parameters: TParams;
+    /** When global pruneToolDescriptions is enabled, keep this tool's per-field parameter descriptions on the wire (already pruned by the tool itself). */
+    keepParameterDescriptions?: boolean;
     /** Optional provider-side constrained sampling request for this tool. Set false to explicitly disable it, equivalent to leaving it undefined. */
     constrainedSampling?: false | ConstrainedSamplingConfig;
     /** Controls whether ToolExecutionComponent renders the standard colored shell or the tool renders its own framing. */

package/dist/core/provider-composer.js

@@ -2,6 +2,17 @@ import { lazyStream, } from "@earendil-works/pi-ai";
 import { getApiProvider } from "@earendil-works/pi-ai/compat";
 import { clearConfigValueCache, getConfigValueEnvVarNames, isCommandConfigValue, isConfigValueConfigured, resolveConfigValueOrThrow, resolveHeadersOrThrow, } from "./resolve-config-value.js";
 export const clearApiKeyCache = clearConfigValueCache;
+/** Sane default when a model definition omits maxTokens (kept small so providers never reject it). */
+const DEFAULT_MAX_TOKENS = 16384;
+/**
+ * Resolve a safe max output token count. Missing or non-positive values fall back
+ * (to a sane default or an inherited value); explicit values are never allowed to
+ * exceed the model's context window.
+ */
+function safeMaxTokens(value, contextWindow, fallback = DEFAULT_MAX_TOKENS) {
+    const resolved = typeof value === "number" && value > 0 ? value : fallback;
+    return Math.min(resolved, Math.max(contextWindow, 1));
+}
 function mergeCompat(base, override) {
     if (!override)
         return base;
@@ -20,6 +31,7 @@ function mergeCompat(base, override) {
     return merged;
 }
 function applyModelOverride(model, override) {
+    const contextWindow = override.contextWindow ?? model.contextWindow;
     return {
         ...model,
         name: override.name ?? model.name,
@@ -37,8 +49,8 @@ function applyModelOverride(model, override) {
                 tiers: override.cost.tiers ?? model.cost.tiers,
             }
             : model.cost,
-        contextWindow: override.contextWindow ?? model.contextWindow,
-        maxTokens: override.maxTokens ?? model.maxTokens,
+        contextWindow,
+        maxTokens: safeMaxTokens(override.maxTokens ?? model.maxTokens, contextWindow, model.maxTokens),
         compat: mergeCompat(model.compat, override.compat),
     };
 }
@@ -56,6 +68,7 @@ function modelFromJson(providerId, definition, providerConfig, defaults) {
     if (definition.maxTokens !== undefined && definition.maxTokens <= 0) {
         throw new Error(`Provider ${providerId}, model ${definition.id}: invalid maxTokens`);
     }
+    const contextWindow = definition.contextWindow ?? 128000;
     return {
         id: definition.id,
         name: definition.name ?? definition.id,
@@ -66,8 +79,8 @@ function modelFromJson(providerId, definition, providerConfig, defaults) {
         thinkingLevelMap: definition.thinkingLevelMap,
         input: (definition.input ?? ["text"]),
         cost: definition.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-        contextWindow: definition.contextWindow ?? 128000,
-        maxTokens: definition.maxTokens ?? 16384,
+        contextWindow,
+        maxTokens: safeMaxTokens(definition.maxTokens, contextWindow),
         headers: undefined,
         compat: mergeCompat(providerConfig.compat, definition.compat),
     };

package/dist/core/settings-manager.d.ts

@@ -77,6 +77,7 @@ export interface Settings {
     branchSummary?: BranchSummarySettings;
     retry?: RetrySettings;
     hideThinkingBlock?: boolean;
+    pruneToolDescriptions?: boolean;
     showCacheMissNotices?: boolean;
     externalEditor?: string;
     shellPath?: string;
@@ -236,6 +237,7 @@ export declare class SettingsManager {
     };
     getWebSocketConnectTimeoutMs(): number | undefined;
     getHideThinkingBlock(): boolean;
+    getPruneToolDescriptions(): boolean;
     getShowCacheMissNotices(): boolean;
     getExternalEditorCommand(): string;
     setHideThinkingBlock(hide: boolean): void;

package/dist/core/settings-manager.js

@@ -598,6 +598,9 @@ export class SettingsManager {
     getHideThinkingBlock() {
         return this.settings.hideThinkingBlock ?? false;
     }
+    getPruneToolDescriptions() {
+        return this.settings.pruneToolDescriptions ?? true;
+    }
     getShowCacheMissNotices() {
         return this.settings.showCacheMissNotices ?? false;
     }

package/dist/core/system-prompt.js

@@ -103,14 +103,8 @@ In addition to the tools above, you may have access to other custom tools depend
 Guidelines:
 ${guidelines}
 
-Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
-- Main documentation: ${readmePath}
-- Additional docs: ${docsPath}
-- Examples: ${examplesPath} (extensions, custom tools, SDK)
-- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
-- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md)
-- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
-- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;
+Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI): main docs ${readmePath}, additional docs ${docsPath}, examples ${examplesPath}.
+When working on pi topics, resolve docs/... and examples/... under those paths (not cwd), read the relevant .md files completely, and follow cross-references before implementing.`;
     if (appendSection) {
         prompt += appendSection;
     }

package/dist/core/system-prompt.test.js

@@ -12,6 +12,12 @@ describe("buildSystemPrompt", () => {
         expect(prompt).toMatch(/Guidelines:/);
         expect(prompt).toContain("Current working directory: /tmp/project");
     });
+    it("keeps the collapsed Pi-docs block without the per-topic filename map", () => {
+        const prompt = buildSystemPrompt({ cwd: "/tmp/project" });
+        expect(prompt).toContain("Pi documentation");
+        expect(prompt).not.toContain("When asked about:");
+        expect(prompt).not.toContain("(docs/extensions.md");
+    });
     it("keeps the default tool snippets, skills, and agents XML read-gated", () => {
         const skill = {
             name: "test-skill",

package/dist/core/tools/index.d.ts

@@ -5,6 +5,7 @@ export { createFindTool, createFindToolDefinition, type FindOperations, type Fin
 export { createGrepTool, createGrepToolDefinition, type GrepOperations, type GrepToolDetails, type GrepToolInput, type GrepToolOptions, } from "./grep.ts";
 export { createLsTool, createLsToolDefinition, type LsOperations, type LsToolDetails, type LsToolInput, type LsToolOptions, } from "./ls.ts";
 export { createReadTool, createReadToolDefinition, type ReadOperations, type ReadToolDetails, type ReadToolInput, type ReadToolOptions, } from "./read.ts";
+export { stripSchemaDescriptions, stripToolParameterDescriptions, } from "./schema-prune.ts";
 export { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationOptions, type TruncationResult, truncateHead, truncateLine, truncateTail, } from "./truncate.ts";
 export { createWriteTool, createWriteToolDefinition, type WriteOperations, type WriteToolInput, type WriteToolOptions, } from "./write.ts";
 import type { AgentTool } from "@earendil-works/pi-agent-core";

package/dist/core/tools/index.js

@@ -5,6 +5,7 @@ export { createFindTool, createFindToolDefinition, } from "./find.js";
 export { createGrepTool, createGrepToolDefinition, } from "./grep.js";
 export { createLsTool, createLsToolDefinition, } from "./ls.js";
 export { createReadTool, createReadToolDefinition, } from "./read.js";
+export { stripSchemaDescriptions, stripToolParameterDescriptions, } from "./schema-prune.js";
 export { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead, truncateLine, truncateTail, } from "./truncate.js";
 export { createWriteTool, createWriteToolDefinition, } from "./write.js";
 import { createBashTool, createBashToolDefinition } from "./bash.js";

package/dist/core/tools/schema-prune.d.ts

@@ -0,0 +1,16 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { TSchema } from "typebox";
+/**
+ * Structural deep clone that omits every `description` key at any depth while
+ * preserving all other own keys (including TypeBox internals such as `~kind`
+ * and `~optional` symbols and function-valued keys). Uses Reflect.ownKeys +
+ * property descriptors so non-enumerable metadata survives; never mutates the
+ * input.
+ */
+export declare function stripSchemaDescriptions<T>(value: T): T;
+/**
+ * Returns a shallow copy of the tool with its parameter schema descriptions
+ * stripped. Top-level tool fields (name, description, execute, ...) are
+ * untouched.
+ */
+export declare function stripToolParameterDescriptions<T extends TSchema>(tool: AgentTool<T>): AgentTool<T>;

package/dist/core/tools/schema-prune.js

@@ -0,0 +1,39 @@
+// Memoized stripped clones, keyed by the original schema root. The input is
+// never mutated; repeat calls return the same cached clone.
+const strippedSchemaCache = new WeakMap();
+/**
+ * Structural deep clone that omits every `description` key at any depth while
+ * preserving all other own keys (including TypeBox internals such as `~kind`
+ * and `~optional` symbols and function-valued keys). Uses Reflect.ownKeys +
+ * property descriptors so non-enumerable metadata survives; never mutates the
+ * input.
+ */
+export function stripSchemaDescriptions(value) {
+    if (!value || typeof value !== "object")
+        return value;
+    const cached = strippedSchemaCache.get(value);
+    if (cached !== undefined)
+        return cached;
+    const result = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
+    for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor)
+            continue;
+        if (key === "description")
+            continue;
+        if ("value" in descriptor) {
+            descriptor.value = stripSchemaDescriptions(descriptor.value);
+        }
+        Object.defineProperty(result, key, descriptor);
+    }
+    strippedSchemaCache.set(value, result);
+    return result;
+}
+/**
+ * Returns a shallow copy of the tool with its parameter schema descriptions
+ * stripped. Top-level tool fields (name, description, execute, ...) are
+ * untouched.
+ */
+export function stripToolParameterDescriptions(tool) {
+    return { ...tool, parameters: stripSchemaDescriptions(tool.parameters) };
+}

package/dist/core/tools/schema-prune.test.d.ts

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

package/dist/core/tools/schema-prune.test.js

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { SettingsManager } from "../settings-manager.js";
+import { stripSchemaDescriptions, stripToolParameterDescriptions } from "./schema-prune.js";
+describe("stripSchemaDescriptions", () => {
+    it("removes description keys at all depths (properties, anyOf arrays, items)", () => {
+        const schema = {
+            type: "object",
+            description: "root",
+            properties: {
+                name: { type: "string", description: "the name" },
+                tags: {
+                    type: "array",
+                    description: "the tags",
+                    items: { type: "string", description: "a tag" },
+                },
+                choice: {
+                    anyOf: [{ type: "string", description: "string branch" }, { type: "number" }],
+                },
+            },
+        };
+        const stripped = stripSchemaDescriptions(schema);
+        expect("description" in stripped).toBe(false);
+        expect("description" in stripped.properties).toBe(false);
+        expect("description" in stripped.properties.tags).toBe(false);
+        expect("description" in stripped.properties.tags.items).toBe(false);
+        expect("description" in stripped.properties.choice.anyOf[0]).toBe(false);
+    });
+    it("preserves non-description keys such as type, enum, required, minimum, additionalProperties", () => {
+        const schema = {
+            type: "object",
+            properties: {
+                level: { type: "string", enum: ["a", "b"], description: "level desc" },
+                count: { type: "integer", minimum: 1, description: "count desc" },
+            },
+            required: ["level"],
+            additionalProperties: false,
+        };
+        const stripped = stripSchemaDescriptions(schema);
+        expect(stripped).toEqual({
+            type: "object",
+            properties: {
+                level: { type: "string", enum: ["a", "b"] },
+                count: { type: "integer", minimum: 1 },
+            },
+            required: ["level"],
+            additionalProperties: false,
+        });
+    });
+    it("never mutates the input schema", () => {
+        const schema = {
+            type: "object",
+            properties: { name: { type: "string", description: "the name" } },
+        };
+        const snapshot = structuredClone(schema);
+        stripSchemaDescriptions(schema);
+        expect(schema).toEqual(snapshot);
+        expect(schema.properties.name.description).toBe("the name");
+    });
+    it("memoizes stripped clones per original root", () => {
+        const schema = {
+            type: "object",
+            properties: { name: { type: "string", description: "the name" } },
+        };
+        const first = stripSchemaDescriptions(schema);
+        const second = stripSchemaDescriptions(schema);
+        expect(first).toBe(second);
+    });
+    it("keeps real TypeBox schemas valid after stripping (symbols survive)", () => {
+        const schema = Type.Object({
+            name: Type.String({ description: "the name" }),
+            age: Type.Optional(Type.Integer({ minimum: 0, description: "the age" })),
+        });
+        const stripped = stripSchemaDescriptions(schema);
+        expect(Value.Check(schema, { name: "pi", age: 3 })).toBe(true);
+        expect(Value.Check(stripped, { name: "pi", age: 3 })).toBe(true);
+        expect(Value.Check(stripped, { name: "pi", age: -1 })).toBe(false);
+    });
+});
+describe("stripToolParameterDescriptions", () => {
+    it("keeps the tool description and name while stripping parameter descriptions", () => {
+        const tool = {
+            name: "read",
+            label: "Read",
+            description: "Read a file",
+            parameters: {
+                type: "object",
+                properties: { path: { type: "string", description: "file path" } },
+            },
+            execute: () => Promise.resolve({ content: [], details: {} }),
+        };
+        const stripped = stripToolParameterDescriptions(tool);
+        expect(stripped).not.toBe(tool);
+        expect(stripped.name).toBe("read");
+        expect(stripped.description).toBe("Read a file");
+        expect("description" in stripped.parameters.properties.path).toBe(false);
+        // Original tool is untouched.
+        expect("description" in tool.parameters.properties.path).toBe(true);
+    });
+});
+describe("pruneToolDescriptions setting", () => {
+    it("defaults to true", () => {
+        const manager = SettingsManager.inMemory();
+        expect(manager.getPruneToolDescriptions()).toBe(true);
+    });
+    it("respects explicit true and false", () => {
+        expect(SettingsManager.inMemory({ pruneToolDescriptions: true }).getPruneToolDescriptions()).toBe(true);
+        expect(SettingsManager.inMemory({ pruneToolDescriptions: false }).getPruneToolDescriptions()).toBe(false);
+    });
+});

package/dist/defaults/models.json

@@ -16,6 +16,7 @@
           "reasoning": true,
           "input": ["text"],
           "contextWindow": 512000,
+          "maxTokens": 64000,
           "thinkingLevelMap": {
             "minimal": null,
             "low": null,
@@ -36,6 +37,7 @@
           "reasoning": true,
           "input": ["text"],
           "contextWindow": 512000,
+          "maxTokens": 64000,
           "thinkingLevelMap": {
             "minimal": null,
             "low": null,
@@ -56,6 +58,7 @@
           "reasoning": true,
           "input": ["text", "image"],
           "contextWindow": 512000,
+          "maxTokens": 64000,
           "thinkingLevelMap": {
             "minimal": null,
             "low": "low",
@@ -75,6 +78,7 @@
           "reasoning": true,
           "input": ["text", "image"],
           "contextWindow": 262128,
+          "maxTokens": 64000,
           "thinkingLevelMap": {
             "minimal": null,
             "low": "low",
@@ -94,6 +98,7 @@
           "reasoning": true,
           "input": ["text"],
           "contextWindow": 1000000,
+          "maxTokens": 64000,
           "thinkingLevelMap": {
             "minimal": null,
             "low": "low",

package/dist/defaults/settings.json

@@ -25,6 +25,7 @@
     "git:github.com/MasuRii/pi-tool-display",
     "git:github.com/omaclaren/pi-markdown-preview"
   ],
+  "pruneToolDescriptions": true,
   "quietStartup": true,
   "retry": {
     "enabled": true,

package/dist/extensions/agent-browser.test.ts

@@ -1,7 +1,7 @@
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import agentBrowserSetupExtension, {
 	DECLINED_MARKER_NAME,
 	ensureAgentBrowser,
@@ -192,4 +192,180 @@ describe("agent-browser setup extension", () => {
 	it("declined marker path lives in the agent dir", () => {
 		expect(getDeclinedMarkerPath()).toBe(join(tmpDir, DECLINED_MARKER_NAME));
 	});
+
+	it("skips probing when the decline marker exists", async () => {
+		const { pi, handlers, exec } = makePi();
+		await agentBrowserSetupExtension(pi);
+		const markerPath = getDeclinedMarkerPath();
+		mkdirSync(dirname(markerPath), { recursive: true });
+		writeFileSync(markerPath, "1", "utf-8");
+		try {
+			await getSessionStartHandler(handlers)({ type: "session_start", reason: "startup" }, makeCtx());
+			expect(exec).not.toHaveBeenCalled();
+		} finally {
+			rmSync(markerPath, { force: true });
+		}
+	});
+
+	it("isAgentBrowserInstalled returns false when exec throws", async () => {
+		const { pi } = makePi(async () => {
+			throw new Error("spawn failed");
+		});
+		expect(await isAgentBrowserInstalled(pi)).toBe(false);
+	});
+
+	it("isAgentBrowserInstalled returns false when the probe is killed", async () => {
+		const { pi } = makePi(async () => ({ code: 0, stdout: "", stderr: "", killed: true }));
+		expect(await isAgentBrowserInstalled(pi)).toBe(false);
+	});
+
+	it("reports a timed-out npm install", async () => {
+		const execImpl = vi
+			.fn()
+			.mockResolvedValueOnce(fail) // probe: missing
+			.mockResolvedValueOnce({ code: 0, stdout: "", stderr: "", killed: true }); // npm killed
+		const { pi, handlers, exec } = makePi(execImpl as any);
+		await agentBrowserSetupExtension(pi);
+		const ctx = makeCtx();
+		await getSessionStartHandler(handlers)({ type: "session_start", reason: "startup" }, ctx);
+
+		expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("timed out"), "error");
+		expect(exec).toHaveBeenCalledTimes(2);
+	});
+
+	it("reports npm success but missing binary on PATH", async () => {
+		const execImpl = vi
+			.fn()
+			.mockResolvedValueOnce(fail) // probe: missing
+			.mockResolvedValueOnce(ok) // npm i -g agent-browser
+			.mockResolvedValueOnce(fail) // probe: still missing
+			.mockResolvedValueOnce(ok); // (unused)
+		const { pi, handlers, exec } = makePi(execImpl as any);
+		await agentBrowserSetupExtension(pi);
+		const ctx = makeCtx();
+		await getSessionStartHandler(handlers)({ type: "session_start", reason: "startup" }, ctx);
+
+		expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("still not on PATH"), "warning");
+		expect(exec).toHaveBeenCalledTimes(3);
+	});
+
+	it("warns when browser provisioning fails after install", async () => {
+		const execImpl = vi
+			.fn()
+			.mockResolvedValueOnce(fail) // probe: missing
+			.mockResolvedValueOnce(ok) // npm i -g agent-browser
+			.mockResolvedValueOnce(ok) // probe: now present
+			.mockResolvedValueOnce({ code: 1, stdout: "", stderr: "browser failed", killed: false }); // agent-browser install fails
+		const { pi, handlers, exec } = makePi(execImpl as any);
+		await agentBrowserSetupExtension(pi);
+		const ctx = makeCtx();
+		await getSessionStartHandler(handlers)({ type: "session_start", reason: "startup" }, ctx);
+
+		expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("Run `agent-browser install`"), "info");
+		expect(exec).toHaveBeenCalledTimes(4);
+	});
+
+	it("provisionBrowser returns false when exec throws", async () => {
+		const execImpl = vi
+			.fn()
+			.mockResolvedValueOnce(fail) // probe: missing
+			.mockResolvedValueOnce(ok) // npm i -g agent-browser
+			.mockResolvedValueOnce(ok) // probe: now present
+			.mockRejectedValueOnce(new Error("spawn failed")); // agent-browser install throws
+		const { pi, handlers, exec } = makePi(execImpl as any);
+		await agentBrowserSetupExtension(pi);
+		const ctx = makeCtx();
+		await getSessionStartHandler(handlers)({ type: "session_start", reason: "startup" }, ctx);
+
+		expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("Run `agent-browser install`"), "info");
+		expect(exec).toHaveBeenCalledTimes(4);
+	});
+
+	it("ensureAgentBrowser returns false when the user declines", async () => {
+		const execImpl = vi.fn().mockResolvedValue(fail);
+		const { pi } = makePi(execImpl as any);
+		const ctx = makeCtx({ confirmResult: false });
+		expect(await ensureAgentBrowser(pi, ctx)).toBe(false);
+	});
+
+	it("ensureAgentBrowser returns true when already installed", async () => {
+		const { pi } = makePi(async () => ok);
+		expect(await ensureAgentBrowser(pi, makeCtx())).toBe(true);
+	});
+
+	it("ensureAgentBrowser returns false without UI", async () => {
+		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+		const execImpl = vi.fn().mockResolvedValue(fail);
+		const { pi } = makePi(execImpl as any);
+		expect(await ensureAgentBrowser(pi, makeCtx({ hasUI: false }))).toBe(false);
+		expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining(INSTALL_COMMAND));
+	});
+
+	it("ensureAgentBrowser returns false when npm install fails", async () => {
+		const execImpl = vi
+			.fn()
+			.mockResolvedValueOnce(fail) // probe
+			.mockResolvedValueOnce({ code: 1, stdout: "", stderr: "EACCES", killed: false }); // npm fails
+		const { pi } = makePi(execImpl as any);
+		expect(await ensureAgentBrowser(pi, makeCtx())).toBe(false);
+	});
+
+	it("npm install failure surfaces stdout when stderr is empty", async () => {
+		const execImpl = vi
+			.fn()
+			.mockResolvedValueOnce(fail) // probe
+			.mockResolvedValueOnce({ code: 1, stdout: "npm error log", stderr: "", killed: false }); // npm fails with stdout only
+		const { pi } = makePi(execImpl as any);
+		const ctx = makeCtx();
+		expect(await ensureAgentBrowser(pi, ctx)).toBe(false);
+		expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("npm error log"), "error");
+	});
+
+	it("npm install failure falls back to exit status when output is empty", async () => {
+		const execImpl = vi
+			.fn()
+			.mockResolvedValueOnce(fail) // probe
+			.mockResolvedValueOnce({ code: 1, stdout: "", stderr: "", killed: false }); // npm fails with no output
+		const { pi } = makePi(execImpl as any);
+		const ctx = makeCtx();
+		expect(await ensureAgentBrowser(pi, ctx)).toBe(false);
+		expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("exit status 1"), "error");
+	});
+
+	it("notify is a no-op without UI even when the CLI is installed", async () => {
+		const { pi } = makePi(async () => ok);
+		const ctx = makeCtx({ hasUI: false });
+		expect(await ensureAgentBrowser(pi, ctx)).toBe(true);
+	});
+
+	it("ensureAgentBrowser returns true after full install flow", async () => {
+		const execImpl = vi
+			.fn()
+			.mockResolvedValueOnce(fail) // probe: missing
+			.mockResolvedValueOnce(ok) // npm i -g agent-browser
+			.mockResolvedValueOnce(ok) // probe: now present
+			.mockResolvedValueOnce(ok); // agent-browser install
+		const { pi } = makePi(execImpl as any);
+		expect(await ensureAgentBrowser(pi, makeCtx())).toBe(true);
+	});
+
+	it("cliCommand wraps args in cmd.exe on win32", () => {
+		const original = process.platform;
+		Object.defineProperty(process, "platform", { value: "win32" });
+		try {
+			const { ensureAgentBrowser: _e, ...rest } = {} as any;
+			// Re-import to pick up the platform at module scope is not needed;
+			// cliCommand is module-private, so exercise it through the public flow.
+			const execImpl = vi.fn().mockResolvedValue(ok);
+			const { pi } = makePi(execImpl as any);
+			return ensureAgentBrowser(pi, makeCtx()).then((result) => {
+				expect(result).toBe(true);
+				const call = execImpl.mock.calls[0];
+				expect(call[0]).toBe("cmd");
+				expect(call[1]).toEqual(["/c", "agent-browser", "--version"]);
+			});
+		} finally {
+			Object.defineProperty(process, "platform", { value: original });
+		}
+	});
 });

package/dist/extensions/agent-browser.ts

@@ -75,6 +75,8 @@ async function runNpmInstall(pi: ExtensionAPI): Promise<string | null> {
 	const result = await pi.exec(command, args, { timeout: INSTALL_TIMEOUT_MS });
 	if (result.killed) return "npm install timed out";
 	if (result.code !== 0) {
+		// The exit-status fallback is always non-empty, so the final || is unreachable.
+		/* v8 ignore next 1 */
 		return (result.stderr || result.stdout || `exit status ${result.code}`).trim() || "npm install failed";
 	}
 	return null;