@litterthanlit/hypher-cli 0.2.0 → 0.2.1

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 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.
 - `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litterthanlit/hypher-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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/commands/doctor.mjs

@@ -7,7 +7,7 @@ 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";
@@ -19,6 +19,25 @@ 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 +65,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");
   }
@@ -115,8 +136,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";
@@ -194,7 +194,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/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.2.1";
 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

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

package/src/hooks/index.mjs

@@ -5,11 +5,17 @@
  * once for a seal when the tree changed. Hooks never acknowledge, never block
  * twice in a row, and never block on Hypher being down. In a repository no
  * human linked they record and upload nothing.
+ *
+ * Claude Code alone (Codex parity is M4) also records a checkpoint after the note is read at SessionStart, and
+ * after a tool ran (PostToolUse: a file edit at most every 10 seconds, a command at most every 60), so a session
+ * killed in the middle of a turn still leaves one. PostToolUse reads only `cwd` and `tool_name` from its payload:
+ * the rest is the tool's input, which can be file contents, and is never looked at.
  */
 import { createClient } from "../api.mjs";
 import { linkFor } from "../config.mjs";
 import { enqueue, flushOutbox, shouldFlush } from "../outbox.mjs";
 import { resumeHere } from "../session.mjs";
+import { claimCheckpoint, toolKind } from "../throttle.mjs";
 import { takeSnapshot } from "../snapshot.mjs";
 import { branchState, readWorktreeState, updateWorktreeState, withBranchState } from "../state.mjs";
 import { findSecret } from "../secrets.mjs";
@@ -67,6 +73,19 @@ function sealRequest(firstHandoff, ledgerOn = false) {
   ].join(" ");
 }
 
+/** The resume statuses whose one line is also shown to the person (`systemMessage`), not only given to the model. */
+const PERSON_SEES = new Set(["unavailable", "not-connected", "unlinked"]);
+
+/** The SessionStart checkpoint, from the snapshot the read already took. It never fails a session start. */
+function recordStartCheckpoint(env, snapshot, agent) {
+  try {
+    if (!snapshot?.repository || !snapshot.tree || !linkFor(snapshot.repository, env)) return;
+    recordCheckpoint(env, snapshot, "SessionStart", Date.now(), agent);
+  } catch {
+    // The note is already read; a checkpoint that could not be written is not worth a failed start.
+  }
+}
+
 async function sessionStart(agent, env, input) {
   const result = await resumeHere({
     env,
@@ -76,7 +95,12 @@ async function sessionStart(agent, env, input) {
     timeoutMs: HOOK_TIMEOUT_MS,
   });
   if (result.status === "not-git" || !result.note) return null;
-  return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: result.note } };
+  // After the note is read and rendered, so the note never names its own checkpoint. Queued, not uploaded:
+  // the next session on this computer sends it.
+  if (agent === "claude-code") 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()) {
@@ -106,6 +130,22 @@ async function stop(agent, env, input, now = Date.now()) {
   return { decision: "block", reason: sealRequest(!state.proposal, state.ledger?.on === true) };
 }
 
+/**
+ * A tool just ran. Only Claude Code has this hook. The payload carries the tool's input, which can be file
+ * contents, so nothing but `cwd` and `tool_name` is read from it. A call inside its window answers from one
+ * small file, with no git call. Queued, not uploaded: a laptop's next session sends it.
+ */
+async function postToolUse(agent, env, input, now = Date.now()) {
+  if (agent !== "claude-code") return null;
+  const kind = toolKind(input.tool_name);
+  if (!kind) return null;
+  const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
+  if (!claimCheckpoint(env, cwd, kind, now)) return null;
+  const found = linkedSnapshot(env, cwd);
+  if (found) recordCheckpoint(env, found.snapshot, "PostToolUse", now, agent);
+  return null;
+}
+
 async function checkpointAndUpload(agent, env, input, event, now = Date.now()) {
   const found = linkedSnapshot(env, input.cwd || process.cwd());
   if (!found) return null;
@@ -129,6 +169,8 @@ export async function handleAgentHook(agent, event, input, env) {
       return await sessionStart(agent, env, input);
     case "Stop":
       return await stop(agent, env, input);
+    case "PostToolUse":
+      return await postToolUse(agent, env, input);
     case "PreCompact":
     case "SessionEnd":
       return await checkpointAndUpload(agent, env, input, event);

package/src/outbox.mjs

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

package/src/throttle.mjs

@@ -0,0 +1,46 @@
+/**
+ * How often a PostToolUse hook may record a checkpoint (M3 slice 3). One small file per working directory
+ * holds the time of the last checkpoint for each kind of tool, so a call that is too soon answers from that
+ * file alone, with no git call. A file edit may record every 10 seconds, a command every 60, each counted
+ * on its own: a command does not wait for an edit, nor an edit for a command.
+ */
+import path from "node:path";
+import { paths } from "./env.mjs";
+import { readJson, sha256, writeJson } from "./fsutil.mjs";
+
+export const EDIT_WINDOW_MS = 10_000;
+export const BASH_WINDOW_MS = 60_000;
+
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+
+/** "edit" for a tool that changes files, "bash" for a command, else null (no checkpoint). */
+export function toolKind(toolName) {
+  if (typeof toolName !== "string") return null;
+  if (EDIT_TOOLS.has(toolName)) return "edit";
+  return toolName === "Bash" ? "bash" : null;
+}
+
+const WINDOWS = { edit: EDIT_WINDOW_MS, bash: BASH_WINDOW_MS };
+
+function throttleFile(env, cwd) {
+  return path.join(paths(env).stateDir, "throttle", `${sha256(String(cwd)).slice(0, 20)}.json`);
+}
+
+/**
+ * True, and counted, when a checkpoint of this kind may be recorded now; false when the last one is too
+ * recent. A last time in the future (a clock that moved back) does not block.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} cwd
+ * @param {"edit" | "bash"} kind
+ * @param {number} now
+ */
+export function claimCheckpoint(env, cwd, kind, now) {
+  const file = throttleFile(env, cwd);
+  const saved = readJson(file, null);
+  const last = saved && typeof saved === "object" && !Array.isArray(saved) ? saved : {};
+  const at = last[kind];
+  if (typeof at === "number" && now >= at && now - at < WINDOWS[kind]) return false;
+  // Counted before the git work, so two hooks started together do not both record.
+  writeJson(file, { ...last, [kind]: now }, { mode: 0o600 });
+  return true;
+}