@caupulican/pi-adaptative 0.84.1 → 0.85.0

package/dist/core/tools/file-mutation-intent.js

@@ -0,0 +1,325 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, copyFile, lstat, open, stat, unlink } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+const DEFAULT_INTENT_LIMIT = 64;
+const DEFAULT_CONTENT_REFERENCE_LIMIT = 64;
+const DEFAULT_INTENT_TTL_MS = 10 * 60 * 1000;
+const DEFAULT_CONTENT_REFERENCE_TTL_MS = 60 * 60 * 1000;
+const HASH_BUFFER_BYTES = 64 * 1024;
+const CONTENT_REFERENCE_PREFIX = "file-content:";
+function isMissingPathError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        (error.code === "ENOENT" || error.code === "ENOTDIR"));
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
+function normalizedPath(path) {
+    const absolutePath = resolve(path);
+    return process.platform === "win32" ? absolutePath.toLocaleLowerCase("en-US") : absolutePath;
+}
+function positiveBound(value, fallback, label) {
+    const resolvedValue = value ?? fallback;
+    if (!Number.isSafeInteger(resolvedValue) || resolvedValue < 1) {
+        throw new TypeError(`${label} must be a positive safe integer.`);
+    }
+    return resolvedValue;
+}
+function normalizedIdentity(value) {
+    return {
+        dev: String(value.dev),
+        ino: String(value.ino),
+        mode: String(value.mode),
+        size: String(value.size),
+        mtimeMs: String(value.mtimeMs),
+        ctimeMs: String(value.ctimeMs),
+    };
+}
+function identitiesMatch(left, right) {
+    return (left !== undefined &&
+        right !== undefined &&
+        left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.mode === right.mode &&
+        left.size === right.size &&
+        left.mtimeMs === right.mtimeMs &&
+        left.ctimeMs === right.ctimeMs);
+}
+async function inspectLocalPath(path, followSymlinks) {
+    try {
+        const result = followSymlinks ? await stat(path, { bigint: true }) : await lstat(path, { bigint: true });
+        return {
+            kind: result.isFile() ? "file" : result.isDirectory() ? "directory" : "other",
+            identity: normalizedIdentity(result),
+        };
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return undefined;
+        throw error;
+    }
+}
+async function hashLocalFile(path, signal) {
+    const handle = await open(path, "r");
+    const hash = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(HASH_BUFFER_BYTES);
+    try {
+        let position = 0;
+        while (true) {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+            position += bytesRead;
+        }
+        return hash.digest("hex");
+    }
+    finally {
+        await handle.close();
+    }
+}
+export const localFileMutationIntentOperations = {
+    inspect: inspectLocalPath,
+    access,
+    copyFileExclusive: (sourcePath, targetPath) => copyFile(sourcePath, targetPath, constants.COPYFILE_EXCL),
+    hashFile: hashLocalFile,
+    removeFile: unlink,
+};
+/**
+ * Session-owned authority for two-phase file mutation intents and bounded exact-content references.
+ * It retains only fixed-size metadata; file bytes remain owned by the filesystem.
+ */
+export class FileMutationIntentController {
+    constructor(options = {}) {
+        this.intents = new Map();
+        this.intentByPath = new Map();
+        this.contentReferences = new Map();
+        this.operations = options.operations ?? localFileMutationIntentOperations;
+        this.intentLimit = positiveBound(options.intentLimit, DEFAULT_INTENT_LIMIT, "Intent limit");
+        this.contentReferenceLimit = positiveBound(options.contentReferenceLimit, DEFAULT_CONTENT_REFERENCE_LIMIT, "Content reference limit");
+        this.intentTtlMs = positiveBound(options.intentTtlMs, DEFAULT_INTENT_TTL_MS, "Intent TTL");
+        this.contentReferenceTtlMs = positiveBound(options.contentReferenceTtlMs, DEFAULT_CONTENT_REFERENCE_TTL_MS, "Content reference TTL");
+        this.now = options.now ?? Date.now;
+    }
+    async prepare(kind, path, signal, displayPath = path) {
+        this.pruneExpired();
+        if (signal?.aborted)
+            throw new Error("Operation aborted");
+        const absolutePath = resolve(path);
+        let identity;
+        if (kind === "write") {
+            const existing = await this.operations.inspect(absolutePath, false);
+            if (existing)
+                throw new Error(`Write collision: ${displayPath} already exists.`);
+            await this.assertCreatableParent(absolutePath);
+        }
+        else {
+            const existing = await this.operations.inspect(absolutePath, true);
+            if (!existing)
+                throw new Error(`Could not edit file: ${displayPath}. Error code: ENOENT.`);
+            if (existing.kind !== "file")
+                throw new Error(`Could not edit file: ${displayPath}. Target is not a regular file.`);
+            try {
+                await this.operations.access(absolutePath, constants.R_OK | constants.W_OK);
+            }
+            catch (error) {
+                const code = errorCode(error);
+                throw new Error(`Could not edit file: ${displayPath}. ${code ? `Error code: ${code}` : String(error)}.`);
+            }
+            identity = existing.identity;
+        }
+        if (signal?.aborted)
+            throw new Error("Operation aborted");
+        const key = `${kind}\0${normalizedPath(absolutePath)}`;
+        const priorIntentId = this.intentByPath.get(key);
+        if (priorIntentId)
+            this.deleteIntent(priorIntentId);
+        while (this.intents.size >= this.intentLimit) {
+            const oldestIntentId = this.intents.keys().next().value;
+            if (typeof oldestIntentId !== "string")
+                break;
+            this.deleteIntent(oldestIntentId);
+        }
+        const intentId = randomUUID();
+        const record = {
+            intentId,
+            kind,
+            path: absolutePath,
+            displayPath,
+            ...(identity ? { identity } : {}),
+            expiresAt: this.now() + this.intentTtlMs,
+        };
+        this.intents.set(intentId, record);
+        this.intentByPath.set(key, intentId);
+        return { intentId, kind, path: absolutePath, displayPath };
+    }
+    consume(intentId, kind, path) {
+        this.pruneExpired();
+        const record = this.intents.get(intentId);
+        if (!record)
+            throw new Error("File mutation intent is invalid, expired, or belongs to another session.");
+        this.deleteIntent(intentId);
+        if (record.kind !== kind)
+            throw new Error(`File mutation intent is for ${record.kind}, not ${kind}.`);
+        if (normalizedPath(record.path) !== normalizedPath(path)) {
+            throw new Error("File mutation intent path does not match the commit path.");
+        }
+        return {
+            intentId: record.intentId,
+            kind: record.kind,
+            path: record.path,
+            displayPath: record.displayPath,
+            ...(record.identity ? { identity: record.identity } : {}),
+        };
+    }
+    async assertCurrent(lease, signal) {
+        if (signal?.aborted)
+            throw new Error("Operation aborted");
+        if (lease.kind === "write") {
+            if (await this.operations.inspect(lease.path, false)) {
+                throw new Error(`Write collision: ${lease.displayPath} already exists; the prepared intent is stale.`);
+            }
+            return;
+        }
+        const current = await this.operations.inspect(lease.path, true);
+        if (!current || current.kind !== "file") {
+            throw new Error(`Could not edit file: ${lease.displayPath}. The prepared target no longer exists.`);
+        }
+        if (!identitiesMatch(lease.identity, current.identity)) {
+            throw new Error(`Could not edit file: ${lease.displayPath}. The file changed after preparation; prepare again.`);
+        }
+        try {
+            await this.operations.access(lease.path, constants.R_OK | constants.W_OK);
+        }
+        catch (error) {
+            const code = errorCode(error);
+            throw new Error(`Could not edit file: ${lease.displayPath}. ${code ? `Error code: ${code}` : String(error)}.`);
+        }
+    }
+    rememberContent(sourcePath, content) {
+        const digest = createHash("sha256").update(content, "utf8").digest("hex");
+        return this.rememberContentDigest(sourcePath, digest, Buffer.byteLength(content, "utf8"));
+    }
+    async copyReferencedContent(contentRef, targetPath, signal) {
+        this.pruneExpired();
+        const record = this.contentReferences.get(contentRef);
+        if (!record)
+            throw new Error("File content reference is invalid, expired, or belongs to another session.");
+        this.touchContentReference(record);
+        if (signal?.aborted)
+            throw new Error("Operation aborted");
+        let sourceDigest;
+        try {
+            sourceDigest = await this.operations.hashFile(record.sourcePath, signal);
+        }
+        catch (error) {
+            throw new Error(`File content reference source is unavailable: ${String(error)}.`);
+        }
+        if (sourceDigest !== record.digest) {
+            this.contentReferences.delete(contentRef);
+            throw new Error("File content reference source changed after it was cached.");
+        }
+        await this.operations.copyFileExclusive(record.sourcePath, targetPath);
+        let targetDigest;
+        try {
+            targetDigest = await this.operations.hashFile(targetPath, signal);
+        }
+        catch (error) {
+            await this.removeFailedCopy(targetPath, error);
+            throw error;
+        }
+        if (targetDigest !== record.digest) {
+            await this.removeFailedCopy(targetPath, new Error("copied bytes did not match the cached digest"));
+            throw new Error("File content copy changed while it was being created; the target was removed.");
+        }
+        return this.rememberContentDigest(targetPath, record.digest, record.byteLength);
+    }
+    async assertCreatableParent(path) {
+        let candidate = dirname(path);
+        while (true) {
+            const inspection = await this.operations.inspect(candidate, true);
+            if (inspection) {
+                if (inspection.kind !== "directory") {
+                    throw new Error(`Write parent path is not a directory: ${candidate}.`);
+                }
+                try {
+                    await this.operations.access(candidate, constants.W_OK);
+                }
+                catch (error) {
+                    const code = errorCode(error);
+                    throw new Error(`Write parent is not writable: ${candidate}${code ? ` (${code})` : ""}.`);
+                }
+                return;
+            }
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                throw new Error(`No writable parent exists for ${path}.`);
+            candidate = parent;
+        }
+    }
+    rememberContentDigest(sourcePath, digest, byteLength) {
+        this.pruneExpired();
+        for (const existing of this.contentReferences.values()) {
+            if (existing.sourcePath === sourcePath && existing.digest === digest) {
+                this.touchContentReference(existing);
+                return { contentRef: existing.contentRef, byteLength: existing.byteLength };
+            }
+        }
+        while (this.contentReferences.size >= this.contentReferenceLimit) {
+            const oldestContentRef = this.contentReferences.keys().next().value;
+            if (typeof oldestContentRef !== "string")
+                break;
+            this.contentReferences.delete(oldestContentRef);
+        }
+        const contentRef = `${CONTENT_REFERENCE_PREFIX}${randomUUID()}`;
+        this.contentReferences.set(contentRef, {
+            contentRef,
+            sourcePath,
+            digest,
+            byteLength,
+            expiresAt: this.now() + this.contentReferenceTtlMs,
+        });
+        return { contentRef, byteLength };
+    }
+    touchContentReference(record) {
+        record.expiresAt = this.now() + this.contentReferenceTtlMs;
+        this.contentReferences.delete(record.contentRef);
+        this.contentReferences.set(record.contentRef, record);
+    }
+    async removeFailedCopy(path, cause) {
+        try {
+            await this.operations.removeFile(path);
+        }
+        catch (cleanupError) {
+            throw new Error(`Copied content verification failed (${String(cause)}), and the newly created target could not be removed: ${String(cleanupError)}.`);
+        }
+    }
+    deleteIntent(intentId) {
+        const record = this.intents.get(intentId);
+        if (!record)
+            return;
+        this.intents.delete(intentId);
+        const key = `${record.kind}\0${normalizedPath(record.path)}`;
+        if (this.intentByPath.get(key) === intentId)
+            this.intentByPath.delete(key);
+    }
+    pruneExpired() {
+        const now = this.now();
+        for (const [intentId, record] of this.intents) {
+            if (record.expiresAt <= now)
+                this.deleteIntent(intentId);
+        }
+        for (const [contentRef, record] of this.contentReferences) {
+            if (record.expiresAt <= now)
+                this.contentReferences.delete(contentRef);
+        }
+    }
+}
+//# sourceMappingURL=file-mutation-intent.js.map

