@tangle-network/agent-runtime 0.79.2 → 0.79.4

package/dist/{router-client-CMAWGv1h.d.ts → router-client-Ak2IGuXq.d.ts}

@@ -23,6 +23,38 @@ type ToolLoopChat = (messages: ReadonlyArray<Msg>, tools: ReadonlyArray<ToolSpec
      *  into a conserved pool (the supervisor brain). `runBrainLoop` itself ignores it. */
     costUsd?: number;
 }>;
+/** Self-compaction — bound the loop's OWN context window the way a fresh-respawn (dumb-Ralph) loop
+ *  does, but in place. A stateless chat API re-sends the WHOLE running conversation every turn, so an
+ *  agent that accumulates dozens of turns of tool results re-bills its entire transcript on every
+ *  inference — the context-overflow-one-level-up that the conserved budget pool cannot fix. With
+ *  compaction set, once the conversation exceeds `thresholdTokens` the accumulated middle (every prior
+ *  assistant turn + tool result) is distilled into ONE compact progress note and the conversation is
+ *  reset to `[...head, digest]`: the preserved head (system + the original task) survives, the stale
+ *  turn-by-turn history does not. The model keeps deciding; it stops re-billing the whole transcript.
+ *  Fires at a CLEAN turn boundary (after a turn's tool results are folded in, before the next
+ *  inference) so it never orphans an assistant `tool_calls` from its `tool` replies. */
+interface ToolLoopCompaction {
+    /** Compact once the estimated token count of the conversation exceeds this. */
+    readonly thresholdTokens: number;
+    /** Distill the conversation into a compact progress note that REPLACES the middle. Receives the
+     *  full conversation (so it can summarize everything done so far); returns the digest string. */
+    readonly distill: (messages: ReadonlyArray<Msg>) => Promise<string> | string;
+    /** Leading messages preserved verbatim (system + the original task). Default 2. */
+    readonly preserveHead?: number;
+    /** Token estimator over the conversation. Default ≈ chars/4 (incl. tool-call arguments). */
+    readonly estimateTokens?: (messages: ReadonlyArray<Msg>) => number;
+    /** Notified each time a compaction fires — for observability/metering. */
+    readonly onCompact?: (info: {
+        turn: number;
+        beforeTokens: number;
+        afterTokens: number;
+    }) => void;
+}
+/** Public supervisor-facing compaction config: same knobs as the primitive, but `distill` is optional
+ *  because the supervisor has a default digest that combines a brain note with live worker state. */
+type ToolLoopCompactionOptions = Omit<ToolLoopCompaction, 'distill'> & {
+    readonly distill?: ToolLoopCompaction['distill'];
+};
 
 /**
  * The one router chat client: direct OpenAI-compatible completions through the
@@ -161,4 +193,4 @@ declare function routerBrain(cfg: RouterConfig, opts?: {
     temperature?: number;
 }): ToolLoopChat;
 
-export { type RouterConfig as R, type ToolSpec as T, type ToolLoopChat as a, type RouterChatResult as b, type RouterChatToolsResult as c, type RouterToolCall as d, type RouterToolLoopResult as e, routerChatWithTools as f, routerChatWithUsage as g, routerToolLoop as h, routerBrain as r };
+export { type RouterConfig as R, type ToolSpec as T, type ToolLoopChat as a, type ToolLoopCompactionOptions as b, type RouterChatResult as c, type RouterChatToolsResult as d, type RouterToolCall as e, type RouterToolLoopResult as f, type ToolLoopCompaction as g, routerChatWithTools as h, routerChatWithUsage as i, routerToolLoop as j, routerBrain as r };

package/dist/{types-C1sozrte.d.ts → types-DYW0tloU.d.ts}

@@ -129,8 +129,8 @@ type UsageEvent = {
 } | {
     kind: 'iteration';
 };
-/** The runtime tag of a `Executor` impl. Open by intent — `string` so a BYO executor
- *  names its own runtime; the built-ins use these literals. */
+/** The runtime tag of a `Executor` impl. Open by intent: custom runtimes use their own string name.
+ * External executors can register additional runtime strings without widening this type. */
 type Runtime = 'router' | 'inline' | 'sandbox' | 'cli' | (string & {});
 /**
  * `AgentProfile` does NOT carry a `harness`/backend field — `harness` lives on the

package/dist/{worktree-fanout-CtQrRDME.d.ts → worktree-fanout-DaUDwCA_.d.ts}

@@ -1,9 +1,9 @@
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { AnalystFinding, DefaultVerdict } from '@tangle-network/agent-eval';
-import { A as AgentSpec, b as ExecutorRegistry, B as Budget, c as Agent, S as SpawnJournal, d as ResultBlobStore, e as RootHandle, f as SupervisedResult, N as NodeId, g as Settled, h as Spend, i as Scope, a as Executor } from './types-C1sozrte.js';
+import { A as AgentSpec, b as ExecutorRegistry, B as Budget, c as Agent, S as SpawnJournal, d as ResultBlobStore, e as RootHandle, f as SupervisedResult, N as NodeId, g as Settled, h as Spend, i as Scope, a as Executor } from './types-DYW0tloU.js';
 import { R as RuntimeHooks, I as Iteration } from './types-BF-MEsQB.js';
 import { BackendType } from '@tangle-network/sandbox';
-import { G as GitRunner, d as DeliverableSpec } from './worktree-CpptK3oF.js';
+import { W as WorktreeHarnessResult, G as GitRunner, a as WorktreeCheckRunner, D as DeliverableSpec } from './worktree-harness-Dt6s_m3z.js';
 import { L as LocalHarness, r as runLocalHarness } from './local-harness-DU7yV6mG.js';
 
 /**
@@ -785,77 +785,6 @@ interface CoderCheckConstraints {
     forbiddenPaths?: string[];
 }
 
-/**
- * @experimental
- *
- * The ONE worktree-harness execution core. The physical act — run a supervisor-authored
- * `AgentProfile` on a local coding-harness CLI (claude / codex / opencode) against a fresh git
- * worktree off `repoRoot`, capture the diff, derive the test/typecheck PASS signals, then clean
- * up — lives here ONCE. Two executors adapt it to two ports without re-implementing it:
- *   - `createWorktreeCliExecutor` — the `Scope`/`Supervisor` leaf `Executor`.
- *   - `createInProcessExecutor`   — the `runLoop` `SandboxClient` / coder-delegate path.
- *
- * §1.5 by construction: the authored `profile.prompt.systemPrompt` + `profile.model.default`
- * reach the harness through `harnessInvocation` HERE, so neither port can drop them — the exact
- * bug that existed while the in-process path called `runLocalHarness` with only the task prompt.
- *
- * Lifecycle: `createWorktree` → `harnessInvocation` + `runLocalHarness` → `captureWorktreeDiff`
- * (BEFORE checks, so the patch is the harness's output, not polluted by files a test run writes)
- * → the configured test/typecheck commands in the live worktree → return the result + a `cleanup`
- * the caller invokes at its own teardown point. A throw cleans up before propagating, so a failed
- * run never leaks a worktree.
- */
-
-/** Outcome of one verification command run in the worktree (test or typecheck). */
-interface WorktreeCommandResult {
-    /** The shell command line that was run. */
-    command: string;
-    /** Did the command exit 0? The PASS signal a deliverable gate / coder output reads. */
-    passed: boolean;
-    /** OS exit code, or `null` when killed before exit. */
-    exitCode: number | null;
-    /** Combined stdout+stderr (capped) — surfaced in traces for diagnosis. */
-    output: string;
-}
-/** The canonical result of one worktree-harness run, projected by each port to its own shape. */
-interface WorktreeHarnessResult {
-    /** The branch the worktree was cut on (`delegate/<runId>`). */
-    branch: string;
-    /** `git diff` of the worktree against its base — the unified patch the harness produced. */
-    patch: string;
-    /** Shortstat-derived change counts. */
-    stats: {
-        filesChanged: number;
-        insertions: number;
-        deletions: number;
-    };
-    /** The harness subprocess outcome. */
-    harness: {
-        name: LocalHarness;
-        exitCode: number | null;
-        timedOut: boolean;
-        killedBySignal: NodeJS.Signals | null;
-        durationMs: number;
-        stdout: string;
-        stderr: string;
-    };
-    /** Verification signals derived in the live worktree (present only when commands were given). */
-    checks?: {
-        tests?: WorktreeCommandResult;
-        typecheck?: WorktreeCommandResult;
-    };
-}
-/** The single shell-command-in-worktree runner seam (replaces the per-executor copies). */
-type WorktreeCheckRunner = (opts: {
-    command: string;
-    cwd: string;
-    timeoutMs: number;
-    signal?: AbortSignal;
-}) => Promise<{
-    exitCode: number | null;
-    output: string;
-}>;
-
 /**
  * @experimental
  *
@@ -907,6 +836,8 @@ interface WorktreeCliExecutorOptions {
     typecheckCmd?: string;
     /** Wall-clock cap per verification command (ms). Default = `harnessTimeoutMs` or 5 min. */
     checkTimeoutMs?: number;
