@code-yeongyu/senpi 2026.9.4 → 2026.9.5

package/dist/core/extensions/builtin/terminal/durable-command.js

@@ -0,0 +1,96 @@
+/**
+ * The `restartable-command` durability class: the restore handler that brings a persistent
+ * command monitor back after a restart. It re-spawns the saved command EXACTLY ONCE, in the
+ * saved working directory, with NO timeout (a persistent watch has no deadline), and
+ * re-registers it under the SAVED `mon_` id so the stable handle the agent already knows
+ * keeps resolving. Nothing the pre-restart PTY produced is replayed — no output is persisted
+ * anywhere, so a restored watch starts from an empty buffer by construction.
+ */
+import { stat } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { reapplyPersistedMute } from "./restore.js";
+import { DEFAULT_COLS, DEFAULT_ROWS } from "./shared.js";
+import { spawnCommandSession } from "./tools/spawn.js";
+const LOST = { outcome: "lost" };
+async function defaultDirectoryExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function compileFilter(source) {
+    if (source === undefined)
+        return undefined;
+    try {
+        return new RegExp(source);
+    }
+    catch {
+        // A filter that no longer compiles must not sink the watch: restore it unfiltered.
+        return undefined;
+    }
+}
+function dimension(value, fallback) {
+    return value !== undefined && Number.isFinite(value) && value >= 1 ? Math.trunc(value) : fallback;
+}
+/**
+ * Decide whether a manifest entry is a restorable persistent command watch. Only the
+ * command runtime kind qualifies, only when it was created `persistent: true` (a
+ * non-persistent watch had a deadline and is deliberately not resurrected), and only
+ * when it actually carries a command and an absolute cwd to spawn it in.
+ */
+function restorable(monitor) {
+    if (monitor.runtimeKind !== "command" || !monitor.persistent)
+        return undefined;
+    const { command, cwd } = monitor;
+    if (command === undefined || command.length === 0)
+        return undefined;
+    if (cwd === undefined || !isAbsolute(cwd))
+        return undefined;
+    return { command, cwd };
+}
+/**
+ * Build the `restartable-command` restore handler. Every guard rejects BEFORE spawning, so a
+ * rejected entry costs zero PTY sessions; a spawn failure is reported lost rather than thrown,
+ * because restore must never fail the startup path for one unrecoverable watch.
+ */
+export function createRestartableCommandHandler(deps) {
+    const spawn = deps.spawn ?? spawnCommandSession;
+    const directoryExists = deps.directoryExists ?? defaultDirectoryExists;
+    return async (monitor) => {
+        const target = restorable(monitor);
+        if (target === undefined)
+            return LOST;
+        if (!(await directoryExists(target.cwd)))
+            return LOST;
+        let spawned;
+        try {
+            spawned = await spawn(deps.ctx, {
+                command: target.command,
+                cols: dimension(deps.ctx.defaultCols, DEFAULT_COLS),
+                rows: dimension(deps.ctx.defaultRows, DEFAULT_ROWS),
+                cwd: target.cwd,
+                // Persistent watches carry no deadline: omit timeoutMs entirely.
+            });
+        }
+        catch {
+            return LOST;
+        }
+        deps.registry.register({
+            id: spawned.id,
+            monitorId: monitor.monitorId,
+            description: monitor.description,
+            runtime: spawned.runtime,
+            filter: compileFilter(monitor.filter),
+            // The persisted deadline rides through verbatim; a restore never extends it.
+            ...(monitor.expiresAt !== null ? { expiresAt: monitor.expiresAt } : {}),
+        });
+        deps.ctx.manager.bindMonitorId(monitor.monitorId, spawned.id);
+        deps.onRestored?.(monitor.monitorId, spawned.id);
+        // A persisted mute is re-applied by the FRESH runtime id; the registry resolves
+        // records by runtime id only, so the mon_ id would silently no-op here.
+        return { outcome: reapplyPersistedMute(deps.registry, monitor, spawned.id) };
+    };
+}
+//# sourceMappingURL=durable-command.js.map