package/dist/core/tools/file-mutation-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-mutation-intent.js","sourceRoot":"","sources":["../../../src/core/tools/file-mutation-intent.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { constants } from \"node:fs\";\nimport { access, copyFile, lstat, open, stat, unlink } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\n\nconst DEFAULT_INTENT_LIMIT = 64;\nconst DEFAULT_CONTENT_REFERENCE_LIMIT = 64;\nconst DEFAULT_INTENT_TTL_MS = 10 * 60 * 1000;\nconst DEFAULT_CONTENT_REFERENCE_TTL_MS = 60 * 60 * 1000;\nconst HASH_BUFFER_BYTES = 64 * 1024;\nconst CONTENT_REFERENCE_PREFIX = \"file-content:\";\n\nexport type FileMutationKind = \"write\" | \"edit\";\n\nexport interface FilePathIdentity {\n\tdev: string;\n\tino: string;\n\tmode: string;\n\tsize: string;\n\tmtimeMs: string;\n\tctimeMs: string;\n}\n\nexport interface FilePathInspection {\n\tkind: \"file\" | \"directory\" | \"other\";\n\tidentity: FilePathIdentity;\n}\n\nexport interface FileMutationIntentOperations {\n\tinspect(path: string, followSymlinks: boolean): Promise<FilePathInspection | undefined>;\n\taccess(path: string, mode: number): Promise<void>;\n\tcopyFileExclusive(sourcePath: string, targetPath: string): Promise<void>;\n\thashFile(path: string, signal?: AbortSignal): Promise<string>;\n\tremoveFile(path: string): Promise<void>;\n}\n\nexport interface PreparedFileMutation {\n\tintentId: string;\n\tkind: FileMutationKind;\n\tpath: string;\n\tdisplayPath: string;\n}\n\nexport interface FileMutationLease extends PreparedFileMutation {\n\tidentity?: FilePathIdentity;\n}\n\nexport interface FileContentReference {\n\tcontentRef: string;\n\tbyteLength: number;\n}\n\ninterface MutationIntentRecord extends FileMutationLease {\n\texpiresAt: number;\n}\n\ninterface ContentReferenceRecord {\n\tcontentRef: string;\n\tsourcePath: string;\n\tdigest: string;\n\tbyteLength: number;\n\texpiresAt: number;\n}\n\nexport interface FileMutationIntentControllerOptions {\n\toperations?: FileMutationIntentOperations;\n\tintentLimit?: number;\n\tcontentReferenceLimit?: number;\n\tintentTtlMs?: number;\n\tcontentReferenceTtlMs?: number;\n\tnow?: () => number;\n}\n\nfunction isMissingPathError(error: unknown): boolean {\n\treturn (\n\t\ttypeof error === \"object\" &&\n\t\terror !== null &&\n\t\t\"code\" in error &&\n\t\t(error.code === \"ENOENT\" || error.code === \"ENOTDIR\")\n\t);\n}\n\nfunction errorCode(error: unknown): string | undefined {\n\treturn typeof error === \"object\" && error !== null && \"code\" in error && typeof error.code === \"string\"\n\t\t? error.code\n\t\t: undefined;\n}\n\nfunction normalizedPath(path: string): string {\n\tconst absolutePath = resolve(path);\n\treturn process.platform === \"win32\" ? absolutePath.toLocaleLowerCase(\"en-US\") : absolutePath;\n}\n\nfunction positiveBound(value: number | undefined, fallback: number, label: string): number {\n\tconst resolvedValue = value ?? fallback;\n\tif (!Number.isSafeInteger(resolvedValue) || resolvedValue < 1) {\n\t\tthrow new TypeError(`${label} must be a positive safe integer.`);\n\t}\n\treturn resolvedValue;\n}\n\nfunction normalizedIdentity(value: {\n\tdev: number | bigint;\n\tino: number | bigint;\n\tmode: number | bigint;\n\tsize: number | bigint;\n\tmtimeMs: number | bigint;\n\tctimeMs: number | bigint;\n}): FilePathIdentity {\n\treturn {\n\t\tdev: String(value.dev),\n\t\tino: String(value.ino),\n\t\tmode: String(value.mode),\n\t\tsize: String(value.size),\n\t\tmtimeMs: String(value.mtimeMs),\n\t\tctimeMs: String(value.ctimeMs),\n\t};\n}\n\nfunction identitiesMatch(left: FilePathIdentity | undefined, right: FilePathIdentity | undefined): boolean {\n\treturn (\n\t\tleft !== undefined &&\n\t\tright !== undefined &&\n\t\tleft.dev === right.dev &&\n\t\tleft.ino === right.ino &&\n\t\tleft.mode === right.mode &&\n\t\tleft.size === right.size &&\n\t\tleft.mtimeMs === right.mtimeMs &&\n\t\tleft.ctimeMs === right.ctimeMs\n\t);\n}\n\nasync function inspectLocalPath(path: string, followSymlinks: boolean): Promise<FilePathInspection | undefined> {\n\ttry {\n\t\tconst result = followSymlinks ? await stat(path, { bigint: true }) : await lstat(path, { bigint: true });\n\t\treturn {\n\t\t\tkind: result.isFile() ? \"file\" : result.isDirectory() ? \"directory\" : \"other\",\n\t\t\tidentity: normalizedIdentity(result),\n\t\t};\n\t} catch (error) {\n\t\tif (isMissingPathError(error)) return undefined;\n\t\tthrow error;\n\t}\n}\n\nasync function hashLocalFile(path: string, signal?: AbortSignal): Promise<string> {\n\tconst handle = await open(path, \"r\");\n\tconst hash = createHash(\"sha256\");\n\tconst buffer = Buffer.allocUnsafe(HASH_BUFFER_BYTES);\n\ttry {\n\t\tlet position = 0;\n\t\twhile (true) {\n\t\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\t\t\tconst { bytesRead } = await handle.read(buffer, 0, buffer.length, position);\n\t\t\tif (bytesRead === 0) break;\n\t\t\thash.update(buffer.subarray(0, bytesRead));\n\t\t\tposition += bytesRead;\n\t\t}\n\t\treturn hash.digest(\"hex\");\n\t} finally {\n\t\tawait handle.close();\n\t}\n}\n\nexport const localFileMutationIntentOperations: FileMutationIntentOperations = {\n\tinspect: inspectLocalPath,\n\taccess,\n\tcopyFileExclusive: (sourcePath, targetPath) => copyFile(sourcePath, targetPath, constants.COPYFILE_EXCL),\n\thashFile: hashLocalFile,\n\tremoveFile: unlink,\n};\n\n/**\n * Session-owned authority for two-phase file mutation intents and bounded exact-content references.\n * It retains only fixed-size metadata; file bytes remain owned by the filesystem.\n */\nexport class FileMutationIntentController {\n\tprivate readonly operations: FileMutationIntentOperations;\n\tprivate readonly intentLimit: number;\n\tprivate readonly contentReferenceLimit: number;\n\tprivate readonly intentTtlMs: number;\n\tprivate readonly contentReferenceTtlMs: number;\n\tprivate readonly now: () => number;\n\tprivate readonly intents = new Map<string, MutationIntentRecord>();\n\tprivate readonly intentByPath = new Map<string, string>();\n\tprivate readonly contentReferences = new Map<string, ContentReferenceRecord>();\n\n\tconstructor(options: FileMutationIntentControllerOptions = {}) {\n\t\tthis.operations = options.operations ?? localFileMutationIntentOperations;\n\t\tthis.intentLimit = positiveBound(options.intentLimit, DEFAULT_INTENT_LIMIT, \"Intent limit\");\n\t\tthis.contentReferenceLimit = positiveBound(\n\t\t\toptions.contentReferenceLimit,\n\t\t\tDEFAULT_CONTENT_REFERENCE_LIMIT,\n\t\t\t\"Content reference limit\",\n\t\t);\n\t\tthis.intentTtlMs = positiveBound(options.intentTtlMs, DEFAULT_INTENT_TTL_MS, \"Intent TTL\");\n\t\tthis.contentReferenceTtlMs = positiveBound(\n\t\t\toptions.contentReferenceTtlMs,\n\t\t\tDEFAULT_CONTENT_REFERENCE_TTL_MS,\n\t\t\t\"Content reference TTL\",\n\t\t);\n\t\tthis.now = options.now ?? Date.now;\n\t}\n\n\tasync prepare(\n\t\tkind: FileMutationKind,\n\t\tpath: string,\n\t\tsignal?: AbortSignal,\n\t\tdisplayPath: string = path,\n\t): Promise<PreparedFileMutation> {\n\t\tthis.pruneExpired();\n\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\t\tconst absolutePath = resolve(path);\n\t\tlet identity: FilePathIdentity | undefined;\n\t\tif (kind === \"write\") {\n\t\t\tconst existing = await this.operations.inspect(absolutePath, false);\n\t\t\tif (existing) throw new Error(`Write collision: ${displayPath} already exists.`);\n\t\t\tawait this.assertCreatableParent(absolutePath);\n\t\t} else {\n\t\t\tconst existing = await this.operations.inspect(absolutePath, true);\n\t\t\tif (!existing) throw new Error(`Could not edit file: ${displayPath}. Error code: ENOENT.`);\n\t\t\tif (existing.kind !== \"file\")\n\t\t\t\tthrow new Error(`Could not edit file: ${displayPath}. Target is not a regular file.`);\n\t\t\ttry {\n\t\t\t\tawait this.operations.access(absolutePath, constants.R_OK | constants.W_OK);\n\t\t\t} catch (error) {\n\t\t\t\tconst code = errorCode(error);\n\t\t\t\tthrow new Error(`Could not edit file: ${displayPath}. ${code ? `Error code: ${code}` : String(error)}.`);\n\t\t\t}\n\t\t\tidentity = existing.identity;\n\t\t}\n\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\n\t\tconst key = `${kind}\\0${normalizedPath(absolutePath)}`;\n\t\tconst priorIntentId = this.intentByPath.get(key);\n\t\tif (priorIntentId) this.deleteIntent(priorIntentId);\n\t\twhile (this.intents.size >= this.intentLimit) {\n\t\t\tconst oldestIntentId = this.intents.keys().next().value;\n\t\t\tif (typeof oldestIntentId !== \"string\") break;\n\t\t\tthis.deleteIntent(oldestIntentId);\n\t\t}\n\t\tconst intentId = randomUUID();\n\t\tconst record: MutationIntentRecord = {\n\t\t\tintentId,\n\t\t\tkind,\n\t\t\tpath: absolutePath,\n\t\t\tdisplayPath,\n\t\t\t...(identity ? { identity } : {}),\n\t\t\texpiresAt: this.now() + this.intentTtlMs,\n\t\t};\n\t\tthis.intents.set(intentId, record);\n\t\tthis.intentByPath.set(key, intentId);\n\t\treturn { intentId, kind, path: absolutePath, displayPath };\n\t}\n\n\tconsume(intentId: string, kind: FileMutationKind, path: string): FileMutationLease {\n\t\tthis.pruneExpired();\n\t\tconst record = this.intents.get(intentId);\n\t\tif (!record) throw new Error(\"File mutation intent is invalid, expired, or belongs to another session.\");\n\t\tthis.deleteIntent(intentId);\n\t\tif (record.kind !== kind) throw new Error(`File mutation intent is for ${record.kind}, not ${kind}.`);\n\t\tif (normalizedPath(record.path) !== normalizedPath(path)) {\n\t\t\tthrow new Error(\"File mutation intent path does not match the commit path.\");\n\t\t}\n\t\treturn {\n\t\t\tintentId: record.intentId,\n\t\t\tkind: record.kind,\n\t\t\tpath: record.path,\n\t\t\tdisplayPath: record.displayPath,\n\t\t\t...(record.identity ? { identity: record.identity } : {}),\n\t\t};\n\t}\n\n\tasync assertCurrent(lease: FileMutationLease, signal?: AbortSignal): Promise<void> {\n\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\t\tif (lease.kind === \"write\") {\n\t\t\tif (await this.operations.inspect(lease.path, false)) {\n\t\t\t\tthrow new Error(`Write collision: ${lease.displayPath} already exists; the prepared intent is stale.`);\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\tconst current = await this.operations.inspect(lease.path, true);\n\t\tif (!current || current.kind !== \"file\") {\n\t\t\tthrow new Error(`Could not edit file: ${lease.displayPath}. The prepared target no longer exists.`);\n\t\t}\n\t\tif (!identitiesMatch(lease.identity, current.identity)) {\n\t\t\tthrow new Error(\n\t\t\t\t`Could not edit file: ${lease.displayPath}. The file changed after preparation; prepare again.`,\n\t\t\t);\n\t\t}\n\t\ttry {\n\t\t\tawait this.operations.access(lease.path, constants.R_OK | constants.W_OK);\n\t\t} catch (error) {\n\t\t\tconst code = errorCode(error);\n\t\t\tthrow new Error(`Could not edit file: ${lease.displayPath}. ${code ? `Error code: ${code}` : String(error)}.`);\n\t\t}\n\t}\n\n\trememberContent(sourcePath: string, content: string): FileContentReference {\n\t\tconst digest = createHash(\"sha256\").update(content, \"utf8\").digest(\"hex\");\n\t\treturn this.rememberContentDigest(sourcePath, digest, Buffer.byteLength(content, \"utf8\"));\n\t}\n\n\tasync copyReferencedContent(\n\t\tcontentRef: string,\n\t\ttargetPath: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<FileContentReference> {\n\t\tthis.pruneExpired();\n\t\tconst record = this.contentReferences.get(contentRef);\n\t\tif (!record) throw new Error(\"File content reference is invalid, expired, or belongs to another session.\");\n\t\tthis.touchContentReference(record);\n\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\t\tlet sourceDigest: string;\n\t\ttry {\n\t\t\tsourceDigest = await this.operations.hashFile(record.sourcePath, signal);\n\t\t} catch (error) {\n\t\t\tthrow new Error(`File content reference source is unavailable: ${String(error)}.`);\n\t\t}\n\t\tif (sourceDigest !== record.digest) {\n\t\t\tthis.contentReferences.delete(contentRef);\n\t\t\tthrow new Error(\"File content reference source changed after it was cached.\");\n\t\t}\n\n\t\tawait this.operations.copyFileExclusive(record.sourcePath, targetPath);\n\t\tlet targetDigest: string;\n\t\ttry {\n\t\t\ttargetDigest = await this.operations.hashFile(targetPath, signal);\n\t\t} catch (error) {\n\t\t\tawait this.removeFailedCopy(targetPath, error);\n\t\t\tthrow error;\n\t\t}\n\t\tif (targetDigest !== record.digest) {\n\t\t\tawait this.removeFailedCopy(targetPath, new Error(\"copied bytes did not match the cached digest\"));\n\t\t\tthrow new Error(\"File content copy changed while it was being created; the target was removed.\");\n\t\t}\n\t\treturn this.rememberContentDigest(targetPath, record.digest, record.byteLength);\n\t}\n\n\tprivate async assertCreatableParent(path: string): Promise<void> {\n\t\tlet candidate = dirname(path);\n\t\twhile (true) {\n\t\t\tconst inspection = await this.operations.inspect(candidate, true);\n\t\t\tif (inspection) {\n\t\t\t\tif (inspection.kind !== \"directory\") {\n\t\t\t\t\tthrow new Error(`Write parent path is not a directory: ${candidate}.`);\n\t\t\t\t}\n\t\t\t\ttry {\n\t\t\t\t\tawait this.operations.access(candidate, constants.W_OK);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tconst code = errorCode(error);\n\t\t\t\t\tthrow new Error(`Write parent is not writable: ${candidate}${code ? ` (${code})` : \"\"}.`);\n\t\t\t\t}\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst parent = dirname(candidate);\n\t\t\tif (parent === candidate) throw new Error(`No writable parent exists for ${path}.`);\n\t\t\tcandidate = parent;\n\t\t}\n\t}\n\n\tprivate rememberContentDigest(sourcePath: string, digest: string, byteLength: number): FileContentReference {\n\t\tthis.pruneExpired();\n\t\tfor (const existing of this.contentReferences.values()) {\n\t\t\tif (existing.sourcePath === sourcePath && existing.digest === digest) {\n\t\t\t\tthis.touchContentReference(existing);\n\t\t\t\treturn { contentRef: existing.contentRef, byteLength: existing.byteLength };\n\t\t\t}\n\t\t}\n\t\twhile (this.contentReferences.size >= this.contentReferenceLimit) {\n\t\t\tconst oldestContentRef = this.contentReferences.keys().next().value;\n\t\t\tif (typeof oldestContentRef !== \"string\") break;\n\t\t\tthis.contentReferences.delete(oldestContentRef);\n\t\t}\n\t\tconst contentRef = `${CONTENT_REFERENCE_PREFIX}${randomUUID()}`;\n\t\tthis.contentReferences.set(contentRef, {\n\t\t\tcontentRef,\n\t\t\tsourcePath,\n\t\t\tdigest,\n\t\t\tbyteLength,\n\t\t\texpiresAt: this.now() + this.contentReferenceTtlMs,\n\t\t});\n\t\treturn { contentRef, byteLength };\n\t}\n\n\tprivate touchContentReference(record: ContentReferenceRecord): void {\n\t\trecord.expiresAt = this.now() + this.contentReferenceTtlMs;\n\t\tthis.contentReferences.delete(record.contentRef);\n\t\tthis.contentReferences.set(record.contentRef, record);\n\t}\n\n\tprivate async removeFailedCopy(path: string, cause: unknown): Promise<void> {\n\t\ttry {\n\t\t\tawait this.operations.removeFile(path);\n\t\t} catch (cleanupError) {\n\t\t\tthrow new Error(\n\t\t\t\t`Copied content verification failed (${String(cause)}), and the newly created target could not be removed: ${String(cleanupError)}.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate deleteIntent(intentId: string): void {\n\t\tconst record = this.intents.get(intentId);\n\t\tif (!record) return;\n\t\tthis.intents.delete(intentId);\n\t\tconst key = `${record.kind}\\0${normalizedPath(record.path)}`;\n\t\tif (this.intentByPath.get(key) === intentId) this.intentByPath.delete(key);\n\t}\n\n\tprivate pruneExpired(): void {\n\t\tconst now = this.now();\n\t\tfor (const [intentId, record] of this.intents) {\n\t\t\tif (record.expiresAt <= now) this.deleteIntent(intentId);\n\t\t}\n\t\tfor (const [contentRef, record] of this.contentReferences) {\n\t\t\tif (record.expiresAt <= now) this.contentReferences.delete(contentRef);\n\t\t}\n\t}\n}\n"]}

