session-orchestrator 5.10.0 → 5.12.0

package/docs/role-profile-contract.md

@@ -0,0 +1,139 @@
+# Role-profile evidence contract v1
+
+Refs #1469. This additive offline contract records role-selection evidence; it does not
+select a model, dispatch an agent, load a registry, start an adapter, or change a pin.
+The test-profile registry under `scripts/lib/profiles/` is a separate contract.
+
+## API and meaning
+
+`scripts/lib/role-profile/schema.mjs` exports `ROLE_PROFILE_CONTRACT_VERSION` (1)
+and `roleProfileEvidenceSchema.safeParse(value)`:
+
+- Success: `{ success: true, data, diagnostics }`. `data` is the original input,
+  unchanged, without defaults, normalization or alias resolution.
+- Failure: `{ success: false, error: { issues } }`. Each issue has a fixed `code`,
+  field-addressing `path` array and `message`. Messages never interpolate raw input.
+- Codes: `INVALID_TYPE`, `MISSING_FIELD`, `UNKNOWN_FIELD`, `INVALID_VALUE`,
+  `INVALID_RELATION`, `UNSUPPORTED_VERSION`. Diagnostics can contain `UNSUPPORTED_EFFORT`.
+
+Success means internal structural consistency only. A source reference is a claim
+by the recorder: the validator does not read it, authenticate it, check revocation,
+verify permissions, or confirm that the harness actually used the recorded model.
+No result asserts host availability, account access, quota, cost, quality, or model
+acceptance. An `authorized` record is not an execution authorization issued by this API.
+No I/O, environment lookup, current-clock read, provider call or input mutation occurs.
+
+## Fields
+
+All fields below are required, including null-valued fields. Objects must have only
+the specified own data properties; arrays, accessors and class instances are rejected.
+Strings must contain a non-whitespace character but are preserved byte for byte.
+IDs and version strings are opaque; unlisted model IDs are accepted without substitution.
+
+| Field | Shape and relationship |
+|---|---|
+| `contractVersion` | Integer literal `1`; separate from harness/profile/registry versions |
+| `role`, `taskClass` | Nonempty role name and task classification; no role registry lookup |
+| `provider`, `transport` | Separate nonempty IDs; never inferred from a model name |
+| `binding` | `{status, sourceRef, reason}`; known bindings in v1 are `openai`/`codex-cli` and `anthropic`/`claude-code` |
+| `model` | `{requested, observed, resolution}`; details below |
+| `effort` | `{requested, effective, support}`; details below |
+| `harness` | `{name, version}`; name is a string, version is evidence with `value` |
+| `profile` | `{id, version}`; id is a string, version is evidence with `value` |
+| `registryVersion` | Evidence with `value`; records provenance without creating a registry |
+| `selection` | `{mode, escalationReason}`; mode `profile`, `owner-override`, or `escalation` |
+| `authorization` | `{status, authority, sourceRef, scope, reason}`; details below |
+| `evidence` | Evidence with `timestamp`; known timestamps are real calendar dates in UTC, exactly `YYYY-MM-DDTHH:mm:ss.sssZ` |
+
+An evidence object has `{status, <field>, sourceRef, reason}`. With `known`, the
+value and source reference are nonempty strings and reason is null. With `unknown`,
+value and source reference are null and reason is nonempty. Missing evidence is not
+an unknown state. Binding uses the same source/reason convention without a value.
+Unrecognized provider/transport pairs require binding `unknown`, retaining the raw IDs;
+known contradictory pairs are rejected. Binding validity is not transport availability.
+
+## Model request, observation and resolution
+
+`requested` is `{kind, value}`: `id` or `alias` requires the original string;
+`inherit` requires null. `observed` is evidence with `id`, independently collected.
+Unknown observation requires resolution `unknown`; no requested ID is copied into it.
+A known observation may still have unknown resolution when the relationship is unproven.
+
+`resolution` has `{status, baselineId, parent, sourceRef, reason}`:
+
+| Status | Required relationship |
+|---|---|
+| `unknown` | baselineId, parent and sourceRef null; reason nonempty |
+| `exact` | Requested kind id, requested value equals observed ID |
+| `alias-resolved` | Requested kind alias, known observation; no drift assertion |
+| `alias-drift` | Requested kind alias, known observation, nonempty baselineId different from observed ID; sourceRef must identify the resolution/baseline evidence |
+| `parent-inherit` | Requested kind inherit; parent `{id, sourceRef}` names the observed ID with separate parent evidence |
+
+All non-unknown resolutions require known observation, nonempty sourceRef and null
+reason. baselineId is null outside alias-drift; parent is null outside parent-inherit.
+A changed alias without a documented baseline is not proof of drift. Inheritance
+without parent evidence remains unknown. The validator checks equality and structure,
+not whether any source genuinely proves the relationship.
+
+## Effort and capability evidence
+
+`requested` is `{provider, dialect, value}`; value is a nonempty string or null
+(no explicit effort requested). `effective` is `{provider, dialect, status, value,
+sourceRef, reason}` with the known/unknown evidence rules above. Both providers must
+match the record provider. Recognized dialects are `openai-reasoning` for openai and
+`anthropic-effort` for anthropic. Unrecognized dialects require both support and
+effective evidence to be unknown, preserving requested values.
+
+`support` is `{status, sourceRef, reason}` with `supported`, `unsupported`, or
+`unknown`. The first two require a source and null reason; unknown requires null
+source and a reason. This describes support for the requested effort, as asserted
+by the source, not a live capability table maintained by this validator. Values
+are never translated or ranked numerically across vendors. A familiar label such
+as medium alone proves no support on a particular harness/version/model.
+
+Unsupported requests emit `UNSUPPORTED_EFFORT`. An identical value cannot also be
+claimed effective; explicitly unknown effective effort or a different documented
+value can be recorded. Unknown support does not become supported merely because
+a syntactically valid record contains a known effective value.
+
+## Escalation and owner authorization
+
+Escalation requires a nonempty escalationReason; other selection modes require null.
+Owner-override and escalation require authorization status `authorized`, authority
+`owner`, nonempty sourceRef, null reason and explicit scope:
+
+```json
+{
+  "role": "worker", "provider": "openai", "transport": "codex-cli",
+  "model": {"kind": "id", "value": "unlisted-model/2030"},
+  "effort": {"provider": "openai", "dialect": "openai-reasoning", "value": "medium"}
+}
+```
+
+Every scope value must match the record's role, provider, transport and original
+model/effort requests. This is an internal coverage comparison, not external policy
+verification. Profile selection can record `unknown` or `not-required`: authority,
+sourceRef and scope are null and reason is nonempty. Neither status grants permission.
+Any authorized record, including profile mode, must carry the full matching scope.
+Historical narratives, cost labels or model preferences never supply missing evidence.
+References must not include tokens, account names, mail addresses or other secrets.
+
+## Unknown example and versioning
+
+The following fragments belong to an otherwise complete v1 record:
+
+```json
+{
+  "requested": {"kind": "id", "value": "unlisted-model/2030"},
+  "observed": {"status": "unknown", "id": null, "sourceRef": null, "reason": "Not measured"},
+  "resolution": {"status": "unknown", "baselineId": null, "parent": null, "sourceRef": null, "reason": "Not resolved"}
+}
+```
+
+This can be contract-valid; it never proves successful resolution or model acceptance.
+Inline executable complete records live in `tests/lib/role-profile/schema.test.mjs`.
+Unknown contract versions are rejected before interpreting nested evidence. Unknown
+field names are rejected; unknown opaque IDs are retained. New fields or changed
+semantics require a new contract version, explicit handling and migration policy;
+there is no automatic upgrade. This offline slice leaves runtime smokes, dispatch
+integration, precedence measurement, billing, access and rollout acceptance open.

