@litterthanlit/hypher-cli 0.2.0 → 0.3.0

package/src/hookConfig.mjs

@@ -3,7 +3,8 @@
  * { hooks: { <Event>: [{ matcher?, hooks: [{ type: "command", command, timeout }] }] } }.
  * Hypher's entries carry a tag in their command, so they can be found again,
  * and are appended after the builder's own, so removing them never shifts
- * the position of anything the builder added.
+ * the position of anything the builder added. An event can have several specs
+ * (Claude Code's PostToolUse has one per tool matcher); each is one group.
  */
 
 /** @param {string} tag e.g. "hook claude-code" */
@@ -34,16 +35,19 @@ function withoutTagged(groups, tag) {
  * @param {{ event: string, matcher?: string, timeout: number }[]} specs
  * @param {string} shim absolute path of the `hypher` shim
  * @param {string} tag
+ * @param {(shim: string, tag: string, event: string) => string} [build] how a spec becomes a command; the repo kit's differs
  */
-export function mergeHooks(config, specs, shim, tag) {
+export function mergeHooks(config, specs, shim, tag, build = hookCommand) {
   const next = { ...config, hooks: { ...(config.hooks ?? {}) } };
+  // Hypher's old groups for an event all go first, so two specs of one event never remove each other.
+  for (const event of new Set(specs.map((spec) => spec.event))) {
+    next.hooks[event] = withoutTagged(next.hooks[event], tag);
+  }
   for (const spec of specs) {
-    const groups = withoutTagged(next.hooks[spec.event], tag);
-    groups.push({
+    next.hooks[spec.event].push({
       ...(spec.matcher ? { matcher: spec.matcher } : {}),
-      hooks: [{ type: "command", command: hookCommand(shim, tag, spec.event), timeout: spec.timeout }],
+      hooks: [{ type: "command", command: build(shim, tag, spec.event), timeout: spec.timeout }],
     });
-    next.hooks[spec.event] = groups;
   }
   return next;
 }
@@ -61,11 +65,17 @@ export function removeHooks(config, tag) {
   return next;
 }
 
-export function installedEvents(config, specs, tag) {
+/** The specs whose hook is in the file: a tagged command in a group of the spec's event (with the spec's matcher, when it has one). */
+export function installedSpecs(config, specs, tag) {
   return specs.filter((spec) =>
     (config?.hooks?.[spec.event] ?? []).some((group) =>
-      (group?.hooks ?? []).some((hook) => isTaggedCommand(hook?.command, tag))))
-    .map((spec) => spec.event);
+      (!spec.matcher || group?.matcher === spec.matcher)
+      && (group?.hooks ?? []).some((hook) => isTaggedCommand(hook?.command, tag))));
+}
+
+/** The events with at least one spec installed, each once, in the specs' order. */
+export function installedEvents(config, specs, tag) {
+  return [...new Set(installedSpecs(config, specs, tag).map((spec) => spec.event))];
 }
 
 /** Where each tagged hook sits: [event, groupIndex, hookIndex]. Codex keys its trust by this position. */

package/src/hooks/index.mjs

@@ -1,15 +1,28 @@
 /**
  * Agent hooks, for Claude Code and Codex alike (both send the same payload
  * shape). SessionStart injects the note (after startup, resume, clear, and
- * compact); Stop, PreCompact, and SessionEnd record a checkpoint; Stop asks
+ * compact; startup and resume move the seal baseline to the tree now, compact and clear keep it, so edits made
+ * before a compaction still make the next Stop ask for a seal); Stop, PreCompact, and SessionEnd record a checkpoint; Stop asks
  * once for a seal when the tree changed. Hooks never acknowledge, never block
  * twice in a row, and never block on Hypher being down. In a repository no
  * human linked they record and upload nothing.
+ *
+ * Claude Code alone (Codex parity is M4) also records a checkpoint after the note is read at SessionStart, and
+ * after a tool ran (PostToolUse: a file edit at most every 10 seconds, a command at most every 60), so a session
+ * killed in the middle of a turn still leaves one. PostToolUse reads only `cwd` and `tool_name` from its payload:
+ * the rest is the tool's input, which can be file contents, and is never looked at.
+ *
+ * In a Claude Code cloud session (cloud.mjs: `CLAUDE_CODE_REMOTE=true`, key from `HYPHER_API_KEY`) the container's
+ * disk dies with it, so every checkpoint also uploads at once (at most one a minute per repository and branch; `Stop`,
+ * `PreCompact`, and `SessionEnd` always try), a repository a human linked in Hypher is linked without a click, and the
+ * seal request names the shell command first. On a laptop none of that applies.
  */
 import { createClient } from "../api.mjs";
 import { linkFor } from "../config.mjs";
+import { cloudMode, findLink, uploadNow } from "../cloud.mjs";
 import { enqueue, flushOutbox, shouldFlush } from "../outbox.mjs";
 import { resumeHere } from "../session.mjs";
+import { claimCheckpoint, toolKind } from "../throttle.mjs";
 import { takeSnapshot } from "../snapshot.mjs";
 import { branchState, readWorktreeState, updateWorktreeState, withBranchState } from "../state.mjs";
 import { findSecret } from "../secrets.mjs";
@@ -18,11 +31,14 @@ export const ASK_AGAIN_AFTER_MS = 15 * 60_000;
 const HOOK_TIMEOUT_MS = 2_500;
 const MAX_FILES = 200;
 
-/** The linked snapshot at cwd, or null: not git, no remote, or not linked. */
-function linkedSnapshot(env, cwd) {
+/**
+ * The linked snapshot at cwd, or null: not git, no remote, or not linked. In a cloud session with no link file yet,
+ * a repository a human linked in Hypher is linked here first (see cloud.mjs).
+ */
+async function linkedSnapshot(env, cwd) {
   const snapshot = takeSnapshot(cwd);
   if (!snapshot?.repository || !snapshot.tree) return null;
-  const link = linkFor(snapshot.repository, env);
+  const { link } = await findLink(env, snapshot.repository);
   return link ? { snapshot, link } : null;
 }
 
@@ -52,7 +68,7 @@ export function recordCheckpoint(env, snapshot, event, now = Date.now(), agent =
  * What the Stop hook asks for. The words are the same for every project, except that when the last resume found
  * the decision ledger on, IDs are named: a decision is replaced by its ID, and the lists are said to be added to.
  */
-function sealRequest(firstHandoff, ledgerOn = false) {
+function sealRequest(firstHandoff, ledgerOn = false, cloud = false) {
   const goal = firstHandoff ? ' --goal "<the goal>"' : "";
   const pairs = ledgerOn
     ? "Add one --decision/--why pair per changed decision (--replaces d-3 names the earlier decision it replaces, by the ID in the note), or none if no decision changed; --next is always needed. What you list is added to the ledger, never replaced: close finished work by listing it under completed (--completed \"…\"). Report only checks you ran (evidence, or --evidence \"<command>=<exit code>\")."
@@ -60,31 +76,59 @@ function sealRequest(firstHandoff, ledgerOn = false) {
   return [
     "Hypher: the working tree changed since the last handoff, and no one saved why.",
     "Before you stop, record the decisions that changed, the next action for the next agent, and the checks you ran with their exit codes:",
-    `call the \`seal\` tool of the hypher MCP server, or, only if that tool is not available, run \`hypher seal${goal} --decision "<a decision that changed>" --why "<why>" --next "<the next action>"\` in the terminal.`,
+    cloud
+      // A cloud session has no signed-in hypher MCP server, so the shell command comes first.
+      ? `run \`hypher seal${goal} --decision "<a decision that changed>" --why "<why>" --next "<the next action>"\` in the shell (a cloud session has no signed-in Hypher MCP server), or, only if that command is not available, call the \`seal\` tool of the hypher MCP server.`
+      : `call the \`seal\` tool of the hypher MCP server, or, only if that tool is not available, run \`hypher seal${goal} --decision "<a decision that changed>" --why "<why>" --next "<the next action>"\` in the terminal.`,
     firstHandoff ? "This is the first handoff here, so give the goal too." : "If the work moved on from the note's goal, give the new goal too (goal, or --goal \"…\").",
     pairs,
     "It sends only your text, file names, and commit identity. Hypher asks once; if you cannot save now, say so and stop.",
   ].join(" ");
 }
 
+/** The resume statuses whose one line is also shown to the person (`systemMessage`), not only given to the model. */
+const PERSON_SEES = new Set(["unavailable", "not-connected", "unlinked"]);
+
+/** The SessionStart checkpoint, from the snapshot the read already took. It never fails a session start. */
+async function recordStartCheckpoint(env, snapshot, agent) {
+  try {
+    if (!snapshot?.repository || !snapshot.tree || !linkFor(snapshot.repository, env)) return;
+    recordCheckpoint(env, snapshot, "SessionStart", Date.now(), agent);
+    // A container's disk dies with it, so the checkpoint leaves at once (at most once a minute).
+    if (cloudMode(env)) await uploadNow(env, snapshot);
+  } catch {
+    // The note is already read; a checkpoint that could not be written is not worth a failed start.
+  }
+}
+
 async function sessionStart(agent, env, input) {
   const result = await resumeHere({
     env,
     cwd: input.cwd || process.cwd(),
     destination: agent,
     sessionId: typeof input.session_id === "string" ? input.session_id : undefined,
+    // Claude Code and Codex send the same names. After `compact` or `clear` the work goes on, so the seal baseline stays.
+    source: typeof input.source === "string" ? input.source : undefined,
     timeoutMs: HOOK_TIMEOUT_MS,
   });
   if (result.status === "not-git" || !result.note) return null;
-  return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: result.note } };
+  // After the note is read and rendered, so the note never names its own checkpoint. Queued, not uploaded:
+  // the next session on this computer sends it.
+  if (agent === "claude-code") await recordStartCheckpoint(env, result.snapshot, agent);
+  const output = { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: result.note } };
+  // The person sees these three too: the model alone may never mention that Hypher is not there.
+  return PERSON_SEES.has(result.status) ? { systemMessage: result.note, ...output } : output;
 }
 
 async function stop(agent, env, input, now = Date.now()) {
-  const found = linkedSnapshot(env, input.cwd || process.cwd());
+  const found = await linkedSnapshot(env, input.cwd || process.cwd());
   if (!found) return null;
   const { snapshot } = found;
   recordCheckpoint(env, snapshot, "Stop", now, agent);
-  if (shouldFlush(env, now)) {
+  const cloud = cloudMode(env);
+  if (cloud) {
+    await uploadNow(env, snapshot, { always: true, now });
+  } else if (shouldFlush(env, now)) {
     await flushOutbox(createClient({ env, timeoutMs: HOOK_TIMEOUT_MS }), { env, now }).catch(() => null);
   }
 
@@ -103,14 +147,34 @@ async function stop(agent, env, input, now = Date.now()) {
   updateWorktreeState(env, snapshot.root, (current) => withBranchState(current, snapshot.branch, {
     askedAt: now, askedTree: snapshot.tree, blockedLast: true,
   }));
-  return { decision: "block", reason: sealRequest(!state.proposal, state.ledger?.on === true) };
+  return { decision: "block", reason: sealRequest(!state.proposal, state.ledger?.on === true, cloud) };
+}
+
+/**
+ * A tool just ran. Only Claude Code has this hook. The payload carries the tool's input, which can be file
+ * contents, so nothing but `cwd` and `tool_name` is read from it. A call inside its window answers from one
+ * small file, with no git call. Queued, not uploaded: a laptop's next session sends it.
+ */
+async function postToolUse(agent, env, input, now = Date.now()) {
+  if (agent !== "claude-code") return null;
+  const kind = toolKind(input.tool_name);
+  if (!kind) return null;
+  const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
+  if (!claimCheckpoint(env, cwd, kind, now)) return null;
+  const found = await linkedSnapshot(env, cwd);
+  if (!found) return null;
+  recordCheckpoint(env, found.snapshot, "PostToolUse", now, agent);
+  // In a cloud session the checkpoint leaves at once, at most once a minute; on a laptop the next session sends it.
+  if (cloudMode(env)) await uploadNow(env, found.snapshot, { now });
+  return null;
 }
 
 async function checkpointAndUpload(agent, env, input, event, now = Date.now()) {
-  const found = linkedSnapshot(env, input.cwd || process.cwd());
+  const found = await linkedSnapshot(env, input.cwd || process.cwd());
   if (!found) return null;
   recordCheckpoint(env, found.snapshot, event, now, agent);
-  await flushOutbox(createClient({ env, timeoutMs: HOOK_TIMEOUT_MS }), { env, now }).catch(() => null);
+  if (cloudMode(env)) await uploadNow(env, found.snapshot, { always: true, now });
+  else await flushOutbox(createClient({ env, timeoutMs: HOOK_TIMEOUT_MS }), { env, now }).catch(() => null);
   return null;
 }
 
@@ -129,6 +193,8 @@ export async function handleAgentHook(agent, event, input, env) {
       return await sessionStart(agent, env, input);
     case "Stop":
       return await stop(agent, env, input);
+    case "PostToolUse":
+      return await postToolUse(agent, env, input);
     case "PreCompact":
     case "SessionEnd":
       return await checkpointAndUpload(agent, env, input, event);

package/src/outbox.mjs

@@ -8,7 +8,7 @@ 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 { readJson, removeFile, sha256, writeJson } from "./fsutil.mjs";
 import { HypherUnavailable } from "./api.mjs";
 
 export const FLUSH_AGE_MS = 5 * 60_000;
@@ -51,6 +51,41 @@ export function enqueue(input, { env = process.env, now = Date.now() } = {}) {
   return item;
 }
 
+function uploadedFile(env, key) {
+  return path.join(paths(env).stateDir, "uploaded", `${sha256(String(key)).slice(0, 20)}.json`);
+}
+
+/** The newest checkpoint Hypher accepted for a key, kept so `hypher status` can say it was uploaded. Never throws. */
+function rememberUploaded(env, item, now) {
+  try {
+    const file = uploadedFile(env, item.key);
+    const before = readJson(file, null);
+    if (typeof before?.body?.capturedAt === "number" && before.body.capturedAt > item.body?.capturedAt) return;
+    writeJson(file, { key: item.key, uploadedAt: now, body: item.body }, { mode: 0o600 });
+  } catch {
+    // Only a convenience for `hypher status`.
+  }
+}
+
+/**
+ * The newest checkpoint on this computer for a repository and branch: waiting in the outbox, or the last one
+ * Hypher accepted. `null` when there is none.
+ * @returns {{ state: "queued" | "uploaded", body: any, queuedAt?: number, uploadedAt?: number } | null}
+ */
+export function newestCheckpoint(env, repository, branch) {
+  const key = `${String(repository).toLowerCase()}#${branch}`;
+  const queued = listOutbox(env)
+    .filter((entry) => entry.item.kind === "checkpoint" && entry.item.key === key)
+    .map((entry) => ({ state: "queued", body: entry.item.body, queuedAt: entry.item.queuedAt }))
+    .sort((a, b) => (b.body?.capturedAt ?? 0) - (a.body?.capturedAt ?? 0))[0];
+  const saved = readJson(uploadedFile(env, key), null);
+  const uploaded = typeof saved?.body?.capturedAt === "number"
+    ? { state: "uploaded", body: saved.body, uploadedAt: saved.uploadedAt }
+    : null;
+  if (queued && (!uploaded || (queued.body?.capturedAt ?? 0) >= uploaded.body.capturedAt)) return queued;
+  return uploaded ?? queued ?? null;
+}
+
 export function oldestAgeMs(env = process.env, now = Date.now()) {
   const [oldest] = listOutbox(env);
   return oldest ? now - oldest.item.queuedAt : 0;
@@ -75,6 +110,7 @@ export async function flushOutbox(client, { env = process.env, now = Date.now(),
     try {
       const response = await client.send("POST", "/api/cli/checkpoints", { body: item.body });
       if (response.ok) {
+        rememberUploaded(env, item, now);
         removeFile(file);
         sent += 1;
         continue;

package/src/repoKit.mjs

@@ -0,0 +1,275 @@
+/**
+ * The repo kit (M3 slice 5): what `hypher init --repo` writes into a repository so a Claude Code cloud session runs
+ * Hypher's hooks. A cloud session runs the repository's `.claude/settings.json` hooks, not the user's, and a fresh
+ * container has no `hypher`, so the kit is three files a person commits:
+ *
+ * - `.claude/settings.json`: Hypher's hooks (the same events as the laptop's), each running `hypher.sh <Event>`,
+ *   merged into whatever is there. They are found again by the script's path in their command.
+ * - `.claude/hooks/hypher.sh`: does nothing outside a cloud session, installs the exact CLI version that wrote it when
+ *   `hypher` is missing, says which variable to add when the key is missing, else runs `hypher hook claude-code`.
+ * - `AGENTS.md`: the marked block `init` writes today.
+ *
+ * `init --repo` never commits or pushes, and never writes `.mcp.json`: a project-level `hypher` entry overrides the
+ * user's own, and a container has no browser for the sign-in. What was there before is kept in the repository's git
+ * directory (never committed), so `uninstall --repo` can give a file back byte for byte; without that record (a fresh
+ * clone) it removes only Hypher's entries and deletes nothing it cannot prove it created.
+ */
+import { chmodSync, existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { removeBlock } from "./agentsBlock.mjs";
+import { CLAUDE_HOOKS } from "./claude.mjs";
+import { installedEvents, installedSpecs, mergeHooks, removeHooks } from "./hookConfig.mjs";
+import { readBytes, readJson, removeFile, writeAtomic, writeJson } from "./fsutil.mjs";
+import { undoTrackedFile, writeTrackedFile } from "./manifest.mjs";
+import { addRepositoryBlock } from "./repoBlock.mjs";
+import { git } from "../vendor/hypher-git.mjs";
+
+export const KIT_SCRIPT = ".claude/hooks/hypher.sh";
+export const KIT_SETTINGS = ".claude/settings.json";
+export const KIT_AGENTS = "AGENTS.md";
+/** What marks a hook command as Hypher's: the script it runs. */
+export const KIT_TAG = KIT_SCRIPT;
+const SCRIPT_MARKER = "`hypher init --repo`";
+/** SessionStart may install the CLI on a first run; the other hooks keep slice 3's timeouts. */
+export const KIT_SESSION_START_TIMEOUT = 120;
+
+export const REPO_HOOKS = CLAUDE_HOOKS.map((spec) => (spec.event === "SessionStart" ? { ...spec, timeout: KIT_SESSION_START_TIMEOUT } : spec));
+
+/** The command a settings entry runs. CLAUDE_PROJECT_DIR is the repository root; `.` covers a version that does not set it. */
+export function kitCommand(_shim, _tag, event) {
+  return `"\${CLAUDE_PROJECT_DIR:-.}/${KIT_SCRIPT}" ${event}`;
+}
+
+const VERSION_SHAPE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?$/;
+const PACKAGE = "@litterthanlit/hypher-cli";
+
+/** The script, pinned to one exact version. Never "latest": this file runs on every clone. */
+export function kitScript(version) {
+  if (!VERSION_SHAPE.test(String(version))) throw new Error(`not an exact version: ${version}`);
+  const pinned = `${PACKAGE}@${version}`;
+  return [
+    "#!/bin/sh",
+    `# Hypher project memory for Claude Code cloud sessions. Written by ${SCRIPT_MARKER}; removed by \`hypher uninstall --repo\`.`,
+    "# It does nothing outside a cloud session, so a laptop with Hypher's user-level hooks never fires twice.",
+    '[ "$CLAUDE_CODE_REMOTE" = "true" ] || exit 0',
+    'if [ -z "$HYPHER_API_KEY" ]; then',
+    '  [ "$1" = "SessionStart" ] && echo "Hypher: add HYPHER_API_KEY (a Hypher API key) to this cloud environment to turn on project memory. Nothing is sent without it."',
+    "  exit 0",
+    "fi",
+    "if ! command -v hypher >/dev/null 2>&1; then",
+    "  # The exact version that wrote this file: a floating tag would run new code on every clone.",
+    `  npm install -g --silent --no-audit --no-fund ${pinned} </dev/null >/dev/null 2>&1`,
+    "  if ! command -v hypher >/dev/null 2>&1; then",
+    `    [ "$1" = "SessionStart" ] && echo "Hypher: could not install ${pinned} (npm install failed); starting without Hypher."`,
+    "    exit 0",
+    "  fi",
+    "fi",
+    'exec hypher hook claude-code "$1"',
+    "",
+  ].join("\n");
+}
+
+/** The version a script pins, or null when it is not Hypher's script. */
+export function kitPinnedVersion(text) {
+  return String(text ?? "").match(/npm install [^\n]*@litterthanlit\/hypher-cli@([0-9A-Za-z.+-]+)/)?.[1] ?? null;
+}
+
+// ---------------------------------------------------------------- settings.json
+
+export function mergeRepoHooks(settings) {
+  return mergeHooks(settings, REPO_HOOKS, "", KIT_TAG, kitCommand);
+}
+
+export function removeRepoHooks(settings) {
+  return removeHooks(settings, KIT_TAG);
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/** True when every hook is there with exactly the command and timeout `init --repo` writes: nothing to change. */
+export function repoHooksCurrent(settings) {
+  return REPO_HOOKS.every((spec) =>
+    (settings?.hooks?.[spec.event] ?? []).some((group) =>
+      (group?.matcher ?? undefined) === (spec.matcher ?? undefined)
+      && (group?.hooks ?? []).some((hook) => hook?.type === "command" && hook.command === kitCommand("", KIT_TAG, spec.event) && hook.timeout === spec.timeout)));
+}
+
+/** The events with a Hypher repo hook, each once. */
+export function installedRepoEvents(settings) {
+  return installedEvents(settings, REPO_HOOKS, KIT_TAG);
+}
+
+/** The hooks the kit needs that are not in these settings, by event (and matcher for an event with two). */
+export function missingRepoHooks(settings) {
+  const present = new Set(installedSpecs(settings, REPO_HOOKS, KIT_TAG));
+  return REPO_HOOKS.filter((spec) => !present.has(spec)).map((spec) => (REPO_HOOKS.filter((other) => other.event === spec.event).length > 1 ? `${spec.event} (${spec.matcher})` : spec.event));
+}
+
+/** The indentation a JSON file uses, so a merge does not reformat the builder's file. */
+export function detectIndent(text) {
+  const match = String(text ?? "").match(/^([ \t]+)\S/m);
+  return match ? match[1] : "  ";
+}
+
+/** Render settings the way the original was written: its indentation, and whether it ended with a newline. */
+export function renderRepoSettings(value, original) {
+  const endsWithNewline = original === undefined || original === null || original === "" || /\n$/.test(original);
+  return `${JSON.stringify(value, null, detectIndent(original))}${endsWithNewline ? "\n" : ""}`;
+}
+
+/**
+ * Settings text without Hypher's repo hooks, keeping everything else and its formatting. `""` when nothing else is
+ * left and `created` says Hypher made the file (so it can be deleted); `null` when the text is not JSON we can
+ * rewrite.
+ */
+export function cleanRepoSettingsText(text, { created = false } = {}) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(parsed)) return null;
+  const cleaned = removeRepoHooks(parsed);
+  // Nothing of Hypher's in it: the text is not ours to reformat.
+  if (JSON.stringify(cleaned) === JSON.stringify(parsed)) return text;
+  if (Object.keys(cleaned).length === 0) return created ? "" : "{}\n";
+  return renderRepoSettings(cleaned, text);
+}
+
+// ---------------------------------------------------------------- the record of what was there
+
+/** Where the original bytes are kept: the repository's git directory, never committed or pushed. */
+export function kitRecordFile(root) {
+  const common = git(root, ["rev-parse", "--git-common-dir"]);
+  return common ? path.resolve(root, common, "hypher-repo-kit.json") : null;
+}
+
+function readRecord(file) {
+  const record = file ? readJson(file, null) : null;
+  return record && Array.isArray(record.entries) ? record : { version: 1, entries: [] };
+}
+
+function saveRecord(file, record) {
+  if (!file) return;
+  if (record.entries.length > 0) writeJson(file, record, { mode: 0o600 });
+  else removeFile(file);
+}
+
+// ---------------------------------------------------------------- install, uninstall, inspect
+
+/**
+ * Write the kit into the repository at `root`. Never commits, never pushes.
+ * @param {string} root
+ * @param {string} version the exact CLI version the script pins
+ * @returns {{ ok: true, changes: [string, string][], files: string[] } | { ok: false, error: string }}
+ */
+export function installRepoKit(root, version) {
+  const recordFile = kitRecordFile(root);
+  const record = readRecord(recordFile);
+  const changes = [];
+
+  const settingsFile = path.join(root, KIT_SETTINGS);
+  const original = readBytes(settingsFile)?.toString("utf8");
+  let settings = {};
+  if (original !== undefined && original.trim() !== "") {
+    try {
+      settings = JSON.parse(original);
+    } catch {
+      return { ok: false, error: `${KIT_SETTINGS} is not valid JSON, so Hypher left it alone. Fix it, then run \`hypher init --repo\` again.` };
+    }
+    if (!isPlainObject(settings)) return { ok: false, error: `${KIT_SETTINGS} is not a JSON object, so Hypher left it alone.` };
+  }
+  if (!repoHooksCurrent(settings)) {
+    const change = writeTrackedFile(record, settingsFile, renderRepoSettings(mergeRepoHooks(settings), original), "repo-claude-settings");
+    if (change !== "unchanged") changes.push([KIT_SETTINGS, `+ hooks ${installedRepoEvents(mergeRepoHooks(settings)).join(", ")}, each running ${KIT_SCRIPT}`]);
+  }
+
+  const scriptFile = path.join(root, KIT_SCRIPT);
+  const script = writeTrackedFile(record, scriptFile, kitScript(version), "repo-script");
+  try {
+    chmodSync(scriptFile, 0o755);
+  } catch {
+    // Not fatal; doctor says when the script is not executable.
+  }
+  if (script !== "unchanged") changes.push([KIT_SCRIPT, `${script === "added" ? "+" : "updated:"} ${PACKAGE}@${version} pinned, runs only in a cloud session`]);
+
+  const block = addRepositoryBlock(record, root);
+  if (block.change !== "unchanged" && block.change !== "skipped") changes.push([KIT_AGENTS, "+ Hypher block (resume first, save at the end)"]);
+
+  saveRecord(recordFile, record);
+  const files = [KIT_SETTINGS, KIT_SCRIPT, ...(existsSync(path.join(root, KIT_AGENTS)) ? [KIT_AGENTS] : [])];
+  return { ok: true, changes, files, agents: block.change };
+}
+
+/**
+ * Take the kit out. A file Hypher recorded, and nobody changed since, goes back byte for byte (or is deleted if Hypher
+ * created it). A file changed since keeps those changes and loses only Hypher's entries. With no record, only
+ * Hypher's entries come out and no file is deleted.
+ * @returns {string[]} what was done, one line each
+ */
+export function uninstallRepoKit(root) {
+  const recordFile = kitRecordFile(root);
+  const record = readRecord(recordFile);
+  const undone = [];
+  // The reverse of the install order, so a folder is empty by the time its last file is gone.
+  const targets = [
+    [KIT_AGENTS, () => removeBlock],
+    // Edited since, and not Hypher's to delete if it was there before: leave it.
+    [KIT_SCRIPT, (entry) => (text) => (entry?.originalBase64 === null && text.includes(SCRIPT_MARKER) ? "" : null)],
+    [KIT_SETTINGS, (entry) => (text) => cleanRepoSettingsText(text, { created: entry?.originalBase64 === null })],
+  ];
+  for (const [rel, cleaner] of targets) {
+    const file = path.join(root, rel);
+    const entry = record.entries.find((item) => item.kind === "file" && item.path === file);
+    const current = readBytes(file)?.toString("utf8");
+    if (entry) {
+      const result = undoTrackedFile(entry, cleaner(entry));
+      record.entries = record.entries.filter((item) => item !== entry);
+      undone.push(`${rel}: ${result === "cleaned" ? "kept your edits, removed Hypher's entries" : result}`);
+    } else if (current !== undefined) {
+      // Not recorded here (a fresh clone): take out Hypher's entries, delete nothing.
+      if (rel === KIT_SCRIPT) {
+        if (current.includes(SCRIPT_MARKER)) {
+          removeFile(file);
+          undone.push(`${rel}: removed`);
+        }
+        continue;
+      }
+      const cleaned = cleaner(null)(current);
+      if (cleaned !== null && cleaned !== current) {
+        writeAtomic(file, cleaned);
+        undone.push(`${rel}: removed Hypher's entries`);
+      }
+    }
+  }
+  saveRecord(recordFile, record);
+  return undone;
+}
+
+/**
+ * What a repository has of the kit, for `hypher doctor`.
+ * @returns {{ state: "none" | "present" | "partial", version: string | null, events: string[], problems: string[] }}
+ */
+export function inspectRepoKit(root) {
+  const scriptFile = path.join(root, KIT_SCRIPT);
+  const script = readBytes(scriptFile)?.toString("utf8");
+  const settings = readJson(path.join(root, KIT_SETTINGS), {}) ?? {};
+  const events = installedRepoEvents(settings);
+  if (script === undefined && events.length === 0) return { state: "none", version: null, events, problems: [] };
+  const problems = [];
+  if (script === undefined) problems.push(`${KIT_SCRIPT} is missing`);
+  else {
+    if (!script.includes(SCRIPT_MARKER)) problems.push(`${KIT_SCRIPT} is not Hypher's script`);
+    try {
+      if ((statSync(scriptFile).mode & 0o111) === 0) problems.push(`${KIT_SCRIPT} is not executable (run chmod +x, then commit it)`);
+    } catch {
+      // Gone between the read and the stat.
+    }
+  }
+  const missing = missingRepoHooks(settings);
+  if (missing.length) problems.push(`hooks missing in ${KIT_SETTINGS}: ${missing.join(", ")}`);
+  return { state: problems.length ? "partial" : "present", version: script === undefined ? null : kitPinnedVersion(script), events, problems };
+}