@oh-my-pi/pi-coding-agent 16.4.6 → 16.5.0

package/src/modes/interactive-mode.ts

@@ -120,6 +120,7 @@ import { formatPhaseDisplayName, todoMatchesAnyDescription } from "../tools/todo
 import { ToolError } from "../tools/tool-errors";
 import { vocalizer } from "../tts/vocalizer";
 import { renderTreeList } from "../tui/tree-list";
+import { copyToClipboard } from "../utils/clipboard";
 import type { EventBus } from "../utils/event-bus";
 import { getEditorCommand, openInEditor } from "../utils/external-editor";
 import { getSessionAccentAnsi, getSessionAccentHex } from "../utils/session-color";
@@ -664,6 +665,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		setMarkdownMermaidRendering(settings.get("tui.renderMermaid"));
 		this.ui = new TUI(new ProcessTerminal(), settings.get("showHardwareCursor"));
 		this.ui.setMaxInlineImages(settings.get("tui.maxInlineImages"));
+		this.ui.setScrollbackRebuild(settings.get("tui.scrollbackRebuild"));
 		// OSC 66 text-sizing is Kitty-only; resolve the setting against the terminal's
 		// capability (`TERMINAL.textSizing` defaults on for Kitty) so it stays off
 		// unless the user opts in, and never emits raw escapes on other terminals.
@@ -1613,9 +1615,12 @@ export class InteractiveMode implements InteractiveModeContext {
 			}
 		}
 		this.chatContainer.clear();