package/dist/core/extensions/builtin/terminal/durable-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-command.js","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/durable-command.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,EAAkD,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpG,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAevD,MAAM,IAAI,GAAyB,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAEvD,KAAK,UAAU,sBAAsB,CAAC,IAAY;IACjD,IAAI,CAAC;QACJ,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC;AAED,SAAS,aAAa,CAAC,MAA0B;IAChD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC;QACJ,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACR,mFAAmF;QACnF,OAAO,SAAS,CAAC;IAClB,CAAC;AACF,CAAC;AAED,SAAS,SAAS,CAAC,KAAyB,EAAE,QAAgB;IAC7D,OAAO,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AACnG,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,OAAwB;IAC3C,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IAC/E,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IACjC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACpE,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5D,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAAC,IAA4B;IAC3E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,mBAAmB,CAAC;IAChD,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,sBAAsB,CAAC;IACvE,OAAO,KAAK,EAAE,OAAwB,EAAiC,EAAE;QACxE,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACtC,IAAI,CAAC,CAAC,MAAM,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAEtD,IAAI,OAAwD,CAAC;QAC7D,IAAI,CAAC;YACJ,OAAO,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE;gBAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,YAAY,CAAC;gBACnD,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,YAAY,CAAC;gBACnD,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,iEAAiE;aACjE,CAAC,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,CAAC;QACb,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACtB,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC;YACrC,6EAA6E;YAC7E,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvE,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QACjD,gFAAgF;QAChF,wEAAwE;QACxE,OAAO,EAAE,OAAO,EAAE,oBAAoB,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;IAC9E,CAAC,CAAC;AACH,CAAC","sourcesContent":["/**\n * The `restartable-command` durability class: the restore handler that brings a persistent\n * command monitor back after a restart. It re-spawns the saved command EXACTLY ONCE, in the\n * saved working directory, with NO timeout (a persistent watch has no deadline), and\n * re-registers it under the SAVED `mon_` id so the stable handle the agent already knows\n * keeps resolving. Nothing the pre-restart PTY produced is replayed — no output is persisted\n * anywhere, so a restored watch starts from an empty buffer by construction.\n */\n\nimport { stat } from \"node:fs/promises\";\nimport { isAbsolute } from \"node:path\";\nimport type { MonitorRegistry } from \"./monitor-registry.ts\";\nimport { type RestoreHandler, type RestoreHandlerResult, reapplyPersistedMute } from \"./restore.ts\";\nimport { DEFAULT_COLS, DEFAULT_ROWS } from \"./shared.ts\";\nimport type { ManifestMonitor } from \"./terminal-manifest.ts\";\nimport type { TerminalToolContext } from \"./tools/context.ts\";\nimport { spawnCommandSession } from \"./tools/spawn.ts\";\n\nexport interface RestartableCommandDeps {\n\t/** Spawn target: supplies the terminal manager, shell config, env and default geometry. */\n\treadonly ctx: TerminalToolContext;\n\t/** The live registry this generation owns; the restored watch is registered here. */\n\treadonly registry: MonitorRegistry;\n\t/** Seam for tests and future callers; defaults to the real PTY spawn. */\n\treadonly spawn?: typeof spawnCommandSession;\n\t/** Directory existence probe; defaults to a real stat of the saved cwd. */\n\treadonly directoryExists?: (path: string) => Promise<boolean>;\n\t/** Called after a successful restore with the stable id and its fresh runtime id. */\n\treadonly onRestored?: (monitorId: string, runtimeId: string) => void;\n}\n\nconst LOST: RestoreHandlerResult = { outcome: \"lost\" };\n\nasync function defaultDirectoryExists(path: string): Promise<boolean> {\n\ttry {\n\t\treturn (await stat(path)).isDirectory();\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction compileFilter(source: string | undefined): RegExp | undefined {\n\tif (source === undefined) return undefined;\n\ttry {\n\t\treturn new RegExp(source);\n\t} catch {\n\t\t// A filter that no longer compiles must not sink the watch: restore it unfiltered.\n\t\treturn undefined;\n\t}\n}\n\nfunction dimension(value: number | undefined, fallback: number): number {\n\treturn value !== undefined && Number.isFinite(value) && value >= 1 ? Math.trunc(value) : fallback;\n}\n\n/**\n * Decide whether a manifest entry is a restorable persistent command watch. Only the\n * command runtime kind qualifies, only when it was created `persistent: true` (a\n * non-persistent watch had a deadline and is deliberately not resurrected), and only\n * when it actually carries a command and an absolute cwd to spawn it in.\n */\nfunction restorable(monitor: ManifestMonitor): { command: string; cwd: string } | undefined {\n\tif (monitor.runtimeKind !== \"command\" || !monitor.persistent) return undefined;\n\tconst { command, cwd } = monitor;\n\tif (command === undefined || command.length === 0) return undefined;\n\tif (cwd === undefined || !isAbsolute(cwd)) return undefined;\n\treturn { command, cwd };\n}\n\n/**\n * Build the `restartable-command` restore handler. Every guard rejects BEFORE spawning, so a\n * rejected entry costs zero PTY sessions; a spawn failure is reported lost rather than thrown,\n * because restore must never fail the startup path for one unrecoverable watch.\n */\nexport function createRestartableCommandHandler(deps: RestartableCommandDeps): RestoreHandler {\n\tconst spawn = deps.spawn ?? spawnCommandSession;\n\tconst directoryExists = deps.directoryExists ?? defaultDirectoryExists;\n\treturn async (monitor: ManifestMonitor): Promise<RestoreHandlerResult> => {\n\t\tconst target = restorable(monitor);\n\t\tif (target === undefined) return LOST;\n\t\tif (!(await directoryExists(target.cwd))) return LOST;\n\n\t\tlet spawned: Awaited<ReturnType<typeof spawnCommandSession>>;\n\t\ttry {\n\t\t\tspawned = await spawn(deps.ctx, {\n\t\t\t\tcommand: target.command,\n\t\t\t\tcols: dimension(deps.ctx.defaultCols, DEFAULT_COLS),\n\t\t\t\trows: dimension(deps.ctx.defaultRows, DEFAULT_ROWS),\n\t\t\t\tcwd: target.cwd,\n\t\t\t\t// Persistent watches carry no deadline: omit timeoutMs entirely.\n\t\t\t});\n\t\t} catch {\n\t\t\treturn LOST;\n\t\t}\n\n\t\tdeps.registry.register({\n\t\t\tid: spawned.id,\n\t\t\tmonitorId: monitor.monitorId,\n\t\t\tdescription: monitor.description,\n\t\t\truntime: spawned.runtime,\n\t\t\tfilter: compileFilter(monitor.filter),\n\t\t\t// The persisted deadline rides through verbatim; a restore never extends it.\n\t\t\t...(monitor.expiresAt !== null ? { expiresAt: monitor.expiresAt } : {}),\n\t\t});\n\t\tdeps.ctx.manager.bindMonitorId(monitor.monitorId, spawned.id);\n\t\tdeps.onRestored?.(monitor.monitorId, spawned.id);\n\t\t// A persisted mute is re-applied by the FRESH runtime id; the registry resolves\n\t\t// records by runtime id only, so the mon_ id would silently no-op here.\n\t\treturn { outcome: reapplyPersistedMute(deps.registry, monitor, spawned.id) };\n\t};\n}\n"]}

