@meistrari/agent-core 0.2.0-experimental.0 → 0.2.0-experimental.2

package/src/steps/contract.ts

@@ -81,8 +81,11 @@ export function splitStepText(text: string): string[] {
 
 export function stepPreview(value: unknown): string {
     const text = (typeof value === 'string' ? value : JSON.stringify(value) ?? '').replaceAll('\0', '\\0')
+    if (Buffer.byteLength(JSON.stringify(text)) <= 2048)
+        return text
     let preview = ''
-    let bytes = 0
+    // Include the JSON quotes and truncation marker in the same preview budget.
+    let bytes = Buffer.byteLength(JSON.stringify('…'))
     for (const character of text) {
         const size = Buffer.byteLength(JSON.stringify(character)) - 2
         if (bytes + size > 2048)

package/src/steps/projector.ts

@@ -272,8 +272,24 @@ export class DurableStepProjector {
         ).get(...key)?.command_id
         const payload = 'payload' in event ? event.payload as Record<string, unknown> : event
         const explicit = typeof payload.commandId === 'string' ? payload.commandId : undefined
-        if (previous && explicit && previous !== explicit)
+        if (previous && explicit && previous !== explicit) {
+            if ('type' in event && event.actor.type === 'main' && payload.role === 'user'
+                && (event.type === 'message.started' || event.type === 'message.ended') && 'messageId' in payload && typeof payload.messageId === 'string') {
+                const messageStepId = stepIdFor({ sessionId: event.sessionId, providerSessionId: event.providerSessionId, actor: event.actor, turnId: event.turnId, kind: 'message', sourceId: payload.messageId })
+                const known = this.db.query<{ command_id: string | null }, [string]>(
+                    'select json_extract(body,\'$.commandId\') as command_id from steps where id=?',
+                ).get(messageStepId)
+                // Delayed/repeated facts for an older message must not rewind the turn's current command.
+                if (known?.command_id === explicit)
+                    return explicit
+                if (!known && event.type === 'message.started') {
+                    this.db.query('update turn_commands set command_id=? where session_id=? and provider_session_id=? and actor_id=? and turn_id=?')
+                        .run(explicit, ...key)
+                    return explicit
+                }
+            }
             throw new Error('Conflicting command identity for a provider turn.')
+        }
         let inherited: string | undefined
         if (!previous && !explicit && event.actor.type === 'subagent') {
             const toolCallId = event.actor.parentToolCallId

package/src/supervisor/agent-provider-factory.ts

@@ -7,6 +7,7 @@ import type { WireEventBody } from '../supervisor-protocol/event-body'
 import type { SupervisorAgentRunSnapshot } from '../supervisor-protocol/supervisor-agent-run-snapshot'
 import type { SupervisorAgentRuntime, SupervisorProviderFactory } from './provider-factory'
 import type { SupervisorRpcClient } from './rpc-client'
+import { Database } from 'bun:sqlite'
 import { wrapAgentEvent } from '../supervisor-protocol/agent-event-wrapper'
 import { createSupervisorProviderFactory } from './provider-factory'
 
@@ -15,6 +16,40 @@ export interface AgentProviderBindingStore {
     save: (input: { sessionId: string, provider: AgentProviderId, providerSessionId: string }) => Promise<void>
 }
 
+/** Local provider identity only; credentials and transcripts do not belong in this store. */
+export class SqliteAgentProviderBindingStore implements AgentProviderBindingStore {
+    private readonly db: Database
+
+    constructor(path: string) {
+        this.db = new Database(path, { create: true })
+        this.db.exec(`pragma journal_mode=WAL; pragma synchronous=FULL;
+            create table if not exists provider_bindings(
+                session_id text not null,
+                provider text not null,
+                provider_session_id text not null,
+                primary key(session_id, provider)
+            );`)
+    }
+
+    async load(input: { sessionId: string, provider: AgentProviderId }): Promise<string | undefined> {
+        return this.db.query<{ provider_session_id: string }, [string, string]>(
+            'select provider_session_id from provider_bindings where session_id=? and provider=?',
+        ).get(input.sessionId, input.provider)?.provider_session_id
+    }
+
+    async save(input: { sessionId: string, provider: AgentProviderId, providerSessionId: string }): Promise<void> {
+        if (!input.sessionId || !input.providerSessionId)
+            throw new Error('Provider binding requires session and provider session identities.')
+        this.db.query(`insert into provider_bindings(session_id,provider,provider_session_id) values (?,?,?)
+            on conflict(session_id,provider) do update set provider_session_id=excluded.provider_session_id`)
+            .run(input.sessionId, input.provider, input.providerSessionId)
+    }
+
+    close(): void {
+        this.db.close()
+    }
+}
+
 export interface AgentSupervisorProviderFactoryOptions {
     eventProcessor?: {
         recover: (emit: (body: WireEventBody) => void, options?: { interruptUnfinishedTurns: boolean }) => Promise<void>
@@ -65,11 +100,28 @@ export function createAgentSupervisorProviderFactory(
                 ? await provider.resumeSession({ ...sessionInput, provider: 'codex', providerSessionId: previousProviderSessionId }, { signal: input.signal })
                 : await provider.openSession({ ...sessionInput, provider: 'codex' }, { signal: input.signal })
 
-        await options.bindingStore.save({
-            sessionId: input.bootstrap.sessionId,
-            provider: provider.id,
-            providerSessionId: run.metadata.providerSessionId,
-        })
+        try {
+            await options.bindingStore.save({
+                sessionId: input.bootstrap.sessionId,
+                provider: provider.id,
+                providerSessionId: run.metadata.providerSessionId,
+            })
+        }
+        catch (error) {
+            try {
+                await run.stop({
+                    type: 'agent.stop',
+                    provider: run.metadata.provider,
+                    sessionId: run.metadata.sessionId,
+                    providerSessionId: run.metadata.providerSessionId,
+                    reason: 'provider_binding_persistence_failed',
+                }, { signal: new AbortController().signal })
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], 'Provider binding persistence and cleanup failed.')
+            }
+            throw error
+        }
 
         return new AgentSupervisorRuntime({
             run,
@@ -138,7 +190,9 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
                 providerSessionId: metadata.providerSessionId,
                 commandId: input.commandId,
                 mode: input.body.mode,
+                turnId: input.body.turnId,
                 model: input.body.model,
+                reasoningEffort: input.body.reasoningEffort,
                 origin: 'user',
                 prompt: input.body.prompt,
                 author: input.body.user
@@ -158,6 +212,7 @@ class AgentSupervisorRuntime implements SupervisorAgentRuntime {
         if (input.body.type === 'agent.interrupt') {
             await this.input.run.interrupt({
                 type: 'agent.interrupt',
+                turnId: input.body.turnId,
                 provider: metadata.provider,
                 sessionId: metadata.sessionId,
                 providerSessionId: metadata.providerSessionId,

package/src/supervisor/bootstrap-binder.ts

@@ -51,8 +51,8 @@ export function createBootstrapBinder(input: {
                 outcome: 'rejected',
                 ack: {
                     kind: 'command.ack',
-                    commandId: request.envelope.body.initialCommand.commandId,
-                    commandSeq: request.envelope.body.initialCommand.commandSeq,
+                    commandId: request.envelope.body.initialCommand?.commandId ?? `bootstrap:${request.envelope.body.sessionId}`,
+                    commandSeq: request.envelope.body.initialCommand?.commandSeq ?? 1,
                     status: 'rejected',
                     errorCode: error.code,
                     detail: error.publicMessage.slice(0, 240),
@@ -123,6 +123,7 @@ export function createBootstrapBinder(input: {
             outcome: 'accepted',
             runtimeState: {
                 kind: 'runtime.state',
+                ...(request.envelope.body.commandTransport === 'wss-v1' ? { sourceId: acceptedBinding.store.journalSourceId() } : {}),
                 lastReceivedCommandSeq: acceptedBinding.store.lastReceivedCommandSeq(),
                 nextEventSeq: acceptedBinding.store.localEventMax() + 1,
                 agentRun: acceptedBinding.store.agentRunSnapshot(),

package/src/supervisor/index.ts

@@ -1,4 +1,4 @@
-export { createAgentSupervisorProviderFactory } from './agent-provider-factory'
+export { createAgentSupervisorProviderFactory, SqliteAgentProviderBindingStore } from './agent-provider-factory'
 export type { AgentProviderBindingStore, AgentSupervisorProviderFactoryOptions } from './agent-provider-factory'
 export {
     CLEAN_EXIT_CODE,

package/src/supervisor/persistence/supervisor-store.ts

@@ -46,6 +46,9 @@ export interface PersistedSupervisorBinding {
     runtimeConnectionAttemptId: string
 }
 
+/** A command whose sequence is already journaled under a different identity or body. */
+export const commandSequenceConflictCode = 'agent-core.command-sequence-conflict'
+
 export class SupervisorStore {
     private closed = false
 
@@ -113,12 +116,14 @@ export class SupervisorStore {
                     now,
                 )
                 this.insertAttempt(input)
-                this.insertCommand({
-                    kind: 'command',
-                    commandId: input.body.initialCommand.commandId,
-                    commandSeq: input.body.initialCommand.commandSeq,
-                    body: input.body.initialCommand.body,
-                })
+                if (input.body.initialCommand) {
+                    this.insertCommand({
+                        kind: 'command',
+                        commandId: input.body.initialCommand.commandId,
+                        commandSeq: input.body.initialCommand.commandSeq,
+                        body: input.body.initialCommand.body,
+                    })
+                }
                 return {
                     body: input.body,
                     bodyHash,
@@ -175,12 +180,12 @@ export class SupervisorStore {
             if (existing.command_id !== envelope.commandId
                 || existing.body_hash !== sha256CanonicalJson(body)
                 || existing.body_json !== canonicalJson(body)) {
-                throw new SupervisorPersistenceError({ message: 'Command sequence conflicts with durable inbox state.' })
+                throw new SupervisorPersistenceError({ code: commandSequenceConflictCode, message: 'Command sequence conflicts with durable inbox state.' })
             }
             return { status: 'received', duplicate: true }
         }
         const maximum = this.lastReceivedCommandSeq()
-        if (envelope.commandSeq !== maximum + 1)
+        if (this.binding()?.body.commandTransport !== 'wss-v1' && envelope.commandSeq !== maximum + 1)
             throw new SupervisorPersistenceError({ message: 'Command sequence contains a gap.' })
         try {
             this.insertCommand({ ...envelope, body })
@@ -240,6 +245,15 @@ export class SupervisorStore {
         })()
     }
 
+    /** Stable identity of this SQLite journal, independent of socket and worker. */
+    journalSourceId(): string {
+        this.database.query('INSERT OR IGNORE INTO metadata (key, value) VALUES (\'journal_source_id\', ?)').run(crypto.randomUUID())
+        const row = this.database.query<{ value: string }, []>('SELECT value FROM metadata WHERE key = \'journal_source_id\'').get()
+        if (!row)
+            throw new SupervisorPersistenceError({ message: 'Missing journal identity.' })
+        return row.value
+    }
+
     lastReceivedCommandSeq(): number {
         return this.database.query<{ maximum: number }, []>('SELECT COALESCE(MAX(seq), 0) AS maximum FROM commands').get()?.maximum ?? 0
     }

package/src/supervisor/runtime-handler.ts

@@ -6,12 +6,15 @@ import type { EventEnvelope } from '../supervisor-protocol/envelopes/supervisor-
 import type { WireEventBody } from '../supervisor-protocol/event-body'
 import type { SupervisorStore } from './persistence/supervisor-store'
 import type { SupervisorAgentRuntime, SupervisorProviderFactory } from './provider-factory'
+import { ZodError } from 'zod'
 import { jsonUtf8ByteLength } from '../protocol'
 import { durabilityOf } from '../supervisor-protocol/durability'
 import { wireEventBodySchema } from '../supervisor-protocol/event-body'
 import { maxDurableEventBytes, maxEphemeralDeltaBytes } from '../supervisor-protocol/payload-overflow'
 import { decodeControlPlaneFrame, encodeWireFrame } from '../supervisor-protocol/wire-codec'
 import { EphemeralFrameBuffer } from './ephemeral-frame-buffer'
+import { SupervisorPersistenceError } from './errors'
+import { commandSequenceConflictCode } from './persistence/supervisor-store'
 import { SupervisorRpcClient } from './rpc-client'
 
 export interface ResidentSupervisorSocket {
@@ -99,8 +102,24 @@ export class SupervisorRuntimeHandler implements RuntimeConnectionHandler {
                 this.schedulePendingCommands()
             }
             catch (error) {
-                this.dependencies.logger.warn({ err: error }, 'rejecting invalid supervisor command')
-                socket.close(1008, 'Supervisor command was rejected.')
+                const rejection = this.dependencies.store.binding()?.body.commandTransport === 'wss-v1'
+                    ? terminalCommandRejection(error)
+                    : undefined
+                if (!rejection) {
+                    this.dependencies.logger.warn({ err: error }, 'rejecting invalid supervisor command')
+                    socket.close(1008, 'Supervisor command was rejected.')
+                    return
+                }
+                // wss-v1: answer a terminal rejection so the worker persists it instead of
+                // redelivering the same command on every reconnect.
+                this.dependencies.logger.warn({ err: error, commandSeq: frame.commandSeq, errorCode: rejection.errorCode }, 'rejecting supervisor command')
+                this.sendRetained(encodeWireFrame({
+                    kind: 'command.ack',
+                    commandId: frame.commandId,
+                    commandSeq: frame.commandSeq,
+                    status: 'rejected',
+                    ...rejection,
+                }))
             }
             return
         }
@@ -328,3 +347,12 @@ function frameText(data: string | ArrayBuffer | Uint8Array): string {
         return data
     return new TextDecoder().decode(data)
 }
+
+/** Only failures the same frame would reproduce are terminal; storage faults still close the socket. */
+function terminalCommandRejection(error: unknown): { errorCode: string, detail: string } | undefined {
+    if (error instanceof ZodError)
+        return { errorCode: 'supervisor.command.invalid-body', detail: 'Command body failed wire validation.' }
+    if (error instanceof SupervisorPersistenceError && error.code === commandSequenceConflictCode)
+        return { errorCode: 'supervisor.command.conflicting-duplicate', detail: error.message.slice(0, 240) }
+    return undefined
+}

package/src/supervisor-protocol/agent-event-wrapper.ts

@@ -2,16 +2,20 @@ import type { AgentEvent } from '../protocol'
 import z from 'zod'
 import {
     contextCompactionCompletedAgentEventSchema,
+    contextCompactionRequestCompletedAgentEventSchema,
     contextCompactionStartedAgentEventSchema,
+    contextUpdatedAgentEventSchema,
     errorAgentEventSchema,
     messageDeltaAgentEventSchema,
     messageEndedAgentEventSchema,
     messageStartedAgentEventSchema,
+    promptTurnCorrelatedAgentEventSchema,
     reasoningEndedAgentEventSchema,
     reasoningStartedAgentEventSchema,
     reasoningSummaryDeltaAgentEventSchema,
     sessionConfiguredAgentEventSchema,
     sessionEndedAgentEventSchema,
+    sessionSettingsChangedAgentEventSchema,
     sessionSkillsUpdatedAgentEventSchema,
     sessionStartedAgentEventSchema,
     sessionStateChangedAgentEventSchema,
@@ -21,6 +25,7 @@ import {
     toolCallCompletedAgentEventSchema,
     toolCallStartedAgentEventSchema,
     toolOutputDeltaAgentEventSchema,
+    toolOutputUpdatedAgentEventSchema,
     turnEndedAgentEventSchema,
     turnStartedAgentEventSchema,
     usageAgentEventSchema,
@@ -42,6 +47,10 @@ export const wrappedSessionConfiguredAgentEventSchema = sessionConfiguredAgentEv
     type: z.literal('agent.session.configured'),
 }).strict()
 
+export const wrappedSessionSettingsChangedAgentEventSchema = sessionSettingsChangedAgentEventSchema.extend({
+    type: z.literal('agent.session.settings.changed'),
+}).strict()
+
 export const wrappedSessionSkillsUpdatedAgentEventSchema = sessionSkillsUpdatedAgentEventSchema.extend({
     type: z.literal('agent.session.skills.updated'),
 }).strict()
@@ -58,6 +67,10 @@ export const wrappedTurnStartedAgentEventSchema = turnStartedAgentEventSchema.ex
     type: z.literal('agent.turn.started'),
 }).strict()
 
+export const wrappedPromptTurnCorrelatedAgentEventSchema = promptTurnCorrelatedAgentEventSchema.extend({
+    type: z.literal('agent.prompt.turn-correlated'),
+}).strict()
+
 export const wrappedTurnEndedAgentEventSchema = turnEndedAgentEventSchema.extend({
     type: z.literal('agent.turn.ended'),
 }).strict()
@@ -98,6 +111,10 @@ export const wrappedToolOutputDeltaAgentEventSchema = toolOutputDeltaAgentEventS
     type: z.literal('agent.tool.output.delta'),
 }).strict()
 
+export const wrappedToolOutputUpdatedAgentEventSchema = toolOutputUpdatedAgentEventSchema.extend({
+    type: z.literal('agent.tool.output.updated'),
+}).strict()
+
 export const wrappedToolCallCompletedAgentEventSchema = toolCallCompletedAgentEventSchema.extend({
     type: z.literal('agent.tool.call.completed'),
 }).strict()
@@ -118,6 +135,10 @@ export const wrappedUsageAgentEventSchema = usageAgentEventSchema.extend({
     type: z.literal('agent.usage'),
 }).strict()
 
+export const wrappedContextUpdatedAgentEventSchema = contextUpdatedAgentEventSchema.extend({
+    type: z.literal('agent.context.updated'),
+}).strict()
+
 export const wrappedContextCompactionStartedAgentEventSchema = contextCompactionStartedAgentEventSchema.extend({
     type: z.literal('agent.context.compaction.started'),
 }).strict()
@@ -126,6 +147,10 @@ export const wrappedContextCompactionCompletedAgentEventSchema = contextCompacti
     type: z.literal('agent.context.compaction.completed'),
 }).strict()
 
+export const wrappedContextCompactionRequestCompletedAgentEventSchema = contextCompactionRequestCompletedAgentEventSchema.extend({
+    type: z.literal('agent.context.compaction.request.completed'),
+}).strict()
+
 export const wrappedUserInputRequestedAgentEventSchema = userInputRequestedAgentEventSchema.extend({
     type: z.literal('agent.user-input.requested'),
 }).strict()
@@ -141,10 +166,12 @@ export const wrappedErrorAgentEventSchema = errorAgentEventSchema.extend({
 export const wrappedAgentEventSchema = z.discriminatedUnion('type', [
     wrappedSessionStartedAgentEventSchema,
     wrappedSessionConfiguredAgentEventSchema,
+    wrappedSessionSettingsChangedAgentEventSchema,
     wrappedSessionSkillsUpdatedAgentEventSchema,
     wrappedSessionStateChangedAgentEventSchema,
     wrappedSessionEndedAgentEventSchema,
     wrappedTurnStartedAgentEventSchema,
+    wrappedPromptTurnCorrelatedAgentEventSchema,
     wrappedTurnEndedAgentEventSchema,
     wrappedWorkObservedAgentEventSchema,
     wrappedMessageStartedAgentEventSchema,
@@ -155,13 +182,16 @@ export const wrappedAgentEventSchema = z.discriminatedUnion('type', [
     wrappedReasoningEndedAgentEventSchema,
     wrappedToolCallStartedAgentEventSchema,
     wrappedToolOutputDeltaAgentEventSchema,
+    wrappedToolOutputUpdatedAgentEventSchema,
     wrappedToolCallCompletedAgentEventSchema,
     wrappedSubagentStartedAgentEventSchema,
     wrappedSubagentProgressAgentEventSchema,
     wrappedSubagentEndedAgentEventSchema,
     wrappedUsageAgentEventSchema,
+    wrappedContextUpdatedAgentEventSchema,
     wrappedContextCompactionStartedAgentEventSchema,
     wrappedContextCompactionCompletedAgentEventSchema,
+    wrappedContextCompactionRequestCompletedAgentEventSchema,
     wrappedUserInputRequestedAgentEventSchema,
     wrappedUserInputResolvedAgentEventSchema,
     wrappedErrorAgentEventSchema,

package/src/supervisor-protocol/bootstrap.ts

@@ -59,12 +59,15 @@ export const sessionBootstrapBodySchema = z.object({
     }),
     gitBotIdentity: gitIdentitySchema.optional(),
     profile: sessionProfileSchema.optional(),
+    commandTransport: z.literal('wss-v1').optional(),
     initialCommand: z.object({
         commandId: z.string().min(1),
         commandSeq: z.literal(1),
         body: wireCommandBodySchema,
-    }).strict(),
+    }).strict().optional(),
 }).strict().superRefine((body, context) => {
+    if (body.commandTransport === 'wss-v1' ? body.initialCommand !== undefined : body.initialCommand === undefined)
+        context.addIssue({ code: 'custom', path: ['initialCommand'], message: 'wss-v1 bootstraps without a command; legacy bootstrap requires command one.' })
     const workspacePrefix = `${body.agent.cwd}/`
     for (const [index, repository] of body.repositories.entries()) {
         if (repository.root !== body.agent.cwd && !repository.root.startsWith(workspacePrefix)) {

package/src/supervisor-protocol/command-body.ts

@@ -1,5 +1,5 @@
 import z from 'zod'
-import { agentPromptModeSchema, agentPromptSchema, agentUserInputAnswersSchema, jsonObjectSchema, jsonUtf8ByteLength } from '../protocol'
+import { agentPromptModeSchema, agentPromptSchema, agentReasoningEffortSchema, agentUserInputAnswersSchema, jsonObjectSchema, jsonUtf8ByteLength } from '../protocol'
 
 const wireSenderContextSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('application') }).strict(),
@@ -40,7 +40,9 @@ export const wireCommandExtensionsSchema = jsonObjectSchema.refine(
 const wireSendPromptCommandSchema = z.object({
     type: z.literal('agent.send-prompt'),
     mode: agentPromptModeSchema,
+    turnId: z.string().min(1).optional(),
     model: z.string().trim().min(1).max(256).optional(),
+    reasoningEffort: agentReasoningEffortSchema.optional(),
     prompt: agentPromptSchema,
     attachments: z.array(wireInputAttachmentRefSchema).superRefine((attachments, context) => {
         const attachmentIds = new Set<string>()
@@ -60,6 +62,7 @@ const wireSendPromptCommandSchema = z.object({
 
 const wireInterruptCommandSchema = z.object({
     type: z.literal('agent.interrupt'),
+    turnId: z.string().min(1).optional(),
 }).strict()
 
 const wireRespondUserInputCommandSchema = z.object({

package/src/supervisor-protocol/envelopes/supervisor-to-control-plane.ts

@@ -14,6 +14,7 @@ export const commandAckErrorCodeSchema = z.string()
 
 export const runtimeStateEnvelopeSchema = z.object({
     kind: z.literal('runtime.state'),
+    sourceId: z.string().uuid().optional(),
     lastReceivedCommandSeq: z.number().int().nonnegative(),
     nextEventSeq: eventSequenceSchema,
     agentRun: supervisorAgentRunSnapshotSchema,

package/src/testing/in-memory-runtime-control-plane.ts

@@ -9,6 +9,7 @@ import type {
     CommandSource,
     ConnectionAuthorityStore,
     ConnectionClaim,
+    ConnectionReadinessRejection,
     DurableEventSink,
     EphemeralEventSink,
     RpcDispatcher,
@@ -19,18 +20,37 @@ import { ulid } from 'ulid'
 
 type NotificationCallbacks = Parameters<RuntimeNotifications['start']>[0]
 
+/** Admission state of an in-memory command; only wss-v1 selection consults it. */
+type InMemoryCommandStatus = 'queued' | 'dispatched' | 'received' | 'withdrawn' | 'rejected'
+
+/** Code the fixture answers when a session sandbox announces a different journal than it pinned. */
+export const inMemoryJournalIdentityChangedCode = 'testing.journal-identity-changed'
+
 export class InMemoryRuntimeControlPlane implements ConnectionAuthorityStore, CommandSource, DurableEventSink,
 EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, RuntimeNotifications {
     readonly durableEventLog: DurableEventEnvelope[] = []
     readonly durableRecordAttempts: number[] = []
     readonly ephemeralEventLog: Array<Parameters<EphemeralEventSink['publish']>[0]> = []
     readonly readySnapshots: SupervisorAgentRunSnapshot[] = []
+    /** `lastReceivedCommandSeq` announced by each accepted bootstrap, in readiness order. */
+    readonly readyReceivedSequences: number[] = []
     readonly projectedCommandSequences: number[] = []
     readonly failedCommandSequences: number[] = []
+    /** wss-v1 receipts, in the order the pump persisted them. */
+    readonly receivedCommandSequences: number[] = []
+    /** wss-v1 terminal rejections, in the order the pump persisted them. */
+    readonly rejectedCommands: Array<{ commandSeq: number, errorCode: string, detail?: string }> = []
+    /** Journal identity announced by each accepted readiness, in order. */
+    readonly readyJournalSourceIds: Array<string | undefined> = []
+    /** Every wss-v1 selection with the receipts that were durable when it ran. */
+    readonly pendingSelections: Array<{ commandSeq: number | undefined, receivedBefore: number[] }> = []
     readonly failureLog: Array<{ kind: string, code?: string, detail?: string }> = []
     readonly rpcCalls: SupervisorRpcRequestEnvelope[] = []
     onDurableRecord: ((event: DurableEventEnvelope) => void | Promise<void>) | undefined
-    private readonly commandLog: CommandEnvelope[]
+    private readonly commandLog: Array<CommandEnvelope & { body: WireCommandBody }>
+    private readonly commandStatus = new Map<number, InMemoryCommandStatus>()
+    private readonly wssV1: boolean
+    private pinnedJournalSourceId: string | undefined
     private notifications: NotificationCallbacks | undefined
     private claimed = false
     private generation = 0
@@ -41,30 +61,49 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
         ref: { sessionId: string, sessionSandboxId: string, providerSandboxId: string }
         trafficAccessTokenEncrypted: string
         bootstrap: Omit<SessionBootstrapBody, 'sessionId' | 'initialCommand'>
-        initialCommand: { commandId: string, body: WireCommandBody }
+        /** Required by the legacy bootstrap, forbidden by `commandTransport: 'wss-v1'`. */
+        initialCommand?: { commandId: string, body: WireCommandBody }
         secrets?: Awaited<ReturnType<BootstrapProvider['issueEphemeralSecrets']>>
         rpcHandlers?: Readonly<Record<string, (body: unknown) => unknown | Promise<unknown>>>
+        /** Journal this session sandbox was already bound to before the runtime under test started. */
+        pinnedJournalSourceId?: string
     }) {
-        this.commandLog = [{
-            kind: 'command',
-            commandId: input.initialCommand.commandId,
-            commandSeq: 1,
-            body: input.initialCommand.body,
-        }]
+        this.wssV1 = input.bootstrap.commandTransport === 'wss-v1'
+        this.pinnedJournalSourceId = input.pinnedJournalSourceId
+        if (this.wssV1 === (input.initialCommand !== undefined))
+            throw new Error('wss-v1 bootstraps without an initial command; the legacy bootstrap requires one.')
+        this.commandLog = input.initialCommand
+            ? [{
+                    kind: 'command',
+                    commandId: input.initialCommand.commandId,
+                    commandSeq: 1,
+                    body: input.initialCommand.body,
+                }]
+            : []
+        for (const command of this.commandLog)
+            this.commandStatus.set(command.commandSeq, 'queued')
     }
 
     enqueueCommand(input: { commandId?: string, body: WireCommandBody }): CommandEnvelope {
-        const command: CommandEnvelope = {
-            kind: 'command',
+        const command = {
+            kind: 'command' as const,
             commandId: input.commandId ?? ulid(),
             commandSeq: this.commandLog.length + 1,
             body: input.body,
         }
         this.commandLog.push(command)
+        this.commandStatus.set(command.commandSeq, 'queued')
         this.notifications?.onCommandsReady(this.input.ref.sessionId)
         return command
     }
 
+    /** Withdraw an admitted command before dispatch; its sequence stays allocated, leaving a gap. */
+    withdrawCommand(commandSeq: number): void {
+        if (this.commandStatus.get(commandSeq) !== 'queued')
+            throw new Error(`Command ${commandSeq} is not queued and cannot be withdrawn.`)
+        this.commandStatus.set(commandSeq, 'withdrawn')
+    }
+
     demandConnection(): void {
         this.notifications?.onConnectionDemand(this.input.ref.sessionSandboxId)
     }
@@ -106,7 +145,9 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
         return {
             renewed,
             ...(renewed ? { leaseExpiresAt: new Date(Date.now() + 30_000) } : {}),
-            hasOutstandingCommand: this.projectedCommandSequences.length + this.failedCommandSequences.length < this.commandLog.length,
+            hasOutstandingCommand: this.wssV1
+                ? this.deliverableCommands().length > 0
+                : this.projectedCommandSequences.length + this.failedCommandSequences.length < this.commandLog.length,
         }
     }
 
@@ -114,13 +155,32 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
         return this.claimed && input.generation === this.generation
     }
 
-    async markConnectionReady(input: { generation: number, agentRunSnapshot: SupervisorAgentRunSnapshot }): Promise<boolean> {
+    async markConnectionReady(input: {
+        generation: number
+        lastReceivedCommandSeq: number
+        agentRunSnapshot: SupervisorAgentRunSnapshot
+        journalSourceId?: string
+    }): Promise<boolean | ConnectionReadinessRejection> {
         if (!this.claimed || input.generation !== this.generation)
             return false
+        if (this.pinnedJournalSourceId !== undefined && input.journalSourceId !== this.pinnedJournalSourceId) {
+            return {
+                ready: false,
+                code: inMemoryJournalIdentityChangedCode,
+                detail: `Session sandbox is pinned to journal ${this.pinnedJournalSourceId}; supervisor announced ${input.journalSourceId ?? 'none'}.`,
+            }
+        }
+        this.pinnedJournalSourceId ??= input.journalSourceId
         this.readySnapshots.push(input.agentRunSnapshot)
+        this.readyReceivedSequences.push(input.lastReceivedCommandSeq)
+        this.readyJournalSourceIds.push(input.journalSourceId)
         return true
     }
 
+    journalSourceId(): string | undefined {
+        return this.pinnedJournalSourceId
+    }
+
     async markConnectionReconnecting(): Promise<void> {}
 
     async releaseConnection(input: { generation: number }): Promise<void> {
@@ -137,9 +197,35 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
     }
 
     async next(input: { afterSequence: number }): Promise<CommandEnvelope | undefined> {
+        if (this.wssV1)
+            throw new Error('wss-v1 never advances a cumulative command cursor.')
         return this.commandLog.find(command => command.commandSeq > input.afterSequence)
     }
 
+    /** wss-v1 selection: cancel and steer jump the queue; withdrawn commands leave gaps. */
+    async pending(): Promise<CommandEnvelope | undefined> {
+        if (!this.wssV1)
+            throw new Error('Individual command selection requires commandTransport wss-v1.')
+        // Yield like a database round trip so admissions made in the same tick are visible.
+        await Promise.resolve()
+        const deliverable = this.deliverableCommands()
+        const selected = deliverable.find(command => isPriorityCommand(command.body)) ?? deliverable[0]
+        this.pendingSelections.push({ commandSeq: selected?.commandSeq, receivedBefore: [...this.receivedCommandSequences] })
+        if (selected)
+            this.commandStatus.set(selected.commandSeq, 'dispatched')
+        return selected
+    }
+
+    async received(input: { commandId: string, commandSeq: number }): Promise<void> {
+        this.settleDispatched(input, 'received')
+        this.receivedCommandSequences.push(input.commandSeq)
+    }
+
+    async rejected(input: { commandId: string, commandSeq: number, errorCode: string, detail?: string }): Promise<void> {
+        this.settleDispatched(input, 'rejected')
+        this.rejectedCommands.push({ commandSeq: input.commandSeq, errorCode: input.errorCode, detail: input.detail })
+    }
+
     async getAckFloor(): Promise<number> {
         return this.ackFloor
     }
@@ -203,4 +289,24 @@ EphemeralEventSink, RpcDispatcher, BootstrapProvider, SessionFailureSink, Runtim
     async stop(): Promise<void> {
         this.notifications = undefined
     }
+
+    private settleDispatched(input: { commandId: string, commandSeq: number }, status: 'received' | 'rejected'): void {
+        const command = this.commandLog[input.commandSeq - 1]
+        if (!command || command.commandId !== input.commandId)
+            throw new Error(`Receipt for unknown command ${input.commandSeq}.`)
+        if (this.commandStatus.get(input.commandSeq) !== 'dispatched')
+            throw new Error(`Command ${input.commandSeq} was not dispatched.`)
+        this.commandStatus.set(input.commandSeq, status)
+    }
+
+    private deliverableCommands(): Array<CommandEnvelope & { body: WireCommandBody }> {
+        return this.commandLog.filter((command) => {
+            const status = this.commandStatus.get(command.commandSeq)
+            return status === 'queued' || status === 'dispatched'
+        })
+    }
+}
+
+function isPriorityCommand(body: WireCommandBody): boolean {
+    return body.type === 'agent.interrupt' || (body.type === 'agent.send-prompt' && body.mode === 'steer')
 }