+    /** Cap on each check's captured output. Default 16k. */
+    checkOutputCap?: number;
     /** Test seam — inject a git runner so unit tests drive the worktree helpers without git. */
     runGit?: GitRunner;
     /** Test seam — inject the harness runner so unit tests script a `LocalHarnessResult`. */
@@ -1038,4 +969,4 @@ interface WorktreeFanoutOptions extends PatchDeliverableOptions {
  */
 declare function worktreeFanout<Task>(options: WorktreeFanoutOptions): CombinatorShape<Task, WorktreePatchArtifact>;
 
-export { type Widen as $, type AuthoredHarness as A, type Panel as B, type CorpusRecord as C, type DefinePersonaInput as D, type EqualKArm as E, type FanoutOptions as F, type PanelJudge as G, type PanelVerdict as H, type PatchDeliverableOptions as I, type PersonaContext as J, type PersonaExecutors as K, type LoopUntilSpec as L, type Pipeline as M, type RenderCorpusToInstructions as N, type Outcome as O, type PanelSpec as P, type RunPersonified as Q, type RenderCorpusToInstructionsOptions as R, type ScopeAnalyzeInput as S, type TrajectoryReportOptions as T, type ShapeBudget as U, type VerifySpec as V, type WinnerStrategy as W, type ShapeContext as X, type TrajectoryNode as Y, type TrajectoryReportFn as Z, type Verify as _, type WorktreeFanoutOptions as a, type WidenDecision as a0, type WidenLineage as a1, type WorktreeCliExecutorOptions as a2, type WorktreeCommandResult as a3, createWorktreeCliExecutor as a4, patchDelivered as a5, worktreeFanout as a6, type WorktreePatchArtifact as b, type Corpus as c, type AssertTraceDerivedFindings as d, type SteerContext as e, type ScopeAnalyst as f, type CombinatorShape as g, type ScopeWidenGate as h, type PipelineStage as i, type FanoutWinnerSelector as j, type WidenSpec as k, type CorpusFilter as l, type Persona as m, type RunPersonifiedOptions as n, type ShapeRegistry as o, type LoopShape as p, type EqualKOnCostOptions as q, type EqualKVerdict as r, type TrajectoryReport as s, type DefinePersona as t, type EqualKOnCost as u, type Fanout as v, type FanoutSynthesis as w, type FlatWidenGate as x, type LoopUntil as y, type LoopUntilState as z };
+export { type Widen as $, type AuthoredHarness as A, type Panel as B, type CorpusRecord as C, type DefinePersonaInput as D, type EqualKArm as E, type FanoutOptions as F, type PanelJudge as G, type PanelVerdict as H, type PatchDeliverableOptions as I, type PersonaContext as J, type PersonaExecutors as K, type LoopUntilSpec as L, type Pipeline as M, type RenderCorpusToInstructions as N, type Outcome as O, type PanelSpec as P, type RunPersonified as Q, type RenderCorpusToInstructionsOptions as R, type ScopeAnalyzeInput as S, type TrajectoryReportOptions as T, type ShapeBudget as U, type VerifySpec as V, type WinnerStrategy as W, type ShapeContext as X, type TrajectoryNode as Y, type TrajectoryReportFn as Z, type Verify as _, type WorktreeFanoutOptions as a, type WidenDecision as a0, type WidenLineage as a1, type WorktreeCliExecutorOptions as a2, createWorktreeCliExecutor as a3, patchDelivered as a4, worktreeFanout as a5, type WorktreePatchArtifact as b, type Corpus as c, type AssertTraceDerivedFindings as d, type SteerContext as e, type ScopeAnalyst as f, type CombinatorShape as g, type ScopeWidenGate as h, type PipelineStage as i, type FanoutWinnerSelector as j, type WidenSpec as k, type CorpusFilter as l, type Persona as m, type RunPersonifiedOptions as n, type ShapeRegistry as o, type LoopShape as p, type EqualKOnCostOptions as q, type EqualKVerdict as r, type TrajectoryReport as s, type DefinePersona as t, type EqualKOnCost as u, type Fanout as v, type FanoutSynthesis as w, type FlatWidenGate as x, type LoopUntil as y, type LoopUntilState as z };

package/dist/{worktree-CpptK3oF.d.ts → worktree-harness-Dt6s_m3z.d.ts}

@@ -1,4 +1,5 @@
-import { a as Executor } from './types-C1sozrte.js';
+import { a as Executor } from './types-DYW0tloU.js';
+import { L as LocalHarness } from './local-harness-DU7yV6mG.js';
 
 /**
  * @experimental
@@ -122,4 +123,75 @@ declare function captureWorktreeDiff(options: DiffOptions): Promise<DiffResult>;
 /** @experimental */
 declare function removeWorktree(options: RemoveWorktreeOptions): Promise<void>;
 
-export { type CreateWorktreeOptions as C, type DiffOptions as D, type GitRunner as G, type RemoveWorktreeOptions as R, type WorktreeHandle as W, type DiffResult as a, createWorktree as b, captureWorktreeDiff as c, type DeliverableSpec as d, gateOnDeliverable as g, removeWorktree as r };
+/**
+ * @experimental
+ *
+ * The ONE worktree-harness execution core. The physical act — run a supervisor-authored
+ * `AgentProfile` on a local coding-harness CLI (claude / codex / opencode) against a fresh git
+ * worktree off `repoRoot`, capture the diff, derive the test/typecheck PASS signals, then clean
+ * up — lives here ONCE. Two executors adapt it to two ports without re-implementing it:
+ *   - `createWorktreeCliExecutor` — the `Scope`/`Supervisor` leaf `Executor`.
+ *   - `createInProcessExecutor`   — the `runLoop` `SandboxClient` / coder-delegate path.
+ *
+ * §1.5 by construction: the authored `profile.prompt.systemPrompt` + `profile.model.default`
+ * reach the harness through `harnessInvocation` HERE, so neither port can drop them — the exact
+ * bug that existed while the in-process path called `runLocalHarness` with only the task prompt.
+ *
+ * Lifecycle: `createWorktree` → `harnessInvocation` + `runLocalHarness` → `captureWorktreeDiff`
+ * (BEFORE checks, so the patch is the harness's output, not polluted by files a test run writes)
+ * → the configured test/typecheck commands in the live worktree → return the result + a `cleanup`
+ * the caller invokes at its own teardown point. A throw cleans up before propagating, so a failed
+ * run never leaks a worktree.
+ */
+
+/** Outcome of one verification command run in the worktree (test or typecheck). */
+interface WorktreeCommandResult {
+    /** The shell command line that was run. */
+    command: string;
+    /** Did the command exit 0? The PASS signal a deliverable gate / coder output reads. */
+    passed: boolean;
+    /** OS exit code, or `null` when killed before exit. */
+    exitCode: number | null;
+    /** Combined stdout+stderr (capped) — surfaced in traces for diagnosis. */
+    output: string;
+}
+/** The canonical result of one worktree-harness run, projected by each port to its own shape. */
+interface WorktreeHarnessResult {
+    /** The branch the worktree was cut on (`delegate/<runId>`). */
+    branch: string;
+    /** `git diff` of the worktree against its base — the unified patch the harness produced. */
+    patch: string;
+    /** Shortstat-derived change counts. */
+    stats: {
+        filesChanged: number;
+        insertions: number;
+        deletions: number;
+    };
+    /** The harness subprocess outcome. */
+    harness: {
+        name: LocalHarness | 'bridge';
+        exitCode: number | null;
+        timedOut: boolean;
+        killedBySignal: NodeJS.Signals | null;
+        durationMs: number;
+        stdout: string;
+        stderr: string;
+    };
+    /** Verification signals derived in the live worktree (present only when commands were given). */
+    checks?: {
+        tests?: WorktreeCommandResult;
+        typecheck?: WorktreeCommandResult;
+    };
+}
+/** The single shell-command-in-worktree runner seam (replaces the per-executor copies). */
+type WorktreeCheckRunner = (opts: {
+    command: string;
+    cwd: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}) => Promise<{
+    exitCode: number | null;
+    output: string;
+}>;
+
+export { type CreateWorktreeOptions as C, type DeliverableSpec as D, type GitRunner as G, type RemoveWorktreeOptions as R, type WorktreeHarnessResult as W, type WorktreeCheckRunner as a, type DiffOptions as b, type DiffResult as c, type WorktreeHandle as d, captureWorktreeDiff as e, createWorktree as f, type WorktreeCommandResult as g, gateOnDeliverable as h, removeWorktree as r };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.79.2",
+  "version": "0.79.4",
   "description": "Shared task-lifecycle skeleton for agents: a recursive loop kernel for chat turns, one-shot tasks, and multi-attempt loops, with trace capture and eval-gated self-improvement. Domain behavior lives in adapters; scoring and ship-gates in @tangle-network/agent-eval.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {

package/skills/build-with-agent-runtime/SKILL.md

@@ -21,8 +21,8 @@ capture-integrity, or eval/prod parity).
 
 ## Load order — point at source, never freeze snippets
 
