session-orchestrator 3.16.0

package/docs/vault-docs-architecture.md

@@ -0,0 +1,297 @@
+# Vault & Docs Architecture — Umbrella Narrative
+
+**Audience:** Plugin contributors (Dev). New contributors who need to understand
+how the four documentation skills, one orchestrator skill, one agent, and two
+discovery probes fit together — what fires when, who owns which file, and how
+to recover when something breaks.
+
+**Status:** Living document. Tracks Epic #229 (Vault & Docs Orchestration).
+
+---
+
+## 1. Purpose
+
+The session-orchestrator plugin treats documentation as a first-class side
+effect of every session, not a manual afterthought. Three problems motivate
+the layer:
+
+- **Cross-session memory loss.** A session ends, the chat closes, the next
+  session starts cold. Without a structured place to land decisions, status
+  changes, and learnings, every session re-discovers context. The Meta-Vault
+  (`~/Projects/vault`) is that place. Source: "Vault & Docs Orchestration" (#229; archived in the private Meta-Vault)
+  Section 1 ("Why" — 14 active projects, daily multi-session workflow).
+- **Audience-specific documentation rotting in parallel.** READMEs,
+  `CLAUDE.md`, and Vault narratives drift independently because nothing
+  reminds the session to update them in lock-step with the diff. Source:
+  "Vault & Docs Orchestration" (#229; archived in the private Meta-Vault) Section 1 (no
+  Docs-Planning step in session-start; doku only touched in session-end Phase 3.1).
+- **Operational telemetry without a home.** Wave outcomes, learnings, and
+  session metrics are JSONL on disk; humans need them as Markdown notes
+  cross-linked into the Vault graph. Source: `skills/vault-mirror/SKILL.md`
+  ("Purpose" — converts JSONL into vault-conformant Markdown).
+
+The architecture below ties these three concerns together with deliberate
+non-overlap: each component owns a narrow slice of the documentation surface,
+and the lifecycle hooks ensure the slices are written, validated, and
+mirrored at the right phase.
+
+---
+
+## 2. Architecture Diagram
+
+Data flow within a single `/session feature → /go → /close` cycle:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  user invokes:  /session feature  →  /go  →  /close              │
+└──────────────────────────────────────────────────────────────────┘
+                                ↓
+┌──────────────────────────────────────────────────────────────────┐
+│  session-start                                                   │
+│   Phase 2.5  docs-orchestrator (opt-in)                          │
+│     └─ audience detection → docs-tasks block in STATE.md         │
+│        Source: skills/session-start/phase-2-5-docs-planning.md   │
+└──────────────────────────────────────────────────────────────────┘
+                                ↓
+┌──────────────────────────────────────────────────────────────────┐
+│  session-plan                                                    │
+│   Step 1.5  docs-writer added to agent registry                  │
+│   Step 1.8  Docs-classified tasks → docs-writer assignment       │
+│        Source: skills/docs-orchestrator/SKILL.md (Invocation)    │
+└──────────────────────────────────────────────────────────────────┘
+                                ↓
+┌──────────────────────────────────────────────────────────────────┐
+│  wave-executor                                                   │
+│   dispatches docs-writer agent with the canonical four sources:  │
+│     diff │ git-log │ session-memory │ affected-files             │
+│        Source: agents/docs-writer.md (Inputs)                    │
+└──────────────────────────────────────────────────────────────────┘
+                                ↓
+┌──────────────────────────────────────────────────────────────────┐
+│  code/diff lands; tests run; metrics written                     │
+└──────────────────────────────────────────────────────────────────┘
+                                ↓
+┌──────────────────────────────────────────────────────────────────┐
+│  session-end                                                     │
+│   Phase 2.1  vault-sync          (frontmatter + wiki-link gate)  │
+│   Phase 2.2  claude-md-drift     (5 narrative drift checks)      │
+│   Phase 2.3  vault-staleness     (opt-in: stale projects)        │
+│   Phase 3.2  docs-verify         (per-task ok/partial/gap)       │
+│   Phase 3.7  vault-mirror        (sessions.jsonl → 50-sessions/) │
+│        Source: skills/session-end/SKILL.md (phase markers)       │
+└──────────────────────────────────────────────────────────────────┘
+                                ↓
+┌──────────────────────────────────────────────────────────────────┐
+│  Meta-Vault (~/Projects/vault)                                   │
+│   01-projects/<slug>/  ← context.md / decisions.md / people.md   │
+│                          (docs-writer, Vault audience)           │
+│   01-projects/<slug>/  ← _overview.md (vault-mirror, no humans)  │
+│   03-daily/YYYY-MM-DD.md  (daily skill, idempotent)              │
+│   40-learnings/<slug>.md  (vault-mirror, evolve hook)            │
+│   50-sessions/<id>.md     (vault-mirror, session-end Phase 3.7)  │
+└──────────────────────────────────────────────────────────────────┘
+                                ↓
+┌──────────────────────────────────────────────────────────────────┐
+│  /discovery vault — on-demand staleness probes                   │
+│     vault-staleness.mjs + vault-narrative-staleness.mjs          │
+│        Source: skills/discovery/probes-vault.md                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Component Table
+
+| Component | Owner | Trigger | Input | Output | Audience |
+|-----------|-------|---------|-------|--------|----------|
+| `vault-sync` | `skills/vault-sync/SKILL.md` | session-end Phase 2.1 (hard gate) | `VAULT_DIR/**/*.md` frontmatter + wiki-links | JSON report (`status`, `errors`, `warnings`) on stdout, exit code 0/1/2 | Dev (validation) |
+| `claude-md-drift-check` | `skills/claude-md-drift-check/SKILL.md` | session-end Phase 2.2 (opt-in gate) | `CLAUDE.md`, `_meta/**/*.md` | JSON report with 5 named checks (path-resolver, project-count-sync, issue-reference-freshness, session-file-existence, command-count) | Dev (validation) |
+| `vault-staleness` probes | `skills/discovery/probes-vault.md` + `skills/discovery/probes/vault-staleness.mjs` | `/discovery vault` (on-demand) and session-end Phase 2.3 (opt-in close-time gate) | `VAULT_DIR/01-projects/*/` `_overview.md` + narrative files | JSONL findings under `.orchestrator/metrics/vault-staleness.jsonl` and `vault-narrative-staleness.jsonl` | Vault/Ops (telemetry) |
+| `docs-orchestrator` | `skills/docs-orchestrator/SKILL.md` | session-start Phase 2.5, session-plan Step 1.5/1.8, session-end Phase 3.2 (all gated on `enabled: true`) | Session scope + Session Config audience list | `docs-tasks` block in STATE.md (write side); `### Documentation Coverage` block in final report (verify side) | All three (User / Dev / Vault) |
+| `docs-writer` agent | `agents/docs-writer.md` | Dispatched by `wave-executor` for each `Docs`-classified task | `diff`, `git-log`, `session-memory`, `affected-files` | Audience-targeted Markdown writes (Edit/Write); `[docs-orchestrator] Docs task complete` report line | All three (per task) |
+| `daily` | `skills/daily/SKILL.md` | User-invocable (`/daily`), idempotent | `VAULT_DIR/03-daily/`, `templates/daily.md.tpl` | `<vault>/03-daily/YYYY-MM-DD.md` (created or no-op) | Vault/Ops (PKM anchor) |
+| `vault-mirror` | `skills/vault-mirror/SKILL.md` + `scripts/vault-mirror.mjs` | session-end Phase 3.7 (sessions); evolve Phase 3.5 (learnings) | `.orchestrator/metrics/sessions.jsonl`, `.orchestrator/metrics/learnings.jsonl` | `<vault>/50-sessions/<id>.md`, `<vault>/40-learnings/<slug>.md` (`_generator` marker `session-orchestrator-vault-mirror@1`) | Vault/Ops (telemetry → Markdown) |
+| `vault-backfill` CLI | `scripts/vault-backfill.mjs` | Manual, also surfaced via `/plan retro vault-backfill` sub-mode | `vault-integration.gitlab-groups` config + GitLab API | `.vault.yaml` per repo + Vault stub directories | Vault/Ops (one-shot migration) |
+
+---
+
+## 4. Audience Model
+
+Three audiences, three documentation surfaces. The split is enforced by
+`skills/docs-orchestrator/audience-mapping.md` (Audiences & File Patterns
+table), which is the **single source of truth** for which files belong to
+which audience. Never inline this table elsewhere — always cross-link.
+
+- **User** — external/internal users of the repo. Targets: `README.md`,
+  `docs/user/**/*.md`, `docs/getting-started.md`, `examples/**/*.md`. Source:
+  `skills/docs-orchestrator/audience-mapping.md` § Audiences & File Patterns.
+- **Dev** — contributors to the repo, including future Claude sessions.
+  Targets: `CLAUDE.md`, `docs/dev/**/*.md`, `docs/adr/**/*.md`. Source: same.
+- **Vault/Ops** — strategic continuity across sessions. Targets:
+  `<vault>/01-projects/<slug>/context.md`, `decisions.md`, `people.md`.
+  Source: same.
+
+The Session Config field `docs-orchestrator.audiences` accepts any subset of
+`[user, dev, vault]`; narrowing it (e.g., `[user, dev]` on a project without a
+Vault) suppresses Vault-targeted docs without disabling the orchestrator
+entirely. Source: `docs/session-config-reference.md` § Docs Orchestrator.
+
+---
+
+## 5. Source-Cited Content Rule
+
+The `docs-writer` agent operates under a **hallucination ban**: every
+substantive paragraph must trace to one of the canonical four sources, or
+carry an inline `<!-- REVIEW: source needed -->` marker. The four sources are
+defined once and reused everywhere:
+
+1. **diff** — `git diff $SESSION_START_REF..HEAD`
+2. **git-log** — `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"`
+3. **session-memory** — `~/.claude/projects/<project>/memory/session-*.md` and
+   `.orchestrator/` outputs
+4. **affected-files** — files in the wave-scope `allowedPaths` block
+
+Source: `agents/docs-writer.md` § Inputs / Source Citation Rules and
+`skills/docs-orchestrator/SKILL.md` Phase 4 (Source Grounding).
+
+The `<!-- REVIEW: source needed -->` marker is **load-bearing**: it signals
+to the human reviewer that a section needs verification before the next
+release. The agent is explicitly forbidden from removing the marker to make
+output appear cleaner. Source: `skills/docs-orchestrator/SKILL.md` Phase 5
+("Sourceless content").
+
+**Hard guard in Phase 4:** if ALL four source blocks are empty or absent in
+the dispatched task prompt, the docs-writer aborts rather than producing
+silent REVIEW-marker-only output. Source:
+`skills/docs-orchestrator/SKILL.md` Phase 4 step 1.
+
+---
+
+## 6. Non-Overlap Discipline
+
+Three forbidden cross-writes are enforced by the architecture, not just by
+convention:
+
+- **`<vault>/01-projects/*/_overview.md` is owned by `vault-mirror`.** The
+  file is regenerated from JSONL metrics on every session-end Phase 3.7. A
+  second writer would corrupt the metrics-derived content or introduce human
+  prose that vault-mirror's next run overwrites silently. Source:
+  `skills/docs-orchestrator/audience-mapping.md` § Non-Overlap (vault-mirror
+  row) and `skills/vault-mirror/SKILL.md` § Idempotency (the `_generator`
+  marker `session-orchestrator-vault-mirror@1` is the discriminator).
+- **`<vault>/03-daily/YYYY-MM-DD.md` is owned by `daily`.** Idempotent by
+  design — re-running `/daily` opens the existing note, never overwrites.
+  Source: `skills/daily/SKILL.md` § Idempotency Guarantee. A second writer
+  would corrupt the day's scratch notes. Source:
+  `skills/docs-orchestrator/audience-mapping.md` § Non-Overlap (daily row).
+- **`CLAUDE.md` may be remediated by `docs-writer` (Dev audience), but
+  `claude-md-drift-check` only diagnoses it.** The two skills must not run
+  on `CLAUDE.md` in parallel within the same wave. Source:
+  `skills/docs-orchestrator/audience-mapping.md` § Non-Overlap
+  (claude-md-drift-check row).
+
+The forbidden patterns are checked in `skills/docs-orchestrator/SKILL.md`
+Phase 3 with an abort-on-match guard before any write occurs.
+
+---
+
+## 7. Lifecycle
+
+Concrete answer to "when does each component fire":
+
+| Phase | Skill / Probe | Gating |
+|-------|---------------|--------|
+| `/session` start, Phase 2.5 | `docs-orchestrator` audience detection | `docs-orchestrator.enabled: true` |
+| `/session` start, Phase 4.5 | resource-health probe | always (env-aware) |
+| session-plan Step 1.5/1.8 | `docs-writer` registered + Docs role classified | `docs-orchestrator.enabled: true` |
+| `/go` waves | `docs-writer` agent dispatched per Docs task | task present in plan |
+| `/close` Phase 2.1 | `vault-sync` validator | `vault-sync.enabled: true` (hard gate by mode) |
+| `/close` Phase 2.2 | `claude-md-drift-check` | `drift-check.enabled: true` |
+| `/close` Phase 2.3 | `vault-staleness` + `vault-narrative-staleness` probes | `vault-staleness.enabled: true` |
+| `/close` Phase 3.2 | `docs-orchestrator` verification | `docs-orchestrator.enabled: true` AND `docs-tasks` block present |
+| `/close` Phase 3.7 | `vault-mirror` (sessions) | `vault-integration.enabled: true` AND `mode != off` |
+| evolve Phase 3.5 | `vault-mirror` (learnings) | same as above |
+| `/discovery vault` | `vault-staleness` probes (on-demand) | `.vault.yaml` present OR `vault-integration.enabled: true` |
+| `/daily` | `daily` skill | user-invocable; no Session Config gate |
+
+Sources: `skills/session-end/SKILL.md` (Phase markers), `docs/session-config-reference.md`
+(per-skill enabled-flag semantics), `skills/discovery/probes-vault.md` (probe
+activation rules).
+
+The **opt-in default** is the design contract: when no Session Config block
+is present for a given skill, that skill's hook short-circuits silently —
+zero overhead. Source: "Vault & Docs Orchestration" (#229; archived in the private Meta-Vault)
+Section 5 (Risk: "Marketplace-Kompatibilität — alle neuen Config-Felder
+opt-in mit sicherem Default → zero-impact für bestehende Plugin-User").
+
+---
+
+## 8. Failure Modes & Escape Hatches
+
+| What breaks | Symptom | Recovery |
+|-------------|---------|----------|
+| `vault-sync` finds invalid frontmatter, `mode: hard` | session-end Phase 2.1 blocks `/close` | Fix the offending file, re-run `/close`. Or temporarily set `vault-sync.mode: warn` to unblock and file an issue. Source: `skills/vault-sync/SKILL.md` § "How session-end invokes it" (exit 1 → block). |
+| `claude-md-drift-check` finds stale issue refs, `mode: hard` | Phase 2.2 blocks `/close` | Update CLAUDE.md to reflect actual state, or set `drift-check.mode: warn`. Source: `skills/claude-md-drift-check/SKILL.md` § "Session-End Phase 2.2". |
+| `vault-staleness` probe finds stale projects, `mode: strict` | Phase 2.3 blocks `/close` with interactive override | Run `/discovery vault` to triage; update narrative files, or use the AskUserQuestion override (logged to STATE.md). Source: `docs/session-config-reference.md` § Vault Staleness ("Mode behavior" table). |
+| `docs-writer` cannot find a source for a section | Section is written with `<!-- REVIEW: source needed -->` | Human review before next release; do NOT remove the marker. Source: `skills/docs-orchestrator/SKILL.md` Phase 5. |
+| `docs-writer` is dispatched with **all four** source blocks empty | Agent aborts with `docs-writer: no grounding sources available` | Coordinator surfaces the failure; fix the task spec to include at least one source. Source: `skills/docs-orchestrator/SKILL.md` Phase 4 step 1 (Hard guard). |
+| `vault-mirror` finds a hand-written file at the target path | `skipped-handwritten` action emitted; file untouched | Intentional safety: human files are never overwritten. If the file should be regenerated, delete it manually. Source: `skills/vault-mirror/SKILL.md` § Idempotency item 4. |
+| Session Config block absent | All hooks skip silently | Default behavior. To enable, add the relevant block per `docs/session-config-reference.md`. |
+| `docs-orchestrator.mode: off` | Phase 2.5 / 3.2 read config but skip all execution | Lighter than `enabled: false` (config still parsed). Useful during onboarding. Source: `skills/docs-orchestrator/SKILL.md` § "Session Config Reference". |
+| Repo lacks `.vault.yaml` but `vault-integration.enabled: true` | vault-sync warns "kein .vault.yaml gefunden" but does not block | Run `scripts/vault-backfill.mjs` (dry-run default) to generate. Source: "Vault & Docs Orchestration" (#229; archived in the private Meta-Vault) § Edge Cases. |
+
+---
+
+## 9. Future Direction
+
+**Epic #229 (Vault & Docs Orchestration) is in-progress.** Closed slices to
+date (per CLAUDE.md "Current State"):
+
+- docs-orchestrator skill + docs-writer agent (foundation #230, hooks #233 /
+  #234 / #235, config #236).
+- vault-staleness probes + Phase 2.3 integration (#232, #242).
+- vault-backfill CLI + `/plan retro vault-backfill` sub-mode (#241).
+- vault-mirror auto-commit phase via `--session-id` (GH#31).
+
+Source: `CLAUDE.md` § "Current State" and "Vault & Docs Orchestration" (#229; archived in the private Meta-Vault)
+§ Sub-Epic A/B/C tracking lists.
+
+**Open work:** Sub-Epic B (projects-baseline `setup-project.sh` Vault auto-
+provisioning) lives in a sibling repo and ships independently. CLAUDE.md
+narrative-sync remediation across consumer repos remains a recurring
+maintenance load. Source: "Vault & Docs Orchestration" (#229; archived in the private Meta-Vault)
+§ Sub-Epic B.
+
+**Explicit non-goals** — these are not on the roadmap:
+
+- **Team-Vault sharing.** Today single-user-local under
+  `~/Projects/vault`. Team sharing requires its own infra (sync, permissions,
+  conflict resolution) and is a separate epic.
+- **Two-way sync (Vault → Repo).** Today one-way (Repo → Vault via
+  `.vault.yaml` + Clank). Reversal would break the ownership model.
+- **LLM-autogenerated User-Docs without source.** docs-writer writes only
+  from the canonical four sources. Sourceless sections get
+  `<!-- REVIEW: source needed -->`, never invented content.
+- **Full ADR autogeneration.** ADRs remain human-authored decisions;
+  docs-writer may suggest skeletons but never commits autonomously.
+- **Migration of historical 50-sessions / 40-learnings entries.** vault-mirror
+  is forward-compatible only.
+
+Source: "Vault & Docs Orchestration" (#229; archived in the private Meta-Vault) § Out-of-Scope.
+
+---
+
+## See Also
+
+- `docs/session-config-reference.md` — authoritative config reference for all
+  fields mentioned above (Vault Sync, CLAUDE.md Drift Check, Vault
+  Integration, Vault Staleness, Docs Orchestrator).
+- "Vault & Docs Orchestration" (#229; archived in the private Meta-Vault) — PRD for the umbrella
+  epic, including layering diagram and ownership table this document
+  derives from.
+- `skills/docs-orchestrator/audience-mapping.md` — single source of truth
+  for audience → file-pattern mapping and non-overlap rules.
+- `agents/docs-writer.md` — the sole agent permitted to write audience-
+  targeted documentation within a session.
+- `CLAUDE.md` § "Current State" — running ledger of which umbrella-epic
+  slices have shipped.

package/hooks/_lib/lock-bootstrap.mjs

@@ -0,0 +1,272 @@
+/**
+ * lock-bootstrap.mjs — mechanical session.lock writer for the SessionStart hook.
+ *
+ * Epic #583 P3 closes the D1 wiring gap: until P3, `acquire()` from
+ * scripts/lib/session-lock.mjs had no mechanical caller in the
+ * /session or /deep flow (only the autopilot-multi pipeline called it).
+ * The lock was written only when the coordinator-LLM happened to invoke
+ * Phase 1.2 prose — silent skip → discoverActiveSessions() returns empty →
+ * parallel-session AUQ never fires.
+ *
+ * This helper is invoked from hooks/on-session-start.mjs once per session.
+ * It is intentionally best-effort: every failure path swallows its error
+ * so the hook stays non-blocking (the hook's contract is informational-only;
+ * a write failure here must NEVER break session-start).
+ *
+ * Schema v2 (Epic #583 D4 #587):
+ *   {
+ *     session_id:           string,  // semantic OR UUID — whatever resolveSessionId returned
+ *     semantic_session_id:  string,  // ALWAYS the semantic form (closes D4)
+ *     started_at:           ISO,
+ *     last_heartbeat:       ISO,     // basis for liveness; replaces PID-liveness checks
+ *     mode:                 string,  // "deep"|"feature"|"housekeeping"|"session"|...
+ *     pid:                  number,  // forensics only — DO NOT use for liveness (D2/D4)
+ *     host:                 string,
+ *     ttl_hours:            number,
+ *   }
+ *
+ * The current scripts/lib/session-lock.mjs (pre-I3) writes the v1 shape
+ * (no last_heartbeat, no semantic_session_id). This helper layers v2 fields
+ * on top via an atomic tmp+rename overwrite — when I3 ships its v2 schema,
+ * this helper's overlay becomes a no-op (the field is already there) and
+ * everything continues to work.
+ *
+ * @module hooks/_lib/lock-bootstrap
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomicSync } from '../../scripts/lib/io.mjs';
+
+/**
+ * Bootstrap the session.lock for this hook invocation.
+ *
+ * Best-effort: every internal failure is swallowed, the helper returns null
+ * instead of throwing. Callers (the SessionStart hook) wrap this in a
+ * try/catch anyway, but the helper itself never propagates.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot — absolute path to the repository root.
+ * @param {string} opts.sessionId — the resolved session id (semantic OR UUID).
+ * @param {string} [opts.semanticSessionId] — the semantic form, ALWAYS surfaced
+ *   even when sessionId is a UUID (closes D4 issue #587). When omitted, the
+ *   field is populated by mirroring sessionId.
+ * @param {string} opts.mode — session mode (e.g. "deep", "feature").
+ * @param {number} [opts.ttlHours=4] — lock TTL in hours.
+ * @param {Function} [opts._acquireImpl] — DI for tests (defaults to importing acquire from session-lock.mjs).
+ * @param {Function} [opts._forceAcquireImpl] — DI for tests (defaults to importing forceAcquire from session-lock.mjs).
+ * @param {Function} [opts._emitEventImpl] — DI for tests (defaults to importing emitEvent from events.mjs).
+ * @returns {Promise<object|null>} the enriched v2 lock body on success, null on any failure.
+ */
+export async function bootstrapLock({
+  repoRoot,
+  sessionId,
+  semanticSessionId,
+  mode,
+  ttlHours = 4,
+  _acquireImpl,
+  _forceAcquireImpl,
+  _emitEventImpl,
+} = {}) {
+  // Sanity-check required inputs. Anything missing → bail silently.
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null;
+  if (typeof mode !== 'string' || mode.length === 0) return null;
+
+  // Resolve DI shims at call time so test mocks can replace the imports.
+  let acquireFn = _acquireImpl;
+  let forceAcquireFn = _forceAcquireImpl;
+  if (!acquireFn || !forceAcquireFn) {
+    try {
+      const lockMod = await import('../../scripts/lib/session-lock.mjs');
+      acquireFn = acquireFn ?? lockMod.acquire;
+      forceAcquireFn = forceAcquireFn ?? lockMod.forceAcquire;
+    } catch {
+      return null;
+    }
+  }
+
+  // Step 1: try to acquire. If a fresh acquire succeeds, we are done.
+  // If a stale-PID-dead/-alive lock exists, force-overwrite it (the prior
+  // session has died; we own the worktree now).
+  // If the existing lock has the same sessionId, force-overwrite so the
+  // last_heartbeat gets refreshed.
+  let acquireResult;
+  try {
+    // quiet: true suppresses the unknown-mode stderr WARN in acquire() (#592 MED-2).
+    // The hook is informational-only and tests assert stderr is empty.
+    acquireResult = acquireFn({ sessionId, mode, ttlHours, repoRoot, quiet: true });
+  } catch {
+    return null;
+  }
+
+  if (!acquireResult || typeof acquireResult !== 'object') return null;
+
+  const shouldForce =
+    acquireResult.ok !== true && (
+      acquireResult.reason === 'stale-pid-dead' ||
+      acquireResult.reason === 'stale-pid-alive' ||
+      (acquireResult.reason === 'active' &&
+        acquireResult.existingLock &&
+        acquireResult.existingLock.session_id === sessionId)
+    );
+
+  if (!acquireResult.ok && shouldForce) {
+    try {
+      acquireResult = forceAcquireFn({ sessionId, mode, ttlHours, repoRoot });
+    } catch {
+      return null;
+    }
+  }
+
+  // Any other non-ok reason (parallel-conflict, fs-error, other-session-active)
+  // → bail without enriching. The hook stays non-blocking.
+  //
+  // Issue #590 Item 1: before bailing, record a durable conflict signal for the
+  // FOREIGN-active case — reason 'active' where the existing lock belongs to a
+  // DIFFERENT session than ours (the same-session case was already force-refreshed
+  // above via shouldForce). Without this, the operator gets no signal that a
+  // parallel session owns the worktree. We persist the foreign session_id into
+  // current-session.json for forensics/operator visibility. Best-effort: any FS
+  // failure is swallowed and the bail proceeds. The return contract is unchanged —
+  // bootstrapLock STILL returns null on this path.
+  if (!acquireResult || acquireResult.ok !== true) {
+    if (
+      acquireResult &&
+      acquireResult.reason === 'active' &&
+      acquireResult.existingLock &&
+      typeof acquireResult.existingLock.session_id === 'string' &&
+      acquireResult.existingLock.session_id.length > 0 &&
+      acquireResult.existingLock.session_id !== sessionId
+    ) {
+      recordConflictSignal(repoRoot, acquireResult.existingLock.session_id);
+    }
+    return null;
+  }
+
+  // Step 2: enrich the lock with v2 fields (last_heartbeat + semantic_session_id).
+  // We re-read the file fresh (acquire() just wrote it) and overlay the new
+  // fields, then atomically tmp+rename. When I3 lands and acquire() writes the
+  // v2 shape natively, this overlay becomes idempotent (already-present fields
+  // get overwritten with identical values).
+  const lockFile = path.join(repoRoot, '.orchestrator', 'session.lock');
+  let baseLock;
+  try {
+    const raw = fs.readFileSync(lockFile, 'utf8');
+    baseLock = JSON.parse(raw);
+    if (typeof baseLock !== 'object' || baseLock === null) return null;
+  } catch {
+    // Lock vanished between write and read — best-effort, return null.
+    return null;
+  }
+
+  const startedAt = typeof baseLock.started_at === 'string'
+    ? baseLock.started_at
+    : new Date().toISOString();
+
+  const enriched = {
+    ...baseLock,
+    // last_heartbeat is the basis for liveness — set to started_at on bootstrap
+    // so an immediate liveness check (< ttl_hours from now) succeeds.
+    last_heartbeat: startedAt,
+    // semantic_session_id is ALWAYS the semantic form, even when session_id is
+    // a UUID-v4 (closes D4 #587). Fallback to mirroring session_id if no
+    // semantic was provided.
+    semantic_session_id:
+      typeof semanticSessionId === 'string' && semanticSessionId.length > 0
+        ? semanticSessionId
+        : (typeof baseLock.session_id === 'string' ? baseLock.session_id : sessionId),
+  };
+
+  {
+    const w = writeJsonAtomicSync(lockFile, enriched, { tmpPrefix: '.session.lock.boot.tmp' });
+    if (!w.ok) {
+      // Failed to overwrite — base lock is still on disk, so we degrade
+      // gracefully. Return null so the caller logs no spurious success.
+      return null;
+    }
+  }
+
+  // Step 3: best-effort observability breadcrumb. Failures are swallowed
+  // so a missing events module never breaks the hook.
+  try {
+    let emitFn = _emitEventImpl;
+    if (!emitFn) {
+      const eventsMod = await import('../../scripts/lib/events.mjs');
+      emitFn = eventsMod.emitEvent;
+    }
+    if (typeof emitFn === 'function') {
+      await emitFn('orchestrator.session.lock.acquired', {
+        session_id: enriched.session_id,
+        semantic_session_id: enriched.semantic_session_id,
+        mode: enriched.mode,
+        pid: enriched.pid,
+        host: enriched.host,
+        ttl_hours: enriched.ttl_hours,
+      });
+    }
+  } catch { /* observability is best-effort */ }
+
+  return enriched;
+}
+
+/**
+ * Record a foreign-session conflict signal into current-session.json (Issue #590
+ * Item 1). When bootstrapLock detects that a DIFFERENT session already owns the
+ * worktree lock, it persists the colliding session_id (plus a forensic timestamp)
+ * so the operator and downstream skills have a durable record of the collision —
+ * the previous behaviour bailed silently with no signal whatsoever.
+ *
+ * Uses an atomic read-modify-write (read → merge → tmp+rename) that PRESERVES
+ * every existing field (`session_id`, `semantic_session_id`, `pid`, `source`,
+ * `timestamp`, and any concurrently-appended `cwd_changes` / `corrective_context`
+ * / `last_batch` arrays). It never overwrites the whole file — it overlays only
+ * the two conflict fields on top of whatever is currently on disk.
+ *
+ * Best-effort: any FS error (missing file, parse failure, write race) is swallowed
+ * so the SessionStart hook stays non-blocking. The conflict signal is a forensic
+ * breadcrumb, not a correctness requirement.
+ *
+ * Lost-update window (Issue #596, deep-6 R2 MED — ACCEPTED): the read→merge→write
+ * is not lock-serialised. recordConflictSignal's only caller is the SessionStart hook
+ * (on-session-start.mjs), which runs it early — well before the slow detectPeers phase.
+ * That hook is async:true, so strict ordering vs the corrective_context/cwd_changes/
+ * last_batch writers (PostToolUse/CwdChanged/PostToolBatch) is not MECHANICALLY
+ * guaranteed; but in practice recordConflictSignal completes in a few ms, long before
+ * any tool-triggered hook can fire. Crucially, the conflict_* fields have zero readers
+ * (forensic-only), so even a lost update is harmless. The real anti-stomp guard is
+ * state.lock/PSA-005, not this advisory file.
+ *
+ * @param {string} repoRoot — absolute path to the repository root.
+ * @param {string} foreignSessionId — the session_id of the lock holder we collided with.
+ */
+function recordConflictSignal(repoRoot, foreignSessionId) {
+  try {
+    const sessionFile = path.join(repoRoot, '.orchestrator', 'current-session.json');
+
+    // Read-modify-write: start from whatever is on disk (or {} when absent /
+    // unparseable) so concurrently-written fields survive the overlay.
+    let current = {};
+    try {
+      const raw = fs.readFileSync(sessionFile, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        current = parsed;
+      }
+    } catch {
+      // File absent or unparseable — start from an empty object. The conflict
+      // signal is still worth recording even if the session file was not yet written.
+    }
+
+    const merged = {
+      ...current,
+      conflict_with_session_id: foreignSessionId,
+      conflict_detected_at: new Date().toISOString(),
+    };
+
+    // Best-effort atomic write — return value swallowed intentionally.
+    writeJsonAtomicSync(sessionFile, merged, { tmpPrefix: '.current-session.conflict.tmp' });
+  } catch {
+    // Best-effort — any failure is swallowed; the caller still returns null.
+  }
+}

package/hooks/_lib/lock-reconcile.mjs

@@ -0,0 +1,93 @@
+/**
+ * lock-reconcile.mjs — root-cause reconciliation fallback for the SessionEnd hook.
+ *
+ * Extracted (Issue #748) from the inline reconciliation branch that used to live
+ * in `hooks/on-session-end.mjs`'s `main()` — that branch was only reachable via
+ * a subprocess spawn in tests, so its behaviour could only be verified through
+ * events.jsonl side effects, never asserted in-process. This module is the
+ * importable, DI-testable seam; `on-session-end.mjs` now just calls it.
+ *
+ * Context (Epic #724 Wave 3 — "ended logged but lock survived"): neither the
+ * UUID nor the semantic id matched the recorded lock (a rotated harness UUID
+ * racing ahead of current-session.json's semantic bridge), but the lease is
+ * already dead. Reconcile now via the same reaper the SessionStart hook uses
+ * (Epic #724 C7), instead of leaving the orphaned lease for the next
+ * session-start to discover. Safe by construction: reapRepoLock() never
+ * touches a live lease, a cross-host lease, or a lease whose recorded PID is
+ * still alive on this host.
+ *
+ * Best-effort by design, mirroring hooks/_lib/lock-bootstrap.mjs: every
+ * internal failure is swallowed so the SessionEnd hook stays non-blocking (the
+ * hook's contract is informational-only; a reconciliation failure here must
+ * NEVER break session teardown).
+ *
+ * @module hooks/_lib/lock-reconcile
+ */
+
+import { isLockLive } from '../../scripts/lib/session-lock.mjs';
+
+/**
+ * Attempt a best-effort reconciliation of a dead, orphaned session.lock that
+ * neither ownership check (UUID nor semantic id) matched. No-op when `lock`
+ * is missing or still live (isLockLive) — mirrors the `else if (!isLockLive(lock))`
+ * guard this function replaces at the call site.
+ *
+ * Never throws. Any failure resolving the DI defaults, calling reapRepoLock,
+ * or emitting the breadcrumb event is swallowed.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot — absolute path to the repository root.
+ * @param {string|null} opts.sessionId — the ending session's id (UUID or semantic).
+ * @param {object} opts.lock — the recorded lock the caller already read via readLock().
+ * @param {Function} [opts._reapRepoLockImpl] — DI for tests (defaults to importing
+ *   reapRepoLock from scripts/lib/lock-reaper.mjs).
+ * @param {Function} [opts._emitEventImpl] — DI for tests (defaults to importing
+ *   emitEvent from scripts/lib/events.mjs).
+ * @returns {Promise<void>}
+ */
+export async function attemptLockReconciliation({
+  repoRoot,
+  sessionId,
+  lock,
+  _reapRepoLockImpl,
+  _emitEventImpl,
+} = {}) {
+  // Mirrors the caller's original `else if (!isLockLive(lock))` guard — a
+  // missing or still-live lock is never reconciled.
+  if (!lock || typeof lock !== 'object' || isLockLive(lock)) return;
+
+  // Resolve DI shims at call time so test mocks can replace the imports.
+  let reapFn = _reapRepoLockImpl;
+  if (!reapFn) {
+    try {
+      const reaperMod = await import('../../scripts/lib/lock-reaper.mjs');
+      reapFn = reaperMod.reapRepoLock;
+    } catch {
+      return;
+    }
+  }
+
+  let emitFn = _emitEventImpl;
+  if (!emitFn) {
+    try {
+      const eventsMod = await import('../../scripts/lib/events.mjs');
+      emitFn = eventsMod.emitEvent;
+    } catch {
+      return;
+    }
+  }
+
+  try {
+    const reapResult = await reapFn({
+      repoRoot,
+      currentSessionId: sessionId,
+      dryRun: false,
+      reapMode: 'auto-session-end',
+    });
+    await emitFn('orchestrator.session.lock.reconcile_attempted', {
+      session_id: sessionId,
+      action: reapResult?.action ?? 'unknown',
+      reason: reapResult?.reason ?? null,
+    });
+  } catch { /* best-effort — reconciliation must never block teardown */ }
+}