session-orchestrator 5.9.0 → 5.11.0

package/docs/owner-config-schema.md

@@ -126,7 +126,7 @@ hardware-sharing: { enabled: true }
 
 # ACCEPTED — all four required sections present and valid
 owner:
-  name: Bernhard
+  name: Example Owner
   language: de
 tone:
   style: direct
@@ -136,3 +136,20 @@ efficiency:
 hardware-sharing:
   enabled: false
 ```
+
+## Owner privacy pattern source
+
+Host-local owner leakage patterns use a separate protected version 1 JSON file, not an owner.yaml section. See [Owner privacy patterns](owner-privacy-patterns.md) for source precedence, schema, migration and strict packed-release checks. `paths.vault-dir` remains the canonical vault target used by the vault migration and consolidation tools; `SO_VAULT_DIR` overrides it.
+
+### Host-local drift path exceptions (#937)
+
+Optional `drift-check.foreign-host-prefixes` is an array of absolute directory
+prefixes belonging to known foreign hosts, for example
+`/Users/remote-user/Projects/foreign-layout`. Missing `/Users/…` references
+under a declared prefix become warnings; other missing paths remain errors.
+Matching respects directory boundaries and accepts a trailing slash. Prefixes
+must contain at least three components (four under `/Users` or `/home`); roots,
+home directories, broad Projects roots, traversal, globs and malformed entries
+are rejected. One invalid entry drops the entire optional `drift-check` section
+while preserving other valid owner settings. This section does not change
+`drift-check.mode` or its precedence. No default allowlist is supplied.

package/docs/owner-privacy-patterns.md

@@ -0,0 +1,85 @@
+# Host-local owner privacy patterns
+
+The owner-leakage scanner keeps host-specific usernames, endpoints, project names and allowed public contacts in a protected file outside every repository. The package ships generic rules and invented test fixtures. Public author and copyright attribution remain public; operational paths and private endpoints belong in local configuration.
+
+## Configure a host
+
+Create `owner-patterns.json` using your own private values. Do not commit it, copy it into a release tree, or print it into CI logs. Resolution follows this order:
+
+1. `SO_OWNER_PATTERNS_FILE`: an explicit absolute filename.
+2. `SO_CONFIG_HOME/owner-patterns.json`.
+3. `XDG_CONFIG_HOME/session-orchestrator/owner-patterns.json`.
+4. `~/.config/session-orchestrator/owner-patterns.json`.
+
+Empty or whitespace-only environment values are unset. An explicit relative filename is unsafe. The file must be regular, owned by the current user, have exactly mode `0600` and a single hard link, and be outside any Git repository, including ignored directories. Its parent and user-owned ancestors must not be group/world writable. User-controlled symlink ancestors and a symlink file are rejected; root-owned operating-system aliases such as macOS `/tmp` are allowed above the protected parent.
+
+For a new directory, use a private umask and create the file with mode `0600`. Choose the directory according to the resolution above; this example uses the default:
+
+```sh
+umask 077
+mkdir -p "$HOME/.config/session-orchestrator"
+# Create owner-patterns.json in that directory with a local editor.
+chmod 600 "$HOME/.config/session-orchestrator/owner-patterns.json"
+```
+
+Existing directory permissions may remain `0755` if they meet the ownership/writability requirements. The file is limited to 64 KiB. Use a local protected file on each host that needs these checks; it is separate from [owner.yaml](owner-config-schema.md).
+
+## Version 1 schema
+
+The object has `version: 1` and these optional arrays of literal strings. Omitted arrays become empty; explicit `null`, unknown fields and invalid types fail validation. Strings are escaped as literals rather than interpreted as regular expressions. Each array permits at most 256 strings, each at most 256 UTF-16 code units, without leading/trailing whitespace or ASCII control characters below U+0020. At least one blocking array must be nonempty.
+
+| Field | Purpose |
+|---|---|
+| `usernamePrefixes` | Personal home-path and bare username prefixes |
+| `privateHosts` | Private service hosts |
+| `eventsHosts` | Private events service hosts |
+| `privateDomains` | Private domain catch-all |
+| `packageScopes` | Private package scope names, **without** the leading `@` |
+| `privateSlugs` | Private project/repository slugs |
+| `vaultClearSlugs` | Members of `privateSlugs` allowed by the synchronous vault namespace consumer; case-insensitive subset |
+| `personalNames` | Personal segments in home-relative `Projects` paths |
+| `publicEmails` | Exact published email contacts permitted by occurrence |
+| `publicUrls` | Exact public publication URLs permitted in designated attribution files |
+
+This invented example demonstrates the schema; replace it locally rather than treating these values as protection for your host:
+
+```json
+{
+  "version": 1,
+  "usernamePrefixes": ["sampleg"],
+  "privateHosts": ["gitlab.example.invalid"],
+  "eventsHosts": ["events.example.invalid"],
+  "privateDomains": ["example.invalid"],
+  "packageScopes": ["example"],
+  "privateSlugs": ["project-secret", "project-public"],
+  "vaultClearSlugs": ["project-public"],
+  "personalNames": ["SampleOwner"],
+  "publicEmails": ["office@example.invalid"],
+  "publicUrls": ["https://www.example.invalid", "www.example.invalid"]
+}
+```
+
+Public contacts exempt only matching occurrences. A line that combines a published contact with a private host still fails. Public URL exceptions apply to designated publication files such as the root README, plugin manifests and site attribution pages. They do not grant every file permission to contain a private domain. Clearance affects the synchronous vault namespace consumer; the full scanner still checks private slugs.
+
+## Scans and releases
+
+An ordinary scan with no host file visibly warns that host-specific rules are unavailable. Generic rules and independently configured confidential-name checks continue. An unsafe or malformed source fails the scan. The synchronous namespace guard stays synchronous and conservatively redacts identities for an invalid/unsafe policy or an explicitly configured missing source.
+
+Release checks require the source with `--require-owner-patterns`. Packed scans also read the actual contents listed in npm's JSON inventory:
+
+```sh
+node scripts/lib/validate/check-owner-leakage.mjs /absolute/extracted/package \
+  --require-owner-patterns --packed-files /absolute/inventory.json
+```
+
+Use an inventory describing the actual extracted tarball and scan that extraction, not just a list of filenames. Packed mode checks all listed regular files and rejects unsafe paths, symlinks and unreadable entries. Ordinary test/file exclusions and CP8/CP10 filename exceptions do not exempt packed contents. Violation output keeps checkpoint IDs, counts and safe file/line locations, omits offending content, and replaces private filename segments; it does not publish configured policy values. This detects the configured patterns, not every possible unknown secret.
+
+Confidential customer-name checking (CP11) remains separately configured through `SO_CONFIDENTIAL_NAMES_FILE` or `owner.yaml` `paths.confidential-names-file`. A configured unusable CP11 source fails closed; absence of that optional source does not disable the other rules.
+
+## Migration and configured vault paths
+
+Hosts upgrading from the previous embedded pattern lists must privately migrate the values they relied on to this version 1 file before strict release checks. Preserve blocking entries, narrowly justified public contacts/URLs and vault clearance; verify mode and a strict scan without printing the source. Do not substitute invented fixture values or remove protection to pass a release. New hosts opt in by creating their own protected policy.
+
+Vault tools resolve the canonical vault from `SO_VAULT_DIR`, then `owner.yaml` `paths.vault-dir`. `vault-consolidate.mjs --canonical` overrides both; it retains the generic source default `~/Projects/vault`, and a source equal to the canonical real path is a no-op before backups or writes. Existing sources require a configured canonical destination. A missing source retains its harmless no-op behavior.
+
+`migrate-vault-paths.mjs` replaces narrowly matched legacy `vault-dir` bases with the whole configured target, preserving suffixes, scalar quoting and comments. It skips the vault-target migration when unconfigured or invalid, without inserting a guessed personal segment; its separately configured username rewrite still applies. Historical and username-owned lines retain their existing protections. Preview either tool before applying it.

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

@@ -74,7 +74,17 @@ The event is what keeps the skip countable rather than silent: `orchestrator.sco
 
 The grant is exactly one directory: containment is exact-prefix on the realpath-resolved candidate (both the raw and the canonical project root are encoded, since Claude Code names the directory after the path it was launched with), so a SIBLING repo's memory dir, an adjacent-prefix sibling directory (`<memory>-evil/`), a `..` traversal out of it, and every other out-of-repo path stay denied. One honest caveat: the harness name is not unique — `encodeProjectDir()` maps both `/` and `.` to `-`, so two repo roots differing only in `.` vs `-` (`/x/a.b` and `/x/a-b`) share ONE memory dir. That collision is the harness's, inherited here and not narrowable by this gate — and in-repo enforcement, including Discovery's `allowedPaths: []` deny-all, is untouched. The encoder is bound lazily and a load failure falls through to the deny (fail-closed). **Who the grant is for (#1352): the COORDINATOR only.** The carve-out opens a directory whose content is auto-injected as trusted project context into every later session, outside `git diff`, CI review, owner-leakage and gitleaks — so a dispatched wave agent must not reach it. The discriminator is the payload's **`agent_id`**, and it is measured, not assumed (Claude Code 2.1.270, `strings` over the shipped binary, 2026-09-13): the base hook-input builder every event shares is `{session_id, transcript_path: yf(session.id), cwd, …, agent_id: toolUseContext?.agentId, agent_type}`, which PreToolUse spreads verbatim, and the harness's own schema says of `agent_id` — *"Present only when the hook fires from within a subagent… Absent for the main thread, even in `--agent` sessions. Use this field (not `agent_type`) to distinguish subagent calls from main-thread calls."* The issue's original candidate is refuted by the same source: `transcript_path` is derived from the SESSION id, so coordinator and subagent carry the identical value; so is `CLAUDE_CODE_SESSION_ID`, and `CLAUDE_CODE_CHILD_SESSION=1` was measured in a main-thread `env` dump (`isSidechain:false`).
 