-This skill carries **no API snippets**. The barrel MOVES (`./loops` is a
-back-compat alias of `./runtime`), the agent-eval pin drifts, and signatures get
+This skill carries **no API snippets**. The barrel MOVES (`./loops` is the
+runtime barrel), the agent-eval pin drifts, and signatures get
 corrected in place. Freezing a snippet here guarantees rot. Instead, read, in
 order, and re-verify against source:
 
@@ -32,9 +32,8 @@ order, and re-verify against source:
    two-substrate map. Every signature there was read from source.
 2. **`grep` the export barrel** — `grep -nE 'export (function|const|type)' src/runtime/index.ts`
    (and `src/agent/index.ts`, `src/improvement/index.ts`, `src/mcp/index.ts`,
-   `src/intelligence/index.ts`) for the live names + subpaths. `./loops` and
-   `./runtime` resolve to the SAME barrel (`package.json` maps both to
-   `src/runtime/index.ts`).
+   `src/intelligence/index.ts`) for the live names + subpaths. `./loops` is the
+   runtime barrel (`package.json` maps it to `src/runtime/index.ts`).
 3. **`bench/HARNESS.md`** — the experiment-harness map: commands, the
    `rollout → corpus → selector → CI → gate` flow, and the `ADAPTERS` registry
    (a harness-local export, `bench/src/adapters.ts`, not a package export).
