@litterthanlit/hypher-cli 0.2.1 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ Pilot · not yet recorded. The bridge between coding agents and Hypher project m
 - `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. 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 does not touch the network; checkpoints upload when the next session starts here. `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.
+- **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.
@@ -14,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.1",
+  "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/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

@@ -13,6 +13,7 @@ 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) {
@@ -124,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) {

package/src/commands/init.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;

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.1";
+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";

package/src/hookConfig.mjs

@@ -35,8 +35,9 @@ 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))) {
@@ -45,7 +46,7 @@ export function mergeHooks(config, specs, shim, tag) {
   for (const spec of specs) {
     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 }],
     });
   }
   return next;

package/src/hooks/index.mjs

@@ -1,7 +1,8 @@
 /**
  * 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.
@@ -10,9 +11,15 @@
  * 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";
@@ -24,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;
 }
 
@@ -58,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>\")."
@@ -66,7 +76,10 @@ 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.",
@@ -77,10 +90,12 @@ function sealRequest(firstHandoff, ledgerOn = false) {
 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. */
-function recordStartCheckpoint(env, snapshot, agent) {
+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.
   }
@@ -92,23 +107,28 @@ async function sessionStart(agent, env, input) {
     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;
   // 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") recordStartCheckpoint(env, result.snapshot, agent);
+  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);
   }
 
@@ -127,7 +147,7 @@ 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) };
 }
 
 /**
@@ -141,16 +161,20 @@ async function postToolUse(agent, env, input, now = Date.now()) {
   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 = linkedSnapshot(env, cwd);
-  if (found) recordCheckpoint(env, found.snapshot, "PostToolUse", now, agent);
+  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;
 }
 

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 };
+}

package/src/session.mjs

@@ -4,11 +4,11 @@
  */
 import { createClient, HypherRejected, HypherUnavailable } from "./api.mjs";
 import { readActiveDecisions, readWholeLedger } from "./ledger.mjs";
-import { linkFor } from "./config.mjs";
+import { CLOUD_NOT_CONNECTED_LINE, cloudUnlinkedLine, findLink, inCloud } from "./cloud.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 { branchState, readWorktreeState, updateWorktreeState, withBranchState } from "./state.mjs";
 import { inCodexSandbox, SANDBOX_LINE } from "./env.mjs";
 import { findSecretInValue } from "./secrets.mjs";
 import { keepHandoffTree, truthCheck } from "../vendor/hypher-git.mjs";
@@ -61,22 +61,35 @@ function checkpointFrom(body) {
   };
 }
 
+/** SessionStart sources after which the same work goes on: `compact` and `clear` do not move the seal baseline. */
+export const KEEPS_SEAL_BASELINE = new Set(["compact", "clear"]);
+
 /**
  * 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.
  * `full` prints every item, uncut; for a project whose decision ledger is on it also reads the ledger's lists.
- * @param {{ env: NodeJS.ProcessEnv, cwd: string, destination: string, sessionId?: string, now?: number, timeoutMs?: number, full?: boolean }} options
+ * `source` is the SessionStart hook's: for `compact` and `clear` the session goes on with the same work, so the
+ * seal baseline stays where it was and edits made before it still count at the next Stop. Anything else (or no
+ * source, as for `hypher resume` and the MCP tool) moves the baseline to the tree now.
+ * @param {{ env: NodeJS.ProcessEnv, cwd: string, destination: string, sessionId?: string, now?: number, timeoutMs?: number, full?: boolean, source?: string }} options
  */
