@selesai/code 0.13.32 → 0.13.34

package/dist/extensions/pi-subagents/test/unit/structured-output-rejection.test.ts

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { Message } from "@earendil-works/pi-ai";
+import {
+	formatStructuredOutputRejectionError,
+	INVALID_STRUCTURED_OUTPUT_SCHEMA_ERROR,
+	MAX_STRUCTURED_OUTPUT_REJECTION_ERROR_BYTES,
+	STRUCTURED_OUTPUT_REJECTION_ERROR,
+	STRUCTURED_OUTPUT_VALIDATOR_UNAVAILABLE_ERROR,
+} from "../../src/runs/shared/structured-output.ts";
+
+function messages(...values: unknown[]): Message[] {
+	return values as Message[];
+}
+
+describe("structured output rejection evidence", () => {
+	it("uses the latest failed result and correlates results without names by toolCallId", () => {
+		const result = formatStructuredOutputRejectionError(messages(
+			{ role: "assistant", content: [{ type: "toolCall", id: "structured-1", name: "structured_output", arguments: { value: {} } }] },
+			{ role: "toolResult", toolCallId: "structured-1", isError: true, content: [{ type: "text", text: "Structured output validation failed: first: is required" }] },
+			{ role: "toolResult", toolName: "structured_output", toolCallId: "structured-2", isError: true, content: [{ type: "text", text: "Structured output validation failed: second: is required" }] },
+		));
+
+		assert.equal(result, "Structured output validation failed: second: is required");
+	});
+
+	it("ignores unrelated failures and returns a truthful fallback", () => {
+		const result = formatStructuredOutputRejectionError(messages(
+			{ role: "toolResult", toolName: "read", isError: true, content: [{ type: "text", text: "EISDIR" }] },
+		));
+
+		assert.equal(result, STRUCTURED_OUTPUT_REJECTION_ERROR);
+	});
+
+	it("does not expose schema compiler diagnostics", () => {
+		const sentinel = "PRIVATE_SCHEMA_SENTINEL";
+		const result = formatStructuredOutputRejectionError(messages(
+			{ role: "toolResult", toolName: "structured_output", isError: true, content: [{ type: "text", text: `Structured output validation failed: invalid outputSchema: Invalid regular expression: /${sentinel}_[invalid/u` }] },
+		));
+
+		assert.equal(result, INVALID_STRUCTURED_OUTPUT_SCHEMA_ERROR);
+		assert.equal(result.includes(sentinel), false);
+	});
+
+	it("categorizes unavailable validation without exposing setup details", () => {
+		const sentinel = "PRIVATE_SETUP_SENTINEL";
+		const result = formatStructuredOutputRejectionError(messages(
+			{ role: "toolResult", toolName: "structured_output", isError: true, content: [{ type: "text", text: `Cannot load typebox/compile for structured output validation (direct import failed: ${sentinel} at /private/compiler.ts)` }] },
+		));
+
+		assert.equal(result, STRUCTURED_OUTPUT_VALIDATOR_UNAVAILABLE_ERROR);
+		assert.equal(result.includes(sentinel), false);
+	});
+
+	it("redacts payload and stack details and clamps complete UTF-8 characters", () => {
+		const secret = "do-not-leak";
+		const oversized = `Structured output validation failed: ${"界".repeat(2_000)}\nsubmitted value: ${secret}\n    at /private/project/file.ts:1:1`;
+		const result = formatStructuredOutputRejectionError(messages(
+			{ role: "toolResult", toolName: "structured_output", isError: true, content: [{ type: "text", text: oversized }] },
+		));
+
+		assert.ok(Buffer.byteLength(result, "utf8") <= MAX_STRUCTURED_OUTPUT_REJECTION_ERROR_BYTES);
+		assert.equal(result.includes("�"), false);
+		assert.equal(result.includes(secret), false);
+		assert.equal(result.includes("/private/project"), false);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/workflow-terminal-proof.test.ts

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, it } from "node:test";
+import type { AsyncStatus, ProcessTerminal, WorkflowChildSummary } from "../../src/shared/types.ts";
+import { readWorkflowTerminalProof } from "../../src/runs/background/workflow-terminal-proof.ts";
+
+type Steps = NonNullable<AsyncStatus["steps"]>;
+
+function summary(overrides: Partial<WorkflowChildSummary> = {}): WorkflowChildSummary {
+	return {
+		version: 1,
+		parentToolCallId: "parent-tool-call",
+		workflowRunId: "workflow-run",
+		inventoryComplete: true,
+		workflowState: "completed",
+		children: [{ childId: "main", runId: "child-run", state: "completed" }],
+		...overrides,
+	};
+}
+
+const asyncChild = [{ agent: "worker", workflowKey: "main", runId: "child-run", async: true, status: "completed" }] as Steps;
+
+function observedChild(): ProcessTerminal {
+	return {
+		version: 1,
+		state: "observed",
+		runId: "child-run",
+		runnerProcessInstanceId: "runner-1",
+		observedAt: 1_234,
+		instances: [{ kind: "runner", processInstanceId: "runner-1", closeObservedAt: 1_234, exitCode: 0, signal: null }],
+	};
+}
+
+function withFixture(run: (dirs: { root: string; asyncDir: string; writeChild: (status: object, proof?: ProcessTerminal) => void }) => void): void {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), "workflow-terminal-proof-"));
+	const asyncDir = path.join(root, "workflow-run");
+	fs.mkdirSync(asyncDir, { recursive: true });
+	const writeChild = (status: object, proof?: ProcessTerminal) => {
+		const childDir = path.join(root, "child-run");
+		fs.mkdirSync(childDir, { recursive: true });
+		fs.writeFileSync(path.join(childDir, "status.json"), JSON.stringify({ runId: "child-run", mode: "single", startedAt: 1, lastUpdate: 2, ...status }));
+		if (proof) fs.writeFileSync(path.join(childDir, "process-terminal.json"), JSON.stringify(proof));
+	};
+	try {
+		run({ root, asyncDir, writeChild });
+	} finally {
+		fs.rmSync(root, { recursive: true, force: true });
+	}
+}
+
+const runnerIdentity = { version: 1, runId: "child-run", runnerProcessInstanceId: "runner-1" };
+
+describe("readWorkflowTerminalProof", () => {
+	it("keeps an open inventory pending", () => withFixture(({ asyncDir }) => {
+		assert.deepEqual(readWorkflowTerminalProof(asyncDir, asyncChild, summary({ inventoryComplete: false, workflowState: "running" }), 0, 2_000), {
+			version: 1, kind: "workflow", runId: "workflow-run", state: "pending", dispatchClosed: false, reason: "Workflow dispatch is still open.",
+		});
+	}));
+
+	it("keeps closed dispatch pending until the child's exit is observed", () => withFixture(({ asyncDir, writeChild }) => {
+		writeChild({ state: "complete", processTerminal: { ...runnerIdentity, state: "pending" } });
+		assert.deepEqual(readWorkflowTerminalProof(asyncDir, asyncChild, summary(), 0, 2_000), {
+			version: 1, kind: "workflow", runId: "workflow-run", state: "pending", dispatchClosed: true,
+			reason: "async workflow child main process-terminal proof is missing",
+		});
+	}));
+
+	it("returns observed after every async child has writer-exit evidence", () => withFixture(({ asyncDir, writeChild }) => {
+		const proof = observedChild();
+		writeChild({ state: "complete", processTerminal: { ...runnerIdentity, state: "pending" } }, proof);
+		assert.deepEqual(readWorkflowTerminalProof(asyncDir, asyncChild, summary({ workflowState: "stopped" }), 0, 1_000), {
+			version: 1, kind: "workflow", runId: "workflow-run", state: "observed", dispatchClosed: true, observedAt: 1_234, children: [proof],
+		});
+	}));
+
+	it("accepts a child whose runner failed before starting", () => withFixture(({ asyncDir, writeChild }) => {
+		const notStarted = { ...runnerIdentity, state: "not-started" } as ProcessTerminal;
+		writeChild({ state: "failed", error: "runner failed to start", processTerminal: notStarted });
+		assert.deepEqual(readWorkflowTerminalProof(asyncDir, asyncChild, summary({ workflowState: "failed" }), 0, 2_000), {
+			version: 1, kind: "workflow", runId: "workflow-run", state: "observed", dispatchClosed: true, observedAt: 2_000, children: [notStarted],
+		});
+	}));
+
+	it("needs no process evidence for synchronous children that run inside the host", () => withFixture(({ asyncDir }) => {
+		const syncChild = [{ agent: "worker", workflowKey: "main", async: false, status: "completed" }] as Steps;
+		assert.deepEqual(readWorkflowTerminalProof(asyncDir, syncChild, summary({ children: [{ childId: "main", state: "completed" }] }), 0, 2_000), {
+			version: 1, kind: "workflow", runId: "workflow-run", state: "observed", dispatchClosed: true, observedAt: 2_000, children: [],
+		});
+	}));
+
+	it("reports host commands as unknown", () => withFixture(({ asyncDir }) => {
+		assert.deepEqual(readWorkflowTerminalProof(asyncDir, [], summary({ children: [] }), 1, 2_000), {
+			version: 1, kind: "workflow", runId: "workflow-run", state: "unknown", dispatchClosed: true, reason: "Workflow host commands have no process-terminal proof.",
+		});
+	}));
+});

