session-orchestrator 3.20.0 → 3.22.0

package/skills/session-start/SKILL.md

@@ -42,7 +42,7 @@ This runs BEFORE the local session-lock acquire in Phase 1.2 — the preamble's
 **Outcome handling:**
 - `PASS_THROUGH` → continue to Phase 1
 - `EXCLUSIVE_BLOCKED` → exit Phase 0 cleanly per the AUQ outcome (`Warten` / `Andere Session beenden` / `Abbrechen` — all three return without initializing STATE.md)
-- `PROMOTION_OFFER` with user picking "Worktree anlegen + starten" → call `enterWorktree({ basePath, sessionId, branch, repoRoot })` from `scripts/lib/autopilot/worktree-pipeline.mjs`. Compute params: `basePath = path.dirname(repoRoot)`, `sessionId` from resolveSemanticSessionId(), `branch` from current HEAD, `repoRoot = process.cwd()`. On success, exit Phase 0 immediately — the new worktree's own session-start runs from scratch (Phase 1 onwards), Phase 1.2 session-lock-acquire is the new worktree's responsibility. On enterWorktree failure (`WorktreeBoundaryError` or `git worktree add` non-zero exit), emit stderr WARN `parallel-aware: enterWorktree failed: <err>; falling back to Manuell` and proceed via the Manuell path.
+- `PROMOTION_OFFER` with user picking "Worktree anlegen + starten" → call `enterWorktree({ basePath, sessionId, branch, repoRoot })` from `scripts/lib/autopilot/worktree-pipeline.mjs`. Compute params: `basePath = path.dirname(repoRoot)`, `sessionId` from resolveSemanticSessionId() **for the worktree-name attribution label only**, `branch` from current HEAD, `repoRoot = process.cwd()`. It is not a lock/registry ownership key; the new worktree's Phase 1.2 obtains its own physical raw `session_id`. On success, exit Phase 0 immediately — the new worktree's own session-start runs from scratch (Phase 1 onwards), Phase 1.2 session-lock-acquire is the new worktree's responsibility. On enterWorktree failure (`WorktreeBoundaryError` or `git worktree add` non-zero exit), emit stderr WARN `parallel-aware: enterWorktree failed: <err>; falling back to Manuell` and proceed via the Manuell path.
 - `PROMOTION_OFFER` with user picking "Manuell — in-place daneben" → append Deviation, continue to Phase 1
 - `PROMOTION_OFFER` with user picking "Abbrechen" → exit cleanly
 