@@ -54,36 +53,48 @@ profile and letting the substrate materialize it into harness shapes —
 self-verification, iteration, and audit are profile levers (hooks/skills/
 subagents), never glue code.
 
-`AgentProfile` is now owned by `@tangle-network/agent-interface` (the `/runtime`
-barrel still re-exports the sandbox alias for back-compat), which also owns
+`AgentProfile` is owned by `@tangle-network/agent-interface` (the `/loops`
+barrel re-exports the sandbox alias as a one-stop import), which also owns
 `HarnessType` + `ReasoningEffort` and a capability layer
 (`harnessSupportsModel` / `reasoningEffortsFor`) — so harness/model/reasoning
 compatibility is a queryable contract, not an assumption.
 
+Harness is a RUN-layer coordinate, not part of the portable genome: it rides on
+agent-runtime's `AgentSpec { profile, harness }`. To sweep it as an eval axis,
+don't hand-declare a harness list — expand one base profile across
+`CODING_HARNESSES` with `expandProfileAxes` (agent-eval), run with
+`runProfileMatrix`, and pivot results by the stamped `AgentProfileCell`
+(`groupRunsByAgentProfileCell`); incompatible `(harness, model)` pairs drop via
+`harnessSupportsModel`.
+
 | Altitude — I want to… | Use | Source |
 |---|---|---|