package/dist/extensions/rtk.test.ts

@@ -41,9 +41,11 @@ esac
 function makePi() {
 	const handlers = new Map<string, Function[]>();
 	const pi = {
-		exec: async (cmd: string, args: string[], opts?: { timeout?: number }) =>
+		exec: async (cmd: string, args: string[]) =>
 			new Promise((resolve) => {
-				execFile(cmd, args, { timeout: opts?.timeout }, (error, stdout, stderr) => {
+				// The shim runs under the suite's own load: enforcing the extension's production
+				// 2s budget here kills it, which the extension reports as a failed probe.
+				execFile(cmd, args, (error, stdout, stderr) => {
 					if (error) {
 						// execFile reports non-zero exits as errors; keep the real exit code.
 						const code =
@@ -63,8 +65,14 @@ function makePi() {
 	return { pi: pi as any, handlers };
 }
 
+// Registration is deferred off startup (the managed-binary probe may spawn a process),
+// so hook installation can outlast vi.waitFor's 1s default on a loaded machine.
+function waitFor<T>(assertion: () => T | Promise<T>): Promise<T> {
+	return vi.waitFor(assertion, { timeout: 5_000 });
+}
+
 async function getToolCall(handlers: Map<string, Function[]>): Promise<Function> {
-	await vi.waitFor(() => expect(handlers.has("tool_call")).toBe(true));
+	await waitFor(() => expect(handlers.has("tool_call")).toBe(true));
 	return handlers.get("tool_call")![0]!;
 }
 
@@ -131,7 +139,7 @@ posixOnly("rtk extension", () => {
 			const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
 			const { pi, handlers } = makePi();
 			rtkExtension(pi);
-			await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("rtk gain failed")));
+			await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("rtk gain failed")));
 			expect(handlers.has("tool_call")).toBe(false);
 		} finally {
 			if (previousPath) process.env.PATH = previousPath;
@@ -156,7 +164,7 @@ posixOnly("rtk extension", () => {
 		// Override exec so --version fails.
 		pi.exec = vi.fn(async () => ({ code: 1, stdout: "", stderr: "not found", killed: false }));
 		rtkExtension(pi);
-		await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("failed --version")));
+		await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("failed --version")));
 		expect(handlers.has("tool_call")).toBe(false);
 	});
 
@@ -166,7 +174,7 @@ posixOnly("rtk extension", () => {
 		ensureToolMock.mockResolvedValue("rtk");
 		pi.exec = vi.fn(async () => ({ code: 0, stdout: "garbage output", stderr: "", killed: false }));
 		rtkExtension(pi);
-		await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("could not parse version")));
+		await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("could not parse version")));
 		expect(handlers.has("tool_call")).toBe(false);
 	});
 
