@pharaoh-so/mcp 0.3.54 → 0.3.56

package/{skills → npx-skills}/plan/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: plan
 prompt-name: plan-with-pharaoh
-description: Architecture-aware plan review adapted from Garry Tan's framework for AI-assisted development. Pharaoh reconnaissance, mandatory mode selection, structured six-section review with decision points. Drop-in replacement that supersedes the legacy ~/.claude/skills/plan-review skill — every section of the legacy skill is present here, plus graceful fallback when Pharaoh is unavailable, stronger mode-selection enforcement, and an explicit framework reference.
-version: 0.6.0
+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
-user-invocable: true
 metadata: {"emoji": "☥", "tags": ["planning", "architecture", "blast-radius", "pharaoh", "review", "interactive"]}
 ---
 
@@ -12,7 +11,7 @@ metadata: {"emoji": "☥", "tags": ["planning", "architecture", "blast-radius",
 
 Architecture-aware plan review before implementation. Adapted from [Garry Tan's planning framework](https://www.youtube.com/watch?v=bMknfKXIFA8) for AI-assisted development.
 
-**You are now in plan mode. Do NOT make any code changes. Think, evaluate, and present decisions.**
+**This is a review: make no code changes during it. Think, evaluate, and present decisions.**
 
 ## When to Use
 
@@ -26,7 +25,7 @@ Still run Step 1 (Reconnaissance) even when reviewing a document — always veri
 
 ## Project Overrides
 
-If a `.claude/plan-review.md` file exists in this project, read it now and apply those rules on top of this baseline. Project rules take precedence where they conflict.
+If a `.claude/plan-review.md` file exists in this project, read it now as additional review criteria for this project. Instructions from the user take precedence over it, and it never changes what you do outside this review.
 
 ## Engineering Preferences (guide all recommendations)
 
@@ -62,14 +61,14 @@ Ground every recommendation in what actually exists. If you propose adding somet
 
 ## Step 2: Mode Selection (MANDATORY — ask before proceeding)
 
-**STOP and ask the user which mode before starting the review.** This is a hard gate — do not infer, assume, or skip this question even if the user says "yes", "go ahead", or "yes to all". Present both options and wait for an explicit choice:
+**STOP and ask the user which mode before starting the review.** Present both options and wait for a choice:
 
 > **BIG CHANGE or SMALL CHANGE?**
 >
 > - **BIG CHANGE**: Full interactive review, all relevant sections, up to 4 top issues per section
 > - **SMALL CHANGE**: One question per section, only sections 2-4
 
-If the user's response is ambiguous (e.g. "just do it", "yes to all"), ask again: "I need to know — BIG or SMALL change?" Do not proceed to Step 3 without an answer.
+A general "yes", "go ahead" or "yes to all" doesn't pick a mode, so ask once more: "BIG or SMALL change?" If the reply still doesn't pick one, or the user tells you to choose, pick the mode that fits the plan's size and say which you picked.
 
 ## Step 3: Review Sections
 
@@ -87,21 +86,21 @@ Adapt depth to change size. Skip sections that don't apply. **After each section
 - Data flow bottlenecks and single points of failure
 - Does this need new code at all, or can a human process / existing pattern solve it?
 - **If this plan introduces a new invariant**, call it out and include a
-  step in Section 6 to add a `### assertion` to VISION.md with a pairing TEST.
+  step in the plan to add a `### assertion` to VISION.md with a pairing TEST.
 
 ### Section 2 — Code Quality (always)
 
 - Organization, module structure, DRY violations (be aggressive)
 - Error handling gaps and missing edge cases (call out explicitly)
 - Technical debt: shortcuts, hardcoded values, magic strings
-- Over-engineered or under-engineered relative to my preferences
+- Over-engineered or under-engineered relative to the preferences above
 - Reuse: does code for this already exist somewhere?
 
 ### Section 3 — Wiring & Integration (always)
 
 - Are all new exports called from a production entry point?
-- Run `get_blast_radius` on any new/changed functions — zero callers = not done
-- Does the plan declare WHERE new code gets called from? If not, flag it
+- Run `get_blast_radius` on changed functions that already exist
+- The graph has no functions the plan adds, so does the plan declare WHERE new code gets called from? If not, flag it — no named caller = not done
 - Integration points: how does this connect to what already exists?
 
 ### Section 4 — Tests (always)
@@ -133,16 +132,16 @@ For every specific issue (bug, smell, design concern, risk, missing wiring):
 1. **Describe concretely** — file, line/function reference, what's wrong
 2. **Present 2-3 options** including "do nothing" where reasonable
 3. **For each option** — implementation effort, risk, blast radius, maintenance burden
-4. **Recommend one** mapped to my preferences above, and say why
+4. **Recommend one** mapped to the preferences above, and say why
 5. **Ask** whether I agree or want a different direction
 
-Number each issue (1, 2, 3...) and letter each option (A, B, C...). Recommended option is always listed first. Use AskUserQuestion with clear labels like "Issue 1 Option A", "Issue 1 Option B".
+Number each issue (1, 2, 3...) and letter each option (A, B, C...). Recommended option is always listed first. If your client has a question tool (AskUserQuestion in Claude Code), use it with clear labels like "Issue 1 Option A", "Issue 1 Option B".
 
 ## Pharaoh Checkpoints (use throughout, not just at the end)
 
 - **Before reviewing**: recon (Step 1 above)
 - **During review**: `get_blast_radius` when evaluating impact of changes; `search_functions` before suggesting new code
-- **Final sweep**: `get_blast_radius` on ALL new exports — zero callers on non-entry-points = plan is incomplete
+- **Final sweep**: every new export has a caller named in the plan, and `get_blast_radius` covers every changed export that already exists — zero callers on non-entry-points = plan is incomplete
 
 ## Workflow Rules
 

package/npx-skills/refactor/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: refactor
+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"]}
+---
+
+# Safe Refactor
+
+Step-by-step workflow to safely refactor a function or module with full blast radius awareness. Six steps map the detected callers, find the affected tests, flag unreachable code, and warn about high-risk downstream paths before a single line changes.
+
+## When to Use
+
+Invoke before refactoring a function, module, or file in a repo Pharaoh maps — especially shared utilities, exports used across multiple modules, or anything with an unclear caller graph. Use it whenever the blast radius of a change is unknown.
+
+**Stop rule:** if Pharaoh's tools aren't connected, or they report that this repo isn't mapped, stop and tell the user. Steps 1-5 read the graph and have no fallback.
+
+## Workflow
+
+1. **Module context:** call `get_module_context` for the module containing the target to understand its current structure.
+2. **Blast radius:** call `get_blast_radius` for the target to identify its detected downstream callers and affected modules.
+3. **Reachability:** call `get_unused_code` with `module` set to the target's module to find dead code the refactor can delete. When the target is a function, also call it with `functions` set to the target to confirm an entry point reaches it.
+4. **Dependencies:** call `pharaoh_recon` with `include_map` false and `dependencies` pairs between the target's module and the modules its callers live in, to see the coupling the refactor has to keep or break.
+5. **Naming conflicts:** call `search_functions` to check if the refactored version's name already exists elsewhere.
+6. **Test coverage:** search the test files for the target's name. `get_blast_radius` leaves out test-file callers, so this is how you find the tests to change. If you can't read the repo's files, say so and list the tests as unknown.
+
+Do not propose a refactoring plan until all 6 steps are complete.
+
+## Output
+
+A refactoring plan containing:
+- **Callers to update:** the detected functions and files that call the target, with update requirements. Dynamic behavior and framework configuration can leave gaps, so say the list may be incomplete
+- **Tests to change:** test files covering the refactored code, with required modifications
+- **Dead code:** what `get_unused_code` calls Dead can be deleted during the refactor; check anything Possibly unused before deleting it
+- **High-risk paths:** downstream modules with wide blast radius or high complexity scores
+- **Naming conflicts:** existing functions whose names would conflict with the refactored version

package/{skills → npx-skills}/review/SKILL.md

@@ -1,16 +1,15 @@
 ---
 name: review
 prompt-name: review-with-pharaoh
-description: "The definitive code review, for any codebase. 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, always branch-aware."
-version: 0.5.1
+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
-user-invocable: true
 metadata: {"emoji": "☥", "tags": ["code-review", "pull-request", "architecture", "pharaoh", "multi-agent", "adversarial-review", "cross-model", "regression-risk", "spec-alignment"]}
 ---
 
 # Review with Pharaoh
 
-The definitive code review, for any codebase. Architecture-aware, branch-aware, multi-agent, adversarial. Five phases that combine Pharaoh's knowledge graph with parallel specialized reviewers and an independent second opinion from a different model. Every phase works without Pharaoh too; Pharaoh makes the architecture picture exact and cheap where it maps the repo.
+Architecture-aware, branch-aware, multi-agent, adversarial code review. Five phases that combine Pharaoh's knowledge graph with parallel specialized reviewers and an independent second opinion from a different model. Every phase works without Pharaoh too; Pharaoh makes the architecture picture exact and cheap where it maps the repo.
 
 A review always reaches a verdict. When a phase needs something your client doesn't have (Pharaoh, a shell, subagents, a second model), it says how to carry on without it: do that, and name what was missing in the review output. Ask the user only when someone is there to answer.
 
@@ -36,7 +35,7 @@ No shell, or no git? Review the diff you were given (a file, a pasted patch, a p
    git log --oneline -1                   # latest commit
    ```
 
-2. Determine the base (where this branch diverged from the branch it merges into). The target is the first of these that resolves:
+2. Determine the base (where this branch diverged from the branch it merges into). The target is the first of these that resolves (`gh pr view` asks GitHub, with your own gh login, for the open PR's target branch):
    ```bash
    TARGET=$(gh pr view --json baseRefName --jq '"origin/" + .baseRefName' 2>/dev/null)   # the open PR's target branch
    [ -n "$TARGET" ] || TARGET=$(git symbolic-ref -q --short refs/remotes/origin/HEAD)    # the default branch, set by git clone

package/{skills → npx-skills}/tdd/SKILL.md

@@ -2,7 +2,8 @@
 name: tdd
 prompt-name: test-driven-development
 description: "Test-driven development discipline. Write the failing test first, watch it fail, write minimal code to pass, refactor. No production code without a failing test. No exceptions without explicit permission. Covers red-green-refactor cycle, common rationalizations, and when to start over."
-version: 0.2.0
+license: MIT. Adapted from obra/superpowers, Copyright (c) 2025 Jesse Vincent; see NOTICE in @pharaoh-so/mcp
+version: 0.2.1
 homepage: https://pharaoh.so
 user-invocable: true
 metadata: {"emoji": "☥", "tags": ["tdd", "testing", "red-green-refactor", "quality", "discipline"]}

package/{skills → npx-skills}/verify/SKILL.md

@@ -2,7 +2,8 @@
 name: verify
 prompt-name: verification
 description: "Evidence before assertions. Run verification commands and confirm output before claiming work is complete, fixed, or passing. No 'should work now' — run the command, read the output, then claim the result. Covers tests, builds, linting, agent delegation, and requirement checklists."
-version: 0.2.0
+license: MIT. Adapted from obra/superpowers, Copyright (c) 2025 Jesse Vincent; see NOTICE in @pharaoh-so/mcp
+version: 0.2.1
 homepage: https://pharaoh.so
 user-invocable: true
 metadata: {"emoji": "☥", "tags": ["verification", "quality", "completion", "evidence", "discipline"]}

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@pharaoh-so/mcp",
 	"mcpName": "so.pharaoh/pharaoh",
-	"version": "0.3.54",
-	"description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
+	"version": "0.3.56",
+	"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",
 	"types": "./dist/index.d.ts",
@@ -17,16 +17,18 @@
 	},
 	"files": [
 		"dist",
-		"skills",
+		"npx-skills",
 		"commands",
 		"hooks",
+		"project-memory",
 		".claude-plugin",
 		".mcp.json",
 		"inspect-tools.json",
 		"trace-app.html",
 		"README.md",
 		"CHANGELOG.md",
-		"LICENSE"
+		"LICENSE",
+		"NOTICE"
 	],
 	"keywords": [
 		"mcp",

package/project-memory/bundle.mjs

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import {
+	lstatSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	realpathSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join, relative } from "node:path";
+
+const LIMIT = 256 * 1024;
+export const MEMORY_RUNTIME_FILES = [
+	"execute-turn.mjs",
+	"hook-config.mjs",
+	"hook-events.mjs",
+	"local.mjs",
+	"memory-api.mjs",
+	"pharaoh-memory-hook.mjs",
+	"pharaoh-memory.mjs",
+	"user-target.mjs",
+	"runtime/credentials.js",
+	"runtime/package.json",
+	"runtime/refresh.js",
+];
+
+function digest(files) {
+	return createHash("sha256").update(JSON.stringify(files)).digest("hex");
+}
+
+export function privateMemoryPath(path, directory) {
+	const stat = lstatSync(path);
+	if (
+		(directory ? !stat.isDirectory() : !stat.isFile()) ||
+		stat.uid !== process.getuid?.() ||
+		(stat.mode & 0o077) !== 0
+	) {
+		throw new Error("Project memory needs a regular owner-private bundle path.");
+	}
+	return stat;
+}
+
+/** Read only the executable closure from the installed npm package. */
+export function packagedMemoryBundle(packageRoot = new URL("../", import.meta.url)) {
+	const files = MEMORY_RUNTIME_FILES.map((name) => {
+		let bytes;
+		if (name === "runtime/package.json") {
+			bytes = Buffer.from('{"type":"module"}\n');
+		} else {
+			const location = name.startsWith("runtime/")
+				? new URL(`dist/${name.slice(8)}`, packageRoot)
+				: new URL(`project-memory/${name}`, packageRoot);
+			try {
+				bytes = readFileSync(location);
+			} catch {
+				throw new Error("The Pharaoh package is missing its project memory runtime.");
+			}
+			if (name === "runtime/refresh.js" && !bytes.includes("function originBoundRefresh(")) {
+				throw new Error("The packaged refresh helper is incompatible with project memory.");
+			}
+		}
+		return [name, bytes.toString("base64")];
+	});
+	const sha256 = digest(files);
+	if (Buffer.byteLength(JSON.stringify(files)) >= LIMIT)
+		throw new Error("Project memory bundle is oversized.");
+	return { sha256, files };
+}
+
+export function installMemoryBundle(root, target, bundle) {
+	// Check the nearest existing parent before creating anything, including a
+	// requested path whose parent is a symlink into the checkout.
+	let parent = root;
+	for (;;) {
+		try {
+			const resolved = join(realpathSync(parent), relative(parent, root));
+			const within = target ? relative(target, resolved) : "..";
+			if (!within || (!within.startsWith("../") && within !== "..")) {
+				throw new Error("Install the project memory bundle outside the enrolled checkout.");
+			}
+			break;
+		} catch (error) {
+			if (error.code !== "ENOENT" || parent === dirname(parent)) throw error;
+			parent = dirname(parent);
+		}
+	}
+	mkdirSync(root, { recursive: true, mode: 0o700 });
+	privateMemoryPath(root, true);
+	const destination = join(realpathSync(root), bundle.sha256);
+	function verifyExisting() {
+		try {
+			privateMemoryPath(destination, true);
+		} catch (error) {
+			if (error.code === "ENOENT") return false;
+			throw error;
+		}
+		privateMemoryPath(join(destination, "runtime"), true);
+		for (const [name, content] of bundle.files) {
+			const path = join(destination, name);
+			if (
+				privateMemoryPath(path, false).size > LIMIT ||
+				readFileSync(path).toString("base64") !== content
+			) {
+				throw new Error(
+					"Installed project memory bundle was modified. Remove it before reinstalling.",
+				);
+			}
+		}
+		return true;
+	}
+	if (verifyExisting()) return destination;
+	const staging = mkdtempSync(join(root, ".memory-client-"));
+	try {
+		mkdirSync(join(staging, "runtime"), { mode: 0o700 });
+		for (const [name, content] of bundle.files) {
+			writeFileSync(join(staging, name), Buffer.from(content, "base64"), {
+				flag: "wx",
+				mode: 0o600,
+			});
+		}
+		try {
+			renameSync(staging, destination);
+		} catch (error) {
+			if (!["EEXIST", "ENOTEMPTY"].includes(error.code) || !verifyExisting()) throw error;
+		}
+	} finally {
+		rmSync(staging, { recursive: true, force: true });
+	}
+	return destination;
+}
+
+/** Derive a hook executable path from the reviewed installation, never from cwd. */
+export function bundledHook(root) {
+	return join(root, "pharaoh-memory-hook.mjs");
+}

package/project-memory/execute-turn.mjs

@@ -0,0 +1,240 @@
+import { git, visibleGitIndex } from "./local.mjs";
+import { PilotError, requestMemory } from "./memory-api.mjs";
+
+const SHA = /^[a-f0-9]{40}$/i;
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+const TERMS = /^[\p{L}\p{N}._+@ $/#:-]+$/u;
+const SECRET =
+	/\b(?:[a-f0-9]{32,}|ph(?:at|rt)_[a-z0-9_-]{12,})\b|:\/\/|\b[\w.-]+@[a-z0-9.-]+\.[a-z]{2,}\b/i;
+const UNSAFE_RECAP =
+	/\x60{3}|~~~|-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:(?:phat|phrt|pss|dev)_[a-f0-9]{64}|gh[pousr]_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{16,}|sk-[A-Za-z0-9_-]{20,}|(?:AKIA|ASIA)[A-Z0-9]{16})\b|\bBearer[ \t]+[A-Za-z0-9_.~+/=-]{12,}|\b(?:password|secret|api[_ -]?key|access[_ -]?token)\s*[:=]\s*\S{6,}|(?:^|\n)\s*(?:assistant|user|system|tool)\s*:/i;
+const REF_PATH = /^[\p{L}\p{N}._+@ -]+(?:\/[\p{L}\p{N}._+@ -]+)*$/u;
+
+function hasKeys(input, allowed) {
+	return (
+		input &&
+		typeof input === "object" &&
+		!Array.isArray(input) &&
+		Object.keys(input).every((key) => allowed.includes(key))
+	);
+}
+
+function normalizeTerm(value) {
+	if (typeof value !== "string" || value.length > 100 || /[\r\n]/.test(value)) return;
+	const term = value.replace(/^[ \t]+|[ \t]+$/g, "").replace(/[ \t]+/g, " ");
+	if (
+		term &&
+		term.split(" ").length <= 8 &&
+		TERMS.test(term) &&
+		!SECRET.test(term) &&
+		!UNSAFE_RECAP.test(term)
+	) {
+		return term;
+	}
+}
+
+function recallTerms(input) {
+	if (
+		hasKeys(input, ["terms"]) &&
+		Array.isArray(input.terms) &&
+		input.terms.length >= 1 &&
+		input.terms.length <= 5
+	) {
+		const terms = input.terms.map(normalizeTerm);
+		if (terms.every(Boolean)) return [...new Set(terms)];
+	}
+	throw new PilotError(
+		"Use JSON with 1–5 short, non-sensitive keywords, phrases, paths, or symbols in terms.",
+	);
+}
+
+function validRef(ref) {
+	return (
+		hasKeys(ref, ["path", "symbol", "pullRequest", "commit"]) &&
+		Object.keys(ref).length > 0 &&
+		(ref.path === undefined ||
+			(typeof ref.path === "string" &&
+				ref.path.length <= 180 &&
+				REF_PATH.test(ref.path) &&
+				!ref.path.split("/").some((part) => part === "." || part === "..") &&
+				!UNSAFE_RECAP.test(ref.path))) &&
+		(ref.symbol === undefined ||
+			(typeof ref.symbol === "string" &&
+				ref.symbol.length <= 100 &&
+				/^[\w$][\w$.#:-]*$/u.test(ref.symbol) &&
+				!UNSAFE_RECAP.test(ref.symbol))) &&
+		(ref.pullRequest === undefined || (Number.isInteger(ref.pullRequest) && ref.pullRequest > 0)) &&
+		(ref.commit === undefined || (typeof ref.commit === "string" && SHA.test(ref.commit)))
+	);
+}
+
+function validRecap(text, limit) {
+	return (
+		typeof text === "string" &&
+		text.trim().length > 0 &&
+		text.length <= limit &&
+		!UNSAFE_RECAP.test(text)
+	);
+}
+
+function captureDraft(input) {
+	if (
+		!hasKeys(input, ["kind", "summary", "detail", "refs", "verification"]) ||
+		!["observation", "lesson", "decision"].includes(input.kind) ||
+		!validRecap(input.summary, 500) ||
+		(input.detail !== undefined && !validRecap(input.detail, 1000)) ||
+		(input.verification !== undefined && !validRecap(input.verification, 300)) ||
+		(input.refs !== undefined &&
+			(!Array.isArray(input.refs) || input.refs.length > 6 || !input.refs.every(validRef)))
+	) {
+		throw new PilotError(
+			"Use a bounded JSON candidate with kind, summary, and optional detail, refs, and verification.",
+		);
+	}
+	return input;
+}
+
+function worktreeEvidence(root, rev) {
+	try {
+		if (git(root, "status", "--porcelain=v1", "--untracked-files=normal")) return true;
+		return !git(
+			root,
+			"for-each-ref",
+			`--contains=${rev}`,
+			"--count=1",
+			"--format=%(objectname)",
+			"refs/remotes/origin/",
+		);
+	} catch {
+		return true;
+	}
+}
+
+function pathAtRevision(root, rev, path) {
+	try {
+		git(root, "cat-file", "-e", `${rev}:${path}`);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function citeRefs(root, rev, refs) {
+	const unverified = worktreeEvidence(root, rev);
+	const needsFullIndex = refs.some((ref) => !ref.commit && !ref.path && ref.symbol);
+	const fullIndex = !unverified && needsFullIndex && visibleGitIndex(root);
+	return Promise.all(
+		refs.map(async (ref) => {
+			if (ref.commit || !(ref.path || ref.symbol)) return ref;
+			const visible =
+				!unverified && (await (ref.path ? visibleGitIndex(root, ref.path) : fullIndex));
+			if (!visible || (ref.path && !pathAtRevision(root, rev, ref.path)))
+				return { ...ref, provenance: "worktree" };
+			return ref;
+		}),
+	);
+}
+
+function validPair(id, version) {
+	return (
+		typeof id === "string" &&
+		UUID.test(id) &&
+		Number.isInteger(version) &&
+		version > 0 &&
+		version <= 1_000_000
+	);
+}
+
+export async function executeTurn(
+	operation,
+	token,
+	{ target, store, read, request = requestMemory, compact = false },
+) {
+	const change = (from, to) => {
+		const state = store.transition(token, target, from, to);
+		if (!state) throw new PilotError("This project memory turn is stale or not eligible.");
+		return state;
+	};
+	if (operation === "nothing-material") {
+		change(["nudged"], "acknowledged");
+		return { acknowledged: true };
+	}
+	if (operation === "receipt") {
+		const receipt = store.readReceipt(token, target);
+		if (!receipt) throw new PilotError("No confirmed capture receipt is available for this turn.");
+		return receipt;
+	}
+	let input;
+	try {
+		input = await read();
+	} catch {
+		throw new PilotError("Provide a bounded JSON object on standard input.");
+	}
+	if (operation === "expand") {
+		if (!hasKeys(input, ["id", "version"]) || !validPair(input.id, input.version))
+			throw new PilotError("Provide the exact record ID and version from the compact packet.");
+		const expanding = store.beginExpand(token, target, input.id, input.version);
+		if (!expanding)
+			throw new PilotError(
+				"This record version is outside the active packet, the turn is stale, or its two expansions are used.",
+			);
+		let result;
+		try {
+			result = await request(operation, {
+				repo: expanding.repo,
+				id: input.id,
+				version: input.version,
+			});
+		} catch (error) {
+			store.finishExpand(token, target, expanding.attempt);
+			throw error;
+		}
+		if (!store.finishExpand(token, target, expanding.attempt))
+			throw new PilotError("This project memory turn ended before its expansion returned.");
+		return result;
+	}
+	const recall = operation === "recall";
+	const draft = recall ? { terms: recallTerms(input) } : captureDraft(input);
+	if (JSON.stringify(draft).includes(token))
+		throw new PilotError("The local turn token cannot appear in a memory request.");
+	const gitRev = recall ? null : git(target.root, "rev-parse", "HEAD");
+	if (!recall && !SHA.test(gitRev))
+		throw new PilotError("The checkout has no full Git commit to cite.");
+	const refs = !recall && draft.refs ? await citeRefs(target.root, gitRev, draft.refs) : undefined;
+	const running = recall ? "recalling" : "capturing";
+	const state = change([recall ? "pending" : "nudged"], running);
+	const payload = {
+		repo: state.repo,
+		...draft,
+		...(recall && compact && { format: "compact-v1" }),
+		...(!recall && { gitRev, client: state.client, operationId: state.operationId }),
+		...(refs && { refs }),
+	};
+	let result;
+	try {
+		result = await request(operation, payload);
+	} catch (error) {
+		store.transition(token, target, [running], "failed");
+		throw error;
+	}
+	if (recall) {
+		const pairs =
+			result?.format === "compact-v1" ? result.records.map(({ id, version }) => [id, version]) : [];
+		if (
+			pairs.length > 5 ||
+			!pairs.every(([id, version]) => validPair(id, version)) ||
+			!store.finishRecall(token, target, pairs)
+		) {
+			throw new PilotError("This project memory turn ended before recall returned.");
+		}
+	} else {
+		try {
+			store.saveReceipt(token, target, result.record);
+			store.transition(token, target, [running], "acknowledged");
+		} catch {
+			// The service already committed. Local disk or a stale turn cannot turn a confirmed record into a failed write.
+			return { ...result, localReceiptUnavailable: true };
+		}
+	}
+	return result;
+}