@litterthanlit/hypher-cli 0.1.0

package/src/manifest.mjs

@@ -0,0 +1,126 @@
+/**
+ * The install manifest: every change `init` made, so `uninstall` removes
+ * exactly that. A file nothing else touched since goes back to its original
+ * bytes. A file changed since keeps those changes and loses only Hypher's
+ * entries. A backup is never restored over later edits.
+ */
+import { mkdirSync, rmdirSync, readdirSync } from "node:fs";
+import { paths } from "./env.mjs";
+import { exists, readBytes, readJson, removeFile, sha256, writeAtomic, writeJson } from "./fsutil.mjs";
+
+/**
+ * @typedef {object} FileEntry
+ * @property {"file"} kind
+ * @property {string} path
+ * @property {string} role What the change is, for the printout and for the cleaner.
+ * @property {string | null} originalBase64 Bytes before the first install, or null when the file did not exist.
+ * @property {string} afterSha256 Hash right after the latest install.
+ * @property {string[]} createdDirs Directories init created for this file, deepest first.
+ */
+
+export function readManifest(env = process.env) {
+  const manifest = readJson(paths(env).manifest);
+  if (manifest && Array.isArray(manifest.entries)) return manifest;
+  return { version: 1, entries: [] };
+}
+
+export function writeManifest(manifest, env = process.env) {
+  writeJson(paths(env).manifest, manifest, { mode: 0o600 });
+}
+
+/** Directories that `mkdir -p` would create for `dir`, deepest first. */
+export function missingDirs(dir) {
+  const missing = [];
+  let current = dir;
+  while (current && !exists(current)) {
+    missing.push(current);
+    const parent = current.replace(/\/[^/]+\/?$/, "");
+    if (parent === current || !parent) break;
+    current = parent;
+  }
+  return missing;
+}
+
+/**
+ * Write `next` to `file` and record it. The first install keeps the original
+ * bytes; later installs only move the after-hash.
+ * @param {{ entries: any[] }} manifest
+ * @param {string} file
+ * @param {string | Buffer} next
+ * @param {string} role
+ * @returns {"added" | "unchanged" | "updated"}
+ */
+export function writeTrackedFile(manifest, file, next, role) {
+  const before = readBytes(file);
+  const bytes = Buffer.isBuffer(next) ? next : Buffer.from(next, "utf8");
+  const existing = manifest.entries.find((entry) => entry.kind === "file" && entry.path === file);
+  if (before && before.equals(bytes)) {
+    if (existing) existing.afterSha256 = sha256(bytes);
+    return "unchanged";
+  }
+  const dir = file.replace(/\/[^/]+$/, "");
+  const createdDirs = missingDirs(dir);
+  mkdirSync(dir, { recursive: true });
+  writeAtomic(file, bytes);
+  if (existing) {
+    existing.afterSha256 = sha256(bytes);
+    return "updated";
+  }
+  manifest.entries.push({
+    kind: "file",
+    path: file,
+    role,
+    originalBase64: before ? before.toString("base64") : null,
+    afterSha256: sha256(bytes),
+    createdDirs,
+  });
+  return "added";
+}
+
+export function recordEntry(manifest, entry) {
+  const same = manifest.entries.findIndex((item) => item.kind === entry.kind && item.id === entry.id);
+  if (same >= 0) manifest.entries[same] = { ...manifest.entries[same], ...entry };
+  else manifest.entries.push(entry);
+}
+
+function removeEmptyDirs(dirs) {
+  for (const dir of dirs ?? []) {
+    try {
+      if (readdirSync(dir).length === 0) rmdirSync(dir);
+    } catch {
+      // Gone already, or not empty: leave it.
+    }
+  }
+}
+
+/**
+ * Undo one tracked file.
+ * @param {FileEntry} entry
+ * @param {(text: string) => string | null} clean Removes Hypher's entries from edited content; null deletes nothing.
+ * @returns {"restored" | "removed" | "cleaned" | "missing"}
+ */
+export function undoTrackedFile(entry, clean) {
+  const current = readBytes(entry.path);
+  if (!current) {
+    removeEmptyDirs(entry.createdDirs);
+    return "missing";
+  }
+  if (sha256(current) === entry.afterSha256) {
+    if (entry.originalBase64 === null) {
+      removeFile(entry.path);
+      removeEmptyDirs(entry.createdDirs);
+      return "removed";
+    }
+    writeAtomic(entry.path, Buffer.from(entry.originalBase64, "base64"));
+    return "restored";
+  }
+  const cleaned = clean(current.toString("utf8"));
+  // A file init created, with nothing left once Hypher's entries are out, goes away.
+  if (cleaned === "" && entry.originalBase64 === null) {
+    removeFile(entry.path);
+    removeEmptyDirs(entry.createdDirs);
+    return "removed";
+  }
+  if (cleaned !== null && cleaned !== current.toString("utf8")) writeAtomic(entry.path, cleaned);
+  return "cleaned";
+}

