session-orchestrator 3.21.0 → 3.22.0

package/skills/session-end/SKILL.md

@@ -141,7 +141,8 @@ For every `SPIRAL` or `FAILED` agent surfaced in the walk above, ALSO append a c
 ```js
 import { appendWhatNotToRetryOnDisk } from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
 
-// `parsed` = parseStateMd(STATE.md); session id from the `session:` frontmatter field.
+// `parsed` = parseStateMd(STATE.md); `session:` is an attribution/history label.
+// It records this entry's provenance only and never authorizes lock ownership.
 const sessionId = parsed.frontmatter.session ?? 'unknown-session';
 const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
 
@@ -646,7 +647,7 @@ import { planTailPhases } from '${PLUGIN_ROOT}/scripts/lib/session-end/phase-ski
 const { plan, skippedReport } = await planTailPhases({
   repoRoot: process.cwd(),
   config,        // parsed Session Config (from $CONFIG)
-  sessionId,     // session.lock `session_id` / STATE.md `session:` field (or null)
+  sessionId,     // physical session.lock `session_id` only (or null), never STATE.md `session`
   platform,      // 'claude' | 'codex' | 'cursor'
 });
 // plan: Array<{ phase, run, reason, inputSource }>, already in ascending phase order.
@@ -733,20 +734,21 @@ After STATE.md is finalized with `status: completed` (Phase 3.4) and Recommendat
 
 ```javascript
 import { release } from 'scripts/lib/session-lock.mjs';
-// sessionId = the session identifier established by session-start Phase 1.2 acquire()
-//   and stored in .orchestrator/session.lock (session_id field); matches the
-//   STATE.md frontmatter `session:` field written during Pre-Wave 1b initialization.
-const result = release({ sessionId, repoRoot: process.cwd() });
+// sessionId is the physical raw value established by session-start Phase 1.2
+// and stored in .orchestrator/session.lock `session_id`. It is not STATE.md
+// `session:` or `semantic_session_id`, both of which are attribution labels.
+const rawSessionId = sessionId;
+const result = release({ sessionId: rawSessionId, repoRoot: process.cwd() });
 // result.ok is always true unless a filesystem error occurred.
 // result.deleted === true  → lock file removed successfully.
-// result.deleted === false → lock was absent or belonged to a different session_id (silent-OK).
+// result.deleted === false → lock was absent or had a different raw session_id.
 ```
 
-If `result.deleted === false`, log `info: session-lock not released — already absent or session_id mismatch (no action needed)` and continue. This is a non-error state.
+If `result.deleted === false`, log `info: session-lock not released — already absent or raw session_id mismatch` and continue. An active lock whose raw id differs is ambiguous: do **not** retry release with an equal `semantic_session_id`, STATE.md `session`, or owner proof. Leave that live lock for its TTL/Reaper lifecycle.
 
 If `result.ok === false` (rare filesystem error), log `⚠ session-lock: release failed — <result.reason>` and continue. Do NOT block the close for a lock-release failure — the TTL provides automatic expiry for the next session.
 
-The lock is released here — AFTER all STATE.md writes are complete and BEFORE the commit is staged in Phase 4.1. This ordering ensures a clean handover: the lock file is absent from the working tree when the commit is assembled, so it is not accidentally staged.
+The lock is released here — AFTER all STATE.md writes are complete and BEFORE the commit is staged in Phase 4.1. This ordering ensures a clean handover when the current raw owner releases it: the lock file is absent from the working tree when the commit is assembled, so it is not accidentally staged.
 
 ## Phase 4: Commit & Push
 
@@ -890,15 +892,24 @@ if (!promoted) {
 When the worktree is dirty (uncommitted, untracked, OR unpushed), render this AUQ via the coordinator's `AskUserQuestion` tool. The AUQ is coordinator-only — per `.claude/rules/ask-via-tool.md` AUQ-004, dispatched agents cannot call AUQ. Calling `git worktree remove --force` without explicit operator confirmation would violate PSA-003 (destructive action safeguards) — the dirty state may contain another session's work-in-progress or unmerged commits.
 
 ```js
+// What is actually at stake, shown beside the options via `preview` (AUQ-006):
+// the operator must see WHICH changes he would lose before he authorises the delete.
+// Capped at 10 lines so the preview never outgrows the option list next to it.
+const dirtyDetail = execFileSync('git', ['-C', promoted.wtPath, 'status', '--short', '--branch'], { encoding: 'utf8' })
+  .trim()
+  .split('\n')
+  .slice(0, 10)
+  .join('\n');
+
 AskUserQuestion({
   questions: [{
     question: `Auto-promoted worktree at ${promoted.wtPath} has uncommitted/untracked/unpushed changes. How should I proceed?`,
-    header: "Worktree-Cleanup",
+    header: "Worktree",
     multiSelect: false,
     options: [
-      { label: "Behalten (Recommended)", description: "Keep the worktree as-is. No cleanup. Review and remove manually later." },
-      { label: "Löschen", description: "I confirm the changes are handled or expendable. Run 'git worktree remove --force' on the worktree." },
-      { label: "Manuell", description: "Exit /close. I will inspect the worktree before re-running /close." },
+      { label: "Behalten (Recommended)", description: "Keeps the worktree exactly as it is — nothing is deleted, and you can still remove it by hand later.", preview: `Stays on disk:\n${dirtyDetail}` },
+      { label: "Löschen", description: "I confirm the changes are handled or expendable. Run 'git worktree remove --force' on the worktree.", preview: `Deleted with the worktree:\n${dirtyDetail}` },
+      { label: "Manuell", description: "Exit /close. I will inspect the worktree before re-running /close.", preview: `You would inspect this first:\n${dirtyDetail}` },
     ],
   }],
 });
