session-orchestrator 3.22.0 → 3.23.0

package/docs/session-config-reference.md

@@ -75,11 +75,32 @@ Some sub-configs live in dedicated policy files under `.orchestrator/policy/`:
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `agents-per-wave` | integer or integer with overrides | `6` | Maximum parallel subagents per wave. Supports session-type overrides: `6 (deep: 18)` outputs `{"default": 6, "deep": 18}`. Plain integers remain plain. The override key names a session type but does **not** create one: there is no `session-type:` Session Config key — `parseSessionConfig()` emits none, so writing one into a repo's `## Session Config` block is inert prose. The session type comes from the `/session` argument (default `deep`, see `commands/session.md`) and is persisted to STATE.md frontmatter as `session-type:`, which is the only live read (`scripts/print-applicable-rules.mjs` rule mode-gating). |
-| `agent-mapping` | object | null | Optional mapping of role keys to agent names for explicit agent binding. Keys: `impl`, `test`, `db`, `ui`, `security`, `compliance`, `docs`, `perf`. Example: `{ impl: code-editor, test: test-specialist }`. Overrides auto-discovery when present. |
+| `agent-mapping` | object | null | Optional mapping of role keys to agent names for explicit agent binding. Keys: `impl`, `test`, `db`, `ui`, `security`, `compliance`, `docs`, `perf`. Example: `{ impl: code-editor, test: test-specialist }`. Overrides auto-discovery when present. Values may carry a channel prefix — see § `agent-mapping` values below. |
 | `waves` | integer | `5` | Number of execution waves for feature and deep sessions. |
 | `recent-commits` | integer | `20` | Number of recent commits to display during session start git analysis. |
 | `special` | string | none | Repo-specific instructions. Freeform text that the orchestrator reads and follows during sessions. |
 
+### `agent-mapping` values — channel prefixes (#1150)
+
+A mapping value has three forms, distinguished by the colon:
+
+| Value form | Meaning | Dispatch |
+|---|---|---|
+| `<project-agent>` (no colon) | An agent file under `<state-dir>/agents/<name>.md` | Agent tool, unchanged |
+| `session-orchestrator:<plugin-agent>` | A plugin agent shipped by this repo | Agent tool, unchanged |
+| `cursor:<model>` | A **foreign model** over the Cursor channel (`cursor-agent`) | Coordinator-direct via `dispatchForeign()` — **not** the Agent tool |
+
+```
+agent-mapping: { impl: cursor:composer-2.5, test: cursor:cursor-grok-4.6-high, security: security-reviewer }
+```
+
+**Unknown channels fail loud.** `scripts/lib/config.mjs` parses this key and throws on any prefix outside `cursor` / `session-orchestrator` (`agent-mapping role '<k>' names unknown channel '<c>' …`), and on a prefix with an empty target. Silently accepting a typo would dispatch to an agent that does not exist and surface only as an empty wave, much later. A value without a colon is a plain agent name and is never channel-parsed.
+
+**Where the rest of the contract lives** — deliberately not here, so one place owns it:
+
+- **Model selection** (which model for which role, and why): the account-switch routing SSOT, ADR-002 / `tools/routing/routing.yaml`. Working defaults are `composer-2.5` for foreign impl and `cursor-grok-4.6-high` for review / test-writing / judgment roles.
+- **Dispatch contract** (detached worktree, the `never_foreign` role lock, the filesystem-measured verdict, the MANDATORY Claude semantic diff-review before merge-back, wall-clock timeout instead of `maxTurns`, and the `orchestrator.foreign_dispatch.completed` event that replaces the hook-chain telemetry a foreign run cannot emit): `skills/wave-executor/wave-loop.md` § Third branch: foreign-model dispatch.
+
 ## VCS & Infrastructure
 
 | Field | Type | Default | Description |
@@ -193,7 +214,7 @@ issue-budget:
 
 **Exemptions (load-bearing).** `priority::critical`, the carryover class (`[Carryover]`, `[SPIRAL]`/`[FAILED]`, `type::carryover`, a bare `carryover` label) and `broken-window` closure issues bypass the cap unconditionally. Without those exemptions the cap would break the standing session-end promises in `skills/session-end/SKILL.md` (Phase 1.8 "non-deselectable" SPIRAL/FAILED carryover, and the Critical Rule "ALWAYS create issues for unfinished PLANNED work"). Exempt creations are counted in the state file's `exempt` field for observability but never blocked.
 
