@litterthanlit/hypher-cli 0.2.0 → 0.3.0

package/README.md

@@ -3,7 +3,9 @@
 Pilot · not yet recorded. The bridge between coding agents and Hypher project memory.
 
 - `hypher init` connects this computer (one browser approval), installs a pinned copy under `~/.hypher/`, and adds Claude Code hooks and Codex hooks (Codex asks once to trust them: `/hooks`). It keeps M0a's `hypher` sign-in entry wherever it finds one.
-- `hypher doctor` checks each piece and prints the fix for anything red.
+- `hypher doctor` checks each piece and prints the fix for anything red. When Hypher is unreachable, or something between this computer and it answers instead (a proxy's `403 Host not in allowlist`, an HTML page, an empty body), it names the host it tried and the status and content type that came back, never the body.
+- An answer that is not Hypher's own JSON counts as Hypher being unavailable, not as Hypher saying no: a queued checkpoint stays in the outbox until it uploads, and the session starts with "Hypher unavailable" (built, released with 0.2.1; not recorded). When Hypher is unavailable, not connected, or the repository is not linked, the `SessionStart` hook also puts that one line in front of you (`systemMessage`), not only in front of the model.
+- **When checkpoints are written (0.2.1; built and rehearsed, not recorded).** In Claude Code a checkpoint (identity, tree hash, file names, never contents) is queued when a session starts, after the note is read; after a file edit (`Edit`, `Write`, `MultiEdit`, `NotebookEdit`), at most every 10 seconds; after a command (`Bash`), at most every 60 seconds; and at turn end, before compaction, and at exit as before. So a session killed mid-turn leaves a checkpoint at most about 10 seconds behind its last edit. The new `PostToolUse` hook reads only `cwd` and the tool's name, never the tool's input, and, on a laptop, does not touch the network; checkpoints upload when the next session starts here (in a Claude Code cloud session they upload as they go: see Cloud sessions below). `hypher status` prints the newest checkpoint of this worktree: its event, the clock time (local and UTC), its age, and whether it is still queued or uploaded. Re-run `npx @litterthanlit/hypher-cli@latest init` to add the hook to a 0.2.0 install. Codex is unchanged (no `PostToolUse` hook, no `SessionStart` checkpoint): that is M4. The note's `Last checkpoint:` line gives the age and the capture time in UTC, for example `2 min ago (14:22 UTC, 2026-11-02)`, in every note the CLI prints (built, released with 0.3.0; the server's own text has no clock time). A `SessionStart` with source `compact` or `clear` keeps the seal baseline, so edits made before a compaction still make the next `Stop` ask for a seal; `startup` and `resume` move it to the tree now, as before (built, released with 0.3.0; Claude Code and Codex send the same source names, so both hooks do this).
 - `hypher resume` prints the note for this repository; `hypher seal` saves a handoff. `hypher resume --full` prints every item the note cut ("N more"); with `--json` it adds the whole decision ledger under `ledger`.
 - `hypher seal --evidence "<command>=<exit code>"` (repeatable, split at the last `=`) reports a check you ran. Hypher binds each to the working tree at the save and labels it an agent report (only agent reports are accepted until hooks capture checks in Baton M3); the next note says whether that tree still matches. It never runs the command. Only the command text, exit code, tree hash, and time leave the machine, never output. Against a server that does not accept evidence yet, the handoff saves without it and says so.
 - `hypher mcp` is the bridge for any MCP client: `resume`, `seal`, and `acknowledge`, with no project id, revision, or key to fill in. It also fills the repository and branch into a bare `read_ledger` call.
@@ -12,6 +14,20 @@ Pilot · not yet recorded. The bridge between coding agents and Hypher project m
 - `init` also puts `~/.hypher/bin` on PATH with one marked block in your shell's startup file (`~/.zshenv` for zsh, `~/.bash_profile` or `~/.bashrc` for bash, a `conf.d` file for fish), so `hypher` runs by name in new terminals and in agents' shells. `--no-path` skips it; hooks and the MCP bridge use the full path either way.
 - Inside Codex's sandbox the Keychain and the network are blocked. Commands run there say so instead of reporting that this computer is not connected.
 
