session-orchestrator 3.17.0 → 3.19.0

package/hooks/hooks-pi.json

@@ -88,6 +88,16 @@
           }
         ]
       },
+      {
+        "matcher": "bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$PI_PLUGIN_ROOT/hooks/run-node.sh\" \"$PI_PLUGIN_ROOT/hooks/post-bash-write-verify.mjs\"",
+            "timeout": 5
+          }
+        ]
+      },
       {
         "matcher": "*",
         "hooks": [

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v3.17.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v3.19.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {
@@ -74,11 +74,21 @@
             "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/pre-bash-memory-propose-audit.mjs\"",
             "timeout": 5
           },
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/pre-bash-sessions-ledger-guard.mjs\"",
+            "timeout": 5
+          },
           {
             "type": "command",
             "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/pre-bash-templates-first.mjs\"",
             "timeout": 5
           },
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/pre-bash-issue-budget.mjs\"",
+            "timeout": 5
+          },
           {
             "type": "command",
             "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/enforce-commands.mjs\"",
@@ -108,6 +118,16 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/post-bash-write-verify.mjs\"",
+            "timeout": 5
+          }
+        ]
+      },
       {
         "matcher": "*",
         "hooks": [

package/hooks/on-session-end.mjs

@@ -31,7 +31,14 @@ if (!shouldRunHook('on-session-end')) process.exit(0);
 import { emitEvent } from '../scripts/lib/events.mjs';
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
 import { backfillAbandonedSession } from '../scripts/lib/session-close-backfill.mjs';
-import { readLock, release } from '../scripts/lib/session-lock.mjs';
+import {
+  readLockDetailed,
+  release,
+  isLockLive,
+  loadOwnerProof,
+  isLockOwnedByProof,
+  OWNER_PROOF_RELPATH,
+} from '../scripts/lib/session-lock.mjs';
 import { attemptLockReconciliation } from './_lib/lock-reconcile.mjs';
 
 // ---------------------------------------------------------------------------
@@ -77,6 +84,19 @@ async function readStdinJson() {
  * keyed by, and the id the backfill (C1 #724) uses when the stdin session_id is
  * a harness UUID with no lock.acquired bridge.
  *
+ * #863 defect (c) — `semanticSessionId` is gated by the SAME "ending session
+ * IS the recorded one" check as `durationMs` above. `current-session.json` is
+ * a single repo-global file: it always reflects whichever session most
+ * recently ran SessionStart, which may be a DIFFERENT, still-live session
+ * when multiple windows share this repo. Before this fix, a foreign
+ * terminating window (its own stdin `session_id` explicitly present, but NOT
+ * equal to the recorded session) still inherited the CURRENTLY-recorded
+ * session's `semantic_session_id` unconditionally — main()'s `ownBySemantic`
+ * check then matched that OTHER, still-running session's lock and released
+ * it. Gating this field closes that window: an unrelated/mismatched ending
+ * session now resolves `semanticSessionId: null`, so `ownBySemantic` can
+ * never accidentally fire on someone else's identity.
+ *
  * @param {object|null} input
  * @param {string} projectRoot
  * @returns {Promise<{sessionId: string|null, semanticSessionId: string|null, durationMs: number}>}
@@ -109,12 +129,18 @@ async function resolveSession(input, projectRoot) {
   if (sessionId === null) sessionId = recordedId;
 
   // Only trust the recorded start time when the ending session IS the recorded one.
-  const durationMs =
-    startedAtMs !== null && sessionId !== null && sessionId === recordedId
-      ? Math.max(0, Date.now() - startedAtMs)
-      : 0;
+  const isRecordedSession = sessionId !== null && sessionId === recordedId;
+  const durationMs = startedAtMs !== null && isRecordedSession
+    ? Math.max(0, Date.now() - startedAtMs)
+    : 0;
+
+  // #863 defect (c) — same guard as durationMs above: only surface the
+  // recorded semantic id when THIS ending session is genuinely the one
+  // current-session.json describes. See the docblock above for the exact
+  // contamination scenario this closes.
+  const resolvedSemanticSessionId = isRecordedSession ? semanticSessionId : null;
 
-  return { sessionId, semanticSessionId, durationMs };
+  return { sessionId, semanticSessionId: resolvedSemanticSessionId, durationMs };
 }
 
 // ---------------------------------------------------------------------------
@@ -173,14 +199,93 @@ async function main() {
   //     reapRepoLock(), which independently NEVER reaps a live lease (and only
   //     ever reaps on this same host with a dead recorded PID).
   try {
-    const lock = readLock({ repoRoot: projectRoot });
-    if (lock) {
+    // readLockDetailed (additive, see its JSDoc in session-lock.mjs) replaces
+    // readLock() here so an unreadable/corrupt lock file is DISTINGUISHABLE
+    // from a genuinely absent one, instead of both collapsing to the same
+    // `null`. Only 'absent' is treated as "nothing to release/reconcile" —
+    // 'unreadable'/'corrupt' is an anomaly worth a breadcrumb, since a lock we
+    // cannot even parse is neither released nor reconciled below, and used to
+    // silently look identical to "no lock, all clear".
+    const lockDetail = readLockDetailed({ repoRoot: projectRoot });
+
+    if (lockDetail.status === 'unreadable' || lockDetail.status === 'corrupt') {
+      try {
+        await emitEvent('orchestrator.session.lock.read_anomaly', {
+          session_id: sessionId,
+          status: lockDetail.status,
+          ...(lockDetail.status === 'unreadable' ? { error: lockDetail.error } : {}),
+        });
+      } catch { /* observability is best-effort */ }
+    } else if (lockDetail.status === 'ok') {
+      const lock = lockDetail.lock;
       const ownByUuid = sessionId !== null && lock.session_id === sessionId;
-      const ownBySemantic =
+      const ownBySemanticStrict =
         semanticSessionId !== null && lock.semantic_session_id === semanticSessionId;
+      // #863 (d) — lock-shape trap: some on-disk locks store the semantic id
+      // directly in `session_id` with no separate `semantic_session_id` field
+      // at all (the "generated-semantic" acquisition path in
+      // on-session-start.mjs mints `session_id === the semantic id`, and
+      // bootstrapLock's v2 enrichment step never ran for that lock). Without
+      // this fallback, ownBySemanticStrict is dead code for that shape.
+      const ownBySemanticFallback =
+        semanticSessionId !== null && lock.session_id === semanticSessionId;
+      const ownBySemantic = ownBySemanticStrict || ownBySemanticFallback;
 
-      if (ownByUuid || ownBySemantic) {
-        const releaseResult = release({ sessionId: lock.session_id, repoRoot: projectRoot });
+      // #987 Part 2 — persisted ownership proof (pid + host + started_at,
+      // written at lock genesis by bootstrapLock Step 2b, see
+      // writeOwnerProof() in session-lock.mjs). loadOwnerProof() is
+      // fail-closed: a missing/corrupt proof file yields null, and a null
+      // proof presented to isLockOwnedByProof() yields false — the hook then
+      // degrades to exactly the pre-#987 (proof-less) behaviour below.
+      const proof = loadOwnerProof({ repoRoot: projectRoot });
+      const ownByProof = isLockOwnedByProof(lock, proof);
+
+      // #906-class fix: the semantic session id
+      // (`<branch>-<date>-<mode>-<n>`) is NOT globally unique — the
+      // id-counter can hand out the SAME id to two different session
+      // processes (live-observed twice on 2026-07-29: `main-2026-07-29-deep-1`
+      // and `main-2026-07-29-session-1`, each assigned to two distinct
+      // sessions). A live lock matched ONLY via a collidable semantic id
+      // (strict OR fallback, never corroborated by a non-collidable factor)
+      // is therefore NEVER trusted for release.
+      //
+      // #987 Part 2 — the discrimination the #906-class fix escalated as
+      // "structurally unobservable" is now OBSERVABLE via the persisted
+      // owner proof: a genuine same-session UUID rotation (clear/compact)
+      // and a foreign same-day semantic collision used to produce the
+      // IDENTICAL shape here (UUID mismatch + semantic match on a live
+      // lock), so the previous fix conservatively left BOTH un-released
+      // (bounded by the ttl_hours reaper). The proof written at lock genesis
+      // (pid + host + started_at — presence-at-genesis, never the collidable
+      // session_id/semantic id, see the FACTOR CHOICE docblock on
+      // isLockOwnedByProof()) is exactly the discriminator that RCR-007
+      // escalation named: on a self-rotation the on-disk lock is FROZEN at
+      // its pre-rotation values (bootstrapLock's shouldForce is false for a
+      // rotated UUID, so it bails without touching the lock), which are the
+      // SAME values the proof captured at genesis → ownByProof is true → the
+      // lock is released correctly. A foreign same-day collision wrote its
+      // lock in a DIFFERENT process at a DIFFERENT millisecond → ownByProof
+      // is false → semanticOnlyLive stays true → no release, the foreign
+      // lease survives (the never-release-a-foreign-lock invariant is
+      // untouched). No proof on disk (pre-#987 sessions, failed proof
+      // write) → ownByProof false → the conservative pre-#987 behaviour.
+      const semanticOnlyLive = !ownByUuid && !ownByProof && ownBySemantic && isLockLive(lock);
+      const releaseEligible = (ownByUuid || ownBySemantic) && !semanticOnlyLive;
+
+      if (releaseEligible) {
+        // Defense-in-depth (#987): when a persisted proof exists, hand it to
+        // release() so the delete is double-gated (session_id match AND
+        // proof match) at the fs layer too. TRAP — release()'s proof gate
+        // triggers on `proof !== undefined`, so a null proof MUST be
+        // spread-guarded out: passing `proof: null` would fail
+        // isLockOwnedByProof() unconditionally and refuse EVERY release.
+        // A 'proof-mismatch' result flows into the existing release_failed
+        // breadcrumb below (releaseResult.reason surfaces verbatim).
+        const releaseResult = release({
+          sessionId: lock.session_id,
+          repoRoot: projectRoot,
+          ...(proof ? { proof } : {}),
+        });
         // release() has a no-throw contract (always returns a structured
         // result). A matched ownership that still fails to delete — an
         // fs-error, or an unexpected non-delete outcome other than the benign
@@ -194,20 +299,75 @@ async function main() {
               reason: releaseResult.ok
                 ? (releaseResult.reason ?? 'not-deleted')
                 : (releaseResult.reason ?? 'fs-error'),
+              caller: 'on-session-end',
             });
           } catch { /* observability is best-effort */ }
+        } else {
+          // #952 (A) — SUCCESS breadcrumb. Until now ONLY the failure path
+          // emitted: a release that actually worked left zero trace, so
+          // "the hook-lock vanished somewhere in the start chain" (#914
+          // residual 3) was forensically undecidable — an absent lock could
+          // equally mean "we released it cleanly at SessionEnd" or "something
+          // else deleted it". Both REACHED outcomes now emit, distinguished by
+          // `outcome`:
+          //   'deleted'      — we unlinked it ourselves (the normal close).
+          //   'already-gone' — ownership matched, but the lock had ALREADY
+          //                    vanished between readLock() and release()
+          //                    (release() reason 'no-lock'). This is the
+          //                    forensically INTERESTING one: a third party
+          //                    removed our lock while we still held it, which
+          //                    IS the #914 disappearance class. Staying silent
+          //                    on it would leave exactly that signal unobservable.
+          //
+          // `end_reason` (not `reason`) deliberately: the sibling
+          // `…lock.release_failed` event above uses `reason` for the FAILURE
+          // reason, so reusing the key for the SessionEnd reason
+          // (clear|logout|prompt_input_exit|other) inside the same
+          // `orchestrator.session.lock.*` namespace would make any consumer
+          // roll-up over `.reason` mix "clear" with "fs-error".
+          //
+          // Emitted at the CALL-SITE, never inside release(): session-lock.mjs
+          // deliberately carries no dependency on events.mjs, and release() is
+          // synchronous while emitEvent() is async. `caller` keeps the two
+          // release call-sites (this hook and the autopilot worktree pipeline)
+          // distinguishable in the single stream.
+          try {
+            await emitEvent('orchestrator.session.lock.released', {
+              session_id: sessionId,
+              lock_session_id: lock.session_id,
+              semantic_session_id: semanticSessionId,
+              end_reason: reason,
+              caller: 'on-session-end',
+              outcome: benignAlreadyGone ? 'already-gone' : 'deleted',
+              verified: releaseResult.verified === true,
+            });
+          } catch { /* observability is best-effort */ }
+
+          // #987 hygiene — the successful own release consumed the genesis
+          // proof; remove it best-effort. A leftover would be harmless (its
+          // millisecond started_at cannot match any FUTURE lock, so it
+          // self-invalidates), this just avoids the stale artifact. ENOENT
+          // (no proof was ever written) lands in the same swallow.
+          try {
+            await fs.unlink(path.join(projectRoot, OWNER_PROOF_RELPATH));
+          } catch { /* best-effort — a leftover proof is self-invalidating */ }
         }
       } else {
-        // Root-cause reconciliation fallback: neither the UUID nor the
-        // semantic id matched the recorded lock. attemptLockReconciliation()
-        // is the extracted, DI-testable seam (Issue #748) — it internally
-        // no-ops when the lease is still live (isLockLive), and is otherwise
-        // best-effort: reapRepoLock() never touches a live lease, a
-        // cross-host lease, or a lease whose recorded PID is still alive on
-        // this host.
+        // Root-cause reconciliation fallback: either NEITHER the UUID nor the
+        // semantic id matched the recorded lock, OR the ONLY match was a
+        // collidable semantic comparison (strict or fallback) on a lock that
+        // is still live (semanticOnlyLive). attemptLockReconciliation() is
+        // the extracted, DI-testable seam (Issue #748) — it internally
+        // no-ops when the lease is still live (isLockLive), which is exactly
+        // what makes it safe to route the semanticOnlyLive case here too: it
+        // is otherwise best-effort, and reapRepoLock() never touches a live
+        // lease, a cross-host lease, or a lease whose recorded PID is still
+        // alive on this host.
         await attemptLockReconciliation({ repoRoot: projectRoot, sessionId, lock });
       }
     }
+    // 'absent' — no lock file at all; nothing to release or reconcile
+    // (mirrors the pre-existing `if (lock)` guard's false branch).
   } catch { /* best-effort — never block teardown */ }
 }
 

package/hooks/on-session-start.mjs

@@ -542,6 +542,29 @@ async function main() {
     });
   } catch { /* hook must remain non-blocking */ }
 
+  // Epic #926 — close-through backfill at SessionStart (decoupled from /close).
+  // hooks/on-session-end.mjs already backfills, but SessionEnd only fires on a
+  // REGULAR close: a session killed by Ctrl-C, a timeout or a crash leaves no
+  // ledger entry, and the backfill then waits for the NEXT clean close. Running
+  // it here reconstructs the PREVIOUS abandoned session whatever killed it.
+  //
+  // ORDERING IS LOAD-BEARING — this MUST stay before the
+  // `orchestrator.session.started` emit at the end of main(). That ordering is
+  // this session's structural self-exclusion: our own started-event is not in
+  // events.jsonl yet, so we are not a backfill candidate at all. (On a
+  // clear/compact/resume re-fire an earlier started-event IS present; that case
+  // is caught by the core's own `skipped-own-live-lock` guard against the lock
+  // bootstrapped above.) A live FOREIGN session is likewise protected: the core
+  // evaluates lock ownership against the CANDIDATE, so a candidate holding a
+  // live lock is skipped before the dead-by-age relaxation is consulted.
+  //
+  // Best-effort like every other probe here: any failure is swallowed so a
+  // backfill problem can never block a session start.
+  try {
+    const { backfillOnSessionStart } = await import('../scripts/backfill-abandoned-sessions.mjs');
+    await backfillOnSessionStart({ repoRoot: projectRoot });
+  } catch { /* hook must remain non-blocking */ }
+
   let peers = [];
   try {
     await sweepZombies().catch(() => ({ removed: [], logged: 0 }));