-| **Define a genome** (who the agent is + what it can do, ONE surface) | `AgentProfile` (runnable) / `AgentSurfaces` (the editable-coordinate map) — `/runtime`, `/agent` | canonical-api §3.2 |
-| **Define the personified-run record** (model+prompt+tools+role+seams) | `definePersona(input)` — `/runtime` | canonical-api §3.1 |
-| **Run a genome driver⟷worker, end-to-end** | `runPersonified({ persona, shape, task, budget })` — `/runtime` | canonical-api §3.1 |
-| **Loop a worker over one evolving artifact, K rounds, stop-when-good** | `loopUntil(seed, spec)` as the `shape` — `/runtime` | canonical-api §3.1 |
-| **Best-of-N / parallel-research at equal compute** | `fanout(items, opts)` — `/runtime` | canonical-api §3.1 |
-| **Produce-then-gate / multi-judge quorum / fixed chain** | `verify` / `panel` / `pipeline` — `/runtime` | canonical-api §3.1 |
+| **Define a genome** (who the agent is + what it can do, ONE surface) | `AgentProfile` (runnable) / `AgentSurfaces` (the editable-coordinate map) — `/loops`, `/agent` | canonical-api §3.2 |
+| **Define the personified-run record** (model+prompt+tools+role+seams) | `definePersona(input)` — `/loops` | canonical-api §3.1 |
+| **Run a genome driver⟷worker, end-to-end** | `runPersonified({ persona, shape, task, budget })` — `/loops` | canonical-api §3.1 |
+| **Loop a worker over one evolving artifact, K rounds, stop-when-good** | `loopUntil(seed, spec)` as the `shape` — `/loops` | canonical-api §3.1 |
+| **Best-of-N / parallel-research at equal compute** | `fanout(items, opts)` — `/loops` | canonical-api §3.1 |
+| **Produce-then-gate / multi-judge quorum / fixed chain** | `verify` / `panel` / `pipeline` — `/loops` | canonical-api §3.1 |
 | **Run depth-vs-breadth (or a custom strategy) over a stateful tool domain** | `runAgentic({ surface, task, mode\|strategy, budget })` — `/loops` | canonical-api §3.3 |
 | **Author a new topology/strategy compactly** | `defineStrategy(name, body)` w/ `ctx.shot()`+`ctx.critique()` — `/loops` | canonical-api §3.3 |
 | **Add a stateful tool-using domain** | implement `AgenticSurface` (5 hooks) — `/loops` | canonical-api §3.3 |
