@tangle-network/agent-runtime 0.51.0 → 0.52.0

package/dist/loop-runner-bin.js

@@ -2,13 +2,13 @@
 import {
   parseLoopRunnerArgv,
   runLoopRunnerCli
-} from "./chunk-XEI7AIHU.js";
+} from "./chunk-COAVO6QB.js";
 import "./chunk-FNMGYYSS.js";
-import "./chunk-HYG4ISNS.js";
+import "./chunk-4JI4BCBI.js";
 import "./chunk-KADIJAD4.js";
 import "./chunk-HNUXAZIJ.js";
 import "./chunk-G3RGMA7C.js";
-import "./chunk-FQH33M5N.js";
+import "./chunk-2OU7ZQPD.js";
 import "./chunk-GSUO5QS6.js";
 import "./chunk-DGUM43GV.js";
 export {

package/dist/loops.d.ts

@@ -1,5 +1,5 @@
 export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
-export { AgenticOptions, AgenticRunResult, AgenticSurface, AgenticTask, AgenticTool, AnytimeReport, AnytimeStrategySummary, AnytimeTaskCurve, ArtifactHandle, AssertTraceDerivedFindings, AuditIntentInput, AuditIntentOptions, AuthorStrategyOptions, AuthoredStrategy, BenchmarkCell, BenchmarkConfig, BenchmarkLift, BenchmarkReport, BenchmarkStrategySummary, BenchmarkTaskRow, BridgeSeam, BudgetPool, BudgetReadout, ChampionPick, ChampionPolicy, CheckpointCapableBox, CliSeam, CombinatorShape, Corpus, CorpusFilter, CorpusRecord, CreateScopeAnalystOptions, CriuCapableClient, DefinePersona, DefinePersonaInput, Deliverable, Environment, EqualKArm, EqualKOnCost, EqualKOnCostOptions, EqualKVerdict, EvolutionArchiveNode, EvolutionAuthor, EvolutionBandInfo, EvolutionCandidate, EvolutionGeneration, EvolutionReport, ExecutorConfig, Fanout, FanoutOptions, FanoutSynthesis, FileCorpus, FileResultBlobStore, FileSpawnJournal, FlatWidenGate, ForkCapableBox, GitWorkspaceOptions, HarvestCorpusOptions, HarvestFailure, HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, InMemorySpawnJournal, IntentAudit, LoopDispatchOptions, LoopOptionsForDispatch, LoopShape, LoopUntil, LoopUntilSpec, LoopUntilState, McpEndpoint, McpEnvironmentOptions, Observation, ObserveInput, ObserveOptions, OpenSandboxRunOptions, Outcome, Panel, PanelJudge, PanelSpec, PanelVerdict, Persona, PersonaContext, PersonaExecutors, Pipeline, PipelineStage, PromotionGateOptions, PromotionVerdict, RenderCorpusToInstructions, RenderCorpusToInstructionsOptions, ReservationTicket, RouterChatResult, RouterChatToolsResult, RouterConfig, RouterSeam, RouterToolCall, RouterToolLoopResult, RouterToolsSeam, RunAgenticOptions, RunPersonified, RunPersonifiedOptions, SandboxCapabilities, SandboxLineage, SandboxLineageHandle, SandboxRun, SandboxSeam, ScopeAnalyst, ScopeAnalyzeInput, ScopeWidenGate, SessionCapableBox, ShapeBudget, ShapeContext, ShapeRegistry, Shell, ShotPersona, ShotSpec, SteerContext, Strategy, StrategyCtx, StrategyEvolutionConfig, StrategyResult, SurfaceScore, ToolSpec, TrajectoryNode, TrajectoryReport, TrajectoryReportFn, TrajectoryReportOptions, TurnResult, UsageSink, VerifierEnvironmentOptions, Verify, VerifySpec, WaterfallCollector, WaterfallReport, WaterfallSpan, Widen, WidenDecision, WidenLineage, WidenSpec, Workspace, WorkspaceCommit, acquireSandbox, adaptiveRefine, anytimeReport, assertStrategyContract, assertTraceDerivedFindings, auditIntent, authorStrategy, breadthDriver, buildSteerContext, builtinShapes, contentAddress, createBudgetPool, createExecutor, createExecutorRegistry, createMcpEnvironment, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, defaultAnalystInstruction, defaultAuditorInstruction, definePersona, defineStrategy, depthDriver, discriminatingMeans, equalKOnCost, extractLlmCallEvent, fanout, flatWidenGate, gitWorkspace, harvestCorpus, inlineSandboxClient, jjWorkspace, localShell, loopDispatch, loopUntil, mapSandboxEvent, materializeTreeView, observe, openSandboxRun, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, promotionGate, refine, registerShape, renderAnytimeTable, renderCorpusToInstructions, renderReport, replaySpawnTree, reportLoopUsage, routerChatWithTools, routerChatWithUsage, routerToolLoop, runAgentic, runBenchmark, runPersonified, runStrategyEvolution, sample, sampleThenRefine, selectChampion, settledToIteration, spendFromUsageEvents, strategyAuthorContract, trajectoryReport, verify, widen } from './runtime.js';
+export { AgenticOptions, AgenticRunResult, AgenticSurface, AgenticTask, AgenticTool, AnytimeReport, AnytimeStrategySummary, AnytimeTaskCurve, ArtifactHandle, AssertTraceDerivedFindings, AuditIntentInput, AuditIntentOptions, AuthorStrategyOptions, AuthoredStrategy, BenchmarkCell, BenchmarkConfig, BenchmarkLift, BenchmarkReport, BenchmarkStrategySummary, BenchmarkTaskRow, BridgeSeam, BudgetPool, BudgetReadout, ChampionPick, ChampionPolicy, CheckpointCapableBox, CliSeam, CombinatorShape, Corpus, CorpusFilter, CorpusRecord, CreateScopeAnalystOptions, CriuCapableClient, DefinePersona, DefinePersonaInput, Deliverable, Environment, EqualKArm, EqualKOnCost, EqualKOnCostOptions, EqualKVerdict, EvolutionArchiveNode, EvolutionAuthor, EvolutionBandInfo, EvolutionCandidate, EvolutionGeneration, EvolutionReport, ExecutorConfig, Fanout, FanoutOptions, FanoutSynthesis, FileCorpus, FileResultBlobStore, FileSpawnJournal, FlatWidenGate, ForkCapableBox, GitWorkspaceOptions, HarvestCorpusOptions, HarvestFailure, HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, InMemorySpawnJournal, IntentAudit, LoopDispatchOptions, LoopOptionsForDispatch, LoopShape, LoopUntil, LoopUntilSpec, LoopUntilState, McpEndpoint, McpEnvironmentOptions, Observation, ObserveInput, ObserveOptions, OpenSandboxRunOptions, Outcome, Panel, PanelJudge, PanelSpec, PanelVerdict, Persona, PersonaContext, PersonaExecutors, Pipeline, PipelineStage, PromotionGateOptions, PromotionVerdict, RegistryAnalyzeProjection, RenderCorpusToInstructions, RenderCorpusToInstructionsOptions, ReservationTicket, RouterChatResult, RouterChatToolsResult, RouterConfig, RouterSeam, RouterToolCall, RouterToolLoopResult, RouterToolsSeam, RunAgenticOptions, RunPersonified, RunPersonifiedOptions, SandboxCapabilities, SandboxLineage, SandboxLineageHandle, SandboxRun, SandboxSeam, ScopeAnalyst, ScopeAnalyzeInput, ScopeWidenGate, SessionCapableBox, ShapeBudget, ShapeContext, ShapeRegistry, Shell, ShotPersona, ShotSpec, SteerContext, Strategy, StrategyCtx, StrategyEvolutionConfig, StrategyResult, SurfaceScore, ToolSpec, TrajectoryNode, TrajectoryReport, TrajectoryReportFn, TrajectoryReportOptions, TurnResult, UsageSink, VerifierEnvironmentOptions, Verify, VerifySpec, WaterfallCollector, WaterfallReport, WaterfallSpan, Widen, WidenDecision, WidenLineage, WidenSpec, Workspace, WorkspaceCommit, acquireSandbox, adaptiveRefine, anytimeReport, assertStrategyContract, assertTraceDerivedFindings, auditIntent, authorStrategy, breadthDriver, buildSteerContext, builtinShapes, contentAddress, createBudgetPool, createExecutor, createExecutorRegistry, createMcpEnvironment, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, defaultAnalystInstruction, defaultAuditorInstruction, definePersona, defineStrategy, depthDriver, discriminatingMeans, equalKOnCost, extractLlmCallEvent, fanout, flatWidenGate, gitWorkspace, harvestCorpus, inlineSandboxClient, jjWorkspace, localShell, loopDispatch, loopUntil, mapSandboxEvent, materializeTreeView, observe, openSandboxRun, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderReport, replaySpawnTree, reportLoopUsage, routerChatWithTools, routerChatWithUsage, routerToolLoop, runAgentic, runBenchmark, runPersonified, runStrategyEvolution, sample, sampleThenRefine, selectChampion, settledToIteration, spendFromUsageEvents, strategyAuthorContract, trajectoryReport, verify, widen } from './runtime.js';
 export { A as AnalyzeInput, a as CompletionAnalyst, b as CompletionEvidence, c as CompletionPolicy, d as CompletionVerdict, C as CreateDriverOptions, D as DriverDecision, P as PlannerContext, e as TopologyMove, T as TopologyPlanner, f as completionAuthorizes, g as createDriver, h as deterministicCompletion, r as renderAnalyses, s as sentinelCompletion, i as stopSentinel } from './driver-DLI1io57.js';
 export { R as RunLoopOptions, c as createSandboxForSpec, d as defaultSelectWinner, r as runLoop } from './run-loop-BIineL1T.js';
 export { A as Agent, d as AgentSpec, B as Budget, j as Executor, k as ExecutorContext, h as ExecutorFactory, E as ExecutorRegistry, l as ExecutorResult, H as Handle, N as NodeId, m as NodeSnapshot, n as NodeStatus, o as Restart, R as ResultBlobStore, e as RootHandle, p as RootSignal, q as Runtime, S as Scope, c as Settled, b as SpawnEvent, a as SpawnJournal, r as SpawnOpts, g as Spend, f as SupervisedResult, i as Supervisor, s as SupervisorOpts, T as TreeView, U as UsageEvent, W as WidenGate } from './types-5MGt5KTY.js';
@@ -7,3 +7,4 @@ export { A as AgentRunSpec, D as Driver, E as ExecCtx, I as Iteration, F as Loop
 export { DefaultVerdict } from '@tangle-network/agent-eval';
 import './runtime-hooks-C7JwKb9E.js';
 import '@tangle-network/agent-eval/campaign';
+import './types-p8dWBIXL.js';

package/dist/loops.js

@@ -60,6 +60,7 @@ import {
   promotionGate,
   refine,
   registerShape,
+  registryScopeAnalyst,
   renderAnalyses,
   renderAnytimeTable,
   renderCorpusToInstructions,
@@ -85,7 +86,7 @@ import {
   trajectoryReport,
   verify,
   widen
-} from "./chunk-FQH33M5N.js";
+} from "./chunk-2OU7ZQPD.js";
 import {
   extractLlmCallEvent,
   mapSandboxEvent
@@ -155,6 +156,7 @@ export {
   promotionGate,
   refine,
   registerShape,
+  registryScopeAnalyst,
   renderAnalyses,
   renderAnytimeTable,
   renderCorpusToInstructions,

package/dist/mcp/bin.js

@@ -4,12 +4,12 @@ import {
   createPropagatingTraceEmitter,
   detectExecutor,
   readTraceContextFromEnv
-} from "../chunk-HAA4KZUD.js";
+} from "../chunk-7SP2OVYZ.js";
 import "../chunk-WIR4HOOJ.js";
 import {
   DelegationTaskQueue,
   FileDelegationStore
-} from "../chunk-47SWANFA.js";
+} from "../chunk-BERLUBAP.js";
 import {
   coderTaskFromArgs,
   composeLoopTraceEmitters,
@@ -20,7 +20,7 @@ import {
   parseDetachedSessionRef,
   runDetachedTurn,
   settleDetachedCoderTurn
-} from "../chunk-HYG4ISNS.js";
+} from "../chunk-4JI4BCBI.js";
 import {
   coderProfile
 } from "../chunk-KADIJAD4.js";
@@ -28,7 +28,7 @@ import "../chunk-GLR25NG7.js";
 import "../chunk-G3RGMA7C.js";
 import {
   runLoop
-} from "../chunk-FQH33M5N.js";
+} from "../chunk-2OU7ZQPD.js";
 import "../chunk-GSUO5QS6.js";
 import "../chunk-DGUM43GV.js";
 

package/dist/mcp/index.js

@@ -14,12 +14,12 @@ import {
   removeWorktree,
   traceContextToEnv,
   validateDelegateUiAuditArgs
-} from "../chunk-HAA4KZUD.js";
+} from "../chunk-7SP2OVYZ.js";
 import "../chunk-WIR4HOOJ.js";
 import {
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "../chunk-FKHNHUXP.js";
+} from "../chunk-V2K35HF2.js";
 import {
   DELEGATE_CODE_DESCRIPTION,
   DELEGATE_CODE_INPUT_SCHEMA,
@@ -54,7 +54,7 @@ import {
   validateDelegateResearchArgs,
   validateDelegationHistoryArgs,
   validateDelegationStatusArgs
-} from "../chunk-47SWANFA.js";
+} from "../chunk-BERLUBAP.js";
 import {
   createKbGate
 } from "../chunk-FNMGYYSS.js";