-**Counter file:** `.orchestrator/runtime/issue-budget.json` — `{ sessionId, count, exempt, overflow: [...] }`. It resets automatically when a new `sessionId` is seen.
+**Counter file:** `.orchestrator/runtime/issue-budget/<sha256(sessionId)[0..16]>.json` — `{ sessionId, count, exempt, overflow: [...] }`, ONE file per session (#1141: the former single `issue-budget.json` slot was reset by whichever session wrote last, so two sessions in one working copy silently disabled each other's cap). Identity-less callers still use the legacy flat path; `budgetStatePath(repoRoot, sessionId)` in `scripts/lib/issue-budget.mjs` is the resolver.
 
 **Used by:** `hooks/pre-bash-issue-budget.mjs` (shell path, PreToolUse/Bash), `scripts/lib/spiral-carryover.mjs` `runCli()` (programmatic path), `scripts/lib/issue-budget.mjs` (shared decision core), `skills/session-end/SKILL.md` Phase 5 Step 3b (overflow drain). Parser: `scripts/lib/config/issue-budget.mjs`.
 
@@ -1215,7 +1236,7 @@ reconcile:
 |-------|------|---------|-------------|
 | `reconcile.enabled` | boolean | `false` | Master toggle. When `false`, session-end Phase 3.6.8 is a silent no-op — the reconciliation engine never runs. When `true`, the engine evaluates learnings that meet `confidence-floor` and presents rule proposals to the operator via `AskUserQuestion`. Rules are never written without explicit operator approval. Epic #693 FA3 (#696). |
 | `reconcile.mode` | string (`warn` \| `off`) | `warn` | Advisory posture. `warn`: proposals surface in the session-end AUQ and the operator may accept or reject each one; accepted proposals are written to `targets`. `off`: advisory surface is suppressed entirely (equivalent to `enabled: false` for the AUQ step, but Phase 3.6.8 may still emit metrics). In both modes, rules are **never** auto-applied — every write is operator-AUQ-gated. |
-| `reconcile.targets` | string[] | `["repo-local"]` | Where approved rules are written. `repo-local` (v1) maps to `.claude/rules/` in the current repository. This is the rule-write location — it is NOT issue-state or label sync. Future values may include `baseline` (global baseline rules) or `global` (cross-repo). |
+| `reconcile.targets` | string[] | `["repo-local"]` | Where approved rules are written — a **CLOSED enum**: `repo-local` → `<repoRoot>/.claude/rules/<slug>.md`; `baseline` (#1099) → `<baselineRoot>/proposals/<slug>.md`, where `<baselineRoot>` is `plan-baseline-path` resolved host-locally (`SO_BASELINE_PATH` env > `owner.yaml` `paths.baseline-path` > committed value). Both targets are equally AUQ-gated and advisory — the `baseline` write drops files into `proposals/` in that checkout and commits nothing. This is the rule-write location — it is NOT issue-state or label sync. An **unknown member is DROPPED with a stderr WARN** naming it and the valid set (`scripts/lib/config/reconcile.mjs` `VALID_TARGETS`), never a throw: the parser is tolerant by contract and runs at session-start, where a throw would fail the session on a config typo. `global` (cross-repo) is documented-but-unimplemented and is deliberately NOT a member — admitting a value nothing implements is the same defect class as the unvalidated pass-through this enum replaced. When `baseline` is declared but its root is unresolvable on all three tiers, is still the committed `OVERRIDE-IN-…` placeholder, or is not absolute, `resolveEffectiveTargets()` (`scripts/lib/reconcile/engine.mjs`) drops it with ONE WARN **before** the approval AUQ, so the operator is never asked to approve a write to a destination that cannot exist; a root that does not exist on disk is refused at the writer and is never created. |
 | `reconcile.rule-expiry-days` | integer \| null | `null` | Optional override for the TTL stamped into each generated rule's `expires-at` frontmatter. **Default is `null`** — when null or absent, the engine uses per-type TTL (`deriveExpiresAt`, default 60 days). Setting this to a positive integer N forces a flat N-day expiry for all proposals in this repo, overriding per-type TTL. CRITICAL: the default must remain `null` to preserve per-type TTL behaviour; a non-null committed default would silently force flat expiry. |
 | `reconcile.confidence-floor` | float | `0.5` | Minimum learning confidence (0.0..1.0) required before a learning is eligible for a rule proposal. Learnings with `confidence < confidence-floor` are skipped by the engine. Bounds: `0.0 ≤ value ≤ 1.0`; out-of-range values silently fall back to `0.5`. Set to `0.0` to surface proposals for all learnings regardless of confidence. |
 | `reconcile.min-rule-days` | integer | `7` | Floor (in days) applied to the emitted rule's `expires-at` — issue #741.1. A learning close to its natural per-type TTL expiry could otherwise generate a rule that expires almost immediately ("born-dead"); `computeExpiresAt()` (`scripts/lib/reconcile/emitter.mjs`) floors the result at `now + min-rule-days` so an approved rule always has at least this many days of active life. Mirrors the hardcoded `MIN_RULE_DAYS_DEFAULT` constant in the emitter. Bounds: positive integer; non-finite or ≤0 values fall back to the default. |
@@ -1539,7 +1560,7 @@ When any condition is false, the full 5-wave flow runs as before — the check i
 
 ### What changes when express path is active
 
-- **session-start:** After Phase 8 Q&A, emits `"Express path activated — N tasks, coordinator-direct, no inter-wave checks."` banner and executes tasks directly as the coordinator. session-plan is called but receives the express-path signal.
+- **session-start:** After Phase 8 Q&A, Phase 8.5 runs `node scripts/express-path.mjs` (the canonical caller — it makes the decision and records `orchestrator.express_path.evaluated` on refusal as well as activation, #1146), which emits the `"Express path activated — N tasks, coordinator-direct, no inter-wave checks."` banner. Tasks are then executed directly as the coordinator. session-plan is called but receives the express-path signal.
 - **session-plan:** Detects the banner in conversation context and emits a minimal 1-wave `coordinator-direct` plan (0 agents dispatched). Skips all role decomposition, complexity scoring, and wave splitting.
 - **STATE.md:** Activation is logged in the `## Deviations` section for traceability.
 - **Inter-wave checkpoints:** Skipped entirely — no Discovery → Impl-Core → Quality pipeline.
@@ -1563,6 +1584,7 @@ Set `express-path.enabled: false` when:
 | `housekeeping` | 1–3 | `true` | Yes | No — parallel agents required |
 
 **Related skills and files:**
+- `scripts/express-path.mjs` — the CLI Phase 8.5 runs; `scripts/lib/express-path.mjs` holds the decision + its `orchestrator.express_path.evaluated` record
 - `skills/session-start/SKILL.md` — Phase 8.5: Express Path Evaluation (activation logic + banner)
 - `skills/session-plan/SKILL.md` — Express Path Short-Circuit section (1-wave plan emission)
 - GitLab issue `#214` (foundation and codification)

package/docs/session-config-template.md

@@ -410,7 +410,7 @@ Opt-in config foundation for the FA3 (#696) advisory rule-proposal delivery at s
 reconcile:
   enabled: false                 # opt-in; FA3 reads this to gate session-end Phase 3.6.8
   mode: warn                     # off | warn — advisory only; rules NEVER auto-applied (#696)
-  targets: [repo-local]          # where approved rules are written; repo-local = .claude/rules/ in v1
+  targets: [repo-local]          # closed enum: repo-local = .claude/rules/ · baseline = <plan-baseline-path>/proposals/ (#1099)
   rule-expiry-days: null         # null = per-type TTL (default 60d); set positive integer for flat override (#697)
   confidence-floor: 0.5          # float 0.0..1.0 — min learning confidence for rule proposal eligibility
   min-rule-days: 7               # #741.1 — floor for emitted rule expires-at: max(derived, now + N days); prevents born-dead rules
@@ -425,6 +425,7 @@ Field semantics:
 - **`confidence-floor`** — learnings below this confidence level are not eligible for rule proposals. Default 0.5 matches `memory.proposals.confidence-floor`.
 - **`min-rule-days`** — floor window (days) applied to a proposed rule's `expires-at` so a near-dead or already-elapsed natural expiry never produces a born-dead rule. Positive integer; malformed or ≤0 falls back to 7 (issue #741.1).
 - **`min-insight-chars`** — opt-in minimum insight length gating the eligibility placeholder-insight check; rejects a learning whose trimmed insight is shorter than N characters before rule conversion. Integer ≥ 0; `0` disables the check (issue #741.2).
+- **`targets`** — CLOSED enum, `repo-local` | `baseline` (issue #1099). `repo-local` writes `<repoRoot>/.claude/rules/<slug>.md`; `baseline` writes `<baselineRoot>/proposals/<slug>.md`, where `<baselineRoot>` is `plan-baseline-path` resolved host-locally (`SO_BASELINE_PATH` env > `owner.yaml` `paths.baseline-path` > committed value). Both are AUQ-gated and advisory — the baseline write commits nothing in that repo. An unknown member is dropped with a stderr WARN naming it and the valid set; `global` is documented-but-unimplemented and is NOT a member. A `baseline` target whose root is unresolvable, is still an `OVERRIDE-IN-…` placeholder, is not absolute, or does not exist on disk degrades to a no-op with a WARN — the root is never created.
 
 Read by: `scripts/lib/config/reconcile.mjs` (parser), `skills/session-end/SKILL.md` Phase 3.6.8 (FA3 delivery). FA2 engine: `scripts/lib/reconcile/`.
 
@@ -604,9 +605,9 @@ webhooks:
     url: https://gitlab.example.com/hooks/pipeline
 ```
 
-Read by: `scripts/lib/webhook-url.mjs`, hooks that emit events (`hooks/on-stop.mjs`, `hooks/on-subagent-stop.mjs`).
+Measured: `scripts/lib/webhook-url.mjs` (`resolveWebhookUrl`) is the only reader of this `webhooks:` block, and it currently has **zero callers repo-wide** (`grep -rn "webhook-url" scripts/ hooks/` outside itself and one exemption comment in `check-unwired-features.mjs`) — the block is unreachable at HEAD; follow-up issue pending.
 
-The internal Clank Event Bus uses two separate env vars (`CLANK_EVENT_SECRET`, `CLANK_EVENT_URL`) — both required for the fire-and-forget POST.
+What actually fires a webhook today is a **separate** mechanism: `scripts/lib/events.mjs`'s `emitEvent()` reads `CLANK_EVENT_SECRET` + `CLANK_EVENT_URL` directly from the environment (never from this Session Config block) and, when both are set, fire-and-forget POSTs every emitted event to the internal Clank Event Bus. Every hook that calls `emitEvent()` — which is most of `hooks/` — participates in that path; none of them reads `webhooks:` here.
 
 ## Hook Runtime Profile (env-only, not config)
 

package/docs/telemetry.md

@@ -84,6 +84,16 @@ Precedence, highest wins:
    headless or CI invocation never shows this prompt and never sends
    telemetry, regardless of any saved state.
 
+The prompt is triggered **mechanically**: `hooks/on-session-start.mjs` calls
+`resolveConsent()` on every session start and, only when no decision is on
+record and the run is not CI, injects a one-line instruction into the session
+via `hookSpecificOutput.additionalContext` — riding the same single stdout
+envelope as the host banner. The skill phase that describes the question
+(`skills/session-start/SKILL.md` § Phase 6.8) is the wording, not the trigger.
+The CI check is `isCiEnv()`, deliberately **not** `isHeadless()`: a hook's
+stdout is always a pipe, so `isHeadless()` would answer "headless" every time
+and the prompt could never appear (#1138).
+
 If the consent file is corrupt or unreadable, the client fails **closed**:
 telemetry state degrades to "no consent" (nothing sent) rather than
 guessing, with a one-line stderr hint pointing at the CLI below.
@@ -129,6 +139,18 @@ unreachable, the batch queues locally (bounded size, oldest entries dropped
 first) and retries later. Telemetry never blocks or slows down a session
 beyond that short timeout budget.
 
+**When a send is attempted.** `hooks/on-session-end.mjs` calls `flush()` at the
+end of every session teardown — including sessions that never run `/close`. The
+`skills/session-end/SKILL.md` § Phase 3.45 description documents the behaviour;
+the hook is what fires it. Each attempt writes one
+`orchestrator.telemetry.flush` breadcrumb (`{outcome, reason}` only — no
+payload, no `anon_id`) to the repo's local `events.jsonl`, so the send rate is
+measurable rather than assumed. A second, `Skill`-triggered daily fallback
+sends when more than 24h have passed since the last successful flush AND either
+the offline queue is non-empty or a session has completed since — the latter
+clause is what lets the fallback originate a ping instead of only retrying a
+failed one (#1138).
+
 ## Retention
 
 - **Raw records:** kept 24 months, then pruned. The retention window exists

package/hooks/_lib/lock-bootstrap.mjs

@@ -89,8 +89,9 @@ export async function bootstrapLock({
   }
 
   // Step 1: try to acquire. If a fresh acquire succeeds, we are done.
-  // If a stale-PID-dead/-alive lock exists, force-overwrite it (the prior
-  // session has died; the current raw owner can take the worktree).
+  // If a stale-heartbeat lock exists, force-overwrite it (the prior session
+  // stopped heartbeating past its ttl; the current raw owner can take the
+  // worktree).
   // Only an exact match of the existing physical raw sessionId permits the
   // same-session force-refresh. semantic_session_id, STATE.md `session`, and
   // an owner proof never make a different raw id the same owner.
@@ -107,8 +108,11 @@ export async function bootstrapLock({
 
   const shouldForce =
     acquireResult.ok !== true && (
-      acquireResult.reason === 'stale-pid-dead' ||
-      acquireResult.reason === 'stale-pid-alive' ||
+      // #1137: 'stale-heartbeat' replaced the former 'stale-pid-dead' /
+      // 'stale-pid-alive' pair. Both legacy spellings are gone from
+      // session-lock.mjs; matching only the new one keeps this force-branch
+      // reachable.
+      acquireResult.reason === 'stale-heartbeat' ||
       (acquireResult.reason === 'active' &&
         acquireResult.existingLock &&
         acquireResult.existingLock.session_id === sessionId)