@@ -176,7 +184,7 @@ posixOnly("rtk extension", () => {
 		ensureToolMock.mockResolvedValue("rtk");
 		pi.exec = vi.fn(async () => ({ code: 0, stdout: "   ", stderr: "", killed: false }));
 		rtkExtension(pi);
-		await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("<empty output>")));
+		await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("<empty output>")));
 		expect(handlers.has("tool_call")).toBe(false);
 	});
 
@@ -186,7 +194,7 @@ posixOnly("rtk extension", () => {
 		ensureToolMock.mockResolvedValue("rtk");
 		pi.exec = vi.fn(async () => ({ code: 0, stdout: "rtk 0.22.0", stderr: "", killed: false }));
 		rtkExtension(pi);
-		await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("too old")));
+		await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("too old")));
 		expect(handlers.has("tool_call")).toBe(false);
 	});
 
@@ -195,7 +203,7 @@ posixOnly("rtk extension", () => {
 		ensureToolMock.mockRejectedValue(new Error("download failed"));
 		const { pi, handlers } = makePi();
 		rtkExtension(pi);
-		await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("managed installation failed")));
+		await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("managed installation failed")));
 		expect(handlers.has("tool_call")).toBe(false);
 	});
 
@@ -204,7 +212,7 @@ posixOnly("rtk extension", () => {
 		ensureToolMock.mockRejectedValue("plain string failure");
 		const { pi, handlers } = makePi();
 		rtkExtension(pi);
-		await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("plain string failure")));
+		await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("plain string failure")));
 		expect(handlers.has("tool_call")).toBe(false);
 	});
 
@@ -213,7 +221,7 @@ posixOnly("rtk extension", () => {
 		ensureToolMock.mockResolvedValue(undefined);
 		const { pi, handlers } = makePi();
 		rtkExtension(pi);
-		await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("unavailable")));
+		await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("unavailable")));
 		expect(handlers.has("tool_call")).toBe(false);
 	});
 
@@ -225,7 +233,7 @@ posixOnly("rtk extension", () => {
 			throw new Error("spawn ENOENT");
 		});
 		rtkExtension(pi);
-		await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("verification failed")));
+		await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("verification failed")));
 		expect(handlers.has("tool_call")).toBe(false);
 	});
 
@@ -237,7 +245,7 @@ posixOnly("rtk extension", () => {
 			throw "string failure";
 		});
 		rtkExtension(pi);
-		await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("string failure")));
+		await waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining("string failure")));
 		expect(handlers.has("tool_call")).toBe(false);
 	});
 

package/dist/extensions/tps.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { calculateLiveTps, calculateReliableTps, type TpsTiming } from "./tps.ts";
+import { calculateLiveTps, calculateReliableTps, setupTpsTracker, type TpsTiming } from "./tps.ts";
 
 function timing(overrides: Partial<TpsTiming> = {}): TpsTiming {
 	return {
@@ -23,6 +23,37 @@ describe("calculateLiveTps", () => {
 	});
 });
 
