session-orchestrator 3.21.0 → 3.23.0

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

@@ -22,15 +22,18 @@ Fires when an `exclusive`-class session (`bootstrap`, `housekeeping`, `memory-cl
 ### Claude Code (AskUserQuestion)
 
 ```js
+// Unpacked once so the question reads as one sentence instead of five key=value pairs.
+const { mode, host, pid, worktreePath } = blockingSession;
+
 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",
+    question: `A ${mode} session (process ${pid} on ${host}) started ${ageHours}h ago in ${worktreePath}. What now?`,
+    header: "Repo belegt",
     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." },
+      { label: "Warten (Recommended)", description: "Nothing else can start here until that session closes. This command does not retry — run it again afterwards." },
+      { label: "Andere Session beenden", description: "You close it yourself, then run this command again. Nothing here stops the other session for you." },
+      { label: "Abbrechen", description: "Exit now. Nothing is written: no STATE.md, no lock." },
     ],
   }],
 });
@@ -39,19 +42,17 @@ AskUserQuestion({
 ### 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.
+A <mode> session (process <pid> on <host>) started <ageHours>h ago in <worktreePath>. What now?
 
-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.
+1. Warten (Recommended) — nothing else can start here until that session closes; this command does not retry, so run it again afterwards.
+2. Andere Session beenden — you close it yourself, then run this command again. Nothing here stops the other session for you.
+3. Abbrechen — exit now. Nothing is written: no STATE.md, no lock.
 
 Reply with the number of your choice.
 ```
 
+The four slots are `blockingSession.mode`, `blockingSession.host`, `blockingSession.pid` and `blockingSession.worktreePath`; `<ageHours>` is the age of that session in hours.
+
 ### Outcome handling
 
 - **Warten** → exit Phase-0 cleanly with stderr note `parallel-aware: waiting on exclusive session_id=<id>`. No retry loop.
@@ -65,37 +66,42 @@ Fires when the caller is `parallel-ok`-class AND another `parallel-ok` session i
 ### Claude Code (AskUserQuestion)
 
 ```js
+// Unpacked once so the question reads as one sentence instead of three key=value pairs.
+const { mode, pid } = parallelPeer;
+
 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",
+    question: `A ${mode} session (process ${pid}) started ${ageHours}h ago in this same folder. Run separately or alongside?`,
+    header: "Wo starten?",
     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." },
+      { label: "Worktree anlegen + starten (Recommended)", description: "Creates a second working folder beside this one and starts there — isolates your edits, so nothing collides." },
+      { label: "Manuell — in-place daneben", description: "Both sessions write in this same folder — conflicts are likely and you resolve them yourself. A Deviation is logged." },
+      { label: "Abbrechen", description: "Exit now. Nothing is written: no STATE.md, no lock." },
     ],
   }],
 });
 ```
 
+The second working folder is a git worktree at `<basePath>/<repo-name>-<sessionId>/`; `enterWorktree()` from `scripts/lib/autopilot/worktree-pipeline.mjs` creates it (see Outcome handling below). Running in-place puts PSA-001/PSA-002/PSA-004 discipline on the operator.
+
 ### 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>)
+A <mode> session (process <pid>) started <ageHours>h ago in this same folder. Run separately or alongside?
 
-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.
+1. Worktree anlegen + starten (Recommended) — creates a second working folder beside this one and starts there; isolates your edits, so nothing collides.
+2. Manuell — in-place daneben — both sessions write in this folder; conflicts are likely and you resolve them. A Deviation is logged.
+3. Abbrechen — exit now. Nothing is written: no STATE.md, no lock.
 
 Reply with the number of your choice.
 ```
 
+The two slots are `parallelPeer.mode` and `parallelPeer.pid`; `<ageHours>` is the age of that session in hours.
+
 ### 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.