+## Cloud sessions: `hypher init --repo` (0.3.0; built and rehearsed, not recorded)
+
+A Claude Code cloud session runs the repository's `.claude/settings.json` hooks, not your user-level ones, and starts in a fresh container with no `hypher`. Run `hypher init --repo` on your laptop, inside the repository. It needs no sign-in, writes three files, and never commits or pushes; it prints what to commit.
+
+- `.claude/settings.json`: Hypher's hooks (`SessionStart`, `Stop`, `PreCompact`, `SessionEnd`, and the two `PostToolUse` entries), each running `.claude/hooks/hypher.sh <Event>`, merged after your own hooks and settings (a second run changes nothing). `SessionStart` has a 120-second timeout, for a first-run install.
+- `.claude/hooks/hypher.sh`: does nothing unless `CLAUDE_CODE_REMOTE=true`, so a laptop with the user-level hooks never fires twice; installs `@litterthanlit/hypher-cli` at the exact version that wrote it (never `latest`) if `hypher` is missing; prints one line naming `HYPHER_API_KEY` at session start if that variable is not set; otherwise runs `hypher hook claude-code <Event>`. It never prints the key.
+- `AGENTS.md`: the marked block `init` writes. No `.mcp.json` is written.
+
+**Commit** `.claude/settings.json`, `.claude/hooks/hypher.sh` (it must stay executable), and `AGENTS.md`. A committed hook runs a script at session start for anyone who clones, so Claude Code asks them to trust it: use it on your own repository first. **In the cloud environment** add `HYPHER_API_KEY`, a Hypher API key from Settings → API keys, named for that environment and revoked when you are done (it reaches your whole account). The environment must let `npm` reach the registry and `www.hypher.app`.
+
+In a cloud session (`CLAUDE_CODE_REMOTE=true`, key from `HYPHER_API_KEY`) the CLI also: links a repository a person linked in Settings → Integrations without a click, keeping the answer in the container (a repository nobody linked uploads nothing and gets one line saying so; Hypher never makes a project); uploads each checkpoint as it is made, at most once a minute per repository and branch, with the newest queued one winning, and always at `Stop`, `PreCompact`, and `SessionEnd`; and names `hypher seal` in the shell first in the `Stop` request, since a container has no signed-in MCP entry. A laptop behaves as before.
+
+`hypher doctor` inside the repository reports whether the kit is present and which version it pins. `hypher uninstall --repo` removes the kit and gives your files back as they were; plain `hypher uninstall` is unchanged. To move the pin, run `npx @litterthanlit/hypher-cli@latest init --repo` and commit the result. Details: `docs/doors/claude-code.md` in the repository.
+
 Only hashes, file names, repository and commit identity, and agent-written handoff text leave the machine. Never code, diffs, or transcripts.
 
 Canonical git helpers are vendored from `packages/hypher-git` (`node script/sync-hypher-git.mjs`). The note renderer, validators, secret scan, and the ledger's op checks, seal mapping, and local note are vendored from `hypher-web/shared` (`node script/sync-hypher-shared.mjs`). Do not edit `vendor/` by hand.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litterthanlit/hypher-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Hypher bridge for coding agents: hooks, a local outbox, and a truth check against the working tree. Pilot, not yet recorded.",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -9,12 +9,21 @@ import { apiBase, CLI_VERSION, paths } from "./env.mjs";
 import { readConfig } from "./config.mjs";
 import { loadCredential } from "./credentials.mjs";
 
