@pharaoh-so/mcp 0.3.58 → 0.3.60

package/.mcp.json

@@ -3,7 +3,7 @@
 		"pharaoh": {
 			"command": "npx",
 			"args": [
-				"@pharaoh-so/mcp@0.3.58"
+				"@pharaoh-so/mcp@0.3.60"
 			]
 		}
 	}

package/CHANGELOG.md

@@ -26,6 +26,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The `pharaoh` skill's connection URL is `https://mcp.pharaoh.so/mcp` instead of `/sse`. The skill also carries the guidance that was only in the server instructions: one Pharaoh call answers what grep and file reads take many turns to piece together, load Pharaoh's tools before the first code search when your client defers them, summarize a block marked "Trace view available" instead of reproducing it, and check related repos when a change touches shared interfaces.
 - The server instructions state facts: what Pharaoh maps, which tool answers which question, what the graph leaves to grep, how repos are mapped and what each account tool does. Asking Pharaoh first, not re-checking its answers with grep, surfacing and crediting its ★ blocks and the rest of that guidance now live in the `pharaoh` skill. Claude Code and OpenClaw list the skill in every session and load its body only when they use it. The Grep hook and the optional `~/.claude/CLAUDE.md` line are unchanged and apply from the start of a session.
 
+## [0.3.60] - 2026-11-05
+
+### Added
+- When it connects, the proxy tells Pharaoh what your agent's instruction files say about it: whether `~/.claude/CLAUDE.md` holds the line setup suggests, mentions Pharaoh another way, doesn't, or is missing, and whether setup's block is still there. In Claude Code started at a git repo's root, the same for the project's `CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md` or `AGENTS.md`. Only those values are sent, never file text. A file over 64 KB, or one that isn't a regular file or can't be read, counts as unknown. Pharaoh uses this to learn whether the line leads agents to use it (privacy policy § 9, connection records).
+
+## [0.3.59] - 2026-11-04
+
+### Changed
+- The project memory pilot uses Pharaoh's MCP tools by default. Interactive setup removes managed pilot hooks from user settings and from eligible ignored settings in the current checkout. Tracked or linked checkout hooks require manual removal.
+- Use `--memory-hooks` during interactive setup to opt in to a prompt reminder for the MCP tools. Use `--disable-memory-hooks` to remove managed pilot hooks without signing in again.
+
 ## [0.3.58] - 2026-11-04
 
 ### Changed

package/README.md

@@ -152,10 +152,11 @@ claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version> --server ht
 - Credentials are stored with restrictive file permissions (`0600` — owner-read/write only)
 - Authentication uses the [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628) device authorization flow — no secrets are embedded in the package
 - All communication with the Pharaoh server uses HTTPS/TLS
-- The proxy never reads or sends your local files. Pharaoh reads your code from GitHub through its GitHub App, maps it into a knowledge graph of structural metadata (function names, file paths, dependency relationships), and deletes the clone when mapping ends.
+- The proxy never sends your code or the text of any file. Pharaoh reads your code from GitHub through its GitHub App, maps it into a knowledge graph of structural metadata (function names, file paths, dependency relationships), and deletes the clone when mapping ends.
+- From 0.3.60, when it connects, the proxy also tells Pharaoh whether your `~/.claude/CLAUDE.md` holds the line setup suggests, mentions Pharaoh another way, doesn't, or is missing, and whether setup's block is still in it. In Claude Code started at a git repo's root, it does the same for that project's `CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md` and `AGENTS.md`. Only these values are sent, never the files' text.
 - Tokens expire after 7 days and are refreshed automatically
 - Only use trusted server URLs — the proxy sends your auth token to the configured server
-- No telemetry. The proxy's only network calls are the device flow, token refresh, the MCP connection, and one registry lookup during interactive setup (below).
+- The proxy's only network calls are the device flow, token refresh, the MCP connection, and one registry lookup during interactive setup (below). Over the MCP connection it tells Pharaoh which client it serves (the name and version that client reports) and whether Pharaoh's Claude Code plugin is enabled, which it reads from `~/.claude/settings.json`. Nothing else about your machine is sent.
 
 ### What the installer writes on your machine
 

