session-orchestrator 3.24.0 → 4.0.0

package/scripts/lib/session-close-backfill.mjs

@@ -67,12 +67,31 @@ import { parseStateMd as defaultParseStateMd } from './state-md/yaml-parser.mjs'
 // Constants
 // ---------------------------------------------------------------------------
 
-/** session_type enum accepted by the schema — lock.mode is coerced against it. */
-const VALID_SESSION_TYPES = new Set(['feature', 'deep', 'housekeeping']);
+/**
+ * The three real session MODES — deliberately NOT the schema's VALID_SESSION_TYPES,
+ * which since GitLab #1234 also carries `unknown`. This set answers a narrower
+ * question: "is `gathered.mode` a MEASUREMENT?". `unknown` must never pass it, or
+ * an events record carrying `mode: 'unknown'` would be recorded as a measured type
+ * (`_session_type_inferred` absent) when it is the opposite.
+ */
+const MEASURED_SESSION_MODES = new Set(['feature', 'deep', 'housekeeping']);
+
+/**
+ * session_type written when nothing in events.jsonl measured the mode
+ * (GitLab #1234). Always paired with `_session_type_inferred` + `_synthetic`.
+ */
+const UNMEASURED_SESSION_TYPE = 'unknown';
 
 const EVENT_STARTED = 'orchestrator.session.started';
 const EVENT_LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
+// Both names for one generation (GitLab #1234): `hooks/on-stop.mjs` now emits
+// `orchestrator.turn.stopped` as the canonical name and keeps the legacy
+// `orchestrator.session.stopped` (with `deprecated: true`) beside it until
+// 2027-03-06. A terminal-event probe must accept EITHER, or every session that
+// closes after the legacy name is dropped silently loses its attested end and
+// falls back to the flagged `lastEventMs` estimate.
 const EVENT_STOPPED = 'orchestrator.session.stopped';
+const EVENT_TURN_STOPPED = 'orchestrator.turn.stopped';
 const EVENT_ENDED = 'orchestrator.session.ended';
 
 const EVENTS_REL = ['.orchestrator', 'metrics', 'events.jsonl'];
@@ -108,14 +127,24 @@ function markerName(id) {
 }
 
 /**
- * Read a JSONL file into an array of parsed objects. Missing file → []; each
- * malformed line is skipped rather than aborting the whole read. Never throws.
+ * Read a JSONL file into an array of parsed objects. Missing file (ENOENT) →
+ * [] silently; an unreadable one (EACCES/EISDIR/…) → [] with a stderr WARN
+ * (#1210 — ENOENT and other read failures are different facts, same split as
+ * `sessions-canonical.mjs` `readCanonicalSessions`). Each malformed line is
+ * skipped rather than aborting the whole read. Never throws.
  */
 function readJsonlSafe(readFileSync, filePath) {
   let raw;
   try {
     raw = readFileSync(filePath, 'utf8');
-  } catch {
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') {
+      process.stderr.write(
+        `⚠ readJsonlSafe: cannot read ${filePath} ` +
+          `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — ` +
+          'treating as EMPTY, counts below are floors\n',
+      );
+    }
     return [];
   }
   const out = [];
