@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/extensibility/gjc-plugins/lifecycle.ts

@@ -1,3 +1,4 @@
+import * as crypto from "node:crypto";
 import * as nodeFs from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
@@ -44,6 +45,9 @@ import type {
 	GjcUninstallPreview,
 	GjcUpdateApplyResult,
 	GjcUpdatePreview,
+	LocalRestorePlanV1,
+	NormalizedGjcPluginBundle,
+	ReviewedRestoreTokenV1,
 } from "./types";
 import { GJC_PLUGIN_MANIFEST_FILENAME, GjcPluginLoadError } from "./types";
 
@@ -824,6 +828,161 @@ export async function applyGjcBundleUpdate(
 	});
 }
 
+async function restoreArtifactObservation(entry: GjcPluginRegistryEntry): Promise<LocalRestorePlanV1["artifact"]> {
+	const hash = crypto.createHash("sha256");
+	try {
+		for (const file of [...entry.copiedFiles].sort((a, b) => a.relativePath.localeCompare(b.relativePath))) {
+			const target = path.join(entry.pluginRoot, file.relativePath);
+			const stat = await fs.lstat(target);
+			if (!stat.isFile() || stat.isSymbolicLink()) return { status: "unreadable" };
+			const bytes = await fs.readFile(target);
+			if (crypto.createHash("sha256").update(bytes).digest("hex") !== file.sha256) return { status: "unreadable" };
+			hash.update(file.relativePath);
+			hash.update("\0");
+			hash.update(file.sha256);
+			hash.update("\0");
+		}
+		return { status: "present", digest: hash.digest("hex") };
+	} catch (error) {
+		hash.digest();
+		return { status: isEnoent(error) ? "absent" : "unreadable" };
+	}
+}
+
+function bundleArtifactFingerprint(bundle: NormalizedGjcPluginBundle): string {
+	const hash = crypto.createHash("sha256");
+	for (const file of [...bundle.files].sort((a, b) => a.relativePath.localeCompare(b.relativePath))) {
+		hash.update(file.relativePath);
+		hash.update("\0");
+		hash.update(file.sha256);
+		hash.update("\0");
+	}
+	return hash.digest("hex");
+}
+
+export async function previewGjcBundleRestore(
+	ctx: GjcLifecycleContext,
+	identity: GjcBundleIdentity,
+): Promise<GjcLifecycleResult<LocalRestorePlanV1>> {
+	const registry = await readRegistry(identity.scope, ctx.cwd, { migrate: false });
+	const entry = registry.plugins.find(plugin => plugin.name === identity.name);
+	if (!entry) return { ok: false, error: notInstalled(identity) };
+	const effective = await readEffective(ctx.cwd);
+	return {
+		ok: true,
+		value: {
+			schemaVersion: 1,
+			kind: "gjc-plugin.restore-artifact",
+			identity,
+			baselineFingerprint: baselineFingerprint(entry),
+			decisionContextFingerprint: decisionContextFingerprint(identity, effective),
+			artifact: await restoreArtifactObservation(entry),
+			writes: false,
+			fetch: false,
+			locks: false,
+		},
+	};
+}
+
+export async function authorizeGjcBundleRestore(
+	ctx: GjcLifecycleContext,
+	plan: LocalRestorePlanV1,
+	authorizations: readonly string[],
+): Promise<GjcLifecycleResult<ReviewedRestoreTokenV1>> {
+	if (plan.kind !== "gjc-plugin.restore-artifact" || plan.schemaVersion !== 1)
+		return { ok: false, error: fail("invalid_target", "Restore plan is invalid") };
+	if (!authorizations.includes("plugin-change") || !authorizations.includes("install-replace"))
+		return { ok: false, error: fail("invalid_target", "Restore authorization is missing") };
+	const registry = await readRegistry(plan.identity.scope, ctx.cwd, { migrate: false });
+	const entry = registry.plugins.find(plugin => plugin.name === plan.identity.name);
+	if (!entry) return { ok: false, error: notInstalled(plan.identity) };
+	if (baselineFingerprint(entry) !== plan.baselineFingerprint)
+		return { ok: false, error: fail("stale_baseline", "The installed bundle changed since it was reviewed") };
+	const effective = await readEffective(ctx.cwd);
+	if (decisionContextFingerprint(plan.identity, effective) !== plan.decisionContextFingerprint)
+		return {
+			ok: false,
+			error: fail("stale_decision_context", "Installed bundles changed since restore was reviewed"),
+		};
+	return await withSourceAvailability(plan.identity, async () =>
+		resolveGjcBundleCandidate(storedSourceLocator(entry.source), async ({ bundle }) => {
+			if (bundle.name !== plan.identity.name)
+				return { ok: false, error: fail("identity_mismatch", "Stored source identity changed") };
+			const fingerprint = candidateFingerprint(plan.identity.scope, bundle);
+			return {
+				ok: true,
+				value: {
+					schemaVersion: 1,
+					kind: "gjc-plugin.restore-artifact",
+					purpose: "restore-artifact",
+					identity: plan.identity,
+					candidateFingerprint: fingerprint,
+					baselineFingerprint: plan.baselineFingerprint,
+					decisionContextFingerprint: plan.decisionContextFingerprint,
+					artifactFingerprint: bundleArtifactFingerprint(bundle),
+					reviewedAt: new Date().toISOString(),
+				},
+			};
+		}),
+	);
+}
+
+export async function applyGjcBundleRestore(
+	ctx: GjcLifecycleContext,
+	token: ReviewedRestoreTokenV1,
+): Promise<GjcLifecycleResult<GjcUpdateApplyResult>> {
+	if (
+		token.kind !== "gjc-plugin.restore-artifact" ||
+		token.purpose !== "restore-artifact" ||
+		token.schemaVersion !== 1
+	)
+		return { ok: false, error: fail("invalid_target", "Restore token is invalid") };
+	const identity = token.identity;
+	const registry = await readRegistry(identity.scope, ctx.cwd, { migrate: false });
+	const stored = registry.plugins.find(plugin => plugin.name === identity.name);
+	if (!stored) return { ok: false, error: notInstalled(identity) };
+	return await withSourceAvailability(identity, async () => {
+		const result = await runGjcBundleTransaction(storedSourceLocator(stored.source), {
+			scope: identity.scope,
+			cwd: ctx.cwd,
+			decide: async ({ existing, effective, bundle, candidate }) => {
+				if (!existing) return { kind: "abort", error: notInstalled(identity) };
+				if (candidateFingerprint(identity.scope, bundle) !== token.candidateFingerprint)
+					return { kind: "abort", error: fail("stale_candidate", "The restore candidate changed since review") };
+				if (baselineFingerprint(existing) !== token.baselineFingerprint)
+					return { kind: "abort", error: fail("stale_baseline", "The installed bundle changed since review") };
+				if (decisionContextFingerprint(identity, effective) !== token.decisionContextFingerprint)
+					return {
+						kind: "abort",
+						error: fail("stale_decision_context", "Installed bundles changed since restore was reviewed"),
+					};
+				const observed = await restoreArtifactObservation(existing);
+				if (observed.status === "present" && observed.digest === bundleArtifactFingerprint(bundle))
+					return { kind: "noop", entry: existing };
+				const reconciled = reconcileEnablement(existing.disabledSurfaceIds, surfaceIdsOf(bundle.surfaces));
+				const next: GjcPluginRegistryEntry = {
+					...candidate,
+					enabled: existing.enabled,
+					installedAt: existing.installedAt,
+					disabledSurfaceIds: reconciled.disabledSurfaceIds,
+				};
+				if (reconciled.quarantine.length) next.quarantine = reconciled.quarantine;
+				else delete next.quarantine;
+				return { kind: "commit", entry: next };
+			},
+		});
+		if (result.status === "aborted") return { ok: false, error: result.error };
+		return {
+			ok: true,
+			value: {
+				status: result.status === "noop" ? "unchanged" : "updated",
+				summary: toBundleSummary(result.entry),
+				remnantCount: result.remnants.length,
+			},
+		};
+	});
+}
+
 async function mutateEntry(
 	ctx: GjcLifecycleContext,
 	identity: GjcBundleIdentity,
@@ -842,6 +1001,36 @@ async function mutateEntry(
 	});
 }
 