@@ -75,7 +75,7 @@ import {
   parseDetachedSessionRef,
   runDetachedTurn,
   settleDetachedCoderTurn
-} from "../chunk-HYG4ISNS.js";
+} from "../chunk-4JI4BCBI.js";
 import "../chunk-KADIJAD4.js";
 import {
   runLocalHarness
@@ -88,7 +88,7 @@ import {
 import "../chunk-G3RGMA7C.js";
 import {
   assertTraceDerivedFindings
-} from "../chunk-FQH33M5N.js";
+} from "../chunk-2OU7ZQPD.js";
 import "../chunk-GSUO5QS6.js";
 import "../chunk-DGUM43GV.js";
 

package/dist/runtime.d.ts

@@ -3,7 +3,7 @@ export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } fro
 import { R as ResultBlobStore, a as SpawnJournal, N as NodeId, b as SpawnEvent, T as TreeView, c as Settled, d as AgentSpec, E as ExecutorRegistry, B as Budget, A as Agent, e as RootHandle, f as SupervisedResult, g as Spend, S as Scope, h as ExecutorFactory, U as UsageEvent, i as Supervisor } from './types-5MGt5KTY.js';
 export { j as Executor, k as ExecutorContext, l as ExecutorResult, H as Handle, m as NodeSnapshot, n as NodeStatus, o as Restart, p as RootSignal, q as Runtime, r as SpawnOpts, s as SupervisorOpts, W as WidenGate } from './types-5MGt5KTY.js';
 import { R as RuntimeHooks } from './runtime-hooks-C7JwKb9E.js';