+| **Drive a team of agents over a graded `AgenticSurface` task** (workers settle on its check, driver self-improves from the failing tests) | `superviseSurface(profile, task, { surface, worker })` — `/loops` | canonical-api §2 |
 | **Benchmark: compare strategies + significance + Pareto on a domain** | `runBenchmark({ environment, tasks, worker, strategies })` — `/loops` | canonical-api §3.3 |
+| **Benchmark report: multi-profile × multi-axis leaderboard** (ranked board + score matrix + SVG/HTML charts, any `RunRecord[]`) | `leaderboard(records)` + `renderLeaderboardMarkdown` / `renderLeaderboardSvg` / `renderLeaderboardHtml` — `/loops` | canonical-api §2 |
+| **Meter one `openSandboxRun` cell's token/cost usage** | `sumSandboxUsage(events)` — `/loops` | canonical-api §2 |
+| **Sweep harness × model as an eval axis** (turn one base profile into the full harness × model set) | `expandProfileAxes({ base, harnesses, models })` over `CODING_HARNESSES` → `runProfileMatrix(...)`, pivot with `groupRunsByAgentProfileCell` — `agent-eval` root — NOT a hand-declared `HARNESSES` list | agent-eval root (verify vs source) |
 | **Benchmark: add/run an external benchmark from the harness** | `ADAPTERS`/`resolveAdapter(key)` + a bench gate (`*-gate.mts`) over `openSandboxRun` + `sandboxAgentRun` (`bench/src/sandbox-run.ts`) | canonical-api §3.3 |
