session-orchestrator 3.16.0

package/skills/_shared/monitor-patterns.md

@@ -0,0 +1,300 @@
+# Monitor Filter Patterns
+
+> Vetted Monitor-tool snippets for the recurring observation points in the
+> session-orchestrator workflow. Each snippet ships with the description
+> string, recommended timeout / persistent flag, and an explicit failure
+> coverage note (per the **silence-is-not-success** rule from
+> `.claude/rules/loop-and-monitor.md`).
+
+## Why this file exists
+
+Anthropic recommends `Monitor` over `/loop` for any stream-able event
+(https://code.claude.com/docs/en/scheduled-tasks). The Monitor tool turns
+each stdout line into a notification, avoiding poll-token cost. But a
+naïve filter that matches only the success marker reads identical to a
+crash — silent. The snippets below are calibrated to emit on **every
+terminal state**, not just the happy path.
+
+When in doubt, copy a snippet, adjust the path or repo, and arm it. Do
+not invent new filters from scratch unless you have re-derived the
+coverage check.
+
+---
+
+## Pattern 1 — GitLab pipeline + GitHub mirror sync (post-push)
+
+**When.** After `git push origin main` from `commands/close.md` Phase 6.
+Watches the GitLab pipeline through to a terminal status, then prints
+the GitHub mirror's main-branch SHA so the operator can confirm parity.
+
+**Description.** `pipeline + mirror sync after push`
+
+**timeout_ms.** `1800000` (30 min — most pipelines finish well inside)
+
+**persistent.** `false`
+
+```bash
+prev=""
+while true; do
+  s=$(glab ci status --pipeline-id LATEST --output json 2>/dev/null || echo '[]')
+  cur=$(jq -r '.[] | select(.status!="running" and .status!="pending") | "\(.name): \(.status)"' <<<"$s" 2>/dev/null | sort)
+  comm -13 <(echo "$prev") <(echo "$cur")
+  prev=$cur
+  jq -e 'all(.status=="success" or .status=="failed" or .status=="canceled" or .status=="skipped")' <<<"$s" >/dev/null 2>&1 && {
+    sha=$(gh api repos/Kanevry/session-orchestrator/commits/main --jq '.sha' 2>/dev/null || echo "(mirror unreachable)")
+    echo "GitHub mirror main: $sha"
+    break
+  }
+  sleep 30
+done
+```
+
+**Coverage.** Emits a line for each job transitioning out of `running` /
+`pending`. Terminates when **all** jobs are in a terminal state (`success`,
+`failed`, `canceled`, `skipped`). The final line prints the GitHub mirror
+SHA — silence at the end means glab JSON parsing failed (the `||` fallbacks
+prevent the whole loop from dying).
+
+**GitHub-mirror equivalent.** When the pipeline is GitHub-Actions-native (PR
+checks rather than a GitLab pipeline), use `gh pr checks <pr> --watch --fail-fast`
+as the `command` source — it streams each check transition and exits non-zero on
+the first failure, so the terminal state is never silent.
+
+---
+
+## Pattern 2 — Long-running test suite (`npm test` ≥ 2700 cases)
+
+**When.** During a deep session's Quality wave when the suite takes long
+enough that synchronous stdout is impractical. Monitor surfaces progress
+and any failure signature without re-running the suite.
+
+**Description.** `vitest progress + failure signatures`
+
+**timeout_ms.** `1200000` (20 min)
+
+**persistent.** `false`
+
+```bash
+# Pre-req: npm test 2>&1 | tee vitest.log was started in another terminal
+tail -f vitest.log | grep -E --line-buffered \
+  "Test Files.*passed|Test Files.*failed|Tests.*failed|FAIL |PASS |Traceback|Error:|AssertionError|UnhandledRejection|OOM|Killed|Aborted"
+```
+
+**Coverage.** Matches both success markers (`Test Files … passed`,
+`PASS `) and the full failure surface: vitest's own
+`FAIL ` / `Tests.*failed`, Node's `Traceback` / `AssertionError` /
+`UnhandledRejection`, and OS-level kill signatures (`OOM`, `Killed`,
+`Aborted`). A crashed worker produces at least one of the failure tokens
+within 200 ms — never silent.
+
+---
+
+## Pattern 3 — `autopilot.jsonl` live read-out
+
+**When.** Operator runs `/autopilot --headless` in terminal A and wants
+a live dashboard in terminal B without building telemetry tooling.
+
+**Description.** `autopilot iteration + kill-switch tail`
+
+**timeout_ms.** `3600000` (1 h — the 1 h ceiling this file uses; repo-internal convention, upstream documents no explicit `timeout_ms` maximum)
+
+**persistent.** `true` (run for the lifetime of the session — autopilot
+runs can take hours)
+
+```bash
+tail -f .orchestrator/metrics/autopilot.jsonl | jq -r --line-buffered '
+  select(.kind == "iteration" or .kind == "kill_switch" or .kind == "loop_end") |
+  "\(.timestamp) iter=\(.iteration // "—") mode=\(.mode // "—") status=\(.status // "—") kill=\(.kill_switch // "none")"
+'
+```
+
+**Coverage.** Emits on three event kinds: per-iteration progress,
+kill-switch firings (the ten tracked in
+`scripts/lib/autopilot/kill-switches.mjs`), and the loop-end record. A
+silent autopilot run means autopilot is not actually writing to the
+JSONL — that itself is a signal worth surfacing manually.
+
+**Detachment seam (Spike #640).** A headless autopilot run detached via
+Bash `run_in_background` (`node scripts/autopilot.mjs --headless … &`)
+is observed through the returned **task-id**, its **output-file**
+(`.../tasks/<id>.output`), and the **completion notification** — never
+through `TaskList` / `claude agents`, which lists nested *agent* sessions
+only and returns "No tasks found" for a Bash-backgrounded process even
+while the run is healthy. This JSONL tail is therefore the **primary live
+view** once a run is detached, not a supplementary one. Stop a detached
+run with `TaskStop(task_id)`, not the in-session `/tasks`/`/stop` slash
+commands.
+
+---
+
+## Pattern 4 — Vault-mirror backlog watcher (long sessions)
+
+**When.** Multi-hour deep session where vault-mirror auto-commit (GH#31)
+fires only at session-end / evolve. Surfaces drift before it accumulates.
+
+**Description.** `vault 40-learnings/50-sessions backlog`
+
+**timeout_ms.** `3600000` (1 h)
+
+**persistent.** `true`
+
+```bash
+prev=0
+while true; do
+  n=$(git -C ~/Projects/vault status --short 40-learnings/ 50-sessions/ 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$n" != "$prev" ]; then
+    echo "$(date -u +%H:%M:%SZ) vault-mirror backlog: $n files"
+    prev=$n
+  fi
+  sleep 1800
+done
+```
+
+**Coverage.** Emits **only on change** to keep the stream quiet during
+idle work. A drop to zero is also reported (e.g. when session-end runs
+mirror-commit). Silence = no drift, which is the desired idle state. The
+30-min sleep matches the `1200s+` idle-tick band from
+`.claude/rules/loop-and-monitor.md` LM-003 (idle observation-rate; under the
+1-hour subscription cache TTL there is no cache penalty here anyway).
+
+---
+
+## Pattern 5 — GitHub mirror push verification (secret-scanner safety net)
+
+**When.** After `git push github main` when there is any chance of a
+secret-scanner false positive. The plugin hit one on 2026-04-28 (the
+`${SCHEMA_DRIFT_TOKEN}` placeholder); silent push success without mirror
+parity bit the operator a day later.
+
+**Description.** `github mirror parity vs local main`
+
+**timeout_ms.** `300000` (5 min — push usually completes in seconds; this is the wall-clock ceiling **for this watch**, **not** the `/loop` cadence band that LM-003 in `.claude/rules/loop-and-monitor.md` warns against)
+
+**persistent.** `false`
+
+```bash
+local_sha=$(git rev-parse main)
+prev=""
+while true; do
+  remote_sha=$(gh api repos/Kanevry/session-orchestrator/commits/main --jq '.sha' 2>/dev/null || echo "unreachable")
+  if [ "$remote_sha" != "$prev" ]; then
+    if [ "$remote_sha" = "$local_sha" ]; then
+      echo "mirror parity OK: $remote_sha"
+      break
+    elif [ "$remote_sha" = "unreachable" ]; then
+      echo "$(date -u +%H:%M:%SZ) GitHub API unreachable — retrying"
+    else
+      echo "$(date -u +%H:%M:%SZ) mirror at $remote_sha (local $local_sha)"
+    fi
+    prev=$remote_sha
+  fi
+  sleep 15
+done
+```
+
+**Coverage.** Emits on every SHA transition and on API unreachability.
+Terminates only when remote SHA matches local — never silent. If the
+push was actually rejected by GitHub's secret scanner, the remote SHA
+never advances and the watcher keeps emitting the stale-SHA line every
+15 s until the operator notices.
+
+---
+
+## Pattern 6 — WebSocket event source (`ws://` / `wss://`, v2.1.195+)
+
+**When.** The upstream already speaks WebSocket (a CI relay, an error-tracker
+push socket, a daemon's `GET /events` upgraded to WS). Point Monitor's `ws`
+source at it directly — the server pushes each text frame as one notification,
+so there is no polling script and no `grep --line-buffered` line-buffering
+pitfall to get right. Prefer this over a `command` source whenever a socket is
+available.
+
+**Input shape.** Monitor takes a `ws` source *instead of* a `command` source —
+the two are mutually exclusive, never combined:
+
+```jsonc
+{
+  "ws": {
+    "url": "wss://relay.internal.example/ci-events",  // ws:// or wss:// only
+    "protocols": ["ci-events.v1"]                      // optional subprotocols
+  }
+}
+```
+
+The `url` must be a bare `ws://`/`wss://` URL — **no embedded credentials, no
+whitespace, ASCII-only**. Each inbound **text** message becomes one
+notification (multi-line frames included). A **binary** frame is surfaced as the
+placeholder `[binary frame, N bytes]` rather than decoded.
+
+**Coverage / termination.** Two clean terminations and one **silent** one — the
+silent case is the whole reason this pattern needs the silence-is-not-success
+discipline:
+
+- **Socket close** → the watch ends and reports the close code (a clean,
+  visible terminal state).
+- **Frame > 1 MiB → the watch ends SILENTLY.** No close code, no error line —
+  it just stops. Therefore **always subscribe to a filtered / compact feed**
+  (a pre-narrowed event topic), **never a raw feed** whose payloads can cross
+  1 MiB. A raw firehose that occasionally emits a large frame is
+  indistinguishable from a healthy-but-quiet socket, which is exactly the
+  crash-reads-as-success trap this file exists to prevent.
+
+**Caveats.**
+
+- **Own approval prompt.** A `ws` source raises its own connect-approval prompt
+  and has **no "skip future" affordance** — each armed socket is approved
+  explicitly.
+- **SSRF denials.** Monitor refuses `ws` URLs pointing at private,
+  link-local, or cloud-metadata hosts, and honours `sandbox.network.deniedDomains`
+  plus `allowManagedDomainsOnly`. Point it at a reachable, allow-listed relay,
+  not an internal-range host.
+- **When to stay on `command`.** If frames must be filtered or reshaped
+  shell-side before they are notification-worthy, keep the `command` (tail/grep)
+  source per `.claude/rules/loop-and-monitor.md` LM-002 — the `ws` source
+  delivers frames verbatim, with no shell-side filter seam.
+
+---
+
+## Pattern — `/tmux-layout` (operator-side persistent visualization)
+
+> Per ADR-0007 + GitLab #561 #562 #563. Opt-in skill, NOT Monitor/loop replacement.
+
+`/tmux-layout` is a sibling primitive to `Monitor` and `/loop` — not a substitute. The three serve genuinely different purposes:
+
+| Primitive | Purpose | When to use |
+|---|---|---|
+| **`Monitor` tool** | Event-driven stream → coordinator reaction | The coordinator must REACT to each terminal-state line (CI fails → take action, build error → patch). Each stdout line = one coordinator notification. |
+| **`/loop` skill** | Periodic coordinator-side polling | "Check vault-staleness every 30 minutes while session runs." Lives inside the coordinator's turn budget. |
+| **`/tmux-layout` skill** | Operator-side persistent visualization (4-pane) | The OPERATOR (human) wants to peripherally observe side-channels — STATE.md tail, CI watch, events.jsonl — in a SECOND terminal without coordinator reaction. Pure observability. |
+
+**Key distinction:** `/tmux-layout` visualizes the *outputs* of `Monitor` and `/loop` peripherally so the coordinator pane stays focused on decisions (AUQ-001). It does NOT replace either — Pane 3 of the default layout, for example, runs a `glab ci status` poll-loop equivalent to a `/loop` cadence, but the coordinator does not see those refreshes (the operator does).
+
+**See also:** `docs/adr/0007-tmux-visualization-substrate.md`, `skills/tmux-layout/SKILL.md`.
+
+---
+
+## Anti-patterns
+
+- **`tail -f log | grep "passed"`** — silent on failure. See LM-002.
+- **`while true; do …; sleep 0.5; done`** with no change detection —
+  spams notifications and gets auto-stopped by Monitor's volume guard.
+- **Forgetting `--line-buffered`** in `grep` pipes — pipe buffering
+  delays events by minutes, which usually masks itself as "no events".
+- **Unbounded `tail -f` for one-shot signals** — use Bash with
+  `run_in_background` and an `until` loop instead. See the Monitor tool
+  docs.
+- **Using Monitor as a `/loop` replacement for periodic scans without a
+  stream** (e.g. polling `glab issue list`). Use `/loop` dynamic mode.
+
+---
+
+## See also
+
+- `.claude/rules/loop-and-monitor.md` — primitive routing (Monitor vs
+  `/loop` vs Routines)
+- `.claude/loop.md` — bare-`/loop` body that delegates to Monitor where
+  appropriate
+- "Background Detachment Test" (#640; archived in the private Meta-Vault) — empirical
+  verification of the Bash `run_in_background` + `TaskStop` detachment
+  seam behind Pattern 3
+- Anthropic Monitor tool reference (in-session)

package/skills/_shared/parallel-aware-auq.md

@@ -0,0 +1,121 @@
+# Parallel-Aware AUQ Templates
+
+> Three reusable AskUserQuestion blocks for the parallel-aware preamble (`parallel-aware-preamble.md`).
+> Consumed by: autopilot, session-start, session-plan, wave-executor, session-end (5 orchestrator entry-points).
+
+## When to fire which AUQ
+
+Driven by the preamble's outcome (see `parallel-aware-preamble.md` § Outcome Handling):
+
+| Preamble outcome | AUQ to fire |
+|------------------|-------------|
+| `EXCLUSIVE_BLOCKED` | Exclusive-Conflict AUQ (below) |
+| `PROMOTION_OFFER` | Worktree-Promotion AUQ (below) |
+| `PASS_THROUGH` | No AUQ |
+
+The third variant — **Always-OK Pass-Through** — fires no AUQ; documented here only for completeness so callers don't reinvent it.
+
+## Exclusive-Conflict AUQ (PRD §3 P1 row 2)
+
+Fires when an `exclusive`-class session (`bootstrap`, `housekeeping`, `memory-cleanup`) is already active in the worktree-family AND the caller is NOT `always-ok`-class.
+
+### Claude Code (AskUserQuestion)
+
+```js
+AskUserQuestion({
+  questions: [{
+    question: `An exclusive session is active in this repository (mode=${blockingSession.mode}, started ${ageHours}h ago, host=${blockingSession.host}, pid=${blockingSession.pid}, worktree=${blockingSession.worktreePath}). This blocks all other modes. How should I proceed?`,
+    header: "Parallel-Exclusive",
+    multiSelect: false,
+    options: [
+      { label: "Warten (Recommended)", description: "Wait for the exclusive session to finish. The preamble will not retry automatically — re-run the command after the other session closes." },
+      { label: "Andere Session beenden", description: "I will close the other session myself, then re-run this command. The preamble surfaces but does NOT terminate the other session." },
+      { label: "Abbrechen", description: "Exit cleanly. No STATE.md initialization, no lock acquired." },
+    ],
+  }],
+});
+```
+
+### Codex CLI / Cursor IDE / Pi fallback (numbered Markdown list)
+
+```
+Parallel-Exclusive conflict — an exclusive session is active in this repository.
+  Mode: <blockingSession.mode>
+  Started: <ageHours>h ago (host=<host>, pid=<pid>)
+  Worktree: <blockingSession.worktreePath>
+This blocks all other modes.
+
+1. Warten (Recommended) — wait for the exclusive session to finish; re-run after it closes.
+2. Andere Session beenden — I will close the other session myself.
+3. Abbrechen — exit cleanly without initializing STATE.md.
+
+Reply with the number of your choice.
+```
+
+### Outcome handling
+
+- **Warten** → exit Phase-0 cleanly with stderr note `parallel-aware: waiting on exclusive session_id=<id>`. No retry loop.
+- **Andere Session beenden** → exit Phase-0 cleanly with stderr note `parallel-aware: deferred to operator — exclusive session_id=<id>`. No automatic termination.
+- **Abbrechen** → exit Phase-0 immediately. No file writes.
+
+## Worktree-Promotion AUQ (PRD §3 P1 row 3)
+
+Fires when the caller is `parallel-ok`-class AND another `parallel-ok` session is active in the SAME worktree (i.e., main worktree collision).
+
+### Claude Code (AskUserQuestion)
+
+```js
+AskUserQuestion({
+  questions: [{
+    question: `A compatible parallel session is active in this worktree (mode=${parallelPeer.mode}, started ${ageHours}h ago, pid=${parallelPeer.pid}). You can either: (a) auto-promote to a sibling worktree to run isolated, or (b) run in-place alongside the existing session (file conflicts likely). How should I proceed?`,
+    header: "Worktree-Promo",
+    multiSelect: false,
+    options: [
+      { label: "Worktree anlegen + starten (Recommended)", description: "Create a sibling git worktree at ../<repo-name>-<semantic-session-id>/ and start the new session there. Isolates file edits; recommended for parallel deep/feature sessions. Calls enterWorktree() from scripts/lib/autopilot/worktree-pipeline.mjs." },
+      { label: "Manuell — in-place daneben", description: "Run in the current worktree alongside the existing session. File conflicts possible; PSA-001/002/004 discipline required. A Deviation is logged." },
+      { label: "Abbrechen", description: "Exit cleanly. No STATE.md initialization." },
+    ],
+  }],
+});
+```
+
+### Codex CLI / Cursor IDE / Pi fallback (numbered Markdown list)
+
+```
+Worktree-Promotion offer — a compatible parallel session is active in this worktree.
+  Peer mode: <parallelPeer.mode>
+  Started: <ageHours>h ago (pid=<pid>)
+
+1. Worktree anlegen + starten (Recommended) — create sibling worktree and start isolated session.
+2. Manuell — in-place daneben — run alongside (file conflicts possible, Deviation logged).
+3. Abbrechen — exit cleanly.
+
+Reply with the number of your choice.
+```
+
+### Outcome handling
+
+- **Worktree anlegen + starten** → invoke `enterWorktree({ basePath, sessionId, branch, repoRoot })` from `scripts/lib/autopilot/worktree-pipeline.mjs`. The helper creates a sibling worktree at `<basePath>/<repo-name>-<sessionId>/`, runs idempotency + boundary checks, and logs a WARN line to stderr on fresh creation. Once the worktree exists, exit the current preamble flow — the new worktree's own session-start runs from scratch (Phase 1 onwards). On failure (`WorktreeBoundaryError` or `git worktree add` non-zero exit), emit a stderr warning `parallel-aware: enterWorktree failed: <error>; falling back to Manuell` and proceed via the Manuell path.
+- **Manuell** → append a Deviation via `appendDeviationOnDisk()`:
+  `Worktree-Auto-Promotion declined; running in-place alongside session_id=<peer.sessionId>, mode=<peer.mode>, pid=<peer.pid>. PSA-001/PSA-002/PSA-004 discipline applies.`
+  Continue Phase-0.
+- **Abbrechen** → exit Phase-0 immediately. No file writes.
+
+## Always-OK Pass-Through (no AUQ)
+
+Fires when the caller's mode is in the `always-ok` class (`discovery`, `evolve`, `plan`, `repo-audit`, `portfolio`). The preamble returns `PASS_THROUGH` immediately regardless of other active sessions. No AUQ, no Deviation, no latency penalty.
+
+```js
+// Conceptual — there is NO AUQ for this case.
+// The preamble returns { outcome: 'PASS_THROUGH', callerClass: 'always-ok', active }.
+// The caller skill continues to Phase 1 unconditionally.
+```
+
+PRD §3 P1 row 5 specifies this is a hard guarantee — read-only modes never produce an interrupt.
+
+## See Also
+
+- `parallel-aware-preamble.md` — the preamble that fires these AUQs
+- `.claude/rules/ask-via-tool.md` — AUQ-001 through AUQ-005 (always use the tool, not prose)
+- `.claude/rules/parallel-sessions.md` — PSA-001/PSA-002 (overlap-check discipline)
+- "Parallel-Aware Sessions" (#568; archived in the private Meta-Vault) § 3 P1 — Gherkin rows 2, 3, 5 that these AUQs satisfy

package/skills/_shared/parallel-aware-preamble.md

@@ -0,0 +1,185 @@
+# Parallel-Aware Preamble
+
+> Single source of truth for the parallel-session-detection preamble.
+> Referenced by: autopilot, session-start, session-plan, wave-executor, session-end (5 orchestrator entry-points).
+
+## Purpose
+
+Every session-orchestrator entry-point runs this preamble silently at Phase-0.x (after the bootstrap-gate, before config-reading). It detects other active sessions in the same repository worktree-family, classifies the caller's mode against the exclusivity-matrix, and either passes through, offers Worktree-Auto-Promotion (P3), or blocks via AskUserQuestion.
+
+When no parallel session is detected, execution continues with zero overhead. When a conflict is detected, the appropriate AUQ from `parallel-aware-auq.md` fires.
+
+## Gate Classes
+
+The preamble applies one of three gate semantics based on the caller's mode-class:
+
+<HARD-GATE>
+**Exclusive class** (`bootstrap`, `housekeeping`, `memory-cleanup`):
+If any other active session exists in the worktree-family, you MUST NOT proceed. The preamble fires the Exclusive-Conflict AUQ from `parallel-aware-auq.md` (`[Warten / Andere Session beenden / Abbrechen]`).
+There is no bypass. There is no exception for urgent housekeeping. The ONLY valid next action is the user's AUQ response.
+</HARD-GATE>
+
+<SOFT-GATE>
+**Parallel-OK class** (`deep`, `feature`):
+If another `parallel-ok`-class session is active in the same worktree, the preamble offers Worktree-Auto-Promotion via the Promotion AUQ from `parallel-aware-auq.md` (`[Worktree anlegen + starten (Recommended) / Manuell / Abbrechen]`). The user may proceed in-place by selecting "Manuell" — the preamble logs a Deviation but does not block.
+
+If an `exclusive`-class session is also active, the Exclusive-Conflict AUQ takes precedence (HARD-GATE wins).
+</SOFT-GATE>
+
+**Always-OK class** (`discovery`, `evolve`, `plan`, `repo-audit`, `portfolio`):
+The preamble passes through with zero AUQ regardless of other active sessions. Read-only modes never conflict.
+
+## Preamble Algorithm
+
+Execute these steps in order. Any classification determines outcome.
+
+```
+1. Call findPeers(repoRoot, { mySessionId: callerSessionId }) from scripts/lib/peer-discovery.mjs.
+   - Returns: { peers: Array<{source, sessionId, mode, pid, host, worktreePath, ageHours?, currentWave?}> }
+   - Phase 0.5 consumes the non-'state-md' subset: peers.filter(p => p.source !== 'state-md').
+   - 2-second timeout built-in (via discoverActiveSessions). On timeout or git failure: A1 fallback (single-worktree mode).
+   - Empty active list → no parallel context → PASS_THROUGH (continue immediately).
+
+2. Classify the caller's mode via classifyMode(callerMode) from scripts/lib/exclusivity-matrix.mjs.
+   - GOTCHA: classifyMode throws on unknown mode. Wrap in try/catch; on throw, default to 'parallel-ok' (most permissive default) and log a stderr WARN.
+   - Returns: 'exclusive' | 'parallel-ok' | 'always-ok'
+
+3. Apply the decision matrix:
+   - If callerClass === 'always-ok' → return PASS_THROUGH (no AUQ; preamble done).
+   - For each active session, classify entry.mode via classifyMode (same safe fallback).
+   - If any entry has entryClass === 'exclusive' AND callerClass !== 'always-ok':
+       → fire Exclusive-Conflict AUQ from parallel-aware-auq.md
+       → block until user response
+   - Else if callerClass === 'parallel-ok' AND any entry has entryClass === 'parallel-ok':
+       → fire Promotion AUQ from parallel-aware-auq.md
+       → user may pick "Worktree anlegen" (P3 fills the action), "Manuell" (in-place + Deviation), or "Abbrechen" (exit)
+   - Otherwise (no overlap) → return PASS_THROUGH.
+
+4. Record any non-PASS_THROUGH outcome as a Deviation in STATE.md via appendDeviationOnDisk().
+```
+
+## Implementation (JavaScript reference)
+
+```js
+import { findPeers } from '../../scripts/lib/peer-discovery.mjs';
+import { classifyMode } from '../../scripts/lib/exclusivity-matrix.mjs';
+
+async function runParallelAwarePreamble({ repoRoot, callerMode, callerSessionId }) {
+  // Step 1: discover active sessions via unified findPeers (fail-open, never throws).
+  // Phase 0.5 consumes only the non-'state-md' subset (lock+registry surface).
+  // The 'state-md' subset is reserved for Phase 1.2.1 (peer-guard after lock acquire).
+  let active;
+  try {
+    const { peers } = await findPeers(repoRoot, { mySessionId: callerSessionId });
+    active = peers.filter((p) => p.source !== 'state-md');
+  } catch (err) {
+    process.stderr.write(`[parallel-aware-preamble] WARN: findPeers failed: ${err.message} — passing through (A1 fallback)\n`);
+    return { outcome: 'PASS_THROUGH', reason: 'discovery-error' };
+  }
+
+  // Step 2: classify caller (safe — never throw)
+  let callerClass;
+  try {
+    callerClass = classifyMode(callerMode);
+  } catch {
+    process.stderr.write(`[parallel-aware-preamble] WARN: unknown mode '${callerMode}' — defaulting to 'parallel-ok'\n`);
+    callerClass = 'parallel-ok';
+  }
+
+  // Step 3: always-ok passes through
+  if (callerClass === 'always-ok') return { outcome: 'PASS_THROUGH', callerClass, active };
+
+  // Step 4: empty active list → no conflict
+  if (!Array.isArray(active) || active.length === 0) {
+    return { outcome: 'PASS_THROUGH', callerClass, active: [] };
+  }
+
+  // Step 5: classify each entry (safe)
+  const classifiedActive = active.map((entry) => {
+    let entryClass;
+    try { entryClass = classifyMode(entry.mode); } catch { entryClass = 'parallel-ok'; }
+    return { ...entry, _class: entryClass };
+  });
+
+  // Step 6: decision matrix
+  const exclusiveActive = classifiedActive.find((e) => e._class === 'exclusive' && e.sessionId !== callerSessionId);
+  if (exclusiveActive && callerClass !== 'always-ok') {
+    return { outcome: 'EXCLUSIVE_BLOCKED', callerClass, blockingSession: exclusiveActive, active: classifiedActive };
+  }
+
+  const parallelPeer = callerClass === 'parallel-ok'
+    ? classifiedActive.find((e) => e._class === 'parallel-ok' && e.sessionId !== callerSessionId)
+    : null;
+  if (parallelPeer) {
+    return { outcome: 'PROMOTION_OFFER', callerClass, parallelPeer, active: classifiedActive };
+  }
+
+  return { outcome: 'PASS_THROUGH', callerClass, active: classifiedActive };
+}
+```
+
+## Outcome Handling
+
+The skill consuming the preamble translates the outcome:
+
+| Outcome | Action |
+|---------|--------|
+| `PASS_THROUGH` | Continue immediately. No AUQ. Pre-P1.3 behavior. |
+| `EXCLUSIVE_BLOCKED` | Fire Exclusive-Conflict AUQ from `parallel-aware-auq.md`. Block until user response. On "Abbrechen": exit cleanly. On "Andere Session beenden": surface to user (preamble does NOT kill other session). On "Warten": pause Phase 0; re-run preamble on user retry. |
+| `PROMOTION_OFFER` | Fire Promotion AUQ from `parallel-aware-auq.md`. On "Worktree anlegen": call enterWorktree() from worktree-pipeline.mjs (see parallel-aware-auq.md outcome-handling). On "Manuell": append Deviation (`Worktree-Auto-Promotion declined; running in-place alongside session_id=<peer.sessionId>`) and continue. On "Abbrechen": exit. |
+
+## Phase 1b Peer-Guard (defense-in-depth)
+
+After Phase 0.5 (parallel-aware preamble) and Phase 1.2 (session-lock acquire), session-start Phase 1b initializes STATE.md. Before overwriting, the guard MUST run — via `findPeers(repoRoot, { mySessionId })` consuming the `state-md`-sourced subset (which delegates internally to `scripts/lib/state-md-peer-guard.mjs:checkPeerStateMd()`).
+
+If `findPeers` yields a `state-md`-sourced peer (non-null), fire the Worktree-Promotion AUQ from `parallel-aware-auq.md`. This catches races where the preamble's lock-based detection missed an active peer (e.g., a session whose lock was force-deleted but STATE.md is still status:active).
+
+The guard is a SOFT-GATE — operator can override, but the warning is mandatory.
+
+### Guard decision tree (for Phase 1b callers)
+
+```
+findPeers(repoRoot, { mySessionId }) → peer = peers.find((p) => p.source === 'state-md') →
+  peer === null  →  safe to write STATE.md; continue Phase 1b normally.
+  peer !== null  →  fire Promotion AUQ (parallel-aware-auq.md "Promotion" block).
+                    On "Worktree anlegen": enterWorktree() → continue in sibling.
+                    On "Manuell": appendDeviationOnDisk() + continue in-place.
+                    On "Abbrechen": exit cleanly.
+```
+
+### Integration reference
+
+```js
+import { findPeers } from '../../scripts/lib/peer-discovery.mjs';
+
+// Inside Phase 1b, before writing STATE.md:
+const { peers } = await findPeers(repoRoot, { 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 !== null) {
+  // peer.sessionId, peer.mode, peer.currentWave, peer.ageHours are populated.
+  // Fire the Promotion AUQ — do NOT silently overwrite.
+  // ... AUQ logic per parallel-aware-auq.md ...
+}
+```
+
+## Cross-References
+
+- **Discovery layer:** `scripts/lib/session-discovery.mjs` (`discoverActiveSessions`, `findWorktrees`) — shipped in P1.1 #569
+- **Classification:** `scripts/lib/exclusivity-matrix.mjs` (`EXCLUSIVITY_MATRIX`, `classifyMode`) — shipped in P1.1 #569
+- **Lock integration:** `scripts/lib/session-lock.mjs:acquire()` extended in P1.2 #570 — accepts pre-computed `activeSessions[]` and returns matrix-aware reasons (`active-incompatible-exclusive`, `active-compatible-parallel`, `active-readonly-bypass`)
+- **AUQ patterns:** `parallel-aware-auq.md` (three reusable AUQ blocks) — sibling file
+- **Deviation logging:** `scripts/lib/state-md.mjs:appendDeviationOnDisk()`
+- **Phase 1b peer-guard:** `scripts/lib/state-md-peer-guard.mjs:checkPeerStateMd()` — shipped in #588
+
+## Idempotency
+
+The preamble is read-only relative to repository state (no file writes unless the user picks an action). Repeated invocation produces the same outcome given the same active-session set. Safe to call multiple times in the same skill invocation if the caller wants to re-check after a wait period.
+
+The Promotion AUQ's "Worktree anlegen" path (P3.1) creates a new sibling worktree and is NOT idempotent — re-running after promotion discovers the new worktree as an active session (which is intended behavior).
+
+## See Also
+
+- `bootstrap-gate.md` — sibling Phase-0 gate (HARD; orthogonal layer)
+- `.claude/rules/parallel-sessions.md` — PSA-001 through PSA-006 (behavioural rules complementing this mechanical layer)
+- "Parallel-Aware Sessions" (#568; archived in the private Meta-Vault) § 3 P1 + § 3.A P1 — acceptance criteria this preamble satisfies