+/**
+ * Doctor-only quarantine primitive. The expected baseline is compared while
+ * holding the ordinary registry writer lock, so concurrent enable/disable or
+ * update cannot be clobbered.
+ */
+export async function setGjcBundleQuarantineExpectedBaseline(
+	ctx: GjcLifecycleContext,
+	identity: GjcBundleIdentity,
+	enabled: boolean,
+	expectedBaseline: string,
+): Promise<GjcLifecycleResult<GjcToggleResult>> {
+	return await mutateEntry(ctx, identity, entry => {
+		if (baselineFingerprint(entry) !== expectedBaseline) {
+			return { ok: false, error: fail("stale_baseline", "The installed bundle changed since it was reviewed") };
+		}
+		if (entry.enabled === enabled) return { ok: true, value: null };
+		return { ok: true, value: { ...entry, enabled, updatedAt: new Date().toISOString() } };
+	});
+}
+
+export async function getGjcBundleEnablementState(
+	ctx: GjcLifecycleContext,
+	identity: GjcBundleIdentity,
+): Promise<GjcLifecycleResult<{ enabled: boolean; baseline: string }>> {
+	const registry = await readRegistry(identity.scope, ctx.cwd, { migrate: false });
+	const entry = registry.plugins.find(p => p.name === identity.name);
+	if (!entry) return { ok: false, error: notInstalled(identity) };
+	return { ok: true, value: { enabled: entry.enabled, baseline: baselineFingerprint(entry) } };
+}
+
 /**
  * Enable or disable a whole bundle. Deterministic quarantine blocks enabling;
  * disabling is always allowed so operators can always de-escalate.

package/src/extensibility/gjc-plugins/paths.ts

@@ -1,6 +1,8 @@
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, pathIsWithin } from "@gajae-code/utils";
+import type { ReadFileOptions } from "../../capability/fs";
+import { readFile } from "../../capability/fs";
 import { GJC_PLUGIN_MANIFEST_FILENAME, GjcPluginLoadError } from "./types";
 
 export function gjcPluginUserRoot(): string {
@@ -28,7 +30,8 @@ function isEnoent(error: unknown): boolean {
 	return (error as NodeJS.ErrnoException).code === "ENOENT";
 }
 
-export async function rootContainsGjcManifest(dir: string): Promise<boolean> {
+export async function rootContainsGjcManifest(dir: string, options?: ReadFileOptions): Promise<boolean> {
+	if (options?.isolatedHome) return (await readFile(path.join(dir, GJC_PLUGIN_MANIFEST_FILENAME), options)) !== null;
 	try {
 		await fs.access(path.join(dir, GJC_PLUGIN_MANIFEST_FILENAME));
 		return true;

package/src/extensibility/gjc-plugins/types.ts

@@ -459,6 +459,33 @@ export interface GjcReviewedUpdateToken {
 	reviewedAt: string;
 }
 
+export interface LocalRestorePlanV1 {
+	schemaVersion: 1;
+	kind: "gjc-plugin.restore-artifact";
+	identity: GjcBundleIdentity;
+	baselineFingerprint: string;
+	decisionContextFingerprint: string;
+	artifact: {
+		status: "present" | "absent" | "unreadable";
+		digest?: string;
+	};
+	writes: false;
+	fetch: false;
+	locks: false;
+}
+
+export interface ReviewedRestoreTokenV1 {
+	schemaVersion: 1;
+	kind: "gjc-plugin.restore-artifact";
+	purpose: "restore-artifact";
+	identity: GjcBundleIdentity;
+	candidateFingerprint: string;
+	baselineFingerprint: string;
+	decisionContextFingerprint: string;
+	artifactFingerprint: string;
+	reviewedAt: string;
+}
+
 export type GjcLifecycleErrorCode =
 	| "already_installed_use_upgrade"
 	| "not_installed"

package/src/extensibility/plugins/manager.ts

@@ -10,6 +10,7 @@ import {
 	isEnoent,
 	logger,
 } from "@gajae-code/utils";
+import { withFileLock } from "../../config/file-lock";
 import { extractPackageName, parsePluginSpec } from "./parser";
 import type {
 	DoctorCheck,
@@ -48,6 +49,11 @@ function validatePackageName(name: string): void {
 // Plugin Manager
 // =============================================================================
 
+export type PluginEnablementState =
+	| { status: "ok"; enabled: boolean; baseline: string }
+	| { status: "not_installed" }
+	| { status: "malformed" };
+
 export class PluginManager {
 	#runtimeConfig: PluginRuntimeConfig | null = null;
 	#cwd: string;
@@ -56,19 +62,179 @@ export class PluginManager {
 		this.#cwd = cwd;
 	}
 
+	/**
+	 * Read-only durable-enablement snapshot for one npm plugin, scope-qualified.
+	 * `"user"` reads the shared runtime lock file (~/.gjc/plugins/gjc-plugins.lock.json);
+	 * `"project"` reads this project's `.gjc/plugin-overrides.json` disabled list.
+	 * A malformed underlying file is reported distinctly from "not installed" —
+	 * neither is silently treated as an empty/enabled state.
+	 */
+	async getEnablementState(name: string, scope: "user" | "project"): Promise<PluginEnablementState> {
+		if (scope === "user") {
+			let config: PluginRuntimeConfig;
+			try {
+				config = await this.#loadRuntimeConfigStrict();
+			} catch {
+				return { status: "malformed" };
+			}
+			const current = config.plugins[name];
+			if (!current) return { status: "not_installed" };
+			return { status: "ok", enabled: current.enabled !== false, baseline: JSON.stringify({ scope, current }) };
+		}
+		let overrides: ProjectPluginOverrides;
+		try {
+			overrides = await this.#loadProjectOverridesStrict();
+		} catch {
+			return { status: "malformed" };
+		}
+		// Project scope has no independent "installed" concept (it modifies the
+		// same npm-managed package the user scope tracks); absence of a user
+		// entry means there is nothing this project scope could be disabling.
+		let config: PluginRuntimeConfig;
+		try {
+			config = await this.#loadRuntimeConfigStrict();
+		} catch {
+			return { status: "malformed" };
+		}
+		if (!config.plugins[name]) return { status: "not_installed" };
+		const disabled = [...(overrides.disabled ?? [])].sort();
+		return { status: "ok", enabled: !disabled.includes(name), baseline: JSON.stringify({ scope, disabled }) };
+	}
+
+	/**
+	 * Durable enablement toggle used by doctor quarantine and the plugin CLI.
+	 * No install/fetch/reinstall occurs — this only flips the durable enabled
+	 * flag a future session-startup load (`getEnabledPlugins`) consults: the
+	 * user-scope runtime lock file, or the project's disabled-list override.
+	 * Serialized under the canonical native-identity-bound file lock shared
+	 * with every other writer of the same file (bounded retry/timeout,
+	 * owner-safe release — never an unbounded wait, never a blind `rm`).
+	 * `expectedBaseline` is required: a caller with no prior
+	 * {@link getEnablementState} read has no CAS authority to mutate.
+	 */
+	async setEnabled(
+		name: string,
+		enabled: boolean,
+		scope: "user" | "project",
+		expectedBaseline: string,
+	): Promise<{ status: "updated" | "not_needed"; enabled: boolean; version?: string }> {
+		if (scope === "project") return await this.#setProjectEnabled(name, enabled, expectedBaseline);
+		const lockfilePath = getPluginsLockfile();
+		return await withFileLock(lockfilePath, async () => {
+			this.#runtimeConfig = null;
+			let config: PluginRuntimeConfig;
+			try {
+				config = await this.#loadRuntimeConfigStrict();
+			} catch (error) {
+				throw Object.assign(new Error(`Plugin runtime config is malformed at ${lockfilePath}`), {
+					code: "malformed_registry",
+					cause: error,
+				});
+			}
+			const current = config.plugins[name];
+			if (!current) throw Object.assign(new Error(`Plugin "${name}" is not installed`), { code: "not_installed" });
+			const baseline = JSON.stringify({ scope: "user" as const, current });
+			if (baseline !== expectedBaseline)
+				throw Object.assign(new Error("The installed plugin entry changed since it was reviewed"), {
+					code: "stale_baseline",
+				});
+			if (current.enabled === enabled) return { status: "not_needed" as const, enabled, version: current.version };
+			config.plugins[name] = { ...current, enabled };
+			this.#runtimeConfig = config;
+			await this.#saveRuntimeConfig();
+			return { status: "updated" as const, enabled, version: current.version };
+		});
+	}
+
+	/**
+	 * Project-scoped disable: adds/removes `name` from the project's
+	 * `.gjc/plugin-overrides.json` disabled list. Serialized under that exact
+	 * file's canonical file lock so an ordinary override edit and this doctor
+	 * toggle cannot race and clobber each other's sibling entries.
+	 */
+	async #setProjectEnabled(
+		name: string,
+		enabled: boolean,
+		expectedBaseline: string,
+	): Promise<{ status: "updated" | "not_needed"; enabled: boolean }> {
+		const overridesPath = getProjectPluginOverridesPath(this.#cwd);
+		return await withFileLock(overridesPath, async () => {
+			let overrides: ProjectPluginOverrides;
+			try {
+				overrides = await this.#loadProjectOverridesStrict();
+			} catch (error) {
+				throw Object.assign(new Error(`Project plugin overrides are malformed at ${overridesPath}`), {
+					code: "malformed_registry",
+					cause: error,
+				});
+			}
+			const disabled = [...(overrides.disabled ?? [])].sort();
+			const baseline = JSON.stringify({ scope: "project" as const, disabled });
+			if (baseline !== expectedBaseline)
+				throw Object.assign(new Error("The project plugin overrides changed since they were reviewed"), {
+					code: "stale_baseline",
+				});
+			const wasDisabled = disabled.includes(name);
+			if (wasDisabled === !enabled) return { status: "not_needed" as const, enabled };
+			const nextDisabled = enabled ? disabled.filter(n => n !== name) : [...new Set([...disabled, name])].sort();
+			const next: ProjectPluginOverrides = { ...overrides, disabled: nextDisabled };
+			await fs.promises.mkdir(path.dirname(overridesPath), { recursive: true });
+			const tmpPath = `${overridesPath}.tmp-${process.pid}-${Date.now()}`;
+			await fs.promises.writeFile(tmpPath, `${JSON.stringify(next, null, 2)}\n`);
+			await fs.promises.rename(tmpPath, overridesPath);
+			return { status: "updated" as const, enabled };
+		});
+	}
+
 	// ==========================================================================
 	// Runtime Config Management
 	// ==========================================================================
 
 	async #loadRuntimeConfig(): Promise<PluginRuntimeConfig> {
+		try {
+			return await this.#loadRuntimeConfigStrict();
+		} catch (err) {
+			logger.warn("Failed to load plugin runtime config", { path: getPluginsLockfile(), error: String(err) });
+			return { plugins: {}, settings: {} };
+		}
+	}
+
+	/**
+	 * Strict variant: a missing lock file is legitimately empty (no plugins
+	 * installed yet), but malformed JSON must never be silently coerced into
+	 * an empty config — a mutating writer built on that would overwrite (and
+	 * lose) an unreadable but non-empty runtime config.
+	 */
+	async #loadRuntimeConfigStrict(): Promise<PluginRuntimeConfig> {
 		const lockPath = getPluginsLockfile();
