@meistrari/agent-core 0.0.0 → 0.1.0

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

@@ -0,0 +1,364 @@
+import type { SessionBootstrapBody } from '../../supervisor-protocol/bootstrap'
+import type { CommandEnvelope } from '../../supervisor-protocol/envelopes/control-plane-to-supervisor'
+import type { DurableEventEnvelope } from '../../supervisor-protocol/envelopes/supervisor-to-control-plane'
+import type { WireEventBody } from '../../supervisor-protocol/event-body'
+import type { SupervisorAgentRunSnapshot } from '../../supervisor-protocol/supervisor-agent-run-snapshot'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { Database } from 'bun:sqlite'
+import { sessionBootstrapBodySchema } from '../../supervisor-protocol/bootstrap'
+import { wireCommandBodySchema } from '../../supervisor-protocol/command-body'
+import { wireEventBodySchema } from '../../supervisor-protocol/event-body'
+import { supervisorAgentRunSnapshotSchema } from '../../supervisor-protocol/supervisor-agent-run-snapshot'
+import { SupervisorPersistenceError } from '../errors'
+import { canonicalJson, sha256CanonicalJson } from './json'
+
+const schemaVersion = 1
+const bootstrapId = 'runtime'
+
+interface BootstrapRow {
+    session_id: string
+    body_json: string
+    body_hash: string
+    connection_generation: number
+    runtime_connection_attempt_id: string
+}
+
+interface CommandRow {
+    command_id: string
+    seq: number
+    body_json: string
+    body_hash: string
+    process_status: 'pending' | 'applied' | 'failed'
+}
+
+interface EventRow {
+    seq: number
+    occurred_at: string
+    body_json: string
+    body_hash: string
+}
+
+export interface PersistedSupervisorBinding {
+    body: SessionBootstrapBody
+    bodyHash: string
+    connectionGeneration: number
+    runtimeConnectionAttemptId: string
+}
+
+export class SupervisorStore {
+    private closed = false
+
+    private constructor(private readonly database: Database) {}
+
+    static open(input: { sqlitePath: string }): SupervisorStore {
+        let store: SupervisorStore | undefined
+        try {
+            mkdirSync(dirname(input.sqlitePath), { recursive: true })
+            store = new SupervisorStore(new Database(input.sqlitePath, { create: true }))
+            store.database.exec('PRAGMA journal_mode = WAL')
+            store.database.exec('PRAGMA foreign_keys = ON')
+            store.database.exec('PRAGMA busy_timeout = 5000')
+            store.database.exec('PRAGMA synchronous = FULL')
+            const version = store.userVersion()
+            if (version === 0)
+                store.initializeSchema()
+            else if (version !== schemaVersion)
+                throw new Error(`Unsupported supervisor SQLite schema version: ${version}.`)
+            return store
+        }
+        catch (cause) {
+            store?.close()
+            throw new SupervisorPersistenceError({ message: 'Failed to open supervisor SQLite state.', cause })
+        }
+    }
+
+    close(): void {
+        if (this.closed)
+            return
+        this.closed = true
+        this.database.close()
+    }
+
+    binding(): PersistedSupervisorBinding | undefined {
+        const row = this.bootstrapRow()
+        return row ? bindingFromRow(row) : undefined
+    }
+
+    bind(input: {
+        body: SessionBootstrapBody
+        connectionGeneration: number
+        runtimeConnectionAttemptId: string
+    }): PersistedSupervisorBinding {
+        const transaction = this.database.transaction(() => {
+            const existing = this.bootstrapRow()
+            if (!existing) {
+                const now = new Date().toISOString()
+                const bodyJson = canonicalJson(input.body)
+                const bodyHash = sha256CanonicalJson(input.body)
+                this.database.query(`
+                    INSERT INTO bootstrap (
+                        id, session_id, body_json, body_hash, connection_generation,
+                        runtime_connection_attempt_id, created_at, updated_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                `).run(
+                    bootstrapId,
+                    input.body.sessionId,
+                    bodyJson,
+                    bodyHash,
+                    input.connectionGeneration,
+                    input.runtimeConnectionAttemptId,
+                    now,
+                    now,
+                )
+                this.insertAttempt(input)
+                this.insertCommand({
+                    kind: 'command',
+                    commandId: input.body.initialCommand.commandId,
+                    commandSeq: input.body.initialCommand.commandSeq,
+                    body: input.body.initialCommand.body,
+                })
+                return {
+                    body: input.body,
+                    bodyHash,
+                    connectionGeneration: input.connectionGeneration,
+                    runtimeConnectionAttemptId: input.runtimeConnectionAttemptId,
+                }
+            }
+            const binding = bindingFromRow(existing)
+            if (binding.body.sessionId !== input.body.sessionId)
+                throw new Error('Supervisor is already bound to another session.')
+            if (input.connectionGeneration < binding.connectionGeneration)
+                throw new Error('Supervisor connection generation is stale.')
+            this.insertAttempt(input)
+            this.database.query(`
+                UPDATE bootstrap
+                SET connection_generation = ?, runtime_connection_attempt_id = ?, updated_at = ?
+                WHERE id = ?
+            `).run(input.connectionGeneration, input.runtimeConnectionAttemptId, new Date().toISOString(), bootstrapId)
+            return {
+                ...binding,
+                connectionGeneration: input.connectionGeneration,
+                runtimeConnectionAttemptId: input.runtimeConnectionAttemptId,
+            }
+        })
+        try {
+            return transaction()
+        }
+        catch (cause) {
+            throw new SupervisorPersistenceError({ message: 'Failed to persist supervisor bootstrap.', cause })
+        }
+    }
+
+    acceptConnectionAttempt(input: {
+        connectionGeneration: number
+        runtimeConnectionAttemptId: string
+    }): PersistedSupervisorBinding {
+        const binding = this.binding()
+        if (!binding)
+            throw new SupervisorPersistenceError({ message: 'Supervisor is not bound.' })
+        return this.bind({
+            body: binding.body,
+            connectionGeneration: input.connectionGeneration,
+            runtimeConnectionAttemptId: input.runtimeConnectionAttemptId,
+        })
+    }
+
+    receiveCommand(envelope: CommandEnvelope): { status: 'received', duplicate: boolean } {
+        const body = wireCommandBodySchema.parse(envelope.body)
+        const existing = this.database.query<CommandRow, [number]>(`
+            SELECT command_id, seq, body_json, body_hash, process_status
+            FROM commands WHERE seq = ?
+        `).get(envelope.commandSeq)
+        if (existing) {
+            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.' })
+            }
+            return { status: 'received', duplicate: true }
+        }
+        const maximum = this.lastReceivedCommandSeq()
+        if (envelope.commandSeq !== maximum + 1)
+            throw new SupervisorPersistenceError({ message: 'Command sequence contains a gap.' })
+        try {
+            this.insertCommand({ ...envelope, body })
+            return { status: 'received', duplicate: false }
+        }
+        catch (cause) {
+            throw new SupervisorPersistenceError({ message: 'Failed to durably receive supervisor command.', cause })
+        }
+    }
+
+    pendingCommands(): Array<CommandEnvelope & { body: ReturnType<typeof wireCommandBodySchema.parse> }> {
+        return this.database.query<CommandRow, []>(`
+            SELECT command_id, seq, body_json, body_hash, process_status
+            FROM commands WHERE process_status = 'pending' ORDER BY seq
+        `).all().map(row => ({
+            kind: 'command',
+            commandId: row.command_id,
+            commandSeq: row.seq,
+            body: commandBodyFromRow(row),
+        }))
+    }
+
+    markCommand(input: { commandSeq: number, status: 'applied' | 'failed' }): void {
+        this.database.query(`UPDATE commands SET process_status = ? WHERE seq = ?`).run(input.status, input.commandSeq)
+    }
+
+    lastReceivedCommandSeq(): number {
+        return this.database.query<{ maximum: number }, []>('SELECT COALESCE(MAX(seq), 0) AS maximum FROM commands').get()?.maximum ?? 0
+    }
+
+    appendDurableEvent(input: { occurredAt: string, body: WireEventBody }): DurableEventEnvelope {
+        const body = wireEventBodySchema.parse(input.body)
+        const bodyJson = canonicalJson(body)
+        const result = this.database.query(`
+            INSERT INTO events (occurred_at, body_json, body_hash, created_at) VALUES (?, ?, ?, ?)
+        `).run(input.occurredAt, bodyJson, sha256CanonicalJson(body), new Date().toISOString())
+        return {
+            kind: 'event',
+            delivery_semantics: 'durable',
+            seq: Number(result.lastInsertRowid),
+            occurredAt: input.occurredAt,
+            body,
+        }
+    }
+
+    eventsAfter(highWaterMark: number): DurableEventEnvelope[] {
+        return this.database.query<EventRow, [number]>(`
+            SELECT seq, occurred_at, body_json, body_hash FROM events WHERE seq > ? ORDER BY seq
+        `).all(highWaterMark).map(row => ({
+            kind: 'event',
+            delivery_semantics: 'durable',
+            seq: row.seq,
+            occurredAt: row.occurred_at,
+            body: eventBodyFromRow(row),
+        }))
+    }
+
+    localEventMax(): number {
+        return this.database.query<{ maximum: number }, []>('SELECT COALESCE(MAX(seq), 0) AS maximum FROM events').get()?.maximum ?? 0
+    }
+
+    agentRunSnapshot(): SupervisorAgentRunSnapshot {
+        const row = this.database.query<{ value: string }, []>('SELECT value FROM metadata WHERE key = \'agent_run\'').get()
+        return row ? supervisorAgentRunSnapshotSchema.parse(JSON.parse(row.value)) : { status: 'not_attached' }
+    }
+
+    setAgentRunSnapshot(snapshot: SupervisorAgentRunSnapshot): void {
+        const value = canonicalJson(supervisorAgentRunSnapshotSchema.parse(snapshot))
+        this.database.query(`
+            INSERT INTO metadata (key, value) VALUES ('agent_run', ?)
+            ON CONFLICT(key) DO UPDATE SET value = excluded.value
+        `).run(value)
+    }
+
+    private insertAttempt(input: { connectionGeneration: number, runtimeConnectionAttemptId: string }): void {
+        const replay = this.database.query<{ present: number }, [number, string]>(`
+            SELECT 1 AS present FROM connection_attempts
+            WHERE connection_generation = ? AND runtime_connection_attempt_id = ?
+        `).get(input.connectionGeneration, input.runtimeConnectionAttemptId)
+        if (replay)
+            throw new Error('Supervisor connection attempt was already admitted.')
+        this.database.query('DELETE FROM connection_attempts WHERE connection_generation < ?').run(input.connectionGeneration)
+        this.database.query(`
+            INSERT INTO connection_attempts (connection_generation, runtime_connection_attempt_id, accepted_at)
+            VALUES (?, ?, ?)
+        `).run(input.connectionGeneration, input.runtimeConnectionAttemptId, new Date().toISOString())
+    }
+
+    private insertCommand(envelope: CommandEnvelope): void {
+        const body = wireCommandBodySchema.parse(envelope.body)
+        this.database.query(`
+            INSERT INTO commands (seq, command_id, body_json, body_hash, process_status, received_at)
+            VALUES (?, ?, ?, ?, 'pending', ?)
+        `).run(
+            envelope.commandSeq,
+            envelope.commandId,
+            canonicalJson(body),
+            sha256CanonicalJson(body),
+            new Date().toISOString(),
+        )
+    }
+
+    private bootstrapRow(): BootstrapRow | undefined {
+        return this.database.query<BootstrapRow, []>(`
+            SELECT session_id, body_json, body_hash, connection_generation, runtime_connection_attempt_id
+            FROM bootstrap WHERE id = 'runtime'
+        `).get() ?? undefined
+    }
+
+    private userVersion(): number {
+        return this.database.query<{ user_version: number }, []>('PRAGMA user_version').get()?.user_version ?? 0
+    }
+
+    private initializeSchema(): void {
+        this.database.transaction(() => {
+            this.database.exec(`
+                CREATE TABLE bootstrap (
+                    id TEXT PRIMARY KEY CHECK (id = 'runtime'),
+                    session_id TEXT NOT NULL CHECK (session_id <> ''),
+                    body_json TEXT NOT NULL,
+                    body_hash TEXT NOT NULL CHECK (length(body_hash) = 64),
+                    connection_generation INTEGER NOT NULL CHECK (connection_generation > 0),
+                    runtime_connection_attempt_id TEXT NOT NULL CHECK (runtime_connection_attempt_id <> ''),
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                );
+                CREATE TABLE connection_attempts (
+                    connection_generation INTEGER NOT NULL CHECK (connection_generation > 0),
+                    runtime_connection_attempt_id TEXT NOT NULL CHECK (runtime_connection_attempt_id <> ''),
+                    accepted_at TEXT NOT NULL,
+                    PRIMARY KEY (connection_generation, runtime_connection_attempt_id)
+                );
+                CREATE TABLE commands (
+                    seq INTEGER PRIMARY KEY CHECK (seq > 0),
+                    command_id TEXT NOT NULL UNIQUE CHECK (command_id <> ''),
+                    body_json TEXT NOT NULL,
+                    body_hash TEXT NOT NULL CHECK (length(body_hash) = 64),
+                    process_status TEXT NOT NULL CHECK (process_status IN ('pending', 'applied', 'failed')),
+                    received_at TEXT NOT NULL
+                );
+                CREATE TABLE events (
+                    seq INTEGER PRIMARY KEY AUTOINCREMENT,
+                    occurred_at TEXT NOT NULL,
+                    body_json TEXT NOT NULL,
+                    body_hash TEXT NOT NULL CHECK (length(body_hash) = 64),
+                    created_at TEXT NOT NULL
+                );
+                CREATE TABLE metadata (
+                    key TEXT PRIMARY KEY CHECK (key <> ''),
+                    value TEXT NOT NULL
+                );
+            `)
+            this.database.exec(`PRAGMA user_version = ${schemaVersion}`)
+        })()
+    }
+}
+
+function commandBodyFromRow(row: CommandRow) {
+    const body = wireCommandBodySchema.parse(JSON.parse(row.body_json))
+    if (canonicalJson(body) !== row.body_json || sha256CanonicalJson(body) !== row.body_hash)
+        throw new SupervisorPersistenceError({ message: `Supervisor command ${row.seq} failed canonical integrity validation.` })
+    return body
+}
+
+function eventBodyFromRow(row: EventRow) {
+    const body = wireEventBodySchema.parse(JSON.parse(row.body_json))
+    if (canonicalJson(body) !== row.body_json || sha256CanonicalJson(body) !== row.body_hash)
+        throw new SupervisorPersistenceError({ message: `Supervisor event ${row.seq} failed canonical integrity validation.` })
+    return body
+}
+
+function bindingFromRow(row: BootstrapRow): PersistedSupervisorBinding {
+    const body = sessionBootstrapBodySchema.parse(JSON.parse(row.body_json))
+    if (canonicalJson(body) !== row.body_json || sha256CanonicalJson(body) !== row.body_hash)
+        throw new SupervisorPersistenceError({ message: 'Supervisor bootstrap body failed canonical integrity validation.' })
+    return {
+        body,
+        bodyHash: row.body_hash,
+        connectionGeneration: row.connection_generation,
+        runtimeConnectionAttemptId: row.runtime_connection_attempt_id,
+    }
+}

