@caupulican/pi-adaptative 0.81.39 → 0.81.40

package/dist/core/session-image-store.js

@@ -0,0 +1,283 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, opendirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import { attachmentsDir } from "./agent-paths.js";
+const FILE_PREFIX = "pi-clip";
+const MAX_SCANNED_ENTRIES = 10_000;
+const MAX_STORED_FILES = 512;
+const MAX_TOTAL_BYTES = 512 * 1024 * 1024;
+const MAX_IMAGE_BYTES = 50 * 1024 * 1024;
+const MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_SEQUENCE = 999_999;
+const FILE_PATTERN = /^pi-clip-([0-9a-f]{16})-(\d{6})-([0-9a-f]{12})\.(png|jpg|webp|gif)$/;
+function extensionForMimeType(mimeType) {
+    switch (mimeType.split(";", 1)[0]?.trim().toLowerCase()) {
+        case "image/jpeg":
+            return "jpg";
+        case "image/webp":
+            return "webp";
+        case "image/gif":
+            return "gif";
+        default:
+            return "png";
+    }
+}
+function mimeTypeForExtension(extension) {
+    switch (extension) {
+        case "jpg":
+            return "image/jpeg";
+        case "webp":
+            return "image/webp";
+        case "gif":
+            return "image/gif";
+        default:
+            return "image/png";
+    }
+}
+function resolveConfiguredDirectory(directory, cwd) {
+    const trimmed = directory.trim();
+    const expanded = trimmed === "~" ? homedir() : trimmed.replace(/^~(?=[/\\])/, homedir());
+    return resolve(isAbsolute(expanded) ? expanded : resolve(cwd, expanded));
+}
+export function resolveSessionImageDirectory(options) {
+    return options.directory?.trim()
+        ? resolveConfiguredDirectory(options.directory, options.cwd)
+        : attachmentsDir(options.agentDir);
+}
+export class SessionImageStore {
+    directory;
+    sessionKey;
+    now;
+    constructor(options) {
+        this.directory = resolveSessionImageDirectory(options);
+        this.sessionKey = createHash("sha256").update(options.sessionId).digest("hex").slice(0, 16);
+        this.now = options.now ?? Date.now;
+    }
+    /** Validate and durably retain provider-neutral image content, reusing its claimed sequence only
+     * when that sequence already contains the exact same bytes and normalized MIME type. */
+    retainContent(content, preferredSequence) {
+        const compactBase64 = content.data.trim();
+        if (!/^image\/(?:png|jpeg|webp|gif)(?:;|$)/iu.test(content.mimeType.trim())) {
+            throw new Error(`Unsupported image MIME type: ${content.mimeType}`);
+        }
+        if (!/^[A-Za-z0-9+/]*={0,2}$/.test(compactBase64) || compactBase64.length % 4 === 1) {
+            throw new Error("Image content is not valid base64");
+        }
+        const bytes = Buffer.from(compactBase64, "base64");
+        if (bytes.toString("base64").replace(/=+$/u, "") !== compactBase64.replace(/=+$/u, "")) {
+            throw new Error("Image content is not canonical base64");
+        }
+        const normalizedMimeType = mimeTypeForExtension(extensionForMimeType(content.mimeType));
+        if (preferredSequence !== undefined) {
+            const existing = this.read(preferredSequence);
+            if (existing && existing.mimeType === normalizedMimeType && Buffer.from(existing.bytes).equals(bytes)) {
+                return existing;
+            }
+        }
+        return this.write(bytes, normalizedMimeType);
+    }
+    write(bytes, mimeType) {
+        if (bytes.byteLength === 0 || bytes.byteLength > MAX_IMAGE_BYTES) {
+            throw new Error(`Clipboard image must be between 1 byte and ${MAX_IMAGE_BYTES} bytes`);
+        }
+        mkdirSync(this.directory, { recursive: true });
+        const directoryStats = lstatSync(this.directory);
+        if (!directoryStats.isDirectory()) {
+            throw new Error(`Attachment path is not a directory: ${this.directory}`);
+        }
+        const before = this.scan();
+        if (!before.complete) {
+            throw new Error(`Attachment directory exceeds the ${MAX_SCANNED_ENTRIES}-entry inspection bound`);
+        }
+        let sequence = Math.max(0, ...before.entries.filter((entry) => entry.sessionKey === this.sessionKey).map((entry) => entry.sequence));
+        const digest = createHash("sha256").update(bytes).digest("hex").slice(0, 12);
+        const extension = extensionForMimeType(mimeType);
+        let path = "";
+        let written = false;
+        while (sequence < MAX_SEQUENCE) {
+            sequence++;
+            path = resolve(this.directory, `${FILE_PREFIX}-${this.sessionKey}-${String(sequence).padStart(6, "0")}-${digest}.${extension}`);
+            try {
+                writeFileSync(path, bytes, { flag: "wx" });
+                written = true;
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        if (!written) {
+            throw new Error("Clipboard image sequence is exhausted");
+        }
+        try {
+            this.prune(path);
+        }
+        catch (error) {
+            try {
+                unlinkSync(path);
+            }
+            catch { }
+            throw error;
+        }
+        return { sequence, path, mimeType: mimeTypeForExtension(extension), bytes: new Uint8Array(bytes) };
+    }
+    read(sequence) {
+        if (!Number.isSafeInteger(sequence) || sequence < 1 || sequence > MAX_SEQUENCE)
+            return undefined;
+        const scan = this.scan();
+        if (!scan.complete)
+            return undefined;
+        const entry = scan.entries.find((candidate) => candidate.sessionKey === this.sessionKey && candidate.sequence === sequence);
+        return entry ? this.readEntry(entry) : undefined;
+    }
+    readLatest() {
+        const scan = this.scan();
+        if (!scan.complete)
+            return undefined;
+        const entries = scan.entries
+            .filter((entry) => entry.sessionKey === this.sessionKey)
+            .sort((left, right) => right.sequence - left.sequence);
+        for (const entry of entries) {
+            const image = this.readEntry(entry);
+            if (image)
+                return image;
+        }
+        return undefined;
+    }
+    resolveReferences(text) {
+        try {
+            const explicitSequences = [];
+            const explicitPattern = /(?:\[\s*)?(?:image|screenshot|picture|photo)\s*#?\s*(\d{1,6})(?:\s*\])?/gi;
+            for (const match of text.matchAll(explicitPattern)) {
+                const sequence = Number(match[1]);
+                if (!explicitSequences.includes(sequence))
+                    explicitSequences.push(sequence);
+            }
+            const resolved = explicitSequences
+                .map((sequence) => this.read(sequence))
+                .filter((image) => image !== undefined);
+            if (resolved.length === 0 && this.referencesLatestImage(text)) {
+                const latest = this.readLatest();
+                if (latest)
+                    resolved.push(latest);
+            }
+            return resolved.map((image) => ({
+                type: "image",
+                data: Buffer.from(image.bytes).toString("base64"),
+                mimeType: image.mimeType,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    referencesLatestImage(text) {
+        return (/\b(?:the|this|that|latest|last|pasted|attached|clipboard)\s+(?:image|screenshot|picture|photo)\b/i.test(text) ||
+            /\b(?:look at|inspect|review|describe|analy[sz]e|check)\s+(?:(?:the|this|that|latest|last|pasted|attached|clipboard)\s+)?(?:image|screenshot|picture|photo)\b/i.test(text));
+    }
+    readEntry(entry) {
+        try {
+            const stats = lstatSync(entry.path);
+            if (!stats.isFile() || stats.isSymbolicLink() || stats.size < 1 || stats.size > MAX_IMAGE_BYTES)
+                return undefined;
+            const bytes = readFileSync(entry.path);
+            const digest = createHash("sha256").update(bytes).digest("hex").slice(0, 12);
+            if (digest !== entry.digest)
+                return undefined;
+            return {
+                sequence: entry.sequence,
+                path: entry.path,
+                mimeType: entry.mimeType,
+                bytes: new Uint8Array(bytes),
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    scan() {
+        if (!existsSync(this.directory))
+            return { entries: [], complete: true };
+        const entries = [];
+        let scanned = 0;
+        let complete = true;
+        const handle = opendirSync(this.directory);
+        try {
+            while (true) {
+                const directoryEntry = handle.readSync();
+                if (!directoryEntry)
+                    break;
+                if (scanned >= MAX_SCANNED_ENTRIES) {
+                    complete = false;
+                    break;
+                }
+                scanned++;
+                if (!directoryEntry.isFile() || directoryEntry.isSymbolicLink())
+                    continue;
+                const match = FILE_PATTERN.exec(directoryEntry.name);
+                if (!match)
+                    continue;
+                const path = resolve(this.directory, directoryEntry.name);
+                try {
+                    const stats = lstatSync(path);
+                    if (!stats.isFile() || stats.isSymbolicLink())
+                        continue;
+                    entries.push({
+                        path,
+                        sessionKey: match[1],
+                        sequence: Number(match[2]),
+                        digest: match[3],
+                        mimeType: mimeTypeForExtension(match[4]),
+                        bytes: stats.size,
+                        mtimeMs: stats.mtimeMs,
+                    });
+                }
+                catch { }
+            }
+        }
+        finally {
+            handle.closeSync();
+        }
+        return { entries, complete };
+    }
+    prune(protectedPath) {
+        const scan = this.scan();
+        if (!scan.complete) {
+            throw new Error(`Attachment directory exceeds the ${MAX_SCANNED_ENTRIES}-entry inspection bound`);
+        }
+        const now = this.now();
+        for (const entry of scan.entries) {
+            if (entry.path !== protectedPath && now - entry.mtimeMs > MAX_AGE_MS) {
+                try {
+                    unlinkSync(entry.path);
+                }
+                catch { }
+            }
+        }
+        const retained = this.scan();
+        if (!retained.complete) {
+            throw new Error(`Attachment directory exceeds the ${MAX_SCANNED_ENTRIES}-entry inspection bound`);
+        }
+        const oldestFirst = retained.entries.sort((left, right) => left.mtimeMs - right.mtimeMs);
+        let totalBytes = oldestFirst.reduce((total, entry) => total + entry.bytes, 0);
+        let totalFiles = oldestFirst.length;
+        for (const entry of oldestFirst) {
+            if (totalFiles <= MAX_STORED_FILES && totalBytes <= MAX_TOTAL_BYTES)
+                break;
+            if (entry.path === protectedPath)
+                continue;
+            try {
+                unlinkSync(entry.path);
+                totalFiles--;
+                totalBytes -= entry.bytes;
+            }
+            catch { }
+        }
+        if (totalFiles > MAX_STORED_FILES || totalBytes > MAX_TOTAL_BYTES) {
+            throw new Error("Attachment retention bounds could not be enforced");
+        }
+    }
+}
+//# sourceMappingURL=session-image-store.js.map

package/dist/core/session-image-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-image-store.js","sourceRoot":"","sources":["../../src/core/session-image-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, lstatSync, mkdirSync, opendirSync, readFileSync, unlinkSync, writeFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { isAbsolute, resolve } from \"node:path\";\nimport type { ImageContent } from \"@caupulican/pi-ai\";\nimport { attachmentsDir } from \"./agent-paths.ts\";\n\nconst FILE_PREFIX = \"pi-clip\";\nconst MAX_SCANNED_ENTRIES = 10_000;\nconst MAX_STORED_FILES = 512;\nconst MAX_TOTAL_BYTES = 512 * 1024 * 1024;\nconst MAX_IMAGE_BYTES = 50 * 1024 * 1024;\nconst MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;\nconst MAX_SEQUENCE = 999_999;\nconst FILE_PATTERN = /^pi-clip-([0-9a-f]{16})-(\\d{6})-([0-9a-f]{12})\\.(png|jpg|webp|gif)$/;\n\nexport interface StoredSessionImage {\n\treadonly sequence: number;\n\treadonly path: string;\n\treadonly mimeType: string;\n\treadonly bytes: Uint8Array;\n}\n\nexport interface SessionImageStoreOptions {\n\tagentDir: string;\n\tcwd: string;\n\tsessionId: string;\n\tdirectory?: string;\n\tnow?: () => number;\n}\n\ninterface StoredImageEntry {\n\tpath: string;\n\tsessionKey: string;\n\tsequence: number;\n\tdigest: string;\n\tmimeType: string;\n\tbytes: number;\n\tmtimeMs: number;\n}\n\ninterface StoreScan {\n\tentries: StoredImageEntry[];\n\tcomplete: boolean;\n}\n\nfunction extensionForMimeType(mimeType: string): \"png\" | \"jpg\" | \"webp\" | \"gif\" {\n\tswitch (mimeType.split(\";\", 1)[0]?.trim().toLowerCase()) {\n\t\tcase \"image/jpeg\":\n\t\t\treturn \"jpg\";\n\t\tcase \"image/webp\":\n\t\t\treturn \"webp\";\n\t\tcase \"image/gif\":\n\t\t\treturn \"gif\";\n\t\tdefault:\n\t\t\treturn \"png\";\n\t}\n}\n\nfunction mimeTypeForExtension(extension: string): string {\n\tswitch (extension) {\n\t\tcase \"jpg\":\n\t\t\treturn \"image/jpeg\";\n\t\tcase \"webp\":\n\t\t\treturn \"image/webp\";\n\t\tcase \"gif\":\n\t\t\treturn \"image/gif\";\n\t\tdefault:\n\t\t\treturn \"image/png\";\n\t}\n}\n\nfunction resolveConfiguredDirectory(directory: string, cwd: string): string {\n\tconst trimmed = directory.trim();\n\tconst expanded = trimmed === \"~\" ? homedir() : trimmed.replace(/^~(?=[/\\\\])/, homedir());\n\treturn resolve(isAbsolute(expanded) ? expanded : resolve(cwd, expanded));\n}\n\nexport function resolveSessionImageDirectory(options: SessionImageStoreOptions): string {\n\treturn options.directory?.trim()\n\t\t? resolveConfiguredDirectory(options.directory, options.cwd)\n\t\t: attachmentsDir(options.agentDir);\n}\n\nexport class SessionImageStore {\n\treadonly directory: string;\n\tprivate readonly sessionKey: string;\n\tprivate readonly now: () => number;\n\n\tconstructor(options: SessionImageStoreOptions) {\n\t\tthis.directory = resolveSessionImageDirectory(options);\n\t\tthis.sessionKey = createHash(\"sha256\").update(options.sessionId).digest(\"hex\").slice(0, 16);\n\t\tthis.now = options.now ?? Date.now;\n\t}\n\n\t/** Validate and durably retain provider-neutral image content, reusing its claimed sequence only\n\t * when that sequence already contains the exact same bytes and normalized MIME type. */\n\tretainContent(content: ImageContent, preferredSequence?: number): StoredSessionImage {\n\t\tconst compactBase64 = content.data.trim();\n\t\tif (!/^image\\/(?:png|jpeg|webp|gif)(?:;|$)/iu.test(content.mimeType.trim())) {\n\t\t\tthrow new Error(`Unsupported image MIME type: ${content.mimeType}`);\n\t\t}\n\t\tif (!/^[A-Za-z0-9+/]*={0,2}$/.test(compactBase64) || compactBase64.length % 4 === 1) {\n\t\t\tthrow new Error(\"Image content is not valid base64\");\n\t\t}\n\t\tconst bytes = Buffer.from(compactBase64, \"base64\");\n\t\tif (bytes.toString(\"base64\").replace(/=+$/u, \"\") !== compactBase64.replace(/=+$/u, \"\")) {\n\t\t\tthrow new Error(\"Image content is not canonical base64\");\n\t\t}\n\t\tconst normalizedMimeType = mimeTypeForExtension(extensionForMimeType(content.mimeType));\n\t\tif (preferredSequence !== undefined) {\n\t\t\tconst existing = this.read(preferredSequence);\n\t\t\tif (existing && existing.mimeType === normalizedMimeType && Buffer.from(existing.bytes).equals(bytes)) {\n\t\t\t\treturn existing;\n\t\t\t}\n\t\t}\n\t\treturn this.write(bytes, normalizedMimeType);\n\t}\n\n\twrite(bytes: Uint8Array, mimeType: string): StoredSessionImage {\n\t\tif (bytes.byteLength === 0 || bytes.byteLength > MAX_IMAGE_BYTES) {\n\t\t\tthrow new Error(`Clipboard image must be between 1 byte and ${MAX_IMAGE_BYTES} bytes`);\n\t\t}\n\t\tmkdirSync(this.directory, { recursive: true });\n\t\tconst directoryStats = lstatSync(this.directory);\n\t\tif (!directoryStats.isDirectory()) {\n\t\t\tthrow new Error(`Attachment path is not a directory: ${this.directory}`);\n\t\t}\n\n\t\tconst before = this.scan();\n\t\tif (!before.complete) {\n\t\t\tthrow new Error(`Attachment directory exceeds the ${MAX_SCANNED_ENTRIES}-entry inspection bound`);\n\t\t}\n\t\tlet sequence = Math.max(\n\t\t\t0,\n\t\t\t...before.entries.filter((entry) => entry.sessionKey === this.sessionKey).map((entry) => entry.sequence),\n\t\t);\n\t\tconst digest = createHash(\"sha256\").update(bytes).digest(\"hex\").slice(0, 12);\n\t\tconst extension = extensionForMimeType(mimeType);\n\t\tlet path = \"\";\n\t\tlet written = false;\n\t\twhile (sequence < MAX_SEQUENCE) {\n\t\t\tsequence++;\n\t\t\tpath = resolve(\n\t\t\t\tthis.directory,\n\t\t\t\t`${FILE_PREFIX}-${this.sessionKey}-${String(sequence).padStart(6, \"0\")}-${digest}.${extension}`,\n\t\t\t);\n\t\t\ttry {\n\t\t\t\twriteFileSync(path, bytes, { flag: \"wx\" });\n\t\t\t\twritten = true;\n\t\t\t\tbreak;\n\t\t\t} catch (error) {\n\t\t\t\tif ((error as NodeJS.ErrnoException).code !== \"EEXIST\") throw error;\n\t\t\t}\n\t\t}\n\t\tif (!written) {\n\t\t\tthrow new Error(\"Clipboard image sequence is exhausted\");\n\t\t}\n\n\t\ttry {\n\t\t\tthis.prune(path);\n\t\t} catch (error) {\n\t\t\ttry {\n\t\t\t\tunlinkSync(path);\n\t\t\t} catch {}\n\t\t\tthrow error;\n\t\t}\n\t\treturn { sequence, path, mimeType: mimeTypeForExtension(extension), bytes: new Uint8Array(bytes) };\n\t}\n\n\tread(sequence: number): StoredSessionImage | undefined {\n\t\tif (!Number.isSafeInteger(sequence) || sequence < 1 || sequence > MAX_SEQUENCE) return undefined;\n\t\tconst scan = this.scan();\n\t\tif (!scan.complete) return undefined;\n\t\tconst entry = scan.entries.find(\n\t\t\t(candidate) => candidate.sessionKey === this.sessionKey && candidate.sequence === sequence,\n\t\t);\n\t\treturn entry ? this.readEntry(entry) : undefined;\n\t}\n\n\treadLatest(): StoredSessionImage | undefined {\n\t\tconst scan = this.scan();\n\t\tif (!scan.complete) return undefined;\n\t\tconst entries = scan.entries\n\t\t\t.filter((entry) => entry.sessionKey === this.sessionKey)\n\t\t\t.sort((left, right) => right.sequence - left.sequence);\n\t\tfor (const entry of entries) {\n\t\t\tconst image = this.readEntry(entry);\n\t\t\tif (image) return image;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\tresolveReferences(text: string): ImageContent[] {\n\t\ttry {\n\t\t\tconst explicitSequences: number[] = [];\n\t\t\tconst explicitPattern = /(?:\\[\\s*)?(?:image|screenshot|picture|photo)\\s*#?\\s*(\\d{1,6})(?:\\s*\\])?/gi;\n\t\t\tfor (const match of text.matchAll(explicitPattern)) {\n\t\t\t\tconst sequence = Number(match[1]);\n\t\t\t\tif (!explicitSequences.includes(sequence)) explicitSequences.push(sequence);\n\t\t\t}\n\n\t\t\tconst resolved = explicitSequences\n\t\t\t\t.map((sequence) => this.read(sequence))\n\t\t\t\t.filter((image): image is StoredSessionImage => image !== undefined);\n\t\t\tif (resolved.length === 0 && this.referencesLatestImage(text)) {\n\t\t\t\tconst latest = this.readLatest();\n\t\t\t\tif (latest) resolved.push(latest);\n\t\t\t}\n\t\t\treturn resolved.map((image) => ({\n\t\t\t\ttype: \"image\",\n\t\t\t\tdata: Buffer.from(image.bytes).toString(\"base64\"),\n\t\t\t\tmimeType: image.mimeType,\n\t\t\t}));\n\t\t} catch {\n\t\t\treturn [];\n\t\t}\n\t}\n\n\tprivate referencesLatestImage(text: string): boolean {\n\t\treturn (\n\t\t\t/\\b(?:the|this|that|latest|last|pasted|attached|clipboard)\\s+(?:image|screenshot|picture|photo)\\b/i.test(\n\t\t\t\ttext,\n\t\t\t) ||\n\t\t\t/\\b(?:look at|inspect|review|describe|analy[sz]e|check)\\s+(?:(?:the|this|that|latest|last|pasted|attached|clipboard)\\s+)?(?:image|screenshot|picture|photo)\\b/i.test(\n\t\t\t\ttext,\n\t\t\t)\n\t\t);\n\t}\n\n\tprivate readEntry(entry: StoredImageEntry): StoredSessionImage | undefined {\n\t\ttry {\n\t\t\tconst stats = lstatSync(entry.path);\n\t\t\tif (!stats.isFile() || stats.isSymbolicLink() || stats.size < 1 || stats.size > MAX_IMAGE_BYTES)\n\t\t\t\treturn undefined;\n\t\t\tconst bytes = readFileSync(entry.path);\n\t\t\tconst digest = createHash(\"sha256\").update(bytes).digest(\"hex\").slice(0, 12);\n\t\t\tif (digest !== entry.digest) return undefined;\n\t\t\treturn {\n\t\t\t\tsequence: entry.sequence,\n\t\t\t\tpath: entry.path,\n\t\t\t\tmimeType: entry.mimeType,\n\t\t\t\tbytes: new Uint8Array(bytes),\n\t\t\t};\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t}\n\n\tprivate scan(): StoreScan {\n\t\tif (!existsSync(this.directory)) return { entries: [], complete: true };\n\t\tconst entries: StoredImageEntry[] = [];\n\t\tlet scanned = 0;\n\t\tlet complete = true;\n\t\tconst handle = opendirSync(this.directory);\n\t\ttry {\n\t\t\twhile (true) {\n\t\t\t\tconst directoryEntry = handle.readSync();\n\t\t\t\tif (!directoryEntry) break;\n\t\t\t\tif (scanned >= MAX_SCANNED_ENTRIES) {\n\t\t\t\t\tcomplete = false;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tscanned++;\n\t\t\t\tif (!directoryEntry.isFile() || directoryEntry.isSymbolicLink()) continue;\n\t\t\t\tconst match = FILE_PATTERN.exec(directoryEntry.name);\n\t\t\t\tif (!match) continue;\n\t\t\t\tconst path = resolve(this.directory, directoryEntry.name);\n\t\t\t\ttry {\n\t\t\t\t\tconst stats = lstatSync(path);\n\t\t\t\t\tif (!stats.isFile() || stats.isSymbolicLink()) continue;\n\t\t\t\t\tentries.push({\n\t\t\t\t\t\tpath,\n\t\t\t\t\t\tsessionKey: match[1]!,\n\t\t\t\t\t\tsequence: Number(match[2]),\n\t\t\t\t\t\tdigest: match[3]!,\n\t\t\t\t\t\tmimeType: mimeTypeForExtension(match[4]!),\n\t\t\t\t\t\tbytes: stats.size,\n\t\t\t\t\t\tmtimeMs: stats.mtimeMs,\n\t\t\t\t\t});\n\t\t\t\t} catch {}\n\t\t\t}\n\t\t} finally {\n\t\t\thandle.closeSync();\n\t\t}\n\t\treturn { entries, complete };\n\t}\n\n\tprivate prune(protectedPath: string): void {\n\t\tconst scan = this.scan();\n\t\tif (!scan.complete) {\n\t\t\tthrow new Error(`Attachment directory exceeds the ${MAX_SCANNED_ENTRIES}-entry inspection bound`);\n\t\t}\n\t\tconst now = this.now();\n\t\tfor (const entry of scan.entries) {\n\t\t\tif (entry.path !== protectedPath && now - entry.mtimeMs > MAX_AGE_MS) {\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(entry.path);\n\t\t\t\t} catch {}\n\t\t\t}\n\t\t}\n\n\t\tconst retained = this.scan();\n\t\tif (!retained.complete) {\n\t\t\tthrow new Error(`Attachment directory exceeds the ${MAX_SCANNED_ENTRIES}-entry inspection bound`);\n\t\t}\n\t\tconst oldestFirst = retained.entries.sort((left, right) => left.mtimeMs - right.mtimeMs);\n\t\tlet totalBytes = oldestFirst.reduce((total, entry) => total + entry.bytes, 0);\n\t\tlet totalFiles = oldestFirst.length;\n\t\tfor (const entry of oldestFirst) {\n\t\t\tif (totalFiles <= MAX_STORED_FILES && totalBytes <= MAX_TOTAL_BYTES) break;\n\t\t\tif (entry.path === protectedPath) continue;\n\t\t\ttry {\n\t\t\t\tunlinkSync(entry.path);\n\t\t\t\ttotalFiles--;\n\t\t\t\ttotalBytes -= entry.bytes;\n\t\t\t} catch {}\n\t\t}\n\t\tif (totalFiles > MAX_STORED_FILES || totalBytes > MAX_TOTAL_BYTES) {\n\t\t\tthrow new Error(\"Attachment retention bounds could not be enforced\");\n\t\t}\n\t}\n}\n"]}

package/dist/core/session-role.d.ts

@@ -5,7 +5,8 @@
  * tool's worker scoping, and the read-only store options threaded through the persistence layer).
  *
  * A session is a worker iff EITHER:
- * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration), or
+ * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration),
+ * - a valid `PI_PARENT_PID` declares this process as a managed child, or
  * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a
  *   lane-bound session is a worker by construction, regardless of how it was launched.
  *
@@ -20,9 +21,10 @@ export declare function getSessionRole(env?: NodeJS.ProcessEnv): SessionRole;
 export declare function isWorkerSession(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Tools a worker session may never activate: the orchestration/self-adaptation surface that would
- * let a worker spawn its own sub-orchestration, mutate settings-driven learning/model state, or
- * shell out to the unbounded `python` execution contract. `python` is load-bearing for the
- * zero-footprint guarantee (it can write anywhere the interpreter can reach); `context_scout` is
+ * let a worker spawn its own sub-orchestration, bypass its parent to request owner input, mutate
+ * settings-driven learning/model state, or shell out to the unbounded `python` execution contract.
+ * `python` is load-bearing for the zero-footprint guarantee (it can write anywhere the interpreter
+ * can reach); `context_scout` is
  * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it
  * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same
  * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.

package/dist/core/session-role.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-role.d.ts","sourceRoot":"","sources":["../../src/core/session-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAI5C,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,WAAW,CAIhF;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE7E;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAYrD,CAAC","sourcesContent":["/**\n * Session-role identity: distinguishes a MAIN session (an interactive/direct `pi` session) from a\n * WORKER session (lane-bound or explicitly dispatched) — the seam every worker-scoped UAC ceiling\n * and zero-footprint store gates on (see runtime-builder.ts's `isAllowedTool`, the worktree_sync\n * tool's worker scoping, and the read-only store options threaded through the persistence layer).\n *\n * A session is a worker iff EITHER:\n * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration), or\n * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a\n *   lane-bound session is a worker by construction, regardless of how it was launched.\n *\n * `PI_SESSION_ROLE=main` is deliberately NOT an escalation: it can never override a bound lane.\n * There is no environment value a lane-bound process can set to shed the worker ceiling — the env\n * var is additive evidence for \"worker\", never a downgrade signal.\n */\n\nimport { getBoundWorktreeLaneKey } from \"./worktree-sync/runtime.ts\";\n\nexport type SessionRole = \"main\" | \"worker\";\n\nconst PI_SESSION_ROLE_ENV = \"PI_SESSION_ROLE\";\n\n/** Derive this process's session role from the environment (env-injectable for tests). */\nexport function getSessionRole(env: NodeJS.ProcessEnv = process.env): SessionRole {\n\tif (env[PI_SESSION_ROLE_ENV] === \"worker\") return \"worker\";\n\tif (getBoundWorktreeLaneKey(env) !== undefined) return \"worker\";\n\treturn \"main\";\n}\n\n/** True iff this process is a worker session (lane-bound or explicitly declared). */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn getSessionRole(env) === \"worker\";\n}\n\n/**\n * Tools a worker session may never activate: the orchestration/self-adaptation surface that would\n * let a worker spawn its own sub-orchestration, mutate settings-driven learning/model state, or\n * shell out to the unbounded `python` execution contract. `python` is load-bearing for the\n * zero-footprint guarantee (it can write anywhere the interpreter can reach); `context_scout` is\n * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it\n * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same\n * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.\n */\nexport const WORKER_FORBIDDEN_TOOLS: ReadonlySet<string> = new Set([\n\t\"goal\",\n\t\"delegate\",\n\t\"delegate_status\",\n\t\"improvement_loop\",\n\t\"extensionify\",\n\t\"skillify\",\n\t\"run_toolkit_script\",\n\t\"model_fitness\",\n\t\"tmux_agent_manager\",\n\t\"context_scout\",\n\t\"python\",\n]);\n"]}
+{"version":3,"file":"session-role.d.ts","sourceRoot":"","sources":["../../src/core/session-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAI5C,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,WAAW,CAKhF;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE7E;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAarD,CAAC","sourcesContent":["/**\n * Session-role identity: distinguishes a MAIN session (an interactive/direct `pi` session) from a\n * WORKER session (lane-bound or explicitly dispatched) — the seam every worker-scoped UAC ceiling\n * and zero-footprint store gates on (see runtime-builder.ts's `isAllowedTool`, the worktree_sync\n * tool's worker scoping, and the read-only store options threaded through the persistence layer).\n *\n * A session is a worker iff EITHER:\n * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration),\n * - a valid `PI_PARENT_PID` declares this process as a managed child, or\n * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a\n *   lane-bound session is a worker by construction, regardless of how it was launched.\n *\n * `PI_SESSION_ROLE=main` is deliberately NOT an escalation: it can never override a bound lane.\n * There is no environment value a lane-bound process can set to shed the worker ceiling — the env\n * var is additive evidence for \"worker\", never a downgrade signal.\n */\n\nimport { getParentPid } from \"./process-identity.ts\";\nimport { getBoundWorktreeLaneKey } from \"./worktree-sync/runtime.ts\";\n\nexport type SessionRole = \"main\" | \"worker\";\n\nconst PI_SESSION_ROLE_ENV = \"PI_SESSION_ROLE\";\n\n/** Derive this process's session role from the environment (env-injectable for tests). */\nexport function getSessionRole(env: NodeJS.ProcessEnv = process.env): SessionRole {\n\tif (env[PI_SESSION_ROLE_ENV] === \"worker\") return \"worker\";\n\tif (getParentPid(env) !== undefined) return \"worker\";\n\tif (getBoundWorktreeLaneKey(env) !== undefined) return \"worker\";\n\treturn \"main\";\n}\n\n/** True iff this process is a worker session (lane-bound or explicitly declared). */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn getSessionRole(env) === \"worker\";\n}\n\n/**\n * Tools a worker session may never activate: the orchestration/self-adaptation surface that would\n * let a worker spawn its own sub-orchestration, bypass its parent to request owner input, mutate\n * settings-driven learning/model state, or shell out to the unbounded `python` execution contract.\n * `python` is load-bearing for the zero-footprint guarantee (it can write anywhere the interpreter\n * can reach); `context_scout` is\n * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it\n * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same\n * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.\n */\nexport const WORKER_FORBIDDEN_TOOLS: ReadonlySet<string> = new Set([\n\t\"goal\",\n\t\"ask_question\",\n\t\"delegate\",\n\t\"delegate_status\",\n\t\"improvement_loop\",\n\t\"extensionify\",\n\t\"skillify\",\n\t\"run_toolkit_script\",\n\t\"model_fitness\",\n\t\"tmux_agent_manager\",\n\t\"context_scout\",\n\t\"python\",\n]);\n"]}

package/dist/core/session-role.js

@@ -5,7 +5,8 @@
  * tool's worker scoping, and the read-only store options threaded through the persistence layer).
  *
  * A session is a worker iff EITHER:
- * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration), or
+ * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration),
+ * - a valid `PI_PARENT_PID` declares this process as a managed child, or
  * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a
  *   lane-bound session is a worker by construction, regardless of how it was launched.
  *
@@ -13,12 +14,15 @@
  * There is no environment value a lane-bound process can set to shed the worker ceiling — the env
  * var is additive evidence for "worker", never a downgrade signal.
  */
+import { getParentPid } from "./process-identity.js";
 import { getBoundWorktreeLaneKey } from "./worktree-sync/runtime.js";
 const PI_SESSION_ROLE_ENV = "PI_SESSION_ROLE";
 /** Derive this process's session role from the environment (env-injectable for tests). */
 export function getSessionRole(env = process.env) {
     if (env[PI_SESSION_ROLE_ENV] === "worker")
         return "worker";
+    if (getParentPid(env) !== undefined)
+        return "worker";
     if (getBoundWorktreeLaneKey(env) !== undefined)
         return "worker";
     return "main";
@@ -29,15 +33,17 @@ export function isWorkerSession(env = process.env) {
 }
 /**
  * Tools a worker session may never activate: the orchestration/self-adaptation surface that would
- * let a worker spawn its own sub-orchestration, mutate settings-driven learning/model state, or
- * shell out to the unbounded `python` execution contract. `python` is load-bearing for the
- * zero-footprint guarantee (it can write anywhere the interpreter can reach); `context_scout` is
+ * let a worker spawn its own sub-orchestration, bypass its parent to request owner input, mutate
+ * settings-driven learning/model state, or shell out to the unbounded `python` execution contract.
+ * `python` is load-bearing for the zero-footprint guarantee (it can write anywhere the interpreter
+ * can reach); `context_scout` is
  * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it
  * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same
  * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.
  */
 export const WORKER_FORBIDDEN_TOOLS = new Set([
     "goal",
+    "ask_question",
     "delegate",
     "delegate_status",
     "improvement_loop",

package/dist/core/session-role.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-role.js","sourceRoot":"","sources":["../../src/core/session-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAIrE,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAE9C,0FAA0F;AAC1F,MAAM,UAAU,cAAc,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAe;IACjF,IAAI,GAAG,CAAC,mBAAmB,CAAC,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAChE,OAAO,MAAM,CAAC;AAAA,CACd;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAW;IAC9E,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC;AAAA,CACxC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IAClE,MAAM;IACN,UAAU;IACV,iBAAiB;IACjB,kBAAkB;IAClB,cAAc;IACd,UAAU;IACV,oBAAoB;IACpB,eAAe;IACf,oBAAoB;IACpB,eAAe;IACf,QAAQ;CACR,CAAC,CAAC","sourcesContent":["/**\n * Session-role identity: distinguishes a MAIN session (an interactive/direct `pi` session) from a\n * WORKER session (lane-bound or explicitly dispatched) — the seam every worker-scoped UAC ceiling\n * and zero-footprint store gates on (see runtime-builder.ts's `isAllowedTool`, the worktree_sync\n * tool's worker scoping, and the read-only store options threaded through the persistence layer).\n *\n * A session is a worker iff EITHER:\n * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration), or\n * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a\n *   lane-bound session is a worker by construction, regardless of how it was launched.\n *\n * `PI_SESSION_ROLE=main` is deliberately NOT an escalation: it can never override a bound lane.\n * There is no environment value a lane-bound process can set to shed the worker ceiling — the env\n * var is additive evidence for \"worker\", never a downgrade signal.\n */\n\nimport { getBoundWorktreeLaneKey } from \"./worktree-sync/runtime.ts\";\n\nexport type SessionRole = \"main\" | \"worker\";\n\nconst PI_SESSION_ROLE_ENV = \"PI_SESSION_ROLE\";\n\n/** Derive this process's session role from the environment (env-injectable for tests). */\nexport function getSessionRole(env: NodeJS.ProcessEnv = process.env): SessionRole {\n\tif (env[PI_SESSION_ROLE_ENV] === \"worker\") return \"worker\";\n\tif (getBoundWorktreeLaneKey(env) !== undefined) return \"worker\";\n\treturn \"main\";\n}\n\n/** True iff this process is a worker session (lane-bound or explicitly declared). */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn getSessionRole(env) === \"worker\";\n}\n\n/**\n * Tools a worker session may never activate: the orchestration/self-adaptation surface that would\n * let a worker spawn its own sub-orchestration, mutate settings-driven learning/model state, or\n * shell out to the unbounded `python` execution contract. `python` is load-bearing for the\n * zero-footprint guarantee (it can write anywhere the interpreter can reach); `context_scout` is\n * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it\n * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same\n * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.\n */\nexport const WORKER_FORBIDDEN_TOOLS: ReadonlySet<string> = new Set([\n\t\"goal\",\n\t\"delegate\",\n\t\"delegate_status\",\n\t\"improvement_loop\",\n\t\"extensionify\",\n\t\"skillify\",\n\t\"run_toolkit_script\",\n\t\"model_fitness\",\n\t\"tmux_agent_manager\",\n\t\"context_scout\",\n\t\"python\",\n]);\n"]}
+{"version":3,"file":"session-role.js","sourceRoot":"","sources":["../../src/core/session-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAIrE,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAE9C,0FAA0F;AAC1F,MAAM,UAAU,cAAc,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAe;IACjF,IAAI,GAAG,CAAC,mBAAmB,CAAC,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACrD,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAChE,OAAO,MAAM,CAAC;AAAA,CACd;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAW;IAC9E,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC;AAAA,CACxC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IAClE,MAAM;IACN,cAAc;IACd,UAAU;IACV,iBAAiB;IACjB,kBAAkB;IAClB,cAAc;IACd,UAAU;IACV,oBAAoB;IACpB,eAAe;IACf,oBAAoB;IACpB,eAAe;IACf,QAAQ;CACR,CAAC,CAAC","sourcesContent":["/**\n * Session-role identity: distinguishes a MAIN session (an interactive/direct `pi` session) from a\n * WORKER session (lane-bound or explicitly dispatched) — the seam every worker-scoped UAC ceiling\n * and zero-footprint store gates on (see runtime-builder.ts's `isAllowedTool`, the worktree_sync\n * tool's worker scoping, and the read-only store options threaded through the persistence layer).\n *\n * A session is a worker iff EITHER:\n * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration),\n * - a valid `PI_PARENT_PID` declares this process as a managed child, or\n * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a\n *   lane-bound session is a worker by construction, regardless of how it was launched.\n *\n * `PI_SESSION_ROLE=main` is deliberately NOT an escalation: it can never override a bound lane.\n * There is no environment value a lane-bound process can set to shed the worker ceiling — the env\n * var is additive evidence for \"worker\", never a downgrade signal.\n */\n\nimport { getParentPid } from \"./process-identity.ts\";\nimport { getBoundWorktreeLaneKey } from \"./worktree-sync/runtime.ts\";\n\nexport type SessionRole = \"main\" | \"worker\";\n\nconst PI_SESSION_ROLE_ENV = \"PI_SESSION_ROLE\";\n\n/** Derive this process's session role from the environment (env-injectable for tests). */\nexport function getSessionRole(env: NodeJS.ProcessEnv = process.env): SessionRole {\n\tif (env[PI_SESSION_ROLE_ENV] === \"worker\") return \"worker\";\n\tif (getParentPid(env) !== undefined) return \"worker\";\n\tif (getBoundWorktreeLaneKey(env) !== undefined) return \"worker\";\n\treturn \"main\";\n}\n\n/** True iff this process is a worker session (lane-bound or explicitly declared). */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn getSessionRole(env) === \"worker\";\n}\n\n/**\n * Tools a worker session may never activate: the orchestration/self-adaptation surface that would\n * let a worker spawn its own sub-orchestration, bypass its parent to request owner input, mutate\n * settings-driven learning/model state, or shell out to the unbounded `python` execution contract.\n * `python` is load-bearing for the zero-footprint guarantee (it can write anywhere the interpreter\n * can reach); `context_scout` is\n * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it\n * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same\n * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.\n */\nexport const WORKER_FORBIDDEN_TOOLS: ReadonlySet<string> = new Set([\n\t\"goal\",\n\t\"ask_question\",\n\t\"delegate\",\n\t\"delegate_status\",\n\t\"improvement_loop\",\n\t\"extensionify\",\n\t\"skillify\",\n\t\"run_toolkit_script\",\n\t\"model_fitness\",\n\t\"tmux_agent_manager\",\n\t\"context_scout\",\n\t\"python\",\n]);\n"]}

package/dist/core/session-snapshot.d.ts

@@ -0,0 +1,34 @@
+import type { SessionEntry, SessionManager } from "@caupulican/pi-agent-core/node";
+export type SessionSnapshotPayload<ValueKey extends string, Value extends object> = {
+    version: 1;
+} & {
+    [Key in ValueKey]: Value;
+};
+export interface SessionSnapshotCodec<Value extends object, ValueKey extends string> {
+    customType: string;
+    valueKey: ValueKey;
+    isValue(value: unknown): value is Value;
+    clone(value: Value): Value;
+}
+export interface SessionBranchEntrySource {
+    getBranch?: () => readonly SessionEntry[];
+    getEntries?: () => readonly SessionEntry[];
+}
+type VersionOneSnapshotPayload = Record<string, unknown> & {
+    version: 1;
+};
+/** Active branch when available; linear entry history only for narrow stores that expose no branch API. */
+export declare function getActiveSessionBranchEntries(source: SessionBranchEntrySource): readonly SessionEntry[];
+export declare function isVersionOneSessionSnapshotPayload(data: unknown): data is VersionOneSnapshotPayload;
+export declare function createSessionSnapshotPayload<Value extends object, ValueKey extends string>(codec: SessionSnapshotCodec<Value, ValueKey>, value: Value): SessionSnapshotPayload<ValueKey, Value>;
+export declare function appendSessionSnapshot<Value extends object, ValueKey extends string>(sessionManager: Pick<SessionManager, "appendCustomEntry">, codec: SessionSnapshotCodec<Value, ValueKey>, value: Value): string;
+export declare function decodeSessionSnapshotPayload<Value extends object, ValueKey extends string>(data: unknown, codec: SessionSnapshotCodec<Value, ValueKey>): Value | undefined;
+export declare function getSessionSnapshots<Value extends object, ValueKey extends string>(entries: readonly SessionEntry[], codec: SessionSnapshotCodec<Value, ValueKey>): Value[];
+export declare function getLatestSessionSnapshot<Value extends object, ValueKey extends string>(entries: readonly SessionEntry[], codec: SessionSnapshotCodec<Value, ValueKey>): Value | undefined;
+/**
+ * Resolves the newest valid snapshot on the active branch. Malformed entries are skipped while
+ * walking leaf to root so they cannot hide an older valid checkpoint.
+ */
+export declare function getLatestSessionSnapshotOnBranch<Value extends object, ValueKey extends string>(sessionManager: Pick<SessionManager, "getLatestCustomEntryOnBranch">, codec: SessionSnapshotCodec<Value, ValueKey>): Value | undefined;
+export {};
+//# sourceMappingURL=session-snapshot.d.ts.map

package/dist/core/session-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-snapshot.d.ts","sourceRoot":"","sources":["../../src/core/session-snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGnF,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,IAAI;IACnF,OAAO,EAAE,CAAC,CAAC;CACX,GAAG;KACF,GAAG,IAAI,QAAQ,GAAG,KAAK;CACxB,CAAC;AAEF,MAAM,WAAW,oBAAoB,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAAC;IACxC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACxC,SAAS,CAAC,EAAE,MAAM,SAAS,YAAY,EAAE,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,KAAK,yBAAyB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE1E,2GAA2G;AAC3G,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,wBAAwB,GAAG,SAAS,YAAY,EAAE,CAIvG;AAED,wBAAgB,kCAAkC,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,yBAAyB,CAEnG;AAED,wBAAgB,4BAA4B,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EACzF,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,EAC5C,KAAK,EAAE,KAAK,GACV,sBAAsB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAKzC;AAED,wBAAgB,qBAAqB,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EAClF,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACzD,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,EAC5C,KAAK,EAAE,KAAK,GACV,MAAM,CAER;AAED,wBAAgB,4BAA4B,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EACzF,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAC1C,KAAK,GAAG,SAAS,CAInB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EAChF,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAC1C,KAAK,EAAE,CAQT;AAED,wBAAgB,wBAAwB,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EACrF,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAC1C,KAAK,GAAG,SAAS,CAQnB;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EAC7F,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,8BAA8B,CAAC,EACpE,KAAK,EAAE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAC1C,KAAK,GAAG,SAAS,CAUnB","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport { isPlainRecord } from \"./util/value-guards.ts\";\n\nexport type SessionSnapshotPayload<ValueKey extends string, Value extends object> = {\n\tversion: 1;\n} & {\n\t[Key in ValueKey]: Value;\n};\n\nexport interface SessionSnapshotCodec<Value extends object, ValueKey extends string> {\n\tcustomType: string;\n\tvalueKey: ValueKey;\n\tisValue(value: unknown): value is Value;\n\tclone(value: Value): Value;\n}\n\nexport interface SessionBranchEntrySource {\n\tgetBranch?: () => readonly SessionEntry[];\n\tgetEntries?: () => readonly SessionEntry[];\n}\n\ntype VersionOneSnapshotPayload = Record<string, unknown> & { version: 1 };\n\n/** Active branch when available; linear entry history only for narrow stores that expose no branch API. */\nexport function getActiveSessionBranchEntries(source: SessionBranchEntrySource): readonly SessionEntry[] {\n\tif (typeof source.getBranch === \"function\") return source.getBranch();\n\tif (typeof source.getEntries === \"function\") return source.getEntries();\n\tthrow new TypeError(\"Session branch entry source exposes neither getBranch nor getEntries\");\n}\n\nexport function isVersionOneSessionSnapshotPayload(data: unknown): data is VersionOneSnapshotPayload {\n\treturn isPlainRecord(data) && data.version === 1;\n}\n\nexport function createSessionSnapshotPayload<Value extends object, ValueKey extends string>(\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n\tvalue: Value,\n): SessionSnapshotPayload<ValueKey, Value> {\n\treturn {\n\t\tversion: 1,\n\t\t[codec.valueKey]: codec.clone(value),\n\t} as SessionSnapshotPayload<ValueKey, Value>;\n}\n\nexport function appendSessionSnapshot<Value extends object, ValueKey extends string>(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n\tvalue: Value,\n): string {\n\treturn sessionManager.appendCustomEntry(codec.customType, createSessionSnapshotPayload(codec, value));\n}\n\nexport function decodeSessionSnapshotPayload<Value extends object, ValueKey extends string>(\n\tdata: unknown,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tif (!isVersionOneSessionSnapshotPayload(data)) return undefined;\n\tconst value = data[codec.valueKey];\n\treturn codec.isValue(value) ? codec.clone(value) : undefined;\n}\n\nexport function getSessionSnapshots<Value extends object, ValueKey extends string>(\n\tentries: readonly SessionEntry[],\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value[] {\n\tconst snapshots: Value[] = [];\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== codec.customType) continue;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) snapshots.push(snapshot);\n\t}\n\treturn snapshots;\n}\n\nexport function getLatestSessionSnapshot<Value extends object, ValueKey extends string>(\n\tentries: readonly SessionEntry[],\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tfor (let index = entries.length - 1; index >= 0; index--) {\n\t\tconst entry = entries[index];\n\t\tif (entry.type !== \"custom\" || entry.customType !== codec.customType) continue;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) return snapshot;\n\t}\n\treturn undefined;\n}\n\n/**\n * Resolves the newest valid snapshot on the active branch. Malformed entries are skipped while\n * walking leaf to root so they cannot hide an older valid checkpoint.\n */\nexport function getLatestSessionSnapshotOnBranch<Value extends object, ValueKey extends string>(\n\tsessionManager: Pick<SessionManager, \"getLatestCustomEntryOnBranch\">,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tlet fromId: string | undefined;\n\tfor (;;) {\n\t\tconst entry = sessionManager.getLatestCustomEntryOnBranch(codec.customType, fromId);\n\t\tif (!entry) return undefined;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) return snapshot;\n\t\tif (entry.parentId === null) return undefined;\n\t\tfromId = entry.parentId;\n\t}\n}\n"]}

package/dist/core/session-snapshot.js

@@ -0,0 +1,68 @@
+import { isPlainRecord } from "./util/value-guards.js";
+/** Active branch when available; linear entry history only for narrow stores that expose no branch API. */
+export function getActiveSessionBranchEntries(source) {
+    if (typeof source.getBranch === "function")
+        return source.getBranch();
+    if (typeof source.getEntries === "function")
+        return source.getEntries();
+    throw new TypeError("Session branch entry source exposes neither getBranch nor getEntries");
+}
+export function isVersionOneSessionSnapshotPayload(data) {
+    return isPlainRecord(data) && data.version === 1;
+}
+export function createSessionSnapshotPayload(codec, value) {
+    return {
+        version: 1,
+        [codec.valueKey]: codec.clone(value),
+    };
+}
+export function appendSessionSnapshot(sessionManager, codec, value) {
+    return sessionManager.appendCustomEntry(codec.customType, createSessionSnapshotPayload(codec, value));
+}
+export function decodeSessionSnapshotPayload(data, codec) {
+    if (!isVersionOneSessionSnapshotPayload(data))
+        return undefined;
+    const value = data[codec.valueKey];
+    return codec.isValue(value) ? codec.clone(value) : undefined;
+}
+export function getSessionSnapshots(entries, codec) {
+    const snapshots = [];
+    for (const entry of entries) {
+        if (entry.type !== "custom" || entry.customType !== codec.customType)
+            continue;
+        const snapshot = decodeSessionSnapshotPayload(entry.data, codec);
+        if (snapshot !== undefined)
+            snapshots.push(snapshot);
+    }
+    return snapshots;
+}
+export function getLatestSessionSnapshot(entries, codec) {
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry.type !== "custom" || entry.customType !== codec.customType)
+            continue;
+        const snapshot = decodeSessionSnapshotPayload(entry.data, codec);
+        if (snapshot !== undefined)
+            return snapshot;
+    }
+    return undefined;
+}
+/**
+ * Resolves the newest valid snapshot on the active branch. Malformed entries are skipped while
+ * walking leaf to root so they cannot hide an older valid checkpoint.
+ */
+export function getLatestSessionSnapshotOnBranch(sessionManager, codec) {
+    let fromId;
+    for (;;) {
+        const entry = sessionManager.getLatestCustomEntryOnBranch(codec.customType, fromId);
+        if (!entry)
+            return undefined;
+        const snapshot = decodeSessionSnapshotPayload(entry.data, codec);
+        if (snapshot !== undefined)
+            return snapshot;
+        if (entry.parentId === null)
+            return undefined;
+        fromId = entry.parentId;
+    }
+}
+//# sourceMappingURL=session-snapshot.js.map

package/dist/core/session-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-snapshot.js","sourceRoot":"","sources":["../../src/core/session-snapshot.ts"],"names":[],"mappings":"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","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport { isPlainRecord } from \"./util/value-guards.ts\";\n\nexport type SessionSnapshotPayload<ValueKey extends string, Value extends object> = {\n\tversion: 1;\n} & {\n\t[Key in ValueKey]: Value;\n};\n\nexport interface SessionSnapshotCodec<Value extends object, ValueKey extends string> {\n\tcustomType: string;\n\tvalueKey: ValueKey;\n\tisValue(value: unknown): value is Value;\n\tclone(value: Value): Value;\n}\n\nexport interface SessionBranchEntrySource {\n\tgetBranch?: () => readonly SessionEntry[];\n\tgetEntries?: () => readonly SessionEntry[];\n}\n\ntype VersionOneSnapshotPayload = Record<string, unknown> & { version: 1 };\n\n/** Active branch when available; linear entry history only for narrow stores that expose no branch API. */\nexport function getActiveSessionBranchEntries(source: SessionBranchEntrySource): readonly SessionEntry[] {\n\tif (typeof source.getBranch === \"function\") return source.getBranch();\n\tif (typeof source.getEntries === \"function\") return source.getEntries();\n\tthrow new TypeError(\"Session branch entry source exposes neither getBranch nor getEntries\");\n}\n\nexport function isVersionOneSessionSnapshotPayload(data: unknown): data is VersionOneSnapshotPayload {\n\treturn isPlainRecord(data) && data.version === 1;\n}\n\nexport function createSessionSnapshotPayload<Value extends object, ValueKey extends string>(\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n\tvalue: Value,\n): SessionSnapshotPayload<ValueKey, Value> {\n\treturn {\n\t\tversion: 1,\n\t\t[codec.valueKey]: codec.clone(value),\n\t} as SessionSnapshotPayload<ValueKey, Value>;\n}\n\nexport function appendSessionSnapshot<Value extends object, ValueKey extends string>(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n\tvalue: Value,\n): string {\n\treturn sessionManager.appendCustomEntry(codec.customType, createSessionSnapshotPayload(codec, value));\n}\n\nexport function decodeSessionSnapshotPayload<Value extends object, ValueKey extends string>(\n\tdata: unknown,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tif (!isVersionOneSessionSnapshotPayload(data)) return undefined;\n\tconst value = data[codec.valueKey];\n\treturn codec.isValue(value) ? codec.clone(value) : undefined;\n}\n\nexport function getSessionSnapshots<Value extends object, ValueKey extends string>(\n\tentries: readonly SessionEntry[],\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value[] {\n\tconst snapshots: Value[] = [];\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== codec.customType) continue;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) snapshots.push(snapshot);\n\t}\n\treturn snapshots;\n}\n\nexport function getLatestSessionSnapshot<Value extends object, ValueKey extends string>(\n\tentries: readonly SessionEntry[],\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tfor (let index = entries.length - 1; index >= 0; index--) {\n\t\tconst entry = entries[index];\n\t\tif (entry.type !== \"custom\" || entry.customType !== codec.customType) continue;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) return snapshot;\n\t}\n\treturn undefined;\n}\n\n/**\n * Resolves the newest valid snapshot on the active branch. Malformed entries are skipped while\n * walking leaf to root so they cannot hide an older valid checkpoint.\n */\nexport function getLatestSessionSnapshotOnBranch<Value extends object, ValueKey extends string>(\n\tsessionManager: Pick<SessionManager, \"getLatestCustomEntryOnBranch\">,\n\tcodec: SessionSnapshotCodec<Value, ValueKey>,\n): Value | undefined {\n\tlet fromId: string | undefined;\n\tfor (;;) {\n\t\tconst entry = sessionManager.getLatestCustomEntryOnBranch(codec.customType, fromId);\n\t\tif (!entry) return undefined;\n\t\tconst snapshot = decodeSessionSnapshotPayload(entry.data, codec);\n\t\tif (snapshot !== undefined) return snapshot;\n\t\tif (entry.parentId === null) return undefined;\n\t\tfromId = entry.parentId;\n\t}\n}\n"]}

package/dist/core/session-supervision-runtime.d.ts

@@ -0,0 +1,31 @@
+import type { AgentSession } from "./agent-session.ts";
+import type { AgentSessionRuntimeResource } from "./agent-session-runtime.ts";
+import type { ResumablePayload } from "./process-matrix/codes.ts";
+import { type ResumeWorkerLaunchOutcome } from "./process-matrix/runtime.ts";
+export interface SessionSupervisionRuntimeOptions {
+    agentDir: string;
+    hasUI: boolean;
+    orchestrationProfileId?: string;
+    isProcessAlive: (pid: number) => boolean;
+    promptConfirm: (message: string) => Promise<boolean>;
+    resumeWorker: (payload: ResumablePayload, parentSessionId: string) => Promise<ResumeWorkerLaunchOutcome>;
+    onDiagnostic: (message: string) => void;
+    requestExit: (session: AgentSession) => void;
+}
+/**
+ * Owns the process-matrix and worktree-sync handles for the currently active session.
+ * Replacement stops the old generation before a new one is started, so no watcher can retain a
+ * disposed session or deliver a notice across a `/new`, `/resume`, or `/fork` boundary.
+ */
+export declare class SessionSupervisionRuntime implements AgentSessionRuntimeResource {
+    private readonly options;
+    private generation;
+    private processMatrix?;
+    private worktreeSync?;
+    constructor(options: SessionSupervisionRuntimeOptions);
+    start(session: AgentSession): Promise<void>;
+    stop(): Promise<void>;
+    private stopHandles;
+    private notify;
+}
+//# sourceMappingURL=session-supervision-runtime.d.ts.map

package/dist/core/session-supervision-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-supervision-runtime.d.ts","sourceRoot":"","sources":["../../src/core/session-supervision-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAE9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAIN,KAAK,yBAAyB,EAE9B,MAAM,6BAA6B,CAAC;AAIrC,MAAM,WAAW,gCAAgC;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,YAAY,EAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACzG,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,WAAW,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;CAC7C;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,YAAW,2BAA2B;IAC5E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,aAAa,CAAC,CAA6B;IACnD,OAAO,CAAC,YAAY,CAAC,CAA4B;IAEjD,YAAY,OAAO,EAAE,gCAAgC,EAEpD;IAEK,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DhD;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAG1B;YAEa,WAAW;YAQX,MAAM;CAYpB","sourcesContent":["import type { AgentSession } from \"./agent-session.ts\";\nimport type { AgentSessionRuntimeResource } from \"./agent-session-runtime.ts\";\nimport { createAgentIdentity } from \"./orchestration/agent-resume.ts\";\nimport type { ResumablePayload } from \"./process-matrix/codes.ts\";\nimport {\n\tgetOrchestrationAgentId,\n\tgetProcessTaskRef,\n\ttype ProcessMatrixRuntimeHandle,\n\ttype ResumeWorkerLaunchOutcome,\n\tstartProcessMatrixRuntime,\n} from \"./process-matrix/runtime.ts\";\nimport type { WorktreeSyncRuntimeHandle } from \"./worktree-sync/runtime.ts\";\nimport { getBoundWorktreeLaneKey, startWorktreeSyncRuntime } from \"./worktree-sync/runtime.ts\";\n\nexport interface SessionSupervisionRuntimeOptions {\n\tagentDir: string;\n\thasUI: boolean;\n\torchestrationProfileId?: string;\n\tisProcessAlive: (pid: number) => boolean;\n\tpromptConfirm: (message: string) => Promise<boolean>;\n\tresumeWorker: (payload: ResumablePayload, parentSessionId: string) => Promise<ResumeWorkerLaunchOutcome>;\n\tonDiagnostic: (message: string) => void;\n\trequestExit: (session: AgentSession) => void;\n}\n\n/**\n * Owns the process-matrix and worktree-sync handles for the currently active session.\n * Replacement stops the old generation before a new one is started, so no watcher can retain a\n * disposed session or deliver a notice across a `/new`, `/resume`, or `/fork` boundary.\n */\nexport class SessionSupervisionRuntime implements AgentSessionRuntimeResource {\n\tprivate readonly options: SessionSupervisionRuntimeOptions;\n\tprivate generation = 0;\n\tprivate processMatrix?: ProcessMatrixRuntimeHandle;\n\tprivate worktreeSync?: WorktreeSyncRuntimeHandle;\n\n\tconstructor(options: SessionSupervisionRuntimeOptions) {\n\t\tthis.options = options;\n\t}\n\n\tasync start(session: AgentSession): Promise<void> {\n\t\tconst generation = ++this.generation;\n\t\tawait this.stopHandles();\n\t\tconst sessionManager = session.sessionManager;\n\t\tconst sessionId = sessionManager.getSessionId();\n\t\tconst boundWorktreeLaneKey = getBoundWorktreeLaneKey();\n\t\tconst orchestrationProfileId =\n\t\t\tthis.options.orchestrationProfileId ??\n\t\t\tsession.capabilityEnvelope?.profileId ??\n\t\t\tsession.settingsManager.getActiveOrchestrationProfile();\n\t\tconst sessionFile = sessionManager.getSessionFile();\n\t\tconst goal = session.getGoalStateSnapshot();\n\t\tconst taskRef = getProcessTaskRef() ?? goal?.goalId;\n\t\tconst agent = createAgentIdentity(getOrchestrationAgentId() ?? sessionId, {\n\t\t\tprovider: \"pi\",\n\t\t\tsessionId,\n\t\t\tsessionDir: sessionManager.getSessionDir(),\n\t\t\t...(sessionFile ? { sessionFile } : {}),\n\t\t\tcwd: sessionManager.getCwd(),\n\t\t\t...(boundWorktreeLaneKey ? { worktreeLaneKey: boundWorktreeLaneKey } : {}),\n\t\t\t...(orchestrationProfileId ? { orchestrationProfileId } : {}),\n\t\t\tresourceProfileNames: session.settingsManager.getActiveResourceProfileNames(),\n\t\t\t...(session.model ? { modelRef: `${session.model.provider}/${session.model.id}` } : {}),\n\t\t\tcontextPointers: [],\n\t\t});\n\n\t\tconst [worktreeSync, processMatrix] = await Promise.all([\n\t\t\tstartWorktreeSyncRuntime({\n\t\t\t\tcwd: sessionManager.getCwd(),\n\t\t\t\tagentDir: this.options.agentDir,\n\t\t\t\tsettingsManager: session.settingsManager,\n\t\t\t\tsessionId,\n\t\t\t\tnotify: (text) => {\n\t\t\t\t\tvoid this.notify(session, \"worktree-sync-notice\", text).catch(() => {});\n\t\t\t\t},\n\t\t\t\tonDiagnostic: this.options.onDiagnostic,\n\t\t\t}),\n\t\t\tstartProcessMatrixRuntime({\n\t\t\t\tagentDir: this.options.agentDir,\n\t\t\t\tagent,\n\t\t\t\t...(taskRef ? { taskRef } : {}),\n\t\t\t\ttaskSummary: goal?.userGoal,\n\t\t\t\tallowAutomaticRecovery: goal === undefined || goal.status === \"active\",\n\t\t\t\tresumeWorker: (payload) => this.options.resumeWorker(payload, sessionId),\n\t\t\t\thasUI: this.options.hasUI,\n\t\t\t\tsettings: session.settingsManager.getProcessMatrixSettings(),\n\t\t\t\tisProcessAlive: this.options.isProcessAlive,\n\t\t\t\tpromptConfirm: this.options.promptConfirm,\n\t\t\t\tnotify: (text) => this.notify(session, \"process-matrix-notice\", text),\n\t\t\t\tonDiagnostic: this.options.onDiagnostic,\n\t\t\t\trequestExit: () => this.options.requestExit(session),\n\t\t\t}),\n\t\t]);\n\n\t\tif (generation !== this.generation) {\n\t\t\tawait Promise.all([worktreeSync.stop(), processMatrix.stop()]);\n\t\t\treturn;\n\t\t}\n\t\tthis.worktreeSync = worktreeSync;\n\t\tthis.processMatrix = processMatrix;\n\t}\n\n\tasync stop(): Promise<void> {\n\t\tthis.generation++;\n\t\tawait this.stopHandles();\n\t}\n\n\tprivate async stopHandles(): Promise<void> {\n\t\tconst worktreeSync = this.worktreeSync;\n\t\tconst processMatrix = this.processMatrix;\n\t\tthis.worktreeSync = undefined;\n\t\tthis.processMatrix = undefined;\n\t\tawait Promise.all([worktreeSync?.stop(), processMatrix?.stop()]);\n\t}\n\n\tprivate async notify(session: AgentSession, customType: string, text: string): Promise<void> {\n\t\ttry {\n\t\t\tawait session.sendCustomMessage(\n\t\t\t\t{ customType, content: text, display: true },\n\t\t\t\t{ triggerTurn: true, deliverAs: \"steer\" },\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\tthis.options.onDiagnostic(`${customType}: failed to notify session: ${message}`);\n\t\t\tthrow error;\n\t\t}\n\t}\n}\n"]}