@@ -207,7 +236,7 @@ function collectSessionEvents(events, { sessionId, semanticSessionId }) {
       if (typeof ev.timestamp === 'string') startedAt = ev.timestamp;
       if (typeof ev.branch === 'string' && ev.branch.length > 0) branch = ev.branch;
       if (typeof ev.project === 'string') project = ev.project;
-    } else if (ev.event === EVENT_STOPPED || ev.event === EVENT_ENDED) {
+    } else if (ev.event === EVENT_STOPPED || ev.event === EVENT_TURN_STOPPED || ev.event === EVENT_ENDED) {
       if (!Number.isNaN(ts)) {
         lastTerminalMs = lastTerminalMs === null ? ts : Math.max(lastTerminalMs, ts);
       }
@@ -307,9 +336,9 @@ function synthesizeRecord({ recordId, synthetic, gathered, nowMs, status = 'aban
   // Guard the same monotonic invariant as before: never earlier than started_at.
   const completedIso = new Date(Math.max(startedMs, completedMs)).toISOString();
 
-  let sessionType = 'housekeeping';
+  let sessionType = UNMEASURED_SESSION_TYPE;
   let inferred = true;
-  if (gathered.mode && VALID_SESSION_TYPES.has(gathered.mode)) {
+  if (gathered.mode && MEASURED_SESSION_MODES.has(gathered.mode)) {
     sessionType = gathered.mode;
     inferred = false;
   }
@@ -346,7 +375,36 @@ function synthesizeRecord({ recordId, synthetic, gathered, nowMs, status = 'aban
     _backfill_incomplete_fields: incomplete,
   };
   if (branchFound) record.branch = gathered.branch;
-  if (inferred) record._session_type_inferred = true;
+  if (inferred) {
+    record._session_type_inferred = true;
+    // GitLab #1234 — BACKFILLER HONESTY, half landed 2026-09-06.
+    //
+    // `session_type` above is now `'unknown'`, not the old `'housekeeping'`
+    // DEFAULT that nothing in events.jsonl ever said. Measured 2026-09-06, all
+    // 1.656 `abandoned` records in the 90-day fleet window carry
+    // `_session_type_inferred: true` + `total_waves: 0`, and NO organically
+    // written `abandoned` record exists anywhere — that `housekeeping` guess is
+    // what produced the "27 % close rate" figure that turned out to be an
+    // artefact (the real rate is 21,3 %). VALID_SESSION_TYPES was widened with
+    // `unknown` in `scripts/lib/session-schema/constants.mjs` to make this
+    // sayable; historical records keep their `housekeeping` label verbatim
+    // (sessions.jsonl is append-only), so a reader wanting the honest
+    // population still filters on `_synthetic !== true` rather than on the type.
+    //
+    // The OTHER half is deliberately NOT landed: `status` stays `'abandoned'`
+    // even though `'unresolved'` is the honest word and the schema now accepts
+    // it. Six executable phantom-stub filters key on the literal `abandoned`
+    // (census + revisit trigger in `scripts/lib/session-schema/validator.mjs`
+    // § SESSION_STATUS) and none of them is in this change's file scope —
+    // flipping the emitter first would make every new stub invisible to all six
+    // and re-open the #834 phantom-in-signal class fleet-wide. Repoint those
+    // filters onto one both-accepting predicate, then flip this one line.
+    //
+    // `_synthetic: true` still carries the claim no enum can: this record was
+    // COMPOSED. A consumer that filters on `_synthetic !== true` gets only
+    // measured records without needing to know either enum.
+    record._synthetic = true;
+  }
   if (synthetic) record._synthetic_session_id = true;
   if (completedEstimated) record._completed_at_estimated = true;
   // #1068 AC3/AC4 — forensic supersede marker. sessions.jsonl is append-only,

package/scripts/lib/session-id.mjs

@@ -42,6 +42,7 @@
 import { open, readFile } from 'node:fs/promises';
 import path from 'node:path';
 
+import { readCanonicalSessions } from './sessions-canonical.mjs';
 import { withStateMdLock } from './session-lock.mjs';
 import { resolveStateMdPath } from './state-md/frontmatter-mutators.mjs';
 import { parseStateMd } from './state-md/yaml-parser.mjs';
@@ -127,34 +128,22 @@ function isValidMode(mode) {
  *  - Malformed JSONL line → silently skipped (per-line try/catch).
  *  - Lines without a string `session_id` field → filtered out.
  *
- * Performance note: sessions.jsonl is line-oriented but typically <100 KB.
- * A single readFile is faster than line-streaming at this size. Should the
- * file grow past ~5 MB a future change can swap to a `readline` stream with
- * early-exit; not a launch blocker.
+ * #1209: migrated to `readCanonicalSessions` (dedup per `session_id`, drop
+ * id-less lines — same three rules `sessions-canonical.mjs` documents).
+ * Number-neutral for THIS reader: the only consumer of its output
+ * (`resolveSemanticSessionId`) folds `candidateIds` through `Math.max` over
+ * the parsed `n` — "Duplicates are fine — Math.max handles them" (see that
+ * function's body) — so collapsing a duplicate `session_id` line to one
+ * record changes nothing observable here. Migrated anyway for one collapse
+ * implementation across all `sessions.jsonl` raw-line-scan readers (#1209).
  *
  * @param {string} repoRoot
- * @returns {Promise<string[]>}  Array of session_id strings (may include duplicates).
+ * @returns {Promise<string[]>}  Array of session_id strings (may include duplicates
+ *   only across DIFFERENT ids — never the same id twice, see above).
  */
 async function readSessionIdsFromHistory(repoRoot) {
   const filePath = path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
-  let raw;
-  try {
-    raw = await readFile(filePath, 'utf8');
-  } catch {
-    return [];
-  }
-  const ids = [];
-  for (const line of raw.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (trimmed === '') continue;
-    try {
-      const parsed = JSON.parse(trimmed);
-      if (typeof parsed?.session_id === 'string') ids.push(parsed.session_id);
-    } catch {
-      // Malformed line — skip silently (audit §3.1 robustness contract).
-    }
-  }
-  return ids;
+  return readCanonicalSessions({ filePath }).map((rec) => rec.session_id);
 }
 
 /**

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

@@ -26,7 +26,49 @@
  * session id.
  */
 
-import { readLock } from '../session-lock.mjs';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { isLockShape } from '../session-lock-shape.mjs';
+
+/**
+ * Read the two session ids out of `<repoRoot>/.orchestrator/session.lock`.
+ *
+ * A deliberate, behaviour-identical stand-in for `readLock()` from
+ * `../session-lock.mjs` (#1153 P7): that import drags a static closure of six
+ * modules (session-lock → exclusivity-matrix, file-lock, io, host-identity,
+ * crypto-digest-utils — measured 2026-09-04 by following its `^import` lines)
+ * into every consumer of this module, of which the live
+ * `hooks/enforce-scope.mjs` runs on EVERY Edit/Write. Two strings do not need
+ * a lock manager.
+ *
+ * Tolerance is matched to `readLock()` exactly, which collapses every non-ok
+ * outcome of `readLockDetailed()` to `null`: missing file, unreadable file,
+ * invalid JSON, and **valid JSON that fails the lock schema** all yield `{}`
+ * here. The schema check is not reproduced but IMPORTED — `isLockShape()` from
+ * `../session-lock-shape.mjs` is the same predicate `parseLock()` applies, and
+ * that module imports nothing, so sharing it costs the hook chain no closure.
+ * A copy would have been free to drift the fail-OPEN way: a relaxed
+ * `parseLock` plus an unchanged copy here drops the lock tier's ids, the own
+ * manifest reads `foreign`, and enforcement switches itself off silently.
+ *
+ * Never throws.
+ *
+ * @param {string} repoRoot
+ * @returns {{ session_id?: string, semantic_session_id?: string }}
+ */
+function readLockIds(repoRoot) {
+  try {
+    const raw = readFileSync(
+      path.join(repoRoot ?? process.cwd(), '.orchestrator', 'session.lock'),
+      'utf8',
+    );
+    const obj = JSON.parse(raw);
+    if (!isLockShape(obj)) return {};
+    return { session_id: obj.session_id, semantic_session_id: obj.semantic_session_id };
+  } catch {
+    return {};
+  }
+}
 
 /**
  * The set of session ids that provably name THIS session — the UNION of every
@@ -112,10 +154,10 @@ export function readOwnSessionIds(repoRoot, { hookInput = null } = {}) {
 
   // Source 3 — repo-global lock file (the manifest writer's own identity).
   try {
-    const lock = readLock({ repoRoot });
+    const lock = readLockIds(repoRoot);
     for (const key of ['session_id', 'semantic_session_id']) add(lock?.[key]);
   } catch {
-    /* readLock never throws by contract, but that contract is not ours to trust */
+    /* readLockIds never throws by contract, but that contract is not ours to trust */
   }
   return ids;
 }
@@ -190,9 +232,11 @@ export function readProcessLocalSessionIds({ env = process.env, hookInput = null
  *   - `'own'` — an id matched.
  *
  * Both id fields are consulted because they address the same session under two
- * naming schemes: `session` is the raw harness session id (a UUID on Claude
- * Code), `semantic_session` the `<branch>-<date>-<mode>-<n>` form. A harness
+ * naming schemes: `session_id` is the raw harness session id (a UUID on Claude
+ * Code), `semantic_session_id` the `<branch>-<date>-<mode>-<n>` form. A harness
  * that resolves only the semantic one must still recognise its own manifest.
+ * The pre-#1153 spellings `session` / `semantic_session` are still READ (see
+ * {@link MANIFEST_SESSION_KEYS}).
  *
  * @param {unknown} scope — parsed wave-scope manifest (any shape; a non-object
  *   simply yields no ids, hence `'unknown'`).
@@ -204,14 +248,85 @@ export function readProcessLocalSessionIds({ env = process.env, hookInput = null
  *   latter returns a `string[]`: a bare array is NOT a Set and folds to the
  *   empty set below, yielding `'unknown'` for every manifest.
  * @returns {{ verdict: 'own'|'foreign'|'unknown', manifestIds: string[] }}
+ * @see MANIFEST_SESSION_KEYS / {@link manifestSessionBinding} — defined
+ *   immediately below rather than above this doc comment, because the three
+ *   live hooks import this module on EVERY tool call: a use-before-define here
+ *   throws inside the hook chain and locks every session sharing the checkout
+ *   out of Edit/Write/Bash (measured 2026-09-04, ~8 minutes, #1153 P2).
  */
+/**
+ * The session-binding key names of a `wave-scope.json` manifest — the ONE place
+ * these literals live (#1153 P2). Every reader imports them from here instead
+ * of repeating the strings: `scripts/materialize-wave-scope.mjs`,
+ * `scripts/validate-wave-scope.mjs`, `scripts/memory-propose.mjs`, and — via
+ * {@link classifyManifestSession} — `scripts/lib/events.mjs` plus the three
+ * live hooks.
+ *
+ * `current` are the canonical names, chosen to match the two neighbouring
+ * session artefacts a reader already knows: `.orchestrator/session.lock` and
+ * `current-session.json` both spell them `session_id` / `semantic_session_id`,
+ * and `scripts/lib/quality-gate.mjs` reads that exact pair. One session
+ * identity should not carry two spellings depending on which file names it.
+ *
+ * `legacy` are the pre-#1153 spellings, and they are **accepted on the READ
+ * side only, until the next minor release**. `wave-scope.json` is git-ignored
+ * and session-ephemeral, so the one surviving reason to read them is a package
+ * upgraded mid-wave with an old-format manifest already on disk. The writer
+ * (`scripts/wave-scope-binding.mjs`) emits `current` exclusively.
+ *
+ * @type {Readonly<{ current: readonly string[], legacy: readonly string[] }>}
+ */
+export const MANIFEST_SESSION_KEYS = Object.freeze({
+  current: Object.freeze(['session_id', 'semantic_session_id']),
+  legacy: Object.freeze(['session', 'semantic_session']),
+});
+
+/**
+ * Resolve the binding out of a manifest under BOTH key spellings. A non-object
+ * — including an ARRAY, which `typeof` calls `'object'` — yields no ids.
+ *
+ * **A CONFLICT yields no value for that slot, and that is fail-CLOSED.**
+ * When both spellings of one slot are present with different non-empty values,
+ * the manifest is self-contradictory (`scripts/validate-wave-scope.mjs` calls
+ * exactly this an ERROR — but no hook runs the validator, so the classifier is
+ * the only thing standing between the manifest and the guard). Preferring the
+ * current spelling let a peer DISARM this session's guard by appending
+ * `"session_id": "attacker"` beside a legitimate legacy `"session": "<me>"`:
+ * the slot then resolved to an id this session does not carry,
+ * {@link classifyManifestSession} returned `'foreign'`, and
+ * `hooks/enforce-scope.mjs` skips enforcement on `'foreign'`. Dropping the slot
+ * instead collapses the verdict to `'unknown'`, which every caller treats as
+ * "keep enforcing".
+ *
+ * Both present and EQUAL (after trim) → that value. Only one present → that
+ * value. Both present and different → the slot is omitted.
+ *
+ * @param {unknown} scope
+ * @returns {{ session_id?: string, semantic_session_id?: string }}
+ */
+export function manifestSessionBinding(scope) {
+  const out = {};
+  if (!scope || typeof scope !== 'object' || Array.isArray(scope)) return out;
+  MANIFEST_SESSION_KEYS.current.forEach((key, i) => {
+    const legacyKey = MANIFEST_SESSION_KEYS.legacy[i];
+    const pick = (v) => (typeof v === 'string' && v.trim() ? v.trim() : '');
+    const current = pick(scope[key]);
+    const legacy = pick(scope[legacyKey]);
+    if (current && legacy && current !== legacy) return; // conflict → no value
+    const value = current || legacy;
+    if (value) out[key] = value;
+  });
+  return out;
+}
+
+/** @see the contract note above `MANIFEST_SESSION_KEYS` — the full docblock for
+ * this function sits there, separated from it only because the constants must
+ * be defined before use (#1153 P2). */
 export function classifyManifestSession(scope, ownIds) {
   const manifestIds = [];
-  if (scope && typeof scope === 'object' && !Array.isArray(scope)) {
-    for (const key of ['session', 'semantic_session']) {
-      const value = typeof scope[key] === 'string' ? scope[key].trim() : '';
-      if (value) manifestIds.push(value);
-    }
+  const binding = manifestSessionBinding(scope);
+  for (const key of MANIFEST_SESSION_KEYS.current) {
+    if (binding[key]) manifestIds.push(binding[key]);
   }
   const own = ownIds instanceof Set ? ownIds : new Set();
   if (manifestIds.length === 0 || own.size === 0) return { verdict: 'unknown', manifestIds };

package/scripts/lib/session-lock-shape.mjs

@@ -0,0 +1,43 @@
+/**
+ * session-lock-shape.mjs — the ONE predicate that decides whether a parsed
+ * JSON value is a `.orchestrator/session.lock` record (#1153 P7).
+ *
+ * **Zero imports on purpose.** One of the two consumers is
+ * `scripts/lib/session-identity/own-session.mjs`, which the live
+ * `hooks/enforce-scope.mjs` loads on EVERY Edit/Write; anything this module
+ * imported would join that hook's static closure. It therefore holds six
+ * `typeof` checks and nothing else.
+ *
+ * **The two consumers, and why they must not drift apart:**
+ *
+ *   - `scripts/lib/session-lock.mjs` `parseLock()` — the lock manager's own
+ *     reader; a value that fails this predicate is `null` there.
+ *   - `scripts/lib/session-identity/own-session.mjs` `readLockIds()` — the
+ *     dependency-free stand-in that reads the same two ids out of the same
+ *     file without dragging the lock manager into a hook.
+ *
+ * The drift direction is FAIL-OPEN, which is why the predicate is shared
+ * rather than repeated: if `parseLock` relaxed the shape and `readLockIds` did
+ * not, the lock tier of {@link readOwnSessionIds} would stop contributing its
+ * ids, this session's own manifest would classify `foreign`, and
+ * `hooks/enforce-scope.mjs` would silently skip enforcement for the whole wave.
+ *
+ * @param {unknown} obj — a value already parsed from JSON.
+ * @returns {boolean} true when `obj` carries all six required lock fields with
+ *   the right primitive types. `semantic_session_id` and `last_heartbeat` are
+ *   deliberately NOT required — both are optional by schema (v1 locks predate
+ *   `last_heartbeat`, and `semantic_session_id` is absent on harnesses that
+ *   resolve no semantic id).
+ */
+export function isLockShape(obj) {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    typeof obj.session_id === 'string' &&
+    typeof obj.started_at === 'string' &&
+    typeof obj.mode === 'string' &&
+    typeof obj.pid === 'number' &&
+    typeof obj.host === 'string' &&
+    typeof obj.ttl_hours === 'number'
+  );
+}

package/scripts/lib/session-lock.mjs

@@ -43,6 +43,7 @@ import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { classifyMode } from './exclusivity-matrix.mjs';
+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';
@@ -199,16 +200,10 @@ function heartbeatAgeMinutes(lock) {
 function parseLock(raw) {
   try {
     const obj = JSON.parse(raw);
-    if (
-      typeof obj === 'object' &&
-      obj !== null &&
-      typeof obj.session_id === 'string' &&
-      typeof obj.started_at === 'string' &&
-      typeof obj.mode === 'string' &&
-      typeof obj.pid === 'number' &&
-      typeof obj.host === 'string' &&
-      typeof obj.ttl_hours === 'number'
-    ) {
+    // The six-field predicate lives in ONE place (#1153 P7) — see
+    // `./session-lock-shape.mjs` for the other consumer and the fail-open
+    // drift this sharing prevents.
+    if (isLockShape(obj)) {
       // Schema v1 → v2 normalisation: when `last_heartbeat` is absent or
       // non-string, treat the lock as if it heartbeat-ed once at started_at.
       const normalised = { ...obj };

package/scripts/lib/session-registry.mjs

@@ -5,11 +5,13 @@
  * peer-detection (F2, #168) and hooks/on-stop.mjs clean deregister + zombie
  * sweep (F3, #169).
  *
- * Registry location: `~/.config/session-orchestrator/sessions/active/<sessionId>.json`
- * Sweep log: `~/.config/session-orchestrator/sessions/sweep.log` (JSONL)
+ * Registry location: `<private-config-dir>/sessions/active/<sessionId>.json`
+ * Sweep log: `<private-config-dir>/sessions/sweep.log` (JSONL)
  *
- * Overridable via env var `SO_SESSION_REGISTRY_DIR` (points to the parent
- * `sessions/` directory, not `active/`) — used by tests for isolation.
+ * `<private-config-dir>` is `resolvePrivateConfigDir()` — `SO_CONFIG_HOME` >
+ * `XDG_CONFIG_HOME` > `~/.config/session-orchestrator`. `SO_SESSION_REGISTRY_DIR`
+ * overrides the whole `sessions/` directory (not `active/`) and outranks all
+ * three — used by tests for isolation.
  *
  * Heartbeat schema (per issue #167):
  *   {
@@ -27,7 +29,6 @@
  * deliberately, see `skills/_shared/state-ownership.md` § Schema v1 Sunset.
  */
 
-import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { promises as fs } from 'node:fs';
@@ -36,16 +37,31 @@ import { digestSha256 } from './crypto-digest-utils.mjs';
 import { appendFileSync, mkdirSync } from 'node:fs';
 
 import { utcTimestamp, appendJsonl } from './common.mjs';
+import { resolvePrivateConfigDir } from './config/private-config-dir.mjs';
 
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
 
-/** Parent directory for all session-registry state. */
+/**
+ * Parent directory for all session-registry state.
+ *
+ * Precedence: `SO_SESSION_REGISTRY_DIR` (names the `sessions/` dir ITSELF —
+ * highest, and what every existing test uses for isolation) > the host-private
+ * config dir resolved by `resolvePrivateConfigDir()` (`SO_CONFIG_HOME` >
+ * `XDG_CONFIG_HOME` > `~/.config/session-orchestrator`).
+ *
+ * Hardcoding `~/.config` here was the #1223 hazard class in its registry form:
+ * a sandboxed probe run that set `SO_CONFIG_HOME=<tmp>` moved every OTHER
+ * host-private artefact but not this one, so the throwaway session registered
+ * itself in the operator's REAL registry and was then discovered as a live peer.
+ * `.trim()` guards the whitespace-only env value (`development.md` § Error
+ * Handling) — `'   '` is truthy and would otherwise be returned verbatim.
+ */
 export function registryBaseDir() {
-  const override = process.env.SO_SESSION_REGISTRY_DIR;
-  if (override && override.length > 0) return override;
-  return path.join(os.homedir(), '.config', 'session-orchestrator', 'sessions');
+  const override = (process.env.SO_SESSION_REGISTRY_DIR || '').trim();
+  if (override) return override;
+  return path.join(resolvePrivateConfigDir(), 'sessions');
 }
 
 /** Directory holding one JSON file per active session. */

package/scripts/lib/session-schema/constants.mjs

@@ -56,8 +56,31 @@ export const SESSION_KEY_ALIASES = Object.freeze({
 // Enums / required field lists
 // ---------------------------------------------------------------------------
 
-/** Closed set of valid session_type values. */
-export const VALID_SESSION_TYPES = Object.freeze(['feature', 'deep', 'housekeeping']);
+/**
+ * Closed set of valid session_type values.
+ *
+ * `unknown` (GitLab #1234, added 2026-09-06) is NOT a fourth session MODE — it is
+ * the absence of a measurement, and it exists so a reconstructed record can say
+ * so instead of guessing. Measured 2026-09-06 over the 90-day fleet corpus: all
+ * 1.656 `abandoned` records carry `_session_type_inferred: true` + `total_waves: 0`
+ * and NO organically written `abandoned` record exists anywhere — i.e. every one
+ * of them was labelled `housekeeping` by `scripts/lib/session-close-backfill.mjs`
+ * because the enum left it no alternative, and that guess is what produced the
+ * fleet-wide "27 % close rate" figure (the real rate is 21,3 %).
+ *
+ * Only `synthesizeRecord()` in `scripts/lib/session-close-backfill.mjs` writes it,
+ * and only for records it also flags `_session_type_inferred` + `_synthetic`.
+ * A live session never becomes `unknown`: `/session` still resolves one of the
+ * three modes, and `scripts/lib/wave-sizing.mjs` (which THROWS on a fourth value)
+ * is only ever fed the live type, never a ledger record.
+ *
+ * Known mis-bucket, out of this change's scope: `normalizeSessionType()` in
+ * `scripts/lib/telemetry/schema.mjs:382` maps any non-empty unlisted value to
+ * `'other'` ("something WAS measured and is not one of the three modes"), which
+ * is the opposite of what `unknown` means — even though that module already
+ * defines `SESSION_TYPE_UNKNOWN = 'unknown'` for its absent-branch.
+ */
+export const VALID_SESSION_TYPES = Object.freeze(['feature', 'deep', 'housekeeping', 'unknown']);
 
 /**
  * Required fields for a schema_version=1 record. Validated by validateSession
@@ -131,4 +154,15 @@ export const OPTIONAL_FIELDS = Object.freeze([
   // into a note a human reads" ⊃ "schema-valid". A record missing it is a clean
   // vault-mirror skip, NOT a malformed record.
   'effectiveness',
+  // PRD docs/prd/2026-09-06-ultradeep-session-profile.md — `session_profile`
+  // names a WAVE-SHAPE variant on top of an unchanged `session_type`. It is
+  // additive and optional on purpose: `ultradeep` is deliberately NOT a member
+  // of VALID_SESSION_TYPES above, because that set is mirrored in
+  // scripts/lib/telemetry/schema.mjs (an unlisted type -> 'other') and in
+  // scripts/lib/wave-sizing.mjs (an unlisted type -> TypeError), where a new
+  // MODE would be MISLABELLED rather than rejected. That reasoning is unchanged
+  // by the `unknown` member added above: `unknown` is the absence of a
+  // measurement, not a mode, and nothing dispatches on it. Every historical
+  // record lacking the field validates unchanged.
+  'session_profile',
 ]);

package/scripts/lib/session-schema/validator.mjs

@@ -28,11 +28,33 @@ const EXPECTED_COST_TIERS = Object.freeze(['quick', 'standard', 'deep']);
 
 /**
  * Valid values for the optional `status` field (Epic #724 C1).
- * `completed` — record written by a normal /close flow.
- * `abandoned` — stub backfilled by the SessionEnd hook because the session
- *               terminated without running /close.
+ * `completed`  — record written by a normal /close flow.
+ * `abandoned`  — stub backfilled by the SessionEnd hook because the session
+ *                terminated without running /close.
+ * `unresolved` — the HONEST label for that same stub: "never reached /close" is
+ *                observed, but "abandoned" is an interpretation of it (a session
+ *                may have finished its work and merely skipped /close, or been
+ *                killed). GitLab #1234, added 2026-09-06.
+ *
+ * CEILING (BV-004) — `unresolved` currently has NO writer, and the emitter must
+ * not adopt it yet. Six EXECUTABLE phantom-stub filters key on the literal
+ * `abandoned` and none is inside this change's file scope, so flipping the
+ * emitter today would make every new stub invisible to all of them and re-open
+ * the #834 phantom-in-signal class fleet-wide. Census measured 2026-09-06 via
+ * `rg -n "status\s*(!==|===|!=|==)\s*[\"']abandoned[\"']" scripts hooks --glob '!*.test.mjs'`:
+ *   scripts/lib/session-schema/filters.mjs:56  (isRealSession — the shared helper,
+ *       imported by sessions-staleness-banner, auto-dream, dialectic-deriver,
+ *       harness-audit/categories/category4, evolve/autopilot-effectiveness)
+ *   scripts/lib/sessions-canonical.mjs:149,172
+ *   scripts/lib/eval/session-resolve.mjs:79
+ *   scripts/mcp-server.sh:195
+ *   scripts/compute-grounding-injection.sh:74
+ * REVISIT TRIGGER: once those six route through one predicate that accepts both
+ * `abandoned` and `unresolved`, switch `synthesizeRecord()` in
+ * `scripts/lib/session-close-backfill.mjs` to emit `unresolved` for inferred
+ * records — a one-line change, which is exactly why this value lands now.
  */
-const SESSION_STATUS = Object.freeze(['completed', 'abandoned']);
+const SESSION_STATUS = Object.freeze(['completed', 'abandoned', 'unresolved']);
 
 /**
  * Canonical ISO-8601 UTC timestamp regex — accepts `YYYY-MM-DDTHH:MM:SSZ`
@@ -462,6 +484,18 @@ function _validateOptionalFields(entry) {
     }
   }
 
+  // `session_profile` — optional wave-shape profile (PRD
+  // docs/prd/2026-09-06-ultradeep-session-profile.md). Non-empty string or
+  // null/absent; absent means "no profile" and is NOT coerced to a string.
+  // Deliberately NOT validated against a closed set: unlike `session_type`,
+  // no consumer branches on the value, so an unrecognised profile is a
+  // readable record with an unknown shape rather than a silent mislabel.
+  if (entry.session_profile !== undefined && entry.session_profile !== null) {
+    if (typeof entry.session_profile !== 'string' || entry.session_profile.length === 0) {
+      throw new ValidationError('session_profile must be a non-empty string or null');
+    }
+  }
+
   // `_express_path_detail` — forensic sidecar written by `normalizeSession`
   // when it collapses a legacy object `express_path` onto its boolean. Holds
   // the pre-collapse object verbatim so the conversion stays reversible.

package/scripts/lib/session-start-probes.mjs

@@ -176,8 +176,16 @@ export const PROBES = [
     args: ({ repoRoot }) => ({ repoRoot }),
     // Bespoke shape: `{status, ok, details, …}` with no `message` field. The
     // banner text is prescribed by SKILL.md § Phase 4.
+    //
+    // The degraded branch is NOT decoration (#1031): this entry overrides BOTH
+    // `render` and `severityOf`, so the module-level defaults that already
+    // handle a `{severity:'warn', message, degraded}` result never run for this
+    // probe. Without these two lines a degraded ci-status result scored `'ok'`
+    // and rendered nothing — "could not read" displayed exactly like "green",
+    // which is the confusion the probe's own migration removed one layer down.
     render: (r) => {
       if (!r || typeof r !== 'object') return null;
+      if (r.degraded) return typeof r.message === 'string' && r.message ? r.message : null;
       if (r.status === 'red') {
         const pid = r.details?.currentPipelineId ?? '?';
         const green = r.lastGreen
@@ -193,7 +201,16 @@ export const PROBES = [
       return null;
     },
     // `status: 'red'` is an alert even though the probe publishes no severity.
-    severityOf: (r) => (r?.status === 'red' ? 'alert' : r?.status === 'green' && r?.allowFailureJobs ? 'warn' : 'ok'),
+    // A degraded result is a finding, never clean — same rule as the generic
+    // path in `severityOf()` below.
+    severityOf: (r) =>
+      r?.degraded
+        ? 'warn'
+        : r?.status === 'red'
+          ? 'alert'
+          : r?.status === 'green' && r?.allowFailureJobs
+            ? 'warn'
+            : 'ok',
   },
   {
     id: 'qg-command-drift',