session-orchestrator 5.12.0 → 5.13.0

package/scripts/lib/session-end/close-precheck.mjs

@@ -0,0 +1,151 @@
+/**
+ * close-precheck.mjs — the `/close` pre-check as code (#1661).
+ *
+ * The pre-check used to be prose that read `<state-dir>/STATE.md` and acted on
+ * its `status` alone. It never asked whose STATE.md that is. Two failures
+ * followed (2026-10-17, three sessions in one afternoon):
+ *   - After `/clear` the tab runs under a NEW native id while STATE.md still
+ *     carries the previous one. A completed foreign STATE.md read as "already
+ *     finalized", the session answered with the wait sentence although its own
+ *     handover was written, and the inbox kept nudging.
+ *   - A foreign ACTIVE STATE.md (a peer working in the same checkout) passed
+ *     condition 3, so session-end would have closed the peer's session.
+ *
+ * Ownership is decided on the native id only: STATE.md `session-id` (#1368)
+ * against `readProcessLocalSessionIds()`. The session lock is no proof here —
+ * it records the pid of the short-lived hook process, and in a shared checkout
+ * it may name a peer.
+ *
+ * Unproven ownership (#1718): a STATE.md without `session-id` (written before
+ * #1368, in practice a foreign old file) or a process that cannot name its own
+ * id never runs session-end on status alone. A would-be session-end verdict
+ * becomes `ownership-unproven` with a `confirmToken` bound to the STATE.md path
+ * and its raw bytes; only that token (`--confirm-own`) turns it back, and only while the
+ * file is unchanged. Field incident 2026-10-21: a legacy STATE.md of an older,
+ * already closed plan read `complete-missing-record`.
+ *
+ * Ceiling (BV-004): on platforms without a native id (Cursor, Pi, Codex
+ * without a thread id) that is one operator confirmation per `/close`.
+ * Revisit when those platforms expose a native session id.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { parseStateMd } from '../state-md.mjs';
+import { findRecordedSession } from '../session-close-backfill.mjs';
+import { readLock } from '../session-lock.mjs';
+import { readProcessLocalSessionIds } from '../session-identity/own-session.mjs';
+import { readJsonlFile } from '../io.mjs';
+import { resolveEventsLedgerRoot, resolveStateDir } from '../platform.mjs';
+
+/**
+ * Confirmation token for an `ownership-unproven` STATE.md (#1718): bound to the
+ * STATE.md path and its raw bytes, so a byte-identical file in another checkout
+ * yields a different token.
+ *
+ * @param {string} statePath  path of the STATE.md (resolved to absolute)
+ * @param {Buffer|string} raw  the raw STATE.md bytes
+ * @returns {string}  16 lowercase hex characters
+ */
+export function computeConfirmToken(statePath, raw) {
+  return createHash('sha256').update(path.resolve(statePath)).update('\0').update(raw).digest('hex').slice(0, 16);
+}
+
+/** Verdicts that hand off to session-end; every other verdict stops `/close`. */
+export const RUNS_SESSION_END = new Set(['run-session-end', 'complete-missing-record']);
+
+/**
+ * Classify `<state-dir>/STATE.md` for `/close`.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot  project root (the working tree `/close` runs in)
+ * @param {string} [opts.stateDir]  `.claude` | `.codex` | `.cursor` | `.pi`; default from the platform
+ * @param {object} [opts.env=process.env]  injectable for tests
+ * @param {string} [opts.confirmToken]  token from an earlier `ownership-unproven`
+ *   result; bound to the STATE.md path and its raw bytes, confirms a legacy/unprovable
+ *   STATE.md while that file is unchanged (#1718)
+ * @returns {{
+ *   verdict: 'no-state'|'foreign'|'run-session-end'|'complete-missing-record'|'already-finalized'|'unexpected-status'|'inconclusive'|'ownership-unproven',
+ *   ownership: 'own'|'foreign'|'legacy'|'unprovable'|'confirmed'|null,
+ *   status: string|null, stateSessionId: string|null, ownSessionIds: string[],
+ *   statePath: string, reason?: string,
+ *   wouldRun?: 'run-session-end'|'complete-missing-record', confirmToken?: string,
+ *   session?: string|null, startedAt?: string|null
+ * }}  the last four only with `ownership-unproven`
+ */
+export function classifyCloseState({ repoRoot, stateDir, env = process.env, confirmToken } = {}) {
+  const dir = stateDir ?? resolveStateDir();
+  const statePath = path.join(repoRoot, dir, 'STATE.md');
+  const ownSessionIds = readProcessLocalSessionIds({ env });
+  const base = { ownership: null, status: null, stateSessionId: null, ownSessionIds, statePath };
+
+  if (!existsSync(statePath)) return { ...base, verdict: 'no-state' };
+
+  const raw = readFileSync(statePath);
+  const parsed = parseStateMd(raw.toString('utf8'));
+  if (!parsed) return { ...base, verdict: 'inconclusive', reason: 'STATE.md has no readable frontmatter' };
+  const fm = parsed.frontmatter;
+  const status = typeof fm.status === 'string' ? fm.status : null;
+  const rawId = typeof fm['session-id'] === 'string' ? fm['session-id'].trim() : '';
+  const stateSessionId = rawId || null;
+
+  const ownership = !stateSessionId ? 'legacy'
+    : ownSessionIds.length === 0 ? 'unprovable'
+      : ownSessionIds.includes(stateSessionId) ? 'own' : 'foreign';
+  const known = { ...base, ownership, status, stateSessionId };
+
+  // A foreign STATE.md is never this session's to close, whatever its status:
+  // completed belongs to an earlier tab incarnation or a peer, active/paused to a
+  // peer (or to this tab before a /clear, which this process cannot prove).
+  if (ownership === 'foreign') return { ...known, verdict: 'foreign' };
+
+  // #1718: legacy/unprovable never reaches session-end without a token bound
+  // to this path and the bytes read here; every non-session-end verdict passes unchanged.
+  const gate = (wouldRun) => {
+    if (ownership === 'own') return { ...known, verdict: wouldRun };
+    const token = computeConfirmToken(statePath, raw);
+    if (confirmToken === token) return { ...known, ownership: 'confirmed', verdict: wouldRun };
+    const unproven = {
+      ...known, verdict: 'ownership-unproven', wouldRun, confirmToken: token,
+      session: typeof fm.session === 'string' ? fm.session : null,
+      startedAt: typeof fm.started_at === 'string' ? fm.started_at : null,
+    };
+    if (confirmToken === undefined) return unproven;
+    return { ...unproven, reason: 'confirm token does not match STATE.md (changed since the pre-check, or the token belongs to another file)' };
+  };
+
+  if (status === 'active' || status === 'paused') return gate('run-session-end');
+  if (status !== 'completed') return { ...known, verdict: 'unexpected-status' };
+
+  // #429: completed alone does not prove the Phase 3.7 writer ran.
+  let records;
+  try {
+    records = readJsonlFile(path.join(resolveEventsLedgerRoot(repoRoot), '.orchestrator', 'metrics', 'sessions.jsonl'));
+  } catch (err) {
+    return { ...known, verdict: 'inconclusive', reason: `sessions.jsonl unreadable: ${err.message}` };
+  }
+  // The lock fallback only for STATE.md without session-id (pre-#1368), and
+  // only when the lock names THIS process (#1663). A peer's lock UUID would
+  // become the native key in findRecordedSession, skip this session's own
+  // record (different UUID) before the label match is reached, and send
+  // session-end a second time. Foreign or unprovable lock → no fallback, the
+  // label + started_at join decides.
+  let lockId = null;
+  if (!stateSessionId) {
+    let lockRaw;
+    try { lockRaw = readLock({ repoRoot })?.session_id ?? null; } catch { lockRaw = null; }
+    const trimmed = typeof lockRaw === 'string' ? lockRaw.trim() : '';
+    if (trimmed && ownSessionIds.includes(trimmed)) lockId = trimmed;
+  }
+  const record = findRecordedSession(records, {
+    sessionId: stateSessionId ?? lockId,
+    semanticSessionId: fm.session ?? null,
+    startedAt: fm.started_at ?? null,
+  });
+  // An abandoned backfill stub is no completion; a legacy record without
+  // `status` (written before the field existed) is authoritative.
+  const finalized = record && (record.status === undefined || record.status === 'completed');
+  return finalized ? { ...known, verdict: 'already-finalized' } : gate('complete-missing-record');
+}

