session-orchestrator 4.2.0 → 5.0.0

package/hooks/enforce-scope.mjs

@@ -22,6 +22,11 @@
  *       Runs before G6 so a deliberate out-of-repo grant (e.g. a vault path)
  *       is reachable at all — G6 would otherwise deny every out-of-repo path
  *       without ever consulting allowedPaths. See matchesAbsoluteAllowlist.
+ *   G5c (#1295) out-of-root carveout for THIS repo's Claude Code auto-memory
+ *       directory (`~/.claude/projects/<encoded-repo-path>/memory/`). Harness-
+ *       owned, lives outside the working copy, cannot collide with any wave
+ *       scope. Evaluated inside G6's out-of-root branch only; a SIBLING repo's
+ *       memory dir and every other out-of-repo path stay denied.
  *   G6  resolved path inside project root
  *   G7  relative path matches an allowedPaths pattern
  *   G8  (all passed) → allow
@@ -432,6 +437,73 @@ async function main() {
 
   // Gate 6: path must be inside the project root
   if (!isPathInside(resolvedPath, projectRoot)) {
+    // Gate 5c (#1295) — THIS repo's harness auto-memory directory.
+    //
+    // Claude Code writes its own auto-memory (`MEMORY.md` + per-fact files)
+    // OUTSIDE the working copy, at
+    // `~/.claude/projects/<encoded-repo-path>/memory/`. Every wave manifest
+    // therefore blocked the coordinator's memory writes until the manifest was
+    // torn down — six sessions in a consumer repo re-documented the same
+    // workaround (bewerbungs-assistent#307, retro 2026-09-09). That directory
+    // is harness-owned and cannot collide with ANY wave file scope, so it is
+    // always-allowed territory; it is the single out-of-repo carveout here.
+    //
+    // NARROWNESS (security boundary — no wider allow than this one directory):
+    //   - Only the memory dir of THIS repo, as the harness names it. That name
+    //     is NOT unique: `encodeProjectDir()` maps both `/` and `.` to `-`, so
+    //     `/x/a.b` and `/x/a-b` share one memory dir — a harness-level collision
+    //     this gate inherits and cannot narrow. Every OTHER sibling repo's
+    //     memory dir stays denied.
+    //   - Containment is exact-prefix on the REALPATH-resolved candidate, so
+    //     `..` segments and symlink tricks cannot widen it.
+    //   - Evaluated only on the out-of-root branch: the in-repo gates (Gate 7,
+    //     Discovery's `allowedPaths: []` deny-all) are untouched.
+    //
+    // Encoder REUSED, never re-written (BV-001 rung 2): `encodeProjectDir()`
+    // from `scripts/lib/wave-transcript-tail.mjs` is the repo's one encoder for
+    // `<encoded-repo-path>`. Bound LAZILY here rather than in `bootstrap()` —
+    // same pattern as the G3b event import above — so the happy path pays no
+    // module load, and an import failure falls through to the deny below
+    // (fail-closed, byte-identical to the pre-#1295 behaviour).
+    //
+    // CEILING (BV-004): `CLAUDE_CONFIG_DIR` is NOT honoured, because nothing in
+    // this codebase honours it today (`rg -n "CLAUDE_CONFIG_DIR" scripts hooks`
+    // → 0 matches, 2026-09-13) and `wave-transcript-tail.mjs` resolves the same
+    // substrate from `homedir()`. Revisit together with that resolver if the
+    // harness config dir ever becomes relocatable here.
+    // CALLER DISCRIMINATION (#1352): the carve-out is the COORDINATOR's, never a
+    // dispatched wave agent's. See {@link classifyCaller} for the measurement.
+    // A subagent falls through to the gates below — under a manifest that does
+    // not grant the path (Discovery's `allowedPaths: []`) that is a DENY.
+    const memoryDirs = await ownMemoryDirs(projectRootRaw, projectRoot);
+    const caller = classifyCaller(input);
+    if (caller !== 'subagent' && memoryDirs.some((dir) => isInsideDir(resolvedPath, dir))) {
+      // One event per decision point, awaited before emitAllow() —
+      // emitAllow() calls process.exit(), which would discard a pending append.
+      try {
+        const { emitEvent } = await import('../scripts/lib/events.mjs');
+        await emitEvent(
+          'orchestrator.scope.memory_dir_allowed',
+          {
+            hook: HOOK_NAME,
+            manifest: scopePath,
+            wave: scope.wave,
+            file_path: resolvedPath,
+            // HR-105: the fail-OPEN case must be COUNTABLE, or the ambiguity is
+            // unfalsifiable — and it takes TWO values to be countable.
+            // `'absent'` = no `agent_id` key at all (the harness's own contract
+            // for a main-thread call); `'malformed'` = an `agent_id` key that is
+            // PRESENT but unusable (number/object/array/blank string), which
+            // would otherwise be indistinguishable from the legitimate case.
+            // `'coordinator'` = `agent_type` without `agent_id`.
+            discriminator: caller,
+          },
+          { repoRoot: projectRoot },
+        );
+      } catch { /* observability is best-effort — never blocks the decision */ }
+      return emitAllow();
+    }
+
     const reason = `Scope violation: path outside project root`;
     const suggestion = suggest(filePath);
     return enforcement === 'strict'
@@ -500,6 +572,135 @@ async function mtimeMsOf(file) {
   }
 }
 
+/**
+ * #1295 — the Claude Code auto-memory directories that belong to THIS repo.
+ *
+ * Returns at most two paths, both naming the SAME repo: the encoding of the
+ * project root as the harness saw it (`CLAUDE_PROJECT_DIR` / cwd) and — when it
+ * differs — the encoding of its realpath. Both are needed because Claude Code
+ * encodes the path it was LAUNCHED with, while this hook compares against the
+ * canonical root (on macOS `/tmp` → `/private/tmp`). Two encodings of one repo
+ * is not a wider grant: a sibling repo's root encodes to neither.
+ *
+ * Returns `[]` when the encoder cannot be loaded, so the caller falls through to
+ * its deny (fail-closed).
+ *
+ * @param {string} projectRootRaw — project root as resolved from env/cwd
+ * @param {string} projectRoot — its realpath
+ * @returns {Promise<string[]>}
+ */
+async function ownMemoryDirs(projectRootRaw, projectRoot) {
+  try {
+    const [{ encodeProjectDir }, { homedir }] = await Promise.all([
+      import('../scripts/lib/wave-transcript-tail.mjs'),
+      import('node:os'),
+    ]);
+    const home = homedir();
+    if (!home) return [];
+    // The candidate arrives REALPATH-resolved (SECURITY-REQ-03), so the home
+    // side must be too — otherwise the macOS `/tmp` → `/private/tmp` symlink
+    // alone makes every comparison miss.
+    let homeReal = home;
+    try {
+      homeReal = await fs.realpath(home);
+    } catch { /* non-existent home — the raw form is all there is */ }
+    const homes = new Set([home, homeReal]);
+    const roots = new Set(
+      [projectRootRaw, projectRoot].filter((p) => typeof p === 'string' && p.length > 0),
+    );
+    const dirs = [];
+    for (const h of homes) {
+      for (const root of roots) {
+        dirs.push(path.join(h, '.claude', 'projects', encodeProjectDir(root), 'memory'));
+      }
+    }
+    return dirs;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Exact-prefix containment: is `candidate` `dir` itself or a descendant of it?
+ *
+ * Both sides are `path.resolve`d first, so `..` segments collapse before the
+ * comparison and cannot escape `dir`. The `path.sep` suffix is load-bearing —
+ * without it `<dir>-evil/x` would match the prefix of `<dir>`.
+ *
+ * @param {string} candidate
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isInsideDir(candidate, dir) {
+  const base = path.resolve(dir);
+  const target = path.resolve(candidate);
+  return target === base || target.startsWith(base + path.sep);
+}
+
+/**
+ * Classify a PreToolUse payload as coming from a dispatched SUBAGENT or from the
+ * main (coordinator) thread — the discriminator Gate 5c's memory carve-out needs
+ * (#1352).
+ *
+ * MEASURED, not assumed (2026-09-13, Claude Code 2.1.270, `strings` over
+ * `~/.local/share/claude/versions/2.1.270`):
+ *  - The base hook-input builder shared by EVERY event is
+ *    `{session_id: e.id, transcript_path: yf(e.id), cwd, …, agent_id: s?.agentId,
+ *    agent_type: d}` — PreToolUse spreads it verbatim
+ *    (`{...Na(s.session,Z(),d,s), hook_event_name:"PreToolUse", tool_name, …}`).
+ *  - The harness's own schema documents the field: *"Subagent identifier. Present
+ *    only when the hook fires from within a subagent (e.g., a tool called by an
+ *    AgentTool worker). Absent for the main thread, even in --agent sessions. Use
+ *    this field (not agent_type) to distinguish subagent calls from main-thread
+ *    calls."*
+ *  - Two candidates are REFUTED by the same source: `transcript_path` is
+ *    `yf(session.id)` — session-derived, hence IDENTICAL for coordinator and
+ *    subagent; and `CLAUDE_CODE_CHILD_SESSION=1` appears in a main-thread `env`
+ *    dump (`isSidechain:false`), so it marks the CLI process, not the caller.
+ *
+ * `agent_type` is deliberately a WEAKER witness, used only in the negative
+ * direction: per the same schema it is present on the main thread of an `--agent`
+ * session WITHOUT `agent_id`, so `agent_type`-without-`agent_id` positively names
+ * a coordinator, while `agent_type` alone can never name a subagent.
+ *
+ * FAIL-OPEN on ambiguity, deliberately (BV-004 ceiling): a payload this function
+ * cannot read as a subagent keeps the pre-#1352 ALLOW, because fail-closed here
+ * would deny the coordinator's own memory writes and break `/close`. The value is
+ * emitted on the event so the ambiguity is countable (HR-105) — but countability
+ * needs TWO fail-open values, not one:
+ *
+ *  - `'absent'`    — NO `agent_id` key in the payload at all. The harness's own
+ *                    documented shape for a main-thread call; the legitimate case.
+ *  - `'malformed'` — an `agent_id` key IS present and carries something this
+ *                    function cannot use as an identity (number, object, array,
+ *                    empty/whitespace string). Folding this into `'absent'` made a
+ *                    PRESENT-but-unusable marker byte-identical to a genuine
+ *                    main-thread call, so a future harness or bridge sending a
+ *                    numeric or object agent id would hand EVERY subagent the
+ *                    carve-out with nothing in the ledger to show it. Empty and
+ *                    whitespace-only strings belong here, not in `'absent'`: the
+ *                    key is present, so the sender believed it was identifying a
+ *                    subagent, and that is exactly the case this value separates.
+ *
+ * Only `agent_id` can produce `'malformed'`. `agent_type` is used solely in the
+ * positive coordinator direction and can never hide a subagent, so an unusable
+ * `agent_type` without an `agent_id` stays `'absent'`.
+ *
+ * Revisit if `discriminator: 'malformed'` appears at all, or if `'absent'`
+ * dominates the records on a harness that DOES dispatch subagents.
+ *
+ * @param {Record<string, unknown>} input Parsed PreToolUse stdin payload.
+ * @returns {'subagent'|'coordinator'|'malformed'|'absent'}
+ */
+function classifyCaller(input) {
+  const agentId = input?.agent_id;
+  if (typeof agentId === 'string' && agentId.trim() !== '') return 'subagent';
+  if (agentId !== undefined && agentId !== null) return 'malformed';
+  const agentType = input?.agent_type;
+  if (typeof agentType === 'string' && agentType.trim() !== '') return 'coordinator';
+  return 'absent';
+}
+
 const COORDINATOR_CARVEOUT_PATHS = Object.freeze([
   '.claude/STATE.md',
   '.codex/STATE.md',

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v4.2.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.0.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks-cursor.json

@@ -161,6 +161,11 @@
             "type": "command",
             "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-tool-failure-corrective-context.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CURSOR_PLUGIN_ROOT/hooks/run-node.sh\" \"$CURSOR_PLUGIN_ROOT/hooks/post-bash-issue-budget-refund.mjs\"",
+            "timeout": 5
           }
         ]
       }

package/hooks/hooks.json

@@ -2,11 +2,11 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|clear|compact",
+        "matcher": "startup|resume|clear|compact",
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v4.2.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.0.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {
@@ -206,6 +206,11 @@
             "type": "command",
             "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/post-tool-failure-corrective-context.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/post-bash-issue-budget-refund.mjs\"",
+            "timeout": 5
           }
         ]
       }

package/hooks/on-session-start.mjs

@@ -54,6 +54,11 @@ import { detectColdStart, consumeMarker } from '../scripts/lib/cold-start-detect
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { readTelemetryState, resolveConsent, isCiEnv } from '../scripts/lib/telemetry/consent.mjs';
 import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
+// SSOT for the "is this a re-entry into the same logical session?" question
+// (#1091). Defined in the lock-bootstrap leaf module, which this hook already
+// loads, so the preservation branch below and the lock force-refresh gate can
+// never drift apart.
+import { SAME_LOGICAL_SESSION_SOURCES } from './_lib/lock-bootstrap.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -336,6 +341,9 @@ async function readStdinJson(timeoutMs = 500) {
  * Best-effort: any persistence failure is swallowed (hook must remain non-blocking).
  */
 async function resolveSessionId(input, projectRoot) {
+  const nativeSource = typeof input?.source === 'string' && input.source.length > 0
+    ? input.source
+    : null;
   const fromStdin = (input && (input.session_id || input.sessionId)) ?? null;
   const parsedStdinId = parseSessionId(fromStdin);
   const rawStdinSessionId = parsedStdinId?.format === 'uuid' ? fromStdin : null;
@@ -364,61 +372,136 @@ async function resolveSessionId(input, projectRoot) {
     source = 'generated-uuid';
   }
 
+  const sessionFilePath = path.join(projectRoot, '.orchestrator', 'current-session.json');
+
+  // Read the PREVIOUS current-session.json BEFORE minting a semantic id: on a
+  // same-logical-session re-entry it decides whether a new id is minted at all
+  // (#1091 F1 below). Best-effort — absent/unparseable leaves prev = null.
+  let prev = null;
+  try {
+    prev = JSON.parse(await readFile(sessionFilePath, 'utf8'));
+    if (typeof prev !== 'object' || prev === null) prev = null;
+  } catch { /* absent / unparseable → no linkage, no preservation */ }
+
+  // #1091 F1 — raw-id linkage on a same-logical-session re-entry.
+  //
+  // resolveSemanticSessionId() has NO self-exclusion: it projects every active
+  // session (including OUR OWN lock and registry entry) to n and returns
+  // maxN + 1. So a second SessionStart of the SAME session mints
+  // `…-session-31` where the first minted `…-session-30`, the
+  // `prev.semantic_session_id === semanticSessionId` preservation branch below
+  // is FALSE, and last_wave / last_batch / last_wave_completed /
+  // wave_start_sha are dropped — re-opening #612, #980 and #1193. Before
+  // #1091 that path was unreachable on Claude Code because `resume` was absent
+  // from the SessionStart matcher; adding it made it live.
+  //
+  // The trustworthy linkage is the RAW id: Claude Code preserves `session_id`
+  // across a native resume, and current-session.json records the raw id the
+  // previous invocation of this hook resolved. When it matches, this is
+  // provably the same logical session and its semantic label is REUSED rather
+  // than re-minted. When it does NOT match, today's behaviour stands (fresh
+  // id, no preservation) — that is the "unverified restart" #1091 defines, and
+  // guessing continuity there would adopt a foreign session's high-water marks
+  // (`.claude/rules/identity-and-locks.md` — a working-copy artefact is not an
+  // identity witness).
+  //
+  // Sources: `clear` and `compact` are re-entries into the same logical
+  // session for exactly the reason the comment block below states (the UUID
+  // changes, the semantic label does not); `resume` is the third per #1091.
+  // `startup` is deliberately absent — a fresh process start must never
+  // inherit a predecessor's markers.
+  let resumeLinkage = 'none';
+  if (
+    nativeSource !== null
+    && SAME_LOGICAL_SESSION_SOURCES.has(nativeSource)
+    && prev
+    && prev.session_id === sessionId
+    && typeof prev.semantic_session_id === 'string'
+    && prev.semantic_session_id.length > 0
+  ) {
+    semanticSessionId = prev.semantic_session_id;
+    resumeLinkage = 'raw-id';
+  }
+
   // Derive a descriptive semantic label for either raw-id source. Best-effort:
   // a failure leaves it null without changing the physical raw session_id.
-  try {
-    const semCandidate = await deriveSemanticCandidate({
-      projectRoot,
-      mode: normalizedMode,
-    });
-    if (semCandidate) semanticSessionId = semCandidate;
-  } catch { /* best effort — leave semanticSessionId = null */ }
+  if (semanticSessionId === null) {
+    try {
+      const semCandidate = await deriveSemanticCandidate({
+        projectRoot,
+        mode: normalizedMode,
+      });
+      if (semCandidate) semanticSessionId = semCandidate;
+    } catch { /* best effort — leave semanticSessionId = null */ }
+  }
 
   try {
-    const dir = path.join(projectRoot, '.orchestrator');
-    await mkdir(dir, { recursive: true });
-    const sessionFilePath = path.join(dir, 'current-session.json');
+    await mkdir(path.dirname(sessionFilePath), { recursive: true });
 
     // High-water-mark preservation (#612 root-cause fix).
-    // SessionStart fires on startup|clear|compact|resume of the SAME logical
-    // session. On clear/compact/resume the UUID `session_id` changes but the
-    // `semantic_session_id` (branch+date+mode+n) stays stable. A naive full
-    // overwrite of current-session.json drops the `last_wave` / `last_batch`
-    // markers written mid-session by post-tool-batch-wave-signal.mjs, which
-    // makes the next PostToolBatch re-read last_wave as absent→0 and re-emit a
-    // duplicate orchestrator.wave.started{N} with no intervening
-    // wave.completed. To prevent that, PRESERVE last_wave/last_batch across a
-    // SessionStart of the SAME logical session (matching semantic id), while
-    // still RESETTING them for a genuinely new session (different/absent
-    // semantic id, or an unparseable prior file). Best-effort: a read failure
-    // must never throw — we simply fall through to the reset path.
+    // SessionStart fires once per source in the matcher of the platform's
+    // hooks file — `startup|resume|clear|compact` on Claude Code and Codex
+    // (`resume` was ABSENT from hooks.json until #1091, so on Claude Code this
+    // hook never ran on a native resume), `startup|reload|new|resume|fork` on
+    // pi, and every source on Cursor (empty matcher). Several of those sources
+    // are re-entries into the SAME logical session. On clear/compact the UUID
+    // `session_id` changes while the `semantic_session_id`
+    // (branch+date+mode+n) stays stable; whether Claude Code PRESERVES the raw
+    // `session_id` across a native resume is what #1091 measures via
+    // `native_source` + `resume_linkage` on `orchestrator.session.started` —
+    // nothing here ASSUMES either answer, it only reacts to the raw id it can
+    // observe. A naive full overwrite of current-session.json drops the
+    // `last_wave` / `last_batch` markers written mid-session by
+    // post-tool-batch-wave-signal.mjs, which makes the next PostToolBatch
+    // re-read last_wave as absent→0 and re-emit a duplicate
+    // orchestrator.wave.started{N} with no intervening wave.completed.
+    //
+    // Three cases, exactly one of which preserves nothing:
+    //   'raw-id'   — same-logical-session source AND the recorded raw
+    //                session_id equals ours → the semantic label was reused
+    //                above, markers PRESERVED. (#1091 F1)
+    //   'semantic' — the freshly minted label equals the recorded one →
+    //                markers PRESERVED. The pre-#1091 behaviour, unchanged.
+    //   'none'     — a genuinely new session, or an unverified restart
+    //                (raw id changed, label re-minted) → markers RESET.
+    // Best-effort throughout: `prev` is null on a read/parse failure, which
+    // lands in 'none' and therefore on the reset path.
     const preserved = {};
     if (typeof semanticSessionId === 'string' && semanticSessionId.length > 0) {
-      try {
-        const prevRaw = await readFile(sessionFilePath, 'utf8');
-        const prev = JSON.parse(prevRaw);
-        if (prev && prev.semantic_session_id === semanticSessionId) {
-          if (Object.prototype.hasOwnProperty.call(prev, 'last_wave')) {
-            preserved.last_wave = prev.last_wave;
-          }
-          if (Object.prototype.hasOwnProperty.call(prev, 'last_batch')) {
-            preserved.last_batch = prev.last_batch;
-          }
-          // #1193 — the final-wave completion marker must survive a
-          // clear/compact too: dropping it re-arms a duplicate SessionEnd
-          // `orchestrator.wave.completed` for a wave already closed.
-          if (Object.prototype.hasOwnProperty.call(prev, 'last_wave_completed')) {
-            preserved.last_wave_completed = prev.last_wave_completed;
-          }
-          // #980 — the OPEN half of the wave-diff pair, written by
-          // post-tool-batch-wave-signal.mjs. Dropping it across a /clear leaves
-          // the running wave with no start point, so the next
-          // `orchestrator.wave.completed` silently omits `files_changed`.
-          if (Object.prototype.hasOwnProperty.call(prev, 'wave_start_sha')) {
-            preserved.wave_start_sha = prev.wave_start_sha;
-          }
+      // Two ways into the SAME logical session, both preserving:
+      //   1. `resumeLinkage === 'raw-id'` — the raw session_id matched on a
+      //      resume/clear/compact re-entry, so the label above was REUSED
+      //      (#1091 F1). Reachable since `resume` entered the matcher.
+      //   2. semantic match — the freshly minted label equals the recorded
+      //      one. This is the case the branch already covered (a clear or
+      //      compact whose discovery view happened to re-mint the same n),
+      //      and it stays untouched.
+      // Anything else (different or absent semantic id, unparseable prior
+      // file, `startup`) is a genuinely new session and RESETS the markers.
+      if (resumeLinkage === 'none' && prev && prev.semantic_session_id === semanticSessionId) {
+        resumeLinkage = 'semantic';
+      }
+      if (prev && (resumeLinkage === 'raw-id' || prev.semantic_session_id === semanticSessionId)) {
+        if (Object.prototype.hasOwnProperty.call(prev, 'last_wave')) {
+          preserved.last_wave = prev.last_wave;
+        }
+        if (Object.prototype.hasOwnProperty.call(prev, 'last_batch')) {
+          preserved.last_batch = prev.last_batch;
         }
-      } catch { /* absent / unparseable → no preservation (reset) */ }
+        // #1193 — the final-wave completion marker must survive a
+        // clear/compact too: dropping it re-arms a duplicate SessionEnd
+        // `orchestrator.wave.completed` for a wave already closed.
+        if (Object.prototype.hasOwnProperty.call(prev, 'last_wave_completed')) {
+          preserved.last_wave_completed = prev.last_wave_completed;
+        }
+        // #980 — the OPEN half of the wave-diff pair, written by
+        // post-tool-batch-wave-signal.mjs. Dropping it across a /clear leaves
+        // the running wave with no start point, so the next
+        // `orchestrator.wave.completed` silently omits `files_changed`.
+        if (Object.prototype.hasOwnProperty.call(prev, 'wave_start_sha')) {
+          preserved.wave_start_sha = prev.wave_start_sha;
+        }
+      }
     }
 
     // Epic #583 W5-F1c — surface semantic_session_id (Q5 H1 / Issue #587 completion).
@@ -441,7 +524,19 @@ async function resolveSessionId(input, projectRoot) {
     );
   } catch { /* best effort */ }
 
-  return { sessionId, semanticSessionId, mode: normalizedMode };
+  return {
+    sessionId,
+    semanticSessionId,
+    mode: normalizedMode,
+    nativeSource,
+    resumeLinkage,
+    // The raw session_id our OWN previous run of this hook recorded, or null.
+    // Surfaced (rather than kept local) because bootstrapLock() needs it as the
+    // third conjunct of the #1091 F2 force-refresh — see the call site in main().
+    predecessorSessionId: typeof prev?.session_id === 'string' && prev.session_id.length > 0
+      ? prev.session_id
+      : null,
+  };
 }
 
 /**
@@ -711,7 +806,12 @@ async function main() {
   // v3.1.0 multi-session registry (#168). All steps best-effort — failures
   // must never break the hook, which is informational-only.
   const input = await stdinPromise;
-  const { sessionId, semanticSessionId, mode } = await resolveSessionId(input, projectRoot);
+  // #1091 — the native SessionStart `source` (Claude Code: startup|resume|
+  // clear|compact), plus the linkage decision resolveSessionId() derived from
+  // it (see SAME_LOGICAL_SESSION_SOURCES). Both are surfaced on the event so
+  // #1091 gets its measurement instead of an inference.
+  const { sessionId, semanticSessionId, mode, nativeSource, resumeLinkage, predecessorSessionId } =
+    await resolveSessionId(input, projectRoot);
   // getPlatform() ALREADY implements the SO_PLATFORM override as step 1 of its
   // precedence — and, unlike a bare `??`, it validates the value against the
   // four-platform allowlist and trims it. The former `process.env.SO_PLATFORM ??
@@ -737,6 +837,13 @@ async function main() {
       semanticSessionId,
       mode,
       ttlHours: 4,
+      nativeSource,
+      // The raw session_id our OWN previous run of this hook recorded. It is the
+      // third conjunct of the same-logical-session force-refresh (#1091 F2): a
+      // semantic-label match alone is collidable on one host (#1066), so the
+      // live lock must ALSO carry our predecessor's raw id before we take it
+      // over. `prev` is read above, before the semantic id is minted.
+      predecessorSessionId,
     });
   } catch { /* hook must remain non-blocking */ }
 
@@ -927,7 +1034,7 @@ async function main() {
 
   // Phase 4 measurement probes — the mechanical caller (#1128).
   //
-  // `skills/session-start/SKILL.md` § Phase 4 names 18 probes with module paths
+  // `skills/session-start/SKILL.md` § Phase 4 names 19 probes with module paths
   // and entry functions. Measured 2026-08-23 at `4f6404e`, not one of them had
   // a caller anywhere in hooks/, npm scripts, .gitlab-ci.yml or .husky/ — the
   // only caller was the prose itself, and across 336 recorded session starts
@@ -1008,6 +1115,21 @@ async function main() {
     peers_superseded: mechanicalPeersSuperseded,
   };
 
+  // #1091 — record the native SessionStart source so "does the same raw
+  // session_id repeat under source=resume?" becomes answerable from
+  // events.jsonl instead of guessed. OMITTED when the harness sends no source
+  // (docs/events-schema.md optional-field convention: absent ≠ measured-empty).
+  if (nativeSource) payload.native_source = nativeSource;
+
+  // #1091 F1 — WHICH linkage the source produced: 'raw-id' (prior raw
+  // session_id matched → semantic label reused, high-water marks preserved),
+  // 'semantic' (the freshly minted label happened to equal the recorded one),
+  // or 'none' (a new session, or an unverified restart whose continuity is
+  // deliberately not guessed). Same optional-field convention as
+  // `native_source`: OMITTED when the harness sends no source at all, so a
+  // Codex/Cursor row is never read as a measured 'none'.
+  if (nativeSource) payload.resume_linkage = resumeLinkage;
+
   // #nnn — installed/latest plugin version on the session record.
   //
   // HR-105: a verdict nothing records is unfalsifiable. `installed` is stamped