-import { ChatClient, AnalystFinding, DefaultVerdict, AgentProfile as AgentProfile$1 } from '@tangle-network/agent-eval';
+import { ChatClient, AnalystFinding, DefaultVerdict, AgentProfile as AgentProfile$1, AnalystRunInputs } from '@tangle-network/agent-eval';
 export { DefaultVerdict } from '@tangle-network/agent-eval';
 export { A as AnalyzeInput, a as CompletionAnalyst, b as CompletionEvidence, c as CompletionPolicy, d as CompletionVerdict, C as CreateDriverOptions, D as DriverDecision, P as PlannerContext, e as TopologyMove, T as TopologyPlanner, f as completionAuthorizes, g as createDriver, h as deterministicCompletion, r as renderAnalyses, s as sentinelCompletion, i as stopSentinel } from './driver-DLI1io57.js';
 import { S as SandboxClient, b as LoopResult, d as LoopTokenUsage, R as RuntimeStreamEvent, A as AgentRunSpec, E as ExecCtx, I as Iteration } from './types-BEQsBhOE.js';
@@ -11,6 +11,7 @@ export { D as Driver, F as LoopDecisionPayload, G as LoopEndedPayload, H as Loop
 import { Scenario, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
 import { R as RunLoopOptions } from './run-loop-BIineL1T.js';
 export { c as createSandboxForSpec, d as defaultSelectWinner, r as runLoop } from './run-loop-BIineL1T.js';
+import { b as AnalystRegistryLike } from './types-p8dWBIXL.js';
 
 /**
  * @experimental
@@ -464,6 +465,9 @@ interface ShapeContext<D = unknown> {
     /** Derive a child `AgentSpec` from the persona's root spec with an overridden profile —
      *  the seam a shape uses to give a worker a narrower role/prompt than the root persona. */
     childSpec(profile: AgentProfile, harness?: BackendType | null): AgentSpec;
+    /** The scope analyst (selector≠judge firewall) the combinator steers from. Absent ⇒ the
+     *  dormant default (empty findings → gates read deliverables/state only). */
+    readonly analyst?: ScopeAnalyst<D>;
 }
 /**
  * A reusable act-body factory. Given the persona's content + seams (`ShapeContext`), it
@@ -521,6 +525,9 @@ interface RunPersonifiedOptions<Task, D> {
     readonly handle?: RootHandle<Outcome<D>>;
     readonly now?: () => number;
     readonly signal?: AbortSignal;
+    /** Optional scope analyst threaded into the shape's ShapeContext so loopUntil/widen steer
+     *  on trace-derived findings instead of the dormant empty default. */
+    readonly analyst?: ScopeAnalyst<D>;
 }
 /** The composed run signature. */
 type RunPersonified = <Task, D>(options: RunPersonifiedOptions<Task, D>) => Promise<SupervisedResult<Outcome<D>>>;