@@ -112,14 +112,14 @@ if (content && !isDispatcherAutonomyBlockPresent(content)) {
 
 Acquire a distributed session-lock to detect parallel sessions in the same repo before initializing STATE.md. This prevents two concurrent Claude/Codex sessions from stomping each other's wave state and metrics writes.
 
-**Mechanical wiring (Epic #583, 2026-05-27):** The SessionStart hook (`hooks/on-session-start.mjs` → `hooks/_lib/lock-bootstrap.mjs`) now writes `.orchestrator/session.lock` mechanically BEFORE this skill's prose runs. The prose Phase 1.2 becomes confirmatory — it verifies the lock exists with the expected shape via `readLock({ repoRoot: process.cwd() })`. Re-call `acquire()` only if `readLock()` returns `null` (mechanical hook failed) OR the existing lock's `session_id` does not match the current session's id (a rare divergence — surface via AUQ before overwriting). The decision flow below still applies to all three outcomes (active / stale / fs-error) when the prose path needs to acquire.
+**Mechanical wiring (Epic #583, 2026-05-27):** The SessionStart hook (`hooks/on-session-start.mjs` → `hooks/_lib/lock-bootstrap.mjs`) now writes `.orchestrator/session.lock` mechanically BEFORE this skill's prose runs. The prose Phase 1.2 becomes confirmatory — it verifies the lock exists with the expected shape via `readLock({ repoRoot: process.cwd() })`. Re-call `acquire()` only if `readLock()` returns `null` (mechanical hook failed) OR the existing lock's raw `session_id` does not exactly match the current session's raw id (a rare divergence — surface via AUQ before overwriting). A matching `semantic_session_id`, STATE.md `session`, or owner proof cannot repair that mismatch. The decision flow below still applies to all three outcomes (active / stale / fs-error) when the prose path needs to acquire.
 
 ```javascript
 import { acquire, forceAcquire } from 'scripts/lib/session-lock.mjs';
 const result = acquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: process.cwd() });
 ```
 
-Where `sessionId` is the session identifier derived from the session type and timestamp (e.g. `main-2026-05-08-deep-1`), and `sessionType` is the session mode (`housekeeping`, `feature`, or `deep`).
+Where `sessionId` is the physical raw identity for this invocation: the native harness-provided raw id, or a generated UUID when no trustworthy raw id exists. It is the only value passed to `acquire()` and the only live lock/registry ownership key. `semanticSessionId` may be recorded separately as an attribution/history label and may populate STATE.md `session`; neither label is a substitute for `sessionId`. `sessionType` is the session mode (`housekeeping`, `feature`, or `deep`).
 
 ### Decision flow
 
@@ -131,21 +131,21 @@ Where `sessionId` is the session identifier derived from the session type and ti
      ```js
      AskUserQuestion({
        questions: [{
-         question: `Another session lock is active in this repo (started ${ageHours}h ago, mode=${existingLock.mode}, host=${existingLock.host}, pid=${existingLock.pid}). How should I proceed?`,
-         header: "Session Lock Conflict",
+         question: `Another session holds the lock here — started ${ageHours}h ago, mode=${existingLock.mode}, host=${existingLock.host}, pid=${existingLock.pid}. Wait, or take the lock?`,
+         header: "Session lock",
          multiSelect: false,
          options: [
-           { label: "Abort (Recommended)", description: "Let the other session finish. Safe default — prevents metrics and wave-state corruption." },
-           { label: "Force-take the lock", description: "Overwrites the active lock. ONLY use if you are certain the other session is no longer running." },
+           { label: "Abort (Recommended)", description: "Stop here and let the other session finish, then start again. Nothing is written until it releases the lock, and two sessions sharing one wave state overwrite each other's metrics." },
+           { label: "Force-take the lock", description: "Overwrites the active lock and starts anyway. Only when that session is certainly gone — otherwise both keep writing the same wave state and one of them loses everything." },
          ],
        }],
      });
      ```
    - **Codex CLI / Cursor IDE fallback (numbered Markdown list):**
      ```
-     Session lock conflict — active lock detected (started <ageHours>h ago, mode=<mode>, host=<host>, pid=<pid>).
-     1. Abort (Recommended) — let the other session finish.
-     2. Force-take the lock — ONLY if the other session is known dead.
+     Another session holds the lock here — started <ageHours>h ago, mode=<mode>, host=<host>, pid=<pid>. Wait, or take the lock?
+     1. Abort (Recommended) — stop here and let the other session finish, then start again; nothing is written until it releases the lock.
+     2. Force-take the lock — overwrites the active lock. Only when that session is certainly gone, otherwise both keep writing the same wave state and one loses everything.
      Reply with the number of your choice.
      ```
    - On **Abort**: exit session-start cleanly with a brief stderr note (`session-lock: aborted — active lock held by session_id=<id>`). Do NOT initialize STATE.md.
@@ -158,21 +158,21 @@ Where `sessionId` is the session identifier derived from the session type and ti
      ```js
      AskUserQuestion({
        questions: [{
-         question: `Stale session lock found (started ${ageHours}h ago, ttl=${existingLock.ttl_hours}h). Process pid=${existingLock.pid} on host=${existingLock.host} is ${reason === 'stale-pid-dead' ? 'confirmed dead' : 'still running or status unknown'}. Reclaim the lock?`,
-         header: "Stale Session Lock",
+         question: `A stale session lock is in the way — started ${ageHours}h ago, its ttl=${existingLock.ttl_hours}h has expired, and pid=${existingLock.pid} on host=${existingLock.host} is ${reason === 'stale-pid-dead' ? 'confirmed dead' : 'still running or status unknown'}. Reclaim it?`,
+         header: "Stale lock",
          multiSelect: false,
          options: [
-           { label: "Reclaim (Recommended)", description: "Overwrite the stale lock and continue. Safe when the previous session is no longer active." },
-           { label: "Abort — investigate manually", description: "Stop here. Inspect .orchestrator/session.lock before proceeding." },
+           { label: "Reclaim (Recommended)", description: "Overwrites the stale lock and continues, because its time-to-live has run out. When that process is really dead, nothing of the old session is lost." },
+           { label: "Abort — investigate manually", description: "Stops here and writes nothing. The lock file `.orchestrator/session.lock` (it names the process that wrote it) tells you whether that session is still alive." },
          ],
        }],
      });
      ```
    - **Codex CLI / Cursor IDE fallback (numbered Markdown list):**
      ```
-     Stale session lock found (started <ageHours>h ago, ttl=<ttlHours>h, pid=<pid> on <host>).
-     1. Reclaim (Recommended) — overwrite stale lock and continue.
-     2. Abort — investigate .orchestrator/session.lock manually.
+     A stale session lock is in the way — started <ageHours>h ago, ttl=<ttlHours>h expired, pid=<pid> on <host>. Reclaim it?
+     1. Reclaim (Recommended) — overwrites the stale lock and continues, because its time-to-live has run out and that process is no longer holding anything.
+     2. Abort — stops here and writes nothing. The lock file `.orchestrator/session.lock` (it names the process that wrote it) tells you whether that session is still alive.
      Reply with the number of your choice.
      ```
    - On **Reclaim**: call `forceAcquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: process.cwd() })`. After Phase 1.5 initializes STATE.md, append a deviation:
@@ -196,11 +196,14 @@ When `existingLock.host !== os.hostname()`, PID liveness cannot be checked (`pid
 
 > Skip this phase if `persistence` config is `false`.
 
-After Phase 1.2 acquires (or confirms) the lock, call `checkPeerStateMd(repoRoot, sessionId)` from `scripts/lib/state-md-peer-guard.mjs`. This catches the rare case where lock-based detection missed an active peer (e.g., the peer's `session.lock` was force-deleted by an out-of-band sweep but STATE.md is still `status: active`, OR the peer's registry write succeeded but the lock-bootstrap hook crashed before the lock landed).
+After Phase 1.2 acquires (or confirms) the lock, use `findPeers(repoRoot, { mySessionId: callerSessionHint })` for the STATE.md peer guard. `callerSessionHint` is the original semantic attribution label when one exists, otherwise the raw `sessionId`: `findPeers` may translate the semantic hint for the discovered lock/registry surface only after the exact raw binding check in `parallel-aware-preamble.md`, while keeping the original hint for STATE.md. This catches the rare case where lock-based detection missed an active peer (e.g., the peer's `session.lock` was force-deleted by an out-of-band sweep but STATE.md is still `status: active`, OR the peer's registry write succeeded but the lock-bootstrap hook crashed before the lock landed).
 
 ```javascript
 import { findPeers } from '$PLUGIN_ROOT/scripts/lib/peer-discovery.mjs';
-const { peers } = await findPeers(process.cwd(), { mySessionId: sessionId });
+// Keep the STATE.md comparison in its original attribution-label space.
+// findPeers performs the guarded semantic→raw translation only for discovered peers.
+const callerSessionHint = semanticSessionId ?? sessionId;
+const { peers } = await findPeers(process.cwd(), { mySessionId: callerSessionHint });
 const peer = peers.find((p) => p.source === 'state-md') ?? null;
 // Phase 1.2.1 consumes only the 'state-md' subset (STATE.md surface only).
 if (peer) {
@@ -367,29 +370,60 @@ If `snaps.length >= 1` → present the following choice:
 
 **Claude Code (AskUserQuestion):**
 
+Before asking, read what "Recover" would actually put back — the operator decides on that diff, not on the word:
+
+```js
+import { execFileSync } from 'node:child_process';
+
+// Read-only: `git stash show` prints a diffstat and never touches the working tree.
+// Capped at 12 lines so the preview box stays shorter than the option list beside it.
+const stat = execFileSync('git', ['stash', 'show', '--stat', snaps[0].sha], { encoding: 'utf8' })
+  .split('\n').slice(0, 12).join('\n');
+const refs = snaps.map((s) => s.ref).join('\n');
+```
+
 ```js
 AskUserQuestion({
   questions: [{
-    question: `Found ${snaps.length} coordinator snapshot(s) from the resumed session (latest from ${humanAgeOf(snaps[0].createdAt)}). Recover, keep as backup, or discard?`,
+    question: `${snaps.length} snapshot(s) from the resumed session, newest ${humanAgeOf(snaps[0].createdAt)}. Recover, keep, discard?`,
     header: "Snapshot",
     multiSelect: false,
     options: [
-      { label: "Recover (diff vs current tree) (Recommended)", description: "Apply the latest snapshot back onto the working tree. You will see a diff and can unstage unwanted changes before committing." },
-      { label: "Keep as backup", description: "Leave refs/so-snapshots/* in place untouched. You can recover manually later via `git stash apply $(git rev-parse <ref>)`." },
-      { label: "Discard all", description: "Delete all refs/so-snapshots/<sessionId>/* immediately via deleteSnapshot." },
+      {
+        label: "Recover (Recommended)",
+        description: "Puts the newest saved state back into your working tree and commits nothing. You can drop any of those changes afterwards.",
+        preview: `These files come back:\n\n\`\`\`\n${stat}\n\`\`\``,
+      },
+      {
+        label: "Keep as backup",
+        description: "Nothing happens now: `refs/so-snapshots/*` (the saved states) stay, and `git stash apply $(git rev-parse <ref>)` (this puts one back) works later.",
+      },
+      {
+        label: "Discard all",
+        description: "Deletes every saved state of this session for good: `refs/so-snapshots/<sessionId>/*` (all of them) is gone, and there is no second copy.",
+        preview: `Deleted for good:\n\n\`\`\`\n${refs}\n\`\`\``,
+      },
     ],
   }],
 });
 ```
 
+`preview` renders beside the option list and only works with `multiSelect: false`. It is used here because the answer decides which literal text lands in the working tree — "Recover" is a diff, "Discard all" is a list of refs that stop existing. "Keep as backup" carries none: keeping is exactly the state the operator already sees.
+
 **Codex CLI / Cursor IDE fallback (numbered Markdown list):**
 
+These harnesses have no preview box, so the same diffstat is printed inline — it is the only place the operator ever sees it:
+
 ```markdown
