hypomnema 1.8.0 → 1.8.2

package/hooks/hypo-shared.mjs

@@ -396,8 +396,23 @@ export function isGateSkipped() {
 // ── state checkers ─────────────────────────────────────────────────────────
 
 export function lastSubstantialOpIsSession() {
-  if (!existsSync(LOG_PATH)) return true;
-  const log = readFileSync(LOG_PATH, 'utf-8');
+  // Single read, no existsSync precheck: a check-then-read pair leaves a race
+  // window where the file exists at the check and is gone by the read, and
+  // the old code treated that ENOENT the same as a stably-missing file
+  // (fail-open, `true`). Only a genuinely absent log.md (ENOENT) folds to
+  // `false` here; any other read failure (EISDIR, EACCES, ...) is a real
+  // problem the caller needs to see, not a silent "no session", so it is
+  // rethrown. hypo-compact-guard.mjs is the only in-repo caller (verified via
+  // grep) and its own try/catch already turns any throw here into
+  // fail-closed ("session log entry missing") plus a stderr line, so this
+  // fail-open-to-fail-closed flip needed no other caller to be re-audited.
+  let log;
+  try {
+    log = readFileSync(LOG_PATH, 'utf-8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return false;
+    throw err;
+  }
   const substantial = log
     .split('\n')
     .filter((l) => /^## \[\d{4}-\d{2}-\d{2}\] (session|ingest)/.test(l));
@@ -414,12 +429,61 @@ export function lastSubstantialOpIsSession() {
 // read it. Callers that gate session-close / compact distinguish the two: they
 // block on `uncommitted` and demote `ahead` to a notice (precompactGateStatus,
 // hypo-compact-guard) so a committed-but-unpushed close is still "compact-ready".
-export function hypoIsClean(dir = HYPO_DIR) {
+// A deadline shared across every git spawn one "am I clean" check can make:
+// `{ end: <performance.now()-based timestamp> }`, built once by a caller that
+// needs to bound hypoIsClean and gitDirtyFiles to a slice of its own hook
+// timeout (session-close-scope-boundary spec §5). remainingSpawnTimeoutMs
+// turns "time left" into what spawnSync's own `timeout` option actually
+// requires — verified on Node 26: `timeout: 0` DISABLES the timeout (waits
+// forever) rather than firing immediately, and a negative or fractional value
+// THROWS ERR_OUT_OF_RANGE. A throw here would escape as an exception through
+// a hook's outermost catch and come back silent, so a caller must never pass
+// a value this function did not produce, and must never spawn once it
+// returns 0.
+// A deadline built from a bad `end` (Infinity, NaN, or already past) must
+// also fold to 0, not just a plain negative one: a caller-supplied
+// `{ end: Infinity }` produces `remaining = Infinity`, and `Infinity` is
+// exactly as unsafe a `timeout` value as a negative or fractional one, same
+// `ERR_OUT_OF_RANGE` throw, just via a different guard. `Number.isFinite`
+// alone is not enough, though: it also passes `Number.MAX_VALUE`, which is
+// finite but still outside spawnSync's documented `timeout` range (0 through
+// `Number.MAX_SAFE_INTEGER`) and throws the same `ERR_OUT_OF_RANGE` (verified
+// directly: `gitDirtyFiles(cwd, { deadline: { end: Number.MAX_VALUE } })`
+// threw before this guard, since MAX_SAFE_INTEGER is exactly spawnSync's
+// upper bound, `Number.isSafeInteger` is the one predicate that matches it.
+//   undefined — no deadline given: omit `timeout` entirely (today's behavior)
+//   0         — budget exhausted, or the deadline itself was not a safe
+//               positive integer: do not spawn
+//   >0        — a whole positive integer number of ms safe to pass as `timeout`
+function remainingSpawnTimeoutMs(deadline) {
+  if (!deadline) return undefined;
+  const remaining = Math.floor(deadline.end - performance.now());
+  return Number.isSafeInteger(remaining) && remaining > 0 ? remaining : 0;
+}
+
+// `opts.deadline` is optional (session-close-scope-boundary spec §5): when
+// omitted, both spawns run exactly as before, no timeout, no status/error
+// check on the second one. hypo-compact-guard.mjs is the only caller that
+// passes one; precompactGateStatus (`:3872`) and all six direct test call
+// sites still pass a bare `dir` and must see byte-identical behavior.
+export function hypoIsClean(dir = HYPO_DIR, opts = {}) {
+  const { deadline } = opts;
   try {
-    const porcelain = spawnSync('git', ['-C', dir, 'status', '--porcelain'], {
-      encoding: 'utf-8',
-    });
-    if (porcelain.status !== 0)
+    const t1 = remainingSpawnTimeoutMs(deadline);
+    if (t1 === 0) {
+      return {
+        clean: false,
+        uncommitted: true,
+        ahead: false,
+        reason: `git check deadline exhausted in ${dir}`,
+      };
+    }
+    const porcelain = spawnSync(
+      'git',
+      ['-C', dir, 'status', '--porcelain'],
+      t1 === undefined ? { encoding: 'utf-8' } : { encoding: 'utf-8', timeout: t1 },
+    );
+    if (porcelain.error || porcelain.status !== 0)
       return {
         clean: false,
         uncommitted: true,
@@ -427,9 +491,38 @@ export function hypoIsClean(dir = HYPO_DIR) {
         reason: `git check failed in ${dir}`,
       };
     const uncommitted = porcelain.stdout.trim() !== '';
-    const aheadRes = spawnSync('git', ['-C', dir, 'status', '--branch', '--porcelain'], {
-      encoding: 'utf-8',
-    });
+
+    const t2 = remainingSpawnTimeoutMs(deadline);
+    if (t2 === 0) {
+      return {
+        clean: false,
+        uncommitted: true,
+        ahead: false,
+        reason: `git check deadline exhausted in ${dir}`,
+      };
+    }
+    const aheadRes = spawnSync(
+      'git',
+      ['-C', dir, 'status', '--branch', '--porcelain'],
+      t2 === undefined ? { encoding: 'utf-8' } : { encoding: 'utf-8', timeout: t2 },
+    );
+    // Only enforced when a deadline is in play. Without one this spawn cannot
+    // time out, and its `stdout` (empty on any other kind of failure too) was
+    // already read as "not ahead" before this change — harmless when nothing
+    // can kill the process out from under it. WITH a deadline this spawn CAN
+    // now die from the same budget the first spawn already spent, and a
+    // silent "not ahead" would make the caller's own notification vanish
+    // (spec §5's own regression). The first spawn already fails closed this
+    // way (`porcelain.status !== 0` above); this brings the second spawn to
+    // the same contract, but only where a deadline made it possible to break.
+    if (deadline && (aheadRes.error || aheadRes.status !== 0)) {
+      return {
+        clean: false,
+        uncommitted: true,
+        ahead: false,
+        reason: `git check failed in ${dir}`,
+      };
+    }
     const ahead = /\[ahead \d+\]/.test(aheadRes.stdout || '');
     const reasons = [];
     if (uncommitted) reasons.push(`uncommitted changes in ${dir}`);
@@ -473,18 +566,33 @@ export function hypoIsClean(dir = HYPO_DIR) {
  *   failure (the caller already has its own git-status result via
  *   hypoIsClean and treats that failure as an unconditional blocker; an
  *   empty return here just means "cannot attribute", not "clean").
+ *
+ * `opts.deadline` (session-close-scope-boundary spec §5): the SAME shared
+ * deadline object passed to hypoIsClean, so the two functions' spawns split
+ * one budget instead of each getting their own (which would let the pair
+ * together run twice as long as intended). Omitted, both spawns run exactly
+ * as before — precompactGateStatus's own call (`:3874`) does not pass one.
  */
-function gitDirtyFiles(dir) {
-  const prefixRes = spawnSync('git', ['-C', dir, 'rev-parse', '--show-prefix'], {
-    encoding: 'utf-8',
-  });
-  if (prefixRes.status !== 0) return []; // can't resolve the repo → cannot attribute
+export function gitDirtyFiles(dir = HYPO_DIR, opts = {}) {
+  const { deadline } = opts;
+  const t1 = remainingSpawnTimeoutMs(deadline);
+  if (t1 === 0) return []; // budget exhausted before the first spawn → cannot attribute
+  const prefixRes = spawnSync(
+    'git',
+    ['-C', dir, 'rev-parse', '--show-prefix'],
+    t1 === undefined ? { encoding: 'utf-8' } : { encoding: 'utf-8', timeout: t1 },
+  );
+  if (prefixRes.error || prefixRes.status !== 0) return []; // can't resolve the repo → cannot attribute
   const prefix = (prefixRes.stdout || '').trim();
 
-  const porcelain = spawnSync('git', ['-C', dir, 'status', '--porcelain', '-uall', '-z'], {
-    encoding: 'utf-8',
-  });
-  if (porcelain.status !== 0) return [];
+  const t2 = remainingSpawnTimeoutMs(deadline);
+  if (t2 === 0) return [];
+  const porcelain = spawnSync(
+    'git',
+    ['-C', dir, 'status', '--porcelain', '-uall', '-z'],
+    t2 === undefined ? { encoding: 'utf-8' } : { encoding: 'utf-8', timeout: t2 },
+  );
+  if (porcelain.error || porcelain.status !== 0) return [];
   const out = [];
   const records = (porcelain.stdout || '').split('\0');
   const toDirRelative = (f) => {
@@ -511,6 +619,74 @@ function gitDirtyFiles(dir) {
   return out;
 }
 
+// session-close-scope-boundary spec §2b/§5: the ONE path-prefix rule that
+// decides a dirty file structurally belongs to a DIFFERENT eligible project
+// than the one this call is scoped to. Extracted from precompactGateStatus's
+// former inline closure so hypo-compact-guard.mjs (spec §5) can call the
+// exact same predicate instead of duplicating it — a closure over the gate's
+// local variables cannot be called, or asserted against, from anywhere else.
+//
+// Lexical, on the RAW git-porcelain path `f`, BEFORE posixPath()'s
+// unconditional `\` -> `/` conversion: a file whose actual NAME contains a
+// literal backslash (`projects\other\x.md`, one path segment, no real
+// subdirectory) must not be reinterpreted as living under `projects/other/`
+// just because posixPath() would rewrite it that way — testing the raw
+// string means it never matches the regex below and falls through to
+// "not foreign", the fail-closed default. `transcriptTouched` IS keyed by
+// posix paths (it comes from extractTouchedWikiFiles), so that one check
+// still normalizes `f` before the lookup.
+//
+// @param {string} f - a raw dirty path from gitDirtyFiles/git porcelain
+// @param {{eligibleSlugs: Set<string>|null, effectiveOverride: string|null,
+//   transcriptTouched?: Set<string>}} ctx
+// @returns {boolean}
+export function isForeignProjectFile(
+  f,
+  { eligibleSlugs, effectiveOverride, transcriptTouched = new Set() },
+) {
+  // Transcript evidence outranks the path-prefix heuristic below: it PROVES
+  // this session edited f, whatever its path prefix says. The heuristic only
+  // exists to cover files an untrusted (or absent) transcript could not
+  // vouch for either way.
+  if (transcriptTouched.has(posixPath(f))) return false;
+  if (!eligibleSlugs) return false;
+  const m = /^projects\/([^/]+)\/.+$/.exec(f);
+  if (!m) return false;
+  const slug = m[1];
+  return slug !== effectiveOverride && eligibleSlugs.has(slug);
+}
+
+// session-close-scope-boundary spec §5: hypo-compact-guard.mjs only needs a
+// yes/no on "may I drop my git notice line", never precompactGateStatus's
+// full per-file partition, and the answer must never escape as a throw — this
+// hook's outermost catch turns ANY exception into a fully suppressed
+// {suppressOutput:true}, so a failure inside collectProjectWorkingDirs (a
+// readdirSync it does not itself catch) must come back as data instead.
+//
+// Returns one of two sentinels, never throws:
+//   'foreign-only'   — dirty is non-empty, at least one eligible project is
+//                       known, and EVERY dirty file is provably someone
+//                       else's under isForeignProjectFile.
+//   'unattributable' — anything short of that full proof (no dirty files, no
+//                       eligible project known, project enumeration failed,
+//                       or a mix of foreign and non-foreign files). The
+//                       caller must treat this exactly like today's unscoped
+//                       git blocker/notice — this is the fail-closed default.
+export function classifyForeignOnlyDirty(hypoDir, dirty, { effectiveOverride = null } = {}) {
+  if (!dirty || dirty.length === 0) return 'unattributable'; // vacuous every() must not pass
+  let eligibleSlugs;
+  try {
+    eligibleSlugs = new Set(collectProjectWorkingDirs(hypoDir).map((p) => p.slug));
+  } catch {
+    return 'unattributable';
+  }
+  if (eligibleSlugs.size === 0) return 'unattributable';
+  const allForeign = dirty.every((f) =>
+    isForeignProjectFile(f, { eligibleSlugs, effectiveOverride }),
+  );
+  return allForeign ? 'foreign-only' : 'unattributable';
+}
+
 export function hotMdIsClean(dir = HYPO_DIR) {
   const hotPath = dir === HYPO_DIR ? HOT_PATH : join(dir, 'hot.md');
   if (!existsSync(hotPath)) return { clean: true };
@@ -1592,8 +1768,11 @@ export function sessionCloseGlobalStatus(hypoDir, opts = {}) {
   // invariant that once justified keeping the writer paths fully unscoped
   // ("marker == compact-ready", codex design review) is superseded by that
   // partition, not restored by it — a marker's own `verified_scope`, attesting
-  // exactly what it checked, is still missing (session-close-scope-boundary
-  // spec §3, next wave).
+  // exactly what this function's caller evaluated (never `markerProjects`'
+  // evidence-based attribution), now ships (session-close-scope-boundary
+  // spec §3). The writer is `scripts/lib/crystallize-close-apply.mjs`
+  // (`runMarkSessionClosed` and `runMarkerPhase`); the reader is
+  // `markerCoversArtifact` in `scripts/doctor.mjs`.
   if (opts.projectOverride) {
     const s = sessionCloseFileStatus(hypoDir, { projectOverride: opts.projectOverride });
     return {
@@ -1634,6 +1813,13 @@ export function sessionCloseGlobalStatus(hypoDir, opts = {}) {
     hasTodayCloseActivity(hypoDir, p, dates),
   );
 
+  // This branch drops `mustEvaluate` on the floor and reports the recency
+  // project instead, so `projects` here can name a DIFFERENT project than the
+  // caller asked for. No marker is ever written from it, though: `close.fallback`
+  // is an unconditional gate blocker (see the fail-closed guards in the partition
+  // below) and both marker writers only stamp on a green gate. So a marker whose
+  // `verified_scope` names the recency project instead of the requested one is
+  // unreachable, not merely fail-safe — do not write code defending that state.
   if (activeCandidates.length === 0) {
     const legacy = sessionCloseFileStatus(hypoDir);
     return {
@@ -3166,6 +3352,33 @@ export function sessionClosedMarkerPath(hypoDir, sessionId) {
   return join(hypoDir, '.cache', `session-closed-${sanitizeSessionId(sessionId)}.marker`);
 }
 
+// verified_scope (session-close-scope-boundary spec §3) records the scope the
+// gate ABOVE this write actually verified, not merely the attribution the
+// marker's `projects` field carries — those can diverge whenever a gate run
+// widens attribution beyond what it narrowed the check to. The caller
+// decides `kind`: this function only refuses to persist a shape it cannot
+// stand behind. Exported so scripts/doctor.mjs's reader runs the SAME
+// collapse instead of a hand-rolled copy — an unrecognized shape, or a
+// 'project'/'global' scope with an empty `projects` (a narrower-than-nothing
+// claim), reads back as "field absent", never as a false claim.
+export function normalizeVerifiedScope(verifiedScope) {
+  if (!verifiedScope || typeof verifiedScope !== 'object') return null;
+  if (verifiedScope.kind === 'log-only') return { kind: 'log-only' };
+  if (verifiedScope.kind === 'project' || verifiedScope.kind === 'global') {
+    const projects = Array.isArray(verifiedScope.projects)
+      ? [...new Set(verifiedScope.projects.filter((p) => typeof p === 'string' && p))]
+      : [];
+    // An empty projects list under 'project'/'global' asserts a verified
+    // boundary with nothing in it — that is not a narrower claim, it is a
+    // malformed one. Drop it rather than persist a scope nothing can satisfy
+    // by design (verified_scope must only ever tighten, never silently gate
+    // out everything).
+    if (projects.length === 0) return null;
+    return { kind: verifiedScope.kind, projects };
+  }
+  return null;
+}
+
 /**
  * Persist a per-session close proof. Caller MUST verify
  * `sessionCloseFileStatus(hypoDir).ok` before invoking — this helper does NOT
@@ -3175,7 +3388,7 @@ export function sessionClosedMarkerPath(hypoDir, sessionId) {
  *
  * @param {string} hypoDir
  * @param {string} sessionId
- * @param {{project?: string, scope?: string, transcript_path?: string}} info
+ * @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;
@@ -3199,6 +3412,7 @@ export function writeSessionClosedMarker(hypoDir, sessionId, info = {}) {
       : info.project
         ? [info.project]
         : [];
+    const verifiedScope = normalizeVerifiedScope(info.verifiedScope);
     const payload = {
       session_id: sessionId,
       project: info.project || projects[0] || null,
@@ -3207,6 +3421,11 @@ export function writeSessionClosedMarker(hypoDir, sessionId, info = {}) {
       transcript_path: info.transcript_path || null,
       closed_at: new Date().toISOString(),
       verification: scope === 'log-only' ? 'log-only-close:ok' : 'session-close-file-status:ok',
+      // Omitted entirely (not even `null`) when the caller passes nothing or
+      // an unrecognized shape, so a marker written by a caller that hasn't
+      // adopted this field reads back byte-identical to before it existed —
+      // doctor's reader treats "field absent" as "no additional scope check".
+      ...(verifiedScope ? { verified_scope: verifiedScope } : {}),
     };
     writeFileSync(sessionClosedMarkerPath(hypoDir, sessionId), JSON.stringify(payload) + '\n');
   } catch (err) {
@@ -3711,8 +3930,12 @@ export function resolveCloseScope(hypoDir, opts = {}, marker = null) {
  * below can tell their own incomplete close from someone else's debt. The
  * invariant that once justified keeping those paths fully unscoped ("marker ==
  * compact-ready", codex design review) is replaced by that partition, not
- * restored by it — a marker's own `verified_scope`, attesting exactly what it
- * checked, is still missing (session-close-scope-boundary spec §3, next wave).
+ * restored by it — a marker's own `verified_scope`, attesting exactly what
+ * this status's caller evaluated (never the marker's `projects`, which is
+ * evidence-based attribution), now ships (session-close-scope-boundary
+ * spec §3). The writer is `scripts/lib/crystallize-close-apply.mjs`
+ * (`runMarkSessionClosed` and `runMarkerPhase`); the reader is
+ * `markerCoversArtifact` in `scripts/doctor.mjs`.
  * Either key ALSO feeds the git-dirty partition (spec §2b): with an untrusted
  * transcript (missing/corrupt), a dirty file structurally under a DIFFERENT
  * eligible project's own directory is demoted to a notice, because the path
@@ -3848,33 +4071,19 @@ export function precompactGateStatus(hypoDir, opts = {}) {
       // exception, the PreCompact hook's outermost catch would turn that
       // into a silent, fully-suppressed gate result, the opposite of "fail
       // closed". Treat any failure as "no eligible projects known", which
-      // makes isForeign() below always false and every dirty file falls
-      // through to the unconditional blocker.
+      // makes isForeignProjectFile() below always false and every dirty file
+      // falls through to the unconditional blocker.
       let eligibleSlugs = null;
       try {
         eligibleSlugs = new Set(collectProjectWorkingDirs(hypoDir).map((p) => p.slug));
       } catch {
         eligibleSlugs = null;
       }
-      // Lexical, on the RAW git-porcelain path, BEFORE posixPath()'s
-      // unconditional `\` -> `/` conversion. A file whose actual NAME
-      // contains a literal backslash (`projects\other\x.md`, one path
-      // segment, no real subdirectory) must not be reinterpreted as living
-      // under `projects/other/` just because posixPath() would rewrite it
-      // that way; testing the raw string here means it never matches this
-      // regex and falls through to fail-closed instead.
-      const isForeign = (f) => {
-        // The transcript already PROVES this session edited f, whatever its
-        // path prefix says: transcript evidence outranks the path-prefix
-        // heuristic below, which only exists to cover files the (untrusted)
-        // transcript could not vouch for either way.
-        if (transcriptTouched.has(posixPath(f))) return false;
-        if (!eligibleSlugs) return false;
-        const m = /^projects\/([^/]+)\/.+$/.exec(f);
-        if (!m) return false;
-        const slug = m[1];
-        return slug !== effectiveOverride && eligibleSlugs.has(slug);
-      };
+      // isForeignProjectFile is the extracted, exported predicate (spec §5):
+      // hypo-compact-guard.mjs calls the exact same function on its own git
+      // axis, instead of a second, silently-diverging copy of this rule.
+      const isForeign = (f) =>
+        isForeignProjectFile(f, { eligibleSlugs, effectiveOverride, transcriptTouched });
       const foreign = dirty.filter(isForeign);
       const rest = dirty.filter((f) => !isForeign(f));
       if (rest.length > 0) {
@@ -4809,6 +5018,48 @@ export function resolveTranscriptBySessionId(
 // dangerous replay/injection paths carry system|sdk|isMeta|isSidechain and are
 // excluded here anyway.
 const COMMAND_INVOCATION_TAG = /<command-(?:name|message|args)>/;
+
+// Text out of a content-block array, or null when the array carries a command
+// invocation (which is a host artifact, not something the user typed as prose).
+// Extracted so the queued_command attachment branch in walkCloseGate can reuse
+// the exact same rule: a queued prompt arrives as this array shape whenever the
+// user pasted an image alongside their words (measured: 8 such deliveries, all
+// origin.kind "human", host versions 2.1.226 through 2.1.263). Reading only
+// `typeof prompt === 'string'` there dropped those to '' and read a real change
+// of mind as nothing at all.
+function contentBlocksText(content) {
+  const texts = content
+    .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+    .map((b) => b.text);
+  const text = texts.length ? texts.join('\n') : null;
+  // A command-invocation tag split across adjacent text blocks (e.g.
+  // '<command-na' + 'me>/hypo:crystallize</command-name>') would survive the
+  // '\n'-joined `text` above with a newline spliced into the middle of the
+  // tag name, so the plain check below can miss it entirely. Today's actual
+  // host format sends the whole invocation as ONE string, so this exact
+  // split is not reproducible against a live session yet — but a check for
+  // "did the host format ever put the tag exactly on a block boundary"
+  // should not depend on where a future host happens to cut the blocks. So
+  // also test each run of CONSECUTIVE text blocks joined with no separator.
+  // This must stay scoped to consecutive text blocks only, never the whole
+  // array: joining across a non-text block in between (an image, say) would
+  // synthesize a tag that never existed in the real content, and that is a
+  // different bug, not a fix — it would throw away a genuine close spoken
+  // next to an unrelated attachment. So a non-text block ends the current
+  // run and starts a new one; it never bridges two runs into one string.
+  let tightRun = '';
+  for (const b of content) {
+    if (b && b.type === 'text' && typeof b.text === 'string') {
+      tightRun += b.text;
+      continue;
+    }
+    if (COMMAND_INVOCATION_TAG.test(tightRun)) return null;
+    tightRun = '';
+  }
+  if (COMMAND_INVOCATION_TAG.test(tightRun)) return null;
+  return text;
+}
+
 function eventUserText(obj) {
   if (obj.isMeta === true) return null;
   if (obj.promptSource === 'system' || obj.promptSource === 'sdk') return null;
@@ -4822,35 +5073,9 @@ function eventUserText(obj) {
   if (typeof content === 'string') {
     text = content.startsWith('Stop hook feedback') ? null : content;
   } else if (Array.isArray(content)) {
-    const texts = content
-      .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
-      .map((b) => b.text);
-    text = texts.length ? texts.join('\n') : null;
-    // A command-invocation tag split across adjacent text blocks (e.g.
-    // '<command-na' + 'me>/hypo:crystallize</command-name>') would survive the
-    // '\n'-joined `text` above with a newline spliced into the middle of the
-    // tag name, so the plain check below can miss it entirely. Today's actual
-    // host format sends the whole invocation as ONE string, so this exact
-    // split is not reproducible against a live session yet — but a check for
-    // "did the host format ever put the tag exactly on a block boundary"
-    // should not depend on where a future host happens to cut the blocks. So
-    // also test each run of CONSECUTIVE text blocks joined with no separator.
-    // This must stay scoped to consecutive text blocks only, never the whole
-    // array: joining across a non-text block in between (an image, say) would
-    // synthesize a tag that never existed in the real content, and that is a
-    // different bug, not a fix — it would throw away a genuine close spoken
-    // next to an unrelated attachment. So a non-text block ends the current
-    // run and starts a new one; it never bridges two runs into one string.
-    let tightRun = '';
-    for (const b of content) {
-      if (b && b.type === 'text' && typeof b.text === 'string') {
-        tightRun += b.text;
-        continue;
-      }
-      if (COMMAND_INVOCATION_TAG.test(tightRun)) return null;
-      tightRun = '';
-    }
-    if (COMMAND_INVOCATION_TAG.test(tightRun)) return null;
+    // null from either cause (no text blocks, or a command invocation) means
+    // "no user prose here", which is exactly what this function returns anyway.
+    text = contentBlocksText(content);
   }
   if (text != null && COMMAND_INVOCATION_TAG.test(text)) return null;
   return text;
@@ -4868,6 +5093,20 @@ function isModelReachableRecord(obj) {
   );
 }
 
+// Queue content that carries no fresh USER decision: empty, or a background-task
+// notification the host injects on the model's behalf. Shared by the enqueue
+// branch and the remove-path (queued_command attachment) branch below so a
+// task notification reads as neutral on BOTH delivery shapes of the same host
+// event. Before this was extracted, only the enqueue branch filtered it — the
+// attachment branch treated any non-close prompt, including a task
+// notification, as a change-of-mind close: a close typed by the user opened
+// the gate, then the notification for an unrelated background task landed
+// via this path and flipped it shut again.
+function isModelCausedQueueContent(text) {
+  const c = typeof text === 'string' ? text.trim() : '';
+  return !c || c.startsWith('<task-notification>');
+}
+
 export function walkCloseGate(transcriptPath) {
   if (!transcriptPath) return { open: false, openedAtIndex: -1 };
   let raw;
@@ -4948,7 +5187,7 @@ export function walkCloseGate(transcriptPath) {
         openedAtIndex = i;
       } else if (/^\/clear(?:\s|$)/.test(c)) {
         open = false; // abandons context → close
-      } else if (!c || c.startsWith('<task-notification>')) {
+      } else if (isModelCausedQueueContent(c)) {
         /* model-caused / empty — neutral */
       } else if (isClosePattern(c)) {
         /* NL close via the queue — the open dequeue gap: the producer cannot be
@@ -4965,16 +5204,80 @@ export function walkCloseGate(transcriptPath) {
     // 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.
+    // 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.
+    //
+    // 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
+    // slash commands. The enqueue branch reads a queued `/compact` as an opener
+    // and `/clear` as a close, and nothing here mirrors that, so the same
+    // command would close the gate if it ever arrived on this path. Measured
+    // 0 of 1321 attachment deliveries carry a slash prompt, so the divergence
+    // is unreachable today rather than fixed; mirroring it would mean copying
+    // an opener that tests already mark a fail-open defect.
     if (o.type === 'attachment' && o.attachment && o.attachment.type === 'queued_command') {
-      const prompt = typeof o.attachment.prompt === 'string' ? o.attachment.prompt : '';
+      // Same channel guard the typed path applies, for the same reason. This
+      // branch can OPEN the gate, and `origin.kind` alone does not say which
+      // channel the record came in on: a sidechain, injected, sdk or meta
+      // record could carry a human origin and close text and mint an approval
+      // the user never gave in this conversation. eventUserText has refused
+      // those channels all along; the opener next to it did not, so one
+      // classifier trusted a record the other threw away. Measured 0 of 1340
+      // queued_command attachments carry any of these flags, so this closes a
+      // shape the corpus has not produced rather than an observed failure.
+      // `interruptedMessageId` rides along because eventUserText refuses it too.
+      if (isModelReachableRecord(o) || o.interruptedMessageId) continue;
+      // A queued prompt arrives as a content-block array whenever the user
+      // pasted an image alongside their words. Reading only the string shape
+      // dropped those to '' and threw away a real change of mind: the gate
+      // stayed open and the close went through anyway. Measured 8 such
+      // deliveries, every one origin.kind "human", host 2.1.226 to 2.1.263.
+      const rawPrompt = o.attachment.prompt;
+      const prompt =
+        typeof rawPrompt === 'string'
+          ? rawPrompt
+          : Array.isArray(rawPrompt)
+            ? (contentBlocksText(rawPrompt) ?? '')
+            : '';
       const humanOrigin = !!(o.attachment.origin && o.attachment.origin.kind === 'human');
-      if (isClosePattern(prompt)) {
+      // The host labels these deliveries on the record itself, and that label is
+      // the authoritative one: every measured task-notification attachment
+      // (1040 of 1040) carries commandMode 'task-notification'. Keying only on
+      // the '<task-notification>' body prefix would leave the whole filter
+      // resting on a string the host owns and can restyle, and a body that
+      // merely gains a line before the tag would slip past it. The queue-op
+      // branch above has no such field to read, so it keeps the body check
+      // alone; here both are available and both are used.
+      const modelCaused =
+        o.attachment.commandMode === 'task-notification' || isModelCausedQueueContent(prompt);
+      // The filter runs FIRST here, exactly as it does in the enqueue branch
+      // above. Order is load-bearing, not cosmetic: a notification body carries
+      // whatever text the finished task was named after, and isClosePattern
+      // matches on a substring ("wrap up", "오늘 여기까지" inside a <summary>
+      // both measure true). Testing isClosePattern first therefore lets a
+      // model-produced event reach the opener, where a human-origin delivery
+      // would set `open` and push `openedAtIndex` forward. That manufactures a
+      // close signal the user never gave, and moves the index the resolution
+      // comparison reads.
+      //
+      // Reachability, so the next reader does not have to re-measure it: no
+      // recorded delivery hits that path. All 1040 task-notification
+      // attachments in the corpus arrive with no `origin`, so `humanOrigin` is
+      // false and the opener is skipped whichever order the two checks run in.
+      // This is a defensive pin against a host that starts stamping origin on
+      // them, not a repair of an observed failure.
+      if (modelCaused) {
+        /* model-caused / empty: neutral, the same filter the enqueue branch
+           above applies to the same host event on its other delivery shape */
+      } else if (isClosePattern(prompt)) {
         if (humanOrigin) {
           open = true;
           openedAtIndex = i;
         }
-      } else if (prompt) {
+      } else {
         open = false;
       }
       continue;
@@ -5306,12 +5609,36 @@ export function isCloseReconfirmDeclined(transcriptPath) {
   return declined;
 }
 
+// Events Claude Code actually reads additionalContext from, per the "Add
+// context for Claude" docs. A hookEventName outside this set has no
+// documented injection path, so buildOutput still emits the nested shape
+// (the caller may be adding a NEW event later) but warns to stderr.
+const INJECTABLE_EVENTS = new Set(['UserPromptSubmit', 'SessionStart', 'PostToolUse', 'Stop']);
+
 /**
- * Build hook output for Claude Code (additionalContext channel).
- * Codex hooks write systemMessage directly in their own files.
+ * Build hook output for Claude Code (nested hookSpecificOutput.additionalContext
+ * channel). Codex hooks write systemMessage directly in their own files.
+ *
+ * @param {string} hookEventName - the event this hook fires on, e.g. 'UserPromptSubmit'.
+ * @param {string} context - the text to inject.
+ * @param {object} [extra] - control fields (continue, suppressOutput, ...) that
+ *   stay top-level siblings of hookSpecificOutput.
  */
-export function buildOutput(context, extra = {}) {
-  return { ...extra, additionalContext: context };
+export function buildOutput(hookEventName, context, extra = {}) {
+  if (!INJECTABLE_EVENTS.has(hookEventName)) {
+    process.stderr.write(
+      `[hypo] buildOutput: ${hookEventName} has no documented context-injection path\n`,
+    );
+  }
+  // `extra` carries control fields, never context. Dropping the key here is
+  // what makes the nested shape the only channel: without it a caller could
+  // pass `{ additionalContext }` and the spread would put a top-level copy
+  // right back, which is the exact bug this function exists to prevent.
+  const { additionalContext: _shadowed, ...control } = extra;
+  return {
+    ...control,
+    hookSpecificOutput: { hookEventName, additionalContext: context },
+  };
 }
 
 // ── growth metrics (F2 + E4) ───────────────────────────────────────────────