+		let text: string;
 		try {
-			return await Bun.file(lockPath).json();
+			text = await Bun.file(lockPath).text();
 		} catch (err) {
 			if (isEnoent(err)) return { plugins: {}, settings: {} };
-			logger.warn("Failed to load plugin runtime config", { path: lockPath, error: String(err) });
-			return { plugins: {}, settings: {} };
+			throw err;
 		}
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(text);
+		} catch (error) {
+			throw Object.assign(new Error(`Plugin runtime config is malformed at ${lockPath}`), {
+				code: "malformed_registry",
+				cause: error,
+			});
+		}
+		if (
+			typeof parsed !== "object" ||
+			parsed === null ||
+			typeof (parsed as PluginRuntimeConfig).plugins !== "object" ||
+			(parsed as PluginRuntimeConfig).plugins === null
+		) {
+			throw Object.assign(new Error(`Plugin runtime config has an unsupported shape at ${lockPath}`), {
+				code: "malformed_registry",
+			});
+		}
+		const config = parsed as PluginRuntimeConfig;
+		return { plugins: config.plugins ?? {}, settings: config.settings ?? {} };
 	}
 
 	async #ensureConfigLoaded(): Promise<PluginRuntimeConfig> {
@@ -84,14 +250,42 @@ export class PluginManager {
 	}
 
 	async #loadProjectOverrides(): Promise<ProjectPluginOverrides> {
