session-orchestrator 3.22.0 → 3.24.0

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

@@ -143,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 `readProcessLocalSessionIds()` + `classifyManifestSession()` (`scripts/lib/session-identity/own-session.mjs`) — process-local tiers only (hook payload, `CLAUDE_CODE_SESSION_ID`), never the repo-global `session.lock`, which is shared by every session in the checkout and made a peer's manifest read `own` (#1194):
+
+- **`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
@@ -237,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
 
@@ -120,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>`)
 
@@ -586,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)
 

package/skills/claude-md-drift-check/checker.mjs

@@ -910,11 +910,18 @@ function main() {
   //   kebab(s) = s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
   //
   // WARN (never error) when:
-  //   - learnings.jsonl is present AND no entry's derived key matches the rule's
-  //     `learning-key` (absent learning), OR
+  //   - NEITHER a learnings.jsonl entry NOR a valid `evidence-digest` frontmatter
+  //     scalar is present (the rule's provenance is unresolvable), OR
   //   - the matching entry's `expires_at` < now (expired learning).
-  // When learnings.jsonl is absent, every key counts as absent — warn on each
-  // generated rule's key.
+  //
+  // #1101 — the digest branch. `.orchestrator/metrics/learnings.jsonl` is
+  // GITIGNORED, so in a fresh clone it does not exist and every generated rule
+  // used to warn (measured 2026-08-26: 23 of 23). A rule carrying a valid
+  // `evidence-digest: sha256-v1:<64 hex>` is SELF-CONTAINED — its `## Evidence`
+  // block plus its own `## Provenance` header fields re-derive the seal with no
+  // jsonl lookup — so its provenance is resolvable offline and it must not warn.
+  // The digest is EVIDENCE, not a second pointer; see
+  // `scripts/lib/reconcile/renderer.mjs` § computeEvidenceDigest.
   // The check is silently skipped (no id pushed) when .claude/rules/ is absent
   // or contains no .md files with auto-generated: true.
   if (!args.skipGeneratedRuleStaleness) {
@@ -926,15 +933,17 @@ function main() {
     // Reads the opening --- ... --- block from a markdown file.
     function extractFrontmatterFields(mdContent) {
       const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(stripLeadingRuleHeaderLines(mdContent));
-      if (!m) return { autoGenerated: false, learningKey: null, expiresAt: null };
+      if (!m) return { autoGenerated: false, learningKey: null, expiresAt: null, evidenceDigest: null };
       const block = m[1];
       const autoGenM = /^auto-generated:\s*(.+)$/m.exec(block);
       const learningKeyM = /^learning-key:\s*(.+)$/m.exec(block);
       const expiresAtM = /^expires-at:\s*(.+)$/m.exec(block);
+      const evidenceDigestM = /^evidence-digest:\s*(.+)$/m.exec(block);
       return {
         autoGenerated: autoGenM ? autoGenM[1].trim() === 'true' : false,
         learningKey: learningKeyM ? learningKeyM[1].trim() : null,
         expiresAt: expiresAtM ? expiresAtM[1].trim() : null,
+        evidenceDigest: evidenceDigestM ? evidenceDigestM[1].trim() : null,
       };
     }
 
@@ -955,12 +964,20 @@ function main() {
         relPath: relative(vaultDir, absPath),
         learningKey: fields.learningKey,
         expiresAt: fields.expiresAt,
+        evidenceDigest: fields.evidenceDigest,
       });
     }
 
     // No generated rules found → silently skip (don't push the check id).
     if (generatedRules.length === 0) return;
 
+    // #1101 — a LITERAL COPY of `EVIDENCE_DIGEST_RE` from
+    // `scripts/lib/reconcile/renderer.mjs`. Copied, not imported: this checker
+    // is a standalone skill script, and importing across the skill/script
+    // boundary would add real coupling for one 30-character literal. The two
+    // copies are pinned equal by `tests/lib/reconcile/renderer.test.mjs`.
+    const EVIDENCE_DIGEST_RE = /^sha256-v1:[0-9a-f]{64}$/;
+
     // Slugify function mirroring emitter.mjs `kebab()`.
     const kebab = (s) =>
       String(s)
@@ -1001,26 +1018,37 @@ function main() {
     const nowMs = Date.now();
 
     for (const rule of generatedRules) {
-      const { relPath, learningKey, expiresAt } = rule;
+      const { relPath, learningKey, expiresAt, evidenceDigest } = rule;
 
       // If we cannot evaluate the key (no learning-key frontmatter), skip
       // silently — avoid false positives on malformed rules.
       if (!learningKey) continue;
 
-      if (!learningsPresent || !knownKeys.has(learningKey)) {
-        // Learning is absent from learnings.jsonl (or the file is missing entirely).
+      const hasJsonlEntry = learningsPresent && knownKeys.has(learningKey);
+      const hasValidDigest =
+        typeof evidenceDigest === 'string' && EVIDENCE_DIGEST_RE.test(evidenceDigest);
+
+      if (!hasJsonlEntry && !hasValidDigest) {
+        // NEITHER resolution path is available: the learning is absent from
+        // learnings.jsonl (or the file is missing entirely) AND the rule carries
+        // no self-contained evidence digest, so nothing can vouch for it.
         warnings.push({
           check: 'generated-rule-staleness',
           file: relPath,
           line: 1,
-          message: `Auto-generated rule references learning-key '${learningKey}' which is absent from .orchestrator/metrics/learnings.jsonl`,
+          message: `Auto-generated rule references learning-key '${learningKey}' which is absent from .orchestrator/metrics/learnings.jsonl, and the rule carries no valid evidence-digest to verify it offline`,
           extracted: learningKey,
         });
         continue;
       }
 
-      // Learning exists — check expiry.
-      const storedExpiresAt = knownKeys.get(learningKey);
+      // Provenance resolves — check expiry.
+      // `storedExpiresAt` is only meaningful when the jsonl entry actually
+      // exists. A digest-only rule (fresh clone, or a learning aged out of the
+      // store) is AUTHORITATIVE FOR ITS OWN EXPIRY via frontmatter; reading a
+      // stored value that is not there would make `expiryStr` null and silently
+      // skip the expiry gate for a rule that has a perfectly good `expires-at`.
+      const storedExpiresAt = hasJsonlEntry ? knownKeys.get(learningKey) : null;
       // Prefer the frontmatter expires-at on the rule file; fall back to the
       // stored expires_at from the learning entry (both should agree, but the
       // rule file is authoritative for its own expiry).

package/skills/contract-version-bump/SKILL.md

@@ -131,7 +131,7 @@ schema, so nobody double-checks the actual runtime behavior, and invalid data pa
 undetected.
 
 Reference case: `maxLength: 63` was the natural way to express S3 bucket-name limits. The
-downstream validator (`aiat-poc-infra/scripts/estate/validate-estate-yaml.sh`) is a hand-written
+downstream validator (`aiat-poc-infra/scripts/estate/validate-estate-yaml.sh`) <!-- path-check: historical --> is a hand-written
 JSON-Schema mini-interpreter that does not implement `maxLength` — it would have parsed the
 schema, not recognized the keyword, and silently done nothing, so a 200-character bucket name
 would still validate green. Decision: extend the consumer (option 1) rather than relying only on

package/skills/dispatcher/SKILL.md

@@ -113,7 +113,7 @@ const res = claimRepo({ repoRoot: R, sessionId, mode, ttlHours, semanticSessionI
 Or reuse the primitive directly: `acquire({ sessionId, mode, ttlHours, repoRoot, semanticSessionId })` from `scripts/lib/session-lock.mjs`. The claim is a `linkSync` create-or-fail = **atomic**.
 
 - **`ok: true`** → the claim is held. Proceed to Phase 4.
-- **`ok: false`** (race lost / busy — reasons: `active`, `stale-pid-alive`, `stale-pid-dead`, `fs-error`, …) → **exclude R**, re-rank the remaining free candidates (drop R from `free`, re-run Phase 1's rank step), and re-present Phase 2. Loop until a claim succeeds or no free candidate remains (then Phase 5).
+- **`ok: false`** (race lost / busy — reasons: `active`, `stale-heartbeat`, `fs-error`, …) → **exclude R**, re-rank the remaining free candidates (drop R from `free`, re-run Phase 1's rank step), and re-present Phase 2. Loop until a claim succeeds or no free candidate remains (then Phase 5).
 
 Do NOT reinvent the claim — always go through `claimRepo`/`acquire`. The `ok:false` path is the load-bearing concurrency guard: two parallel dispatchers can both recommend R, but only one wins the `linkSync`; the loser must re-rank, never force.
 

package/skills/ecosystem-health/SKILL.md

@@ -24,7 +24,10 @@ For harness < 2.1.105 (no monitor support), the skill's manual probes documented
 
 This skill reads from the project's `## Session Config` section in the platform instruction file:
 
-- **`health-endpoints`** — list of `{name, url}` objects for service health checks
+- **`health-endpoints`** — list of `{name, url}` objects for service health checks. Parsed
+  content-scoped by `scripts/lib/config/health-endpoints.mjs` (#1174), which accepts the nested
+  block form this wizard writes (below), an inline object array, and a bare list of URLs — see
+  `docs/session-config-reference.md` § VCS & Infrastructure for the full form table.
 - **`cross-repos`** — list of related repositories for critical issue scanning
 
 Both fields are optional. The skill degrades gracefully when either is missing. On Codex this means `AGENTS.md`; on Claude/Cursor it means `CLAUDE.md`.

package/skills/ecosystem-health/wizard.md

@@ -128,6 +128,11 @@ ecosystem-health:
 the block is NOT overwritten. The wizard prints "Skipped (already present)" and
 exits 0. Re-run to edit: remove the existing block first, then re-run.
 
+This nested `health-endpoints:` block (an indented list under a valueless header) is now parsed
+content-scoped by `scripts/lib/config/health-endpoints.mjs` (#1174) — before that fix the flat
+key/value reader bailed to `null` the moment it saw the `{`/nested-list shape this wizard writes,
+so the block above wrote successfully but the ecosystem-health skill silently never saw it.
+
 ### 4b — `.orchestrator/policy/ecosystem.json`
 
 ```json

package/skills/evolve/SKILL.md

@@ -34,6 +34,8 @@ Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills
 
 ## Phase 1: Config & Data Loading
 
+**Telemetry start marker (#1200):** note the current wall-clock time before Step 1.1 runs (e.g. `date +%s%3N`, or the coordinator's own turn-start instant). Every `orchestrator.evolve.completed` emit in Phase 1 / Phase 3 below reports `duration_ms` (placeholder `DURATION_MS`) as the elapsed milliseconds since this marker — same in-memory-value convention as `CT`/`AC`/`ASK`/`DROP` in `skills/session-end/SKILL.md`'s `orchestrator.handover.gated` emits.
+
 ### 1.1 Read Session Config
 
 Read and parse Session Config per `skills/_shared/config-reading.md`. Store result as `$CONFIG`.
@@ -44,6 +46,13 @@ Extract `persistence` from `$CONFIG`. If `persistence` is `false`, abort with me
 
 > "Learnings require persistence to be enabled in Session Config. Add `persistence: true` to your Session Config block (CLAUDE.md for Claude Code, AGENTS.md for Codex CLI)."
 
+**Telemetry on abort (#1200):** before stopping, emit the abort form of the run-completion event:
+
+```bash
+node scripts/emit-event.mjs --type orchestrator.evolve.completed --payload \
+  "$(node -e "process.stdout.write(JSON.stringify({aborted: 'persistence-disabled', reason: 'Learnings require persistence to be enabled in Session Config.'.slice(0,300), duration_ms: DURATION_MS}))")"
+```
+
 ### 1.3 Determine Mode
 
 Read mode from `$ARGUMENTS`:
@@ -91,7 +100,12 @@ Extract learnings from session history.
 - Read all entries from `.orchestrator/metrics/sessions.jsonl` (or `<state-dir>/metrics/sessions.jsonl` if the v2 path does not exist — see Phase 1.4 fallback)
 - Parse each JSONL line as JSON
 - Sort by `completed_at` descending (most recent first)
-- If no sessions found, abort: "No session data available. Complete at least one session before running evolve."
+- If no sessions found, abort: "No session data available. Complete at least one session before running evolve." **Telemetry on abort (#1200):** before stopping, emit:
+
+  ```bash
+  node scripts/emit-event.mjs --type orchestrator.evolve.completed --payload \
+    "$(node -e "process.stdout.write(JSON.stringify({aborted: 'no-session-data', reason: 'No session data available. Complete at least one session before running evolve.'.slice(0,300), duration_ms: DURATION_MS}))")"
+  ```
 
 ### Step 3.1b: Read Extra Sources (#638)
 
@@ -380,6 +394,13 @@ For confirmed learnings, use atomic rewrite strategy:
 
 Report: "Saved N new learnings, updated M existing. Total active: K."
 
+**Telemetry (#1200):** emit the run-completion event as the last action of this step, using the counts already computed above — `N` (Step 3.5(4) new-learnings count) → `appended`, `M` (Step 3.5(2) reinforced-existing count) → `boosted`, `$PRUNE.archived` (the sweep CLI's returned total, Step 3.5(5)) → `pruned`. `promoted` is always `0` from THIS call site: promotion to `public` scope is the separate `npm run share:hw-learnings -- --promote` CLI, never invoked by `/evolve analyze` itself — see `docs/events-schema.md`. All four counters are ALWAYS present, including as `0`:
+
+```bash
+node scripts/emit-event.mjs --type orchestrator.evolve.completed --payload \
+  "$(node -e "process.stdout.write(JSON.stringify({appended: N, boosted: M, pruned: PRUNED, promoted: 0, duration_ms: DURATION_MS}))")"
+```
+
 ### Step 3.6: C2 Auto-Repair Feeder (opt-in — #647)
 
 > **Default OFF (advisory-only).** With no `skill-evolution:` block in Session Config, this step surfaces repair candidates as ADVICE only — it applies nothing and opens no MR. This mirrors the opt-in precedent of `slopcheck` (#520) and `verification-auto-fix` (#521): the engine is dark unless explicitly enabled.
@@ -542,6 +563,8 @@ N active learnings (M high confidence, K expiring soon)
 
 Single-pass LLM derivation of USER.md + AGENT.md (peer cards from #503) updates from current learnings + sessions + steering files. Dry-run-default per #506 EARS contract.
 
+**Telemetry start marker (#1200):** note the current wall-clock time at Phase 6 entry (`DURATION_MS` in the Step 6.4/6.5 emits below is the elapsed milliseconds since this marker) — same placeholder convention as `skills/session-end/SKILL.md`'s `orchestrator.handover.gated` emits.
+
 ### Step 6.0: Argument Parsing
 
 Parse `$ARGUMENTS` for trailing flags after the `dialectic` keyword:
@@ -603,6 +626,13 @@ const result = await runDialecticDeriver({
 - If `--apply`: call `mergePeerCard(existingBody, managedUpdates)` from `scripts/lib/peer-cards/merger.mjs` for each card target, then `writePeerCard(repoRoot, 'user', mergedUserCard)` and `writePeerCard(repoRoot, 'agent', mergedAgentCard)` from `scripts/lib/peer-cards/writer.mjs`. Update the `updated:` frontmatter.
 - Report: `Dialectic-derived: M deltas to USER.md, N deltas to AGENT.md. Dry-run | Applied. Tokens: in=<X> out=<Y>.`
 
+**Telemetry (#1200):** immediately after the report line above, emit the success form (`mode` mirrors which branch ran):
+
+```bash
+node scripts/emit-event.mjs --type orchestrator.dialectic.completed --payload \
+  "$(node -e "process.stdout.write(JSON.stringify({mode: 'MODE', user_deltas: M, agent_deltas: N, tokens_in: X, tokens_out: Y, duration_ms: DURATION_MS}))")"
+```
+
 ### Step 6.5: Error Handling
 - `status: 'unknown-model'` → fail with clear error (already thrown by validateModel)
 - `status: 'budget-exceeded'` → emit `{status:'budget-exceeded', used:N, budget:M}`, do NOT truncate
@@ -610,6 +640,13 @@ const result = await runDialecticDeriver({
 - `status: 'empty-input'` → exit clean with message "dialectic: skipped (no input)"
 - subagent crash → log ⚠, exit cleanly (do NOT write to `.orchestrator/dialectic-pending.md`)
 
+**Telemetry (#1200):** for EACH outcome above, before exiting, emit `orchestrator.dialectic.completed` in its abort form — `SLUG` is `unknown-model` \| `budget-exceeded` \| `would-empty-card` \| `empty-input` \| `subagent-crash` respectively (the subagent-crash case has no `runDialecticDeriver` status of its own; use the literal slug `subagent-crash`):
+
+```bash
+node scripts/emit-event.mjs --type orchestrator.dialectic.completed --payload \
+  "$(node -e "process.stdout.write(JSON.stringify({aborted: 'SLUG', duration_ms: DURATION_MS}))")"
+```
+
 Cross-reference: PRD #506 AC1-AC4 + EARS gates. Vault Integration: dialectic does NOT mirror to vault (#506 scope — peer cards are repo-local by design; vault mirror is for cross-repo sessions/learnings).
 
 ---