-		// Live display uses the compacted transcript tail; export/resume callers
-		// can still request the full inline compaction history.
-		const context = this.viewSession.buildTranscriptSessionContext({ collapseCompactedHistory: true });
+		// Live display collapses to the compacted transcript tail unless the
+		// user opted into the full inline history; export/resume callers choose
+		// their own mode.
+		const context = this.viewSession.buildTranscriptSessionContext({
+			collapseCompactedHistory: settings.get("display.collapseCompacted"),
+		});
 		this.renderSessionContext(context);
 		for (const child of liveComponents) {
 			this.chatContainer.addChild(child);
@@ -2517,6 +2522,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			{
 				onPick: choice => finish(choice),
 				onCancel: () => finish(undefined),
+				onCopyPlan: content => void this.#copyPlanToClipboard(content),
 				onExternalEditor: dialogOptions?.onExternalEditor,
 				onAnnotationExternalEditor: (draft, commit) => void this.#openPlanAnnotationInExternalEditor(draft, commit),
 				onPlanEdited: dialogOptions?.onPlanEdited,
@@ -2583,6 +2589,17 @@ export class InteractiveMode implements InteractiveModeContext {
 		return contextUsage !== undefined && contextUsage.percent > PLAN_KEEP_CONTEXT_DISABLE_THRESHOLD_PERCENT;
 	}
 
+	async #copyPlanToClipboard(content: string): Promise<void> {
+		try {
+			await copyToClipboard(content);
+			this.showStatus("Copied plan to clipboard");
+		} catch (error) {
+			this.showWarning(
+				`Failed to copy plan to clipboard: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
 	async #openPlanInExternalEditor(planFilePath: string): Promise<void> {
 		const editorCmd = getEditorCommand();
 		if (!editorCmd) {

package/src/modes/print-mode.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Contract: `--mode json` output stays linear in conversation size. Streaming
+ * `message_update` events must not re-serialize the in-progress message, and
+ * printed messages must not carry provider-opaque replay payloads (encrypted
+ * reasoning history), which previously produced multi-GB transcripts.
+ */
+import { describe, expect, it } from "bun:test";
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import type { AgentSessionEvent } from "../session/agent-session";
+import { printableEvent } from "./print-mode";
+
+const assistant: AssistantMessage = {
+	role: "assistant",
+	content: [{ type: "text", text: "hello" }],
+	api: "openai-responses",
+	provider: "openai",
+	model: "gpt-test",
+	usage: {} as AssistantMessage["usage"],
+	stopReason: "stop",
+	timestamp: 1,
+	providerPayload: { type: "openaiResponsesHistory", provider: "openai", dt: true, items: [{ big: "blob" }] },
+};
+
+describe("printableEvent", () => {
+	it("emits only the incremental delta for message_update", () => {
+		const event: AgentSessionEvent = {
+			type: "message_update",
+			message: assistant,
+			assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: "hel", partial: assistant },
+		};
+		const printed = JSON.parse(JSON.stringify(printableEvent(event)));
+		expect(printed).toEqual({
+			type: "message_update",
+			assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: "hel" },
+		});
+	});
+
+	it("drops the done-variant message snapshot from message_update", () => {
+		const event: AgentSessionEvent = {
+			type: "message_update",
+			message: assistant,
+			assistantMessageEvent: { type: "done", reason: "stop", message: assistant },
+		};
+		const printed = JSON.parse(JSON.stringify(printableEvent(event)));
+		expect(printed).toEqual({ type: "message_update", assistantMessageEvent: { type: "done", reason: "stop" } });
+	});
+
+	it("strips providerPayload from message_end but keeps the message content", () => {
+		const event: AgentSessionEvent = { type: "message_end", message: assistant };
+		const printed = JSON.parse(JSON.stringify(printableEvent(event))) as {
+			message: Record<string, unknown>;
+		};
+		expect(printed.message.providerPayload).toBeUndefined();
+		expect(printed.message.content).toEqual([{ type: "text", text: "hello" }]);
+		expect(printed.message.model).toBe("gpt-test");
+	});
+
+	it("strips providerPayload from every message in agent_end", () => {
+		const event: AgentSessionEvent = { type: "agent_end", messages: [assistant, assistant] };
+		const printed = JSON.parse(JSON.stringify(printableEvent(event))) as {
+			messages: Array<Record<string, unknown>>;
+		};
+		expect(printed.messages).toHaveLength(2);
+		for (const message of printed.messages) expect(message.providerPayload).toBeUndefined();
+	});
+
+	it("passes unrelated events through untouched", () => {
+		const event: AgentSessionEvent = { type: "notice", level: "info", message: "hi" };
+		expect(printableEvent(event)).toBe(event);
+	});
+});

package/src/modes/print-mode.ts

@@ -5,9 +5,10 @@
  * - `omp -p "prompt"` - text output
  * - `omp --mode json "prompt"` - JSON event stream
  */
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, ImageContent } from "@oh-my-pi/pi-ai";
 import { logger, sanitizeText } from "@oh-my-pi/pi-utils";
-import type { AgentSession } from "../session/agent-session";
+import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import { isSilentAbort } from "../session/messages";
 import { flushTelemetryExport } from "../telemetry-export";
 import { initializeExtensions } from "./runtime-init";
@@ -28,6 +29,54 @@ export interface PrintModeOptions {
 	printThoughts?: boolean;
 }
 
+/** Drop the provider-opaque replay payload (e.g. encrypted reasoning items) before printing. */
+function stripProviderPayload<T extends AgentMessage>(message: T): T {
+	if (!("providerPayload" in message) || message.providerPayload === undefined) return message;
+	const { providerPayload: _providerPayload, ...rest } = message;
+	return rest as T;
+}
+
+/**
+ * Shape an event for `--mode json` output.
+ *
+ * Removes two classes of bloat so transcripts grow linearly with conversation
+ * size instead of quadratically (a single long turn used to re-serialize its
+ * whole in-progress message on every streamed delta, producing multi-GB logs):
+ * - `message_update` snapshots (`message`, `assistantMessageEvent.partial`,
+ *   and the `done`/`error` payloads) are dropped; only the incremental delta
+ *   is printed. The authoritative message follows in `message_end`.
+ * - `providerPayload` is transport-native replay state, opaque and useless
+ *   outside this process.
+ */
+export function printableEvent(event: AgentSessionEvent): unknown {
+	switch (event.type) {
+		case "message_update": {
+			const streamEvent = event.assistantMessageEvent;
+			if (streamEvent.type === "done" || streamEvent.type === "error") {
+				return {
+					type: "message_update",
+					assistantMessageEvent: { type: streamEvent.type, reason: streamEvent.reason },
+				};
+			}
+			const { partial: _partial, ...rest } = streamEvent;
+			return { type: "message_update", assistantMessageEvent: rest };
+		}
+		case "message_start":
+		case "message_end":
+			return { ...event, message: stripProviderPayload(event.message) };
+		case "turn_end":
+			return {
+				...event,
+				message: stripProviderPayload(event.message),
+				toolResults: event.toolResults.map(stripProviderPayload),
+			};
+		case "agent_end":
+			return { ...event, messages: event.messages.map(stripProviderPayload) };
+		default:
+			return event;
+	}
+}
+
 /**
  * Run in print (single-shot) mode.
  * Sends prompts to the agent and outputs the result.
@@ -58,7 +107,7 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 	session.subscribe(event => {
 		// In JSON mode, output all events
 		if (mode === "json") {
-			process.stdout.write(`${JSON.stringify(event)}\n`);
+			process.stdout.write(`${JSON.stringify(printableEvent(event))}\n`);
 		}
 	});
 

package/src/modes/theme/theme.ts

@@ -92,6 +92,7 @@ export type SymbolKey =
 	// Icons
 	| "icon.model"
 	| "icon.plan"
+	| "icon.prewalk"
 	| "icon.goal"
 	| "icon.pause"
 	| "icon.loop"
@@ -225,6 +226,7 @@ export type SymbolKey =
 	| "tool.debug"
 	| "tool.mcp"
 	| "tool.job"
+	| "tool.launch"
 	| "tool.task"
 	| "tool.todo"
 	| "tool.memory"
@@ -300,6 +302,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	// Icons
 	"icon.model": "⬢",
 	"icon.plan": "🗺",
+	"icon.prewalk": "🏃",
 	"icon.goal": "🎯",
 	"icon.pause": "⏸",
 	"icon.loop": "↻",
@@ -433,6 +436,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"tool.debug": "🐞",
 	"tool.mcp": "🔌",
 	"tool.job": "⚙",
+	"tool.launch": "🚀",
 	"tool.task": "⇶",
 	"tool.todo": "☑",
 	"tool.memory": "🧠",
@@ -560,6 +564,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.model": "\uec19",
 	// pick:  | alt:  
 	"icon.plan": "\uf2d2",
+	"icon.prewalk": "\uf29d",
 	// pick:  (nf-fa-bullseye) | alt:  (nf-md-target) ◎ ⌖
 	"icon.goal": "\uf140",
 	// pick:  (nf-fa-pause) | alt: ⏸ ||
@@ -742,6 +747,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"tool.debug": "\uEAD8",
 	"tool.mcp": "\uEB2D",
 	"tool.job": "\uEBA2",
+	"tool.launch": "\uF135",
 	"tool.task": "\uf4a0",
 	"tool.todo": "\uEAB3",
 	"tool.memory": "\uEACE",
@@ -816,6 +822,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	// Icons
 	"icon.model": "[M]",
 	"icon.plan": "plan",
+	"icon.prewalk": "prewalk",
 	"icon.goal": "goal",
 	"icon.pause": "||",
 	"icon.loop": "loop",
@@ -946,6 +953,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"tool.debug": "dbg",
 	"tool.mcp": "<>",
 	"tool.job": "job",
+	"tool.launch": "run",
 	"tool.task": ">>>",
 	"tool.todo": "[x]",
 	"tool.memory": "mem",
@@ -1815,6 +1823,7 @@ export class Theme {
 		return {
 			model: this.#symbols["icon.model"],
 			plan: this.#symbols["icon.plan"],
+			prewalk: this.#symbols["icon.prewalk"],
 			goal: this.#symbols["icon.goal"],
 			pause: this.#symbols["icon.pause"],
 			loop: this.#symbols["icon.loop"],

package/src/modes/utils/ui-helpers.ts

@@ -45,7 +45,7 @@ import {
 	SKILL_PROMPT_MESSAGE_TYPE,
 	type SkillPromptDetails,
 } from "../../session/messages";
-import type { SessionContext } from "../../session/session-context";
+import type { SessionContext, StrippedToolCallsMarker } from "../../session/session-context";
 import { replaceTabs } from "../../tools/render-utils";
 import { buildSkillCommandPrompt, invokeSkillCommandFromText, isKnownSkillCommand } from "../skill-command";
 import { createAssistantMessageComponent } from "./interactive-context-helpers";
@@ -465,6 +465,26 @@ export class UiHelpers {
 						this.ctx.pendingTools.set(content.id, component);
 					}
 				}
+				// Dangling toolCalls (no result on the resolved path — failed or
+				// retried turns, results on sibling branches) were stripped by the
+				// context build; surface a placeholder so the turn's activity is
+				// visibly elided instead of silently vanishing (the "bare thinking
+				// lines" transcript trap).
+				const strippedToolCalls = (message as AgentMessage & StrippedToolCallsMarker).strippedToolCalls ?? 0;
+				if (strippedToolCalls > 0) {
+					this.ctx.chatContainer.addChild(
+						new Text(
+							theme.fg(
+								"dim",
+								theme.italic(
+									`${strippedToolCalls} tool call${strippedToolCalls === 1 ? "" : "s"} elided — no result on this branch`,
+								),
+							),
+							1,
+							0,
+						),
+					);
+				}
 				pendingUsage =
 					this.ctx.settings.get("display.showTokenUsage") && assistantUsageIsBilled(message.usage)
 						? message.usage
@@ -607,13 +627,14 @@ export class UiHelpers {
 		this.ctx.pendingBashComponents = [];
 		this.ctx.pendingPythonComponents = [];
 
-		// Live display uses the compacted transcript tail; export/resume callers
-		// can still request the full inline compaction history. Mid-turn rebuilds
+		// Live display collapses to the compacted transcript tail unless the
+		// user opted into the full inline history; export/resume callers can
+		// still request either mode. Mid-turn rebuilds
 		// (focus attach/unfocus while a tool executes) keep dangling toolCalls so
 		// the in-flight call re-renders as pending instead of vanishing;
 		// renderSessionContext then keeps it in `pendingTools` for live routing.
 		const context = this.ctx.viewSession.buildTranscriptSessionContext({
-			collapseCompactedHistory: true,
+			collapseCompactedHistory: settings.get("display.collapseCompacted"),
 			keepDanglingToolCalls: this.ctx.viewSession.isStreaming,
 		});
 		this.ctx.renderSessionContext(context, {

package/src/prompts/agents/designer.md

@@ -1,7 +1,7 @@
 ---
 name: designer
 description: UI/UX specialist for design implementation, review, visual refinement
-model: pi/designer
+model: "@designer"
 ---
 
 Implement and review UI designs. Edit files, create components, run commands when needed.

package/src/prompts/agents/librarian.md

@@ -2,7 +2,7 @@
 name: librarian
 description: Researches external libraries and APIs by reading source code. Returns definitive, source-verified answers.
 tools: read, grep, glob, bash, lsp, web_search, ast_grep
-model: pi/smol
+model: "@smol"
 thinking-level: minimal
 read-summarize: false
 output:

package/src/prompts/agents/reviewer.md

@@ -3,7 +3,7 @@ name: reviewer
 description: "Code review specialist for quality/security analysis"
 tools: read, grep, glob, bash, lsp, web_search, ast_grep
 spawns: scout
-model: pi/slow
+model: "@slow"
 output:
   properties:
     overall_correctness:

package/src/prompts/agents/scout.md

@@ -2,7 +2,7 @@
 name: scout
 description: MUST be used for exploratory codebase research, rapid code analysis, and broad pattern searches. Fast read-only scout returning compressed context for handoff.
 tools: read, grep, glob, web_search
-model: pi/smol
+model: "@smol"
 thinking-level: medium
 read-summarize: false
 output:

package/src/prompts/system/plan-yolo-handoff.md

@@ -0,0 +1,5 @@
+Plan approved: **{{title}}**.
+
+Read `{{planFilePath}}` and implement it now — full tool access is restored. Execute the plan top to bottom exactly as written; you were not part of drafting it, so treat every choice in it as already made. Do not ask for further approval and do not re-plan.
+
+When finished, re-read the plan and confirm every step was completed before ending your turn.

package/src/prompts/system/prewalk-checklist.md

@@ -0,0 +1,7 @@
+Before you consider this task finished, verify:
+
+- Consistency: if you changed a pattern, signature, or check in one place, grep for every other call site or duplicate copy that needs the identical change. A fix applied to only some of the matching sites is still a failure.
+- Scope: if your diff does more than the minimal change needed to resolve the issue, confirm you have not altered behavior for any case outside the reported issue. Prefer the smallest correct diff over a broader rewrite.
+- Verification: run the full test module or file the issue lives in, not just the one test you expect to flip. A change that breaks a sibling test is not a fix.
+
+Do not claim the task is complete until you have done these three checks.

package/src/prompts/system/prewalk-continue.md

@@ -0,0 +1 @@
+Continue the task now — do not end your turn here.

package/src/prompts/system/prewalk-plan.md

@@ -0,0 +1,13 @@
+Stop and write the complete plan in your NEXT reply — before any further exploration. You have already seen enough to commit to a plan; do not defer this.
+
+First, state the plan itself, explicitly and comprehensively:
+
+- Every remaining step in execution order, with the exact files, symbols, commands, and checks involved.
+- Known risks, edge cases, and how you will verify each step actually landed (specific commands, expected outputs). Never modify tests or verification assets to make checks pass.
+- What is already done, stated briefly, so no step gets repeated.
+
+Be thorough and concrete — this plan is the reference for the remainder of the run. You may verify details with tools after the plan is written, never before.
+
+Then, only once the plan above is complete, in the SAME reply, capture it as a todo list (the todo tool): 5-9 items, one per MEANINGFUL step, each naming its concrete target and its verification. Only steps that change or verify code belong on the list — no reporting, bookkeeping, cleanup-ceremony, or release-note items. The todo list serves the task, never the reverse: when reality disagrees with an item, fix the actual problem rather than working the checklist.
+
+This is a checkpoint, not a final answer: do not end your turn on the plan alone — after recording the todo list, continue the task; do not stop here.

package/src/prompts/system/system-prompt.md

@@ -192,7 +192,7 @@ EXECUTION WORKFLOW
 
 # 3. Decompose
 - Update todos as you go; skip them for trivial requests. Marking a todo done is a transition: start the next in the same turn.
-- Plan only what makes the request work. Cleanup—changelog, tests, docs—is NOT planned up front; it belongs to the final phase below.
+- Plan only what makes the request work. Cleanup—changelog, docs, removing scaffolding—is NOT planned up front; it belongs to the final phase below. Tests are cleanup only for permanent feature/bug-fix work (see Cleanup).
 
 # 4. Implement
 - Fix problems at the source. Remove obsolete code—no leftover comments, aliases, or re-exports.
@@ -202,14 +202,16 @@ EXECUTION WORKFLOW
 {{#has tools "ask"}}- Ask before destructive commands or deleting code you didn't write.{{else}}- Don't run destructive git commands or delete code you didn't write.{{/has}}
 
 # 5. Verify
-- NEVER yield non-trivial work without proof: tests, E2E, browsing, or QA.
-- Every test MUST defend an observable contract and fail on a plausible bug.
-- Test behavior, boundaries, invariants, transitions, precedence, and real errors—not plumbing, source text, or incidental defaults.
-- Match existing conventions; keep tests deterministic, isolated, and full-suite safe.
-- Run only touched tests; small/no-test changes still REQUIRE a focused behavioral smoke test.
+- NEVER yield non-trivial work without proof that the deliverable works. The proof method depends on the ask:
+  - **Experiment / investigation** → run it. The output IS the proof. No tests.
+  - **UI change** → drive it in browser. Visual confirmation IS the proof. No tests unless the existing suite breaks and the break is real.
+  - **Bug fix** → reproduce the bug, apply the fix, confirm the reproduction no longer triggers.
+  - **Permanent feature / API change** → existing tests that cover the changed contract. Add a test only when the change introduces a new observable contract not already covered, or the user asked for one.
+- Smoke test: run the thing, not a test file. Launch it, exercise the changed path, observe the result.
+- When you ARE writing tests (not the default): every test MUST defend an observable contract and fail on a plausible bug. Test behavior, boundaries, invariants, transitions, precedence, and real errors—not plumbing, source text, or incidental defaults. Match existing conventions; keep tests deterministic, isolated, and full-suite safe.
 
 # 6. Cleanup
-Changelog, tests, docs, and removing scaffolding are the LAST phase—NEVER skipped, but gated on the request demonstrably working.
+Changelog and removing scaffolding are the LAST phase—NEVER skipped, but gated on the request demonstrably working. Tests and docs are cleanup ONLY when the work is a permanent feature change or bug fix, not for experiments or one-off investigations.
 
 - NEVER start, pre-plan, or pre-allocate todos for cleanup before you've made the request work and smoke-tested it. Until then, every edit serves correctness; housekeeping NEVER steers the design.
 - Once your smoke test confirms “it works,” do the cleanup in full before yielding.

package/src/prompts/system/tan-context-switch.md

@@ -0,0 +1,17 @@
+<system-notice cause="fork">
+The conversation above belongs to your parent session.
+You are a fork created solely to handle the user's request below.
+
+Your parent agent is still working on the original task — that responsibility is
+NOT yours. You have no obligations from the prior conversation.
+
+- Focus EXCLUSIVELY on the user's immediate request. Nothing else.
+- NEVER continue, follow up on, or intervene in anything discussed before this
+  message. Those belong to the parent session.
+- Your parent is CONCURRENTLY editing this same working directory. Files may
+  change between your reads, look mid-refactor, or fail to compile. That is the
+  parent's live work — NEVER fix, audit, or build on it, even if it looks broken.
+- Any todo list, plan, or unfinished checklist from the prior conversation is
+  the parent's. NEVER resume or update it.
+- After addressing the user's request, STOP. Do not work on ANY OTHER TASK.
+</system-notice>

package/src/prompts/tools/bash.md

@@ -5,6 +5,7 @@ Runs commands in the embedded shell — terminal ops: git, bun, cargo, python.
 The shell invokes **real binaries** with simple args. It is NOT full GNU Bash.
 
 Use bash ONLY for: a single binary call, or one short pipeline that COMPUTES a fact and does not depend on shell-specific regex/quoting (`wc -l`, `sort | uniq -c`, `comm`, `diff`, a checksum, `git status`).
+{{#if hasLaunch}}Long-running service, watcher, debugger, REPL, or process needing later input? MUST use `launch`, not bash.{{/if}}
 
 {{#if hasEval}}Anything below → `eval` cell, not bash:
 - Inline interpreter scripts (`-e`/`-c`/`--eval`) when an eval runtime exists for that language
@@ -33,7 +34,7 @@ Use bash ONLY for: a single binary call, or one short pipeline that COMPUTES a f
 - Internal URIs (`skill://`, `agent://`, …) auto-resolve to FS paths
 {{#if hasEval}}- Need exact pipeline semantics (`cmd | head`, multi-stage filtering) or output truncation? Prefer `eval` and process the stream directly.{{else}}- Need exact pipeline semantics (`cmd | head`, multi-stage filtering) or output truncation? Use a checked-in script, purpose-built tool, or single command that owns the output shape.{{/if}}
 {{#if asyncEnabled}}
-- `async: true` for long-running commands when you don't need immediate output: returns a background job ID; result delivered as a follow-up.
+- `async: true` defers reporting for finite commands that need no later input; completion arrives as a follow-up.
 {{/if}}
 </instruction>
 
@@ -42,6 +43,7 @@ Use bash ONLY for: a single binary call, or one short pipeline that COMPUTES a f
 {{#if hasGrep}}- NEVER shell out to search content or files: `grep/rg` → `grep`.{{else}}- Avoid shelling out for broad content search; use an active search/read tool when one is available.{{/if}}
 {{#if hasRead}}{{#if hasGlob}}- NEVER use `ls` or `find` to list or locate files — `ls` → `read` (a directory path lists entries), `find` → the `glob` tool (globbing). This is non-negotiable, even for a single quick listing.{{else}}- Prefer `read` for known file and directory reads. Only use shell listing when no file-listing tool is active.{{/if}}{{else}}{{#if hasGlob}}- Prefer `glob` for file discovery; avoid `find` when `glob` is active.{{else}}- If no file read/listing tool is active, keep shell inspection narrow and state that limitation.{{/if}}{{/if}}
 - Avoid head/tail/redirections: stderr already merged; long output auto-truncated, FULL capture kept at `artifact://<id>`.
+{{#if hasLaunch}}- NEVER launch daemons, watchers, dev servers, debuggers, or REPLs through bash/background shell syntax — use `launch`.{{/if}}
 </critical>
 
 <output>
@@ -52,9 +54,9 @@ Use bash ONLY for: a single binary call, or one short pipeline that COMPUTES a f
 {{#if asyncEnabled}}
 # Timeout and async
 
-- `timeout` is seconds; nonzero values are clamped to `1..3600` and the process is killed on elapse. Set `timeout: 0` only for commands that must run until completion or explicit cancellation.
-- `async: true` defers only reporting — it does NOT extend a nonzero timeout; use `timeout: 0` when a daemon or watcher must be cancellation-owned.
-- Need a daemon or >3600s run? Use `async: true` with `timeout: 0` when the harness should keep it alive until cancellation, or detach/manage lifecycle yourself (`cmd &`, supervisor, self-restarting script). The shell session persists across calls.
+- `timeout` is seconds; nonzero values are clamped to `1..3600` and the process is killed on elapse. Set `timeout: 0` only for finite commands whose completion is cancellation-owned.
+- `async: true` defers only reporting; it does NOT extend a nonzero timeout.
+{{#if hasLaunch}}- Need a service, watcher, debugger, REPL, or later stdin? MUST use `launch`. NEVER use `cmd &`, `nohup`, or async bash as a process supervisor.{{else}}- Need a long-running process or >3600s run? Use an external process supervisor; avoid detached shell jobs you cannot later observe or stop.{{/if}}
 {{/if}}
 {{#if autoBackgroundEnabled}}
 

package/src/prompts/tools/browser.md

@@ -5,7 +5,7 @@ Drives real Chromium tab; full puppeteer access via JS.
 - Three actions:
   - `open` — acquire/reuse named tab (`name` defaults `"main"`). Optional `url` (navigate once ready), `viewport`, `dialogs: "accept" | "dismiss"` (auto-handle `alert`/`confirm`/`beforeunload`; else page hangs till you wire `page.on('dialog', …)`).
   - `close` — release tab by `name`, or all with `all: true`. `kill: true` also kills spawned-app process trees.
-  - `run` — execute JS in existing tab. `code` = async function body; `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. Return value JSON-stringified into result; `display(value)` accumulates text/images.
+  - `run` — execute JS in existing tab. `code` = async function body; `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. Return value JSON-stringified into result; `display(value)` accumulates text/images. `wait(ms)` sleeps; `wait(fn, { timeout?, interval? })` polls `fn` (sync or async) until truthy and resolves with that value (default 100ms interval; deadline min(30s, cell budget − 1s), named error on timeout) — use it instead of in-page polling Promises inside `tab.evaluate`.
 - Tabs survive `run` calls and in-process subagents — open once, reuse.
 - Browser kinds (`app` on `open`):
   - default (no `app`) → headless Chromium with stealth patches.
@@ -13,7 +13,7 @@ Drives real Chromium tab; full puppeteer access via JS.
   - `app.cdp_url` → connect to existing CDP endpoint (e.g. `http://127.0.0.1:9222`).
   - `app.target` (with `path`/`cdp_url`) — substring on url+title picks BrowserWindow.
 - `tab` helpers; drop to raw puppeteer `page` for anything uncovered:
-  - `tab.goto(url, { waitUntil? })` — navigate.
+  - `tab.goto(url, { waitUntil? })` — navigate. A hung load fails ~1s before the cell budget with a named, catchable error and the pending navigation is stopped; for slow pages raise `timeout` or use `waitUntil: "domcontentloaded"`.
   - `tab.observe({ includeAll?, viewportOnly? })` — accessibility snapshot: `{ url, title, viewport, scroll, elements: [{ id, role, name, value, states, … }] }`. Ids stable until next observe/goto.
   - `tab.ariaSnapshot(selector?, { depth?, boxes? })` — Playwright-format ARIA-tree YAML (nested roles + accessible names + `/url`/`/placeholder`), scoped to `selector` or the whole document. Every node carries a `[ref=eN]` id; `[cursor=pointer]` flags clickables. Captures dense, hierarchical structure/text that `observe()`'s flat list flattens away. Refs renumber from e1 each call and stay valid until the next `ariaSnapshot()`.
   - `tab.ref("e5")` — `[ref=eN]` from the last ariaSnapshot → element handle with the common action methods (`.click()`, `.type()`, `.fill()`, `.hover()`, `.evaluate()`, …); the primary way to act on a ref. For convenience `aria-ref=e5` also works inline in `tab.click`/`type`/`fill`/`waitFor`/`scrollIntoView` (e.g. `tab.click("aria-ref=e5")`).
@@ -27,10 +27,10 @@ Drives real Chromium tab; full puppeteer access via JS.
   - `tab.waitForUrl(pattern, { timeout? })` — substring or `RegExp` (matches SPA pushState nav); returns matched URL.
   - `tab.waitForResponse(pattern, { timeout? })` — substring, `RegExp`, or `(response) => boolean`; returns puppeteer `HTTPResponse` (`.text()`/`.json()`/`.status()`/`.headers()`).
   - `tab.waitForNavigation({ waitUntil?, timeout? })` — resolves on the next navigation. Start it BEFORE the click/submit that triggers it; after `tab.goto` (which already waits) use `tab.waitForUrl`/`tab.waitForSelector` instead.
-  - `tab.evaluate(fn, …args)` — `page.evaluate` for ad-hoc DOM reads.
+  - `tab.evaluate(fn, …args)` — run ad-hoc code in the page's MAIN world. DOM and page-defined globals (`window.myFlag`) are visible; mutations affect the page.
   - `tab.screenshot({ selector?, fullPage?, save?, silent? })` — capture + attach for viewing (`silent: true` skips). Pass `save` only when a later step needs the file.
   - `tab.extract(format = "markdown")` — readable page content (`"markdown"` | `"text"`); throws when nothing readable.
-- Selectors: CSS + puppeteer handlers `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`; also Playwright-style `p-aria/…`, `p-text/…`. Playwright-only engines/pseudos (`:has-text()`, `:visible`, …) are rejected — use `text/…` or `aria/…`. A stalled action/wait fails fast with a named `tab.<op>` error carrying a match-count diagnosis, never the whole-cell timeout; a selector matching nothing fails in ~2s (pass an explicit `{ timeout }` to `waitFor`/`waitForSelector` to wait out slow-appearing elements).
+- Selectors: CSS + puppeteer handlers `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`; also Playwright-style `p-aria/…`, `p-text/…`. Playwright-only engines/pseudos (`:has-text()`, `:visible`, …) are rejected — use `text/…` or `aria/…`. A stalled action/wait fails fast with a named `tab.<op>` error carrying a match-count diagnosis, never the whole-cell timeout; a selector matching nothing fails in ~2s (pass an explicit `{ timeout }` to `waitFor`/`waitForSelector` to wait out slow-appearing elements). A whole-cell timeout names the stalled op (including `wait(…)`) and any unhandled dialog blocking the page.
 </instruction>
 
 <critical>

package/src/prompts/tools/launch.md

@@ -0,0 +1,25 @@
+Launches and controls project-scoped long-running processes shared by every omp instance in the same directory.
+
+<instruction>
+- Long-running service, watcher, debugger, REPL, or process needing later input? MUST use `launch`, not `bash`.
+- `start` launches `application` + `args` directly. `cwd` defaults to the session directory; `pty` defaults true.
+- `ready.log` is a regex; `ready.port` is a TCP port. Both supplied? BOTH MUST pass. `ready.timeout` is seconds.
+- Names are unique per project directory. A completed name MAY be started again; a live name MUST be stopped or restarted.
+- `list`, `logs`, `wait`, `send`, `stop`, `restart`, and `describe` address the stable `name`.
+- `logs` defaults to the last 100 lines. `head: true` reads the beginning. `grep` is a regex.
+- `logs` with `follow: true` waits for output after `cursor`; reuse the returned cursor on the next call.
+- `wait` blocks until readiness/exit/pattern or timeout. Use it only when blocked; do useful work instead of tight polling.
+- `send.text` writes stdin; `enter` defaults true. `keys` supports ENTER, TAB, ESCAPE, CTRL_C, CTRL_D, UP, DOWN, LEFT, RIGHT.
+- `send.signal` supports SIGINT, SIGTERM, SIGHUP, SIGQUIT, SIGKILL. PTY input is serialized; many clients MAY observe, but writes share one input stream.
+- `stop` performs graceful process-tree termination before hard-kill. `restart` reuses the retained launch spec.
+- `restart` policy defaults `no`; `on-failure` and `always` use bounded backoff.
+- `persist: true` opts out of last-omp teardown. Otherwise the broker stops every non-persistent supervised process after the last omp in this directory exits.
+- `detached: true` survives broker shutdown and all omp exits. It implies `persist` and disables PTY/stdin.
+</instruction>
+
+<critical>
+- Long-running work MUST use `launch`, not async/background bash.
+- Readiness MUST be observed; process creation alone is not readiness.
+- Omit `persist` and `detached` unless their survival guarantees are required.
+- Use `stop`; NEVER kill an unverified PID through bash.
+</critical>

package/src/sdk.ts

@@ -109,7 +109,7 @@ import {
 	obfuscateProviderContext,
 	SecretObfuscator,
 } from "./secrets";
-import { AgentSession } from "./session/agent-session";
+import { AgentSession, type PlanYolo, type Prewalk } from "./session/agent-session";
 import { discoverAuthStorage as discoverAuthStorageFromConfig } from "./session/auth-broker-config";
 import type { AuthStorage } from "./session/auth-storage";
 import {
@@ -407,6 +407,10 @@ export interface CreateAgentSessionOptions {
 	thinkingLevel?: ConfiguredThinkingLevel;
 	/** Models available for cycling (Ctrl+P in interactive mode) */
 	scopedModels?: Array<{ model: Model; thinkingLevel?: ThinkingLevel }>;
+	/** Prewalk from the starting model to a fast/cheap target at the first edit/write once the todo list exists. */
+	prewalk?: Prewalk;
+	/** Force read-only plan mode at start, auto-approve on the model's first resolve call, then switch to execute. */
+	planYolo?: PlanYolo;
 
 	/** Provider-facing system prompt override. Replaces the fully rendered default blocks. */
 	systemPrompt?: string | string[] | ((defaultPrompt: string[]) => string | string[]);
@@ -1983,7 +1987,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			}
 		}
 		// Resolve deferred --model/subagent patterns now that extension models are
-		// registered. Expand role aliases (`pi/smol`) and comma chains to concrete
+		// registered. Expand role aliases (`@smol`) and comma chains to concrete
 		// selectors first so deferred resolution accepts everything the immediate
 		// path (resolveModelOverride → resolveModelRoleValue) accepts.
 		if (!model && deferredModelPatterns.length > 0) {
@@ -2863,6 +2867,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			agent,
 			pruneToolDescriptions: inlineToolDescriptors,
 			thinkingLevel: autoThinking ? AUTO_THINKING : effectiveThinkingLevel,
+			prewalk: options.prewalk,
+			planYolo: options.planYolo,
 			serviceTierByFamily: initialServiceTierByFamily,
 			sessionManager,
 			settings,