omnius 1.0.591 → 1.0.592

package/docs/longhaul-35b-workorders.md

@@ -0,0 +1,496 @@
+# Work Orders — Long-Haul Implementation on a 35B-Class Model
+
+**Origin:** Root-cause review of the `myactuator` ESP32/PlatformIO session (35B `ornith-vision`)
+plus a 2026-literature sweep of surprising remedies. See companion analysis in
+`docs/context-management-medium-models-proposal.md` and
+`docs/duplicate-calls-root-cause-analysis.md`.
+
+## Implementation status (Ralph loop + live wiring, 2026-07-04)
+
+All 8 core modules implemented, unit-tested, and wired into `agenticRunner.ts` via a single
+fault-tolerant integration bundle (`packages/orchestrator/src/longhaul-integration.ts`,
+`LongHaulComponents`). Full monorepo `pnpm -r build` exits 0 (cli, apps/api, apps/worker included).
+
+| WO | Module | Tests | Live in `agenticRunner` |
+|----|--------|-------|--------------------------|
+| WO-1 | `execution/src/boundary-verifier.ts` | 12 ✅ | **glue live**; compiler-runner dormant (needs repo profile — fires only when a runner is supplied) |
+| WO-2 | `orchestrator/src/coherence-gate.ts` | 8 ✅ | **LIVE** — scans full-file writes to boundary files; regenerate guidance via `runtimeSystemGuidance` |
+| WO-3 | `orchestrator/src/convergence-breaker.ts` | 9 ✅ | **LIVE** — wired into `focusSupervisor`; cross-session ledger at `.omnius/convergence-ledger.json` (gated on `disablePersistentMemory`) |
+| WO-4 | `memory/src/context-folding.ts` | 5 ✅ | bundle instantiated; active-window rewrite dormant (needs context-frame-builder integration) |
+| WO-5 | `memory/src/compaction-policy.ts` | 9 ✅ | decision/validate/SNR available via bundle; SNR already computed in the context dump; compaction firing unchanged (advisory) |
+| WO-6 | `orchestrator/src/spec-gate.ts` | 8 ✅ | functions live; dormant until a planner supplies a `LockedContract` |
+| WO-7 | `execution/src/harness-plan.ts` | 8 ✅ | plan+guard live; execution gated on the sandbox + security review |
+| WO-8 | `execution/src/adaptive-edit-strategy.ts` | 7 ✅ | **LIVE** — tracks edit failures per file at the tool seam; rewrite guidance via `runtimeSystemGuidance` |
+| WO-9 | `orchestrator/src/focusSupervisor.ts` (family-key normalization) | 17 ✅ | **LIVE** — generic action-identity canonicalizer collapses command-string/path/error variants so WO-3 actually escalates; `resolve()` on success. Found + fixed from live monitoring. |
+
+**Cross-cutting genericity invariant:** every triage component is **toolchain-agnostic** and validated
+across ecosystems — never tuned to a specific project or command (that would be reward-hacking the
+demo, not hardening the harness). WO-1 parses gcc/clang **and** tsc; WO-2 scans C/C++ **and** TS;
+WO-8 keys on file path (tool-neutral); WO-9's normalizer keys on shell *grammar* only, proven on
+npm/cargo/pytest/make/go with pio as just one row.
+
+**74 new unit tests, all green** (66 module + 8 integration-bundle). Wiring is additive and
+try/catch-guarded so a long-haul component can never throw into the agentic loop; when
+`disablePersistentMemory` is set, the convergence ledger stays in-memory (test-isolated).
+
+**LIVE now** (behavior changes in the loop): WO-3 (convergence escalation past `forced_replan`),
+WO-8 (edit→rewrite guidance), WO-2 (coherence→regenerate guidance on full-file writes).
+**Dormant-by-necessity** (infra not present): WO-1 compiler runner, WO-4 active-window rewrite,
+WO-6 locked contract, WO-7 execution. These are instantiated and one dependency away from firing;
+each is documented above. Runtime behavior (as opposed to type/unit correctness) needs live-model
+validation — the loop cannot be exercised end-to-end without a backend.
+
+## The failure signature these work orders attack
+
+Observed in `~/Documents/Projects/myactuator/.omnius` telemetry:
+
+| Signal | Value | Contract that fixes it |
+|---|---|---|
+| Successful builds, ever | **0** (9 FAILED markers) | WO-1, WO-2 |
+| Duplicate-call dedup events | **15,342** | WO-3 |
+| Lifetime tool failures | **15,505** | WO-3, WO-8 |
+| `forced_replan` never escalating past itself | ∞ loop | WO-3 |
+| Context frame @ 82k tokens, `signalToNoiseRatio: null` | bloat | WO-4, WO-5 |
+| `file_edit` hash-mismatch retried 8× identically | thrash | WO-8 |
+| Cross-file type drift (3× `MotorConfig`) | incoherent base | WO-1, WO-2, WO-6 |
+| `z212/MCP2515` hallucinated package | ungrounded | WO-1, WO-7 |
+
+The convergence-cliff literature (Yang et al., EMNLP 2025: rounds 1–2 capture ~75% of
+reachable improvement; 96.5% of refinement sequences resolve in ≤3 iterations; skill loops
+plateau by round 5) says a trajectory that has not converged in ~3 rounds essentially never
+will — it needs a *different* trajectory, not more iterations. Every work order below is built
+so the harness can detect "not converging" and switch strategy instead of brute-forcing.
+
+---
+
+## Verified integration map (anchors)
+
+| Package | File | Role |
+|---|---|---|
+| orchestrator | `src/agenticRunner.ts` (33k LOC — **do not enlarge**; wire, don't grow) | main turn loop; calls supervisor, ledger, compaction, context dump |
+| orchestrator | `src/focusSupervisor.ts` (1212 LOC) | failure-family counting → `forced_replan` directives |
+| orchestrator | `src/dedup-gate.ts` | cross-turn duplicate-call gate |
+| orchestrator | `src/completionLedger.ts`, `src/completion-evidence-gate.ts` | completion evidence |
+| orchestrator | `src/resolution-memory.ts` | cross-session failure→fix learning |
+| orchestrator | `src/contextWindowDump.ts` | telemetry frame dumps |
+| memory | `src/compaction.ts` (155 LOC), `src/context-window.ts` (336 LOC) | context management |
+| execution | `src/typecheckRunner.ts`, `src/buildRunner.ts`, `src/linterRunner.ts` | verifier primitives (already exist!) |
+| execution | `src/tool-executor.ts`, `src/tools/file-edit.ts` (671 LOC), `src/tools/batch-edit.ts` | tool dispatch + edits |
+| execution | `src/model-broker.ts` | model tier selection |
+| backend-vllm | `src/routing.ts` | request→backend routing |
+
+Persistence convention: session-scoped JSON under the project `.omnius/` dir, matching the
+existing `error-patterns.json` / `resolution-memory.json` / handoffs pattern.
+
+---
+
+## WO-1 — In-Loop Structural Verifier (verify *during* generation, not after)
+
+**Insight:** Decoding-Time Verification (arXiv 2605.17626) — interleave the compiler/type-checker
+at structural boundaries; "early errors corrupt the autoregressive context." Qwen3-4B
+72.3%→82.0% (C→Rust) with in-loop verification.
+
+**Root-cause tie:** `pal.cpp` was written whole against an imagined `MotorConfig`/`Command`
+shape; the mismatch was only discovered after 300+ lines, then patched forever.
+
+**Anchors:** new `packages/execution/src/boundary-verifier.ts`; reuses `typecheckRunner.ts`,
+`buildRunner.ts`, `linterRunner.ts`. Integration point: `tool-executor.ts` post-write hook +
+`agenticRunner.ts` turn epilogue.
+
+**Design:** after any file-mutating tool that touches a "structural boundary" (a header/interface
+file, a new function/struct/class), synchronously run the cheapest applicable verifier for that
+language (tsc/clang/pio check) scoped to the changed unit. Emit a `BoundaryVerdict {ok, diagnostics[],
+scope}` that the turn epilogue attaches to the frame. On failure, the next turn is gated with the
+exact diagnostics as authoritative evidence and forbidden from proceeding to unrelated files.
+
+**Acceptance (measurable):**
+- After editing a header, a signature-mismatch is reported within the same turn (not N turns later).
+- `boundary-verifier` unit tests: given a fixture with a header/impl drift, verdict.ok === false and
+  diagnostics name the drifted symbol.
+- Regression harness: replaying the myactuator `pal.cpp` edit produces a boundary block before the
+  next unrelated file edit.
+
+**Telemetry:** `boundaryVerifier: { runs, blocked, avgMs }` in the context dump.
+
+**Depends on:** none. **Status:** SPEC (verifier primitives already exist → medium effort).
+
+---
+
+## WO-2 — Contract-Coherence Regime Switch (patch ⇄ regenerate)
+
+**Insight:** Patch repair beats regeneration *when invariants hold*; below a coherence floor you
+must regenerate the type layer wholesale (Solvita 2605.15301; Beyond-Accuracy 2511.11012). myactuator
+was below the floor (3× `MotorConfig`) so every patch was whack-a-mole.
+
+**Anchors:** new `packages/orchestrator/src/coherence-gate.ts`. Consumes WO-1 verifier diagnostics +
+a lightweight structural scan (duplicate type/symbol defs, header/impl signature-match ratio).
+Integration point: `agenticRunner.ts` before choosing edit strategy; emits a new
+`FocusRequiredNextAction: "regenerate_from_spec"` (enum widened here).
+
+**Design:** compute `coherenceScore ∈ [0,1]` from: (a) duplicate top-level symbol definitions,
+(b) fraction of impl methods whose signature matches a declaration, (c) unresolved-symbol density.
+Below `regenThreshold` (default 0.6) the gate forces a **full-file / whole-module regeneration from
+the locked contract (WO-6)** and forbids incremental `file_edit` on the incoherent unit until it
+compiles once. Above threshold, patch mode as today.
+
+**Acceptance:** unit test on a 3×-duplicate-typedef fixture → score < 0.6 → verdict `regenerate`;
+a coherent fixture → `patch`. Integration: myactuator `types.h` replay → `regenerate`.
+
+**Depends on:** WO-1 (diagnostics), WO-6 (locked contract as regeneration source). **Status:** SPEC.
+
+---
+
+## WO-3 — Convergence Circuit-Breaker (the hard cliff) — **IMPLEMENTED THIS PASS**
+
+**Insight:** Rounds 1–2 = ~75% of reachable improvement; ≤3 iterations resolves 96.5%; plateau by
+round 5 (Yang et al. EMNLP 2025; EvoSkills 2604.01687; Practical Limits 2605.01471). More iterations
+on the same trajectory ≈ zero marginal value.
+
+**Root-cause tie:** `focusSupervisor` escalates to `forced_replan` at family-count ≥ 2 but **never
+escalates further**, and its `failureFamilies` map is **session-local** — a resumed session re-earns
+the count from zero. The myactuator `pio run` family repeated across 5 sessions with no global
+"abandon this trajectory."
+
+**Anchors:** new `packages/orchestrator/src/convergence-breaker.ts` (+ test); minimal additive hook in
+`focusSupervisor.ts observeToolResult`; exported from `src/index.ts`. Cross-session store:
+`.omnius/convergence-ledger.json` (matches `error-patterns.json` convention).
+
+**Design:** pure `ConvergenceBreaker` observes the same failure-family key focusSupervisor already
+computes. `totalRounds = sessionCount + priorSessionCarry(family)`. A *productive mutation* since the
+last failure decays the carry (progress resets the cliff). Tiers by `totalRounds`:
+`healthy < 2 ≤ converging_warn < 3 ≤ stalled < 5 ≤ abandon`. `stalled` → directive to **stop
+patching, regenerate the incoherent layer** (`run_verification`/replan); `abandon` → escalate
+focusSupervisor to `terminal_incomplete` + `report_incomplete` with a regeneration instruction,
+instead of emitting `forced_replan` forever. Cross-session carry is loaded on construction and
+persisted on each trip so a resumed session trips immediately.
+
+**Acceptance (measurable):**
+- Same family observed 5× (across a simulated session boundary) → verdict `abandon`, tripped === true.
+- A productive mutation between failures decays the count (no false abandon).
+- focusSupervisor with a breaker injected escalates to `terminal_incomplete` on abandon; **without** a
+  breaker, behavior is byte-identical to today (existing `focusSupervisor.test.ts` stays green).
+- Cross-session: store round-trips the carry; a fresh breaker seeded from the store trips on round 1.
+
+**Telemetry:** `convergence: { family, totalRounds, tier }` in the context dump + a
+`.omnius/convergence-ledger.json` audit trail.
+
+**Depends on:** none. **Status:** ✅ IMPLEMENTED (module + unit tests + additive focusSupervisor hook).
+
+---
+
+## WO-4 — Context-Folding (10× smaller active context)
+
+**Insight:** Context-Folding (arXiv 2510.11967) — branch into a subtask sub-trajectory, then *fold*
+it to a one-line outcome; active context up to 10× smaller, beats summarization.
+
+**Root-cause tie:** a single 380 KB myactuator frame contained "duplicate" ×276, "error" ×423 —
+finished-subtask noise crowding out the live type contract.
+
+**Anchors:** new `packages/memory/src/context-folding.ts`; integrates with `compaction.ts` +
+`context-window.ts`; frame assembly in `agenticRunner.ts` (`upsertContextFrame`).
+
+**Design:** a `FoldableSegment` boundary opened when the agent starts a named subtask (e.g. "make
+cem_driver.cpp compile") and closed on its boundary-verifier success (WO-1). On close, replace the
+segment's turns with `folded: { subtask, outcome, artifacts[], verifier: pass }`. Folded segments are
+excluded from the active window but retained on disk for audit and re-expansion.
+
+**Acceptance:** a run that folds 3 completed subtasks shows active-window tokens drop ≥5× vs unfolded;
+folded outcomes remain queryable. **Depends on:** WO-1 (fold trigger). **Status:** SPEC.
+
+---
+
+## WO-5 — Decision-Based Compaction + Validation
+
+**Insight:** Self-Compacting agents (arXiv 2606.23525) — model fires compaction by rubric (fire when
+subtask resolved/converging, **hold when mid-derivation/stuck**), +18.1 pts at 30–70% lower cost.
+Slipstream (2605.08580) — trajectory-grounded validation that compaction didn't drop architectural
+decisions.
+
+**Root-cause tie:** myactuator compaction fired on a token threshold and `signalToNoiseRatio` was
+`null` (never computed); the locked type contract was at risk each compaction.
+
+**Anchors:** extend `packages/memory/src/compaction.ts` with a `shouldCompact(rubric)` decision fn;
+new `packages/memory/src/compaction-validator.ts` (Slipstream check); pin the locked contract into the
+system-prompt region so it survives every compaction. Integration: `agenticRunner.ts` compaction gate
+(currently threshold-only at `compactionThreshold`/`compactionPercent`).
+
+**Design:** replace pure-threshold firing with `threshold AND rubric`: hold if a boundary-verifier is
+mid-run or the last N turns are a single unresolved derivation; fire when the last subtask verified or
+the trajectory is converging. Post-compaction, the validator asserts every pinned invariant (locked
+contract symbols, open bugs, next-action) still appears; if not, it rolls back and keeps the pre-compaction frame.
+
+**Acceptance:** compute and emit `signalToNoiseRatio` (no longer null); validator blocks a compaction
+that drops a pinned symbol in a fixture. **Depends on:** WO-6 (what to pin). **Status:** SPEC.
+
+---
+
+## WO-6 — Strong-Planner / Weak-Executor + Spec-as-Executable-Gate
+
+**Insight:** Scaffolding out-levers model size ("Sonnet+plan > Opus+vibe"); planner-executor with a
+strong planner and cheap executor + re-plan on failure; SDD specs *execute as validation gates*.
+
+**Root-cause tie:** the 35B decided the type architecture across 40 files; the excellent
+`contracts/` docs were never enforced as gates → definitions diverged file-by-file.
+
+**Anchors:** new `packages/orchestrator/src/plan-executor.ts` + `src/spec-gate.ts`; model tiering via
+`execution/src/model-broker.ts` + `backend-vllm/src/routing.ts`. Integration: `agenticRunner.ts` run
+setup (a plan phase precedes the execute loop).
+
+**Design:** a one-time plan phase (larger tier via broker, or the current session) emits a locked
+**type/interface contract** (structs, signatures, file manifest) derived from the project's spec docs.
+The executor loop (35B) fills one manifest unit at a time; every unit must pass its `spec-gate`
+(declared symbols present, signatures match the contract) — a hard gate, not advice. Re-plan triggers
+on WO-3 `stalled`.
+
+**Acceptance:** spec-gate rejects a unit whose emitted `MotorConfig` diverges from the contract;
+the locked contract is the single source WO-2 regenerates from. **Depends on:** WO-2, WO-3.
+**Status:** SPEC.
+
+---
+
+## WO-7 — Code-as-Harness (env manipulation via code, fewer brittle tool-args)
+
+**Insight:** Code-as-Agent-Harness (arXiv 2605.18747) — the agent manipulates its environment by
+writing code rather than emitting brittle structured tool calls.
+
+**Root-cause tie:** a large share of the 15,505 failures were malformed tool arguments
+(obsolete metadata envelopes, a `ce_m_driver.h` typo, hash mismatches).
+
+**Anchors:** new `packages/execution/src/tools/harness-exec.ts` (sandboxed, allow-listed); reuses the
+existing `code-sandbox.ts` tool. Integration: register in the tool registry; route multi-step file/env
+ops through a single code cell.
+
+**Design:** expose a constrained code channel (fs + shell within the project root, no network) so a
+batch of edits/reads/moves is one verified code cell with real error messages, instead of a dozen
+brittle `file_edit` calls each subject to the hash/`old_string` contract.
+
+**Acceptance:** a 5-file rename that today needs 5 hash-guarded edits completes as one code cell with a
+single pass/fail. **Depends on:** existing `code-sandbox.ts`. **Status:** SPEC (security review required
+per `browser-control-safety`/`token-security` conventions).
+
+---
+
+## WO-8 — Adaptive Edit Strategy (HarnessBridge-lite: auto-switch edit→rewrite)
+
+**Insight:** HarnessBridge (arXiv 2606.12882) — a learnable controller for the harness↔model
+interface. The harness should *adapt* rather than let a weak model bang on a brittle primitive.
+
+**Root-cause tie:** `file_edit expected_hash=…` rejected and retried **8× identically**; 965
+`file_edit:not_found`.
+
+**Anchors:** new `packages/execution/src/adaptive-edit-strategy.ts` (+ test); minimal hook in
+`tool-executor.ts` / `tools/file-edit.ts`.
+
+**Design:** per-file counter of consecutive `file_edit` failures (hash-mismatch / old_string-not-found
+/ not_found). After `switchThreshold` (default 2) failures on a file, the strategy recommends
+switching that file to a **full-file rewrite** (`file_write`) seeded with the current file contents,
+and the executor surfaces that as the required recovery. Counter resets on a successful mutation.
+
+**Acceptance:** 2 hash-mismatch failures on one file → strategy returns `mode: "rewrite"` with the
+current contents as the base; a success resets the counter; unit tests cover mismatch, not-found, and
+reset. **Depends on:** none. **Status:** SPEC (small, self-contained — next after WO-3).
+
+---
+
+## WO-9 — Convergence Family Normalization & Correctness (from live monitoring)
+
+**Origin:** Live 35B run on `myactuator` (2026-07-04, turn 14–16). WO-3 was confirmed firing —
+`.omnius/convergence-ledger.json` was created and tracking the `pio run` failure — **but the breaker
+never escalated** because the model re-ran the same logical action with trivially different command
+strings, so the ledger fragmented into 3 families each stuck at `rounds=1`:
+
+```
+rounds=1  shell:cd firmware/esp32 && pio run 2>&1 | tail -100 :tool_failed
+rounds=1  shell:cd firmware/esp32 && pio run 2>&1              :tool_failed
+rounds=1  shell:cd /home/roko/.../firmware/esp32 && pio run    :tool_failed
+```
+
+None reaches `stalled`(3)/`abandon`(5). The 35B slips the guard by varying the command — the same
+evasion behind the original 15k-thrash. (Positive: context stayed ~1.2–1.4k tokens, no bloat.)
+
+### Root cause (two fragmentation axes) — anchors
+
+1. **Command-string axis.** `actionFamily(toolName, args)` in
+   `packages/orchestrator/src/focusSupervisor.ts` keys a shell family on the raw command:
+   ```ts
+   if (toolName === "shell") {
+     const command = args?.["command"] ?? args?.["cmd"] ?? "";
+     return `${toolName}:${compactTarget(String(command ?? "") || "no-command", 120)}`;
+   }
+   ```
+   `compactTarget()` only collapses whitespace + truncates — no semantic normalization. So
+   `pio run`, `pio run 2>&1`, and `pio run | tail -100` are three families.
+
+2. **Error-class axis.** `failureFamilyKey()` = `` `${actionFamily(...)}:${errorClass}` ``. The
+   breaker is fed this (`family`, with errorClass) at `focusSupervisor.ts` ~line 662. A command that
+   fails with a different `errorClass` each attempt fragments a second way. Convergence should track
+   *"stuck repeating this action,"* independent of which error each attempt throws.
+
+3. **No `resolve()` on success.** The breaker never clears a family when the underlying work
+   succeeds (the `resolve()` API exists in `convergence-breaker.ts` but is unwired). A family that
+   accumulates rounds then finally passes could still carry stale rounds and falsely trip later.
+
+### Genericity & anti-reward-hacking guardrails (PRIMARY constraint)
+
+The `pio run` case is the *symptom that surfaced the gap*, **not** the thing to fix. The normalizer
+MUST be a generic **action-identity canonicalizer** that reduces any semantically-equivalent shell
+invocation to the same key across **any** toolchain — never a PlatformIO/`pio`-aware special case.
+Tuning to the demo command would be reward-hacking (making this run look good instead of making the
+harness robust) and is explicitly forbidden.
+
+Rules:
+
+1. **No tool-name allow-lists / no project-specific patterns.** The normalizer never matches `pio`,
+   `platformio`, `firmware/esp32`, or any literal from this repo. It operates only on *shell
+   grammar* (pipes, redirections, path syntax, whitespace) — decoration that is semantically neutral
+   for *every* command.
+2. **Strip only meaning-preserving decoration.** Remove trailing display filters (`| tail`, `| head`,
+   `| less`, `| cat`, `| grep` used for viewing), stream redirections (`2>&1`, `>/dev/null`,
+   `2>/dev/null`), and normalize absolute↔relative path *form* (via the run's cwd, not a hard-coded
+   root). Never remove flags/arguments that change *what the command does*.
+3. **Conservative — prefer false-split over false-merge.** Collapsing two genuinely different
+   commands into one family causes *premature abandonment* of distinct work — worse than leaving
+   them split. When a token's semantic effect is uncertain, keep it. `npm test` and
+   `npm test -- --grep auth` must stay **distinct**; `cargo build -e x` and `cargo build -e y` must
+   stay **distinct**.
+4. **Validated across ecosystems, not one.** Correctness is demonstrated on npm, cargo, pytest, make,
+   go, and generic shell — with `pio` as merely one of several rows — so the rules cannot silently
+   overfit. The same discipline applies to the other triage components (WO-1 parses gcc/clang **and**
+   tsc; WO-2 scans C/C++ **and** TS; WO-8 keys on file path, tool-agnostic).
+
+### Design
+
+- **9a — Generic action-identity canonicalizer** for family keying. New
+  `normalizeShellForFamily(cmd, cwd?)`: collapse whitespace (reuse the pattern from
+  `packages/execution/src/tools/shell.ts:899 normalizeCommand`), strip trailing *display* pipelines
+  and stream redirections, and canonicalize path *form* against the run's cwd (relative↔absolute) —
+  all grammar-level, tool-agnostic. Semantically-meaningful arguments are preserved verbatim.
+  Examples (each collapses to one family; none is pio-specific):
+  `npm test 2>&1 | tail -50` ≡ `npm test`; `cargo build 2>&1` ≡ `cargo build`;
+  `cd <abs>/svc && pytest -q | tee log` ≡ `cd svc && pytest -q | tee log` (only the `cd` path form
+  is normalized; `-q` and the writing `tee` are preserved). Counter-examples that must **stay
+  distinct:** `npm test` vs `npm run test:e2e`; `make` vs `make clean`; `go build ./a` vs
+  `go build ./b`.
+- **9b — Coarser convergence key.** Feed the breaker the normalized **action** family
+  (`actionFamily(...)` alone, no `:errorClass`) rather than `failureFamilyKey`. Keeps the focus
+  `failureFamilies` map as-is (error-specific); only the convergence trajectory is coarsened, so
+  error-message churn on the same action doesn't fragment it either.
+- **9c — Wire `resolve()` on verified success.** When a verification-like shell command succeeds,
+  clear that action family's carry (generic: any command that previously failed and now succeeds).
+
+### Full integration modification points (exact)
+
+| # | File · anchor | Change |
+|---|---------------|--------|
+| 1 | `orchestrator/src/focusSupervisor.ts` · `actionFamily()` shell branch | wrap `command` in `normalizeShellForFamily(...)` before `compactTarget` |
+| 2 | `orchestrator/src/focusSupervisor.ts` · new top-level helper near `actionFamily`/`compactTarget` | add `normalizeShellForFamily(cmd: string): string` (9a) |
+| 3 | `orchestrator/src/focusSupervisor.ts` · breaker wiring (~L662) | change `family` → `convergenceFamily` where `const convergenceFamily = actionFamily(input.toolName, input.args)` (9b) |
+| 4 | `orchestrator/src/focusSupervisor.ts` · `observeToolResult` shell-success branch (`if (input.toolName === "shell" && input.success)`) | add `this.convergenceBreaker?.resolve(actionFamily(input.toolName, input.args))` (9c) |
+| 5 | `orchestrator/src/convergence-breaker.ts` | no change required (keys on `obs.family`); optionally accept a `normalizeFamily` fn for defense-in-depth |
+| 6 | `orchestrator/tests/focusSupervisor.test.ts:1104` | update the `forbiddenActionFamilies` expected string if the normalized shell family differs (**test modification point**) |
+| 7 | `orchestrator/tests/*` (new) | add: `normalizeShellForFamily` collapses the 3 pio variants; breaker escalates `stalled`→`abandon` after 3/5 *varied* pio-run failures; `resolve()` clears on success |
+| 8 | `orchestrator/src/longhaul-integration.test.ts` (new case) | end-to-end: 3 varied `pio run` failures through a `FocusSupervisor` → terminal escalation |
+
+### Acceptance (measurable — proven generic, parameterized over ecosystems)
+
+- **Genericity table** (drives a parameterized test — pio is one row of many): for each
+  `{ base, variants[] }` below, all variants collapse to one family:
+  | base | variants that must MERGE |
+  |------|--------------------------|
+  | `npm test` | `npm test 2>&1`, `npm test \| tail -50` |
+  | `cargo build` | `cargo build 2>&1 \| head`, `cargo build 2>/dev/null` |
+  | `cd firmware && pio run` (path FORM only) | `cd <abs>/firmware && pio run 2>&1`, `cd <abs>/firmware && pio run \| tail` |
+  | `pytest -q` | `pytest -q 2>&1`, `pytest -q \| tail -80` |
+  | `make` | `make 2>/dev/null`, `cd <abs> && make` |
+  | `go test ./...` | `go test ./... 2>&1 \| tail` |
+  | `pio run` | `pio run 2>&1`, `cd <abs>/firmware/esp32 && pio run \| tail -100` |
+- **Non-merge table** (must stay DISTINCT — proves conservatism): `npm test` ≠ `npm run test:e2e`;
+  `make` ≠ `make clean`; `go build ./a` ≠ `go build ./b`; `cargo build -e x` ≠ `cargo build -e y`.
+- For any base, three *varied* failures → one family, `rounds` 3 → `stalled`; a 5th → `abandon` →
+  `focusSupervisor` state `terminal_incomplete` (validated with a non-pio base, e.g. `npm test`).
+- A successful verification command clears the family (`resolve()`), so a later unrelated failure
+  starts at round 1.
+- `focusSupervisor.test.ts` updated and green; full orchestrator suite has no new regressions;
+  `pnpm -r build` exits 0.
+
+### Peripheral gaps folded in / noted
+
+- **WO-8 edit families** key on file path (`adaptive-edit-strategy.ts`) — stable, low fragmentation
+  risk; verify `batch_edit`/`file_patch` path extraction is consistent (`realMutationPaths[0]`).
+- **WO-1 boundary compiler runner** remains dormant (needs a repo profile / runner) — separate,
+  already tracked in the status table.
+
+**Status:** ✅ IMPLEMENTED + LIVE-WIRED. `normalizeShellForFamily()` +
+`actionFamily(…, cwd)` + coarse convergence key (`convergenceFamilyCounts`) + `resolve()` on shell
+success, all in `focusSupervisor.ts`; cwd threaded from `agenticRunner`. 17 new WO-9 tests
+(cross-ecosystem merge/non-merge, path-form, escalation on varied commands, resolve) + updated the
+one focusSupervisor test that encoded the old pager-evasion behavior. Found during live monitoring;
+fixes the 5-families-at-rounds-1 fragmentation.
+
+## Root refinement — progress = verification delta, not edit activity (from live monitoring + literature)
+
+**Observed live (post-WO-9):** the breaker never escalated the myactuator *edit* loop — the model
+edited ~1000× without ever compiling, and WO-3/WO-9's progress-decay treated every mutation as
+"advancing," so a *futile* edit loop looked like progress forever.
+
+**Literature confirms this is the crux.** *Coherence Collapse* (arXiv 2603.24631): agents reach/near
+correct code then degrade it; the fix is quality-tracked verification, not edit counting. RLCSF /
+Lanser-CLI (arXiv 2510.22907) and PyTy: "coding agents fail when text-level guesses outrun program
+facts" — progress must be measured by the **compiler/verification signal**, not by edits.
+
+**Root fix (implemented):** the convergence breaker's decay is now driven by a **verification signal
+delta** — `failureSignal` (a generic error count) must *drop* across repetitions to count as progress;
+editing that doesn't reduce errors no longer decays the cliff, so a futile loop escalates to
+`stalled`/`abandon` → regenerate. Crucially this needs **no separate compiler run** — the signal is
+extracted from the failing action's *own output* (`failureProgressSignal()` in `focusSupervisor.ts`),
+which the model already produces when it runs the build/test. Generic: counts `error:`/`error TS`/
+`error[`/`N failed`/`FAIL` across gcc/clang/tsc/cargo/pytest/go with no tool literals; falls back to
+the mutation heuristic when no signal is present (legacy behavior preserved).
+
+- `convergence-breaker.ts`: `ConvergenceObservation.failureSignal`; decay iff signal dropped; `resolve()` clears signal history.
+- `focusSupervisor.ts`: `failureProgressSignal(output)` extractor; passed as `failureSignal` in the breaker call.
+- 11 tests (cross-toolchain extraction, stagnant→escalate, dropping→hold, signal-over-mutation authority, worsening→escalate fastest, focus-integration futile-vs-progressing build loops).
+
+This is the highest-ROI change for the *edit-without-convergence* frontier: WO-1 (a dedicated
+compiler run) is now optional for this signal, though still valuable for injecting the *named*
+diagnostic into the next edit (PyTy pattern) and for WO-2's coherence regenerate decision.
+
+## Mainline wiring — final status (after investigating the existing runner infra)
+
+Investigating the mainline (research-before-decision) changed the answer for two WOs: their
+intent is **already implemented** by existing omnius machinery, so wiring my modules would be
+redundant duplication (and risk the tuned compaction path). Honest outcome:
+
+| WO | Status | Evidence |
+|----|--------|----------|
+| WO-1 | ✅ **LIVE-WIRED** | `diagnosticGuidance()` at the tool seam — named drifted symbols from the model's own compiler output (PyTy). New capability. |
+| WO-2 | ✅ LIVE | coherence scan → regenerate guidance on full-file writes |
+| WO-3 | ✅ LIVE | convergence breaker → focusSupervisor (validated live: republish escalated to `stalled`) |
+| WO-6 | ✅ **LIVE-WIRED** | locked contract from *coherent* units + spec-gate at the boundary seam — gives the breaker's "regenerate from the locked contract" a real target. New capability. |
+| WO-8 | ✅ LIVE | adaptive edit→rewrite guidance |
+| WO-9 + root fix | ✅ LIVE | family normalization + diagnostic-delta progress (validated live) |
+| **WO-4** | ⚠️ **already covered** | The fold-to-one-line-that-survives-compaction is already done by `TaskState.completedSteps` (pushed on every successful mutation/verify, agenticRunner ~20806) + `recent_completed=` re-injection (~2952/27943, "survives compaction"). My `ContextFolder` duplicates this. Not wired — redundant. The *non*-redundant part (window rewrite) is the layered compaction below. |
+| **WO-5** | ⚠️ **already covered** | Compaction is a 3-layer tuned system: `compactMessages` (summarization) + `WO-CE-BOUNDARY` context-engine token-budget pruning + `microcompact` (idle Qwen pattern), with mode-collapse ROOT-FIX guards; SNR (`signalToNoise.ratio`) already computed in the dump (~3531). My `decideCompaction`/`validateCompaction` would be a redundant 4th layer that risks the tuned system. Not wired. |
+| **WO-7** | 🔒 **security-gated** | Arbitrary sandboxed exec requires a security review per `browser-control-safety`/`token-security`. The `planHarnessBatch` builder (pure validation) is available; adding an exec tool is blocked on review — a rule, not a gap. |
+
+Net: every WO that adds *new* capability the mainline lacked is now live (WO-1/2/3/6/8/9 + root fix).
+WO-4 and WO-5 were built before the existing `completedSteps`/layered-compaction infra was known;
+their intent is already met by that infra, so wiring my modules would be duplication. WO-7's exec is
+security-gated. The remaining *real* build is WO-11 (compile-verify-fold isolated sub-agents on the
+existing `subtask_call`/`sub_agent` recursion), now unblocked by WO-6's locked contract.
+
+## Dependency-ordered build sequence
+
+0. **WO-9** convergence family normalization — **do first**; without it WO-3 fragments on command
+   variants and never escalates (found in live monitoring). Generic, zero deps, blocks further live runs.
+1. **WO-3** convergence-breaker — *landed + live-wired* (unblocks the infinite loop; zero deps).
+2. **WO-8** adaptive-edit — small, zero deps, kills the edit thrash.
+3. **WO-1** boundary-verifier — reuses existing runners; foundation for WO-2/WO-4.
+4. **WO-2** coherence-gate — needs WO-1 diagnostics.
+5. **WO-6** planner/executor + spec-gate — needs WO-2 (regeneration source) + WO-3.
+6. **WO-4** context-folding — needs WO-1 (fold trigger).
+7. **WO-5** decision-compaction — needs WO-6 (what to pin).
+8. **WO-7** code-as-harness — independent; gated on security review.
+
+Each work order lands as a **new focused module** (≤300 LOC) with its own unit tests, wired into the
+seam with a minimal additive hook, never enlarging `agenticRunner.ts`.