@code-yeongyu/senpi 2026.8.28 → 2026.8.30-2

package/dist/core/extensions/builtin/terminal/manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/manager.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\tSessionRegistry,\n\tSessionRegistryCapacityError,\n\ttype TerminalSession,\n\ttype TerminalSessionOptions,\n} from \"@earendil-works/pi-pty\";\nimport { type TerminalRuntimeOptions, TerminalRuntimeSession } from \"./runtime-session.ts\";\nimport { DEFAULT_MAX_SESSIONS } from \"./shared.ts\";\n\nexport { SessionRegistryCapacityError } from \"@earendil-works/pi-pty\";\n\nexport interface TerminalManagerOptions {\n\treadonly maxSessions?: number;\n\treadonly scrollback?: number;\n}\n\nexport interface CreatedTerminalSession {\n\treadonly id: string;\n\treadonly runtime: TerminalRuntimeSession;\n}\n\n/**\n * Owns the live terminal sessions for one agent session. Delegates id allocation,\n * capacity caps, LRU-exited pruning, and tree-kill teardown to the pi-pty\n * {@link SessionRegistry}, while keeping the richer {@link TerminalRuntimeSession}\n * wrappers (screen model + output buffer) in lock-step.\n */\nexport class TerminalManager {\n\tprivate readonly registry: SessionRegistry<TerminalSession>;\n\tprivate readonly runtimes = new Map<string, TerminalRuntimeSession>();\n\tprivate readonly scrollback?: number;\n\n\tconstructor(options: TerminalManagerOptions = {}) {\n\t\tthis.registry = new SessionRegistry<TerminalSession>({\n\t\t\tmaxSessions: options.maxSessions ?? DEFAULT_MAX_SESSIONS,\n\t\t});\n\t\tthis.scrollback = options.scrollback;\n\t}\n\n\tget size(): number {\n\t\treturn this.runtimes.size;\n\t}\n\n\t/** Spawn a new terminal session and register it under an allocated `bash_N` id. */\n\tasync create(command: string, options: TerminalSessionOptions): Promise<CreatedTerminalSession> {\n\t\tconst runtimeOptions: TerminalRuntimeOptions = { ...options, scrollback: this.scrollback };\n\t\tconst runtime = new TerminalRuntimeSession(command, runtimeOptions);\n\t\tlet entry: { id: string };\n\t\ttry {\n\t\t\tentry = await this.registry.create({ command, session: runtime.session });\n\t\t} catch (error) {\n\t\t\truntime.dispose();\n\t\t\truntime.session.kill();\n\t\t\tthrow error;\n\t\t}\n\t\tthis.runtimes.set(entry.id, runtime);\n\t\tthis.reconcileRuntimes();\n\t\treturn { id: entry.id, runtime };\n\t}\n\n\t/** Look up a live-or-exited session, refreshing its LRU timestamp. */\n\tget(id: string): TerminalRuntimeSession | null {\n\t\tconst entry = this.registry.get(id);\n\t\tif (!entry) return null;\n\t\treturn this.runtimes.get(id) ?? null;\n\t}\n\n\tlist(): { id: string; runtime: TerminalRuntimeSession }[] {\n\t\tconst result: { id: string; runtime: TerminalRuntimeSession }[] = [];\n\t\tfor (const entry of this.registry.list()) {\n\t\t\tconst runtime = this.runtimes.get(entry.id);\n\t\t\tif (runtime) result.push({ id: entry.id, runtime });\n\t\t}\n\t\treturn result;\n\t}\n\n\t/** Tree-kill one session; the exited entry is kept for a final output read until swept. */\n\tasync stop(id: string): Promise<boolean> {\n\t\tconst stopped = await this.registry.stop(id);\n\t\tthis.reconcileRuntimes();\n\t\treturn stopped;\n\t}\n\n\t/** Tree-kill every session and dispose all runtime wrappers. */\n\tasync teardown(): Promise<void> {\n\t\tawait this.registry.teardown();\n\t\tfor (const runtime of this.runtimes.values()) runtime.dispose();\n\t\tthis.runtimes.clear();\n\t}\n\n\t/** Dispose runtime wrappers whose registry entry was pruned (capacity/LRU eviction). */\n\tprivate reconcileRuntimes(): void {\n\t\tconst liveIds = new Set(this.registry.list().map((entry) => entry.id));\n\t\tfor (const [id, runtime] of this.runtimes) {\n\t\t\tif (liveIds.has(id)) continue;\n\t\t\truntime.dispose();\n\t\t\tthis.runtimes.delete(id);\n\t\t}\n\t}\n}\n\nexport function isCapacityError(error: unknown): error is SessionRegistryCapacityError {\n\treturn error instanceof SessionRegistryCapacityError;\n}\n"]}
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/manager.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\tSessionRegistry,\n\tSessionRegistryCapacityError,\n\ttype TerminalSession,\n\ttype TerminalSessionOptions,\n} from \"@earendil-works/pi-pty\";\nimport { type TerminalRuntimeOptions, TerminalRuntimeSession } from \"./runtime-session.ts\";\nimport { DEFAULT_MAX_SESSIONS } from \"./shared.ts\";\n\nexport { SessionRegistryCapacityError } from \"@earendil-works/pi-pty\";\n\nexport interface TerminalManagerOptions {\n\treadonly maxSessions?: number;\n\treadonly scrollback?: number;\n}\n\nexport interface CreatedTerminalSession {\n\treadonly id: string;\n\treadonly runtime: TerminalRuntimeSession;\n}\n\n/**\n * Owns the live terminal sessions for one agent session. Delegates id allocation,\n * capacity caps, LRU-exited pruning, and tree-kill teardown to the pi-pty\n * {@link SessionRegistry}, while keeping the richer {@link TerminalRuntimeSession}\n * wrappers (screen model + output buffer) in lock-step.\n */\nexport class TerminalManager {\n\tprivate readonly registry: SessionRegistry<TerminalSession>;\n\tprivate readonly runtimes = new Map<string, TerminalRuntimeSession>();\n\tprivate readonly scrollback?: number;\n\tprivate readonly maxSessions: number;\n\tprivate readonly exited = new Set<string>();\n\tprivate reservations = 0;\n\n\tconstructor(options: TerminalManagerOptions = {}) {\n\t\tthis.maxSessions = options.maxSessions ?? DEFAULT_MAX_SESSIONS;\n\t\tthis.registry = new SessionRegistry<TerminalSession>({ maxSessions: this.maxSessions });\n\t\tthis.scrollback = options.scrollback;\n\t}\n\n\tget size(): number {\n\t\treturn this.runtimes.size;\n\t}\n\n\tget activeSize(): number {\n\t\tthis.reconcileRuntimes();\n\t\treturn this.runtimes.size - this.exited.size + this.reservations;\n\t}\n\n\treserve(): (() => void) | null {\n\t\tthis.reconcileRuntimes();\n\t\tif (this.runtimes.size - this.exited.size + this.reservations >= this.maxSessions) return null;\n\t\tthis.reservations += 1;\n\t\tlet released = false;\n\t\treturn () => {\n\t\t\tif (released) return;\n\t\t\treleased = true;\n\t\t\tthis.reservations -= 1;\n\t\t};\n\t}\n\n\t/** Spawn a new terminal session and register it under an allocated `bash_N` id. */\n\tasync create(command: string, options: TerminalSessionOptions): Promise<CreatedTerminalSession> {\n\t\tconst release = this.reserve();\n\t\tif (!release) throw new SessionRegistryCapacityError(this.maxSessions);\n\t\tconst runtimeOptions: TerminalRuntimeOptions = { ...options, scrollback: this.scrollback };\n\t\tconst runtime = new TerminalRuntimeSession(command, runtimeOptions);\n\t\tlet entry: { id: string };\n\t\ttry {\n\t\t\tentry = await this.registry.create({ command, session: runtime.session });\n\t\t} catch (error) {\n\t\t\trelease();\n\t\t\truntime.dispose();\n\t\t\truntime.session.kill();\n\t\t\tthrow error;\n\t\t}\n\t\tthis.runtimes.set(entry.id, runtime);\n\t\truntime.session.onExit(() => {\n\t\t\tthis.exited.add(entry.id);\n\t\t});\n\t\trelease();\n\t\tthis.reconcileRuntimes();\n\t\treturn { id: entry.id, runtime };\n\t}\n\n\t/** Look up a live-or-exited session, refreshing its LRU timestamp. */\n\tget(id: string): TerminalRuntimeSession | null {\n\t\tconst entry = this.registry.get(id);\n\t\tif (!entry) return null;\n\t\treturn this.runtimes.get(id) ?? null;\n\t}\n\n\tlist(): { id: string; runtime: TerminalRuntimeSession }[] {\n\t\tconst result: { id: string; runtime: TerminalRuntimeSession }[] = [];\n\t\tfor (const entry of this.registry.list()) {\n\t\t\tconst runtime = this.runtimes.get(entry.id);\n\t\t\tif (runtime) result.push({ id: entry.id, runtime });\n\t\t}\n\t\treturn result;\n\t}\n\n\t/** Tree-kill one session; the exited entry is kept for a final output read until swept. */\n\tasync stop(id: string): Promise<boolean> {\n\t\tconst stopped = await this.registry.stop(id);\n\t\tthis.reconcileRuntimes();\n\t\treturn stopped;\n\t}\n\n\t/** Tree-kill every session and dispose all runtime wrappers. */\n\tasync teardown(): Promise<void> {\n\t\tawait this.registry.teardown();\n\t\tfor (const runtime of this.runtimes.values()) runtime.dispose();\n\t\tthis.runtimes.clear();\n\t\tthis.exited.clear();\n\t}\n\n\t/** Dispose runtime wrappers whose registry entry was pruned (capacity/LRU eviction). */\n\tprivate reconcileRuntimes(): void {\n\t\tconst liveIds = new Set(this.registry.list().map((entry) => entry.id));\n\t\tfor (const [id, runtime] of this.runtimes) {\n\t\t\tif (liveIds.has(id)) continue;\n\t\t\truntime.dispose();\n\t\t\tthis.runtimes.delete(id);\n\t\t\tthis.exited.delete(id);\n\t\t}\n\t}\n}\n\nexport function isCapacityError(error: unknown): error is SessionRegistryCapacityError {\n\treturn error instanceof SessionRegistryCapacityError;\n}\n"]}