+describe("setupTpsTracker with anthropic-style usage", () => {
+	it("ignores the tiny usage.output seeded at message_start while streaming", async () => {
+		const handlers = new Map<string, (event: any, ctx: any) => Promise<void>>();
+		const statuses: string[] = [];
+		const ctx = { ui: { setStatus: (_k: string, v: string) => statuses.push(v), notify: () => {}, theme: { fg: (_c: string, t: string) => t } } };
+		setupTpsTracker({ on: (name: string, fn: any) => handlers.set(name, fn) } as any);
+
+		let now = 0;
+		const realNow = performance.now;
+		performance.now = () => now;
+		try {
+			const message = { role: "assistant", provider: "anthropic", model: "claude", usage: { output: 1 } };
+			await handlers.get("agent_start")!({}, ctx);
+			await handlers.get("message_start")!({ message }, ctx);
+			for (let i = 0; i < 20; i++) {
+				now += 50;
+				await handlers.get("message_update")!({ message, assistantMessageEvent: { type: "text_delta", delta: "x".repeat(40) } }, ctx);
+			}
+			// 20 deltas * 10 est. tokens over ~1s => ~200 tok/s, not ~1 tok/s
+			expect(statuses.at(-1)).toBe("211 tok/s");
+
+			message.usage.output = 200;
+			await handlers.get("message_end")!({ message }, ctx);
+			await handlers.get("agent_end")!({}, ctx);
+			expect(statuses.at(-1)).toMatch(/^done [1-9]\d* t\/s \(main [1-9]\d* t\/s\)$/);
+		} finally {
+			performance.now = realNow;
+		}
+	});
+});
+
 describe("calculateReliableTps", () => {
 	it("uses active stream time for sufficiently sampled output", () => {
 		expect(calculateReliableTps(100, timing())).toEqual({

package/dist/extensions/tps.ts

@@ -230,7 +230,9 @@ export function setupTpsTracker(pi: ExtensionAPI): void {
 		streamStart ??= now;
 		estimatedStreamedTokens += Math.max(0, streamEvent.delta.length / 4);
 		const officialTokens = generatedTokensFromUsage(asRecord(event.message.usage));
-		const currentTokens = officialTokens > 0 ? officialTokens : estimatedStreamedTokens;
+		// Anthropic seeds usage.output (~1) at message_start and only finalizes it at message_delta,
+		// so a nonzero official count mid-stream is not authoritative; take whichever is larger.
+		const currentTokens = Math.max(officialTokens, estimatedStreamedTokens);
 		const tps = calculateLiveTps(currentTokens, now - streamStart);
 		if (tps !== null) {
 			ctx.ui.setStatus("tps", ctx.ui.theme.fg("accent", `${tps} tok/s`));

package/dist/skills/pi-subagents/references/constraints-and-recipes.md

@@ -6,10 +6,10 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
 
 - **Explicit forking requires a persisted parent session.** If the current session
   does not have a persisted session file or current leaf, explicit `context: "fork"`
-  fails. An agent-level `defaultContext: fork` is a preference: packaged `worker`,
-  `oracle`, and `advisor` fall back to `fresh` when those fork preconditions are not
-  met yet. Use `context: "fresh"` when you do not want a fork even after the parent
-  session exists.
+  fails. Packaged `worker` defaults to `fresh`; `oracle` and `advisor` default to
+  `fork`, which falls back to `fresh` when fork preconditions are not met yet. A
+  configured global `defaultSubagentContext` can override agent defaults. Use explicit
+  `context: "fresh"` or `context: "fork"` when the mode matters.
 - **Forked runs inherit parent history.** They are branched threads, not fresh
   filtered contexts. Use fresh context for adversarial reviewers unless the user explicitly asks for forked context.
 - **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
@@ -122,7 +122,7 @@ Run the work through seven gated phases:
 
 For straightforward non-trivial work, this sequence is the lightweight version of the parent-owned loop. When the task is complex, use Fable mode above. In either case, factor in the packaged prompt workflows without literally invoking slash commands. Use the same patterns through tools and subagents.
 
-Keep builtin agent defaults unless the user explicitly asks for a different model, thinking level, skills, output behavior, context mode, or other override. Do not add overrides just because you are orchestrating; the defaults encode the intended role behavior. In particular, packaged `worker`, `oracle`, and `advisor` default to forked context.
+Keep builtin agent defaults unless the user explicitly asks for a different model, thinking level, skills, output behavior, context mode, or other override. Do not add overrides just because you are orchestrating; the defaults encode the intended role behavior. Packaged `worker` defaults to fresh context; `oracle` and `advisor` default to forked context.
 
 When the user approves launching a subagent to carry out a plan or workflow, treat that as approval to generate a proper role-specific meta prompt for that subagent. Include the approved plan path or summary, clarified requirements, non-goals, relevant context, role boundaries, files or areas to inspect, acceptance criteria, expected output, and validation expectations. Do not pass vague instructions like “implement the plan fully” or “review this” by themselves.
 
@@ -142,7 +142,7 @@ The validation contract defines acceptance before code is written: expected beha
 
 For one host-run verification command, `gate: "npm test"` on the child is shorthand for verified acceptance with that command; it cannot be combined with `acceptance` and is rejected on retained resume items. Use the structured `acceptance` field when the run should carry an explicit acceptance contract. If omitted, subagents infer an effective policy from role, mode, and risk. Evidence levels end at `verified`: use `level: "checked"` for ordinary writer evidence and `level: "verified"` when the runtime should run explicit validation commands. Independent review is orthogonal; use `review: { required: true, agent: "reviewer" }` and orchestrate the reviewer separately. `review-required` means evidence passed but review is pending, while `reviewed` means a real independent result found no blockers. For reviewer/read-only calls, omit `acceptance`. Never explicitly request `level: "reviewed"`; that value remains recognized only so preflight can return an actionable correction. To disable gates, use `{ level: "none", reason: "..." }`; the bare string `"none"` is rejected, and `false` is accepted only as a deprecated shorthand. Child-reported command success is evidence, not runtime verification.
 
-The first `worker` implements the approved plan. The parent continues with independent inspection or validation prep while it runs, not parallel edits to the same worktree. When the async worker completes, treat its handoff as the transition into review, not as final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Parallel reviewers inspect the resulting diff from fresh context. Validators check behavior with the best available evidence: commands, tests, browser/CLI interaction, screenshots, logs, or manual reproduction notes. The final `worker` applies synthesized review fixes in forked context, then the parent looks over the final diff before completing. The parent may launch these steps as an initial async `workflowScript` when the workflow is already clear, or as follow-up workflowScript runs after each async completion. Initial workflows should pass `async: true` so the main chat is unblocked. Do not stop after parallel review unless the user explicitly asked for review-only output or the review surfaced a decision that needs approval first.
+The first `worker` implements the approved plan. The parent continues with independent inspection or validation prep while it runs, not parallel edits to the same worktree. When the async worker completes, treat its handoff as the transition into review, not as final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Parallel reviewers inspect the resulting diff from fresh context. Validators check behavior with the best available evidence: commands, tests, browser/CLI interaction, screenshots, logs, or manual reproduction notes. The final `worker` applies synthesized review fixes with explicit `context: "fork"` when it should reuse the parent thread, then the parent looks over the final diff before completing. The parent may launch these steps as an initial async `workflowScript` when the workflow is already clear, or as follow-up workflowScript runs after each async completion. Initial workflows should pass `async: true` so the main chat is unblocked. Do not stop after parallel review unless the user explicitly asked for review-only output or the review surfaced a decision that needs approval first.
 
 For complex work, risky changes, broad refactors, or many changed lines, increase review and validation fanout rather than trusting one reviewer. Use distinct angles such as correctness/regressions, tests/validation, simplicity/maintainability, security/privacy, performance, docs/API contracts, and user-flow behavior. When reviewers find non-trivial issues or the fix worker touches many lines, run another focused review round before final validation.
 
@@ -155,10 +155,10 @@ Keep orchestration authority in the parent session. Child subagents should not l
 1. Clarify first. This is mandatory. Gather code context with `scout`, add `researcher` only when external evidence matters, then ask the user clarifying questions with `interview` until scope, acceptance criteria, constraints, and non-goals are clear.
 2. Define the validation contract. State acceptance before implementation: expected behavior, checks to run, user flows to exercise, and evidence required in the worker handoff. For UI, CLI, integration, or workflow changes, include at least one validator angle that uses the product the way a user would rather than only reading code.
 3. Plan when useful. For complex work, write a plan doc yourself and get approval before implementation. For simple work, confirm shared understanding and explicitly note why planning is skipped.
-4. Implement with one writer. After approval, launch `worker` asynchronously with a proper meta prompt that includes clarified requirements, relevant context, plan path or summary, the validation contract, and output expectations. Packaged `worker` defaults to forked context; pass `context: "fresh"` only when you intentionally want a fresh child. While it runs, prepare validation or inspect adjacent code instead of editing the same worktree.
+4. Implement with one writer. After approval, launch `worker` asynchronously with a proper meta prompt that includes clarified requirements, relevant context, plan path or summary, the validation contract, and output expectations. Packaged `worker` defaults to fresh context; pass `context: "fork"` only when inherited parent history is intentionally needed. While it runs, prepare validation or inspect adjacent code instead of editing the same worktree.
 5. Require a useful worker handoff. Ask the worker to report changed files, what was implemented, what was left undone, commands run with exit codes, validation evidence, surprises or new risks, decisions made inside approved scope, and decisions needing parent approval.
 6. Review after implementation. After the worker completes, launch parallel async fresh-context `reviewer` agents for correctness/regressions, tests/validation, and simplicity/maintainability. Add security, performance, docs/API, domain-specific, or user-flow validators for complex work, risky changes, broad refactors, or many changed lines. Use `output: false` unless review artifacts are explicitly needed.
-7. Synthesize, then run the fix worker. Separate blockers, fixes worth doing now, optional improvements, and feedback to ignore/defer, then launch an async forked `worker` to apply fixes worth doing now when the workflow is implementation-authorized. If reviewers found scope/product/architecture choices that were not approved, ask the user first instead of applying them.
+7. Synthesize, then run the fix worker. Separate blockers, fixes worth doing now, optional improvements, and feedback to ignore/defer, then launch an async `worker` with `context: "fork"` when an authorized fix pass should inherit the parent thread. If reviewers found scope/product/architecture choices that were not approved, ask the user first instead of applying them.
 8. Review again when warranted. If the fix worker made substantial changes or addressed non-trivial findings, run another focused parallel review round before final validation.
 9. Validate and complete. After the fix worker and any follow-up review return, inspect the final diff yourself, run or confirm focused validation, update docs/changelog when relevant, and summarize what changed and why.
 

package/dist/skills/pi-subagents/references/execution-controls.md

@@ -398,7 +398,7 @@ subagent({
   workflowScript: `return runs.run("oracle-check", { agent: "oracle", task: "Review my current direction, challenge assumptions, and propose the best next move." })`
 })
 
-// Implementation only after explicit approval. Worker defaults to forked context.
+// Implementation only after explicit approval. Worker defaults fresh; set context: "fork" when inherited history is needed.
 subagent({
   workflowScript: `return runs.run("implementation", { agent: "worker", task: "Implement the approved approach: ..." })`
 })

package/dist/skills/pi-subagents/references/prompting-and-roles.md

@@ -88,7 +88,7 @@ subagent({
 
 ### Review-loop technique
 
-Use this when the user wants implementation or current diff review to continue until reviewers stop finding fixes worth doing now. Keep the loop in the parent session: one async `worker` implements or fixes, fresh-context `reviewer` agents inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async forked `worker` applies them. The parent can express the sequence up front as an async/background `workflowScript` when the workflow is known, or continue with explicit follow-up workflowScript runs after each async completion. For an initial workflow, pass `async: true` so the main chat is unblocked. Treat an async implementation worker handoff as an intermediate state, not final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Stop when reviewers find no P0 blockers or P1 fixes worth doing now, remaining P2 feedback is optional or deferred, an unapproved product/scope/architecture decision appears, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.
+Use this when the user wants implementation or current diff review to continue until reviewers stop finding fixes worth doing now. Keep the loop in the parent session: one async `worker` implements or fixes, fresh-context `reviewer` agents inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async `worker` applies them (pass `context: "fork"` when that fix pass should inherit the parent thread). The parent can express the sequence up front as an async/background `workflowScript` when the workflow is known, or continue with explicit follow-up workflowScript runs after each async completion. For an initial workflow, pass `async: true` so the main chat is unblocked. Treat an async implementation worker handoff as an intermediate state, not final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Stop when reviewers find no P0 blockers or P1 fixes worth doing now, remaining P2 feedback is optional or deferred, an unapproved product/scope/architecture decision appears, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.
 
 As a conservative orchestration policy, do not pass `turnBudget` or a hard `toolBudget` to an implementation worker, fix worker, reviewer with edit authority, or other mutation-capable child. The default tool budget blocks read/search tools rather than mutation tools, but count limits still do not measure delivery safety. Use a narrow task plus an outer elapsed deadline with enough margin, then request a checkpoint after the current tool returns. The checkpoint should report changed files, build/test state, remaining work, and commit or PR state. An elapsed timeout is not a mutation-safe boundary and must not be used as the checkpoint trigger.
 

package/docs/settings.md

@@ -49,8 +49,8 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 ### Jev Advisory Routing
 
 The bundled `jev-advisory-routing` extension uses the Jev decisions model for bounded opt-in
-routing. Every route stays off until it is enabled in `jevAdvisory`; the two routes share one
-Jev provider/model pair:
+routing. The host-side routes stay off until they are enabled in `jevAdvisory`; the agent's own
+`ask` route is on by default. All three share one Jev provider/model pair:
 
 - `memory` — only after an explicit durable-memory cue (for example “the convention we
   decided” or “don't repeat the past failure”), Jev chooses one read-only local
@@ -58,6 +58,14 @@ Jev provider/model pair:
 - `recommendations` — one discovered skill or prompt workflow that fits, or a proportionate
   verification level. Nothing is loaded, started, or executed: the recommendation is context for the
   agent, and required project/workflow gates are unchanged.
+- `ask` — the agent-callable `ask_jev` tool (on by default). The agent decides when to call it: it
+  passes its own prose, file `paths`, and one `command`, and gets typed choice/score/noul answers back —
+  never the file contents or command output, so a verdict about code costs a few lines of context
+  instead of the files. Files must be inside the working directory, secret-named files (`.env`,
+  `*.pem`, `id_rsa*`, `auth.json`, …) are refused, and the command runs through the bash tool's local
+  shell. Whatever the agent passes is sent to Jev. Without Token-In credentials the tool is taken out
+  of the agent's loadout before each run (it returns after `/tokenin add`, no reload needed), and a call
+  that slips through reads no file and runs no command.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
@@ -66,11 +74,15 @@ Jev provider/model pair:
 | `jevAdvisory.baseUrl` | string | inherited | Base URL override; defaults to any registered model of `provider` |
 | `jevAdvisory.routes.memory.enabled` | boolean | `false` | Enable the memory-lookup route |
 | `jevAdvisory.routes.recommendations.enabled` | boolean | `false` | Enable skill/workflow and verification recommendations |
-| `<route>.timeoutMs` | number | `8000` | Route request timeout (ms); memory is capped at 750ms |
+| `jevAdvisory.routes.ask.enabled` | boolean | `true` | Offer the agent the `ask_jev` tool; set `false` to turn it off |
+| `<route>.timeoutMs` | number | `8000` | Route request timeout (ms); memory is capped at 750ms; `ask` defaults to `15000` |
 | `<route>.minConfidence` | number | `0.6` | Below this Jev confidence the route abstains |
 | `<route>.contextTurns` | number | `4` | Prior user turns sent as recommendation context; memory sends only the current bounded prompt |
 | `<route>.contextChars` | number | `4000` | Character budget for recommendation context |
-| `<route>.payloadBytes` | number | `8192` | Hard cap on the serialized decision request |
+| `<route>.payloadBytes` | number | `8192` | Hard cap on the serialized decision request; `ask` defaults to `32768` |
+
+`ask` ignores `minConfidence`, `contextTurns`, and `contextChars`: it returns every confidence to the
+agent, and its context is whatever the agent put in the request.
 
 Only idle, top-level, interactive prompts are routed: queued steering/follow-up input, slash
 commands, and extension-injected turns are skipped, and each turn is routed at most once. The memory
@@ -99,16 +111,28 @@ needed: a compact `capability_catalog` lists them, `capability_discover` activat
 current run, and `capability_skill_show` loads one skill's full instructions. Set
 `SELESAI_CAPABILITY_GATEWAY=0` to disable the gateway and keep every tool visible.
 
-Routing has two rungs:
+Routing has three rungs:
 
 1. A deterministic router activates a tool when the prompt uniquely matches its name, alias, or
    discovery summary. Skills are never auto-loaded or auto-selected.
 2. Default-on Jev tie-breaking: when the deterministic router returns an ambiguous lexical hint
    among optional tools, the Jev decisions model is asked which of two or three hinted tools (or
    `none`) should be exposed. Jev sees only the bounded current prompt and each hinted tool's compact
-   discovery line — never conversation history, tool schemas, or the full catalog. A prompt with no
+   discovery line — never conversation history or tool schemas. A prompt with no
    lexical signal, a unique activation, and a skill-only match never reach Jev. Token-In credentials
    are required; without them, no Jev request is sent and Selesai prompts you to run `/tokenin add`.
+3. The agent-driven route: `capability_discover` also takes a `job` instead of a name. Tools and
+   skills are separate decisions — a tool is callable code from an extension or MCP server that the
+   agent may use many times, a skill is a written procedure it reads once — so one Jev request asks
+   two questions, each from catalog metadata only (never a schema or skill body), each allowed to
+   answer `none`. A chosen tool is activated for the run and its parameters are returned; a chosen
+   skill is named for `capability_skill_show`. Tools are offered first, so only skills can be left out
+   of an oversized catalog, and a `none` then says how many were not considered. A skill found in
+   several sources is offered once. While Jev has no credential, the `job` route is left out of the
+   agent's instructions and the agent is pointed at `capability_catalog` plus an exact `name`.
+
+All Jev features share one warning per session, shown the first time one of them actually needs the
+missing credential; a user without a subscription is not warned just for starting a session.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
@@ -117,8 +141,9 @@ Routing has two rungs:
 | `capabilityGateway.routing.jev.model` | string | `"jev-1.13"` | Decisions model the tie-breaker calls |
 | `capabilityGateway.routing.jev.baseUrl` | string | inherited | Base URL override; defaults to any registered model of `provider` |
 | `capabilityGateway.routing.jev.timeoutMs` | number | `1000` | Pre-turn request timeout (ms); hard-capped at `2000` |
+| `capabilityGateway.routing.jev.discoverTimeoutMs` | number | `5000` | Timeout (ms) for `capability_discover({ job })`; hard-capped at `15000` |
 | `capabilityGateway.routing.jev.minConfidence` | number | `0.6` | Below this Jev confidence the tie-breaker abstains |
-| `capabilityGateway.routing.jev.payloadBytes` | number | `8192` | Hard cap on the serialized decision request |
+| `capabilityGateway.routing.jev.payloadBytes` | number | `32768` | Hard cap on the serialized decision request; the pre-turn tie-break uses a few hundred bytes of it |
 
 This area is independent of `jevAdvisory`: gateway routing reads only
 `capabilityGateway.routing.jev` and shares just the Jev provider/model deployment identity. A
@@ -362,6 +387,20 @@ When selesai reads extensions from both `~/.selesai/agent/extensions/` and `~/.p
 
 Keys are top-level entry names (dir name for packaged extensions, file name for loose `.ts`). Values are `"selesai"` or `"pi"`. See [Shared Host Extensions](shared-host-extensions.md) for the full flow.
 
+## Bundled extension settings
+
+The `pi-hermes-memory` extension reads its options from the `hermesMemory` object in global `~/.selesai/agent/settings.json`:
+
+```json
+{
+  "hermesMemory": {
+    "llmThinkingOverride": "off",
+    "consolidationTimeoutMs": 300000
+  }
+}
+```
+
+These settings load at startup and take precedence over the legacy `hermes-memory-config.json` fallback. `llmModelOverride` is optional and uses `provider/model` format (for example, `tokenin/deepseek-v4.1-flash` if your account has access); leave it unset to use the active model. See the [memory extension configuration reference](../src/extensions/pi-hermes-memory/README.md#configuration) for all options.
 
 ## Example
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selesai/code",
-  "version": "0.13.32",
+  "version": "0.13.34",
   "description": "Maintained, extension-first Pi coding agent with built-in workflows, subagents, web research, questions, skills, and an enhanced terminal UI.",
   "type": "module",
   "engines": {
@@ -55,8 +55,8 @@
     "clean": "shx rm -rf dist",
     "dev": "tsx src/cli.ts",
     "dev:print": "tsx src/cli.ts --print",
-    "test": "vitest run src/__tests__/model-registry-completion.test.ts src/extensions/jev/decisions.test.ts src/extensions/capability-gateway/routing.test.ts src/core/settings-manager-auto-handoff.test.ts src/core/remote-catalog-provider.test.ts src/extensions/jev-advisory-memory.test.ts src/extensions/jev-advisory-recommendations.test.ts src/extensions/jev-advisory-lifecycle.test.ts src/extensions/undo.test.ts src/extensions/tps.test.ts src/extensions/pi-graft src/extensions/agent-browser.test.ts src/extensions/auto-session-name.test.ts src/extensions/context-compaction-reminder.test.ts src/extensions/copy-turn.test.ts src/extensions/grep-app/index.test.ts src/extensions/inline-skills.test.ts src/extensions/rtk.test.ts src/extensions/handoff-new.test.ts src/extensions/question/tests src/extensions/ponytail/test src/__tests__/tokenin-search.test.ts src/__tests__/tokenin-onboarding.test.ts src/__tests__/model-registry-defaults.test.ts src/core/system-prompt.test.ts src/core/session-format.test.ts test/settings-manager-compaction.test.ts test/suite/agent-session-runtime.test.ts test/suite/agent-session-prompt.test.ts test/suite/agent-session-queue.test.ts test/suite/agent-session-retry-events.test.ts test/suite/agent-session-compaction.test.ts test/suite/agent-session-compaction-model-overrides.test.ts test/suite/agent-session-bash-persistence.test.ts test/suite/agent-session-model-extension.test.ts test/clipboard.test.ts test/clipboard-command.test.ts test/clipboard-image.test.ts test/clipboard-image-bmp-conversion.test.ts test/clipboard-image-native-errors.test.ts src/cli/args.test.ts",
-    "test:coverage": "vitest run --coverage src/__tests__/model-registry-completion.test.ts src/extensions/jev/decisions.test.ts src/extensions/capability-gateway/routing.test.ts src/core/settings-manager-auto-handoff.test.ts src/core/remote-catalog-provider.test.ts src/extensions/jev-advisory-memory.test.ts src/extensions/jev-advisory-recommendations.test.ts src/extensions/jev-advisory-lifecycle.test.ts src/extensions/undo.test.ts src/extensions/tps.test.ts src/extensions/agent-browser.test.ts src/extensions/auto-session-name.test.ts src/extensions/context-compaction-reminder.test.ts src/extensions/copy-turn.test.ts src/extensions/grep-app/index.test.ts src/extensions/inline-skills.test.ts src/extensions/rtk.test.ts src/extensions/handoff-new.test.ts src/extensions/question/tests src/extensions/ponytail/test src/__tests__/tokenin-search.test.ts src/__tests__/tokenin-onboarding.test.ts src/__tests__/model-registry-defaults.test.ts src/core/system-prompt.test.ts src/core/session-format.test.ts test/settings-manager-compaction.test.ts test/suite/agent-session-runtime.test.ts test/suite/agent-session-prompt.test.ts test/suite/agent-session-queue.test.ts test/suite/agent-session-retry-events.test.ts test/suite/agent-session-compaction.test.ts test/suite/agent-session-compaction-model-overrides.test.ts test/suite/agent-session-bash-persistence.test.ts test/suite/agent-session-model-extension.test.ts test/clipboard.test.ts test/clipboard-command.test.ts test/clipboard-image.test.ts test/clipboard-image-bmp-conversion.test.ts test/clipboard-image-native-errors.test.ts src/cli/args.test.ts",
+    "test": "vitest run src/__tests__/model-registry-completion.test.ts src/extensions/jev/decisions.test.ts src/extensions/capability-gateway/routing.test.ts src/core/settings-manager-auto-handoff.test.ts src/core/remote-catalog-provider.test.ts src/extensions/jev-advisory-memory.test.ts src/extensions/jev-advisory-recommendations.test.ts src/extensions/jev-ask-tool.test.ts src/extensions/jev-advisory-lifecycle.test.ts src/extensions/undo.test.ts src/extensions/tps.test.ts src/extensions/pi-graft src/extensions/agent-browser.test.ts src/extensions/auto-session-name.test.ts src/extensions/context-compaction-reminder.test.ts src/extensions/copy-turn.test.ts src/extensions/grep-app/index.test.ts src/extensions/inline-skills.test.ts src/extensions/rtk.test.ts src/extensions/handoff-new.test.ts src/extensions/question/tests src/extensions/ponytail/test src/__tests__/tokenin-search.test.ts src/__tests__/tokenin-onboarding.test.ts src/__tests__/model-registry-defaults.test.ts src/core/system-prompt.test.ts src/core/session-format.test.ts test/settings-manager-compaction.test.ts test/suite/agent-session-runtime.test.ts test/suite/agent-session-prompt.test.ts test/suite/agent-session-queue.test.ts test/suite/agent-session-retry-events.test.ts test/suite/agent-session-compaction.test.ts test/suite/agent-session-compaction-model-overrides.test.ts test/suite/agent-session-bash-persistence.test.ts test/suite/agent-session-model-extension.test.ts test/clipboard.test.ts test/clipboard-command.test.ts test/clipboard-image.test.ts test/clipboard-image-bmp-conversion.test.ts test/clipboard-image-native-errors.test.ts src/cli/args.test.ts",
+    "test:coverage": "vitest run --coverage src/__tests__/model-registry-completion.test.ts src/extensions/jev/decisions.test.ts src/extensions/capability-gateway/routing.test.ts src/core/settings-manager-auto-handoff.test.ts src/core/remote-catalog-provider.test.ts src/extensions/jev-advisory-memory.test.ts src/extensions/jev-advisory-recommendations.test.ts src/extensions/jev-ask-tool.test.ts src/extensions/jev-advisory-lifecycle.test.ts src/extensions/undo.test.ts src/extensions/tps.test.ts src/extensions/agent-browser.test.ts src/extensions/auto-session-name.test.ts src/extensions/context-compaction-reminder.test.ts src/extensions/copy-turn.test.ts src/extensions/grep-app/index.test.ts src/extensions/inline-skills.test.ts src/extensions/rtk.test.ts src/extensions/handoff-new.test.ts src/extensions/question/tests src/extensions/ponytail/test src/__tests__/tokenin-search.test.ts src/__tests__/tokenin-onboarding.test.ts src/__tests__/model-registry-defaults.test.ts src/core/system-prompt.test.ts src/core/session-format.test.ts test/settings-manager-compaction.test.ts test/suite/agent-session-runtime.test.ts test/suite/agent-session-prompt.test.ts test/suite/agent-session-queue.test.ts test/suite/agent-session-retry-events.test.ts test/suite/agent-session-compaction.test.ts test/suite/agent-session-compaction-model-overrides.test.ts test/suite/agent-session-bash-persistence.test.ts test/suite/agent-session-model-extension.test.ts test/clipboard.test.ts test/clipboard-command.test.ts test/clipboard-image.test.ts test/clipboard-image-bmp-conversion.test.ts test/clipboard-image-native-errors.test.ts src/cli/args.test.ts",
     "prepare": "npm run build",
     "build": "npm run clean && tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
     "copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/ && shx mkdir -p dist/defaults && shx cp src/defaults/* dist/defaults/ && shx mkdir -p dist/extensions && node scripts/copy-extensions.mjs && shx mkdir -p dist/themes && shx cp -r src/themes/. dist/themes/ && shx mkdir -p dist/skills && shx cp -r src/skills/. dist/skills/"