session-orchestrator 5.2.0 → 5.4.0

package/scripts/vault-mirror.mjs

@@ -18,7 +18,7 @@
  *   2 — filesystem error
  *
  * Output: one JSON line per action on stdout:
- *   {"action":"created|updated|skipped-noop|skipped-handwritten|skipped-collision-resolved|skipped-invalid|skipped-quality-low","path":"...","kind":"...","id":"..."}
+ *   {"action":"created|updated|skipped-noop|skipped-handwritten|skipped-collision-resolved|skipped-invalid|skipped-quality-low|skipped-abandoned|skipped-duplicate-session","path":"...","kind":"...","id":"..."}
  *
  * Idempotency rules:
  *   1. File does not exist → create.
@@ -48,22 +48,27 @@
  * Part of session-orchestrator vault-mirror (Issue #14).
  */
 
-import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { createReadStream } from 'node:fs';
 
-import { processLearning, processSession, getMaskerStats } from './lib/vault-mirror/process.mjs';
+import {
+  processLearning,
+  processSession,
+  getMaskerStats,
+  emitAction,
+} from './lib/vault-mirror/process.mjs';
 import { emitMirrorEvent, emitMirrorRunEvent } from './lib/vault-mirror/telemetry.mjs';
 import { emitEvent } from './lib/events.mjs';
 import { autoCommitVaultMirror } from './lib/vault-mirror/auto-commit.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { resolveRepoNamespace } from './lib/vault-mirror/namespace.mjs';
-import { resolveCanonicalSuffixes } from './lib/named-vault-resolver.mjs';
+import { checkCanonicalVault, describeOriginForLog, normalizeRemote } from './lib/named-vault-resolver.mjs';
 import { loadOwnerConfig } from './lib/owner-yaml.mjs';
 import { canonicalizeSessions } from './lib/sessions-canonical.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { expandTilde } from './lib/common.mjs';
 
 // ── Canonical-vault helpers (#600 D2 / #607 D2) ────────────────────────────────
 // These are module-level (above the CLI bootstrap) so the module is import-safe
@@ -85,7 +90,7 @@ export function _resolveCanonicalSuffix(envValue) {
   return envValue && envValue.trim() ? envValue.trim() : '/agents/vault';
 }
 
-// Kept for documentation; the guard now uses resolveCanonicalSuffixes() which
+// Kept for documentation; the guard now uses checkCanonicalVault() which
 // generalises this to N suffixes. The `_` prefix satisfies the no-unused-vars rule.
 const _CANONICAL_VAULT_SUFFIX = _resolveCanonicalSuffix(
   process.env.VAULT_MIRROR_CANONICAL_SUFFIX,
@@ -93,18 +98,14 @@ const _CANONICAL_VAULT_SUFFIX = _resolveCanonicalSuffix(
 
 /**
  * Normalize a git remote URL to a host/path tail for canonical-suffix matching
- * (#607 D2 — exported for unit tests). Strips `.git`, the `git@host:` / scheme
- * prefixes, and trailing slashes.
+ * (#607 D2 — exported for unit tests). Since #1450 the ONE implementation is
+ * `normalizeRemote` in lib/named-vault-resolver.mjs, shared with the board
+ * writer's guard; this name is kept for the existing test imports.
  * @param {string} url
  * @returns {string}
  */
 export function _normalizeRemote(url) {
-  return String(url ?? '')
-    .trim()
-    .replace(/\.git$/, '')
-    .replace(/^git@([^:]+):/, '$1/')
-    .replace(/^[a-z]+:\/\//, '')
-    .replace(/\/+$/, '');
+  return normalizeRemote(url);
 }
 
 // ── Mirror telemetry (#1116) ──────────────────────────────────────────────────
@@ -235,7 +236,11 @@ if (flagValues.help === true) {
   process.exit(0);
 }
 
-const vaultDir = flagValues['vault-dir'];
+// Expand a leading `~` before anything touches the path: owner.yaml `vault-dirs:` /
+// `paths.vault-dir` and the committed Session Config all accept `~/…`, and a quoted
+// `--vault-dir "~/…"` reaches us literally. `resolve('~/x')` would yield `<cwd>/~/x`
+// and the existsSync check below would abort with `missing-vault-dir` (agents/vault#319).
+const vaultDir = expandTilde(flagValues['vault-dir']);
 const source = flagValues.source;
 const kind = flagValues.kind;
 const dryRun = flagValues['dry-run'] === true;
@@ -323,6 +328,21 @@ if (kind !== 'learning' && kind !== 'session') {
 // imports) so they are import-safe and unit-testable; see _resolveCanonicalSuffix
 // / _normalizeRemote there (#607 D2).
 
+/**
+ * Render a CLI path flag for a stderr line as its basename only (#1479).
+ *
+ * This CLI's stderr lands in CI logs and session transcripts, and an absolute
+ * `--vault-dir` / `--source` carries the operator's home directory — the
+ * owner-leakage class `.claude/rules/security.md` § Owner-Privacy guards. The
+ * basename still says WHICH value was wrong; the caller passed the full path
+ * and already knows it.
+ * @param {string} p
+ * @returns {string}
+ */
+function pathForLog(p) {
+  return `.../${basename(String(p ?? ''))}`;
+}
+
 // ── Run-level accounting + run close-out (#1147) ──────────────────────────────
 //
 // Deliberately OUTSIDE main(): the run event's whole contract is that it is
@@ -430,32 +450,29 @@ async function main() {
   // are all `0`, and `aborted` is what makes that zero readable as "never
   // started" rather than "ran over an empty source".
   if (!existsSync(resolve(vaultDir))) {
-    process.stderr.write(`vault-mirror: vault-dir not found: ${vaultDir}\n`);
+    process.stderr.write(`vault-mirror: vault-dir not found: ${pathForLog(vaultDir)}\n`);
     await finishRun('missing-vault-dir');
     process.exit(2);
   }
 
-  if (process.env.VAULT_MIRROR_SKIP_CANONICAL_CHECK !== '1') {
-    const res = spawnSync('git', ['-C', resolve(vaultDir), 'remote', 'get-url', 'origin'], {
-      encoding: 'utf8',
-    });
-    const canonicalSuffixes = resolveCanonicalSuffixes({
-      ownerConfig: loadOwnerConfig().config,
-      env: process.env,
-    });
-    const ok = res.status === 0 && canonicalSuffixes.some((s) => _normalizeRemote(res.stdout).endsWith(s));
-    if (!ok) {
-      const got = res.status === 0 ? res.stdout.trim() : 'no git origin';
-      process.stderr.write(
-        `vault-mirror: refusing to mirror — "${vaultDir}" is not the canonical Meta-Vault (expected git origin ending in one of: ${canonicalSuffixes.join(', ')}; got ${got})\n`,
-      );
-      await finishRun('vault-not-canonical');
-      process.exit(2);
-    }
+  // The check itself — origin probe, suffix match, the SKIP_CANONICAL_CHECK
+  // escape hatch — is the shared `checkCanonicalVault` (#1450), the same one the
+  // board writer applies, so the two vault writers cannot drift apart again.
+  const canonical = checkCanonicalVault({
+    vaultDir: resolve(vaultDir),
+    ownerConfig: loadOwnerConfig().config,
+    env: process.env,
+  });
+  if (!canonical.ok) {
+    process.stderr.write(
+      `vault-mirror: refusing to mirror — vault is not the canonical Meta-Vault (expected git origin ending in one of: ${canonical.expected.join(', ')}; got ${describeOriginForLog(canonical.got) || 'no git origin'})\n`,
+    );
+    await finishRun('vault-not-canonical');
+    process.exit(2);
   }
 
   if (!existsSync(resolve(source))) {
-    process.stderr.write(`vault-mirror: source file not found: ${source}\n`);
+    process.stderr.write(`vault-mirror: source file not found: ${pathForLog(source)}\n`);
     await finishRun('missing-source');
     process.exit(2);
   }
@@ -485,6 +502,10 @@ async function main() {
     kind,
     force,
     vaultName,
+    // #1389: the repo whose `.vault.yaml` declares the namespace slug. This CLI
+    // has no repo-root flag, so it is the invocation cwd — bound ONCE here and
+    // shared by every processor call and the auto-commit below.
+    repoRoot: process.cwd(),
     qualityMinNarrativeChars,
     qualityMinConfidence,
   };
@@ -650,18 +671,27 @@ async function main() {
       if (isIdentifiable(entry) && !survivors.has(entry)) {
         // A losing duplicate: an earlier line whose `session_id` a LATER line
         // in this same batch supersedes or overwrites (crash-recovery
-        // re-append, #1068 stub/supersede pair). No dispatch, no stdout line,
-        // no tally for it — the winning occurrence (dispatched below, at its
-        // own position) already produces the ONE note this physical session
-        // gets. BV-004 ceiling: `runState.total` still counts this raw line,
-        // so `created+updated+skipped+failed` no longer partitions `total`
-        // for a `--kind session` run that collapsed at least one duplicate —
-        // no test pins that invariant for session kind (only for `learning`,
-        // where duplicates are not collapsed), and a partially-written vault
-        // from a batch that could not be fully deduped is the worse failure
-        // mode. Revisit with a dedicated telemetry action if an operator ever
-        // needs to name WHICH lines were collapsed, not just how many notes
-        // were written.
+        // re-append, #1068 stub/supersede pair). Never dispatched — the winning
+        // occurrence (dispatched below, at its own position) produces the ONE
+        // note this physical session gets. It is still ACCOUNTED for (#1291):
+        // `skipped-duplicate-session` goes through the same per-entry path as
+        // every other skip (stdout line + per-entry ledger record, no `path`
+        // because no target file exists for it) and into the tally, so
+        // `created+updated+skipped+failed === total` partitions a `--kind
+        // session` run that collapsed duplicates, and the ledger names WHICH
+        // lines were collapsed, not just how many notes were written.
+        tally(
+          await emitAction({
+            action: 'skipped-duplicate-session',
+            path: null,
+            kind,
+            id: entry.session_id,
+            vaultDir: ctx.vaultDir,
+            meta: { line: sessionLineNums[i] },
+            line: sessionLineNums[i],
+            dryRun,
+          }),
+        );
         continue;
       }
       await dispatchEntry(entry, sessionLineNums[i]);
@@ -693,7 +723,11 @@ async function main() {
   // Opt-in: triggers only when --session-id is provided. Callers (session-end, evolve)
   // pass it explicitly; bare invocations stay quiet to preserve legacy behaviour.
   if (!dryRun && !noCommit && sessionIdArg) {
-    autoCommitVaultMirror(resolve(vaultDir), sessionIdArg, resolveRepoNamespace({ vaultName }));
+    autoCommitVaultMirror(
+      resolve(vaultDir),
+      sessionIdArg,
+      resolveRepoNamespace({ vaultName, repoRoot: ctx.repoRoot }),
+    );
   }
 }
 

package/scripts/wave-scope-binding.mjs

@@ -37,6 +37,7 @@
  */
 
 import { parseArgs } from 'node:util';
+import path from 'node:path';
 import { attributionForRecord, emitEvent } from './lib/events.mjs';
 import { MANIFEST_SESSION_KEYS } from './lib/session-identity/own-session.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
@@ -109,7 +110,7 @@ async function main(argv) {
     return;
   }
 
-  const repoRoot = parsed.values['repo-root'] ?? process.cwd();
+  const repoRoot = path.resolve(parsed.values['repo-root'] ?? process.cwd());
   const binding = resolveBinding(repoRoot);
 
   if (Object.keys(binding).length === 0) {

package/skills/_shared/config-reading.md

@@ -133,14 +133,14 @@ Learnings live exclusively in `.orchestrator/metrics/learnings.jsonl`. The pre-`
 
 The learning lifecycle states are:
 
-- **Created**: `confidence: 0.5`, `expires_at`: current date + `learning-expiry-days` (default: 30)
-- **Confirmed** (same type+subject seen again): `confidence += 0.15` (cap 1.0), `expires_at` reset
+- **Created**: `confidence: 0.5`, `expires_at` = `created_at` + a per-TYPE TTL — `deriveExpiresAt(created_at, type)` with `LEARNING_TTL_DAYS[type] ?? LEARNING_TTL_DAYS.default` (`scripts/lib/learnings/schema.mjs`; 30–90 days per type, 60 for an unknown type). A caller-supplied `expires_at` is kept. `learning-expiry-days` does NOT set it: `scripts/lib/config.mjs` still parses that key (default 30), but no script or hook reads the parsed value — it survives only in skill prose (the `/evolve` Review-mode *Extend* action).
+- **Confirmed** (same type+subject seen again): `confidence += 0.15` (cap 1.0), `expires_at` reset to `deriveExpiresAt(now, type)`
 - **Contradicted** (evidence against): `confidence -= 0.2` — do NOT reset `expires_at` (let the learning decay naturally if contradicted)
 - **Decayed** (untouched this session): `confidence -= learning-decay-rate` (from Session Config, default `0.05`). Applied at session-end after touched-set update, before prune. Clamped to 0.0. Does NOT reset `expires_at`.
 - **Expired**: `expires_at < current date` — removed on next write
 - **Dead**: `confidence <= 0.0` — removed on next write
 
-**Expiration check semantics:** Compare `expires_at` by date portion only (ignore time-of-day) to avoid intra-day jitter. When writing `expires_at`, set it to `<current_date>T00:00:00Z + learning-expiry-days` (midnight UTC).
+**Expiration check semantics:** The code compares full timestamps, not dates: `pruneLearnings()` (`scripts/lib/learnings/expiry-sweep.mjs`) archives when `expires_at < now`; the time-driven sweep archives only after a 14-day grace window past `expires_at`. When writing `expires_at`, derive it with `deriveExpiresAt()` (full ISO timestamp, no midnight rounding) — never from `learning-expiry-days`.
 
 **Confidence bounds enforcement:** After EVERY increment or decrement, clamp confidence to [0.0, 1.0]. A learning at 0.95 confirmed becomes 1.0 (not 1.10). A learning at 0.1 contradicted becomes 0.0 and is pruned.
 

package/skills/_shared/fleet-protocol.md

@@ -0,0 +1,131 @@
+# Fleet Protocol v1 — Dateien statt Nachrichten (#1462, Epic #1461)
+
+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
+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).
+
+**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.
+
+## 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.
+- 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.
+- 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)
+
+| Feld | Inhalt |
+|---|---|
+| `session_id` | Registry-ID des Navigators (Pflicht; pfadsicher wie oben, höchstens 128 Zeichen) |
+| `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) |
+| `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.
+
+## `checkin/<session_id>.json` — Session an Navigator (PRD 3.2)
+
+**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, 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.
+
+| 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` |
+| `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) |
+| `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
+erwarten, nie darauf warten (CSM-004).
+
+## `auflagen/<session_id>.json` — Navigator an Session (PRD 3.3)
+
+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.
+
+**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):
+
+- Caps: 2 prozessstartende + 2 lesende Agents, solange der lokale Host ≥ 50 % Speicher frei hat
+  (`memory_pressure | tail -1`).
+- 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`.
+- 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`.
+
+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)
+
+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`.
+
+## 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`)

package/skills/_shared/platform-tools.md

@@ -8,15 +8,17 @@ The current platform is determined by the `scripts/lib/platform.mjs` library:
 - `$SO_PLATFORM` = `claude` | `codex` | `cursor` | `pi`
 - Environment: `$CLAUDE_PLUGIN_ROOT` (Claude Code), `$CODEX_PLUGIN_ROOT` (Codex CLI), `$CURSOR_RULES_DIR` (Cursor IDE), or `$PI_PLUGIN_ROOT` (Pi)
 
-## Identical Tools (no mapping needed)
-
-These tools have the same name and behavior on all platforms. Cursor IDE uses equivalent built-in tools for file operations and terminal commands.
-- **Read** — read file contents
-- **Write** — create/overwrite files
-- **Edit** — string replacement in files
-- **Bash** — execute shell commands
-- **Glob** — file pattern matching
-- **Grep** — content search (ripgrep)
+## File and Shell Tool Adaptation
+
+Skill bodies use Claude Code names as operations, not as a requirement that every
+harness expose those exact tools. Use the current runtime's available tools.
+Measured in Codex Desktop 0.153.4 on 2026-09-19: `exec_command` runs shell
+commands (`cat`, `rg`, `rg --files` for Read/Grep/Glob); `apply_patch` performs
+file edits. These may be exposed through a `functions.exec` tools namespace.
+Never call an unavailable `Read`, `Bash`, or `Skill` tool by name. An instruction
+to invoke `session-orchestrator:<name>` means read and follow the canonical
+`skills/<name>/SKILL.md` relative to the plugin root when no Skill tool exists.
+Keep the user's project as the working directory for project operations.
 
 ## Platform-Specific Tool Mapping
 
@@ -24,7 +26,7 @@ These tools have the same name and behavior on all platforms. Cursor IDE uses eq
 
 | Function | Claude Code | Codex CLI | Cursor IDE | Pi |
 |----------|------------|-----------|------------|----|
-| Present choices to user | `AskUserQuestion` tool with structured options | Numbered Markdown list as plain text, wait for user reply | Numbered Markdown list (same as Codex) | Numbered Markdown list v1; native UI adapter planned |
+| Present choices to user | `AskUserQuestion` tool with structured options | Available native user-input tool, respecting its mode restrictions; plain-text fallback when unavailable | Available native choice tool or numbered Markdown list | Numbered Markdown list v1; native UI adapter planned |
 | Dispatch subagent | `Agent({ description, prompt, subagent_type })` | Native multi-agent collaboration namespace: `spawn_agent`, `list_agents`, `wait_agent`, `send_message`, `followup_task`, `interrupt_agent`, `close_agent`. Measured 2026-08-25 on `codex-cli 0.141.0` — `codex features list` → `multi_agent  stable  true`. | No native in-session Agent tool. Coordinator-side foreign dispatch via the headless `cursor-agent` CLI exists (`scripts/lib/wave-executor/foreign-dispatch.mjs`, #1150) — measured 2026-08-25 on `cursor-agent 2026.08.11-e8db854`. | Sequential execution v1. Do not assume native subagents until the Pi SDK dispatcher exists. |
 | Track tasks | `TaskCreate` / `TaskUpdate` / `TaskList` | Plain-text checklist in response context | Plain-text checklist (same as Codex) | Plain-text checklist (same as Codex) |
 | Enter plan mode | `EnterPlanMode` / `ExitPlanMode` tools | `/plan` slash command (prompt-level, not tool-based) | Instruction-based: "Focus on analysis and planning. Do not modify files until the user approves." | `/plan` prompt template; use instruction-based planning when tool mode is unavailable |
@@ -37,7 +39,13 @@ When a skill instructs "Use the AskUserQuestion tool", apply this pattern:
 
 **On Claude Code:** Use the AskUserQuestion tool with structured options as documented.
 
-**On Codex CLI / Cursor IDE / Pi:** Present the same choices as a numbered Markdown list and ask the user to respond:
+**On Codex:** Prefer the available native user-input tool. In the measured Desktop
+0.153.4 runtime (2026-09-19), `request_user_input_async` allows a question while
+independent work continues; `request_user_input` has mode restrictions. Follow
+the live tool contract. Existing user authorization remains valid; do not ask
+again merely because a workflow names `AskUserQuestion`.
+
+**When no suitable native tool is available (including Cursor IDE / Pi):** Present the same choices as a numbered Markdown list and ask the user to respond:
 ```
 Choose one:
 1. Option A — description
@@ -85,6 +93,10 @@ No Session Orchestrator Pi subagent dispatcher exists in v1. Execute wave tasks
 
 Skills use `model-preference` (Claude), `model-preference-codex` (Codex), `model-preference-cursor` (Cursor), and active-model fallback on Pi in YAML frontmatter.
 
+These are preferences, not authority to replace a user's selected model,
+reasoning effort, or service tier. Preserve the current settings unless the user
+requests a change; inherit them for native subagents.
+
 ## State Directory
 
 - **Claude Code:** `.claude/` (STATE.md, wave-scope.json)

package/skills/_shared/state-ownership.md

@@ -104,6 +104,11 @@ 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 the `/navigator`
+  skill re-sets it each ticker 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.

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 |
 | `--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 |
 
@@ -235,6 +244,7 @@ import { runLoop, parseFlags } from '$PLUGIN_ROOT/scripts/lib/autopilot.mjs';
 import { buildLiveSignals } from '$PLUGIN_ROOT/scripts/lib/build-live-signals.mjs';
 import { selectMode } from '$PLUGIN_ROOT/scripts/lib/mode-selector.mjs';
 import { probe, evaluate } from '$PLUGIN_ROOT/scripts/lib/resource-probe.mjs';
+import { detectPeers } from '$PLUGIN_ROOT/scripts/lib/session-registry.mjs';
 
 const flags = parseFlags(process.argv.slice(2));
 
@@ -250,20 +260,37 @@ const modeSelector = async () => {
   return selectMode(signals);
 };
 
+let cachedProbeSnapshot = null;   // written by peerCounter, read by resourceEvaluator
+
 const resourceEvaluator = () => {
-  const snapshot = probeSync();   // or cached snapshot if probe is async
-  return evaluate(snapshot, thresholds);
+  // Synchronous by contract: never calls probe() itself (it is async) — reads
+  // the snapshot peerCounter refreshed on the prior iteration.
+  if (cachedProbeSnapshot === null) {
+    return { verdict: 'warn', reasons: ['probe not yet available'], recommended_agents_per_wave_cap: null };
+  }
+  return evaluate(cachedProbeSnapshot, thresholds);
 };
 
-const peerCounter = () => {
-  // Synchronous-friendly count from a recent probe snapshot.
-  return latestSnapshot.claude_processes_count ?? 0;
+const peerCounter = async () => {
+  // A SESSION count, not a process count (host-resources.md HR-103) —
+  // claude_processes_count runs ~6 processes per session. `ownSessionId` is
+  // this coordinator's registry id, so detectPeers() excludes it.
+  const [peers, snapshot] = await Promise.all([
+    detectPeers({ sessionId: ownSessionId, freshnessMin: 15 }),
+    probe(),
+  ]);
+  cachedProbeSnapshot = snapshot;
+  return peers.length;
 };
 
 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,
@@ -289,8 +316,9 @@ The in-process driver has Claude (the coordinator) call `/session <mode>` betwee
 - **Pro:** zero new infra. Reuses canonical kill-switch logic. Validates `buildLiveSignals`
   against real Phase 7.5 swap before headless complexity. Each iteration carries
   inter-session memory through STATE.md / sessions.jsonl / learnings.
-- **Con:** not truly autonomous — Claude must stay in the chat. Doesn't deliver
-  walk-away UX. That's Phase C-5's job.
+- **Con:** not truly autonomous — Claude must stay in the chat. The in-process
+  driver does not deliver walk-away UX; that is the shipped headless driver
+  (`--headless`, `scripts/autopilot.mjs`, Phase C-5; see § Headless Driver Wiring).
 
 ### Headless Driver Wiring (Option A — `scripts/autopilot.mjs`)
 
@@ -299,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

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

package/skills/bootstrap/_shared-template.md

@@ -17,7 +17,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)