session-orchestrator 3.23.0 → 4.0.0

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,11 +154,66 @@ 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;
+}
+
+/**
+ * The ids that name this session and are PROCESS-LOCAL — tiers 1 and 2 only,
+ * never the lock and never STATE.md.
+ *
+ * A sibling of {@link readOwnSessionIds}, not a replacement: the two answer
+ * different questions and the difference is the whole point.
+ *
+ *   - `readOwnSessionIds()` answers *"could this id name me?"* and unions three
+ *     tiers, the third of which IS `session.lock`. That union is correct when
+ *     the thing being classified was written by some OTHER process (a wave-scope
+ *     manifest), because every id this process can legitimately claim counts.
+ *   - This function answers *"which process is emitting right now?"*, and for
+ *     that question the lock is **vacuous**: when the candidate ids under
+ *     judgement are the lock's OWN values, a membership test against a set that
+ *     contains the lock matches by construction — a peer-owned lock would
+ *     classify as `own` 100% of the time.
+ *
+ * **STATE.md is excluded for the same reason, and this is the #1177-FX1 fix.**
+ * `.claude/STATE.md` is a SHARED working-copy artefact written by whichever
+ * session owns the working copy — normally the lock holder. So when a peer holds
+ * the lock, the peer also wrote STATE.md, and the two "independent" witnesses
+ * agree with each other about the PEER. Unioning a shared-file witness with a
+ * process-local one lets the weaker witness carry the verdict while a
+ * disagreeing process-local id cannot veto it (measured: lock=peer +
+ * STATE.md=peer + `CLAUDE_CODE_SESSION_ID`=me stamped the PEER's ids). Tiering
+ * rather than unioning is the fix — a better signal REPLACES a worse one
+ * (`.claude/rules/host-resources.md` § HR-102).
+ *
+ * Never throws.
+ *
+ * @param {{ env?: object, hookInput?: object|null }} [opts]
+ * @param {object} [opts.env=process.env] — injectable for tests.
+ * @param {object|null} [opts.hookInput=null] — the harness's statement about
+ *   THIS invocation, when the caller is a hook.
+ * @returns {string[]} possibly EMPTY — an empty result means "this process
+ *   cannot prove who it is", which callers must treat as unprovable rather
+ *   than as a match.
+ */
+export function readProcessLocalSessionIds({ env = process.env, hookInput = null } = {}) {
+  const ids = [];
+  const add = (value) => {
+    const trimmed = typeof value === 'string' ? value.trim() : '';
+    if (trimmed && !ids.includes(trimmed)) ids.push(trimmed);
+  };
+
+  // Tier 1 — the harness's statement about THIS invocation.
+  if (hookInput && typeof hookInput === 'object') {
+    for (const key of ['session_id', 'sessionId', 'parent_session_id']) add(hookInput[key]);
   }
+  // Tier 2 — process-scoped env var.
+  add(env?.CLAUDE_CODE_SESSION_ID);
+
   return ids;
 }
 
@@ -135,22 +232,101 @@ export function readOwnSessionIds(repoRoot, { 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'`).
- * @param {Set<string>} ownIds — from {@link readOwnSessionIds}.
+ * @param {Set<string>} ownIds — from EITHER producer, depending on what is
+ *   being judged: {@link readOwnSessionIds} when every id this process could
+ *   legitimately claim counts, or `new Set(`{@link readProcessLocalSessionIds}
+ *   `(...))` when the lock tier would match vacuously — which is the case for a
+ *   wave-scope manifest in a checkout shared by two sessions (#1194). Note the
+ *   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',

package/scripts/lib/session-transition.mjs

@@ -134,7 +134,7 @@ export const LOCK_RELEASED_EVENT = 'orchestrator.session.lock.released';
  *   lock owned by someone else, an unparseable lock, a registry entry pinned to
  *   a different root, a registry unlink that failed, a contradictory owner
  *   proof, or a filesystem error. Callers WARN on it and continue; see the
- *   `parallel-aware: leaveSourceRoot: <reason>` contract in
+ *   `enterWorktree: leaveSourceRoot: <reason>` contract in
  *   `skills/_shared/parallel-aware-auq.md`.
  *
  *   `reason` is present whenever something other than a full clean teardown