+/**
+ * Hypher could not be reached, or what answered is not Hypher: a timeout, a 5xx, or any answer that is not
+ * Hypher's own JSON (a proxy's 403 in plain text, an HTML page, an empty body). `answer` says what came back,
+ * as a status and a content type, never a body, so `hypher doctor` can name it.
+ * @param {string} base
+ * @param {unknown} cause
+ * @param {{ status: number, contentType: string } | null} [answer]
+ */
 export class HypherUnavailable extends Error {
-  constructor(base, cause) {
+  constructor(base, cause, answer = null) {
     super(`Hypher unavailable at ${base}`);
     this.name = "HypherUnavailable";
     this.base = base;
     this.causeText = cause instanceof Error ? cause.message : String(cause ?? "");
+    this.answer = answer;
   }
 }
 
@@ -29,6 +38,16 @@ export class HypherRejected extends Error {
 
 const MAX_LOG_BYTES = 20_000;
 
+/** The parsed body when it is a JSON object (Hypher's shape for every answer), else null. */
+function ownJson(text) {
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
 function logSent(env, entry) {
   try {
     const file = paths(env).sentLog;
@@ -70,13 +89,19 @@ export function createClient({ env = process.env, apiKey, timeoutMs = 4_000 } =
     } catch (error) {
       throw new HypherUnavailable(base, error);
     }
-    let json = null;
+    const contentType = (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+    const answer = { status: response.status, contentType };
+    let text;
     try {
-      json = await response.json();
-    } catch {
-      json = null;
+      text = await response.text();
+    } catch (error) {
+      throw new HypherUnavailable(base, error, answer);
     }
-    if (response.status >= 500) throw new HypherUnavailable(base, `HTTP ${response.status}`);
+    if (response.status >= 500) throw new HypherUnavailable(base, `HTTP ${response.status}`, answer);
+    const json = ownJson(text);
+    // The one rule: Hypher answers in JSON, every time, refusals included. Anything else came from something
+    // between this computer and Hypher (a proxy, a captive portal), so Hypher is unavailable, not saying no.
+    if (json === null) throw new HypherUnavailable(base, `HTTP ${response.status} that is not Hypher's answer`, answer);
     return { status: response.status, ok: response.ok, json };
   }
 

package/src/claude.mjs

@@ -3,18 +3,32 @@
  * merges them into ~/.claude/settings.json without touching the builder's
  * own entries, and `uninstall` takes out only these.
  */
-import { hookCommand as taggedCommand, installedEvents, isTaggedCommand, mergeHooks, removeHooks, renderJson } from "./hookConfig.mjs";
+import { hookCommand as taggedCommand, installedEvents, installedSpecs, isTaggedCommand, mergeHooks, removeHooks, renderJson } from "./hookConfig.mjs";
 
 /** Every Hypher hook command carries this, so it can be found again. */
 export const HOOK_TAG = "hook claude-code";
 
+/**
+ * PostToolUse is two entries, one per tool matcher: a file edit (a checkpoint at most every 10 seconds) and a
+ * command (at most every 60). The handler tells them apart by the payload's `tool_name`. The 5-second timeout is
+ * a ceiling; a throttled call answers in well under a quarter of a second. Codex has no PostToolUse hook (M4).
+ */
+export const EDIT_TOOLS_MATCHER = "Edit|Write|MultiEdit|NotebookEdit";
 export const CLAUDE_HOOKS = [
   { event: "SessionStart", matcher: "startup|resume|clear|compact", timeout: 10 },
   { event: "Stop", timeout: 10 },
   { event: "PreCompact", timeout: 15 },
   { event: "SessionEnd", timeout: 15 },
+  { event: "PostToolUse", matcher: EDIT_TOOLS_MATCHER, timeout: 5 },
+  { event: "PostToolUse", matcher: "Bash", timeout: 5 },
 ];
 
+/** A spec's name for a person: its event, and for an event with several entries, its matcher too. */
+export function hookLabel(spec) {
+  const shared = CLAUDE_HOOKS.filter((other) => other.event === spec.event).length > 1;
+  return shared ? `${spec.event} (${spec.matcher})` : spec.event;
+}
+
 export function hookCommand(shim, event) {
   return taggedCommand(shim, HOOK_TAG, event);
 }
@@ -35,10 +49,17 @@ export function removeClaudeHooks(settings) {
   return removeHooks(settings, HOOK_TAG);
 }
 
+/** The events Hypher has a hook for, each once. */
 export function installedHookEvents(settings) {
   return installedEvents(settings, CLAUDE_HOOKS, HOOK_TAG);
 }
 
+/** The hooks `init` would add that are not in these settings, by name. Empty when everything is there. */
+export function missingHooks(settings) {
+  const present = new Set(installedSpecs(settings, CLAUDE_HOOKS, HOOK_TAG));
+  return CLAUDE_HOOKS.filter((spec) => !present.has(spec)).map(hookLabel);
+}
+
 export const renderSettings = renderJson;
 
 /** Clean edited settings text; null when it is not JSON we can safely rewrite. */

package/src/cli.mjs

@@ -25,6 +25,7 @@ const OPTIONS = {
   full: { type: "boolean" },
   "no-browser": { type: "boolean" },
   "no-path": { type: "boolean" },
+  repo: { type: "boolean" },
   help: { type: "boolean", short: "h" },
   version: { type: "boolean", short: "v" },
   goal: { type: "string" },
@@ -51,7 +52,8 @@ Usage: hypher <command>
   init        Connect this computer (one browser approval); add Claude Code and Codex hooks
               [--yes: never ask in the terminal] [--json: one JSON summary] [--no-browser]
               [--no-path: leave your shell's PATH alone]
-  link        Bind this repository to a Hypher project (one browser approval)
+              [--repo: write the cloud kit into this repository for Claude Code cloud sessions; commit it yourself]
+  link       Bind this repository to a Hypher project (one browser approval)
   doctor      Check every piece and print the fix for anything red
   status      What is installed; --last shows exactly what was last sent
   resume      Print the handoff note for this repository and its truth check
@@ -62,6 +64,7 @@ Usage: hypher <command>
   ack         Acknowledge the handoff this session read
   mcp         Run the stdio MCP bridge: resume, seal, acknowledge (for any MCP client)
   uninstall   Remove exactly what init added and revoke the key
+              [--repo: remove only the cloud kit from this repository]
 
 Only hashes, file names, repository and commit identity, and agent-written
 handoff text leave this machine. Never code, diffs, or transcripts.`;

package/src/cloud.mjs

@@ -0,0 +1,145 @@
+/**
+ * Cloud mode (M3 slice 5): a Claude Code cloud session, started by the repository's committed kit
+ * (`hypher init --repo`). It is on when `CLAUDE_CODE_REMOTE=true` and the key is the one from
+ * `HYPHER_API_KEY` (a container has no Keychain). Three things differ from a laptop, and nothing else does:
+ *
+ * - No link file exists in a fresh container. A repository a human linked in Hypher is linked here without a click
+ *   (`resolve_project_for_repo`, as `hypher link` already does when Hypher knows the repository), and the answer is
+ *   kept in the container's `~/.hypher`. A repository nobody linked uploads nothing and says so in one line. Hypher
+ *   never creates a project.
+ * - The container's disk dies with the session, so a checkpoint uploads at once instead of at the next session: at
+ *   most one upload a minute per repository and branch (a newer queued checkpoint replaces an older one, so the
+ *   newest wins), and `Stop`, `PreCompact`, and `SessionEnd` always try.
+ * - The seal request names `hypher seal` in the shell first (see hooks/index.mjs): no signed-in MCP entry exists.
+ */
+import path from "node:path";
+import { createClient, HypherRejected, HypherUnavailable } from "./api.mjs";
+import { linkFor, saveLink } from "./config.mjs";
+import { loadCredential } from "./credentials.mjs";
+import { paths } from "./env.mjs";
+import { readJson, sha256, writeJson } from "./fsutil.mjs";
+import { flushOutbox } from "./outbox.mjs";
+
+/** One upload a minute per repository and branch, outside the three events that always try. */
+export const UPLOAD_WINDOW_MS = 60_000;
+/** After an unmatched or unreachable answer, how long a hook that is not a session start waits before asking again. */
+const UNAVAILABLE_RETRY_MS = 60_000;
+
+/** True in any Claude Code cloud session, with or without a key. */
+export function inCloud(env = process.env) {
+  return env?.CLAUDE_CODE_REMOTE === "true";
+}
+
+/** Cloud mode: a cloud session whose key is `HYPHER_API_KEY`. The cheap test goes first: a laptop never reads a credential here. */
+export function cloudMode(env = process.env) {
+  return inCloud(env) && loadCredential(env).source === "HYPHER_API_KEY";
+}
+
+export const CLOUD_NOT_CONNECTED_LINE =
+  "Hypher is not connected in this cloud session; starting without it. Add HYPHER_API_KEY (a Hypher API key) to the cloud environment.";
+
+export function cloudUnlinkedLine(repository) {
+  return `Hypher: ${String(repository).slice(0, 200)} is not linked to a Hypher project, so nothing is uploaded from this session. A person links it in Settings → Integrations at hypher.app; Hypher never creates a project on its own.`;
+}
+
+function cloudFile(env, name) {
+  return path.join(paths(env).stateDir, "cloud", name);
+}
+
+function readMap(file) {
+  const value = readJson(file, null);
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+/**
+ * The project this repository is linked to. On a laptop that is the link file, as always. In cloud mode a
+ * repository with no link asks Hypher whether a human linked it, and keeps the answer. A session start (`force`)
+ * always asks; any other hook asks only if the last answer was neither "no project" nor a failure in the last minute,
+ * so a repository nobody linked costs one request per session start, not one per edit.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} repository owner/repo
+ * @param {{ force?: boolean, now?: number, timeoutMs?: number }} [options]
+ * @returns {Promise<{ link: object | null, status: "linked" | "unlinked" | "unmatched" | "not-connected" | "unavailable" | "rejected", error?: string }>}
+ */
+export async function findLink(env, repository, { force = false, now = Date.now(), timeoutMs = 2_500 } = {}) {
+  const known = linkFor(repository, env);
+  if (known) return { link: known, status: "linked" };
+  if (!inCloud(env)) return { link: null, status: "unlinked" };
+  const client = createClient({ env, timeoutMs });
+  if (!client.apiKey) return { link: null, status: "not-connected" };
+
+  const file = cloudFile(env, "resolve.json");
+  const key = String(repository).toLowerCase();
+  const before = readMap(file)[key];
+  if (!force && before) {
+    if (before.status === "unmatched") return { link: null, status: "unmatched" };
+    if (now >= before.at && now - before.at < UNAVAILABLE_RETRY_MS) return { link: null, status: before.status };
+  }
+  const remember = (status) => {
+    try {
+      writeJson(file, { ...readMap(file), [key]: { status, at: now } }, { mode: 0o600 });
+    } catch {
+      // Only saves a request; never fail a hook over it.
+    }
+  };
+  try {
+    const { structured } = await client.tool("resolve_project_for_repo", { repo: repository });
+    if (structured.matched && structured.projectId) {
+      const link = { projectId: structured.projectId, projectName: structured.projectName };
+      saveLink(repository, link, env);
+      return { link: linkFor(repository, env), status: "linked" };
+    }
+    remember("unmatched");
+    return { link: null, status: "unmatched" };
+  } catch (error) {
+    if (error instanceof HypherUnavailable) {
+      remember("unavailable");
+      return { link: null, status: "unavailable" };
+    }
+    if (error instanceof HypherRejected) {
+      remember("rejected");
+      return { link: null, status: "rejected", error: error.message };
+    }
+    throw error;
+  }
+}
+
+function uploadWindowFile(env) {
+  return cloudFile(env, "upload.json");
+}
+
+/**
+ * True, and counted, when a checkpoint of this repository and branch may upload now; false inside the minute after the
+ * last one. Counted before the request, so two hooks started together do not both upload. A time in the future (a
+ * clock that moved back) does not block.
+ */
+export function claimUpload(env, key, now) {
+  const file = uploadWindowFile(env);
+  const all = readMap(file);
+  const hash = sha256(String(key)).slice(0, 20);
+  const last = all[hash];
+  if (typeof last === "number" && now >= last && now - last < UPLOAD_WINDOW_MS) return false;
+  writeJson(file, { ...all, [hash]: now }, { mode: 0o600 });
+  return true;
+}
+
+/**
+ * Upload what is queued. `always` is for `Stop`, `PreCompact`, and `SessionEnd`: no window, no wait for a retry
+ * time. Anything else uploads at most once a minute per repository and branch; a checkpoint that waits stays
+ * queued, and a newer one replaces it there.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {{ repository: string, branch: string }} snapshot
+ * @param {{ always?: boolean, now?: number, timeoutMs?: number }} [options]
+ */
+export async function uploadNow(env, snapshot, { always = false, now = Date.now(), timeoutMs = 2_500 } = {}) {
+  const key = `${snapshot.repository.toLowerCase()}#${snapshot.branch}`;
+  if (!always && !claimUpload(env, key, now)) return null;
+  if (always) {
+    try {
+      claimUpload(env, key, now);
+    } catch {
+      // The window is a convenience here.
+    }
+  }
+  return await flushOutbox(createClient({ env, timeoutMs }), { env, now, force: always }).catch(() => null);
+}

package/src/commands/doctor.mjs

@@ -7,18 +7,38 @@ import { CLI_VERSION, INTEGRATIONS_URL, inCodexSandbox, paths } from "../env.mjs
 import { linkFor, readConfig } from "../config.mjs";
 import { loadCredential } from "../credentials.mjs";
 import { createClient, HypherRejected, HypherUnavailable } from "../api.mjs";
-import { installedHookEvents, CLAUDE_HOOKS } from "../claude.mjs";
+import { installedHookEvents, missingHooks } from "../claude.mjs";
 import { claudeHypherServer, detectTools, isSignInEntry, projectLevelHypherEntry } from "../tools.mjs";
 import { listOutbox } from "../outbox.mjs";
 import { readBytes, readJson } from "../fsutil.mjs";
 import { CODEX_HOOKS, codexHookTrust, codexHypherEntry, codexSupportsHooks, installedCodexHookEvents, readCodexHooks } from "../codex.mjs";
 import { hasBlock } from "../agentsBlock.mjs";
+import { inspectRepoKit } from "../repoKit.mjs";
 import { remotesExposingHypherRefs, repoIdentity } from "../../vendor/hypher-git.mjs";
 
 function pad(text, width = 22) {
   return text.length >= width ? `${text} ` : text + " ".repeat(width - text.length);
 }
 
+function hostOf(base) {
+  try {
+    return new URL(base).host;
+  } catch {
+    return base;
+  }
+}
+
+/** What was tried and what came back: status and content type, never a body. */
+function unavailableDetail(base, error) {
+  const host = hostOf(base);
+  const answer = error.answer;
+  if (!answer) return `${base} (${error.causeText || "no answer"})`;
+  const type = answer.contentType || "no content type";
+  return answer.status >= 500
+    ? `${host} answered HTTP ${answer.status} (${type})`
+    : `${host} answered HTTP ${answer.status} (${type}), which is not Hypher's answer`;
+}
+
 export async function run({ io }) {
   const env = io.env;
   const p = paths(env);
@@ -46,11 +66,13 @@ export async function run({ io }) {
 
   const tools = detectTools(env);
   if (tools.claude.found) {
-    const events = installedHookEvents(readJson(p.claudeSettings, {}) ?? {});
+    const settings = readJson(p.claudeSettings, {}) ?? {};
+    const events = installedHookEvents(settings);
+    const missing = missingHooks(settings);
     const entry = claudeHypherServer(env);
     const mcp = entry ? (isSignInEntry(entry) ? "MCP hypher (sign-in)" : "MCP hypher (bridge)") : "no hypher MCP entry";
-    if (events.length === CLAUDE_HOOKS.length) add("✓", `Claude Code ${tools.claude.version}`, `hooks ${events.join(", ")} · ${mcp}`);
-    else add("✗", `Claude Code ${tools.claude.version}`, `hooks missing: ${CLAUDE_HOOKS.map((hook) => hook.event).filter((event) => !events.includes(event)).join(", ")}`, "run `hypher init`.");
+    if (missing.length === 0) add("✓", `Claude Code ${tools.claude.version}`, `hooks ${events.join(", ")} · ${mcp}`);
+    else add("✗", `Claude Code ${tools.claude.version}`, `hooks missing: ${missing.join(", ")}`, "run `hypher init`.");
   } else {
     add("–", "Claude Code", "not found");
   }
@@ -103,6 +125,19 @@ export async function run({ io }) {
       add("✓", "refs/hypher", "stay local (no remote pushes them)");
     }
   }
+  if (identity.root) {
+    const kit = inspectRepoKit(identity.root);
+    if (kit.state === "none") {
+      add("–", "Repo kit", "not in this repository (`hypher init --repo` adds it for Claude Code cloud sessions)");
+    } else if (kit.state === "partial") {
+      add("✗", "Repo kit", kit.problems.join("; "), "run `hypher init --repo` here and commit the result.");
+    } else if (kit.version === CLI_VERSION) {
+      add("✓", "Repo kit", `present · pinned @litterthanlit/hypher-cli@${kit.version} · hooks ${kit.events.join(", ")}`);
+    } else {
+      add("!", "Repo kit", `present · pinned @litterthanlit/hypher-cli@${kit.version ?? "unknown"}; this copy is ${CLI_VERSION} · hooks ${kit.events.join(", ")}`,
+        "to move the pin, run `npx @litterthanlit/hypher-cli@latest init --repo` here and commit the result.");
+    }
+  }
 
   const client = createClient({ env, timeoutMs: 5_000 });
   if (credential.apiKey) {
@@ -115,8 +150,8 @@ export async function run({ io }) {
       if (error instanceof HypherUnavailable && sandboxed) {
         add("!", "Hypher reachable", `not reachable inside Codex's sandbox (${client.base})`);
       } else if (error instanceof HypherUnavailable) {
-        add("✗", "Hypher unavailable", `${client.base} (${error.causeText || "no answer"})`,
-          "check your network, VPN, or proxy, then run `hypher doctor` again. Sessions start without Hypher until then.");
+        add("✗", "Hypher unavailable", unavailableDetail(client.base, error),
+          `${error.answer && error.answer.status < 500 ? `something between this computer and ${hostOf(client.base)} (a proxy, VPN, or firewall) is answering for Hypher: allow ${hostOf(client.base)}, then` : "check your network, VPN, or proxy, then"} run \`hypher doctor\` again. Sessions start without Hypher until then, and queued checkpoints are kept.`);
       } else if (error instanceof HypherRejected) {
         add("✗", "Hypher reachable", error.message, "run `hypher init` to connect this computer again.");
       } else {

package/src/commands/hook.mjs

@@ -47,7 +47,7 @@ export async function run({ args, io }) {
   } catch (error) {
     logError(io.env, event, error);
     if (event === "SessionStart") {
-      io.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: HYPHER_UNAVAILABLE_LINE } })}\n`);
+      io.stdout.write(`${JSON.stringify({ systemMessage: HYPHER_UNAVAILABLE_LINE, hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: HYPHER_UNAVAILABLE_LINE } })}\n`);
     }
   } finally {
     // A client that keeps stdin open must not keep this hook alive.

package/src/commands/init.mjs

@@ -14,7 +14,7 @@ import { credentialPromptLine, credentialStore, loadCredential, saveCredential }
 import { createClient, HypherUnavailable } from "../api.mjs";
 import { runDeviceFlow } from "../device.mjs";
 import { readManifest, recordEntry, writeManifest, writeTrackedFile } from "../manifest.mjs";
-import { mergeClaudeHooks, renderSettings, CLAUDE_HOOKS } from "../claude.mjs";
+import { mergeClaudeHooks, renderSettings, installedHookEvents } from "../claude.mjs";
 import { claudeHypherServer, claudeMcpAdd, detectTools, isSignInEntry } from "../tools.mjs";
 import { readBytes, readJson } from "../fsutil.mjs";
 import { CODEX_HOOKS, CODEX_TRUST_LINE, addBridge, codexHookTrust, codexHypherEntry, codexSupportsHooks, mergeCodexHooks, readCodexHooks } from "../codex.mjs";
@@ -22,7 +22,8 @@ import { renderJson } from "../hookConfig.mjs";
 import { addBlock, agentsBlock, alreadyUsesHypher } from "../agentsBlock.mjs";
 import { addRepositoryBlock, displayPath } from "../repoBlock.mjs";
 import { addPathBlock, manualPathLine, pathBlock, shellStartupFile } from "../shellPath.mjs";
-import { repoIdentity } from "../../vendor/hypher-git.mjs";
+import { installRepoKit } from "../repoKit.mjs";
+import { git, repoIdentity } from "../../vendor/hypher-git.mjs";
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
@@ -52,12 +53,62 @@ export function installPinnedCopy(env, manifest) {
   return change;
 }
 
+/**
+ * `hypher init --repo`: write the repo kit (repoKit.mjs) into the repository you are in, so Claude Code cloud sessions
+ * run Hypher's hooks. Needs no sign-in and touches nothing outside the repository. Never commits and never pushes:
+ * it prints what to commit.
+ */
+async function runRepo({ flags, io }) {
+  const identity = repoIdentity(io.cwd);
+  if (!identity.root) {
+    io.err("hypher init --repo: run this inside a git repository.");
+    return 2;
+  }
+  const done = installRepoKit(identity.root, CLI_VERSION);
+  if (!done.ok) {
+    io.err(`hypher init --repo: ${done.error}`);
+    return 1;
+  }
+  // Only files git sees as new or modified need committing; a rerun on a committed kit says so.
+  const dirty = (git(identity.root, ["status", "--porcelain", "--untracked-files=all", "--", ...done.files]) ?? "").split("\n").filter(Boolean);
+  const toCommit = done.files.filter((file) => dirty.some((line) => line.slice(3) === file));
+  const say = flags.json ? (line = "") => io.err(line) : (line = "") => io.out(line);
+  say(`Hypher · cloud kit  (hypher-cli ${CLI_VERSION}, pinned in the script)`);
+  say("");
+  if (done.changes.length) {
+    say("  Changed");
+    for (const [file, what] of done.changes) say(`    ${pad(file, 28)}${what}`);
+  } else {
+    say("  Already set up. Nothing changed.");
+  }
+  say("");
+  if (toCommit.length) {
+    say("  Hypher did not commit or push anything. To turn it on for cloud sessions, commit these files:");
+    say(`    git add ${toCommit.join(" ")}`);
+    say('    git commit -m "Add Hypher project memory for Claude Code cloud sessions"');
+    say("  hypher.sh must stay executable; git add records that. A committed hook runs a script at session start for anyone who clones, so Claude Code asks them to trust it.");
+  } else {
+    say("  These files are already committed.");
+  }
+  say("");
+  say("  In the Claude Code cloud environment for this repository, add a variable:");
+  say("    HYPHER_API_KEY = a Hypher API key (Settings → API keys, named for that environment, revoked when you are done)");
+  say(`  ${API_KEYS_URL}`);
+  say(`  Hypher uploads nothing until a person has linked ${identity.repository ?? "this repository"} to a project in Settings → Integrations.${identity.repository ? "" : " (This repository has no GitHub remote, so it cannot be linked.)"}`);
+  say("  Undo: hypher uninstall --repo");
+  if (flags.json) {
+    io.out(JSON.stringify({ ok: true, version: CLI_VERSION, alreadySetUp: done.changes.length === 0, changed: done.changes.map(([file, what]) => ({ file, what })), commit: toCommit, env: ["HYPHER_API_KEY"] }));
+  }
+  return 0;
+}
+
 /**
  * `--yes` never asks in the terminal (today init asks nothing there; the one
  * approval is in the browser). `--json` prints one JSON summary on stdout.
  * @param {{ args: string[], flags: Record<string, any>, io: any }} input
  */
 export async function run({ flags, io }) {
+  if (flags.repo) return runRepo({ flags, io });
   const env = io.env;
   const started = Date.now();
   let approvalMs = 0;
@@ -194,7 +245,7 @@ export async function run({ flags, io }) {
     const settings = readJson(p.claudeSettings, {}) ?? {};
     const merged = mergeClaudeHooks(settings && typeof settings === "object" ? settings : {}, p.shim);
     const change = writeTrackedFile(manifest, p.claudeSettings, renderSettings(merged), "claude-settings");
-    if (change !== "unchanged") changed.push([p.claudeSettings, `+ hooks ${CLAUDE_HOOKS.map((hook) => hook.event).join(", ")}`]);
+    if (change !== "unchanged") changed.push([p.claudeSettings, `+ hooks ${installedHookEvents(merged).join(", ")}`]);
     writeManifest(manifest, env);
     if (!claudeEntry) {
       const added = claudeMcpAdd(env, p.shim);

package/src/commands/status.mjs

@@ -6,7 +6,7 @@ import { readFileSync } from "node:fs";
 import { CLI_VERSION, paths } from "../env.mjs";
 import { readConfig, linkFor } from "../config.mjs";
 import { loadCredential } from "../credentials.mjs";
-import { listOutbox } from "../outbox.mjs";
+import { listOutbox, newestCheckpoint } from "../outbox.mjs";
 import { repoIdentity } from "../../vendor/hypher-git.mjs";
 
 export function lastSent(env) {
@@ -18,6 +18,39 @@ export function lastSent(env) {
   }
 }
 
+const pad2 = (n) => String(n).padStart(2, "0");
+
+/** The computer's clock time, like 14:32:05, and the same instant in UTC as an ISO string. */
+export function clockTimes(ms) {
+  const at = new Date(ms);
+  return { local: `${pad2(at.getHours())}:${pad2(at.getMinutes())}:${pad2(at.getSeconds())}`, utc: at.toISOString() };
+}
+
+/** How long ago, in words a person reads at a glance. */
+export function ageWords(ms) {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  if (seconds < 90) return `${seconds} s ago`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 90) return `${minutes} min ago`;
+  return `${Math.round(minutes / 60)} h ago`;
+}
+
+/** The lines for the newest checkpoint of this worktree: its event, clock time, age, and whether it has left this computer. */
+export function checkpointLines(found, now) {
+  if (!found) return ["  Newest checkpoint: none yet for this worktree (one is written when a session starts and as files change)"];
+  const { body } = found;
+  const times = clockTimes(body.capturedAt);
+  const files = Array.isArray(body.changedFiles) ? body.changedFiles : [];
+  const where = found.state === "queued"
+    ? "Queued on this computer, not uploaded yet: it uploads at the next session start in this repository."
+    : `Uploaded to Hypher at ${clockTimes(found.uploadedAt).local} local.`;
+  return [
+    `  Newest checkpoint: ${body.event} · ${times.local} local (${times.utc} UTC) · ${ageWords(now - body.capturedAt)}`,
+    `                     ${where}`,
+    `                     ${files.length ? `files: ${files.slice(0, 12).join(", ")}${files.length > 12 ? ` (+${files.length - 12} more)` : ""}` : "no changed files"}`,
+  ];
+}
+
 export async function run({ flags, io }) {
   const env = io.env;
   if (flags.last) {
@@ -34,5 +67,8 @@ export async function run({ flags, io }) {
   io.out(`  Connected:  ${credential.apiKey ? `yes · key "${config?.keyName ?? "Hypher CLI"}" (${credential.source})` : "no"}`);
   io.out(`  Repository: ${identity.repository ?? "none"}${identity.repository ? (link ? ` → "${link.projectName}"` : " (not linked; run hypher link)") : ""}`);
   io.out(`  Outbox:     ${listOutbox(env).length} checkpoint(s) waiting`);
+  if (identity.repository && identity.branch) {
+    for (const line of checkpointLines(newestCheckpoint(env, identity.repository, identity.branch), Date.now())) io.out(line);
+  }
   return 0;
 }

package/src/commands/uninstall.mjs

@@ -16,6 +16,8 @@ import { removeBlock } from "../agentsBlock.mjs";
 import { removePathBlock } from "../shellPath.mjs";
 import { claudeHypherServer, claudeMcpRemove, detectTools } from "../tools.mjs";
 import { readJson, writeAtomic } from "../fsutil.mjs";
+import { uninstallRepoKit } from "../repoKit.mjs";
+import { repoIdentity } from "../../vendor/hypher-git.mjs";
 
 /**
  * How to take only Hypher's entries out of a file edited since install.
@@ -43,7 +45,29 @@ function readLine(stdin) {
   });
 }
 
+/**
+ * `hypher uninstall --repo`: take the cloud kit out of this repository and nothing else. It needs no manifest in
+ * ~/.hypher and does not touch the key, the credential, or the hooks on this computer. Plain `uninstall` is unchanged.
+ */
+function runRepo({ io }) {
+  const identity = repoIdentity(io.cwd);
+  if (!identity.root) {
+    io.err("hypher uninstall --repo: run this inside a git repository.");
+    return 2;
+  }
+  const undone = uninstallRepoKit(identity.root);
+  if (undone.length === 0) {
+    io.out("The Hypher cloud kit is not in this repository. Nothing to undo.");
+    return 0;
+  }
+  io.out("Hypher cloud kit removed from this repository.");
+  for (const line of undone) io.out(`  ✓ ${line}`);
+  io.out("  Nothing was committed. Review with `git status`, then commit the removal.");
+  return 0;
+}
+
 export async function run({ flags, io }) {
+  if (flags.repo) return runRepo({ io });
   const env = io.env;
   const p = paths(env);
   const manifest = readManifest(env);

package/src/env.mjs

@@ -7,7 +7,7 @@ import os from "node:os";
 import path from "node:path";
 
 // Keep equal to package.json; a test checks it.
-export const CLI_VERSION = "0.2.0";
+export const CLI_VERSION = "0.3.0";
 export const DEFAULT_API_BASE = "https://www.hypher.app";
 export const INTEGRATIONS_URL = "https://hypher.app/app/settings/integrations";
 export const API_KEYS_URL = "https://hypher.app/app/settings/api-keys";