package/dist/core/tools/goal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"goal.d.ts","sourceRoot":"","sources":["../../../src/core/tools/goal.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,KAAK,iBAAiB,EAAwB,MAAM,4BAA4B,CAAC;AAC1F,OAAO,KAAK,EAAoB,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,eAAe,EAEpB,MAAM,4BAA4B,CAAC;AAQpC,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;EAkEf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,cAAc,GAAG,KAAK,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;iHAE6G;IAC7G,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;uGAImG;IACnG,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACpC,mEAAmE;IACnE,YAAY,EAAE,MAAM,SAAS,GAAG,SAAS,CAAC;IAC1C,+DAA+D;IAC/D,aAAa,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACxE,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,SAAS,UAAU,EAAE,CAAC;IAC7C;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,MAAM,SAAS,WAAW,EAAE,CAAC;IACvD;;;;;;;;;OASG;IACH,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC9B,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;KACrB,KAAK;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC3D;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC3B,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;KACrB,KAAK,OAAO,CAAC;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,mGAAmG;IACnG,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;OAGG;IACH,oCAAoC,CAAC,EAAE,MAAM,OAAO,CAAC;IACrD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,SAAS,eAAe,EAAE,CAAC;CACpD;AA4JD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,oBAAoB,GAAG,cAAc,CAkKnF"}
+{"version":3,"file":"goal.d.ts","sourceRoot":"","sources":["../../../src/core/tools/goal.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,KAAK,iBAAiB,EAAwB,MAAM,4BAA4B,CAAC;AAC1F,OAAO,KAAK,EAAoB,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,eAAe,EAEpB,MAAM,4BAA4B,CAAC;AAQpC,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;EAgEf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,cAAc,GAAG,KAAK,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;iHAE6G;IAC7G,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;uGAImG;IACnG,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACpC,mEAAmE;IACnE,YAAY,EAAE,MAAM,SAAS,GAAG,SAAS,CAAC;IAC1C,+DAA+D;IAC/D,aAAa,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACxE,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,SAAS,UAAU,EAAE,CAAC;IAC7C;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,MAAM,SAAS,WAAW,EAAE,CAAC;IACvD;;;;;;;;;OASG;IACH,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC9B,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;KACrB,KAAK;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC3D;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC3B,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;KACrB,KAAK,OAAO,CAAC;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,mGAAmG;IACnG,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;OAGG;IACH,oCAAoC,CAAC,EAAE,MAAM,OAAO,CAAC;IACrD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,SAAS,eAAe,EAAE,CAAC;CACpD;AAgKD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,oBAAoB,GAAG,cAAc,CAsLnF"}

package/dist/core/tools/goal.js

@@ -23,13 +23,13 @@ const goalSchema = Type.Object({
     userGoal: Type.Optional(Type.String({ description: "The goal statement. Required for action 'start'." })),
     tokenBudget: Type.Optional(Type.Integer({ minimum: 1, description: "Optional positive token budget for action 'start'." })),
     requirementId: Type.Optional(Type.String({
-        description: "Requirement id for add_requirement/satisfy_requirement/block_requirement/reopen_requirement/dispatch_worker.",
+        description: "Requirement id for requirement actions.",
     })),
     text: Type.Optional(Type.String({ description: "Requirement text. Required for add_requirement." })),
     instructions: Type.Optional(Type.String({ description: "Worker instructions. Required for dispatch_worker." })),
     evidenceId: Type.Optional(Type.String({ description: "Evidence id. Required for add_evidence." })),
     evidenceIds: Type.Optional(Type.Array(Type.String(), {
-        description: "Evidence ids supporting a satisfy_requirement action. Each must already be recorded.",
+        description: "Existing evidence ids for satisfy_requirement.",
     })),
     kind: Type.Optional(Type.Union([
         Type.Literal("file"),
@@ -41,13 +41,16 @@ const goalSchema = Type.Object({
     ], { description: "Evidence kind. Required for add_evidence." })),
     summary: Type.Optional(Type.String({ description: "Evidence summary. Required for add_evidence." })),
     uri: Type.Optional(Type.String({
-        description: "Optional evidence locator (path/URL for kind 'file', a toolCallId for kind 'tool', a laneId for kind 'worker').",
+        description: "Optional file/URL, toolCallId, or laneId evidence locator.",
     })),
     reason: Type.Optional(Type.String({ description: "Reason for block_requirement or block_goal." })),
     dispatchTarget: Type.Optional(Type.Union([Type.Literal("in_process"), Type.Literal("tmux")], {
-        description: "Legacy worker target. Prefer the delegate tool for new work.",
+        description: "Legacy target. Native is default; use tmux only for an owner-requested persistent pane.",
     })),
 }, { additionalProperties: false });
+function allowsNativeTmuxFallback(reason) {
+    return reason === "tmux_unavailable" || reason === "tmux_extension_not_loaded";
+}
 /**
  * Validate an evidence ref's `uri` against session records ("tool") or the filesystem ("file").
  * Returns `undefined` for kinds/refs that carry nothing checkable (e.g. "user"/"finding"/"test",
@@ -204,12 +207,12 @@ export function createGoalToolDefinition(deps) {
     return {
         name: "goal",
         label: "goal",
-        description: "Read or update the compact durable goal record for explicitly requested long-running work. Planning belongs to task_steps, workers to delegate, and evidence to current tools/artifacts. Pause, resume, edit, clear, and budget stops are owner/system controlled.",
-        promptSnippet: "Read or update the compact durable goal record.",
+        description: "Read or update the durable goal for explicitly persistent work. Use task_steps for plans and delegate for workers; owner or system controls lifecycle and budget stops.",
+        promptSnippet: "Read or update the durable goal.",
         promptGuidelines: [
-            "Call action 'start' only when the user or system explicitly requests a persistent goal; that request may be ordinary chat and does not require a slash command. The host may already have admitted high-confidence chat wording, so use 'get' before starting when uncertain. Do not infer a goal from an ordinary multi-step task or replace an unfinished goal implicitly. Set tokenBudget only when the user explicitly requested a token budget.",
-            "Use 'get' when the current objective or status is uncertain. Use task_steps for decomposition and delegate for workers; detailed ledger actions exist only for goals that already use the legacy ledger.",
-            "Mark 'complete' only after current authoritative evidence proves the full objective and no required work remains. Mark 'block_goal' only after the same genuine impasse persists for three goal turns.",
+            "Start only for an explicit persistent goal from chat or system; no slash command is needed. Use get when uncertain, never replace an unfinished goal, and set tokenBudget only when explicitly requested.",
+            "Use task_steps for plans and delegate for workers; use legacy actions only on legacy goals.",
+            "Complete only with current authoritative evidence and no remaining work; block_goal only after the same real impasse lasts three goal turns.",
         ],
         parameters: goalSchema,
         renderShell: "self",
@@ -291,26 +294,46 @@ export function createGoalToolDefinition(deps) {
                 }
             }
             if (action.action === "dispatch_worker" && !dispatchGuardRefused) {
-                const useTmux = input.dispatchTarget === "tmux" && deps.dispatchTmuxWorker !== undefined;
-                const dispatched = useTmux
-                    ? await deps.dispatchTmuxWorker?.({
+                const tmuxRequested = input.dispatchTarget === "tmux";
+                let useTmux = tmuxRequested && deps.dispatchTmuxWorker !== undefined;
+                let tmuxFallbackReason;
+                let dispatched;
+                if (useTmux) {
+                    dispatched = await deps.dispatchTmuxWorker?.({
                         requirementId: action.requirementId,
                         instructions: action.instructions,
-                    })
-                    : deps.startWorkerDelegation?.({
+                    });
+                    if (!dispatched?.laneId &&
+                        allowsNativeTmuxFallback(dispatched?.skipReason) &&
+                        deps.startWorkerDelegation) {
+                        tmuxFallbackReason = dispatched?.skipReason;
+                        useTmux = false;
+                        dispatched = deps.startWorkerDelegation({
+                            requirementId: action.requirementId,
+                            instructions: action.instructions,
+                        });
+                    }
+                }
+                else {
+                    if (tmuxRequested)
+                        tmuxFallbackReason = "tmux_extension_not_loaded";
+                    dispatched = deps.startWorkerDelegation?.({
                         requirementId: action.requirementId,
                         instructions: action.instructions,
                     });
+                }
                 action = { ...action, laneId: dispatched?.laneId };
                 if (dispatched?.laneId) {
-                    dispatchNote = useTmux
-                        ? `Dispatched tmux worker lane '${dispatched.laneId}' for requirement '${action.requirementId}'.`
-                        : `Dispatched in-process worker lane '${dispatched.laneId}' for requirement '${action.requirementId}' (tmux dispatch is not available from this tool yet).`;
+                    dispatchNote = tmuxFallbackReason
+                        ? `Tmux route returned ${tmuxFallbackReason}; dispatched native fallback worker lane '${dispatched.laneId}' for requirement '${action.requirementId}'.`
+                        : useTmux
+                            ? `Dispatched tmux worker lane '${dispatched.laneId}' for requirement '${action.requirementId}'.`
+                            : `Dispatched in-process worker lane '${dispatched.laneId}' for requirement '${action.requirementId}' (native default).`;
                 }
                 else {
                     const wired = useTmux ? deps.dispatchTmuxWorker : deps.startWorkerDelegation;
                     dispatchSkipReason = dispatched?.skipReason ?? (wired ? "declined" : "dependency_unwired");
-                    dispatchNote = `No worker was dispatched (${dispatchSkipReason}); requirement '${action.requirementId}' is recorded but not bound to a lane.`;
+                    dispatchNote = `${tmuxFallbackReason ? `Tmux route returned ${tmuxFallbackReason}; ` : ""}No worker was dispatched (${dispatchSkipReason}); requirement '${action.requirementId}' is recorded but not bound to a lane.`;
                 }
             }
             const current = deps.getGoalState();