package/dist/core/extensions/builtin/terminal/durable-file.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The `checkpointed-file` durability class: the restore handler that makes a persistent file
+ * watch survive a restart. On create the monitor tool persists the registry's own identity
+ * tuple (dev/ino/size/mtimeMs/digest/present) as the manifest checkpoint; here that checkpoint
+ * is compared ONCE against the file as it is now, and any change that happened while the process
+ * was gone is reported as EXACTLY ONE line through the registry's normal event sink — so the
+ * notifier's coalescing and wake budget apply to it exactly as they do to a live watch event.
+ *
+ * `digest` is load-bearing: without it a same-size, same-mtime rewrite is invisible across a restart.
+ */
+import type { MonitorRegistry } from "./monitor-registry.ts";
+import type { RestoreHandler } from "./restore.ts";
+import type { TerminalManifestCheckpoint, TerminalManifestWriter } from "./terminal-manifest.ts";
+/**
+ * What a detached change is reported as. `null` means the file is byte-identical to the checkpoint;
+ * `"gone"` means it existed at checkpoint time and does not now, which is not restorable.
+ */
+export type DetachedChange = "created" | "replaced" | "modified" | "gone" | null;
+/** Only what the handler needs, so a caller can hand it a narrower registry/writer. */
+export interface CheckpointedFileRestoreDeps {
+    readonly registry: Pick<MonitorRegistry, "registerFile" | "fileCheckpoint" | "emitFileLine" | "stopFile">;
+    /** Optional: the durable checkpoint is re-persisted through the writer when one is bound. */
+    readonly writer?: Pick<TerminalManifestWriter, "scheduleCheckpoint">;
+    /** Optional: re-bind the stable `mon_` id to its fresh runtime id so kill_bash keeps resolving it. */
+    readonly bindMonitorId?: (monitorId: string, runtimeId: string) => void;
+    readonly now?: () => number;
+}
+/** The live tuple `registry.fileCheckpoint` returns; identical in shape to the persisted checkpoint. */
+type LiveCheckpoint = NonNullable<ReturnType<MonitorRegistry["fileCheckpoint"]>>;
+/**
+ * The single comparison, run once per restore. `created` and `replaced` outrank `modified`:
+ * an absent→present transition or a new dev/ino is a stronger statement about the same file.
+ */
+export declare function classifyDetachedChange(saved: TerminalManifestCheckpoint, live: LiveCheckpoint): DetachedChange;
+/**
+ * Build the `checkpointed-file` restore handler. It re-registers the watch under its original
+ * `mon_` id and approved parent (so the permission decision still holds), then reports at most
+ * one detached-change line. Returns `lost` when the path is gone or unreadable, `restored` otherwise.
+ */
+export declare function createCheckpointedFileRestoreHandler(deps: CheckpointedFileRestoreDeps): RestoreHandler;
+export {};
+//# sourceMappingURL=durable-file.d.ts.map

package/dist/core/extensions/builtin/terminal/durable-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-file.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/durable-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAmB,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAElH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;AAEjF,uFAAuF;AACvF,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,cAAc,GAAG,gBAAgB,GAAG,cAAc,GAAG,UAAU,CAAC,CAAC;IAC1G,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,oBAAoB,CAAC,CAAC;IACrE,sGAAsG;IACtG,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACxE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED,wGAAwG;AACxG,KAAK,cAAc,GAAG,WAAW,CAAC,UAAU,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;AAEjF;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,0BAA0B,EAAE,IAAI,EAAE,cAAc,GAAG,cAAc,CAM9G;AAcD;;;;GAIG;AACH,wBAAgB,oCAAoC,CAAC,IAAI,EAAE,2BAA2B,GAAG,cAAc,CAwDtG"}

package/dist/core/extensions/builtin/terminal/durable-file.js