-`classifyCaller()` therefore returns `subagent` (non-empty `agent_id` → **no carve-out**; the write falls through to the normal gates, which is a DENY under Discovery's `allowedPaths: []`), `coordinator` (no `agent_id` but a non-empty `agent_type` — per the schema that combination is the main thread of an `--agent` session), or `absent` (neither field). **`absent` keeps the pre-#1352 ALLOW, deliberately fail-OPEN:** fail-closed on ambiguity would deny the coordinator's own memory writes and break `/close`, and a harness that sends no marker is indistinguishable from a main thread. The outcome rides on the existing `orchestrator.scope.memory_dir_allowed` event as `discriminator`, so the fail-open case is countable rather than silent (HR-105) — revisit if `absent` ever dominates the records on a harness that does dispatch subagents.
+`classifyCaller()` therefore returns `subagent` (non-empty `agent_id` → **no carve-out**; the write falls through to the normal gates, which is a DENY under Discovery's `allowedPaths: []`), `coordinator` (no `agent_id` but a non-empty `agent_type` — per the schema that combination is the main thread of an `--agent` session), or `absent` (neither field). **For a caller outside a verified isolated agent checkout, `absent` keeps the pre-#1352 ALLOW, deliberately fail-OPEN:** fail-closed on ambiguity would deny the coordinator's own memory writes and break `/close`, and a harness that sends no marker is indistinguishable from a main thread. The outcome rides on the existing `orchestrator.scope.memory_dir_allowed` event as `discriminator`, so the fail-open case is countable rather than silent (HR-105) — revisit if `absent` ever dominates the records on a harness that does dispatch subagents.
+
+### 2.5 Isolated agent worktrees (#1504 items 1–2)
+
+`resolveScopeContext()` separates the coordinator's **manifest root** from the agent's **write root**. `enforce-scope`, `enforce-commands` and `post-bash-write-verify` use this context; `resolveSessionRoot()` keeps its existing lifecycle behavior. A relative grant such as `src/**` applies to the actual agent checkout. Writing the coordinator's `src/` requires an explicit absolute grant, and isolated agents receive neither coordinator control-file nor memory-directory carveouts, even when their hook payload omits `agent_id`.
+
+Discovery requires the Claude harness agent-directory shape and reciprocal Git worktree metadata belonging to the launch checkout's common Git directory. A local own, unbound or corrupt manifest retains precedence. When no local authority exists, the resolver inspects only registered worktree roots, at most 256 entries, and adopts a uniquely owned manifest using process-local session identity. Multiple owned coordinators, unreadable discovery or an unsafe remote manifest deny instead of becoming unrestricted absence. Unknown or foreign remote manifests cannot supply authority. Ordinary checkout and no-match behavior remain unchanged; arbitrary subdirectories of registered worktrees are not searched.
+
+The post-Bash hook reads control state from the coordinator but observes Git changes in the agent checkout. Its saved observations are keyed by both roots and the manifest path, preventing one agent's snapshot from hiding another's changes.
+
+These guarantees require the named hooks to run. Native Codex `exec_command` and `apply_patch` are not wired to these Claude `PreToolUse` matchers. Codex sessions still require explicit scope manifests, disjoint assignments and diff verification; this change does not claim native pre-tool enforcement. The environment-only commit guard and dispatch-ledger retention are separate mechanisms.
 
 ## 3. The collision algorithm
 
@@ -86,7 +96,7 @@ The grant is exactly one directory: containment is exact-prefix on the realpath-
    - **3a — witness:** expand both entries against `KNOWN = knownFiles ∪ {every concrete entry of every agent}`; a non-empty intersection is `glob-expanded`. The second half of that union matters — a file the wave is about to *create* is not in `git ls-files`, but a concrete claim by one agent can still witness another's glob.
    - **3b — prefix fallback:** for the intersection that exists only in files not yet on disk. Requires literal-prefix containment in either direction, at least one **recursive** entry (`**`, or a trailing `/`, which `pathMatchesPattern` matches by `startsWith` at any depth), and compatible literal suffixes. The suffix filter is a necessary condition, so it adds no false negative while removing `scripts/**/*.ts` vs `scripts/**/*.mjs`.
 
-`knownFiles` is **injected, never discovered**: `scope-gate.mjs` is hook-safe (pure, sync, no I/O, no spawn) because `enforce-scope.mjs` reaches it on a hot path, and under the exit-0/stdout-JSON protocol a throw there reads as "no decision" = ALLOW. The CLI spawns `git ls-files` in `knownRepoFiles()`; the hook does the same in `listTrackedFiles()`, both resolving `git rev-parse --show-toplevel` first so a session started in a subdirectory produces repo-relative paths on both sides.
+`knownFiles` is **injected, never discovered** by the collision helpers: they remain pure and synchronous, with no I/O or spawning. The separate scope-context resolver in the same module performs bounded synchronous filesystem reads (§ 2.5). Under the exit-0/stdout-JSON protocol, an uncaught throw in a hook reads as "no decision" = ALLOW. The CLI spawns `git ls-files` in `knownRepoFiles()`; the hook does the same in `listTrackedFiles()`, both resolving `git rev-parse --show-toplevel` first so a session started in a subdirectory produces repo-relative paths on both sides.
 
 Duplicate agent ids are reported separately (`duplicateIds`), not as a self-collision. A record with no usable id runs as `<unnamed#i>` rather than being dropped — an unreviewed scope is exactly the one that collides.
 
@@ -201,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
 
@@ -218,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
 

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/enforce-commands.mjs

@@ -95,10 +95,9 @@ import { pathToFileURL } from 'node:url';
 /** @type {typeof import('../scripts/lib/io.mjs').emitAllow} */ let emitAllow;
 /** @type {typeof import('../scripts/lib/io.mjs').emitDeny} */ let emitDeny;
 /** @type {typeof import('../scripts/lib/io.mjs').emitWarn} */ let emitWarn;
-let resolveSessionRoot;
 let readJson;
 // #1504 point 6 — bound from scope-gate below.
-let findOwnScopeFile;
+let resolveScopeContext;
 let extractBashWriteTargets;
 let pathMatchesPattern;
 /** @type {typeof import('../scripts/lib/session-identity/own-session.mjs').readProcessLocalSessionIds} */
@@ -208,10 +207,9 @@ async function bootstrap() {
   );
 
   ({ readStdin, emitAllow, emitDeny, emitWarn } = modules.io);
-  ({ resolveSessionRoot } = modules.platform);
   ({ readJson } = modules.common);
   ({ extractBashWriteTargets, pathMatchesPattern } = modules.hardening);
-  ({ findOwnScopeFile } = modules.scopeGate);
+  ({ resolveScopeContext } = modules.scopeGate);
   ({ readProcessLocalSessionIds, classifyManifestSession } = modules.sessionIdentity);
   blocker = modules.blocker;
   degradedLabels = degraded;
@@ -281,21 +279,13 @@ async function main() {
     );
   }
 
-  // #1492 — the SESSION's working copy, not the launch dir `$CLAUDE_PROJECT_DIR`
-  // keeps after `EnterWorktree` (the manifest lives in the worktree). See
-  // `resolveSessionRoot` in scripts/lib/platform.mjs.
-  const projectRoot = resolveSessionRoot(input.cwd);
-
-  // `new Set(...)` is load-bearing: `readProcessLocalSessionIds` returns a
-  // string[], and `classifyManifestSession` does `ownIds instanceof Set ?
-  // ownIds : new Set()` — a bare array would silently become EMPTY.
+  // Coordinator control state and isolated-agent write targets may live in
+  // different working copies; the shared guard context resolves both.
   const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
-
-  // G3 — no scope file → allow. #1504 point 6: the first manifest that is not
-  // provably a peer's, so a peer's higher-precedence `.pi`/`.cursor`/`.codex`
-  // manifest no longer hides this session's own one; only when every candidate
-  // is foreign does the first come back, and G3b below stands down as before.
-  const located = findOwnScopeFile(projectRoot, ownIds, classifyManifestSession);
+  const context = resolveScopeContext({ cwd: input.cwd, ownIds, classify: classifyManifestSession });
+  if (context.error) return emitDeny('Scope coordinator cannot be resolved', context.error);
+  const projectRoot = context.writeRoot;
+  const located = context;
   const scopePath = located.path ?? located.foreignPath;
   if (!scopePath) return flushNotices(notices);
 
@@ -350,7 +340,7 @@ async function main() {
             wave: scope.wave,
             command_hash: hashCommand(command),
           },
-          { repoRoot: projectRoot },
+          { repoRoot: context.manifestRoot },
         );
       } catch { /* observability is best-effort — never blocks the decision */ }
       return flushNotices(notices);