session-orchestrator 5.2.0 → 5.4.0

package/skills/evolve/references/evolve-dialectic-mode.md

@@ -8,7 +8,7 @@
 
 Single-pass LLM derivation of USER.md + AGENT.md (peer cards from #503) updates from current learnings + sessions + steering files. Dry-run-default per #506 EARS contract.
 
-**Telemetry start marker (#1200):** note the current wall-clock time at Phase 6 entry (`DURATION_MS` in the Step 6.4/6.5 emits below is the elapsed milliseconds since this marker) — same placeholder convention as `skills/session-end/SKILL.md`'s `orchestrator.handover.gated` emits.
+**Telemetry start marker (#1200):** note the current wall-clock time at Phase 6 entry (`DURATION_MS` in the Step 6.4 apply emit below is the elapsed milliseconds since this marker) — same placeholder convention as `skills/session-end/SKILL.md`'s `orchestrator.handover.gated` emits.
 
 ### Step 6.0: Argument Parsing
 
@@ -19,14 +19,14 @@ Parse `$ARGUMENTS` for trailing flags after the `dialectic` keyword:
 | `--apply` | `false` | Write diff to USER.md/AGENT.md via merger.mjs; without it = dry-run |
 | `--dry-run` | `true` | Explicit dry-run (default); mutually exclusive with --apply |
 | `--model <name>` | from Session Config `dialectic.model` (default `haiku`) | Override LLM |
-| `--budget-tokens <N>` | from Session Config `dialectic.budget-tokens` (default 8000) | Token budget |
+| `--budget-tokens <N>` | from Session Config `dialectic.budget-tokens` (default 32000) | Input-token ceiling (the pre-dispatch estimate aborts above it; not a spend) |
 
 Mutex check: `--apply` + `--dry-run` together = error "flags mutually exclusive".
 
 ### Step 6.1: Pre-checks
 - Bootstrap gate (Phase 0) — already executed
 - Persistence check (Phase 1.2) — already executed
-- Cadence check: if invoked via session-end Phase 3.6.7 auto-trigger, the trigger has already pre-checked cadence. For manual invocation, skip cadence — manual always runs.
+- Cadence check: none. `/evolve dialectic` is invoked MANUALLY (by the operator, or by the session-start maintenance loop acting on the `maintenance-due` probe's `dialectic` signal) and always runs. The session-end Phase 3.6.7 auto-trigger that used to pre-check cadence was removed in #1288; `shouldDispatchAutoDialectic` (`scripts/lib/auto-dialectic.mjs`) survives only as the side-effect-free signal that probe reads, and this phase never calls it.
 
 ### Step 6.2: Data Load
 Read all 4 input sources via `runDialecticDeriver()` from `scripts/dialectic-deriver.mjs` (see W2 I1):
@@ -60,19 +60,39 @@ const result = await runDialecticDeriver({
   dispatchAgent,
   repoRoot: process.cwd(),
   model: argv.model ?? config.dialectic?.model ?? 'haiku',
-  budget: { input: argv['budget-tokens'] ?? config.dialectic?.['budget-tokens'] ?? 8000, output: 4000 },
+  budget: { input: argv['budget-tokens'] ?? config.dialectic?.['budget-tokens'] ?? 32000, output: 4000 },
   dryRun: !argv.apply,
   allowEmptying: argv['allow-emptying'] ?? false,
 });
 ```
 
 ### Step 6.4: Diff Output & Apply Gate
-- If dry-run (default): present diff inline; write to `.orchestrator/dialectic-pending.md` via `writeDialecticPending({ repoRoot, diff })` from `scripts/lib/auto-dialectic.mjs` (path constant `DIALECTIC_PENDING_PATH`; atomic tmp+rename). `runDialecticDeriver()` does NOT write this file itself — the dry-run branch returns the diff and the caller persists it. The body parameter is named `diff`, not `body`: a non-string or empty value throws `TypeError`, as does a missing `repoRoot`. EXIT. Suggestion: "Re-run with `/evolve --dialectic --apply` to apply." <!-- path-check: example -->
+- If dry-run (default): present diff inline; write to `.orchestrator/dialectic-pending.md` via `writeDialecticPending({ repoRoot, diff })` from `scripts/lib/auto-dialectic.mjs` (path constant `DIALECTIC_PENDING_PATH`; atomic tmp+rename). `runDialecticDeriver()` does NOT write this file itself — the dry-run branch returns the diff and the caller persists it. The body parameter is named `diff`, not `body`, and it is a Markdown **string**: `result.diff` is an OBJECT `{ user?, agent? }`, so serialize it first — passing the object throws `TypeError` (as does an empty string or a missing `repoRoot`). An empty `result.diff` (no target proposed) has nothing to review: write no sidecar. EXIT. Suggestion: "Re-run with `/evolve --dialectic --apply` to apply." <!-- path-check: example -->
+
+  ```javascript
+  const pendingBody = renderPendingBody(result.diff); // scripts/lib/auto-dialectic.mjs
+  if (pendingBody) {
+    await writeDialecticPending({ repoRoot, diff: pendingBody, usage: result.usage, model });
+  }
+  ```
+
+  `renderPendingBody({ user?, agent? })` is the serializer that used to live here as a snippet (#1386). It is now code so the dry-run write and the apply-time drift check below build the body the SAME way — two hand-copied serializers would report drift that is only formatting. It returns `''` when neither target is a string: nothing to review, write no sidecar.
+- **Before `--apply` writes anything: show the operator what changed since he approved (#1386).** `--apply` re-derives from the model (`dispatchAgent` runs unconditionally in `scripts/dialectic-deriver.mjs`), so under variant (b) the apply still costs a SECOND model call and what would be applied is not necessarily what was read in `.orchestrator/dialectic-pending.md`. This step makes that drift VISIBLE; it does **not** make apply deterministic. Run it after the fresh derivation and BEFORE any `writePeerCard()` call: <!-- path-check: example -->
+
+  ```javascript
+  const fresh = renderPendingBody(result.diff);
+  const cmp = await comparePendingBody({ repoRoot, body: fresh }); // never throws
+  ```
+
+  - `cmp.sidecarAbsent === true` (no sidecar — the operator may never have run the dry-run) or `cmp.drifted === false`: apply SILENTLY. An `AskUserQuestion` that blocks nothing is a rule break (`.claude/rules/ask-via-tool.md` AUQ-001/AUQ-005).
+  - `cmp.drifted === true`: present BOTH bodies (`cmp.sidecarBody` = approved, `cmp.freshBody` = fresh) and ask via `AskUserQuestion` — two options, each description carrying reason + cost + consequence, and the drifted text in the option `preview` so the operator decides from the payload rather than from a file:
+    - **"Frischen Vorschlag anwenden (Recommended)"** — recommended because the fresh derivation saw the newest learnings and sessions, while the sidecar is a snapshot of an earlier run; cost: the peer cards get text the operator has not reviewed line by line; consequence: cards are written, `writeDialecticLastRun` + `consumeDialecticPending` run, the sidecar is archived.
+    - **"Verwerfen, Sidecar für eine weitere Prüfung behalten"** — when the delta is large enough to want a second read; cost: the second model call just spent is wasted and `--apply` must run again later; consequence: **nothing is written to the peer cards and the sidecar is NOT consumed** — skip both bookkeeping calls below so the `pending-sidecar` signal keeps the review due. EXIT.
 - If `--apply`: call **`mergeDerivedBody(existingBody, result.diff[target])`** from `scripts/lib/peer-cards/merger.mjs` for each card target, then `writePeerCard(repoRoot, 'user', mergedUserCard)` and `writePeerCard(repoRoot, 'agent', mergedAgentCard)` from `scripts/lib/peer-cards/writer.mjs`. Update the `updated:` frontmatter.
 
   **`writePeerCard` shape (#1303).** `writePeerCard(repoRoot, target, card)` takes `card = { frontmatter, body }`. `frontmatter.id` (kebab-case slug, 2..128 chars) is **required and never auto-filled**; `type: 'peer-card'`, `target`, `updated` (defaults to `new Date().toISOString()`) and `created` (defaults to `updated`) are filled by the writer. ISO timestamps may carry optional milliseconds (`scripts/lib/peer-cards/schema.mjs` `ISO_DATETIME_REGEX`). A missing `id` returns `{ ok: false, errors: [...] }` and leaves the target file untouched — it does **not** throw; branch on `result.ok`.
 
-  **Why `mergeDerivedBody` and not `mergePeerCard` directly (#1310):** the deriver emits a FULL BODY STRING per target (`agents/dialectic-deriver.md` § Output format); `mergePeerCard` consumes a SECTION MAP keyed by sentinel name. `mergeDerivedBody` is the adapter between the two — it splits the proposed body at `## ` headings and maps each heading to a sentinel section. `mergePeerCard` stays available as the section-map primitive. Handling per heading class, all of it in `mergeDerivedBody`'s return value:
+  **Why `mergeDerivedBody` and not `mergePeerCard` directly (#1310):** the deriver emits, per target, the WHOLE `## ` SECTIONS it changes or adds — never the card's full body (`agents/dialectic-deriver.md` § Output format: "Omitted sections stay unchanged (nothing auto-deletes), so emit only the sections you change or newly ground"). `mergePeerCard` consumes a SECTION MAP keyed by sentinel name. `mergeDerivedBody` is the adapter between the two — it splits the proposed text at `## ` headings and maps each heading to a sentinel section, merging SECTION-WISE. Do not read this as a full-body replacement: a deriver that emitted the full body would overwrite every hand-written managed section with an LLM reproduction, and `detectEmptying` (`scripts/dialectic-deriver.mjs`) would not catch it — it refuses only a proposal with ZERO content lines. `mergePeerCard` stays available as the section-map primitive. Handling per heading class, all of it in `mergeDerivedBody`'s return value:
 
   | Heading in the proposed body | Section name | Merge effect | Surfaced as |
   |---|---|---|---|
@@ -81,10 +101,18 @@ const result = await runDialecticDeriver({
   | Existing managed section the proposal omits | — | KEPT (no auto-delete, per `mergePeerCard` semantics) | — |
   | Section name outside `[A-Za-z0-9_-]+` | — | `mergePeerCard` **throws** `invalid section name` | fix the name before merging |
   | Text before the first `## ` heading | — | NOT applied | `preamble` + a `{ type: 'unmapped-preamble' }` entry in `conflicts[]` |
+  | Falls inside an existing managed region that wraps MORE than one `## ` heading | — | NOT applied — the region stays byte-unchanged (no replace, which would delete its sibling headings' hand-written text; no append, which would duplicate the heading) | `{ type: 'multi-heading-region', region, headings, skipped }` in `conflicts[]` — `region` is the region's section name, `headings` the `## ` headings it wraps, `skipped` the proposed headings dropped. Operator action: split the region by hand into one managed region per heading, then re-run — or discard the proposal for those headings |
 
   Existing names are read back out of the card rather than re-derived because the live names are not a pure function of their headings — measured 2026-09-11 in `.orchestrator/peers/AGENT.md`: `## Guard and protocol-migration discipline` → `guard-and-protocol-migration`. Re-slugifying would APPEND a duplicate section instead of replacing one.
 
-  **Present `conflicts[]` before writing.** A non-empty `conflicts[]` (`duplicate-section`, `orphan-begin`, `unmapped-preamble`) is operator-visible content that the merge did not place — report it beside the delta line rather than writing silently.
+  **Present `conflicts[]` before writing.** A non-empty `conflicts[]` (`duplicate-section`, `orphan-begin`, `unmapped-preamble`, `multi-heading-region`) is operator-visible content that the merge did not place — report it beside the delta line rather than writing silently.
+- **Close the loop — after a successful `--apply` AND after the operator explicitly discards a reviewed proposal** (never after a dry-run, a failure, a skip, or the drift-check's "keep the sidecar for another review" branch above): record the run and consume the sidecar, both from `scripts/lib/auto-dialectic.mjs`. Without these two calls the maintenance-due probe keeps `dialectic` (measured against `.orchestrator/dialectic-last-run`) and `pending-sidecar` (`.orchestrator/dialectic-pending.md` younger than 14 days) due forever — nothing else writes the one or moves the other (#1380). Both return `{ ok, error? }` and never throw; log a failure and continue. Since #1388 `consumeDialecticPending` MOVES the sidecar to `.orchestrator/consumed/<timestamp>-dialectic-pending.md` (newest 10 retained) instead of deleting it, so the reviewed text survives the apply; `archivedTo` on the result names the file. <!-- path-check: example -->
+
+  ```javascript
+  const lastRun = await writeDialecticLastRun({ repoRoot, isoTimestamp: new Date().toISOString() });
+  const consumed = await consumeDialecticPending({ repoRoot }); // ENOENT → { ok: true, consumed: false }
+  if (!lastRun.ok || !consumed.ok) console.error(`⚠ dialectic bookkeeping: ${lastRun.error ?? consumed.error}`);
+  ```
 - Report: `Dialectic-derived: M deltas to USER.md, N deltas to AGENT.md. Dry-run | Applied. Tokens: in=<X> out=<Y>.`
 
 **Telemetry (#1200, #1206) — emitted by `scripts/dialectic-deriver.mjs`, not skill prose.**
@@ -117,27 +145,16 @@ await recordDialecticRun({
 ### Step 6.5: Error Handling
 - `status: 'unknown-model'` → fail with clear error (already thrown by validateModel)
 - `status: 'budget-exceeded'` → emit `{status:'budget-exceeded', used:N, budget:M}`, do NOT truncate.
-  Measured in a consumer repo (S119, 2026-09-10): 12 learnings + 127 sessions estimated at 11 158 input tokens against the 8000 default. Raise with `--budget-tokens 16000` or `dialectic.budget-tokens` in Session Config rather than trimming inputs.
+  The budget is an input CEILING, not a spend. The former 8000 default aborted real runs — a consumer repo estimated 11 158 input tokens (S119, 2026-09-10) and later 30 262, this repo ~12 268 for card bodies + steering alone — so the default is 32000 since #1380. If a repo still exceeds it, raise `--budget-tokens` or `dialectic.budget-tokens` in Session Config rather than trimming inputs.
 - `status: 'would-empty-card'` → warn + require `--allow-emptying` flag
 - `status: 'empty-input'` → exit clean with message "dialectic: skipped (no input)"
 - subagent crash → log ⚠, exit cleanly (do NOT write to `.orchestrator/dialectic-pending.md`) <!-- path-check: example -->
 
-**Telemetry (#1200, #1206) — emitted by `scripts/dialectic-deriver.mjs` for THREE of the five
-outcomes.** `budget-exceeded`, `would-empty-card`, and `empty-input` are `runDialecticDeriver()`
-RETURN values, so the module records them itself, mechanically, at the exact return point —
-nothing to do here for those three. The remaining two are THROWN, not returned, and can only be
-caught one layer up:
-
-- `unknown-model` — `validateModel()` throws synchronously before `runDialecticDeriver()` can
-  record anything about the call.
-- `subagent-crash` — a `dispatchAgent`/`Agent()` failure propagates out of
-  `runDialecticDeriver()` uncaught (it has no status of its own for this case).
-
-Catch both here and call the SAME `recordDialecticRun()` used in Step 6.4's apply branch,
-passing the literal slug as `status` (the abort form: `{aborted: status, duration_ms}`):
-
-```javascript
-await recordDialecticRun({ repoRoot, status: 'unknown-model' /* or 'subagent-crash' */, durationMs: DURATION_MS });
-```
+**Telemetry (#1200, #1206, #1221) — all five outcomes are emitted by `scripts/dialectic-deriver.mjs`;
+do NOT call `recordDialecticRun()` for any of them here.** `budget-exceeded`, `would-empty-card` and
+`empty-input` are recorded at their return point; `unknown-model` and `subagent-crash` are recorded
+at the throw point, and the original error is then rethrown unchanged — so catch it for the ⚠ log
+above, but a second record here would double-count the run. The only caller-side emit left is
+apply-mode success (Step 6.4).
 
 Cross-reference: PRD #506 AC1-AC4 + EARS gates. Vault Integration: dialectic does NOT mirror to vault (#506 scope — peer cards are repo-local by design; vault mirror is for cross-repo sessions/learnings).

package/skills/gitlab-ops/SKILL.md

@@ -178,7 +178,8 @@ glab issue list -R <OWNER>/<REPO> --closed --per-page 10                   # Rec
 glab issue view -R <OWNER>/<REPO> <IID>                                    # View issue details
 glab issue view -R <OWNER>/<REPO> <IID> --comments                         # With comments
 glab issue create -R <OWNER>/<REPO> --title "title" --label "priority::high,status:ready"
-glab issue update -R <OWNER>/<REPO> <IID> --label "status:in-progress"     # WARNING: --label REPLACES the full set — see caveat below
+glab issue update -R <OWNER>/<REPO> <IID> --label "status:in-progress"     # ADDS; existing labels stay — see caveat below
+glab issue update -R <OWNER>/<REPO> <IID> --unlabel "status:in-progress"   # removes only the named label(s)
 glab issue close -R <OWNER>/<REPO> <IID>                                   # then VERIFY: re-read the issue; it must show state=closed
 glab issue note -R <OWNER>/<REPO> <IID> -m "Comment text"                  # Add comment
 
@@ -196,7 +197,7 @@ glab api --hostname "$GITLAB_HOST" "projects/${ENCODED_PROJECT_PATH}/issues?stat
 glab api --hostname "$GITLAB_HOST" "projects/${ENCODED_PROJECT_PATH}/milestones?state=active"
 ```
 
-**Label update caveat (PUT-replaces, not additive):** `glab issue update --label` (and the underlying GitLab labels API) PUT-REPLACES the entire label set — it does not add to the existing set. To change a single label you must pass the FULL desired label list, or use the dedicated add/remove operations, which are themselves unreliable across `glab` versions. Preferred safe pattern: use `--label` (adds) together with `--unlabel` (removes) on `glab issue update` when your installed `glab` version supports both; otherwise read the current labels first, compute the full new set, and PUT once. The same PUT-replace semantics apply to `glab mr update --label`.
+**Label update caveat: the `glab` flags add or remove, the raw API `labels=` sets the whole list.** Measured 2026-09-19 with `glab 1.117.0 (44790937b)`: `glab issue update <IID> --label "status:in-progress"` on 7 issues (#1390 #1389 #1339 #1298 #1273 #1221 #1202) ADDED the label and left every existing label in place. Read-only re-check (canonical identity form above): `glab api --hostname "$GITLAB_HOST" "projects/${ENCODED_PROJECT_PATH}/issues/${ISSUE_IID}" | jq .labels` → for #1390 `["area:meta","follow-up","priority::low","status:in-progress","type:chore"]`. `glab issue update --help` agrees (`-l --label  Add labels.`, `-u --unlabel  Remove labels.`). To remove a label, use `--unlabel` (comma-separated for several); `stripStatusLabels` in `scripts/lib/issue-close-strip-labels.mjs` does exactly that. The raw REST API is different, and this part comes from the docs, not a measurement: the GitLab Issues API documents `labels` on `PUT /projects/:id/issues/:issue_iid` as "Comma-separated label names for an issue. Set to an empty string to unassign all labels.", with `add_labels` / `remove_labels` as the incremental parameters. So a `glab api --silent --hostname "$GITLAB_HOST" -X PUT "projects/${ENCODED_PROJECT_PATH}/issues/${ISSUE_IID}" -f labels=…` call must carry the FULL desired set; prefer `add_labels=` / `remove_labels=`. Other `glab` versions were not measured, so re-run the read-only check after an upgrade. `glab mr update` lists the same `--label` "Add labels." / `--unlabel` "Remove labels." help text in 1.117.0; its behaviour was not measured.
 
 **Close verification:** after `glab issue close <IID>`, always verify the close actually landed — re-read the issue (`glab issue view <IID>`) and confirm `state: closed` in the output. A stale or wrong project path, or a silent 404, can report local success while closing nothing; use the canonical project identity above for API operations rather than resolving a numeric ID.
 

package/skills/memory-cleanup/SKILL.md

@@ -25,7 +25,7 @@ description: >
 
 The user invoked `/memory-cleanup` with arguments: **$ARGUMENTS**. Parse them before anything else — two optional, mutually-exclusive flags are recognised (`--dry-run`, `--apply-pending`, see PRD #502); passing both is an error, and the absence of both selects the legacy interactive 4-phase mode. The per-flag behaviour, the exact status lines and the exit codes are in § Argument Handling (Phase 0) below; the interactive default runs Phases 1-4 (Orient → Gather Signal → Consolidate → Prune & Index) against `~/.claude/projects/<encoded-cwd>/memory/` and reports per § Output.
 
-Sidecar producer/consumer contract: session-end Phase 3.6.5 (`scripts/lib/auto-dream.mjs`) is nudge-only (#614) — it never dispatches a subagent to write the sidecar. The only real producer of `.orchestrator/pending-dream.md` is a manual `/memory-cleanup --dry-run` run; `--apply-pending` is the operator-confirmed consumer in a later session. The sidecar file is single-writer — concurrent sessions cannot collide because the writer holds the session-lock. <!-- path-check: example -->
+Sidecar producer/consumer contract: session-start's `maintenance-due` probe uses `scripts/lib/auto-dream.mjs` to report when cleanup is due; the former session-end Phase 3.6.5 nudge was retired in #1288. Neither path generates the sidecar. The only real producer of `.orchestrator/pending-dream.md` is a manual `/memory-cleanup --dry-run` run; `--apply-pending` is the operator-confirmed consumer in a later session. The sidecar file is single-writer — concurrent sessions cannot collide because the writer holds the session-lock. <!-- path-check: example -->
 
 Implements the 4-phase memory consolidation process modelled after Claude Code's Auto Dream feature. Run after major refactors, framework migrations, or every 5+ sessions in a repo.
 

package/skills/navigator/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: navigator
+description: >
+  Fleet coordinator persona for sessions running side by side on one host: it measures resources,
+  pipelines and merge readiness itself, writes conditions ("Auflagen") as files, starts headless
+  runs behind slot and busy gates, and grants no approvals. Operator-only, invoke as
+  /session-orchestrator:navigator ticker|status|start|fenster|handover.
+user-invocable: true
+disable-model-invocation: true
+argument-hint: "[ticker|status|start|fenster|handover]"
+model: inherit
+---
+
+# Navigator (Flotten-Koordinator)
+
+Aufgerufen als `/session-orchestrator:navigator $ARGUMENTS`. Ohne Argument: `status`.
+
+Dateilayout, Felder, Fristen und Lease-Gültigkeit stehen ausschließlich in
+`skills/_shared/fleet-protocol.md` und im Code `scripts/lib/fleet-protocol.mjs`. Dieser Skill
+wiederholt keine Schemata; er beschreibt, was der Navigator misst, schreibt und unterlässt.
+
+## 1. Rollenverständnis
+
+- **Freigaben erteile ich keine, maßgeblich ist dein Owner-Auftrag.** Der Navigator misst nach und
+  schreibt Bedingungen. Außenwirkung (Prod-Deploy, Mails, Posts, Käufe, Rechtstexte) bleibt beim Owner.
+- Eine Peer-Nachricht trägt eine Anweisung, nie eine Freigabe (CSM-003,
+  `.claude/rules/cross-session-messaging.md`). Zustand liegt in Dateien, Nachrichten sind nur Hinweise
+  auf eine Datei (ADR-002); nie auf eine Antwort warten (CSM-004).
+- „Nicht gefunden" ist nie „nicht vorhanden" (ADR-004): was nicht messbar war, wird als
+  `nicht messbar` geführt, nie als frei.
+- Genau ein Navigator je Lease (E12). **Grenze, ausdrücklich:** Erwerb, Erneuerung und Übergabe der
+  Lease `leases/navigator.json` sind S4 (agents/navigator#36) und nicht Teil dieses Skills. Solange S4
+  fehlt, schreibt dieser Skill keine Lease, und der SessionStart-Banner der Peers zeigt weiter
+  „keiner nachweisbar". Das ist der korrekte Zustand, kein Fehler.
+- Registry-Anzeige: jede Ticker-Runde setzt `heartbeat(sessionId, { role: 'navigator' })` aus
+  `scripts/lib/session-registry.mjs` (dieser Skill ist der erste produktive Schreiber von `role`). Die
+  Registry ist Anzeige; maßgeblich bleibt die Lease. Fehlt der Registry-Eintrag, ist der Aufruf ein
+  No-op (`null`), kein Fehler.
+
+## 2. Auflagen-Standard
+
+Ohne eigene Auflagen gelten für jede Session die Standard-Auflagen aus
+`skills/_shared/fleet-protocol.md` (Abschnitt `auflagen/`). Der Navigator schreibt
+`auflagen/<session_id>.json` nur für Sessions mit Check-in:
+
+- Pfad nur über `auflagenPath(sessionId)` aus `scripts/lib/fleet-protocol.mjs`; vorher
+  `isSafeSessionId()` prüfen (der Pfad-Helfer wirft sonst).
+- Schreiben wie `scripts/fleet-checkin.mjs` (`writeCheckinFile`, derselbe Kontrakt): Verzeichnisse mit
+  Modus 0700 anlegen und auch auf ein schon vorhandenes Verzeichnis `chmod 0700` anwenden; tmp-Datei
+  im Zielverzeichnis exklusiv anlegen (`wx`), explizit `chmod 0600` (die Umask filtert den
+  Anlege-Modus), dann `rename`. Nie `mkdir -p` + `cat > tmp && mv` ohne diese drei Schritte.
+- `zeit` aus `date -u +%FT%TZ` (`utcSecondsTimestamp()`), nie geschätzt.
+
+Schwellen (freier Speicher des lokalen Hosts laut `memory_pressure | tail -1`):
+
+| Freier Speicher | Caps je Peer |
+|---|---|
+| ≥ 50 % | 2 prozessstartende + 2 lesende Agents |
+| 35–50 % | 1 prozessstartender Agent |
+| < 35 % | keine neuen Starts |
+
+Offload auf `m5-remote` trägt keine eigene Lastzahl: maßgeblich ist allein `navigator m5-ersatz
+--quiet` mit dem Exit-Vertrag aus `skills/_shared/fleet-protocol.md` (Standard-Auflagen). Jeder Exit
+außer 0 heißt keine neuen Offload-Gates; den gemessenen Exit trägt `offload.m5_ersatz_exit`.
+
+Minimalbeispiel (nur Platzhalter; Feldbedeutung laut Referenz):
+
+```json
+{
+  "session": "session-A1",
+  "caps": { "prozessstartend": 2, "lesend": 2, "grundlage": "frei 54 %" },
+  "pipelines": { "repo-A": 2 },
+  "offload": { "host": "m5-remote", "m5_ersatz_exit": 0, "regel": "offload nur nach m5-ersatz Exit 0", "lokal": "vitest/eslint je Datei mit timeout" },
+  "merge_protokoll": "Ansage, eigene Messung, Befugnis nach PRD 3.5",
+  "zeitregel": "Zeiten nur aus date",
+  "flottenprioritaet": ["repo-A", "repo-B"],
+  "besitzkonflikte": [],
+  "pflichtsatz": "Freigaben erteile ich keine, maßgeblich ist dein Owner-Auftrag",
+  "zeit": "2026-01-01T00:00:00Z"
+}
+```
+
+## 3. Merge-Zeichen als Messung, nicht als Freigabe
+
+Ein „Zeichen" heißt: die Belege stimmen und main ist frei, nie „du darfst". Davor misst der Navigator
+selbst, nie aus dem Bericht einer Session:
+
+1. MR `opened` und `mergeable`.
+2. Head-SHA = Pipeline-SHA = Gate-SHA; Gate-Beleg ist die SHA-Zeile im Job-Log.
+3. Pipeline `success`, Jobliste mit gelaufen / übersprungen / manuell, Pflichtjobs eingeschlossen.
+4. main frei: keine laufende main-Pipeline, keine gültige fremde Ansage im Repo.
+5. Dateiüberschneidung mit anderen offenen MRs.
+
+Nach dem Merge: main-Pipeline bis zum Ende verfolgen, bei Deploy-Repos die Health-SHA messen. Die
+Befugnis kommt aus PRD 3.5 (Owner-Auftrag oder `navigator authority query`), nie vom Navigator.
+Merge-Leases sind S2 (#1463): siehe Abschnitt „Vorschau" in `skills/_shared/fleet-protocol.md`.
+
+## 4. Kopflose Läufe starten (`start`)
+
+- Vor jedem Start Platz-Tor und Belegt-Tor: `references/slot-check.sh` misst,
+  `references/fleet-decisions.mjs` entscheidet (`slot`, `busy`). Verweigert heißt: nicht starten.
+  Nie in einem Repo mit aktiver Claude- oder Codex-Session (Belegt-Tor: Codex-Rollout mit diesem
+  Checkout jünger als 30 min oder `session.lock` jünger als 6 h). Das Platz-Tor zählt kopflose Läufe
+  je Host (4 / 3 / 0 bei ≥ 50 % / ≥ 35 % / darunter freiem Speicher, Last1 > 40 schließt alles) und ist
+  eine andere Größe als die Agent-Caps je Peer aus Abschnitt 2.
+- Brief als Datei; er verlangt, vor jeder Welle und jedem MR `auflagen/` und `merge/` zu lesen.
+- Phase 1 mit fester Session-ID, spätere Phasen per `--resume`. Obergrenze je Lauf über
+  `timeout -k 60 <sekunden>` (ganze Sekunden; das Platz-Tor zählt Läufe an genau diesem Wrapper). Protokolldateien `phaseN.meta`, `phaseN.jsonl`, `phaseN.err`; je Lauf eine
+  Parkplatz-Datei (nur anhängen, nie überschreiben). Ablage je Lauf unter
+  `<NAVIGATOR_CONFIG_DIR>/fleet/<lauf>/` (Konvention, kein Skript liest sie).
+- Hintergrund-Tasks und Monitor sterben mit dem Turn-Ende; ein alleinstehendes langes `sleep` blockt
+  der Harness; die `until`/`case`-Form kehrt sofort zurück, weil `case` ohne Treffer 0 liefert.
+  **Wartemuster**, wörtlich:
+
+  `timeout 540 bash -c 'while :; do s=$(<status-befehl>); case "$s" in success|failed|canceled|skipped|manual) echo "$s"; exit 0;; esac; sleep 20; done'; echo "rc=$?"`
+
+  Exit 124 heißt weiter warten: denselben Befehl wiederholen. Der Turn endet nie, solange etwas läuft.
+
+## 5. Pfad-Regel für Offload
+
+`offload gate|run` immer mit dem **Worktree-Pfad**, nie mit dem Repo-Namen (sonst wird der
+Haupt-Checkout gespiegelt). Host nur über den Alias `m5-remote`. Im entfernten Befehl kein `timeout`
+und keine Login-Shell. Details: `skills/remote-offload/SKILL.md`.
+
+## 6. Codex-Läufe
+
+- `codex exec` mit `--json` und `-o <datei>`; Fortsetzung per `codex exec resume <thread-id>`.
+- Codex-Läufe mergen nie. Eine Claude-Session prüft ihr Ergebnis unabhängig, bevor irgendetwas
+  gemergt wird.
+- Laufende Codex-Sessions sind nur lesend beobachtbar (Rollout-Dateien unter
+  `$NAVIGATOR_CODEX_HOME/sessions`, mtime < 3 min = aktiv in der Lage; das Belegt-Tor aus Abschnitt 4
+  zählt konservativer, 30 min) und per Nachricht nicht erreichbar.
+
+## 7. Phase-2-Fortsetzung bei Abbruch
+
+Endet ein Lauf früh (Exit ≠ 0, „killed"-Task im Log, Bericht fehlt): Parkplatz-Datei und die letzten
+`result`-Zeilen lesen, Zustand selbst messen (Worktree, HEAD, Gate-Job), dann Phase 2 mit einem kurzen
+Fortsetzungsbrief starten, wieder hinter beiden Toren.
+
+## 8. Konto-Wache
+
+- Nutzbar: 5h < 97 % und 7d < 97 %. Das nutzbare Konto mit dem frühesten 7d-Reset (≤ 3 Tage) zuerst
+  aufbrauchen; ferne Konten fair nach Verbrauch. Toleranz 1 800 s bei gleichem Reset gegen Flattern.
+- Fehlende Daten = nicht messbar, nie „frei".
+- Werkzeug: `references/account-check.sh` liest `NAVIGATOR_ACCOUNT_CMD` und gibt nur die Entscheidung
+  aus (Ziel als Slot-Nummer, nie als Alias); ungesetzt meldet es „nicht messbar". Nie Konto-Rohdaten
+  ausgeben.
+- Ein Wechsel wirkt auf alle Sessions des Hosts und braucht eine dauerhafte Owner-Freigabe; ohne sie
+  nur eine Empfehlung.
+
+## 9. KI-Budget-Regel
+
+Bezahlter API-Key nur produktiv. Tests, Evals und CI-Proben laufen mit Mock, Kassette oder
+Abo-/CLI-Modell. Tages- und Wochenverbrauch aus den Peer-Meldungen in die Lage-Datei; die Schwelle
+für einen Owner-Punkt ist Konfiguration, nie eine erfundene Zahl.
+
+## 10. Unterbefehle
+
+| Befehl | Was er tut |
+|---|---|
+| `ticker` | Eine Runde (unten). Wiederholung nur über `/loop`, nie selbst gebaut. |
+| `status` | Liest Registry, Lease, `checkin/`, `auflagen/`; schreibt nichts. |
+| `start` | Tore aus Abschnitt 4, dann Lauf. |
+| `fenster` | Merge-Fenster je Repo als Messung nach Abschnitt 3. |
+| `handover` | Übergabedatei an den Nachfolger. `uebergabe_an` in der Lease ist S4 und wird hier nur beschrieben. |
+
+**Ticker-Runde:** (1) Zeit aus `date`; (2) Ressourcen (Speicher, Last lokal und `m5-remote`, Platte);
+(3) Peers per `ListAgents`; (4) Codex nur lesend; (5) kopflose Läufe (`phaseN.meta`, Parkplatz);
+(6) Pipelines per `glab api "projects/:id/pipelines?status=running"`; (7) Waisen: Prozesse mit PPID 1
+aus Flotten-Repos, nur melden, beenden nur mit Register-Treffer (HR-107); (8) Owner-Punkte; (9) Konto;
+(10) Budget. Danach `heartbeat(sessionId, { role: 'navigator' })`. Antwort eine Zeile, bei Befund
+höchstens sechs.
+
+**Kopflos:** unter `claude -p` sind nur `session` und `plan` als eingebaute Namen reserviert. Bis
+`/navigator` ohne Namespace gemessen ist, gilt `/session-orchestrator:navigator`.
+
+## Konfiguration
+
+Nur über Umgebungsvariablen (getrimmt; leer zählt als nicht gesetzt):
+
+| Variable | Default | Zweck |
+|---|---|---|
+| `NAVIGATOR_CONFIG_DIR` | `~/.config/navigator` | Protokollwurzel (`navigatorDir()`, S1) |
+| `NAVIGATOR_CODEX_HOME` | `~/.codex` | Codex-Rollouts, nur lesend |
+| `NAVIGATOR_ACCOUNT_CMD` | ungesetzt | Konto-Messung (wird als Shell-Befehl ausgeführt, Owner-eigen); ungesetzt = nicht messbar |
+| `NAVIGATOR_ACCOUNT_SWITCH_CMD` | ungesetzt | Wechselbefehl; `--apply` zeigt ihn nur an, führt ihn nie aus |
+| `FLEET_SLOT_OVERRIDE`, `FLEET_BUSY_OVERRIDE` | ungesetzt | `1` = Owner-Override je Tor (Grund `override` in der Entscheidung) |
+
+## See Also
+
+`skills/_shared/fleet-protocol.md` · `skills/remote-offload/SKILL.md` ·
+`.claude/rules/cross-session-messaging.md` · `.claude/rules/parallel-sessions.md` ·
+`skills/_shared/state-ownership.md` · PRD `docs/prd/2026-09-27-navigator-peer-protokoll.md`

package/skills/navigator/references/account-check.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# account-check.sh — account watch: recommend which account this host should run on.
+#
+# Usage: account-check.sh [--apply]
+#
+# Runs $NAVIGATOR_ACCOUNT_CMD (must print JSON rows: an array, or {"accounts": [...]}, each row
+# {slot, alias?, active, p7, p5, resetAt}) and pipes it into `fleet-decisions.mjs account`.
+# Prints ONLY the decision line — raw account rows never reach stdout or stderr (SEC-008).
+#
+# --apply does not switch. It prints the command that WOULD run via $NAVIGATOR_ACCOUNT_SWITCH_CMD
+# and refuses if that variable is unset: a switch affects every session on the host and needs a
+# durable owner approval, so this script only ever recommends.
+#
+# NAVIGATOR_ACCOUNT_CMD is executed as shell code by design: it is operator-owned configuration.
+#
+# Env (leading/trailing whitespace is trimmed; a whitespace-only value counts as unset):
+#   NAVIGATOR_ACCOUNT_CMD         command printing the account rows as JSON (required)
+#   NAVIGATOR_ACCOUNT_SWITCH_CMD  switch command, shown with the target appended under --apply
+#
+# Exit: 0 stay/switch recommended, 1 no usable account, 2 bad input/usage, 3 not measurable.
+set -u
+
+apply=0
+case "${1:-}" in
+  '') ;;
+  --apply) apply=1 ;;
+  *) echo "usage: account-check.sh [--apply]" >&2; exit 2 ;;
+esac
+
+# Trim leading/trailing whitespace.
+trim() {
+  local v=$1
+  v=${v#"${v%%[![:space:]]*}"}
+  v=${v%"${v##*[![:space:]]}"}
+  printf '%s' "$v"
+}
+account_cmd=$(trim "${NAVIGATOR_ACCOUNT_CMD:-}")
+switch_cmd=$(trim "${NAVIGATOR_ACCOUNT_SWITCH_CMD:-}")
+
+if [ -z "$account_cmd" ]; then
+  echo "account watch: not measurable (NAVIGATOR_ACCOUNT_CMD unset)"
+  exit 3
+fi
+
+here=$(cd "$(dirname "$0")" && pwd)
+# Cap the operator command at 40 s where a timeout binary exists (GNU coreutils `timeout`, Homebrew
+# `gtimeout`); a stock macOS host has neither, and the command then runs uncapped rather than failing
+# as "not measurable" (measured on the offload host: `command -v timeout` and `gtimeout` both empty).
+# No bash array here: under `set -u` an empty array expansion fails on bash 3.2 (stock macOS).
+run_capped() {
+  if command -v timeout >/dev/null 2>&1; then timeout 40 "$@"
+  elif command -v gtimeout >/dev/null 2>&1; then gtimeout 40 "$@"
+  else "$@"
+  fi
+}
+rows=$(run_capped bash -c "$account_cmd" 2>/dev/null)
+cmd_rc=$?
+if [ "$cmd_rc" -ne 0 ] || [ -z "$rows" ]; then
+  echo "account watch: not measurable (account command failed, rc=$cmd_rc)"
+  exit 3
+fi
+
+decision=$(printf '%s' "$rows" | node "$here/fleet-decisions.mjs" account 2>/dev/null)
+rc=$?
+if [ "$rc" -eq 2 ]; then
+  echo "account watch: not measurable (account command output is not valid account JSON)"
+  exit 2
+fi
+if { [ "$rc" -ne 0 ] && [ "$rc" -ne 1 ]; } || [ -z "$decision" ]; then
+  echo "account watch: not measurable (decision unavailable, rc=$rc)"
+  exit 3
+fi
+echo "account: $decision"
+
+if [ "$apply" -eq 1 ] && [ "$rc" -eq 0 ]; then
+  if [ -z "$switch_cmd" ]; then
+    echo "apply refused: NAVIGATOR_ACCOUNT_SWITCH_CMD unset" >&2
+    exit 2
+  fi
+  target=$(printf '%s' "$decision" | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>{const d=JSON.parse(s);process.stdout.write(d.action==="switch"?String(d.target):"")})')
+  if [ -n "$target" ]; then
+    echo "would run: $switch_cmd $target (not executed — switching needs a durable owner approval)"
+  else
+    echo "would run: nothing (stay)"
+  fi
+fi
+exit "$rc"