package/src/supervisor/ports/index.ts

@@ -0,0 +1,109 @@
+import type { AgentInputBlock, AgentProviderId } from '../../protocol'
+import type { EphemeralCredentials, SessionBootstrapBody } from '../../supervisor-protocol/bootstrap'
+import type { WireSendPromptCommand } from '../../supervisor-protocol/command-body'
+import type { ProductEvent } from '../../supervisor-protocol/product-event'
+import type { SupervisorRpcClient } from '../rpc-client'
+
+export interface ProviderCredentialsSource {
+    initial: () => EphemeralCredentials | undefined
+    refresh: (input: { reason: 'startup' | 'expired' | 'rejected', signal?: AbortSignal }) => Promise<EphemeralCredentials>
+    environmentFor: (provider: AgentProviderId) => Record<string, string>
+}
+
+export interface SupervisorAgentTool {
+    name: string
+}
+
+export type ToolRegistryFactory = (provider: AgentProviderId) => readonly SupervisorAgentTool[]
+
+export type InstructionComposer = (input: {
+    provider: AgentProviderId
+    tools: readonly { name: string }[]
+}) => string
+
+export interface InitializedWorkspaceRepository {
+    repository: { id: string, fullName: string }
+    root: string
+    branch: string
+    sha: string
+}
+
+export interface MaterializedAgentInputAttachment {
+    attachmentId: string
+    ordinal: number
+    filename: string
+    mediaType: string
+    byteSize: number
+    sha256: string
+    localPath: string
+}
+
+export interface WorkspacePreparer {
+    initialize: (input: {
+        signal: AbortSignal
+        onStartupStage: (input: { stage: string, outcome: 'success' | 'failure', duration: number }) => void
+    }) => Promise<readonly InitializedWorkspaceRepository[]>
+    prepareTurn: (input: {
+        commandId: string
+        command: WireSendPromptCommand
+        signal: AbortSignal
+    }) => Promise<{
+        attachments: readonly MaterializedAgentInputAttachment[]
+        promptPrefixBlocks?: AgentInputBlock[]
+    }>
+}
+
+export interface WorkspaceSyncContext {
+    trigger: 'turn-ended' | 'boot-reconcile'
+    turnId: string
+    author: { name: string, email: string } | undefined
+    additionalUsers: Array<{ id: string, name: string, gitEmail: string }>
+    assistantSummary: string | undefined
+    commitAllowed: boolean
+}
+
+export type RepositorySyncAction
+    = | { kind: 'commit-completed', repository: { id: string, fullName: string }, branch: string, commitSha: string }
+        | { kind: 'commit-failed', repository: string, branch: string, reason: 'unknown', detail: string }
+        | { kind: 'push-completed', repository: { id: string, fullName: string }, branch: string, remoteHeadSha: string }
+        | {
+            kind: 'push-failed'
+            repository: string
+            branch: string
+            reason: 'non-fast-forward' | 'auth' | 'network' | 'rejected' | 'unknown'
+            detail: string
+        }
+
+export interface WorkspaceSync {
+    sync: (context: WorkspaceSyncContext) => Promise<RepositorySyncAction[]>
+    fetch: () => Promise<void>
+}
+
+export interface TurnHooks {
+    onTurnEnded: (input: {
+        turnId: string
+        status: 'completed' | 'failed' | 'interrupted' | 'cancelled'
+        cwd: string
+        signal: AbortSignal
+    }) => Promise<ProductEvent[]>
+}
+
+export interface LargePayloadStore {
+    put: (input: {
+        sessionId: string
+        eventType: string
+        bytes: Uint8Array
+        signal: AbortSignal
+    }) => Promise<{ ref: string }>
+}
+
+export interface SupervisorExtensionContext {
+    bootstrap: SessionBootstrapBody
+    rpc: SupervisorRpcClient
+    signal: AbortSignal
+}
+
+export interface SupervisorBroker {
+    start: () => void | Promise<void>
+    stop: () => void | Promise<void>
+}