package/docs/scope-collision-guard.md

@@ -211,6 +211,7 @@ Complete list of what this guard does **not** see, or sees only approximately:
 9. **The session binding is self-declared** (§ 2.3). `session` is a plain field in a file any process in this working copy can write, so writing a foreign id into it turns the write gate off for that manifest. Named rather than hidden: it is the SAME power `enforcement: "off"` already grants in the same file, so Gate 3b adds no new authority — the manifest is the coordinator's own artefact either way.
 10. **The manifest binding is read by the WRITE gates, not by the dispatch hook.** `enforce-scope`, `enforce-commands`, `post-bash-write-verify` and — since #1493.1 — the git pre-commit `wave-scope-commit-guard` (env-tier identity only, it has no hook payload) classify the manifest via `classifyManifestSession()` and stand down on a foreign one. The dispatch ledger of § 4 takes its session from the harness's own `input.session_id` instead — in its file name since #1493 and in `waveKeyOf(projectDir, sessionId, …)` — and reads only `wave` and `role` out of `wave-scope.json`; the `session` field is not consulted there at all. So a peer session's manifest cannot bind this session's writes or commits, but the hooks reach that property by different routes, and a change to one does not carry to the other.
 11. **A session that published a peer's id reads its OWN manifest as `foreign` (#1194) — the writer's defense is now mechanical (#1207).** Dropping the lock tier (§ 2.3) moved the cost to the other side of the trade: with a raw `sessionAttribution()` read, a session that lost the `bootstrapLock()` race could get the peer's id and write it into its own manifest, and Gate 3b would then classify the manifest `foreign`, standing its own write guard down. Since #1207 the writer calls `attributionForRecord(repoRoot)` instead — `skills/wave-executor/wave-loop.md` § Scope Manifest 1 — which confirms the lock's raw `session_id` against `readProcessLocalSessionIds()` before returning anything and yields `{}` on any mismatch, so the coordinator performs no manual comparison and STATE.md plays no part in it (a shared working-copy artefact written by whichever session holds the lock, not a process-local witness). A filled binding is therefore provably this session's own; unbound (`{}`) = ENFORCE. CEILING (BV-004): on a harness that exports no session env var and puts no `session_id` in the hook payload (Codex CLI, Cursor today) both tiers are empty, so G3b is permanently `unknown` = enforce = pre-#1123 behaviour there. Revisit when Codex/Cursor hook payloads carry a session id.
+12. **The commit guard's identity is whatever the committing shell exports (#1504 point 7b).** `wave-scope-commit-guard` runs inside `git commit` and gets no hook payload, so `readProcessLocalSessionIds()` reads the env only. `CLAUDE_CODE_SESSION_ID=<foreign id> git commit` therefore makes this session's own manifest read as `foreign` and the guard stands down. Named, not fixed (owner decision 2026-10-09): it is the same power `git commit --no-verify` already grants to the same shell, so reading identity from `session.lock` instead would add a failure mode (lock absent or reaped) without closing the bypass. The guard protects against accidents, not against intent. Revisit if `--no-verify` is ever blocked for coordinator sessions.
 
 ## 7. Debugging
 
@@ -228,6 +229,8 @@ node scripts/validate-wave-scope.mjs --assert-disjoint "$WAVE_SCOPES_SIDECAR" <
 
 Exit 1 prints one `ERROR:` line per collision (`agents "A" and "B" both claim [...]`) and one per duplicate id. Exit 0 — nothing on stderr, the manifest echoed back on stdout — means the declared scopes really are disjoint and the hook was right to allow; the divergence is then in the prompt, not in the plan. No manifest yet (e.g. `/plan`, before any `wave-scope.json` exists)? Add `--no-manifest` and drop the stdin redirect: the sidecar is checked alone and stdout stays empty — without the flag an empty stdin is still an error, and the flag refuses `--union` / `--assert-subset`, which need the manifest (#1510 f).
 
+**`--assert-disjoint` reports a collision with an agent that has already finished (#1026 point 1).** Expected: the CLI checks the declared plan and has no notion of liveness. That keeps its verdict reproducible. The hook (§ 5) is the gate that knows a partner finished. When the coordinator (or a fix agent) takes over a finished agent's file, move the file from the finished agent's record to the new owner's record in the canonical `{id, files}` array, pipe that array into `materialize-wave-scope.mjs --state-dir <state-dir> --wave <N>` again (it rewrites both shapes), then re-assert. Do not mark records as done or bypass the check: an ownership change is a plan change, and the plan is what the CLI certifies (owner decision 2026-10-09).
+
 **Reset.** Delete this session's `.orchestrator/wave-dispatch-scopes.<session>.json` (and its `.lock` if a dead holder is suspected) — never a peer's. Both are gitignored here (in a consumer repo only once bootstrap's `store-lock-ignore` step has run, #1495), both are rebuilt on the next dispatch, and neither is shared with any other mechanism or session. After the final wave, `<state-dir>/filescopes/` is deleted along with `wave-scope.json` and this session's ledger file (`skills/wave-executor/references/wave-loop-scope-manifest.md` step 7, session-end 3.0); a crashed session's file stays behind, inert — no other session reads it — a stale `wave-<N>/` directory left behind is a scope claim nobody re-verified.
 
 **Disable.** The hook honours the repo's profile gate (`shouldRunHook('pre-task-scope-disjoint')`, row 1) — a silent exit 0, no decision at all.

package/docs/session-config-reference.md

@@ -915,7 +915,7 @@ node scripts/memory-propose.mjs \
 
 A successful dry-run exits `0` with stdout status `dry-run-ok` (see updated exit-codes table below) and never appends to `proposals.jsonl`.
 
-`--type` accepts one of the `PROPOSAL_TYPES` enum values (the agent-writable subset of the learnings schema): `mode-selector-accuracy`, `hardware-pattern`, `fragile-file`, `effective-sizing`, `recurring-issue`, `workflow-pattern`, `proven-pattern`, `anti-pattern`, `autopilot-effectiveness`, `domain-regression`, `convention`, `architecture-pattern`, `design-pattern`. Analyzer-only learning types such as `autonomy-verdict` are intentionally excluded because their evidence gates are enforced by `/evolve` analyzers, not by agent proposals. Strings with embedded quotes must be shell-escaped per usual conventions. The CLI appends one JSONL line to `.orchestrator/metrics/proposals.jsonl` (atomic via O_APPEND under the `.orchestrator/metrics/proposals-write.lock` mutex) and updates a per-wave summary at `.orchestrator/metrics/proposals-summary-<wave-id>.json` (counters: queued / dropped / below_floor / fs_error). The coordinator surfaces both files at session-end Phase 3.6.3 to render the AUQ multiSelect; approved entries promote into `.orchestrator/metrics/learnings.jsonl` with `_provenance: agent-proposed@<wave-id>`; rejected entries archive to `.orchestrator/proposals.rejected.log`. Privacy: `proposed_by_agent` is captured in the audit hook (`events.jsonl`) only and is stripped before promotion to learnings.jsonl.
+`--type` accepts one of the `PROPOSAL_TYPES` enum values (the agent-writable subset of the learnings schema): `mode-selector-accuracy`, `hardware-pattern`, `fragile-file`, `effective-sizing`, `recurring-issue`, `workflow-pattern`, `proven-pattern`, `anti-pattern`, `autopilot-effectiveness`, `domain-regression`, `convention`, `architecture-pattern`, `design-pattern`. Analyzer-only learning types such as `autonomy-verdict` are intentionally excluded because their evidence gates are enforced by `/evolve` analyzers, not by agent proposals. Strings with embedded quotes must be shell-escaped per usual conventions. The CLI appends one JSONL line to `.orchestrator/metrics/proposals.jsonl` (atomic via O_APPEND under the `.orchestrator/metrics/proposals-write.lock` mutex) and updates a per-wave summary at `.orchestrator/metrics/proposals-summary-<wave-id>.json` (counters: queued / dropped / below_floor / fs_error). A proposal the quota rejects (`dropped`) is not discarded: its full record is appended to `.orchestrator/metrics/proposals-overflow.jsonl` under the same lock — never counted against the quota, not read by the collector, not cleared at wave end (#1027); if that append fails the CLI exits `4` instead of `1`. The coordinator surfaces both files at session-end Phase 3.6.3 to render the AUQ multiSelect; approved entries promote into `.orchestrator/metrics/learnings.jsonl` with `_provenance: agent-proposed@<wave-id>`; rejected entries archive to `.orchestrator/proposals.rejected.log`. Privacy: `proposed_by_agent` is captured in the audit hook (`events.jsonl`) only and is stripped before promotion to learnings.jsonl.
 
 ### Exit codes
 
@@ -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/evals/instruction-ablation/run.mjs

@@ -243,7 +243,7 @@ function runCell(variant, kase, run) {
   if (DRY) return { variant: variant.id, case: kase.id, run, dry: true, workdir: wd };
 
   let usage = {};
-  let cost = 0;
+  let cost = null;
   let text = '';
   let error = null;
   try {
@@ -255,7 +255,9 @@ function runCell(variant, kase, run) {
     });
     const j = JSON.parse(out);
     usage = j.usage || {};
-    cost = j.total_cost_usd || 0;
+    // Missing or non-numeric cost stays unknown; a reported 0 stays 0 (#1547).
+    const c = j.total_cost_usd;
+    cost = typeof c === 'number' && Number.isFinite(c) && c >= 0 ? c : null;
     text = typeof j.result === 'string' ? j.result : '';
   } catch (e) {
     error = String(e.message || e).slice(0, 300);
@@ -275,7 +277,7 @@ function runCell(variant, kase, run) {
     error,
     context_tokens: ctx,
     output_tokens: usage.output_tokens || 0,
-    cost_usd: Number(cost.toFixed(4)),
+    cost_usd: cost === null ? null : Number(cost.toFixed(4)),
     oracles,
     reply_excerpt: text.slice(0, 300),
     workdir: wd,
@@ -300,7 +302,7 @@ for (const kase of cases) {
       const rec = runCell(variant, kase, run);
       records.push(rec);
       if (!DRY) appendFileSync(outFile, JSON.stringify(rec) + '\n');
-      process.stderr.write(rec.dry ? 'built\n' : `${rec.pass ? 'PASS' : 'FAIL'} (${rec.cost_usd ?? 0} USD)\n`);
+      process.stderr.write(rec.dry ? 'built\n' : `${rec.pass ? 'PASS' : 'FAIL'} (${rec.cost_usd ?? 'unknown'} USD)\n`);
     }
   }
 }
@@ -324,13 +326,16 @@ for (const kase of cases) {
   console.log(row.join('\t'));
 }
 
-const spend = records.reduce((a, r) => a + (r.cost_usd || 0), 0);
+// One unknown cell makes the total unknown; a partial sum would read as complete.
+const spend = records.some((r) => r.cost_usd === null)
+  ? 'unknown'
+  : records.reduce((a, r) => a + r.cost_usd, 0).toFixed(2);
 const ctxAvg = (id) => {
   const c = records.filter((r) => r.variant === id && r.context_tokens);
   return c.length ? Math.round(c.reduce((a, r) => a + r.context_tokens, 0) / c.length) : 0;
 };
 console.log('\n=== mean context tokens by variant ===');
 for (const v of variants) console.log(`${v.id}\t${ctxAvg(v.id)}`);
-console.log(`\ntotal spend: USD ${spend.toFixed(2)}`);
+console.log(`\ntotal spend: USD ${spend}`);
 console.log(`results:     ${outFile}`);
 console.log(`workdirs:    ${ROOT}  (throwaway; inspect failures there, remove when done)`);

package/hooks/_lib/hook-import-set.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-10-05T10:45:41.038Z",
-  "head": "94dc4a0cf182a06492feb217162d290e9fd0e921",
+  "generated_at": "2026-10-10T12:04:56.821Z",
+  "head": "f4f6200c067d28025bf70e34296cd5ebabcfc7f8",
   "entries": [
     {
       "file": "hooks/_lib/atomic-json.mjs",
@@ -34,6 +34,12 @@
         "on-session-end.mjs"
       ]
     },
+    {
+      "file": "hooks/_lib/orchestrator-ignore.mjs",
+      "reachable_from": [
+        "on-session-start.mjs"
+      ]
+    },
     {
       "file": "hooks/_lib/profile-gate.mjs",
       "reachable_from": [
@@ -1158,6 +1164,19 @@
         "post-edit-validate.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/native-command.mjs",
+      "reachable_from": [
+        "on-session-end.mjs",
+        "on-session-start.mjs",
+        "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
+        "post-edit-validate.mjs",
+        "post-subagent-discovery-validator.mjs",
+        "pre-bash-issue-budget.mjs",
+        "pre-bash-templates-first.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/orphan-reaper/defaults.mjs",
       "reachable_from": [
@@ -1633,6 +1652,12 @@
         "skill-invocation-telemetry.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/telemetry/pricing.mjs",
+      "reachable_from": [
+        "subagent-telemetry.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/telemetry/queue.mjs",
       "reachable_from": [

package/hooks/_lib/orchestrator-ignore.mjs

@@ -0,0 +1,112 @@
+/**
+ * orchestrator-ignore.mjs — keep the plugin's runtime state out of `git status`
+ * in a repo that has never been bootstrapped (#1515 Pkt 5).
+ *
+ * Measured 2026-10-08 @ 644743cc: one SessionStart in a fresh `git init` repo
+ * left five untracked files under `.orchestrator/` (session.lock,
+ * current-session.json, host.json, runtime/lock-owner-proof.json,
+ * metrics/events.jsonl) and nothing ignored them. Bootstrapped repos get their
+ * runtime ignore lines from `skills/bootstrap/_shared-template.md`
+ * § store-lock-ignore; an un-bootstrapped one gets nothing.
+ *
+ * Root, not per writer (BV-003): 23 hook-reachable modules call mkdir, and
+ * `.orchestrator/` is created by whichever runs first. SessionStart is the first
+ * plugin hook of every session (hooks/hooks.json), so the one call in
+ * on-session-start.mjs covers the session. Because SessionStart runs async, a
+ * PreToolUse hook MAY have created the directory a moment earlier — which is
+ * why the decision keys on "nothing under .orchestrator/ is tracked" (one
+ * `git ls-files`), not on "the directory was just created".
+ *
+ * Invariants:
+ *   - A repo WITH `.orchestrator/bootstrap.lock` is never given the file. If it
+ *     carries a file this helper wrote (byte-identical), the file is removed:
+ *     after bootstrap, steering/, peers/, policy/ and the ledgers are durable
+ *     project data and must not stay ignored.
+ *   - An existing `.orchestrator/.gitignore` is never overwritten.
+ *   - Any tracked path under `.orchestrator/`, or git failing (no repo, no git
+ *     binary), means: write nothing.
+ *   - Never throws; returns a reason string for tests and diagnostics.
+ *
+ * The negations are the exact `.orchestrator/` paths a bootstrap run stages
+ * with `git add -- <file>` (BOOTSTRAP_FILES in skills/bootstrap/*-template.md,
+ * measured 2026-10-08). The Bootstrap Gate runs bootstrap in the SAME session
+ * this file was written, before the next SessionStart can remove it, and git
+ * refuses `git add` on an explicitly named ignored path. NAMED CEILING
+ * (BV-004): the list is hand-copied; revisit when a template adds a new
+ * `BOOTSTRAP_FILES+=(.orchestrator/...)` entry.
+ */
+
+import { readFile, writeFile, link, unlink, mkdir } from 'node:fs/promises';
+import { existsSync, lstatSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+
+/** Directories that hold durable project data, never plugin runtime output. */
+const PROJECT_DATA_DIRS = ['steering', 'peers', 'policy'];
+
+export const GENERATED_IGNORE = [
+  '# Written by session-orchestrator (#1515): this repo has no .orchestrator/bootstrap.lock,',
+  '# so the plugin runtime state below stays out of git status. Removed automatically',
+  '# at the first session start after /bootstrap.',
+  '*',
+  '!*/',
+  '!/bootstrap.lock',
+  '!/metrics/learnings.jsonl',
+  '!/metrics/sessions.jsonl',
+  '!/metrics/README.md',
+  '!/policy/quality-gates.json',
+  '',
+].join('\n');
+
+function trackedUnderOrchestrator(repoRoot) {
+  return new Promise((resolve) => {
+    execFile('git', ['ls-files', '-z', '--', '.orchestrator'], { cwd: repoRoot, timeout: 2000 }, (err, stdout) => {
+      if (err) return resolve(null); // unknown → caller writes nothing
+      resolve(stdout.length > 0);
+    });
+  });
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {Promise<'written'|'removed'|'bootstrapped'|'present'|'project-data'|'symlink'|'tracked'|'no-git'|'error'>}
+ */
+export async function ensureOrchestratorIgnore(repoRoot) {
+  try {
+    const dir = path.join(repoRoot, '.orchestrator');
+    const target = path.join(dir, '.gitignore');
+    if (existsSync(path.join(dir, 'bootstrap.lock'))) {
+      if (existsSync(target)) {
+        const current = await readFile(target, 'utf8').catch(() => null);
+        if (current === GENERATED_IGNORE) {
+          await unlink(target);
+          return 'removed';
+        }
+      }
+      return 'bootstrapped';
+    }
+    if (existsSync(target)) return 'present';
+    // Durable project data (bootstrap/_shared-template.md #store-lock-ignore)
+    // the user may hold untracked on purpose: ignoring it would hide it from
+    // git status without a word. Only plugin runtime output may be swept.
+    if (PROJECT_DATA_DIRS.some((d) => existsSync(path.join(dir, d)))) return 'project-data';
+    // A symlinked .orchestrator would put the file outside the repo.
+    if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) return 'symlink';
+    const tracked = await trackedUnderOrchestrator(repoRoot);
+    if (tracked === null) return 'no-git';
+    if (tracked) return 'tracked';
+    await mkdir(dir, { recursive: true });
+    // tmp + link: atomic, and link() fails with EEXIST instead of replacing a
+    // .gitignore another process created in between (rename would overwrite).
+    const tmp = `${target}.tmp-${process.pid}`;
+    await writeFile(tmp, GENERATED_IGNORE, 'utf8');
+    try {
+      await link(tmp, target);
+    } finally {
+      await unlink(tmp).catch(() => {});
+    }
+    return 'written';
+  } catch (err) {
+    return err && err.code === 'EEXIST' ? 'present' : 'error';
+  }
+}

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.10.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.10.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-end.mjs

@@ -43,6 +43,7 @@ import {
   release,
   loadOwnerProof,
   OWNER_PROOF_RELPATH,
+  isLockOwnedByProof,
 } from '../scripts/lib/session-lock.mjs';
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
@@ -789,8 +790,14 @@ async function main() {
           // millisecond started_at cannot match any FUTURE lock, so it
           // self-invalidates), this just avoids the stale artifact. ENOENT
           // (no proof was ever written) lands in the same swallow.
+          // Only when the proof still describes the lock we released: since
+          // #1541 every acquire() rewrites it, so a successor that acquired
+          // during the awaited emit above owns a fresh proof we must not
+          // remove. A narrow window between this read and the unlink remains.
           try {
-            await fs.unlink(path.join(projectRoot, OWNER_PROOF_RELPATH));
+            if (isLockOwnedByProof(lock, loadOwnerProof({ repoRoot: projectRoot }))) {
+              await fs.unlink(path.join(projectRoot, OWNER_PROOF_RELPATH));
+            }
           } catch { /* best-effort — a leftover proof is self-invalidating */ }
         }
       } else {

package/hooks/on-session-start.mjs

@@ -29,16 +29,17 @@
  */
 
 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';
 import path from 'node:path';
 
 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';
@@ -781,6 +782,12 @@ function maybeQueueConsentNudge() {
 async function main() {
   const projectRoot = resolveProjectDir();
 
+  // #1515 Pkt 5 — before this hook's own writers (host.json, session.lock,
+  // events.jsonl) run: an un-bootstrapped repo gets `.orchestrator/.gitignore`
+  // so the runtime state never shows up in `git status`. Bootstrapped repos
+  // pay two existsSync and nothing else. Never throws.
+  await ensureOrchestratorIgnore(projectRoot);
+
   // Read optional stdin payload in parallel with git info so we don't stall
   // the hook. Both are best-effort and the promise races against a 500 ms cap
   // inside readStdinJson itself.
@@ -810,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
@@ -1033,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/hooks/post-bash-write-verify.mjs

@@ -1299,10 +1299,23 @@ async function main() {
     ? []
     : readPeerScopeRecords(path.dirname(scopePath), scope.wave, sidecarRaw);
   if (sidecarBinding.notify) {
-    messages.push(formatSidecarMismatchNotice(
-      path.relative(repoRoot, path.join(path.dirname(scopePath), 'filescopes', `wave-${scope.wave}.scopes.json`)),
-    ));
+    const relSidecar = path.relative(
+      repoRoot,
+      path.join(path.dirname(scopePath), 'filescopes', `wave-${scope.wave}.scopes.json`),
+    );
+    messages.push(formatSidecarMismatchNotice(relSidecar));
     warn = true;
+    // #1514 point 6 (HR-105) — the notice alone left its firing rate unmeasurable.
+    // Same once-per-new-hash dedupe as the notice (`bindPeerSidecar().notify`);
+    // awaited so the append cannot be lost to the process exiting.
+    try {
+      const { emitEvent } = await import('../scripts/lib/events.mjs');
+      await emitEvent(
+        'orchestrator.scope.sidecar_mismatch',
+        { hook: 'post-bash-write-verify', sidecar: relSidecar.split(path.sep).join('/'), wave: scope.wave },
+        { repoRoot: context.manifestRoot },
+      );
+    } catch { /* observability is best-effort — never blocks the notice */ }
   }
   const violations = [];
   for (const relPath of report) {