@oh-my-pi/pi-coding-agent 17.3.5 → 17.3.7

package/dist/types/cli/stats-cli.d.ts

@@ -5,13 +5,8 @@
  */
 export interface StatsCommandArgs {
     port: number;
+    host: string;
     json: boolean;
     summary: boolean;
 }
-/**
- * Parse stats subcommand arguments.
- * Returns undefined if not a stats command.
- */
-export declare function parseStatsArgs(args: string[]): StatsCommandArgs | undefined;
 export declare function runStatsCommand(cmd: StatsCommandArgs): Promise<void>;
-export declare function printStatsHelp(): void;

package/dist/types/commands/stats.d.ts

@@ -10,6 +10,10 @@ export default class Stats extends Command {
             description: string;
             default: number;
         };
+        host: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            default: string;
+        };
         json: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
             char: string;
             description: string;

package/dist/types/extensibility/extensions/runner.d.ts

@@ -52,10 +52,12 @@ export type SwitchSessionHandler = (sessionPath: string) => Promise<{
 }>;
 export type ShutdownHandler = () => void;
 /**
- * Emit `session_shutdown` and clear timers owned by an extension runner.
+ * Emit `session_shutdown`, dispose file-write-fallback registrations, and clear
+ * timers owned by an extension runner.
  *
- * Returns whether any shutdown handlers were present. Timer cleanup runs even
- * when a handler fails so extension background work cannot outlive its host.
+ * Returns whether any shutdown handlers were present. Fallback disposal and timer
+ * cleanup run even when a handler fails so extension background work — and a
+ * fallback bound to this session's context — cannot outlive its host.
  */
 export declare function emitSessionShutdownEvent(extensionRunner: ExtensionRunner | undefined): Promise<boolean>;
 export declare class ExtensionRunner {
@@ -115,6 +117,15 @@ export declare class ExtensionRunner {
      * leak into another's `ctx.cwd` by reading a shared global.
      */
     get cwd(): string;
+    /**
+     * Stable id of the session this runner serves. Read through `sessionManager`
+     * for the same reason as {@link cwd}: it is this session's own, never a
+     * process-global, so a subagent runner reports itself and not its parent.
+     *
+     * Used to attribute a denied file write or delete to the session that issued
+     * it, since the fallback registry those handlers live in is process-wide.
+     */
+    get sessionId(): string;
     initialize(actions: ExtensionActions, contextActions: ExtensionContextActions, commandContextActions?: ExtensionCommandContextActions, uiContext?: ExtensionUIContext, mode?: ExtensionMode): void;
     /**
      * Forward a `credential_disabled` event from `AuthStorage` to extension handlers.
@@ -218,6 +229,13 @@ export declare class ExtensionRunner {
      * firing against a disposed session).
      */
     clearManagedTimers(): void;
+    /**
+     * Remove every file write and delete fallback this runner installed into the
+     * process-wide registries. Called on session shutdown (and before reinstalling
+     * on a re-{@link initialize}) so a handler bound to a torn-down session's
+     * context can never fire for another session sharing this process.
+     */
+    disposeFileFallbacks(): void;
     createCommandContext(): ExtensionCommandContext;
     emit<TEvent extends RunnerEmitEvent>(event: TEvent): Promise<RunnerEmitResult<TEvent>>;
     emitToolResult(event: ToolResultEvent): Promise<ToolResultEventResult | undefined>;

package/dist/types/extensibility/extensions/types.d.ts

@@ -33,6 +33,7 @@ import type { CustomMessage, CustomMessagePayload } from "../../session/messages
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager.js";
 import type { BashToolDetails, BashToolInput, GlobToolDetails, GlobToolInput, GrepToolDetails, GrepToolInput, ReadToolDetails, ReadToolInput, WriteToolInput } from "../../tools/index.js";
 import type { ApprovalMode } from "../../tools/approval.js";
+import type { FileDeleteFallbackHandler, FileWriteFallbackHandler } from "../../tools/file-write-fallback.js";
 import type { EventBus } from "../../utils/event-bus.js";
 import type { AgentEndEvent, AgentStartEvent, AutoCompactionEndEvent, AutoCompactionStartEvent, AutoRetryEndEvent, AutoRetryStartEvent, ContextEvent, GoalUpdatedEvent, RetryFallbackAppliedEvent, RetryFallbackSucceededEvent, SessionBeforeBranchEvent, SessionBeforeBranchResult, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionBranchEvent, SessionCompactEvent, SessionCompactingEvent, SessionCompactingResult, SessionEvent, SessionShutdownEvent, SessionStartEvent, SessionStopEvent, SessionStopEventResult, SessionSwitchEvent, SessionTreeEvent, TodoReminderEvent, ToolCallEventResult, ToolResultEventResult, TtsrTriggeredEvent, TurnEndEvent, TurnStartEvent } from "../shared-events.js";
 import type { SlashCommandInfo } from "../slash-commands.js";
@@ -834,6 +835,61 @@ export interface ExtensionAPI {
     on(event: "mcp_notification", handler: ExtensionHandler<McpNotificationEvent>): void;
     /** Register a tool that the LLM can call. */
     registerTool<TParams extends TSchema = TSchema, TDetails = unknown>(tool: ToolDefinition<TParams, TDetails>): void;
+    /**
+     * Register a fallback writer consulted when a native `write`/`edit` byte-write is
+     * denied with a permission error (`EPERM`/`EACCES`/`EROFS`). Every other write
+     * error is unaffected. Handlers run in registration order; the first one to
+     * resolve `true` counts as the bytes being durably on disk, and the native tool
+     * continues as if its own write had succeeded — including recording its file
+     * snapshot under the real destination path, so a later hashline `edit` on that
+     * path keeps working. Intended for a host embedding the agent inside a sandbox
+     * that denies direct filesystem writes but exposes a privileged write channel.
+     *
+     * A denial that `Bun.write` masks as `ENOENT` — a write into a directory the host
+     * may not create — also diverts here, with `req.dst`'s parent absent and the
+     * handler responsible for creating it.
+     *
+     * `req.dst` is symlink-RESOLVED: the path the failed write itself acted on, not
+     * the one the tool was given. A link anywhere in a lexical path redirects the
+     * bytes while still passing a prefix allowlist, so treat `req.dst` as
+     * authoritative. A destination that cannot be resolved is never brokered.
+     *
+     * Call this during extension load, like the other `register*` methods: handlers
+     * are installed when the runner initializes, so an extension that has registered
+     * none by then is skipped and a first registration made later never takes effect.
+     *
+     * The underlying registry is process-wide, so a handler may be consulted for a
+     * denied write from any session in the process, not only its own.
+     * `req.sessionId` names the session that issued the write and
+     * `ctx.sessionManager.getSessionId()` names the handler's own; compare them
+     * before prompting, because `ctx.ui` belongs to the latter. See
+     * `docs/extensions.md`.
+     */
+    registerFileWriteFallback(handler: FileWriteFallbackHandler): void;
+    /**
+     * Register a fallback deleter consulted when a native `edit`/`apply_patch` unlink is
+     * denied with a permission error (`EPERM`/`EACCES`/`EROFS`). Covers `edit`'s `REM`,
+     * the source side of a hashline `MV`, and `apply_patch`'s delete op. Return `true`
+     * once `dst` is gone from disk.
+     *
+     * A handler MUST remove `dst` with a plain unlink and MUST NOT fall back to a
+     * recursive removal. `unlink` on a directory reports `EPERM` on Darwin, so the seam
+     * checks the target before diverting — but when the target's own metadata is behind
+     * the same boundary that denied the unlink, which is the common sandbox case, that
+     * check cannot be resolved and `dst` may be a directory. `req.confirmedFile` says
+     * which situation the handler is in.
+     *
+     * `req.dst` resolves every component ABOVE the last, for the same reason the
+     * write seam resolves all of them; the last is left alone because `unlink`
+     * removes a link rather than its target, so `req.dst` may name a link.
+     *
+     * Separate from {@link registerFileWriteFallback} on purpose. A write handler
+     * brokers `req.content` to `req.dst`, so a delete request reaching it with no
+     * content invites brokering an empty write and truncating the file instead of
+     * removing it. Registering for deletes is therefore an explicit opt-in, and the
+     * same load-time and process-wide notes above apply.
+     */
+    registerFileDeleteFallback(handler: FileDeleteFallbackHandler): void;
     /** Register a custom command. */
     registerCommand(name: string, options: {
         description?: string;
@@ -1142,6 +1198,8 @@ export interface Extension {
     tools: Map<string, RegisteredTool<any, any>>;
     toolRegistrationListeners?: Set<ToolRegistrationListener>;
     assistantThinkingRenderers: AssistantThinkingRenderer[];
+    fileWriteFallbackHandlers: FileWriteFallbackHandler[];
+    fileDeleteFallbackHandlers: FileDeleteFallbackHandler[];
     messageRenderers: Map<string, MessageRenderer>;
     commands: Map<string, RegisteredCommand>;
     flags: Map<string, ExtensionFlag>;

package/dist/types/slash-commands/helpers/stats-dashboard.d.ts

@@ -1,6 +1,7 @@
 export declare const DEFAULT_STATS_DASHBOARD_PORT = 3847;
 export interface StatsDashboardArgs {
     port: number;
+    host: string;
 }
 export interface StatsDashboardLaunchResult {
     url: string;

package/dist/types/tools/file-write-fallback.d.ts

@@ -0,0 +1,124 @@
+import type { BunFile } from "bun";
+import type { ExtensionContext } from "../extensibility/extensions/types.js";
+/** A denied write, captured for a registered fallback to retry through a privileged channel. */
+export interface FileWriteFallbackRequest {
+    /**
+     * Absolute, symlink-resolved path to write the bytes to.
+     *
+     * This is where the failed in-process write would itself have landed, which is
+     * not necessarily the path the tool was given: `open` follows every component,
+     * so a link anywhere in that path redirects the bytes. Resolving it here is
+     * what lets a handler's allowlist see the real destination instead of a
+     * lexically innocent path, so a handler MUST treat this as authoritative and
+     * MUST NOT re-derive the target from anything else.
+     */
+    dst: string;
+    /**
+     * Session the denied write was issued from, or `undefined` when the mutation
+     * did not happen inside a tool call (an external `applyPatch` caller, a test).
+     *
+     * The registry is process-wide, so a handler can be consulted for a write from
+     * a session other than the one whose extension registered it. Compare this with
+     * `ctx.sessionManager.getSessionId()` to tell the two apart — a handler that
+     * prompts through `ctx.ui` needs to, since that UI belongs to ITS session and
+     * not necessarily to the one being asked about.
+     */
+    sessionId: string | undefined;
+    /** The exact bytes the tool intended to write. */
+    content: string;
+    /**
+     * The error that proves the write hit a permission boundary. Usually the write's
+     * own `EPERM`/`EACCES`/`EROFS`; for a write into a directory the host may not
+     * create, the denial raised by creating that directory, in which case `dst`'s
+     * parent may not exist yet and the handler is responsible for creating it.
+     */
+    cause: unknown;
+}
+/** Extension-authored handler. Return `true` once `content` is durably on disk at `dst`. */
+export type FileWriteFallbackHandler = (req: FileWriteFallbackRequest, ctx: ExtensionContext) => Promise<boolean>;
+/** A handler already bound to its owning extension's live context. */
+type BoundFileWriteFallbackHandler = (req: FileWriteFallbackRequest) => Promise<boolean>;
+/** A denied unlink, captured for a registered fallback to perform through a privileged channel. */
+export interface FileDeleteFallbackRequest {
+    /**
+     * Absolute, symlink-resolved path the unlink was denied for.
+     *
+     * Every component ABOVE the last is resolved, so a handler cannot be walked
+     * outside its allowed roots through a link in the path. The last component is
+     * deliberately NOT resolved, because `unlink` removes a link itself rather
+     * than its target — which is also why this may still name a symlink.
+     */
+    dst: string;
+    /** The `EPERM`/`EACCES`/`EROFS` that proves the unlink hit a permission boundary. */
+    cause: unknown;
+    /**
+     * Whether `dst` was confirmed to be a plain regular file before diverting.
+     *
+     * `false` means the seam could not establish that, either because the target's
+     * own metadata is behind the same boundary that denied the unlink — the common
+     * sandbox case, since `unlink` on a directory also reports `EPERM` on Darwin —
+     * or because `dst` is a symlink.
+     *
+     * A handler MUST remove `dst` with a plain unlink. It MUST NOT remove it
+     * recursively, and MUST NOT resolve the path first: when this is `false` the
+     * target may be a directory, and resolving a symlink would delete whatever it
+     * points at instead of the link.
+     */
+    confirmedFile: boolean;
+    /** See {@link FileWriteFallbackRequest.sessionId}. */
+    sessionId: string | undefined;
+}
+/** Extension-authored handler. Return `true` once `dst` is gone from disk. */
+export type FileDeleteFallbackHandler = (req: FileDeleteFallbackRequest, ctx: ExtensionContext) => Promise<boolean>;
+/** A handler already bound to its owning extension's live context. */
+type BoundFileDeleteFallbackHandler = (req: FileDeleteFallbackRequest) => Promise<boolean>;
+/** True for `EPERM`, `EACCES`, and `EROFS` — the sandbox-boundary write failures this seam exists for. */
+export declare function isPermissionDeniedError(error: unknown): boolean;
+/** Whether any fallback is registered. Lets a caller skip work that only this seam needs. */
+export declare function hasFileWriteFallback(): boolean;
+/**
+ * Append a fallback writer, consulted in registration order when a direct write is
+ * permission-denied. Returns a disposer that removes this exact registration; the
+ * runner calls it on session shutdown so no handler outlives its session.
+ */
+export declare function addFileWriteFallback(handler: BoundFileWriteFallbackHandler): () => void;
+/** Whether any delete fallback is registered. */
+export declare function hasFileDeleteFallback(): boolean;
+/**
+ * Append a fallback deleter, consulted in registration order when a direct unlink is
+ * permission-denied. Deliberately a separate registry from
+ * {@link addFileWriteFallback}: a write handler brokers `content` to `dst`, and
+ * handing it a request with no content would let it "broker" an empty write and
+ * truncate the file it was asked to remove. Opting in is explicit for that reason.
+ */
+export declare function addFileDeleteFallback(handler: BoundFileDeleteFallbackHandler): () => void;
+/**
+ * Name the session whose tool call is about to run, so a denied mutation inside it
+ * can tell a handler where the request came from.
+ *
+ * Entered once per tool call by `ExtensionToolWrapper` (`extensibility/extensions/
+ * wrapper.ts`), which `sdk.ts` puts around the whole tool registry whenever an
+ * `ExtensionRunner` exists — so the component that owns the handlers is the one
+ * naming its own session, and no caller has to thread an `AgentToolContext`
+ * through for attribution to work.
+ *
+ * That covers the deferred LSP write batch too: a batch id belongs to one
+ * assistant turn of one session, and its flush is awaited inside a tool call of
+ * that same session, so a write performed during a later call of the group is
+ * still attributed to the session that issued it.
+ *
+ * Deliberately NOT a general "current session" accessor: nothing else enters this
+ * scope, so outside a tool call it is empty by design — an external `applyPatch`
+ * caller reports `undefined` rather than borrowing someone else's identity.
+ */
+export declare function withFileMutationSession<T>(sessionId: string | undefined, fn: () => T): T;
+/**
+ * Remove a file, consulting registered delete fallbacks when the unlink is denied.
+ *
+ * Unlike the write path there is no masked-`ENOENT` case to see through: nothing is
+ * created on the way, so an `ENOENT` here means the file genuinely is not there and
+ * must propagate — `edit`'s `REM` turns it into a `NotFoundError`.
+ */
+export declare function deleteFileWithFallback(dst: string, file?: BunFile): Promise<void>;
+export declare function writeFileWithFallback(dst: string, content: string, file?: BunFile): Promise<void>;
+export {};

package/dist/types/tools/index.d.ts

@@ -50,6 +50,7 @@ export * from "./debug.js";
 export * from "./essential-tools.js";
 export * from "./eval.js";
 export * from "./eval-backends.js";
+export * from "./file-write-fallback.js";
 export * from "./gh.js";
 export * from "./glob.js";
 export * from "./grep.js";

package/dist/types/tools/path-utils.d.ts

@@ -155,6 +155,29 @@ export declare function resolveToCwd(filePath: string, cwd: string): string;
  * The cwd itself is rejected: a download names a file, never the directory.
  */
 export declare function confineToWorkspace(filePath: string, cwd: string): string | null;
+/**
+ * Resolve the path a syscall on `filePath` would really act on, or `null` when
+ * that cannot be established.
+ *
+ * A lexical path is not a destination. The kernel follows every component above
+ * the last, so `ws/link/file` under a `ws/link -> /elsewhere` link lands outside
+ * `ws` while still looking relative and `..`-free. Handing such a path to a
+ * privileged helper defeats the defence a helper author reaches for first — a
+ * prefix allowlist passes, because the link sits inside the allowed root while
+ * its target does not. Callers that hand a path to something more privileged
+ * than the syscall that just failed resolve it here first.
+ *
+ * Rejecting symlinked components outright is not an option: `/var` and `/tmp`
+ * are links on macOS, so every path under `os.tmpdir()` traverses one. They are
+ * resolved instead, and only a path whose real destination cannot be established
+ * is refused, because "where would this land" then has no answer to hand over.
+ * {@link confineToWorkspace} refuses an unresolvable link for the same reason.
+ *
+ * @param followFinal `true` for a syscall that follows a link at the final
+ *   component (`open`, so every write), `false` for one that acts on the link
+ *   itself (`unlink`) and therefore needs it left alone.
+ */
+export declare function resolveSyscallTarget(filePath: string, followFinal: boolean): Promise<string | null>;
 export declare function formatPathRelativeToCwd(filePath: string, cwd: string, options?: {
     trailingSlash?: boolean;
 }): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "17.3.5",
+	"version": "17.3.7",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -48,18 +48,18 @@
 	},
 	"dependencies": {
 		"@babel/parser": "^7.29.7",
-		"@oh-my-pi/hashline": "17.3.5",
-		"@oh-my-pi/omp-stats": "17.3.5",
-		"@oh-my-pi/omptype": "17.3.5",
-		"@oh-my-pi/pi-agent-core": "17.3.5",
-		"@oh-my-pi/pi-ai": "17.3.5",
-		"@oh-my-pi/pi-catalog": "17.3.5",
-		"@oh-my-pi/pi-mnemopi": "17.3.5",
-		"@oh-my-pi/pi-natives": "17.3.5",
-		"@oh-my-pi/pi-tui": "17.3.5",
-		"@oh-my-pi/pi-utils": "17.3.5",
-		"@oh-my-pi/pi-wire": "17.3.5",
-		"@oh-my-pi/snapcompact": "17.3.5",
+		"@oh-my-pi/hashline": "17.3.7",
+		"@oh-my-pi/omp-stats": "17.3.7",
+		"@oh-my-pi/omptype": "17.3.7",
+		"@oh-my-pi/pi-agent-core": "17.3.7",
+		"@oh-my-pi/pi-ai": "17.3.7",
+		"@oh-my-pi/pi-catalog": "17.3.7",
+		"@oh-my-pi/pi-mnemopi": "17.3.7",
+		"@oh-my-pi/pi-natives": "17.3.7",
+		"@oh-my-pi/pi-tui": "17.3.7",
+		"@oh-my-pi/pi-utils": "17.3.7",
+		"@oh-my-pi/pi-wire": "17.3.7",
+		"@oh-my-pi/snapcompact": "17.3.7",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/api-logs": "^0.220.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",

package/src/cli/stats-cli.ts

@@ -5,7 +5,7 @@
  */
 
 import { truncateToWidth } from "@oh-my-pi/pi-tui/utils";
-import { APP_NAME, formatDuration, formatNumber, formatPercent } from "@oh-my-pi/pi-utils";
+import { formatDuration, formatNumber, formatPercent } from "@oh-my-pi/pi-utils";
 import chalk from "@oh-my-pi/pi-utils/chalk";
 import { openPath } from "../utils/open";
 
@@ -57,45 +57,11 @@ function shortenSessionFile(p: string): string {
 
 export interface StatsCommandArgs {
 	port: number;
+	host: string;
 	json: boolean;
 	summary: boolean;
 }
 
-// =============================================================================
-// Argument Parser
-// =============================================================================
-
-/**
- * Parse stats subcommand arguments.
- * Returns undefined if not a stats command.
- */
-export function parseStatsArgs(args: string[]): StatsCommandArgs | undefined {
-	if (args.length === 0 || args[0] !== "stats") {
-		return undefined;
-	}
-
-	const result: StatsCommandArgs = {
-		port: 3847,
-		json: false,
-		summary: false,
-	};
-
-	for (let i = 1; i < args.length; i++) {
-		const arg = args[i];
-		if (arg === "--json" || arg === "-j") {
-			result.json = true;
-		} else if (arg === "--summary" || arg === "-s") {
-			result.summary = true;
-		} else if ((arg === "--port" || arg === "-p") && i + 1 < args.length) {
-			result.port = parseInt(args[++i], 10);
-		} else if (arg.startsWith("--port=")) {
-			result.port = parseInt(arg.split("=")[1], 10);
-		}
-	}
-
-	return result;
-}
-
 function formatCost(n: number): string {
 	if (n < 0.01) return `$${n.toFixed(4)}`;
 	if (n < 1) return `$${n.toFixed(3)}`;
@@ -112,9 +78,8 @@ function normalizePremiumRequests(n: number): number {
 
 export async function runStatsCommand(cmd: StatsCommandArgs): Promise<void> {
 	// Lazy import to avoid loading stats module when not needed
-	const { getDashboardStats, syncAllSessions, getTotalMessageCount, startServer, closeDb } = await import(
-		"@oh-my-pi/omp-stats"
-	);
+	const { closeDb, formatStatsDashboardUrl, getDashboardStats, getTotalMessageCount, startServer, syncAllSessions } =
+		await import("@oh-my-pi/omp-stats");
 
 	// Sync session files first
 	const progress = createSyncProgressReporter();
@@ -136,8 +101,8 @@ export async function runStatsCommand(cmd: StatsCommandArgs): Promise<void> {
 	}
 
 	// Start the dashboard server
-	const { hostname, port } = await startServer(cmd.port);
-	const url = `http://${hostname}:${port}`;
+	const { hostname, port } = await startServer(cmd.port, cmd.host);
+	const url = formatStatsDashboardUrl(hostname, port);
 	console.log(chalk.green(`Dashboard available at: ${url}`));
 
 	// Open browser
@@ -197,34 +162,3 @@ async function printStatsSummary(): Promise<void> {
 
 	console.log("");
 }
-
-// =============================================================================
-// Help
-// =============================================================================
-
-export function printStatsHelp(): void {
-	console.log(`${chalk.bold(`${APP_NAME} stats`)} - AI Usage Statistics Dashboard
-
-${chalk.bold("Usage:")}
-  ${APP_NAME} stats [options]
-
-${chalk.bold("Options:")}
-  -p, --port <port>  Port for the dashboard server (default: 3847)
-  -j, --json         Output stats as JSON and exit
-  -s, --summary      Print summary to console and exit
-  -h, --help         Show this help message
-
-${chalk.bold("Examples:")}
-  ${APP_NAME} stats              # Start dashboard server
-  ${APP_NAME} stats --json       # Print stats as JSON
-  ${APP_NAME} stats --summary    # Print summary to console
-  ${APP_NAME} stats --port 8080  # Start on custom port
-
-${chalk.bold("Metrics:")}
-  - Total requests and error rate
-  - Token usage (input, output, cache)
-  - Cost breakdown
-  - Average duration and time to first token (TTFT)
-  - Tokens per second throughput
-`);
-}

package/src/commands/stats.ts

@@ -4,13 +4,15 @@
 
 import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
 import { statsHelp as commandHelp } from "../cli/command-help";
-import { runStatsCommand, type StatsCommandArgs } from "../cli/stats-cli";
-import { initTheme } from "../modes/theme/theme";
+import type { StatsCommandArgs } from "../cli/stats-cli";
+import * as statsCli from "../cli/stats-cli";
+import * as theme from "../modes/theme/theme";
 
 export default class Stats extends Command {
 	static description = commandHelp.description;
 	static flags = {
 		port: Flags.integer({ char: "p", description: "Port for the dashboard server", default: 3847 }),
+		host: Flags.string({ description: "Host to bind", default: "127.0.0.1" }),
 		json: Flags.boolean({ char: "j", description: "Output stats as JSON", default: false }),
 		summary: Flags.boolean({ char: "s", description: "Print summary to console", default: false }),
 	};
@@ -20,11 +22,12 @@ export default class Stats extends Command {
 
 		const cmd: StatsCommandArgs = {
 			port: flags.port,
+			host: flags.host ?? "127.0.0.1",
 			json: flags.json,
 			summary: flags.summary,
 		};
 
-		await initTheme();
-		await runStatsCommand(cmd);
+		await theme.initTheme();
+		await statsCli.runStatsCommand(cmd);
 	}
 }

package/src/edit/hashline/filesystem.ts

@@ -25,6 +25,7 @@ import { FileChangeType, notifyWorkspaceWatchedFiles } from "../../lsp/client";
 import type { ToolSession } from "../../tools";
 import { routeWriteThroughBridge } from "../../tools/acp-bridge";
 import { assertEditableFileContent } from "../../tools/auto-generated-guard";
+import { deleteFileWithFallback, writeFileWithFallback } from "../../tools/file-write-fallback";
 import { invalidateFsScanAfterWrite } from "../../tools/fs-cache-invalidation";
 import { isInternalUrlPath } from "../../tools/path-utils";
 import { enforcePlanModeWrite, resolvePlanPath, targetsLocalSandbox } from "../../tools/plan-mode-guard";
@@ -153,7 +154,7 @@ export class HashlineFilesystem extends Filesystem {
 		enforcePlanModeWrite(this.session, relativePath, { op: "delete" });
 		const absolutePath = this.resolveAbsolute(relativePath);
 		try {
-			await fs.rm(absolutePath);
+			await deleteFileWithFallback(absolutePath);
 		} catch (error) {
 			if (isEnoent(error)) throw new NotFoundError(relativePath, error);
 			throw error;
@@ -173,8 +174,13 @@ export class HashlineFilesystem extends Filesystem {
 		const fromAbsolute = this.resolveAbsolute(fromRelative);
 		const toAbsolute = this.resolveAbsolute(toRelative);
 		if (content !== undefined) {
-			await Bun.write(toAbsolute, content);
-			await fs.rm(fromAbsolute);
+			// The one `edit` write that does not pass through the writethrough, so it
+			// routes to the fallback seam directly. `patcher.ts` always supplies
+			// `content` for a hashline `MV`, making this the live branch. The source
+			// unlink is a separate primitive with its own seam, so a move out of the
+			// workspace and a move out of denied territory both complete.
+			await writeFileWithFallback(toAbsolute, content);
+			await deleteFileWithFallback(fromAbsolute);
 		} else {
 			await fs.rename(fromAbsolute, toAbsolute);
 		}

package/src/edit/modes/patch.ts

@@ -20,6 +20,12 @@ import { FileChangeType, notifyWorkspaceWatchedFiles } from "../../lsp/client";
 import type { ToolSession } from "../../tools";
 import { routeWriteThroughBridge } from "../../tools/acp-bridge";
 import { assertEditableFile } from "../../tools/auto-generated-guard";
+import {
+	deleteFileWithFallback,
+	hasFileWriteFallback,
+	isPermissionDeniedError,
+	writeFileWithFallback,
+} from "../../tools/file-write-fallback";
 import {
 	invalidateFsScanAfterDelete,
 	invalidateFsScanAfterRename,
@@ -111,6 +117,26 @@ export interface ApplyPatchOptions {
 // Default File System
 // ═══════════════════════════════════════════════════════════════════════════
 
+/**
+ * Create a patch target's parent directory, tolerating a permission denial when a
+ * file-write fallback is registered.
+ *
+ * `apply_patch` mkdirs the parent before writing, so under a sandbox that denies
+ * the out-of-tree path this throws before the write — and therefore before
+ * {@link writeFileWithFallback} — is ever reached, leaving the fallback unable to
+ * broker a `create` or a rename-move into a new directory. Swallowing only a
+ * permission denial, and only with a handler installed, hands control to the write,
+ * which reports the denial through the seam. Without a handler the error propagates
+ * exactly as before.
+ */
+async function mkdirAllowingFallback(dir: string): Promise<void> {
+	try {
+		await fs.promises.mkdir(dir, { recursive: true });
+	} catch (error) {
+		if (!hasFileWriteFallback() || !isPermissionDeniedError(error)) throw error;
+	}
+}
+
 /** Default filesystem implementation using Bun APIs */
 export const defaultFileSystem: FileSystem = {
 	async exists(path: string): Promise<boolean> {
@@ -123,13 +149,13 @@ export const defaultFileSystem: FileSystem = {
 		return fs.promises.readFile(path);
 	},
 	async write(path: string, content: string): Promise<void> {
-		await Bun.write(path, await serializeEditFileText(path, path, content));
+		await writeFileWithFallback(path, await serializeEditFileText(path, path, content));
 	},
 	async delete(path: string): Promise<void> {
-		await fs.promises.unlink(path);
+		await deleteFileWithFallback(path);
 	},
 	async mkdir(path: string): Promise<void> {
-		await fs.promises.mkdir(path, { recursive: true });
+		await mkdirAllowingFallback(path);
 	},
 };
 
@@ -1753,7 +1779,7 @@ class LspFileSystem implements FileSystem {
 	}
 
 	async delete(path: string): Promise<void> {
-		await this.#getFile(path).unlink();
+		await deleteFileWithFallback(path, this.#getFile(path));
 		if (this.session.enableLsp ?? true) {
 			await notifyWorkspaceWatchedFiles(
 				this.session.cwd,
@@ -1764,7 +1790,7 @@ class LspFileSystem implements FileSystem {
 	}
 
 	async mkdir(path: string): Promise<void> {
-		await fs.promises.mkdir(path, { recursive: true });
+		await mkdirAllowingFallback(path);
 	}
 
 	getDiagnostics(): FileDiagnosticsResult | undefined {

package/src/extensibility/extensions/loader.ts

@@ -28,6 +28,7 @@ import { execCommand } from "../../exec/exec";
 // Runtime self-reference: dereference this namespace only inside loader functions to keep the index.ts cycle safe.
 import * as PiCodingAgent from "../../index";
 import type { CustomMessagePayload } from "../../session/messages";
+import type { FileDeleteFallbackHandler, FileWriteFallbackHandler } from "../../tools/file-write-fallback";
 import { EventBus } from "../../utils/event-bus";
 import * as TypeBox from "../legacy-typebox";
 import { installLegacyPiSpecifierShim, loadLegacyPiModule } from "../plugins/legacy-pi-compat";
@@ -183,6 +184,14 @@ class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
 		for (const listener of this.extension.toolRegistrationListeners ?? []) listener(tool.name);
 	}
 
+	registerFileWriteFallback(handler: FileWriteFallbackHandler): void {
+		this.extension.fileWriteFallbackHandlers.push(handler);
+	}
+
+	registerFileDeleteFallback(handler: FileDeleteFallbackHandler): void {
+		this.extension.fileDeleteFallbackHandlers.push(handler);
+	}
+
 	registerCommand(
 		name: string,
 		options: {
@@ -320,6 +329,8 @@ function createExtension(extensionPath: string, resolvedPath: string): Extension
 		tools: new Map(),
 		toolRegistrationListeners: new Set(),
 		assistantThinkingRenderers: [],
+		fileWriteFallbackHandlers: [],
+		fileDeleteFallbackHandlers: [],
 		messageRenderers: new Map(),
 		commands: new Map(),
 		flags: new Map(),