hypomnema 1.8.2 → 1.9.0

package/hooks/hypo-stop.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * hypo-stop.mjs: the ONLY Stop hook registered in hooks/hooks.json.
+ *
+ * Claude Code runs every hook matched by an event in PARALLEL. Stop used to
+ * carry four separate registrations (hot-rebuild, session-record, auto-commit,
+ * auto-minimal-crystallize), so the order they ran in was whatever the four
+ * processes happened to reach first. hypo-hot-rebuild.mjs was written against
+ * an order it did not have: it writes root hot.md and log.md and only THEN
+ * claims those paths into the session's touched-paths set, and hypo-auto-commit
+ * could take the vault lock in between and commit without them. The rebuild
+ * still succeeded, so no health notice fired either, and the fresh bytes just
+ * sat uncommitted.
+ *
+ * One registration, four stages, run in order. The order is the contract now,
+ * and STAGES below is the only place it is written down.
+ *
+ * Stages are spawned as child processes, not imported as functions. Each of the
+ * four is a standalone script whose work happens at module top level: it reads
+ * the hook payload off its own stdin and prints one hook-protocol JSON object to
+ * its own stdout. Importing them would mean rewriting all four into exported
+ * functions (auto-minimal-crystallize alone is ~300 lines of top-level decision
+ * flow) and would put four sets of module state, and any process.exit or throw,
+ * inside one process. A child per stage costs four Node startups, roughly 50ms
+ * each against a 110s budget, and buys back the property serialization would
+ * otherwise cost: a stage that dies, hangs, or writes garbage cannot take the
+ * rest of the chain with it. That was free when the four ran in parallel, and
+ * this is what keeps it.
+ *
+ * Node built-ins only (architecture invariant: hooks never import from
+ * scripts/, and a hook's own directory is the only place it may reach).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HOOKS_DIR = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The Stop chain, in the order it must run.
+ *
+ * - hot-rebuild first: it writes root hot.md and log.md and claims them into
+ *   the session's touched-paths set, which is the scope auto-commit later
+ *   commits. Anything that runs before it contributes nothing to that scope.
+ * - session-record next: it only appends to a gitignored cache file, so its
+ *   position is free; it sits here because it is cheap and cannot fail the
+ *   ones after it.
+ * - auto-commit third: it has to see everything the two above claimed.
+ * - auto-minimal-crystallize last: it is the only stage that can emit
+ *   `decision: "block"`, and its close gate reads the committed state the
+ *   stage before it produced.
+ *
+ * `timeoutMs` is each stage's own share of the budget, enforced here rather
+ * than by the single hooks.json timeout. Serializing four hooks under one
+ * registration makes one registration's timeout the ceiling for all four, so
+ * without a per-stage kill a single hung stage would eat the whole budget and
+ * the stages after it would never run at all. The values are the per-hook
+ * timeouts these four carried in hooks.json before the merge, unchanged.
+ */
+const STAGES = [
+  { file: 'hypo-hot-rebuild.mjs', timeoutMs: 30000 },
+  { file: 'hypo-session-record.mjs', timeoutMs: 10000 },
+  { file: 'hypo-auto-commit.mjs', timeoutMs: 60000 },
+  { file: 'hypo-auto-minimal-crystallize.mjs', timeoutMs: 10000 },
+];
+
+/**
+ * A stage's hook-protocol object, or null when it printed nothing usable.
+ *
+ * The last non-empty line, not the whole stream: a stage is free to write
+ * diagnostics before its result (none do today), and the protocol object is
+ * always the last thing out. A parse failure is null, which the caller treats
+ * as "this stage said nothing", never as a reason to stop the chain.
+ *
+ * @param {string} stdout
+ * @returns {object|null}
+ */
+function parseStageOutput(stdout) {
+  const lines = String(stdout || '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  if (lines.length === 0) return null;
+  try {
+    const parsed = JSON.parse(lines[lines.length - 1]);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * How a stage failed to finish normally, in words a person can act on, or null
+ * when it exited 0. `error` is a spawn failure or the per-stage timeout (Node
+ * reports the kill as ETIMEDOUT); `signal` without a timeout is a death from
+ * outside, such as an OOM kill.
+ *
+ * @param {{file: string, timeoutMs: number}} stage
+ * @param {{error?: Error, status: number|null, signal: string|null}} res
+ * @returns {string|null}
+ */
+function stageFailure(stage, res) {
+  if (res.error?.code === 'ETIMEDOUT') return `${stage.file} timed out after ${stage.timeoutMs}ms`;
+  if (res.error) return `${stage.file} failed to run: ${res.error.message ?? String(res.error)}`;
+  if (res.signal) return `${stage.file} was killed by ${res.signal}`;
+  if (res.status !== 0) return `${stage.file} exited ${res.status}`;
+  return null;
+}
+
+let raw = '';
+try {
+  raw = await new Promise((resolve) => {
+    let d = '';
+    process.stdin.on('data', (c) => (d += c));
+    process.stdin.on('end', () => resolve(d));
+  });
+} catch {
+  raw = '';
+}
+
+// The merged reply. The hook protocol gives one JSON object per registration,
+// so four stage replies have to collapse into one:
+//   - systemMessage: every non-empty one, joined. Dropping any would silence a
+//     stage that has something to tell the user.
+//   - suppressOutput: true only while nothing wants to be seen. One stage
+//     asking for output, or contributing a systemMessage, turns it off.
+//   - continue / decision: the first stage that says "do not continue" ends the
+//     chain (see the loop).
+const messages = [];
+// Stages that did not finish normally. The chain still runs past them (see the
+// fail-open note in the loop), but the reply must not read as a clean Stop:
+// hot-rebuild dying after its rename and before it claims the path leaves a
+// changed, uncommitted hot.md, and stderr alone is not something a person
+// sees. So each one is also named in systemMessage, which turns suppressOutput
+// off. Not a `decision: "block"`: a transient timeout would then keep the
+// session from ending, over and over.
+const failures = [];
+let suppressOutput = true;
+let blocked = null;
+let halted = null;
+
+for (const stage of STAGES) {
+  let res;
+  try {
+    res = spawnSync(process.execPath, [join(HOOKS_DIR, stage.file)], {
+      input: raw,
+      encoding: 'utf-8',
+      timeout: stage.timeoutMs,
+    });
+  } catch (err) {
+    process.stderr.write(`[hypo-stop] error: ${stage.file}: ${err?.message ?? String(err)}\n`);
+    failures.push(`${stage.file} failed to run: ${err?.message ?? String(err)}`);
+    continue;
+  }
+  if (res.stderr) process.stderr.write(res.stderr);
+  // Fail-open, deliberately, and this is the decision serialization would
+  // otherwise reverse. In parallel, a stage that crashed or hung took nothing
+  // with it; in a chain, "abort on a non-zero exit" would let a hot-rebuild
+  // crash cancel the commit that saves the session's work. So a stage that
+  // exits non-zero, gets killed at its timeout, or prints unparseable output is
+  // logged, reported in the reply, and skipped, and the chain moves on. The
+  // ONLY thing that ends the chain early is a stage explicitly asking for it
+  // through the protocol.
+  const failure = stageFailure(stage, res);
+  if (failure) {
+    process.stderr.write(`[hypo-stop] error: ${failure}\n`);
+    failures.push(failure);
+  }
+
+  const out = parseStageOutput(res.stdout);
+  if (!out) continue;
+
+  if (typeof out.systemMessage === 'string' && out.systemMessage.length > 0) {
+    messages.push(out.systemMessage);
+  }
+  if (out.suppressOutput === false) suppressOutput = false;
+
+  if (out.decision === 'block') {
+    // Only auto-minimal-crystallize emits this today, and it is last, so
+    // nothing is actually cut short. The rule still has to be written down: a
+    // block means Claude is not allowed to stop, and the protocol carries one
+    // reason, so a later stage's reply would either be discarded or have to be
+    // merged into a decision that is not a merge.
+    blocked = { reason: out.reason, stopReason: out.stopReason };
+    break;
+  }
+  if (out.continue === false) {
+    halted = { stopReason: out.stopReason };
+    break;
+  }
+}
+
+if (failures.length > 0) {
+  messages.push(
+    `[hypo-stop] Stop step(s) did not finish normally: ${failures.join('; ')}. ` +
+      'Their work may be partly on disk and uncommitted; the steps after them still ran.',
+  );
+}
+
+const reply = blocked
+  ? { decision: 'block', reason: blocked.reason, stopReason: blocked.stopReason }
+  : { continue: !halted, suppressOutput: suppressOutput && messages.length === 0 };
+if (!blocked && halted && halted.stopReason) reply.stopReason = halted.stopReason;
+if (messages.length > 0) reply.systemMessage = messages.join('\n');
+
+console.log(JSON.stringify(reply));

package/hooks/proposal-store.mjs

@@ -4,7 +4,7 @@
 // SessionStart-chain hook (T8's session-start surface) counts pending proposals,
 // so the store must sit where a hook can import it without reaching up into
 // scripts/. scripts/ (crystallize, the T7 CLI) already imports from hooks/, never
-// the reverse. Registered in hooks.json `shared` alongside base-store.
+// the reverse. Registered in hooks/shared.json alongside base-store.
 //
 // When crystallize's close path finds that an OVERWRITE target drifted away from
 // the base this session observed at start, it withholds the bytes rather than
@@ -45,17 +45,9 @@
 // fatal) and atomic on the write side (tmp+rename), mirroring base-store.
 
 import { createHash } from 'node:crypto';
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-  renameSync,
-  readdirSync,
-  unlinkSync,
-  realpathSync,
-} from 'node:fs';
+import { existsSync, readFileSync, readdirSync, unlinkSync, realpathSync, statSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
+import { atomicWrite } from './atomic-write.mjs';
 
 /** `<hypoDir>/.cache/proposals/`. */
 export function proposalsDir(hypoDir) {
@@ -132,14 +124,6 @@ export function makeProposalId(createdAt, target) {
   return `${ts}-${slugTarget(target)}-${rand}`;
 }
 
-/** 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);
-}
-
 /**
  * Read+parse one artifact file by absolute path. Returns null when absent,
  * unreadable, or malformed (best-effort: a corrupt artifact must never crash a
@@ -157,11 +141,97 @@ function readArtifactFile(path) {
   }
 }
 
+/**
+ * Scan an already-`readdirSync`'d proposals dir once, splitting `.json` entries
+ * into parsed artifacts and everything readArtifactFile would not hand back.
+ * "Everything else" covers three cases indistinguishably (unreadable bytes, a
+ * body that is not the artifact shape, an id that does not match its own
+ * filename), so a caller that needs to tell those apart already has the
+ * filename in hand to go look. Shared by listProposals and
+ * listProposalsChecked so a directory is walked and each file parsed exactly
+ * once per call, not twice.
+ */
+// atomicWrite's OWN temp-file name (`<path>.<pid>.<rand>.tmp`; see
+// atomic-write.mjs), so a `.json.<pid>.<rand>.tmp` sitting in this store is
+// a completed artifact body whose rename never landed: the process that
+// wrote it died in the gap between `writeFileSync` and `renameSync`. That
+// gap holds real, already-serialized proposal bytes, not empty scratch
+// space, so a scan that only ever looked for `.json` names read a vault
+// with nothing BUT one of these as `parkedTotal: 0`, the same silent-zero
+// this file's own listProposalsChecked doc comment already warns about, just
+// reached through a different failure than a corrupt `.json`.
+const PROPOSAL_TMP_RE = /\.json\.\d+\.[a-z0-9]+\.tmp$/;
+// A live writer's tmp file looks identical to an orphan for the instant
+// between its own writeFileSync and renameSync, so only a tmp file idle
+// longer than this counts as unfinished. writeProposal's write is a single
+// synchronous JSON.stringify + one syscall pair, so anything past a few
+// seconds is already generous; a full minute gives slow disks and CI
+// runners headroom without leaving a real crash unreported for long.
+const PROPOSAL_TMP_GRACE_MS = 60_000;
+
+/**
+ * The filename an orphan tmp's body would have landed at if its rename had
+ * finished. Shared with `checkProposals` (doctor.mjs) so its recovery hint
+ * names the same target this store would have produced, rather than a second
+ * copy of PROPOSAL_TMP_RE's suffix that could drift from this one.
+ */
+export function orphanTmpTargetName(name) {
+  return name.replace(PROPOSAL_TMP_RE, '.json');
+}
+
+function scanProposalFiles(dir, names) {
+  const proposals = [];
+  const unreadable = [];
+  // Subset of `unreadable`: filenames that matched PROPOSAL_TMP_RE past the
+  // grace period. A caller keeping only `unreadable` cannot tell a corrupt
+  // artifact from a complete proposal body whose rename never landed, and the
+  // two have different fixes (discard vs. `mv` back to its `.json` name).
+  // Kept as an ADDITIONAL array rather than removed from `unreadable`, so the
+  // existing `unreadable.length` contract (what `--json` consumers already
+  // parse) does not shrink out from under them; a name can legitimately sit
+  // in both.
+  const orphanTmp = [];
+  for (const name of names) {
+    if (PROPOSAL_TMP_RE.test(name)) {
+      let stale = true;
+      try {
+        stale = Date.now() - statSync(join(dir, name)).mtimeMs > PROPOSAL_TMP_GRACE_MS;
+      } catch {
+        stale = false; // vanished mid-scan: the writer's own rename just landed, not an orphan
+      }
+      if (stale) {
+        unreadable.push(name);
+        orphanTmp.push(name);
+      }
+      continue;
+    }
+    if (!name.endsWith('.json')) continue;
+    const path = join(dir, name);
+    const parsed = readArtifactFile(path);
+    // A well-formed artifact's `id` field equals its filename stem and is itself
+    // id-safe. A mismatch means the body was hand-edited or corrupt; trusting its
+    // `id` would let a spoofed value drive supersede or T7 apply against the wrong
+    // file, so skip it (it stays on disk but is never acted on).
+    if (parsed && isValidProposalId(parsed.id) && parsed.id === name.slice(0, -'.json'.length)) {
+      proposals.push({ ...parsed, _path: path });
+    } else {
+      unreadable.push(name);
+    }
+  }
+  return { proposals, unreadable, orphanTmp };
+}
+
 /**
  * List parked proposals, newest artifacts included, malformed ones skipped.
  * Each entry is the parsed body plus `_path` (absolute) so callers (the T7 CLI)
  * can act on the exact file without re-deriving the path.
  *
+ * A file this could not parse is silently absent from the result, same as
+ * before: every existing caller here acts on whatever IS readable and treats
+ * one bad artifact as no reason to fail a supersede scan or a T7 listing. A
+ * caller that needs to know a bad file exists at all, rather than just not
+ * see it, wants listProposalsChecked below, not this.
+ *
  * @returns {Array<object>} parsed artifacts; empty when the dir is absent/empty
  */
 export function listProposals(hypoDir) {
@@ -173,20 +243,64 @@ export function listProposals(hypoDir) {
   } catch {
     return [];
   }
-  const out = [];
-  for (const name of names) {
-    if (!name.endsWith('.json')) continue;
-    const path = join(dir, name);
-    const parsed = readArtifactFile(path);
-    // A well-formed artifact's `id` field equals its filename stem and is itself
-    // id-safe. A mismatch means the body was hand-edited or corrupt; trusting its
-    // `id` would let a spoofed value drive supersede or T7 apply against the wrong
-    // file, so skip it (it stays on disk but is never acted on).
-    if (parsed && isValidProposalId(parsed.id) && parsed.id === name.slice(0, -'.json'.length)) {
-      out.push({ ...parsed, _path: path });
-    }
+  return scanProposalFiles(dir, names).proposals;
+}
+
+/**
+ * Same enumeration as listProposals, but keeps THREE states apart that all
+ * look like "nothing to review" from a bare count: an absent store (zero
+ * proposals were ever parked, `ok: true, proposals: [], unreadable: []`); a
+ * `readdirSync` failure on the store itself, permissions or a file sitting
+ * where the directory should be (the count is unmeasured, not zero, `ok:
+ * false`); and, the gap this once shared with listProposals, a `.json`
+ * candidate that sat right there in a perfectly listable directory but came
+ * back corrupt, permission-denied, or hand-edited into an unrecognizable
+ * shape. That third case used to fold into the same `[]` listProposals
+ * returns for "no proposals", so a vault with one chmod-000 artifact and zero
+ * readable ones reported `parkedTotal: 0` with no line of output anywhere
+ * naming the file: a silent success over a backlog that was never actually
+ * empty. `unreadable` is exactly those filenames (relative, `.json`
+ * included), so a caller can print "N candidate(s) unreadable, run doctor" even
+ * when the readable count is zero.
+ *
+ * listProposals above still gates on `existsSync` and stays fail-open on ANY
+ * stat or readdir failure: every one of its callers (the supersede scan in
+ * writeProposal, the T7 CLI's ordinary listing) wants "proposals I can act on
+ * right now", never a three-way judgment, and none of them has anywhere to
+ * put an `ok: false`. This function exists because `checkProposals` and the
+ * close report DO have somewhere to put it, and folding "could not tell" into
+ * "empty" is exactly the silent-zero this file's own docblock warns about.
+ * `existsSync` cannot make that call: it returns false for every stat
+ * failure, not just ENOENT, so it cannot tell "never created" apart from
+ * "could not be examined" (see the errno check below).
+ *
+ * @returns {{ok: boolean, proposals: object[], unreadable: string[], orphanTmp: string[]}}
+ *   `orphanTmp` is the subset of `unreadable` whose rename never landed (see
+ *   `orphanTmpTargetName`): a complete proposal body, recoverable with `mv`,
+ *   not a corrupt file to discard.
+ */
+export function listProposalsChecked(hypoDir) {
+  const dir = proposalsDir(hypoDir);
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (e) {
+    // ENOENT is the only errno that means "no store was ever created" (zero
+    // proposals, ok: true). Every other errno (EACCES, ENOTDIR when a file
+    // sits where the directory should be, ELOOP, ...) means the store could
+    // not be examined at all, so the count is unmeasured, not zero.
+    //
+    // Cost accepted: a vault that has never parked anything now throws and
+    // catches one ENOENT on every listProposalsChecked call, instead of the
+    // existsSync precheck this replaced. In exchange, there is no longer a
+    // window between "does it exist" and "list it" where the directory could
+    // change underneath the two calls, and a real access failure can no
+    // longer masquerade as "never created".
+    if (e && e.code === 'ENOENT') return { ok: true, proposals: [], unreadable: [], orphanTmp: [] };
+    return { ok: false, proposals: [], unreadable: [], orphanTmp: [] };
   }
-  return out;
+  const { proposals, unreadable, orphanTmp } = scanProposalFiles(dir, names);
+  return { ok: true, proposals, unreadable, orphanTmp };
 }
 
 /**
@@ -228,13 +342,37 @@ export function deleteProposal(hypoDir, id) {
  * @param {string} fields.sessionId owning session
  * @param {string} fields.device machine identifier (crystallize passes currentDevice())
  * @param {string} [fields.createdAt] ISO timestamp; defaults to now
+ * @param {string} [fields.parkReason] human-readable cause of the park (crystallize's
+ *   conflictWhy(c)) — this is the artifact's own copy of the same string a `--json`
+ *   close now also puts in that close's conflicts[].why, kept here because the T7
+ *   CLI's list/apply/discard/challenge/resolve actions read only the artifact and
+ *   never that close's own stdout. Additive: absent on artifacts written before this
+ *   field existed, and every reader (this module's own readArtifactFile, and the T7
+ *   CLI's actions above) treats an absent value as "no cause recorded", never as
+ *   malformed — none of them requires this key to be present.
+ * @param {string[]} [fields.lostSections] the `##` headings a section-loss park
+ *   dropped (crystallize-close-apply.mjs's sectionLossReason). Present only when
+ *   `parkReason` names that cause; omitted for every other park reason, same as
+ *   `diskSectionCount` below.
+ * @param {number} [fields.diskSectionCount] how many `##` headings disk had at
+ *   park time, alongside `lostSections`.
  * @returns {{id: string, target: string, path: string, supersedeWarnings: string[]}}
  *   `supersedeWarnings` is non-empty only when the new artifact WAS written but an
  *   older same-target sibling could not be removed — a non-fatal condition (the
  *   payload is parked), reported separately from a write failure (which throws).
  */
 export function writeProposal(hypoDir, fields) {
-  const { target, baseHash, currentAtProposalHash, proposedContent, sessionId, device } = fields;
+  const {
+    target,
+    baseHash,
+    currentAtProposalHash,
+    proposedContent,
+    sessionId,
+    device,
+    parkReason,
+    lostSections,
+    diskSectionCount,
+  } = fields;
   const createdAt = fields.createdAt || new Date().toISOString();
 
   // Match on the parsed `target` field, never on the filename slug: two distinct
@@ -266,6 +404,16 @@ export function writeProposal(hypoDir, fields) {
     sessionId: sessionId != null ? String(sessionId) : null,
     device: device != null ? String(device) : null,
     createdAt,
+    // Additive fields (see this function's own doc comment): omitted rather
+    // than stored as `null` when the caller does not pass them, so an artifact
+    // written before this field existed and one written by a caller that
+    // genuinely has no cause to report look identical on disk — both simply
+    // lack the key, and every reader already treats an absent key as "not
+    // recorded", never as a malformed body (readArtifactFile only requires
+    // `id` and `target`; nothing here reads these three as mandatory).
+    ...(parkReason != null ? { parkReason: String(parkReason) } : {}),
+    ...(Array.isArray(lostSections) ? { lostSections } : {}),
+    ...(typeof diskSectionCount === 'number' ? { diskSectionCount } : {}),
   };
   // Write the new artifact DURABLY before removing the old one: a crash in the
   // gap leaves a stale sibling (superseded next close), never a lost payload.
@@ -412,9 +560,13 @@ function sessionChallengeFiles(hypoDir, sessionId) {
  * un-superseded old nonce would be a second, unreviewed key to the same write).
  *
  * @param {string} hypoDir
- * @param {{nonce: string, sessionId: string, mintedAt: string,
+ * @param {{nonce: string, sessionId: string, closeSessionId?: string, mintedAt: string,
  *          items: Array<{id: string, target: string, proposedHash: string,
  *                        freshness: {state: 'hash'|'absent', hash: string|null}}>}} record
+ *   `closeSessionId` is the session whose close this batch resumes, which the CALLER
+ *   is running challenge FROM when the two differ (a later session finishing a park
+ *   an earlier, possibly gone, session left behind). Optional and additive: a caller
+ *   that omits it is read as "resumes its own session" (see readChallenge).
  * @returns {string|null} the artifact path, or null when the session id is unsafe
  */
 export function writeChallenge(hypoDir, record) {
@@ -475,7 +627,21 @@ export function readChallenge(hypoDir, sessionId) {
       if (!f || (f.state !== 'hash' && f.state !== 'absent')) return null;
       if (f.state === 'hash' && typeof f.hash !== 'string') return null;
     }
-    return parsed;
+    // `closeSessionId` names the close this approval resumes, which can predate
+    // this field (see writeChallenge's doc comment). A record that carries it must
+    // carry a well-formed one: a hand-edited or malformed value here is a REMINT,
+    // the same polarity every other field in this record gets. But a record that
+    // never carried it (every challenge minted before this feature, or one minted
+    // without `--close-session-id`) is read as resuming its OWN session: the
+    // approving session and the parking session were always the same one before
+    // this existed, so treating "absent" as "same session" changes no existing
+    // behavior and needs no migration.
+    if (parsed.closeSessionId !== undefined) {
+      if (typeof parsed.closeSessionId !== 'string' || !isValidSessionId(parsed.closeSessionId)) {
+        return null;
+      }
+    }
+    return { ...parsed, closeSessionId: parsed.closeSessionId ?? sessionId };
   } catch {
     return null;
   }

package/hooks/shared.json

@@ -0,0 +1,15 @@
+[
+  "atomic-write.mjs",
+  "hypo-shared.mjs",
+  "version-check.mjs",
+  "version-check-fetch.mjs",
+  "base-store.mjs",
+  "proposal-store.mjs",
+  "close-gate-store.mjs",
+  "close-journal.mjs",
+  "hypo-hot-rebuild.mjs",
+  "hypo-session-record.mjs",
+  "hypo-auto-commit.mjs",
+  "hypo-auto-minimal-crystallize.mjs",
+  "close-receipt.mjs"
+]

package/hooks/version-check.mjs

@@ -18,7 +18,8 @@
  *     than overwrites so it never erases the hook's `notifiedFor` marks.
  */
 
-import { readFileSync, writeFileSync, renameSync, mkdirSync, realpathSync, existsSync } from 'fs';
+import { readFileSync, realpathSync, existsSync } from 'fs';
+import { atomicWrite } from './atomic-write.mjs';
 import { dirname, join, delimiter } from 'path';
 import { homedir } from 'os';
 
@@ -165,7 +166,7 @@ export function selectPluginVersion(plugins) {
  *
  *  Lives here because both hooks and scripts need it and the dependency only
  *  runs one way (scripts import hooks, never the reverse). This file is already
- *  in hooks.json's `shared` list, so it reaches every standalone install.
+ *  listed in hooks/shared.json, so it reaches every standalone install.
  *
  *  Use UPGRADE_APPLY_EITHER when the target channel is genuinely unknown, e.g.
  *  an instruction about a DIFFERENT machine. */
@@ -246,12 +247,13 @@ export function readCache(path) {
   }
 }
 
-/** Atomic write: tmp file in the same dir, then rename (last-writer-wins). */
+/** Atomic write: tmp file in the same dir, then rename (last-writer-wins).
+ * Delegates to the shared writer so a failure here cleans its temp file up.
+ * It did not before, and the callers below swallow errors, so every failure
+ * left a `<path>.<pid>.<rand>.tmp` nothing would ever pick up again. This is a
+ * per-session cache path, so those accumulated faster than anywhere else. */
 export function writeCacheAtomic(path, obj) {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
-  writeFileSync(tmp, JSON.stringify(obj, null, 2));
-  renameSync(tmp, path);
+  atomicWrite(path, JSON.stringify(obj, null, 2));
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",
@@ -39,6 +39,7 @@
     "scripts/lib/feedback-scope.mjs",
     "scripts/lib/frontmatter.mjs",
     "scripts/lib/git-hooks-dir.mjs",
+    "scripts/lib/hook-inventory.mjs",
     "scripts/lib/hypo-ignore.mjs",
     "scripts/lib/hypo-root.mjs",
     "scripts/lib/page-usage.mjs",
@@ -50,6 +51,7 @@
     "scripts/lib/schema-vocab.mjs",
     "scripts/lib/slug-resolver.mjs",
     "scripts/lib/template-schema-version.mjs",
+    "scripts/lib/time.mjs",
     "scripts/lib/wd-match.mjs",
     "scripts/lib/wikilink.mjs",
     "commands/",

package/scripts/crystallize.mjs

@@ -12,13 +12,13 @@
  * Options:
  *   --hypo-dir=<path>        Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
  *   --min-group=<n>          Min pages per tag group to report (default: 2)
- *   --check-session-close    Verify the strict session-close memory files — 5 mandatory + open-questions conditional
+ *   --check-session-close    Verify the strict session-close memory files: 4 mandatory + open-questions conditional
  *   --project=<slug>         Override the recency-inferred project on --check / --mark (single segment
  *                            [A-Za-z0-9._-]+, projects/<slug>/ must exist). On --check it NARROWS the
  *                            gate to that one project — a project-scoped diagnostic, NOT a global
  *                            compact-ready verdict. On --mark it is ATTRIBUTION only; the gate stays
  *                            global (the marker == compact-ready invariant). Ignored on --apply.
- *   --apply-session-close    Apply a JSON payload that updates the 5 mandatory memory files
+ *   --apply-session-close    Apply a JSON payload that updates the 4 mandatory memory files
  *                            (+ optional open-questions). Idempotent — re-running with the same
  *                            payload is a no-op. Always finishes with the strict gate check.
  *
@@ -40,7 +40,6 @@
  *     "date":         "YYYY-MM-DD",                   // optional — defaults to today (local)
  *     "sessionState": { "content": "<full file>" },   // overwrite (idempotent: identical bytes → skip)
  *     "projectHot":   { "content": "<full file>" },   // overwrite
- *     "rootHot":      { "content": "<full file>" },   // overwrite
  *     "sessionLog":   { "entry":   "## [date] ..." }, // append, skip if heading already present
  *     "log":          { "entry":   "## [date] session | <project> ..." }, // OPTIONAL (B-1): omit it and apply derives the root log.md entry from this close's sessionLog heading; supply it only for a deliberately custom log line
  *     "openQuestions":{ "content": "<full file>" }    // optional overwrite
@@ -53,7 +52,7 @@
  * Lint gates:
  *   • Preflight — runs `lint.mjs --json` BEFORE any payload byte is written.
  *     Errors in files this payload will OVERWRITE (sessionState/projectHot/
- *     rootHot/openQuestions) are filtered out — they're about to be replaced,
+ *     openQuestions) are filtered out: they're about to be replaced,
  *     and not filtering them dead-locks the documented "fix payload and retry"
  *     recovery after a post-apply-lint failure (codex P2). Errors in any other
  *     file → exit 1 with stage='preflight-lint', no apply occurs. PreCompact's