@@ -907,8 +918,8 @@ AskUserQuestion({
 **Codex CLI / Cursor IDE fallback** (numbered Markdown list):
 
 ```
-Worktree cleanup options:
-1. **Behalten (Recommended)** — Keep the worktree as-is. No cleanup. Review and remove manually later.
+Worktree cleanup options (the changes at stake are the `git status --short --branch` lines printed above):
+1. **Behalten (Recommended)** — Keeps the worktree exactly as it is; nothing is deleted, and you can still remove it by hand later.
 2. **Löschen** — I confirm the changes are handled or expendable. Run 'git worktree remove --force'.
 3. **Manuell** — Exit /close. I will inspect the worktree before re-running /close.
 Reply with the number of your choice.
@@ -1026,16 +1037,38 @@ if (sweep) {
     **Ordering (load-bearing):** run this as the LAST issue-creating action of Phase 5 — after step 3, after "Discovery Issue Creation", after step 4 — and re-read the counter file at that moment. Those steps can themselves push new entries into `overflow[]`; draining early would leave them unfiled.
 
     ```js
-    import { readBudgetState, budgetStatePath } from '${PLUGIN_ROOT}/scripts/lib/issue-budget.mjs';
-    const state = readBudgetState(repoRoot, sessionId);   // { sessionId, count, exempt, overflow: [...] }
+    import { readFileSync } from 'node:fs';
+    import {
+      readBudgetState,
+      budgetStatePath,
+      resolveIssueBudgetSessionId,
+    } from '${PLUGIN_ROOT}/scripts/lib/issue-budget.mjs';
+
+    // `sessionId` is the physical raw lock/registry identity from session-start.
+    const rawSessionId = sessionId;
+    let currentSession = null;
+    try {
+      currentSession = JSON.parse(
+        readFileSync(`${repoRoot}/.orchestrator/current-session.json`, 'utf8'),
+      );
+    } catch { /* no verified semantic accounting bridge */ }
+    const accountingSessionId = resolveIssueBudgetSessionId(rawSessionId, currentSession);
+    const state = readBudgetState(repoRoot, accountingSessionId);
+    // { sessionId, count, exempt, overflow: [...] }
     ```
 
+    `accountingSessionId` may be semantic only after
+    `currentSession.session_id === rawSessionId`; this is budget accounting, not
+    lock/registry ownership. When that proof is absent it remains the raw id.
+    A host rotation that changes both raw and semantic values has no guaranteed
+    budget continuity.
+
     - **`issue-budget.overflow: collect-issue` (default)** — create exactly ONE issue:
-      - Title: `[Backlog-Sammel] <session-id>, <N> zurückgestellte Punkte`
+      - Title: `[Backlog-Sammel] <accountingSessionId>, <N> zurückgestellte Punkte`
       - Labels: `type::backlog`, `priority::low`
       - Body: a Markdown checklist with one `- [ ]` line per `overflow[]` entry (`title` when present, otherwise the truncated `command`, plus its `at` timestamp).
       - This collector issue is itself EXEMPT from the cap (`[Backlog-Sammel]` is in the exemption list in `scripts/lib/issue-budget.mjs`), so it always lands even at count == max.
-    - **`issue-budget.overflow: vault-note`** — create NO issue. Write one Markdown file `vault/00-inbox/<session-id>-backlog-sammel.md` (path relative to `vault-integration.vault-dir`) with valid vault frontmatter and the same checklist body.
+    - **`issue-budget.overflow: vault-note`** — create NO issue. Write one Markdown file `vault/00-inbox/<accountingSessionId>-backlog-sammel.md` (path relative to `vault-integration.vault-dir`) with valid vault frontmatter and the same checklist body.
     - After the artefact exists, reset `overflow` to `[]` in the counter file and record the collector issue ID / note path in the Phase 6 Final Report under `### Zurückgestellt (issue-budget)`.
     - **Never exempt-by-accident:** the cap never applied to `priority::critical`, the carryover class (`[Carryover]`, SPIRAL/FAILED, `type::carryover`), or `broken-window` closure issues, so nothing on the Phase 1.65 carry-list can ever appear in `overflow[]`. The promises at Phase 1.8 ("SPIRAL / FAILED agent carryover … non-deselectable") and the Critical Rule "ALWAYS create issues for unfinished PLANNED work" stay intact by construction.
     - Fail-open: a missing or malformed counter file means "no overflow" — log a WARN and continue the close.
@@ -1134,7 +1167,7 @@ Present to the user:
 | `phase-3-7a-recommendations.md` § 3.7b | Phase 3.7b full procedural body — `withDurableCommit` invocation for `sessions.jsonl` + `STATE.md` (#490 AC2), `enabled:false` local no-op, autopilot.jsonl exclusion note |
 | (inline) Phase 3.7c | Vault Board → Closed (#674) — `mirrorBoard({ explicitStatus: 'closed' })` transitions this repo's board row to `closed`; gated on `vault-integration.enabled`, generator-marked + idempotent, non-blocking, ordered after 3.7b and before 3.7d/3.4/3.8 |
 | (inline) Phase 3.7d | Session-Eval (opt-in — #803) — `node scripts/eval-session.mjs --json` scores the just-closed session; gated on `eval.enabled` + `eval.mode != off` (parsed by `scripts/lib/config/eval.mjs`), optional `eval-judge` dispatch + `writeEvalReport`, advisory/never-blocks-close, ordered after 3.7 (record must exist) and before 3.4/Phase 4 (record committed with the session). Full flow in `skills/eval/SKILL.md` |
-| (inline) Phase 3.8 | Session Lock Release — `release()` call, silent-OK on mismatch/absent, non-fatal on fs-error, ordering note (after STATE.md writes, before Phase 4 commit staging) |
+| (inline) Phase 3.8 | Session Lock Release — `release()` uses the physical raw `session_id`; raw mismatch/absent is non-fatal but never repaired with semantic labels or proof (live ambiguity remains for TTL/Reaper); fs-errors are non-fatal; runs after STATE.md writes and before Phase 4 commit staging |
 
 ## Anti-Patterns
 

package/skills/session-end/phase-3-6-tail.md

@@ -81,7 +81,25 @@ The proposals queue is populated mid-session by wave-executor agents calling `no
    }
    ```
 
-   Then iterate `batches` and emit one `AskUserQuestion` per batch with `header: "Memory — Confirm Proposals (Batch N of M)"`. Option label format: `[<type-12>] | <subject-40> | conf=X.XX`. Option description: `evidence: <first 60 chars of insight>`. `multiSelect: true`.
+   Then iterate `batches` and emit one `AskUserQuestion` per batch. The verbatim template is `agents/memory-proposal-collector.md` § AUQ Question Template — keep the two in step:
+
+   ```javascript
+   AskUserQuestion({
+     questions: [{
+       header: "Memory",
+       question: "Batch <N> of <M> — which of these learnings should be stored permanently?",
+       options: [
+         // one entry per proposal in this batch (max 4)
+         // label + description formats are LOCKED by D3 — see that file, do not restate them here
+         { label: "[type   ] | subject(40) | conf=X.XX", description: "evidence: <first 60 chars of insight>" },
+         ...
+       ],
+       multiSelect: true
+     }]
+   })
+   ```
+
+   The batch counter moved out of `header` and into the question because `header` is cut off after 12 characters — `Memory — Confirm Proposals (Batch N of M)` reached the operator as `Memory — Con`.
 
 5. After all batches answered, partition the queue into `approved` (any option selected across all batches) and `rejected` (all unselected).
 
@@ -337,7 +355,24 @@ After the auto-dialectic nudge decision is made (Phase 3.6.7), and when the reco
    }
    ```
 
-   Iterate `batches` and emit one `AskUserQuestion` per batch with `header: "Reconciliation — Confirm Rule Proposals (Batch N of M)"`. Option label format: `<slug-40> | conf=<confidence>`. Option description: first 80 chars of the rendered `content` (the rule prose preview). `multiSelect: true`.
+   Iterate `batches` and emit one `AskUserQuestion` per batch:
+
+   ```javascript
+   AskUserQuestion({
+     questions: [{
+       header: "Regeln",
+       question: "Batch <N> of <M> — which rule proposals should be written into .claude/rules/?",
+       options: [
+         // one entry per proposal in this batch (max 4)
+         { label: "<slug-40>", description: "Confidence <confidence>. First 80 chars of the rendered rule text: <…>" },
+         ...
+       ],
+       multiSelect: true
+     }]
+   })
+   ```
+
+   The batch counter moved out of `header` and into the question because `header` is cut off after 12 characters — `Reconciliation — Confirm Rule Proposals (Batch N of M)` reached the operator as `Reconciliati`. The rendered `content` shown in the description is the rule prose that will land on disk.
 
 6. After all batches are answered, partition proposals into `approved` (any option selected across all batches) and `rejected` (all unselected). Proposals the operator rejected join the engine's `rejected` array for archival.
 

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>
+
+<N> snapshot(s) from the resumed session, newest <age>. Recover, keep, discard?
 
-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.
+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.
 
@@ -1049,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)." },
     ],
   }],
 });
@@ -1064,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.