-export async function resumeHere({ env, cwd, destination, sessionId, now = Date.now(), timeoutMs = 2_500, full = false }) {
+export async function resumeHere({ env, cwd, destination, sessionId, now = Date.now(), timeoutMs = 2_500, full = false, source }) {
   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);
+  // In a cloud session a repository a human linked in Hypher is linked here without a click (cloud.mjs).
+  const found = await findLink(env, snapshot.repository, { force: true, now, timeoutMs });
+  const link = found.link;
   // A repository no human linked uploads nothing at all.
-  if (!link) return { status: "unlinked", note: renderUnlinkedLine(snapshot.repository), snapshot };
+  if (!link) {
+    if (found.status === "not-connected") return { status: "not-connected", note: CLOUD_NOT_CONNECTED_LINE, snapshot };
+    if (found.status === "unavailable") return { status: "unavailable", note: HYPHER_UNAVAILABLE_LINE, snapshot };
+    if (found.status === "rejected") return { status: "rejected", note: `Hypher: ${found.error}`, snapshot };
+    return { status: "unlinked", note: inCloud(env) ? cloudUnlinkedLine(snapshot.repository) : renderUnlinkedLine(snapshot.repository), snapshot };
+  }
   const client = createClient({ env, timeoutMs });
   if (!client.apiKey) {
     return inCodexSandbox(env)
@@ -84,6 +97,9 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
       : { status: "not-connected", note: NOT_CONNECTED_LINE, snapshot };
   }
   const unavailableLine = inCodexSandbox(env) ? SANDBOX_LINE : HYPHER_UNAVAILABLE_LINE;
+  // The tree the next Stop compares against: the one already recorded for this branch after a compaction or a
+  // /clear (unsealed edits stay unsealed), the tree now at a start or a resume, or when none was recorded.
+  const sealBaseline = (state) => (KEEPS_SEAL_BASELINE.has(source) ? branchState(state, snapshot.branch).sealTree : undefined) ?? snapshot.tree;
 
   let prepared;
   let checkpoint = null;
@@ -118,9 +134,9 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
         // A project with no handoff saves its first one the v1 way, in every mode: no ledger flag.
         const { ledger: _ledger, ...rest } = state;
         return withBranchState({ ...rest, ...base, baseRevision: 0, proposal: null, receiptId: null, receiptRevision: null },
-          snapshot.branch, { sealTree: snapshot.tree });
+          snapshot.branch, { sealTree: sealBaseline(state) });
       });
-      return { status: "no-handoff", note: renderNoHandoffNote({ repository: snapshot.repository, projectName: link.projectName, now, checkpoint: shown }), snapshot, checkpoint: shown };
+      return { status: "no-handoff", note: renderNoHandoffNote({ repository: snapshot.repository, projectName: link.projectName, now, checkpoint: shown, checkpointClock: true }), snapshot, checkpoint: shown };
     }
     return { status: "rejected", note: `Hypher: ${prepared?.error ?? "could not load the handoff"}. Run \`hypher doctor\`.`, snapshot };
   }
@@ -148,6 +164,7 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
       // Each reported check says whether its tree is the tree now.
       currentTree: verdict?.current?.tree ?? snapshot.tree,
       checkpoint: shownCheckpoint,
+      checkpointClock: true,
       acknowledge: ACK_HINT,
       notice,
       moreHint: MORE_HINT,
@@ -170,7 +187,7 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
       // A later save moves baseRevision; the receipt stays tied to the revision that was read.
       receiptRevision: prepared.revision,
       ...(ledger ? { ledger } : {}),
-    }, snapshot.branch, { sealTree: snapshot.tree });
+    }, snapshot.branch, { sealTree: sealBaseline(state) });
   });
   const wholeLedger = full && ledgerNote
     ? await readWholeLedger(client, { projectId: link.projectId, branch: snapshot.branch })
@@ -207,8 +224,8 @@ 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) };
+  const { link } = await findLink(env, snapshot.repository, { now, timeoutMs: 10_000 });
+  if (!link) return { ok: false, code: "unlinked", message: inCloud(env) ? cloudUnlinkedLine(snapshot.repository) : renderUnlinkedLine(snapshot.repository) };
 
   // Agent text is scanned before anything is built or sent.
   const secret = findSecretInValue(seal);

package/vendor/handoffNote.mjs

@@ -88,9 +88,23 @@ export function describeVerdict(verdict, maxFiles = MAX_FILES_SHOWN) {
             return `Tree: this checkout is ${noteText(verdict.current?.repository ?? "unknown", 200)}, not the repository the handoff recorded. ${STOP}`;
     }
 }
