@litterthanlit/hypher-cli 0.2.0 → 0.3.0

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

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) {