@oh-my-pi/pi-coding-agent 15.12.3 → 15.13.0

package/src/async/job-manager.ts

@@ -6,6 +6,27 @@ const DELIVERY_RETRY_JITTER_MS = 200;
 const DEFAULT_RETENTION_MS = 5 * 60 * 1000;
 const DEFAULT_MAX_RUNNING_JOBS = 15;
 
+/**
+ * Adaptive ("smart") `job` poll-wait ladder (ms). A tight poll loop climbs
+ * these rungs so each immediate re-poll backs off and stops spending turns on
+ * "still running" frames; the floor (first rung) is the shortest wait and the
+ * top rung is the longest a smart poll will ever block. Only used when
+ * `async.pollWaitDuration` is set to `smart`; fixed durations wait verbatim.
+ */
+const POLL_WAIT_LADDER_MS = [5_000, 10_000, 30_000, 60_000, 300_000] as const;
+/**
+ * Going at least this long between poll calls means the agent stepped out of
+ * the poll loop to do real work — the next poll drops back to the ladder floor.
+ */
+const POLL_ESCALATION_RESET_MS = 60_000;
+
+interface PollEscalationState {
+	/** Index into POLL_WAIT_LADDER_MS used for the most recent poll wait. */
+	level: number;
+	/** Timestamp (ms) when the most recent poll wait returned. */
+	lastPollEndAt: number;
+}
+
 export interface AsyncJob {
 	id: string;
 	type: "bash" | "task";
@@ -96,6 +117,7 @@ export class AsyncJobManager {
 	readonly #suppressedDeliveries = new Set<string>();
 	readonly #watchedJobs = new Set<string>();
 	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
+	readonly #pollEscalation = new Map<string | undefined, PollEscalationState>();
 	readonly #onJobComplete: AsyncJobManagerOptions["onJobComplete"];
 	readonly #maxRunningJobs: number;
 	readonly #retentionMs: number;
@@ -295,6 +317,32 @@ export class AsyncJobManager {
 		return removed;
 	}
 
+	/**
+	 * Compute the next adaptive ("smart") wait (ms) for a blocking `job` poll by
+	 * the given owner. Consecutive polls — those starting within
+	 * POLL_ESCALATION_RESET_MS of the previous poll returning — climb
+	 * POLL_WAIT_LADDER_MS so a tight wait loop backs off; a longer gap means the
+	 * agent left to do real work, so the wait resets to the floor. Pair each call
+	 * with `recordPollWaitEnd()` once the wait returns.
+	 */
+	nextPollWaitMs(ownerId: string | undefined, now: number = Date.now()): number {
+		const prev = this.#pollEscalation.get(ownerId);
+		const reset = !prev || now - prev.lastPollEndAt >= POLL_ESCALATION_RESET_MS;
+		const level = reset ? 0 : Math.min(prev.level + 1, POLL_WAIT_LADDER_MS.length - 1);
+		this.#pollEscalation.set(ownerId, { level, lastPollEndAt: prev?.lastPollEndAt ?? now });
+		return POLL_WAIT_LADDER_MS[level];
+	}
+
+	/**
+	 * Mark a blocking poll wait as finished so the idle-reset window is measured
+	 * from now. Polling again before POLL_ESCALATION_RESET_MS elapses keeps
+	 * climbing the ladder; waiting longer resets it to the floor.
+	 */
+	recordPollWaitEnd(ownerId: string | undefined, now: number = Date.now()): void {
+		const prev = this.#pollEscalation.get(ownerId);
+		this.#pollEscalation.set(ownerId, { level: prev?.level ?? 0, lastPollEndAt: now });
+	}
+
 	acknowledgeDeliveries(jobIds: string[]): number {
 		const uniqueJobIds = Array.from(new Set(jobIds.map(id => id.trim()).filter(id => id.length > 0)));
 		if (uniqueJobIds.length === 0) return 0;
@@ -405,6 +453,7 @@ export class AsyncJobManager {
 		this.#inFlightDeliveries.length = 0;
 		this.#suppressedDeliveries.clear();
 		this.#watchedJobs.clear();
+		this.#pollEscalation.clear();
 		return drained;
 	}
 

package/src/autolearn/controller.ts

@@ -0,0 +1,139 @@
+/**
+ * Auto-learn session controller (experimental).
+ *
+ * Subscribes to the session event stream and, after a substantive turn,
+ * nudges the agent to capture reusable lessons. Default posture is passive
+ * (a hidden reminder rides the next real turn); with `autolearn.autoContinue`
+ * it auto-runs exactly one synthetic capture turn at stop.
+ *
+ * Installed once per top-level session (taskDepth 0). The subscription lives
+ * for the session's lifetime — `newSession` resets the session in place
+ * without re-running startup — so the controller needs no disposal.
+ */
+import { logger } from "@oh-my-pi/pi-utils";
+import type { Settings } from "../config/settings";
+import autolearnGuidance from "../prompts/system/autolearn-guidance.md" with { type: "text" };
+import autolearnGuidanceLearn from "../prompts/system/autolearn-guidance-learn.md" with { type: "text" };
+import autolearnNudge from "../prompts/system/autolearn-nudge.md" with { type: "text" };
+import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+
+const AUTOLEARN_NUDGE = autolearnNudge.trim();
+const DEFAULT_MIN_TOOL_CALLS = 5;
+
+/**
+ * Build the standing auto-learn guidance for the system prompt from the tools
+ * actually present in the active set, or null when `manage_skill` is absent.
+ *
+ * Driven by tool presence rather than live settings: the `learn`/`manage_skill`
+ * registry is built ONCE at session start (and only for top-level sessions), so
+ * keying the guidance on `autolearn.enabled` would let a mid-session enable — or
+ * a subagent that filtered the tools out — inject guidance pointing at tools the
+ * session never built. The `learn` addendum is included only when the `learn`
+ * tool is present (it requires a memory backend).
+ */
+export function buildAutoLearnInstructions(available: { manageSkill: boolean; learn: boolean }): string | null {
+	if (!available.manageSkill) return null;
+	const parts = [autolearnGuidance.trim()];
+	if (available.learn) parts.push(autolearnGuidanceLearn.trim());
+	return parts.join("\n\n");
+}
+
+export interface AutoLearnControllerOptions {
+	session: AgentSession;
+	settings: Settings;
+}
+
+export class AutoLearnController {
+	readonly #session: AgentSession;
+	readonly #settings: Settings;
+	#toolCalls = 0;
+	/**
+	 * Whether the in-flight turn BEGAN while goal mode was active. Captured at
+	 * agent_start because a `goal` tool can complete or drop the goal mid-turn,
+	 * clearing the live flag before agent_end — so the end-of-turn state alone
+	 * would let a goal-continuation turn slip through and get nudged.
+	 */
+	#turnStartedInGoalMode = false;
+	/** Swallow the agent_end produced by an auto-run capture turn so it cannot re-trigger. */
+	#suppressNext = false;
+
+	constructor(options: AutoLearnControllerOptions) {
+		this.#session = options.session;
+		this.#settings = options.settings;
+		// The listener closure captures `this`, so the session's listener array
+		// keeps the controller alive — no stored unsubscribe needed.
+		this.#session.subscribe(event => this.#onEvent(event));
+	}
+
+	#onEvent(event: AgentSessionEvent): void {
+		if (event.type === "agent_start") {
+			// Capture goal-mode state at the turn boundary, before any tool runs.
+			this.#turnStartedInGoalMode = this.#session.getGoalModeState()?.enabled === true;
+			return;
+		}
+		if (event.type === "tool_execution_end") {
+			this.#toolCalls++;
+			return;
+		}
+		if (event.type === "agent_end") {
+			this.#onAgentEnd();
+		}
+	}
+
+	#onAgentEnd(): 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.
+		const toolCalls = this.#toolCalls;
+		this.#toolCalls = 0;
+		// Snapshot the turn-start goal flag alongside the counter so a turn that
+		// observed no agent_start can never inherit a stale value.
+		const startedInGoalMode = this.#turnStartedInGoalMode;
+		this.#turnStartedInGoalMode = false;
+
+		if (this.#suppressNext) {
+			this.#suppressNext = false;
+			return;
+		}
+		// 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;
+		const minToolCalls = this.#settings.get("autolearn.minToolCalls") ?? DEFAULT_MIN_TOOL_CALLS;
+		if (toolCalls < minToolCalls) return;
+		// Never interrupt plan-mode review.
+		if (this.#session.getPlanModeState()?.enabled) return;
+		// Never divert a goal loop. Skip when the turn STARTED in goal mode — a
+		// `goal` tool may have completed/dropped the goal before this stop — or is
+		// still in it: a passive nudge would ride the goal continuation, and
+		// auto-continue would compete with it.
+		if (startedInGoalMode || this.#session.getGoalModeState()?.enabled) return;
+
+		// Auto-run a capture turn only when explicitly enabled; otherwise the
+		// hidden reminder rides the next real turn passively.
+		const autoContinue = this.#settings.get("autolearn.autoContinue") === true;
+		// Arm suppression synchronously: the synthetic capture turn's agent_end
+		// fires inside sendCustomMessage (before it resolves), so the flag must be
+		// set before then. Disarm when no turn actually started — a deferred/queued
+		// dispatch or a failed send produces no agent_end, and a latched flag would
+		// otherwise swallow the next real stop.
+		if (autoContinue) this.#suppressNext = true;
+
+		this.#session
+			.sendCustomMessage(
+				{
+					customType: "autolearn-nudge",
+					content: AUTOLEARN_NUDGE,
+					display: false,
+					attribution: "user",
+				},
+				{ deliverAs: "nextTurn", triggerTurn: autoContinue },
+			)
+			.then(started => {
+				if (!started) this.#suppressNext = false;
+			})
+			.catch(err => {
+				this.#suppressNext = false;
+				logger.warn("auto-learn nudge delivery failed", { err });
+			});
+	}
+}

package/src/autolearn/managed-skills.ts

@@ -0,0 +1,257 @@
+/**
+ * Managed-skills primitives for the experimental auto-learn feature.
+ *
+ * Managed skills are auto-generated/enhanced `SKILL.md` files kept in an
+ * isolated directory (`~/.omp/agent/managed-skills`) separate from
+ * user-authored skills (`~/.omp/agent/skills`). They are discovered and
+ * surfaced like normal skills, but every write here is confined to
+ * `getManagedSkillsDir()` — auto-management can never touch authored skills.
+ */
+import { constants as fsConstants, type Stats } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import { YAML } from "bun";
+import { SOURCE_PATHS } from "../discovery/helpers";
+
+/** Provider id stamped on discovered managed skills (distinguishes them from authored). */
+export const MANAGED_SKILLS_PROVIDER_ID = "omp-managed";
+
+/** Hard cap on a managed SKILL.md body to keep generated skills bounded. */
+export const MAX_MANAGED_SKILL_BYTES = 64_000;
+
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** Resolve the isolated managed-skills directory (`~/.omp/agent/managed-skills`). */
+export function getManagedSkillsDir(home: string = os.homedir()): string {
+	return path.join(home, SOURCE_PATHS.native.userAgent, "managed-skills");
+}
+
+/**
+ * Validate + normalize a managed-skill name. Throws on anything outside the
+ * strict allowlist so a bad name can never escape `getManagedSkillsDir()`
+ * (blocks `..`, slashes, empty, and uppercase).
+ */
+export function sanitizeSkillName(raw: string): string {
+	const name = raw.trim().toLowerCase();
+	if (!SKILL_NAME_PATTERN.test(name)) {
+		throw new Error(
+			`Invalid skill name "${raw}". Use lowercase letters, digits, and hyphens (1-64 chars, starting with a letter or digit).`,
+		);
+	}
+	return name;
+}
+
+/**
+ * Whether `name` is a safe managed-skill name (the exact post-sanitize shape).
+ * Used to validate names read from disk at discovery time — a managed
+ * `SKILL.md` whose `frontmatter.name` was not produced by `sanitizeSkillName`
+ * (e.g. hand-placed) must not render unescaped into the system prompt.
+ */
+export function isValidManagedSkillName(name: string): boolean {
+	return SKILL_NAME_PATTERN.test(name);
+}
+
+/**
+ * Neutralize a machine-generated managed-skill description so it cannot break
+ * out of the system prompt's `<skills>` listing. Managed descriptions are
+ * generated from prior task content and persist across sessions, so this is a
+ * trust boundary: strip control/format chars, angle brackets (`<system-directive>`
+ * / `</skills>`), and Markdown fence delimiters (backticks, `~~~`), then collapse
+ * to a single line. Applied on BOTH write and read so existing files are safe too.
+ */
+export function sanitizeManagedDescription(raw: string): string {
+	return raw
+		.replace(/[\p{Cc}\p{Cf}]/gu, " ")
+		.replace(/[<>`]/g, "")
+		.replace(/~{2,}/g, "~")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/**
+ * Serialize the minimal `name`/`description` frontmatter block via the repo's
+ * YAML helper (round-trips through `parseFrontmatter`).
+ */
+export function toSkillFrontmatter(name: string, description: string): string {
+	const frontmatter = YAML.stringify(
+		{ name, description: sanitizeManagedDescription(description) },
+		null,
+		2,
+	).trimEnd();
+	return `---\n${frontmatter}\n---\n`;
+}
+
+export interface WriteManagedSkillInput {
+	action: "create" | "update";
+	name: string;
+	description: string;
+	body: string;
+}
+
+/**
+ * Serialize create/update/delete on the same skill name. Both tools are
+ * non-exclusive, so a parallel tool batch in one turn can run two mutations on
+ * the same skill at once (e.g. an update observing the file mid-delete). This
+ * per-name promise chain runs same-skill mutations in submission order while
+ * different names still proceed in parallel. In-process only; cross-process
+ * races are out of scope.
+ */
+const skillMutationChains = new Map<string, Promise<unknown>>();
+function serializeSkillMutation<T>(name: string, op: () => Promise<T>): Promise<T> {
+	const prev = skillMutationChains.get(name) ?? Promise.resolve();
+	const run = prev.then(op, op);
+	const guarded = run.catch(() => {});
+	skillMutationChains.set(name, guarded);
+	void guarded.finally(() => {
+		if (skillMutationChains.get(name) === guarded) skillMutationChains.delete(name);
+	});
+	return run;
+}
+
+/**
+ * Reject when the managed-skills root itself is a symlink. lstat on a child
+ * follows intermediate components, so a symlinked root would let an otherwise
+ * valid name write/delete outside the isolated directory (e.g. onto authored
+ * skills). Checked before composing any child path.
+ */
+async function assertManagedRootSafe(): Promise<void> {
+	const rootStat = await fs.lstat(getManagedSkillsDir()).catch(err => {
+		if (isEnoent(err)) return null;
+		throw err;
+	});
+	if (rootStat?.isSymbolicLink()) {
+		throw new Error("The managed-skills root is a symlink; refusing to operate outside the managed directory.");
+	}
+}
+
+const UPDATE_FILE_OPEN_FLAGS = fsConstants.O_WRONLY | fsConstants.O_NOFOLLOW;
+
+function assertManagedSkillFileSafeForUpdate(name: string, fileStat: Stats): void {
+	if (!fileStat.isFile()) {
+		throw new Error(`Managed skill "${name}" SKILL.md is not a regular file; refusing to overwrite it.`);
+	}
+	if (fileStat.nlink > 1) {
+		throw new Error(
+			`Managed skill "${name}" SKILL.md has ${fileStat.nlink} hard links; refusing to overwrite a file that may be user-authored elsewhere.`,
+		);
+	}
+}
+
+async function openManagedSkillFileForUpdate(name: string, file: string) {
+	try {
+		return await fs.open(file, UPDATE_FILE_OPEN_FLAGS);
+	} catch (err) {
+		if ((err as { code?: string }).code === "ELOOP") {
+			throw new Error(`Managed skill "${name}" SKILL.md is a symlink; refusing to overwrite it.`);
+		}
+		throw err;
+	}
+}
+
+/** Create or update a managed `SKILL.md`. Returns the resolved file path. */
+export async function writeManagedSkill(input: WriteManagedSkillInput): Promise<{ path: string }> {
+	const name = sanitizeSkillName(input.name);
+	const description = sanitizeManagedDescription(input.description);
+	const body = input.body.trim();
+	// Reject empty content: an all-whitespace/control description sanitizes to ""
+	// and the `requireDescription` discovery scan then silently drops the skill,
+	// so the tool would report success for a skill that never appears.
+	if (!description) {
+		throw new Error(`Managed skill "${name}" needs a non-empty description.`);
+	}
+	if (!body) {
+		throw new Error(`Managed skill "${name}" needs a non-empty body.`);
+	}
+	const content = `${toSkillFrontmatter(name, description)}\n${body}\n`;
+	// Cap the UTF-8 byte size of the FINAL file (body + description + frontmatter),
+	// not the UTF-16 code-unit length of the body alone.
+	const bytes = Buffer.byteLength(content, "utf8");
+	if (bytes > MAX_MANAGED_SKILL_BYTES) {
+		throw new Error(
+			`Managed skill is ${bytes} bytes; the limit is ${MAX_MANAGED_SKILL_BYTES}. Trim the body or description.`,
+		);
+	}
+	return serializeSkillMutation(name, async () => {
+		await assertManagedRootSafe();
+		const dir = path.join(getManagedSkillsDir(), name);
+		const file = path.join(dir, "SKILL.md");
+		// Reject a symlinked skill directory: an intermediate symlink would let the
+		// write escape the isolated managed root. lstat does not follow the final
+		// component, so a symlinked `dir` is caught here.
+		const dirStat = await fs.lstat(dir).catch(err => {
+			if (isEnoent(err)) return null;
+			throw err;
+		});
+		if (dirStat?.isSymbolicLink()) {
+			throw new Error(
+				`Managed skill "${name}" resolves through a symlink; refusing to write outside the managed directory.`,
+			);
+		}
+		if (input.action === "create") {
+			await fs.mkdir(dir, { recursive: true });
+			// O_CREAT|O_EXCL ("wx"): atomic create that fails if the file already
+			// exists (closing the check-then-write race) and refuses a symlinked SKILL.md.
+			try {
+				await fs.writeFile(file, content, { flag: "wx" });
+			} catch (err) {
+				if ((err as { code?: string }).code === "EEXIST") {
+					throw new Error(`Managed skill "${name}" already exists. Use action "update" to change it.`);
+				}
+				throw err;
+			}
+			return { path: file };
+		}
+		// update: the file must already exist, be a plain managed file, and must
+		// not share an inode with a user-authored file via hard link. Open the
+		// checked file handle before truncating so a path swap after lstat cannot
+		// redirect the write into a symlink or newly hard-linked target.
+		const fileStat = await fs.lstat(file).catch(err => {
+			if (isEnoent(err)) return null;
+			throw err;
+		});
+		if (fileStat === null) {
+			throw new Error(`Managed skill "${name}" does not exist. Use action "create" to add it.`);
+		}
+		if (fileStat.isSymbolicLink()) {
+			throw new Error(`Managed skill "${name}" SKILL.md is a symlink; refusing to overwrite it.`);
+		}
+		assertManagedSkillFileSafeForUpdate(name, fileStat);
+		const handle = await openManagedSkillFileForUpdate(name, file);
+		try {
+			const openStat = await handle.stat();
+			assertManagedSkillFileSafeForUpdate(name, openStat);
+			await handle.truncate(0);
+			await handle.writeFile(content);
+		} finally {
+			await handle.close();
+		}
+		return { path: file };
+	});
+}
+
+/** Delete a managed skill directory. Throws when it does not exist. */
+export async function deleteManagedSkill(name: string): Promise<void> {
+	const safe = sanitizeSkillName(name);
+	await serializeSkillMutation(safe, async () => {
+		await assertManagedRootSafe();
+		const dir = path.join(getManagedSkillsDir(), safe);
+		// Refuse to follow a symlinked skill directory (rm would delete the target).
+		const dirStat = await fs.lstat(dir).catch(err => {
+			if (isEnoent(err)) return null;
+			throw err;
+		});
+		if (dirStat?.isSymbolicLink()) {
+			throw new Error(`Managed skill "${safe}" is a symlink; refusing to delete outside the managed directory.`);
+		}
+		try {
+			await fs.rm(dir, { recursive: true });
+		} catch (err) {
+			if (isEnoent(err)) {
+				throw new Error(`Managed skill "${safe}" does not exist.`);
+			}
+			throw err;
+		}
+	});
+}

package/src/autoresearch/state.ts

@@ -1,4 +1,4 @@
-import type { SessionEntry } from "../session/session-manager";
+import type { SessionEntry } from "../session/session-entries";
 import { inferMetricUnitFromName, isBetter } from "./helpers";
 import type { RunRow, SessionRow } from "./storage";
 import type {

package/src/autoresearch/storage.ts

@@ -194,7 +194,6 @@ const SCHEMA_VERSION = 1;
 const SCHEMA_SQL = `
 PRAGMA journal_mode=WAL;
 PRAGMA synchronous=NORMAL;
-PRAGMA busy_timeout=5000;
 PRAGMA foreign_keys=ON;
 
 CREATE TABLE IF NOT EXISTS sessions (
@@ -263,6 +262,8 @@ export class AutoresearchStorage {
 		this.#projectDir = projectDir;
 		fs.mkdirSync(path.dirname(dbPath), { recursive: true });
 		this.#db = new Database(dbPath);
+		// Install the busy handler BEFORE any lock-taking statement. See #2421.
+		this.#db.run("PRAGMA busy_timeout = 5000");
 		this.#db.run(SCHEMA_SQL);
 		const versionRow = this.#db.query("PRAGMA user_version").get() as { user_version: number } | null;
 		const currentVersion = versionRow?.user_version ?? 0;

package/src/autoresearch/tools/init-experiment.ts

@@ -1,7 +1,7 @@
 import * as path from "node:path";
 
 import { Text } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolDefinition } from "../../extensibility/extensions";
 import type { Theme } from "../../modes/theme/theme";
 import { replaceTabs, truncateToWidth } from "../../tools/render-utils";

package/src/autoresearch/tools/log-experiment.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 
 import { Text } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolDefinition } from "../../extensibility/extensions";
 import type { Theme } from "../../modes/theme/theme";
 import { replaceTabs, truncateToWidth } from "../../tools/render-utils";

package/src/autoresearch/tools/run-experiment.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { Text } from "@oh-my-pi/pi-tui";
 import { formatBytes } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import { executeBash } from "../../exec/bash-executor";
 import type { ToolDefinition } from "../../extensibility/extensions";
 import type { Theme } from "../../modes/theme/theme";

package/src/autoresearch/tools/update-notes.ts

@@ -1,5 +1,5 @@
 import { Text } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolDefinition } from "../../extensibility/extensions";
 import type { Theme } from "../../modes/theme/theme";
 import { replaceTabs, truncateToWidth } from "../../tools/render-utils";

package/src/autoresearch/types.ts

@@ -1,6 +1,6 @@
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import type { ExtensionAPI, ExtensionContext } from "../extensibility/extensions";
-import type { SessionEntry } from "../session/session-manager";
+import type { SessionEntry } from "../session/session-entries";
 import type { TruncationResult } from "../session/streaming-output";
 
 export type MetricDirection = "lower" | "higher";

package/src/cli/args.ts

@@ -48,14 +48,24 @@ export interface Args {
 	noSkills?: boolean;
 	skills?: string[];
 	noRules?: boolean;
-	listModels?: string | true;
 	noTitle?: boolean;
 	autoApprove?: boolean;
 	approvalMode?: "always-ask" | "write" | "yolo";
 	messages: string[];
 	fileArgs: string[];
-	/** Unknown flags (potentially extension flags) - map of flag name to value */
+	/** Extension-registered flags this parse recognized — name to value. */
 	unknownFlags: Map<string, boolean | string>;
+	/**
+	 * `--`/`-` prefixed tokens this parse could not match against any built-in
+	 * or {@link extensionFlags} entry. The startup parse runs *before*
+	 * extensions load, so it always lists every extension-registered flag here;
+	 * the post-extension reparse in {@link applyExtensionFlags} clears those
+	 * once the real flag set is known. Anything still present after that
+	 * reparse is a genuine typo or stale flag and {@link reportUnrecognizedFlags}
+	 * surfaces it as a hard error so the agent does not silently start a
+	 * session with the misparsed positionals as a prompt (issue #2459).
+	 */
+	unrecognizedFlags: string[];
 }
 
 export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
@@ -68,12 +78,23 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 		messages: [],
 		fileArgs: [],
 		unknownFlags: new Map(),
+		unrecognizedFlags: [],
 	};
 
+	let sawSeparator = false;
 	for (let i = 0; i < args.length; i++) {
 		let arg = args[i];
 		const flagIndex = i;
 
+		// POSIX positional separator: once `--` lands, every remaining token is
+		// a positional regardless of shape. Without this, a flag-looking message
+		// (`omp -p -- --explain-this`) would be re-validated by the loop below
+		// and rejected by the unknown-flag guard (#2461 review).
+		if (sawSeparator) {
+			result.messages.push(arg);
+			continue;
+		}
+
 		// Support --flag=value syntax (e.g. --tools=ask,read). The value is
 		// spliced in as the next token so value-consuming flags pick it up via
 		// `args[++i]`; a non-consuming flag (e.g. a boolean) leaves it behind and
@@ -228,17 +249,24 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 		} else if (arg === "--skills" && i + 1 < args.length) {
 			// Comma-separated glob patterns for skill filtering
 			result.skills = args[++i].split(",").map(s => s.trim());
-		} else if (arg === "--list-models") {
-			// Check if next arg is a search pattern (not a flag or file arg)
-			if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i + 1].startsWith("@")) {
-				result.listModels = args[++i];
-			} else {
-				result.listModels = true;
-			}
 		} else if (arg.startsWith("@")) {
 			result.fileArgs.push(arg.slice(1)); // Remove @ prefix
-		} else if (!arg.startsWith("-")) {
+		} else if (!arg.startsWith("-") || arg === "-") {
+			// Plain positional or lone `-` (stdin marker) — pass through as a
+			// message rather than flagging it.
 			result.messages.push(arg);
+		} else if (arg === "--") {
+			// POSIX positional separator: drop the token and switch the loop
+			// into "everything from here is a positional" mode. The guard at
+			// the top of the loop body handles the remaining tokens.
+			sawSeparator = true;
+		} else {
+			// Flag-shaped (`-x`, `--name`) but unrecognized at this parse. Record
+			// it so the post-extension reparse can decide whether to surface it
+			// as a hard error. `--flag=value` already split `value` into the next
+			// slot; the standard "drop unconsumed equals value" guard below
+			// removes it so it does not leak into messages (issue #2459).
+			result.unrecognizedFlags.push(arg);
 		}
 		// Drop an unconsumed `--flag=value` value (e.g. a boolean flag): when no
 		// branch advanced past the spliced token, remove it so it does not fall
@@ -251,6 +279,24 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 	return result;
 }
 
+/**
+ * Emit a stderr error listing the unrecognized flags and return `true` when
+ * there were any. Caller is expected to exit with a non-zero status. Splitting
+ * the print from the exit keeps the helper unit-testable without forking a
+ * process (issue #2459).
+ */
+export function reportUnrecognizedFlags(
+	args: Pick<Args, "unrecognizedFlags">,
+	write: (text: string) => void = text => process.stderr.write(text),
+): boolean {
+	if (args.unrecognizedFlags.length === 0) return false;
+	const flags = args.unrecognizedFlags;
+	const plural = flags.length === 1 ? "" : "s";
+	write(`${chalk.red(`Error: unknown flag${plural}: ${flags.join(", ")}`)}\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/auth-gateway-cli.ts

@@ -409,7 +409,7 @@ function pickProbeCandidates(provider: string): Model<Api>[] {
 		if (!model.input.includes("text")) return false;
 		const totalCost = (model.cost?.input ?? 0) + (model.cost?.output ?? 0);
 		if (!Number.isFinite(totalCost) || totalCost < 0) return false;
-		if (model.maxTokens <= 0) return false;
+		if (model.maxTokens !== null && model.maxTokens <= 0) return false;
 		return true;
 	});
 	candidates.sort((a, b) => a.cost.input + a.cost.output - (b.cost.input + b.cost.output) || a.id.localeCompare(b.id));

package/src/cli/bench-cli.ts

@@ -180,7 +180,7 @@ async function runBenchRequest(
 			apiKey: options.apiKey,
 			sessionId: options.sessionId,
 			maxTokens:
-				Number.isFinite(model.maxTokens) && model.maxTokens > 0
+				model.maxTokens !== null && Number.isFinite(model.maxTokens) && model.maxTokens > 0
 					? Math.min(options.maxTokens, model.maxTokens)
 					: options.maxTokens,
 			reasoning: options.reasoning,