package/dist/core/extensions/builtin/terminal/monitor-permission.d.ts

@@ -0,0 +1,8 @@
+export declare const APPROVED_MONITOR_PARENT: unique symbol;
+export type MonitorPermissionInput = Record<string, unknown> & {
+    [APPROVED_MONITOR_PARENT]?: string;
+};
+export declare function setApprovedMonitorParent(input: Record<string, unknown>, parent: string): void;
+export declare function getApprovedMonitorParent(input: Record<string, unknown>): string | undefined;
+export declare function monitorParent(path: string): string;
+//# sourceMappingURL=monitor-permission.d.ts.map

package/dist/core/extensions/builtin/terminal/monitor-permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor-permission.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/monitor-permission.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC9D,CAAC,uBAAuB,CAAC,CAAC,EAAE,MAAM,CAAC;CACnC,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAM7F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAE3F;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/core/extensions/builtin/terminal/monitor-permission.js

@@ -0,0 +1,16 @@
+import { dirname } from "node:path";
+export const APPROVED_MONITOR_PARENT = Symbol("approved-monitor-parent");
+export function setApprovedMonitorParent(input, parent) {
+    Object.defineProperty(input, APPROVED_MONITOR_PARENT, {
+        configurable: true,
+        value: parent,
+        writable: false,
+    });
+}
+export function getApprovedMonitorParent(input) {
+    return input[APPROVED_MONITOR_PARENT];
+}
+export function monitorParent(path) {
+    return dirname(path);
+}
+//# sourceMappingURL=monitor-permission.js.map