package/scripts/lib/session-end/phase-skip.mjs

@@ -61,11 +61,11 @@
  */
 
 import { existsSync } from 'node:fs';
-import path from 'node:path';
 
 import { collectProposals } from '../memory-proposals/collector.mjs';
 import { sweepExpiredLearnings } from '../learnings/expiry-sweep.mjs';
-import { readSkillInvocations } from '../skill-invocations-schema.mjs';
+import { readSkillInvocations, defaultSkillInvocationsPath } from '../skill-invocations-schema.mjs';
+import { resolveLedgerPath } from '../ledger-path.mjs';
 import { runReconcileFromPhaseSkip, resolveEffectiveTargets } from '../reconcile/engine.mjs';
 
 // NOTE (2026-09-09): `shouldDispatchAutoDream` / `shouldDispatchAutoDialectic`
@@ -91,10 +91,11 @@ import { runReconcileFromPhaseSkip, resolveEffectiveTargets } from '../reconcile
  * @returns {{filePath: string, archivePath: string}}
  */
 export function resolveLearningsPaths(repoRoot) {
-  const dir = path.join(repoRoot, '.orchestrator', 'metrics');
+  // #1722: each store resolves on its own — a linked worktree of a repo that
+  // ignores them maps to the main checkout, a versioned one stays local.
   return {
-    filePath: path.join(dir, 'learnings.jsonl'),
-    archivePath: path.join(dir, 'learnings-archive.jsonl'),
+    filePath: resolveLedgerPath('.orchestrator/metrics/learnings.jsonl', repoRoot),
+    archivePath: resolveLedgerPath('.orchestrator/metrics/learnings-archive.jsonl', repoRoot),
   };
 }
 
