jeopi-cli 16.4.2 → 16.4.4

package/dist/types/tools/browser/launch.d.ts

@@ -13,6 +13,7 @@ export declare const DEFAULT_VIEWPORT: {
 export declare const BROWSER_PROTOCOL_TIMEOUT_MS = 60000;
 export declare function loadPuppeteer(): Promise<typeof Puppeteer>;
 export declare function loadPuppeteerInWorker(safeDir: string): Promise<typeof Puppeteer>;
+export declare function ensureChromiumExecutable(): Promise<string | undefined>;
 export interface LaunchHeadlessOptions {
     headless: boolean;
     viewport?: {

package/dist/types/tools/browser/run-cancellation.d.ts

@@ -1,4 +1,19 @@
-/** Sleeps inside evaluated browser code while honoring the owning run's cancellation signal. */
-export declare function waitForBrowserRun(ms: number, signal: AbortSignal): Promise<void>;
+/** Options for the predicate form of the run-scoped `wait()` helper. */
+export interface WaitPredicateOptions {
+    /** Max time to poll before failing, in ms (default 30_000). */
+    timeout?: number;
+    /** Poll interval in ms (default 100, floor 10). */
+    interval?: number;
+}
+/**
+ * Run-scoped `wait()` helper for evaluated browser code, honoring the owning run's
+ * cancellation signal.
+ *
+ * - `wait(ms)` sleeps for `ms` milliseconds.
+ * - `wait(fn, { timeout?, interval? })` polls `fn` (sync or async) until it returns a
+ *   truthy value and resolves with that value; throws a named `ToolError` on timeout
+ *   instead of stalling into the whole-cell deadline. Predicate errors propagate.
+ */
+export declare function waitForBrowserRun(msOrPredicate: number | (() => unknown), signal: AbortSignal, opts?: WaitPredicateOptions): Promise<unknown>;
 /** Binds a long-lived browser facade to one evaluated run's abort signal. */
 export declare function bindBrowserRunFacade<T extends object>(target: T, signal: AbortSignal): T;

package/dist/types/tools/browser/run-output.d.ts

@@ -0,0 +1,25 @@
+import type { ImageContent, TextContent } from "jeopi-ai";
+import type { JsDisplayOutput } from "../../eval/js/shared/types";
+/**
+ * Accumulates a browser run's result entries: explicit `display()` payloads,
+ * screenshot captions/images, and buffered stream text (`console.*`, `print`,
+ * `display()` of strings/primitives — `JsRuntime.displayValue` emits those via
+ * `onText`). Stream text is buffered and flushed as one entry before the next
+ * display/screenshot (and on `finish()`) so it reaches the tool result in
+ * order instead of vanishing into the debug log.
+ */
+export declare class RunOutput {
+    #private;
+    /** Buffer a stream-text chunk; it joins the entries at the next push or on finish(). */
+    pushText(chunk: string): void;
+    /** Append a `display()` payload (image/json/status), flushing buffered text first. */
+    pushDisplay(output: JsDisplayOutput): void;
+    /** Append a pre-built entry (e.g. a screenshot caption/image), flushing buffered text first. */
+    push(entry: TextContent | ImageContent): void;
+    /** Flush any remaining stream text and return the ordered entries. */
+    finish(): Array<TextContent | ImageContent>;
+}
+/** JSON.stringify that never throws (cycles/BigInt → String(value)). */
+export declare function safeJsonStringify(value: unknown): string;
+/** Pass a return value across the run boundary: structured-cloneable as-is, else JSON round-trip, else String. */
+export declare function cloneSafe(value: unknown): unknown;

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

@@ -1,6 +1,12 @@
 import type { HTMLElement } from "linkedom";
 import type { ElementHandle, ImageFormat } from "puppeteer-core";
 import type { Transport } from "./tab-protocol";
+declare module "puppeteer-core" {
+    interface Frame {
+        /** Puppeteer's main JavaScript realm, retained by our pinned runtime patch. */
+        mainRealm(): Realm;
+    }
+}
 declare global {
     interface Element extends HTMLElement {
     }
@@ -37,6 +43,22 @@ interface ScreenshotOptions {
     silent?: boolean;
 }
 export declare function normalizeSelector(selector: string): string;
+/** ElementHandle enriched with the `fill()` the tool docs promise on handles from `tab.id()`/`tab.ref()`/`tab.waitFor()`. */
+export type ActionableHandle = ElementHandle & {
+    fill(value: string): Promise<void>;
+};
+/**
+ * Attach `fill()` to a puppeteer ElementHandle before handing it to user code.
+ * Puppeteer handles expose `type()` but no `fill()`; the semantics mirror the
+ * selector-based `tab.fill()`: focus, clear any existing value, then type.
+ */
+export declare function toActionableHandle(handle: ElementHandle): ActionableHandle;
+/**
+ * Hint appended to a selector op's fail-fast timeout, given the selector's current
+ * match count: a missing element (consent wall, wrong page) reads differently from
+ * a present-but-unactionable one.
+ */
+export declare function formatSelectorMatchHint(count: number): string;
 export interface InflightOp {
     label: string;
     startedAt: number;

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

@@ -4,6 +4,24 @@ export interface ChangelogEntry {
     patch: number;
     content: string;
 }
+/** Number of changelog releases shown by automatic and default recent views. */
+export declare const RECENT_CHANGELOG_ENTRY_LIMIT = 3;
+/** Maximum Markdown source bytes allowed in automatic startup release notes. */
+export declare const STARTUP_CHANGELOG_MAX_BYTES: number;
+/** Hint appended when automatic startup release notes are truncated. */
+export declare const STARTUP_CHANGELOG_FULL_HINT = "Use `/changelog full` to view the complete changelog.";
+/** Markdown generated from selected changelog entries and whether it hit a size cap. */
+export interface RenderedChangelog {
+    markdown: string;
+    truncated: boolean;
+}
+/** Automatic startup changelog decision, including whether the marker should advance. */
+export interface StartupChangelogSelection {
+    markdown: string | undefined;
+    persistCurrentVersion: boolean;
+    truncated: boolean;
+    selectedEntries: number;
+}
 /**
  * Parse changelog entries from the file at `changelogPath`. Scans for `## [x.y.z]`
  * headings and collects each block until the next heading or EOF.
@@ -19,9 +37,25 @@ export declare function parseChangelog(changelogPath: string | undefined): Promi
  */
 export declare function compareVersions(v1: ChangelogEntry, v2: ChangelogEntry): number;
 /**
- * Get entries newer than lastVersion
+ * Parse an omp changelog marker version into comparable parts.
+ */
+export declare function parseChangelogVersion(version: string | undefined): ChangelogEntry | undefined;
+/**
+ * Get entries newer than lastVersion.
  */
 export declare function getNewEntries(entries: ChangelogEntry[], lastVersion: string): ChangelogEntry[];
+/**
+ * Render changelog entries oldest-first by default and optionally cap the Markdown source size.
+ */
+export declare function renderChangelogEntries(entries: ChangelogEntry[], options?: {
+    maxBytes?: number;
+    truncationHint?: string;
+    oldestFirst?: boolean;
+}): RenderedChangelog;
+/**
+ * Select bounded release notes for interactive startup.
+ */
+export declare function selectStartupChangelog(entries: ChangelogEntry[], lastVersion: string | undefined, currentVersion: string): StartupChangelogSelection;
 export { getChangelogPath } from "../config";
 /**
  * Last jeopi version whose changelog the user has seen. Stored as a plain-text

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "jeopi-cli",
-	"version": "16.4.2",
+	"version": "16.4.4",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/akillness/jeopi",
 	"author": "Can Boluk",
@@ -57,17 +57,17 @@
 		"@agentclientprotocol/sdk": "0.25.0",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"jeopi-hashline": "16.4.2",
-		"jeopi-stats": "16.4.2",
-		"jeopi-agent-core": "16.4.2",
-		"jeopi-ai": "16.4.2",
-		"jeopi-catalog": "16.4.2",
-		"jeopi-mnemopi": "16.4.2",
-		"jeopi-natives": "16.4.2",
-		"jeopi-tui": "16.4.2",
-		"jeopi-utils": "16.4.2",
-		"jeopi-wire": "16.4.2",
-		"jeopi-snapcompact": "16.4.2",
+		"jeopi-hashline": "16.4.4",
+		"jeopi-stats": "16.4.4",
+		"jeopi-agent-core": "16.4.4",
+		"jeopi-ai": "16.4.4",
+		"jeopi-catalog": "16.4.4",
+		"jeopi-mnemopi": "16.4.4",
+		"jeopi-natives": "16.4.4",
+		"jeopi-tui": "16.4.4",
+		"jeopi-utils": "16.4.4",
+		"jeopi-wire": "16.4.4",
+		"jeopi-snapcompact": "16.4.4",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",

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

@@ -1839,6 +1839,19 @@ describe("advisor", () => {
 			expect(text).toContain("read, grep, glob (default)");
 		});
 
+		it("renders an explicit no-tools advisor distinctly from the omitted default", async () => {
+			const uiTheme = await getThemeByName("dark");
+			if (!uiTheme) throw new Error("theme unavailable");
+			setThemeInstance(uiTheme);
+			const overlay = make({
+				advisors: [{ name: "Blank", tools: [] }],
+			});
+
+			const text = strip(overlay.render(200));
+			expect(text.toLowerCase()).toContain("no tools");
+			expect(text).not.toContain("read, grep, glob (default)");
+		});
+
 		it("moves the preview with keyboard selection and preserves an explicit tool set", async () => {
 			const uiTheme = await getThemeByName("dark");
 			if (!uiTheme) throw new Error("theme unavailable");

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

@@ -55,6 +55,27 @@ describe("discoverAdvisorConfigs", () => {
 		expect(sharedInstructions).toBe("Shared baseline for all advisors.");
 	});
 
+	it("distinguishes omitted tools, explicit no-tools, and invalid-only lists", async () => {
+		const yaml = [
+			"advisors:",
+			"  - name: No Tools",
+			"    tools: []",
+			"  - name: Default Tools",
+			"  - name: Invalid Only",
+			"    tools: [reed]",
+		].join("\n");
+		await Bun.write(path.join(tmp, "WATCHDOG.yml"), yaml);
+
+		const { advisors } = await discoverAdvisorConfigs(tmp, agentDir);
+		const noTools = advisors.find(a => a.name === "No Tools");
+		const defaultTools = advisors.find(a => a.name === "Default Tools");
+		const invalidOnly = advisors.find(a => a.name === "Invalid Only");
+
+		expect(noTools?.tools).toEqual([]);
+		expect(defaultTools?.tools).toBeUndefined();
+		expect(invalidOnly?.tools).toBeUndefined();
+	});
+
 	it("ignores a malformed YAML file without throwing", async () => {
 		await Bun.write(path.join(tmp, "WATCHDOG.yml"), "advisors: [unclosed bracket");
 		const result = await discoverAdvisorConfigs(tmp, agentDir);
@@ -122,6 +143,21 @@ describe("WATCHDOG.yml file round-trip", () => {
 		expect(sharedInstructions).toContain("Shared baseline.");
 	});
 
+	it("round-trips an explicit empty tools list without collapsing it into the default", async () => {
+		const file = path.join(tmp, "WATCHDOG.yml");
+		const explicitNoToolsDoc: WatchdogConfigDoc = {
+			advisors: [{ name: "No Tools", tools: [] }, { name: "Default Tools" }],
+		};
+
+		await saveWatchdogConfigFile(file, explicitNoToolsDoc);
+		const serializedDoc = await loadWatchdogConfigFile(file);
+		expect(serializedDoc).toEqual(explicitNoToolsDoc);
+
+		const { advisors } = await discoverAdvisorConfigs(tmp, tmp);
+		expect(advisors.find(a => a.name === "No Tools")?.tools).toEqual([]);
+		expect(advisors.find(a => a.name === "Default Tools")?.tools).toBeUndefined();
+	});
+
 	it("removes the file when the doc is empty so legacy discovery resumes", async () => {
 		const file = path.join(tmp, "WATCHDOG.yml");
 		await saveWatchdogConfigFile(file, doc);

package/src/advisor/advise-tool.ts

@@ -94,6 +94,9 @@ export function isAdvisorInterruptImmuneTurnActive(opts: {
  * - An interrupting `concern`/`blocker` is normally steered into the agent: into
  *   the live turn while one is streaming, or (when idle) a triggered turn so the
  *   advice is acted on immediately.
+ * - If the primary tail is already a terminal text answer and there is no queued
+ *   work, late interrupting advice is preserved as a visible card instead of
+ *   waking the primary to restate completion.
  * - After a deliberate user interrupt (`autoResumeSuppressed`) the advisor must
  *   not auto-resume the stopped run. While the agent is idle — or still tearing
  *   the interrupted turn down (`aborting`) — the note is preserved as a visible
@@ -103,17 +106,19 @@ export function isAdvisorInterruptImmuneTurnActive(opts: {
  *   run instead strands it (it never reaches the running agent) and the withheld
  *   notes dump as one burst at the next user prompt — the bug this guards.
  * - During the post-interrupt immune-turn window, further `concern`/`blocker`
- *   notes are downgraded to asides; suppression preservation still wins.
+ *   notes are downgraded to asides; preservation still wins.
  */
 export function resolveAdvisorDeliveryChannel(opts: {
 	severity: AdvisorSeverity | undefined;
 	autoResumeSuppressed: boolean;
 	streaming: boolean;
 	aborting: boolean;
+	terminalAnswerNoQueuedWork?: boolean;
 	interruptImmuneTurnActive?: boolean;
 }): AdvisorDeliveryChannel {
 	if (!isInterruptingSeverity(opts.severity)) return "aside";
 	if (opts.autoResumeSuppressed && (opts.aborting || !opts.streaming)) return "preserve";
+	if (opts.terminalAnswerNoQueuedWork && !opts.streaming && !opts.aborting) return "preserve";
 	if (opts.interruptImmuneTurnActive) return "aside";
 	return "steer";
 }

package/src/advisor/config.ts

@@ -12,9 +12,10 @@ import { collectConfigCandidates } from "./watchdog";
  * with an optional `:level` thinking suffix (e.g. `x-ai/grok-code-fast:high`),
  * resolved exactly like any other model override; `tools` is a subset of
  * `BUILTIN_TOOL_NAMES` — any built-in name, including mutating tools such as
- * `edit`/`write`/`bash` (the advisor is a full agent). Omitted or empty falls
- * back to the default `read`/`grep`/`glob` subset. `instructions` is the
- * advisor's specialization, appended to the shared baseline.
+ * `edit`/`write`/`bash` (the advisor is a full agent). Omitted falls back to
+ * the default `read`/`grep`/`glob` subset; an explicit empty list grants no
+ * tools. `instructions` is the advisor's specialization, appended to the shared
+ * baseline.
  */
 export interface AdvisorConfig {
 	name: string;
@@ -65,11 +66,13 @@ const KNOWN_TOOL_NAMES = new Set<string>(BUILTIN_TOOL_NAMES);
 /**
  * Keep only valid tool names from an advisor's `tools` list, dropping unknowns
  * with a warning. The advisor is a full agent, so any built tool may be granted;
- * the runtime further filters to what's actually available this session. An empty
- * result (or no list) means "use the default subset" (read/grep/glob).
+ * the runtime further filters to what's actually available this session.
+ * `undefined` means "use the default subset" (read/grep/glob); only an explicit
+ * raw empty list means "no tools".
  */
 function filterAdvisorTools(tools: string[] | undefined, sourcePath: string): string[] | undefined {
-	if (!tools || tools.length === 0) return undefined;
+	if (tools === undefined) return undefined;
+	if (tools.length === 0) return [];
 	// Normalize legacy aliases (search→grep, find→glob) and dedupe before validating.
 	const filtered = normalizeToolNames(tools).filter(name => {
 		if (KNOWN_TOOL_NAMES.has(name)) return true;
@@ -210,7 +213,7 @@ export async function loadWatchdogConfigFile(filePath: string): Promise<Watchdog
 		advisors: (result.advisors ?? []).map(a => ({
 			name: a.name,
 			model: a.model?.trim() || undefined,
-			tools: a.tools?.length ? [...a.tools] : undefined,
+			tools: a.tools === undefined ? undefined : [...a.tools],
 			instructions: a.instructions?.trim() ? a.instructions : undefined,
 		})),
 	};
@@ -229,7 +232,7 @@ export function serializeWatchdogConfig(doc: WatchdogConfigDoc): string {
 		out.advisors = doc.advisors.map(a => {
 			const entry: AdvisorConfig = { name: a.name };
 			if (a.model?.trim()) entry.model = a.model;
-			if (a.tools?.length) entry.tools = [...a.tools];
+			if (a.tools !== undefined) entry.tools = [...a.tools];
 			if (a.instructions?.trim()) entry.instructions = a.instructions;
 			return entry;
 		});

package/src/advisor/runtime.ts

@@ -65,6 +65,94 @@ export interface AdvisorRuntimeOptions {
 	includeThinking?: boolean;
 }
 
+const ADVISOR_QUARANTINE_PREFIX = "Advisor response quarantined";
+
+/** Signals that an advisor response was discarded before it could become model-visible context. */
+export class AdvisorOutputQuarantinedError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "AdvisorOutputQuarantinedError";
+	}
+}
+
+interface AdvisorOutputHazard {
+	label: string;
+	pattern: RegExp;
+}
+
+const ADVISOR_OUTPUT_ONLY_HAZARDS: readonly AdvisorOutputHazard[] = [
+	{ label: "account-deletion claim", pattern: /\buser\b.{0,80}\b(?:deleted|erased)\b.{0,80}\baccount\b/i },
+	{
+		label: "instruction override",
+		pattern: /\bignore\s+(?:all\s+)?(?:prior|previous|earlier)\s+(?:user\s+)?instructions\b/i,
+	},
+	{ label: "destructive shell command", pattern: /\brm\s+-[a-z]*r[a-z]*f[a-z]*(?:\s|$)/i },
+	{ label: "denial instruction", pattern: /\bdeny\s+(?:this|it|the\s+request)\s+if\s+(?:asked|questioned)\b/i },
+];
+
+/**
+ * Replaces an advisor assistant turn that requested unavailable tools or generated
+ * output-only destructive directives with a sanitized error before dispatch.
+ */
+export function quarantineAdvisorUnsafeOutput(
+	message: AssistantMessage,
+	availableToolNames: ReadonlySet<string>,
+	sourceText = "",
+): string | undefined {
+	const reasons: string[] = [];
+	const unavailableToolNames = new Set<string>();
+	const generatedParts: string[] = [];
+	for (const block of message.content) {
+		if (block.type === "toolCall" && !availableToolNames.has(block.name)) unavailableToolNames.add(block.name);
+		if (block.type === "toolCall" && block.name === "advise" && typeof block.arguments.note === "string") {
+			generatedParts.push(block.arguments.note);
+		}
+		if (block.type === "text") generatedParts.push(block.text);
+	}
+	if (unavailableToolNames.size > 0) {
+		const names = [...unavailableToolNames].sort();
+		const toolLabel = names.length === 1 ? "tool" : "tools";
+		reasons.push(`requested unavailable ${toolLabel} ${names.join(", ")}`);
+	}
+
+	const generatedText = generatedParts.join("\n");
+	if (generatedText) {
+		const labels: string[] = [];
+		for (const hazard of ADVISOR_OUTPUT_ONLY_HAZARDS) {
+			if (hazard.pattern.test(generatedText) && !hazard.pattern.test(sourceText)) labels.push(hazard.label);
+		}
+		if (labels.includes("destructive shell command") || labels.length >= 3) {
+			reasons.push(`generated output-only destructive directives: ${labels.join(", ")}`);
+		}
+	}
+
+	if (reasons.length === 0) return undefined;
+
+	const messageText = `${ADVISOR_QUARANTINE_PREFIX}: ${reasons.join("; ")}`;
+	message.content = [{ type: "text", text: messageText }];
+	message.stopReason = "error";
+	message.stopDetails = undefined;
+	message.providerPayload = undefined;
+	message.errorMessage = messageText;
+	return messageText;
+}
+
+/**
+ * Builds the provenance text used to decide whether hazardous advisor output was
+ * generated by the advisor or came from model-visible primary/tool context.
+ */
+export function buildAdvisorQuarantineSourceText(currentInput: string, messages: readonly AgentMessage[]): string {
+	const parts: string[] = [];
+	if (currentInput) parts.push(currentInput);
+	for (const message of messages) {
+		if (message.role !== "toolResult") continue;
+		for (const block of message.content) {
+			if (block.type === "text") parts.push(block.text);
+		}
+	}
+	return parts.join("\n");
+}
+
 /**
  * Match the stable `Refusal` / `Refusal (…)` message prefix pi-ai emits for a
  * provider classifier refusal (`stop_details.type === "refusal"` mapped in
@@ -384,10 +472,18 @@ export class AdvisorRuntime {
 					// successful empty cycle.
 					const promptError = this.agent.state.error;
 					if (promptError) throw new Error(promptError);
+					const emptyResponseError = getAdvisorEmptyResponseError(
+						this.agent.state.messages.slice(messageSnapshot),
+					);
+					if (emptyResponseError) throw emptyResponseError;
 					success = true;
 					this.#consecutiveFailures = 0;
 					this.#failureNotified = false;
 				} catch (err) {
+					if (err instanceof AdvisorOutputQuarantinedError) {
+						this.#resetAdvisorContext(true, true);
+						continue;
+					}
 					// reset()/dispose() aborts the in-flight prompt; the rejection is the
 					// reset itself, not a transient advisor failure. Drop the stale batch
 					// (reset already cleared #pending and rewound the cursor) instead of
@@ -457,6 +553,37 @@ export class AdvisorRuntime {
 }
 
 type TextualContent = string | readonly (TextContent | ImageContent)[];
+function getAdvisorEmptyResponseError(messages: readonly AgentMessage[]): Error | undefined {
+	let sawAssistant = false;
+	for (const message of messages) {
+		if (message.role !== "assistant") continue;
+		sawAssistant = true;
+		if (message.stopReason !== "stop") return undefined;
+		if (hasAdvisorResponseContent(message)) return undefined;
+	}
+	if (sawAssistant) return new Error("Advisor turn returned an empty stop response without advice");
+	if (messages.length > 0) return new Error("Advisor turn ended without an assistant response");
+	return undefined;
+}
+
+function hasAdvisorResponseContent(message: AssistantMessage): boolean {
+	return message.content.some(block => {
+		switch (block.type) {
+			case "text":
+				return block.text.trim().length > 0;
+			case "thinking":
+				return block.thinking.trim().length > 0;
+			case "redactedThinking":
+				return block.data.length > 0;
+			case "toolCall":
+				return block.name.trim().length > 0;
+			case "fallback":
+				return false;
+			default:
+				return false;
+		}
+	});
+}
 
 function obfuscateTextualContent(obfuscator: SecretObfuscator, content: TextualContent): TextualContent {
 	if (typeof content === "string") return obfuscator.obfuscate(content);

package/src/autolearn/controller.ts

@@ -84,11 +84,11 @@ export class AutoLearnController {
 			return;
 		}
 		if (event.type === "agent_end") {
-			this.#onAgentEnd();
+			this.#onAgentEnd(event);
 		}
 	}
 
-	#onAgentEnd(): void {
+	#onAgentEnd(event: Extract<AgentSessionEvent, { type: "agent_end" }>): void {
 		// Snapshot and reset every turn: the counter describes only the
 		// just-finished turn, so below-threshold, disabled, and plan-mode stops
 		// must not let tool calls accumulate into a later turn.
@@ -107,6 +107,18 @@ export class AutoLearnController {
 			this.#suppressNext = false;
 			return;
 		}
+		// Never nudge a turn that ended in an abort (ESC, cancel, etc.). The
+		// abort flag on the session is unreliable by the time agent_end is
+		// deferred to subscribers; read stopReason from the event messages.
+		for (let i = event.messages.length - 1; i >= 0; i--) {
+			const message = event.messages[i];
+			if (message && typeof message === "object" && "role" in message && message.role === "assistant") {
+				if ("stopReason" in message && message.stopReason === "aborted") {
+					return;
+				}
+				break;
+			}
+		}
 		// Honor a live opt-out: the subscription outlives the setting, so re-check
 		// the current flag rather than trusting install-time state.
 		if (!this.#settings.get("autolearn.enabled")) return;
@@ -148,7 +160,7 @@ export class AutoLearnController {
 					display: false,
 					attribution: "user",
 				},
-				{ deliverAs: "nextTurn", triggerTurn: true },
+				{ deliverAs: "nextTurn", triggerTurn: true, acceptTerminalEmptyStop: true },
 			)
 			.then(started => {
 				if (!started) this.#suppressNext = false;

package/src/cli/args.ts

@@ -14,6 +14,7 @@ import {
 	STRING_SETTERS,
 	STRING_VALUE_FLAGS,
 } from "./flag-tables";
+import { CliUsageError } from "./usage-error";
 
 export type Mode = "text" | "json" | "rpc" | "acp" | "rpc-ui";
 
@@ -299,6 +300,17 @@ export function reportUnrecognizedFlags(
 	return true;
 }
 
+/** Emit a clean CLI usage error without an internal stack trace. */
+export function reportCliUsageError(
+	error: unknown,
+	write: (text: string) => void = text => process.stderr.write(text),
+): boolean {
+	if (!(error instanceof CliUsageError)) return false;
+	write(`${chalk.red(`Error: ${error.message}`)}\n`);
+	write(`Run \`${APP_NAME} --help\` for available flags.\n`);
+	return true;
+}
+
 export function getExtraHelpText(): string {
 	return `${chalk.bold("Environment Variables:")}
   ${chalk.dim("# Core Providers")}

package/src/cli/flag-tables.ts

@@ -32,6 +32,7 @@
 
 import type { ConfiguredThinkingLevel } from "../thinking";
 import type { Args } from "./args";
+import { CliUsageError } from "./usage-error";
 
 /**
  * Runtime dependencies injected into setters that need to validate input or
@@ -85,6 +86,24 @@ const setResume: OptionalSetter = (result, value) => {
 	result.resume = value !== undefined ? value : true;
 };
 
+const MAX_TIME_DURATION_RE = /^(\d+(?:\.\d+)?)([smh])$/;
+
+function maxTimeMultiplier(unit: string | undefined): number {
+	if (unit === "h") return 3600;
+	if (unit === "m") return 60;
+	return 1;
+}
+
+function parseMaxTimeSeconds(value: string): number {
+	const trimmed = value.trim();
+	const duration = MAX_TIME_DURATION_RE.exec(trimmed);
+	const seconds = duration ? Number(duration[1]) * maxTimeMultiplier(duration[2]) : Number(trimmed);
+	if (Number.isFinite(seconds) && seconds > 0) return seconds;
+	throw new CliUsageError(
+		`Invalid --max-time value: ${JSON.stringify(value)}. Expected a positive number of seconds or duration like "5s", "10m", "1h".`,
+	);
+}
+
 /**
  * Setters for flags with string values. Most built-ins consume the next argv
  * token even when it starts with `-`; flags listed in
@@ -121,13 +140,8 @@ export const STRING_SETTERS: Record<string, StringSetter> = {
 	"--plan": (result, value) => {
 		result.plan = value;
 	},
-	"--max-time": (result, value, deps) => {
-		const seconds = Number(value);
-		if (Number.isFinite(seconds) && seconds > 0) {
-			result.maxTime = seconds;
-		} else {
-			deps.logger.warn("Invalid seconds passed to --max-time", { value });
-		}
+	"--max-time": (result, value) => {
+		result.maxTime = parseMaxTimeSeconds(value);
 	},
 	"--api-key": (result, value) => {
 		result.apiKey = value;