-export function describeCheckpoint(checkpoint, now, maxFiles = MAX_FILES_SHOWN) {
+/**
+ * "14:22 UTC, 2026-11-02": when a checkpoint was captured, in UTC so the line reads the same on every machine.
+ * An unreadable time gives "", and the line goes without it.
+ */
+export function formatClockUtc(at) {
+    if (!Number.isFinite(at))
+        return "";
+    const date = new Date(at);
+    if (Number.isNaN(date.getTime()))
+        return "";
+    const iso = date.toISOString();
+    return `${iso.slice(11, 16)} UTC, ${iso.slice(0, 10)}`;
+}
+export function describeCheckpoint(checkpoint, now, maxFiles = MAX_FILES_SHOWN, options = {}) {
     const files = checkpoint.changedFiles.length ? `changed: ${fileList(checkpoint.changedFiles, maxFiles)}` : "no uncommitted changes";
-    return `Last checkpoint: ${formatAge(now - checkpoint.capturedAt)} ago from ${noteText(checkpoint.source, 40)} (${noteText(checkpoint.event, 40)}), not sealed · branch ${noteText(checkpoint.branch, 200)} · ${files}.`;
+    const clock = options.clock ? formatClockUtc(checkpoint.capturedAt) : "";
+    return `Last checkpoint: ${formatAge(now - checkpoint.capturedAt)} ago${clock ? ` (${clock})` : ""} from ${noteText(checkpoint.source, 40)} (${noteText(checkpoint.event, 40)}), not sealed · branch ${noteText(checkpoint.branch, 200)} · ${files}.`;
 }
 /** A code span that survives backticks inside the text. */
 function codeSpan(text) {
@@ -152,7 +166,7 @@ function sections(input, max, listLimit) {
         ...(proposal.evidence?.length
             ? [`Evidence: ${limit(proposal.evidence).map((item) => describeEvidence(item, input.now, input.currentTree, max)).join(" ")}${more(proposal.evidence)}`]
             : []),
-        ...(input.checkpoint ? [describeCheckpoint(input.checkpoint, input.now)] : []),
+        ...(input.checkpoint ? [describeCheckpoint(input.checkpoint, input.now, undefined, { clock: input.checkpointClock })] : []),
         `Sources: ${limit(proposal.sources).map((source) => {
             const kind = source.kind === "capture" ? "project capture" : source.kind === "agent_event" ? "stored agent report" : "agent report";
             return `${noteText(source.label ? `${source.label}: ${source.ref}` : source.ref, max)} (${kind})`;
@@ -180,7 +194,7 @@ export function renderNoHandoffNote(input) {
     return frame([
         `Hypher · ${noteText(input.repository, 200)}${input.projectName ? ` · project ${noteText(input.projectName, 120)}` : ""} · no handoff saved yet`,
         NOTE_PREAMBLE,
-        ...(input.checkpoint ? [describeCheckpoint(input.checkpoint, input.now)] : []),
+        ...(input.checkpoint ? [describeCheckpoint(input.checkpoint, input.now, undefined, { clock: input.checkpointClock })] : []),
         "Next: work as usual. When the tree changes, Hypher asks once for the decisions and the next action.",
     ]);
 }

package/vendor/ledgerNoteLocal.mjs

@@ -79,7 +79,7 @@ function place(input, body, tier, withCheckpoint) {
         const preamble = out.indexOf(NOTE_PREAMBLE);
         out.splice(preamble >= 0 ? preamble + 1 : edge, 0, noteText(input.notice, 500));
     }
-    const checkpoint = withCheckpoint && input.checkpoint ? describeCheckpoint(input.checkpoint, input.now, tier.files) : null;
+    const checkpoint = withCheckpoint && input.checkpoint ? describeCheckpoint(input.checkpoint, input.now, tier.files, { clock: true }) : null;
     const acknowledge = input.acknowledge ? ` Then acknowledge this handoff: ${input.acknowledge}.` : "";
     let nextAt = -1;
     for (let index = out.length - 1; index >= 0; index -= 1) {