package/dist/backend.d.ts

@@ -17,6 +17,7 @@
  */
 import type { CallToolResult, ClientCapabilities, Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { DeviceFlowGateway } from "./gateway.js";
+import type { InstructionState, ManagedBlockState } from "./install-skills.js";
 /**
  * Notification that tells Pharaoh which client the proxy serves. Pharaoh sees
  * the proxy itself as `pharaoh-proxy`; this lands on the session's row.
@@ -32,6 +33,12 @@ export type DownstreamClient = {
     };
     /** Pharaoh's Claude Code plugin as ~/.claude/settings.json lists it. */
     plugin: "enabled" | "disabled" | "absent";
+    /** What the client's instruction files say about Pharaoh (install-skills.ts instructionStates); never their text. */
+    instructions?: {
+        user: InstructionState;
+        managed: ManagedBlockState;
+        project: InstructionState;
+    };
 };
 /** The contract ProxyServer uses to delegate tool handling. */
 export interface Backend {

package/dist/helpers.js

@@ -96,7 +96,7 @@ export function parseArgs(argv = process.argv.slice(2)) {
     return { server, logout };
 }
 export function printUsage() {
-    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials, MCP config, the Claude Code plugin and the CLAUDE.md line, then exit", "  --clean           Remove Pharaoh setup, including managed local project memory hooks", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --version, -v     Print the version", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
+    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials, MCP config, the Claude Code plugin and the CLAUDE.md line, then exit", "  --clean           Remove Pharaoh setup, including managed local project memory hooks", "  --memory-hooks    Install optional project memory reminders during interactive setup", "  --disable-memory-hooks  Remove Pharaoh's local project memory hooks", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --version, -v     Print the version", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
 }
 /**
  * Validate that a server-supplied SSE URL shares the same origin as the configured server.

package/dist/index.js

@@ -37,9 +37,11 @@ function reportMemorySetup(options) {
         const notices = syncMemoryHooks(options);
         if (notices.length)
             printLines(...notices);
+        return notices.length === 0;
     }
     catch {
         printLines("Pharaoh: project memory setup could not update local activation.");
+        return false;
     }
 }
 async function main() {
@@ -65,6 +67,11 @@ async function main() {
         runInstallSkills();
         return;
     }
+    if (args.includes("--disable-memory-hooks")) {
+        if (!reportMemorySetup())
+            process.exitCode = 1;
+        return;
+    }
     // Clean mode — remove all pharaoh traces from Claude Code config (MCP entries,
     // disabled states, project-scoped configs). Useful for resetting broken installs.
     if (args.includes("--clean")) {
@@ -73,7 +80,7 @@ async function main() {
         cleanSlate();
         uninstallClaudePlugin();
         cleanCodexSetup();
-        reportMemorySetup({ removeLegacy: true });
+        reportMemorySetup();
         printLines("Pharaoh: local setup cleanup finished.");
         process.exit(0);
     }
@@ -86,7 +93,7 @@ async function main() {
         cleanSlate();
         uninstallClaudePlugin();
         cleanCodexSetup();
-        reportMemorySetup({ removeLegacy: true });
+        reportMemorySetup();
         printLines("Pharaoh: credentials cleared and local setup cleanup finished.");
         process.exit(0);
     }
@@ -137,7 +144,7 @@ async function main() {
             if (claudeMd)
                 printLines(claudeMd);
         }
-        reportMemorySetup({ credentials: newCreds, clients });
+        reportMemorySetup({ credentials: newCreds, clients, enable: args.includes("--memory-hooks") });
         // The registration is pinned to this version; upgrading is a deliberate
         // re-run. Interactive only, and quiet when the registry can't be reached.
         const latest = await fetchLatestVersion();

package/dist/install-skills.d.ts

@@ -87,6 +87,19 @@ export declare function allowReadTools(home?: string): AllowReadToolsResult;
 export declare function describeAllowReadTools(result: AllowReadToolsResult): string;
 /** What the interactive setup asks before writing the line. */
 export declare const CLAUDE_MD_QUESTION = "Pharaoh: add one line to ~/.claude/CLAUDE.md so Claude checks Pharaoh before searching your code?\n  \"In repos Pharaoh has mapped, before searching or reading files, ask Pharaoh where the relevant code is, what calls it, and whether what you need already exists.\"\n[Y/n] ";
+/** What an instruction file says about Pharaoh: the suggested line, another mention, none, no file, or unreadable. */
+export type InstructionState = "exact" | "mention" | "none" | "missing" | "unknown";
+/** Whether the block setup wrote into ~/.claude/CLAUDE.md is there and holds the current line. */
+export type ManagedBlockState = "current" | "stale" | "absent" | "unknown";
+/**
+ * The instruction state the proxy reports for its client. Project files only
+ * for clients known to start the proxy in the project folder. Never throws.
+ */
+export declare function instructionStates(clientName: string | undefined, cwd?: string, home?: string): {
+    user: InstructionState;
+    managed: ManagedBlockState;
+    project: InstructionState;
+};
 /** What `offerClaudeMdLine` did; `describeClaudeMdOutcome` words it. */
 export type ClaudeMdOutcome = "added" | "updated" | "declined" | "kept" | "failed" | "current" | "answered" | "cancelled" | "no-terminal" | "no-claude";
 /**

package/dist/install-skills.js

@@ -6,9 +6,9 @@
  * and OpenClaw skills in ~/.openclaw/skills/. Also merges the Pharaoh MCP
  * server config into OpenClaw.
  */
-import { closeSync, constants, cpSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { closeSync, constants, cpSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ensurePharaohHome } from "./credentials.js";
 import { CLAUDE_CLI_SETUP_URL, claudeCliFor } from "./setup.js";
@@ -765,6 +765,111 @@ function readClaudeMd(home) {
     const current = text.slice(block.body, block.to) === `${PHARAOH_CLAUDE_MD_LINE}\n`;
     return { state: current ? "current" : "stale", path, text, block };
 }
+/** A CLAUDE.md is a few KB; anything bigger reads as "unknown" instead of slowing initialize. */
+const INSTRUCTION_READ_CAP = 64 * 1024;
+/**
+ * A project's instruction files, read only for clients confirmed to start the
+ * proxy in the project folder (Claude Code 2.1.310 does: probed 2026-11-04).
+ */
+const PROJECT_INSTRUCTION_FILES = [
+    "CLAUDE.md",
+    "CLAUDE.local.md",
+    join(".claude", "CLAUDE.md"),
+    "AGENTS.md",
+];
+const PROJECT_CWD_CLIENTS = new Set(["claude-code"]);
+/**
+ * Up to `cap` bytes of a regular file, read from the descriptor that was
+ * checked, so a FIFO or device swapped in can't block `initialize`. A symlink
+ * is followed: only a state is derived from what it points at.
+ *
+ * @returns The file's text, wrapped so no content can read as a state;
+ *   "missing" when there's no file; "unknown" when it's over the cap, not a
+ *   regular file, or unreadable
+ */
+function readBoundedText(path, cap = INSTRUCTION_READ_CAP) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+    }
+    catch (err) {
+        const code = err.code;
+        return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "unknown";
+    }
+    try {
+        if (!fstatSync(fd).isFile())
+            return "unknown";
+        const buf = Buffer.alloc(cap + 1);
+        let length = 0;
+        while (length <= cap) {
+            const n = readSync(fd, buf, length, cap + 1 - length, null);
+            if (n === 0)
+                break;
+            length += n;
+        }
+        return length > cap ? "unknown" : { text: buf.toString("utf-8", 0, length) };
+    }
+    catch {
+        return "unknown";
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Whether `text` holds the suggested line, otherwise mentions Pharaoh, or neither. */
+function classifyInstructionText(text) {
+    if (text.includes(PHARAOH_CLAUDE_MD_LINE))
+        return "exact";
+    return /\bpharaoh\b/i.test(text) ? "mention" : "none";
+}
+/** What ~/.claude/CLAUDE.md says about Pharaoh, and whether setup's block is there and current. */
+function userInstructionState(home = homedir()) {
+    const file = readBoundedText(join(home, ".claude", "CLAUDE.md"));
+    if (file === "missing")
+        return { user: "missing", managed: "absent" };
+    if (file === "unknown")
+        return { user: "unknown", managed: "unknown" };
+    const { text } = file;
+    const block = findClaudeMdBlock(text);
+    const managed = block === null
+        ? "absent"
+        : block === "broken"
+            ? "unknown"
+            : text.slice(block.body, block.to) === `${PHARAOH_CLAUDE_MD_LINE}\n`
+                ? "current"
+                : "stale";
+    return { user: classifyInstructionText(text), managed };
+}
+/**
+ * The strongest state across a project's instruction files: any exact line,
+ * then any mention, then any unreadable file, then a file without a mention.
+ * "unknown" outside a git repository's root or in the home folder.
+ */
+function projectInstructionState(cwd, home = homedir()) {
+    if (resolve(cwd) === resolve(home) || !existsSync(join(cwd, ".git")))
+        return "unknown";
+    const states = PROJECT_INSTRUCTION_FILES.map((file) => {
+        const read = readBoundedText(join(cwd, file));
+        return typeof read === "string" ? read : classifyInstructionText(read.text);
+    });
+    return (["exact", "mention", "unknown", "none"].find((s) => states.includes(s)) ?? "missing");
+}
+/**
+ * The instruction state the proxy reports for its client. Project files only
+ * for clients known to start the proxy in the project folder. Never throws.
+ */
+export function instructionStates(clientName, cwd, home = homedir()) {
+    try {
+        // process.cwd() throws when the folder was deleted: inside the try, so it reads as unknown.
+        const project = clientName && PROJECT_CWD_CLIENTS.has(clientName)
+            ? projectInstructionState(cwd ?? process.cwd(), home)
+            : "unknown";
+        return { ...userInstructionState(home), project };
+    }
+    catch {
+        return { user: "unknown", managed: "unknown", project: "unknown" };
+    }
+}
 /**
  * Offer the Pharaoh-first line in ~/.claude/CLAUDE.md. Interactive setup only,
  * never a proxy start. Asks only when the block is absent and the user hasn't

package/dist/proxy-server.js

@@ -27,7 +27,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { AuthRequiredBackend, createSseBackend, } from "./backend.js";
 import { loadBundledCatalog } from "./catalog.js";
 import { createGateway } from "./gateway.js";
-import { claudePluginState } from "./install-skills.js";
+import { claudePluginState, instructionStates } from "./install-skills.js";
 import { TenantSuspendedError, TokenExpiredError } from "./proxy.js";
 import { registerTraceResource } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
@@ -70,6 +70,7 @@ export class ProxyServer {
             const downstream = {
                 client: { name: info?.name, version: info?.version },
                 plugin: claudePluginState(),
+                instructions: instructionStates(info?.name),
             };
             this.downstream = downstream;
             this.clientCapabilities = this.server.getClientCapabilities() ?? {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pharaoh-so/mcp",
 	"mcpName": "so.pharaoh/pharaoh",
-	"version": "0.3.58",
+	"version": "0.3.60",
 	"description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for coding agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
 	"type": "module",
 	"main": "dist/index.js",

package/project-memory/hook-config.mjs

@@ -20,15 +20,29 @@ function hookCommand(entry) {
 	return entry?.type === "command" && typeof entry.command === "string" ? entry.command : "";
 }
 
+function matchesLegacyHook(client, root) {
+	const suffix = ` ${legacyMarker(client, root)}`;
+	return (value) => value.includes("pharaoh-memory-hook.mjs") && value.endsWith(suffix);
+}
+
+function matchesUserHook(value) {
+	return (
+		value.includes("pharaoh-memory-hook.mjs") &&
+		(value.endsWith(` ${GLOBAL_MARKER}`) || LEGACY_MARKER.test(value))
+	);
+}
+
 /** Keep unrelated handlers even when they share an event group with ours. */
-function replaceHooks(config, client, matches, command) {
+function replaceHooks(config, client, matches, command, installEvents = EVENTS[client]) {
 	if (!isObject(config) || (config.hooks !== undefined && !isObject(config.hooks))) {
 		throw new Error("The existing hooks configuration is not a JSON object.");
 	}
 	const hooks = { ...config.hooks };
 	for (const event of EVENTS[client]) {
 		const current = hooks[event];
-		if (current === undefined && !command) continue;
+		const install = command && installEvents.includes(event);
+		if (!install && (current === undefined || (Array.isArray(current) && !current.length)))
+			continue;
 		if (
 			current !== undefined &&
 			(!Array.isArray(current) || current.some((group) => !Array.isArray(group?.hooks)))
@@ -40,7 +54,7 @@ function replaceHooks(config, client, matches, command) {
 			if (rest.length === group.hooks.length) return [group];
 			return rest.length ? [{ ...group, hooks: rest }] : [];
 		});
-		if (command) kept.push({ hooks: [{ type: "command", command, timeout: 3 }] });
+		if (install) kept.push({ hooks: [{ type: "command", command, timeout: 3 }] });
 		if (kept.length) hooks[event] = kept;
 		else delete hooks[event];
 	}
@@ -55,37 +69,33 @@ export function updateHooks(config, client, target, remove, hookPath, node = pro
 	const command = remove
 		? null
 		: `${[node, hookPath, client, target.root, target.repo].map(shellWord).join(" ")} ${marker}`;
-	return replaceHooks(config, client, (value) => value.endsWith(` ${marker}`), command);
+	return replaceHooks(config, client, matchesLegacyHook(client, target.root), command);
 }
 
 export function updateUserHooks(config, client, hookPath, node = process.execPath) {
 	const command = hookPath
 		? `${[node, hookPath, client, "--user"].map(shellWord).join(" ")} ${GLOBAL_MARKER}`
 		: null;
-	return replaceHooks(
-		config,
-		client,
-		(value) =>
-			value.endsWith(` ${GLOBAL_MARKER}`) ||
-			(value.includes("pharaoh-memory-hook.mjs") && LEGACY_MARKER.test(value)),
-		command,
-	);
+	return replaceHooks(config, client, matchesUserHook, command, ["UserPromptSubmit"]);
 }
 
-export function hasLegacyHooks(config, client, root) {
-	const suffix = ` ${legacyMarker(client, root)}`;
+function hasHooks(config, client, matches) {
 	return EVENTS[client].some((event) => {
 		const groups = config?.hooks?.[event];
 		return (
 			Array.isArray(groups) &&
 			groups.some(
 				(group) =>
-					Array.isArray(group?.hooks) &&
-					group.hooks.some((entry) => {
-						const command = hookCommand(entry);
-						return command.includes("pharaoh-memory-hook.mjs") && command.endsWith(suffix);
-					}),
+					Array.isArray(group?.hooks) && group.hooks.some((entry) => matches(hookCommand(entry))),
 			)
 		);
 	});
 }
+
+export function hasLegacyHooks(config, client, root) {
+	return hasHooks(config, client, matchesLegacyHook(client, root));
+}
+
+export function hasUserHooks(config, client) {
+	return hasHooks(config, client, matchesUserHook);
+}

package/project-memory/hook-events.mjs

@@ -35,7 +35,7 @@ function promptContext(token, compact, mayCapture) {
 	].join("\n");
 }
 
-function skipPrompt(value) {
+export function skipMemoryPrompt(value) {
 	const prompt = typeof value === "string" ? value.trim() : "";
 	return (
 		!prompt ||
@@ -47,6 +47,16 @@ function skipPrompt(value) {
 	);
 }
 
+export function memoryReminder(repo) {
+	if (!REPO.test(repo)) return;
+	return {
+		hookSpecificOutput: {
+			hookEventName: "UserPromptSubmit",
+			additionalContext: `For work in ${repo}, use pharaoh_memory_recall if prior decisions may matter. Use pharaoh_memory_expand if you need the full record, and pharaoh_memory_capture for one supported candidate when the task permits. Mention memory only when it changes a decision.`,
+		},
+	};
+}
+
 /** Hook input can contain raw prompts and transcripts. Neither is persisted or transmitted. */
 export function handleEvent(
 	input,
@@ -90,7 +100,7 @@ export function handleEvent(
 				input.prompt,
 			);
 		const opened = store.begin(key, target, client, nativeTurn, {
-			skip: skipPrompt(input.prompt),
+			skip: skipMemoryPrompt(input.prompt),
 			readOnly: noCapture,
 			memorySession,
 		});

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

@@ -1,7 +1,7 @@
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { handleEvent } from "./hook-events.mjs";
-import { checkout, readStdin } from "./local.mjs";
+import { handleEvent, memoryReminder, skipMemoryPrompt } from "./hook-events.mjs";
+import { readStdin } from "./local.mjs";
 import {
 	activeMemoryRuntime,
 	readMemoryCredentials,
@@ -15,30 +15,29 @@ const exitQuietly = setTimeout(() => process.exit(0), Math.max(0, deadline - per
 try {
 	const [client, root, repo] = process.argv.slice(2);
 	const input = await readStdin(1024 * 1024);
-	const credentials = await readMemoryCredentials();
-	let target = { root, repo };
+	let result;
 	if (root === "--user") {
 		const runtime = dirname(fileURLToPath(import.meta.url));
 		if (!activeMemoryRuntime(client, runtime)) process.exit(0);
-		const isPrompt = input?.hook_event_name === "UserPromptSubmit";
+		if (input?.hook_event_name !== "UserPromptSubmit" || skipMemoryPrompt(input.prompt))
+			process.exit(0);
 		const eligible = await resolveMemoryHookTarget(
 			client,
 			input?.cwd,
-			credentials,
-			isPrompt && typeof input?.prompt === "string" && Boolean(input.prompt.trim()),
+			await readMemoryCredentials(),
+			true,
 			deadline,
 		);
-		// Cleanup must still close the turn after sign-out or loss of eligibility.
-		const resolved = eligible ?? (!isPrompt && checkout(input?.cwd, deadline));
-		if (!resolved) process.exit(0);
-		target = { ...resolved, runtime };
+		if (eligible && performance.now() < deadline) result = memoryReminder(eligible.repo);
+	} else {
+		result = handleEvent(input, {
+			client,
+			root,
+			repo,
+			credentials: await readMemoryCredentials(),
+			deadline,
+		});
 	}
-	const result = handleEvent(input, {
-		client,
-		...target,
-		credentials,
-		deadline,
-	});
 	if (result) process.stdout.write(JSON.stringify(result));
 } catch {
 	// Project memory never blocks ordinary work or opens a continuation.

package/project-memory/setup.d.mts

@@ -5,10 +5,10 @@ export function syncMemoryHooks(options?: {
 		project_memory_status?: "unavailable";
 	};
 	clients?: string[];
+	enable?: boolean;
 	home?: string;
 	env?: NodeJS.ProcessEnv;
 	cwd?: string;
 	node?: string;
-	removeLegacy?: boolean;
 	packageRoot?: URL;
 }): string[];

package/project-memory/setup.mjs

@@ -1,18 +1,20 @@
 import { lstatSync, mkdirSync, realpathSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 import { bundledHook, installMemoryBundle, packagedMemoryBundle } from "./bundle.mjs";
-import { hasLegacyHooks, updateHooks, updateUserHooks } from "./hook-config.mjs";
+import { hasLegacyHooks, hasUserHooks, updateHooks, updateUserHooks } from "./hook-config.mjs";
 import { atomicWrite, checkout, git, hasMemoryGit } from "./local.mjs";
 import {
-	eligibleCheckout,
 	legacySettingsPath,
+	matchingMemoryHint,
 	memoryClientRoot,
 	projectMemoryHint,
 	readActiveMemoryClients,
 	readHookSettings,
 } from "./user-target.mjs";
 
+const CLIENTS = ["claude-code", "codex"];
+
 function userSettings(client, home, env) {
 	const codex = client === "codex";
 	const directory =
@@ -21,131 +23,173 @@ function userSettings(client, home, env) {
 	return join(directory, codex ? "hooks.json" : "settings.json");
 }
 
-function writeSettings(path, previous, next) {
-	if (JSON.stringify(previous) === JSON.stringify(next)) return;
+function canonicalSettingsPath(path) {
+	try {
+		return realpathSync(path);
+	} catch (error) {
+		const parent = dirname(path);
+		if (error.code !== "ENOENT" || parent === path) throw error;
+		// Even a missing settings file can be under a linked ancestor.
+		return join(canonicalSettingsPath(parent), basename(path));
+	}
+}
+
+function inspectSettings(path) {
+	const resolved = canonicalSettingsPath(path);
+	return { path, resolved, config: readHookSettings(resolved) };
+}
+
+function writeSettings({ path, resolved, config }, next, target, requireIgnored = false) {
+	if (JSON.stringify(config) === JSON.stringify(next)) return;
+	if (requireIgnored && path !== resolved)
+		throw new Error("The checkout hook settings are linked.");
+	if (target) {
+		const location = relative(target.root, resolved);
+		if (
+			location &&
+			location !== ".." &&
+			!location.startsWith(`..${sep}`) &&
+			!isAbsolute(location)
+		) {
+			if (git(target.root, "ls-files", "--", `:(literal)${location}`))
+				throw new Error("The checkout hook settings are tracked.");
+			if (requireIgnored) git(target.root, "check-ignore", "--quiet", "--no-index", "--", location);
+		}
+	}
 	const directory = dirname(path);
+	const file = lstatSync(path, { throwIfNoEntry: false });
+	if (file && !file.isFile()) throw new Error("The hook settings are linked.");
 	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`);
+	atomicWrite(resolved, `${JSON.stringify(next, null, "\t")}\n`);
 }
 
-function migrateCheckout(client, target) {
+function migrateCheckout(client, target, notices) {
 	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));
+	let known = false;
+	try {
+		const settings = inspectSettings(legacySettingsPath(client, target.root));
+		known = hasLegacyHooks(settings.config, client, target.root);
+		if (known)
+			writeSettings(settings, updateHooks(settings.config, client, target, true), target, true);
+	} catch {
+		if (known)
+			notices.push(
+				`Pharaoh: the earlier ${client} checkout hook remains in place for this checkout.`,
+			);
+	}
 }
 
-/** Run only as part of a deliberate normal setup, upgrade, clean or logout. */
+function syncUserHooks(client, home, env, target, hookPath, node, alreadyActive) {
+	let known = Boolean(alreadyActive);
+	try {
+		const settings = inspectSettings(userSettings(client, home, env));
+		known ||= hasUserHooks(settings.config, client);
+		if (hookPath || known) {
+			const legacy = target && legacySettingsPath(client, target.root);
+			const checkoutHook =
+				legacy &&
+				[settings.path, settings.resolved].includes(legacy) &&
+				hasLegacyHooks(settings.config, client, target.root);
+			writeSettings(
+				settings,
+				updateUserHooks(settings.config, client, hookPath, node),
+				target,
+				checkoutHook,
+			);
+		}
+	} catch (error) {
+		if (hookPath || known) throw error;
+	}
+}
+
+function writeActivation(path, active) {
+	if (Object.keys(active).length) atomicWrite(path, `${JSON.stringify(active)}\n`);
+	else rmSync(path, { force: true });
+}
+
+/** Run only during setup or explicit cleanup of the local memory hooks. */
 export function syncMemoryHooks({
 	credentials,
 	clients = [],
+	enable = false,
 	home = homedir(),
 	env = process.env,
 	cwd = process.cwd(),
 	node = process.execPath,
-	removeLegacy = false,
 	packageRoot,
 } = {}) {
-	const hint = projectMemoryHint(credentials);
+	if (typeof process.getuid !== "function")
+		return enable ? ["Pharaoh: project memory reminders need a POSIX client."] : [];
 	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 activePath = join(root, "active.json");
+	let active = readActiveMemoryClients(home);
+	const target = checkout(cwd);
 	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) {
+	const hint = projectMemoryHint(credentials);
+	if (enable) {
+		if (credentials?.project_memory_status === "unavailable")
+			return [
+				"Pharaoh: project memory eligibility could not be checked. Retry setup to enable reminders.",
+			];
+		if (!hint.length) return ["Pharaoh: this session has no project memory hook grant."];
 		try {
-			if (!hasMemoryGit || typeof process.getuid !== "function")
-				throw new Error("Project memory needs a POSIX client with system Git.");
+			if (!hasMemoryGit) throw new Error("Project memory needs a POSIX client with system Git.");
+			const enrolledRoot = target && matchingMemoryHint(target, hint) ? target.root : undefined;
 			const bundle = packagedMemoryBundle(packageRoot);
 			digest = bundle.sha256;
-			installed = bundledHook(installMemoryBundle(root, target?.root ?? pendingRoot, bundle));
+			installed = bundledHook(installMemoryBundle(root, enrolledRoot, bundle));
 		} catch (error) {
-			return [`Pharaoh: project memory setup unavailable. ${error.message}`];
+			return [`Pharaoh: project memory reminders unavailable. ${error.message}`];
 		}
 	}
 
-	for (const client of ["claude-code", "codex"]) {
-		const desired = clients.includes(client) ? installed : undefined;
-		if (!desired && !previous[client] && !removeLegacy) continue;
+	for (const client of CLIENTS) {
+		if (enable && !clients.includes(client)) continue;
+		const next = { ...active, [client]: digest };
 		try {
-			const path = userSettings(client, home, env);
-			const before = readHookSettings(path);
-			writeSettings(path, before, updateUserHooks(before, client, desired, node));
-			if (desired) {
-				active[client] = digest;
+			// Enable the replacement before swapping any settings, so failed
+			// activation cannot strand an existing hook or remove a legacy one.
+			const replacing = enable && active[client] !== digest;
+			if (replacing) writeActivation(activePath, next);
+			try {
+				syncUserHooks(client, home, env, target, installed, node, active[client]);
+			} catch (error) {
+				if (replacing) writeActivation(activePath, active);
+				throw error;
+			}
+			if (enable) {
+				active = next;
 				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.`,
-				);
+			notices.push(
+				`Pharaoh: could not update ${client} project memory hooks. Check the client settings and retry.`,
+			);
 		}
 	}
 
-	// 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) {
+	// Deactivate loaded user hooks even if known settings could not be edited.
+	if (!enable && Object.keys(active).length) writeActivation(activePath, {});
+	for (const client of enable ? configured : CLIENTS) migrateCheckout(client, target, notices);
+	if (configured.length) {
+		notices.push(
+			"Pharaoh project memory reminders are set up for your eligible repositories. Start a new local conversation.",
+		);
+		if (hint.some((entry) => entry?.revision === null))
 			notices.push(
-				"Pharaoh project memory is set up for your eligible repositories. Start a new local conversation.",
+				"A connected repository is still mapping. Its reminder will run after the mapped revision is available.",
 			);
-			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 {
+		if (configured.includes("codex"))
 			notices.push(
-				`Pharaoh: the earlier ${client} checkout hook remains in place for this checkout.`,
+				"In Codex, review and trust the Pharaoh reminder in /hooks or Settings > Hooks.",
 			);
-		}
 	}
 	return notices;
 }

package/project-memory/user-target.mjs

@@ -33,7 +33,7 @@ export function projectMemorySession(credentials) {
 		return session;
 }
 
-function matchingHint(target, hints) {
+export function matchingMemoryHint(target, hints) {
 	return hints.find(
 		(entry) =>
 			typeof entry?.repo === "string" && entry.repo.toLowerCase() === target.repo.toLowerCase(),
@@ -51,12 +51,6 @@ function hasMappedCommit(target, revision, deadline = Infinity) {
 	}
 }
 
-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");
 }
@@ -142,7 +136,7 @@ export async function cachedMemoryCheckout(cwd, credentials) {
 	const hints = projectMemoryHint(credentials);
 	if (!hints.length) return;
 	const target = checkout(cwd);
-	const hint = target && matchingHint(target, hints);
+	const hint = target && matchingMemoryHint(target, hints);
 	if (hint) return resolveMappedCheckout(target, credentials, hint, false);
 }
 
@@ -169,7 +163,7 @@ export async function resolveMemoryHookTarget(
 	const hints = projectMemoryHint(credentials);
 	if (!hints.length) return;
 	const target = checkout(cwd, deadline);
-	const hint = target && matchingHint(target, hints);
+	const hint = target && matchingMemoryHint(target, hints);
 	if (!hint) return;
 	try {
 		// A checkout enrolled by the original pilot may still have its own hook.