session-orchestrator 5.4.0 → 5.6.0

package/skills/_shared/fleet-protocol.md

@@ -1,54 +1,60 @@
-# Fleet Protocol v1 — Dateien statt Nachrichten (#1462, Epic #1461)
+# Fleet Protocol v1 — Dateien statt Nachrichten (#1462)
 
-Shared reference for every session-orchestrator session (Claude Code, Codex, headless) that
-runs 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
+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. Source: PRD
-`docs/prd/2026-09-27-navigator-peer-protokoll.md` §§ 3.1–3.3, 3.7, Anhang A.2 (MR !53).
+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 (ADR-002, CSM-003).** Zustand liegt in Dateien; Nachrichten sind nur Hinweise auf eine
-Datei. Der Navigator erteilt keine Freigaben — wörtlich: **„Freigaben erteile ich keine, maßgeblich
-ist dein Owner-Auftrag"**. Eine Datei, die fehlt, heißt „nicht nachweisbar", nie „nicht vorhanden"
-(ADR-004): eine fehlende Lease ist kein freies Feld, sondern ein Zustand ohne Beleg.
+**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) — dieselbe Variable wie die navigator-CLI, keine zweite.
-  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.
+  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`).
-- Jede Datei trägt `zeit` aus `date -u +%FT%TZ` (Sekunden, `YYYY-MM-DDTHH:MM:SSZ`); nie geschätzt,
-  nie aus einer anderen Uhr. Code: `utcSecondsTimestamp()`.
-- Dateinamen aus einer `session_id` sind pfadsicher: nur `[A-Za-z0-9._-]`, nicht `.` oder `..`,
-  kein `/`. Code: `isSafeSessionId()`; `checkinPath()` und `auflagenPath()` werfen sonst.
+- 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 (PRD 3.1)
+## `leases/navigator.json` — genau ein aktiver Navigator
 
 | Feld | Inhalt |
 |---|---|
-| `session_id` | Registry-ID des Navigators (Pflicht; pfadsicher wie oben, höchstens 128 Zeichen) |
+| `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`; Erneuerung je Ticker-Runde, Ablauf 30 min nach der letzten (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.
-Erwerb und Übergabe der Lease sind S4 (agents/navigator#36), nicht Teil dieses Repos.
+`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 (PRD 3.2)
+## `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
@@ -58,74 +64,71 @@ als Ausnahme im Check-in genannt (`vorab_geschrieben`). (`CLAUDE.md` heißt auf
 `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, ergänzt
-`zeit`, validiert (`validateCheckin()`), schreibt atomar mit Modus 0600 und emittiert
-`orchestrator.fleet.checkin` (Payload `session`, `repo`, `modus`, `kandidaten`, `navigator_state`).
-Exit 0 geschrieben, 2 ungültige Eingabe (Fehlerliste auf stderr, keine Datei), 1 Schreibfehler.
+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`, `plattform` | Registry-ID (aus `.orchestrator/current-session.json`); `claude` / `codex` / `kopflos` |
-| `repo`, `repo_id`, `worktree` | Name; `repo_id` aus `navigator identity` oder `null`; Worktree `true`/`false` |
-| `modus` | `housekeeping` / `feature` / `deep` / `operations` |
-| `auftrag_ref` | Pfad der Auftragsdatei oder „Owner-Chat <zeit>" mit Wortlaut in einem Satz |
-| `konto_slot`, `quota` | `account_slot` als Nummer (`navigator identity`) oder `null`; Quota aus `navigator quota` oder `nicht messbar` |
+| `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`, `schreibbereich` | Issue-Nummern; Verzeichnisse/Dateien |
-| `bedarf` | Objekt: geplante volle Pipelines, m5-remote-Jobs, prozessstartende Agents |
-| `vorab_geschrieben`, `rueckfall` | Ausnahmen nach der Definition oben; Verhalten ohne Auflagen (unten) |
+| `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 eine Peer-Adresse `navigator-*` erreichbar ist; nie eine Antwort
+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 (PRD 3.3)
+## `auflagen/<session_id>.json` — Navigator an Session
 
-Felder: Caps (prozessstartende / lesende Agents nach freiem Speicher des lokalen Hosts), volle
-Pipelines je Repo, m5-remote-Regel (`m5-ersatz`-Exit, was lokal erlaubt ist), Merge-Protokoll, Zeitregel,
-Flottenpriorität, Besitzkonflikte, Pflichtsatz „Freigaben erteile ich keine, maßgeblich ist dein
-Owner-Auftrag". Die Session **liest** die Datei; sie wartet auf keine Nachricht.
+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, wenn `CHECKIN_FALLBACK_MIN` = 10 Minuten
-nach `checkin.zeit` keine Auflagen-Datei liegt — und sofort, wenn kein Navigator aktiv ist
-(PRD Anhang A.2, v2-Wortlaut):
+**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
-  (`memory_pressure | tail -1`).
+- 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 `m5-remote`, und nur wenn
-  `navigator m5-ersatz --quiet` unmittelbar davor mit Exit 0 endet. Exit-Vertrag: 0 nutzbar,
-  3 Ersatzregel, 5 überlastet, 6 nicht messbar; jeder Exit außer 0 (auch ein fehlender Befehl)
-  heißt: kein neues Offload-Gate. Schwelle und Hysterese leben allein in diesem Befehl — hier und
-  in den Skills steht bewusst keine Lastzahl. Lokal nur `vitest` bzw. `eslint` je Datei mit `timeout`.
+- 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 Befugnis nach PRD 3.5: `navigator authority query <repo> merge --exit-code` mit
-  Exit 0 **oder** ein ausdrücklicher Owner-Auftrag, der Merge für genau dieses Repo nennt
-  (`auftrag_ref`). Ohne navigator-CLI ist jeder Merge `einzeln`.
+- 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 (PRD 3.7)
+## 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; ihr Brief verlangt, vor jeder
-Welle und vor jedem MR `auflagen/` und `merge/` zu lesen.
-
-## Vorschau: `merge/<repo_id>/*` (S2, #1463 — hier keine Mechanik)
-
-Ansage `ansage-<mr>.json` (MR, gepinnte Head-SHA, Pipeline-ID, Jobliste, Gate-Log-SHA, Review-Stand,
-Migration, `laeuft_ab` +20 min), Lease `lease-<mr>.json` (Navigator, +15 min), Meldung
-`done-<mr>.json` (Merge-SHA, main-Pipeline-ID, Prod-SHA). Verfall bei Ablauf, MR nicht mehr
-`opened` oder geändertem Head. Nichts davon ist in diesem Repo implementiert; bis S2 gilt PRD 3.4
-Punkt 3: selbst messen und nach 3.5 mergen, oder `navigator ask --aktion merge`.
+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` ·
-`skills/navigator/SKILL.md` (`/session-orchestrator:navigator`)
+(CSM-003/004) · `scripts/lib/fleet-protocol.mjs` · `scripts/fleet-checkin.mjs`

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

@@ -113,7 +113,7 @@ In-place beside a peer is survivable when the two scopes are DECLARED to each ot
 Four steps, in order. Steps 1 and 2 are the protocol; 3 and 4 are what keeps it honest.
 
 1. **Declare the COMPLETE path list.** The arriving session sends the peer every path it will write — including the ones a script produces (fixtures, snapshots, result files, temp helpers), not only the ones it plans to edit by hand. A path omitted here is a path the peer's guard reports as a violation. In the same message it adopts the peer's resource rules.
-2. **The peer unions.** The receiving coordinator adds those paths to its `allowedPaths` as ONE record `peer-session-<id>` in the wave's scope manifest, re-asserts subset/disjointness, and re-materializes them on every wave rollover (`skills/wave-executor/wave-loop.md` § Scope Manifest).
+2. **The peer unions.** The receiving coordinator adds those paths to its `allowedPaths` as ONE record `peer-session-<id>` in the wave's scope manifest, re-asserts subset/disjointness, and re-materializes them on every wave rollover (`skills/wave-executor/wave-loop.md` § Scope Manifest). Mid-wave, re-run the FULL sequence of `skills/wave-executor/references/wave-loop-scope-manifest.md` § 3, including § 3.3's skeleton write (`"allowedPaths": []`) before the final manifest: `--union` excludes `peer-session-*` records, so re-materializing the sidecar alone leaves the manifest bytes unchanged, `bash-write-verify` keeps the sidecar bound to the OLD hash, and every agreed peer write then reports as a violation for the rest of the wave (#1504 point 5). The skeleton rewrite changes the manifest hash, which re-binds the new sidecar.
 3. **Probe with ONE real write.** Before dispatching any agent, make one small PLANNED Edit from the declared list. A denial here costs one edit; the same denial found after a fan-out costs the wave.
 4. **Announce before committing.** The arriving session sends its final file list, the peer sequences its own push behind it, and the SHAs come back. The git index is shared (PSA-007) — sequencing it is the only thing that makes two sessions in one checkout committable.
 

package/skills/_shared/state-ownership.md

@@ -107,8 +107,9 @@ layer.
 - **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 the `/navigator`
-  skill re-sets it each ticker round via `heartbeat(id, { role })` (#1462).
+  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.
@@ -250,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)
@@ -277,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

@@ -127,7 +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 |
+| `--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

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. |
@@ -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
@@ -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.

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/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
 

package/skills/discovery/probes/ssot-code-diff.mjs

@@ -24,7 +24,8 @@
  *   2. `.claude/rules/*.md` file count (non-recursive) vs. "N rule files" claims.
  *   3. `skills/` user-facing directory count (excludes `_shared/`) vs.
  *      "N user-facing skills" / "N skills" claims.
- *   4. `commands/*.md` file count vs. "N slash-commands" / "N commands" claims.
+ *   4. Slash-command count (`commands/*.md` ∪ skills with `user-invocable: true`)
+ *      vs. "N slash-commands" / "N commands" claims.
  *
  * Scope exclusions: CHANGELOG.md, docs/adr/, docs/prd/, docs/retro/ are never
  * scanned — same principle as the docs-staleness probe (historical/immutable
@@ -45,6 +46,7 @@
 
 import { existsSync, readdirSync, readFileSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { slashCommandNames } from '../../../scripts/lib/user-invocable-skills.mjs';
 
 // ---------------------------------------------------------------------------
 // Doc source sets (deliberately small and hand-curated)
@@ -101,12 +103,16 @@ function countUserFacingSkills(root) {
   }
 }
 
+// Slash commands = `commands/*.md` ∪ skills with an explicit
+// `user-invocable: true` (the #1370 commands→skills fold) — the shared census
+// in user-invocable-skills.mjs, not a second copy. Counting `commands/` alone
+// reported 2 against the real 27 on every run (#1506 pt 7). `null` (entry
+// skipped) only when the repo has neither source.
 function countCommands(root) {
-  const dir = join(root, 'commands');
-  if (!existsSync(dir)) return null;
   try {
-    const entries = readdirSync(dir, { withFileTypes: true });
-    return entries.filter((e) => e.isFile() && e.name.endsWith('.md')).length;
+    const names = slashCommandNames(root);
+    if (names.length === 0 && !existsSync(join(root, 'commands'))) return null;
+    return names.length;
   } catch {
     return null;
   }
@@ -180,7 +186,7 @@ const REGISTRY = [
   },
   {
     id: 'commands-count',
-    label: 'commands/*.md file count',
+    label: 'slash-command count (commands/*.md + user-invocable skills)',
     sources: SOURCE_SET_INVENTORY,
     severity: 'medium',
     getActual: countCommands,