hypomnema 1.8.2 → 1.8.4

package/hooks/hypo-shared.mjs

@@ -1953,7 +1953,21 @@ function atomicWriteShared(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);
+  try {
+    renameSync(tmp, path);
+  } catch (err) {
+    // The rename is what makes this atomic, so a failure here leaves the
+    // target untouched, which is the point. What it also leaves is the tmp
+    // file, and nothing else ever looks at that name again: the suffix
+    // carries this pid and a fresh random, so the next run picks a
+    // different one and this one sits in the vault forever, close after
+    // close. Take it back out before rethrowing, and do not let the
+    // cleanup hide the real error.
+    try {
+      rmSync(tmp, { force: true });
+    } catch {}
+    throw err;
+  }
 }
 
 // Read the pid the current holder recorded in its lockfile (see withFileLock).
@@ -3391,7 +3405,7 @@ export function normalizeVerifiedScope(verifiedScope) {
  * @param {{project?: string, scope?: string, transcript_path?: string, verifiedScope?: {kind: 'log-only'|'project'|'global', projects?: string[]}}} info
  */
 export function writeSessionClosedMarker(hypoDir, sessionId, info = {}) {
-  if (!sessionId) return;
+  if (!sessionId) return false;
   try {
     const cacheDir = join(hypoDir, '.cache');
     if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
@@ -3427,9 +3441,24 @@ export function writeSessionClosedMarker(hypoDir, sessionId, info = {}) {
       // doctor's reader treats "field absent" as "no additional scope check".
       ...(verifiedScope ? { verified_scope: verifiedScope } : {}),
     };
-    writeFileSync(sessionClosedMarkerPath(hypoDir, sessionId), JSON.stringify(payload) + '\n');
+    // Atomic, and it reports. Two reasons, and the caller needs both.
+    //
+    // A plain writeFileSync can leave a truncated file behind, and the reader
+    // below drops a marker it cannot parse. That combination turns one failed
+    // write into a session that can never close: the caller sees a file, calls
+    // the close signal spent, and the next Stop deletes the unparseable marker.
+    // temp+rename means the target is either the old bytes or the whole new
+    // ones, never half.
+    //
+    // And existsSync cannot answer the question the caller is really asking.
+    // "A marker file is there" is not "this run put it there" — a corrupt
+    // marker from an earlier attempt satisfies it just as well. So say whether
+    // THIS write landed and let the caller key on that.
+    atomicWriteShared(sessionClosedMarkerPath(hypoDir, sessionId), JSON.stringify(payload) + '\n');
+    return true;
   } catch (err) {
     process.stderr.write(`[hypo] session-closed marker write failed: ${err?.message || err}\n`);
+    return false;
   }
 }
 
@@ -4024,21 +4053,25 @@ export function precompactGateStatus(hypoDir, opts = {}) {
     }
   }
 
