@tangle-network/agent-runtime 0.93.2 → 0.94.0

package/dist/{prepare-DiVGKcwS.d.ts → prepare-BKxAiUcH.d.ts}

@@ -715,4 +715,4 @@ interface PrepareAgentCandidateExecutionOptions {
 /** Materializes a verified candidate into one immutable evaluator-owned execution plan. */
 declare function prepareAgentCandidateExecution(candidate: VerifiedAgentCandidate, task: AgentCandidateTaskExecution, ports: AgentCandidateExecutionPorts, options?: PrepareAgentCandidateExecutionOptions): Promise<PreparedAgentCandidateExecution>;
 
-export { InMemoryAgentCandidateExecutionClaimStore as $, type AgentCandidateTaskExecution as A, type AgentCandidateExecutorProfileFile as B, type AgentCandidateExecutorRequest as C, type AgentCandidateExecutorStopRequest as D, type ExecutePreparedAgentCandidateOptions as E, type AgentCandidateExecutorTaskOutcomeCapture as F, type AgentCandidateExecutorWorkspaceFile as G, type AgentCandidateExecutorWorkspaceInput as H, type AgentCandidateMemoryPort as I, type AgentCandidateMemoryResetResult as J, type AgentCandidateModelLimits as K, type AgentCandidateModelPort as L, type AgentCandidateOutputArtifactPort as M, type AgentCandidateOutputPurpose as N, type AgentCandidateProtectedModelActivation as O, type PrepareAgentCandidateExecutionOptions as P, type AgentCandidateProtectedModelCall as Q, type AgentCandidateProtectedModelReservation as R, type AgentCandidateProtectedModelSettlement as S, type AgentCandidateProtectedRunCapture as T, type AgentCandidateRepositoryPort as U, type AgentCandidateRetryRejection as V, type AgentCandidateVerificationPorts as W, type AgentCandidateWorkspacePort as X, CANDIDATE_TRACE_ENV as Y, CANDIDATE_TRACE_TAGS as Z, type CanonicalCandidateDocument as _, type AgentCandidateExecutionPorts as a, type PreparedAgentCandidateExecution as a0, type PreparedAgentCandidateInstruction as a1, type PreparedAgentCandidateLaunch as a2, type PreparedAgentCandidateTrace as a3, type ResolvedAgentCandidateContainer as a4, type VerifiedAgentCandidate as a5, type VerifiedAgentCandidateTaskOutcome as a6, executePreparedAgentCandidate as a7, prepareAgentCandidateExecution as a8, sealAgentCandidateBundle as a9, type AgentCandidateRunFinalization as b, type AgentCandidateBundleInput as c, type AgentCandidateArtifactPort as d, type AgentCandidateBenchmarkGraderIdentity as e, type AgentCandidateBenchmarkGraderPort as f, type AgentCandidateContainerPort as g, type AgentCandidateExecutionAttemptRecord as h, type AgentCandidateExecutionAttemptRef as i, type AgentCandidateExecutionClaim as j, type AgentCandidateExecutionClaimResult as k, type AgentCandidateExecutionClaimStore as l, type AgentCandidateExecutionCleanupHandles as m, type AgentCandidateExecutionFailureClass as n, type AgentCandidateExecutionFinishResult as o, type AgentCandidateExecutionLease as p, type AgentCandidateExecutionPhase as q, type AgentCandidateExecutionPhaseResult as r, type AgentCandidateExecutionRecoveryEvidence as s, type AgentCandidateExecutionStageResult as t, type AgentCandidateExecutionTerminalRecord as u, type AgentCandidateExecutionTerminalResult as v, type AgentCandidateExecutionUsage as w, type AgentCandidateExecutorFinalCapture as x, type AgentCandidateExecutorMemoryCapture as y, type AgentCandidateExecutorPort as z };
+export { InMemoryAgentCandidateExecutionClaimStore as $, type AgentCandidateBundleInput as A, type AgentCandidateExecutorProfileFile as B, type AgentCandidateExecutorRequest as C, type AgentCandidateExecutorStopRequest as D, type ExecutePreparedAgentCandidateOptions as E, type AgentCandidateExecutorTaskOutcomeCapture as F, type AgentCandidateExecutorWorkspaceFile as G, type AgentCandidateExecutorWorkspaceInput as H, type AgentCandidateMemoryPort as I, type AgentCandidateMemoryResetResult as J, type AgentCandidateModelLimits as K, type AgentCandidateModelPort as L, type AgentCandidateOutputArtifactPort as M, type AgentCandidateOutputPurpose as N, type AgentCandidateProtectedModelActivation as O, type PrepareAgentCandidateExecutionOptions as P, type AgentCandidateProtectedModelCall as Q, type AgentCandidateProtectedModelReservation as R, type AgentCandidateProtectedModelSettlement as S, type AgentCandidateProtectedRunCapture as T, type AgentCandidateRepositoryPort as U, type AgentCandidateRetryRejection as V, type AgentCandidateVerificationPorts as W, type AgentCandidateWorkspacePort as X, CANDIDATE_TRACE_ENV as Y, CANDIDATE_TRACE_TAGS as Z, type CanonicalCandidateDocument as _, type AgentCandidateTaskExecution as a, type PreparedAgentCandidateExecution as a0, type PreparedAgentCandidateInstruction as a1, type PreparedAgentCandidateLaunch as a2, type PreparedAgentCandidateTrace as a3, type ResolvedAgentCandidateContainer as a4, type VerifiedAgentCandidate as a5, type VerifiedAgentCandidateTaskOutcome as a6, executePreparedAgentCandidate as a7, prepareAgentCandidateExecution as a8, sealAgentCandidateBundle as a9, type AgentCandidateExecutionPorts as b, type AgentCandidateRunFinalization as c, type AgentCandidateArtifactPort as d, type AgentCandidateBenchmarkGraderIdentity as e, type AgentCandidateBenchmarkGraderPort as f, type AgentCandidateContainerPort as g, type AgentCandidateExecutionAttemptRecord as h, type AgentCandidateExecutionAttemptRef as i, type AgentCandidateExecutionClaim as j, type AgentCandidateExecutionClaimResult as k, type AgentCandidateExecutionClaimStore as l, type AgentCandidateExecutionCleanupHandles as m, type AgentCandidateExecutionFailureClass as n, type AgentCandidateExecutionFinishResult as o, type AgentCandidateExecutionLease as p, type AgentCandidateExecutionPhase as q, type AgentCandidateExecutionPhaseResult as r, type AgentCandidateExecutionRecoveryEvidence as s, type AgentCandidateExecutionStageResult as t, type AgentCandidateExecutionTerminalRecord as u, type AgentCandidateExecutionTerminalResult as v, type AgentCandidateExecutionUsage as w, type AgentCandidateExecutorFinalCapture as x, type AgentCandidateExecutorMemoryCapture as y, type AgentCandidateExecutorPort as z };

package/dist/profiles.d.ts

@@ -1,7 +1,7 @@
 import { a as UiFinding, U as UiLens } from './substrate-DO2GHNg2.js';
 export { C as CoderTask, b as UI_FINDING_SEVERITIES, c as UI_LENSES, d as UiFindingScreenshot, e as UiFindingSeverity, f as coderTaskToPrompt } from './substrate-DO2GHNg2.js';
 import { AgentProfile, SandboxEvent } from '@tangle-network/sandbox';
-import { V as Validator, e as AgentRunSpec, d as OutputAdapter, D as Driver, S as SandboxClient } from './types-B00NtbCs.js';
+import { V as Validator, d as AgentRunSpec, c as OutputAdapter, D as Driver, S as SandboxClient } from './types-DWA64rbJ.js';
 import { AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
 import '@tangle-network/agent-eval';
 

package/dist/{sanitize-C9go6tXj.d.ts → sanitize-C2jicjNf.d.ts}

@@ -1,5 +1,5 @@
 import { ControlEvalResult, KnowledgeReadinessReport, KnowledgeRequirement } from '@tangle-network/agent-eval';
-import { A as AgentRuntimeEvent, b as RuntimeStreamEvent, c as AgentTaskStatus } from './types-B00NtbCs.js';
+import { A as AgentRuntimeEvent, a as RuntimeStreamEvent, b as AgentTaskStatus } from './types-DWA64rbJ.js';
 
 /**
  * THE canonical agentic tool-loop. One inference turn → run any requested tools → fold the

package/dist/{supervise-T2pazU3G.d.ts → supervise-Gmf709kn.d.ts}

@@ -1,7 +1,7 @@
-import { S as Scope, a as ResultBlobStore, B as Budget, A as Agent, b as SupervisedResult } from './types-DAdIm4AC.js';
-import { M as MakeWorkerAgent, A as AnalystRegistry, E as ExecutorConfig } from './coordination-DxJ83oZA.js';
-import { R as RouterConfig, T as ToolLoopChat, a as ToolLoopCompactionOptions } from './sanitize-C9go6tXj.js';
-import { D as DeliverableSpec } from './completion-gate-BLaiN0-X.js';
+import { S as Scope, a as ResultBlobStore, B as Budget, A as Agent, b as SupervisedResult } from './types-Cg_teUPO.js';
+import { M as MakeWorkerAgent, A as AnalystRegistry, E as ExecutorConfig } from './coordination-EGoRbbsd.js';
+import { R as RouterConfig, T as ToolLoopChat, a as ToolLoopCompactionOptions } from './sanitize-C2jicjNf.js';
+import { D as DeliverableSpec } from './completion-gate-BDkEYB_-.js';
 
 /** The supervisor's profile — the subset of an `AgentProfile` that selects + shapes its brain.
  *  `harness` is the backend-as-data discriminant; `systemPrompt` is the standing instruction. */

package/dist/{types-DAdIm4AC.d.ts → types-Cg_teUPO.d.ts}

@@ -1,7 +1,7 @@
 import { DefaultVerdict } from '@tangle-network/agent-eval';
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { BackendType } from '@tangle-network/sandbox';
-import { L as LoopTokenUsage, R as RuntimeHooks } from './types-B00NtbCs.js';
+import { L as LoopTokenUsage, R as RuntimeHooks } from './types-DWA64rbJ.js';
 
 /**
  *
@@ -494,4 +494,4 @@ interface WidenGate<Out> {
     readonly judgeExempt?: boolean;
 }
 
-export type { Agent as A, Budget as B, ExecutorFactory as E, NodeId as N, Runtime as R, Scope as S, TreeView as T, UsageEvent as U, WidenGate as W, ResultBlobStore as a, SupervisedResult as b, Executor as c, Settled as d, Spend as e, AgentSpec as f, SpawnJournal as g, ExecutorRegistry as h, RootHandle as i, SpawnEvent as j, Supervisor as k, ExecutorContext as l, ExecutorResult as m, SupervisorOpts as n };
+export type { Agent as A, Budget as B, ExecutorFactory as E, NodeId as N, Runtime as R, Scope as S, TreeView as T, UsageEvent as U, WidenGate as W, ResultBlobStore as a, SupervisedResult as b, Executor as c, AgentSpec as d, ExecutorRegistry as e, SpawnJournal as f, RootHandle as g, Settled as h, Spend as i, SpawnEvent as j, Supervisor as k, ExecutorContext as l, ExecutorResult as m, SupervisorOpts as n };

package/dist/{types-B00NtbCs.d.ts → types-DWA64rbJ.d.ts}

@@ -1308,4 +1308,4 @@ interface ExecCtx {
     parentSpanId?: string;
 }
 
-export { type MountRecorder as $, type AgentRuntimeEvent as A, type BackendErrorDetail as B, type RuntimeHookContext as C, type Driver as D, type ExecCtx as E, type RuntimeHookErrorContext as F, type RuntimeHookEvent as G, type RuntimeHookPhase as H, type Iteration as I, type RuntimeHookTarget as J, type KnowledgeReadinessDecision as K, type LoopTokenUsage as L, type RuntimeRunHandle as M, type RuntimeRunPersistenceAdapter as N, type OpenAIChatTool as O, type RuntimeRunRow as P, composeRuntimeHooks as Q, type RuntimeHooks as R, type SandboxClient as S, defineRuntimeHooks as T, notifyRuntimeDecisionPoint as U, type Validator as V, notifyRuntimeHookEvent as W, startRuntimeRun as X, type LoopWinner as Y, type LoopLineageOptions as Z, type LoopResult as _, type SelectionReceipt as a, type LoopDecisionPayload as a0, type LoopEndedPayload as a1, type LoopIterationDispatchPayload as a2, type LoopIterationEndedPayload as a3, type LoopIterationStartedPayload as a4, type LoopPlanDescription as a5, type LoopPlanPayload as a6, type LoopStartedPayload as a7, type LoopTeardownFailedPayload as a8, type MountManifestEntry as a9, type RunProvenance as aa, type ValidationCtx as ab, type RuntimeStreamEvent as b, type AgentTaskStatus as c, type OutputAdapter as d, type AgentRunSpec as e, type LoopSandboxPlacement as f, type LoopTraceEvent as g, type LoopTraceEmitter as h, type AgentBackendInput as i, type OpenAIChatToolChoice as j, type OpenAIChatResponseFormat as k, type AgentExecutionBackend as l, type AgentBackendContext as m, type RunAgentTaskOptions as n, type AgentTaskRunResult as o, type RunAgentTaskStreamOptions as p, type RuntimeSessionStore as q, type RuntimeSession as r, type AgentAdapter as s, type AgentKnowledgeProvider as t, type AgentRuntimeEventSink as u, type AgentTaskContext as v, type AgentTaskSpec as w, type RuntimeDecisionEvidenceRef as x, type RuntimeDecisionKind as y, type RuntimeDecisionPoint as z };
+export { type SelectionReceipt as $, type AgentRuntimeEvent as A, type BackendErrorDetail as B, type RuntimeHookErrorContext as C, type Driver as D, type ExecCtx as E, type RuntimeHookEvent as F, type RuntimeHookPhase as G, type RuntimeHookTarget as H, type Iteration as I, type RuntimeRunHandle as J, type KnowledgeReadinessDecision as K, type LoopTokenUsage as L, type RuntimeRunPersistenceAdapter as M, type RuntimeRunRow as N, type OpenAIChatTool as O, composeRuntimeHooks as P, defineRuntimeHooks as Q, type RuntimeHooks as R, type SandboxClient as S, notifyRuntimeDecisionPoint as T, notifyRuntimeHookEvent as U, type Validator as V, startRuntimeRun as W, type LoopWinner as X, type LoopLineageOptions as Y, type LoopResult as Z, type MountRecorder as _, type RuntimeStreamEvent as a, type LoopDecisionPayload as a0, type LoopEndedPayload as a1, type LoopIterationDispatchPayload as a2, type LoopIterationEndedPayload as a3, type LoopIterationStartedPayload as a4, type LoopPlanDescription as a5, type LoopPlanPayload as a6, type LoopStartedPayload as a7, type LoopTeardownFailedPayload as a8, type MountManifestEntry as a9, type RunProvenance as aa, type ValidationCtx as ab, type AgentTaskStatus as b, type OutputAdapter as c, type AgentRunSpec as d, type LoopSandboxPlacement as e, type LoopTraceEvent as f, type LoopTraceEmitter as g, type AgentBackendInput as h, type OpenAIChatToolChoice as i, type OpenAIChatResponseFormat as j, type AgentExecutionBackend as k, type AgentBackendContext as l, type RunAgentTaskOptions as m, type AgentTaskRunResult as n, type RunAgentTaskStreamOptions as o, type RuntimeSessionStore as p, type RuntimeSession as q, type AgentAdapter as r, type AgentKnowledgeProvider as s, type AgentRuntimeEventSink as t, type AgentTaskContext as u, type AgentTaskSpec as v, type RuntimeDecisionEvidenceRef as w, type RuntimeDecisionKind as x, type RuntimeDecisionPoint as y, type RuntimeHookContext as z };

package/dist/{worktree-fanout-BUb2Ag02.d.ts → worktree-fanout-BrB4att3.d.ts}

@@ -1,11 +1,240 @@
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { AnalystFinding, DefaultVerdict } from '@tangle-network/agent-eval';
-import { N as NodeId, d as Settled, e as Spend, f as AgentSpec, S as Scope, g as SpawnJournal, a as ResultBlobStore, h as ExecutorRegistry, B as Budget, A as Agent, i as RootHandle, b as SupervisedResult, c as Executor } from './types-DAdIm4AC.js';
-import { I as Iteration, R as RuntimeHooks } from './types-B00NtbCs.js';
+import { d as AgentSpec, e as ExecutorRegistry, B as Budget, A as Agent, f as SpawnJournal, a as ResultBlobStore, g as RootHandle, b as SupervisedResult, N as NodeId, h as Settled, i as Spend, S as Scope, c as Executor } from './types-Cg_teUPO.js';
+import { R as RuntimeHooks, I as Iteration } from './types-DWA64rbJ.js';
 import { BackendType } from '@tangle-network/sandbox';
-import { W as WorktreeHarnessResult, G as GitRunner, a as WorktreeCheckRunner, D as DeliverableSpec } from './completion-gate-BLaiN0-X.js';
+import { W as WorktreeHarnessResult, G as GitRunner, a as WorktreeCheckRunner, D as DeliverableSpec } from './completion-gate-BDkEYB_-.js';
 import { L as LocalHarness, r as runLocalHarness } from './local-harness-dcD5WTTr.js';
 
+/**
+ *
+ * The personify layer — the "act like X" knob on top of the recursive keystone.
+ *
+ * The keystone (`src/loops/supervise/`) is pure STRUCTURE: a recursive `Agent` atom inside
+ * a budget-conserving `Scope`, an `ExecutorRegistry` mapping an `AgentSpec` to a runtime,
+ * and a `Supervisor` that runs a root agent to a typed `SupervisedResult`. It carries no
+ * CONTENT — no model, no prompt, no goal framing, no notion of "who this loop is".
+ *
+ * This layer adds exactly that content seam without inventing a second engine:
+ *  - A `Persona` is a thin record: the root `AgentSpec` (profile + harness + optional BYO
+ *    executor), a root `directive` (the goal framing handed to the chosen shape), a
+ *    `context` blob (who the loop is acting as), and the executor seams the registry needs.
+ *    `definePersona` builds it; it is data, not behavior.
+ *  - A `LoopShape` is a reusable act-body FACTORY: `(ctx: ShapeContext) => Agent`. The shape
+ *    owns the STRUCTURE (how to decompose / fan out / verify / synthesize); the persona's
+ *    content parameterizes it. A new shape is ONE file + one `registerShape` call.
+ *  - `Outcome<D>` is the contract every shape synthesizes into: a finished deliverable OR a
+ *    list of concrete blockers — "100% done or 100%-defined blockers", never a vague middle.
+ *
+ * Layering: this module imports ONLY keystone runtime types (`./supervise/types`) and the
+ * substrate `AgentProfile`/`BackendType`. It typechecks standalone — no impl, no engine.
+ * Extensibility is structural: `Persona` carries an open `extensions` bag so a later
+ * world-model / memory field is additive (a new optional key), never a breaking change.
+ *
+ * @experimental
+ */
+
+/**
+ * The terminal contract Drew wants: a loop returns a FINISHED deliverable, or the concrete
+ * list of blockers that stopped it — never a half-done best-effort coercion. A `blocked`
+ * outcome with an empty `blockers` list is a contract violation (a shape that can't finish
+ * MUST name why); impls fail loud on it rather than emitting a vacuous block.
+ *
+ * `Outcome` is the `Out` type a personified `Agent`/`Supervisor` is parameterized by, so the
+ * keystone's typed `SupervisedResult<Outcome<D>>` carries it end to end with no coercion.
+ */
+type Outcome<D> = {
+    kind: 'done';
+    deliverable: D;
+} | {
+    kind: 'blocked';
+    blockers: string[];
+};
+/**
+ * The "act like X" record. A thin composition over the keystone's `AgentSpec`: it pairs the
+ * root spec (the executor mapping for the root agent the shape builds) with the CONTENT a
+ * shape consumes — the goal framing (`directive`) and who the loop is acting as (`context`).
+ *
+ * The framework never reads `directive`/`context` semantically; it threads them to the shape
+ * verbatim through `ShapeContext`. This is the rule the mandate names: the FRAMEWORK is
+ * structure, the PERSONA carries model/prompt/tools/directive. No model name, prompt, or
+ * persona string is ever hardcoded in a shape or the engine.
+ *
+ * `D` is the deliverable type this persona's loops produce; it flows into `Outcome<D>`.
+ */
+interface Persona<D = unknown> {
+    /** Stable persona name — used as the trace/journal label root, never as content. */
+    readonly name: string;
+    /**
+     * The root agent's executor mapping (profile + harness + optional BYO executor). The
+     * shape's root `Agent` carries THIS as its `executorSpec`; child specs the shape spawns
+     * are derived from / resolved against the same persona registry (see `ShapeContext`).
+     */
+    readonly root: AgentSpec;
+    /** The goal framing handed to the shape — the "what to achieve", not "how". */
+    readonly directive: string;
+    /** Who the loop is acting as — the opaque persona context blob the shape may inject into
+     *  child tasks. Opaque to the framework; only the persona's profiles/prompts interpret it. */
+    readonly context: PersonaContext;
+    /**
+     * The executor seams (router endpoint+key, sandbox client, cli bin) the built-in runtimes
+     * read off `ExecutorContext.seams`, OR a fully pre-configured registry. The supervisor
+     * threads an EMPTY seam bag to the root scope, so a persona that uses built-in metered
+     * runtimes MUST supply a registry whose factories close over their seams (or BYO executors
+     * on each `AgentSpec`). Carried here so `runPersonified` can build `SupervisorOpts.executors`.
+     */
+    readonly executors: PersonaExecutors;
+    /**
+     * Forward-compatible extension bag — a later world-model / memory / tool-budget field is an
+     * additive key here, never a breaking change to the `Persona` shape. Opaque to the engine.
+     */
+    readonly extensions?: Readonly<Record<string, unknown>>;
+    /** Phantom: binds the persona to its deliverable type so `runPersonified` infers `D` from
+     *  the persona and the chosen shape must agree. Type-only — never present at runtime. */
+    readonly __deliverable?: D;
+}
+/** The persona context blob — who the loop is acting as. Open by intent: a persona names its
+ *  own role/audience/constraints; the framework treats it as opaque content. */
+interface PersonaContext {
+    /** The role the loop embodies ("senior staff engineer", "equity research analyst", …). */
+    readonly role: string;
+    /** Optional freeform framing the persona's prompts/profiles consume. */
+    readonly notes?: string;
+    /** Open content bag — persona-specific fields a shape's child tasks may carry. */
+    readonly [key: string]: unknown;
+}
+/**
+ * How a persona supplies executor resolution. Either a pre-built registry (factories already
+ * closed over their seams) OR the raw seam bag the engine uses to construct a registry +
+ * thread the seams onto each spawn. Exactly one is required — fail loud if neither is set.
+ */
+interface PersonaExecutors {
+    /** A registry whose factories already capture their seams. Highest precedence. */
+    readonly registry?: ExecutorRegistry;
+    /** Raw seams to thread onto built-in runtimes (`router`/`sandbox`/`cli` keys). */
+    readonly seams?: Readonly<Record<string, unknown>>;
+}
+/** The minimal input to build a `Persona`. Mirrors `Persona` but lets the builder default
+ *  the executors-supplied invariant check and freeze the record. */
+interface DefinePersonaInput<D = unknown> {
+    readonly name: string;
+    readonly root: AgentSpec;
+    readonly directive: string;
+    readonly context: PersonaContext;
+    readonly executors: PersonaExecutors;
+    readonly extensions?: Readonly<Record<string, unknown>>;
+    /** Phantom: pins the input's deliverable type so `definePersona<D>` returns a `Persona<D>`
+     *  the caller's shape must agree with. Type-only — never supplied at a call site. */
+    readonly __deliverable?: D;
+}
+/** Builds a frozen `Persona`, failing loud on the executors-supplied invariant (neither a
+ *  registry nor seams = an unresolvable persona). Pure — no I/O, no engine. */
+type DefinePersona = <D = unknown>(input: DefinePersonaInput<D>) => Persona<D>;
+/**
+ * Budget knobs a shape reads to size its fanout/children WITHOUT owning the conserved pool.
+ * The root budget lives on `SupervisorOpts.budget`; the shape only needs the per-child
+ * sizing hints + the fanout width it is allowed to open. All ceilings — the pool reserves
+ * against them and fails closed, so an over-eager shape can never overspend.
+ */
+interface ShapeBudget {
+    /** Per-child spawn budget the shape reserves for each leaf/sub-loop it opens. */
+    readonly perChild: Budget;
+    /** Max children a fanout step may open in one round (the shape's structural width). */
+    readonly fanout: number;
+}
+/**
+ * The construction context a `LoopShape` factory receives. Carries the persona's resolved
+ * executor seams + the budget knobs, plus the ONE helper a shape needs to spawn a child
+ * through the keystone: `spawnChild` resolves an `AgentSpec` (or a persona-derived child
+ * profile) into an `Agent` the shape hands to `scope.spawn`. The shape never touches the
+ * registry directly — it asks the context, keeping resolution single-sourced.
+ */
+interface ShapeContext<D = unknown> {
+    readonly persona: Persona<D>;
+    readonly budget: ShapeBudget;
+    /**
+     * Wrap an `AgentSpec` into a leaf `Agent` carrying it as `executorSpec`, so the shape can
+     * `scope.spawn(spawnChild(spec), task, opts)`. `name` labels the child for traces. The
+     * returned agent's `act` is never invoked by the keystone (it is spawned, not run) — the
+     * spec drives the resolved `Executor`; `act` exists only to satisfy the `Agent` shape.
+     */
+    spawnChild(name: string, spec: AgentSpec): Agent<unknown, Outcome<D>>;
+    /** 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
+ * returns the root `Agent<Task, Outcome<D>>` whose `act` decomposes the task, fans out
+ * children through `scope.spawn`, verifies/selects across their settlements (selector≠judge:
+ * via `settledToIteration` + `defaultSelectWinner`, never re-ranking behind the driver), and
+ * synthesizes the terminal `Outcome<D>`. The shape is STRUCTURE; the persona is CONTENT.
+ */
+type LoopShape<Task, D> = (ctx: ShapeContext<D>) => Agent<Task, Outcome<D>>;
+/**
+ * The open shape registry — the extension point that makes a new loop-shape ONE file + one
+ * `registerShape` call with zero edits elsewhere. `resolve` returns a typed outcome (inspect
+ * `succeeded` before `value`); `register` fails loud on a duplicate name.
+ */
+interface ShapeRegistry {
+    register<Task, D>(name: string, factory: LoopShape<Task, D>): void;
+    resolve<Task, D>(name: string): {
+        succeeded: true;
+        value: LoopShape<Task, D>;
+    } | {
+        succeeded: false;
+        error: string;
+    };
+    /** The registered shape names — for diagnostics + a fail-loud "unknown shape" message. */
+    names(): string[];
+}
+/**
+ * The end-to-end entrypoint. Builds the persona's root `Agent` from the chosen shape, then
+ * runs it through a fresh `createSupervisor` over the persona's executors + the supplied
+ * budget/journal/blobs. Returns the keystone's typed `SupervisedResult<Outcome<D>>` — a
+ * `winner` carries the synthesized `Outcome<D>`; a `no-winner` is never coerced into one.
+ *
+ * `shape` is either a resolved `LoopShape` or a registered shape NAME (resolved through the
+ * default registry). The journal/blobs default to in-memory impls in the engine when omitted
+ * (durable FS impls are passed explicitly for a persisted run).
+ */
+interface RunPersonifiedOptions<Task, D> {
+    readonly persona: Persona<D>;
+    /** A resolved shape factory OR a registered shape name. */
+    readonly shape: LoopShape<Task, D> | string;
+    readonly task: Task;
+    readonly budget: Budget;
+    /** Per-child sizing + fanout width handed to the shape. Defaults derive from `budget`. */
+    readonly shapeBudget?: Partial<ShapeBudget>;
+    /** Trace/journal root key. Defaults to the persona name + a run discriminator in the engine. */
+    readonly runId?: string;
+    readonly journal?: SpawnJournal;
+    readonly blobs?: ResultBlobStore;
+    /** Runtime recursion-depth ceiling, paired with the conserved pool. */
+    readonly maxDepth?: number;
+    /** OTP intensity breaker bounds, forwarded to the supervisor verbatim. */
+    readonly maxRestarts?: number;
+    readonly withinMs?: number;
+    /** A live root handle to attach (view/signal/abort) before the run starts. */
+    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>;
+    /**
+     * Lifecycle stream sink, forwarded to `SupervisorOpts.hooks` so the root `Scope`'s
+     * `agent.spawn`/`agent.child` events flow to an observer (e.g. the Intelligence SDK's
+     * trace export). Absent ⇒ no stream (the run is silent, as today).
+     */
+    readonly hooks?: RuntimeHooks;
+}
+/** The composed run signature. */
+type RunPersonified = <Task, D>(options: RunPersonifiedOptions<Task, D>) => Promise<SupervisedResult<Outcome<D>>>;
+
 /**
  *
  * The RSI-wave type surface — the FROZEN contracts the wave's Core + Compose build to.
@@ -538,235 +767,6 @@ interface EqualKOnCostOptions {
 /** `equalKOnCost(arms, opts)` — the cross-arm equal-compute check on conserved cost. */
 type EqualKOnCost = (arms: ReadonlyArray<EqualKArm>, options?: EqualKOnCostOptions) => EqualKVerdict;
 
-/**
- *
- * The personify layer — the "act like X" knob on top of the recursive keystone.
- *
- * The keystone (`src/loops/supervise/`) is pure STRUCTURE: a recursive `Agent` atom inside
- * a budget-conserving `Scope`, an `ExecutorRegistry` mapping an `AgentSpec` to a runtime,
- * and a `Supervisor` that runs a root agent to a typed `SupervisedResult`. It carries no
- * CONTENT — no model, no prompt, no goal framing, no notion of "who this loop is".
- *
- * This layer adds exactly that content seam without inventing a second engine:
- *  - A `Persona` is a thin record: the root `AgentSpec` (profile + harness + optional BYO
- *    executor), a root `directive` (the goal framing handed to the chosen shape), a
- *    `context` blob (who the loop is acting as), and the executor seams the registry needs.
- *    `definePersona` builds it; it is data, not behavior.
- *  - A `LoopShape` is a reusable act-body FACTORY: `(ctx: ShapeContext) => Agent`. The shape
- *    owns the STRUCTURE (how to decompose / fan out / verify / synthesize); the persona's
- *    content parameterizes it. A new shape is ONE file + one `registerShape` call.
- *  - `Outcome<D>` is the contract every shape synthesizes into: a finished deliverable OR a
- *    list of concrete blockers — "100% done or 100%-defined blockers", never a vague middle.
- *
- * Layering: this module imports ONLY keystone runtime types (`./supervise/types`) and the
- * substrate `AgentProfile`/`BackendType`. It typechecks standalone — no impl, no engine.
- * Extensibility is structural: `Persona` carries an open `extensions` bag so a later
- * world-model / memory field is additive (a new optional key), never a breaking change.
- *
- * @experimental
- */
-
-/**
- * The terminal contract Drew wants: a loop returns a FINISHED deliverable, or the concrete
- * list of blockers that stopped it — never a half-done best-effort coercion. A `blocked`
- * outcome with an empty `blockers` list is a contract violation (a shape that can't finish
- * MUST name why); impls fail loud on it rather than emitting a vacuous block.
- *
- * `Outcome` is the `Out` type a personified `Agent`/`Supervisor` is parameterized by, so the
- * keystone's typed `SupervisedResult<Outcome<D>>` carries it end to end with no coercion.
- */
-type Outcome<D> = {
-    kind: 'done';
-    deliverable: D;
-} | {
-    kind: 'blocked';
-    blockers: string[];
-};
-/**
- * The "act like X" record. A thin composition over the keystone's `AgentSpec`: it pairs the
- * root spec (the executor mapping for the root agent the shape builds) with the CONTENT a
- * shape consumes — the goal framing (`directive`) and who the loop is acting as (`context`).
- *
- * The framework never reads `directive`/`context` semantically; it threads them to the shape
- * verbatim through `ShapeContext`. This is the rule the mandate names: the FRAMEWORK is
- * structure, the PERSONA carries model/prompt/tools/directive. No model name, prompt, or
- * persona string is ever hardcoded in a shape or the engine.
- *
- * `D` is the deliverable type this persona's loops produce; it flows into `Outcome<D>`.
- */
-interface Persona<D = unknown> {
-    /** Stable persona name — used as the trace/journal label root, never as content. */
-    readonly name: string;
-    /**
-     * The root agent's executor mapping (profile + harness + optional BYO executor). The
-     * shape's root `Agent` carries THIS as its `executorSpec`; child specs the shape spawns
-     * are derived from / resolved against the same persona registry (see `ShapeContext`).
-     */
-    readonly root: AgentSpec;
-    /** The goal framing handed to the shape — the "what to achieve", not "how". */
-    readonly directive: string;
-    /** Who the loop is acting as — the opaque persona context blob the shape may inject into
-     *  child tasks. Opaque to the framework; only the persona's profiles/prompts interpret it. */
-    readonly context: PersonaContext;
-    /**
-     * The executor seams (router endpoint+key, sandbox client, cli bin) the built-in runtimes
-     * read off `ExecutorContext.seams`, OR a fully pre-configured registry. The supervisor
-     * threads an EMPTY seam bag to the root scope, so a persona that uses built-in metered
-     * runtimes MUST supply a registry whose factories close over their seams (or BYO executors
-     * on each `AgentSpec`). Carried here so `runPersonified` can build `SupervisorOpts.executors`.
-     */
-    readonly executors: PersonaExecutors;
-    /**
-     * Forward-compatible extension bag — a later world-model / memory / tool-budget field is an
-     * additive key here, never a breaking change to the `Persona` shape. Opaque to the engine.
-     */
-    readonly extensions?: Readonly<Record<string, unknown>>;
-    /** Phantom: binds the persona to its deliverable type so `runPersonified` infers `D` from
-     *  the persona and the chosen shape must agree. Type-only — never present at runtime. */
-    readonly __deliverable?: D;
-}
-/** The persona context blob — who the loop is acting as. Open by intent: a persona names its
- *  own role/audience/constraints; the framework treats it as opaque content. */
-interface PersonaContext {
-    /** The role the loop embodies ("senior staff engineer", "equity research analyst", …). */
-    readonly role: string;
-    /** Optional freeform framing the persona's prompts/profiles consume. */
-    readonly notes?: string;
-    /** Open content bag — persona-specific fields a shape's child tasks may carry. */
-    readonly [key: string]: unknown;
-}
-/**
- * How a persona supplies executor resolution. Either a pre-built registry (factories already
- * closed over their seams) OR the raw seam bag the engine uses to construct a registry +
- * thread the seams onto each spawn. Exactly one is required — fail loud if neither is set.
- */
-interface PersonaExecutors {
-    /** A registry whose factories already capture their seams. Highest precedence. */
-    readonly registry?: ExecutorRegistry;
-    /** Raw seams to thread onto built-in runtimes (`router`/`sandbox`/`cli` keys). */
-    readonly seams?: Readonly<Record<string, unknown>>;
-}
-/** The minimal input to build a `Persona`. Mirrors `Persona` but lets the builder default
- *  the executors-supplied invariant check and freeze the record. */
-interface DefinePersonaInput<D = unknown> {
-    readonly name: string;
-    readonly root: AgentSpec;
-    readonly directive: string;
-    readonly context: PersonaContext;
-    readonly executors: PersonaExecutors;
-    readonly extensions?: Readonly<Record<string, unknown>>;
-    /** Phantom: pins the input's deliverable type so `definePersona<D>` returns a `Persona<D>`
-     *  the caller's shape must agree with. Type-only — never supplied at a call site. */
-    readonly __deliverable?: D;
-}
-/** Builds a frozen `Persona`, failing loud on the executors-supplied invariant (neither a
- *  registry nor seams = an unresolvable persona). Pure — no I/O, no engine. */
-type DefinePersona = <D = unknown>(input: DefinePersonaInput<D>) => Persona<D>;
-/**
- * Budget knobs a shape reads to size its fanout/children WITHOUT owning the conserved pool.
- * The root budget lives on `SupervisorOpts.budget`; the shape only needs the per-child
- * sizing hints + the fanout width it is allowed to open. All ceilings — the pool reserves
- * against them and fails closed, so an over-eager shape can never overspend.
- */
-interface ShapeBudget {
-    /** Per-child spawn budget the shape reserves for each leaf/sub-loop it opens. */
-    readonly perChild: Budget;
-    /** Max children a fanout step may open in one round (the shape's structural width). */
-    readonly fanout: number;
-}
-/**
- * The construction context a `LoopShape` factory receives. Carries the persona's resolved
- * executor seams + the budget knobs, plus the ONE helper a shape needs to spawn a child
- * through the keystone: `spawnChild` resolves an `AgentSpec` (or a persona-derived child
- * profile) into an `Agent` the shape hands to `scope.spawn`. The shape never touches the
- * registry directly — it asks the context, keeping resolution single-sourced.
- */
-interface ShapeContext<D = unknown> {
-    readonly persona: Persona<D>;
-    readonly budget: ShapeBudget;
-    /**
-     * Wrap an `AgentSpec` into a leaf `Agent` carrying it as `executorSpec`, so the shape can
-     * `scope.spawn(spawnChild(spec), task, opts)`. `name` labels the child for traces. The
-     * returned agent's `act` is never invoked by the keystone (it is spawned, not run) — the
-     * spec drives the resolved `Executor`; `act` exists only to satisfy the `Agent` shape.
-     */
-    spawnChild(name: string, spec: AgentSpec): Agent<unknown, Outcome<D>>;
-    /** 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
- * returns the root `Agent<Task, Outcome<D>>` whose `act` decomposes the task, fans out
- * children through `scope.spawn`, verifies/selects across their settlements (selector≠judge:
- * via `settledToIteration` + `defaultSelectWinner`, never re-ranking behind the driver), and
- * synthesizes the terminal `Outcome<D>`. The shape is STRUCTURE; the persona is CONTENT.
- */
-type LoopShape<Task, D> = (ctx: ShapeContext<D>) => Agent<Task, Outcome<D>>;
-/**
- * The open shape registry — the extension point that makes a new loop-shape ONE file + one
- * `registerShape` call with zero edits elsewhere. `resolve` returns a typed outcome (inspect
- * `succeeded` before `value`); `register` fails loud on a duplicate name.
- */
-interface ShapeRegistry {
-    register<Task, D>(name: string, factory: LoopShape<Task, D>): void;
-    resolve<Task, D>(name: string): {
-        succeeded: true;
-        value: LoopShape<Task, D>;
-    } | {
-        succeeded: false;
-        error: string;
-    };
-    /** The registered shape names — for diagnostics + a fail-loud "unknown shape" message. */
-    names(): string[];
-}
-/**
- * The end-to-end entrypoint. Builds the persona's root `Agent` from the chosen shape, then
- * runs it through a fresh `createSupervisor` over the persona's executors + the supplied
- * budget/journal/blobs. Returns the keystone's typed `SupervisedResult<Outcome<D>>` — a
- * `winner` carries the synthesized `Outcome<D>`; a `no-winner` is never coerced into one.
- *
- * `shape` is either a resolved `LoopShape` or a registered shape NAME (resolved through the
- * default registry). The journal/blobs default to in-memory impls in the engine when omitted
- * (durable FS impls are passed explicitly for a persisted run).
- */
-interface RunPersonifiedOptions<Task, D> {
-    readonly persona: Persona<D>;
-    /** A resolved shape factory OR a registered shape name. */
-    readonly shape: LoopShape<Task, D> | string;
-    readonly task: Task;
-    readonly budget: Budget;
-    /** Per-child sizing + fanout width handed to the shape. Defaults derive from `budget`. */
-    readonly shapeBudget?: Partial<ShapeBudget>;
-    /** Trace/journal root key. Defaults to the persona name + a run discriminator in the engine. */
-    readonly runId?: string;
-    readonly journal?: SpawnJournal;
-    readonly blobs?: ResultBlobStore;
-    /** Runtime recursion-depth ceiling, paired with the conserved pool. */
-    readonly maxDepth?: number;
-    /** OTP intensity breaker bounds, forwarded to the supervisor verbatim. */
-    readonly maxRestarts?: number;
-    readonly withinMs?: number;
-    /** A live root handle to attach (view/signal/abort) before the run starts. */
-    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>;
-    /**
-     * Lifecycle stream sink, forwarded to `SupervisorOpts.hooks` so the root `Scope`'s
-     * `agent.spawn`/`agent.child` events flow to an observer (e.g. the Intelligence SDK's
-     * trace export). Absent ⇒ no stream (the run is silent, as today).
-     */
-    readonly hooks?: RuntimeHooks;
-}
-/** The composed run signature. */
-type RunPersonified = <Task, D>(options: RunPersonifiedOptions<Task, D>) => Promise<SupervisedResult<Outcome<D>>>;
-
 /**
  *
  * The mechanical patch gate — the SINGLE source of the no-op / always-on secret-path floor /
@@ -975,4 +975,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 Corpus 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 CorpusRecord 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.93.2",
+  "version": "0.94.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": {
@@ -104,7 +104,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
-    "@tangle-network/agent-eval": "^0.114.0",
+    "@tangle-network/agent-eval": "^0.115.1",
     "@tangle-network/agent-interface": "^0.25.0",
     "@tangle-network/sandbox": "^0.9.7",
     "@types/node": "^25.9.3",
@@ -134,7 +134,7 @@
   "license": "MIT",
   "packageManager": "pnpm@10.28.0",
   "peerDependencies": {
-    "@tangle-network/agent-eval": ">=0.114.0 <1.0.0",
+    "@tangle-network/agent-eval": ">=0.115.1 <1.0.0",
     "@tangle-network/agent-interface": ">=0.25.0 <1.0.0",
     "@tangle-network/sandbox": ">=0.8.0 <1.0.0",
     "playwright": "^1.40.0"
@@ -148,7 +148,7 @@
     }
   },
   "dependencies": {
-    "@tangle-network/agent-knowledge": "^1.11.2",
+    "@tangle-network/agent-knowledge": "^1.12.1",
     "@tangle-network/agent-profile-materialize": "0.3.2"
   }
 }

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

@@ -93,7 +93,7 @@ to its native default (`HARNESS_NATIVE_MODEL`) — never silently dropped.
 | **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 |
 | **Freeze a measured profile/diff + code surface for execution** | `buildAgentCandidateBundle(...)` then `verifyAgentCandidateBundle(...)` — `/candidate-execution` | canonical-api §2 |
-| **Optimize any agent/code surface** (one call) — START HERE | `improve(profile, findings, { surface, gate })` — root `.`; prompt, skill-document, and curated-memory surfaces have built-in proposers, config/whole-profile surfaces accept a proposer, rollout policy enumerates bounded variants, and code gets isolated incumbent/candidate worktrees; drop to `selfImprove({ agent, scenarios, judge, baselineSurface })` only for lower-level control | canonical-api §3.4 |
+| **Optimize any agent/code surface** (one call) — START HERE | `improve(profile, findings, { surface, gate })` — root `.`; prompt, skill-document, and curated-memory surfaces have built-in proposers, config/whole-profile surfaces accept a proposer, and code gets isolated incumbent/candidate worktrees. Workflow and rollout-policy files use code plus agent-eval's `parameterSweepProposer` for JSON sweeps; drop to `selfImprove({ agent, scenarios, judge, baselineSurface })` only for lower-level control | canonical-api §3.4 |
 | **Gate: ship/hold a candidate** (campaign ctx) | `defaultProductionGate` / `heldOutGate` / `composeGate` — `agent-eval/contract`; `neutralizationGate` (footprint-matched PLACEBO gate — proves a held-out lift is CONTENT, not added prompt/mount footprint) — `agent-eval/campaign` | canonical-api §3.4 |
 | **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 |