session-orchestrator 5.11.0 → 5.12.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
-    "version": "5.11.0"
+    "version": "5.12.0"
   },
   "plugins": [
     {
@@ -24,6 +24,17 @@
       "keywords": ["session", "orchestration", "waves", "gitlab", "github", "quality-gates", "subagents"],
       "category": "productivity",
       "tags": ["session-management", "wave-execution", "vcs-integration", "code-review", "agent-orchestration"]
+    },
+    {
+      "name": "so-hud",
+      "source": "./mods/so-hud",
+      "description": "See Session Orchestrator status, warnings and session beacons in Claude Code. Read-only; needs the Session Orchestrator release that ships it, or later.",
+      "author": { "name": "session-orchestrator contributors" },
+      "homepage": "https://session-orchestrator.com",
+      "repository": "https://github.com/Kanevry/session-orchestrator",
+      "license": "MIT",
+      "category": "productivity",
+      "tags": ["status-line", "session-management", "agent-orchestration"]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "session-orchestrator",
-  "version": "5.11.0",
+  "version": "5.12.0",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.11.0+codex.20261010111731",
+  "version": "5.12.0+codex.20261011193338",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "keywords": [
     "session",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.11.0",
+  "version": "5.12.0",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer"

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.12.0] - 2026-10-11
+
+### Added
+
+- **so-hud, a native Claude Code status mod** (#1508): `mods/so-hud` (version 0.1.0) shows the session state (lock, registry, wave scope, agent status, STATE.md, gate and vault events) as a status line and, when something needs attention, a warning band, and writes one beacon per session that other sessions can read through `$.so.beacons()`; the status line shows how many peer sessions are running. It reads everything through `scripts/so-hud.mjs` (JSON v1 with provenance and `degraded`), keeps no second copy of the state and never changes a tool decision. It is listed in this repo's marketplace: `/plugin install so-hud@kanevry` (Claude Code only, tested with 2.1.296, Node.js 24+, Session Orchestrator 5.12.0 or later as the plugin or as a checkout set through `soRoot`). Status texts are German for now; an English table is prepared but not yet selectable.
+- **Mod CI gate** (#1508): the `mods:plugin` job runs `claude plugin validate --strict --json` and `claude plugin test` for every mod under `mods/` with Claude Code pinned once in `CLAUDE_CODE_VERSION` (2.1.296). It verifies the registry signatures of both downloaded packages, calls the platform binary directly so `ignore-scripts` stays on, runs without credentials or nonessential traffic, and is a hard dependency of `pipeline-gate`.
+- **Session-end names untracked vault files modified during the session** (#1563): new Phase 3.7e runs `scripts/vault-orphans.mjs`, which lists untracked files under `vault-dir` modified since the session started (`git ls-files --others --exclude-standard -z`, read-only) and leaves out files carrying a `_generator: session-orchestrator-` marker. The close names them in the final report and records one Open Question with the path list; it never commits, moves or deletes anything in the vault, because a modification time does not prove which session wrote a file. A vault that cannot be read is reported as "could not measure", never as "none". There is no blanket exclusion of `40-learnings/` and `50-sessions/`: an unmarked file there blocks every later mirror auto-commit and is exactly the case to surface.
+
+### Fixed
+
+- **The Mode-Selector sees the previous session's recommendation again** (#1560): the session-start Idle Reset was prose only, and its rule 6 deleted the five recommendation keys from the STATE.md frontmatter that Phase 7.5 reads through `buildLiveSignals()`, so after every clean `/close` the selector answered with confidence 0. The reset is now code (`scripts/lib/state-md/idle-reset.mjs`, CLI `scripts/state-md-idle-reset.mjs`, written under the STATE.md lock) and keeps those keys; session-end Phase 3.7a overwrites them at the next close. Without a new Wave History the earlier `## Previous Session` archive stays below the new recommendations copy. `parseRecommendations()` accepts `"#42"` and `"42"` in `top-priorities` and drops free-text entries instead of discarding the whole list.
+- **A first `/session` no longer starts `deep` silently** (#1561): a bare `/session` in a repo whose `.orchestrator/metrics/sessions.jsonl` holds no real session resolves with `defaultReason: "no-session-history"`, and `commands/session.md` then asks for task and mode first (recommending `feature`). A linked worktree reads its main checkout's ledger, and an unreadable ledger counts as not measured, so neither triggers the question.
+- **Solo users see no fleet machinery** (#1559): without fleet integration (`NAVIGATOR_CONFIG_DIR` unset and no `~/.config/navigator/` directory), `scripts/fleet-checkin.mjs` still validates its input, then writes nothing, creates no directory, emits no event and prints `skipped: "no-fleet"`; a headless (`plattform: kopflos`) run without fleet integration applies the Standard-Auflagen instead of writing. The SessionStart banner drops the navigator line. In a git repository without `.orchestrator/bootstrap.lock` (neither at the toplevel nor in the session directory) the first banner action is `/bootstrap`, in place of the decision nudge whose `/go` and `/close` do not work before setup; once bootstrapped, the nudge returns and now reads in plain words instead of naming an internal rule file. The hint no longer follows `cold-start.enabled`, which governs only the post-bootstrap first-session nudge.
+- **The npm package no longer ships this repo's own `AGENTS.md`** (#1559): it carried the maintainer's Session Config (vault path, remote host aliases), and no consumer reads an instruction file from the installed package. `tests/scripts/pack-policy-floor.test.mjs` keeps root `AGENTS.md` and `CLAUDE.md` out of the tarball. Config examples use the neutral alias `build-host`.
+- **Install docs match current Claude Code** (#1369, #1559): `docs/install.md` runs `npm install` in the plugin cache only when `node_modules/js-yaml` is missing, since `/plugin install` already provisions the dependencies. The README quickstart says that `/bootstrap` writes the Session Config and names `/bootstrap --fast --no-interview` as the shortest path. The website install step (EN and DE) and the guide use the same conditional command (#1564).
+- **One identity for a repo reached through a symlink** (#1557): `repoPathHash()` and the registry's `repo_name` resolve the real path (`realpathSync.native`, falling back to `path.resolve` when the path is unavailable), so a session in a symlink and one in its target count as the same repo for peer discovery, session transition and the live-status board. Board keys of canonical paths are unchanged. A board row stored under a pre-#1557 alias key is adopted on its first fresh write when it names the same repo; a row of another repo that merely shares the 8-character key stays. Registry entries written before the update keep their old hash until the session registers again.
+- **Umlauts survive in new learning-note slugs** (#1548): vault-mirror transliterates the slugs of new learning notes with a traceable origin (ä to ae, ö to oe, ü to ue, ß to ss, accents after NFC) instead of deleting the characters ("grnes" for "grünes"). Existing notes with a traceable origin keep their path, file name and id, and namespace and tags stay as they were, so auto-commit, relocation and backfill see the same folder. Session notes, tags and records without a traceable origin keep the historical slug, which drops umlauts; the backfill reverse lookup does not find older notes with umlauts; æ, ø, ł and œ are still dropped.
+- **No overwriting another repo's fleet check-in** (#1556): `scripts/fleet-checkin.mjs` exits 2 and writes nothing when the check-in file for the same semantic session id already belongs to another repo; the same repo still updates its own check-in. The existing file is opened without following symlinks and without blocking, read only as a regular file of at most 64 KiB, and the foreign repo name is printed as a JSON string on one stderr line.
+
 ## [5.11.0] - 2026-10-11
 
 ### Added

package/README.md

@@ -1,8 +1,9 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-5.11.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.12.0-blue.svg)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
+[![Release](https://img.shields.io/github/v/release/Kanevry/session-orchestrator)](https://github.com/Kanevry/session-orchestrator/releases/latest)
 
 **Give your agents a working rhythm.**
 
@@ -34,9 +35,18 @@ Longer explanation, with examples and screenshots: **[session-orchestrator.com](
 
 You need **Node.js 24 or later**, a git repository, and one of the four agents below. Full requirements, upgrade path and uninstall: [docs/install.md](docs/install.md).
 
+In Claude Code, two lines:
+
+```text
+/plugin marketplace add Kanevry/session-orchestrator
+/plugin install session-orchestrator@kanevry
+```
+
+Optional, Claude Code only: `/plugin install so-hud@kanevry` adds a status line for the running session ([mods/so-hud](mods/so-hud/README.md)).
+
 | Platform | Install |
 |---|---|
-| **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry`, then [install its Node dependencies once](docs/install.md#claude-code-install-the-node-dependencies-once). |
+| **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry`, then [check its Node dependencies once](docs/install.md#claude-code-check-the-node-dependencies) (current Claude Code installs them for you). |
 | **Codex CLI** | `git clone` the repo, `npm install`, then `node scripts/codex-install.mjs` ([guide](docs/codex-setup.md)). |
 | **Cursor IDE** | `git clone` the repo, `npm install`, then `node scripts/cursor-install.mjs /path/to/your/project` ([guide](docs/cursor-setup.md)). |
 | **Pi** | `pi install npm:session-orchestrator` ([guide](docs/pi-setup.md)). |
@@ -45,9 +55,9 @@ After a clone-based install (Codex CLI, Cursor IDE, or contributing), run `npx h
 
 ## Quick Start
 
-**1. Run `/bootstrap` once in your project.** It creates the minimum structure and writes `.orchestrator/bootstrap.lock`. `/session` refuses to start until that file exists.
+**1. Run `/bootstrap` once in your project.** It creates the minimum structure, writes `.orchestrator/bootstrap.lock` and adds a Session Config. `/session` refuses to start until the lock exists. For the shortest path, `/bootstrap --fast --no-interview` skips the tier question and the personal-preferences interview; run that interview later with `/bootstrap --owner-reset`.
 
-**2. Add a Session Config** to your project's instruction file — `CLAUDE.md` on Claude Code and Cursor, `AGENTS.md` on Codex CLI and Pi ([which file each platform reads](skills/_shared/instruction-file-resolution.md)). These seven fields are enough:
+**2. Check the Session Config** that `/bootstrap` wrote into your project's instruction file — `CLAUDE.md` on Claude Code and Cursor, `AGENTS.md` on Codex CLI and Pi ([which file each platform reads](skills/_shared/instruction-file-resolution.md)). Add it by hand only if the block is missing. These seven fields are enough:
 
 ```yaml
 ## Session Config
@@ -139,16 +149,16 @@ How this compares to other orchestrators, with measured results kept separate fr
 
 All four platforms share the same skills, commands and scripts; only the hooks differ, because each harness fires different events. Codex leaves its `PreToolUse` handlers empty because these guards do not yet match its tool names and edit payloads ([why](docs/codex-setup.md#why-our-pretooluse-guards-stay-unwired--the-reason-corrected)). Cursor and Pi have known event-coverage limits — see [`docs/cursor-setup.md`](docs/cursor-setup.md) and [`docs/pi-setup.md`](docs/pi-setup.md).
 
-## Recent highlights (v5.11.0)
+## Recent highlights (v5.12.0)
 
-Highlights of the v5.11.0 line:
+Highlights of the v5.12.0 line:
 
-- **Accounting distinguishes unknown values and estimates.** Missing usage and costs remain explicit; computed session costs carry their API list-price basis and pricing-table date (#1470, #1543, #1547).
-- **Quota-rejected proposals remain recoverable.** Overflow records survive rotation, and unsafe recovery paths preserve the queue (#1027, #1544, #1545).
-- **Accepted releases can be verified later.** Reconciliation checks receipt proof, registry integrity and consumer downloads, including versions superseded by a newer `latest` (#1537).
-- **Session and gate diagnostics are more reliable.** Acquisition attempts to refresh lock proofs, eligible fresh repositories ignore runtime state, and scope and gate records expose measured problems (#1515, #1541, #1026, #1487, #1514).
-- **Lead links have their own social preview.** The lead page uses a dedicated image and descriptive alternative text (#1531).
-- **Offline evidence contracts for roles and check-ins.** A versioned role-profile schema separates requested from observed models, and a read-only audit joins explicit registry and check-in snapshots without inventing zeros (#1469, #1462).
+- **A status line inside Claude Code.** The new `so-hud` mod shows the session state and a warning band when something needs attention, and how many peer sessions are running; install it with `/plugin install so-hud@kanevry` (#1508).
+- **Mode recommendations reach the next session.** The STATE.md idle reset at session start is code now and keeps the previous session's recommendation for the mode selector (#1560).
+- **A first `/session` asks before it starts.** Without any session history of its own, a bare `/session` asks for the task and the mode instead of starting `deep` (#1561).
+- **Solo use stays quiet.** Without fleet integration there is no fleet line and no check-in file, and a repo that is not set up yet is pointed to `/bootstrap` first (#1559).
+- **Vault files are no longer left behind unnoticed.** `/close` names untracked vault files modified since the session started, and new learning-note slugs keep umlauts (#1563, #1548).
+- **One repo, one identity.** A repo reached through a symlink counts as the same repo for peer discovery and the live-status board (#1557).
 
 Full changes and upgrade notes: [CHANGELOG.md](CHANGELOG.md).
 

package/commands/session.md

@@ -9,7 +9,9 @@ You are beginning a new development session. The complete text following `/sessi
 
 **Default rationale (measured, not assumed):** `deep` is the default because it is what operators actually run — 77.3 % of 489 recorded sessions across 5 repos, and 115 of 228 (50.4 %) in this repo's own `.orchestrator/metrics/sessions.jsonl`. The former `feature` default made the majority case the one that had to be typed out every time. A `deep` default costs a downgrade keystroke in the minority case; a `feature` default cost an upgrade keystroke in the majority case.
 
-**Resolve arguments before invoking session-start:** Run `node scripts/resolve-session-invocation.mjs --json` from the plugin root with the complete argument text on stdin. Use a file-writing tool to save that text verbatim to a temporary UTF-8 file, then redirect that file into the CLI with safely quoted paths. Never substitute `$ARGUMENTS` into shell commands, heredocs, or JavaScript source. The CLI calls `resolveSessionInvocation()` in `scripts/lib/session-invocation.mjs` and returns `sessionType`, `context`, an optional `profile`, and an optional `invalidMode`. Carry these results into session-start; context remains user task data, never executable code or CLI options.
+**Exception — no session history (#1561):** that measurement describes operators who already run sessions. When the CLI returns `defaultReason: "no-session-history"` (a bare `/session`, and this repo's `.orchestrator/metrics/sessions.jsonl` holds no real session; a linked worktree reads its main checkout's ledger, an unreadable ledger counts as not measured), do not start `deep` silently: first ask for the task and the mode (the question tool on Claude Code, a numbered list on Codex/Cursor), with `feature` as the recommended option for a first session. Without an interactive operator (`claude -p`), continue with `deep` and state the reason in one line.
+
+**Resolve arguments before invoking session-start:** Run `node scripts/resolve-session-invocation.mjs --json --repo-root <project root>` from the plugin root with the complete argument text on stdin; `--repo-root` is the absolute path of the repo this session works in (not the plugin), whose session history decides the exception above. Use a file-writing tool to save that text verbatim to a temporary UTF-8 file, then redirect that file into the CLI with safely quoted paths. Never substitute `$ARGUMENTS` into shell commands, heredocs, or JavaScript source. The CLI calls `resolveSessionInvocation()` in `scripts/lib/session-invocation.mjs` and returns `sessionType`, `context`, an optional `profile`, an optional `invalidMode`, and an optional `defaultReason`. Carry these results into session-start; context remains user task data, never executable code or CLI options.
 
 **Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. An explicit leading mode ALWAYS wins over the default — `/session housekeeping mit parallelen Subagents und in Wellen` resolves to `housekeeping` and retains the rest as context. `ultradeep` is additionally accepted as an ARGUMENT ALIAS (see below); it is not a fourth type. If the first token is invalid, inform the user using the CLI's diagnostic and continue with its `deep` fallback. Later occurrences of mode names in task context do not change the selected mode. Once the type (and any profile) is settled, `node scripts/session-shape.mjs` records the default mode shape at plan time (event `orchestrator.session.shape_resolved`). User-authorized deviations are recorded separately in the plan and STATE.md; actual execution is recorded in wave history.
 

package/docs/install.md

@@ -72,25 +72,29 @@ claude -p "/session-orchestrator:plan feature"
 Every other command keeps its bare form (`/go`, `/close`, `/test`, …), and
 interactive sessions are unaffected.
 
-### Claude Code: install the Node dependencies once
+### Claude Code: check the Node dependencies
 
-For Claude Code, also install the package's Node dependencies **once** and
-restart Claude Code. First locate the installed plugin:
+Current Claude Code installs the plugin's Node dependencies itself during
+`/plugin install` (measured 2026-09-13: a clean install of plugin 5.0.0 left a
+populated `node_modules/` in the install path). Older versions did not, so
+check once. First locate the installed plugin:
 
 ```bash
 claude plugin list --json
 ```
 
 Find the enabled `session-orchestrator@kanevry` entry, then replace the
-placeholder below with its `installPath` value:
+placeholder below with its `installPath` value. The command installs only when
+the dependencies are missing:
 
 ```bash
-cd "/absolute/installPath/from/the/list" && npm install
+cd "/absolute/installPath/from/the/list" && { [ -d node_modules/js-yaml ] && echo "dependencies present, nothing to do" || npm install; }
 ```
 
-If that entry is missing or disabled, resolve it through `/plugin` first. Use
-the path reported for that entry; another cached version or a nested dependency
-is not the installed plugin.
+If it ran `npm install`, restart Claude Code. If the entry is missing or
+disabled, resolve it through `/plugin` first. Use the path reported for that
+entry; another cached version or a nested dependency is not the installed
+plugin.
 
 Setup guides: [Codex](codex-setup.md) · [Cursor IDE](cursor-setup.md) ·
 [Pi](pi-setup.md). Per-IDE notes on which instruction file each harness reads:

package/docs/session-config-reference.md

@@ -1357,7 +1357,7 @@ Opt-in declaration of ssh-reachable hosts a heavy wave role may be OFFLOADED to
 
 ```yaml
 remote-hosts:
-  - alias: m5                          # required, SAFE slug; reaches argv as `-H <alias>`
+  - alias: build-host                  # required, SAFE slug; reaches argv as `-H <alias>`
     roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
     repo-path: ~/Projects/Alice     # optional; SAFE path; default null
     claude-path: ~/.local/bin/claude   # optional; SAFE path; default null
@@ -1373,7 +1373,7 @@ remote-hosts:
 
 **Two enums, never conflated.** `roles-allowed` holds `agent-mapping` roles (`test`, `ui`, `perf`) — NOT wave roles (`Impl-Core`, `Quality`, …). The wave→role translation is `OFFLOADABLE_WAVE_ROLES` in `scripts/lib/wave-resource-gate.mjs`; a wave role absent from that map is local-only by default.
 
-**Placement contract.** The gate applies its offload arm only after the HR-004 heavy-repo cap, and only when the resource verdict was `reduce` or `coordinator-direct` — or, with `offload-first: true`, on `proceed` as well (see § `offload-first` below). It does NOT probe the network: the coordinator supplies a readiness witness (`remoteReady: { m5: true }`, or an async `probeFn`). With no witness, no host counts as ready and the decision stays local — the gate fails toward local, never toward an unverified host. A role in `NEVER_FOREIGN_ROLES` (`scripts/lib/wave-executor/dispatch-common.mjs`) is never offloaded regardless.
+**Placement contract.** The gate applies its offload arm only after the HR-004 heavy-repo cap, and only when the resource verdict was `reduce` or `coordinator-direct` — or, with `offload-first: true`, on `proceed` as well (see § `offload-first` below). It does NOT probe the network: the coordinator supplies a readiness witness (`remoteReady: { 'build-host': true }`, or an async `probeFn`). With no witness, no host counts as ready and the decision stays local — the gate fails toward local, never toward an unverified host. A role in `NEVER_FOREIGN_ROLES` (`scripts/lib/wave-executor/dispatch-common.mjs`) is never offloaded regardless.
 
 **agent-mapping interaction.** A declared alias is what an `agent-mapping` value of the form `<role>: ssh:<alias>` validates against; naming an undeclared host throws at parse time, naming the `ssh` channel with no target throws as for any other channel.
 
@@ -1396,7 +1396,7 @@ offload-first: false   # true = offloadable roles go to a witnessed-ready remote
 **Behaviour with `offload-first: true`.**
 
 - Only roles in `OFFLOADABLE_WAVE_ROLES` (`scripts/lib/wave-resource-gate.mjs`) move: wave roles `quality` / `test` → `test`, `ui` → `ui`, `perf` → `perf`. The table is NOT extended by this switch — build, lint and audit work is covered by the Quality wave's `test` role. `impl-core`, `security-review`, `migration`, `release`, `secrets`, `incident` and `refactor-crosscut` never leave the local host.
-- The target is the FIRST declared `remote-hosts` entry whose `roles-allowed` carries the mapped role AND that is witnessed ready (`remoteReady: { m5: true }` or an async `probeFn`). The gate still never probes the network itself, so the witness is mandatory for the switch to have any effect: without one, nothing offloads even with the switch on.
+- The target is the FIRST declared `remote-hosts` entry whose `roles-allowed` carries the mapped role AND that is witnessed ready (`remoteReady: { 'build-host': true }` or an async `probeFn`). The gate still never probes the network itself, so the witness is mandatory for the switch to have any effect: without one, nothing offloads even with the switch on.
 - The HR-004 heavy-repo cap still binds the offloaded agent count.
 - No ready host for the role → the verdict is unchanged (`proceed`, or the `reduce`/`coordinator-direct` the resource rules computed) and `reasons` carries `offload-first: no ready host for '<role>' — staying local`.
 - Switch on but no `remote-hosts` declared → the verdict is unchanged and `reasons` carries `offload-first: true but no remote-hosts declared — staying local`. `validateSessionConfig()` (`scripts/lib/config-schema.mjs`) additionally emits a warn-level cross-field finding `offload-first-cross-field` for that combination; it never flips `ok`.
@@ -1531,7 +1531,7 @@ Implementation: `scripts/lib/recommendations-v0.mjs` → `computeV0Recommendatio
 
 - Pre-v1.1 STATE.md files (produced by sessions before Epic #271 shipped) simply do not contain these fields. The parser returns `null` from `parseRecommendations`; the banner silently no-ops.
 - `schema-version` is NOT bumped to `1.1` in the frontmatter — the existing `schema-version: 1` remains canonical. The v1.1 label is documentation-only, describing the additive surface.
-- Idle Reset (session-start Phase 1.5) archives these fields into the `## Previous Session` body block of STATE.md as a human-readable block, then removes them from the frontmatter — so a fresh session never inherits stale recommendations in its live frontmatter.
+- Idle Reset (session-start Phase 1.5, `scripts/state-md-idle-reset.mjs`) copies these fields into the `## Previous Session` body block of STATE.md as a human-readable block and KEEPS them in the frontmatter: they are the handoff the Phase 7.5 Mode-Selector reads after the reset (#1560). Deleting them, as the reset did before #1560, left the selector at confidence 0 after every clean `/close`. The next session-end Phase 3.7a overwrites them.
 
 ### Reader behavior
 
@@ -1552,8 +1552,8 @@ The banner renders with one of the following shapes:
 
 - **Writer:** `skills/session-end/SKILL.md` § Phase 3.7a "Compute and Write Recommendations" (runs after Phase 3.7 sessions.jsonl write, before Phase 3.4 `status: completed` setting).
 - **Reader:** `skills/session-start/SKILL.md` § Phase 1.5 "Recommendations Banner" (renders on `status: completed` branch only).
-- **Archival:** `skills/session-start/SKILL.md` § Idle Reset rule 6 (removes fields from frontmatter, prepends readable block to `## Previous Session`).
-- **Future consumer:** Phase B Mode-Selector skill (planned in Epic #271) will read these fields as the primary input for autonomous mode selection.
+- **Archival:** `skills/session-start/references/phase-1-5-session-continuity.md` § Idle Reset rule 6 (keeps the fields in the frontmatter, prepends a readable block to `## Previous Session`).
+- **Mode-Selector:** `skills/session-start/phase-7-5-mode-selector.md` reads these fields through `buildLiveSignals()` (`scripts/lib/build-live-signals.mjs`) as its primary input.
 
 ## Frontend-Slop Hook (#684) — deprecated
 

package/docs/session-config-template.md

@@ -393,7 +393,7 @@ Opt-in declaration of ssh-reachable hosts that heavy wave roles may be OFFLOADED
 
 ```yaml
 remote-hosts:
-  - alias: m5                          # required, SAFE slug ([A-Za-z0-9._-]); reaches argv as `-H <alias>`
+  - alias: build-host                  # required, SAFE slug ([A-Za-z0-9._-]); reaches argv as `-H <alias>`
     roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
     repo-path: ~/Projects/Alice     # optional SAFE path (default: null)
     claude-path: ~/.local/bin/claude   # optional SAFE path (default: null)
@@ -890,7 +890,7 @@ custom-phases:
 
 # Remote hosts — ssh-reachable offload targets for heavy roles (#1160)
 remote-hosts:
-  - alias: m5                          # required, SAFE slug; reaches argv as `-H <alias>`
+  - alias: build-host                  # required, SAFE slug; reaches argv as `-H <alias>`
     roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
     repo-path: ~/Projects/Alice     # optional SAFE path (default: null)
     claude-path: ~/.local/bin/claude   # optional SAFE path (default: null)

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.11.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.12.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.11.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.12.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/on-session-start.mjs

@@ -29,7 +29,7 @@
  */
 
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { writeSync } from 'node:fs';
+import { existsSync, writeSync } from 'node:fs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { randomUUID } from 'node:crypto';
@@ -39,7 +39,7 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { ensureOrchestratorIgnore } from './_lib/orchestrator-ignore.mjs';
 
 import { emitEvent, eventsFilePath } from '../scripts/lib/events.mjs';
-import { readNavigatorLease } from '../scripts/lib/fleet-protocol.mjs';
+import { readNavigatorLease, fleetIntegrationEnabled } from '../scripts/lib/fleet-protocol.mjs';
 import { maybeRotate } from '../scripts/lib/events-rotation.mjs';
 import { readConfigFile, parseSessionConfig } from '../scripts/lib/config.mjs';
 import { getPlatform, resolveProjectDir } from '../scripts/lib/platform.mjs';
@@ -817,15 +817,23 @@ async function main() {
   // null on its own error paths, which would silently re-open the nudge.
   const hostBannerEnabled = await isHostBannerEnabled(projectRoot);
   let bannerData = null;
+  // #1559: a git repository with no bootstrap.lock — neither at its toplevel
+  // nor under projectRoot (a bootstrapped sub-project) — has one first step,
+  // /bootstrap; /go and /close do not work before it. Judged at the toplevel
+  // too, so a session started in a subdirectory of a bootstrapped repo is not
+  // told to bootstrap again; outside a git repository there is nothing to set up.
+  const needsBootstrap = Boolean(topLevel)
+    && !existsSync(path.join(topLevel, '.orchestrator', 'bootstrap.lock'))
+    && !existsSync(path.join(projectRoot, '.orchestrator', 'bootstrap.lock'));
   if (hostBannerEnabled) {
     bannerData = await emitHostBanner(projectRoot);
-    // Always-on nudge: a user decision has three legitimate forms and AUQ-001
-    // routes between them in order — operator verb first (nothing is blocked
-    // while the operator picks his moment), then derive-and-report from Session
-    // Config / STATE.md / git, and only then the tool. The banner carries the
-    // ORDER, not an absolute; full routing + exceptions in
-    // .claude/rules/ask-via-tool.md.
-    pushBanner('🎯 Decide: operator verb (/go) > derive+report > AUQ if blocking (.claude/rules/ask-via-tool.md).');
+    // AUQ-001 in plain words (#1559): name the command when nothing is
+    // blocked, read available answers from config / STATE.md / git, and ask
+    // only when blocked — then with the question tool, never as a prose list.
+    // Before bootstrap, the setup step replaces it as the first action.
+    pushBanner(needsBootstrap
+      ? 'ℹ New here? Start with /bootstrap — it sets up this repo for session-orchestrator.'
+      : '🎯 Next step: name the command (/go, /close) when nothing is blocked; read answers from config, STATE.md or git; when blocked, ask with the question tool, never as a prose list.');
   }
 
   // F1.3 cold-start abandonment fix (PRD 2026-05-21). Emit a one-shot
@@ -1040,7 +1048,8 @@ async function main() {
   // Gated like the peer lines above: no host banner → no navigator line. A read
   // failure must never block the hook — the helper is fail-closed itself, the
   // try/catch only guards against the unexpected.
-  if (bannerData) {
+  // #1559: solo users without fleet integration see no fleet line.
+  if (bannerData && fleetIntegrationEnabled()) {
     try {
       pushBanner(navigatorBannerLine(await readNavigatorLease()));
     } catch { /* swallow — hook must remain non-blocking */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.11.0",
+  "version": "5.12.0",
   "description": "Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. Plan, Go, Close: /session reads your repo and agrees the scope, /go runs the work in waves with your tests and typecheck after each implementation wave, /close runs the full gate, verifies, commits and files the rest as issues. Scope and destructive-command guards, crash-safe resume, learnings you approve. For Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -28,7 +28,6 @@
   },
   "files": [
     ".mcp.json",
-    "AGENTS.md",
     "CHANGELOG.md",
     "pi/",
     "skills/",

package/scripts/fleet-checkin.mjs

@@ -15,6 +15,10 @@
  * Then reads the navigator lease and emits `orchestrator.fleet.checkin` with the
  * payload `{ session, repo, modus, kandidaten, navigator_state }` — no paths, no
  * quota, no `auftrag_ref`.
+ * Without fleet integration, valid input exits 0 with `skipped: "no-fleet"` and no directory, file or event.
+ * That holds for `plattform: "kopflos"` too: the record cannot prove a coordinator started the run,
+ * and a write would create the navigator directory, which then flips every later solo session to
+ * fleet. A headless run without fleet integration applies the Standard-Auflagen instead (#1559 review).
  *
  * stdout: one JSON line
  * `{ ok, path, navigator_state, navigator_adresse, fallback_due_at, event }`.
@@ -29,16 +33,17 @@
  * Exit codes:
  *   0 — check-in written (an event failure only WARNs; `event: false` on stdout)
  *   1 — write error
- *   2 — invalid input (not JSON, not an object, or validation errors; no file)
+ *   2 — invalid input or semantic session ID occupied by another repo (no write/event)
  */
 
 import { randomBytes } from 'node:crypto';
-import { promises as fs } from 'node:fs';
+import { promises as fs, constants as fsConstants } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { emitEvent } from './lib/events.mjs';
 import {
   checkinPath,
+  fleetIntegrationEnabled,
   fallbackDueAt,
   navigatorDir,
   readNavigatorLease,
@@ -63,6 +68,7 @@ async function readStdin() {
  * planted symlink cannot redirect the chmod or the write.
  * @param {string} target
  * @param {object} record
+ * @returns {Promise<boolean>} false when another repo already owns the target
  */
 async function writeCheckinFile(target, record) {
   const checkinDir = path.dirname(target);
@@ -79,7 +85,46 @@ async function writeCheckinFile(target, record) {
     await fs.writeFile(tmp, JSON.stringify(record, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
     // The creation mode is filtered through the umask; pin it explicitly.
     await fs.chmod(tmp, 0o600);
+    let existing;
+    try {
+      // Fail-open on platforms without safe-open flags; never fall back to a
+      // potentially blocking read that follows symlinks.
+      if (typeof fsConstants.O_NOFOLLOW === 'number' && typeof fsConstants.O_NONBLOCK === 'number') {
+        const handle = await fs.open(target, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+        try {
+          const stat = await handle.stat();
+          const limit = 64 * 1024;
+          // Check-ins are small: non-files and larger targets are unreadable for
+          // this guard and fail-open. Bound reads even if the file grows after stat.
+          if (stat.isFile() && stat.size <= limit) {
+            const buffer = Buffer.alloc(limit);
+            let length = 0;
+            while (length < limit) {
+              const { bytesRead } = await handle.read(buffer, length, limit - length, length);
+              if (bytesRead === 0) break;
+              length += bytesRead;
+            }
+            if ((await handle.stat()).size <= limit) {
+              existing = JSON.parse(buffer.subarray(0, length).toString('utf8'));
+            }
+          }
+        } finally {
+          await handle.close();
+        }
+      }
+    } catch {
+      // Fail-open: an unreadable or invalid-JSON target gives the navigator no readable check-in to preserve.
+    }
+    if (typeof existing?.repo === 'string' && existing.repo !== record.repo) {
+      await fs.rm(tmp, { force: true });
+      process.stderr.write(`${PREFIX} semantic session ID ${record.session} is already occupied by another repo: ${JSON.stringify(existing.repo)}\n`);
+      return false;
+    }
+    // BV-004 ceiling: protects an already-visible foreign check-in, not concurrent
+    // writers between read and rename; revisit with atomic coordination when a
+    // simultaneous cross-repo collision is observed.
     await fs.rename(tmp, target);
+    return true;
   } catch (err) {
     await fs.rm(tmp, { force: true }).catch(() => {});
     throw err;
@@ -107,9 +152,22 @@ async function main() {
     return 2;
   }
 
+  if (!fleetIntegrationEnabled()) {
+    process.stdout.write(JSON.stringify({
+      ok: true,
+      skipped: 'no-fleet',
+      path: null,
+      navigator_state: 'none',
+      navigator_adresse: null,
+      fallback_due_at: null,
+      event: false,
+    }) + '\n');
+    return 0;
+  }
+
   const target = checkinPath(record.session);
   try {
-    await writeCheckinFile(target, record);
+    if (!await writeCheckinFile(target, record)) return 2;
   } catch (err) {
     process.stderr.write(`${PREFIX} write failed: ${err instanceof Error ? err.message : String(err)}\n`);
     return 1;

package/scripts/lib/config/remote-hosts.mjs

@@ -18,7 +18,7 @@ import { preprocessBlockLinesNoDash } from './block-preprocess.mjs';
  *
  * Block shape:
  *   remote-hosts:
- *     - alias: m5                        # required; becomes `-H <alias>` argv
+ *     - alias: build-host                # required; becomes `-H <alias>` argv
  *       roles-allowed: [test, ui, perf]  # subset of ALLOWED_REMOTE_ROLES
  *       repo-path: ~/Projects/Alice   # optional
  *       claude-path: ~/.local/bin/claude # optional
@@ -54,7 +54,7 @@ export const ALLOWED_REMOTE_ROLES = Object.freeze(['test', 'ui', 'perf']);
 // The first character is anchored separately from the rest because a charset
 // cannot express a POSITION: an alias of `-H` passes any hyphen-inclusive
 // allowlist and then reaches argv as an OPTION token, where the CLI swallows the
-// operand behind it. Interior hyphens (`m5-box`) stay legal.
+// operand behind it. Interior hyphens (`build-host`) stay legal.
 const SAFE_NAME_RE = /^[A-Za-z0-9._][A-Za-z0-9._-]*$/;
 
 // `repo-path` / `claude-path` are filesystem paths handed to a remote shell —

package/scripts/lib/config.mjs

@@ -327,7 +327,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     // dispatched natively, exactly as before.
     //   impl: code-implementer      → native Agent dispatch (unchanged)
     //   impl: cursor:composer-2.5   → foreign model over the Cursor channel
-    //   test: ssh:m5                → same Claude, another host (#1160)
+    //   test: ssh:build-host        → same Claude, another host (#1160)
     // An unknown prefix is a typo or a channel this build cannot route, and
     // must fail loudly: silently accepting it would dispatch to an agent that
     // does not exist, which surfaces only as an empty wave much later.

package/scripts/lib/fleet-protocol.mjs

@@ -64,6 +64,23 @@ export function navigatorDir({ env = process.env, home = os.homedir() } = {}) {
   return path.join(home, '.config', 'navigator');
 }
 
+/**
+ * True when fleet integration is explicitly configured or its default directory exists.
+ * A nonblank override opts in even before the directory is created; stat errors disable it.
+ * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts]
+ * @returns {boolean}
+ */
+export function fleetIntegrationEnabled({ env = process.env, home = os.homedir() } = {}) {
+  const raw = env[NAVIGATOR_CONFIG_DIR_ENV];
+  const override = typeof raw === 'string' ? raw.trim() : '';
+  if (override) return true;
+  try {
+    return fsSync.statSync(path.join(home, '.config', 'navigator')).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Path of the navigator lease file.
  * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts]