@pharaoh-so/mcp 0.3.57 → 0.3.59

package/.mcp.json

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

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.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
+- The ankh (☥) is gone: the Trace card's header has no mark, and the skills no longer set it as their emoji.
+
 ## [0.3.57] - 2026-11-04
 
 ### Changed

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/npx-skills/brainstorm/SKILL.md

@@ -6,7 +6,7 @@ license: MIT. Adapted from obra/superpowers, Copyright (c) 2025 Jesse Vincent; s
 version: 0.2.1
 homepage: https://pharaoh.so
 user-invocable: true
-metadata: {"emoji": "☥", "tags": ["planning", "design", "brainstorming", "requirements", "architecture"]}
+metadata: {"tags": ["planning", "design", "brainstorming", "requirements", "architecture"]}
 ---
 
 # Brainstorm

package/npx-skills/debug/SKILL.md

@@ -6,7 +6,7 @@ license: MIT. Adapted from obra/superpowers, Copyright (c) 2025 Jesse Vincent; s
 version: 0.2.1
 homepage: https://pharaoh.so
 user-invocable: true
-metadata: {"emoji": "☥", "tags": ["debugging", "root-cause", "investigation", "troubleshooting", "methodology"]}
+metadata: {"tags": ["debugging", "root-cause", "investigation", "troubleshooting", "methodology"]}
 ---
 
 # Systematic Debugging

package/npx-skills/pharaoh/SKILL.md

@@ -4,7 +4,7 @@ prompt-name: pharaoh-core
 description: "Codebase knowledge graph — gives AI agents full architectural awareness. Query architecture, dependencies, blast radius, module context, and function search instead of reading files one at a time. Code intelligence via MCP: understand any codebase in seconds."
 version: 0.3.1
 homepage: https://pharaoh.so
-metadata: {"emoji": "☥", "openclaw": {"always": true}, "tags": ["code-intelligence", "architecture", "mcp", "knowledge-graph", "dependencies", "codebase-understanding"]}
+metadata: {"openclaw": {"always": true}, "tags": ["code-intelligence", "architecture", "mcp", "knowledge-graph", "dependencies", "codebase-understanding"]}
 ---
 
 # Pharaoh Tool Guide

package/npx-skills/plan/SKILL.md

@@ -4,7 +4,7 @@ prompt-name: plan-with-pharaoh
 description: Review a plan or spec against the codebase before implementing it. Pharaoh reconnaissance, a BIG or SMALL change choice, then architecture, code quality, wiring, tests, performance and security sections with numbered decisions.
 version: 0.7.1
 homepage: https://pharaoh.so
-metadata: {"emoji": "☥", "tags": ["planning", "architecture", "blast-radius", "pharaoh", "review", "interactive"]}
+metadata: {"tags": ["planning", "architecture", "blast-radius", "pharaoh", "review", "interactive"]}
 ---
 
 # Plan Review

package/npx-skills/refactor/SKILL.md

@@ -4,7 +4,7 @@ prompt-name: safe-refactor
 description: "Safe refactoring workflow using Pharaoh codebase knowledge graph. Six-step process: module context, blast radius of detected downstream callers, reachability verification, dependency mapping, naming conflict detection, and a search for the affected tests. Produces a refactoring plan with detected callers listed, test files identified, unreachable code flagged, and high-risk paths warned. Use when refactoring, renaming, moving or splitting code in a repo Pharaoh maps, with Pharaoh's tools connected."
 version: 0.3.1
 homepage: https://pharaoh.so
-metadata: {"emoji": "☥", "tags": ["refactoring", "blast-radius", "architecture", "pharaoh", "safe-refactor", "test-coverage"]}
+metadata: {"tags": ["refactoring", "blast-radius", "architecture", "pharaoh", "safe-refactor", "test-coverage"]}
 ---
 
 # Safe Refactor

package/npx-skills/review/SKILL.md

@@ -4,7 +4,7 @@ prompt-name: review-with-pharaoh
 description: "Five-phase workflow: git context detection (worktree, branch, base, changed files), Pharaoh recon (architecture map, module context, blast radius in one call, with a fallback when the repo isn't mapped), parallel specialized agent dispatch (code quality, security against the project's own rules, error handling, test coverage, type design), adversarial review by the other model (Codex from Claude Code, Claude from Codex) for security-sensitive changes, and a final synthesized verdict of SHIP / SHIP WITH CHANGES / BLOCK. Architecture-aware wherever Pharaoh maps the repo. Use when reviewing a branch or pull request before merging, or when the user asks for a code review."
 version: 0.6.1
 homepage: https://pharaoh.so
-metadata: {"emoji": "☥", "tags": ["code-review", "pull-request", "architecture", "pharaoh", "multi-agent", "adversarial-review", "cross-model", "regression-risk", "spec-alignment"]}
+metadata: {"tags": ["code-review", "pull-request", "architecture", "pharaoh", "multi-agent", "adversarial-review", "cross-model", "regression-risk", "spec-alignment"]}
 ---
 
 # Review with Pharaoh

package/npx-skills/tdd/SKILL.md

@@ -6,7 +6,7 @@ license: MIT. Adapted from obra/superpowers, Copyright (c) 2025 Jesse Vincent; s
 version: 0.2.1
 homepage: https://pharaoh.so
 user-invocable: true
-metadata: {"emoji": "☥", "tags": ["tdd", "testing", "red-green-refactor", "quality", "discipline"]}
+metadata: {"tags": ["tdd", "testing", "red-green-refactor", "quality", "discipline"]}
 ---
 
 # Test-Driven Development

package/npx-skills/verify/SKILL.md

@@ -6,7 +6,7 @@ license: MIT. Adapted from obra/superpowers, Copyright (c) 2025 Jesse Vincent; s
 version: 0.2.1
 homepage: https://pharaoh.so
 user-invocable: true
-metadata: {"emoji": "☥", "tags": ["verification", "quality", "completion", "evidence", "discipline"]}
+metadata: {"tags": ["verification", "quality", "completion", "evidence", "discipline"]}
 ---
 
 # Verification Before Completion

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pharaoh-so/mcp",
 	"mcpName": "so.pharaoh/pharaoh",
-	"version": "0.3.57",
+	"version": "0.3.59",
 	"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.

package/trace-app.html

@@ -29,7 +29,6 @@
     .mark-s { font:var(--strong) var(--type-caption) var(--mono); width:1ch; }
     #trace { color:var(--text); border:var(--line); border-radius:var(--radius); padding:10px 12px; font:var(--regular) var(--type-body)/var(--leading) var(--sans); min-width:0; }
     .head { display:flex; flex-wrap:wrap; align-items:baseline; gap:2px 10px; }
-    .mark { color:var(--gold); font-size:var(--type-heading); line-height:1; }
     .headline { flex:1 1 16em; margin:0; min-width:0; overflow-wrap:anywhere; }
     #kind { color:var(--muted); }
     #target { color:var(--ink); font:var(--strong) var(--type-heading)/var(--leading) var(--mono); }
@@ -126,7 +125,6 @@
 <body>
   <main id="trace" data-state="waiting">
     <div class="head">
-      <span class="mark" aria-hidden="true">☥</span>
       <p class="headline"><span id="kind"></span><span id="target"></span><span id="title">Pharaoh</span><span id="summary" role="status" aria-live="polite">Waiting for the tool</span></p>
       <span class="meta"><span id="verdict" hidden></span><span id="sha" hidden></span></span>
     </div>