hypomnema 1.8.4 → 1.9.0

package/hooks/close-gate-store.mjs

@@ -32,9 +32,11 @@
 // own doc comment for the caller contract.
 
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { walkCloseGate } from './hypo-shared.mjs';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sessionClosedMarkerPath, walkCloseGate } from './hypo-shared.mjs';
+import { receiptPath } from './close-receipt.mjs';
+import { atomicWrite } from './atomic-write.mjs';
 
 /** `<hypoDir>/.cache/close-gate/<session-id>.json`. */
 export function closeGatePath(hypoDir, sessionId) {
@@ -121,14 +123,6 @@ export function resolutionStamp(rawTranscript, upToIndex = Infinity) {
   return { index, prefixSha };
 }
 
-/** Atomic overwrite via tmp+rename, mirroring base-store's atomicWrite. */
-function atomicWrite(path, content) {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
-  writeFileSync(tmp, content);
-  renameSync(tmp, path);
-}
-
 /**
  * Record that this session's close gate is resolved, at the point `stamp`
  * describes. Best-effort: a hook must never fail a close over a cache write,
@@ -382,20 +376,62 @@ export function readResolution(hypoDir, sessionId, rawTranscript) {
  * doing so.
  *
  * @param {{transcriptPath: string|null, hypoDir: string, sessionId: string|null}} args
- * @returns {{ok: boolean, open: boolean, reason: string|null}}
+ * @returns {{ok: boolean, open: boolean, reason: string|null, hostTagWarning?: string}}
+ *   `hostTagWarning` is present on any result whose gate reads OPEN and whose
+ *   `walkCloseGate` reported a `neutralizedHostTagName`: the close in effect
+ *   survived a HOST_TAG_NAMES-shaped queue item reading as neutral rather
+ *   than a retraction. Not gated on `ok`, because the two `ok: false` returns
+ *   below that still read open (transcript-rewrite-detected,
+ *   no-new-open-since-resolution) reach a caller which keeps going on the raw
+ *   `isCloseGateOpen` boolean (`runMarkSessionClosed`), and that caller needs
+ *   the same residual named. See the field's own doc comment in
+ *   hypo-shared.mjs for why that reading is accepted rather than closed on.
+ *   It states WHAT happened and nothing about undoing it: the undo differs per
+ *   entry point, so a caller pairs this with `hostTagWarningWithUndo` below
+ *   and surfaces the pair exactly once per run.
  */
 export function closeGateStatus({ transcriptPath, hypoDir, sessionId }) {
-  const { open, openedAtIndex } = walkCloseGate(transcriptPath ?? null);
+  const { open, openedAtIndex, retractedByUnknownTagName, neutralizedHostTagName } = walkCloseGate(
+    transcriptPath ?? null,
+  );
   if (!open) {
     return {
       ok: false,
       open: false,
       reason:
         'no-open: this session carries no close signal in its transcript yet — ' +
-        'ask the user whether they actually want to close before treating this as one.',
+        'ask the user whether they actually want to close before treating this as one.' +
+        // Names the retraction's shape when walkCloseGate found one. A tag
+        // shaped queue item only ever retracts here when it is NOT one of
+        // HOST_TAG_NAMES (a known host tag reads as neutral instead, see the
+        // enqueue-branch reversion note in hypo-shared.mjs), so this is
+        // always the "which tag to add" diagnostic, never a known tag
+        // retracting a close that was already judged expected.
+        (retractedByUnknownTagName
+          ? ` A queued item shaped like a host tag ("<${retractedByUnknownTagName}...>") retracted ` +
+            'the last close BECAUSE that tag is not in HOST_TAG_NAMES (hooks/hypo-shared.mjs). ' +
+            'That is fail-closed and applies even when the item itself reads like a close phrase: ' +
+            'an unregistered tag cannot be attributed to the host, so it counts as the user taking ' +
+            'the close back. If it is a genuine host notification rather than something the user ' +
+            'typed, add it to HOST_TAG_NAMES; until then the user has to confirm the close again.'
+          : ''),
     };
   }
 
+  // Computed once here, past the `!open` return above, so every return that
+  // still reads the gate as open can carry it without repeating the message.
+  // Not itself a reason to refuse anything: walkCloseGate already chose to
+  // read this shape as neutral, not a retraction (see its own doc comment).
+  // This is the one-time surfacing of the residual that reading accepts, and
+  // it stops at WHAT happened; see hostTagWarningWithUndo below for why the
+  // undo instructions are not baked in here.
+  const hostTagWarning = neutralizedHostTagName
+    ? `this close was granted while a queued item shaped like a known host tag ` +
+      `("<${neutralizedHostTagName}...>") stayed neutral instead of retracting it. If a person ` +
+      'typed or pasted that tag verbatim, rather than the host sending it, this close may not ' +
+      'reflect a decision the user actually made.'
+    : null;
+
   let rawTranscript = null;
   try {
     rawTranscript = transcriptPath ? readFileSync(transcriptPath) : null;
@@ -407,7 +443,7 @@ export function closeGateStatus({ transcriptPath, hypoDir, sessionId }) {
   if (closedAtIndex === null) {
     // NO_CONSTRAINT: no valid resolution record exists for this session, so
     // the open found above is unconstrained.
-    return { ok: true, open: true, reason: null };
+    return { ok: true, open: true, reason: null, ...(hostTagWarning ? { hostTagWarning } : {}) };
   }
   if (prefixMatches === false) {
     // Checked ahead of the index comparison on purpose, even though
@@ -421,10 +457,11 @@ export function closeGateStatus({ transcriptPath, hypoDir, sessionId }) {
         'transcript-rewrite-detected: the recorded resolution no longer matches this ' +
         "transcript's history — treat this session's prior resolution as untrustworthy " +
         'and confirm the close with the user again.',
+      ...(hostTagWarning ? { hostTagWarning } : {}),
     };
   }
   if (openedAtIndex >= closedAtIndex) {
-    return { ok: true, open: true, reason: null };
+    return { ok: true, open: true, reason: null, ...(hostTagWarning ? { hostTagWarning } : {}) };
   }
   return {
     ok: false,
@@ -432,5 +469,83 @@ export function closeGateStatus({ transcriptPath, hypoDir, sessionId }) {
     reason:
       'no-new-open-since-resolution: this session already resolved its last close signal — ' +
       'a fresh close phrase from the user is needed before this can pass again.',
+    ...(hostTagWarning ? { hostTagWarning } : {}),
   };
 }
+
+// The undo half of a `hostTagWarning`, which closeGateStatus deliberately
+// leaves out: what a run can actually take back differs by entry point, and a
+// message naming a commit the run never made sends the reader after nothing.
+// `kind` says what THIS run did:
+//   'commit-and-marker'   a close apply that committed and landed its marker
+//   'commit-only'         a close apply that committed, marker never landed
+//   'marker-only'         --mark-session-closed: a marker, no commit at all
+//   'uncommitted-writes'  bytes on disk, no commit and no marker
+// A null or unrecognized `kind` means the run left nothing to undo, and so
+// nothing to warn about either: the answer is null and the caller stays
+// quiet. `commitSha` is the commit hash for the two committing kinds
+// (commitWikiChanges returns it as `sha`); see the comment inside for what
+// each of its three states produces. The marker path is derived from
+// sessionClosedMarkerPath rather than
+// written out here, so it cannot drift from the file the writer actually
+// creates; an earlier version of this text hardcoded a `.cache/
+// session-closed-<id>.json` path that no writer has ever produced (the
+// `.json` under `.cache/close-gate/` is this file's own resolution record, a
+// different file), and the model relaying it sent users to delete something
+// that was not there.
+//
+// A close now also files a receipt (`hooks/close-receipt.mjs`) alongside the
+// compat marker, and deleting the marker alone would leave that receipt
+// standing: readReceiptStrict still reads it as valid, so a new Stop would
+// keep treating the session as closed even after the marker it was told to
+// delete is gone. Undo has to name both files or it does not actually undo
+// anything a receipt-aware reader honors. `commit-and-marker` and
+// `marker-only` are the two kinds whose write path always lands the receipt
+// BEFORE the marker, so by the time either kind's text
+// is composed the receipt is guaranteed to exist and the message just names
+// it. `commit-only` is the one kind where the receipt write and the marker
+// write can fail independently, so its wording checks the receipt path on
+// disk rather than assume either way.
+export function hostTagWarningWithUndo(warning, kind, hypoDir, sessionId, commitSha) {
+  if (!warning || !kind) return null;
+  const marker = sessionClosedMarkerPath(hypoDir, sessionId);
+  const receipt = receiptPath(hypoDir, sessionId);
+  // MAJOR fix: "git revert" with no target was an instruction a reader could
+  // only carry out by guessing, and the obvious guess (HEAD) is wrong the
+  // moment a concurrent session on the same vault commits after this one:
+  // reverting HEAD then undoes that session's work instead. `commitSha` is
+  // commitWikiChanges's own `sha` for the commit THIS close made, so the
+  // instruction names it. Three states, deliberately distinguished:
+  //   a string    that commit exists; name it in a runnable command
+  //   null        the commit was a no-op (`scoped: 0`), nothing to revert
+  //   undefined   the caller did not say, so say what is known and no more,
+  //               rather than inventing a target
+  const revert =
+    typeof commitSha === 'string' && commitSha
+      ? `revert the commit this close just made (\`git -C ${hypoDir} revert ${commitSha}\`)`
+      : commitSha === null
+        ? 'nothing needs reverting (this close changed no tracked file, so git created no commit)'
+        : `revert the commit this close just made in the wiki repo (find it with \`git -C ${hypoDir} log -1\` and check it is this close's own commit before reverting: on a shared vault another session may have committed after it)`;
+  // Named only when there is a valid receipt path to name at all (a bad
+  // session id has no receipt directory to file one under, same edge case
+  // `receiptPath` itself refuses). `both` reads naturally whether or not
+  // that path is reachable, so the two kinds below stay correct either way.
+  const both = receipt ? `${marker} and ${receipt}` : marker;
+  const undo = {
+    'commit-and-marker':
+      `To undo it: ${revert}, delete ` + `${both}, and ask the user whether they meant to close.`,
+    'commit-only':
+      `To undo it: ${revert} and ask the user whether they meant to close. No marker was ` +
+      'written, so there is none to delete.' +
+      (receipt && existsSync(receipt)
+        ? ` A close receipt landed at ${receipt} and should be deleted too.`
+        : ''),
+    'marker-only':
+      `To undo it: delete ${both} and ask the user whether they meant to close. This run wrote ` +
+      'no commit, so there is nothing to revert.',
+    'uncommitted-writes':
+      'Nothing to revert: this run made no commit and wrote no marker. The files it did write are ' +
+      'still uncommitted in the wiki working tree, so check git status there before closing again.',
+  }[kind];
+  return undo ? `${warning} ${undo}` : null;
+}

package/hooks/close-journal.mjs

@@ -28,22 +28,34 @@
 // NARROW what a retry is allowed to restage, never widen it — the same
 // direction close-gate-store's NO_CONSTRAINT keeps for its own file.
 
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWrite } from './atomic-write.mjs';
+import { isValidSessionId } from './proposal-store.mjs';
+import { withFileLock } from './hypo-shared.mjs';
 
-/** `<hypoDir>/.cache/close-journal/<sessionId>.json`. */
+/**
+ * `<hypoDir>/.cache/close-journal/<sessionId>.json`, or null when the id is not
+ * a shape that is safe to use as a filename.
+ *
+ * The check lives HERE, at the sink, not only at the CLI entry points that
+ * happen to call this today. Every entry point did validate, and the hole
+ * opened anyway the moment a new caller (reconcile) fed this an id read back
+ * out of `.cache/proposals/applied.log` rather than typed by a person: a
+ * `closeSessionId` of `../../../../../Users/<you>/.claude/settings` resolves
+ * clean out of the vault, and the caller then atomically overwrites whatever
+ * is there. Guarding each caller is what produced that gap; guarding the one
+ * place the string becomes a path is what closes it for callers not written yet.
+ *
+ * Returns null rather than throwing so the read path can keep treating an
+ * unusable journal as "nothing recorded", which is the direction it already
+ * fails in for a corrupt or absent file.
+ */
 export function closeJournalPath(hypoDir, sessionId) {
+  if (!isValidSessionId(sessionId)) return null;
   return join(hypoDir, '.cache', 'close-journal', `${sessionId}.json`);
 }
 
-/** Atomic overwrite via tmp+rename, mirroring close-gate-store's atomicWrite. */
-function atomicWrite(path, content) {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
-  writeFileSync(tmp, content);
-  renameSync(tmp, path);
-}
-
 /**
  * Read this session's journal. Absent, corrupt, or wrong-shaped reads as
  * `{}` — never partially trusted. A caller that widened a retry off a
@@ -56,7 +68,9 @@ function atomicWrite(path, content) {
 export function readJournal(hypoDir, sessionId) {
   if (!sessionId) return {};
   const path = closeJournalPath(hypoDir, sessionId);
-  if (!existsSync(path)) return {};
+  // An id that cannot be a filename has no journal, which reads the same as an
+  // absent one. Same direction this function already fails in.
+  if (path === null || !existsSync(path)) return {};
   try {
     const parsed = JSON.parse(readFileSync(path, 'utf-8'));
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
@@ -92,20 +106,119 @@ export function readJournal(hypoDir, sessionId) {
  *   `appliedPaths` / `commitWikiChanges`
  * @param {string} hash sha256 hex of the bytes just written (hashContent)
  */
+/**
+ * The read half of a read-modify-write, for callers that already hold the
+ * journal's lock. Public readJournal takes no lock: atomicWrite's rename means
+ * a reader sees one whole version or another, never a torn one. Re-entering the
+ * lock from inside it would deadlock the writers below.
+ */
+function readJournalAt(path) {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    if (parsed.v !== 1 || !parsed.paths || typeof parsed.paths !== 'object') return {};
+    const out = {};
+    for (const [k, v] of Object.entries(parsed.paths)) {
+      if (typeof k === 'string' && k && typeof v === 'string' && v) out[k] = v;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
 export function recordJournalEntry(hypoDir, sessionId, relPath, hash) {
   if (!sessionId) return;
+  const path = closeJournalPath(hypoDir, sessionId);
+  // Unusable id: nothing to record against, and nowhere safe to put it. This
+  // one is best-effort by contract, so it declines the same way it declines a
+  // failed write.
+  if (path === null) return;
   try {
-    const paths = readJournal(hypoDir, sessionId);
-    paths[relPath] = hash;
-    atomicWrite(
-      closeJournalPath(hypoDir, sessionId),
-      JSON.stringify({ v: 1, sessionId: String(sessionId), paths }, null, 2),
-    );
+    // Read-modify-write under the journal's own lock. atomicWrite already stops
+    // a reader seeing a torn file; what it cannot stop is two writers each
+    // reading the same `paths` and the second saving a copy that never had the
+    // first one's entry. Every mutator here takes the same lock, so they
+    // serialise against each other and against clearJournal.
+    withFileLock(path, () => {
+      const paths = readJournalAt(path);
+      paths[relPath] = hash;
+      atomicWrite(path, JSON.stringify({ v: 1, sessionId: String(sessionId), paths }, null, 2));
+    });
   } catch {
     // best-effort — see doc comment above
   }
 }
 
+/**
+ * Record ONE close handoff receipt: a target that a DIFFERENT session's
+ * approved `proposal resolve` just wrote, credited back to the close whose
+ * park produced it.
+ *
+ * Same on-disk shape as recordJournalEntry (readJournal reads either one the
+ * same way), but not best-effort. recordJournalEntry swallows a write
+ * failure on purpose: the bytes it describes were ALSO written by this same
+ * close's own overwrite step moments earlier, so a lost entry only costs a
+ * future retry its fast restage and falls back to the ordinary gate block,
+ * the safe direction to fail toward. A handoff receipt has no such fallback.
+ * The bytes it describes were written by a HUMAN approval in a possibly
+ * unrelated session, and the proposal artifact that once pointed at them is
+ * deleted the moment that write succeeds (the T7 CLI's writeApprovedProposal,
+ * step 12), so if this call fails silently, the owning close's retry can
+ * never find those bytes again by any means. The T7 CLI must see the failure
+ * and hold the artifact and audit entry instead of deleting them
+ * (`close-receipt-failed`), or the failure disappears along with the
+ * artifact.
+ *
+ * @param {string} hypoDir
+ * @param {string} closeSessionId the ORIGINATING close's session id, not the
+ *   session that approved the resolve. Legacy challenges/artifacts that
+ *   predate this field are read as this being the SAME session that resolved
+ *   them (see the T7 CLI), so this parameter is never called with
+ *   an empty value from that path.
+ * @param {string} relPath vault-relative path, exactly as it appears in the
+ *   proposal artifact's `target`
+ * @param {string} hash sha256 hex of the bytes just written, the SAME
+ *   hashContent() crystallize's own overwrite step hashes with (base-store.mjs),
+ *   so the retry's `journalHash === hashContent(disk)` comparison in
+ *   crystallize-close-apply.mjs trusts a receipt exactly as much as its own
+ *   same-session entries.
+ * @returns {{ok: true} | {ok: false, error: string}}
+ */
+export function recordHandoffReceipt(hypoDir, closeSessionId, relPath, hash) {
+  if (!closeSessionId) return { ok: false, error: 'no closeSessionId to journal against' };
+  const path = closeJournalPath(hypoDir, closeSessionId);
+  // Strict by contract, so an unusable id is a reported failure rather than a
+  // quiet decline. This is the call reconcile makes with an id it read out of
+  // the audit log, so it is the one that must not treat a hostile string as
+  // merely unlucky.
+  if (path === null) {
+    return {
+      ok: false,
+      error: `closeSessionId is not a usable session id: ${JSON.stringify(closeSessionId)}`,
+    };
+  }
+  try {
+    // Same lock as every other mutator. Without it, two resolves handing off to
+    // the same close, or a resolve racing that close's own clearJournal, could
+    // each return ok:true while one receipt silently vanished. The artifact is
+    // deleted the moment this returns ok, and reconcile only ever considers
+    // artifacts, so a lost receipt would have no way back.
+    withFileLock(path, () => {
+      const paths = readJournalAt(path);
+      paths[relPath] = hash;
+      atomicWrite(
+        path,
+        JSON.stringify({ v: 1, sessionId: String(closeSessionId), paths }, null, 2),
+      );
+    });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
 /**
  * Clear this session's journal once its close has actually committed. A
  * journal entry that outlives a successful commit would keep offering to
@@ -120,8 +233,17 @@ export function recordJournalEntry(hypoDir, sessionId, relPath, hash) {
  */
 export function clearJournal(hypoDir, sessionId) {
   if (!sessionId) return;
+  const path = closeJournalPath(hypoDir, sessionId);
+  // An id that never produced a path never produced a file to remove, and an
+  // rmSync on a traversed path would be the destructive half of the same hole.
+  if (path === null) return;
   try {
-    rmSync(closeJournalPath(hypoDir, sessionId), { force: true });
+    // Under the same lock: a clear landing between another writer's read and
+    // its save would be undone by that save, resurrecting a journal the close
+    // had already consumed.
+    withFileLock(path, () => {
+      rmSync(path, { force: true });
+    });
   } catch {
     // best-effort — see doc comment above
   }