package/src/outbox.mjs

@@ -0,0 +1,103 @@
+/**
+ * The outbox: a durable queue of checkpoints waiting to upload. It is not a
+ * store. Each item is dropped once Hypher accepts it; a newer checkpoint for
+ * the same repository and branch replaces an unsent older one but keeps its
+ * queue time, so the five-minute upload rule still fires.
+ */
+import { mkdirSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { paths } from "./env.mjs";
+import { readJson, removeFile, writeJson } from "./fsutil.mjs";
+import { HypherUnavailable } from "./api.mjs";
+
+export const FLUSH_AGE_MS = 5 * 60_000;
+const MAX_ATTEMPTS = 20;
+
+function dir(env) {
+  return paths(env).outboxDir;
+}
+
+/** @returns {{ file: string, item: any }[]} oldest first */
+export function listOutbox(env = process.env) {
+  let names = [];
+  try {
+    names = readdirSync(dir(env)).filter((name) => name.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  return names
+    .map((name) => ({ file: path.join(dir(env), name), item: readJson(path.join(dir(env), name)) }))
+    .filter((entry) => entry.item && typeof entry.item === "object")
+    .sort((a, b) => a.item.queuedAt - b.item.queuedAt || a.file.localeCompare(b.file));
+}
+
+/**
+ * @param {{ kind: "checkpoint", key: string, body: object }} input
+ * @param {{ env?: NodeJS.ProcessEnv, now?: number }} [options]
+ */
+export function enqueue(input, { env = process.env, now = Date.now() } = {}) {
+  mkdirSync(dir(env), { recursive: true });
+  let queuedAt = now;
+  for (const entry of listOutbox(env)) {
+    if (entry.item.kind === input.kind && entry.item.key === input.key) {
+      queuedAt = Math.min(queuedAt, entry.item.queuedAt);
+      removeFile(entry.file);
+    }
+  }
+  const id = `${now}-${randomBytes(4).toString("hex")}`;
+  const item = { id, kind: input.kind, key: input.key, body: input.body, queuedAt, attempts: 0, nextAttemptAt: 0 };
+  writeJson(path.join(dir(env), `${id}.json`), item, { mode: 0o600 });
+  return item;
+}
+
+export function oldestAgeMs(env = process.env, now = Date.now()) {
+  const [oldest] = listOutbox(env);
+  return oldest ? now - oldest.item.queuedAt : 0;
+}
+
+export function shouldFlush(env = process.env, now = Date.now()) {
+  return oldestAgeMs(env, now) >= FLUSH_AGE_MS;
+}
+
+/**
+ * Upload what is due. Stops at the first network failure; retries back off.
+ * @param {{ send: Function }} client
+ * @param {{ env?: NodeJS.ProcessEnv, now?: number, force?: boolean }} [options]
+ * @returns {Promise<{ sent: number, dropped: number, remaining: number, unavailable: boolean }>}
+ */
+export async function flushOutbox(client, { env = process.env, now = Date.now(), force = false } = {}) {
+  let sent = 0;
+  let dropped = 0;
+  let unavailable = false;
+  for (const { file, item } of listOutbox(env)) {
+    if (!force && item.nextAttemptAt > now) continue;
+    try {
+      const response = await client.send("POST", "/api/cli/checkpoints", { body: item.body });
+      if (response.ok) {
+        removeFile(file);
+        sent += 1;
+        continue;
+      }
+      if (response.status >= 400 && response.status < 500 && response.status !== 401 && response.status !== 429) {
+        // The server will never take this one; keep the queue moving.
+        removeFile(file);
+        dropped += 1;
+        continue;
+      }
+      throw new HypherUnavailable(client.base ?? "", `HTTP ${response.status}`);
+    } catch (error) {
+      if (!(error instanceof HypherUnavailable)) throw error;
+      unavailable = true;
+      const attempts = item.attempts + 1;
+      if (attempts >= MAX_ATTEMPTS) {
+        removeFile(file);
+        dropped += 1;
+      } else {
+        writeJson(file, { ...item, attempts, nextAttemptAt: now + Math.min(30 * 60_000, 15_000 * 2 ** attempts) }, { mode: 0o600 });
+      }
+      break;
+    }
+  }
+  return { sent, dropped, remaining: listOutbox(env).length, unavailable };
+}

package/src/repoBlock.mjs

@@ -0,0 +1,28 @@
+/**
+ * The repository's AGENTS.md: `init` and `link` add the marked Hypher block,
+ * creating the file if needed, unless the file already tells agents to use
+ * Hypher. It goes in the manifest, so `uninstall` takes out exactly it.
+ */
+import path from "node:path";
+import { readBytes } from "./fsutil.mjs";
+import { writeTrackedFile } from "./manifest.mjs";
+import { addBlock, agentsBlock, alreadyUsesHypher } from "./agentsBlock.mjs";
+
+/**
+ * @param {{ entries: any[] }} manifest
+ * @param {string} root the repository root
+ * @returns {{ file: string, change: "added" | "updated" | "unchanged" | "skipped" }}
+ */
+export function addRepositoryBlock(manifest, root) {
+  const file = path.join(root, "AGENTS.md");
+  const text = readBytes(file)?.toString("utf8") ?? "";
+  if (alreadyUsesHypher(text)) return { file, change: "skipped" };
+  return { file, change: writeTrackedFile(manifest, file, addBlock(text, agentsBlock("repository")), "agents-md") };
+}
+
+/** How to show a path: ./relative inside the working directory, ~/ under HOME, else absolute. */
+export function displayPath(file, { cwd, home }) {
+  if (cwd && (file === cwd || file.startsWith(`${cwd}/`))) return `./${path.relative(cwd, file)}`;
+  if (home && file.startsWith(`${home}/`)) return `~/${file.slice(home.length + 1)}`;
+  return file;
+}

package/src/secrets.mjs

@@ -0,0 +1,2 @@
+/** Secret shapes from hypher-web/shared/secretScan.ts, the same list the server enforces. */
+export { findSecret, findSecretInValue, SECRET_SHAPES } from "../vendor/secretScan.mjs";

package/src/session.mjs

@@ -0,0 +1,211 @@
+/**
+ * Resume and seal: the two things every door does. Hooks, `hypher resume`,
+ * `hypher seal`, and (later) the MCP tools all come through here.
+ */
+import { createClient, HypherRejected, HypherUnavailable } from "./api.mjs";
+import { linkFor } from "./config.mjs";
+import { canonicalJson, sha256 } from "./fsutil.mjs";
+import { flushOutbox } from "./outbox.mjs";
+import { handoffTreeOf, takeSnapshot } from "./snapshot.mjs";
+import { readWorktreeState, updateWorktreeState, withBranchState } from "./state.mjs";
+import { findSecretInValue } from "./secrets.mjs";
+import { keepHandoffTree, truthCheck } from "../vendor/hypher-git.mjs";
+import {
+  HYPHER_UNAVAILABLE_LINE,
+  renderHandoffNote,
+  renderNoHandoffNote,
+  renderUnlinkedLine,
+} from "../vendor/handoffNote.mjs";
+import { buildSealProposal } from "../vendor/handoffSeal.mjs";
+import { parseHandoffProposal } from "../vendor/structuredHandoff.mjs";
+
+export const ACK_HINT = "run `hypher ack`";
+const NOT_CONNECTED_LINE = "Hypher is not connected on this computer; starting without it. Run `hypher init` in a terminal.";
+
+/** The agent running this command, from its environment. */
+export function detectAgent(env, fallback) {
+  if (env.HYPHER_AGENT) return String(env.HYPHER_AGENT).slice(0, 40);
+  if (env.CLAUDECODE === "1" || env.CLAUDE_CODE_ENTRYPOINT) return "claude-code";
+  if (env.CODEX_SANDBOX || env.CODEX_MANAGED_BY_NPM || env.CODEX_THREAD_ID) return "codex";
+  return fallback ?? "agent";
+}
+
+function checkpointFrom(body) {
+  const checkpoint = body?.checkpoint;
+  if (!checkpoint || typeof checkpoint.capturedAt !== "number") return null;
+  return {
+    capturedAt: checkpoint.capturedAt,
+    source: String(checkpoint.source ?? "agent"),
+    event: String(checkpoint.event ?? "checkpoint"),
+    branch: String(checkpoint.branch ?? ""),
+    commit: String(checkpoint.commit ?? ""),
+    changedFiles: Array.isArray(checkpoint.changedFiles) ? checkpoint.changedFiles.map(String) : [],
+  };
+}
+
+/**
+ * Load the handoff for the repository at cwd, check it against the working
+ * tree, record a prepared receipt, and render the note. Never throws for a
+ * missing link, credential, or network; returns a status and one line instead.
+ * @param {{ env: NodeJS.ProcessEnv, cwd: string, destination: string, sessionId?: string, now?: number, timeoutMs?: number }} options
+ */
+export async function resumeHere({ env, cwd, destination, sessionId, now = Date.now(), timeoutMs = 2_500 }) {
+  const snapshot = takeSnapshot(cwd);
+  if (!snapshot) return { status: "not-git", note: "" };
+  if (!snapshot.repository) {
+    return { status: "no-remote", note: "Hypher: this repository has no GitHub remote, so Hypher has no note for it." };
+  }
+  const link = linkFor(snapshot.repository, env);
+  // A repository no human linked uploads nothing at all.
+  if (!link) return { status: "unlinked", note: renderUnlinkedLine(snapshot.repository), snapshot };
+  const client = createClient({ env, timeoutMs });
+  if (!client.apiKey) return { status: "not-connected", note: NOT_CONNECTED_LINE, snapshot };
+
+  let prepared;
+  let checkpoint = null;
+  try {
+    // A killed session's last checkpoint goes up first, so this note can name it.
+    const flushed = await flushOutbox(client, { env, now, force: true });
+    if (flushed.unavailable) return { status: "unavailable", note: HYPHER_UNAVAILABLE_LINE, snapshot };
+    const [resume, latest] = await Promise.all([
+      client.tool("prepare_handoff", { projectId: link.projectId, destination, currentRepo: snapshot.currentRepo }),
+      client.send("GET", `/api/cli/checkpoints?repository=${encodeURIComponent(snapshot.repository)}&branch=${encodeURIComponent(snapshot.branch)}`)
+        .then((response) => (response.ok ? response.json : null)),
+    ]);
+    prepared = resume.structured;
+    checkpoint = checkpointFrom(latest);
+  } catch (error) {
+    if (error instanceof HypherUnavailable) return { status: "unavailable", note: HYPHER_UNAVAILABLE_LINE, snapshot };
+    if (error instanceof HypherRejected) return { status: "rejected", note: `Hypher: ${error.message}`, snapshot };
+    throw error;
+  }
+
+  const base = {
+    repository: snapshot.repository,
+    projectId: link.projectId,
+    destination,
+    sessionId,
+    resumedAt: now,
+  };
+  if (prepared?.ok !== true) {
+    if (prepared?.code === "no-handoff") {
+      const shown = checkpoint && checkpoint.branch === snapshot.branch ? checkpoint : null;
+      updateWorktreeState(env, snapshot.root, (state) => withBranchState({ ...state, ...base, baseRevision: 0, proposal: null, receiptId: null, receiptRevision: null },
+        snapshot.branch, { sealTree: snapshot.tree }));
+      return { status: "no-handoff", note: renderNoHandoffNote({ repository: snapshot.repository, projectName: link.projectName, now, checkpoint: shown }), snapshot, checkpoint: shown };
+    }
+    return { status: "rejected", note: `Hypher: ${prepared?.error ?? "could not load the handoff"}. Run \`hypher doctor\`.`, snapshot };
+  }
+
+  const parsed = parseHandoffProposal(prepared.proposal, { allowPlaceholders: true });
+  if (!parsed.ok) return { status: "rejected", note: "Hypher returned a handoff this CLI cannot read. Update with `hypher init`.", snapshot };
+  const proposal = parsed.value;
+  const verdict = truthCheck(snapshot.root, proposal.repo);
+  const savedAt = typeof prepared.savedAt === "number" ? prepared.savedAt : undefined;
+  const shownCheckpoint = checkpoint && (!savedAt || checkpoint.capturedAt > savedAt) ? checkpoint : null;
+  const note = renderHandoffNote({
+    proposal,
+    revision: prepared.revision,
+    now,
+    from: prepared.sourceAgent,
+    savedAt,
+    verdict,
+    checkpoint: shownCheckpoint,
+    acknowledge: ACK_HINT,
+  });
+  updateWorktreeState(env, snapshot.root, (state) => withBranchState({
+    ...state,
+    ...base,
+    baseRevision: prepared.revision,
+    proposal,
+    receiptId: prepared.receiptId ?? null,
+    // A later save moves baseRevision; the receipt stays tied to the revision that was read.
+    receiptRevision: prepared.revision,
+  }, snapshot.branch, { sealTree: snapshot.tree }));
+  return {
+    status: "ready",
+    note,
+    verdict,
+    revision: prepared.revision,
+    receiptId: prepared.receiptId,
+    projectId: link.projectId,
+    checkpoint: shownCheckpoint,
+    snapshot,
+  };
+}
+
+/**
+ * Save a handoff from what the agent knows: decisions that changed and why,
+ * and the next action. Based on the revision this session was handed.
+ * @param {{ env: NodeJS.ProcessEnv, cwd: string, seal: object, agent: string, now?: number }} options
+ */
+export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
+  const snapshot = takeSnapshot(cwd);
+  if (!snapshot) return { ok: false, code: "not-git", message: "Run this inside a git repository." };
+  if (!snapshot.repository) return { ok: false, code: "no-remote", message: "This repository has no GitHub remote, so Hypher cannot save for it." };
+  const link = linkFor(snapshot.repository, env);
+  if (!link) return { ok: false, code: "unlinked", message: renderUnlinkedLine(snapshot.repository) };
+
+  // Agent text is scanned before anything is built or sent.
+  const secret = findSecretInValue(seal);
+  if (secret) {
+    return { ok: false, code: "secret", message: `Refused: ${secret.field} looks like ${secret.shape}. Nothing was sent. Remove it and seal again.` };
+  }
+  const state = readWorktreeState(env, snapshot.root);
+  if (!state || state.projectId !== link.projectId || typeof state.baseRevision !== "number") {
+    return { ok: false, code: "no-base", message: "Run `hypher resume` first, so this save is based on the handoff you read." };
+  }
+  const prior = state.proposal ? parseHandoffProposal(state.proposal, { allowPlaceholders: true }) : null;
+  const iso = new Date(now).toISOString().slice(0, 16).replace("T", " ");
+  const built = buildSealProposal({
+    prior: prior?.ok ? prior.value : null,
+    seal,
+    repo: snapshot.currentRepo,
+    sessionRef: `${agent} session on ${snapshot.branch}, ${iso} UTC`,
+  });
+  if (!built.ok) return { ok: false, code: "invalid", message: built.error };
+
+  const client = createClient({ env, timeoutMs: 10_000 });
+  if (!client.apiKey) return { ok: false, code: "not-connected", message: "This computer is not connected. Run `hypher init`." };
+  const request = {
+    kind: "handoff",
+    source: agent,
+    projectId: link.projectId,
+    proposal: built.proposal,
+    expectedBaseRevision: state.baseRevision,
+  };
+  // Same base and same request: same key, so a retry dedupes. A change that
+  // returns to earlier content has a newer base, so it is not a duplicate.
+  const idempotencyKey = `seal-${sha256(`${state.baseRevision}\n${canonicalJson(request)}`).slice(0, 40)}`;
+  let result;
+  try {
+    result = (await client.tool("post_agent_event", { ...request, idempotencyKey })).structured;
+  } catch (error) {
+    if (error instanceof HypherUnavailable) return { ok: false, code: "unavailable", message: "Hypher unavailable; nothing was saved. Run `hypher doctor`, then seal again." };
+    if (error instanceof HypherRejected) return { ok: false, code: "rejected", message: error.message };
+    throw error;
+  }
+  if (!result?.ok) {
+    if (result?.code === "stale-revision") {
+      return { ok: false, code: "stale", message: `Hypher has a newer handoff (revision ${result.headRevision}) than the one this session read (revision ${state.baseRevision}). Run \`hypher resume\`, read it, and seal again.` };
+    }
+    return { ok: false, code: result?.code ?? "rejected", message: `Hypher refused the handoff: ${result?.error ?? "unknown error"}` };
+  }
+  const tree = snapshot.tree;
+  if (tree) keepHandoffTree(snapshot.root, { branch: snapshot.branch, tree, commit: snapshot.commit });
+  updateWorktreeState(env, snapshot.root, (current) => withBranchState({
+    ...current,
+    baseRevision: result.revision,
+    proposal: built.proposal,
+    agent,
+  }, snapshot.branch, { sealTree: tree }));
+  return {
+    ok: true,
+    code: result.code,
+    revision: result.revision,
+    projectName: link.projectName,
+    message: `Saved handoff revision ${result.revision} for "${link.projectName}". Memory did not transfer code.`,
+  };
+}
+
+export { handoffTreeOf };

package/src/snapshot.mjs

@@ -0,0 +1,56 @@
+/**
+ * What this machine may say about a working tree: repository identity,
+ * branch, commit, dirty state, a tree hash, and file names. Never contents.
+ */
+import { git, repoIdentity, worktreeTreeHash } from "../vendor/hypher-git.mjs";
+
+/** Changed file names, one per file (untracked directories expanded), from `git status -z`. */
+export function changedFileNames(root) {
+  const out = git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { trim: false });
+  if (!out) return [];
+  const parts = out.split("\0");
+  const names = [];
+  for (let index = 0; index < parts.length; index += 1) {
+    const entry = parts[index];
+    if (entry.length < 4) continue;
+    names.push(entry.slice(3));
+    // A rename or copy is followed by its original path; the new name is enough.
+    if (entry[0] === "R" || entry[0] === "C") index += 1;
+  }
+  return names;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {null | { root: string, repository: string | null, branch: string, commit: string, dirty: boolean,
+ *   tree: string | null, changedFiles: string[], currentRepo: object }}
+ */
+export function takeSnapshot(cwd) {
+  const identity = repoIdentity(cwd);
+  if (!identity.root || !identity.commit || !identity.branch) return null;
+  const tree = worktreeTreeHash(cwd);
+  const changedFiles = identity.dirty ? changedFileNames(identity.root) : [];
+  const currentRepo = {
+    ...(identity.repository ? { repository: identity.repository } : {}),
+    branch: identity.branch,
+    commit: identity.commit,
+    dirty: identity.dirty,
+    ...(identity.dirty && tree ? { dirtyFingerprint: `tree:${tree}` } : {}),
+  };
+  return {
+    root: identity.root,
+    repository: identity.repository,
+    branch: identity.branch,
+    commit: identity.commit,
+    dirty: identity.dirty,
+    tree,
+    changedFiles,
+    currentRepo,
+  };
+}
+
+/** The tree a handoff recorded: its fingerprint when dirty, else its commit's tree. */
+export function handoffTreeOf(repo) {
+  if (typeof repo?.dirtyFingerprint === "string" && repo.dirtyFingerprint.startsWith("tree:")) return repo.dirtyFingerprint.slice(5);
+  return null;
+}

package/src/state.mjs

@@ -0,0 +1,53 @@
+/**
+ * Local session state. Per worktree: the revision this session was handed
+ * (every save is based on it), the receipt to acknowledge, and the proposal to
+ * carry forward. Per worktree and branch: the tree at the last seal and when
+ * Hypher last asked for one.
+ */
+import path from "node:path";
+import { paths } from "./env.mjs";
+import { readJson, sha256, writeJson } from "./fsutil.mjs";
+
+function worktreeFile(env, root) {
+  return path.join(paths(env).stateDir, "worktrees", `${sha256(String(root)).slice(0, 20)}.json`);
+}
+
+/**
+ * @typedef {object} WorktreeState
+ * @property {string} root
+ * @property {string} repository
+ * @property {string} projectId
+ * @property {number} baseRevision 0 when no handoff existed.
+ * @property {any} [proposal] The proposal at baseRevision.
+ * @property {string} [receiptId]
+ * @property {number} [receiptRevision] The revision the receipt was prepared for.
+ * @property {string} [destination]
+ * @property {string} [agent]
+ * @property {string} [sessionId]
+ * @property {number} [resumedAt]
+ * @property {Record<string, { sealTree?: string, askedAt?: number, askedTree?: string, blockedLast?: boolean }>} [branches]
+ */
+
+/** @returns {WorktreeState | null} */
+export function readWorktreeState(env, root) {
+  return root ? readJson(worktreeFile(env, root)) : null;
+}
+
+export function writeWorktreeState(env, root, state) {
+  writeJson(worktreeFile(env, root), { ...state, root }, { mode: 0o600 });
+}
+
+export function updateWorktreeState(env, root, patch) {
+  const current = readWorktreeState(env, root) ?? {};
+  const next = typeof patch === "function" ? patch(current) : { ...current, ...patch };
+  writeWorktreeState(env, root, next);
+  return next;
+}
+
+export function branchState(state, branch) {
+  return state?.branches?.[branch] ?? {};
+}
+
+export function withBranchState(state, branch, patch) {
+  return { ...state, branches: { ...(state.branches ?? {}), [branch]: { ...branchState(state, branch), ...patch } } };
+}

package/src/tools.mjs

@@ -0,0 +1,60 @@
+/**
+ * Find the agent tools on this machine. Only config commands (`--version`,
+ * `mcp add`, `mcp remove`) ever run; never a model turn.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { paths } from "./env.mjs";
+import { readJson } from "./fsutil.mjs";
+
+function run(bin, args, env, timeout = 15_000) {
+  const result = spawnSync(bin, args, { env, encoding: "utf8", timeout, stdio: ["ignore", "pipe", "pipe"] });
+  return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "", error: result.error };
+}
+
+function version(bin, env) {
+  const result = run(bin, ["--version"], env);
+  if (result.error || result.status !== 0) return null;
+  return result.stdout.match(/\d+\.\d+\.\d+[\w.-]*/)?.[0] ?? (result.stdout.trim().slice(0, 40) || "unknown");
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+export function detectTools(env = process.env) {
+  const p = paths(env);
+  const claude = version("claude", env);
+  const codex = version("codex", env);
+  const cursor = version("cursor", env) ?? (existsSync(path.join(p.home, ".cursor")) ? "installed" : null);
+  return {
+    claude: { found: Boolean(claude), version: claude },
+    codex: { found: Boolean(codex), version: codex },
+    cursor: { found: Boolean(cursor), version: cursor },
+  };
+}
+
+/** The user-scope `hypher` MCP entry Claude Code has, if any. */
+export function claudeHypherServer(env = process.env) {
+  const config = readJson(paths(env).claudeJson, {});
+  return config?.mcpServers?.hypher ?? null;
+}
+
+/** True when the entry is M0a's hosted sign-in (an http server), not the local bridge. */
+export function isSignInEntry(entry) {
+  return Boolean(entry && (entry.type === "http" || entry.type === "sse" || typeof entry.url === "string"));
+}
+
+export function claudeMcpAdd(env, shim) {
+  return run("claude", ["mcp", "add", "--scope", "user", "hypher", "--", shim, "mcp"], env);
+}
+
+export function claudeMcpRemove(env) {
+  return run("claude", ["mcp", "remove", "hypher", "--scope", "user"], env);
+}
+
+/** A project-level `hypher` entry in this repository overrides the user-level one inside it. */
+export function projectLevelHypherEntry(repoRoot) {
+  if (!repoRoot) return null;
+  const file = path.join(repoRoot, ".mcp.json");
+  const entry = readJson(file, {})?.mcpServers?.hypher;
+  return entry ? { file, entry } : null;
+}