@@ -232,7 +233,7 @@ async function decideSkillJudge({ repoRoot, cfg, sessionId }) {
       return mkSkip(phase, 'disabled (skill-evolution.judge=false)', 'config-gate');
     }
     if (isPersistenceOff(cfg)) return mkSkip(phase, 'persistence=false', 'config-gate');
-    const invPath = path.join(repoRoot, '.orchestrator', 'metrics', 'skill-invocations.jsonl');
+    const invPath = defaultSkillInvocationsPath(repoRoot);
     const entries = await readSkillInvocations(invPath);
     const noSessionFilter = sessionId === null || sessionId === undefined;
     const judged = new Set(
@@ -272,7 +273,7 @@ async function decideReconcile({ repoRoot, cfg }) {
     if (cfg?.reconcile?.enabled !== true) {
       return mkSkip(phase, 'disabled (reconcile.enabled=false)', 'config-gate');
     }
-    const learningsPath = path.join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
+    const learningsPath = resolveLearningsPaths(repoRoot).filePath;
     if (!existsSync(learningsPath)) {
       return mkSkip(phase, 'learnings.jsonl absent', 'learnings.jsonl');
     }

package/scripts/lib/session-end/tail-runner.mjs

@@ -41,7 +41,8 @@
  *
  * @typedef {Object} SweepResult
  * @property {boolean} ran            - true only when the store was actually rewritten.
- * @property {string}  [reason]       - why it did not run ('plan-skip' | 'no-plan' | 'error').
+ * @property {string}  [reason]       - why it did not run ('plan-skip' | 'no-plan' |
+ *                                      'store-role-inbox' | 'error').
  * @property {string}  [error]        - error message, `reason === 'error'` only.
  * @property {number}  [scanned]      - entries read from the active store (ran only).
  * @property {number}  [archived]     - entries moved to the archive sidecar (ran only).
@@ -50,7 +51,7 @@
  * @property {string}  [archivePath]  - the archive sidecar written to (ran only).
  */
 
-import { sweepExpiredLearnings } from '../learnings/expiry-sweep.mjs';
+import { SKIPPED_STORE_ROLE_INBOX, sweepExpiredLearnings } from '../learnings/expiry-sweep.mjs';
 import { resolveLearningsPaths } from './phase-skip.mjs';
 
 /** Event name — a plain string literal so the events-schema census can see it. */
@@ -151,6 +152,10 @@ export async function runExpiredSweep({ repoRoot, plan, now, graceDays, emit = t
       ...(graceDays === undefined ? {} : { graceDays }),
     });
 
+    // Inbox role (#1516): the sweep wrote nothing, so this is not a run and
+    // emits no sweep_applied — that record's presence claims a rewrite.
+    if (res?.skipped === SKIPPED_STORE_ROLE_INBOX) return { ran: false, reason: SKIPPED_STORE_ROLE_INBOX };
+
     const scanned = res?.scanned ?? 0;
     const archived = res?.archived ?? 0;
     // The sweep result omits `malformed` when the read found none, so absent IS

package/scripts/lib/session-id.mjs

@@ -43,6 +43,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { eventsFilePath } from './events.mjs';
+import { resolveEventsLedgerRoot } from './platform.mjs';
 import { readCanonicalSessions } from './sessions-canonical.mjs';
 import { readTailWindow } from './tail-window.mjs';
 import { withStateMdLock } from './session-lock.mjs';
@@ -144,7 +145,11 @@ function isValidMode(mode) {
  *   only across DIFFERENT ids — never the same id twice, see above).
  */
 async function readSessionIdsFromHistory(repoRoot) {
-  const filePath = path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
+  // #1592: the repo's ONE sessions ledger (main checkout of a linked worktree,
+  // where every close writes since #1584). Aggregation is a monotone max, so the
+  // wider ledger can only raise n — the events source does not always cover a
+  // closed session (rotated ledger, no lock event), the worktree read was empty.
+  const filePath = path.join(resolveEventsLedgerRoot(repoRoot), '.orchestrator', 'metrics', 'sessions.jsonl');
   return readCanonicalSessions({ filePath }).map((rec) => rec.session_id);
 }
 
@@ -266,6 +271,9 @@ async function readSessionIdsFromEvents(repoRoot) {
  * @returns {Promise<string|null>}  The session_id string, or null when absent.
  */
 async function readSessionIdFromStateMd(repoRoot) {
+  // #1636 decision: deliberately the READ resolver, foreign STATE.md included —
+  // this source only collects ids already TAKEN, so a foreign one can only raise
+  // n (max over a union) and ignoring it could re-mint a peer's id.
   const filePath = resolveStateMdPath(repoRoot);
   let raw;
   try {

package/scripts/lib/session-identity/own-session.mjs

@@ -27,6 +27,8 @@
  */
 
 import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import { isLockShape } from '../session-lock-shape.mjs';
 
@@ -228,6 +230,67 @@ export function readProcessLocalSessionIds({ env = process.env, hookInput = null
   return ids;
 }
 
+/**
+ * Read only process parent/name metadata, never command arguments or env.
+ * @param {number} pid
+ * @returns {{ ppid: number, comm: string } | null}
+ */
+function readProcessParent(pid) {
+  const output = execFileSync('ps', ['-p', String(pid), '-o', 'ppid=,comm='], {
+    encoding: 'utf8', timeout: 1000, maxBuffer: 2048,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const match = /^\s*(\d+)\s+(\S+)\s*$/.exec(output);
+  return match ? { ppid: Number(match[1]), comm: match[2] } : null;
+}
+
+/**
+ * Prove an acknowledgement's own invocation using the nearest Claude process.
+ * Unlike the general identity union, inherited env and shared repo files are
+ * never proof here. Stop at the nearest Claude even when its session is unreadable.
+ * Missing, contradictory or unmeasurable evidence returns null; never throws.
+ * Reader injection permits deterministic fixtures when native ps is unavailable.
+ *
+ * @param {{ env?: object, pid?: number, homeDir?: string,
+ *   readProcess?: (pid: number) => { ppid: number, comm: string } | null,
+ *   readSession?: (pid: number) => unknown }} [opts]
+ * @returns {string|null}
+ */
+export function readInvocationSessionId({
+  env = process.env, pid = process.pid, homeDir = homedir(),
+  readProcess = readProcessParent,
+  readSession = (ancestorPid) => JSON.parse(readFileSync(
+    path.join(homeDir, '.claude', 'sessions', `${ancestorPid}.json`), 'utf8',
+  )),
+} = {}) {
+  const seen = new Set();
+  try {
+    for (let depth = 0; depth < 64; depth++) {
+      if (!Number.isSafeInteger(pid) || pid <= 0 || seen.has(pid)) return null;
+      seen.add(pid);
+      const processInfo = readProcess(pid);
+      if (!processInfo || !Number.isSafeInteger(processInfo.ppid) || processInfo.ppid < 0 ||
+          seen.has(processInfo.ppid) || typeof processInfo.comm !== 'string' || !processInfo.comm.trim()) return null;
+      // macOS reports comm as argv[0]; a Claude started by absolute path must still count.
+      if (path.basename(processInfo.comm) === 'claude') {
+        const session = readSession(pid);
+        const sessionId = typeof session?.sessionId === 'string' ? session.sessionId.trim() : '';
+        if (!sessionId) return null;
+        // Every present native ID must agree; platform selection cannot hide
+        // a contradictory inherited ID from a nested harness.
+        for (const key of ['CLAUDE_CODE_SESSION_ID', 'CODEX_THREAD_ID']) {
+          const value = env?.[key];
+          if (value !== undefined && value !== null &&
+              (typeof value !== 'string' || (value.trim() && value.trim() !== sessionId))) return null;
+        }
+        return sessionId;
+      }
+      pid = processInfo.ppid;
+    }
+  } catch { /* Missing process/session evidence must fail closed. */ }
+  return null;
+}
+
 /**
  * Decide whether a wave-scope manifest belongs to THIS session.
  *

package/scripts/lib/session-lock.mjs

@@ -47,6 +47,7 @@ import { isLockShape } from './session-lock-shape.mjs';
 import { isPidAliveOnHost } from './file-lock.mjs';
 import { writeJsonAtomicSync } from './io.mjs';
 import { hostnamesMatch, lockHostCandidate, recordHostAlias, stableHostname } from './host-identity.mjs';
+import { isSafeSessionId } from './fleet-protocol.mjs';
 
 // isPidAliveOnHost moved into file-lock.mjs in #630 (the file-lock primitive
 // owns it so the dependency edge points file-lock → io, never the reverse).
@@ -133,6 +134,13 @@ export const LOCK_LEFTOVER_MIN_AGE_MS = 60 * 60 * 1000;
  */
 export const OWNER_PROOF_RELPATH = '.orchestrator/runtime/lock-owner-proof.json';
 
+/**
+ * Directory of the "released on purpose" markers (#1651), relative to the repo
+ * root — one `<raw session_id>.json` per session that gave its lock back via
+ * `scripts/release-session-lock.mjs`. Gitignored like the owner proof beside it.
+ */
+export const RELEASE_MARKER_RELDIR = '.orchestrator/runtime/lock-released';
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -875,6 +883,10 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
 function withOwnerProof(result, repoRoot) {
   const w = writeOwnerProof({ repoRoot, lock: result.lock });
   result.ownerProof = w.ok ? { ok: true } : { ok: false, reason: w.reason };
+  // #1651: the session holds a lock again, so its earlier "released on
+  // purpose" marker no longer describes it. This is the one junction every
+  // ok:true write of acquire()/forceAcquire() passes. Never throws.
+  clearReleaseMarker({ repoRoot, sessionId: result.lock?.session_id });
   return result;
 }
 
@@ -1253,6 +1265,108 @@ export function loadOwnerProof({ repoRoot } = {}) {
   }
 }
 
+/**
+ * Absolute path of the release marker for `sessionId`, or null when the id is
+ * not a safe single file-name component (#1651). The id comes from a lock file
+ * or a CLI flag, so it is validated before it reaches a path: no separator, no
+ * `.`/`..`, at most 128 chars of `[A-Za-z0-9._-]`.
+ *
+ * @param {string|undefined} repoRoot
+ * @param {unknown} sessionId
+ * @returns {string|null}
+ */
+function releaseMarkerPath(repoRoot, sessionId) {
+  if (!isSafeSessionId(sessionId)) return null;
+  return path.join(repoRoot ?? process.cwd(), RELEASE_MARKER_RELDIR, `${sessionId}.json`);
+}
+
+/**
+ * Record that `sessionId` deliberately released its own lock (#1651), so the
+ * SessionStart bootstrap does not re-create it on a `compact` or `resume` of
+ * that same raw session — a headless run may be using the slot. Atomic
+ * (tmp+rename). Never throws.
+ *
+ * Ceiling (BV-004): markers are never pruned — one small file per released
+ * session id. Revisit if `.orchestrator/runtime/lock-released/` grows past a
+ * few hundred entries.
+ *
+ * `reason` (optional, #1747) records why the lock was given back; the
+ * SessionStart bootstrap writes `'lead-yield'` and honours such a marker only
+ * while a fleet lead's lease is active. Absent = an explicit release.
+ *
+ * @param {{ repoRoot?: string, sessionId: string, reason?: string }} args
+ * @returns {{ ok: true, path: string } | { ok: false, reason: string, error?: string }}
+ */
+export function writeReleaseMarker({ repoRoot, sessionId, reason } = {}) {
+  try {
+    const file = releaseMarkerPath(repoRoot, sessionId);
+    if (file === null) return { ok: false, reason: 'unsafe-session-id' };
+    const w = writeJsonAtomicSync(
+      file,
+      {
+        schema_version: 1,
+        session_id: sessionId,
+        released_at: nowIso(),
+        host: stableHostname(),
+        ...(typeof reason === 'string' ? { reason } : {}),
+      },
+      { tmpPrefix: '.lock-released.tmp' },
+    );
+    if (!w.ok) return { ok: false, reason: 'fs-error', error: w.error };
+    return { ok: true, path: file };
+  } catch (err) {
+    return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * True when a release marker for `sessionId` exists (#1651). Never throws; an
+ * unsafe id or any fs error reads as "no marker", i.e. the pre-#1651 behaviour.
+ *
+ * @param {{ repoRoot?: string, sessionId: string }} args
+ * @returns {boolean}
+ */
+export function hasReleaseMarker({ repoRoot, sessionId } = {}) {
+  try {
+    const file = releaseMarkerPath(repoRoot, sessionId);
+    return file !== null && fs.lstatSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The release marker body for `sessionId`, or null when it is absent, unsafe,
+ * not a regular file or not a JSON object (#1747). Never throws. Existence
+ * alone is {@link hasReleaseMarker}; this reader only adds the `reason`.
+ *
+ * @param {{ repoRoot?: string, sessionId: string }} args
+ * @returns {{ reason?: unknown } & Record<string, unknown> | null}
+ */
+export function readReleaseMarker({ repoRoot, sessionId } = {}) {
+  try {
+    const file = releaseMarkerPath(repoRoot, sessionId);
+    if (file === null || !fs.lstatSync(file).isFile()) return null;
+    const body = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return body !== null && typeof body === 'object' && !Array.isArray(body) ? body : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove the release marker for `sessionId` (#1651). Best-effort, never throws.
+ *
+ * @param {{ repoRoot?: string, sessionId: string }} args
+ * @returns {void}
+ */
+export function clearReleaseMarker({ repoRoot, sessionId } = {}) {
+  try {
+    const file = releaseMarkerPath(repoRoot, sessionId);
+    if (file !== null) fs.rmSync(file, { force: true });
+  } catch { /* best-effort */ }
+}
+
 /**
  * Release the lock IFF it belongs to the given session_id.
  * Silent no-op when the lock belongs to a different session or does not exist.