feat(supervise): chat-transport executor — conversation workers with real resume continuity; P1 live path made valid

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.128.0
+
+### chat-transport executor: workers on a bare chat-completions transport
+
+A first-class `Executor` whose runtime is a plain OpenAI-compatible `/v1/chat/completions` transport — the worker IS a model conversation, not a sandboxed process (#721).
+What every offline test faked through `AgentSpec.executor` is now a shipped, supported leaf: node pinning, conserved spend, settle/verdict, and the journal + edge ledger all apply to a chat worker.
+
+New kernel exports (`src/runtime/supervise/chat-transport-executor.ts`):
+
+- `chatTransportExecutor(options): Executor<string>` — one `execute` is one conversation SHOT: seed (fresh system prompt, or a resumed session's recorded history) + the task as the next user message, then completion → host tool calls → tool messages until the model answers without a tool call (or `maxTurnsPerShot`, default 200). Settles with the final assistant text as `out`. NON-streaming by design: the streaming `UsageEvent` channel cannot mark an unmetered turn (`tokens` has no `tokensKnown: false` twin — the documented limitation in `supervise/types`), while the one-shot `Spend` carries both honesty markers.
+- Metering honesty: tokens from the transport's `usage` fields (`tokensKnown: false` when a turn omits them); dollars ONLY from the response's own cost fields (`usage.cost` / `usage.cost_usd` — `usdKnown: false` when absent). Never estimated from a local price table: this executor speaks to arbitrary endpoints whose models no local table can price.
+- Fail-loud: transport failures (non-2xx, network faults, malformed completions) throw `ValidationError` — the scope's INFRA settle class — never a fake success. The turns that DID run are still recorded first, because resume-after-failure is a kernel-supported path.
+- `ChatTransportTool` — the optional tool table: the OpenAI function spec the model sees plus the host-side `execute`; unknown tools and malformed arguments are fed back to the model as tool messages, never thrown.
+- `chatCompletionsTransport({ url, bearer })` — the one buffered wire function (also the executor's default transport), exported so a paired harness can drive two arms through the SAME instance; `ChatTransportExecutorOptions.complete` injects a scripted transport for fully-offline runs (mirrors `RouterConfig.complete`).
+- **Session continuity** — the executor is the resume consumer the kernel's `continuity: 'resume'` contract calls for: `createChatSessionStore()` keeps conversation histories keyed by settled worker id, `resume: WorkerResumeContext` continues `ofWorker`'s exact recorded message list (fails loud before any spend when the store has none — the same process-local resume boundary the kernel documents), and the finished conversation is recorded under `sessionKey` for the next resume.
+- `chatWorkerSeam(options): MakeWorkerAgent` — the session-owning worker seam `workerFromBackend` refuses to be: profile model/prompt (including a graph's appended delegates directive) drive each spawn, `WorkerSpawnContext.resume` re-attaches through the seam's store keyed by kernel node ids, and an optional `deliverable` gates each settle through the existing `gateOnDeliverable` (settled ⟺ delivered).
+
+New example + proof: `examples/graphs/user-sim-conversation.ts` — a CONVERSATION as a graph: a simulated user is a NODE (persona profile as the root), the product agent is a chat-transport worker, each dialogue turn is one ledgered `delegates` traversal with `continuity: 'resume'`, and the offline test (`tests/examples/user-sim-conversation.test.ts`) asserts the resumed message-history chain on the requests CAPTURED at the wire (turn k = turn k−1's whole message list + the prior assistant reply + the new user turn), the `fresh`/`resume`/`resume` ledger stamps, the executor-seam lineage, and the metered spend in the one conserved pool.
+
+P1 parity live path fixed (the three audited #710 gaps, `examples/p1-parity`):
+
+- Both arms' coders now share ONE substrate: the multishot arm's transport and the graph arm's `chatTransportExecutor` speak the same bare chat-completions endpoint with the same wire model, and the parity delegates edge declares `continuity: 'resume'` so the graph arm's shots continue one session exactly as `runMultishot`'s single transcript does. As previously wired the graph arm spawned a full cli-bridge harness worker against the multishot arm's bare chat calls — a substrate gap that invalidated any live parity number.
+- The live graph arm now HAS a driver: the `'chat'` graph backend requires the reviewer brain's `RouterConfig` (previously the live arm shipped with neither `brain` nor `router` and could not run).
+- No silent model fallback anywhere: the coder model rides its profile, the driver model is explicit per-arm substrate config (`MultishotArmBackend.driverModel` / `RouterConfig.model`), and the live entry requires `VB_CLI_BRIDGE_URL`, `VB_CLI_BRIDGE_BEARER`, `VB_PARITY_MODEL`, `VB_PARITY_ROUTER_URL`, `VB_PARITY_ROUTER_KEY`, `VB_PARITY_DRIVER_MODEL` — a missing variable fails loud; `'parity/unspecified'` is gone.
+
 ## 0.127.0
 
 ### Continuity is a first-class axis of delegates traversals

docs/api/primitive-catalog.md

@@ -7,7 +7,7 @@
 
 # Primitive catalog — the never-stale anti-reinvention inventory
 
-> **GENERATED** from `@tangle-network/agent-runtime@0.127.0` and `@tangle-network/agent-eval@0.143.0` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`.
+> **GENERATED** from `@tangle-network/agent-runtime@0.128.0` and `@tangle-network/agent-eval@0.143.0` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`.
 
 ## 1. agent-runtime — own public surface
 
@@ -510,7 +510,7 @@ Import from `@tangle-network/agent-runtime/intelligence` — 166 exports.
 
 ### Execution kernel — recursive atom, supervision, executors, round-synchronous loop
 
-Import from `@tangle-network/agent-runtime/kernel` — 710 exports.
+Import from `@tangle-network/agent-runtime/kernel` — 719 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -537,6 +537,9 @@ Import from `@tangle-network/agent-runtime/kernel` — 710 exports.
 | `canonicalFindingEvent` | function | Producer-side cleanliness for the `finding` event. The findings payload is arbitrary analyst |
 | `canonicalizeAuthoredProfile` | function | Lift a profile the supervisor AUTHORED into the canonical shape every executor reads. |
 | `captureWorkerTraceEvidence` | function | Collect and persist one executor's structured tool trace without changing its task outcome. |
+| `chatCompletionsTransport` | function | The default transport: POST `${url}/chat/completions` with an optional bearer. Fail-loud on |
+| `chatTransportExecutor` | function | Build the chat-transport `Executor`: one `execute` = one conversation SHOT — seed (fresh system |
+| `chatWorkerSeam` | function | The `makeWorkerAgent` seam over {@link chatTransportExecutor} — the continuity consumer |
 | `closingWorkerNote` | function | The worker's closing commentary off a local harness run: the TAIL of its |
 | `collectAgentTurn` | function | Drain a `streamAgentTurn` stream (or any `RuntimeStreamEvent` stream that |
 | `compareCheckOutcomes` | function | The selection order: crash < ran; then official pass-fraction; authored guesses only |
@@ -550,6 +553,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 710 exports.
 | `createActivityLog` | function | Create a bounded activity ring. `limit` caps memory for a worker that runs thousands of tools. |
 | `createAgentEnvironmentProviderRegistry` | function | Create a registry that resolves provider names to concrete provider instances. |
 | `createBudgetPool` | function | Create a conserved reservation pool from a root `Budget`. `now()` is injected so the |
+| `createChatSessionStore` | function | In-memory `ChatSessionStore`. Entries are detached copies — a caller mutating a saved array |
 | `createEventBus` | function | Create the child→parent coordination bus: one typed pipe for settled outputs, questions, and analyst findings, with a priority-ordered pull queue and a pass-through subscribe lane. |
 | `createExecutor` | function | The single built-in executor factory. Picks a leaf backend by data (`config.backend`), |
 | `createExecutorRegistry` | function | The open resolver/registry. Pre-registers the three built-ins under their |
@@ -789,6 +793,8 @@ Import from `@tangle-network/agent-runtime/kernel` — 710 exports.
 | `BudgetPoolRestore` | interface | State recovered from a prior process before new work is admitted. `committed` is measured spend |
 | `BusEvent` | interface | Every bus event is a discriminated union member keyed by `type`. |
 | `BusRecord` | interface | A published event stamped for ordering and observability. `seq` is the monotonic publish index; |
+| `ChatSessionStore` | interface | Conversation history keyed by the settled worker id — the resume substrate. The kernel owns |
+| `ChatTransportTool` | interface | One entry of the caller-provided tool table: the OpenAI function spec the model sees, and the |
 | `CheckExecChannel` | interface | Minimal exec channel the default runner needs. `SandboxInstance` (and therefore |
 | `CheckOutcome` | interface | How one candidate fared against the frozen visible checks, split by check kind. |
 | `CheckpointCapableBox` | interface | Loop-side widening of the box's optional checkpoint method. The |
@@ -992,6 +998,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 710 exports.
 | `AuthorizeDownMessage` | type | Product decision over an exact continuation before it is durably recorded or delivered. |
 | `AxisScoresOf` | type | Decompose ONE record into per-axis scores (e.g. judge dimensions). When set, it REPLACES the |
 | `BudgetReadout` | type | Post-reservation pool readout — the shape `Scope.budget` exposes. `tokensLeft`, |
+| `ChatCompletionsTransport` | type | One buffered chat-completions call: the OpenAI-shape request body in, the parsed completion |
 | `CombinatorShape` | type | A combinator is just a `LoopShape`: a factory `(ShapeContext) => Agent` whose `Agent.act` |
 | `ContinuityMode` | type | How a spawn CONTINUES a node's prior work: `'fresh'` starts a brand-new session (the default, |
 | `CoordinationDeliveryEvidence` | type | Durable delivery evidence retained in commit order. An attempt without a later event carrying |
@@ -1071,7 +1078,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 710 exports.
 | `WorktreeCheckRunner` | type | The single shell-command-in-worktree runner seam (replaces the per-executor copies). |
 | `WorktreePatchArtifact` | type | Terminal artifact of one worktree-CLI run — the canonical worktree-harness result (the captured |
 
-**Undocumented supporting types** (add a TSDoc line at the declaration to earn a table row): `AcquireOptions`, `AgentEnvironment`, `AgentEnvironmentCapabilities`, `AgentEnvironmentEvent`, `AgentEnvironmentProvider`, `AgentEnvironmentQuery`, `AgentEnvironmentSummary`, `AgentGraph`, `AgenticOptions`, `AgenticRunResult`, `AgenticTask`, `AgenticTool`, `AgentSession`, `AgentSessionRef`, `AgentTurnInput`, `AgentTurnResult`, `AllWorkersStalledOptions`, `AnalystRegistry`, `AnytimeReport`, `AnytimeStrategySummary`, `AnytimeTaskCurve`, `ArtifactHandle`, `AuditIntentInput`, `AuditIntentOptions`, `AuthoredHarness`, `AuthoredStrategy`, `AuthorStrategyOptions`, `BenchmarkConfig`, `BenchmarkLift`, `BenchmarkStrategySummary`, `BenchmarkTaskRow`, `BudgetPool`, `BusStats`, `ChampionPick`, `CheckpointRef`, `CheckpointRequest`, `CheckRunContext`, `CliWorktreeBridgeSeam`, `CoordinationMcpHandle`, `CopyOptions`, `CorpusReadbackOptions`, `CreateAgentEnvironmentInput`, `CreateTangleSandboxExactProcessProviderOptions`, `DefinedLeaderboard`, `DispatchReport`, `Driver`, `DriverAgentOptions`, `EventBus`, `EvolutionArchiveNode`, `EvolutionAuthor`, `EvolutionBandInfo`, `EvolutionCandidate`, `EvolutionGeneration`, `EvolutionReport`, `ExecRequest`, `ExecResult`, `ForkRequest`, `GitWorkspaceOptions`, `GraphResult`, `HarvestCorpusOptions`, `HarvestFailure`, `HarvestReport`, `Inbox`, `InProcessSandboxClientOptions`, `IntentAudit`, `Iteration`, `Leaderboard`, `LeaderboardOptions`, `LocalSandboxClientOptions`, `LoopDecisionPayload`, `LoopDispatchOptions`, `LoopEndedPayload`, `LoopIterationEndedPayload`, `LoopIterationStartedPayload`, `LoopPlanDescription`, `LoopResult`, `LoopSandboxPlacement`, `LoopStartedPayload`, `LoopTraceEmitter`, `LoopWinner`, `MaterializeLocalMcpOptions`, `McpEnvironmentOptions`, `McpToolDescriptor`, `NodeSnapshot`, `NoProgressForOptions`, `Observation`, `ObserveInput`, `ObserveOptions`, `OpenSandboxRunOptions`, `PairwiseOptions`, `PatchDeliverableOptions`, `PlacementInfo`, `PlateauOptions`, `ProgressTrackerOptions`, `PromotionGateOptions`, `PromotionVerdict`, `PublishOptions`, `ReproductionCheck`, `ResolveSandboxClientOptions`, `ResourceRequest`, `RollingDispatchOptions`, `RouterChatResult`, `RouterChatToolsResult`, `RouterConfig`, `RouterToolLoopResult`, `RunAgenticOptions`, `RunAgentRoundsOptions`, `RunGraphOptions`, `SandboxRun`, `ShotSpec`, `SpawnOpts`, `StdioMcpConnection`, `StdioMcpServerSpec`, `SteerableSandboxArgs`, `Strategy`, `StrategyEvolutionConfig`, `StrategyResult`, `StreamAgentTurnOptions`, `StructuralRolloutConfig`, `SuperviseOptions`, `SuperviseSurfaceOptions`, `SupervisorAgentDeps`, `SupervisorOpts`, `SupervisorSpanOptions`, `SupervisorSpanRecorder`, `SurfaceScore`, `ToolSpec`, `ToolStepInput`, `TraceSource`, `TrajectoryAnalysis`, `UntrackedCopyStats`, `ValidationCtx`, `Validator`, `VerifierEnvironmentOptions`, `WatchTraceOptions`, `WaterfallCollector`, `WaterfallReport`, `WaterfallSpan`, `WorkerEvidenceInput`, `Workspace`, `WorkspaceRequest`, `WorkspaceRun`, `WorktreeCliExecutorOptions`, `WorktreeFanoutOptions`, `AgentEnvironmentStatus`, `AgentSessionStatus`, `ChampionPolicy`, `EdgeDeliveryOutcome`, `GraphEdge`, `LoopTraceEvent`, `MakeWorkerAgent`, `RepairStop`, `SandboxControlClient`, `WorkspaceCommit`.
+**Undocumented supporting types** (add a TSDoc line at the declaration to earn a table row): `AcquireOptions`, `AgentEnvironment`, `AgentEnvironmentCapabilities`, `AgentEnvironmentEvent`, `AgentEnvironmentProvider`, `AgentEnvironmentQuery`, `AgentEnvironmentSummary`, `AgentGraph`, `AgenticOptions`, `AgenticRunResult`, `AgenticTask`, `AgenticTool`, `AgentSession`, `AgentSessionRef`, `AgentTurnInput`, `AgentTurnResult`, `AllWorkersStalledOptions`, `AnalystRegistry`, `AnytimeReport`, `AnytimeStrategySummary`, `AnytimeTaskCurve`, `ArtifactHandle`, `AuditIntentInput`, `AuditIntentOptions`, `AuthoredHarness`, `AuthoredStrategy`, `AuthorStrategyOptions`, `BenchmarkConfig`, `BenchmarkLift`, `BenchmarkStrategySummary`, `BenchmarkTaskRow`, `BudgetPool`, `BusStats`, `ChampionPick`, `ChatTransportExecutorOptions`, `ChatWorkerSeamOptions`, `CheckpointRef`, `CheckpointRequest`, `CheckRunContext`, `CliWorktreeBridgeSeam`, `CoordinationMcpHandle`, `CopyOptions`, `CorpusReadbackOptions`, `CreateAgentEnvironmentInput`, `CreateTangleSandboxExactProcessProviderOptions`, `DefinedLeaderboard`, `DispatchReport`, `Driver`, `DriverAgentOptions`, `EventBus`, `EvolutionArchiveNode`, `EvolutionAuthor`, `EvolutionBandInfo`, `EvolutionCandidate`, `EvolutionGeneration`, `EvolutionReport`, `ExecRequest`, `ExecResult`, `ForkRequest`, `GitWorkspaceOptions`, `GraphResult`, `HarvestCorpusOptions`, `HarvestFailure`, `HarvestReport`, `Inbox`, `InProcessSandboxClientOptions`, `IntentAudit`, `Iteration`, `Leaderboard`, `LeaderboardOptions`, `LocalSandboxClientOptions`, `LoopDecisionPayload`, `LoopDispatchOptions`, `LoopEndedPayload`, `LoopIterationEndedPayload`, `LoopIterationStartedPayload`, `LoopPlanDescription`, `LoopResult`, `LoopSandboxPlacement`, `LoopStartedPayload`, `LoopTraceEmitter`, `LoopWinner`, `MaterializeLocalMcpOptions`, `McpEnvironmentOptions`, `McpToolDescriptor`, `NodeSnapshot`, `NoProgressForOptions`, `Observation`, `ObserveInput`, `ObserveOptions`, `OpenSandboxRunOptions`, `PairwiseOptions`, `PatchDeliverableOptions`, `PlacementInfo`, `PlateauOptions`, `ProgressTrackerOptions`, `PromotionGateOptions`, `PromotionVerdict`, `PublishOptions`, `ReproductionCheck`, `ResolveSandboxClientOptions`, `ResourceRequest`, `RollingDispatchOptions`, `RouterChatResult`, `RouterChatToolsResult`, `RouterConfig`, `RouterToolLoopResult`, `RunAgenticOptions`, `RunAgentRoundsOptions`, `RunGraphOptions`, `SandboxRun`, `ShotSpec`, `SpawnOpts`, `StdioMcpConnection`, `StdioMcpServerSpec`, `SteerableSandboxArgs`, `Strategy`, `StrategyEvolutionConfig`, `StrategyResult`, `StreamAgentTurnOptions`, `StructuralRolloutConfig`, `SuperviseOptions`, `SuperviseSurfaceOptions`, `SupervisorAgentDeps`, `SupervisorOpts`, `SupervisorSpanOptions`, `SupervisorSpanRecorder`, `SurfaceScore`, `ToolSpec`, `ToolStepInput`, `TraceSource`, `TrajectoryAnalysis`, `UntrackedCopyStats`, `ValidationCtx`, `Validator`, `VerifierEnvironmentOptions`, `WatchTraceOptions`, `WaterfallCollector`, `WaterfallReport`, `WaterfallSpan`, `WorkerEvidenceInput`, `Workspace`, `WorkspaceRequest`, `WorkspaceRun`, `WorktreeCliExecutorOptions`, `WorktreeFanoutOptions`, `AgentEnvironmentStatus`, `AgentSessionStatus`, `ChampionPolicy`, `EdgeDeliveryOutcome`, `GraphEdge`, `LoopTraceEvent`, `MakeWorkerAgent`, `RepairStop`, `SandboxControlClient`, `WorkspaceCommit`.
 
 ### Environment provider adapters — generic sandbox/compute bridge