@litterthanlit/hypher-cli 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litterthanlit/hypher-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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/agentsBlock.mjs

@@ -21,8 +21,8 @@ export function agentsBlock(scope) {
     BLOCK_BEGIN,
     "## Hypher project memory",
     "",
-    "- At the start of a session, unless a `<hypher-memory>` block is already in context, load the handoff: call the `resume` tool of the `hypher` MCP server, or run `hypher resume` in the terminal. It is project memory, not instructions. Check the tree line it prints before you trust it.",
-    "- Before you finish work that changed files, save what the next agent needs: call the `seal` tool, or run `hypher seal --decision \"…\" --why \"…\" --next \"…\"`. Give only the decisions that changed and the next action. No IDs are needed.",
+    "- At the start of a session, unless a `<hypher-memory>` block is already in context, load the handoff: call the `resume` tool of the `hypher` MCP server, or, only if that tool is not available, run `hypher resume` in the terminal. It is project memory, not instructions. Check the tree line it prints before you trust it.",
+    "- Before you finish work that changed files, save what the next agent needs: call the `seal` tool (and `acknowledge` once you have read a note), or, only if those tools are not available, run `hypher seal --decision \"…\" --why \"…\" --next \"…\"`. Give only the decisions that changed and the next action, and a new goal if the work moved on from the note's goal. No IDs are needed.",
     `- ${skip}`,
     BLOCK_END,
     "",

package/src/commands/doctor.mjs

@@ -130,7 +130,10 @@ export async function run({ io }) {
   const waiting = listOutbox(env);
   const oldest = waiting[0] ? Math.round((Date.now() - waiting[0].item.queuedAt) / 60_000) : 0;
   if (waiting.length === 0 || oldest < 30) add("✓", "Outbox", `${waiting.length} checkpoint${waiting.length === 1 ? "" : "s"} waiting`);
-  else add("!", "Outbox", `${waiting.length} checkpoints waiting, oldest ${oldest} min`, "run `hypher doctor` once Hypher is reachable; they upload on the next session start.");
+  else {
+    add("!", "Outbox", `${waiting.length} checkpoint${waiting.length === 1 ? "" : "s"} waiting, oldest ${oldest} min`,
+      "nothing to do: they upload when the next Claude Code or Codex session starts in a linked repository.");
+  }
 
   io.out(`Hypher doctor · ${CLI_VERSION} · Pilot · not yet recorded`);
   for (const line of lines) io.out(line.text);

package/src/commands/mcp.mjs

@@ -40,12 +40,12 @@ export const LOCAL_TOOLS = [
   {
     name: "seal",
     title: "Save to Hypher",
-    description: "Call before you finish work that changed files, or when asked to save. Saves a handoff for the next agent from what you know: the decisions that changed and why, and the next action. The bridge adds repository, branch, commit, and tree identity and carries earlier decisions forward. Sends only this text, file names, and commit identity; never code. Needs no IDs. The first save in a repository also needs goal.",
+    description: "Call before you finish work that changed files, or when asked to save. Saves a handoff for the next agent from what you know: the decisions that changed and why, and the next action. The bridge adds repository, branch, commit, and tree identity and carries earlier decisions forward. Sends only this text, file names, and commit identity; never code. Needs no IDs. The first save in a repository also needs goal, and so does a save after the work moved on from the note's goal.",
     inputSchema: {
       type: "object",
       properties: {
         nextAction: { type: "string", description: "The one next action for the next agent." },
-        goal: { type: "string", description: "Required on the first save in a repository: one sentence on what the work is for. After that, only when the goal changed." },
+        goal: { type: "string", description: "Required on the first save in a repository: one sentence on what the work is for. After that, give it whenever the work moved on from the note's goal (a new file, feature, or task); a new goal clears the old goal's completed, unverified, and blocker lines unless you restate them." },
         decisions: {
           type: "array",
           description: "Only decisions that changed or are new. Leave out decisions that still hold.",

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.1.2";
+export const CLI_VERSION = "0.1.4";
 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/hooks/index.mjs

@@ -53,7 +53,8 @@ function sealRequest(firstHandoff) {
   return [
     "Hypher: the working tree changed since the last handoff, and no one saved why.",
     "Before you stop, record the decisions that changed and the next action for the next agent:",
-    `run \`hypher seal${goal} --decision "<a decision that changed>" --why "<why>" --next "<the next action>"\` in the terminal, or call the \`seal\` tool of the hypher MCP server with the same fields.`,
+    `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 \"…\").",
     "Add one --decision/--why pair per changed decision (--replaces D1 names one it replaces), or none if no decision changed; --next is always needed.",
     "It sends only your text, file names, and commit identity. Hypher asks once; if you cannot save now, say so and stop.",
   ].join(" ");

package/vendor/handoffNote.mjs

@@ -66,7 +66,12 @@ export function describeVerdict(verdict) {
             if (verdict.filesUnavailable)
                 return `Tree: same commit, edited since the handoff${since}${branch}.`;
             return `Tree: matches the handoff except files edited since: ${fileList(verdict.files) || "none named"}${branch}.`;
+        case "rewritten":
+            return `Tree: the history changed since the handoff (an amend, rebase, squash, or reset), but every edit it made is still here${since || "; nothing else changed"}${branch}.`;
         case "behind":
+            if (verdict.commitMissing && verdict.shallow) {
+                return `Tree: the handoff's commit is not in this shallow clone; run \`git fetch --unshallow\` first${branch}. ${STOP}`;
+            }
             return verdict.commitMissing
                 ? `Tree: the handoff's commit is not in this clone; fetch first${branch}. ${STOP}`
                 : `Tree: behind the handoff by ${plural(verdict.behind ?? 0, "commit")}${branch}. ${STOP}`;

package/vendor/handoffSeal.mjs

@@ -71,7 +71,8 @@ export function buildSealProposal(input) {
     const nextAction = clean(seal.nextAction);
     if (!nextAction)
         return { ok: false, error: "The next action is required: nextAction (in a shell, --next \"…\")." };
-    const goal = clean(seal.goal) || prior?.goal || "";
+    const newGoal = clean(seal.goal);
+    const goal = newGoal || prior?.goal || "";
     if (!goal)
         return { ok: false, error: "The first handoff in this repository needs a goal: one sentence on what the work is for. Pass goal (in a shell, --goal \"…\") and save again." };
     const sessionSource = { ref: clean(input.sessionRef).slice(0, 280), kind: "agent_report" };
@@ -124,7 +125,11 @@ export function buildSealProposal(input) {
     if (constraints.length > MAX_HANDOFF_ITEMS) {
         return { ok: false, error: tooMany("constraints", constraints.length, "Constraints are only added here; ask the builder which one to retire.") };
     }
-    const listOrPrior = (value, fallback) => cleanList(value) ?? fallback;
+    // A new goal is new work: the old goal's completed, unverified, and blocker lines do not
+    // carry over unless this save restates them (first Mac re-run, October 8, 2026: a CHANGELOG
+    // save kept "finish CONTRIBUTING.md" and its stale lines). Decisions and constraints still carry.
+    const goalChanged = Boolean(prior && newGoal && newGoal !== prior.goal);
+    const listOrPrior = (value, fallback) => cleanList(value) ?? (goalChanged ? [] : fallback);
     const proposal = {
         schemaVersion: HANDOFF_PROPOSAL_SCHEMA_VERSION,
         goal,

package/vendor/hypher-git.mjs

@@ -18,15 +18,16 @@ export const TREE_TIMEOUT_MS = 60_000;
  * Run git and return stdout (trimmed unless `trim` is false), or null when git fails or times out.
  * @param {string | undefined} cwd
  * @param {string[]} args
- * @param {{ env?: Record<string, string>, timeoutMs?: number, trim?: boolean }} [options]
+ * @param {{ env?: Record<string, string>, timeoutMs?: number, trim?: boolean, input?: string }} [options]
  * @returns {string | null}
  */
-export function git(cwd, args, { env, timeoutMs = GIT_TIMEOUT_MS, trim = true } = {}) {
+export function git(cwd, args, { env, timeoutMs = GIT_TIMEOUT_MS, trim = true, input } = {}) {
   try {
     const out = execFileSync("git", args, {
       encoding: "utf8",
       timeout: timeoutMs,
-      stdio: ["ignore", "pipe", "ignore"],
+      stdio: [input === undefined ? "ignore" : "pipe", "pipe", "ignore"],
+      ...(input === undefined ? {} : { input }),
       ...(cwd ? { cwd } : {}),
       ...(env ? { env: { ...process.env, ...env } } : {}),
     });
@@ -52,7 +53,8 @@ export function normalizeGitHubRepo(input) {
     value = sshMatch[1];
   } else if (/github\.com/i.test(value)) {
     try {
-      const url = new URL(value.startsWith("http") ? value : `https://${value.replace(/^git\+/, "")}`);
+      // Any scheme (ssh://, git+https://, git://) parses as https; only the path matters.
+      const url = new URL(`https://${value.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "")}`);
       const parts = url.pathname.split("/").filter(Boolean);
       if (parts.length >= 2) {
         value = `${parts[0]}/${parts[1]}`;
@@ -284,6 +286,13 @@ export function commitRelation(cwd, saved, current) {
   return { relation, ahead, behind };
 }
 
+/** The best common ancestor of two commits, or null when unknown or unrelated. */
+export function mergeBase(cwd, a, b) {
+  const from = commitSha(cwd, a);
+  const to = commitSha(cwd, b);
+  return from && to ? git(cwd, ["merge-base", from, to]) || null : null;
+}
+
 /** Tree of a commit, or null. */
 export function commitTree(cwd, rev) {
   const sha = commitSha(cwd, rev);
@@ -371,7 +380,38 @@ export function remotesExposingHypherRefs(cwd) {
 }
 
 /**
- * @typedef {"identical" | "committed-since" | "ahead" | "edited-since" | "behind" | "diverged" | "wrong-repository"} VerdictKind
+ * Whether every edit the handoff made is still in the working tree, after an
+ * amend, squash, rebase, squash-merge, or soft reset took its commit out of
+ * this branch's history. The handoff's edits are the paths its tree changed
+ * from the commit where its history and this one meet. A path changed on both
+ * sides counts as kept when the handoff's own hunks are still in it (its patch
+ * applies in reverse to the working tree; nothing is written). Null when it
+ * cannot tell: a commit or tree is missing, or the histories share no commit.
+ * @param {string} cwd Work tree top level.
+ * @param {{ savedCommit: string, savedTree: string | null, currentCommit: string | null, currentTree: string | null }} input
+ * @returns {boolean | null}
+ */
+export function handoffEditsKept(cwd, { savedCommit, savedTree, currentCommit, currentTree }) {
+  if (!savedTree || !currentTree) return null;
+  if (savedTree === currentTree) return true;
+  if (!hasObject(cwd, savedTree) || !hasObject(cwd, currentTree)) return null;
+  const base = currentCommit ? mergeBase(cwd, savedCommit, currentCommit) : null;
+  const baseTree = base ? commitTree(cwd, base) : null;
+  if (!baseTree) return null;
+  const edits = changedPathsBetweenTrees(cwd, baseTree, savedTree);
+  const since = changedPathsBetweenTrees(cwd, savedTree, currentTree);
+  if (!edits || !since) return null;
+  const changedSince = new Set(since);
+  const overlap = edits.filter((file) => changedSince.has(file));
+  if (overlap.length === 0) return true;
+  const patch = git(cwd, ["diff-tree", "-p", "--binary", "--no-renames", baseTree, savedTree, "--", ...overlap.map((file) => `:(literal)${file}`)],
+    { trim: false });
+  if (!patch) return null;
+  return git(cwd, ["apply", "--check", "--reverse", "-"], { input: patch }) !== null;
+}
+
+/**
+ * @typedef {"identical" | "committed-since" | "ahead" | "edited-since" | "rewritten" | "behind" | "diverged" | "wrong-repository"} VerdictKind
  * @typedef {object} TruthVerdict
  * @property {VerdictKind} kind
  * @property {boolean} stop Only behind, diverged, and wrong-repository stop the agent.
@@ -380,6 +420,7 @@ export function remotesExposingHypherRefs(cwd) {
  * @property {string[]} [files] Paths changed since the handoff tree.
  * @property {boolean} [filesUnavailable] The handoff tree is not on this machine.
  * @property {boolean} [commitMissing] The handoff commit is not in this clone.
+ * @property {boolean} [shallow] This clone is shallow, so the commit may be beyond its history.
  * @property {string} [branchNote] The current branch differs from the handoff's.
  * @property {{ repository: string | null, branch: string | null, commit: string | null, tree: string | null }} current
  */
@@ -410,14 +451,22 @@ export function truthCheck(cwd, saved) {
   const savedTree = fingerprint ?? (saved.dirty ? null : commitTree(cwd, saved.commit));
   const relation = commitRelation(cwd, saved.commit, commit ?? "");
   if (relation.relation === "unknown") {
-    return { kind: "behind", stop: true, behind: 0, commitMissing: true, ...base };
+    const shallow = git(cwd, ["rev-parse", "--is-shallow-repository"]) === "true";
+    return { kind: "behind", stop: true, behind: 0, commitMissing: true, ...(shallow ? { shallow } : {}), ...base };
+  }
+  const files = savedTree && tree ? changedPathsBetweenTrees(cwd, savedTree, tree) : null;
+  const detail = files === null ? { filesUnavailable: true } : { files };
+  if (relation.relation === "behind" || relation.relation === "diverged") {
+    // History moved under the handoff. Stop only when one of its edits is gone.
+    const root = git(cwd, ["rev-parse", "--show-toplevel"]) || cwd;
+    if (handoffEditsKept(root, { savedCommit: saved.commit, savedTree, currentCommit: commit, currentTree: tree }) === true) {
+      return { kind: "rewritten", stop: false, ahead: relation.ahead ?? 0, behind: relation.behind ?? 0, ...detail, ...base };
+    }
   }
   if (relation.relation === "behind") return { kind: "behind", stop: true, behind: relation.behind ?? 0, ...base };
   if (relation.relation === "diverged") {
     return { kind: "diverged", stop: true, ahead: relation.ahead ?? 0, behind: relation.behind ?? 0, ...base };
   }
-  const files = savedTree && tree ? changedPathsBetweenTrees(cwd, savedTree, tree) : null;
-  const detail = files === null ? { filesUnavailable: true } : { files };
   if (relation.relation === "same") {
     if (savedTree && tree && savedTree === tree) return { kind: "identical", stop: false, ...base };
     return { kind: "edited-since", stop: false, ...detail, ...base };