package/dist/core/extensions/builtin/terminal/monitor-permission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor-permission.js","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/monitor-permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC;AAMzE,MAAM,UAAU,wBAAwB,CAAC,KAA8B,EAAE,MAAc;IACtF,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,uBAAuB,EAAE;QACrD,YAAY,EAAE,IAAI;QAClB,KAAK,EAAE,MAAM;QACb,QAAQ,EAAE,KAAK;KACf,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAA8B;IACtE,OAAQ,KAAgC,CAAC,uBAAuB,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY;IACzC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC","sourcesContent":["import { dirname } from \"node:path\";\n\nexport const APPROVED_MONITOR_PARENT = Symbol(\"approved-monitor-parent\");\n\nexport type MonitorPermissionInput = Record<string, unknown> & {\n\t[APPROVED_MONITOR_PARENT]?: string;\n};\n\nexport function setApprovedMonitorParent(input: Record<string, unknown>, parent: string): void {\n\tObject.defineProperty(input, APPROVED_MONITOR_PARENT, {\n\t\tconfigurable: true,\n\t\tvalue: parent,\n\t\twritable: false,\n\t});\n}\n\nexport function getApprovedMonitorParent(input: Record<string, unknown>): string | undefined {\n\treturn (input as MonitorPermissionInput)[APPROVED_MONITOR_PARENT];\n}\n\nexport function monitorParent(path: string): string {\n\treturn dirname(path);\n}\n"]}

