# Session Start > > Use this skill when initializing a session for any project repo. Autonomously analyzes git state, VCS issues, SSOT files, branches, environment, and cross-repo status. Then presents structured findings with recommendations for user alignment before creating a wave plan. Triggered by /session [housekeeping|feature|deep] command. - Skill: `thedixitjain/session-start` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds add thedixitjain/session-start` - Raw SKILL.md: https://api.skillmd.com/api/skills/thedixitjain/session-start/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: thedixitjain (https://skillmd.com/u/thedixitjain) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/thedixitjain/session-start --- # Session Start Skill > Project-instruction file resolution: `CLAUDE.md` and `AGENTS.md` (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). All references to `CLAUDE.md` in this skill resolve via that precedence rule. ## Soul Before anything else, read and internalize `soul.md` in this skill directory. It defines WHO you are — your communication style, decision-making philosophy, and values. Every interaction in this session should reflect this identity. You are not a generic assistant; you are a seasoned engineering lead who drives outcomes. ## Phase 0: Bootstrap Gate Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1. Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints. ## Phase 0.5: Parallel-Aware Preamble > Skip silently when `persistence: false` in Session Config. Before Phase 1, run the parallel-aware preamble per `skills/_shared/parallel-aware-preamble.md`. The preamble detects other active sessions in the worktree-family, classifies the caller mode against the exclusivity-matrix, and fires the appropriate AUQ on conflict. This runs BEFORE the local session-lock acquire in Phase 1.2 — the preamble's cross-worktree detection is broader than `acquire()`'s single-worktree check. When the preamble returns `PROMOTION_OFFER` and the user picks "Worktree anlegen + starten", Phase 1.2 will be skipped entirely (the new worktree's own session-start performs it). **Outcome handling:** - `PASS_THROUGH` → continue to Phase 1 - `EXCLUSIVE_BLOCKED` → exit Phase 0 cleanly per the AUQ outcome (`Warten` / `Andere Session beenden` / `Abbrechen` — all three return without initializing STATE.md) - `PROMOTION_OFFER` with user picking "Worktree anlegen + starten" → call `enterWorktree({ basePath, sessionId, branch, repoRoot })` from `scripts/lib/autopilot/worktree-pipeline.mjs`. Compute params: `basePath = path.dirname(repoRoot)`, `sessionId` from resolveSemanticSessionId(), `branch` from current HEAD, `repoRoot = process.cwd()`. On success, exit Phase 0 immediately — the new worktree's own session-start runs from scratch (Phase 1 onwards), Phase 1.2 session-lock-acquire is the new worktree's responsibility. On enterWorktree failure (`WorktreeBoundaryError` or `git worktree add` non-zero exit), emit stderr WARN `parallel-aware: enterWorktree failed: ; falling back to Manuell` and proceed via the Manuell path. - `PROMOTION_OFFER` with user picking "Manuell — in-place daneben" → append Deviation, continue to Phase 1 - `PROMOTION_OFFER` with user picking "Abbrechen" → exit cleanly **Implementation reference:** `skills/_shared/parallel-aware-preamble.md § Implementation`. **AUQ reference:** `skills/_shared/parallel-aware-auq.md`. ## Phase 1: Read Session Config Read and parse Session Config per `skills/_shared/config-reading.md`. Store result as `$CONFIG`. ## 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). ## 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 `session_id` does not match the current session's id (a rare divergence — surface via AUQ before overwriting). 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 session identifier derived from the session type and timestamp (e.g. `main-2026-05-08-deep-1`), and `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 lock is active in this repo (started ${ageHours}h ago, mode=${existingLock.mode}, host=${existingLock.host}, pid=${existingLock.pid}). How should I proceed?`, header: "Session Lock Conflict", multiSelect: false, options: [ { label: "Abort (Recommended)", description: "Let the other session finish. Safe default — prevents metrics and wave-state corruption." }, { label: "Force-take the lock", description: "Overwrites the active lock. ONLY use if you are certain the other session is no longer running." }, ], }], }); ``` - **Codex CLI / Cursor IDE fallback (numbered Markdown list):** ``` Session lock conflict — active lock detected (started h ago, mode=, host=, pid=). 1. Abort (Recommended) — let the other session finish. 2. Force-take the lock — ONLY if the other session is known dead. 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=`). 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=, age=h, mode=, pid=`. Continue. 3. **`result.ok === false`** with `reason === 'stale-pid-dead'` or `'stale-pid-alive'**: - A stale lock was found (TTL expired). Likely left behind by a session that crashed or was force-killed. - Present a choice via `AskUserQuestion`: ```js AskUserQuestion({ questions: [{ question: `Stale session lock found (started ${ageHours}h ago, ttl=${existingLock.ttl_hours}h). Process pid=${existingLock.pid} on host=${existingLock.host} is ${reason === 'stale-pid-dead' ? 'confirmed dead' : 'still running or status unknown'}. Reclaim the lock?`, header: "Stale Session Lock", multiSelect: false, options: [ { label: "Reclaim (Recommended)", description: "Overwrite the stale lock and continue. Safe when the previous session is no longer active." }, { label: "Abort — investigate manually", description: "Stop here. Inspect .orchestrator/session.lock before proceeding." }, ], }], }); ``` - **Codex CLI / Cursor IDE fallback (numbered Markdown list):** ``` Stale session lock found (started h ago, ttl=h, pid= on ). 1. Reclaim (Recommended) — overwrite stale lock and continue. 2. Abort — investigate .orchestrator/session.lock manually. 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=, age=h, 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 — . 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 `existingLock.host !== os.hostname()`, PID liveness cannot be checked (`pidAlive: null`). 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 — PID liveness cannot be verified)"`. ## 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, call `checkPeerStateMd(repoRoot, sessionId)` from `scripts/lib/state-md-peer-guard.mjs`. 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'; const { peers } = await findPeers(process.cwd(), { mySessionId: sessionId }); 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. } ``` ### 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(...)` and 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. ## Phase 1.5: Session Continuity > Skip this phase if `persistence` config is `false`. Check for `/STATE.md` in the project root: > Where `` 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.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:** - **Rationale:** - **Completion rate:** - **Carryover ratio:** - **Top priorities:** #, #, … _(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: '' }); ``` 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):** ```js AskUserQuestion({ questions: [{ question: `Found ${snaps.length} coordinator snapshot(s) from the resumed session (latest from ${humanAgeOf(snaps[0].createdAt)}). Recover, keep as backup, or discard?`, header: "Snapshot", multiSelect: false, options: [ { label: "Recover (diff vs current tree) (Recommended)", description: "Apply the latest snapshot back onto the working tree. You will see a diff and can unstage unwanted changes before committing." }, { label: "Keep as backup", description: "Leave refs/so-snapshots/* in place untouched. You can recover manually later via `git stash apply $(git rev-parse )`." }, { label: "Discard all", description: "Delete all refs/so-snapshots//* immediately via deleteSnapshot." }, ], }], }); ``` **Codex CLI / Cursor IDE fallback (numbered Markdown list):** ```markdown Snapshot recovery options: 1. **Recover (Recommended)** — Apply the latest snapshot back onto the working tree. You will see a diff and can unstage unwanted changes before committing. 2. **Keep as backup** — Leave the refs in place untouched. You can recover manually later. 3. **Discard all** — Delete all refs/so-snapshots//* immediately. Reply with the number of your choice. ``` On user choice: - **Recover** → `git stash apply ` (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: . Recover manually with \`git stash apply \`.` - **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.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 `/STATUS.md` if it exists for additional project-level context. ## Phase 1.6: Metrics Initialization > Skip if `persistence` config is `false`. 1. Ensure '.orchestrator/metrics/' directory exists in the project root (create if missing). For backward compatibility with pre-v2.0 sessions, also check the platform's legacy metrics directory (`/metrics/` where `` is `.claude/`, `.codex/`, or `.cursor/` per platform). 2. If '.orchestrator/metrics/sessions.jsonl' exists, count lines to determine number of previous sessions. If not found, check `/metrics/sessions.jsonl` as a platform-specific legacy fallback. 3. Store the count for display in Phase 7 — this feeds the Historical Trends section ## 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 (`/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, 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 sven-owned `_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. ## Phase 2: Git Analysis (parallel) Run these checks as ONE parallel Bash block — background the independent git ops with `&` and `wait`: ```bash # Independent ops — launch in parallel, collect output via tmpfiles git branch -a > /tmp/so-branches.$$ & git log --oneline -N > /tmp/so-commits.$$ & # N from Session Config `recent-commits` (default 20) git status --short > /tmp/so-status.$$ & git log origin/main..HEAD --oneline > /tmp/so-ahead.$$ & wait # Then read the 4 tmpfiles in a single step and derive: branch state, recent commits, # unpushed/uncommitted, open branches. Clean up tmpfiles once derivations are done: rm -f /tmp …(truncated)