@@ -1635,6 +1642,32 @@ interface CreateScopeAnalystOptions<D> {
  *  - any finding cites judge-derived metric evidence → `PlannerError` via the firewall
  */
 declare function createScopeAnalyst<D>(scope: Scope<Outcome<D>>, options: CreateScopeAnalystOptions<D>): ScopeAnalyst<D>;
+/**
+ * Project a `ScopeAnalyzeInput` into the `AnalystRegistry.run` arguments. The registry runs over a
+ * `runId` + `AnalystRunInputs` (a trace store / run record / artifact dir), NOT in-memory scope
+ * settlements — so the CALLER owns the projection from the combinator's drained children to the
+ * registry's inputs (e.g. the trace store the run already wrote). This adapter never invents that
+ * bridge; it only runs the projected inputs and firewalls the merged findings.
+ */
+interface RegistryAnalyzeProjection {
+    readonly runId: string;
+    readonly inputs: AnalystRunInputs;
+    /** Optional `run` opts (e.g. `priorFindings`) forwarded verbatim to the registry. */
+    readonly opts?: Parameters<AnalystRegistryLike['run']>[2];
+}
+/**
+ * A `ScopeAnalyst` backed by an `AnalystRegistry` — the panel-of-analysts seam. The registry merges
+ * N analyst KINDS into one `AnalystRunResult.findings`; `analyze` runs it over the caller-projected
+ * `{ runId, inputs }` and pipes the merged findings through the SAME `assertTraceDerivedFindings`
+ * firewall `createScopeAnalyst` uses (single-sourced selector≠judge). Distinct from `panel()`
+ * (judges-vs-one-artifact) — this is analysts-over-a-trace, the diagnosis side of the wire.
+ *
+ * Fail loud: a registry that throws propagates; a judge-derived finding aborts via the firewall.
+ * The projection is the caller's (`buildInputs`) — if the scope settlements do not cleanly map to
+ * the registry's `AnalystRunInputs`, that is a caller-side contract gap, surfaced there, not papered
+ * over with a fabricated input here.
+ */
+declare function registryScopeAnalyst<D>(registry: AnalystRegistryLike, buildInputs: (input: ScopeAnalyzeInput<D>) => RegistryAnalyzeProjection): ScopeAnalyst<D>;
 /**
  * Build the `SteerContext` a combinator reads to steer (its `loopUntil.until`, `widen` gate, any
  * future steer). One place enforces the firewall: `findings` is asserted trace-derived before it is
@@ -1693,9 +1726,10 @@ declare function fanout<Task, Item, D>(items: ReadonlyArray<Item>, opts: FanoutO
  * the deployable stop. The conserved pool IS the loop bound: once `spawn` fails closed the loop
  * stops. A loop that exhausted the pool without `until` ever satisfying is a concrete blocker.
  *
- * Findings are threaded through the `SteerContext` firewall in the analyst seam (`analyst.ts`);
- * absent a wired analyst on this surface the firewall stays dormant and `until` is consulted with
- * an empty findings array — never a fabricated finding (fail-loud honesty over a silent default).
+ * When `ctx.analyst` is set, each round runs it over the children settled so far and steers
+ * `until` on the resulting trace-derived findings (the analyst spawns into THIS scope, so its
+ * compute is conserved-pooled — equal-k holds by construction). Absent an analyst the findings
+ * argument is the empty array — never a fabricated finding (fail-loud honesty over a silent default).
  */
 declare function loopUntil<Task, State, D>(seed: State, spec: LoopUntilSpec<Task, State, D>): CombinatorShape<Task, D>;
 /**
@@ -1721,9 +1755,14 @@ declare function verify<Task, Candidate, D>(spec: VerifySpec<Task, Candidate, D>
  * never a child's raw `verdict` — and the default gate (`flatWidenGate`) never widens, so the R2
  * firewall stays dormant. Terminal selection is `spec.synthesize` over every settled lineage.
  *
- * No analyst is wired on this frozen surface, so `decide` is consulted with an empty findings
- * array; a flat gate ignores it. A non-flat gate that wants findings reads them through the
- * `SteerContext` firewall the analyst seam owns — never fabricated here.
+ * When `ctx.analyst` is set, `decide` is consulted with that round's trace-derived findings;
+ * absent an analyst the findings argument is the empty array a flat gate ignores. The analyst
+ * spawns into THIS scope (conserved-pooled, so equal-k holds). Streaming caveat: a wired analyst
+ * drains its own child off the SHARED cursor by id-match, so on a NON-flat gate (which spawns
+ * widen children that are live concurrently) the analyst can consume a sibling's settlement before
+ * the widen loop sees it. The shipped default (`flatWidenGate`) never widens, so no widen child is
+ * ever live when the analyst runs and the wire is exact; a non-flat gate must drive the analyst on
+ * a scope whose siblings are quiesced, or read findings without the shared-cursor drain.
  */
 declare function widen<Task, Seed, D>(spec: WidenSpec<Seed, D>): CombinatorShape<Task, D>;
 /**
@@ -3184,4 +3223,4 @@ declare function gitWorkspace(opts: GitWorkspaceOptions): Workspace;
  *  requires `jj` on the `Shell`'s host. */
 declare function jjWorkspace(opts: GitWorkspaceOptions): Workspace;
 
-export { Agent, AgentRunSpec, AgentSpec, type AgenticOptions, type AgenticRunResult, type AgenticSurface, type AgenticTask, type AgenticTool, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ArtifactHandle, type AssertTraceDerivedFindings, type AuditIntentInput, type AuditIntentOptions, type AuthorStrategyOptions, type AuthoredStrategy, type BenchmarkCell, type BenchmarkConfig, type BenchmarkLift, type BenchmarkReport, type BenchmarkStrategySummary, type BenchmarkTaskRow, type BridgeSeam, Budget, type BudgetPool, type BudgetReadout, type ChampionPick, type ChampionPolicy, type CheckpointCapableBox, type CliSeam, type CombinatorShape, type Corpus, type CorpusFilter, type CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, type DefinePersona, type DefinePersonaInput, type Deliverable, type Environment, type EqualKArm, type EqualKOnCost, type EqualKOnCostOptions, type EqualKVerdict, type EvolutionArchiveNode, type EvolutionAuthor, type EvolutionBandInfo, type EvolutionCandidate, type EvolutionGeneration, type EvolutionReport, ExecCtx, type ExecutorConfig, ExecutorFactory, ExecutorRegistry, type Fanout, type FanoutOptions, type FanoutSynthesis, FileCorpus, FileResultBlobStore, FileSpawnJournal, type FlatWidenGate, type ForkCapableBox, type GitWorkspaceOptions, type HarvestCorpusOptions, type HarvestFailure, type HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, InMemorySpawnJournal, type IntentAudit, Iteration, type LoopDispatchOptions, type LoopOptionsForDispatch, LoopResult, type LoopShape, LoopTokenUsage, type LoopUntil, type LoopUntilSpec, type LoopUntilState, type McpEndpoint, type McpEnvironmentOptions, NodeId, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunOptions, type Outcome, type Panel, type PanelJudge, type PanelSpec, type PanelVerdict, type Persona, type PersonaContext, type PersonaExecutors, type Pipeline, type PipelineStage, type PromotionGateOptions, type PromotionVerdict, type RenderCorpusToInstructions, type RenderCorpusToInstructionsOptions, type ReservationTicket, ResultBlobStore, RootHandle, type RouterChatResult, type RouterChatToolsResult, type RouterConfig, type RouterSeam, type RouterToolCall, type RouterToolLoopResult, type RouterToolsSeam, type RunAgenticOptions, RunLoopOptions, type RunPersonified, type RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, type SandboxSeam, Scope, type ScopeAnalyst, type ScopeAnalyzeInput, type ScopeWidenGate, type SessionCapableBox, Settled, type ShapeBudget, type ShapeContext, type ShapeRegistry, type Shell, type ShotPersona, type ShotSpec, SpawnEvent, SpawnJournal, Spend, type SteerContext, type Strategy, type StrategyCtx, type StrategyEvolutionConfig, type StrategyResult, SupervisedResult, Supervisor, type SurfaceScore, type ToolSpec, type TrajectoryNode, type TrajectoryReport, type TrajectoryReportFn, type TrajectoryReportOptions, TreeView, type TurnResult, UsageEvent, type UsageSink, type VerifierEnvironmentOptions, type Verify, type VerifySpec, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, type Widen, type WidenDecision, type WidenLineage, type WidenSpec, type Workspace, type WorkspaceCommit, acquireSandbox, adaptiveRefine, anytimeReport, assertStrategyContract, assertTraceDerivedFindings, auditIntent, authorStrategy, breadthDriver, buildSteerContext, builtinShapes, contentAddress, createBudgetPool, createExecutor, createExecutorRegistry, createMcpEnvironment, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, defaultAnalystInstruction, defaultAuditorInstruction, definePersona, defineStrategy, depthDriver, discriminatingMeans, equalKOnCost, extractLlmCallEvent, fanout, flatWidenGate, gitWorkspace, harvestCorpus, inlineSandboxClient, jjWorkspace, localShell, loopDispatch, loopUntil, mapSandboxEvent, materializeTreeView, observe, openSandboxRun, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, promotionGate, refine, registerShape, renderAnytimeTable, renderCorpusToInstructions, renderReport, replaySpawnTree, reportLoopUsage, routerChatWithTools, routerChatWithUsage, routerToolLoop, runAgentic, runBenchmark, runPersonified, runStrategyEvolution, sample, sampleThenRefine, selectChampion, settledToIteration, spendFromUsageEvents, strategyAuthorContract, trajectoryReport, verify, widen };
+export { Agent, AgentRunSpec, AgentSpec, type AgenticOptions, type AgenticRunResult, type AgenticSurface, type AgenticTask, type AgenticTool, type AnytimeReport, type AnytimeStrategySummary, type AnytimeTaskCurve, type ArtifactHandle, type AssertTraceDerivedFindings, type AuditIntentInput, type AuditIntentOptions, type AuthorStrategyOptions, type AuthoredStrategy, type BenchmarkCell, type BenchmarkConfig, type BenchmarkLift, type BenchmarkReport, type BenchmarkStrategySummary, type BenchmarkTaskRow, type BridgeSeam, Budget, type BudgetPool, type BudgetReadout, type ChampionPick, type ChampionPolicy, type CheckpointCapableBox, type CliSeam, type CombinatorShape, type Corpus, type CorpusFilter, type CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, type DefinePersona, type DefinePersonaInput, type Deliverable, type Environment, type EqualKArm, type EqualKOnCost, type EqualKOnCostOptions, type EqualKVerdict, type EvolutionArchiveNode, type EvolutionAuthor, type EvolutionBandInfo, type EvolutionCandidate, type EvolutionGeneration, type EvolutionReport, ExecCtx, type ExecutorConfig, ExecutorFactory, ExecutorRegistry, type Fanout, type FanoutOptions, type FanoutSynthesis, FileCorpus, FileResultBlobStore, FileSpawnJournal, type FlatWidenGate, type ForkCapableBox, type GitWorkspaceOptions, type HarvestCorpusOptions, type HarvestFailure, type HarvestReport, InMemoryCorpus, InMemoryResultBlobStore, InMemorySpawnJournal, type IntentAudit, Iteration, type LoopDispatchOptions, type LoopOptionsForDispatch, LoopResult, type LoopShape, LoopTokenUsage, type LoopUntil, type LoopUntilSpec, type LoopUntilState, type McpEndpoint, type McpEnvironmentOptions, NodeId, type Observation, type ObserveInput, type ObserveOptions, type OpenSandboxRunOptions, type Outcome, type Panel, type PanelJudge, type PanelSpec, type PanelVerdict, type Persona, type PersonaContext, type PersonaExecutors, type Pipeline, type PipelineStage, type PromotionGateOptions, type PromotionVerdict, type RegistryAnalyzeProjection, type RenderCorpusToInstructions, type RenderCorpusToInstructionsOptions, type ReservationTicket, ResultBlobStore, RootHandle, type RouterChatResult, type RouterChatToolsResult, type RouterConfig, type RouterSeam, type RouterToolCall, type RouterToolLoopResult, type RouterToolsSeam, type RunAgenticOptions, RunLoopOptions, type RunPersonified, type RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, type SandboxSeam, Scope, type ScopeAnalyst, type ScopeAnalyzeInput, type ScopeWidenGate, type SessionCapableBox, Settled, type ShapeBudget, type ShapeContext, type ShapeRegistry, type Shell, type ShotPersona, type ShotSpec, SpawnEvent, SpawnJournal, Spend, type SteerContext, type Strategy, type StrategyCtx, type StrategyEvolutionConfig, type StrategyResult, SupervisedResult, Supervisor, type SurfaceScore, type ToolSpec, type TrajectoryNode, type TrajectoryReport, type TrajectoryReportFn, type TrajectoryReportOptions, TreeView, type TurnResult, UsageEvent, type UsageSink, type VerifierEnvironmentOptions, type Verify, type VerifySpec, type WaterfallCollector, type WaterfallReport, type WaterfallSpan, type Widen, type WidenDecision, type WidenLineage, type WidenSpec, type Workspace, type WorkspaceCommit, acquireSandbox, adaptiveRefine, anytimeReport, assertStrategyContract, assertTraceDerivedFindings, auditIntent, authorStrategy, breadthDriver, buildSteerContext, builtinShapes, contentAddress, createBudgetPool, createExecutor, createExecutorRegistry, createMcpEnvironment, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, createVerifierEnvironment, createWaterfallCollector, defaultAnalystInstruction, defaultAuditorInstruction, definePersona, defineStrategy, depthDriver, discriminatingMeans, equalKOnCost, extractLlmCallEvent, fanout, flatWidenGate, gitWorkspace, harvestCorpus, inlineSandboxClient, jjWorkspace, localShell, loopDispatch, loopUntil, mapSandboxEvent, materializeTreeView, observe, openSandboxRun, panel, pickChampion, pipeline, printBenchmarkReport, probeSandboxCapabilities, promotionGate, refine, registerShape, registryScopeAnalyst, renderAnytimeTable, renderCorpusToInstructions, renderReport, replaySpawnTree, reportLoopUsage, routerChatWithTools, routerChatWithUsage, routerToolLoop, runAgentic, runBenchmark, runPersonified, runStrategyEvolution, sample, sampleThenRefine, selectChampion, settledToIteration, spendFromUsageEvents, strategyAuthorContract, trajectoryReport, verify, widen };

package/dist/runtime.js

@@ -60,6 +60,7 @@ import {
   promotionGate,
   refine,
   registerShape,
+  registryScopeAnalyst,
   renderAnalyses,
   renderAnytimeTable,
   renderCorpusToInstructions,
@@ -85,7 +86,7 @@ import {
   trajectoryReport,
   verify,
   widen
-} from "./chunk-FQH33M5N.js";
+} from "./chunk-2OU7ZQPD.js";
 import {
   extractLlmCallEvent,
   mapSandboxEvent
@@ -155,6 +156,7 @@ export {
   promotionGate,
   refine,
   registerShape,
+  registryScopeAnalyst,
   renderAnalyses,
   renderAnytimeTable,
   renderCorpusToInstructions,

package/dist/workflow.js

@@ -2,7 +2,7 @@ import {
   createSandboxForSpec,
   describeSandboxPlacement,
   runLoop
-} from "./chunk-FQH33M5N.js";
+} from "./chunk-2OU7ZQPD.js";
 import {
   ValidationError,
   extractLlmCallEvent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "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/agent-runtime-adoption/SKILL.md

@@ -35,14 +35,24 @@ A `Driver<Task, Output, Decision>` is just `plan(task, history) → Task[]`
 (`[task]`→refine, N copies→fanout, `[]`→stop) + `decide(history) → Decision`.
 Topology is data; the kernel is topology-agnostic.
 
-### Three shipped drivers — `@tangle-network/agent-runtime/loops`
-
-- **`createRefineDriver({ maxIterations?, refineTask? })`** — one task/iteration,
-  validator-gated; replay or rewrite the task until valid or capped. Use for
-  incremental patches, document revision, anything monotonic.
-- **`createFanoutVoteDriver({ n, selector? })`** — N parallel attempts in
-  iteration 0, score once, pick the winner (default: highest valid score). Use
-  for multi-harness coder fanout, redundant research with disagreement detection.
+### Topology drivers — `@tangle-network/agent-runtime/loops`
+
+> **Stale-name correction (gen-6 consolidation, #165):** the standalone
+> `createRefineDriver` / `createFanoutVoteDriver` factories were **removed** —
+> refine/fanout collapsed into the one recursive agent tree. Canonical today:
+> the personify combinators `loopUntil`(depth/refine) / `fanout`(breadth/vote)
+> and the `Strategy` values `refine` / `sample`, plus `createDriver` for an
+> agent-authored topology. Verify names in `src/runtime/index.ts`; see
+> `build-with-agent-runtime` + `docs/canonical-api.md` §3.1/§3.3 for the live
+> signatures. Likewise `createSandboxPlanner` is gone — pass a `TopologyPlanner`
+> to `createDriver({ planner })` directly.
+
+- **`refine` / `loopUntil`** — one attempt/round, validator-gated; iterate over
+  one evolving artifact until valid or budget-capped. Use for incremental
+  patches, document revision, anything monotonic. (Replaces `createRefineDriver`.)
+- **`sample` / `fanout`** — N attempts at equal budget, score once, pick the
+  winner via the single-sourced selector. Use for multi-harness coder fanout,
+  redundant research with disagreement detection. (Replaces `createFanoutVoteDriver`.)
 - **`createDriver({ planner, maxIterations?, maxFanout? })`** — **the
   agent authors the topology.** `plan`/`decide` are backed by an injected
   `TopologyPlanner` that emits one `TopologyMove` per round
@@ -56,16 +66,18 @@ round-robins `agentRuns[]` to decide which harness (claude-code / codex /
 opencode / pi) runs each branch. One driver spans all backends, including
 fanning a single round across several.
 
-### Wiring an LLM planner — `createSandboxPlanner`
+### Wiring an LLM planner — inject a `TopologyPlanner`
+
+`createDriver({ planner })` takes an injected `TopologyPlanner` (the standalone
+`createSandboxPlanner` factory was removed in the gen-6 consolidation — verify
+the live shape in `src/runtime/driver.ts` / `src/runtime/index.ts`). The planner
+is the brain (it may call any harness/LLM to author the move); the driver maps
+each `TopologyMove` onto kernel structure.
 
 ```ts
-import { createDriver, createSandboxPlanner, runLoop } from '@tangle-network/agent-runtime/loops'
+import { createDriver, runLoop, type TopologyPlanner } from '@tangle-network/agent-runtime/loops'
 
-const planner = createSandboxPlanner<Task, Out>({
-  client, profile: plannerProfile,          // any harness; cheap model is fine
-  decodeTask: (raw) => raw as Task,          // envelope task → domain Task
-  // buildPrompt?  — defaults to a history-summary prompt; override to customize
-})
+const planner: TopologyPlanner<Task, Out> = {/* plan() → one {kind:'refine'|'fanout'|'stop',…} per round */}
 const result = await runLoop({
   driver: createDriver({ planner, maxIterations: 8 }),
   agentRuns: workerSpecs, output, validator, task, ctx: { sandboxClient: client },
@@ -88,23 +100,25 @@ a topology nobody chose.
 - Dynamic driver: set the kernel's `runLoop` `maxIterations >=` the driver's so
   the driver's cap governs and the loop closes on a clean `'done'`.
 
-## Campaign bridge — `loopDispatch` / `loopCampaignDispatch`
+## Campaign bridge — `loopDispatch`
 
 To run `runLoop` as an agent-eval campaign cell, do NOT hand-build the ExecCtx +
 forward trace + report usage every time (the third is silent — forgetting it
-yields a `{0,0}` cell `assertRealBackend` reads as a stub). Use the adapter:
+yields a `{0,0}` cell `assertRealBackend` reads as a stub). Use the one bridge,
+`loopDispatch` (the old `loopCampaignDispatch` name was consolidated away; verify
+in `src/runtime/index.ts`):
 
 ```ts
-import { loopCampaignDispatch } from '@tangle-network/agent-runtime/loops'
-const dispatch = loopCampaignDispatch({
+import { loopDispatch } from '@tangle-network/agent-runtime/loops'
+const dispatch = loopDispatch({
   sandboxClient,
-  toLoopOptions: (scenario) => ({ driver, agentRun, output, validator, task: toTask(scenario) }),
+  toLoopOptions: (scenario, profile) => ({ driver, agentRun, output, validator, task: toTask(scenario) }),
   // toArtifact? — defaults to result.winner?.output
 })
 // pass `dispatch` to runCampaign / runEvalCampaign; usage + trace are auto-forwarded
 ```
 
-`loopDispatch` is the `runProfileMatrix` variant (profile is an axis).
+`loopDispatch` doubles as the `runProfileMatrix` variant (the `profile` arg is an axis).
 
 ## Identity-gated optimization — agent-eval's `selfImprove`
 
@@ -159,11 +173,12 @@ Mount it on a production `AgentProfile.mcp`; do not re-implement delegation.
 
 ## Acceptance checklist
 
-- [ ] Topology is a `Driver`, not hard-coded control flow. Reuse refine /
-      fanout-vote / dynamic; build a custom `Driver` against
-      `loops/types.ts:Driver` only when none fit — never fork the kernel.
-- [ ] `runLoop` is bridged to campaigns via `loopDispatch` / `loopCampaignDispatch`
-      (usage + trace auto-forwarded), not a hand-rolled ExecCtx.
+- [ ] Topology is a `Driver`/combinator, not hard-coded control flow. Reuse
+      `refine`/`loopUntil`, `sample`/`fanout`, or the agent-authored `createDriver`;
+      build a custom `Driver` against `loops/types.ts:Driver` only when none fit —
+      never fork the kernel.
+- [ ] `runLoop` is bridged to campaigns via `loopDispatch` (usage + trace
+      auto-forwarded), not a hand-rolled ExecCtx.
 - [ ] Every optimizable prompt is registered through `selfImprove` (or the
       product's existing `runImprovementLoop`), identity-gated on a held-out set.
 - [ ] Boundaries fail loud: no `null` sandbox client, no silent adapter return,

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

@@ -0,0 +1,143 @@
+---
+name: build-with-agent-runtime
+description: Use before hand-rolling a tool loop, driver, corpus, or optimizer wrapper. Create an agent genome, run it on a benchmark, optimize+gate it, observe/ship it with @tangle-network/agent-runtime. The genome→run→optimize→observe spine.
+---
+
+# build-with-agent-runtime
+
+The one create→run→optimize→observe seam for `@tangle-network/agent-runtime`. A
+**genome** (an `AgentProfile`/`AgentSurfaces` — systemPrompt + skills + tools +
+mcp + knowledge + memory + rag as ONE combined surface) runs as a
+**driver⟷worker** shape over a **benchmark**, gets **optimized by a gated loop**
+that evolves the genome and certifies wins on a **frozen holdout**, and is
+**observed** through the one lifecycle stream. The selector is never the judge;
+observation attaches to the loop, never to the portable genome.
+
+If you are about to write a `runConversation`, a "skill optimizer", a
+"profile-seam", a depth-vs-breadth A/B harness, a bootstrap loop, or a
+`new Sandbox(...)` + stream + read dance — **stop.** It exists, and a parallel
+silently breaks a load-bearing invariant (equal-k, selector≠judge,
+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
+corrected in place. Freezing a snippet here guarantees rot. Instead, read, in
+order, and re-verify against source:
+
+1. **`docs/canonical-api.md`** — the source of truth: the §2 decision table
+   ("I want to X → use Y → NOT Z"), §3 per-subsystem signatures (each cited
+   `file:line`), §4 the end-to-end recipe, §5 the recursive atom, §6 the
+   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`).
+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).
+
+**Code wins.** If a name, subpath, or signature here or in `docs/canonical-api.md`
+disagrees with source, the **source is right** — fix the map in the *same turn*
+(the anti-rediscovery law). Verify with Read/Edit, don't re-read to confirm.
+
+## Decision table — by altitude (each row → ONE source, not a snippet)
+
+Read the cited `docs/canonical-api.md` row before writing; it carries the live
+signature + the exact "do NOT build".
+
+| 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 |
+| **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 |
+| **Benchmark: compare strategies + significance + Pareto on a domain** | `runBenchmark({ environment, tasks, worker, strategies })` — `/loops` | canonical-api §3.3 |
+| **Benchmark: add/run an external benchmark from the harness** | `ADAPTERS`/`resolveAdapter(key)` + `runExperiment` — `bench` | canonical-api §3.3 |
+| **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 |
+| **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` / `createTopologyView` / `createOtelExporter` via `composeRuntimeHooks(...)` — root | canonical-api §3.5 |
+| **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) |
+
+## Do-NOT-reinvent — the traps this skill exists to stop
+
+Each of these gets hand-rolled every session; the canonical primitive already
+holds the load-bearing invariant the parallel breaks:
+
+- `runConversation` / persona-runner / `while(!done)` steering loop **≈**
+  `loopUntil` + `runPersonified` (threads executor seams; equal-k; selector≠judge
+  firewall; journal/replay — a parallel runner silently fails to wire the seams).
+- "skill optimizer" / "topology mutator" that opens branches + applies patches
+  **≈** `improvementDriver` (code surface) or `selfImprove`/`gepaDriver` (prompt
+  surface) — both gated on a frozen holdout.
+- "profile-seam" / agent-config wrapper carrying model+prompt+tools+role **≈**
+  `AgentProfile` (it IS that bundle) + `definePersona` (the run record);
+  `sandboxAgentRun({ profile })` is the box seam — never pass a router key into
+  the box.
+- `new Sandbox()` + acquire + stream + `box.fs.read` + delete **≈**
+  `openSandboxRun` (persistent + resume) or `runLoop` (fresh box/round).
+- `Promise.all` over N calls + manual argmax/merge **≈** `fanout` (bypassing the
+  budget pool breaks equal-compute claims).
+- a per-step cost/token tally over events **≈** `createWaterfallCollector` (the
+  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`).
+
+## End-to-end recipe
+
+`docs/canonical-api.md` §4 is the real composition — copy it from there, don't
+re-derive: **define a genome → run driver⟷worker via the reactive substrate over
+a multi-turn `AgenticSurface` → measure with `runBenchmark` → optimize a prompt
+surface with `selfImprove` → certify on a frozen holdout with the gate.** For the
+multi-generation flywheel, replace the measure/certify steps with one
+`runStrategyEvolution(...)` and read `report.verdict` (NOT `report.trajectory`)
+as the evidence. For a sandbox coding rollout judged by an external deterministic
+checker, use the bench path: `runExperiment({ adapter: resolveAdapter(...),
+sandboxClient, agentRun: sandboxAgentRun({ profile }), arms: [randomArm(...),
+analystArm(...)] })` — `arms[0]` is the mandatory equal-compute control.
+
+## Two substrates — pick one, don't invent a third
+
+Both implement the same recursive-decision atom over the one `Executor` port and
+share `defaultSelectWinner`. **Reactive** (`Supervisor`/`Scope` + personify
+combinators: `runPersonified`/`runAgentic`/`runBenchmark`) — prefer for NEW
+recursive work; equal-k by construction. **Round-synchronous** (`runLoop` +
+`createDriver`, `runExperiment`) — sandbox coding rollouts against external
+benchmarks. The full when-which map is `docs/canonical-api.md` §6.
+
+## Observe / ship with the Intelligence SDK
+
+One line wraps any agent with trace + billing boundary:
+`withTangleIntelligence(agent, { project, effort })`, `effort ∈
+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).
+
+## Final check
+
+- Picked a primitive from the decision table, not a hand-rolled parallel?
+- Genome is ONE `AgentProfile`/`AgentSurfaces` surface, not split skill/tool/prompt knobs?
+- Equal compute preserved (budget pool, or `arms[0]` control) — no `Promise.all` zoo?
+- Selector ≠ judge: no judge score feeding a driver/another judge; holdout score write-only?
+- Any win certified on a FROZEN holdout via a gate, never on the training composite?
+- Map fixed in the same turn if source disagreed with `docs/canonical-api.md`?
+
+See `_common.md` for shared conventions (frontmatter, fail-loud, no AI attribution).
+
+Next: build the genome/loop/optimizer against `docs/canonical-api.md` §3–§4; if a
+strategy beats incumbent on the holdout gate, `/ship` it.

package/skills/loop-writer/SKILL.md

@@ -24,7 +24,7 @@ The driver owns strategy.
 
 | Objective | Use |
 |---|---|
-| Try N attempts, pick best | `fanout` or `createFanoutVoteDriver` |
+| Try N attempts, pick best | `fanout` (or the `sample` strategy) |
 | Ordered stages | `pipeline` |
 | Improve until executable check passes | `loopUntil` + verifier |
 | Review from several lenses | `panel` |
@@ -138,16 +138,15 @@ Git is the durable workspace seam:
 - resume derives completion from git state, not only a side journal
 - conflicts become blockers/questions, not silent overwrite
 
-Proof command for the local substrate join:
+Proof command (real sandbox, real observe→steer join):
 
 ```bash
-pnpm exec tsx bench/src/observe-steer-workspace-loop.mts
+TANGLE_API_KEY=... pnpm exec tsx bench/src/cloud-loop.mts
 ```
 
-It proves `Scope.spawn -> coordination tools -> gitWorkspace -> observe ->
-Scope.send -> corrective worker -> integration pass`. Until the same proof runs
-with `openSandboxRun` and a remote branch, claim local substrate closure and
-serial git accumulation, not full cloud migration safety.
+It proves `openSandboxRun -> observe -> steer -> corrective worker` over a live
+sandbox. The old `observe-steer-workspace-loop.mts` used mock executors and is
+deleted — the live proof is the only valid one.
 
 ## Final Check