session-orchestrator 3.24.0 → 4.0.0

package/skills/session-start/phase-8-5-express-path.md

@@ -21,7 +21,7 @@ invalid `--session-type` / `--task-count` / `--repo-root`), exit `2` an unreadab
 `--parallel-agents` is optional and tri-state — omitting it asserts nothing and leaves the field
 out of the record, which is NOT the same claim as `false`.
 
-`--repo-root` is required and is never defaulted from `SO_PROJECT_DIR` (#941): an ambient
+`--repo-root` is required and is never defaulted from `getProjectDir()` (#941): an ambient
 destination once put a synthetic record into the operator's real fleet ledger.
 
 Until #1146 this block was a fenced `js` snippet with an `import` — prose no process runs. Measured

package/skills/session-start/references/phase-1-1-dispatcher-autonomy-capture.md

@@ -0,0 +1,55 @@
+# Phase 1.1: Dispatcher-Autonomy Migration Capture
+
+> Sub-file of the session-start skill (#1157 — agentskills.io: SKILL.md core < 500 lines, procedure in `references/`). Extracted VERBATIM from `skills/session-start/SKILL.md`; `SKILL.md` keeps a one-line stub naming this phase and its gate condition.
+
+## Phase 1.1: Dispatcher-Autonomy Migration Capture (one-time, per-repo)
+
+> Closes session-orchestrator issue #681 (Epic #673 P3 — one-time per-repo dispatcher-autonomy capture). Migration trigger: the first session-start after this feature ships on a repo whose committed `dispatcher-autonomy:` block is still absent. Cross-reference `.claude/rules/ask-via-tool.md` (AUQ via tool, not prose).
+
+**WHEN:** Runs after Phase 1 (config read) and BEFORE Phase 1.2 (session-lock acquire). Fires **exactly once per repo** — the write makes the committed block present, so every subsequent session skips it.
+
+**WHY (one-time guard):** The committed `## Dispatcher Autonomy` block is the never-re-ask marker. Detect "block absent" via `isDispatcherAutonomyBlockPresent($CLAUDE_MD_CONTENT)` — a raw `/^dispatcher-autonomy:\s*$/m` presence check on the file content. Do NOT use the resolved autonomy value from `$CONFIG`: it returns `'off'` for BOTH "block absent" AND "block present with `autonomy: off`", so it cannot distinguish a first-run migration from a deliberate `off`. Only the raw presence check distinguishes them.
+
+> **The guard is gated purely on committed-block PRESENCE, never on the resolved value.** A machine whose effective autonomy differs from the committed default — because `SO_DISPATCHER_AUTONOMY` or `owner.yaml` `dispatcher.autonomy` overrides it — STILL counts as captured the moment the committed block exists, and is never re-asked. Conversely a host with `owner.yaml` `dispatcher.autonomy` set but NO committed block is still asked once at this migration: a host-local override does NOT satisfy the migration guard; only the committed CLAUDE.md / AGENTS.md block does. Even a header-present-but-body-malformed block counts as PRESENT (a malformed block is the operator's to fix, not a re-prompt trigger).
+
+**WHAT:** When the block is absent, the coordinator dispatches ONE `AskUserQuestion` using the definition from `scripts/lib/config/dispatcher-autonomy-capture.mjs`:
+
+- **Dispatcher autonomy** — `off` (Recommended, fail-closed) | `advisory` | `autonomous-gated`
+
+On **any** answer (including `off`) the committed block is written, presented, and never re-asked. The writer persists ONLY the committed default — host-local overrides (`SO_DISPATCHER_AUTONOMY` env, `owner.yaml` `dispatcher.autonomy`) stay host-local and NEVER land in CLAUDE.md.
+
+> **Capture writes the committed default; the runtime value flows through `resolveDispatcherAutonomy`.** This phase only persists the operator's one-time choice as the committed baseline. The EFFECTIVE autonomy at run time is resolved separately by `resolveDispatcherAutonomy()` in `scripts/lib/config/dispatcher-autonomy.mjs` with host-local precedence `SO_DISPATCHER_AUTONOMY` env > `owner.yaml` `dispatcher.autonomy` > committed > `off` (#653 pattern). Migration capture never reads or writes those override tiers — it writes the committed tier only, so a machine with an active override differs from the committed default WITHOUT re-triggering this capture.
+
+**AUQ (mandatory — use the tool, not prose):** On Claude Code / Cursor IDE, dispatch this via the **`AskUserQuestion` tool** per `.claude/rules/ask-via-tool.md` (AUQ-001) — never an inline markdown "choose 1/2/3" list. Option 1 (`off`) is the recommended, fail-closed default. Only Codex CLI (no `AskUserQuestion`) falls back to a numbered-list prose prompt (AUQ-004 exception 1).
+
+**HOW (coordinator steps):**
+
+```js
+import {
+  getDispatcherAutonomyQuestion,
+  isDispatcherAutonomyBlockPresent,
+  writeDispatcherAutonomyBlock,
+} from '$PLUGIN_ROOT/scripts/lib/config/dispatcher-autonomy-capture.mjs';
+import { readFileSync } from 'node:fs';
+
+const claudeMdPath = `${process.cwd()}/CLAUDE.md`;
+let content = '';
+try { content = readFileSync(claudeMdPath, 'utf8'); } catch { /* no CLAUDE.md — skip */ }
+if (content && !isDispatcherAutonomyBlockPresent(content)) {
+  const q = getDispatcherAutonomyQuestion(); // option 1 = 'off' (Recommended, fail-closed)
+  // Claude Code / Cursor: dispatch AskUserQuestion([q]) (the TOOL — AUQ-001); collect the
+  //   selected label (the `autonomy` enum). Never an inline numbered-list prose question here.
+  // Codex CLI fallback only (no AskUserQuestion — AUQ-004 exception 1): print q.question +
+  //   numbered q.options list, read the operator's pick, map it to the option label.
+  const autonomy = /* selected option label: 'off' | 'advisory' | 'autonomous-gated' */;
+  const result = writeDispatcherAutonomyBlock({ claudeMdPath, autonomy });
+  // result: { written: true, path } on first write; { written: false, reason: 'already-present' } if a
+  //   parallel session already wrote it OR a malformed block already exists (defensive
+  //   double-write guard re-checks absence against freshly-read content before writing).
+}
+```
+
+> Skip silently when no committed `CLAUDE.md` exists (e.g. a not-yet-bootstrapped repo) — the read failure is non-fatal. The capture then runs at bootstrap (Phase 3.5.1) instead.
+
+**WHERE:** Appended as a standalone `## Dispatcher Autonomy` H2 in the repo's committed `CLAUDE.md` (NOT a key inside `## Session Config` — the standalone-H2 placement keeps `claude-md-drift-check` Check-6 parity green).
+

package/skills/session-start/references/phase-1-2-session-lock.md

@@ -0,0 +1,140 @@
+# Phase 1.2 + 1.2.1: Session Lock Acquire and Peer-Guard
+
+> Sub-file of the session-start skill (#1157 — agentskills.io: SKILL.md core < 500 lines, procedure in `references/`). Extracted VERBATIM from `skills/session-start/SKILL.md`; `SKILL.md` keeps a one-line stub naming this phase and its gate condition.
+
+## Phase 1.2: Session Lock Acquire (#330)
+
+> **See also Phase 0.5 (Parallel-Aware Preamble)** — the cross-worktree detection runs first. This Phase 1.2 handles the single-worktree local-lock semantics that complement the preamble.
+
+> Skip this phase if `persistence` config is `false`.
+
+Acquire a distributed session-lock to detect parallel sessions in the same repo before initializing STATE.md. This prevents two concurrent Claude/Codex sessions from stomping each other's wave state and metrics writes.
+
+**Mechanical wiring (Epic #583, 2026-05-27):** The SessionStart hook (`hooks/on-session-start.mjs` → `hooks/_lib/lock-bootstrap.mjs`) now writes `.orchestrator/session.lock` mechanically BEFORE this skill's prose runs. The prose Phase 1.2 becomes confirmatory — it verifies the lock exists with the expected shape via `readLock({ repoRoot: process.cwd() })`. Re-call `acquire()` only if `readLock()` returns `null` (mechanical hook failed) OR the existing lock's raw `session_id` does not exactly match the current session's raw id (a rare divergence — surface via AUQ before overwriting). A matching `semantic_session_id`, STATE.md `session`, or owner proof cannot repair that mismatch. The decision flow below still applies to all three outcomes (active / stale / fs-error) when the prose path needs to acquire.
+
+```javascript
+import { acquire, forceAcquire } from 'scripts/lib/session-lock.mjs';
+const result = acquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: process.cwd() });
+```
+
+Where `sessionId` is the physical raw identity for this invocation: the native harness-provided raw id, or a generated UUID when no trustworthy raw id exists. It is the only value passed to `acquire()` and the only live lock/registry ownership key. `semanticSessionId` may be recorded separately as an attribution/history label and may populate STATE.md `session`; neither label is a substitute for `sessionId`. `sessionType` is the session mode (`housekeeping`, `feature`, or `deep`).
+
+### Decision flow
+
+1. **`result.ok === true`** → lock is held. Continue to Phase 1.5 (Session Continuity). The lock must be released in session-end.
+
+2. **`result.ok === false`** with `reason === 'active'**:
+   - Another Claude/Codex session holds an active lock in this repo.
+   - Present a choice via `AskUserQuestion`:
+     ```js
+     AskUserQuestion({
+       questions: [{
+         question: `Another session holds the lock here — started ${ageHours}h ago, mode=${existingLock.mode}, host=${existingLock.host}, pid=${existingLock.pid}. Wait, or take the lock?`,
+         header: "Session lock",
+         multiSelect: false,
+         options: [
+           { label: "Abort (Recommended)", description: "Stop here and let the other session finish, then start again. Nothing is written until it releases the lock, and two sessions sharing one wave state overwrite each other's metrics." },
+           { label: "Force-take the lock", description: "Overwrites the active lock and starts anyway. Only when that session is certainly gone — otherwise both keep writing the same wave state and one of them loses everything." },
+         ],
+       }],
+     });
+     ```
+   - **Codex CLI / Cursor IDE fallback (numbered Markdown list):**
+     ```
+     Another session holds the lock here — started <ageHours>h ago, mode=<mode>, host=<host>, pid=<pid>. Wait, or take the lock?
+     1. Abort (Recommended) — stop here and let the other session finish, then start again; nothing is written until it releases the lock.
+     2. Force-take the lock — overwrites the active lock. Only when that session is certainly gone, otherwise both keep writing the same wave state and one loses everything.
+     Reply with the number of your choice.
+     ```
+   - On **Abort**: exit session-start cleanly with a brief stderr note (`session-lock: aborted — active lock held by session_id=<id>`). Do NOT initialize STATE.md.
+   - On **Force-take**: call `forceAcquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: process.cwd() })`. After Phase 1.5 initializes STATE.md, append a deviation via `appendDeviation()`:
+     `Force-took session lock from session_id=<existingLock.session_id>, age=<ageHours>h, mode=<existingLock.mode>, pid=<existingLock.pid>`. Continue.
+
+3. **`result.ok === false`** with `reason === 'stale-heartbeat'`:
+   - A stale lock was found (its last heartbeat is older than its ttl). Likely left behind by a session that crashed or was force-killed. The lock's recorded `pid` is NOT consulted — it belongs to the ephemeral hook subprocess that wrote the lock, never to the session; measured 2026-08-23: 7 of 7 recorded pids were dead, including the live heartbeating session's own (#1137).
+   - Present a choice via `AskUserQuestion`:
+     ```js
+     // `heartbeatAgeMinutes` and `ageHours` come straight off the acquire() result (#1137);
+     // `sameHost` is not on the result — compute it first. Use hostnamesMatch, NEVER a raw
+     // `===` against os.hostname(): the hostname flips spelling on a single machine
+     // (measured 2026-08-24: `Mac.home` and `Ferdinands-MacBook-Pro.local` ten minutes apart),
+     // so a raw comparison labels this machine's OWN lock "another machine" (#1072).
+     // `||`, not `??` — an EMPTY-STRING host_id must fall back to `host`, or
+     // hostnamesMatch('', …) is false and this machine reads its own lock as
+     // cross-host. Production uses `lockHostCandidate()` from host-identity.mjs.
+     const sameHost = hostnamesMatch(existingLock.host_id || existingLock.host, os.hostname());
+     AskUserQuestion({
+       questions: [{
+         question: `A stale session lock is in the way — started ${ageHours}h ago on host=${existingLock.host}${sameHost ? '' : ' (another machine)'}, its ttl=${existingLock.ttl_hours}h has expired, and its last heartbeat was ${Math.round(heartbeatAgeMinutes)} minutes ago. Reclaim it?`,
+         header: "Stale lock",
+         multiSelect: false,
+         options: [
+           { label: "Reclaim (Recommended)", description: "Overwrites the stale lock and continues, because its time-to-live has run out. When that process is really dead, nothing of the old session is lost." },
+           { label: "Abort — investigate manually", description: "Stops here and writes nothing. The lock file `.orchestrator/session.lock` (it names the process that wrote it) tells you whether that session is still alive." },
+         ],
+       }],
+     });
+     ```
+   - **Codex CLI / Cursor IDE fallback (numbered Markdown list):**
+     ```
+     A stale session lock is in the way — started <ageHours>h ago on <host>, ttl=<ttlHours>h expired, last heartbeat <heartbeatAgeMinutes> minutes ago. Reclaim it?
+     1. Reclaim (Recommended) — overwrites the stale lock and continues, because its time-to-live has run out and that process is no longer holding anything.
+     2. Abort — stops here and writes nothing. The lock file `.orchestrator/session.lock` (it names the process that wrote it) tells you whether that session is still alive.
+     Reply with the number of your choice.
+     ```
+   - On **Reclaim**: call `forceAcquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: process.cwd() })`. After Phase 1.5 initializes STATE.md, append a deviation:
+     `Stale-lock reclaim: replaced lock from session_id=<existingLock.session_id>, age=<ageHours>h, pid=<existingLock.pid>`. Continue.
+   - On **Abort**: exit cleanly.
+
+4. **`result.ok === false`** with `reason === 'fs-error'**:
+   - Filesystem error when writing the lock file. Log `⚠ session-lock: acquire failed — <error>. Continuing without lock (degraded mode).` and proceed without a lock. Do NOT block the session for a transient FS error.
+
+> **New reasons from P1.2 #570:** When called with the optional `activeSessions` argument, `acquire()` can also return `active-incompatible-exclusive`, `active-compatible-parallel`, or `active-readonly-bypass`. Session-start invokes `acquire()` WITHOUT `activeSessions` (the preamble in Phase 0.5 already handled cross-worktree detection); these new reasons surface only in callers that bypass the preamble. Other entry-points (autopilot, session-plan, wave-executor, session-end) follow the same pattern.
+
+### Cross-host behaviour
+
+When `hostnamesMatch(existingLock.host_id || existingLock.host, os.hostname())` is **false** — never a raw `existingLock.host !== os.hostname()`, which labels this machine's own lock "another machine" the moment the hostname flips spelling (#1072; mirror the Phase-1.2 snippet above) — the lock was written on another machine and nothing local can corroborate its heartbeat. `checkStale()` carries no `pidAlive` field at all (REMOVED in #1151; #1137 had left it as an always-`null` stub) — `heartbeatAgeMinutes` is the magnitude to reason from, and `isLive` the verdict. In this case:
+- For `reason === 'active'`: the recommendation is **Abort** — cross-host locks cannot be verified as dead.
+- For stale reasons: the recommendation is still **Reclaim** only if TTL is clearly expired (>2× ttl_hours). Otherwise default to **Abort**.
+- **Never auto-reclaim cross-host locks** under any circumstance — always present the AUQ and let the user decide.
+- The AUQ question text for cross-host cases should note: `"(cross-host — the heartbeat cannot be corroborated locally)"`. Do NOT phrase it as PID liveness: the pid on a lock belongs to the ephemeral writer subprocess, not the session, and is never probed (#1137/#1151).
+
+## Phase 1.2.1: Peer-Guard (Epic #583 defense-in-depth)
+
+> Skip this phase if `persistence` config is `false`.
+
+After Phase 1.2 acquires (or confirms) the lock, use `findPeers(repoRoot, { mySessionId: callerSessionHint })` for the STATE.md peer guard. `callerSessionHint` is the original semantic attribution label when one exists, otherwise the raw `sessionId`: `findPeers` may translate the semantic hint for the discovered lock/registry surface only after the exact raw binding check in `parallel-aware-preamble.md`, while keeping the original hint for STATE.md. This catches the rare case where lock-based detection missed an active peer (e.g., the peer's `session.lock` was force-deleted by an out-of-band sweep but STATE.md is still `status: active`, OR the peer's registry write succeeded but the lock-bootstrap hook crashed before the lock landed).
+
+```javascript
+import { findPeers } from '$PLUGIN_ROOT/scripts/lib/peer-discovery.mjs';
+// Keep the STATE.md comparison in its original attribution-label space.
+// findPeers performs the guarded semantic→raw translation only for discovered peers.
+const callerSessionHint = semanticSessionId ?? sessionId;
+const { peers } = await findPeers(process.cwd(), { mySessionId: callerSessionHint });
+const peer = peers.find((p) => p.source === 'state-md') ?? null;
+// Phase 1.2.1 consumes only the 'state-md' subset (STATE.md surface only).
+if (peer) {
+  // STATE.md is owned by an active peer — do NOT overwrite.
+  // peer.sessionId, peer.mode, peer.currentWave, peer.ageHours are populated.
+  // Fire the Worktree-Promotion AUQ from parallel-aware-auq.md.
+}
+```
+
+GH#67 note: the `lockSuperseded` advisory-downgrade described in Phase 0.5's outcome handling applies only to the `discovered` peer subset — this phase's `peer` is always `source: 'state-md'`, so a `discovered`-side `lockSuperseded: true` never suppresses this guard; the Worktree-Promotion AUQ still fires exactly as below whenever a live STATE.md peer is found.
+
+### Decision flow
+
+1. **`peer === null`** → no active peer owns STATE.md. Continue to Phase 1.5.
+2. **`peer !== null`** → STATE.md is owned by a live peer session. **Do NOT proceed with the default Phase 1.5/1b STATE.md overwrite.** Fire the Worktree-Promotion AUQ from `skills/_shared/parallel-aware-auq.md` (same options the Phase 0.5 preamble would emit on `PROMOTION_OFFER`).
+   - User picks "Worktree anlegen + starten" → call `enterWorktree({ ..., rawSessionId, reason: 'worktree-promotion' })` from `scripts/lib/autopilot/worktree-pipeline.mjs` — since #1170 this ONE call also releases the source root: it calls `leaveSourceRoot({ repoRoot, sessionId: rawSessionId, semanticSessionId, reason })` from `scripts/lib/session-transition.mjs` internally, on BOTH success exits, so no separate `leaveSourceRoot` call is made at this site. `rawSessionId` is the RAW physical `session_id` read from this root's `.orchestrator/session.lock` via `readLock({ repoRoot })`, never the semantic label and never `current-session.json` (which may describe a peer, #863) — (#1069 process boundary: this site runs AFTER Phase 1.2 already acquired the lock, so the old root MUST be deregistered and its lock released here, or the new worktree's own Phase 1.2 finds a phantom owner). The return value's `left` field carries `leaveSourceRoot()`'s result; it never throws, so on `left.ok !== true` `enterWorktree` itself emits the stderr WARN `enterWorktree: leaveSourceRoot: <reason>` and the promotion continues regardless — the destination worktree already exists, so aborting here would leave exactly the two-live-roots state the call prevents. Then exit Phase 1 immediately (the new worktree's own session-start runs from scratch).
+   - User picks "Manuell — in-place daneben" → append a Deviation describing the missed peer detection, continue to Phase 1.5. STATE.md WILL be overwritten — the user has explicitly accepted that risk.
+   - User picks "Abbrechen" → exit cleanly.
+
+### Soft-gate semantics
+
+This is a SOFT-GATE — the operator can override via the AUQ — but the warning is mandatory and must not be silenced. Treat any `checkPeerStateMd` failure (read error, malformed STATE.md, etc.) as `peer === null` (fail-open: do not block the session for a corrupted STATE.md file; the rest of the parallel-aware machinery still applies).
+
+### Why this complements Phase 1.2
+
+Phase 1.2 owns the `.orchestrator/session.lock` file; Phase 1.2.1 owns the STATE.md frontmatter. The two surfaces can disagree (briefly, during a crash; durably, if a sweep deleted one but not the other). The Peer-Guard treats STATE.md as a second, independent source of truth — if EITHER source says a peer is active, the coordinator must pause before stomping shared state.
+

package/skills/session-start/references/phase-1-5-session-continuity.md

@@ -0,0 +1,254 @@
+# Phase 1.5: Session Continuity
+
+> Sub-file of the session-start skill (#1157 — agentskills.io: SKILL.md core < 500 lines, procedure in `references/`). Extracted VERBATIM from `skills/session-start/SKILL.md`; `SKILL.md` keeps a one-line stub naming this phase and its gate condition.
+
+## Phase 1.5: Session Continuity
+
+> Skip this phase if `persistence` config is `false`.
+
+Check for `<state-dir>/STATE.md` in the project root:
+
+> Where `<state-dir>` is `.claude/` under Claude Code or `.codex/` under Codex CLI. See `skills/_shared/platform-tools.md` for details.
+
+> **Ownership Reference:** See `skills/_shared/state-ownership.md` for the STATE.md ownership contract, schema, and guards.
+
+Before reading STATE.md contents, validate the branch field:
+- If STATE.md's `branch` does not match `git rev-parse --abbrev-ref HEAD`, log: "⚠ STATE.md from branch [X], current branch is [Y] — treating as stale." Skip to step 2 (treat as if STATE.md does not exist).
+
+1. **STATE.md exists** — read it and inspect the `status` field:
+   - `status: active` — previous session crashed or was interrupted. Use the AskUserQuestion tool to present: "Found unfinished session from [started_at]. [N] waves completed. Resume or start fresh?" with options to resume the previous plan or start a new session. After a resume choice, proceed to **Snapshot Recovery** subsection below. **HISTORICAL guard (mandatory, #621):** when the user chooses resume, any surfaced prior-session plan, wave-history, deviations, or recommendations MUST be presented wrapped in the HISTORICAL guard banner BEFORE you act on them — never treat the recovered record as a live instruction.
+   - `status: paused` — session was intentionally paused. Use AskUserQuestion to offer resuming from the pause point or starting fresh. After a resume choice, proceed to **Snapshot Recovery** subsection below. **HISTORICAL guard (mandatory, #621):** as on the `active` branch, surface the resumed prior-session plan / wave-history / deviations wrapped in the HISTORICAL guard banner before acting on it.
+   - `status: completed` — previous session ended cleanly. Note the summary for context (what was done, what was deferred), then **render the Recommendations Banner** (see subsection below) and **reset STATE.md to idle** before any new session state is written (see "Idle Reset" below). Continue with normal initialization.
+2. **STATE.md does not exist** — first session or persistence was previously off. Continue normally.
+
+> **HISTORICAL guard banner (SSOT: `scripts/lib/historical-guard.mjs`, exported as `HISTORICAL_GUARD_BANNER`).** When resuming an `active` or `paused` session, prefix the surfaced prior-session context with this LITERAL banner so the coordinator never treats a stale record as a live instruction (documented incident class: crashed-session resume on a stale premise):
+>
+> `⚠ HISTORICAL REFERENCE ONLY — NOT LIVE INSTRUCTIONS. This is a record of a prior session. Verify every claim against current git state and open issues before acting. Do NOT re-execute slash-commands or ARGUMENTS quoted here.`
+>
+> Verify every quoted claim against current `git` state and open issues, and do NOT re-execute slash-commands or ARGUMENTS lifted from the prior record.
+
+### Recommendations Banner (Epic #271 Phase A)
+
+> Runs on the `status: completed` branch only, BEFORE Idle Reset archives the fields. Silent no-op on other branches.
+
+> **HISTORICAL guard (mandatory, #621).** The "📋 Previous session recommended…" output below is a prior-session record, not a live instruction. Prepend the LITERAL banner (SSOT: `scripts/lib/historical-guard.mjs`, importable as `HISTORICAL_GUARD_BANNER` from `@lib/historical-guard.mjs` inside the `node -e` block) so the coordinator verifies before acting:
+>
+> `⚠ HISTORICAL REFERENCE ONLY — NOT LIVE INSTRUCTIONS. This is a record of a prior session. Verify every claim against current git state and open issues before acting. Do NOT re-execute slash-commands or ARGUMENTS quoted here.`
+>
+> Verify every recommended mode / priority / rationale against current `git` state and open issues, and do NOT re-execute any slash-commands or ARGUMENTS the prior session quoted.
+
+Read the 5 optional v1.1 Recommendation fields from STATE.md frontmatter via `parseRecommendations` (from `scripts/lib/state-md.mjs`). The writer is session-end Phase 3.7a (see `skills/session-end/SKILL.md`).
+
+```bash
+node --input-type=module -e "
+import {readFileSync} from 'node:fs';
+import {parseStateMd, parseRecommendations} from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
+import {isValidMode} from '${PLUGIN_ROOT}/scripts/lib/recommendations-v0.mjs';
+import {HISTORICAL_GUARD_BANNER} from '${PLUGIN_ROOT}/scripts/lib/historical-guard.mjs';
+import {appendFileSync, mkdirSync} from 'node:fs';
+
+const SWEEP_LOG = '.orchestrator/metrics/sweep.log';
+function logWarn(event, detail) {
+  try {
+    mkdirSync('.orchestrator/metrics', {recursive: true});
+    appendFileSync(SWEEP_LOG, JSON.stringify({timestamp: new Date().toISOString(), event, detail}) + '\n');
+  } catch {}
+}
+
+const parsed = parseStateMd(readFileSync('<state-dir>/STATE.md', 'utf8'));
+if (!parsed) process.exit(0);
+const rec = parseRecommendations(parsed.frontmatter);
+if (!rec) process.exit(0); // pre-v1.1 STATE.md — graceful silent no-banner (AC3)
+
+// AC4: type-mismatch in top-priorities — field-level null from parser; still render other fields
+if (rec.priorities === null && Object.prototype.hasOwnProperty.call(parsed.frontmatter, 'top-priorities')) {
+  logWarn('state-md-type-mismatch', {field: 'top-priorities', got: typeof parsed.frontmatter['top-priorities']});
+}
+
+// AC4: partial fields — warn but still render available ones
+const missingCount = [rec.mode, rec.priorities, rec.carryoverRatio, rec.completionRate, rec.rationale].filter((x) => x === null).length;
+if (missingCount > 0 && missingCount < 5) {
+  logWarn('state-md-partial-recommendation', {missing: missingCount});
+}
+
+const modeOk = rec.mode && isValidMode(rec.mode);
+const mode = modeOk ? rec.mode : '(unknown-mode)';
+const rationale = rec.rationale || '(no rationale)';
+const pct = (x) => (x === null ? '—' : Math.round(x * 100) + '%');
+console.log(HISTORICAL_GUARD_BANNER); // #621 — prior-session record, verify before acting; do NOT re-execute quoted commands/ARGUMENTS
+console.log('📋 Previous session recommended: ' + mode + ' — ' + rationale + ' (completion: ' + pct(rec.completionRate) + ', carryover: ' + pct(rec.carryoverRatio) + ')');
+if (Array.isArray(rec.priorities) && rec.priorities.length > 0) {
+  console.log('  Suggested issues: ' + rec.priorities.map((id) => '#' + id).join(', '));
+}
+"
+```
+
+**Behavior matrix (AC1/AC3/AC4):**
+- All 5 fields present + valid → banner line + suggested-issues line (if priorities non-empty).
+- Field(s) absent entirely → no banner (graceful no-op, no WARN).
+- 1–4 fields present (partial) → banner renders with `—` for missing, WARN `state-md-partial-recommendation` to sweep.log.
+- `top-priorities` is not an array (type-mismatch) → treated as null, WARN `state-md-type-mismatch` to sweep.log, other fields still render.
+- Unknown `recommended-mode` value → banner shows `(unknown-mode)` instead of the string.
+
+The reader does NOT mutate STATE.md — it is a pure observer. Idle Reset (subsection below) is the only code path that modifies the file on the `completed` branch.
+
+### Idle Reset (completed-branch only)
+
+When (and only when) the prior `status` is `completed`, rewrite STATE.md to a clean idle state before Phase 1b (Initialize STATE.md) runs. This prevents the next agent from reading a stale "completed" banner at session-start, while preserving the prior session's record in a demoted archive block.
+
+Reset rules — applies ONLY on the `completed` branch. Do NOT perform this reset on `active` or `paused`; those paths stay user-interactive via AskUserQuestion.
+
+1. Set frontmatter `status: idle`.
+2. Clear `current-wave` (set to `0`).
+3. Move the existing `## Wave History` body into a new `## Previous Session` archive section (retain the record, but demote it below the new session's live state). Remove the original `## Wave History` section — wave-executor will recreate it on the next wave.
+4. Clear `## Deviations` (leave the heading with an empty body so the schema is preserved).
+   - **PRESERVE `## What Not To Retry` (#623):** do NOT clear, demote, or drop this section during the Idle Reset. Unlike `## Deviations` (per-session, emptied above) and `## Wave History` (demoted into `## Previous Session`), `## What Not To Retry` is a **cross-session continuity slot** — its entries must survive into the next session so session-start Phase 6.5.1 can surface them. Leave the section, its heading, and all entries byte-for-byte intact.
+   - **PRESERVE `## Open Questions` (#772):** do NOT clear, demote, or drop this section during the Idle Reset. Unlike `## Deviations` (per-session, emptied above) and `## Wave History` (demoted into `## Previous Session`), `## Open Questions` is a **cross-session continuity slot** — unanswered entries must survive into the next session so session-start Phase 6.5.2 can surface them as a forced-read. Leave the section, its heading, and all entries (answered and unanswered) byte-for-byte intact.
+5. Leave other frontmatter fields (`schema-version`, `session-type`, `branch`, `issues`, `started_at`, `total-waves`) intact until Phase 1b overwrites them with the new session's values.
+6. **v1.1 Recommendation-field archival (Epic #271 Phase A, AC2):** If ANY of the 5 Recommendation fields (`recommended-mode`, `top-priorities`, `carryover-ratio`, `completion-rate`, `rationale`) is present in the frontmatter, remove them from the frontmatter via `updateFrontmatterFields(contents, {field: null, ...})` (null value deletes the key). Then prepend a readable block (NOT YAML) to the `## Previous Session` body:
+
+   ```markdown
+   ### Recommendations (archived from v1.1 frontmatter)
+   - **Recommended mode:** <mode>
+   - **Rationale:** <rationale>
+   - **Completion rate:** <XX%>
+   - **Carryover ratio:** <XX%>
+   - **Top priorities:** #<id>, #<id>, …  _(or "none")_
+   ```
+
+   Omit individual bullets for null-valued fields. If all 5 are null (i.e., `parseRecommendations` returned non-null but every field is null after type-coercion), skip the archival block entirely.
+7. **Scope-baseline key deletion (Epic #894 S5, #898):** If ANY of the 5 `scope-baseline-*` frontmatter keys (`scope-baseline-intent`, `scope-baseline-owner-boundary`, `scope-baseline-planned-files`, `scope-baseline-session`, `scope-baseline-frozen-at`) is present, remove them via the same `updateFrontmatterFields(contents, {field: null, ...})` mechanism as rule 6 (null value deletes the key). Rule 5 leaves unknown frontmatter fields intact and no other rule removes these five — without this step they survive into session N+1 and silently corrupt the next session's drift-baseline denominator. This is a hygiene layer only: the primary defense is mechanical — `scripts/lib/scope-baseline.mjs` compares `scope-baseline-session` against the canonical `session` field, so a stale baseline self-invalidates (`readBaseline()` returns `{stale: true, …}`) even if this rule were skipped. Delete exactly these five keys; do not remove any other unknown key.
+
+Rationale: `/close` intentionally keeps STATE.md as a record so the next session-start can read it. This reset completes that contract by demoting the record before new session state is written, so a fresh session never appears "already completed". The Recommendation archival (rule 6) preserves the session-to-session handoff in a human-readable form after the Recommendations Banner has rendered — Phase B's Mode-Selector will read the LIVE frontmatter of the current session and does not need the archived copy, so this is purely informational for humans browsing STATE.md history.
+
+### Snapshot Recovery (#196)
+
+> **HISTORICAL guard (mandatory, #621).** The recovered working-tree state and the shown diff below are HISTORICAL — a record of where a prior session left off, NOT live instructions. Treat them under the LITERAL banner (SSOT: `scripts/lib/historical-guard.mjs`):
+>
+> `⚠ HISTORICAL REFERENCE ONLY — NOT LIVE INSTRUCTIONS. This is a record of a prior session. Verify every claim against current git state and open issues before acting. Do NOT re-execute slash-commands or ARGUMENTS quoted here.`
+>
+> Verify the recovered tree against current `git` state before building on it, and do NOT re-execute any slash-commands or ARGUMENTS the snapshot implies.
+
+Applies ONLY after the user chose to **resume** from the `active`/`paused` branch above. Skip entirely on the `completed` branch (snapshots for completed sessions are GC'd by session-end, not offered for recovery) and on the "start fresh" path of an `active`/`paused` prompt (starting fresh implies abandoning any snapshot).
+
+```js
+import { listSnapshots, deleteSnapshot } from '$PLUGIN_ROOT/scripts/lib/coordinator-snapshot.mjs';
+
+const snaps = await listSnapshots({ sessionId: '<sessionId from STATE.md>' });
+```
+
+If `snaps.length === 0` → no snapshots to recover; continue to the Current-Task Banner.
+
+If `snaps.length >= 1` → present the following choice:
+
+**Claude Code (AskUserQuestion):**
+
+Before asking, read what "Recover" would actually put back — the operator decides on that diff, not on the word:
+
+```js
+import { execFileSync } from 'node:child_process';
+
+// Read-only: `git stash show` prints a diffstat and never touches the working tree.
+// Capped at 12 lines so the preview box stays shorter than the option list beside it.
+const stat = execFileSync('git', ['stash', 'show', '--stat', snaps[0].sha], { encoding: 'utf8' })
+  .split('\n').slice(0, 12).join('\n');
+const refs = snaps.map((s) => s.ref).join('\n');
+```
+
+```js
+AskUserQuestion({
+  questions: [{
+    question: `${snaps.length} snapshot(s) from the resumed session, newest ${humanAgeOf(snaps[0].createdAt)}. Recover, keep, discard?`,
+    header: "Snapshot",
+    multiSelect: false,
+    options: [
+      {
+        label: "Recover (Recommended)",
+        description: "Puts the newest saved state back into your working tree and commits nothing. You can drop any of those changes afterwards.",
+        preview: `These files come back:\n\n\`\`\`\n${stat}\n\`\`\``,
+      },
+      {
+        label: "Keep as backup",
+        description: "Nothing happens now: `refs/so-snapshots/*` (the saved states) stay, and `git stash apply $(git rev-parse <ref>)` (this puts one back) works later.",
+      },
+      {
+        label: "Discard all",
+        description: "Deletes every saved state of this session for good: `refs/so-snapshots/<sessionId>/*` (all of them) is gone, and there is no second copy.",
+        preview: `Deleted for good:\n\n\`\`\`\n${refs}\n\`\`\``,
+      },
+    ],
+  }],
+});
+```
+
+`preview` renders beside the option list and only works with `multiSelect: false`. It is used here because the answer decides which literal text lands in the working tree — "Recover" is a diff, "Discard all" is a list of refs that stop existing. "Keep as backup" carries none: keeping is exactly the state the operator already sees.
+
+**Codex CLI / Cursor IDE fallback (numbered Markdown list):**
+
+These harnesses have no preview box, so the same diffstat is printed inline — it is the only place the operator ever sees it:
+
+```markdown
+"Recover" would put these files back:
+
+    <git stash show --stat <snaps[0].sha>, capped at 12 lines>
+
+<N> snapshot(s) from the resumed session, newest <age>. Recover, keep, discard?
+
+1. **Recover (Recommended)** — puts the newest saved state back into your working tree and commits nothing. You can drop any of those changes afterwards.
+2. **Keep as backup** — nothing happens now: `refs/so-snapshots/*` (the saved states) stay, and `git stash apply $(git rev-parse <ref>)` (this puts one back) works later.
+3. **Discard all** — deletes every saved state of this session for good: `refs/so-snapshots/<sessionId>/*` (all of them) is gone, and there is no second copy.
+
+Reply with the number of your choice.
+```
+
+On user choice:
+- **Recover** → `git stash apply <snaps[0].sha>` (use apply, not pop — leaves the ref intact in case the user changes their mind). Then show the resulting `git diff --stat` so the user sees what landed.
+- **Keep as backup** → no-op. Log in the Session Overview: `Snapshot(s) retained: <N>. Recover manually with \`git stash apply <sha>\`.`
+- **Discard all** → for each snapshot in `snaps`, call `deleteSnapshot({refName: snap.ref})`. Log count.
+
+Snapshot age (`humanAgeOf`) is derived from `snap.createdAt` (ISO 8601 from `git for-each-ref --format='%(committerdate:iso8601)'`). A simple inline helper:
+
+```js
+function humanAgeOf(iso) {
+  const mins = Math.floor((Date.now() - new Date(iso).getTime()) / 60000);
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h ago`;
+  return `${Math.floor(hrs / 24)}d ago`;
+}
+```
+
+### Current-Task Banner (#184)
+
+After the continuity checks above, render a one-line banner showing the current task from STATE.md. This gives the user an immediate "where am I" signal before the rest of the session overview loads.
+
+```bash
+node --input-type=module -e "
+import {readFileSync} from 'node:fs';
+import {readCurrentTask} from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
+try {
+  const t = readCurrentTask(readFileSync('<state-dir>/STATE.md', 'utf8'));
+  if (t) console.log('Current task: ' + t.description);
+} catch {}
+"
+```
+
+Skip silently when STATE.md is absent or unreadable. The banner is informational, not load-bearing.
+
+Also read `<state-dir>/STATUS.md` if it exists for additional project-level context.
+
+### Session-Profile Persistence (`ultradeep` alias)
+
+> **CONTENT ADDITION — not part of the #1157 move.** Applies to the STATE.md initialization write (Phase 1b), the same write that sets `session-type`. Rationale, wave shape and budgets: `docs/prd/2026-09-06-ultradeep-session-profile.md` — do not restate them here. Alias resolution: `commands/session.md` § Argument alias.
+
+When the `/session` argument was the `ultradeep` ALIAS, persist the profile alongside the type:
+
+```js
+import { setSessionProfile } from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
+// `session-type` stays `deep` and must NEVER become `ultradeep` — an unknown type
+// degrades SILENTLY in two places: `scripts/lib/telemetry/schema.mjs:83` maps it to
+// `other`, `scripts/lib/session-close-backfill.mjs:71` labels it `housekeeping`.
+contents = setSessionProfile(contents, 'ultradeep');
+```
+
+For every other argument, write **nothing** — absence is the contract, never `''`, `none` or `null` as a value. `setSessionProfile(contents, null)` deletes a stale key inherited from a previous session's record; it throws on an empty-string profile, so never pass one.

package/skills/session-start/references/phase-1-7-vault-status-board.md

@@ -0,0 +1,53 @@
+# Phase 1.7: Vault Live-Status Board (#674)
+
+> Sub-file of the session-start skill (#1157 — agentskills.io: SKILL.md core < 500 lines, procedure in `references/`). Extracted VERBATIM from `skills/session-start/SKILL.md`; `SKILL.md` keeps a one-line stub naming this phase and its gate condition.
+
+## Phase 1.7: Vault Live-Status Board (#674)
+
+> Skip this phase silently when `vault-integration.enabled` is not `true` in Session Config. Use the same `jq -r` idiom Phase 2.7 uses (`echo "$CONFIG" | jq -r '."vault-integration".enabled // false'`). When the value is anything other than `true`, do nothing and proceed to Phase 2 — no banner, no warning.
+
+When active, this phase marks THIS repo as live on the cross-repo vault board (`<vault-dir>/01-projects/_active-sessions.md`) so an operator scanning the vault can see, at a glance, which repos have a session in flight. Epic #673 / PRD §FA-1.
+
+### Config check
+
+```bash
+VAULT_ENABLED=$(echo "$CONFIG" | jq -r '."vault-integration".enabled // false')
+if [ "$VAULT_ENABLED" != "true" ]; then
+  exit 0  # silent no-op — vault integration disabled
+fi
+```
+
+### Dispatch
+
+Call `sweepBoard` from `scripts/lib/vault-status/board-writer.mjs` — the host-wide sweep (issue #716):
+
+```js
+import { sweepBoard } from 'scripts/lib/vault-status/board-writer.mjs';
+
+await sweepBoard({
+  repoRoot: process.cwd(),
+});
+```
+
+`sweepBoard` enumerates candidate repos host-wide (`enumerateCandidates` — confinement root `~/Projects` plus any `cross-repo.projects` config-declared repos, issue #676), re-derives the board status for every BUSY repo it finds (`in-progress` or `force-closed`, never `frei`), unions in THIS repo so its own row is always re-derived, and writes the board in one idempotent merge. **A crashed session in ANY repo now renders `force-closed` on the board from THIS repo's session-start** — not only from that repo's own next session-start/-end.
+
+> **Call-site contract:** `sweepBoard` is now the primary call. `explicitStatus` is **inert for `'in-progress'`** — `collectRows` only honors an explicit per-repo `status: 'closed'` override; THIS repo's `in-progress` row is always rendered from its own **live `session.lock` lease** (already written/heartbeated by Phase 1.2's `acquire()`), never from a passed-in status string. If constructing `repos` manually for a narrower sweep, `collectRows` requires `{ repoRoot }` object descriptors and silently skips bare path strings (`board-writer.mjs` `collectRows` guard) — `sweepBoard`/`buildSweepRepos` already produce the correct shape, so this only matters for a hand-rolled `mirrorBoard({ repos })` call.
+
+This single call does three things:
+
+1. **Sets THIS repo's board row to `in-progress`** with the current semantic-session-id **attribution label** (never a lock/registry ownership key), branch, mode, and heartbeat (read off this repo's `session.lock` v2 lease + the host-wide registry — both already written by Phase 1.2's `acquire()`).
+2. **Re-derives THIS repo's status from its live lease**, so a stale lease left by a prior crashed session in this same repo renders as `force-closed` (heartbeat older than the v2 ttl, default 4h — `DEFAULT_TTL_HOURS` in `scripts/lib/session-lock.mjs`, evaluated via `isLockLive`) and is **never silently dropped** — its fields are read straight off the dead lock.
+3. **Re-derives every OTHER busy repo's status host-wide** via `enumerateCandidates` — a dead lease in repo B renders `force-closed` on the board the next time ANY repo's session-start runs `sweepBoard`, closing the #676→#716 gap. `frei` (lock-less) repos are excluded from re-derivation to avoid board noise; their prior rows, and the prior rows of any repo `enumerateCandidates` did not surface, are preserved unchanged via the idempotent merge — never dropped.
+
+`sweepBoard` internally calls `mirrorBoard`, which re-reads Session Config, resolves the host-local vault-dir, and **silently no-ops** (returning `{ action: 'skipped-vault-disabled' }`) when `vault-integration.enabled` is not `true`, the vault-dir is absent, the vault resolves outside `$HOME`, or the config is unreadable. The Bash gate above is the fast-path skip; this internal guard is the defense-in-depth backstop — both agree on the same condition.
+
+### Safety invariants
+
+- **Generator-marked + idempotent.** The board carries the `_generator: session-orchestrator-active-sessions@1` frontmatter sentinel; repeated writes that produce identical content are no-ops, so re-running this phase never churns the file.
+- **Host-local + git-ignorable.** The board lives under the operator's vault tree (under `$HOME`), never inside any repo — it is never committed.
+- **NEVER touches the human-authored `_overview.md`.** The writer hard-refuses any path whose basename is `_overview.md` (returns `{ action: 'skipped-handwritten' }`), and only ever overwrites files it owns (frontmatter `_generator` matches the marker). The handwritten overview is structurally safe.
+
+### Non-blocking behavior
+
+This is **best-effort**, exactly like the Phase 4 banners: a board-write failure (I/O error, thrown exception, malformed lease, or a failed host-wide enumeration) MUST NOT halt session-start. `sweepBoard` already degrades internally — if `enumerateCandidates` throws for any reason, it falls back to the pre-#716 single-repo write (`mirrorBoard({ repoRoot, explicitStatus: 'in-progress' })`) so the board write still happens. On top of that internal fallback, the coordinator MUST STILL wrap the `sweepBoard` call so any remaining error is swallowed and logged as a single WARN line, then continue to Phase 2. Session-start is never blocked by a vault-board failure.
+

package/skills/session-start/references/phase-2-7-portfolio-snapshot.md

@@ -0,0 +1,75 @@
+# Phase 2.7: GitLab Portfolio Snapshot (#41)
+
+> Sub-file of the session-start skill (#1157 — agentskills.io: SKILL.md core < 500 lines, procedure in `references/`). Extracted VERBATIM from `skills/session-start/SKILL.md`; `SKILL.md` keeps a one-line stub naming this phase and its gate condition.
+
+## Phase 2.7: GitLab Portfolio Snapshot (#41)
+
+> Skip this phase if `gitlab-portfolio.enabled` is not `true` in Session Config (default: `false`). Also skip silently when `vault-integration.enabled` is `false` or `vault-integration.vault-dir` is absent.
+
+When active, this phase surfaces a compact portfolio health banner at session-start without writing any file. It runs in **dry-run mode only** — the full write path is reserved for the `/portfolio` command.
+
+### Config check
+
+```bash
+PORTFOLIO_ENABLED=$(echo "$CONFIG" | jq -r '."gitlab-portfolio".enabled // false')
+VAULT_ENABLED=$(echo "$CONFIG" | jq -r '."vault-integration".enabled // false')
+VAULT_DIR=$(echo "$CONFIG" | jq -r '."vault-integration"."vault-dir" // empty')
+PORTFOLIO_MODE=$(echo "$CONFIG" | jq -r '."gitlab-portfolio".mode // "warn"')
+
+if [ "$PORTFOLIO_ENABLED" != "true" ] || [ "$VAULT_ENABLED" != "true" ] || [ -z "$VAULT_DIR" ]; then
+  exit 0  # silent no-op
+fi
+if [ "$PORTFOLIO_MODE" = "off" ]; then
+  exit 0  # silent no-op
+fi
+```
+
+### Dispatch
+
+Invoke `scripts/lib/gitlab-portfolio/cli.mjs` in dry-run mode (same orchestrator used by `/portfolio`):
+
+```bash
+node scripts/lib/gitlab-portfolio/cli.mjs \
+  --vault-dir "$VAULT_DIR" \
+  --dry-run \
+  --session-start-snapshot   # instructs cli.mjs to emit the compact JSON summary for banner rendering
+```
+
+The CLI emits a single-line JSON to stdout:
+
+```json
+{ "repos": 16, "openIssues": 42, "critical": 3, "stale": 5, "lastRefresh": "2026-05-16T08:00:00Z" }
+```
+
+### Banner rendering
+
+Parse the JSON and render the banner into the Session Overview:
+
+```
+📊 Portfolio: 16 repos · 42 open issues · 3 critical · 5 stale (>30d)
+    Last refresh: 2026-05-16 08:00 UTC
+    Run /portfolio to refresh.
+```
+
+### Failure behavior
+
+Governed by the `mode` field from `gitlab-portfolio:` config:
+
+- `warn` (default): if the CLI exits non-zero or emits invalid JSON, append `⚠ partial (<X>/<N> repos failed)` to the banner and continue session-start normally. Do NOT halt.
+- `strict`: if the CLI fails, emit a single-line banner `❌ portfolio snapshot failed — run /portfolio for details` into the Session Overview. Do NOT halt session-start — session-start must never be blocked by portfolio failures.
+- `off`: silent no-op (already handled by the config check above).
+
+### Performance budget
+
+Must complete within **8 seconds** for portfolios of ≤16 repos (matches the D3 timeout used by vault-staleness and CI-status probes). If the CLI has not exited after 8 seconds, terminate it, skip banner rendering, and emit a single WARN line to `.orchestrator/metrics/sweep.log`:
+
+```json
+{"timestamp":"<ISO>","event":"portfolio-snapshot-timeout","detail":{"timeout_ms":8000}}
+```
+
+Proceed to Phase 3 without blocking.
+
+### Cross-reference
+
+See `commands/portfolio.md` for the `/portfolio` command (full write path, `--dry-run`, `--repo` single-repo testing).
+