-| **Spawn N coding agents on isolated git worktrees, keep the one whose patch passes checks** | `worktreeFanout` + `createWorktreeCliExecutor` + `gateOnDeliverable(DeliverableSpec)` over a raw `WorktreePatchArtifact`, winner via `selectValidWinner` — `/runtime` — NOT a hand-rolled spawn-loop / "coder" role | canonical-api §3.1 / §5 |
-| **Sandbox coding rollout** (fresh box/round, or persistent+resume) | `runLoop(options)` / `openSandboxRun(client, opts, deliverable)` — `/runtime` | canonical-api §3.1 |
-| **Optimize a CODE surface** in a gated loop | `improvementDriver({ worktree, generator })` — `/improvement` | canonical-api §3.4 |
+| **Spawn N coding agents on isolated git worktrees, keep the one whose patch passes checks** | `worktreeFanout` + `createWorktreeCliExecutor` + `gateOnDeliverable(DeliverableSpec)` over a raw `WorktreePatchArtifact`, winner via `selectValidWinner` — `/loops` — NOT a hand-rolled spawn-loop / "coder" role | canonical-api §3.1 / §5 |
+| **Sandbox coding rollout** (fresh box/round, or persistent+resume) | `runLoop(options)` / `openSandboxRun(client, opts, deliverable)` — `/loops` | canonical-api §3.1 |
+| **Optimize a CODE surface** in a gated loop | `improvementDriver({ worktree, generator })` — root `.` | canonical-api §3.4 |
 | **Optimize a PROMPT/config surface** (one call) | `selfImprove({ agent, scenarios, judge, baselineSurface })` — `agent-eval/contract` | canonical-api §3.4 |
 | **Gate: ship/hold a candidate** (campaign ctx) | `defaultProductionGate` / `heldOutGate` / `composeGate` — `agent-eval/contract` | canonical-api §3.4 |