+		try {
+			return await this.#loadProjectOverridesStrict();
+		} catch (err) {
+			logger.warn("Failed to load project plugin overrides", {
+				path: getProjectPluginOverridesPath(this.#cwd),
+				error: String(err),
+			});
+			return {};
+		}
+	}
+
+	/** Strict variant: missing is empty; malformed JSON/shape throws. */
+	async #loadProjectOverridesStrict(): Promise<ProjectPluginOverrides> {
 		const overridesPath = getProjectPluginOverridesPath(this.#cwd);
+		let text: string;
 		try {
-			return await Bun.file(overridesPath).json();
+			text = await Bun.file(overridesPath).text();
 		} catch (err) {
 			if (isEnoent(err)) return {};
-			logger.warn("Failed to load project plugin overrides", { path: overridesPath, error: String(err) });
-			return {};
+			throw err;
 		}
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(text);
+		} catch (error) {
+			throw Object.assign(new Error(`Project plugin overrides are malformed at ${overridesPath}`), {
+				code: "malformed_registry",
+				cause: error,
+			});
+		}
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+			throw Object.assign(new Error(`Project plugin overrides have an unsupported shape at ${overridesPath}`), {
+				code: "malformed_registry",
+			});
+		}
+		return parsed as ProjectPluginOverrides;
 	}
 
 	// ==========================================================================