package/src/supervisor/provider-factory.ts

@@ -0,0 +1,37 @@
+import type { EphemeralCredentials, SessionBootstrapBody, SessionBootstrapGitToken } from '../supervisor-protocol/bootstrap'
+import type { WireCommandBody } from '../supervisor-protocol/command-body'
+import type { WireEventBody } from '../supervisor-protocol/event-body'
+import type { SupervisorAgentRunSnapshot } from '../supervisor-protocol/supervisor-agent-run-snapshot'
+import type { SupervisorRpcClient } from './rpc-client'
+
+export interface SupervisorAgentRuntime {
+    snapshot: () => SupervisorAgentRunSnapshot
+    handle: (input: {
+        commandId: string
+        commandSeq: number
+        body: WireCommandBody
+        signal: AbortSignal
+        emit: (body: WireEventBody) => void
+    }) => Promise<void>
+    refreshSecrets?: (input: {
+        credentials?: EphemeralCredentials
+        gitToken?: SessionBootstrapGitToken
+    }) => void | Promise<void>
+    close: (input: { signal: AbortSignal }) => Promise<void>
+}
+
+export interface SupervisorProviderFactory {
+    create: (input: {
+        bootstrap: SessionBootstrapBody
+        credentials?: EphemeralCredentials
+        gitToken?: SessionBootstrapGitToken
+        rpc: SupervisorRpcClient
+        signal: AbortSignal
+    }) => Promise<SupervisorAgentRuntime>
+}
+
+export function createSupervisorProviderFactory(
+    create: SupervisorProviderFactory['create'],
+): SupervisorProviderFactory {
+    return { create }
+}

