session-orchestrator 5.3.0 → 5.5.0

package/skills/_shared/fleet-protocol.md

@@ -0,0 +1,134 @@
+# Fleet Protocol v1 — Dateien statt Nachrichten (#1462)
+
+Generic contract note for every session-orchestrator session (Claude Code, Codex, headless) that
+may run beside a fleet coordinator ("navigator"). It is a reference, **not a rule**: nothing under
+`.claude/rules/**` loads it; session-start Phase 7.6 and the operations-contract peer preflight
+point here. The mechanics live in code — `scripts/lib/fleet-protocol.mjs` is the only place that
+knows paths, fields, deadlines and lease validity; `scripts/fleet-checkin.mjs` writes the check-in.
+This file describes them and never redefines them. The coordinator itself is not part of this
+package: it is operated outside the plugin, which owns its operational detail (how it measures,
+which conditions it issues, how it acquires and hands over the lease).
+
+**Grundsatz (CSM-003).** Zustand liegt in Dateien; Nachrichten sind nur Hinweise auf eine Datei.
+Der Navigator erteilt keine Freigaben — maßgeblich ist der Owner-Auftrag der Session. Eine Datei,
+die fehlt, heißt „nicht nachweisbar", nie „nicht vorhanden": eine fehlende Lease ist kein freies
+Feld, sondern ein Zustand ohne Beleg.
+
+## Verzeichnis und Dateiform
+
+- Wurzel `~/.config/navigator/`, Override `NAVIGATOR_CONFIG_DIR` (getrimmt; leer oder nur
+  Whitespace zählt als nicht gesetzt). Code: `navigatorDir()`. Ein Override zeigt nur auf ein
+  eigenes Verzeichnis mit Modus 0700, nie auf einen geteilten Ort: wer dort schreiben kann, kann
+  eine „aktive" Lease vortäuschen.
+- Verzeichnisse Modus `0700`, Dateien Modus `0600`. Schreiben immer atomar (tmp-Datei im
+  Zielverzeichnis, dann `rename`).
+- Zeiten in Check-in und Lease stehen in UTC mit `Z`; eine Zeit ohne `Z` oder mit Offset ist dort
+  ungültig. Die Form hängt an der Datei: Nur der Check-in trägt `zeit`, in Sekunden wie `date -u +%FT%TZ`
+  (`YYYY-MM-DDTHH:MM:SSZ`), gesetzt von der CLI, nie geschätzt, nie aus einer anderen Uhr (Code:
+  `utcSecondsTimestamp()`). Die Lease trägt `seit` und `laeuft_ab` in Sekunden oder Millisekunden
+  (Tabelle unten, Code: `LEASE_TS_RE`). Inhalt und Form der Auflagen gehören dem Navigator.
+- Dateinamen aus einer `session_id` sind pfadsicher: nur `[A-Za-z0-9._-]`, 1–128 Zeichen, nicht
+  `.` oder `..`, kein `/`. Code: `isSafeSessionId()`; `checkinPath()` und `auflagenPath()` werfen
+  sonst.
+- Tests berühren das echte Verzeichnis nie: `tests/setup/navigator-dir-guard.mjs` setzt
+  `NAVIGATOR_CONFIG_DIR` je vitest-Worker auf ein tmp-Verzeichnis.
+
+## `leases/navigator.json` — genau ein aktiver Navigator
+
+| Feld | Inhalt |
+|---|---|
+| `session_id` | Registry-ID des Navigators (Pflicht; pfadsicher wie oben) |
+| `plattform` | `claude` \| `codex` \| `kopflos` (Pflicht) |
+| `adresse` | `ListAgents`-Name, wenn Claude (`[A-Za-z0-9._:@-]`, 1–128 Zeichen); sonst `null` |
+| `seit` | Zeit des Erwerbs, UTC mit `Z`, Sekunden oder Millisekunden (Pflicht) |
+| `laeuft_ab` | UTC mit `Z`, gleiche Form; nach diesem Zeitpunkt ist die Lease abgelaufen (Pflicht) |
+| `uebergabe_an` | `null` oder Session-ID des Nachfolgers |
+
+**„Aktiv" heißt ausschließlich: gültige Lease.** `readNavigatorLease()` liefert genau eines von
+`active` (Datei lesbar, Pflichtfelder da, `laeuft_ab` in der Zukunft), `none` (Datei fehlt oder
+`laeuft_ab` überschritten) oder `unreadable` (kaputtes JSON, fehlende Pflichtfelder, Lesefehler,
+oder ein Feld außerhalb der Tabellenform: unbekannte `plattform`, Steuerzeichen in
+`session_id`/`adresse`, eine Zeit ohne `Z` oder mit Offset — sie würde in lokaler Zeit gelesen und
+könnte die Lease verlängern). Unlesbar oder abgelaufen ist **nie** aktiv (fail-closed).
+Registry-Heartbeat (`role: navigator`, `scripts/lib/session-registry.mjs`) und `ListAgents` sind
+Zusatzsignale, keine Lebendbeweise. Dieses Paket liest die Lease nur (SessionStart-Banner,
+`fleet-checkin.mjs`); Erwerb, Erneuerung und Übergabe liegen beim Navigator.
+
+## `checkin/<session_id>.json` — Session an Navigator
+
+**Schreibend** heißt: Änderung an Repo-Inhalt oder VCS-Zustand (Datei im Arbeitsbaum außerhalb
+`.orchestrator/` und `.claude/`, Commit, Branch, Push, MR, Issue, Kommentar). SO-eigener
+Sitzungszustand zählt nicht: Phase 1.1 (CLAUDE.md-Migration, einmalig), 1.2 `session.lock`, 1.5
+`STATE.md`, 1.6 Metriken, 1.7 Live-Status-Board. Phase 1.1 ist eine Repo-Datei und wird deshalb
+als Ausnahme im Check-in genannt (`vorab_geschrieben`). (`CLAUDE.md` heißt auf Codex CLI `AGENTS.md`, siehe
+`skills/_shared/instruction-file-resolution.md`.)
+
+Der Check-in liegt **vor der ersten schreibenden Aktion** (Phase 7.6, oder der Peer-Preflight der
+Operations-Route). Schreiber: `node scripts/fleet-checkin.mjs` liest das JSON von stdin, setzt
+`zeit` (überschreibt immer), validiert (`validateCheckin()`), schreibt atomar mit Modus 0600 und
+emittiert `orchestrator.fleet.checkin` (Payload `session`, `repo`, `modus`, `kandidaten`,
+`navigator_state` — keine Pfade, keine Quota, kein `auftrag_ref`). stdout: eine JSON-Zeile
+`{ ok, path, navigator_state, navigator_adresse, fallback_due_at, event }`; `navigator_adresse` ist
+die vom Lease-Validator akzeptierte `adresse` einer aktiven Lease, sonst `null` (keine aktive
+Lease, kein Eintrag oder ein abgelehnter Wert — nie ein ungeprüfter String). `fallback_due_at` ist
+der Zeitpunkt, ab dem die Standard-Auflagen (unten) gelten, in der Form von `zeit` (Code:
+`fallbackDueAt()`); er steht nur auf stdout, die Check-in-Datei behält ihr Schema. Exit 0
+geschrieben, 2 ungültige Eingabe (Fehlerliste auf stderr, keine Datei), 1 Schreibfehler.
+
+| Feld | Inhalt |
+|---|---|
+| `session` | Registry-ID aus `.orchestrator/current-session.json`, pfadsicher (Pflicht) |
+| `plattform` | `claude` / `codex` / `kopflos` (Pflicht) |
+| `repo` | Repo-Name `name` oder `gruppe/name`, nie ein Pfad (Pflicht) |
+| `repo_id`, `worktree` | String oder `null`; Worktree `true`/`false` |
+| `modus` | `housekeeping` / `feature` / `deep` / `operations` (Pflicht) |
+| `auftrag_ref` | Pfad der Auftragsdatei oder „Owner-Chat <zeit>" mit Wortlaut in einem Satz (Pflicht) |
+| `konto_slot`, `quota` | Zahl, String oder `null`; Quota als String, sonst `nicht messbar` |
+| `stand` | Objekt: main-, origin/main-, Prod-SHA (sonst `nicht messbar`), offene MRs |
+| `kandidaten` | höchstens 64 Issue-Nummern (`42` oder `"#42"`) (Pflicht) |
+| `schreibbereich` | Liste von Verzeichnissen/Dateien als Strings (Pflicht) |
+| `bedarf` | Objekt: geplante volle Pipelines, Remote-Offload-Jobs, prozessstartende Agents |
+| `vorab_geschrieben` | Liste der Ausnahmen nach der Definition oben |
+| `rueckfall` | Verhalten ohne Auflagen (unten), nicht leer (Pflicht) |
+| `zeit` | von der CLI gesetzt |
+
+Eine `SendMessage` an den Navigator ist optional und nur ein Hinweis auf die Datei: höchstens eine,
+nur wenn die Lease aktiv ist und `navigator_adresse` (stdout der Check-in-CLI) nicht `null` und per
+`ListAgents` erreichbar ist, und nur an genau diesen Namen; nie eine Antwort
+erwarten, nie darauf warten (CSM-004).
+
+## `auflagen/<session_id>.json` — Navigator an Session
+
+Bedingungen, die der Navigator einer Session schreibt (z. B. Agent-Caps, volle Pipelines je Repo,
+Offload-Regel, Merge- und Zeitregeln, Besitzkonflikte); Inhalt und Form gehören dem Navigator. Die
+Session **liest** die Datei; sie wartet auf keine Nachricht. Keine Auflage ist eine Freigabe.
+
+**Standard-Auflagen (konservative Stufe).** Sie gelten ab `fallback_due_at` (stdout der
+Check-in-CLI), wenn bis dahin keine Auflagen-Datei liegt. Die Frist rechnet `fallbackDueAt()`:
+`CHECKIN_FALLBACK_MIN` = 10 Minuten nach `checkin.zeit`, solange ein Navigator aktiv ist; ohne
+aktiven Navigator ist `fallback_due_at` gleich `zeit`, die Auflagen gelten also sofort:
+
+- Caps: 2 prozessstartende + 2 lesende Agents, solange der lokale Host ≥ 50 % Speicher frei hat.
+- Pipelines: ≤ 2 volle je Repo; Nachzug-Pushes vorher im Check-in (`bedarf`) benennen.
+- Offload: Heavy-Rollen (test, build, lint, audit) nur auf einen deklarierten Remote-Host, der
+  unmittelbar davor als bereit belegt ist (`skills/remote-offload/SKILL.md`); ohne Beleg kein neues
+  Offload. Lokal nur `vitest` bzw. `eslint` je Datei mit `timeout`.
+- Zeiten nur aus `date`.
+- Kein Merge ohne ausdrücklichen Owner-Auftrag, der Merge für genau dieses Repo nennt
+  (`auftrag_ref`).
+
+Lesende Arbeit und Schreiben im eigenen Worktree laufen währenddessen weiter; der Rückfall ist ein
+Dateistand mit Frist, kein Warten auf eine Antwort.
+
+## Verhalten ohne Navigator
+
+Lease `none` oder `unreadable`: die Check-in-Datei wird **trotzdem** geschrieben (sie ist der
+zählbare Beleg), die Standard-Auflagen gelten sofort, es geht keine Nachricht ab. Kopflose Läufe
+sind per Nachricht nicht erreichbar und nutzen dieselben Dateien: vor jeder Welle `auflagen/` lesen.
+
+## See Also
+
+`skills/session-start/SKILL.md` Phase 7.6 · `skills/session-start/references/operations-contract.md`
+(Peer-Preflight) · `skills/_shared/state-ownership.md` § Session Identity and Lock Ownership (`role`) ·
+`docs/events-schema.md` (`orchestrator.fleet.checkin`) · `.claude/rules/cross-session-messaging.md`
+(CSM-003/004) · `scripts/lib/fleet-protocol.mjs` · `scripts/fleet-checkin.mjs`