-| **Gate: ship/hold from a `BenchmarkReport`** (per-task cells) | `promotionGate({ report, incumbent, candidate })` — `/runtime` | canonical-api §3.4 |
-| **Run the full multi-generation flywheel + certify** | `runStrategyEvolution(config)` — `/runtime` | canonical-api §3.4 |
-| **Compose the prod sandbox profile** (eval/prod parity) | `composeProductionAgentProfile(base, opts)` — `/mcp` | canonical-api §3.2 |
-| **Observe a run** (cost/time waterfall, live tree, OTLP) | `createWaterfallCollector` / `createOtelExporter` via `composeRuntimeHooks(...)` — root; `createTopologyView` / `renderTopologyTree` — `/topology` | canonical-api §3.5 |
+| **Gate: ship/hold from a `BenchmarkReport`** (per-task cells) | `promotionGate({ report, incumbent, candidate })` — `/loops` | canonical-api §3.4 |
+| **Run the full multi-generation flywheel + certify** | `runStrategyEvolution(config)` — `/loops` | canonical-api §3.4 |
+| **Observe a run** (cost/time waterfall, OTLP) | `createWaterfallCollector()` — `/loops`; `createOtelExporter` attached via `composeRuntimeHooks(...)` — root `.` | canonical-api §2 |
 | **State any A/B claim** | `pairedLift` (bench) over `pairedBootstrap`/`heldoutSignificance` (substrate) | canonical-api §3.5 |
-| **Observe/ship with billing-boundary** | `withTangleIntelligence(agent, { project, effort })` — `/intelligence` | canonical-api §7 (now live on main — verify) |
+| **Observe/ship with billing-boundary** | `withTangleIntelligence(agent, { project, effort })` — `/intelligence` | canonical-api §2 |
+| **Pull the certified profile from the Intelligence plane** (pull-by-default delivery: fold the gate-certified prompt onto the base surface) | `pullCertified` / `withCertifiedDelivery` / `composeCertifiedPrompt` — `/intelligence` | `src/intelligence/delivery.ts` |
 
 ## Do-NOT-reinvent — the traps this skill exists to stop
 
@@ -112,6 +123,12 @@ holds the load-bearing invariant the parallel breaks:
   sum of spans IS the billed run cost; a parallel tally drifts).
 - your own bootstrap loop / PRNG per gate **≈** `pairedLift` / `promotionGate`
   (seeded, identical run-to-run; never report a point lift without `low/high/pairs`).
+- a per-product `HARNESSES` / `HarnessBackend` list + a metadata-harness reader
+  **≈** `CODING_HARNESSES` + `expandProfileAxes` (the one canonical harness list;
+  incompatible `(harness, model)` pairs drop via `harnessSupportsModel`) and the
+  `AgentProfileCell` stamped by `runProfileMatrix`, pivoted via
+  `groupRunsByAgentProfileCell` — never bake the harness into the model id so the
+  same model can run under multiple harnesses.
 
 ## End-to-end recipe
 
@@ -146,8 +163,21 @@ One line wraps any agent with trace + billing boundary:
 off|eco|standard|thorough|max` (`'off'` is the provable passthrough floor —
 intelligence spend clamped to 0). It builds on `createOtelExporter` +
 `loopEventToOtelSpan` — don't hand-roll a trace-wrapper or effort/tier config.
-Verify the live subpath against `src/intelligence/index.ts` (canonical-api §7's
-"branch-only" note is stale — it landed on main).
+Verify the live subpath against `src/intelligence/index.ts`.
+
+Two operational facts every consumer must know:
+
+- **Export is a silent no-op without an endpoint.** The export leg only ships
+  when `INTELLIGENCE_OTLP_ENDPOINT` (or `OTEL_EXPORTER_OTLP_ENDPOINT`) is set —
+  e.g. `https://intelligence.tangle.tools/v1/otlp`; absent, spans are dropped
+  best-effort with no error. The client's `doctor().exportConfigured` is the
+  check that export will actually ship.
+- **Delivery pulls the certified profile from the plane.** `pullCertified` /
+  `withCertifiedDelivery` hit
+  `GET {TANGLE_INTELLIGENCE_URL|https://intelligence.tangle.tools}/v1/profiles/:target/composed`
+  with `Bearer TANGLE_API_KEY`; `withCertifiedDelivery` folds the certified
+  prompt onto the base surface, refreshes at most every 5 minutes, and is
+  fail-closed — a failed pull runs the agent on its base surface.
 
 ## Final check