package/src/supervisor/resident.ts

@@ -0,0 +1,143 @@
+import type { Logger } from '../logger'
+import type { SessionBootstrapEnvelope } from '../supervisor-protocol/envelopes/control-plane-to-supervisor'
+import type { BootstrapAdmission, SupervisorProcessBinding } from './bootstrap-binder'
+import type { ResidentSupervisorConfig } from './config'
+import type { VerifySupervisorControlAuthority } from './control-authority-verifier'
+import type { SupervisorStore } from './persistence/supervisor-store'
+import type { SupervisorProviderFactory } from './provider-factory'
+import { agentCoreProvenance } from '../provenance'
+import { createBootstrapBinder } from './bootstrap-binder'
+import { CLEAN_EXIT_CODE, RECOVERABLE_ERROR_CODE, TERMINAL_ERROR_CODE } from './config'
+import { createSupervisorControlAuthorityVerifier } from './control-authority-verifier'
+import { SupervisorConfigurationError } from './errors'
+import { discoverPersistedSupervisorState } from './persistence/state-discovery'
+import { SupervisorRuntimeHandler } from './runtime-handler'
+import { ResidentSupervisorWebSocketServer } from './websocket-server'
+
+export interface ResidentSupervisor {
+    start: () => void
+    stop: (input?: { reason?: 'sigterm' | 'sigint' | 'fatal_error', exitCode?: number }) => Promise<void>
+    port: () => number | undefined
+    binding: () => 'unbound' | 'bound'
+}
+
+export async function createResidentSupervisor(input: {
+    config: ResidentSupervisorConfig
+    logger: Logger
+    providerFactory: SupervisorProviderFactory
+    profile: { name: string, version: number, requiredRpcMethods: readonly string[] }
+    admission?: BootstrapAdmission
+    verifyControlAuthority?: VerifySupervisorControlAuthority
+    onExitRequested?: (code: number) => void
+    onStartupStage?: (fact: {
+        event: 'sandbox.startup-stage'
+        stage: 'bootstrap-persisted' | 'bootstrap-readiness-sent'
+        outcome: 'success' | 'failure'
+        duration: number
+        sessionId: string
+    }) => void
+}): Promise<ResidentSupervisor> {
+    const recovered = await discoverPersistedSupervisorState({ stateRoot: input.config.stateRoot })
+    let binding: SupervisorProcessBinding = recovered
+        ? { status: 'bound', store: recovered.store, sessionId: recovered.sessionId }
+        : { status: 'unbound' }
+    let handler: SupervisorRuntimeHandler | undefined
+    let processStartedPersisted = false
+    let stopped = false
+    let exitCode = CLEAN_EXIT_CODE
+
+    const verifyControlAuthority = input.verifyControlAuthority
+        ?? await createSupervisorControlAuthorityVerifier({ jwksPath: input.config.authorityJwksPath })
+    if (recovered) {
+        recovered.store.appendDurableEvent({
+            occurredAt: new Date().toISOString(),
+            body: { type: 'supervisor.started', payload: {} },
+        })
+        processStartedPersisted = true
+    }
+    const requestShutdown = (code: number) => {
+        exitCode = code
+        input.onExitRequested?.(code)
+        void stop({ reason: 'fatal_error', exitCode: code })
+    }
+    const activate = async (activation: { store: SupervisorStore, envelope: SessionBootstrapEnvelope }) => {
+        if (!processStartedPersisted) {
+            activation.store.appendDurableEvent({
+                occurredAt: new Date().toISOString(),
+                body: { type: 'supervisor.started', payload: {} },
+            })
+            processStartedPersisted = true
+        }
+        if (!handler) {
+            handler = new SupervisorRuntimeHandler({
+                store: activation.store,
+                providerFactory: input.providerFactory,
+                credentials: activation.envelope.credentials,
+                gitToken: activation.envelope.gitToken,
+                logger: input.logger,
+                onFatal: error => requestShutdown(
+                    error instanceof SupervisorConfigurationError ? TERMINAL_ERROR_CODE : RECOVERABLE_ERROR_CODE,
+                ),
+            })
+        }
+        else {
+            await handler.refreshSecrets({
+                credentials: activation.envelope.credentials,
+                gitToken: activation.envelope.gitToken,
+            })
+        }
+        return handler
+    }
+    const bindBootstrap = createBootstrapBinder({
+        stateRoot: input.config.stateRoot,
+        getBinding: () => binding,
+        setBinding: value => binding = value,
+        admission: input.admission,
+        activate,
+        shutdown: requestShutdown,
+        logger: input.logger,
+    })
+    const listener = new ResidentSupervisorWebSocketServer({
+        config: input.config,
+        logger: input.logger,
+        health: () => ({
+            status: 'ok',
+            binding: binding.status,
+            profile: input.profile,
+            agentCore: agentCoreProvenance(),
+        }),
+        getBoundSessionId: () => binding.status === 'bound' ? binding.sessionId : undefined,
+        getLocalEventMax: () => binding.status === 'bound' ? binding.store.localEventMax() : 0,
+        verifyControlAuthority,
+        acceptBoundConnectionGeneration: (connection) => {
+            if (binding.status !== 'bound')
+                throw new Error('Supervisor is not bound.')
+            binding.store.acceptConnectionAttempt({
+                connectionGeneration: connection.generation,
+                runtimeConnectionAttemptId: connection.runtimeConnectionAttemptId,
+            })
+        },
+        bindBootstrap,
+        onStartupStage: input.onStartupStage ?? (() => undefined),
+    })
+
+    async function stop(options: { reason?: 'sigterm' | 'sigint' | 'fatal_error', exitCode?: number } = {}): Promise<void> {
+        if (stopped)
+            return
+        stopped = true
+        exitCode = options.exitCode ?? exitCode
+        await listener.stop()
+        await handler?.stop(options.reason)
+        if (binding.status === 'bound')
+            binding.store.close()
+        if (exitCode !== CLEAN_EXIT_CODE)
+            process.exitCode = exitCode
+    }
+
+    return {
+        start: () => listener.start(),
+        stop,
+        port: () => listener.port(),
+        binding: () => binding.status,
+    }
+}