@sayknow-cli/coding-agent 0.4.7 → 0.5.1

package/src/internal-urls/local-protocol.ts

@@ -149,6 +149,19 @@ async function assertDirectoryNotSymlink(directoryPath: string): Promise<void> {
 const LEGACY_MIGRATION_MARKER = ".skc-local-legacy-migrated-v1";
 const MAX_LEGACY_LOCAL_BYTES = 64 * 1024 * 1024;
 
+type LegacyMigrationState = "complete" | "cleanup_pending";
+
+/**
+ * Marker values that mean legacy migration has settled for this root and the
+ * synchronous resolver may proceed. `cleanup_pending` counts: the entries are
+ * installed and content-verified, and only retirement of the legacy source is
+ * outstanding. Must stay in sync with {@link readMigrationMarker}, which the
+ * async gate uses to decide the same question.
+ */
+function isSettledMigrationMarkerValue(value: string): boolean {
+	return value === "verified\n" || value === "absent\n" || value === "cleanup_pending\n";
+}
+
 interface LegacyEntrySnapshot {
 	readonly relativePath: string;
 	readonly dev: bigint;
@@ -173,6 +186,26 @@ async function snapshotDirectory(directoryPath: string, relativePath: string): P
 	return { relativePath, dev: stat.dev, ino: stat.ino, size: stat.size };
 }
 
+interface CanonicalLegacyRoot {
+	readonly root: string;
+	readonly identity: LegacyEntrySnapshot;
+}
+
+async function canonicalLegacyRoot(artifactsDir: string): Promise<CanonicalLegacyRoot> {
+	const lexicalRoot = path.resolve(artifactsDir, "local");
+	const lexicalIdentity = await snapshotDirectory(lexicalRoot, "");
+	const [canonicalArtifactsDir, canonicalRoot] = await Promise.all([
+		fs.realpath(path.resolve(artifactsDir)),
+		fs.realpath(lexicalRoot),
+	]);
+	if (canonicalRoot === canonicalArtifactsDir) throw new Error("Unsafe legacy local:// migration source");
+	ensureWithinRoot(canonicalRoot, canonicalArtifactsDir);
+	const canonicalIdentity = await snapshotDirectory(canonicalRoot, "");
+	if (!matchesSnapshot(canonicalIdentity, lexicalIdentity))
+		throw new Error("Legacy local:// migration source changed during capture");
+	return { root: canonicalRoot, identity: lexicalIdentity };
+}
+
 async function snapshotRegularFile(filePath: string, relativePath: string): Promise<LegacyEntrySnapshot> {
 	const before = await fs.lstat(filePath, { bigint: true });
 	if (!before.isFile() || before.isSymbolicLink()) throw new Error("Unsafe legacy local:// migration source");
@@ -206,11 +239,16 @@ function manifestsMatch(left: readonly LegacyEntrySnapshot[], right: readonly Le
 	);
 }
 
-async function captureLegacyManifest(root: string): Promise<readonly LegacyEntrySnapshot[]> {
+async function captureLegacyManifest(
+	root: string,
+	expectedRootIdentity: LegacyEntrySnapshot,
+): Promise<readonly LegacyEntrySnapshot[]> {
 	const manifest: LegacyEntrySnapshot[] = [];
 	let copiedBytes = 0n;
 	const captureDirectory = async (directoryPath: string, relativePath: string): Promise<void> => {
 		const directory = await snapshotDirectory(directoryPath, relativePath);
+		if (relativePath === "" && !matchesSnapshot(directory, expectedRootIdentity))
+			throw new Error("Legacy local:// migration source changed during capture");
 		manifest.push(directory);
 		const entries = (await fs.readdir(directoryPath, { withFileTypes: true })).sort((a, b) =>
 			a.name.localeCompare(b.name),
@@ -313,7 +351,7 @@ async function migrateManagedLegacyLocal(
 	}
 	const staging = path.join(scratchParent, `.skc-local-migration-${randomUUID()}`);
 	const installed: Array<{ readonly path: string; readonly dev: bigint; readonly ino: bigint }> = [];
-	let installedMarker: { readonly dev: bigint; readonly ino: bigint } | null = null;
+	let sourceRetired = false;
 	try {
 		await fs.mkdir(staging, { mode: 0o700 });
 		for (const entry of captured.entries) {
@@ -327,7 +365,7 @@ async function migrateManagedLegacyLocal(
 					throw new Error("Legacy local:// migration destination verification failed");
 			}
 		}
-		for (const entry of await fs.readdir(staging)) {
+		for (const entry of (await fs.readdir(staging)).sort()) {
 			const destination = path.join(localRoot, entry);
 			try {
 				await fs.lstat(destination);
@@ -339,18 +377,22 @@ async function migrateManagedLegacyLocal(
 			const identity = await fs.lstat(destination, { bigint: true });
 			installed.push({ path: destination, dev: identity.dev, ino: identity.ino });
 		}
+		try {
+			source.retire(captured.snapshot);
+			sourceRetired = true;
+		} catch (error) {
+			if (!(error instanceof Error) || error.message !== "cleanup_pending") throw error;
+			await fs.writeFile(marker, "cleanup_pending\n", { mode: 0o600, flag: "wx" });
+			return;
+		}
 		await fs.writeFile(marker, "verified\n", { mode: 0o600, flag: "wx" });
-		const markerIdentity = await fs.lstat(marker, { bigint: true });
-		installedMarker = { dev: markerIdentity.dev, ino: markerIdentity.ino };
-		source.retire(captured.snapshot);
 	} catch (error) {
-		const currentMarker = await fs.lstat(marker, { bigint: true }).catch(() => null);
-		if (installedMarker && currentMarker?.dev === installedMarker.dev && currentMarker.ino === installedMarker.ino)
-			await fs.rm(marker, { force: true });
-		for (const destination of installed.reverse()) {
-			const current = await fs.lstat(destination.path, { bigint: true }).catch(() => null);
-			if (current?.dev === destination.dev && current.ino === destination.ino)
-				await fs.rm(destination.path, { recursive: true, force: true });
+		if (!sourceRetired) {
+			for (const destination of installed.reverse()) {
+				const current = await fs.lstat(destination.path, { bigint: true }).catch(() => null);
+				if (current?.dev === destination.dev && current.ino === destination.ino)
+					await fs.rm(destination.path, { recursive: true, force: true });
+			}
 		}
 		throw error;
 	} finally {
@@ -358,15 +400,16 @@ async function migrateManagedLegacyLocal(
 	}
 }
 
-async function readMigrationMarker(marker: string): Promise<boolean> {
+async function readMigrationMarker(marker: string): Promise<LegacyMigrationState | null> {
 	try {
 		const snapshot = await snapshotRegularFile(marker, LEGACY_MIGRATION_MARKER);
 		if (snapshot.size > 32n || snapshot.bytes === undefined) throw new Error("Unsafe local:// migration marker");
 		const value = snapshot.bytes.toString("utf8");
-		if (value !== "verified\n" && value !== "absent\n") throw new Error("Unsafe local:// migration marker");
-		return true;
+		if (value === "cleanup_pending\n") return "cleanup_pending";
+		if (value === "verified\n" || value === "absent\n") return "complete";
+		throw new Error("Unsafe local:// migration marker");
 	} catch (error) {
-		if (isEnoent(error)) return false;
+		if (isEnoent(error)) return null;
 		throw error;
 	}
 }
@@ -388,10 +431,11 @@ async function migrateLegacyLocal(
 		await fs.writeFile(marker, "absent\n", { mode: 0o600, flag: "wx" });
 		return;
 	}
-	const legacyRoot = path.resolve(artifactsDir, "local");
+	let legacySource: CanonicalLegacyRoot;
 	let manifest: readonly LegacyEntrySnapshot[];
 	try {
-		manifest = await captureLegacyManifest(legacyRoot);
+		legacySource = await canonicalLegacyRoot(artifactsDir);
+		manifest = await captureLegacyManifest(legacySource.root, legacySource.identity);
 	} catch (error) {
 		if (isEnoent(error)) {
 			await fs.writeFile(marker, "absent\n", { mode: 0o600, flag: "wx" });
@@ -401,8 +445,8 @@ async function migrateLegacyLocal(
 	}
 	const staging = path.join(scratchParent, `.skc-local-migration-${randomUUID()}`);
 	try {
-		await copyLegacyManifest(legacyRoot, staging, manifest);
-		const verifiedManifest = await captureLegacyManifest(legacyRoot);
+		await copyLegacyManifest(legacySource.root, staging, manifest);
+		const verifiedManifest = await captureLegacyManifest(legacySource.root, legacySource.identity);
 		if (!manifestsMatch(verifiedManifest, manifest))
 			throw new Error("Legacy local:// migration source changed during capture");
 		for (const entry of await fs.readdir(staging)) {
@@ -414,7 +458,17 @@ async function migrateLegacyLocal(
 			}
 			await fs.rename(path.join(staging, entry), path.join(localRoot, entry));
 		}
-		await retireLegacyTree(legacyRoot, manifest);
+		try {
+			await retireLegacyTree(legacySource.root, manifest);
+		} catch (error) {
+			if (
+				!(error instanceof Error) ||
+				error.message !== "Legacy local:// migration retirement failed: cleanup_pending"
+			)
+				throw error;
+			await fs.writeFile(marker, "cleanup_pending\n", { mode: 0o600, flag: "wx" });
+			return;
+		}
 		await fs.writeFile(marker, "verified\n", { mode: 0o600, flag: "wx" });
 	} finally {
 		await fs.rm(staging, { recursive: true, force: true });
@@ -501,8 +555,13 @@ function initializeLocalRootSyncWhenLegacyAbsent(options: LocalProtocolOptions,
 	if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error("Unsafe local:// root");
 	const marker = path.join(localRoot, LEGACY_MIGRATION_MARKER);
 	try {
-		const value = fsSync.readFileSync(marker, "utf8");
-		if (value !== "verified\n" && value !== "absent\n") throw new Error("Unsafe local:// migration marker");
+		// Accept exactly the marker states the async gate treats as settled. A
+		// `cleanup_pending` marker means the entries are fully installed and verified
+		// and only retirement of the legacy source is outstanding, so resolution is
+		// safe; rejecting it here made the sync resolver fail closed on a root the
+		// async gate had already completed.
+		if (!isSettledMigrationMarkerValue(fsSync.readFileSync(marker, "utf8")))
+			throw new Error("Unsafe local:// migration marker");
 		initializedLocalRoots.add(localRoot);
 		return;
 	} catch (error) {
@@ -519,7 +578,10 @@ function initializeLocalRootSyncWhenLegacyAbsent(options: LocalProtocolOptions,
 		fsSync.writeFileSync(marker, "absent\n", { mode: 0o600, flag: "wx" });
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-		if (fsSync.readFileSync(marker, "utf8") !== "absent\n") throw new Error("Unsafe local:// migration marker");
+		// A concurrent initializer won the exclusive create. Any settled marker state
+		// it wrote is authoritative; only an unrecognized value is unsafe.
+		if (!isSettledMigrationMarkerValue(fsSync.readFileSync(marker, "utf8")))
+			throw new Error("Unsafe local:// migration marker");
 	}
 	initializedLocalRoots.add(localRoot);
 }

package/src/internal-urls/local-root-gc.ts

@@ -0,0 +1,127 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isEnoent } from "@sayknow-cli/utils";
+import type { GcCollectResult, GcContext, GcError, GcRecord, GcStoreAdapter } from "../skc-runtime/gc-runtime";
+
+/**
+ * GC for `local://` session roots.
+ *
+ * `resolveLocalRoot` gives every session its own `<tmp>/skc-local/<session-id>`
+ * directory, and the first `local://` resolution seeds it with a migration
+ * marker. Nothing ever removes those directories, so a machine accumulates one
+ * per session indefinitely — and the overwhelming majority only ever hold the
+ * marker, because most sessions never write a `local://` file.
+ *
+ * Only marker-only directories are eligible, and only after a grace period.
+ * That keeps the rule provably safe without needing a session-liveness oracle:
+ * a directory holding real content is never touched, and a session that just
+ * started is still inside its grace window.
+ */
+
+const LOCAL_ROOT_PARENT = "skc-local";
+const LEGACY_MIGRATION_MARKER = ".skc-local-legacy-migrated-v1";
+
+/** Directories younger than this are left alone so a live session is never raced. */
+const GRACE_MS = 24 * 60 * 60 * 1000;
+
+/** Bound the scan so a pathological directory cannot stall `skc gc`. */
+const MAX_ENTRIES = 20_000;
+
+function localRootParent(env: NodeJS.ProcessEnv): string {
+	return path.join(env.TMPDIR?.trim() || os.tmpdir(), LOCAL_ROOT_PARENT);
+}
+
+/** A root is prunable only when the marker is the single thing inside it. */
+async function classify(dir: string, now: number): Promise<{ status: string; stale: boolean; reason: string } | null> {
+	let entries: string[];
+	try {
+		entries = await fs.readdir(dir);
+	} catch (error) {
+		if (isEnoent(error)) return null;
+		throw error;
+	}
+
+	const extra = entries.filter(name => name !== LEGACY_MIGRATION_MARKER);
+	if (extra.length > 0)
+		return {
+			status: "in_use",
+			stale: false,
+			reason: `Holds ${extra.length} entr${extra.length === 1 ? "y" : "ies"} beyond the marker`,
+		};
+
+	const stat = await fs.stat(dir);
+	if (now - stat.mtimeMs < GRACE_MS) return { status: "recent", stale: false, reason: "Inside the grace window" };
+	return { status: "marker_only", stale: true, reason: "Only the migration marker, past the grace window" };
+}
+
+export const localRootsGcAdapter: GcStoreAdapter = {
+	store: "local_roots",
+	async collect(ctx: GcContext): Promise<GcCollectResult> {
+		const records: GcRecord[] = [];
+		const errors: GcError[] = [];
+		const parent = localRootParent(ctx.env);
+		const now = Date.now();
+
+		let dirents: string[];
+		try {
+			dirents = await fs.readdir(parent);
+		} catch (error) {
+			if (isEnoent(error)) return { records, errors };
+			errors.push({ store: "local_roots", scope: parent, message: (error as Error).message });
+			return { records, errors };
+		}
+
+		for (const name of dirents.slice(0, MAX_ENTRIES)) {
+			const dir = path.join(parent, name);
+			try {
+				const classified = await classify(dir, now);
+				if (!classified) continue;
+				records.push({
+					store: "local_roots",
+					id: name,
+					path: dir,
+					status: classified.status,
+					stale: classified.stale,
+					removable: classified.stale,
+					action: classified.stale ? "would_remove" : "none",
+					reason: classified.reason,
+				});
+			} catch (error) {
+				errors.push({ store: "local_roots", scope: dir, message: (error as Error).message });
+			}
+		}
+
+		if (dirents.length > MAX_ENTRIES) {
+			errors.push({
+				store: "local_roots",
+				scope: parent,
+				message: `Scan truncated at ${MAX_ENTRIES} entries`,
+			});
+		}
+
+		return { records, errors };
+	},
+	async prune(record: GcRecord) {
+		const dir = record.path;
+		if (!dir) return { removed: false, error: "Missing local root path" };
+
+		// Re-validate immediately before removing: the session may have written a
+		// file between collect and prune.
+		let classified: Awaited<ReturnType<typeof classify>>;
+		try {
+			classified = await classify(dir, Date.now());
+		} catch (error) {
+			return { removed: false, error: (error as Error).message };
+		}
+		if (!classified) return { removed: false, skipped: "Local root disappeared" };
+		if (!classified.stale) return { removed: false, skipped: `Local root no longer eligible (${classified.status})` };
+
+		try {
+			await fs.rm(dir, { recursive: true, force: true });
+			return { removed: true };
+		} catch (error) {
+			return { removed: false, error: (error as Error).message };
+		}
+	},
+};

package/src/internal-urls/mcp-protocol.ts

@@ -2,29 +2,91 @@ import { MCPManager } from "../runtime-mcp/manager";
 import type { MCPResourceReadResult } from "../runtime-mcp/types";
 import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
 
-function escapeRegex(text: string): string {
-	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const MAX_MCP_RESOURCE_URI_CHARS = 16_384;
+const MAX_MCP_URI_TEMPLATE_CHARS = 8_192;
+const MAX_MCP_URI_TEMPLATE_EXPRESSIONS = 32;
+
+interface CompiledUriTemplate {
+	literalSegments: string[];
+	literalChars: number;
+	expressionCount: number;
+}
+
+function containsExpressionLineTerminator(text: string, start: number, end: number): boolean {
+	for (let index = start; index < end; index++) {
+		const code = text.charCodeAt(index);
+		if (code === 0x0a || code === 0x0d || code === 0x2028 || code === 0x2029) return true;
+	}
+	return false;
+}
+
+function compileUriTemplate(uriTemplate: string): CompiledUriTemplate | undefined {
+	if (uriTemplate.length > MAX_MCP_URI_TEMPLATE_CHARS) return undefined;
+
+	const literalSegments: string[] = [];
+	let expressionCount = 0;
+	let literalChars = 0;
+	let segmentStart = 0;
+	let scanPosition = 0;
+	while (scanPosition < uriTemplate.length) {
+		const expressionStart = uriTemplate.indexOf("{", scanPosition);
+		if (expressionStart < 0) break;
+		const expressionEnd = uriTemplate.indexOf("}", expressionStart + 1);
+		if (expressionEnd < 0) break;
+		if (expressionEnd === expressionStart + 1) {
+			scanPosition = expressionStart + 1;
+			continue;
+		}
+		expressionCount++;
+		if (expressionCount > MAX_MCP_URI_TEMPLATE_EXPRESSIONS) return undefined;
+		const segment = uriTemplate.slice(segmentStart, expressionStart);
+		literalSegments.push(segment);
+		literalChars += segment.length;
+		segmentStart = expressionEnd + 1;
+		scanPosition = segmentStart;
+	}
+	const finalSegment = uriTemplate.slice(segmentStart);
+	literalSegments.push(finalSegment);
+	literalChars += finalSegment.length;
+	return { literalSegments, literalChars, expressionCount };
+}
+
+function matchesUriTemplate(uri: string, template: CompiledUriTemplate): boolean {
+	const { literalSegments, expressionCount } = template;
+	if (expressionCount === 0) return uri === literalSegments[0];
+	if (!uri.startsWith(literalSegments[0])) return false;
+
+	let cursor = literalSegments[0].length;
+	for (let index = 1; index < literalSegments.length - 1; index++) {
+		const segment = literalSegments[index];
+		const matchIndex = uri.indexOf(segment, cursor);
+		if (matchIndex < 0 || containsExpressionLineTerminator(uri, cursor, matchIndex)) return false;
+		cursor = matchIndex + segment.length;
+	}
+
+	const suffix = literalSegments.at(-1) ?? "";
+	const suffixStart = uri.length - suffix.length;
+	return suffixStart >= cursor && uri.endsWith(suffix) && !containsExpressionLineTerminator(uri, cursor, suffixStart);
 }
 
 function getUriTemplateMatchScore(
 	uri: string,
 	uriTemplate: string,
 ): { literalChars: number; expressionCount: number } | undefined {
-	const expressionPattern = /\{[^}]+\}/g;
-	const literalSegments = uriTemplate.split(expressionPattern);
-	const expressionCount = (uriTemplate.match(expressionPattern) ?? []).length;
-	const pattern = literalSegments.map(escapeRegex).join("(.*?)");
-	const regex = new RegExp(`^${pattern}$`);
-	if (!regex.test(uri)) return undefined;
-	const literalChars = literalSegments.reduce((total, segment) => total + segment.length, 0);
-	return { literalChars, expressionCount };
+	const template = compileUriTemplate(uriTemplate);
+	if (!template || !matchesUriTemplate(uri, template)) return undefined;
+	return { literalChars: template.literalChars, expressionCount: template.expressionCount };
 }
 
 function extractResourceUri(url: InternalUrl): string {
 	const host = url.rawHost || url.hostname;
 	const rawPathname = url.rawPathname ?? url.pathname;
 	const hasPath = rawPathname && rawPathname !== "/";
-	const uri = `${host}${hasPath ? rawPathname : ""}${url.search}${url.hash}`.trim();
+	const rawUri = `${host}${hasPath ? rawPathname : ""}${url.search}${url.hash}`;
+	if (rawUri.length > MAX_MCP_RESOURCE_URI_CHARS) {
+		throw new Error("MCP resource URI exceeds the 16384-character limit.");
+	}
+	const uri = rawUri.trim();
 	if (!uri) {
 		throw new Error("mcp:// URL requires a resource URI: mcp://<resource-uri>");
 	}