@pharaoh-so/mcp 0.3.54 → 0.3.56

package/project-memory/memory-api.mjs

@@ -0,0 +1,182 @@
+export const PROJECT_MEMORY_ORIGIN = "https://mcp.pharaoh.so";
+const READY_TIMEOUT_MS = 1_200;
+const BUILD = new URL("runtime/refresh.js", import.meta.url);
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+const STATUS = new Set(["candidate", "approved", "superseded", "retracted"]);
+
+export class PilotError extends Error {}
+
+async function responseJson(response) {
+	if (!response.body) throw new PilotError("Pharaoh returned an incomplete response.");
+	const chunks = [];
+	let bytes = 0;
+	for await (const chunk of response.body) {
+		bytes += chunk.length;
+		if (bytes > 32_768) throw new PilotError("Pharaoh returned an oversized response.");
+		chunks.push(chunk);
+	}
+	return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+export async function refreshHelper() {
+	try {
+		const helper = await import(BUILD.href);
+		if (typeof helper.originBoundRefresh === "function") return helper;
+	} catch {
+		// Missing or incomplete build.
+	}
+	throw new PilotError(
+		"The installed project memory bundle has no compatible refresh helper. Rerun normal Pharaoh setup.",
+	);
+}
+
+/** Check only mapping metadata using the current device session. Normal proxy
+ * startup handles token refresh; the prompt hook never waits on a refresh lock. */
+export async function requestMemoryReadiness(repo, credentials) {
+	const expiresAt = Date.parse(credentials?.expires_at);
+	if (typeof credentials?.access_token !== "string" || !(expiresAt > Date.now())) return;
+	try {
+		if (new URL(credentials.sse_url).origin !== PROJECT_MEMORY_ORIGIN) return;
+		const response = await fetch(`${PROJECT_MEMORY_ORIGIN}/api/project-memory/readiness`, {
+			method: "POST",
+			redirect: "error",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${credentials.access_token}`,
+			},
+			body: JSON.stringify({ repo }),
+			signal: AbortSignal.timeout(READY_TIMEOUT_MS),
+		});
+		if (!response.ok) {
+			await response.body?.cancel();
+			return;
+		}
+		const result = await responseJson(response);
+		return result?.revision;
+	} catch {
+		// Pending, denied, unavailable and timed-out lookups leave hooks dormant.
+	}
+}
+
+export async function requestMemory(operation, payload, { fetcher = fetch, helper } = {}) {
+	if (!["recall", "capture", "expand"].includes(operation))
+		throw new PilotError("Unknown memory request.");
+	const { originBoundRefresh } = helper ?? (await refreshHelper());
+	const refresh = originBoundRefresh(PROJECT_MEMORY_ORIGIN);
+	const outcome = await refresh.load();
+	if (!outcome?.ok)
+		throw new PilotError(
+			"Connect to Pharaoh with its device sign-in, or retry if sign-in is temporarily unavailable.",
+		);
+	const send = async (creds) => {
+		try {
+			return await fetcher(`${PROJECT_MEMORY_ORIGIN}/api/project-memory/${operation}`, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					"Content-Type": "application/json",
+					Authorization: `Bearer ${creds.access_token}`,
+				},
+				body: JSON.stringify(payload),
+				signal: AbortSignal.timeout(12_000),
+			});
+		} catch {
+			throw new PilotError(
+				operation === "capture"
+					? "Pharaoh did not confirm whether this capture was saved. Check the project memory inspector before retrying."
+					: "Pharaoh project memory could not respond before the request ended.",
+			);
+		}
+	};
+	const response = await send(outcome.creds);
+	if (!response.ok) {
+		await response.body?.cancel();
+		// The shared credential file can now name a different OAuth session. Do
+		// not reuse an already prepared operation under newly loaded credentials.
+		if (response.status === 401)
+			throw new PilotError("Pharaoh rejected this sign-in. Reconnect before trying again.");
+		if (response.status === 404)
+			throw new PilotError("Project memory is unavailable for this repository or account.");
+		if (response.status === 400 || response.status === 413)
+			throw new PilotError(
+				"Pharaoh rejected the memory payload. Check its shape, size, and sensitive content.",
+			);
+		if (response.status === 409)
+			throw new PilotError(
+				"Pharaoh could not save this candidate because the operation conflicts or the project log is full.",
+			);
+		if (response.status === 429)
+			throw new PilotError("Pharaoh project memory reached its request limit.");
+		if (operation === "capture" && response.status >= 500) {
+			throw new PilotError(
+				"Pharaoh did not confirm whether this capture was saved. Check the project memory inspector before retrying.",
+			);
+		}
+		throw new PilotError("Pharaoh project memory is temporarily unavailable.");
+	}
+	let result;
+	try {
+		result = await responseJson(response);
+	} catch (error) {
+		if (operation === "capture")
+			throw new PilotError(
+				"Pharaoh did not confirm whether this capture was saved. Check the project memory inspector before retrying.",
+			);
+		throw error;
+	}
+	if (
+		operation === "recall" &&
+		Array.isArray(result?.records) &&
+		result.records.length <= 5 &&
+		result.records.every((record) => typeof record?.id === "string" && UUID.test(record.id))
+	) {
+		if (payload.format === "compact-v1") {
+			if (
+				result.format === "compact-v1" &&
+				typeof result.repo === "string" &&
+				result.repo.toLowerCase() === payload.repo.toLowerCase() &&
+				typeof result.moreMatches === "boolean" &&
+				Number.isInteger(result.omittedRecords) &&
+				result.omittedRecords >= 0 &&
+				result.records.every(
+					(record) =>
+						Number.isInteger(record.version) &&
+						record.version >= 1 &&
+						record.version <= 1_000_000 &&
+						STATUS.has(record.status),
+				)
+			)
+				return result;
+			throw new PilotError("Pharaoh returned an incomplete compact recall packet.");
+		}
+		return { records: result.records, graph: result.graph };
+	}
+	if (
+		operation === "expand" &&
+		result?.record?.id === payload.id &&
+		result.record.version === payload.version &&
+		STATUS.has(result.record.status) &&
+		Number.isInteger(result.current?.version) &&
+		result.current.version >= payload.version &&
+		STATUS.has(result.current.status)
+	) {
+		const omitted = result.omittedHistoricalEvidence;
+		return {
+			record: result.record,
+			current: result.current,
+			...(Number.isInteger(omitted) && omitted >= 0 && { omittedHistoricalEvidence: omitted }),
+		};
+	}
+	if (
+		operation === "capture" &&
+		typeof result?.record?.id === "string" &&
+		UUID.test(result.record.id)
+	) {
+		return { record: { id: result.record.id, status: result.record.status } };
+	}
+	if (operation === "capture")
+		throw new PilotError(
+			"Pharaoh did not confirm whether this capture was saved. Check the project memory inspector before retrying.",
+		);
+	throw new PilotError("Pharaoh returned an incomplete response.");
+}

package/project-memory/pharaoh-memory-hook.mjs

@@ -0,0 +1,33 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { handleEvent } from "./hook-events.mjs";
+import { readStdin } from "./local.mjs";
+import {
+	activeMemoryRuntime,
+	readMemoryCredentials,
+	resolveMemoryHookTarget,
+} from "./user-target.mjs";
+
+try {
+	const [client, root, repo] = process.argv.slice(2);
+	const input = await readStdin(1024 * 1024);
+	let target = { root, repo };
+	if (root === "--user") {
+		const runtime = dirname(fileURLToPath(import.meta.url));
+		if (!activeMemoryRuntime(client, runtime)) process.exit(0);
+		const eligible = await resolveMemoryHookTarget(
+			client,
+			input?.cwd,
+			await readMemoryCredentials(),
+			input?.hook_event_name === "UserPromptSubmit" &&
+				typeof input?.prompt === "string" &&
+				Boolean(input.prompt.trim()),
+		);
+		if (!eligible) process.exit(0);
+		target = { ...eligible, runtime };
+	}
+	const result = handleEvent(input, { client, ...target });
+	if (result) process.stdout.write(JSON.stringify(result));
+} catch {
+	// Fail open. handleEvent reports state failures when the prompt is eligible.
+}

package/project-memory/pharaoh-memory.mjs

@@ -0,0 +1,55 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { executeTurn } from "./execute-turn.mjs";
+import { checkout, readStdin, turnStore } from "./local.mjs";
+import { PilotError, refreshHelper } from "./memory-api.mjs";
+import {
+	activeMemoryRuntime,
+	cachedMemoryCheckout,
+	readMemoryCredentials,
+} from "./user-target.mjs";
+
+async function main(args) {
+	const [operation, option, token, compactFlag, ...extra] = args;
+	if (operation === "doctor" && args.length === 1) {
+		await refreshHelper();
+		process.stdout.write("The local Pharaoh refresh helper is ready.\n");
+		return;
+	}
+	if (
+		option !== "--turn" ||
+		!/^[a-f0-9]{64}$/.test(token) ||
+		extra.length > 0 ||
+		(compactFlag !== undefined && (compactFlag !== "--compact" || operation !== "recall")) ||
+		!["recall", "expand", "capture", "nothing-material", "receipt"].includes(operation)
+	) {
+		throw new PilotError(
+			"Use doctor, or recall, expand, capture, receipt, or nothing-material with the active hook's --turn token.",
+		);
+	}
+	const cwd = process.cwd();
+	const target = checkout(cwd);
+	if (!target) throw new PilotError("Run this inside the enrolled GitHub checkout.");
+	const runtime = dirname(fileURLToPath(import.meta.url));
+	const active =
+		activeMemoryRuntime("claude-code", runtime) || activeMemoryRuntime("codex", runtime);
+	const eligible = active && (await cachedMemoryCheckout(cwd, await readMemoryCredentials()));
+	const result = await executeTurn(operation, token, {
+		target: eligible ? { ...target, runtime } : target,
+		store: turnStore(),
+		read: () => readStdin(8_192),
+		compact: compactFlag === "--compact" || process.env.PHARAOH_PROJECT_MEMORY_COMPACT === "true",
+	});
+	process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+try {
+	await main(process.argv.slice(2));
+} catch (error) {
+	const message =
+		error instanceof PilotError
+			? error.message
+			: "Pharaoh project memory is temporarily unavailable.";
+	process.stderr.write(`${message}\n`);
+	process.exitCode = 1;
+}

package/project-memory/setup.d.mts

@@ -0,0 +1,14 @@
+export function syncMemoryHooks(options?: {
+	credentials?: {
+		sse_url: string;
+		project_memory?: Array<{ repo: string; revision: string | null }>;
+		project_memory_status?: "unavailable";
+	};
+	clients?: string[];
+	home?: string;
+	env?: NodeJS.ProcessEnv;
+	cwd?: string;
+	node?: string;
+	removeLegacy?: boolean;
+	packageRoot?: URL;
+}): string[];

package/project-memory/setup.mjs

@@ -0,0 +1,151 @@
+import { lstatSync, mkdirSync, realpathSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { bundledHook, installMemoryBundle, packagedMemoryBundle } from "./bundle.mjs";
+import { hasLegacyHooks, updateHooks, updateUserHooks } from "./hook-config.mjs";
+import { atomicWrite, checkout, git, hasMemoryGit } from "./local.mjs";
+import {
+	eligibleCheckout,
+	legacySettingsPath,
+	memoryClientRoot,
+	projectMemoryHint,
+	readActiveMemoryClients,
+	readHookSettings,
+} from "./user-target.mjs";
+
+function userSettings(client, home, env) {
+	const codex = client === "codex";
+	const directory =
+		(codex ? env.CODEX_HOME : env.CLAUDE_CONFIG_DIR) ?? join(home, codex ? ".codex" : ".claude");
+	if (!isAbsolute(directory)) throw new Error("Client configuration directory must be absolute.");
+	return join(directory, codex ? "hooks.json" : "settings.json");
+}
+
+function writeSettings(path, previous, next) {
+	if (JSON.stringify(previous) === JSON.stringify(next)) return;
+	const directory = dirname(path);
+	mkdirSync(directory, { recursive: true, mode: 0o700 });
+	const info = lstatSync(directory);
+	if (!info.isDirectory() || info.uid !== process.getuid?.())
+		throw new Error("Client settings directory is not owner-controlled.");
+	atomicWrite(path, `${JSON.stringify(next, null, "\t")}\n`);
+}
+
+function migrateCheckout(client, target) {
+	if (!target) return;
+	const path = legacySettingsPath(client, target.root);
+	const before = readHookSettings(path);
+	if (!hasLegacyHooks(before, client, target.root)) return;
+	const relative = path.slice(target.root.length + 1);
+	if (realpathSync(dirname(path)) !== dirname(path) || git(target.root, "ls-files", "--", relative))
+		throw new Error("The earlier checkout hook is in tracked or linked settings.");
+	// The legacy installer always wrote ignored files. Never create or alter
+	// Git excludes, and never migrate project settings that can be committed.
+	git(target.root, "check-ignore", "--quiet", "--no-index", "--", relative);
+	writeSettings(path, before, updateHooks(before, client, target, true));
+}
+
+/** Run only as part of a deliberate normal setup, upgrade, clean or logout. */
+export function syncMemoryHooks({
+	credentials,
+	clients = [],
+	home = homedir(),
+	env = process.env,
+	cwd = process.cwd(),
+	node = process.execPath,
+	removeLegacy = false,
+	packageRoot,
+} = {}) {
+	const hint = projectMemoryHint(credentials);
+	const root = memoryClientRoot(home);
+	const previous = readActiveMemoryClients(home);
+	if (!removeLegacy && credentials?.project_memory_status === "unavailable") {
+		return [
+			"Pharaoh: project memory eligibility could not be checked. Existing hook settings were kept. Rerun normal setup to retry.",
+		];
+	}
+	if (!hint.length && !Object.keys(previous).length && !removeLegacy) return [];
+	const notices = [];
+	const active = {};
+	const configured = [];
+	let installed;
+	let digest;
+	const target = removeLegacy ? checkout(cwd) : eligibleCheckout(cwd, hint);
+	const pendingCheckout =
+		!target && hint.some((entry) => entry?.revision === null) ? checkout(cwd) : undefined;
+	const pendingRoot =
+		pendingCheckout &&
+		hint.some(
+			(entry) =>
+				entry?.revision === null &&
+				entry.repo?.toLowerCase() === pendingCheckout.repo.toLowerCase(),
+		)
+			? pendingCheckout.root
+			: undefined;
+
+	if (hint.length) {
+		try {
+			if (!hasMemoryGit || typeof process.getuid !== "function")
+				throw new Error("Project memory needs a POSIX client with system Git.");
+			const bundle = packagedMemoryBundle(packageRoot);
+			digest = bundle.sha256;
+			installed = bundledHook(installMemoryBundle(root, target?.root ?? pendingRoot, bundle));
+		} catch (error) {
+			return [`Pharaoh: project memory setup unavailable. ${error.message}`];
+		}
+	}
+
+	for (const client of ["claude-code", "codex"]) {
+		const desired = clients.includes(client) ? installed : undefined;
+		if (!desired && !previous[client] && !removeLegacy) continue;
+		try {
+			const path = userSettings(client, home, env);
+			const before = readHookSettings(path);
+			writeSettings(path, before, updateUserHooks(before, client, desired, node));
+			if (desired) {
+				active[client] = digest;
+				configured.push(client);
+			}
+		} catch {
+			if (desired && previous[client]) active[client] = previous[client];
+			if (desired || previous[client])
+				notices.push(
+					`Pharaoh: project memory could not update ${client} hooks. Check the client settings and rerun normal setup.`,
+				);
+		}
+	}
+
+	// This private activation record makes older hook commands inert even if a
+	// client still has them loaded or its settings could not be updated.
+	const activePath = join(root, "active.json");
+	if (Object.keys(active).length) {
+		if (JSON.stringify(previous) !== JSON.stringify(active))
+			atomicWrite(activePath, `${JSON.stringify(active)}\n`);
+		if (configured.length) {
+			notices.push(
+				"Pharaoh project memory is set up for your eligible repositories. Start a new local conversation.",
+			);
+			if (hint.some((entry) => entry?.revision === null))
+				notices.push(
+					"A connected repository is still mapping. Its hooks will start memory automatically when the mapped revision is available.",
+				);
+			if (configured.includes("codex"))
+				notices.push("In Codex, review and trust the Pharaoh hooks in /hooks or Settings > Hooks.");
+		}
+	} else if (Object.keys(previous).length) {
+		rmSync(activePath, { force: true });
+	}
+	// The old checkout hook is a fallback until its replacement settings and
+	// the private activation record are both in place.
+	for (const client of ["claude-code", "codex"]) {
+		if (!removeLegacy && !configured.includes(client)) continue;
+		try {
+			migrateCheckout(client, target);
+		} catch {
+			notices.push(
+				`Pharaoh: the earlier ${client} checkout hook remains in place for this checkout.`,
+			);
+		}
+	}
+	return notices;
+}

package/project-memory/user-target.mjs

@@ -0,0 +1,221 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { hasLegacyHooks } from "./hook-config.mjs";
+import { atomicWrite, checkout, git } from "./local.mjs";
+import { PROJECT_MEMORY_ORIGIN, requestMemoryReadiness } from "./memory-api.mjs";
+
+const REVISION = /^(?!0{40}$)[a-f0-9]{40}$/;
+const READINESS_RETRY_MS = 15_000;
+const LEGACY_SETTINGS = {
+	"claude-code": ".claude/settings.local.json",
+	codex: ".codex/hooks.json",
+};
+
+export function legacySettingsPath(client, root) {
+	return join(root, LEGACY_SETTINGS[client]);
+}
+
+export function projectMemoryHint(credentials) {
+	if (!credentials || !Array.isArray(credentials.project_memory)) return [];
+	try {
+		if (new URL(credentials.sse_url).origin !== PROJECT_MEMORY_ORIGIN) return [];
+	} catch {
+		return [];
+	}
+	return credentials.project_memory;
+}
+
+function matchingHint(target, hints) {
+	return hints.find(
+		(entry) =>
+			typeof entry?.repo === "string" && entry.repo.toLowerCase() === target.repo.toLowerCase(),
+	);
+}
+
+function hasMappedCommit(target, revision) {
+	if (typeof revision !== "string" || !REVISION.test(revision)) return false;
+	try {
+		// An origin URL is editable. Require an actual GitHub-mapped commit
+		// locally, without fetching, consulting replace refs, or running hooks.
+		return git(target.root, "cat-file", "-t", revision) === "commit";
+	} catch {
+		return false;
+	}
+}
+
+export function eligibleCheckout(cwd, hints) {
+	if (!hints.length) return;
+	const target = checkout(cwd);
+	if (target && hasMappedCommit(target, matchingHint(target, hints)?.revision)) return target;
+}
+
+function hash(value) {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function readReadiness(path, binding) {
+	try {
+		const stat = lstatSync(path);
+		if (!stat.isFile() || stat.uid !== process.getuid?.() || stat.mode & 0o077 || stat.size > 512)
+			return;
+		const state = JSON.parse(readFileSync(path, "utf8"));
+		if (state.binding === binding) return state;
+	} catch {
+		// A missing or unreadable cache cannot authorize a checkout.
+	}
+}
+
+function tryReadinessLease(path, now) {
+	try {
+		try {
+			const stat = lstatSync(path);
+			if (
+				!stat.isFile() ||
+				stat.uid !== process.getuid?.() ||
+				now - stat.mtimeMs < READINESS_RETRY_MS
+			)
+				return;
+			rmSync(path, { force: true });
+		} catch (error) {
+			if (error.code !== "ENOENT") return;
+		}
+		const owner = randomUUID();
+		writeFileSync(path, owner, { flag: "wx", mode: 0o600 });
+		return () => {
+			try {
+				if (readFileSync(path, "utf8") === owner) rmSync(path, { force: true });
+			} catch {
+				// A stale lease expires without blocking ordinary work.
+			}
+		};
+	} catch {
+		// Another hook is already checking or private local state is unavailable.
+	}
+}
+
+async function resolveRevision(repo, credentials, probe) {
+	const session = credentials.project_memory_session;
+	if (typeof session !== "string" || !/^[0-9a-f-]{36}$/.test(session)) return;
+	const binding = hash(session);
+	const path = join(memoryClientRoot(), `ready-${hash(repo.toLowerCase())}.json`);
+	const saved = readReadiness(path, binding);
+	if (typeof saved?.revision === "string" && REVISION.test(saved.revision)) return saved.revision;
+	const now = Date.now();
+	if (!probe || now - (saved?.checkedAt ?? 0) < READINESS_RETRY_MS) return;
+	const release = tryReadinessLease(`${path}.lock`, now);
+	if (!release) return;
+	try {
+		const latest = readReadiness(path, binding);
+		if (typeof latest?.revision === "string" && REVISION.test(latest.revision))
+			return latest.revision;
+		if (now - (latest?.checkedAt ?? 0) < READINESS_RETRY_MS) return;
+		atomicWrite(path, JSON.stringify({ binding, checkedAt: now }));
+		const revision = await requestMemoryReadiness(repo, credentials);
+		if (typeof revision === "string" && REVISION.test(revision)) {
+			atomicWrite(path, JSON.stringify({ binding, checkedAt: now, revision }));
+			return revision;
+		}
+	} catch {
+		// A cache failure must not activate memory or block the normal prompt.
+	} finally {
+		release();
+	}
+}
+
+async function resolveMappedCheckout(target, credentials, hint, probe) {
+	const revision =
+		hint.revision === null ? await resolveRevision(hint.repo, credentials, probe) : hint.revision;
+	if (hasMappedCommit(target, revision)) return target;
+}
+
+export async function cachedMemoryCheckout(cwd, credentials) {
+	const hints = projectMemoryHint(credentials);
+	if (!hints.length) return;
+	const target = checkout(cwd);
+	const hint = target && matchingHint(target, hints);
+	if (hint) return resolveMappedCheckout(target, credentials, hint, false);
+}
+
+export function readHookSettings(path) {
+	try {
+		const info = lstatSync(path);
+		if (!info.isFile() || info.uid !== process.getuid?.() || info.size > 512 * 1024)
+			throw new Error("Expected a regular owner-controlled hook settings file.");
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		if (error.code === "ENOENT") return {};
+		throw error;
+	}
+}
+
+export async function resolveMemoryHookTarget(client, cwd, credentials, probe = false) {
+	if (!Object.hasOwn(LEGACY_SETTINGS, client)) return;
+	const hints = projectMemoryHint(credentials);
+	if (!hints.length) return;
+	const target = checkout(cwd);
+	const hint = target && matchingHint(target, hints);
+	if (!hint) return;
+	try {
+		// A checkout enrolled by the original pilot may still have its own hook.
+		// Leave that hook in charge until normal setup migrates the checkout.
+		if (
+			hasLegacyHooks(readHookSettings(legacySettingsPath(client, target.root)), client, target.root)
+		)
+			return;
+	} catch {
+		// A client settings file we cannot inspect is not safe to double-enroll.
+		return;
+	}
+	return resolveMappedCheckout(target, credentials, hint, probe);
+}
+
+export function memoryClientRoot(home = homedir()) {
+	return join(home, ".pharaoh", "project-memory-client");
+}
+
+export function readActiveMemoryClients(home = homedir()) {
+	try {
+		const root = memoryClientRoot(home);
+		const directory = lstatSync(root);
+		if (!directory.isDirectory() || directory.uid !== process.getuid?.() || directory.mode & 0o077)
+			return {};
+		const path = join(root, "active.json");
+		const file = lstatSync(path);
+		if (!file.isFile() || file.uid !== process.getuid?.() || file.mode & 0o077 || file.size > 512)
+			return {};
+		const active = JSON.parse(readFileSync(path, "utf8"));
+		return Object.fromEntries(
+			Object.keys(LEGACY_SETTINGS).flatMap((client) => {
+				const digest = active?.[client];
+				return typeof digest === "string" && /^[a-f0-9]{64}$/.test(digest)
+					? [[client, digest]]
+					: [];
+			}),
+		);
+	} catch {
+		return {};
+	}
+}
+
+export function activeMemoryRuntime(client, directory, home = homedir()) {
+	const digest = readActiveMemoryClients(home)[client];
+	return Boolean(digest && directory === join(realpathSync(memoryClientRoot(home)), digest));
+}
+
+export async function readMemoryCredentials() {
+	try {
+		const { CREDENTIALS_PATH, readCredentials } = await import("./runtime/credentials.js");
+		const stat = lstatSync(CREDENTIALS_PATH);
+		if (
+			stat.isFile() &&
+			stat.uid === process.getuid?.() &&
+			!(stat.mode & 0o077) &&
+			stat.size <= 65_536
+		)
+			return readCredentials();
+	} catch {
+		// No current owner-private credential file.
+	}
+}