@@ -0,0 +1,102 @@
+/**
+ * The `checkpointed-file` durability class: the restore handler that makes a persistent file
+ * watch survive a restart. On create the monitor tool persists the registry's own identity
+ * tuple (dev/ino/size/mtimeMs/digest/present) as the manifest checkpoint; here that checkpoint
+ * is compared ONCE against the file as it is now, and any change that happened while the process
+ * was gone is reported as EXACTLY ONE line through the registry's normal event sink — so the
+ * notifier's coalescing and wake budget apply to it exactly as they do to a live watch event.
+ *
+ * `digest` is load-bearing: without it a same-size, same-mtime rewrite is invisible across a restart.
+ */
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+/**
+ * The single comparison, run once per restore. `created` and `replaced` outrank `modified`:
+ * an absent→present transition or a new dev/ino is a stronger statement about the same file.
+ */
+export function classifyDetachedChange(saved, live) {
+    if (!saved.present)
+        return live.present ? "created" : null;
+    if (!live.present)
+        return "gone";
+    if (live.dev !== saved.dev || live.ino !== saved.ino)
+        return "replaced";
+    if (live.mtimeMs !== saved.mtimeMs || live.size !== saved.size || live.digest !== saved.digest)
+        return "modified";
+    return null;
+}
+function lost(reason) {
+    return { outcome: "lost", reason };
+}
+/** Remaining lifetime of a durable watch; a watch with no recorded expiry keeps its default window. */
+function remainingMs(monitor, now) {
+    if (monitor.expiresAt === null)
+        return DEFAULT_RESTORED_WATCH_MS;
+    return Math.max(1, monitor.expiresAt - now);
+}
+const DEFAULT_RESTORED_WATCH_MS = 300_000;
+/**
+ * Build the `checkpointed-file` restore handler. It re-registers the watch under its original
+ * `mon_` id and approved parent (so the permission decision still holds), then reports at most
+ * one detached-change line. Returns `lost` when the path is gone or unreadable, `restored` otherwise.
+ */
+export function createCheckpointedFileRestoreHandler(deps) {
+    const now = deps.now ?? Date.now;
+    return async (monitor) => {
+        if (monitor.runtimeKind !== "file" || monitor.path === undefined || monitor.cwd === undefined) {
+            return lost(`monitor ${monitor.monitorId} is not a restorable file watch`);
+        }
+        const saved = monitor.lastCheckpoint;
+        if (saved === null)
+            return lost(`monitor ${monitor.monitorId} has no checkpoint to compare against`);
+        // A watch whose file existed at checkpoint time but is gone or unreadable now cannot be
+        // resumed; probe BEFORE re-registering so a lost restore never leaves a live watch behind.
+        if (saved.present) {
+            try {
+                const target = await stat(resolve(monitor.cwd, monitor.path));
+                if (!target.isFile())
+                    return lost(`watched path is no longer a regular file: ${monitor.path}`);
+            }
+            catch (error) {
+                return lost(`watched path is gone: ${monitor.path} (${error instanceof Error ? error.message : error})`);
+            }
+        }
+        let runtimeId;
+        try {
+            const registered = await deps.registry.registerFile({
+                description: monitor.description,
+                path: monitor.path,
+                monitorId: monitor.monitorId,
+                event: monitor.event ?? "create",
+                timeoutMs: remainingMs(monitor, now()),
+                cwd: monitor.cwd,
+                // Preserve the parent approved at permission time: registerFile re-checks it.
+                ...(monitor.approvedParent !== undefined ? { approvedParent: monitor.approvedParent } : {}),
+                // The persisted deadline rides through verbatim; a restore never extends it.
+                ...(monitor.expiresAt !== null ? { expiresAt: monitor.expiresAt } : {}),
+            });
+            runtimeId = registered.id;
+        }
+        catch (error) {
+            return lost(`cannot re-watch ${monitor.path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const live = deps.registry.fileCheckpoint(runtimeId);
+        if (live === undefined)
+            return lost(`monitor ${monitor.monitorId} settled before its checkpoint was compared`);
+        const change = classifyDetachedChange(saved, live);
+        if (change === "gone") {
+            // Lost the race with a deletion between the probe and re-registration: report lost, not a
+            // change, and settle the watch just registered so a lost restore leaves nothing behind.
+            await deps.registry.stopFile(runtimeId);
+            return lost(`watched path is gone: ${monitor.path}`);
+        }
+        deps.bindMonitorId?.(monitor.monitorId, runtimeId);
+        if (change !== null)
+            deps.registry.emitFileLine(runtimeId, `changed while detached: ${change} ${monitor.path}`);
+        // Re-checkpoint on every restore: after `replaced` this is the new identity, and otherwise
+        // it re-states the tuple the next restart compares against.
+        deps.writer?.scheduleCheckpoint(monitor.monitorId, live);
+        return { outcome: "restored" };
+    };
+}
+//# sourceMappingURL=durable-file.js.map

package/dist/core/extensions/builtin/terminal/durable-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-file.js","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/durable-file.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `checkpointed-file` durability class: the restore handler that makes a persistent file\n * watch survive a restart. On create the monitor tool persists the registry's own identity\n * tuple (dev/ino/size/mtimeMs/digest/present) as the manifest checkpoint; here that checkpoint\n * is compared ONCE against the file as it is now, and any change that happened while the process\n * was gone is reported as EXACTLY ONE line through the registry's normal event sink — so the\n * notifier's coalescing and wake budget apply to it exactly as they do to a live watch event.\n *\n * `digest` is load-bearing: without it a same-size, same-mtime rewrite is invisible across a restart.\n */\n\nimport { stat } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport type { MonitorRegistry } from \"./monitor-registry.ts\";\nimport type { RestoreHandler, RestoreHandlerResult } from \"./restore.ts\";\nimport type { ManifestMonitor, TerminalManifestCheckpoint, TerminalManifestWriter } from \"./terminal-manifest.ts\";\n\n/**\n * What a detached change is reported as. `null` means the file is byte-identical to the checkpoint;\n * `\"gone\"` means it existed at checkpoint time and does not now, which is not restorable.\n */\nexport type DetachedChange = \"created\" | \"replaced\" | \"modified\" | \"gone\" | null;\n\n/** Only what the handler needs, so a caller can hand it a narrower registry/writer. */\nexport interface CheckpointedFileRestoreDeps {\n\treadonly registry: Pick<MonitorRegistry, \"registerFile\" | \"fileCheckpoint\" | \"emitFileLine\" | \"stopFile\">;\n\t/** Optional: the durable checkpoint is re-persisted through the writer when one is bound. */\n\treadonly writer?: Pick<TerminalManifestWriter, \"scheduleCheckpoint\">;\n\t/** Optional: re-bind the stable `mon_` id to its fresh runtime id so kill_bash keeps resolving it. */\n\treadonly bindMonitorId?: (monitorId: string, runtimeId: string) => void;\n\treadonly now?: () => number;\n}\n\n/** The live tuple `registry.fileCheckpoint` returns; identical in shape to the persisted checkpoint. */\ntype LiveCheckpoint = NonNullable<ReturnType<MonitorRegistry[\"fileCheckpoint\"]>>;\n\n/**\n * The single comparison, run once per restore. `created` and `replaced` outrank `modified`:\n * an absent→present transition or a new dev/ino is a stronger statement about the same file.\n */\nexport function classifyDetachedChange(saved: TerminalManifestCheckpoint, live: LiveCheckpoint): DetachedChange {\n\tif (!saved.present) return live.present ? \"created\" : null;\n\tif (!live.present) return \"gone\";\n\tif (live.dev !== saved.dev || live.ino !== saved.ino) return \"replaced\";\n\tif (live.mtimeMs !== saved.mtimeMs || live.size !== saved.size || live.digest !== saved.digest) return \"modified\";\n\treturn null;\n}\n\nfunction lost(reason: string): RestoreHandlerResult {\n\treturn { outcome: \"lost\", reason };\n}\n\n/** Remaining lifetime of a durable watch; a watch with no recorded expiry keeps its default window. */\nfunction remainingMs(monitor: ManifestMonitor, now: number): number {\n\tif (monitor.expiresAt === null) return DEFAULT_RESTORED_WATCH_MS;\n\treturn Math.max(1, monitor.expiresAt - now);\n}\n\nconst DEFAULT_RESTORED_WATCH_MS = 300_000;\n\n/**\n * Build the `checkpointed-file` restore handler. It re-registers the watch under its original\n * `mon_` id and approved parent (so the permission decision still holds), then reports at most\n * one detached-change line. Returns `lost` when the path is gone or unreadable, `restored` otherwise.\n */\nexport function createCheckpointedFileRestoreHandler(deps: CheckpointedFileRestoreDeps): RestoreHandler {\n\tconst now = deps.now ?? Date.now;\n\treturn async (monitor: ManifestMonitor): Promise<RestoreHandlerResult> => {\n\t\tif (monitor.runtimeKind !== \"file\" || monitor.path === undefined || monitor.cwd === undefined) {\n\t\t\treturn lost(`monitor ${monitor.monitorId} is not a restorable file watch`);\n\t\t}\n\t\tconst saved = monitor.lastCheckpoint;\n\t\tif (saved === null) return lost(`monitor ${monitor.monitorId} has no checkpoint to compare against`);\n\t\t// A watch whose file existed at checkpoint time but is gone or unreadable now cannot be\n\t\t// resumed; probe BEFORE re-registering so a lost restore never leaves a live watch behind.\n\t\tif (saved.present) {\n\t\t\ttry {\n\t\t\t\tconst target = await stat(resolve(monitor.cwd, monitor.path));\n\t\t\t\tif (!target.isFile()) return lost(`watched path is no longer a regular file: ${monitor.path}`);\n\t\t\t} catch (error) {\n\t\t\t\treturn lost(`watched path is gone: ${monitor.path} (${error instanceof Error ? error.message : error})`);\n\t\t\t}\n\t\t}\n\n\t\tlet runtimeId: string;\n\t\ttry {\n\t\t\tconst registered = await deps.registry.registerFile({\n\t\t\t\tdescription: monitor.description,\n\t\t\t\tpath: monitor.path,\n\t\t\t\tmonitorId: monitor.monitorId,\n\t\t\t\tevent: monitor.event ?? \"create\",\n\t\t\t\ttimeoutMs: remainingMs(monitor, now()),\n\t\t\t\tcwd: monitor.cwd,\n\t\t\t\t// Preserve the parent approved at permission time: registerFile re-checks it.\n\t\t\t\t...(monitor.approvedParent !== undefined ? { approvedParent: monitor.approvedParent } : {}),\n\t\t\t\t// The persisted deadline rides through verbatim; a restore never extends it.\n\t\t\t\t...(monitor.expiresAt !== null ? { expiresAt: monitor.expiresAt } : {}),\n\t\t\t});\n\t\t\truntimeId = registered.id;\n\t\t} catch (error) {\n\t\t\treturn lost(`cannot re-watch ${monitor.path}: ${error instanceof Error ? error.message : String(error)}`);\n\t\t}\n\n\t\tconst live = deps.registry.fileCheckpoint(runtimeId);\n\t\tif (live === undefined) return lost(`monitor ${monitor.monitorId} settled before its checkpoint was compared`);\n\n\t\tconst change = classifyDetachedChange(saved, live);\n\t\tif (change === \"gone\") {\n\t\t\t// Lost the race with a deletion between the probe and re-registration: report lost, not a\n\t\t\t// change, and settle the watch just registered so a lost restore leaves nothing behind.\n\t\t\tawait deps.registry.stopFile(runtimeId);\n\t\t\treturn lost(`watched path is gone: ${monitor.path}`);\n\t\t}\n\n\t\tdeps.bindMonitorId?.(monitor.monitorId, runtimeId);\n\t\tif (change !== null) deps.registry.emitFileLine(runtimeId, `changed while detached: ${change} ${monitor.path}`);\n\t\t// Re-checkpoint on every restore: after `replaced` this is the new identity, and otherwise\n\t\t// it re-states the tuple the next restart compares against.\n\t\tdeps.writer?.scheduleCheckpoint(monitor.monitorId, live);\n\t\treturn { outcome: \"restored\" };\n\t};\n}\n"]}

package/dist/core/extensions/builtin/terminal/extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/extension.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AAsKrE,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA2GhE;AAED,eAAe,yBAAyB,CAAC"}
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/extension.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AAiXrE,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA4IhE;AAED,eAAe,yBAAyB,CAAC"}

package/dist/core/extensions/builtin/terminal/extension.js

@@ -1,26 +1,43 @@
+import { isAbsolute, join } from "node:path";
 import { getShellEnv } from "../../../../utils/shell.js";
+import { encodedSessionId } from "../../../session-sidecar-store.js";
 import { SettingsManager } from "../../../settings-manager.js";
 import { isAnthropicBashEnabled } from "../anthropic-bash/index.js";
 import { isEvalOnlyRouting } from "../eval-only-routing.js";
 import { TERMINAL_MONITOR_STATE_EVENT, WAKE_SOURCE_STATE_EVENT } from "../monitor-state-event.js";
+import { createRestartableCommandHandler } from "./durable-command.js";
+import { createCheckpointedFileRestoreHandler } from "./durable-file.js";
+import { acquireTerminalLease, releaseTerminalLease } from "./manifest-lease.js";
 import { MonitorNotifier } from "./monitor-notify.js";
 import { MONITOR_STATUS_KEY } from "./monitor-status.js";
 import { MonitorStatusTicker } from "./monitor-status-ticker.js";
-import { TerminalNotifier } from "./notify.js";
+import { getTerminalNotificationDelivery, TerminalNotifier } from "./notify.js";
 import { buildTerminalPromptSection } from "./prompt.js";
+import { reapplyPersistedMute, restoreTerminalState, } from "./restore.js";
 import { claimParkedBundle, parkBundle, TerminalSessionBundle, teardownParkedBundle, } from "./session-bundle.js";
 import { loadTerminalSettings, TERMINAL_SETTINGS_DEFAULTS } from "./settings.js";
 import { TERMINAL_BASH_TOOL, TERMINAL_COMPANION_TOOLS } from "./shared.js";
+import { TerminalManifestWriter } from "./terminal-manifest.js";
 import { createPtyBashTool } from "./tools/bash.js";
 import { createBashInputTool } from "./tools/bash-input.js";
 import { createBashOutputTool } from "./tools/bash-output.js";
 import { createBashResizeTool } from "./tools/bash-resize.js";
 import { createKillBashTool } from "./tools/kill-bash.js";
-import { createMonitorTool } from "./tools/monitor.js";
+import { bindTerminalManifestWriter, createMonitorTool, unbindTerminalManifestWriter } from "./tools/monitor.js";
 /** Tests and SDK callers may hand partial contexts without a session manager. */
 function sessionKeyOf(ctx) {
     return ctx?.sessionManager?.getSessionId?.();
 }
+/**
+ * Per-session persistence dir for the terminal lease + manifest; undefined when the context
+ * carries no durable session dir (SDK/in-memory sessions must not persist terminal state).
+ */
+function terminalStateDir(ctx) {
+    const sessionDir = ctx?.sessionManager?.getSessionDir?.();
+    if (sessionDir === undefined || sessionDir.length === 0 || !isAbsolute(sessionDir))
+        return undefined;
+    return join(sessionDir, "extensions", "terminal");
+}
 function createBundle(state) {
     return new TerminalSessionBundle({
         maxSessions: state.settings.maxSessions,
@@ -53,6 +70,8 @@ function bundleSinks(pi, state) {
                     startedAtMs: entry.startedAtMs,
                 })),
             });
+            if (state.manifestWriter)
+                void state.manifestWriter.observeMonitorState(snapshot);
         },
         onBackgroundState: (snapshot) => {
             pi.events?.emit(WAKE_SOURCE_STATE_EVENT, {
@@ -60,8 +79,22 @@ function bundleSinks(pi, state) {
                 activeCount: snapshot.length,
                 items: snapshot,
             });
+            const writer = state.manifestWriter;
+            if (!writer)
+                return;
+            for (const entry of snapshot) {
+                if (state.recordedBackgroundIds.has(entry.id))
+                    continue;
+                state.recordedBackgroundIds.add(entry.id);
+                void writer.recordBackgroundStart(entry.id, entry.description ?? entry.id, entry.startedAtMs);
+            }
+        },
+        onBackgroundExit: (id, runtime) => {
+            state.recordedBackgroundIds.delete(id);
+            if (state.manifestWriter)
+                void state.manifestWriter.recordBackgroundExit(id);
+            state.notifier?.notifyCompletion(id, runtime);
         },
-        onBackgroundExit: (id, runtime) => state.notifier?.notifyCompletion(id, runtime),
     };
 }
 function buildToolContext(pi, state) {
@@ -141,6 +174,160 @@ function syncToolset(pi, state) {
     state.steppedAside = stepAside;
     pi.setActiveTools([...active]);
 }
+/** Send one model-visible terminal reminder; suppressed by notify `off` and non-interactive modes. */
+function sendTerminalReminder(pi, state, sentence) {
+    getTerminalNotificationDelivery({
+        sendMessage: (message, options) => pi.sendMessage(message, options),
+        getContext: () => state.ctx,
+        getMode: () => state.settings.notify,
+    })?.send(`<system-reminder>${sentence}</system-reminder>`);
+}
+function clauseWithDescriptions(label, count, descriptions) {
+    return descriptions.length > 0 ? `${label} ${count} (${descriptions.join(", ")})` : `${label} ${count}`;
+}
+/**
+ * The ONE coalesced restore digest. Counts come from the restore orchestrator; descriptions
+ * are attributed per manifest entry so the sentence stays a single message however many
+ * monitors there are. Empty clauses are omitted; undefined when there is nothing to report.
+ */
+function restoreDigestSentence(digest, restoredDescriptions, lostDescriptions) {
+    const clauses = [];
+    if (digest.restored > 0)
+        clauses.push(clauseWithDescriptions("restored", digest.restored, restoredDescriptions));
+    if (digest.lost > 0)
+        clauses.push(clauseWithDescriptions("lost", digest.lost, lostDescriptions));
+    if (digest.expired > 0)
+        clauses.push(`expired ${digest.expired}`);
+    if (digest.muted > 0)
+        clauses.push(`${digest.muted} still muted`);
+    if (clauses.length === 0)
+        return undefined;
+    return `Terminal state after restart: ${clauses.join("; ")}.`;
+}
+/**
+ * Non-reload startup: acquire the persistence lease, then restore from the manifest and
+ * deliver EXACTLY ONE coalesced digest. A live foreign holder keeps its lease and gets one
+ * attached-elsewhere reminder; an unreadable manifest fails closed with one notice and no
+ * restore attempt. Only the lease owner records manifest state afterwards.
+ */
+async function adoptPersistedTerminalState(pi, state, toolCtx, bundle, sessionKey) {
+    const ctx = state.ctx;
+    const dir = terminalStateDir(ctx);
+    if (dir === undefined || !ctx?.sessionManager)
+        return;
+    const lease = await acquireTerminalLease({ dir, encodedSessionId: sessionKey });
+    if (!lease.acquired) {
+        sendTerminalReminder(pi, state, `Terminal monitors for this session are attached in another live process (pid ${lease.holder.pid}); nothing was restored here.`);
+        return;
+    }
+    state.lease = { path: lease.path, pid: lease.pid };
+    const writer = new TerminalManifestWriter({ session: ctx.sessionManager });
+    state.manifestWriter = writer;
+    state.recordedBackgroundIds.clear();
+    bindTerminalManifestWriter(sessionKey, writer);
+    // The real durability handlers, built from what this restore site already owns: the live
+    // registry/manager of the bundle created for this generation, plus the manifest writer.
+    // Each monitor's REAL outcome is recorded so the digest attributes descriptions correctly.
+    const nowMs = Date.now();
+    const outcomesById = new Map();
+    const registry = bundle.monitors;
+    const record = (handler) => {
+        return async (monitor) => {
+            const result = await handler(monitor);
+            outcomesById.set(monitor.monitorId, result.outcome);
+            // Re-adopt every entry that is LIVE in this generation, so the next persist rewrites
+            // the manifest with it instead of erasing it: `restored` and `muted` both describe a
+            // live monitor (a mute only silences delivery). `lost`/`expired`/`attachedElsewhere`
+            // are deliberately not adopted — nothing is running for them here.
+            if (result.outcome === "restored" || result.outcome === "muted") {
+                writer.adoptRestored(monitor);
+                // Re-bind the persisted fire budget so a restart cannot hand the watch a fresh window.
+                registry.adoptFireWindow(monitor.monitorId, monitor.fireWindow);
+            }
+            return result;
+        };
+    };
+    const restartableCommand = createRestartableCommandHandler({ ctx: toolCtx, registry });
+    // The file handler re-binds the mon_ id to the fresh runtime id; capture that id here so a
+    // persisted mute is re-applied by the runtime id the registry can actually resolve.
+    let freshFileRuntimeId;
+    const checkpointedFile = createCheckpointedFileRestoreHandler({
+        registry,
+        writer,
+        bindMonitorId: (monitorId, runtimeId) => {
+            freshFileRuntimeId = runtimeId;
+            bundle.manager.bindMonitorId(monitorId, runtimeId);
+        },
+        now: () => nowMs,
+    });
+    const handlers = {
+        "restartable-command": record(restartableCommand),
+        "checkpointed-file": record(async (monitor) => {
+            freshFileRuntimeId = undefined;
+            const result = await checkpointedFile(monitor);
+            if (result.outcome !== "restored" || freshFileRuntimeId === undefined)
+                return result;
+            return { ...result, outcome: reapplyPersistedMute(registry, monitor, freshFileRuntimeId) };
+        }),
+    };
+    const digest = await restoreTerminalState({ manifest: writer.store, handlers, now: () => nowMs });
+    let manifest = null;
+    let unreadable = digest.storeError;
+    if (!unreadable) {
+        try {
+            manifest = await writer.store.read();
+        }
+        catch {
+            unreadable = true;
+        }
+    }
+    if (unreadable) {
+        sendTerminalReminder(pi, state, "Terminal state after restart: the persisted terminal manifest is corrupt; nothing was restored here (fail closed).");
+        return;
+    }
+    if (manifest === null)
+        return; // nothing was ever persisted for this session
+    const restoredDescriptions = [];
+    const lostDescriptions = [];
+    for (const monitor of manifest.monitors) {
+        // Same boundary as the restore orchestrator: at the deadline the entry is expired.
+        if (monitor.expiresAt !== null && monitor.expiresAt <= nowMs)
+            continue;
+        const outcome = outcomesById.get(monitor.monitorId);
+        // Only `restored` and `lost` carry descriptions; a muted restore is reported by its own
+        // count clause, so naming it under either list would desync the clause counts.
+        if (outcome === "restored")
+            restoredDescriptions.push(monitor.description);
+        else if (outcome === undefined || outcome === "lost")
+            lostDescriptions.push(monitor.description);
+    }
+    for (const background of manifest.backgroundSessions)
+        lostDescriptions.push(background.command);
+    const sentence = restoreDigestSentence(digest, restoredDescriptions, lostDescriptions);
+    if (sentence !== undefined)
+        sendTerminalReminder(pi, state, sentence);
+}
+/** Detach the manifest recorder without writing (a reload keeps live state instead). */
+function detachManifestWriter(state, sessionKey) {
+    state.manifestWriter = null;
+    state.recordedBackgroundIds.clear();
+    if (sessionKey !== undefined)
+        unbindTerminalManifestWriter(sessionKey);
+}
+/**
+ * Shutdown view of the manifest: recordShutdown absorbs pending checkpoints, marks every
+ * live monitor `suspended`, and persists in one write. Detach FIRST so bundle teardown's
+ * empty-registry sync cannot touch the recorder afterwards.
+ */
+async function suspendAndFlushManifest(state, sessionKey) {
+    const writer = state.manifestWriter;
+    // Final live-state sync: the shutdown write must carry each watch's burned fire window.
+    if (writer && state.bundle)
+        await writer.observeMonitorState(state.bundle.monitors.snapshot());
+    detachManifestWriter(state, sessionKey);
+    if (writer)
+        await writer.recordShutdown();
+}
 export function registerTerminalExtension(pi) {
     const state = {
         bundle: null,
@@ -159,6 +346,9 @@ export function registerTerminalExtension(pi) {
         shellPath: undefined,
         steppedAside: false,
         noticeShown: false,
+        lease: null,
+        manifestWriter: null,
+        recordedBackgroundIds: new Set(),
     };
     const toolCtx = buildToolContext(pi, state);
     pi.registerTool(createPtyBashTool(toolCtx));
@@ -201,6 +391,19 @@ export function registerTerminalExtension(pi) {
         }
         state.bundle ??= createBundle(state);
         state.bundle.bind(bundleSinks(pi, state));
+        if (event.reason === "reload") {
+            // Park/claim and the lease stay untouched: the same pid keeps holding it. The
+            // reload generation only rebinds the recorder so manifest coverage continues.
+            if (sessionKey !== undefined && terminalStateDir(ctx) !== undefined) {
+                const writer = new TerminalManifestWriter({ session: ctx.sessionManager });
+                state.manifestWriter = writer;
+                state.recordedBackgroundIds.clear();
+                bindTerminalManifestWriter(sessionKey, writer);
+            }
+        }
+        else if (sessionKey !== undefined) {
+            await adoptPersistedTerminalState(pi, state, toolCtx, state.bundle, sessionKey);
+        }
         syncToolset(pi, state);
     });
     pi.on("model_select", async (event, ctx) => {
@@ -234,10 +437,30 @@ export function registerTerminalExtension(pi) {
         if (event.reason === "reload" && state.bundle && sessionKey !== undefined) {
             // Keep state.bundle referenced: exit listeners captured by this instance's tool
             // context still route through the shared bundle after the new owner claims it.
+            // The lease is deliberately NOT released: the same pid keeps it across the reload.
+            detachManifestWriter(state, sessionKey);
             state.bundle.park();
             await parkBundle(sessionKey, state.bundle);
             return;
         }
+        if (sessionKey !== undefined)
+            await suspendAndFlushManifest(state, sessionKey);
+        const lease = state.lease;
+        state.lease = null;
+        if (lease !== null) {
+            await releaseTerminalLease(lease);
+        }
+        else if (sessionKey !== undefined) {
+            const dir = terminalStateDir(ctx) ?? terminalStateDir(state.ctx);
+            // A reload generation inherits the pre-reload lease without re-acquiring it;
+            // releasing by (path, own pid) removes exactly that file and no foreign holder's.
+            if (dir !== undefined) {
+                await releaseTerminalLease({
+                    path: join(dir, `${encodedSessionId(sessionKey)}.lease`),
+                    pid: process.pid,
+                });
+            }
+        }
         const bundle = state.bundle;
         state.bundle = null;
         await bundle?.teardown();