one-code-extension 0.1.4 → 0.3.1

package/extensions/bash/background.ts

@@ -5,16 +5,18 @@
  * A background command spawns detached in its own process group, spools
  * stdout+stderr to memory (tail-capped) and to a log file when one is given,
  * and satisfies the BackgroundTask contract so task_output/task_stop work
- * unchanged. Robustness rules from docs/plan/background-bash.md: `output()`
+ * unchanged. Robustness rules from docs/features/tools/records/background-bash.md: `output()`
  * never returns an empty body for a finished task (an explicitly-marked
  * "(no output)" beats an ambiguous blank a weak model reads as failure), and
  * the completion callback receives exactly what `output()` returns, so the
  * notification and task_output can never disagree.
  */
 
-import { type ChildProcess, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import { createWriteStream } from "node:fs";
 import type { BackgroundTask } from "../background/registry.ts";
+import { whenAborted } from "../lib/abort.ts";
+import { detachedSpawnOptions, KILL_GRACE_MS, stopProcessTree } from "../lib/process-tree.ts";
 
 export const STORED_OUTPUT_CAP = 200_000;
 
@@ -46,24 +48,11 @@ export interface StartBackgroundBashOptions {
 	onFinished(task: BackgroundTask, summary: BashFinishSummary): void;
 }
 
-function killTree(child: ChildProcess): void {
-	if (child.pid == null) return;
-	// Detached → own process group; negative pid signals the whole tree.
-	try {
-		process.kill(-child.pid, "SIGTERM");
-	} catch {
-		try {
-			child.kill("SIGTERM");
-		} catch {
-			// Already gone.
-		}
-	}
-}
-
 export function startBackgroundBash(options: StartBackgroundBashOptions): BackgroundTask {
+	// Own process group, so stop/timeout can signal the whole tree (lib/process-tree.ts).
 	const child = spawn(process.env.SHELL || "/bin/sh", ["-c", options.command], {
 		cwd: options.cwd,
-		detached: process.platform !== "win32",
+		...detachedSpawnOptions(),
 		stdio: ["ignore", "pipe", "pipe"],
 	});
 
@@ -93,13 +82,17 @@ export function startBackgroundBash(options: StartBackgroundBashOptions): Backgr
 		id: options.id,
 		kind: "bash",
 		description: options.description,
+		command: options.command,
 		status: "running",
 		startedAt: Date.now(),
 		logPath: options.logPath,
+		ownUI: true, // rendered live by the subagents panel's shell manager
 		output: () => stored || (task.status === "running" ? "" : EMPTY_OUTPUT_MARKER),
 		stop: () => {
 			stopRequested = true;
-			killTree(child);
+			// SIGTERM the tree, SIGKILL after the grace: a command that traps TERM
+			// would otherwise never close, and a blocking one-shot run never return.
+			stopProcessTree(child, KILL_GRACE_MS);
 		},
 		finished,
 	};
@@ -108,7 +101,7 @@ export function startBackgroundBash(options: StartBackgroundBashOptions): Backgr
 	if (options.timeoutSeconds && options.timeoutSeconds > 0) {
 		timer = setTimeout(() => {
 			timedOut = true;
-			killTree(child);
+			stopProcessTree(child, KILL_GRACE_MS);
 		}, options.timeoutSeconds * 1000);
 		timer.unref?.();
 	}
@@ -119,9 +112,16 @@ export function startBackgroundBash(options: StartBackgroundBashOptions): Backgr
 		if (timer) clearTimeout(timer);
 		task.status = status;
 		task.finishedAt = Date.now();
-		log?.end();
-		finish();
-		options.onFinished(task, { exitCode, signal, stopped: stopRequested, timedOut, output: task.output() });
+		const complete = () => {
+			finish();
+			options.onFinished(task, { exitCode, signal, stopped: stopRequested, timedOut, output: task.output() });
+		};
+		// end() flushes asynchronously; `finished` must not resolve while the
+		// log file is still short of what output() returns, or a reader sent to
+		// logPath by the completion notification can see a truncated file. The
+		// callback also fires if the stream errors, so this cannot hang.
+		if (log) log.end(complete);
+		else complete();
 	};
 
 	child.on("error", (error) => {
@@ -134,3 +134,28 @@ export function startBackgroundBash(options: StartBackgroundBashOptions): Backgr
 
 	return task;
 }
+
+/**
+ * Run a background command to completion and resolve with its summary — the
+ * shape the one-shot modes need (`-p` / `--mode json`): the process exits when
+ * the turn settles, so a detached task would be orphaned with its completion
+ * undelivered — and, worse, its late callback would call `sendMessage` on the
+ * disposed session and crash pi (STEERING-REVIEW-2026-09-05 H3). The tool's
+ * abort signal stops the process tree; the summary then reports `stopped`.
+ */
+export function runBackgroundBashBlocking(
+	options: Omit<StartBackgroundBashOptions, "onFinished">,
+	signal?: AbortSignal,
+): Promise<BashFinishSummary> {
+	return new Promise((resolve) => {
+		let unhook = () => {};
+		const task = startBackgroundBash({
+			...options,
+			onFinished: (_task, summary) => {
+				unhook();
+				resolve(summary);
+			},
+		});
+		unhook = whenAborted(signal, () => task.stop());
+	});
+}

package/extensions/bash/guards.ts

@@ -0,0 +1,229 @@
+/**
+ * Deterministic pre-execution guards for the bash tool (pure).
+ *
+ * Each guard recognises a workflow anti-pattern BEFORE the command runs and
+ * refuses it with an instructive error: what tripped it, why it is a problem,
+ * the sanctioned alternative, and a clause closing the obvious workaround.
+ * These are steering, not security — the permission gate and the auto-mode
+ * classifier still apply to everything that passes. The contract mirrors the
+ * auto-mode pre-gate's: a guard concludes only on a positive parse, so an
+ * unparseable command always passes through.
+ *
+ * Guards, in order:
+ * - interactive guard (foreground + background): a command that needs a TTY
+ *   (`vim`, `git rebase -i`, `git add -p`, `watch`) hangs until the timeout —
+ *   or worse, silently no-ops — in this pipe-connected shell.
+ * - wait guard (foreground): a command that LEADS with `sleep` exists only to
+ *   wait and stalls the whole session. Provably-short sleeps (< 2s) are
+ *   legitimate pacing and pass; a sleep deeper in a chain is a pause inside
+ *   real work and is left alone.
+ * - poll-loop guard (foreground): a `while`/`until`/`for` loop that sleeps is
+ *   the same stall spelled as a loop — the monitor tool exists to run the
+ *   until-loop without occupying the session.
+ * - orphan guard (foreground): `nohup`/`setsid`/a top-level `&` detaches a
+ *   process nothing manages, losing its output and exit status. A command
+ *   that ends with `wait` reaps its own children and passes.
+ */
+
+import {
+	gitSubcommand,
+	leadTokens,
+	parseCommand,
+	resolvePayload,
+	type Segment,
+	type Token,
+} from "../auto-mode/shell-analysis.ts";
+
+const clip = (text: string, max = 200): string => (text.length > max ? `${text.slice(0, max)}…` : text);
+
+export function bashGuardReason(command: string, opts: { background: boolean }): string | undefined {
+	// A heredoc/here-string body is data, but parseCommand tokenizes it as live
+	// shell — every guard would misfire on body text (a literal `vim` or
+	// `while … sleep` inside a document). Judge only the command that PRECEDES
+	// the first `<<`: `sleep 600 <<< ""` is still a sleep (review T14), while a
+	// `cat <<EOF` body is never read.
+	const lead = command.split(/<</)[0];
+	if (lead !== command && !lead.trim()) return undefined;
+	const { segments, parseFailed } = parseCommand(lead);
+	if (parseFailed || segments.length === 0) return undefined;
+	const interactive = interactiveReason(segments);
+	if (interactive || opts.background) return interactive;
+	return waitReason(segments) ?? pollLoopReason(lead, segments) ?? orphanReason(lead, segments);
+}
+
+// ---------------------------------------------------------------------------
+// Wait guard
+
+/**
+ * Seconds a `sleep` invocation provably lasts (GNU sleep sums multiple
+ * duration arguments), or undefined when any argument is not a literal.
+ */
+function sleepSeconds(args: Token[]): number | undefined {
+	if (args.length === 0) return undefined;
+	let total = 0;
+	for (const arg of args) {
+		const match = /^(\d+(?:\.\d+)?|\.\d+)([smhd]?)$/.exec(arg.value);
+		if (!match) return undefined;
+		total += Number(match[1]) * ({ "": 1, s: 1, m: 60, h: 3600, d: 86400 }[match[2]] ?? 1);
+	}
+	return total;
+}
+
+// A segment's raw slice can keep half of the operator that ended the previous
+// one (`a && b` → second raw is `& b`) — strip it for a clean echo.
+
+function waitReason(segments: Segment[]): string | undefined {
+	// Measure the run of LEADING sleep segments: `sleep 1 && sleep 1 && …` is
+	// one wait spelled as a chain, so the pacing exemption applies only to a
+	// single provably-short sleep. Unprovable durations (`sleep "$DELAY"`)
+	// count as long — the model controls the literal.
+	let leadSleeps = 0;
+	let total: number | undefined = 0;
+	for (const seg of segments) {
+		const { command: cmd, args } = resolvePayload(leadTokens(seg));
+		if (cmd !== "sleep") break;
+		leadSleeps++;
+		const seconds = sleepSeconds(args);
+		total = total === undefined || seconds === undefined ? undefined : total + seconds;
+	}
+	if (leadSleeps === 0) return undefined;
+	if (leadSleeps === 1 && total !== undefined && total < 2) return undefined;
+	const rest = segments.slice(leadSleeps).map((seg) => seg.raw).filter(Boolean).join("; ");
+	const shown = segments.slice(0, leadSleeps).map((seg) => seg.raw).join(" && ");
+	const echo = rest ? `\`${shown}\` followed by: ${clip(rest)}` : `standalone \`${shown}\``;
+	return (
+		`Blocked: ${echo}. A foreground sleep stalls the whole session while it runs. ` +
+		"To wait for a command you started, run it with run_in_background: true — its completion arrives as a system notification on its own, so you never need to poll. " +
+		"To wait for a condition, use the monitor tool with an until-loop (e.g. `until <check>; do sleep 2; done`) — monitor is deferred, load it with tool_search select:monitor. " +
+		"If you genuinely need a delay (rate limiting, deliberate pacing), keep it under 2 seconds. " +
+		"Do not chain shorter sleeps to work around this block."
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Poll-loop guard
+
+function pollLoopReason(command: string, segments: Segment[]): string | undefined {
+	const first = leadTokens(segments[0])[0]?.value;
+	if (first !== "while" && first !== "until" && first !== "for") return undefined;
+	// `sleep` counts only in command position (segment lead, or right after a
+	// `do`/`then`/`else` keyword) — `echo sleep` is data, not a wait.
+	const sleeps = segments.some((seg) => {
+		const { command: cmd } = resolvePayload(leadTokens(seg));
+		return cmd === "sleep";
+	});
+	if (!sleeps) return undefined;
+	return (
+		`Blocked: a foreground polling loop (\`${clip(command, 160)}\`). It occupies the whole session while it spins. ` +
+		"Use the monitor tool to run the until-loop for you (deferred — load it with tool_search select:monitor) — it returns when the condition holds — or start the underlying work with run_in_background: true and let its completion notification arrive on its own. " +
+		"Do not shorten the sleep or unroll the loop to work around this block."
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Orphan guard
+
+/** True when the command backgrounds something with a top-level unquoted `&`. */
+export function hasBackgroundAmp(command: string): boolean {
+	let inSingle = false;
+	let inDouble = false;
+	let inAnsiC = false; // $'…' honors backslash-escaped quotes, unlike '…'
+	let escape = false;
+	for (let i = 0; i < command.length; i++) {
+		const ch = command[i];
+		if (escape) {
+			escape = false;
+			continue;
+		}
+		if (inAnsiC) {
+			if (ch === "\\") escape = true;
+			else if (ch === "'") inAnsiC = false;
+			continue;
+		}
+		if (ch === "'" && !inSingle && !inDouble && command[i - 1] === "$") {
+			inAnsiC = true;
+			continue;
+		}
+		if (ch === "\\" && !inSingle) {
+			escape = true;
+			continue;
+		}
+		if (ch === "'" && !inDouble) {
+			inSingle = !inSingle;
+			continue;
+		}
+		if (ch === '"' && !inSingle) {
+			inDouble = !inDouble;
+			continue;
+		}
+		if (inSingle || inDouble || ch !== "&") continue;
+		const prev = command[i - 1];
+		const next = command[i + 1];
+		if (next === "&") {
+			i++; // logical &&
+			continue;
+		}
+		if (next === ">") continue; // &> redirect
+		if (prev === ">" || prev === "|") continue; // 2>&1 fd duplication, |& pipe
+		return true;
+	}
+	return false;
+}
+
+function orphanReason(command: string, segments: Segment[]): string | undefined {
+	const message = (via: string) =>
+		`Blocked: this command detaches a process with ${via}, leaving an orphan this session cannot manage — its output and exit status would be lost. ` +
+		"Run it with run_in_background: true instead: it returns a task id immediately, completion arrives as a system notification, output stays readable with task_output, and it can be stopped with task_stop. " +
+		"If you need shell-level parallelism inside one command, end it with `wait` so the children are reaped.";
+
+	for (const seg of segments) {
+		const { peeled } = resolvePayload(leadTokens(seg));
+		const detacher = peeled.find((p) => p === "nohup" || p === "setsid");
+		if (detacher) return message(`\`${detacher}\``);
+	}
+	// Only a `wait` that comes LAST reaps the children — `wait; job &` still
+	// orphans the job it precedes.
+	const lastCmd = resolvePayload(leadTokens(segments[segments.length - 1])).command;
+	if (hasBackgroundAmp(command) && lastCmd !== "wait") return message("`&`");
+	return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Interactive guard
+
+const EDITORS = new Set(["vi", "vim", "nvim", "view", "vimdiff", "nano", "pico", "emacs"]);
+
+function interactiveReason(segments: Segment[]): string | undefined {
+	for (const seg of segments) {
+		const { command: cmd, args } = resolvePayload(leadTokens(seg));
+		if (EDITORS.has(cmd)) {
+			if (cmd === "emacs" && args.some((a) => ["--batch", "-batch", "--script"].includes(a.value))) continue;
+			return (
+				`Blocked: \`${cmd}\` is an interactive editor and this shell has no TTY — it would hang until the timeout. ` +
+				"Read files with the read tool and change them with edit/write."
+			);
+		}
+		if (cmd === "watch") {
+			return (
+				"Blocked: `watch` needs an interactive terminal, which this shell does not have. " +
+				"Use the monitor tool (deferred — load it with tool_search select:monitor) to wait for a condition, or run_in_background: true with task_output to check on long-running output."
+			);
+		}
+		if (cmd !== "git") continue;
+		const { sub, rest } = gitSubcommand(args);
+		const flags = new Set(rest.map((t) => t.value));
+		if (sub === "rebase" && (flags.has("-i") || flags.has("--interactive"))) {
+			return (
+				"Blocked: `git rebase -i` opens an interactive editor, which this shell cannot provide — it would hang until the timeout. " +
+				"Drive it non-interactively instead: `GIT_SEQUENCE_EDITOR=: git rebase …` accepts the todo list as-is, or restructure history with `git rebase --onto`, `git commit --amend`, or `git cherry-pick`."
+			);
+		}
+		if (sub === "add" && ["-i", "--interactive", "-p", "--patch"].some((f) => flags.has(f))) {
+			return (
+				"Blocked: interactive `git add` prompts on a TTY this shell does not have — it would read EOF and stage nothing while appearing to succeed. " +
+				"Stage whole files with `git add <paths>`, or stage a partial change non-interactively with `git apply --cached` and a crafted diff."
+			);
+		}
+	}
+	return undefined;
+}

package/extensions/bash/index.ts

@@ -11,8 +11,8 @@
  * A background run spawns detached, returns a task id immediately, spools
  * output to `<sessionDir>/bash/<taskId>/output.log`, registers on the shared
  * background registry (task_output/task_stop just work — they are
- * kind-agnostic), and announces completion as a follow-up system
- * notification. The permission gate and auto-mode classifier run before
+ * kind-agnostic), and announces completion as a steered system notification
+ * (lib/notifications.ts). The permission gate and auto-mode classifier run before
  * execute like any bash call — a background command is NOT auto-allowed, and
  * the gate fires before anything detaches.
  */
@@ -23,18 +23,26 @@ import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-w
 import { createBashToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { generateTaskId, TASK_REGISTER_CHANNEL } from "../background/registry.ts";
-import { type BashFinishSummary, startBackgroundBash, tailCap } from "./background.ts";
-import { systemNotification } from "../lib/notifications.ts";
+import { type BashFinishSummary, runBackgroundBashBlocking, startBackgroundBash, tailCap } from "./background.ts";
+import { bashGuardReason } from "./guards.ts";
+import { commandToEvaluate, trackOriginalCommands } from "../lib/original-command.ts";
+import { createTaskNotifier, oneShotNote, sessionOutlivesTurn, systemNotification } from "../lib/notifications.ts";
+import { persistIfLarge, sessionResultsDir } from "../lib/persisted-output.ts";
 import { perCwd } from "../lib/per-cwd.ts";
 import { ccWrapBuiltinRenderers, linesComponent, resultLines } from "../lib/tui-render.ts";
 
-const NOTIFY_OUTPUT_CAP = 30_000;
+// The completion notification carries status + exit code + where the output is,
+// plus only a short tail: a finished build used to push 30 KB (~8k tokens) into
+// context unasked (review T7). The full tail stays behind task_output / the log.
+const NOTIFY_OUTPUT_CAP = 2_000;
+/** One-shot modes return the whole output in the result; past this it is persisted (file + preview), never cut. */
+const ONE_SHOT_OUTPUT_CAP = 30_000;
+/** Claude Code's Bash cap; the tool's `timeout` is milliseconds, as CC's is. */
+const MAX_TIMEOUT_MS = 600_000;
 
 const BashParams = Type.Object({
 	command: Type.String({ description: "Bash command to execute" }),
-	timeout: Type.Optional(
-		Type.Number({ description: "Timeout in seconds (optional; also applies to background runs)" }),
-	),
+	timeout: Type.Optional(Type.Number({ description: "Optional timeout in milliseconds (max 600000)" })),
 	run_in_background: Type.Optional(
 		Type.Boolean({
 			description:
@@ -52,13 +60,22 @@ export default function bashExtension(pi: ExtensionAPI) {
 	// switches change ctx.cwd mid-session).
 	const base = createBashToolDefinition(process.cwd());
 	const foreground = perCwd(createBashToolDefinition);
+	// pi's base sentence is "Optionally provide a timeout in seconds." — but the
+	// `timeout` parameter and the execute path both use milliseconds (Claude
+	// Code's Bash unit; the executor divides by 1000). The two must not
+	// contradict, or a model that trusts the description sends `timeout: 120`
+	// and gets a 120 ms deadline (TOOL-FIDELITY-REVIEW-2026-09-07 H3). Swap in
+	// CC's Bash sentence.
+	const baseDescription = base.description.replace(
+		"Optionally provide a timeout in seconds.",
+		"`timeout` is in milliseconds: default 120000, max 600000.",
+	);
 
-	const notify = (text: string, details: Record<string, unknown>) => {
-		pi.sendMessage(
-			{ customType: "task-notification", content: [{ type: "text", text }], display: true, details },
-			{ deliverAs: "followUp", triggerTurn: true },
-		);
-	};
+	const notifyTask = createTaskNotifier(pi);
+	// A worktree session cd-wraps input.command; the pre-wrapper original arrives
+	// over the bus keyed by toolCallId (never read from params — model-writable).
+	const originalCommands = trackOriginalCommands(pi);
+	const notify = (text: string, details: Record<string, unknown>) => notifyTask("task-notification", text, details);
 
 	const taskLogPath = (ctx: ExtensionContext, taskId: string): string | undefined => {
 		try {
@@ -80,7 +97,7 @@ export default function bashExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "bash",
 		label: base.label,
-		description: `${base.description} Pass run_in_background: true for long-running commands (builds, servers, watches): it returns a task id immediately so you can keep working, completion arrives as a system notification, and the output is retrievable with task_output / stoppable with task_stop.`,
+		description: `${baseDescription} Pass run_in_background: true for long-running commands (builds, servers, watches): it returns a task id immediately so you can keep working, completion arrives as a system notification, and the output is retrievable with task_output / stoppable with task_stop (both deferred — load them with tool_search; in a one-shot print/json session the call runs to completion and returns the output directly). Foreground \`sleep\` is blocked; to wait on a condition use the monitor tool (deferred — load it with tool_search select:monitor) with an until-loop.`,
 		promptSnippet: base.promptSnippet,
 		promptGuidelines: base.promptGuidelines,
 		executionMode: base.executionMode,
@@ -97,7 +114,9 @@ export default function bashExtension(pi: ExtensionAPI) {
 					// the transcript needs one line (Claude Code: "Running in the background").
 					const details = result.details as { taskId?: string; logPath?: string } | undefined;
 					if (details?.taskId && !context.isError) {
-						const line = `Running in background (task ${details.taskId}${details.logPath ? ` · log: ${details.logPath}` : ""})`;
+						const line = options.expanded
+							? `Running in the background (task ${details.taskId}${details.logPath ? ` · log: ${details.logPath}` : ""})`
+							: "Running in the background (↓ to manage)";
 						return linesComponent(() => resultLines(theme as any, line, options.expanded, false));
 					}
 					return wrapped.renderResult(result, options, theme, context);
@@ -106,10 +125,23 @@ export default function bashExtension(pi: ExtensionAPI) {
 		})(),
 		parameters: BashParams,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			// Guards check the model's original command — a worktree session rewrites
+			// input.command to `cd '<wt>' && (…)`, which would hide the real lead.
+			const originalCommand = commandToEvaluate(originalCommands, toolCallId, params.command);
+			const guardReason = bashGuardReason(originalCommand, { background: params.run_in_background === true });
+			if (guardReason) return { content: [{ type: "text" as const, text: guardReason }], isError: true, details: {} };
+			const timeoutSeconds =
+				params.timeout !== undefined && Number.isFinite(params.timeout) && params.timeout > 0
+					? Math.min(params.timeout, MAX_TIMEOUT_MS) / 1000
+					: undefined;
+
 			if (!params.run_in_background) {
+				// pi's executor takes seconds; the model-facing unit is milliseconds
+				// (Claude Code's Bash), so a habitual `timeout: 120000` is 2 minutes,
+				// not 33 hours (review T11).
 				return foreground(ctx.cwd).execute(
 					toolCallId,
-					{ command: params.command, timeout: params.timeout },
+					{ command: params.command, timeout: timeoutSeconds },
 					signal,
 					onUpdate,
 					ctx,
@@ -119,16 +151,46 @@ export default function bashExtension(pi: ExtensionAPI) {
 			const id = generateTaskId();
 			const logPath = taskLogPath(ctx, id);
 			const description = params.description || params.command.slice(0, 80);
+
+			// One-shot modes (`-p` / `--mode json`) exit when the turn settles: a
+			// detached task would be orphaned, and its completion callback would
+			// call sendMessage on the disposed session and crash pi (measured,
+			// STEERING-REVIEW-2026-09-05 H3). Run blocking there — the same rule the
+			// Agent tool applies — and return the output in the result.
+			if (!sessionOutlivesTurn(ctx.mode)) {
+				const summary = await runBackgroundBashBlocking(
+					{ id, command: params.command, description, cwd: ctx.cwd, timeoutSeconds, logPath },
+					signal,
+				);
+				const output = persistIfLarge(summary.output, { dir: sessionResultsDir(ctx), id: `bash-${id}`, maxBytes: ONE_SHOT_OUTPUT_CAP });
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Bash task ${id} (${description}) ${finishLine(summary, timeoutSeconds)}. ${oneShotNote("command")}${logPath ? ` Log: ${logPath}.` : ""}\n\n${output}`,
+						},
+					],
+					// No taskId: nothing was registered behind task_output/task_stop, and
+					// its presence is what renderResult reads as "running in the background".
+					details: { logPath },
+					isError: summary.exitCode !== 0 && !summary.stopped,
+				};
+			}
+
 			const task = startBackgroundBash({
 				id,
 				command: params.command,
 				description,
 				cwd: ctx.cwd,
-				timeoutSeconds: params.timeout,
+				timeoutSeconds,
 				logPath,
 				onFinished: (finishedTask, summary) => {
+					const tail = tailCap(summary.output, NOTIFY_OUTPUT_CAP).trim();
+					const where = `Full output: task_output ${id}${logPath ? ` (or read ${logPath})` : ""}.`;
 					notify(
-						systemNotification(`Background bash ${id} (${description}) ${finishLine(summary, params.timeout)}.\n\n${tailCap(summary.output, NOTIFY_OUTPUT_CAP)}`),
+						systemNotification(
+							`Background bash ${id} (${description}) ${finishLine(summary, timeoutSeconds)}. ${where}${tail ? `\n\nLast output:\n${tail}` : ""}`,
+						),
 						{ taskId: id, status: finishedTask.status, exitCode: summary.exitCode, logPath },
 					);
 				},

package/extensions/branding/index.ts

@@ -20,11 +20,14 @@ import { dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, SettingsManager, VERSION as PI_VERSION } from "@earendil-works/pi-coding-agent";
 import { piVersionWarning } from "../lib/pi-version.ts";
+import { extensionVersion } from "../lib/package-version.ts";
 import {
+	formatModel,
+	formatModelSpec,
+	isRealModel,
 	PERMISSION_STATUS_CHANNEL,
 	permissionModeDisplay,
 	type PermissionStatus,
-	shortModelName,
 } from "../permissions/modes.ts";
 import { SUBAGENT_STATUS_CHANNEL, type SubagentStatus } from "../subagents/model-select.ts";
 import {
@@ -34,7 +37,7 @@ import {
 	shouldDefaultHideThinking,
 	type StartupSection,
 } from "./startup.ts";
-import { safeThemePaint, truncateLine } from "../lib/tui-render.ts";
+import { linesComponent, safeThemePaint, truncateLine } from "../lib/tui-render.ts";
 import { markAssistantMarkdown } from "./assistant-marker.ts";
 import { PROMPT_PADDING, PromptEditor } from "./prompt-editor.ts";
 
@@ -298,11 +301,13 @@ export default function brandingExtension(pi: ExtensionAPI) {
 	let permissionStatus: PermissionStatus | undefined;
 	let subagentStatus: SubagentStatus | undefined;
 	let currentModelId: string | undefined;
+	let currentModelProvider: string | undefined;
 	let requestHeaderRender: (() => void) | undefined;
 	// The model line goes stale the same way the mode line did once the header
 	// re-renders live, so it follows ctrl+p / /model changes too.
 	pi.on("model_select", (event) => {
 		currentModelId = event.model?.id ?? currentModelId;
+		currentModelProvider = event.model?.provider ?? currentModelProvider;
 		requestHeaderRender?.();
 	});
 	pi.events.on(PERMISSION_STATUS_CHANNEL, (data) => {
@@ -318,8 +323,9 @@ export default function brandingExtension(pi: ExtensionAPI) {
 		// Only the TUI has a header to replace; rpc/print modes have no chrome.
 		if (!ctx.hasUI || ctx.mode !== "tui") return;
 
-		const version = process.env.CC_VERSION ?? "0.1.0";
-		currentModelId = ctx.model ? `${ctx.model.id}` : currentModelId;
+		const version = process.env.CC_VERSION ?? extensionVersion();
+		currentModelId = ctx.model?.id ?? currentModelId;
+		currentModelProvider = ctx.model?.provider ?? currentModelProvider;
 
 		// With pi's own listing silenced, the banner carries compact sections
 		// instead (minus the internal [Extensions] noise).
@@ -334,33 +340,53 @@ export default function brandingExtension(pi: ExtensionAPI) {
 		ctx.ui.setTitle(NAME);
 		ctx.ui.setHeader((tui: unknown, theme: unknown) => {
 			const paint = safeThemePaint(theme);
-			requestHeaderRender = () => {
-				(tui as { requestRender?: () => void } | undefined)?.requestRender?.();
-			};
-			return {
-				// Rendered per paint rather than precomputed, so the mode line
-				// follows ctrl+q cycles and the classifier pinning.
-				render: (width: number) => [
+			// Width-memoized (pi-tui renders every mounted component every frame);
+			// the mode/model/subagent lines stay live because each of their
+			// updates invalidates the cache before requesting a repaint.
+			const component = linesComponent((width) => {
+				// Read live each render (model_select invalidates the cache). isRealModel
+				// narrows currentModelId to string; the label is undefined when no
+				// provider is configured, which both fields below render as "none" — a
+				// fresh machine must not show pi's placeholder `(unknown) unknown` (M3).
+				const modelLabel = isRealModel(currentModelId) ? formatModel(currentModelProvider ?? "", currentModelId) : undefined;
+				return [
 					"",
 					...bannerLines(
 						{
 							version,
-							model: currentModelId,
+							model: modelLabel ?? "none",
 							cwd: ctx.cwd,
 							mode: permissionModeDisplay(permissionStatus ?? { mode: "default", paused: false }),
-							subagents: subagentStatus?.model
-								? `${shortModelName(subagentStatus.model)}${subagentStatus.via ? ` (${subagentStatus.via})` : ""}`
-								: undefined,
+							subagents:
+								modelLabel === undefined
+									? "none"
+									: subagentStatus?.model
+										? `${formatModelSpec(subagentStatus.model)}${subagentStatus.via ? ` (${subagentStatus.via})` : ""}`
+										: undefined,
 							sections,
 						},
 						paint,
 						width,
 					),
 					"",
-				],
-				// Nothing is cached, so there is nothing to invalidate.
-				invalidate: () => {},
+				];
+			});
+			requestHeaderRender = () => {
+				component.invalidate();
+				(tui as { requestRender?: () => void } | undefined)?.requestRender?.();
 			};
+			return component;
 		});
+
+		// A fresh machine has no provider configured; pi's own hint prints two
+		// absolute doc paths inside node_modules. Replace it with a One Code
+		// onboarding line that names the command that actually connects a provider
+		// and points at the guide, not pi's files (distribution review M3).
+		if (!isRealModel(ctx.model?.id)) {
+			ctx.ui.notify(
+				"No model provider yet. Run /login to connect one (free options at https://github.com/IsuruMaduranga/one-code/blob/master/docs/guide/providers-and-models.md).",
+				"warning",
+			);
+		}
 	});
 }