session-orchestrator 3.23.0 → 4.0.0

package/skills/evolve/SKILL.md

@@ -34,6 +34,8 @@ Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills
 
 ## Phase 1: Config & Data Loading
 
+**Telemetry start marker (#1200):** note the current wall-clock time before Step 1.1 runs (e.g. `date +%s%3N`, or the coordinator's own turn-start instant). Every `orchestrator.evolve.completed` emit in Phase 1 / Phase 3 below reports `duration_ms` (placeholder `DURATION_MS`) as the elapsed milliseconds since this marker — same in-memory-value convention as `CT`/`AC`/`ASK`/`DROP` in `skills/session-end/SKILL.md`'s `orchestrator.handover.gated` emits.
+
 ### 1.1 Read Session Config
 
 Read and parse Session Config per `skills/_shared/config-reading.md`. Store result as `$CONFIG`.
@@ -44,6 +46,13 @@ Extract `persistence` from `$CONFIG`. If `persistence` is `false`, abort with me
 
 > "Learnings require persistence to be enabled in Session Config. Add `persistence: true` to your Session Config block (CLAUDE.md for Claude Code, AGENTS.md for Codex CLI)."
 
+**Telemetry on abort (#1200, #1206):** before stopping, emit the abort form of the run-completion event. Kept as a minimal `emit-event.mjs` call, not routed through `scripts/sweep-expired-learnings.mjs` — no store-write CLI has run yet at this gate (it fires before Step 1.4 even reads `learnings.jsonl`), so there is no mechanical pipeline call site to fold this emit into, unlike the Step 3.5(5)/(6) success path below:
+
+```bash
+node scripts/emit-event.mjs --type orchestrator.evolve.completed --payload \
+  "$(node -e "process.stdout.write(JSON.stringify({aborted: 'persistence-disabled', reason: 'Learnings require persistence to be enabled in Session Config.'.slice(0,300), duration_ms: DURATION_MS}))")"
+```
+
 ### 1.3 Determine Mode
 
 Read mode from `$ARGUMENTS`:
@@ -91,7 +100,12 @@ Extract learnings from session history.
 - Read all entries from `.orchestrator/metrics/sessions.jsonl` (or `<state-dir>/metrics/sessions.jsonl` if the v2 path does not exist — see Phase 1.4 fallback)
 - Parse each JSONL line as JSON
 - Sort by `completed_at` descending (most recent first)
-- If no sessions found, abort: "No session data available. Complete at least one session before running evolve."
+- If no sessions found, abort: "No session data available. Complete at least one session before running evolve." **Telemetry on abort (#1200, #1206):** before stopping, emit — same minimal `emit-event.mjs` call as Phase 1.2's abort, and for the same reason: this gate fires before the Step 3.5(5) `sweep-expired-learnings.mjs --prune` call exists to fold the emit into:
+
+  ```bash
+  node scripts/emit-event.mjs --type orchestrator.evolve.completed --payload \
+    "$(node -e "process.stdout.write(JSON.stringify({aborted: 'no-session-data', reason: 'No session data available. Complete at least one session before running evolve.'.slice(0,300), duration_ms: DURATION_MS}))")"
+  ```
 
 ### Step 3.1b: Read Extra Sources (#638)
 
@@ -167,7 +181,7 @@ For each of the 9 built-in analyzer learning types, apply these heuristics:
 - Read `.orchestrator/metrics/events.jsonl` (session + wave events) and the registry `sweep.log` at `~/.config/session-orchestrator/sessions/sweep.log`. Both are optional — missing files produce no candidates.
 - Invoke `scripts/lib/hardware-pattern-detector.mjs` → `detectHardwarePatterns({events, sweepLogEntries, thresholds})`. Thresholds come from Session Config `resource-thresholds` when present, falling back to `DEFAULT_THRESHOLDS`.
 - Five detection signals (aggregated per `(signal, host_class)` pair, ≥2 occurrences required):
-  - **oom-kill** — `orchestrator.session.stopped` with `exit_code: 137` or OOM-marker in `error`
+  - **oom-kill** — `orchestrator.turn.stopped` (or its deprecated alias `orchestrator.session.stopped`, which `hooks/on-stop.mjs` still emits with `deprecated: true` until **2027-03-06**) with `exit_code: 137` or OOM-marker in `error`. Both names are accepted for the deprecation window because every OOM record already on disk carries only the legacy name; the detector's set lives in `OOM_TERMINAL_EVENTS` (`scripts/lib/hardware-pattern-detector.mjs`) and drops the alias on that date.
   - **heartbeat-gap** — registry sweep-log entries with `gap_minutes` above `resource-thresholds.zombie-threshold-min`
   - **concurrent-session-pressure** — session-start events with `peer_count ≥ concurrent-sessions-warn`
   - **disk-full** — events whose `error` matches `ENOSPC` / "no space left"
@@ -302,22 +316,34 @@ For confirmed learnings, use atomic rewrite strategy:
    Write the full next-generation entry set (existing entries **with** the step-2/3 confidence
    updates, **plus** the step-4 new learnings) as JSONL to a temp sidecar **via the Write tool**
    (not a shell `>` redirect — the destructive-command guard blocks it), then invoke the
-   `--prune` subcommand of the sweep CLI:
+   `--prune` subcommand of the sweep CLI. **This call is also `/evolve`'s ONLY
+   `orchestrator.evolve.completed` success emit (#1206)** — export `N` (Step 3.5(4)'s
+   new-learnings count), `M` (Step 3.5(2)'s reinforced-existing count) and `DURATION_MS`
+   (elapsed ms since the Phase 1 marker) as real shell variables before running this line;
+   `${N:-0}`-style expansion means an un-exported variable degrades to a safe `0` rather than
+   an argument error:
 
    ```bash
    NEXT=".orchestrator/metrics/.learnings-next.jsonl"   # written by the step above
-   node scripts/sweep-expired-learnings.mjs --prune --apply --json --entries "$NEXT" && rm -f "$NEXT"
+   node scripts/sweep-expired-learnings.mjs --prune --apply --json --entries "$NEXT" \
+     --appended "${N:-0}" --boosted "${M:-0}" --duration-ms "${DURATION_MS:-0}" \
+     --repo-root "$(pwd)" && rm -f "$NEXT"
    ```
 
    `--file` / `--archive` default to the canonical store + archive paths — pass them only when
    operating on a non-default pair. The command prints ONE JSON line; capture it as `$PRUNE` and
-   report its `{scanned, kept, archived, byReason}` in the final summary. Preview first with
-   `--prune --dry-run --json` (same counts, zero writes) whenever the next generation was
-   hand-assembled.
-
-   > **This step is `/evolve`'s only store-write path.** Until #1017 the invocation lived here as
-   > an inline `node --input-type=module -e` block, which is a mechanism hiding inside prose: no
-   > `--help`, no exit-code contract, no test. Do not re-inline it, and do not hand-roll a
+   report its `{scanned, kept, archived, byReason}` in the final summary — `$PRUNE.archived` is
+   also the `pruned` counter the emit above just wrote, so there is nothing left to compute for
+   the telemetry after this line. Preview first with `--prune --dry-run --json` (same counts,
+   zero writes, **no telemetry emit** — dry-run never claims a completed run) whenever the next
+   generation was hand-assembled.
+
+   > **This step is `/evolve`'s only store-write path, and (since #1206) its only
+   > `orchestrator.evolve.completed` success emit.** Until #1017 the store write lived here as
+   > an inline `node --input-type=module -e` block, and until #1206 the telemetry emit was a
+   > SEPARATE `emit-event.mjs` call further down this file — both were a mechanism hiding inside
+   > prose: no `--help`, no exit-code contract, no test, and (for the emit) forgettable
+   > independently of the write it reported on. Do not re-inline either, and do not hand-roll a
    > `jq | ... > learnings.jsonl` pass — that bypasses every #721 safety net.
 
    **Exit codes are the no-op rule.** `0` = applied (or a clean no-op). `1` = input error: the
@@ -380,6 +406,13 @@ For confirmed learnings, use atomic rewrite strategy:
 
 Report: "Saved N new learnings, updated M existing. Total active: K."
 
+**Telemetry (#1200, #1206):** already emitted by `scripts/sweep-expired-learnings.mjs --prune`
+at Step 3.5(5) above — no separate action here. `appended`/`boosted`/`duration_ms` are whatever
+`$N`/`$M`/`$DURATION_MS` carried into that call, and `pruned` is `$PRUNE.archived` (the sweep
+CLI's own returned total). `promoted` is always `0` from THIS call site: promotion to `public`
+scope is the separate `npm run share:hw-learnings -- --promote` CLI, never invoked by
+`/evolve analyze` itself — see `docs/events-schema.md`.
+
 ### Step 3.6: C2 Auto-Repair Feeder (opt-in — #647)
 
 > **Default OFF (advisory-only).** With no `skill-evolution:` block in Session Config, this step surfaces repair candidates as ADVICE only — it applies nothing and opens no MR. This mirrors the opt-in precedent of `slopcheck` (#520) and `verification-auto-fix` (#521): the engine is dark unless explicitly enabled.
@@ -542,6 +575,8 @@ N active learnings (M high confidence, K expiring soon)
 
 Single-pass LLM derivation of USER.md + AGENT.md (peer cards from #503) updates from current learnings + sessions + steering files. Dry-run-default per #506 EARS contract.
 
+**Telemetry start marker (#1200):** note the current wall-clock time at Phase 6 entry (`DURATION_MS` in the Step 6.4/6.5 emits below is the elapsed milliseconds since this marker) — same placeholder convention as `skills/session-end/SKILL.md`'s `orchestrator.handover.gated` emits.
+
 ### Step 6.0: Argument Parsing
 
 Parse `$ARGUMENTS` for trailing flags after the `dialectic` keyword:
@@ -603,6 +638,29 @@ const result = await runDialecticDeriver({
 - If `--apply`: call `mergePeerCard(existingBody, managedUpdates)` from `scripts/lib/peer-cards/merger.mjs` for each card target, then `writePeerCard(repoRoot, 'user', mergedUserCard)` and `writePeerCard(repoRoot, 'agent', mergedAgentCard)` from `scripts/lib/peer-cards/writer.mjs`. Update the `updated:` frontmatter.
 - Report: `Dialectic-derived: M deltas to USER.md, N deltas to AGENT.md. Dry-run | Applied. Tokens: in=<X> out=<Y>.`
 
+**Telemetry (#1200, #1206) — emitted by `scripts/dialectic-deriver.mjs`, not skill prose.**
+The dry-run branch needs no action here: `runDialecticDeriver()` already emitted the success
+form (`mode: 'dry-run'`) internally at Step 6.2, using `countManagedSections(diff)` on the SAME
+diff this step presents — in dry-run the diff IS the final artefact, so the event and the
+artefact are computed from the same value. The **apply** branch is the one case that pipeline
+cannot record on its own: the merge above happens here, one layer up, so call
+`recordDialecticRun()` (the sibling export beside `emitEvolveCompleted` in
+`scripts/lib/learnings/evolve-telemetry.mjs`) immediately after the `writePeerCard()` calls,
+using each target's `mergePeerCard()` `stats` for the deltas:
+
+```javascript
+await recordDialecticRun({
+  repoRoot,
+  status: 'ok',
+  mode: 'apply',
+  userDeltas: userMergeStats.replaced + userMergeStats.appended,
+  agentDeltas: agentMergeStats.replaced + agentMergeStats.appended,
+  tokensIn: result.usage?.input_tokens,
+  tokensOut: result.usage?.output_tokens,
+  durationMs: DURATION_MS,
+});
+```
+
 ### Step 6.5: Error Handling
 - `status: 'unknown-model'` → fail with clear error (already thrown by validateModel)
 - `status: 'budget-exceeded'` → emit `{status:'budget-exceeded', used:N, budget:M}`, do NOT truncate
@@ -610,6 +668,24 @@ const result = await runDialecticDeriver({
 - `status: 'empty-input'` → exit clean with message "dialectic: skipped (no input)"
 - subagent crash → log ⚠, exit cleanly (do NOT write to `.orchestrator/dialectic-pending.md`)
 
+**Telemetry (#1200, #1206) — emitted by `scripts/dialectic-deriver.mjs` for THREE of the five
+outcomes.** `budget-exceeded`, `would-empty-card`, and `empty-input` are `runDialecticDeriver()`
+RETURN values, so the module records them itself, mechanically, at the exact return point —
+nothing to do here for those three. The remaining two are THROWN, not returned, and can only be
+caught one layer up:
+
+- `unknown-model` — `validateModel()` throws synchronously before `runDialecticDeriver()` can
+  record anything about the call.
+- `subagent-crash` — a `dispatchAgent`/`Agent()` failure propagates out of
+  `runDialecticDeriver()` uncaught (it has no status of its own for this case).
+
+Catch both here and call the SAME `recordDialecticRun()` used in Step 6.4's apply branch,
+passing the literal slug as `status` (the abort form: `{aborted: status, duration_ms}`):
+
+```javascript
+await recordDialecticRun({ repoRoot, status: 'unknown-model' /* or 'subagent-crash' */, durationMs: DURATION_MS });
+```
+
 Cross-reference: PRD #506 AC1-AC4 + EARS gates. Vault Integration: dialectic does NOT mirror to vault (#506 scope — peer cards are repo-local by design; vault mirror is for cross-repo sessions/learnings).
 
 ---

package/skills/frontmatter-guard/SKILL.md

@@ -94,13 +94,19 @@ The output is stable across calls for the same schema version. Regenerate only w
 
 ## Schema Source Path
 
-The canonical schema source is:
+The canonical schema source is `packages/zod-schemas/src/vault-frontmatter.ts` inside a **projects-baseline** checkout. That checkout is **optional and private** — see [`docs/baseline.md`](../../docs/baseline.md) — so the path is RESOLVED, never hardcoded. `resolveSchemaSourcePath()` resolves it in two tiers and returns `null` when nothing resolves. When the EXPLICIT tier is set it is used **alone** — probing past a wrong explicit value would silently read a different baseline than the one named:
 
-```
-~/Projects/projects-baseline/packages/zod-schemas/src/vault-frontmatter.ts
-```
+| Tier | Candidate | Set by |
+|---|---|---|
+| **explicit** (exclusive) | `<baseline-path>/packages/zod-schemas/src/vault-frontmatter.ts` | `SO_BASELINE_PATH` env, else `owner.yaml` `paths.baseline-path` (host-local, never committed) — via `resolveHostPath('baseline-path', …)` |
+| convention 1 | `<repoRoot>/../projects-baseline/packages/…` | sibling-checkout convention, the same one `scripts/sync-vault-schema.mjs` uses |
+| convention 2 | `~/Projects/projects-baseline/packages/…` | legacy default this module shipped with |
+
+Before this was resolved, convention 2 was the ONLY path and it was hardcoded: on a host whose checkout lives anywhere else, `readVaultSchema()` returned `null` and `generateFrontmatterSnippet()` then died with `Cannot destructure property 'typeEnum' of 'schema' as it is undefined`.
+
+`readVaultSchema()` reads the resolved file on every call unless the in-memory mtime cache is current. It returns `null` (no throw) when no candidate resolves or the file is unreadable.
 
-`readVaultSchema()` reads this file on every call unless the in-memory mtime cache is current. The function returns `null` (no throw) when the file is absent or unreadable.
+**Degraded mode.** With `null`, `generateFrontmatterSnippet()` does not throw: it falls back to an in-module enum/field set mirroring `skills/vault-sync/validator.mjs` (this repo's own in-tree copy of the schema, and what `vault-sync` actually validates against) and writes ONE stderr WARN per process. `computeSchemaHash()` returns `null` in that state — never the SHA-256 of the empty string, which would look like a real measurement and compare equal across every baseline-less host.
 
 The parsed output includes:
 

package/skills/npm-publish/SKILL.md

@@ -39,7 +39,7 @@ The script gates mechanics. These three are yours, and it will not make them for
 
 **2. What a leak means when one is found.** A hit from the leakage gate is not a pattern to silence. Decide which of two it is: a real leak (fix `package.json` `files`, re-pack, re-check) or genuine over-matching (fix `LEAKAGE_PATTERNS` in `scripts/release.mjs` **with a test**). There is no third option, and neither is "publish anyway and clean it up in the next version" — an npm publish is not revocable, and unpublishing burns the version number permanently. Operator handling detail: `docs/distribution/npm-publish-checklist.md` § 3.
 
-**3. When to abort instead of repair.** Abort — do not patch forward — when the failure is upstream of the target-confirmed npm receipt: a red preflight row, a lagging `github` mirror, CI not green on the exact commit, a dead token, or a publish that did not issue the target receipt. These are cheap to fix and re-run from the top. Repair-in-place is only appropriate *after* that receipt, where the version is already immutable: registry propagation, a missing GitHub release, or a lagging site deploy can be reconciled because npm already has the correct artifact. When `--publish` reports **Post-publish reconciliation required**, **do not rerun `--publish`**; repair the listed state directly. `commands/release.md` § Abort criteria is the operative list.
+**3. When to abort instead of repair.** Abort — do not patch forward — when the failure is upstream of the target-confirmed npm receipt: a red preflight row, a lagging `github` mirror, CI not green on the exact commit **on either platform** (`--check` carries both `ci-green-on-head` for GitLab and `ci-green-on-head-github` for the mirror, whose macOS matrix leg has no GitLab equivalent), a dead token, or a publish that did not issue the target receipt. These are cheap to fix and re-run from the top. Repair-in-place is only appropriate *after* that receipt, where the version is already immutable: registry propagation, a missing GitHub release, or a lagging site deploy can be reconciled because npm already has the correct artifact. When `--publish` reports **Post-publish reconciliation required**, **do not rerun `--publish`**; repair the listed state directly. `commands/release.md` § Abort criteria is the operative list.
 
 ## Failure-mode table
 

package/skills/reconcile/SKILL.md

@@ -156,9 +156,9 @@ himself.
 ### 2.3 Invoke `runReconcile`
 
 ```javascript
-import { runReconcile } from '$PLUGIN_ROOT/scripts/lib/reconcile/engine.mjs';
+import { runReconcileFromSkill } from '$PLUGIN_ROOT/scripts/lib/reconcile/engine.mjs';
 
-const { proposals, rejected, summary, error } = await runReconcile({
+const { proposals, rejected, summary, error } = await runReconcileFromSkill({
   repoRoot,             // absolute path from git rev-parse --show-toplevel
   ruleExpiryDays: RULE_EXPIRY_DAYS,   // empty → undefined → engine per-type TTL
   minRuleDays: MIN_RULE_DAYS,         // default 7 — floors a near-dead expires-at
@@ -166,6 +166,9 @@ const { proposals, rejected, summary, error } = await runReconcile({
   maxProposalsPerRun: MAX_PROPOSALS_PER_RUN, // default 10 — volume brake (issue #900 D)
   now: new Date(),
   dryRun: DRY_RUN,     // true → engine touches no disk (no idempotency sidecar write)
+  // trigger is pinned to 'skill' IN CODE by runReconcileFromSkill (#1201 Part A) —
+  // this prose block no longer sets it.
+  targets,             // from resolveEffectiveTargets above; recorded when non-empty, omitted otherwise
 });
 
 // The engine does NOT apply a confidence floor — it proposes every eligible
@@ -353,6 +356,39 @@ If `written === 0` and `approved.length === 0`:
 
 ---
 
+## Consolidating and Dropping Generated Rules (merge contract)
+
+`.claude/rules/` grows one file per approved learning, so it accumulates. This
+repo consolidated 43 generated files (112,443 B, 46.2 % frontmatter+provenance
+overhead) into 8 thematic files plus 10 drops on 2026-09-06. Both operations
+are safe ONLY under the contract below — the full authoring spec is
+[`docs/rule-authoring.md`](../../docs/rule-authoring.md) § "Consolidated rules:
+N provenance pairs in ONE file". The three facts that decide whether a
+consolidation survives the next `/reconcile`:
+
+- **A target file may carry N provenance bullet PAIRS.** Frontmatter
+  `learning-key:` is a scalar, so at most one marker fits there; the other N−1
+  live in the body as `` - learning-key: `…` `` + `` - learning-id: `…` ``
+  bullets, which `engine.mjs` reads via `BODY_LEARNING_KEY_RE` /
+  `BODY_LEARNING_ID_RE`. One pair per absorbed learning — a missing pair
+  regenerates that learning as a standalone file on the next run.
+- **A merged file's `expires-at` is the EARLIEST of its parts**, never the
+  latest: it must not outlive its shortest-lived content.
+- **A dropped learning must be STAMPED before deletion, or it regenerates.**
+  `rm .claude/rules/<slug>.md` alone leaves `isProcessed()` false and no
+  on-disk marker, so the engine re-proposes it. Stamp it terminal first with
+  `markCandidateProcessed({ learningKey, outcome: 'rejected', fallbackSlug,
+  repoRoot })` from `scripts/lib/reconcile/idempotency.mjs` — the ONLY
+  sanctioned writer of `.orchestrator/runtime/reconcile-candidates.jsonl`
+  (never append to that file by hand; the read-side shape guard drops foreign
+  records and `mergeCandidates` rewrites the store in full).
+
+**Verify a consolidation with a dry run**, not by eye: `alreadyMaterialized`
+must equal absorbed + dropped. If it equals only the absorbed count, the drops
+were not stamped and the next run will resurrect them. Do the whole operation
+while `reconcile.enabled: false` in Session Config, so nothing regenerates
+underneath you mid-edit.
+
 ## Critical Rules
 
 - **NEVER** call `writeApprovedRules` before the operator has confirmed via AUQ — this is the

package/skills/remote-offload/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: remote-offload
+user-invocable: false
+tags: [reference, remote, offload, wave-executor, resource-gate]
+model: haiku
+model-preference: sonnet
+model-preference-codex: gpt-5.4-mini
+model-preference-cursor: claude-sonnet-4-6
+description: Use when local resource pressure would shrink or coordinator-direct a wave, a wave plan carries heavy build/test/audit roles (test, ui, perf), or the operator says offload, remote host, or auslagern — reference for routing that wave role to a declared SSH-reachable host instead of reducing agent count
+---
+
+# Remote Offload — routing a wave role to a declared host instead of shrinking it
+
+Repo-side half of #1160: `remote-hosts:` declares hosts, `wave-resource-gate.mjs` places work on them, `remote-dispatch.mjs` runs it. The host-side `offload` CLI (a separate baseline repo owns its SSOT) is invoked as a subprocess; this skill covers what the repo itself knows about it.
+
+## Quick reference
+
+| Task | Command |
+|---|---|
+| Host readiness | `offload doctor -H <alias> --brief` |
+| Gate (typecheck/lint/test) | `offload gate <repo> -H <alias>` |
+| Run a command | `offload run <repo> -H <alias> -- <cmd...>` |
+| Read-only analysis | `offload claude <repo> -H <alias> --model <name> < prompt.txt` |
+| Implementation + patch | `offload claude <repo> -H <alias> --write --patch <path> < prompt.txt` |
+| Remove finished jobs | `offload clean -H <alias> --older-than <hours>` |
+
+Exit codes (`offload --help`, measured 2026-09-02): `0` ok · `1` usage/config · `2` host unreachable/not ready · `3` remote command failed · `4` sync failed · `5` timeout · `6` empty diff on a `--write` run · `7` account quota exhausted (429) · `8` write lock held. Same map as `OFFLOAD_EXIT_REASONS` in `scripts/lib/wave-executor/remote-dispatch.mjs`.
+
+## 1. Decision rule — offload vs reduce
+
+The gate decides, not the coordinator. `applyOffloadDecision()` in `scripts/lib/wave-resource-gate.mjs` only fires when the resource verdict is already `reduce` or `coordinator-direct`, and only AFTER the HR-004 heavy-repo cap — a capped wave that offloads still respects the cap. It never probes the network; the coordinator supplies a readiness WITNESS:
+
+- `opts.remoteReady` — `{ [alias]: boolean }`, built from the SessionStart banner line `Offload <alias>: ready=yes …`, or
+- `opts.probeFn` — an async `(alias) => boolean` fallback, consulted only for aliases `remoteReady` doesn't answer for (backed by `remoteDoctor()`, i.e. `offload doctor -H <alias> --brief` parsed by `parseDoctorLine()`).
+
+With neither supplied, no host counts as ready and the wave 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`: `impl-core`, `security-review`, `migration`, `release`, `secrets`) is never offloaded regardless of readiness.
+
+## 2. What is declared where
+
+`remote-hosts:` in Session Config (`docs/session-config-reference.md` § Remote Hosts) declares the hosts, in preference order — the gate takes the FIRST host whose `roles-allowed` accepts the wave role and is witnessed ready:
+
+```yaml
+remote-hosts:
+  - alias: <ssh-alias>                 # required, SAFE slug; reaches argv as `-H <alias>`
+    roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
+    repo-path: ~/path/on/host          # optional; SAFE path; default null
+    claude-path: ~/.local/bin/claude   # optional; SAFE path; default null
+```
+
+Two enums meet here and must not be conflated: `roles-allowed` holds `agent-mapping` roles (`test`/`ui`/`perf`), not wave roles (`Impl-Core`/`Quality`/…). The translation table is `OFFLOADABLE_WAVE_ROLES` in `wave-resource-gate.mjs` (`quality`→`test`, `test`→`test`, `ui`→`ui`, `perf`→`perf`; a wave role absent from that map stays local by default).
+
+An `agent-mapping` entry of the form `<role>: ssh:<alias>` routes that wave role to Claude running ON the declared host instead of shrinking the wave; the alias must already exist under `remote-hosts`, or the config parse throws.
+
+## 3. Three channels of work
+
+| Channel | Command | Verdict rule |
+|---|---|---|
+| Gate / arbitrary command | `offload gate` / `offload run` | Exit code decides — use the table above, never the prose in the run's own output |
+| Implementation, patch back | `offload claude --write --patch <file>` via `dispatchRemote()` | Empty patch (exit `6`) is a FAILURE regardless of what the run reports; the coordinator READS the patch, then applies it with its own `git apply` — the remote job never touches the repo the coordinator commits from |
+| Read-only analysis | `offload claude` (no `--write`) | No patch is produced; treat the transcript as advisory input, same skepticism as any reviewer output (`receiving-review.md`) |
+
+`dispatchRemote()` (`scripts/lib/wave-executor/remote-dispatch.mjs`) is the wave-executor caller for the second and third channels; it emits `orchestrator.remote_dispatch.completed` once per call (`docs/events-schema.md`) — the only ledger record a remote dispatch produces, since a Bash-spawned `offload` child fires no `SubagentStop` hook. Payload: `host`, `role`, `run_id`, `ok`, `exit_code`, `duration_ms`, `patch_files`, `patch_bytes`, `reason` (present on every refusal and every failure class — absence means success). Deliberately excluded from the payload: prompt text, patch body, `patch_path`.
+
+## 4. Rules
+
+- **Supervised, not blind.** Read the gate log or the patch before treating it as a result — completed and correct are not the same claim.
+- **Prompt travels on stdin, never argv** (`offload --help`: "prompts travel by file (mode 600), never argv"; argv is visible to every process on the host).
+- **The patch is READ, then applied by the coordinator** — never inside the offloaded job.
+- **`never_foreign` roles are never offloaded** — checked first in `dispatchRemote()`, before any spawn or side effect.
+- **One `--job` per concurrent run.** A job holds ONE set of run artefacts; two parallel runs sharing a job collided until per-run ids were introduced.
+- **Rate-limit (exit `7`) carries the reset time in the message** — do not retry blind.
+- **Secrets never in output** (SEC-008) — `offload` does not print credentials, and the module deliberately excludes prompt text and patch body from telemetry.
+- **Never "clean up" another checkout on the host.** `offload clean` only removes the offload tool's OWN finished job worktrees, never a host's other active checkouts.
+
+## 5. Host readiness checklist
+
+- SSH alias configured with key auth (no password/interactive prompt on connect).
+- `tmux` available on the host (for an interactive `offload session`).
+- Claude authenticated ON the host — never copy OAuth credentials between machines (refresh-token rotation invalidates the source copy); log in fresh with `/login` there instead.
+- Repo cloned on the host with headless git credentials configured (no interactive auth prompt on push/pull).
+- Node version matching this repo's `.nvmrc`.
+- Toolchain parity with the local checkout (same package manager, same lockfile).
+
+## 6. Pitfalls measured in this repo
+
+- **The pre-push quality gate used to fire on the sync push.** `.husky/pre-push` (#C10) detects a SCRATCH push — an unconfigured remote URL, e.g. the offload tool's own SSH sync target — and skips the gate for it; publish remotes (`origin`, `github`) stay gated regardless. The offload tool has since been fixed upstream to push with `--no-verify` itself, so this repo-side detection is defense-in-depth, not the primary fix.
+- **The host installer must follow this repo's committed lockfile.** `package-lock.json` is tracked here (npm-canonical — `.claude/rules/development.md` § Package Management); install with `npm ci`, never a different package manager's install command, or the host checkout's `node_modules` layout diverges from CI's.
+- **A linked worktree makes `.git` a file, not a directory.** 13 tracked files used to be flagged as "not in repository" in an unmodified worktree at the same layout, because the file form of `.git` was read as an untracked candidate rather than the repository marker — wave 3 fixed `scripts/lib/validate/check-untracked-test-deps.mjs` to treat a `.git` FILE as the repository marker in a linked worktree; the remote gate then ran 15,829/0.
+- **Keychain-route auth shares the host account's usage window with that account's other interactive sessions**, not a dedicated quota — a token-slot profile (`--via slot`) avoids the sharing where a fixed quota matters.