-  // 1. wiki git state. Uncommitted changes (real unsaved work) BLOCK, but only
-  //    the ones inside closeAccountableScope, and only when sessionTouchTrusted
-  //    (above) says that scope can actually be trusted: a session's own scoped
-  //    auto-commit (commitWikiChanges, PR #222) can leave the working tree
-  //    non-empty when a DIFFERENT session sharing this vault still has its own
-  //    file dirty, the 2026-08-03 multi-session block. That dirty file is
-  //    human-fixable by whoever owns it, not by this session, so it demotes to
-  //    a notice (listed by path, never silently dropped) instead of refusing
-  //    this session's marker. A dirty file THIS session owns still blocks
-  //    unconditionally (fail-closed is unchanged for scope this session
-  //    actually touched), and so does an unattributable state: a git failure
-  //    gitDirtyFiles can't enumerate (dirty.length === 0 despite
-  //    git.uncommitted === true), OR a scope we cannot trust
-  //    (!sessionTouchTrusted) both fall back to the original unscoped blocker:
-  //    "cannot attribute" is not "clean".
+  // 1. wiki git state. Uncommitted changes (real unsaved work) BLOCK, but a
+  //    file this session cannot be held to still demotes to a notice: a
+  //    session's own scoped auto-commit (commitWikiChanges, PR #222) can
+  //    leave the working tree non-empty when a DIFFERENT session sharing
+  //    this vault still has its own file dirty, the 2026-08-03 multi-session
+  //    block. That dirty file is human-fixable by whoever owns it, not by
+  //    this session, so it demotes to a notice (listed by path, never
+  //    silently dropped) instead of refusing this session's marker. Which
+  //    set decides "not mine" depends on what the caller told us: a
+  //    caller-provided project (--project, or the cwd-derived
+  //    attributionScope) demotes by PATH STRUCTURE alone
+  //    (isForeignProjectFile below), independent of transcript trust; with
+  //    no such scope, only a trusted transcript's closeAccountableScope can
+  //    tell mine from foreign, so an untrusted,
+  //    unscoped session falls back to the original unscoped blocker:
+  //    "cannot attribute" is not "clean". A dirty file THIS session owns
+  //    still blocks unconditionally either way, and so does the
+  //    enumeration-failed case below (dirty.length === 0 despite
+  //    git.uncommitted === true).
   //    Unpushed commits (ahead) DEMOTE to a notice regardless of scope: push is
   //    automatic (auto-commit Stop hook) and its failures are already non-fatal, so
   //    "ahead" is a transient sync state, not a human-fixable blocker. Demoting it