-Snapshot recovery options:
+"Recover" would put these files back:
+
+    <git stash show --stat <snaps[0].sha>, capped at 12 lines>
 
-1. **Recover (Recommended)** — Apply the latest snapshot back onto the working tree. You will see a diff and can unstage unwanted changes before committing.
-2. **Keep as backup** — Leave the refs in place untouched. You can recover manually later.
-3. **Discard all** — Delete all refs/so-snapshots/<sessionId>/* immediately.
+<N> snapshot(s) from the resumed session, newest <age>. Recover, keep, discard?
+
+1. **Recover (Recommended)** — puts the newest saved state back into your working tree and commits nothing. You can drop any of those changes afterwards.
+2. **Keep as backup** — nothing happens now: `refs/so-snapshots/*` (the saved states) stay, and `git stash apply $(git rev-parse <ref>)` (this puts one back) works later.
+3. **Discard all** — deletes every saved state of this session for good: `refs/so-snapshots/<sessionId>/*` (all of them) is gone, and there is no second copy.
 
 Reply with the number of your choice.
 ```
@@ -471,7 +505,7 @@ await sweepBoard({
 
 This single call does three things:
 
-1. **Sets THIS repo's board row to `in-progress`** with the current semantic-session-id, branch, mode, and heartbeat (read off this repo's `session.lock` v2 lease + the host-wide registry — both already written by Phase 1.2's `acquire()`).
+1. **Sets THIS repo's board row to `in-progress`** with the current semantic-session-id **attribution label** (never a lock/registry ownership key), branch, mode, and heartbeat (read off this repo's `session.lock` v2 lease + the host-wide registry — both already written by Phase 1.2's `acquire()`).
 2. **Re-derives THIS repo's status from its live lease**, so a stale lease left by a prior crashed session in this same repo renders as `force-closed` (heartbeat older than the v2 ttl, default 4h — `DEFAULT_TTL_HOURS` in `scripts/lib/session-lock.mjs`, evaluated via `isLockLive`) and is **never silently dropped** — its fields are read straight off the dead lock.
 3. **Re-derives every OTHER busy repo's status host-wide** via `enumerateCandidates` — a dead lease in repo B renders `force-closed` on the board the next time ANY repo's session-start runs `sweepBoard`, closing the #676→#716 gap. `frei` (lock-less) repos are excluded from re-derivation to avoid board noise; their prior rows, and the prior rows of any repo `enumerateCandidates` did not surface, are preserved unchanged via the idempotent merge — never dropped.
 
@@ -785,7 +819,19 @@ Group issues by:
 
    Non-blocking. Cross-reference: `scripts/lib/ci-status-banner.mjs` (the sibling project-facing probe) and `.claude/rules/test-value.md` § TV-005 (why structural gates beat unit-test volume).
 
-   All banners are non-blocking — display in the Session Overview, do not halt the session. If `bootstrap-lock-freshness.mjs` is absent (pre-#186 plugin install) or `peer-cards/staleness-banner.mjs` is absent (pre-#503 plugin install) or `loop-readiness-banner.mjs` is absent (pre-#633 plugin install) or `instruction-budget-guard.mjs` is absent (pre-#687 plugin install) or `reconcile-nudge-banner.mjs` is absent (pre-#723 plugin install) or `sessions-staleness-banner.mjs` is absent (pre-#724 plugin install) or `sessions-integrity-banner.mjs` is absent (pre-#958 plugin install) or `owner-config-banner.mjs` is absent (pre-#820 plugin install) or `moc-staleness-banner.mjs` / `context-coverage-banner.mjs` are absent (pre-#831 plugin install) or `claude-md-budget-lint.mjs` is absent (pre-#878 plugin install), skip silently.
+   Additionally, invoke the mirror-issues probe (`scripts/lib/mirror-issues-banner.mjs`) via `await checkMirrorIssues({ repoRoot })`. This is the only probe that deliberately queries the platform the session did NOT auto-detect. `skills/gitlab-ops/SKILL.md` § VCS Auto-Detection selects exactly one platform via if/else, so in a repo whose `origin` is GitLab and whose `github` remote is a public mirror, no code path ever reads the mirror's issue tracker — issues filed there by external reporters are structurally invisible to every session. The VCS family is therefore hard-pinned to `'github'` inside the module rather than auto-detected. It takes no Session Config key: `resolveRepoSpec({ repoRoot, vcs: 'github' })` derives the `gh -R` spec from `git remote`, which makes the probe self-disabling — a repo with no GitHub mirror resolves to `undefined`, returns `null`, and spawns no subprocess.
+
+   The return contract has THREE states, not the usual two, and the third is the point: `null` means either "no mirror remote" or "queried successfully, zero open issues"; `{ severity, message, count, repoSpec, issues }` means N > 0; and `{ severity, message, repoSpec, degraded }` means the query did NOT succeed, where `degraded` is one of `cli-missing | timeout | parse-error | auth-error | query-failed`. Render `result.message` verbatim in either non-null case. A `degraded` result must be read as *"the mirror's state is unknown"* — never as clean. `scripts/lib/ci-status-banner.mjs` collapses all three of missing-CLI, unparseable output and absent-remote onto `null`, which in the banner contract reads as "all clear"; that collapse is why this gap survived unseen. Do not reproduce it.
+
+   Additionally, invoke the git-config-drift probe (`scripts/lib/git-config-drift.mjs`) via `checkGitConfigDrift({ repoRoot })` (synchronous — no await; `env` defaults to `process.env`). It reads `git config --local --list` with a FILTERED environment, so an ambient `GIT_DIR` cannot redirect the probe itself at a foreign repository and let it call this one clean. **Three states, not two:** `null` = read and clean; `{ severity: 'warn', message, findings }` = at least one unexpected entry (a local identity override, a local `commit.gpgsign`, a remote on a reserved fixture host, a `core.hooksPath` not pointing at `.husky/_`, or `GIT_DIR`/`GIT_WORK_TREE` set in the environment); `{ …, degraded }` = the config could NOT be read — **never render that as clean.** Render `result.message` alongside the other banners.
+
+   This is the only probe that inspects `.git/config`, and that is the whole point: `git status` cannot see that file. On 2026-08-19 a coordinator diagnostic exported `GIT_DIR` at this repository while the suite ran; test fixtures wrote a foreign remote and their own `user.email`/`user.name` into the local config, and the identity then authored two commits that reached both remotes. A recovery pass checked HEAD, the index and all 1614 tracked files, found everything clean, and missed it — because none of those surfaces show `.git/config`. It surfaced two hours later, from an agent measuring something else.
+
+   The complementary halves live elsewhere and are not duplicates of this probe: `tests/setup/scrub-git-env.mjs` (wired via `setupFiles` in `vitest.config.mjs`) removes the redirecting variables before any test runs, and `scripts/lib/validate/check-test-git-config-target.mjs` censuses untargeted state-mutating git calls in `tests/**`. The census is WARN-only by measurement — its first cut was 11 hits, all false positives — and it explicitly reports `gitDirInheritable`, the population it cannot close, because the incident's own call sites passed a correct `cwd` and were redirected anyway.
+
+   Non-blocking. Cross-reference: `scripts/lib/vcs-repo-spec.mjs` (`isQueryFailure` — the same absence-vs-query-failure split this probe's `degraded` state implements).
+
+   All banners are non-blocking — display in the Session Overview, do not halt the session. If `bootstrap-lock-freshness.mjs` is absent (pre-#186 plugin install) or `peer-cards/staleness-banner.mjs` is absent (pre-#503 plugin install) or `loop-readiness-banner.mjs` is absent (pre-#633 plugin install) or `instruction-budget-guard.mjs` is absent (pre-#687 plugin install) or `reconcile-nudge-banner.mjs` is absent (pre-#723 plugin install) or `sessions-staleness-banner.mjs` is absent (pre-#724 plugin install) or `sessions-integrity-banner.mjs` is absent (pre-#958 plugin install) or `owner-config-banner.mjs` is absent (pre-#820 plugin install) or `moc-staleness-banner.mjs` / `context-coverage-banner.mjs` are absent (pre-#831 plugin install) or `claude-md-budget-lint.mjs` is absent (pre-#878 plugin install) or `mirror-issues-banner.mjs` is absent (pre-#1022 plugin install), skip silently.
 
 ## Phase 4.5: Resource Health (v3.1.0)
 
@@ -1037,12 +1083,12 @@ if (!c.prompt) {
 ```js
 AskUserQuestion({
   questions: [{
-    question: "Anonyme Usage-Telemetrie aktivieren? Strikt opt-in, whitelist-projiziert (keine Repo-Namen/Pfade/Prompts), jederzeit abschaltbar — Details: docs/telemetry.md",
-    header: "Usage Telemetry",
+    question: "Anonyme Usage-Telemetrie aktivieren? Strikt opt-in, jederzeit abschaltbar; was genau gesendet wird: docs/telemetry.md",
+    header: "Telemetrie",
     multiSelect: false,
     options: [
-      { label: "Ja, aktivieren", description: "Anonymer Zähl-/Struktur-Datensatz (Skill-/Phasen-Nutzung, Erfolg/Abbruch) — whitelist-projiziert, keine Pfade/Prompts/Repo-Namen. Details: docs/telemetry.md" },
-      { label: "Nein", description: "Keine Telemetrie senden. Jederzeit später aktivierbar via node scripts/telemetry.mjs." },
+      { label: "Ja, aktivieren", description: "Sendet anonyme Zähl- und Strukturdaten (welche Phase lief, Erfolg oder Abbruch), whitelist-projiziert: keine Pfade, keine Prompts, keine Repo-Namen." },
+      { label: "Nein", description: "Sendet nichts; die Frage kommt hier nicht wieder. Einschalten geht später mit `node scripts/telemetry.mjs` (das ist der Befehl dafür)." },
     ],
   }],
 });
@@ -1052,9 +1098,9 @@ AskUserQuestion({
 
 - **Codex CLI / Cursor IDE fallback (numbered Markdown list — AUQ-004 exception 1):**
   ```
-  Anonyme Usage-Telemetrie aktivieren? Strikt opt-in, whitelist-projiziert (keine Repo-Namen/Pfade/Prompts), jederzeit abschaltbar — Details: docs/telemetry.md
-  1. Ja, aktivieren — anonymer Zähl-/Struktur-Datensatz, keine Pfade/Prompts/Repo-Namen.
-  2. Nein — keine Telemetrie senden.
+  Anonyme Usage-Telemetrie aktivieren? Strikt opt-in, jederzeit abschaltbar; was genau gesendet wird: docs/telemetry.md
+  1. Ja, aktivieren — sendet anonyme Zähl- und Strukturdaten (welche Phase lief, Erfolg oder Abbruch), whitelist-projiziert: keine Pfade, keine Prompts, keine Repo-Namen.
+  2. Nein — sendet nichts; die Frage kommt hier nicht wieder. Einschalten geht später mit `node scripts/telemetry.mjs` (das ist der Befehl dafür).
   Reply with the number of your choice. (No option is pre-recommended — the choice is yours.)
   ```
 

package/skills/session-start/phase-2-5-docs-planning.md

@@ -58,15 +58,15 @@ AskUserQuestion({
     options: [
       {
         label: "Dev (Recommended)",   // add "(Recommended)" to each detected audience
-        description: "Architektur-, Modul- oder Refactoring-Änderungen — aktualisiert CLAUDE.md (oder AGENTS.md auf Codex CLI), docs/dev/**, docs/adr/**."
+        description: "Architektur-, Modul-, Refactoring-Änderungen. Dann ändern sich CLAUDE.md bzw. AGENTS.md und `docs/dev/**, docs/adr/**` (Handbuch und Entscheidungen)."
       },
       {
         label: "User",
-        description: "Öffentlich sichtbare Änderungen — aktualisiert README.md, docs/user/**, examples/**."
+        description: "Öffentlich sichtbare Änderungen. Dann werden README.md und `docs/user/**, examples/**` (was Nutzer davon lesen) nachgezogen."
       },
       {
         label: "Vault",
-        description: "Strategische oder Status-Änderungen — aktualisiert <vault>/01-projects/<slug>/context.md, decisions.md, people.md."
+        description: "Strategische oder Status-Änderungen. Dann wird `<vault>/01-projects/<slug>/context.md, decisions.md, people.md` (die Projektakte dazu) nachgezogen."
       }
     ]
   }]
@@ -76,13 +76,13 @@ AskUserQuestion({
 **Codex CLI / Cursor IDE fallback (numbered Markdown list):**
 
 ```markdown
-Welche Audiences berührt dieser Scope? (Mehrfachauswahl möglich)
-
 Auto-detected: [dev]  ← list detected audiences here, or "none" if empty intersection
 
-1. **Dev (Recommended)** — Architektur-, Modul- oder Refactoring-Änderungen. Targets: CLAUDE.md (oder AGENTS.md auf Codex CLI), docs/dev/**, docs/adr/**.
-2. **User** — Öffentlich sichtbare Änderungen. Targets: README.md, docs/user/**, examples/**.
-3. **Vault** — Strategische oder Status-Änderungen. Targets: <vault>/01-projects/<slug>/context.md, decisions.md, people.md.
+Welche Audiences berührt dieser Scope? Mehrfachauswahl möglich.
+
+1. **Dev (Recommended)** — Architektur-, Modul-, Refactoring-Änderungen. Dann ändern sich CLAUDE.md bzw. AGENTS.md und `docs/dev/**, docs/adr/**` (Handbuch und Entscheidungen).
+2. **User** — öffentlich sichtbare Änderungen. Dann werden README.md und `docs/user/**, examples/**` (was Nutzer davon lesen) nachgezogen.
+3. **Vault** — strategische oder Status-Änderungen. Dann wird `<vault>/01-projects/<slug>/context.md, decisions.md, people.md` (die Projektakte dazu) nachgezogen.
 
 Enter one or more numbers (comma-separated), or press Enter to accept the recommended default.
 ```

package/skills/session-start/phase-4-5-resource-health.md

@@ -16,31 +16,88 @@ const verdict = evaluate(snapshot, config['resource-thresholds'], {
 });
 ```
 
-The `evaluate()` result has three fields:
-- `verdict`: `green` | `warn` | `critical`
-- `reasons`: array of human-readable explanations
+The `evaluate()` result has four fields:
+- `verdict`: `green` | `warn` | `critical` (the `degraded` tier is no longer produced)
+- `reasons`: array of human-readable explanations, including `info:`-prefixed
+  lines for signals that were seen but deliberately not acted on
 - `recommended_agents_per_wave_cap`: integer cap (0 = coordinator-direct) or null
+- `signals`: `{ hard: string[], soft: string[] }` — which axes fired (#1089)
 
 The third `options` argument is optional (HR-003/HR-004, baseline #60) — when `config['heavy-repo']` is `true`, the cap is forced to at most `config['agents-per-wave']` regardless of the live verdict (static preflight ceiling; more-restrictive-wins against whatever the resource signals already computed). Omitting `options` entirely preserves pre-#60 behaviour.
 
-## Adaptive Rules (default thresholds; configurable via `resource-thresholds`)
-
-| Signal | Threshold | Action |
-|--------|-----------|--------|
-| RAM free below `ram-free-min-gb` (default 4) | warn | Cap `agents-per-wave` at 2 |
-| RAM free below `ram-free-critical-gb` (default 2) | critical | Recommend coordinator-direct (0 agents) |
-| CPU load above `cpu-load-max-pct` (default 80) sustained — judged on **min(1m, 5m)** load average (#943) | warn | Cap `agents-per-wave` at 2 |
-| Claude processes ≥ `concurrent-sessions-warn` (default 5) | warn | Warn; suggest sequencing or waiting |
-| SSH session detected AND `ssh-no-docker: true` | info | Append note: host is SSH-attached, Docker-dependent steps should run on a local dev host |
-
-**CPU methodology (#943):** the gate/probe runs right after the coordinator's own CPU-saturating quality-gate run by construction, so the 1-minute load average systematically carries that decaying tail (observed: 96% → 75% within 36s). `probe()` therefore also emits `cpu_load_5m` / `cpu_load_5m_pct`, and `evaluate()` + `evaluateWaveResourceGate()` judge the CPU threshold on **min(1m, 5m)**: only-1m-high is reported as an informational "decaying transient" reason without capping; both-high (genuine sustained load) still caps. When `cpu_load_5m_pct` is `null` (Windows, zero-load), judging falls back to the 1m-derived `cpu_load_pct` alone.
+## Adaptive Rules (rebuilt in #1089 — see `.claude/rules/host-resources.md`)
+
+The rule set is **signal precedence + the two-signal rule**, not a list of
+independent thresholds ORed together. Measured 2026-08-21 over 1477
+`orchestrator.session.started` events across 18 repos, the previous OR-of-three
+produced warn-or-worse on **99.0%** of session starts — a warning that fires
+almost always changes no decision except how fast it gets ignored.
+
+**Memory — judge on the best signal present, never on a worse one:**
+
+| Precedence | Signal | Hard (→ critical) | Soft |
+|---|---|---|---|
+| 1 | `memory_pressure_pct_free` (macOS) | `< 15%` | `< 30%` |
+| 2 | `ram_available_gb` (macOS, vm_stat) | `< ram-free-critical-gb` | `< ram-free-min-gb` |
+| 3 | `ram_free_gb` (`os.freemem`) | same | same |
+
+Level 3 is reached only when neither better signal exists — i.e. on
+Linux/Windows, where `os.freemem()` is accurate. On Darwin it reports `Pages
+free` only (median **0.4 GB** across the corpus, on 24-128 GB hosts), so gating
+on it there fired the *critical* threshold on 84.0% of starts.
+
+**Other axes:**
+
+| Signal | Threshold | Class |
+|---|---|---|
+| CPU, judged on **min(1m, 5m)** (#943) | above `cpu-load-max-pct` (default 90) | soft |
+| Live peer **sessions** from the registry | ≥ `concurrent-sessions-warn` (default 5) | soft |
+| Claude **processes** (fallback only, registry unreadable) | ≥ threshold × 6 | soft |
+| Swap, **only while memory is unhealthy** | `> 3072 MB` hard / `> 1024 MB` soft | both |
+| Zombie processes with a live peer/process context | ≥ 1 | **info** (reported, never counted — see HR-104) |
+| SSH detected AND `ssh-no-docker: true` | — | info note |
+
+**Verdict composition:**
+
+- any **hard** signal → `critical`, recommend coordinator-direct (0 agents)
+- **two or more independent soft** signals → `warn`, cap agents-per-wave at 2
+- exactly **one soft** signal → `green`, reported in `reasons`, **no cap**
+- none → `green`
+
+`evaluate()` additionally returns `signals: { hard: [...], soft: [...] }` so a
+caller can log which axes fired rather than re-deriving them from prose.
+
+**Unit note (#1089):** `concurrent-sessions-warn` is denominated in SESSIONS. It
+was compared against `claude_processes_count` until this rebuild — a measured 6x
+unit error (median processes:sessions = 6.0 over 1461 paired samples) that made
+the threshold fire on 93.6% of starts instead of 4.2%. `probe()` now supplies
+`peer_sessions_count` from the session registry (`detectPeers()`, self excluded,
+heartbeat-fresh); the rescaled process count is a fallback for hosts where the
+registry is unreadable.
+
+**CPU methodology (#943):** the gate/probe runs right after the coordinator's own
+CPU-saturating quality-gate run by construction, so the 1-minute load average
+systematically carries that decaying tail (observed: 96% → 75% within 36s).
+`probe()` therefore also emits `cpu_load_5m` / `cpu_load_5m_pct`, and both
+`evaluate()` and `evaluateWaveResourceGate()` judge CPU on **min(1m, 5m)**:
+only-1m-high is reported as an informational "decaying transient" and is NOT
+counted as a signal at all — so it cannot become the second signal that triggers
+a cap. When `cpu_load_5m_pct` is `null` (Windows, zero-load), judging falls back
+to `cpu_load_pct` alone.
 
 ## Presentation
 
 Print a one-line Resource Health verdict immediately after Phase 4's output:
 
 ```
-Resource Health: ⚠ warn — RAM free 3.1 GB below threshold 4 GB; capping agents-per-wave at 2.
+Resource Health: ⚠ warn — two signals agree (cpu + concurrency); capping agents-per-wave at 2.
+```
+
+On `green` with a reported signal, print the line but say plainly that nothing
+was capped — a bare signal with no consequence reads as a suppressed warning:
+
+```
+Resource Health: ✓ green — 6884 MB swap present but memory_pressure healthy (53% free); no cap.
 ```
 
 When `config['heavy-repo']` is `true` and the HR-004 preflight ceiling actually reduces `recommended_agents_per_wave_cap` below what the live verdict alone would have produced, print an additional banner line right after the verdict line:
@@ -49,10 +106,16 @@ When `config['heavy-repo']` is `true` and the HR-004 preflight ceiling actually
 ⚠ Heavy-repo mode active — agents-per-wave capped to 4 (Session Config heavy-repo: true)
 ```
 
-When verdict is `warn` or `critical`, use the AskUserQuestion tool to present:
-1. **Proceed as recommended** (apply the cap) — Recommended
-2. **Proceed as originally planned** (user accepts the risk)
-3. **Abort** (no wave planning runs; user closes or investigates)
+**AUQ only on `critical`** (#1089). A `warn` applies its cap and reports it in
+one line — it does not interrupt. Under the previous rule set warn-or-worse was
+the verdict on 99.0% of session starts, so an AUQ here was an operator interrupt
+on essentially every session, which `.claude/rules/ask-via-tool.md` AUQ-005
+names outright ("an AUQ that blocks nothing"). `critical` means coordinator-direct
+— zero agents — which genuinely changes the plan, so it earns the prompt:
+
+1. **Proceed coordinator-direct** (0 agents) — Recommended
+2. **Proceed as originally planned** (operator accepts the risk)
+3. **Abort** (no wave planning runs; operator closes or investigates)
 
 When SSH is detected and the session type is `deep`, auto-append this note to the plan handoff to session-plan (no user prompt needed):
 > Host is SSH-attached — Docker-dependent wave steps should run on a local dev host.

package/skills/session-start/soul.md

@@ -64,6 +64,116 @@ The active level is `efficiency.output-level` in `~/.config/session-orchestrator
 - Shape: explain the WHY behind each recommendation, name the alternatives you rejected and why, spell out unfamiliar terms on first use.
 - Escalation: `expand <topic>` — see § Escalation above.
 
+### Register — how a sentence reads
+
+The budgets above set *how much* you say. This sets *how*. It binds at every
+level and is not itself a budget: applying it changes word order and word
+choice, not line count. It is the canonical statement for this repo — the
+other three souls (`plan`, `brainstorm`, `grill`) point here rather than
+copying it.
+
+**Write for someone who knows this project but has not seen what you just saw.**
+What he needs to decide stands in the text, not in the file it points at — in
+the AUQ payload and in every finding you post.
+
+This is not "explain it like he is five". The operator owns this repo. He is
+not missing knowledge, he is missing **observation** — he did not watch the
+command you just ran or read the file you just opened. A knowledge framing
+would be factually wrong and condescending at the same time. Write across, not
+down: same expertise as yours, minus your last ten minutes.
+
+#### Plain words, real things
+
+> **Say more simply what actually happens — and introduce nothing that does not exist.**
+>
+> **The test:** delete every noun the system does not contain. If the sentence
+> is still true and complete, it was no analogy. If it collapses, the analogy
+> was load-bearing — replace it with a description of what actually happens.
+
+Five worked cases, in rising difficulty:
+
+1. "Waiting means the other session finishes first." — **allowed.** Sessions
+   and waiting both exist; nothing foreign was introduced.
+2. "Think of the session as a level crossing." — **forbidden.** Delete "level
+   crossing" and nothing is left. Say what happens instead: one session holds
+   `.orchestrator/session.lock`, the other waits for it.
+3. "The token budget is used up." — **allowed.** `TOKEN_BUDGET_EXCEEDED` is a
+   real identifier and "budget" is the system's own word. Adding "…like a tank
+   of fuel" would be forbidden — the tank does not exist.
+4. "Think of the kill-switches as a fuse box." — **forbidden, and wrong on the
+   facts.** Fuses trip on overload; the kill-switches also test elapsed time and
+   confidence. The image sounds helpful and is not. A wrong picture costs more
+   than no picture, because the operator reasons from it.
+5. **Dead metaphors.** A proper name may itself be a metaphor —
+   `pre-bash-destructive-guard` is called a guard — and you use the name as
+   given. Reviving the image is the violation: "the guard will not let it
+   through" invites the operator to picture a guard and then reason from the
+   picture instead of from the hook. Name the identifier, then say what it
+   does: the hook denies the Bash call.
+
+#### Precedence over § "Never traded for brevity"
+
+There is a real collision above: "say it more simply" can water down a precise
+error message. Resolve it in three steps.
+
+1. **Simplifying removes words, never facts.** If a path, a number, an error
+   code, an identifier, or an instruction to act disappears, that is data loss,
+   not simplification — and § "Never traded for brevity" already forbids it.
+2. **When both will not fit in one sentence: precision in the sentence,
+   plainness in the one beside it.** The exact term is never replaced, only
+   accompanied. It is what the operator greps, quotes, and pastes into an issue.
+3. **The mechanical tie-breaker:** could the token you are about to cut ever
+   appear in a `grep`? Then it stays.
+
+Measured 2026-08-22 at `a4f93cf`: of 191 option descriptions in this repo, the
+20 that match the safety lexicon (`SAFETY_PATTERN` in
+`scripts/lib/auq/schema.mjs`) run 26–108 codepoints — all of them under both K6
+length thresholds (`descriptionCharsWarn` 120, `descriptionCharsFail` 150). The
+collision therefore does not occur today. This precedence rule is a precaution,
+not a repair.
+
+#### Worked example — an operator-visible message
+
+`formatBlockReason()` in `scripts/lib/issue-budget.mjs` is what the operator
+sees when the issue cap blocks a creation. Rendered with the collector-issue
+sink, before:
+
+```
+issue-budget: session cap reached — 12/12 issues already created.
+This request was NOT created. It is parked as overflow entry #3 in:
+  .orchestrator/runtime/issue-budget-overflow.jsonl
+session-end Phase 5 will fold all overflow entries into ONE collector issue `[Backlog-Sammel] <session-id>, N zurückgestellte Punkte`. Nothing is lost.
+Exempt from the cap: priority::critical, the carryover class (SPIRAL/FAILED, [Carryover]),
+and broken-window closure issues — those are never deferred.
+To raise the cap for this repo, edit `issue-budget.max-per-session` in the Session Config;
+`mode: warn` reports without blocking, `mode: off` disables the gate.
+```
+
+After:
+
+```
+Nothing is lost — the issue is parked, and nothing needs doing right now.
+issue-budget: session cap reached — 12/12 issues already created, so this one was NOT created.
+It is parked as overflow entry #3 in:
+  .orchestrator/runtime/issue-budget-overflow.jsonl
+session-end Phase 5 folds all overflow entries into ONE collector issue `[Backlog-Sammel] <session-id>, N zurückgestellte Punkte`.
+Exempt from the cap: priority::critical, the carryover class (SPIRAL/FAILED, [Carryover]),
+and broken-window closure issues — those are never deferred.
+To raise the cap for this repo, edit `issue-budget.max-per-session` in the Session Config; `mode: warn` reports without blocking, `mode: off` disables the gate.
+```
+
+Three changes, and only these three: the operator's own question — *must I do
+something?* — moved to line 1, carrying "Nothing is lost" up from line 4 where
+he used to reach it last; `will fold` became the active `folds`; and the first
+two lines merged on a causal `so`, which is why "This request" is now "this
+one" — the same subject, already named in the sentence.
+
+The whole word-level diff is four dropped tokens: `This`, `request`, `will`,
+`fold`. Not one of them is a path, a count, a label, a config key, or a mode
+value; every one of those survives character for character. Eight lines before,
+eight lines after — **this register is not a diet.** It is the same facts, in
+the order the reader needs them.
+
 ### Companion dials
 
 Same file, same lookup, same fallback-to-default rule:

package/skills/spinout/SKILL.md

@@ -2,7 +2,11 @@
 name: spinout
 user-invocable: true
 model: sonnet
-description: Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its incubator repo) or a sanitized content-snapshot fork. Guided 5-step runbook: target sphere + path, confidentiality/sanitize check, copy + fresh git init, SNAPSHOT-FREEZE marker in the source repo, remotes + registration. Trigger on 'spin out X', 'extract this into its own repo', 'fork X sanitized'.
+description: >
+  Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its
+  incubator repo) or a sanitized content-snapshot fork. Guided 5-step runbook: target sphere + path,
+  confidentiality/sanitize check, copy + fresh git init, SNAPSHOT-FREEZE marker in the source repo,
+  remotes + registration. Trigger on 'spin out X', 'extract this into its own repo', 'fork X sanitized'.
 ---
 
 # spinout — Guided Project-Extraction Runbook

package/skills/sunset-review/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: sunset-review
-description: Use this skill when the user wants to identify unused, near-zero-use, or stale skills/agents/commands in the plugin surface so they can be demoted or retired. Combines agent-dispatch telemetry (start-events only) with static reference scanning, classifies every surface item into Active / Investigate / Demote / Retire, and emits a Markdown report plus JSON sidecar. NEVER auto-deletes — surfaces candidates for human decision. Quarterly cadence. <example>Context: The plugin surface has grown and the maintainer wants to prune dead weight. user: "/sunset-review" assistant: "Running the sunset walk — classifying skills, agents, and commands by usage telemetry + static refs, grouped by Retire / Demote / Investigate / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision." <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker, presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>
+description: >
+  Use this skill when the user wants to identify unused, near-zero-use, or stale skills/agents/commands in
+  the plugin surface so they can be demoted or retired. Combines agent-dispatch telemetry (start-events
+  only) with static reference scanning, classifies every surface item into Active / Investigate / Demote /
+  Retire, and emits a Markdown report plus JSON sidecar. NEVER auto-deletes — surfaces candidates for
+  human decision. Quarterly cadence. <example>Context: The plugin surface has grown and the maintainer
+  wants to prune dead weight. user: "/sunset-review" assistant: "Running the sunset walk — classifying
+  skills, agents, and commands by usage telemetry + static refs, grouped by Retire / Demote / Investigate
+  / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision."
+  <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker,
+  presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>
 model: inherit
 color: amber
 ---

package/skills/test-runner/SKILL.md

@@ -216,11 +216,11 @@ Group `medium` and `low` findings and present via a single `AskUserQuestion` cal
 AskUserQuestion({
   questions: [{
     question: `<N> medium/low findings to triage. How to handle?`,
-    header: "Test-runner triage",
+    header: "Triage",
     options: [
       {
         label: "Create all (Recommended)",
-        description: "File <N> new issues, all with label from:test-runner"
+        description: "Files <N> new issues at once, all with label from:test-runner — fastest, and you can still close any of them afterwards."
       },
       {
         label: "Review each",

package/skills/tmux-layout/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: tmux-layout
-description: Use this skill when the operator wants a prepared tmux visualization layout for the session's side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug layout. Read-only side-channel observability — the coordinator chat stays in the operator's original terminal. Trigger phrases: "tmux layout", "split panes for ci watch", "visualize session side-channels", "show me state-md tail and ci".
+description: >
+  Use this skill when the operator wants a prepared tmux visualization layout for the session's
+  side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug
+  layout. Read-only side-channel observability — the coordinator chat stays in the operator's original
+  terminal. Trigger phrases: "tmux layout", "split panes for ci watch", "visualize session side-channels",
+  "show me state-md tail and ci".
 model: inherit
 color: cyan
 tools: Read, Bash, Grep, Glob
@@ -47,7 +52,7 @@ The skill prints a one-line tmux command. Paste it into a SECOND terminal (do no
 |---|---|---|
 | 1 | **Shell** (operator scratch — NOT claude) | `bash` (interactive) |
 | 2 | STATE.md tail | `tail -F <state-dir>/STATE.md` |
-| 3 | CI watch (poll-loop wrapper) | `while true; do clear; glab ci status --pipeline-id LATEST --output json \| jq ...; sleep 15; done` |
+| 3 | CI watch (poll-loop wrapper) | `while true; do clear; glab ci status -R <spec> --output json \| jq -r '.jobs[] \| ...'; sleep 15; done` |
 | 4 | events.jsonl wave/gate filter | `tail -F .orchestrator/metrics/events.jsonl \| jq --unbuffered 'select(.event \| test("wave\|gate\|spiral"))'` |
 | 5 | agent-status telemetry (#565, only with `--with-status-pane`) | `while true; do clear; jq . .orchestrator/runtime/agent-status-current.json 2>/dev/null \|\| echo ...; sleep 2; done` |