package/skills/_shared/state-ownership.md

@@ -104,6 +104,12 @@ layer.
   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.
+- **Registry `role` (`'navigator'`) is display, never ownership.** The
+  authoritative claim is the navigator lease (`leases/navigator.json` under
+  `~/.config/navigator/`, see `skills/_shared/fleet-protocol.md`); `registerSelf()`
+  does not carry the field across a repeated SessionStart, so a navigator
+  (operated outside this plugin) has to re-set it on every round via
+  `heartbeat(id, { role })` (#1462).
 
 The peer-discovery and issue-budget procedures below apply these rules at their
 narrow surfaces; neither creates a second ownership model.
@@ -245,8 +251,11 @@ The `.orchestrator/session.lock` file is written mechanically by `hooks/_lib/loc
 
 ```
 isAlive = (Date.now() - Date.parse(last_heartbeat)) < ttl_hours * 3600 * 1000
+          && Date.parse(last_heartbeat) <= Date.now() + 5 * 60 * 1000
 ```
 
+The second conjunct (#1494): a heartbeat stamped more than 5 minutes in the future is not live. Without it the age went negative and stayed below every TTL, so a hand-edited or clock-skewed lock held the repo until the wall clock caught up. The 5 minutes absorb a clock stepped back a little; the `category4.mjs` mirror carries the same guard.
+
 This replaces the v1 PID-liveness check (`process.kill(pid, 0)`) which was fundamentally broken because the recorded `pid` belongs to the ephemeral hook subprocess (dies in <1s), not the long-lived Claude coordinator process. The PostgreSQL pattern — use a heartbeat timestamp rather than PID to establish liveness — is the authoritative reference (see W1-D4 best-practices §1.5).
 
 ### #744 — heartbeat is the SOLE active gate (incident + fix)
@@ -272,23 +281,43 @@ The fix removes the question rather than re-answering it. `classifyExisting()` r
 
 `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
+### Schema v1 → v2 backward-compat — ENDED 2026-10-02 (#595)
+
+Lock readers no longer tolerate a v1 lock. A `session.lock` without `last_heartbeat` is foreign or damaged — no writer has produced one since Epic #583 (`buildLock()`, `hooks/_lib/lock-bootstrap.mjs` and `updateHeartbeat()` all set it) — and it is handled as **visible but not live**:
+
+- `parseLock()` returns it unchanged: still shape-valid (`isLockShape()` does not require `last_heartbeat`), so `readLockDetailed()` reports `ok` and the lock is never silently dropped.
+- `isLockLive()` and its stdlib-only mirror `lockIsLive()` in `scripts/lib/harness-audit/categories/category4.mjs` call it NOT live; there is no `started_at` fallback any more.
+- `heartbeatAgeMinutes` is `null` (no heartbeat, so no heartbeat age) in both `acquire()`'s result and `checkStale()`.
+- `acquire()` classifies it `stale-heartbeat`, so the SessionStart bootstrap reclaims it instead of the repo staying blocked for a TTL window that nothing heartbeats.
+
+Rejecting such a lock outright was considered and refused. At the time, a rejected lock made `readLock()` return `null`, the create-or-fail in `acquire()` hit `EEXIST` on the file still there, and the vanished-race branch answered `active` with `existingLock: null` on every attempt, so a lock nobody could see blocked every new session. That wedge is closed now (see **Corrupt lock** below), but rejecting would still hide the lock's `session_id`, host and `started_at` from every `readLock()` caller.
+
+`semantic_session_id` stays optional by schema, not as a v1 artefact: when absent, treat it as unknown.
+
+#### Schema v1 Sunset — decided 2026-10-02 (#595)
+
+**History.** The 90-day window from Epic #583 (target 2026-08-25) was evaluated on 2026-08-15 and the tolerance RETAINED. The blocker then was not v1 data but a second production copy of the rule (the `category4.mjs` mirror, pinned by `tests/lib/lock-ttl-parity.test.mjs` *for a v1 lock*) plus v1-shaped test fixtures: a removal attempt turned 18 tests red across 4 files.
+
+**Precondition, re-measured 2026-10-02 on this host (read-only):**
+
+- `find ~/Projects -maxdepth 4 -path '*/.orchestrator/session.lock'` → **8 files, 8/8 carry a non-empty `last_heartbeat`**.
+- `~/.config/session-orchestrator/sessions/active/*.json` → **10 entries, 10/10 carry `last_heartbeat` and the `mode` key**.
 
-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.
+**Decision (owner-approved scope, 2026-10-02):**
 
-#### Schema v1 Sunset — evaluated 2026-08-15, tolerance RETAINED (#595)
+1. **Lock side: the fallback is REMOVED** from all three readers in `scripts/lib/session-lock.mjs` (`parseLock()` normalisation, `isLockLive()`, `heartbeatAgeMinutes()`) and from the `category4.mjs` mirror in the same change. The mirror stays, because the audit path must not import the lock manager. `lock-ttl-parity.test.mjs` now asserts that both copies call a heartbeat-less lock not live, so a copy that grows the fallback back breaks parity. The default-lock fixture factories in `tests/lib/session-discovery.test.mjs` and `tests/lib/session-discovery-fallback.test.mjs` now set `last_heartbeat`; at the measurement those two files carried 17 of the 19 tests the removal turned red.
+2. **Registry side: `_validEntry()` keeps accepting an entry without `mode`.** This is no longer framed as v1 compat. It is a deliberate fail-open for peer visibility: rejecting a mode-less entry would drop a possibly LIVE peer from `readRegistry()` / `detectPeers()` and hide it from parallel-session detection, while an unclassifiable peer mode already degrades to `parallel-ok` in `acquire()`. This follows `.claude/rules/development.md` § Guard & Threshold Design.
 
-The 90-day sunset window from Epic #583 (target 2026-08-25) came due and the removal was evaluated against the live fleet. **Verdict: keep the three reader tolerances; the blocker is not v1 data, it is a second production copy of the rule.**
+**Display readers aligned (2026-10-02, follow-up to the sunset).** Three readers that parse the lock themselves kept the `started_at` stand-in after the change above, and now read `last_heartbeat` only:
 
-**Precondition — zero v1 artefacts on disk (measured 2026-08-15, this host):**
+- `scripts/lib/lock-reaper.mjs` `ageHoursOf()` reports `null` for a heartbeat-less lock (the CLI prints "unknown age") instead of the age since `started_at` labelled as staleness. It is display only; the reap gate is `isLockLive()`.
+- `scripts/lib/autopilot/stall-sampler.mjs` `readHeartbeatMs()` treats a heartbeat-less lock like a timestamp-less one and falls back to the `autopilot.jsonl` mtime marker. `started_at` never advances during a run, so as a stand-in it read as a stall after 600 s, or as fresh in the first 30 s.
+- `scripts/lib/vault-status/board-writer.mjs` renders `—` in the "Last heartbeat" column, never `started_at` under that label.
 
-- `find ~/Projects ~/.claude ~/.config /tmp/claude-501 -name 'session.lock' -not -path '*/node_modules/*'` → **12 files, 12/12 carry a non-empty `last_heartbeat`** (0 v1).
-- `~/.config/session-orchestrator/sessions/active/*.json` → **3 entries, 3/3 carry the `mode` key** (0 v1).
-- The only co-installed older plugin build (`~/.claude/plugins/cache/session-orchestrator/session-orchestrator/3.13.0`) already writes `last_heartbeat` (`session-lock.mjs:195`) and `mode` (`session-registry.mjs:209`) — **no v1 writer remains on this host.**
+The Phase-1.2 stale-lock prompt (`skills/session-start/references/phase-1-2-session-lock.md`) renders a `null` `heartbeatAgeMinutes` as "last heartbeat: never (lock has no last_heartbeat)" and drops the "ttl has expired" clause in that case, instead of `Math.round(null)` = "0 minutes ago".
 
-**Why the branches stay anyway:**
+**Corrupt lock (2026-10-02).** A `session.lock` that fails `parseLock()` (invalid JSON, or JSON without the six-field shape) makes `acquire()` return `reason: 'corrupt'` (`existingLock: null`), and the SessionStart bootstrap reclaims it with one stderr WARN. Before this, the file wedged the repo: `readLock()` returned `null`, the create-or-fail hit `EEXIST`, and the vanished-race branch answered `active` with `existingLock: null` on every attempt, which the bootstrap never forces. Reclaiming is safe because such a file can never be a live lock: all four production writers write a full `buildLock()` body atomically (tmp+link / tmp+rename).
 
-1. **`parseLock()` / `isLockLive()` — the rule is duplicated.** `scripts/lib/harness-audit/categories/category4.mjs` `lockIsLive()` inlines the same `last_heartbeat ?? started_at` fallback, and `tests/lib/lock-ttl-parity.test.mjs` asserts the mirror and the SSOT return identical verdicts *for a v1 lock*. Dropping it in `session-lock.mjs` alone breaks that parity by construction. A measured removal attempt turned **18 tests red across 4 files** (`session-discovery` 9, `session-discovery-fallback` 6, `lock-ttl-parity` 1, `on-session-start` 2) — all outside the lock/registry module pair, all seeding v1-shaped fixtures.
-2. **`_validEntry()` optional `mode` — removal is a net safety LOSS.** Rejecting a mode-less registry entry drops a **live peer** from `readRegistry()`, making it invisible to the exclusivity matrix. An absent `mode` already degrades to the `parallel-ok` bucket, so strictening buys no detection and costs peer visibility — the wrong direction under `.claude/rules/development.md` § Guard & Threshold Design.
+**Unreadable lock (#1494).** A lock path that exists but cannot be read (`EACCES`, or a directory: `EISDIR`) makes `acquire()` return `reason: 'unreadable'` (`existingLock: null`, `error`). It used to answer `active` / `existingLock: null`, which the bootstrap neither forced nor reported, so every session ran without a lock and left no trace. It is still never reclaimed (no lock writer produces it, and a directory may hold content nobody here created), but the SessionStart bootstrap now prints one stderr WARN and emits `orchestrator.session.lock.read_anomaly` with `status: 'unreadable'`.
 
-**What a real sunset needs (co-change set, one atomic MR):** `scripts/lib/session-lock.mjs` + `scripts/lib/harness-audit/categories/category4.mjs` (the mirror) + fixture updates in `tests/lib/session-discovery.test.mjs`, `tests/lib/session-discovery-fallback.test.mjs`, `tests/lib/lock-ttl-parity.test.mjs`, `tests/hooks/on-session-start.test.mjs`. Deleting the *mirror* in favour of importing the SSOT is the durable fix — the duplication, not the v1 data, is what keeps this class alive. The registry item should be closed as won't-do per point 2.
+**Single-winner reclaim (#1494).** The bootstrap reclaims a `stale-heartbeat` or `corrupt` lock with `forceAcquire({ onlyIfNotLive: true })`. The lock is renamed to a unique tombstone first, so only one caller can hold the moved file; a moved lock that is not live is replaced by the create-or-fail link, a live one (a racer's fresh lock) is linked back. Every lost path returns a fresh `acquire()` result, normally `active` with the winner's lock, so the loser records `conflict_with_session_id` instead of running on as the owner. Before, two starts that saw the same stale lock both forced it, both got `ok: true`, and the later rename won. A plain `forceAcquire()` (the operator-approved force-take of a live lock in Phase 1.2) still overwrites unconditionally.

package/skills/autopilot/SKILL.md

@@ -39,11 +39,19 @@ the invocation surface only:
 Headless requirements:
 
 - Anthropic API key configured for `claude -p` (Claude Code CLI auth).
-- `scripts/autopilot.mjs` reads `sessions.jsonl` tail after each child exit to construct
-  the `sessionRunner` return shape — the spawned session must complete cleanly and append
-  its record (session-end Phase 3.7 handles this).
-- `AUTOPILOT_RUN_ID` env var is propagated to the child so session-end stamps it onto the
-  per-iteration `sessions.jsonl` record.
+- `scripts/autopilot.mjs` starts each child with `--session-id <fresh uuid>` and, after it
+  exits, reads the one canonical `sessions.jsonl` record whose `raw_session_id` is that uuid
+  to construct the `sessionRunner` return shape — the spawned session must complete cleanly
+  and append its record (session-end Phase 3.7 handles this). No such record, or more than
+  one, stops the loop with `failed-wave` instead of reading the ledger tail (#1457). So does
+  a unique record that is only a backfill stub (no waves/agents/token totals — the child never
+  closed): its token usage is unknown, not 0, so it is never counted as a healthy 0-token
+  iteration (#1457 F2).
+- `AUTOPILOT_RUN_ID` env var is set in the child's env, but **nothing reads it yet**
+  (measured 2026-10-01: `rg -n "AUTOPILOT_RUN_ID" scripts hooks skills` finds only the writer
+  in `scripts/autopilot.mjs` and this line). CLI-driven iterations therefore carry no
+  `autopilot_run_id` on their `sessions.jsonl` record yet; join them to `autopilot.jsonl` via
+  the `sessions` list there, not via that field.
 
 Do NOT re-implement loop logic inline — this skill and `scripts/lib/autopilot.mjs` are
 authoritative. Kill-switches are enforced by `scripts/lib/autopilot.mjs`, not inline by
@@ -111,7 +119,7 @@ intent for THIS run, not a standing policy.
 ## Command Surface
 
 ```
-/autopilot [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--dry-run]
+/autopilot [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--max-tokens=N] [--dry-run]
 ```
 
 | Flag | Default | Bounds | Meaning |
@@ -119,6 +127,7 @@ intent for THIS run, not a standing policy.
 | `--max-sessions` | `5` | 1..50 | Iteration cap (graceful exit when reached) |
 | `--max-hours` | `4.0` | 0.5..24.0 | Wall-clock budget for entire loop |
 | `--confidence-threshold` | `0.85` | 0.0..1.0 | Minimum `selectMode` confidence for auto-execute |
+| `--max-tokens` | `0` (off) | 0..10000000 | Token budget for `token-budget-exceeded`. Unit: cumulative **subagent OUTPUT** tokens, summed from each `sessions.jsonl` record's `total_token_output` (falling back to `total_tokens`, which is subagent-only as well) — coordinator tokens are not counted. Off by default until calibrated: one measured deep session's subagents produced 450 499 output tokens, so a six-figure budget stops the loop after about one deep session. An iteration whose record carries no token figure adds nothing and is counted as `tokens_unknown_sessions` (state, return value, `autopilot.jsonl`, and the run summary line on stdout, which prints `tokens=<sum>` and — when non-zero — `tokens_unknown_sessions=<n>`), so with any such iteration the sum is a LOWER bound and the budget can be overshot |
 | `--dry-run` | `false` | — | Print planned iterations without executing |
 
 Out-of-range values silently clamp to bounds. `--dry-run` exits after printing — never
@@ -136,7 +145,7 @@ WHILE state.iterations_completed < max-sessions:
     kill_switch := 'max-sessions-reached'; break
   IF (now() - state.started_at) > max-hours:
     kill_switch := 'max-hours-exceeded'; break
-  IF cumulative_tokens_used >= max-tokens:
+  IF max-tokens > 0 AND cumulative_tokens_used >= max-tokens:
     kill_switch := 'token-budget-exceeded'; break
   IF resource_verdict() == 'critical' AND peer_count() > autopilot-peer-abort:
     kill_switch := 'resource-overload'; break
@@ -222,7 +231,7 @@ session — drives `runLoop` between manual `/session` invocations. The headless
 | Field | Signature | Source |
 |---|---|---|
 | `modeSelector` | `() => Promise<{mode, confidence, rationale?}>` | wraps `selectMode(await buildLiveSignals())` |
-| `sessionRunner` | `({mode, autopilotRunId}) => Promise<{session_id, agent_summary?, effectiveness?}>` | wraps a `/session <mode>` invocation; reads `sessions.jsonl` tail to construct return value |
+| `sessionRunner` | `({mode, autopilotRunId}) => Promise<{session_id, agent_summary?, effectiveness?}>` | wraps a `/session <mode>` invocation; reads the child's own record (matched on `raw_session_id`) to construct return value |
 | `resourceEvaluator` | `() => {verdict}` | calls `evaluate(cachedProbeSnapshot, thresholds)` from `resource-probe.mjs` over a snapshot `peerCounter` refreshed on the prior iteration — never calls `probe()` itself, which is what keeps it synchronous |
 | `peerCounter` | `() => Promise<number>` | returns `peers.length` from `detectPeers({ sessionId, freshnessMin: 15 })` (a SESSION count, not a process count — see `host-resources.md` HR-103) while refreshing the cached `probe()` snapshot `resourceEvaluator` reads |
 
@@ -278,6 +287,10 @@ const sessionRunner = async ({ mode, autopilotRunId }) => {
   // The coordinator (Claude) invokes /session <mode> manually here. After the
   // session completes (/close runs, sessions.jsonl appended), this function
   // reads the tail entry and projects it into the runLoop return-shape.
+  // CAUTION: a tail read has the peer-append error class — a parallel session
+  // that appends after this one supplies ITS record (and token usage). A real
+  // run should read its own record by raw session id, as scripts/autopilot.mjs
+  // does (readOwnSession → raw_session_id match, #1457).
   const tail = readSessionsJsonlTail(1);   // last line, normalized
   return {
     session_id: tail.session_id,
@@ -314,9 +327,10 @@ four required `runLoop` dependencies (`modeSelector`, `sessionRunner`,
 `resourceEvaluator`, `peerCounter`) plus the optional `abortSignal` to production
 sources — distinct from, and more concrete than, the in-process skeleton above:
 
-- `sessionRunner` — spawns `claude -p '/session <mode>'` as a child process; after it
-  exits cleanly, reads the `sessions.jsonl` tail to construct the return shape
-  `{session_id, agent_summary?, effectiveness?}` (`scripts/autopilot.mjs` `sessionRunner`).
+- `sessionRunner` — spawns `claude -p '/session <mode>' --session-id <uuid>` as a child
+  process; after it exits cleanly, reads the one canonical `sessions.jsonl` record whose
+  `raw_session_id` is that uuid to construct the return shape
+  `{session_id, agent_summary?, effectiveness?, usage?}` (`scripts/autopilot.mjs` `sessionRunner`).
 - `resourceEvaluator` — calls `evaluate(cachedProbeSnapshot, thresholds)` from
   `scripts/lib/resource-probe.mjs`, reading a snapshot refreshed by `peerCounter` on the
   prior iteration so the function itself stays synchronous, per the `runLoop` contract

package/skills/bootstrap/SKILL.md

@@ -58,7 +58,7 @@ skill without dispatching to a tier template.
 |------|----------------|
 | `--upgrade <tier>` | You bootstrapped `fast` earlier and now need `standard` or `deep`. Idempotent — writes only the delta. Refuses downgrade. Valid: `fast → standard`, `fast → deep`, `standard → deep`. |
 | `--retroactive` | The repo already has `CLAUDE.md` (or `AGENTS.md` on Codex CLI) + `## Session Config` but no `bootstrap.lock` (manually bootstrapped before the gate existed). Writes the lock based on file inventory; **makes no scaffolding changes**. Commit: `chore: bootstrap lock (retroactive)`. |
-| `--refresh-lock` | Your `bootstrap.lock` already has valid `version`/`tier` fields but the freshness probe flags it as stale or plugin-version-drifted — `--retroactive` is a no-op here. Acknowledges the current plugin version and resets the freshness clock (`refreshed-at` + `refreshed-plugin-version`) without touching the lock's original bootstrap provenance. No scaffolding, no auto-commit. |
+| `--refresh-lock` | Your `bootstrap.lock` already has valid `version`/`tier` fields but the freshness probe flags it as stale or plugin-version-drifted — `--retroactive` is a no-op here. Acknowledges the current plugin version and resets the freshness clock (`refreshed-at` + `refreshed-plugin-version`) without touching the lock's original bootstrap provenance. Also appends missing store-lock `.gitignore` lines. No scaffolding, no auto-commit. |
 | `--sync-rules` | Pull canonical rules from the plugin's `rules/` library into `.claude/rules/`. Preserves local rules (files without the plugin source header). Standalone — does not touch `bootstrap.lock`. |
 | `--ecosystem-health` | Run the ecosystem-health wizard: detects CI provider + package manager, prompts for health endpoints, pipelines, and critical issue labels. Writes the config block + `.orchestrator/policy/ecosystem.json`. No scaffolding, no auto-commit. |
 | `--fast` / `--standard` / `--deep` | Skip the tier confirmation question (e.g., for scripted runs). Equivalent to running `/bootstrap` and selecting that option. |
@@ -94,7 +94,7 @@ Store `INVOCATION_MODE = transitive | direct`.
 
 - `private`: the existing host-local config resolution found a baseline directory and its reduced contract validated. Use `private-contract.md` for selection, templates, commands, CI and rules.
 - `public`: the resolved baseline is absent, empty, or points to a missing directory. Use plugin-bundled templates.
-- Existing but invalid configured baseline: abort before dispatch; report the reader's sanitized error reason.
+- Existing but invalid configured baseline: abort before dispatch; report the reader's sanitized error reason; for `producer-missing` also surface the `message` and the migrate-or-unconfigure choice (see `public-fallback.md` § Step 1).
 
 Pass `PATH_TYPE` into Phase 1 and all subsequent phases. All tier templates (`fast-template.md`, `standard-template.md`, `deep-template.md`) must consult `public-fallback.md` for CLAUDE.md generation and archetype file sourcing when `PATH_TYPE = public`.
 
@@ -213,6 +213,8 @@ Entered when `$ARGUMENTS` contains `--upgrade <tier>`. No scaffolding questions
 
 6. **Apply delta files.** Execute only the relevant template steps for the missing files. Read the appropriate template (`standard-template.md` and/or `deep-template.md`) and execute ONLY the steps that produce the delta files. Do NOT re-run already-completed steps.
 
+6a. **Ignore the store-lock and runtime-lock artifacts (#1489 Pkt 17, #1495).** Execute the bash block in [`_shared-template.md#store-lock-ignore`](_shared-template.md) regardless of the delta. It amends the existing `.gitignore` instead of producing a delta file, so steps 5–6 never reach it — and a repo bootstrapped before it existed lacks some or all of its patterns (the store locks, the session lock, `runtime/`, `current-session.json`, `tmp/` and the other runtime files listed there). Idempotent: only missing lines are appended. The append is NOT a delta file: step 8 leaves it unstaged, and step 9 names it.
+
 7. **Update bootstrap.lock atomically.** Overwrite `.orchestrator/bootstrap.lock` with `tier: <TARGET_TIER>`. Preserve a validated existing `archetype`; when upgrading a null Fast archetype, record the newly confirmed ID and scaffold source. Update `timestamp` to now. Preserve the prior `source` otherwise. Write `plugin-version` from `$PLUGIN_ROOT/package.json` (current plugin version at upgrade time).
 
 8. **Commit.** Stage only the delta files that were just written and commit:
@@ -224,7 +226,7 @@ Entered when `$ARGUMENTS` contains `--upgrade <tier>`. No scaffolding questions
    git commit -m "chore: bootstrap upgrade to <TARGET_TIER>"
    ```
 
-9. **Report.** Print a one-line summary: `Bootstrap upgraded from <CURRENT_TIER> to <TARGET_TIER>. <N> files added.`
+9. **Report.** Print a one-line summary: `Bootstrap upgraded from <CURRENT_TIER> to <TARGET_TIER>. <N> files added.` When step 6a appended to `.gitignore`, add: `.gitignore: store-lock patterns appended (unstaged).`
 
 ---
 
@@ -240,7 +242,7 @@ See [references/bootstrap-retroactive-flow.md](references/bootstrap-retroactive-
 
 ## Refresh-Lock Flow (`--refresh-lock`)
 
-Acknowledges the current plugin version and resets the freshness clock on an already-valid `bootstrap.lock` (`refreshed-at` + `refreshed-plugin-version`) without disturbing its original bootstrap provenance or re-running scaffolding.
+Acknowledges the current plugin version and resets the freshness clock on an already-valid `bootstrap.lock` (`refreshed-at` + `refreshed-plugin-version`) without disturbing its original bootstrap provenance or re-running scaffolding; appends missing store-lock `.gitignore` lines via `_shared-template.md#store-lock-ignore` (#1489 Pkt 17).
 
 See [references/bootstrap-refresh-lock-flow.md](references/bootstrap-refresh-lock-flow.md).
 

package/skills/bootstrap/_shared-template.md

@@ -1,7 +1,8 @@
 # Bootstrap Shared Template Partials
 
 > This file is NOT a standalone template. It contains shared step definitions
-> referenced from `standard-template.md` and `deep-template.md` via
+> referenced from the tier templates (and, for `#store-lock-ignore`, from the
+> `SKILL.md` Upgrade and Refresh-Lock flows) via
 > `<!-- @include _shared-template.md#section-name -->` markers.
 >
 > When the bootstrap skill reads a tier template, sections marked with an
@@ -17,7 +18,7 @@ Vendor the canonical always-on rules from the plugin's `rules/` library into `$R
 
 Idempotency is handled by the writer itself:
 - Missing → create
-- Exists, plugin-owned (first line is the `<!-- source: session-orchestrator plugin ... -->` header) and byte-identical → skip silently
+- Exists, plugin-owned (the `<!-- source: session-orchestrator plugin ... -->` header is on line 1, or is the first line after a line-1 frontmatter's closing `---` — `isPluginOwnedContent()`, #1449) 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)
 
@@ -334,3 +335,97 @@ fi
 ```
 
 On Codex CLI / Cursor IDE, substitute `.codex/` or `.cursor/` for `.claude/` per the platform state-directory convention.
+
+---
+
+## #store-lock-ignore — Store-Lock and Runtime-Lock Artifacts in .gitignore (#1487, #1489 Pkt 17, #1495, #1500)
+
+Applied by Fast Step 3 (so by every tier), by the Upgrade Flow and by the Refresh-Lock Flow in `SKILL.md` — the last two because a repo bootstrapped before this step existed never gets it otherwise: both flows write no `.gitignore` of their own.
+
+`.orchestrator/` itself stays versioned: `bootstrap.lock`, `policy/`, `steering/`, `peers/` and the `.orchestrator/metrics/*.jsonl` ledgers are durable project data. What the plugin writes there at runtime is per-process state or a per-run artifact that a `git add -A` would otherwise commit — the session lock is rewritten on every SessionStart, every store rewrite leaves a full backup copy of the ledger beside it, the auto-dream sidecar is a full replacement body of the operator's private MEMORY.md, and the quality-gate and ux-grill artifacts can carry secrets or a rendered password. Each pattern below names one writer's file, its `.acquire` guard where it has one, and its own temp files (left behind only by a crash mid-write). Rotated and archived ledger copies (`*.jsonl.[0-9]*`, `*.jsonl.archive-*`, `metrics/_archive/`) are not on this list: they carry ledger history, and whether that is versioned is the consumer's call.
+
+| Pattern(s) | Written by |
+|---|---|
+| `.orchestrator/metrics/*.jsonl.lock*`, `.file.lock.*` | the store locks of the ledgers (`scripts/lib/file-lock.mjs` temps sit beside every lock) |
+| `.orchestrator/metrics/*.jsonl.bak-*` | the store backups: the keep-3 `<store>.bak-<ISO>` copy before every learnings rewrite (`scripts/lib/learnings/io.mjs`) and the `<stem>.pre-drop-malformed.jsonl.bak-<ISO>` snapshot of `sweep-expired-learnings --drop-malformed` (`scripts/lib/learnings/expiry-sweep.mjs`); the `*.jsonl` ledgers themselves stay versioned |
+| `.orchestrator/session.lock`, `.orchestrator/.session.lock.*` | the session lock, every SessionStart (`scripts/lib/session-lock.mjs`, `hooks/_lib/lock-bootstrap.mjs`) |
+| `.orchestrator/runtime/` | the lock-owner proof written beside it on every SessionStart, plus agent-status and cache files |
+| `.orchestrator/current-session.json`, `.orchestrator/.current-session.*` | the SessionStart hook |
+| `.orchestrator/host.json*` | the host-identity cache |
+| `.orchestrator/state.lock*`, `.orchestrator/.state.lock.*` | the STATE.md write lock |
+| `.orchestrator/rules.lock*` | the `/reconcile` rules lock |
+| `.orchestrator/wave-dispatch-scopes.*`, `.orchestrator/.wave-dispatch-scopes.*` | the dispatch-scope ledger and its lock (`hooks/pre-task-scope-disjoint.mjs`) |
+| `.orchestrator/wave-transcript-tail.lock*`, `.orchestrator/.wave-transcript-tail.lock.*` | the wave-transcript-tail singleton |
+| `.orchestrator/metrics/proposals-write.lock*`, `.orchestrator/metrics/.proposals-write.lock.*` | the memory-proposals store lock |
+| `.orchestrator/staging-fence/` | the staging-fence commit mutex and intent log |
+| `.orchestrator/tmp/` | machine-local scratch: lock-reaper archives of reaped session locks (`tmp/reaped-locks/`, carrying host name, pid and session ids), worktree metadata (`tmp/worktree-meta/`), the orphan-reaper throttle marker (`tmp/reaper-last-scan`) |
+| `.orchestrator/metrics/*.jsonl.bak.*` | the legacy evolve backup `learnings.jsonl.bak.evolve-<ts>`, a full store copy still on disk in older repos (`scripts/lib/learnings/io.mjs`) |
+| `.orchestrator/metrics/*.jsonl.tmp-*` | atomic-write temp files of the ledgers (`scripts/lib/autopilot/telemetry.mjs`), left behind only by a crash |
+| `.orchestrator/pending-dream.md` | the auto-dream sidecar — a full replacement body of the private MEMORY.md (`scripts/lib/auto-dream.mjs`) |
+| `.orchestrator/dialectic-pending.md`, `.orchestrator/dialectic-last-run`, `.orchestrator/consumed/` | the auto-dialectic sidecar, its last-run timestamp and the archive of consumed sidecars (`scripts/lib/auto-dialectic.mjs`) |
+| `.orchestrator/promoted-from.json` | the worktree-promotion marker, a per-worktree fact (`scripts/lib/autopilot/worktree-pipeline.mjs`, read by `scripts/lib/session-end/worktree-cleanup.mjs`) |
+| `.orchestrator/welcome-banner-pending` | the zero-byte cold-start marker (`scripts/migrate-cold-start-seed.mjs`, read by `scripts/lib/cold-start-detector.mjs`) |
+| `.orchestrator/debug/` | the `/debug` Phase-1 investigation artifacts |
+| `.orchestrator/eval/` | the eval HTML run reports, rebuildable from `eval.jsonl` (`scripts/lib/eval/report.mjs`) |
+| `.orchestrator/metrics/verification-failures/` | the quality-gate auto-fix diagnostics bundles, which can carry secrets from gate output (`scripts/lib/quality-gate.mjs`) |
+| `.orchestrator/metrics/ux-grill/`, `.orchestrator/metrics/test-runs/` | the per-run artifact directories of `/ux-grill` and `/test`, screenshots included — ux-grill takes one after every journey step, including the step after a password fill (`scripts/lib/ux-grill/paths.mjs`, `scripts/lib/test-runner/artifact-paths.mjs`); their `*.jsonl` rollups stay versioned |
+| `.orchestrator/metrics/repo-audit-*.json` | the `/repo-audit` JSON sidecar of each run |
+| `.orchestrator/metrics/proposals-summary-*.json` | the per-wave memory-proposals summary sidecars (`scripts/lib/memory-proposals/sink.mjs`) |
+| `.orchestrator/metrics/.backfilled-*.marker` | the session-close-backfill idempotency markers (`scripts/lib/session-close-backfill.mjs`) |
+| `.orchestrator/*.log`, `.orchestrator/metrics/*.log` | the append-only diagnostic logs: the declined-proposal archives `reconcile.rejected.log` (`scripts/lib/reconcile/writer.mjs`) and `proposals.rejected.log` (`scripts/lib/memory-proposals/sink.mjs`), and `metrics/session-close-backfill.log`, whose `error` text carries fs error messages with absolute paths (`scripts/lib/session-close-backfill.mjs`) |
+
+Append the missing patterns:
+
+```bash
+# The Upgrade and Refresh-Lock flows run in a fresh shell where REPO_ROOT may be unset.
+_GI_ROOT="${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+_GI="$_GI_ROOT/.gitignore"
+_GI_MISSING=()
+# Never add a file consumers COMMIT here: .orchestrator/bootstrap.lock, policy/, steering/, the *.jsonl ledgers.
+_GI_PATTERNS=(
+  '.orchestrator/metrics/*.jsonl.lock*' '.file.lock.*'
+  '.orchestrator/metrics/*.jsonl.bak-*'
+  '.orchestrator/session.lock' '.orchestrator/.session.lock.*'
+  '.orchestrator/runtime/'
+  '.orchestrator/current-session.json' '.orchestrator/.current-session.*'
+  '.orchestrator/host.json*'
+  '.orchestrator/state.lock*' '.orchestrator/.state.lock.*'
+  '.orchestrator/rules.lock*'
+  '.orchestrator/wave-dispatch-scopes.*' '.orchestrator/.wave-dispatch-scopes.*'
+  '.orchestrator/wave-transcript-tail.lock*' '.orchestrator/.wave-transcript-tail.lock.*'
+  '.orchestrator/metrics/proposals-write.lock*' '.orchestrator/metrics/.proposals-write.lock.*'
+  '.orchestrator/staging-fence/'
+  '.orchestrator/tmp/'
+  '.orchestrator/metrics/*.jsonl.bak.*' '.orchestrator/metrics/*.jsonl.tmp-*'
+  '.orchestrator/pending-dream.md'
+  '.orchestrator/dialectic-pending.md' '.orchestrator/dialectic-last-run' '.orchestrator/consumed/'
+  '.orchestrator/promoted-from.json'
+  '.orchestrator/welcome-banner-pending'
+  '.orchestrator/debug/'
+  '.orchestrator/eval/'
+  '.orchestrator/metrics/verification-failures/'
+  '.orchestrator/metrics/ux-grill/' '.orchestrator/metrics/test-runs/'
+  '.orchestrator/metrics/repo-audit-*.json'
+  '.orchestrator/metrics/proposals-summary-*.json'
+  '.orchestrator/metrics/.backfilled-*.marker'
+  '.orchestrator/*.log' '.orchestrator/metrics/*.log'
+)
+if [[ -z "$_GI_ROOT" ]]; then
+  # No repo root: never fall back to "/.gitignore" (a stray file at / when run as root).
+  echo "store-lock-ignore: no repository root (REPO_ROOT unset, not inside a repo) — skipped" >&2
+else
+  for _pat in "${_GI_PATTERNS[@]}"; do
+    # A CRLF .gitignore stores "pattern\r" — count that as present, or every run appends a duplicate block.
+    grep -qxF -- "$_pat" "$_GI" 2>/dev/null || grep -qxF -- "$_pat"$'\r' "$_GI" 2>/dev/null || _GI_MISSING+=("$_pat")
+  done
+fi
+# An unreadable .gitignore (e.g. mode 0200) defeats both the presence check and the newline check — leave it alone.
+if [[ -n "$_GI_ROOT" && ! -L "$_GI" && ( ! -e "$_GI" || -r "$_GI" ) && ${#_GI_MISSING[@]} -gt 0 ]]; then
+  # A last line without a trailing newline would fuse with the comment below: `.env` + `# …`
+  # becomes `.env# …`, which git no longer reads as `.env` — the append would UN-ignore it.
+  if [[ -s "$_GI" && -n "$(tail -c1 "$_GI")" ]]; then printf '\n' >> "$_GI"; fi
+  printf '%s\n' '# session-orchestrator runtime locks and state (never versioned)' "${_GI_MISSING[@]}" >> "$_GI"
+fi
+```
+
+Idempotent (only missing patterns are appended — a repo that already carries the two store-lock lines from before #1495 gets just the runtime lines), and a symlinked `.gitignore` is left alone. A `.gitignore` created earlier in the same run is already in `BOOTSTRAP_FILES` and is committed with that run; an append to a pre-existing one stays an unstaged change, because no bootstrap commit stages a file bootstrap did not create (the Upgrade Flow stages only its delta files, the Refresh-Lock Flow commits nothing). Name the append in the flow's report so the operator commits it.

package/skills/bootstrap/fast-template.md

@@ -172,6 +172,9 @@ build/
 
 Note: `.orchestrator/` is NOT gitignored — `bootstrap.lock` must be committed. Only the platform state dirs (`.claude/`, `.codex/`, `.cursor/`) are excluded.
 
+<!-- @include _shared-template.md#store-lock-ignore -->
+**Then ignore the store-lock artifacts** — whether `.gitignore` was just written or already existed. Execute the bash block in [`_shared-template.md#store-lock-ignore`](_shared-template.md): it appends the missing store-lock patterns (`.orchestrator/metrics/*.jsonl.lock*`, `.file.lock.*`) and the runtime-lock and state patterns (`.orchestrator/session.lock`, `runtime/`, `current-session.json`, … — the full list and their writers are in that section; idempotent, a symlinked `.gitignore` is left alone). `bootstrap.lock`, `policy/`, `steering/` and the ledgers stay versioned. Standard and Deep inherit this through their Fast steps.
+
 ## Step 3a: Install Canonical Rules
 
 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.
@@ -182,7 +185,7 @@ inherited Fast passes the confirmed contract ID and records all created paths.
 
 Idempotency is handled by the writer itself:
 - Missing → create
-- Exists, plugin-owned (first line is the `<!-- source: session-orchestrator plugin ... -->` header) and byte-identical → skip silently
+- Exists, plugin-owned (the `<!-- source: session-orchestrator plugin ... -->` header is on line 1, or is the first line after a line-1 frontmatter's closing `---` — `isPluginOwnedContent()`, #1449) 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)
 

package/skills/bootstrap/private-contract.md

@@ -22,7 +22,8 @@ BOOTSTRAP_CONTRACT=$(node "$PLUGIN_ROOT/scripts/baseline-archetypes.mjs" \
 export BOOTSTRAP_CONTRACT
 ```
 
-`status: error` aborts before scaffolding. Its reason is safe to report; do not
+`status: error` aborts before scaffolding. Its reason — and, for
+`producer-missing`, its path-free `message` — is safe to report; do not
 print baseline paths, raw producer diagnostics, or private catalog files.
 `insufficient-evidence` is a selection state, not permission to use `node-minimal`.
 Fast tier has no archetype; use the plugin's minimal instruction-file flow and

package/skills/bootstrap/public-fallback.md

@@ -23,12 +23,15 @@ export BOOTSTRAP_CONTRACT PATH_TYPE
 |----------------|--------------------|
 | No configured baseline, empty value, or missing directory | `public`; use bundled templates |
 | Existing baseline with valid reduced schema v1 export | `private`; retain `archetypes` and `selected` |
-| Existing baseline with missing CLI, invalid export, unsafe source, or producer failure | Abort; report the sanitized error reason |
+| Existing baseline directory without its `scripts/archetype-manifest.mjs` exporter (`reason: producer-missing`) | Abort with the sanitized reason and its `message`; tell the user which interface is missing and offer the two ways forward: migrate the baseline to the exporter contract ([`docs/baseline.md`](../../docs/baseline.md) § How bootstrap finds it) or unset the configured baseline path (`SO_BASELINE_PATH` / matching `owner.yaml` `baselines` entry / `paths.baseline-path` / `plan-baseline-path`) to run the public path. This is the user's decision — never silently downgrade to public. <!-- path-check: example --> |
+| Existing baseline with invalid export, unsafe source (symlink, path escape), or producer failure | Abort; report the sanitized error reason |
 | Valid private contract but no matching repository markers | `private`, `selected: null`; require selection for Standard/Deep |
 
 Lookup is offline and read-only. A broken configured contract never silently
-switches to a public archetype. Missing directories retain the established
-public fallback. Never guess a baseline path or fetch one automatically.
+switches to a public archetype. `producer-missing` is the one reason with a
+documented migration path (migrate or unconfigure, above); even then the public
+path runs only after the user unsets the configured baseline. Missing
+directories retain the established public fallback. Never guess a baseline path or fetch one automatically.
 
 ## Private Path
 

package/skills/bootstrap/references/bootstrap-refresh-lock-flow.md

@@ -1,6 +1,6 @@
 # Bootstrap — Refresh-Lock Flow (`--refresh-lock`)
 
-> Reference of the `bootstrap` skill, split out of `SKILL.md` (#1246). Body moved **byte-identical**; only this header is new.
+> Reference of the `bootstrap` skill, split out of `SKILL.md` (#1246). Body moved **byte-identical**; only this header is new. Later addition: step 3a (#1489 Pkt 17, 2026-10-02).
 > **Sibling-file paths inside this body are relative to the parent directory, not to `references/`**: `SKILL.md` → `../SKILL.md`. They were deliberately NOT rewritten, so the moved bytes stay verifiable against the pre-split file.
 
 ## Refresh-Lock Flow (`--refresh-lock`)
@@ -27,9 +27,11 @@ Entered when `$ARGUMENTS` contains `--refresh-lock`. No scaffolding questions ar
 
    `refreshBootstrapLock` writes (or replaces, if already present) exactly two lines — `refreshed-at: <ISO 8601 UTC>` and `refreshed-plugin-version: <current plugin version>` — via the same atomic tmp-file + rename pattern used by the Retroactive Flow's lock write: write to a sibling tmp file, then rename over the target so the lock is never observed half-written. **Every other line of the lock — `bootstrapped-at`, `timestamp`, `plugin-version`, `tier`, `archetype`, `source`, … — is left byte-identical.** This is the provenance-honesty guarantee: a refresh is an acknowledgement, not a re-bootstrap. On failure (`result.ok === false`), surface `result.message` and stop — do not retry with a fabricated lock.
 
-4. **No auto-commit.** Unlike the Retroactive Flow, `--refresh-lock` does not stage or commit. The refreshed lock is a small, reviewable diff (two changed/added lines); the user commits it alongside their own work at their own cadence.
+3a. **Ignore the store-lock and runtime-lock artifacts (#1489 Pkt 17, #1495, added 2026-10-02).** Execute the bash block in [`_shared-template.md#store-lock-ignore`](../_shared-template.md) (link relative to `references/` — new in this step, not moved). The freshness probe sends every drifted repo here, so this is the one path on which a repo bootstrapped before that step existed — any tier, Deep included — picks up the `.gitignore` patterns that section lists (store locks, session lock, `runtime/`, `current-session.json`, `tmp/` and the other runtime files). Only a repo the probe flags as drifted gets here. Idempotent; it touches nothing but missing ignore lines.
 
-5. **Report.** Print: `Lock refreshed (refreshed-at: <now>, plugin-version: <current>). Original bootstrap provenance unchanged.`
+4. **No auto-commit.** Unlike the Retroactive Flow, `--refresh-lock` does not stage or commit. The refreshed lock (two changed/added lines) and any `.gitignore` append from step 3a are small, reviewable diffs; the user commits them alongside their own work at their own cadence.
+
+5. **Report.** Print: `Lock refreshed (refreshed-at: <now>, plugin-version: <current>). Original bootstrap provenance unchanged.` When step 3a appended to `.gitignore`, add: `.gitignore: store-lock patterns appended (unstaged).`
 
 **Idempotency.** Running `/bootstrap --refresh-lock` twice in a row replaces the same two lines in place — it never duplicates them.
 

package/skills/bootstrap/references/bootstrap-retroactive-flow.md

@@ -28,7 +28,8 @@ Entered when `$ARGUMENTS` contains `--retroactive`. Writes the lock file and, pe
 4. **Infer archetype.** Run Phase 0.5's read-only source detection. For a private
    contract, use its detected `selected.id`; retain `null` with an explicit
    `insufficient-evidence` report if no markers match. An invalid configured
-   contract aborts. Do not scaffold or apply rules in this retroactive flow.
+   contract aborts (for `producer-missing`, report its path-free `message` with
+   the reason). Do not scaffold or apply rules in this retroactive flow.
    For the public path, use best-effort detection from existing files:
    - `pyproject.toml` present → `python-uv`
    - `package.json` with `next` in dependencies → `nextjs-minimal`

package/skills/bootstrap/standard-template.md

@@ -634,6 +634,8 @@ fi
 
 **Gitignore guidance:** Do NOT add `.orchestrator/metrics/*.jsonl` to `.gitignore`. The files are intentionally visible in version control — they carry project learnings and session history that future contributors benefit from.
 
+The store's LOCK artifacts are the opposite case and DO get ignored (#1487), together with the plugin's other runtime locks and state under `.orchestrator/` (#1495): Fast Step 3, inherited above, already appended `.orchestrator/metrics/*.jsonl.lock*`, `.file.lock.*`, `.orchestrator/session.lock` and the rest of the list via [`_shared-template.md#store-lock-ignore`](_shared-template.md) — the one canonical snippet, also run by the `--upgrade` and `--refresh-lock` flows. Nothing to repeat here.
+
 <!-- @include _shared-template.md#baseline-fetch -->
 ## Step S99: (Optional) Fetch Canonical Rules + Agents from Baseline