package/dist/core/extensions/builtin/terminal/monitor-registry.d.ts

@@ -23,6 +23,16 @@ export interface MonitorSnapshotEntry {
 export interface MonitorRegistryOptions {
     /** Observes every registry transition (register/pause/rearm/settle/dispose) with the live snapshot. */
     readonly onChange?: (snapshot: readonly MonitorSnapshotEntry[]) => void;
+    /** Reserves one shared terminal capacity slot for a native watch. */
+    readonly reserve?: () => (() => void) | null;
+}
+export interface RegisterFileMonitorOptions {
+    readonly description: string;
+    readonly path: string;
+    readonly event: "create" | "modify";
+    readonly timeoutMs: number;
+    readonly cwd: string;
+    readonly approvedParent?: string;
 }
 export interface RegisterMonitorOptions {
     readonly id: string;
@@ -39,6 +49,9 @@ export declare class MonitorRegistry {
     #private;
     constructor(emit: (event: MonitorEvent) => void, options?: MonitorRegistryOptions);
     snapshot(): readonly MonitorSnapshotEntry[];
+    registerFile(options: RegisterFileMonitorOptions): Promise<string>;
+    stopFile(id: string): Promise<boolean>;
+    stopAllFiles(): Promise<number>;
     register(options: RegisterMonitorOptions): void;
     pauseAll(): string[];
     rearm(id: string): MonitorRearmResult;

package/dist/core/extensions/builtin/terminal/monitor-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"monitor-registry.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/monitor-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAGnE,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;AAElE,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC;AAExE,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC,uGAAuG;IACvG,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,KAAK,IAAI,CAAC;CACxE;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAeD;;;;GAIG;AACH,qBAAa,eAAe;;gBAKf,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,sBAAsB;IAKjF,QAAQ,IAAI,SAAS,oBAAoB,EAAE;IAS3C,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI;IAwB/C,QAAQ,IAAI,MAAM,EAAE;IAWpB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB;IASrC,OAAO,IAAI,IAAI;CAgDf"}
+{"version":3,"file":"monitor-registry.d.ts","sourceRoot":"","sources":["../../../../../src/core/extensions/builtin/terminal/monitor-registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAGnE,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;AAElE,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC;AAExE,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC,uGAAuG;IACvG,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,KAAK,IAAI,CAAC;IACxE,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAiDD;;;;GAIG;AACH,qBAAa,eAAe;;gBAYf,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,sBAAsB;IAMjF,QAAQ,IAAI,SAAS,oBAAoB,EAAE;IASrC,YAAY,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,MAAM,CAAC;IA+KlE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOtC,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IA2HrC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI;IAwB/C,QAAQ,IAAI,MAAM,EAAE;IAWpB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB;IAUrC,OAAO,IAAI,IAAI;CAyHf"}

package/dist/core/extensions/builtin/terminal/monitor-registry.js

@@ -1,3 +1,7 @@
+import { createHash } from "node:crypto";
+import { watch } from "node:fs";
+import { access, lstat, open, realpath, stat } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 import { describeExit } from "./tools/spawn.js";
 /**
  * Tracks active monitor sessions alongside the terminal manager's existing bash-id registry.
@@ -8,18 +12,351 @@ export class MonitorRegistry {
     #records = new Map();
     #emit;
     #onChange;
+    #reserve;
+    #files = new Map();
+    #nextFileId = 1;
+    #disposed = false;
+    #pendingRegistrations = 0;
+    #pending = new Set();
+    #lifecycle = 0;
     constructor(emit, options) {
         this.#emit = emit;
         this.#onChange = options?.onChange;
+        this.#reserve = options?.reserve;
     }
     snapshot() {
-        return [...this.#records.values()].map((record) => ({
+        return [...this.#records.values(), ...this.#files.values()].map((record) => ({
             id: record.id,
             description: record.description,
             paused: record.paused,
             startedAtMs: record.startedAtMs,
         }));
     }
+    async registerFile(options) {
+        if (this.#disposed)
+            throw new Error("Cannot create file monitor: monitor registry is disposed.");
+        this.#pendingRegistrations += 1;
+        const lifecycle = this.#lifecycle;
+        const release = this.#reserve?.();
+        if (this.#reserve && !release) {
+            this.#pendingRegistrations -= 1;
+            throw new Error("Cannot create file monitor: terminal capacity is already in use.");
+        }
+        const pending = {
+            release: release ?? undefined,
+            abort: new AbortController(),
+            deadline: setTimeout(() => pending.abort.abort(), options.timeoutMs),
+            settled: false,
+        };
+        this.#pending.add(pending);
+        const path = resolve(options.cwd, options.path);
+        const parent = dirname(path);
+        let approvedParent;
+        try {
+            await this.#registrationAwait(pending, access(parent));
+            approvedParent = await this.#registrationAwait(pending, realpath(parent));
+            const approvedParentAtPermission = options.approvedParent;
+            if (approvedParentAtPermission !== undefined && approvedParent !== approvedParentAtPermission) {
+                throw new Error(`Cannot watch file: parent directory changed during permission approval: ${parent}`);
+            }
+            if (this.#disposed)
+                throw new Error("Cannot create file monitor: monitor registry is disposed.");
+        }
+        catch (error) {
+            this.#finishPending(pending);
+            this.#pendingRegistrations -= 1;
+            if (error instanceof Error && error.message.includes("disposed"))
+                throw error;
+            if (error?.code !== "ENOENT") {
+                throw new Error(`Cannot access parent directory ${parent}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            throw new Error(`Cannot watch file: parent directory does not exist: ${parent}`);
+        }
+        let initial = null;
+        let initialHandle;
+        try {
+            const target = await this.#registrationAwait(pending, lstat(path));
+            if (target.isSymbolicLink())
+                throw new Error(`Cannot watch file: target is a symbolic link: ${path}`);
+            initialHandle = await this.#registrationAwait(pending, open(path, "r"), async (handle) => {
+                await handle.close();
+            });
+            initial = await this.#registrationAwait(pending, initialHandle.stat());
+            if (!initial.isFile())
+                throw new Error(`Cannot watch file: target is not a regular file: ${path}`);
+            const resolvedTarget = await this.#registrationAwait(pending, realpath(path));
+            if (resolvedTarget !== join(approvedParent, basename(path)))
+                throw new Error(`Cannot watch file: target identity changed: ${path}`);
+            const rebound = await this.#registrationAwait(pending, lstat(path));
+            if (rebound.isSymbolicLink())
+                throw new Error(`Cannot watch file: target identity changed: ${path}`);
+            const reboundStat = await this.#registrationAwait(pending, stat(path));
+            if (!reboundStat.isFile() || reboundStat.dev !== initial.dev || reboundStat.ino !== initial.ino)
+                throw new Error(`Cannot watch file: target identity changed: ${path}`);
+        }
+        catch (error) {
+            await initialHandle?.close();
+            initialHandle = undefined;
+            if (error?.code !== "ENOENT") {
+                this.#finishPending(pending);
+                this.#pendingRegistrations -= 1;
+                throw error;
+            }
+        }
+        if (this.#disposed || lifecycle !== this.#lifecycle || this.#pendingRegistrations < 1) {
+            this.#finishPending(pending);
+            this.#pendingRegistrations -= 1;
+            throw new Error("Cannot create file monitor: monitor registry is disposed.");
+        }
+        const id = `watch_${this.#nextFileId++}`;
+        let watcher;
+        try {
+            const activationParent = await this.#registrationAwait(pending, realpath(parent));
+            if (activationParent !== approvedParent) {
+                throw new Error(`Cannot watch file: parent directory changed during registration: ${parent}`);
+            }
+            watcher = watch(activationParent, (_kind, name) => {
+                if (!name || basename(String(name)) === basename(path))
+                    void this.#checkFile(id);
+            });
+        }
+        catch (error) {
+            this.#finishPending(pending);
+            this.#pendingRegistrations -= 1;
+            throw new Error(`Cannot watch file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        let registrationError;
+        watcher.on("error", (error) => {
+            registrationError = `watcher error: ${error instanceof Error ? error.message : String(error)}`;
+            const record = this.#files.get(id);
+            if (record)
+                this.#settleFile(record, registrationError);
+        });
+        let registrationCleaned = false;
+        const finishRegistration = () => {
+            if (registrationCleaned)
+                return;
+            registrationCleaned = true;
+            this.#pendingRegistrations -= 1;
+        };
+        const cleanupRegistration = () => {
+            if (registrationCleaned)
+                return;
+            watcher.close();
+            finishRegistration();
+            this.#finishPending(pending);
+        };
+        if (this.#disposed || lifecycle !== this.#lifecycle) {
+            cleanupRegistration();
+            throw new Error("Cannot create file monitor: monitor registry is disposed.");
+        }
+        const canonicalPath = join(approvedParent, basename(path));
+        let digest;
+        try {
+            digest =
+                initial && initialHandle
+                    ? await this.#registrationAwait(pending, this.#digestHandle(initialHandle, pending.abort.signal))
+                    : "";
+        }
+        catch (error) {
+            cleanupRegistration();
+            await initialHandle?.close();
+            initialHandle = undefined;
+            if (registrationError) {
+                this.#emit({ type: "summary", id, description: options.description, summary: registrationError });
+                throw new Error(registrationError);
+            }
+            throw error;
+        }
+        await initialHandle?.close();
+        initialHandle = undefined;
+        if (registrationError) {
+            cleanupRegistration();
+            this.#emit({ type: "summary", id, description: options.description, summary: registrationError });
+            throw new Error(registrationError);
+        }
+        if (this.#disposed || lifecycle !== this.#lifecycle) {
+            cleanupRegistration();
+            throw new Error("Cannot create file monitor: monitor registry is disposed.");
+        }
+        const record = {
+            id,
+            description: options.description,
+            startedAtMs: Date.now(),
+            path,
+            canonicalPath,
+            canonicalParent: approvedParent,
+            event: options.event,
+            watcher,
+            release: release ?? (() => { }),
+            poll: setInterval(() => void this.#checkFile(id), 250),
+            paused: false,
+            settled: false,
+            present: initial !== null,
+            mtimeMs: initial?.mtimeMs ?? 0,
+            size: initial?.size ?? 0,
+            digest,
+            device: initial?.dev ?? 0,
+            inode: initial?.ino ?? 0,
+            pendingChange: false,
+            dirty: false,
+            dirtyPasses: 0,
+            dirtyWindowStartedAt: 0,
+            checking: undefined,
+            deadline: setTimeout(() => {
+                const current = this.#files.get(id);
+                if (current)
+                    this.#settleFile(current, "watcher timed_out");
+            }, options.timeoutMs),
+        };
+        this.#files.set(id, record);
+        finishRegistration();
+        this.#finishPending(pending, true);
+        if (registrationError || this.#disposed || lifecycle !== this.#lifecycle) {
+            this.#settleFile(record, registrationError ?? "watcher killed");
+            throw new Error(registrationError ?? "Cannot create file monitor: monitor registry is disposed.");
+        }
+        this.#notifyChange();
+        return id;
+    }
+    async stopFile(id) {
+        const record = this.#files.get(id);
+        if (!record)
+            return false;
+        this.#settleFile(record, "watcher killed");
+        return true;
+    }
+    async stopAllFiles() {
+        this.#lifecycle += 1;
+        const records = [...this.#files.values()];
+        for (const record of records)
+            this.#settleFile(record, "watcher killed");
+        for (const pending of [...this.#pending])
+            this.#finishPending(pending);
+        return records.length;
+    }
+    #settleFile(record, summary) {
+        if (record.settled)
+            return;
+        record.settled = true;
+        clearInterval(record.poll);
+        clearTimeout(record.deadline);
+        record.watcher.close();
+        record.release();
+        this.#files.delete(record.id);
+        this.#notifyChange();
+        this.#emit({ type: "summary", id: record.id, description: record.description, summary });
+    }
+    async #checkFile(id) {
+        const record = this.#files.get(id);
+        if (!record || record.settled)
+            return;
+        if (record.checking) {
+            record.dirty = true;
+            return;
+        }
+        record.checking = this.#checkFileImpl(record)
+            .catch((error) => {
+            if (!record.settled)
+                this.#settleFile(record, `watcher error: ${error instanceof Error ? error.message : String(error)}`);
+        })
+            .finally(() => {
+            record.checking = undefined;
+            const now = Date.now();
+            if (now - record.dirtyWindowStartedAt >= 1_000) {
+                record.dirtyWindowStartedAt = now;
+                record.dirtyPasses = 0;
+            }
+            if (record.dirty && !record.settled && record.dirtyPasses < 1) {
+                record.dirty = false;
+                record.dirtyPasses += 1;
+                void this.#checkFile(id);
+            }
+            else {
+                record.dirty = false;
+            }
+        });
+        return record.checking;
+    }
+    async #checkFileImpl(record) {
+        if (record.settled)
+            return;
+        let current = null;
+        let handle;
+        try {
+            const currentParent = await realpath(dirname(record.path));
+            if (currentParent !== record.canonicalParent) {
+                this.#settleFile(record, `watcher error: monitored parent changed: ${dirname(record.path)}`);
+                return;
+            }
+            const target = await lstat(record.canonicalPath);
+            if (target.isSymbolicLink())
+                throw new Error(`Cannot watch file: target identity changed: ${record.path}`);
+            const resolvedTarget = await realpath(record.canonicalPath);
+            if (resolvedTarget !== record.canonicalPath)
+                throw new Error(`Cannot watch file: target identity changed: ${record.path}`);
+            handle = await open(record.canonicalPath, "r");
+            const opened = await handle.stat();
+            if (!opened.isFile())
+                throw new Error(`Cannot watch file: target is not a regular file: ${record.path}`);
+            if ((opened.dev !== record.device || opened.ino !== record.inode) && opened.nlink > 1)
+                throw new Error(`Cannot watch file: target identity changed: ${record.path}`);
+            current = opened;
+            const rebound = await lstat(record.canonicalPath);
+            if (rebound.isSymbolicLink())
+                throw new Error(`Cannot watch file: target identity changed: ${record.path}`);
+            const reboundPath = await stat(record.canonicalPath);
+            if (!reboundPath.isFile() || reboundPath.dev !== opened.dev || reboundPath.ino !== opened.ino)
+                throw new Error(`Cannot watch file: target identity changed: ${record.path}`);
+        }
+        catch (error) {
+            await handle?.close();
+            if (error?.code !== "ENOENT") {
+                this.#settleFile(record, `watcher error: ${error instanceof Error ? error.message : String(error)}`);
+                return;
+            }
+        }
+        const present = current !== null;
+        let digest = "";
+        try {
+            digest = present && handle ? await this.#digestHandle(handle) : "";
+            if (present && handle) {
+                const afterDigest = await stat(record.canonicalPath);
+                const opened = await handle.stat();
+                if (afterDigest.dev !== opened.dev || afterDigest.ino !== opened.ino)
+                    throw new Error(`Cannot watch file: target identity changed: ${record.path}`);
+            }
+        }
+        finally {
+            await handle?.close();
+        }
+        const changed = record.event === "create"
+            ? !record.present && present
+            : record.present &&
+                present &&
+                (current.mtimeMs !== record.mtimeMs || current.size !== record.size || digest !== record.digest);
+        record.pendingChange ||= changed;
+        if (!record.present && current) {
+            record.device = current.dev;
+            record.inode = current.ino;
+        }
+        record.present = present;
+        record.mtimeMs = current?.mtimeMs ?? 0;
+        record.size = current?.size ?? 0;
+        record.digest = digest;
+        if (!record.pendingChange || record.paused || record.settled)
+            return;
+        record.pendingChange = false;
+        if (record.settled)
+            return;
+        this.#emit({
+            type: "line",
+            id: record.id,
+            description: record.description,
+            line: `${record.event} ${record.path}`,
+        });
+        this.#settleFile(record, "watcher completed");
+    }
     register(options) {
         const record = {
             id: options.id,
@@ -45,7 +382,7 @@ export class MonitorRegistry {
     }
     pauseAll() {
         const paused = [];
-        for (const record of this.#records.values()) {
+        for (const record of [...this.#records.values(), ...this.#files.values()]) {
             if (record.paused)
                 continue;
             record.paused = true;
@@ -56,21 +393,84 @@ export class MonitorRegistry {
         return paused;
     }
     rearm(id) {
-        const record = this.#records.get(id);
+        const record = this.#records.get(id) ?? this.#files.get(id);
         if (!record)
             return "not_found";
         if (!record.paused)
             return "not_paused";
         record.paused = false;
         this.#notifyChange();
+        if ("pendingChange" in record && record.pendingChange)
+            void this.#checkFile(record.id);
         return "rearmed";
     }
     dispose() {
+        this.#disposed = true;
+        this.#lifecycle += 1;
         for (const record of this.#records.values())
             this.#disposeRecord(record);
+        for (const record of this.#files.values())
+            this.#settleFile(record, "watcher disposed");
+        for (const pending of this.#pending)
+            this.#finishPending(pending);
         this.#records.clear();
         this.#notifyChange();
     }
+    #finishPending(pending, transfer = false) {
+        if (pending.settled)
+            return;
+        pending.settled = true;
+        clearTimeout(pending.deadline);
+        this.#pending.delete(pending);
+        if (transfer)
+            pending.release = undefined;
+        else {
+            pending.abort.abort();
+            pending.release?.();
+        }
+    }
+    async #registrationAwait(pending, operation, lateCleanup) {
+        if (pending.abort.signal.aborted) {
+            void operation.then((value) => lateCleanup?.(value), () => undefined);
+            throw new Error("Cannot create file monitor: registration timed out or was disposed.");
+        }
+        let aborted = false;
+        const abort = new Promise((_, reject) => pending.abort.signal.addEventListener("abort", () => {
+            aborted = true;
+            reject(new Error("Cannot create file monitor: registration timed out or was disposed."));
+        }, { once: true }));
+        const guarded = operation.then((value) => {
+            if (aborted)
+                void lateCleanup?.(value);
+            return value;
+        }, (error) => {
+            if (aborted)
+                return undefined;
+            throw error;
+        });
+        return Promise.race([guarded, abort]);
+    }
+    async #digestHandle(handle, signal) {
+        const SAMPLE_SIZE = 64 * 1024;
+        if (signal?.aborted)
+            throw new Error("file monitor registration cancelled");
+        const metadata = await handle.stat();
+        const hash = createHash("sha256");
+        const first = Buffer.alloc(Math.min(SAMPLE_SIZE, metadata.size));
+        if (first.length > 0) {
+            await handle.read(first, 0, first.length, 0);
+            hash.update(first);
+        }
+        if (metadata.size > SAMPLE_SIZE) {
+            const middle = Buffer.alloc(SAMPLE_SIZE);
+            await handle.read(middle, 0, middle.length, Math.floor((metadata.size - middle.length) / 2));
+            hash.update(middle);
+            const last = Buffer.alloc(SAMPLE_SIZE);
+            await handle.read(last, 0, last.length, metadata.size - last.length);
+            hash.update(last);
+        }
+        return `${metadata.size}:${hash.digest("hex")}`;
+    }
     #notifyChange() {
         this.#onChange?.(this.snapshot());
     }