@oh-my-pi/pi-coding-agent 15.10.10 → 15.10.12

package/src/session/streaming-output.ts

@@ -11,6 +11,16 @@ export const DEFAULT_MAX_LINES = 3000;
 export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
 export const DEFAULT_MAX_COLUMN = 512; // Max chars per grep match line
 
+/**
+ * Default artifact-on-disk cap for {@link OutputSink}.
+ *
+ * `0` means unbounded: by default, `artifact://<id>` references preserve the
+ * complete raw stream instead of a capped head/tail sample.
+ */
+export const ARTIFACT_DEFAULT_MAX_BYTES = 0;
+/** Default head budget; the remainder becomes the rolling tail window. */
+export const ARTIFACT_DEFAULT_HEAD_BYTES = 3 * 1024 * 1024; // 3 MiB
+
 const NL = "\n";
 const ELLIPSIS = "…";
 
@@ -58,6 +68,20 @@ export interface OutputSinkOptions {
 	onChunk?: (chunk: string) => void;
 	/** Minimum ms between onChunk calls. 0 = every chunk (default). */
 	chunkThrottleMs?: number;
+	/**
+	 * Optional cap on bytes written to the artifact-on-disk file. When the cap
+	 * is hit, the head window is preserved verbatim and subsequent output feeds
+	 * a rolling tail window; on close, the sink writes a single
+	 * `[ARTIFACT TRUNCATED: …]` notice between them. Default
+	 * {@link ARTIFACT_DEFAULT_MAX_BYTES} (unbounded).
+	 */
+	artifactMaxBytes?: number;
+	/**
+	 * Bytes reserved for the head window of the capped artifact file. The
+	 * tail window receives `artifactMaxBytes - artifactHeadBytes`. Default
+	 * {@link ARTIFACT_DEFAULT_HEAD_BYTES}; clamped to `[0, artifactMaxBytes]`.
+	 */
+	artifactHeadBytes?: number;
 }
 
 export interface TruncationResult {
@@ -650,6 +674,7 @@ export class OutputSink {
 	#sawData = false;
 	#truncated = false;
 	#lastChunkTime = 0;
+	#pendingChunk = "";
 
 	// Per-line column cap streaming state (persists across `push` calls so a
 	// long line split across chunks still trips the same trigger).
@@ -675,6 +700,21 @@ export class OutputSink {
 	readonly #chunkThrottleMs: number;
 	readonly #maxColumns: number;
 
+	// Optional artifact-on-disk cap. When `#artifactMaxBytes > 0` the file sink
+	// owns a head budget + a rolling tail buffer; once the head is closed,
+	// subsequent chunks are diverted into `#artifactTailRing` (bounded by
+	// `#artifactTailBudget`). On `dump()` the tail is flushed back to the sink
+	// behind a `[ARTIFACT TRUNCATED: …]` notice. The default cap is disabled so
+	// advertised `artifact://<id>` captures are lossless.
+	readonly #artifactMaxBytes: number;
+	readonly #artifactHeadBudget: number;
+	readonly #artifactTailBudget: number;
+	#artifactHeadBytesWritten = 0;
+	#artifactHeadClosed = false;
+	#artifactTailRing = "";
+	#artifactTailRingBytes = 0;
+	#artifactTailIncomingBytes = 0;
+
 	constructor(options?: OutputSinkOptions) {
 		const {
 			artifactPath,
@@ -684,6 +724,8 @@ export class OutputSink {
 			maxColumns = 0,
 			onChunk,
 			chunkThrottleMs = 0,
+			artifactMaxBytes = ARTIFACT_DEFAULT_MAX_BYTES,
+			artifactHeadBytes = ARTIFACT_DEFAULT_HEAD_BYTES,
 		} = options ?? {};
 		this.#artifactPath = artifactPath;
 		this.#artifactId = artifactId;
@@ -692,6 +734,9 @@ export class OutputSink {
 		this.#maxColumns = Math.max(0, maxColumns);
 		this.#onChunk = onChunk;
 		this.#chunkThrottleMs = chunkThrottleMs;
+		this.#artifactMaxBytes = Math.max(0, artifactMaxBytes);
+		this.#artifactHeadBudget = Math.max(0, Math.min(artifactHeadBytes, this.#artifactMaxBytes));
+		this.#artifactTailBudget = Math.max(0, this.#artifactMaxBytes - this.#artifactHeadBudget);
 	}
 
 	/**
@@ -701,14 +746,20 @@ export class OutputSink {
 	push(chunk: string): void {
 		chunk = sanitizeWithOptionalSixelPassthrough(chunk, sanitizeText);
 
-		// Throttled onChunk: only call the callback when enough time has passed.
+		// Throttled onChunk: coalesce chunks arriving inside the throttle window
+		// and flush the buffered concatenation on the next eligible tick (plus a
+		// final flush in dump()) so the preview never has silent gaps.
 		// Live preview gets the raw (pre-cap) chunk so the TUI never lags behind
 		// what reached the sink — the column cap is for the persisted LLM view.
 		if (this.#onChunk) {
 			const now = Date.now();
 			if (now - this.#lastChunkTime >= this.#chunkThrottleMs) {
 				this.#lastChunkTime = now;
-				this.#onChunk(chunk);
+				const merged = this.#pendingChunk + chunk;
+				this.#pendingChunk = "";
+				this.#onChunk(merged);
+			} else {
+				this.#pendingChunk += chunk;
 			}
 		}
 
@@ -858,14 +909,18 @@ export class OutputSink {
 	/**
 	 * Write a chunk to the artifact file. Handles the async file sink creation
 	 * by queuing writes until the sink is ready, then draining synchronously.
+	 * Once the sink is up, every byte flows through {@link #emitToSink} which
+	 * owns the head + tail cap so artifacts cannot grow beyond
+	 * `#artifactMaxBytes` on disk.
 	 */
 	#writeToFile(chunk: string): void {
 		if (this.#fileReady && this.#file) {
-			// Fast path: file sink exists, write synchronously
-			this.#file.sink.write(chunk);
+			this.#emitToSink(chunk);
 			return;
 		}
-		// File sink not yet created — queue this chunk and kick off creation
+		// File sink not yet created — queue this chunk and kick off creation.
+		// The queue is bounded only by how many chunks arrive before the open
+		// resolves (typically <2). The cap is enforced on drain.
 		if (!this.#pendingFileWrites) {
 			this.#pendingFileWrites = [chunk];
 			void this.#createFileSink();
@@ -874,26 +929,99 @@ export class OutputSink {
 		}
 	}
 
+	/**
+	 * Cap-aware sink writer. Bytes flow into the head window verbatim until the
+	 * budget is exhausted; subsequent bytes are diverted into a rolling tail
+	 * ring, evicted from the front so total RAM stays bounded by
+	 * `#artifactTailBudget`. `dump()` replays the ring behind a single notice
+	 * line before closing the sink.
+	 *
+	 * When the cap is disabled (`#artifactMaxBytes === 0`) this collapses to a
+	 * straight pass-through, preserving the historical "stream everything"
+	 * contract.
+	 */
+	#emitToSink(chunk: string): void {
+		if (!this.#file || chunk.length === 0) return;
+		if (this.#artifactMaxBytes === 0) {
+			this.#file.sink.write(chunk);
+			return;
+		}
+		const chunkBytes = Buffer.byteLength(chunk, "utf-8");
+		const room = this.#artifactHeadClosed ? 0 : this.#artifactHeadBudget - this.#artifactHeadBytesWritten;
+		if (room >= chunkBytes) {
+			this.#file.sink.write(chunk);
+			this.#artifactHeadBytesWritten += chunkBytes;
+			return;
+		}
+		let overflow = chunk;
+		if (room > 0) {
+			const headSlice = truncateHeadBytes(chunk, room);
+			if (headSlice.bytes > 0) {
+				this.#file.sink.write(headSlice.text);
+				this.#artifactHeadBytesWritten += headSlice.bytes;
+			}
+			// Even when UTF-8 boundary safety leaves a few bytes of nominal room,
+			// this chunk has already overflowed the head window. Close it now so a
+			// later small ASCII chunk cannot be written before this overflow tail.
+			this.#artifactHeadClosed = true;
+			overflow = chunk.substring(headSlice.text.length);
+		}
+		if (overflow.length === 0 || this.#artifactTailBudget === 0) {
+			// No tail budget: count the dropped bytes so the notice reflects them.
+			if (overflow.length > 0) {
+				this.#artifactTailIncomingBytes += Buffer.byteLength(overflow, "utf-8");
+			}
+			return;
+		}
+		this.#pushArtifactTail(overflow);
+	}
+
+	#pushArtifactTail(chunk: string): void {
+		const chunkBytes = Buffer.byteLength(chunk, "utf-8");
+		this.#artifactTailIncomingBytes += chunkBytes;
+		const budget = this.#artifactTailBudget;
+		if (chunkBytes >= budget) {
+			// Chunk alone dominates — keep only its tail slice.
+			const { text, bytes } = truncateTailBytes(chunk, budget);
+			this.#artifactTailRing = text;
+			this.#artifactTailRingBytes = bytes;
+			return;
+		}
+		this.#artifactTailRing += chunk;
+		this.#artifactTailRingBytes += chunkBytes;
+		if (this.#artifactTailRingBytes > budget) {
+			const { text, bytes } = truncateTailBytes(this.#artifactTailRing, budget);
+			this.#artifactTailRing = text;
+			this.#artifactTailRingBytes = bytes;
+		}
+	}
+
 	async #createFileSink(): Promise<void> {
 		if (!this.#artifactPath || this.#fileReady) return;
 		try {
 			const sink = Bun.file(this.#artifactPath).writer();
 			this.#file = { path: this.#artifactPath, artifactId: this.#artifactId, sink };
+			this.#fileReady = true;
+
+			// Head-retained bytes precede the rolling tail buffer in the capture.
+			// Route through #emitToSink so they count against the artifact head
+			// budget — a direct sink.write would let them escape the cap.
+			if (this.#head.length > 0) {
+				this.#emitToSink(this.#head);
+			}
 
 			// Flush existing buffer to file BEFORE it gets trimmed further.
 			if (this.#buffer.length > 0) {
-				sink.write(this.#buffer);
+				this.#emitToSink(this.#buffer);
 			}
 
-			// Drain any chunks that arrived while the sink was being created
+			// Drain any chunks that arrived while the sink was being created.
 			if (this.#pendingFileWrites) {
 				for (const pending of this.#pendingFileWrites) {
-					sink.write(pending);
+					this.#emitToSink(pending);
 				}
 				this.#pendingFileWrites = undefined;
 			}
-
-			this.#fileReady = true;
 		} catch {
 			try {
 				await this.#file?.sink?.end();
@@ -902,6 +1030,7 @@ export class OutputSink {
 			}
 			this.#file = undefined;
 			this.#pendingFileWrites = undefined;
+			this.#fileReady = false;
 		}
 	}
 
@@ -946,13 +1075,61 @@ export class OutputSink {
 		this.#columnEllipsisAdded = false;
 		this.#columnDroppedBytes = 0;
 		this.#columnTruncatedLines = 0;
+		this.#pendingChunk = "";
+	}
+
+	/**
+	 * Replay the rolling tail ring back into the artifact sink. When bytes
+	 * were actually dropped from the middle (the head budget was exhausted
+	 * *and* the tail ring evicted), a single `[ARTIFACT TRUNCATED: …]`
+	 * notice is injected between head and tail so a reader of
+	 * `artifact://<id>` understands the gap. When the total stream simply
+	 * spilled past the head budget but still fits below `artifactMaxBytes`,
+	 * `droppedBytes` is zero — head + tail together are the verbatim stream
+	 * and the notice is suppressed so we don't corrupt the artifact with a
+	 * misleading "0 B elided" marker (PR #2083 review by codex).
+	 *
+	 * No-op when the cap was never hit at all (head budget never exhausted,
+	 * tail ring empty).
+	 */
+	#flushArtifactTailIfCapped(): void {
+		if (!this.#file) return;
+		if (this.#artifactMaxBytes === 0) return;
+		const tailBytes = this.#artifactTailRingBytes;
+		const droppedBytes = Math.max(0, this.#artifactTailIncomingBytes - tailBytes);
+		if (tailBytes === 0 && droppedBytes === 0) return;
+
+		if (droppedBytes > 0) {
+			const headWritten = this.#artifactHeadBytesWritten;
+			const totalCapped = headWritten + this.#artifactTailIncomingBytes;
+			const headSep = headWritten > 0 ? "\n" : "";
+			const tailSep = tailBytes > 0 && !this.#artifactTailRing.startsWith("\n") ? "\n" : "";
+			const notice =
+				`${headSep}[ARTIFACT TRUNCATED: kept first ${formatBytes(headWritten)} + last ${formatBytes(tailBytes)} ` +
+				`of ${formatBytes(totalCapped)}; ${formatBytes(droppedBytes)} elided from the middle]${tailSep}`;
+			this.#file.sink.write(notice);
+		}
+		if (tailBytes > 0) {
+			this.#file.sink.write(this.#artifactTailRing);
+		}
 	}
 
 	async dump(notice?: string): Promise<OutputSummary> {
 		const noticeLine = notice ? `[${notice}]\n` : "";
+
+		// Flush any chunk still held back by the throttle so the live preview
+		// ends with the complete stream.
+		if (this.#onChunk && this.#pendingChunk.length > 0) {
+			const pending = this.#pendingChunk;
+			this.#pendingChunk = "";
+			this.#onChunk(pending);
+		}
 		const totalLines = this.#sawData ? this.#totalLines + 1 : 0;
 
-		if (this.#file) await this.#file.sink.end();
+		if (this.#file) {
+			this.#flushArtifactTailIfCapped();
+			await this.#file.sink.end();
+		}
 
 		// Compose the visible output. With head retention, splice head + marker
 		// + tail when content was elided. Otherwise return the rolling buffer.

package/src/slash-commands/acp-builtins.ts

@@ -5,6 +5,30 @@ import type { AcpBuiltinSlashCommandResult, SlashCommandRuntime } from "./types"
 
 export type { AcpBuiltinSlashCommandResult } from "./types";
 
+/**
+ * All names (primary + aliases) that are reserved by ACP builtins. Used to
+ * filter out extension commands that would shadow a builtin or its alias at
+ * dispatch time (e.g. `models` is an alias for `/model`, so an extension
+ * registering `models` would appear in the palette but execute the builtin).
+ */
+export const ACP_BUILTIN_RESERVED_NAMES: ReadonlySet<string> = new Set(
+	BUILTIN_SLASH_COMMANDS_INTERNAL.filter(c => c.handle !== undefined).flatMap(c => [c.name, ...(c.aliases ?? [])]),
+);
+
+/**
+ * Whether an extension command named `name` would be captured by ACP builtin
+ * dispatch before reaching the extension handler. Beyond exact name/alias
+ * collisions, `parseSlashCommand` treats `:` as a name/args separator, so a
+ * colon-namespaced name whose prefix is a handled builtin (e.g. `model:foo`)
+ * executes the `/model` builtin with `foo` as args. Such names must not be
+ * advertised to ACP clients.
+ */
+export function isAcpBuiltinShadowedName(name: string): boolean {
+	if (ACP_BUILTIN_RESERVED_NAMES.has(name)) return true;
+	const colon = name.indexOf(":");
+	return colon !== -1 && ACP_BUILTIN_RESERVED_NAMES.has(name.slice(0, colon));
+}
+
 /**
  * Commands advertised to ACP clients. Entries without a text-mode `handle`
  * (e.g. `/quit`, `/login`, dashboards) are filtered out so the client doesn't

package/src/slash-commands/builtin-registry.ts

@@ -30,6 +30,7 @@ import { createMarketplaceManager } from "./helpers/marketplace-manager";
 import { handleMcpAcp } from "./helpers/mcp";
 import { commandConsumed, errorMessage, parseSlashCommand, parseSubcommand, usage } from "./helpers/parse";
 import { handleSshAcp } from "./helpers/ssh";
+import { launchStatsDashboard, parseStatsDashboardArgs } from "./helpers/stats-dashboard";
 import { handleTodoAcp } from "./helpers/todo";
 import { buildUsageReportText } from "./helpers/usage-report";
 import { parseMarketplaceInstallArgs, parsePluginScopeArgs } from "./marketplace-install-parser";
@@ -81,6 +82,23 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "setup",
+		aliases: ["providers"],
+		description: "Open provider setup",
+		allowArgs: true,
+		subcommands: [{ name: "providers", description: "Configure sign-in and web search providers" }],
+		handleTui: async (command, runtime) => {
+			const args = command.args.trim().toLowerCase();
+			const opensProviders = args === "" || args === "providers";
+			if (opensProviders) {
+				await runtime.ctx.showProviderSetup();
+			} else {
+				runtime.ctx.showWarning(`Usage: /${command.name} [providers]`);
+			}
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "plan",
 		description: "Toggle plan mode (agent plans before executing)",
@@ -542,6 +560,25 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "stats",
+		description: "Launch the local stats dashboard",
+		inlineHint: "[--port <port>]",
+		allowArgs: true,
+		handle: async (command, runtime) => {
+			const parsed = parseStatsDashboardArgs(command.args);
+			if ("error" in parsed) return usage(parsed.error, runtime);
+
+			await runtime.output("Syncing session files...");
+			try {
+				const result = await launchStatsDashboard(parsed);
+				await runtime.output(result.message);
+			} catch (error) {
+				await runtime.output(`Stats dashboard failed: ${errorMessage(error)}`);
+			}
+			return commandConsumed();
+		},
+	},
 	{
 		name: "changelog",
 		description: "Show changelog entries",
@@ -1677,10 +1714,13 @@ for (const command of BUILTIN_SLASH_COMMAND_REGISTRY) {
 	}
 }
 
+export const BUILTIN_SLASH_COMMAND_RESERVED_NAMES: ReadonlySet<string> = new Set(BUILTIN_SLASH_COMMAND_LOOKUP.keys());
+
 /** Builtin command metadata used for slash-command autocomplete and help text. */
 export const BUILTIN_SLASH_COMMAND_DEFS: ReadonlyArray<BuiltinSlashCommand> = BUILTIN_SLASH_COMMAND_REGISTRY.map(
 	command => ({
 		name: command.name,
+		aliases: command.aliases,
 		description: command.description,
 		subcommands: command.subcommands,
 		inlineHint: command.inlineHint,

package/src/slash-commands/helpers/stats-dashboard.ts

@@ -0,0 +1,85 @@
+import * as stats from "@oh-my-pi/omp-stats";
+import * as openUtils from "../../utils/open";
+
+export const DEFAULT_STATS_DASHBOARD_PORT = 3847;
+
+interface StatsDashboardServer {
+	port: number;
+	stop: () => void;
+}
+
+export interface StatsDashboardArgs {
+	port: number;
+}
+
+export interface StatsDashboardLaunchResult {
+	url: string;
+	message: string;
+}
+
+let activeStatsServer: StatsDashboardServer | undefined;
+
+const STATS_DASHBOARD_USAGE = "Usage: /stats [--port <port>]";
+
+function parsePort(value: string | undefined): number | string {
+	if (!value) return `Missing port. ${STATS_DASHBOARD_USAGE}`;
+	if (!/^\d+$/.test(value)) return `Invalid port: ${value}`;
+	const port = Number(value);
+	if (!Number.isInteger(port) || port < 0 || port > 65_535) return `Invalid port: ${value}`;
+	return port;
+}
+
+export function parseStatsDashboardArgs(args: string): StatsDashboardArgs | { error: string } {
+	const tokens = args.split(/\s+/).filter(Boolean);
+	let port = DEFAULT_STATS_DASHBOARD_PORT;
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token === "--port" || token === "-p") {
+			const parsed = parsePort(tokens[++i]);
+			if (typeof parsed === "string") return { error: parsed };
+			port = parsed;
+			continue;
+		}
+		if (token.startsWith("--port=")) {
+			const parsed = parsePort(token.slice("--port=".length));
+			if (typeof parsed === "string") return { error: parsed };
+			port = parsed;
+			continue;
+		}
+		return { error: `Unknown option: ${token}. ${STATS_DASHBOARD_USAGE}` };
+	}
+
+	return { port };
+}
+
+export async function launchStatsDashboard(args: StatsDashboardArgs): Promise<StatsDashboardLaunchResult> {
+	const { processed, files } = await stats.syncAllSessions();
+	const total = await stats.getTotalMessageCount();
+	let requestedPortIgnored = false;
+
+	if (!activeStatsServer) {
+		activeStatsServer = await stats.startServer(args.port);
+	} else if (args.port !== activeStatsServer.port) {
+		requestedPortIgnored = true;
+	}
+
+	const url = `http://localhost:${activeStatsServer.port}`;
+	openUtils.openPath(url);
+
+	const serverLine = requestedPortIgnored
+		? `Dashboard already running at: ${url} (requested port ${args.port} ignored)`
+		: `Dashboard available at: ${url}`;
+
+	return {
+		url,
+		message: `Synced ${processed} new entries from ${files} files (${total} total)\n${serverLine}`,
+	};
+}
+
+export function stopStatsDashboard(): void {
+	if (!activeStatsServer) return;
+	activeStatsServer.stop();
+	activeStatsServer = undefined;
+	stats.closeDb();
+}

package/src/slash-commands/types.ts

@@ -14,6 +14,7 @@ export interface SubcommandDef {
 /** Declarative builtin slash command metadata used by autocomplete and help UI. */
 export interface BuiltinSlashCommand {
 	name: string;
+	aliases?: string[];
 	description: string;
 	/** Subcommands for dropdown completion (e.g. /mcp add, /mcp list). */
 	subcommands?: SubcommandDef[];
@@ -82,7 +83,6 @@ export interface TuiSlashCommandRuntime {
 
 /** Unified slash-command spec consumed by both TUI and ACP dispatchers. */
 export interface SlashCommandSpec extends BuiltinSlashCommand {
-	aliases?: string[];
 	/** When false, the dispatcher refuses to handle invocations that include arguments. */
 	allowArgs?: boolean;
 	/**

package/src/ssh/connection-manager.ts

@@ -355,6 +355,33 @@ export async function getHostInfoForHost(host: SSHConnectionTarget): Promise<SSH
 	return await loadHostInfoFromDisk(host);
 }
 
+/**
+ * Synchronous, probe-free host info lookup for startup paths.
+ *
+ * Checks the in-memory cache, then falls back to a synchronous read of the
+ * persisted host-info cache file. Never opens a connection or probes the
+ * remote host — callers get `undefined` when nothing is cached yet.
+ */
+export function getCachedHostInfoSync(host: SSHConnectionTarget): SSHHostInfo | undefined {
+	const cached = hostInfoCache.get(host.name);
+	if (cached) {
+		const resolved = applyCompatOverride(host, cached);
+		if (resolved !== cached) hostInfoCache.set(host.name, resolved);
+		return resolved;
+	}
+	try {
+		const parsed = parseHostInfo(JSON.parse(fs.readFileSync(getHostInfoPath(host.name), "utf-8")));
+		if (!parsed) return undefined;
+		const resolved = applyCompatOverride(host, parsed);
+		hostInfoCache.set(host.name, resolved);
+		return resolved;
+	} catch (err) {
+		if (isEnoent(err)) return undefined;
+		logger.warn("Failed to load SSH host info", { host: host.name, error: String(err) });
+		return undefined;
+	}
+}
+
 export async function ensureHostInfo(host: SSHConnectionTarget): Promise<SSHHostInfo> {
 	const cached = hostInfoCache.get(host.name);
 	if (cached) {

package/src/system-prompt.ts

@@ -8,6 +8,7 @@ import { $env, getGpuCachePath, getProjectDir, hasFsCode, isEnoent, logger, prom
 import { $ } from "bun";
 import { contextFileCapability } from "./capability/context-file";
 import { systemPromptCapability } from "./capability/system-prompt";
+import { findConfigFile } from "./config";
 import type { SkillsSettings } from "./config/settings";
 import { type ContextFile, loadCapability, type SystemPrompt as SystemPromptFile } from "./discovery";
 import { expandAtImports } from "./discovery/at-imports";
@@ -208,6 +209,19 @@ async function getEnvironmentInfo(): Promise<Array<{ label: string; value: strin
 	return entries.filter((e): e is { label: string; value: string } => !!e.value);
 }
 
+/** Discover TITLE_SYSTEM.md file for automatic session-title prompt overrides */
+export function discoverTitleSystemPromptFile(cwd?: string): string | undefined {
+	const projectPath = findConfigFile("TITLE_SYSTEM.md", { user: false, cwd });
+	if (projectPath) {
+		return projectPath;
+	}
+	const globalPath = findConfigFile("TITLE_SYSTEM.md", { user: true, cwd });
+	if (globalPath) {
+		return globalPath;
+	}
+	return undefined;
+}
+
 /** Resolve input as file path or literal string */
 export async function resolvePromptInput(input: string | undefined, description: string): Promise<string | undefined> {
 	if (!input) {

package/src/task/commands.ts

@@ -120,7 +120,8 @@ export function getCommand(commands: WorkflowCommand[], name: string): WorkflowC
  * Replaces $@ with the provided input.
  */
 export function expandCommand(command: WorkflowCommand, input: string): string {
-	return command.instructions.replace(/\$@/g, input);
+	// Function replacement so `$`-patterns in user input ($$, $&, ...) stay literal.
+	return command.instructions.replace(/\$@/g, () => input);
 }
 
 /**