+- **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. When `<branch>` is already checked out by another worktree — the normal case, since Phase 0.5 passes the current HEAD — the worktree lands on a fresh `so/<sessionId>` branch created at `<branch>` and the helper returns `{ branch: 'so/<sessionId>', promotedFrom: '<branch>' }` (#1067); the new worktree's STATE.md `branch` MUST record `so/<sessionId>` and note `promoted from <branch>@<repoRoot>`. Once the worktree exists, and BEFORE exiting the preamble flow, call `leaveSourceRoot({ repoRoot, sessionId: <the raw physical session_id owning this root's lock/registry entry>, semanticSessionId, reason: 'worktree-promotion' })` from `scripts/lib/session-transition.mjs`. **Read that `sessionId` from this root's `.orchestrator/session.lock` via `readLock({ repoRoot })` — never the semantic label, and never `current-session.json`, which may describe a peer session (#863); a wrong id aborts the teardown with `ok: false, reason: 'lock-session-mismatch:<owner>'` and removes nothing.** In detail: the promotion is a PROCESS BOUNDARY, not a live migration (#1069) — the old root is deregistered and its `session.lock` released BEFORE the new worktree's own Phase 1.2 acquires, so the two roots never both own a live claim at once. The call never throws; on `{ ok: false }` emit a stderr WARN `parallel-aware: leaveSourceRoot: <reason>` and continue (the destination worktree already exists — aborting here would leave the two-live-roots state the call prevents). Then 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.

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

@@ -29,6 +29,33 @@ If an `exclusive`-class session is also active, the Exclusive-Conflict AUQ takes
 **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.
 
+## Identity Binding for `findPeers` (#1085)
+
+`mySessionId` / `callerSessionId` is a **hint for the caller's original
+surface**, not a license to turn an attribution label into ownership. A native
+raw id self-excludes on the discovered lock/registry surface directly. Given a
+semantic hint, `findPeers` may translate it to a concrete local raw id only when
+both proofs hold: `current-session.json` has the same semantic label **and** its
+raw `session_id` exactly equals the readable local lock's raw `session_id`.
+
+On a missing, malformed, or mismatched binding, `findPeers` must map nothing and
+leave the discovered lock visible. The STATE.md surface always receives the
+original hint and therefore compares STATE.md `session` as the attribution label
+it is; it is never rewritten to a raw id. This guarded translation is only
+self-exclusion for discovery, not lock/registry ownership and not a continuity
+bridge across a host rotation that changes both values.
+
+**What the binding does not prove.** Both files it reads are repo-global, so the
+check establishes that they are mutually CONSISTENT — not that they describe
+*this* process. Semantic labels are routinely shared between simultaneously live
+sessions, and when a foreign live session wrote both files last under a label
+equal to this hint, its raw id is filtered out and the peer disappears from the
+result. Measured 2026-08-21: with a null hint the foreign peer is returned, with
+the colliding semantic hint `peers` is empty. Treat a quiet `findPeers` result as
+weaker evidence than a git or filesystem signal, and prefer passing the native
+raw id whenever the caller has one. Closing this needs a per-process ownership
+proof; see #1091.
+
 ## Preamble Algorithm
 
 Execute these steps in order. Any classification determines outcome.
@@ -126,7 +153,7 @@ The skill consuming the preamble translates the outcome:
 |---------|--------|
 | `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. |
+| `PROMOTION_OFFER` | Fire Promotion AUQ from `parallel-aware-auq.md`. On "Worktree anlegen": call enterWorktree() from worktree-pipeline.mjs, then — BEFORE exiting Phase 0 — `leaveSourceRoot({ repoRoot, sessionId, semanticSessionId, reason: 'worktree-promotion' })` from `session-transition.mjs` (see parallel-aware-auq.md outcome-handling). `sessionId` is the RAW physical `session_id` from this root's `.orchestrator/session.lock` (`readLock({ repoRoot })`), never the semantic label and never `current-session.json` (may describe a peer, #863). The promotion is a process boundary, not a live migration (#1069): the old root is deregistered and its lock released BEFORE the new worktree's own Phase 1.2 acquires — never both roots owning at once. It never throws; on `{ ok: false }` emit a stderr WARN `parallel-aware: leaveSourceRoot: <reason>` and continue. 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)
 
@@ -142,7 +169,9 @@ The guard is a SOFT-GATE — operator can override, but the warning is mandatory
 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 "Worktree anlegen": enterWorktree() → leaveSourceRoot(this root)
+                                           → continue in sibling (process boundary,
+                                             old root released before the new acquire).
                     On "Manuell": appendDeviationOnDisk() + continue in-place.
                     On "Abbrechen": exit cleanly.
 ```
@@ -152,8 +181,10 @@ findPeers(repoRoot, { mySessionId }) → peer = peers.find((p) => p.source === '
 ```js
 import { findPeers } from '../../scripts/lib/peer-discovery.mjs';
 
-// Inside Phase 1b, before writing STATE.md:
-const { peers } = await findPeers(repoRoot, { mySessionId: sessionId });
+// Inside Phase 1b, before writing STATE.md. Preserve the original
+// attribution-label hint for the STATE.md surface; findPeers guards any
+// semantic→raw translation for discovered peers internally.
+const { peers } = await findPeers(repoRoot, { mySessionId: callerSessionHint });
 const peer = peers.find((p) => p.source === 'state-md') ?? null;
 // Phase 1.2.1 consumes only the 'state-md' subset (STATE.md surface only).
 if (peer !== null) {

package/skills/_shared/platform-tools.md

@@ -20,10 +20,12 @@ These tools have the same name and behavior on all platforms. Cursor IDE uses eq
 
 ## Platform-Specific Tool Mapping
 
+> **Every statement about a foreign platform carries a measurement date and the tool version it was measured on** (PSA-006). An undated capability claim about Codex CLI, Cursor IDE, or Pi is unverified — re-measure before relying on it, and stamp what you find.
+
 | Function | Claude Code | Codex CLI | Cursor IDE | Pi |
 |----------|------------|-----------|------------|----|
 | Present choices to user | `AskUserQuestion` tool with structured options | Numbered Markdown list as plain text, wait for user reply | Numbered Markdown list (same as Codex) | Numbered Markdown list v1; native UI adapter planned |
-| Dispatch subagent | `Agent({ description, prompt, subagent_type })` | Delegate via Codex subagents / typed roles (`explorer`, `worker`) when available; otherwise execute sequentially in the main session | Sequential execution — no parallel subagents. Execute tasks one by one within a single session. | Sequential execution v1. Do not assume native subagents until the Pi SDK dispatcher exists. |
+| Dispatch subagent | `Agent({ description, prompt, subagent_type })` | Native multi-agent collaboration namespace: `spawn_agent`, `list_agents`, `wait_agent`, `send_message`, `followup_task`, `interrupt_agent`, `close_agent`. Measured 2026-08-25 on `codex-cli 0.141.0` — `codex features list` → `multi_agent  stable  true`. | No native in-session Agent tool. Coordinator-side foreign dispatch via the headless `cursor-agent` CLI exists (`scripts/lib/wave-executor/foreign-dispatch.mjs`, #1150) — measured 2026-08-25 on `cursor-agent 2026.08.11-e8db854`. | Sequential execution v1. Do not assume native subagents until the Pi SDK dispatcher exists. |
 | Track tasks | `TaskCreate` / `TaskUpdate` / `TaskList` | Plain-text checklist in response context | Plain-text checklist (same as Codex) | Plain-text checklist (same as Codex) |
 | Enter plan mode | `EnterPlanMode` / `ExitPlanMode` tools | `/plan` slash command (prompt-level, not tool-based) | Instruction-based: "Focus on analysis and planning. Do not modify files until the user approves." | `/plan` prompt template; use instruction-based planning when tool mode is unavailable |
 | Web search | `WebSearch` tool | Built-in web search (invoke via instruction) | `@web` in Cursor chat | Use Pi's available web/search tools if configured; otherwise Bash curl or browser handoff |
@@ -53,18 +55,22 @@ Agent({
   description: "3-5 word summary",
   prompt: "full task context...",
   subagent_type: "general-purpose",
-  run_in_background: false
+  run_in_background: true   // RECOMMENDED for wave dispatch since 2026-08-25 (FA-6);
+                            // verify the started set via meta.json sidecars, never via the
+                            // launch ack — see skills/wave-executor/wave-loop.md § Started-Set Verification
 })
 ```
 
 **On Codex CLI / Codex Desktop:**
-Delegate the task in detail using the available Codex subagent mechanism when it exists. Map work to these roles:
+Codex has a native multi-agent collaboration namespace — use it; do not fall back to sequential in-session execution. Measured 2026-08-25 on `codex-cli 0.141.0`: `codex features list` reports `multi_agent  stable  true`, and a tool-call census over `~/.codex/sessions` (`grep -rhoE '"(spawn_agent|send_message|wait_agent|list_agents|followup_task|interrupt_agent|close_agent)"' . | sort | uniq -c`) returns wait_agent 6041 · send_message 2233 · spawn_agent 1748 · list_agents 836 · close_agent 781 · followup_task 656 · interrupt_agent 109 — i.e. the toolset is in routine production use, not a preview.
+
+Lifecycle: `spawn_agent` (launch, one per wave task) → `list_agents` (enumerate the started set) → `wait_agent` (block on completion) → `send_message` / `followup_task` (steer a running agent) → `interrupt_agent` / `close_agent` (abort / reap). Verify the started set via `list_agents`, never via the `spawn_agent` return alone. Map wave work to these prompt-level roles:
 - **explorer** — read-only evidence gathering (maps to Claude Code's `Explore` subagent)
 - **worker** — implementation tasks (maps to Claude Code's `general-purpose` subagent)
-- **session-reviewer** — quality review when a dedicated review role is available; otherwise perform the review in the main session
+- **session-reviewer** — quality review; spawn as a separate agent rather than reviewing in the main session
 
 **On Cursor IDE:**
-No Agent() tool or typed agent roles. Execute wave tasks sequentially within the active Composer session. After completing each task, report status and move to the next. Parallel execution is not possible — `agents-per-wave` config is ignored on Cursor.
+No native Agent() tool or typed agent roles inside the Composer session — wave tasks run sequentially there, and `agents-per-wave` is ignored. This is a statement about the IDE session only: coordinator-side foreign dispatch to Cursor models via the headless `cursor-agent` CLI does exist (`scripts/lib/wave-executor/foreign-dispatch.mjs`, #1150 — detached worktree, filesystem-measured result, `orchestrator.foreign_dispatch.completed` telemetry, mandatory Claude review, `NEVER_FOREIGN_ROLES` lock). Measured 2026-08-25 on `cursor-agent 2026.08.11-e8db854`. Slash commands live in `.cursor/commands/`. There is no Skill tool — Read `skills/<name>/SKILL.md` instead.
 
 **On Pi:**
 No Session Orchestrator Pi subagent dispatcher exists in v1. Execute wave tasks sequentially in the active Pi session. Treat `agents-per-wave` as advisory until the SDK-based dispatcher lands.

package/skills/_shared/state-ownership.md

@@ -17,7 +17,7 @@ current-wave: <N>
 total-waves: <N>
 # Optional fields (schema-version 1, additive for backward-compat):
 updated: <ISO 8601 UTC>      # last write timestamp, touched by any writer
-session: <session-id>        # <branch>-<YYYY-MM-DD>-<mode>-<n> (semantic, since #573); legacy UUID-v4 also accepted by parseSessionId
+session: <session-label>     # attribution/history label; normally semantic since #573, legacy UUID-v4 remains readable; never a lock/registry ownership key
 session-start-ref: <sha>     # git ref at session start
 ---
 ```
@@ -25,7 +25,7 @@ session-start-ref: <sha>     # git ref at session start
 ### Required vs. optional fields
 
 - `schema-version`, `session-type`, `branch`, `issues`, `started_at`, `status`, `current-wave`, `total-waves` — **required** in every session-owned STATE.md.
-- `updated`, `session`, `session-start-ref` — **optional**. Added by #184. STATE.md files without these fields remain valid and should be treated as `updated: null` / `session: null`. Writers SHOULD populate these fields but readers MUST tolerate their absence. The `session` field's value format is `<branch>-<YYYY-MM-DD>-<mode>-<n>` since #573 (Epic #568 Parallel-Aware Sessions P2.2); pre-#573 files may contain a UUID-v4 — both formats are read via `parseSessionId()` from `scripts/lib/session-id.mjs` per PRD §3 P2 row 3 (backward-compat).
+- `updated`, `session`, `session-start-ref` — **optional**. Added by #184. STATE.md files without these fields remain valid and should be treated as `updated: null` / `session: null`. Writers SHOULD populate these fields but readers MUST tolerate their absence. `session` is an attribution/history label, normally `<branch>-<YYYY-MM-DD>-<mode>-<n>` since #573 (Epic #568 Parallel-Aware Sessions P2.2); pre-#573 files may contain a UUID-v4 — both formats are read via `parseSessionId()` from `scripts/lib/session-id.mjs` per PRD §3 P2 row 3 (backward-compat). Neither form grants lock or registry ownership.
 
 The `session-type: none` + `status: idle` combination is used only for bootstrap-scaffolded placeholder files (no active session).
 
@@ -79,6 +79,32 @@ A log of unresolved, user-facing questions surfaced by wave agents during a sess
 
 Helpers: `readOpenQuestions` (pure), `appendOpenQuestion` (pure), `markOpenQuestionAnswered` (pure), `appendOpenQuestionOnDisk` (lock-guarded write), `markOpenQuestionAnsweredOnDisk` (lock-guarded write) — all exported from `scripts/lib/state-md.mjs`.
 
+## Session Identity and Lock Ownership (#1085)
+
+This contract distinguishes a physical live-session key from labels that make a
+session intelligible to people and history readers. It does not add an identity
+layer.
+
+- **`session_id` is the only live ownership key.** It is the native raw identity
+  supplied by the active harness, or a generated UUID when no trustworthy raw
+  identity is available. Lock acquisition, registry membership, self-exclusion,
+  proof checks, and lock release use this physical key.
+- **`semantic_session_id` and STATE.md `session` are attribution/history
+  labels, never ownership.** They may describe the same work to a human, but
+  equality of either label cannot acquire, refresh, release, or reclaim a lock.
+  A legacy UUID in STATE.md remains readable only as historical data.
+- **Never bridge a raw mismatch with a label or a proof.** If the current raw
+  id and a live lock's raw id differ, ownership is ambiguous. Leave the live
+  lock visible and let its TTL/Reaper lifecycle resolve it; do not substitute a
+  semantic match, STATE.md `session` match, or owner-proof match.
+- **There is no `logical_session_id`.** A true cross-harness restart-continuity
+  contract requires a trusted native resume identifier and remains a follow-up.
+  In particular, a host rotation that changes both raw and semantic values has
+  no guaranteed continuity.
+
+The peer-discovery and issue-budget procedures below apply these rules at their
+narrow surfaces; neither creates a second ownership model.
+
 ## CCU-009 — Status = Index, Never History (#730/H6)
 
 > Adopted from an external-repo fleet-mining finding (2026-07-02): narrative
@@ -117,6 +143,20 @@ The Ownership Model above resolves *STATE.md* specifically, but the same discipl
 
 This is the wave-plan-time analog of PSA-007 (subagents never race the shared git index) applied one layer up, to shared *files* rather than the git index — see [`../../.claude/rules/parallel-sessions.md`](../../.claude/rules/parallel-sessions.md) § PSA-007.
 
+### `wave-scope.json` Session Binding (#1123)
+
+The rule above deconflicts writers *inside one wave*. The same working copy is also shared across SESSIONS, and `<state-dir>/wave-scope.json` is the one control artefact that constrains writes rather than describing them. It lives in the working copy, not in the session — so before #1123 a manifest written by session A governed session B's every Edit. Measured 2026-08-22 (#1082): a Discovery wave's `allowedPaths: []` — prescribed for every Discovery wave — denied all writes of an unrelated parallel session, with a deny reason that could only tell it to fix a wave plan it does not own.
+
+**The manifest is SESSION-BOUND since #1123.** The coordinator that writes it names itself in two optional fields, `session` (raw `session_id`) and `semantic_session`, both from ONE `sessionAttribution(repoRoot)` call (`scripts/lib/events.mjs`) — see `skills/wave-executor/wave-loop.md` § Scope Manifest 1. `hooks/enforce-scope.mjs` Gate 3b classifies the manifest with `readOwnSessionIds()` + `classifyManifestSession()` (`scripts/lib/session-identity/own-session.mjs`):
+
+- **`foreign`** (ids present, none of them ours) → the gate ALLOWS the write and emits one `orchestrator.scope.foreign_session_ignored` event. A foreign manifest is somebody else's wave plan; it never had authority here, and the event keeps the skip counted rather than silent.
+- **`own`** → enforce, unchanged.
+- **`unknown`** — no id in the manifest (legacy, pre-#1123) or our own identity unresolvable → enforce, unchanged. Only what is PROVABLY foreign is treated as foreign; a guess would turn "cannot tell" into a silent enforcement-off.
+
+Two consequences for anyone touching this artefact. A stale manifest left by a crashed or finished PEER session no longer scopes this session out of its own writes — but a stale manifest of THIS session still does, so the § Scope Manifest lifecycle (delete `wave-scope.json` with `filescopes/` at session end) remains the operator's job. And an empty id is never an honest "unbound": `scripts/validate-wave-scope.mjs` (`validateSession()`) rejects `"session": ""` as an ERROR while an ABSENT key is only a warning, because an empty id matches nobody and would make every reader treat the manifest as foreign where the writer meant "binds everyone".
+
+Mechanism, disposition table and named limits: [`../../docs/scope-collision-guard.md`](../../docs/scope-collision-guard.md) § 2.3.
+
 ## Guards
 
 ### Branch Validation
@@ -174,8 +214,8 @@ The `.orchestrator/session.lock` file is written mechanically by `hooks/_lib/loc
 
 ```json
 {
-  "session_id":          "<UUID-v4 OR semantic-id>",
-  "semantic_session_id": "<branch>-<YYYY-MM-DD>-<mode>-<n>",
+  "session_id":          "<native-raw-id OR generated-UUID>",
+  "semantic_session_id": "<attribution-label>",
   "started_at":          "<ISO-8601 UTC>",
   "last_heartbeat":      "<ISO-8601 UTC>",
   "mode":                "deep|feature|housekeeping|session|...",
@@ -189,8 +229,8 @@ The `.orchestrator/session.lock` file is written mechanically by `hooks/_lib/loc
 
 | Field | Required since | Description |
 |---|---|---|
-| `session_id` | v1 | The session identifier (UUID-v4 on Claude Code, semantic on Codex/Cursor). |
-| `semantic_session_id` | v2 (Epic #583) | The semantic form (`<branch>-<YYYY-MM-DD>-<mode>-<n>`) **always present**, even when `session_id` is a UUID. Closes D4 gap: semantic-id branch was previously dead code on Claude Code (stdin always provides UUID). |
+| `session_id` | v1 | The physical live lock/registry ownership key: a native raw harness identity, or a generated UUID when no trustworthy raw identity exists. Never use a semantic label here. |
+| `semantic_session_id` | v2 (Epic #583) | An attribution/history label, normally `<branch>-<YYYY-MM-DD>-<mode>-<n>`, surfaced alongside the raw key. It never establishes lock or registry ownership, including when it equals STATE.md `session`. |
 | `started_at` | v1 | ISO-8601 timestamp when the lock was written. |
 | `last_heartbeat` | v2 (Epic #583) | ISO-8601 timestamp updated by the `SessionStart` hook and by `PostToolBatch`/`Stop` hooks. **Basis for liveness determination** — replaces PID-liveness (see below). |
 | `mode` | v1 | Session mode consulted by exclusivity-matrix. May be `"unknown"` in the provisional lock written by the hook before Session Config + AUQ have settled. |
@@ -211,11 +251,24 @@ This replaces the v1 PID-liveness check (`process.kill(pid, 0)`) which was funda
 Despite the v2 liveness rule above existing since Epic #583, `acquire()`'s conflict classifier (`scripts/lib/session-lock.mjs`, the `classifyExisting()` closure) and `checkStale()` still let `pidAlive`/TTL-age act as an independent veto — which let an external `/close` observe the lock's recorded `pid` (the ephemeral hook subprocess / `node -e acquire()` PID, routinely dead within <1s) as dead and misclassify a live, actively-heartbeating session as `stale-pid-dead`, hijacking it mid-wave. Fixed in #744:
 
 - `classifyExisting()` now checks `isLockLive(existing)` **first** and unconditionally returns `{ reason: 'active' }` when true — a dead recorded `pid` can never veto a fresh `last_heartbeat`.
-- Only once `isLockLive()` is false does `pidAlive` pick the stale variant: `stale-pid-dead` when `pidAlive === false` (same-host, confirmed dead), else `stale-pid-alive` — which also covers `pidAlive === null` (cross-host locks, `host !== os.hostname()`, never a confirmable dead PID, so cross-host locks can never land on `stale-pid-dead`).
-- `checkStale()` surfaces the same `isLockLive()` result as an additive `isLive` field alongside the legacy `ttlExpired`/`pidAlive` signals, so recovery-flow diagnostics can observe when the two diverge.
+- Only once `isLockLive()` is false is the lock classified stale — see the #1137 follow-up below for the single reason it now returns.
+- `checkStale()` surfaces the same `isLockLive()` result as an additive `isLive` field alongside the legacy `ttlExpired` signal, so recovery-flow diagnostics can observe when the two diverge.
 
 Net: `pid` (field notes above) stays forensic-only; `last_heartbeat` freshness is the sole determinant of "is this session still active" everywhere in `session-lock.mjs`.
 
+### #1137 — one stale reason, `stale-heartbeat`
+
+#744 left the *stale* half still keyed on `pidAlive`: `stale-pid-dead` when the recorded pid was confirmed dead, `stale-pid-alive` otherwise. Measured 2026-08-23 across the fleet's live locks: **7 of 7 recorded pids were dead**, including the lock of the session that was heartbeating at that very moment. The pid on a lock is the `node -e` / hook subprocess that wrote it, and it exits within about a second of genesis. Two consequences, both live defects:
+
+- `stale-pid-alive` was **structurally unreachable** same-host — nothing could produce it except a pid-number collision.
+- The Phase-1.2 recovery AUQ rendered "pid=… is confirmed dead" for **every** same-host stale lock, presenting a measurement it had not made as the operator's reason to reclaim.
+
+The fix removes the question rather than re-answering it. `classifyExisting()` returns exactly one stale reason, `stale-heartbeat`, carrying `ageHours` (age from `started_at`, unchanged) and `heartbeatAgeMinutes` (age from `last_heartbeat`) — the quantity the liveness rule actually thresholds against, so a recovery prompt states the measured heartbeat age instead of a liveness verdict. `checkStale()` gains the same `heartbeatAgeMinutes` field.
+
+**#1151 follow-up — the `pidAlive` stub is GONE.** #1137 left `checkStale()` returning `pidAlive: null` as a shape-compatible placeholder. It was removed outright: measured @ `f0766e1`, zero production readers repo-wide, so the field only invited a reader to treat `null` as "unknown liveness" — a question this code no longer asks. `checkStale()` now returns `isLive` (the verdict) and `heartbeatAgeMinutes` (the magnitude behind it); anything reasoning about a lock's liveness reads those two. `isPidAliveOnHost` stays exported for `file-lock.mjs` and `lock-reaper.mjs`, where the pid IS the process being asked about.
+
+`isPidAliveOnHost` remains exported from `session-lock.mjs` and is unaffected — `file-lock.mjs` and `lock-reaper.mjs` are legitimate callers, because there the pid IS the process being asked about.
+
 ### Schema v1 → v2 backward-compat
 
 Readers (e.g., `readLock()` in `session-lock.mjs`, `discoverActiveSessions()`) MUST tolerate absent `last_heartbeat` and `semantic_session_id` fields (v1 locks written before Epic #583). When `last_heartbeat` is absent, fall back to TTL-based expiry from `started_at`. When `semantic_session_id` is absent, treat as unknown.

package/skills/autopilot/SKILL.md

@@ -206,7 +206,11 @@ const modeSelector = async () => {
   // Each iteration rebuilds signals from current disk state. STATE.md will be
   // freshly idle-reset by the previous /close, sessions.jsonl will have the
   // new tail entry, etc. This is the contract: live signals every iteration.
-  const signals = await buildLiveSignals({ backlogLimit: 50 });
+  // `repoRoot` is passed explicitly (#1071) rather than left to the helper's
+  // cwd default. Do NOT hand-write a `backlogLimit` here — the window default
+  // lives once, in backlog-scan.mjs (`DEFAULT_BACKLOG_LIMIT`); see
+  // skills/session-start/phase-7-5-mode-selector.md for the same contract.
+  const signals = await buildLiveSignals({ repoRoot: process.cwd() });
   return selectMode(signals);
 };
 

package/skills/bootstrap/SKILL.md

@@ -19,7 +19,7 @@ description: >
 
 This skill runs when the Bootstrap Gate is closed (missing CLAUDE.md, Session Config, or `.orchestrator/bootstrap.lock`) or when the user invokes `/bootstrap` directly. It scaffolds the minimum structure required by all session-orchestrator skills, commits it, and writes the lock file that opens the gate for all future invocations.
 
-**Anti-bureaucracy contract:** At most ONE `AskUserQuestion` call in the normal case (tier confirmation). A second question is only asked when the archetype is truly ambiguous on the Public Path for Standard/Deep tiers. No wizard, no multi-step flow.
+**Anti-bureaucracy contract:** On a first-time full bootstrap (no tier flags, no `--no-interview`), expect **7–9** `AskUserQuestion` prompts in three fixed blocks — not an open-ended wizard. (1) **Tier/stack** (Phase 2): one tier-confirmation question, plus an optional second archetype question when `PATH_TYPE = public` and archetype confidence is low (Standard/Deep only). (2) **Owner persona** (Phase 3.5): five questions from `scripts/lib/owner-interview.mjs` (first-run only). (3) **Dispatcher autonomy** (Phase 3.5.1): one question from `scripts/lib/config/dispatcher-autonomy-capture.mjs`. Flagged flows (`--upgrade`, `--retroactive`, `--sync-rules`, `--ecosystem-health`) and `--no-interview` skip some or all of these blocks.
 
 ## Invocation Context
 
@@ -79,7 +79,6 @@ AskUserQuestion({
     question: "Leeres Repo erkannt. Basierend auf '<HEURISTIC_REASON>' empfehle ich **<RECOMMENDED_TIER>**. Passt das?",
     header: "Bootstrap",
     options: [
-      { label: "<RECOMMENDED_TIER> (Empfohlen)", description: "<one-line description of what this tier scaffolds>" },
       { label: "fast", description: "Nur CLAUDE.md + .gitignore + README. Für Demos, Spikes, Playgrounds." },
       { label: "standard", description: "Fast + package.json/Manifest + TypeScript + Linting + Tests. Für MVPs und echte Produkte." },
       { label: "deep", description: "Standard + CI + CODEOWNERS + CHANGELOG. Für Production, Team, Langlebige Repos." },
@@ -90,6 +89,8 @@ AskUserQuestion({
 })
 ```
 
+Before rendering: append ` (Empfohlen)` to whichever of the three tier labels equals `<RECOMMENDED_TIER>`, and move that option to position 1. The recommended tier is one of the three — listing it a fourth time as its own option made five options, one more than `AskUserQuestion` accepts, and repeated the same choice twice.
+
 If user selects "Abbrechen": stop. Report "Bootstrap abgebrochen. Kein Kommando wird ausgeführt." Do not continue.
 
 Store confirmed tier as `CONFIRMED_TIER`.
@@ -119,7 +120,7 @@ AskUserQuestion({
 })
 ```
 
-Store as `CONFIRMED_ARCHETYPE`. Maximum interactions in bootstrap flow: **2 questions total**.
+Store as `CONFIRMED_ARCHETYPE`. The tier/stack block contributes **1–2** questions; a first-run full bootstrap adds **6 more** from the owner interview (Phase 3.5, five questions) and dispatcher-autonomy capture (Phase 3.5.1, one question) — **7–9 total**.
 
 ## Upgrade Flow (`--upgrade <tier>`)
 
@@ -585,7 +586,7 @@ If invoked directly via `/bootstrap`: report the created files list and stop.
 
 - **NEVER create application code during bootstrap** — only structural files (CLAUDE.md, .gitignore, README.md, manifests, CI). The feature that follows brings its own implementation.
 - **NEVER skip the lock file write** — `.orchestrator/bootstrap.lock` is the gate's mechanical truth. Bootstrap without a lock file is incomplete.
-- **NEVER ask more than 2 questions** — even if the user's intent is unclear, make a best-effort recommendation and let the user correct via `/bootstrap --upgrade` later.
+- **Fixed question budget, no ad-hoc prompts** — tier/stack (1–2), owner interview (5, Phase 3.5), dispatcher-autonomy capture (1, Phase 3.5.1) sum to **7–9** on a first-run full bootstrap; `--no-interview` and flag short-circuits reduce this. Make a best-effort tier recommendation and let the user correct via `/bootstrap --upgrade` later — do not add prompts beyond these blocks.
 - **ALWAYS commit** — bootstrap ends with a git commit. The lock file is part of that commit.
 - **ALWAYS check for retroactive flag** — if `--retroactive` is in `$ARGUMENTS`, skip all scaffolding and jump directly to writing `bootstrap.lock` (tier inferred from existing file inventory, fallback: `fast`).
 - **NEVER abort bootstrap on rules-fetch failure** — rules-fetch is opt-in and best-effort. The legacy Clank sync path is the safety net.

package/skills/bootstrap/_shared-template.md

@@ -11,25 +11,34 @@
 
 ---
 
-## #parallel-sessions-rule — Step 3a: Install Parallel-Sessions Rule
+## #parallel-sessions-rule — Step 3a: Install Canonical Rules
 
-Write the vendored rule from `$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md` to `$REPO_ROOT/.claude/rules/parallel-sessions.md`.
+Vendor the canonical always-on rules from the plugin's `rules/` library into `$REPO_ROOT/.claude/rules/`. `rules/` is the single source of truth for every distributable rule — never `cp` a rule file from anywhere else (see "Why one writer" below).
 
-Idempotency:
+Idempotency is handled by the writer itself:
 - Missing → create
-- Exists and byte-identical → skip silently
-- Exists and differs → overwrite (vendored is canonical)
+- Exists, plugin-owned (first line is the `<!-- source: session-orchestrator plugin ... -->` header) and byte-identical → skip silently
+- Exists, plugin-owned and stale → overwrite (the plugin copy is canonical)
+- Exists WITHOUT that header → preserved untouched (a repo-private rule the operator authored)
 
 Shell:
 ```bash
-mkdir -p "$REPO_ROOT/.claude/rules"
-cp "$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md" "$REPO_ROOT/.claude/rules/parallel-sessions.md"
+mkdir -p "$REPO_ROOT/.claude"
+node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"
 cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"
 ```
 
-Why: PSA-003 destructive-command safeguards require every consumer repo to carry the rule. See issue #155. The `loop.md` vendor gives bare `/loop` a repo-aware maintenance prompt (issue #633 Hebel 3).
+The command prints a JSON report (`written` / `skipped` / `preserved` / `errors` / `warnings` / `sanitizer`) and exits non-zero on any error. Surface `errors[]` to the operator; a non-empty `preserved[]` is normal and means a repo-private rule was left alone.
 
-Note: This step runs before the baseline-fetch step (S99/D99). If that step executes and fetches a newer version of `parallel-sessions.md` from the baseline, the baseline version wins (S99 overwrites by design — acceptable).
+Also surface `sanitizer[]` (issue #1098) — `{file, line, kind, text}` records for citations that read fine inside the plugin repo and dangle once vendored (`repo-local-path`, `unresolvable-see-also`). The CLI additionally prints each one to stderr as `rules-sync: sanitizer <kind> <file>:<line> — <text>`. **Report it to the operator; do not act on it automatically** — the sanitizer never rewrites content and never changes the exit code, because silently stripping a citation would change a rule's meaning at vendoring time. A human decides whether the citation is a leak.
+
+Archetype-scoped entries in `rules/_index.md` resolve from `.orchestrator/bootstrap.lock`, which does not exist yet at this step — they report `archetype-unknown` and are skipped. The always-on rules (including `parallel-sessions.md`) are universal and vendor regardless. Re-run `/bootstrap --sync-rules` after the lock is written to pick up the archetype-scoped ones.
+
+Why: PSA-003 destructive-command safeguards require every consumer repo to carry the parallel-sessions rule. See issue #155. The `loop.md` vendor gives bare `/loop` a repo-aware maintenance prompt (issue #633 Hebel 3).
+
+Why one writer (issue #1060): a literal `cp` from a second source directory bypasses the pre-write validator AND lands a file carrying no provenance header. On the next `--sync-rules` a headerless file is classified as a repo-private override and preserved forever — so the plugin can never update it again, and whichever rival copy is smaller silently wins. `rules/` is the only source with a manifest, archetype scoping, a basename-collision guard and a pre-write validator, so it is the only sanctioned writer to `.claude/rules/`.
+
+Note: This step runs before the baseline-fetch step (S99/D99), and S99 must NOT overwrite a rule that `rules/` owns. The baseline's copy carries no provenance header, so letting it win would permanently mark the target as a repo-private override — the exact failure described above. `.claude/rules/parallel-sessions.md` has therefore been removed from the S99 manifest. Any other basename present in BOTH `rules/_index.md` and the S99 manifest has the same defect and needs the same treatment.
 
 ---
 
@@ -133,7 +142,6 @@ if [[ -n "$BASELINE_REF" && -n "${GITLAB_TOKEN:-}" && -n "${GITLAB_HOST:-}" && -
 .claude/rules/swift.md
 .claude/rules/mvp-scope.md
 .claude/rules/cli-design.md
-.claude/rules/parallel-sessions.md
 .claude/rules/ai-agent.md
 .claude/rules/claude-code-usage.md
 MANIFEST

package/skills/bootstrap/deep-template.md

@@ -492,14 +492,18 @@ If the call fails, log the structured message above and continue. Raw API respon
 
 Canonical implementation in [`_shared-template.md#parallel-sessions-rule`](_shared-template.md).
 
-Write the vendored rule from `$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md` to
-`$REPO_ROOT/.claude/rules/parallel-sessions.md` (idempotent: missing→create, identical→skip,
-differs→overwrite). The shared partial also runs
+Run `node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"` — it vendors every
+rule registered in `rules/_index.md` (idempotent: missing→create, identical→skip, differs→overwrite),
+and it is the only writer that applies the pre-write validator, the basename-collision guard and the
+copy-on-write branch that preserves repo-private rules. The shared partial also runs
 `cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"` so bare `/loop` gets a
-repo-aware maintenance prompt. See shared partial for full shell command. Issues #155, #633.
+repo-aware maintenance prompt. See shared partial for full shell command. Issues #155, #633, #1060.
 
-Note: Runs before D99. If D99 (via inherited S99) fetches a newer `parallel-sessions.md` from
-the baseline, the baseline version wins (acceptable — S99 is canonical).
+Note: Runs before D99. D99 (via inherited S99) no longer fetches `parallel-sessions.md` from the
+baseline — that entry was removed from the S99 manifest in #1060. The baseline copy carries no
+provenance header, so letting it win would make the next `--sync-rules` classify the target as a
+repo-private override and preserve it permanently, i.e. the plugin could never update that rule
+again. `rules/` is the single source for it.
 
 ## Step 3b: Initialize .orchestrator/metrics/ (Deep) (#185)
 

package/skills/bootstrap/fast-template.md

@@ -162,23 +162,30 @@ build/
 
 Note: `.orchestrator/` is NOT gitignored — `bootstrap.lock` must be committed. Only the platform state dirs (`.claude/`, `.codex/`, `.cursor/`) are excluded.
 
-## Step 3a: Install Parallel-Sessions Rule
+## Step 3a: Install Canonical Rules
 
-Write the vendored rule from `$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md` to `$REPO_ROOT/.claude/rules/parallel-sessions.md`.
+Vendor the canonical always-on rules from the plugin's `rules/` library into `$REPO_ROOT/.claude/rules/`. `rules/` is the single source of truth for every distributable rule — never `cp` a rule file from anywhere else.
 
-Idempotency:
+Idempotency is handled by the writer itself:
 - Missing → create
-- Exists and byte-identical → skip silently
-- Exists and differs → overwrite (vendored is canonical)
+- Exists, plugin-owned (first line is the `<!-- source: session-orchestrator plugin ... -->` header) and byte-identical → skip silently
+- Exists, plugin-owned and stale → overwrite (the plugin copy is canonical)
+- Exists WITHOUT that header → preserved untouched (a repo-private rule the operator authored)
 
 Shell:
 ```bash
-mkdir -p "$REPO_ROOT/.claude/rules"
-cp "$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md" "$REPO_ROOT/.claude/rules/parallel-sessions.md"
+mkdir -p "$REPO_ROOT/.claude"
+node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"
 cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"
 ```
 
-Why: PSA-003 destructive-command safeguards require every consumer repo to carry the rule. See issue #155. The `loop.md` vendor gives bare `/loop` a repo-aware maintenance prompt (issue #633 Hebel 3).
+The command prints a JSON report (`written` / `skipped` / `preserved` / `errors` / `warnings` / `sanitizer`) and exits non-zero on any error. At fast tier `.orchestrator/bootstrap.lock` does not exist yet (Step 5 writes it), so archetype-scoped entries report `archetype-unknown` and are skipped — the always-on rules vendor regardless.
+
+Surface `errors[]` and `sanitizer[]` to the operator. `sanitizer[]` (issue #1098) carries `{file, line, kind, text}` records for citations that read fine inside the plugin repo and dangle once vendored (`repo-local-path`, `unresolvable-see-also`); the CLI also prints each to stderr as `rules-sync: sanitizer <kind> <file>:<line> — <text>`. **Report it, do not act on it automatically** — it never rewrites content and never changes the exit code, so a human decides whether the citation is a leak.
+
+Why: PSA-003 destructive-command safeguards require every consumer repo to carry the parallel-sessions rule. See issue #155. The `loop.md` vendor gives bare `/loop` a repo-aware maintenance prompt (issue #633 Hebel 3).
+
+Why one writer (issue #1060): a literal `cp` from a second source directory bypasses the pre-write validator AND lands a file carrying no provenance header. On the next `--sync-rules` a headerless file is classified as a repo-private override and preserved forever, so the plugin can never update it again — and whichever rival copy is smaller silently wins.
 
 ## Step 4: Generate README.md
 

package/skills/bootstrap/standard-template.md

@@ -592,14 +592,18 @@ indent_size = 2
 
 Canonical implementation in [`_shared-template.md#parallel-sessions-rule`](_shared-template.md).
 
-Write the vendored rule from `$PLUGIN_ROOT/templates/_shared/rules/parallel-sessions.md` to
-`$REPO_ROOT/.claude/rules/parallel-sessions.md` (idempotent: missing→create, identical→skip,
-differs→overwrite). The shared partial also runs
+Run `node "$PLUGIN_ROOT/scripts/lib/rules-sync.mjs" --repo-root "$REPO_ROOT"` — it vendors every
+rule registered in `rules/_index.md` (idempotent: missing→create, identical→skip, differs→overwrite),
+and it is the only writer that applies the pre-write validator, the basename-collision guard and the
+copy-on-write branch that preserves repo-private rules. The shared partial also runs
 `cp "$PLUGIN_ROOT/templates/_shared/loop.md" "$REPO_ROOT/.claude/loop.md"` so bare `/loop` gets a
-repo-aware maintenance prompt. See shared partial for full shell command. Issues #155, #633.
+repo-aware maintenance prompt. See shared partial for full shell command. Issues #155, #633, #1060.
 
-Note: Runs before S99. If S99 fetches a newer `parallel-sessions.md` from the baseline, the
-baseline version wins (acceptable — S99 is canonical).
+Note: Runs before S99. S99 no longer fetches `parallel-sessions.md` from the baseline — that entry
+was removed from the S99 manifest in #1060. The baseline copy carries no provenance header, so
+letting it win would make the next `--sync-rules` classify the target as a repo-private override and
+preserve it permanently, i.e. the plugin could never update that rule again. `rules/` is the single
+source for it.
 
 ## Step 3b: Initialize .orchestrator/metrics/ (#185)