@@ -4053,17 +4086,26 @@ export function precompactGateStatus(hypoDir, opts = {}) {
       // porcelain status): "cannot attribute" is not "clean", block exactly
       // as before, override or not.
       blockers.push({ type: 'git', reason: git.reason });
-    } else if (!sessionTouchTrusted && (opts.projectOverride || opts.attributionScope)) {
-      // session-close-scope-boundary spec §2b: a broken/missing transcript
-      // normally means "cannot attribute, fail closed" (the branch below).
-      // But when the CALLER told us which project is ours (an explicit
-      // --project, or the cwd-derived attributionScope), a dirty file that
-      // lives structurally under a DIFFERENT eligible project's own directory
-      // needs no attribution inference at all: the path alone proves it is
-      // not this session's file. Everything else (this session's own
-      // project, pages/, an unregistered or _template project dir) keeps the
-      // pre-existing fail-closed behavior; only a provably-foreign path is
-      // demoted.
+    } else if (opts.projectOverride || opts.attributionScope) {
+      // session-close-scope-boundary spec §2b, revised 2026-09-11: a
+      // caller-provided scope (an explicit --project, or the cwd-derived
+      // attributionScope) proves which project is ours PATH-STRUCTURALLY,
+      // regardless of transcript trust. This used to run only when
+      // !sessionTouchTrusted, on the theory that a trusted transcript could
+      // fall back to closeAccountableScope instead. But closeAccountableScope
+      // is `closeFileTargetsGlobal` whenever opts.projectOverride is unset
+      // (every caller here passes attributionScope, never projectOverride;
+      // see crystallize-close-apply.mjs), which unions in every OTHER
+      // today-active project's own mandatory close files too. That let a
+      // different session's still-dirty close files (session-state.md,
+      // project hot.md, today's session-log shard) block THIS session's
+      // marker even with --project set. A dirty file that lives structurally
+      // under a DIFFERENT eligible project's own
+      // directory needs no attribution inference at all: the path alone
+      // proves it is not this session's file. Everything else (this
+      // session's own project, pages/, an unregistered or _template project
+      // dir) keeps the pre-existing fail-closed behavior; only a
+      // provably-foreign path is demoted.
       const effectiveOverride = opts.projectOverride || opts.attributionScope;
       // Computed once per gate call, never per file (collectProjectWorkingDirs
       // walks the projects/ dir and reads every index.md). A throw here (a
@@ -4085,6 +4127,20 @@ export function precompactGateStatus(hypoDir, opts = {}) {
       const isForeign = (f) =>
         isForeignProjectFile(f, { eligibleSlugs, effectiveOverride, transcriptTouched });
       const foreign = dirty.filter(isForeign);
+      // A dirty file inside the scoped project's OWN directory blocks, even one
+      // this close does not write. An earlier revision demoted those to notices
+      // to escape a deadlock: a close whose commit fails leaves
+      // `projects/<p>/index.md` (seeded by ensureProjectIndex) uncommitted, the
+      // retry skips every payload field as already-current without re-staging
+      // it, and the marker can then never land again no matter how often the
+      // user retries.
+      //
+      // That demotion was far wider than the deadlock it answered. It waved
+      // through every unsaved file in the project, which is exactly the work a
+      // close is supposed to refuse to walk away from. The deadlock is fixed at
+      // its source instead: applyOverwrites re-stages index.md on the retry
+      // path (crystallize-close-apply.mjs), so the file this branch used to
+      // demote is now in the close's own commit scope and never reaches here.
       const rest = dirty.filter((f) => !isForeign(f));
       if (rest.length > 0) {
         blockers.push({
@@ -5201,14 +5257,25 @@ export function walkCloseGate(transcriptPath) {
     // `attachment` of type queued_command with the prompt verbatim). This opens
     // the gate ONLY with an audited human producer — origin.kind "human", present
     // on every 2.1.181+ user delivery (measured). A legacy origin-absent delivery
-    // cannot attest a producer, so it does not open (fail-closed). A NON-close
-    // queued command (e.g. "keep working") is a fresh user intent and CLOSES
-    // a prior open regardless of origin — that is what closes the re-close hole
-    // where a queued "continue" after a close leaves the stale open live. A
-    // task notification is not that: `modelCaused` below filters it out before
-    // this reaches the change-of-mind close, because the model, not the user,
-    // produced it. This delivery path used to skip that filter and let an
-    // unrelated background-task notification flip a just-opened gate shut.
+    // cannot attest a producer, so it does not open (fail-closed). Closing asks
+    // for the same proof: a NON-close queued command (e.g. "keep working") is a
+    // fresh user intent and retracts a prior open, but only with that same
+    // audited human producer. This branch used to close by default instead,
+    // on the theory that anything the model-caused list did not recognise had
+    // to be the user. That default is what let an unrelated background-task
+    // notification flip a just-opened gate shut, and every new machine-minted
+    // event would have needed its own line in that list to stay safe. Requiring
+    // a positive producer means an event this filter has never seen is neutral
+    // rather than hostile. `modelCaused` below still runs first, so a
+    // recognised notification never reaches either decision.
+    //
+    // The enqueue branch above does NOT share this rule: those records carry no
+    // `origin` at all, so requiring one would stop them closing anything. It
+    // keeps the old enumerate-the-machine default, and the re-close hole (a
+    // queued "continue" after a close leaving the stale open live) is closed
+    // there rather than here. The two delivery shapes of one user action are
+    // therefore judged differently on purpose; see the residual noted on the
+    // queue-operation branch.
     //
     // Scope of "both shapes classify alike": it holds for task notifications and
     // for empty content, which is what this fix is about. It does not hold for
@@ -5277,9 +5344,20 @@ export function walkCloseGate(transcriptPath) {
           open = true;
           openedAtIndex = i;
         }
-      } else {
-        open = false;
+      } else if (humanOrigin) {
+        open = false; // an audited human change of mind → close
       }
+      // else: not caught by the known-machine shapes above, not a close
+      // phrase, and no audited human producer either — a host event this
+      // filter does not yet recognize. The old rule closed here by default
+      // (anything not on the model-caused list must be the user), which is
+      // exactly the shape of bug #289 fixed for <task-notification>: a new
+      // kind of unattributed host event would silently retract a close the
+      // user already granted, and every future one would need its own line
+      // in isModelCausedQueueContent to avoid repeating that. Requiring a
+      // POSITIVE human producer to close, instead of enumerating every way to
+      // recognize a machine one, means an event this filter has never seen
+      // still cannot close the gate on its own.
       continue;
     }
 

package/hooks/proposal-store.mjs

@@ -228,13 +228,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 +290,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.

package/hooks/shared.json

@@ -0,0 +1,9 @@
+[
+  "hypo-shared.mjs",
+  "version-check.mjs",
+  "version-check-fetch.mjs",
+  "base-store.mjs",
+  "proposal-store.mjs",
+  "close-gate-store.mjs",
+  "close-journal.mjs"
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.8.2",
+  "version": "1.8.4",
   "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",

package/scripts/doctor.mjs

@@ -18,6 +18,7 @@ import { homedir } from 'os';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { loadHookInventory } from './lib/hook-inventory.mjs';
 import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
 import { readRenameMarker, renameMarkerPath, RENAME_MARKER_REL } from './lib/rename-marker.mjs';
 import {
@@ -154,94 +155,22 @@ function fail(label, detail = '') {
 }
 
 // ── hook map (loaded from hooks/hooks.json — single source of truth) ─────────
-
-let _hookConfig;
-try {
-  _hookConfig = JSON.parse(readFileSync(join(PKG_ROOT, 'hooks', 'hooks.json'), 'utf-8'));
-} catch {
-  console.error(`Error: cannot read hooks/hooks.json from package root: ${PKG_ROOT}`);
-  console.error(PKG_INTEGRITY_HINT);
-  process.exit(1);
-}
-if (!_hookConfig || typeof _hookConfig !== 'object' || Array.isArray(_hookConfig)) {
-  console.error('Error: hooks/hooks.json must be a JSON object');
-  console.error(PKG_INTEGRITY_HINT);
-  process.exit(1);
-}
-if (
-  !_hookConfig.hooks ||
-  typeof _hookConfig.hooks !== 'object' ||
-  Array.isArray(_hookConfig.hooks)
-) {
-  console.error('Error: hooks/hooks.json must contain a "hooks" object');
-  console.error(PKG_INTEGRITY_HINT);
-  process.exit(1);
-}
-function _extractCommandFileName(command) {
-  if (typeof command !== 'string') return null;
-  const matches = [...command.matchAll(/(?:^|[\/\\])([^\/\\\s"'`]+\.mjs)(?=$|[\s"'`])/g)];
-  if (matches.length > 0) return matches[matches.length - 1][1];
-  const bare = command.match(/(?:^|\s)([^\/\\\s"'`]+\.mjs)(?=$|[\s"'`])/);
-  return bare ? bare[1] : null;
-}
-
-function _isHookFileName(file) {
-  return typeof file === 'string' && /^[^/\\\s]+\.mjs$/.test(file.trim());
-}
-
-function _isHookGroup(group) {
-  return (
-    group &&
-    typeof group === 'object' &&
-    !Array.isArray(group) &&
-    Array.isArray(group.hooks) &&
-    group.hooks.length > 0 &&
-    group.hooks.every(
-      (hook) =>
-        hook &&
-        typeof hook === 'object' &&
-        !Array.isArray(hook) &&
-        hook.type === 'command' &&
-        _extractCommandFileName(hook.command),
-    )
-  );
-}
-
-// Extract .mjs file names from both old format (string[]) and new format (hook-group object[])
-function _extractFileNames(groups) {
-  return groups.flatMap((group) => {
-    if (typeof group === 'string') return [group.trim()];
-    return group.hooks.map((hook) => _extractCommandFileName(hook.command));
-  });
-}
-
-for (const [event, groups] of Object.entries(_hookConfig.hooks)) {
-  const valid =
-    Array.isArray(groups) &&
-    groups.length > 0 &&
-    groups.every((group) => _isHookFileName(group) || _isHookGroup(group)) &&
-    _extractFileNames(groups).length > 0;
-  if (!valid) {
-    console.error(
-      `Error: hooks/hooks.json "hooks.${event}" must be a non-empty array of .mjs file names or Claude hook groups`,
-    );
-    console.error(PKG_INTEGRITY_HINT);
-    process.exit(1);
-  }
-}
-if (
-  _hookConfig.shared !== undefined &&
-  (!Array.isArray(_hookConfig.shared) || !_hookConfig.shared.every((f) => _isHookFileName(f)))
-) {
-  console.error('Error: hooks/hooks.json "shared" must be an array of .mjs file names');
+//
+// loadHookInventory (scripts/lib/hook-inventory.mjs) is the one parser every
+// hooks.json/shared.json consumer reads through — smoke-plugin, init, upgrade,
+// and uninstall all call the same function. It existence-checks every named
+// file against THIS package's own hooks/ before returning ok:true, so a
+// corrupt or incomplete doctor.mjs's OWN package (never the vault being
+// audited — that stays checkHooks()'s job below) fails here rather than
+// auditing an install against a hook list doctor cannot trust.
+const _hookInventory = loadHookInventory(PKG_ROOT);
+if (!_hookInventory.ok) {
+  console.error(`Error: ${_hookInventory.error}`);
   console.error(PKG_INTEGRITY_HINT);
   process.exit(1);
 }
-
-const HOOK_MAP = Object.fromEntries(
-  Object.entries(_hookConfig.hooks).map(([e, gs]) => [e, _extractFileNames(gs)]),
-);
-const SHARED_FILES = _hookConfig.shared ?? [];
+const HOOK_MAP = _hookInventory.hookMap;
+const SHARED_FILES = _hookInventory.shared;
 
 // ── checks ───────────────────────────────────────────────────────────────────
 
@@ -543,15 +472,38 @@ function checkGit(hypoDir) {
     // plugin-cache leaf-drift precedent: reporting must never turn into
     // filtering, or a still-real, still-resolvable root looks like it vanished).
     const parsedRoot = parseWikiPreCommitRoot(content);
-    const wantRoot = resolveDurableHookRoot();
-    if (parsedRoot.ok && wantRoot !== null && wantRoot !== parsedRoot.root) {
+    if (parsedRoot.ok && parsedRoot.root === null) {
+      // The runtime-resolving form: the hook looks up its own
+      // install root at commit time, so there is no baked value to compare
+      // against the active install — it cannot structurally go stale the way
+      // the old, version-pinned form could. Report that fact in place of the
+      // stale-root comparison below, rather than falling silent.
+      pass(`${label} root`, 'Resolved at commit time by the hook itself — never goes stale');
+    } else if (!parsedRoot.ok) {
+      // The pass above only checked that our START marker is present, not
+      // that the body it wraps is one this codebase can actually run. This is
+      // the fail-open this branch used to leave: a hand-edited body, a
+      // corrupted one, or (before the rewrite-safe root check) an OLD-form
+      // hook whose baked-in install root no longer existed all read as a
+      // clean "guard installed" pass while the hook fails MODULE_NOT_FOUND on
+      // every real commit.
       warn(
         `${label} root`,
-        `Points at an old install root (${parsedRoot.root}) — the active install is ` +
-          `${wantRoot}. To repoint it, run ${upgradeApplyHint(
-            pluginMode || hypomnemaPluginEnabled,
-          )}.`,
+        'Guard marker present but the hook body is not recognized, it may be failing on ' +
+          `every commit. Run \`hypomnema init --force-commands\` (or the plugin's ` +
+          `\`/hypo:init --force-commands\`) to reinstall it.`,
       );
+    } else {
+      const wantRoot = resolveDurableHookRoot();
+      if (wantRoot !== null && wantRoot !== parsedRoot.root) {
+        warn(
+          `${label} root`,
+          `Points at an old install root (${parsedRoot.root}) — the active install is ` +
+            `${wantRoot}. To repoint it, run ${upgradeApplyHint(
+              pluginMode || hypomnemaPluginEnabled,
+            )}.`,
+        );
+      }
     }
   } else {
     warn(label, 'Exists but not managed by Hypomnema — manual git add can bypass .hypoignore');