@@ -383,22 +577,6 @@ export class PluginManager {
 		};
 	}
 
-	// ==========================================================================
-	// Enable / Disable
-	// ==========================================================================
-
-	/**
-	 * Enable or disable a plugin globally.
-	 */
-	async setEnabled(name: string, enabled: boolean): Promise<void> {
-		const config = await this.#ensureConfigLoaded();
-		if (!config.plugins[name]) {
-			throw new Error(`Plugin ${name} not found in runtime config`);
-		}
-		config.plugins[name].enabled = enabled;
-		await this.#saveRuntimeConfig();
-	}
-
 	// ==========================================================================
 	// Features
 	// ==========================================================================

package/src/extensibility/plugins/marketplace/cache.ts

@@ -10,12 +10,11 @@
  * This ensures cache paths cannot be crafted to escape the cache directory.
  */
 
+import { createHash } from "node:crypto";
 import * as nodeFs from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-
 import { isEnoent } from "@gajae-code/utils";
-
 import { isValidNameSegment } from "./types";
 
 // Reject anything that could be used for path traversal or shell injection in
@@ -88,6 +87,60 @@ export async function cachePlugin(
 	return targetPath;
 }
 
+export async function stageCachedPlugin(sourcePath: string, stagingPath: string): Promise<string> {
+	await fs.rm(stagingPath, { recursive: true, force: true });
+	await fs.cp(sourcePath, stagingPath, { recursive: true, errorOnExist: true, verbatimSymlinks: true });
+	return stagingPath;
+}
+
+export async function digestCachedPlugin(targetPath: string): Promise<string | undefined> {
+	const hash = createHash("sha256");
+	const walk = async (root: string, rel = ""): Promise<void> => {
+		const entries = (await fs.readdir(root, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+		for (const entry of entries) {
+			const childRel = rel ? path.join(rel, entry.name) : entry.name;
+			const child = path.join(root, entry.name);
+			const stat = await fs.lstat(child);
+			if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) throw new Error("unsafe cache artifact");
+			// Reject a regular file with more than one hard link: its bytes could be
+			// mutated through a second pathname we never inspected, so a digest taken
+			// here would not be provably bound to the artifact this walk actually saw.
+			// Directory entries never carry meaningful hard-link counts on POSIX
+			// (nlink for a directory reflects '.'/subdir back-references), so this
+			// check applies only to regular files.
+			if (stat.isFile() && stat.nlink > 1) throw new Error("unsafe cache artifact: multiply-linked file");
+			if (stat.isDirectory()) await walk(child, childRel);
+			else {
+				hash.update(childRel);
+				hash.update("\0");
+				hash.update(await fs.readFile(child));
+				hash.update("\0");
+			}
+		}
+	};
+	try {
+		await walk(targetPath);
+		return hash.digest("hex");
+	} catch (error) {
+		hash.digest();
+		if (isEnoent(error)) return undefined;
+		return undefined;
+	}
+}
+
+export async function inspectCachedPlugin(
+	targetPath: string,
+): Promise<{ status: "present" | "absent" | "unreadable"; digest?: string }> {
+	try {
+		const stat = await fs.lstat(targetPath);
+		if (!stat.isDirectory() || stat.isSymbolicLink()) return { status: "unreadable" };
+		const digest = await digestCachedPlugin(targetPath);
+		return digest ? { status: "present", digest } : { status: "unreadable" };
+	} catch (error) {
+		return isEnoent(error) ? { status: "absent" } : { status: "unreadable" };
+	}
+}
+
 /**
  * Synchronous check — true when the cache directory exists on disk.
  * Uses `existsSync` because callers may need to run this check inline without async.