session-orchestrator 5.11.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-end/vault-orphans.mjs

@@ -0,0 +1,205 @@
+/**
+ * vault-orphans.mjs - Phase 3.7e Vault Orphans (#1563).
+ *
+ * Lists the untracked files in the Meta-Vault that were modified since this
+ * session started, so the closing session can NAME what it may have left
+ * behind there.
+ *
+ * Why this exists (measured 2026-10-11): one vault checkout had accumulated 268
+ * untracked files over five days - website audits, session reports, reviews,
+ * lead handovers - written by sessions of OTHER repos into their configured
+ * `vault-dir`. None of them was ever committed: a session's close commits only
+ * in its own repo, and vault-mirror auto-commits only its own generator-marked
+ * files (`scripts/lib/vault-mirror/auto-commit.mjs`). The writing session is the
+ * only one that knows it wrote them, and nothing made it look.
+ *
+ * THE IRON RULE: this module PROPOSES, it never DISPOSES. Its only git
+ * invocation is the read-only `ls-files --others --exclude-standard -z`. No
+ * add, commit, rm, mv, clean, stash; no file is written, moved or deleted. The
+ * vault is another repo with its own rules (PSA-003).
+ *
+ * The return field is named `candidates`, not `orphans`: mtime is a HINT, not
+ * proof of ownership. A concurrent session of another repo may have written the
+ * same file in the same window. The coordinator names them and records one Open
+ * Question; it never acts on them.
+ *
+ * Three states, never two (a missing measurement must not look like zero):
+ *   - `{ status: 'ok', total: 0 }`   - measured, nothing found
+ *   - `{ status: 'ok', total: N }`   - measured, N candidates
+ *   - `{ status: 'unavailable' }`    - could not measure (no vault dir, not a
+ *                                      git repo, git failed). Never reported as
+ *                                      "no orphans".
+ *
+ * Exclusion - what another writer already owns: any file whose first 4 KB
+ * carries a `_generator: session-orchestrator-` frontmatter line. Census
+ * 2026-10-11 @ 686e2c12 (`rg -n "GENERATOR_MARKER\s*=" scripts/`): four marker
+ * values, all with that prefix - `vault-mirror@1` (40-learnings/, 50-sessions/,
+ * monthly rollups), `vault-status-narrative@1` (01-projects/<slug>/
+ * _session-narrative.md), `active-sessions@1` (01-projects/_active-sessions.md),
+ * `gitlab-portfolio@1`. The match is line-anchored so a hand-written note that
+ * merely QUOTES the marker in prose is still reported.
+ *
+ * There is deliberately NO blanket exclusion of `40-learnings/` / `50-sessions/`:
+ * vault-mirror owns only the MARKED files there. `autoCommitVaultMirror` treats
+ * an unmarked staged file in those dirs as an offender and skips its whole
+ * commit, so an unmarked untracked file there is owned by nobody AND blocks the
+ * mirror - the last thing to hide.
+ *
+ * Never throws. DI seams (#580-DI-001), synchronous like the Phase 4b sibling
+ * ./worktree-orphan-sweep.mjs: `execFileFn` (default `execFileSync`) and
+ * `statFn` (default `lstatSync` - a symlink is reported as itself, never
+ * followed out of the vault). Every git call passes an args ARRAY, no shell
+ * (#577 HARDEN-001).
+ */
+
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { closeSync, lstatSync, openSync, readSync } from 'node:fs';
+
+import { redactHomeDir } from '../common.mjs';
+
+/** Upper bound on the returned `candidates` list; `total` still counts all. */
+export const MAX_CANDIDATES = 200;
+
+/** Bytes read per file for the generator check - same window as auto-commit.mjs. */
+const HEAD_BYTES = 4096;
+
+/** A frontmatter line naming one of this plugin's generators. */
+const GENERATOR_LINE_RE = /^_generator:[ \t]*session-orchestrator-/m;
+
+/**
+ * Env vars that retarget git away from `-C <dir>`. An inherited `GIT_DIR` beats
+ * `-C` (incident 2026-08-19), which here would list ANOTHER repo's untracked
+ * files as vault candidates. Stripped for the one git call below.
+ */
+const REPO_REDIRECT_ENV = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR'];
+
+/**
+ * Ceiling for git's NUL-separated path list: 16 MiB is ~150k paths at ~100
+ * bytes. Past it, execFileSync throws ENOBUFS and the result is `unavailable`
+ * (could not measure), never a silently cut list. Revisit if a vault ever
+ * reports that reason.
+ */
+const LS_FILES_MAX_BUFFER = 16 * 1024 * 1024;
+
+/**
+ * A vault on a hung network filesystem must not stall /close: past this the
+ * call is killed and the result is `unavailable` (git-failed). 20k untracked
+ * files took 0.46 s (2026-10-11), so 20 s is a hang, not a slow vault.
+ */
+const LS_FILES_TIMEOUT_MS = 20_000;
+
+/** @param {string} absPath @returns {boolean} true when the head names one of our generators */
+function isGeneratorOwned(absPath) {
+  let fd;
+  try {
+    fd = openSync(absPath, 'r');
+    const buf = Buffer.alloc(HEAD_BYTES);
+    const n = readSync(fd, buf, 0, HEAD_BYTES, 0);
+    return GENERATOR_LINE_RE.test(buf.subarray(0, n).toString('utf8'));
+  } catch {
+    // Unreadable -> not provably someone else's. This module only REPORTS, so
+    // the safe direction is to show the file, not to hide it.
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* already closed */
+      }
+    }
+  }
+}
+
+/**
+ * @param {string} reason
+ * @param {string} [detail]
+ * @returns {{status: 'unavailable', reason: string, detail?: string, candidates: []}}
+ */
+function unavailable(reason, detail) {
+  return detail ? { status: 'unavailable', reason, detail, candidates: [] } : { status: 'unavailable', reason, candidates: [] };
+}
+
+/**
+ * Find untracked vault files modified at or after `sinceMs`.
+ *
+ * @param {object} [opts]
+ * @param {string} opts.vaultDir - Vault working-tree root (already tilde-expanded).
+ * @param {number} opts.sinceMs - Session start, epoch ms. Files with an older
+ *   mtime are not candidates.
+ * @param {Function} [opts.execFileFn] - execFileSync seam: (file, args, options) => string.
+ * @param {Function} [opts.statFn] - lstatSync seam: (absPath) => { mtimeMs, isFile() }.
+ * @returns {{status: 'ok', candidates: Array<{path: string, mtimeMs: number}>,
+ *   total: number, truncated: boolean, untracked: number}
+ *   | {status: 'unavailable', reason: string, detail?: string, candidates: []}}
+ *   `path` is vault-relative as git reports it. `total` counts every candidate,
+ *   `candidates` holds at most MAX_CANDIDATES of them (sorted by path),
+ *   `untracked` is everything git listed before the mtime and generator filters.
+ */
+export function findVaultOrphans({ vaultDir, sinceMs, execFileFn, statFn } = {}) {
+  try {
+    if (typeof vaultDir !== 'string' || vaultDir.trim() === '') return unavailable('no-vault-dir');
+    if (typeof sinceMs !== 'number' || !Number.isFinite(sinceMs)) return unavailable('invalid-since');
+
+    const exec = typeof execFileFn === 'function' ? execFileFn : execFileSync;
+    const stat = typeof statFn === 'function' ? statFn : lstatSync;
+    const root = path.resolve(vaultDir);
+
+    const env = { ...process.env };
+    for (const key of REPO_REDIRECT_ENV) delete env[key];
+
+    // -- THE ONLY GIT CALL - read-only --------------------------------------
+    let out;
+    try {
+      out = exec('git', ['-C', root, 'ls-files', '--others', '--exclude-standard', '-z'], {
+        encoding: 'utf8',
+        env,
+        maxBuffer: LS_FILES_MAX_BUFFER,
+        timeout: LS_FILES_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      const stderr = typeof err?.stderr === 'string' ? err.stderr : String(err?.stderr ?? '');
+      const reason = /not a git repository/i.test(stderr) ? 'not-a-git-repo' : 'git-failed';
+      const firstLine = redactHomeDir(stderr.split('\n').find((l) => l.trim() !== '') ?? err?.code ?? '');
+      return unavailable(reason, typeof firstLine === 'string' ? firstLine.trim().slice(0, 200) : undefined);
+    }
+    if (typeof out !== 'string') return unavailable('git-failed', 'non-string git output');
+
+    const untrackedPaths = out.split('\0').filter((p) => p !== '');
+
+    // Cost is linear in the untracked count: one lstat per path, plus one 4 KB
+    // read per path that passes the mtime filter (cheapest filter first). Fine
+    // for the measured 268; revisit if a close reports more than ~10k untracked
+    // files, where the per-file read would start to show in /close time.
+    const all = [];
+    for (const rel of untrackedPaths) {
+      const abs = path.join(root, rel);
+      let st;
+      try {
+        st = stat(abs);
+      } catch {
+        // Vanished between listing and stat (a concurrent writer moved it):
+        // nothing left to name.
+        continue;
+      }
+      const mtimeMs = Number(st?.mtimeMs);
+      if (!Number.isFinite(mtimeMs) || mtimeMs < sinceMs) continue;
+      if (typeof st.isFile === 'function' && st.isFile() && isGeneratorOwned(abs)) continue;
+      all.push({ path: rel, mtimeMs });
+    }
+
+    all.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return {
+      status: 'ok',
+      candidates: all.slice(0, MAX_CANDIDATES),
+      total: all.length,
+      truncated: all.length > MAX_CANDIDATES,
+      untracked: untrackedPaths.length,
+    };
+  } catch (err) {
+    // Defensive catch-all - this probe must never throw into /close.
+    return unavailable('internal-error', String(err?.message ?? err).slice(0, 200));
+  }
+}

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-invocation.mjs

@@ -3,15 +3,26 @@
  * This is a text boundary, not a shell/option parser: quotes and command syntax
  * in the context remain data. `unknown` is a ledger value, never a live mode.
  *
+ * A bare `/session` defaults to `deep`. In a repo without any session history
+ * of its own that default is not silent: the result carries
+ * `defaultReason: 'no-session-history'`, and the caller asks for task and mode
+ * first (#1561). `hasHistory` left undefined means "not measured" and keeps
+ * the plain default.
+ *
  * @param {string} [argumentsText] Complete text following /session.
- * @returns {{sessionType: string, context: string, profile?: string, invalidMode?: string}}
+ * @param {{hasHistory?: boolean}} [options]
+ * @returns {{sessionType: string, context: string, profile?: string, invalidMode?: string, defaultReason?: string}}
  */
-export function resolveSessionInvocation(argumentsText = '') {
+export function resolveSessionInvocation(argumentsText = '', { hasHistory } = {}) {
   if (typeof argumentsText !== 'string') {
     throw new TypeError('session invocation arguments must be a string');
   }
   const [_, mode, context = ''] = argumentsText.trimStart().match(/^(\S+)(?:\s+([\s\S]*))?$/u) ?? [];
-  if (mode === undefined) return { sessionType: 'deep', context: '' };
+  if (mode === undefined) {
+    return hasHistory === false
+      ? { sessionType: 'deep', context: '', defaultReason: 'no-session-history' }
+      : { sessionType: 'deep', context: '' };
+  }
   if (mode === 'ultradeep') return { sessionType: 'deep', profile: 'ultradeep', context };
   if (['housekeeping', 'feature', 'deep'].includes(mode)) {
     return { sessionType: mode, context };