firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/native/control-plane.js

@@ -0,0 +1,1354 @@
+/**
+ * Native control-plane transport (Plan20 W09, spec 3.5).
+ *
+ * `httpControlPlane(scope)` is the only HTTP implementation of
+ * NativeControlPlane. Released root producers it consumes:
+ *  - executor presence: the enrolled local runner device's signed presence
+ *    pulses (openSession/heartbeat/closeSession);
+ *  - native/campaigns/{campaign}/slots/{slot}/offer and
+ *    native-executors/{device}/assignments?state=offered: offers to this
+ *    device (identity, fence, deadline; no commands, bindings or budgets);
+ *  - native-executors/{device}/assignments/{id}/control: signed
+ *    firedrill.native-control.v1 actions with a per-assignment sequence
+ *    (accept, reject, lease renewal);
+ *  - .../artifacts and .../artifacts/commit: signed evidence declarations,
+ *    a write-once storage PUT, then a signed commit root inspects;
+ *  - .../observations: signed observation-batch.v1 documents, acknowledged
+ *    by `acknowledged_sequence`;
+ *  - .../actions and .../actions/{id}/control: offered participant-message
+ *    target actions, a signed claim that returns the frozen dispatch once
+ *    (a replayed claim is `recovered` and never invoked again), a signed
+ *    complete naming the acknowledged v2 reply event, and a signed abandon
+ *    withdrawing this client's claim of an input that never reached the target.
+ * Every signed request is re-sent byte-identical on retry (same request key,
+ * deterministic Ed25519 signature), so root returns its retained original.
+ *
+ *  - .../artifacts (readiness): the signed execution-readiness.v1 document,
+ *    committed as the driver.started record the drill's single driver.started
+ *    observation references; root's controller then admits the drill on its own
+ *    (recordReadiness);
+ *  - .../stop: a signed native-execution-stop.v1 request once the drill stops;
+ *    root freezes dispatch, withdraws only never-claimed offers and returns the
+ *    exact last target action, the cutoff the close names (stopExecution);
+ *  - .../close: the signed execution-close.v1 document, committed as the
+ *    driver.<outcome> evidence record (recordClose); the drill's final outcome
+ *    observation references that record, and once root acknowledged it the
+ *    close is submitted by artifact id (submitClose);
+ *  - .../dependency-access: a signed native-dependency-access.v1 request for one
+ *    simulated dependency's short-lived gateway token (dependencyAccess);
+ *  - .../cleanup: after root fenced an execution (lease expired or revoked), its
+ *    frozen cleanup challenge (readCleanup) and a signed cleanup-only
+ *    execution-cleanup.v1 report of how each service ended (submitCleanup);
+ *  - native-executors/{device}/campaigns/{campaign}/run: the campaign's local run
+ *    on this device, read (readRun) and advanced by signed
+ *    local-run-lifecycle.v1 events (submitRun: register, observe, close);
+ *  - native/devices/{device}/campaigns/{campaign}/stream: the selected
+ *    campaign's companion channel (companion-channel.ts, `wakes`), whose
+ *    invalidation hints wake the offer loop and the drills instead of timers.
+ *    It never replaces a signed request or its receipt.
+ *
+ * Every operation is wired to a released root producer; nothing here is
+ * pending. Malformed local input is refused before anything is sent:
+ *  - a step whose id, kind or input digest is malformed (`native_target_action_invalid`);
+ *  - a completion without its own action id and acknowledged reply event
+ *    (`native_target_completion_invalid`).
+ * Accepting an offer does not start the target: root's controller admits
+ * capacity and bindings before any action, and cleanup, scoring and settlement
+ * after a close are root's. Executor routes use the server device id from the
+ * runner receipt (NativeExecutor.device_id). A companion without an enrolled
+ * runner device is refused with `runner_required`, and a receipt without a
+ * device id with `runner_receipt_invalid`. No route is guessed and no success
+ * is fabricated.
+ *
+ * This module also owns the transport-level helpers the companion and drill
+ * runner share: transient-error classification, capped exponential backoff with
+ * jitter, abortable sleep, bounded retry and the connection gate that pauses new
+ * steps while disconnected.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { open, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { privateDirectory } from '../credentials.js';
+import { PNG_MAX_BYTES, isMetadataFreePng } from './png.js';
+import { api } from '../auth.js';
+import { CliError } from '../http.js';
+import { companionChannel } from './companion-channel.js';
+import { ENDING_REASONS, EVENT_SIGNATURE_HEADER, EVIDENCE_RECORD_MAX_BYTES, LOCAL_RUN_MAX_SERVICES, NATIVE_ERRORS, NATIVE_ID, READINESS_MAX_RESETS, READINESS_MAX_SERVICES, SHA256_HEX, STOP_REASONS, SecretValue, TARGET_ACTION_KINDS, nativeError, } from './contracts.js';
+/** Root's size limit for the signed close record. */
+const CLOSE_MAX_BYTES = 65_536;
+/**
+ * One target session per drill attempt: every message and task of an attempt
+ * goes to the same session, and no two attempts share one. A fixed key would let
+ * a target that keeps conversation state by session continue an earlier drill's
+ * conversation, so a `fresh-session` reset would be claimed without happening.
+ * The key is a digest of the attempt id, so no service id reaches the target,
+ * and it is stable when a restarted runner resumes the same attempt.
+ */
+function participantSession(assignment) {
+    return `participant-${createHash('sha256').update(`firedrill.participant-session.v1\n${assignment.attempt_id}`).digest('hex').slice(0, 32)}`;
+}
+/** Offered-action pages read per poll (root keeps at most one live action per assignment). */
+const ACTION_PAGES = 5;
+/** Offers listed per claim (oldest unexpired first after filtering). */
+const OFFER_PAGE = 20;
+/** Drill deadline this client requests for a slot offer (root allows at most 24 hours). */
+const OFFER_DEADLINE_MS = 2 * 60 * 60 * 1000;
+/** Root refusals that mean "no offer for this device right now", not a failure. */
+const NO_OFFER_CODES = new Set(['native_campaign_offer_unavailable', 'native_campaign_parallel_limit', 'native_executor_parallel_limit',
+    'native_device_unavailable', 'native_local_run_unavailable']);
+const LOCAL_RUN_STATES = new Set(['active', 'uncertain', 'closed']);
+/** Root accepts at most this many sequenced cleanup reports per frozen execution. */
+const CLEANUP_MAX_REPORTS = 1024;
+const LOCAL_RUN_SERVICE_STATES = new Set(['planned', 'running', 'reaped', 'not_started', 'unknown']);
+/** Server codes that mean this attempt may no longer act, or this executor lost its authority. */
+const FENCE_CODES = {
+    native_lease_inactive: NATIVE_ERRORS.lease_expired,
+    native_fence_stale: NATIVE_ERRORS.stale_generation,
+};
+const REVOKED_CODES = new Set(['native_session_required', 'native_session_inactive', 'native_device_inactive',
+    'write_access_required', 'runner_access_removed', 'runner_scope_changed', 'runner_revoked']);
+/** Translate root refusals into the native fence and revocation codes the runner classifies. */
+function translated(error) {
+    if (!(error instanceof CliError))
+        return error;
+    const fence = FENCE_CODES[error.code];
+    if (fence)
+        return new CliError(fence, error.message, error.exitCode, error.httpStatus);
+    if (REVOKED_CODES.has(error.code))
+        return new CliError(NATIVE_ERRORS.revoked, error.message, error.exitCode, error.httpStatus);
+    return error;
+}
+/** Root's signed-payload canonical form: sorted keys, compact, ASCII-escaped (Python ensure_ascii). */
+function rootCanonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(rootCanonical).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const object = value;
+        return `{${Object.keys(object).sort().map((key) => `${rootCanonical(key)}:${rootCanonical(object[key])}`).join(',')}}`;
+    }
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new CliError('native_request_invalid', 'A signed request held an unsupported value. Nothing was submitted.');
+    return encoded.replace(/[\u007f-\uffff]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+const digestOf = (value) => createHash('sha256').update(rootCanonical(value), 'ascii').digest('hex');
+/** Root's cap on a claim's `dispatch_canonical` (supplementary characters escape to 12 bytes each). */
+const MAX_DISPATCH_CANONICAL = 262144;
+/**
+ * The dispatch a fresh claim froze, read from root's exact canonical text: printable ASCII only
+ * (Python ensure_ascii), within the cap, and hashing byte-for-byte to the action's input digest.
+ * Only then is it parsed; null when any of that fails.
+ */
+function frozenDispatch(text, inputDigest) {
+    if (typeof text !== 'string' || !text || text.length > MAX_DISPATCH_CANONICAL || !/^[\x20-\x7e]+$/.test(text))
+        return null;
+    if (createHash('sha256').update(text, 'ascii').digest('hex') !== inputDigest)
+        return null;
+    try {
+        return record(JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+}
+const isUuid = (value) => typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value);
+/** Readiness and descriptor aliases (stricter than the close's service pattern). */
+const READINESS_ALIAS = /^[a-z][a-z0-9_-]{0,63}$/;
+const HANDSHAKE_PROBES = new Set(['jsonl_handshake', 'function_import', 'browser_document', 'signed_event_handshake']);
+/** One execution-readiness.v1 service entry: a run reference only for a run-owned service. */
+function readinessServiceValid(item) {
+    const probe = item.probe;
+    const probeValid = probe.kind === 'http' ? Number.isSafeInteger(probe.status_code) && probe.status_code >= 200 && probe.status_code <= 299
+        : probe.kind === 'process' ? probe.observation === 'running'
+            : HANDSHAKE_PROBES.has(probe.kind) && SHA256_HEX.test(probe.response_sha256);
+    return READINESS_ALIAS.test(item.service) && isUuid(item.launch_id) && probeValid
+        && (item.ownership === 'owned_run' ? isUuid(item.run_id) : (item.ownership === 'owned' || item.ownership === 'attached') && item.run_id === null);
+}
+/** One reset evidence entry: a hook digest exactly when the reset is an approved hook. */
+function readinessResetValid(item) {
+    return READINESS_ALIAS.test(item.alias) && ['fresh-session', 'fresh-process', 'approved-hook'].includes(item.reset)
+        && (item.reset === 'approved-hook' ? typeof item.hook_sha256 === 'string' && SHA256_HEX.test(item.hook_sha256) : item.hook_sha256 === null)
+        && isUuid(item.evidence_artifact_id) && SHA256_HEX.test(item.evidence_sha256);
+}
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+function receiptInvalid(what) {
+    return new CliError('native_receipt_invalid', `The service response for ${what} did not match the request. Nothing further was sent for it.`);
+}
+const time = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const count = (value, min) => typeof value === 'number' && Number.isSafeInteger(value) && value >= min;
+/** The local step kind each target-action kind runs as. */
+const STEP_KIND = {
+    participant_message: 'message', scenario_message: 'message', task: 'task', event: 'event',
+};
+/** Root's target-visible event path: relative to the locally approved receiver prefix. */
+const EVENT_PATH = /^\/[A-Za-z0-9_/-]{0,255}$/;
+/** A listed step's payload before its claim returns the input (listing carries none). */
+function placeholderPayload(kind, actionId, session) {
+    if (kind === 'task')
+        return { kind: 'task', input: null, session_key: session };
+    if (kind === 'event') {
+        return { kind: 'event', delivery_id: actionId, method: 'POST', path: '/', headers: {}, body_base64: '', signature_header: null };
+    }
+    return { kind: 'message', text: '', session_key: session };
+}
+/**
+ * The input a claimed dispatch carries, or null when it does not match its
+ * kind: v1 for a participant message (unchanged), v2 for a scripted message, a
+ * task or a signed event. An event's delivery id is its action id, and its
+ * signature header is root's; the signing key is never in a dispatch.
+ */
+function dispatchedPayload(dispatch, kind, session) {
+    if (kind === 'participant_message') {
+        if (dispatch.schema !== 'firedrill.native-target-action.v1' || typeof dispatch.text !== 'string' || !isUuid(dispatch.participant_step_id))
+            return null;
+        return { kind: 'message', text: dispatch.text, session_key: session };
+    }
+    if (dispatch.schema !== 'firedrill.native-target-action.v2' || dispatch.participant_step_id !== null
+        || (kind === 'scenario_message' ? !isUuid(dispatch.scenario_event_id) : dispatch.scenario_event_id !== null))
+        return null;
+    const payload = record(dispatch.payload);
+    if (!payload)
+        return null;
+    const keys = Object.keys(payload).sort().join(',');
+    if (kind === 'scenario_message') {
+        return keys === 'kind,text' && payload.kind === 'message' && typeof payload.text === 'string'
+            ? { kind: 'message', text: payload.text, session_key: session } : null;
+    }
+    if (kind === 'task')
+        return keys === 'input,kind' && payload.kind === 'task' ? { kind: 'task', input: payload.input, session_key: session } : null;
+    const headers = record(payload.headers);
+    const method = payload.method;
+    if (keys !== 'body_base64,delivery_id,headers,kind,method,path,signature_header' || payload.kind !== 'event'
+        || (method !== 'POST' && method !== 'PUT' && method !== 'PATCH')
+        || typeof payload.path !== 'string' || !EVENT_PATH.test(payload.path) || payload.path.includes('//')
+        || !headers || !Object.keys(headers).every((name) => name === 'content-type')
+        || (headers['content-type'] !== undefined && headers['content-type'] !== 'application/json')
+        || typeof payload.body_base64 !== 'string' || payload.signature_header !== EVENT_SIGNATURE_HEADER
+        || payload.delivery_id !== dispatch.action_id)
+        return null;
+    return { kind: 'event', delivery_id: payload.delivery_id, method, path: payload.path,
+        headers: headers, body_base64: payload.body_base64, signature_header: EVENT_SIGNATURE_HEADER };
+}
+const SCHEDULE_KEYS = 'completed,completed_target_turns,due_remaining,future_conditions,next_after_turn,scheduled';
+const SCHEDULE_KEYS_V3 = 'active_elapsed_ms,completed,completed_target_turns,due_remaining,future_conditions,future_timers,'
+    + 'next_after_active_ms,next_after_turn,scheduled';
+/**
+ * Root's delivery status on a target-actions page. A page without it (a root
+ * that predates the status) says nothing has ended. `done` always names its
+ * ending reason, and a reason never comes without `done`. The schedule summary
+ * is optional (root sends it once nothing is in flight) and exact when present.
+ */
+function deliveryStatus(raw) {
+    const reconciliation = raw.reconciliation_required ?? null;
+    if (reconciliation !== null && (reconciliation !== 'participant_outcome_unknown' || raw.done !== false)) {
+        throw receiptInvalid('the target actions');
+    }
+    if (raw.done === undefined && raw.cancelled === undefined && raw.ending_reason === undefined && raw.schedule === undefined) {
+        return { done: false, cancelled: false, ending_reason: null, schedule: null };
+    }
+    const reason = raw.ending_reason;
+    if (typeof raw.done !== 'boolean' || typeof raw.cancelled !== 'boolean'
+        || (reason !== null && !ENDING_REASONS.includes(reason)) || raw.done !== (reason !== null)) {
+        throw receiptInvalid('the target actions');
+    }
+    let schedule = null;
+    if (raw.schedule !== undefined) {
+        const value = record(raw.schedule);
+        const keys = value ? Object.keys(value).sort().join(',') : '';
+        // Only a v3 scenario adds its active schedule time; then all three timer fields are present.
+        const timed = keys === SCHEDULE_KEYS_V3;
+        if (!value || (keys !== SCHEDULE_KEYS && !timed)
+            || !count(value.scheduled, 0) || !count(value.completed, 0) || !count(value.due_remaining, 0)
+            || !count(value.future_conditions, 0) || !count(value.completed_target_turns, 0)
+            || (value.next_after_turn !== null && !count(value.next_after_turn, 1))
+            || (timed && (!count(value.active_elapsed_ms, 0) || !count(value.future_timers, 0)
+                || (value.next_after_active_ms === null) !== (value.future_timers === 0)
+                || (value.next_after_active_ms !== null && !(count(value.next_after_active_ms, 0)
+                    && value.next_after_active_ms > value.active_elapsed_ms))))) {
+            throw receiptInvalid('the target actions');
+        }
+        schedule = value;
+    }
+    return { done: raw.done, cancelled: raw.cancelled, ending_reason: reason, schedule,
+        reconciliation_required: reconciliation };
+}
+/** Root's local-run service snapshot: unique aliases and launch ids, an exit code exactly when reaped. */
+function runServices(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > LOCAL_RUN_MAX_SERVICES)
+        return null;
+    const services = [];
+    for (const entry of value) {
+        const item = record(entry);
+        if (!item || Object.keys(item).sort().join(',') !== 'exit_code,launch_id,service,state' || typeof item.service !== 'string'
+            || !READINESS_ALIAS.test(item.service) || !isUuid(item.launch_id) || typeof item.state !== 'string' || !LOCAL_RUN_SERVICE_STATES.has(item.state)
+            || (item.state === 'reaped' ? !Number.isSafeInteger(item.exit_code) || item.exit_code < -255 || item.exit_code > 255
+                : item.exit_code !== null))
+            return null;
+        services.push({ service: item.service, launch_id: item.launch_id, state: item.state, exit_code: item.exit_code });
+    }
+    if (new Set(services.map((item) => item.service)).size !== services.length
+        || new Set(services.map((item) => item.launch_id)).size !== services.length)
+        return null;
+    return services;
+}
+/** Root AssignmentReceipt for this device, validated field by field. */
+function offerRow(value, deviceId, campaignId, slotId) {
+    const raw = record(value);
+    if (!raw || !isUuid(raw.id) || !isUuid(raw.attempt_id) || raw.device_id !== deviceId || !isUuid(raw.descriptor_id)
+        || !isUuid(raw.world_revision_id) || typeof raw.approved_plan_digest !== 'string' || !SHA256_HEX.test(raw.approved_plan_digest)
+        || typeof raw.state !== 'string' || !/^[a-z_]{1,24}$/.test(raw.state) || !count(raw.lease_epoch, 1) || !count(raw.state_generation, 1)
+        || !time(raw.offer_expires_at) || !time(raw.lease_expires_at) || !time(raw.deadline_at) || !count(raw.control_sequence, 0)
+        || !count(raw.observation_sequence, 0) || !count(raw.observation_elapsed_ms, 0) || (raw.revoked_at !== null && !time(raw.revoked_at))
+        || typeof raw.descriptor_digest !== 'string' || !SHA256_HEX.test(raw.descriptor_digest)
+        // Root names the offer's campaign (null for a controller offer); a root that predates it sends none.
+        || (raw.campaign_id !== undefined && raw.campaign_id !== null && !isUuid(raw.campaign_id))
+        || (campaignId !== null && raw.campaign_id !== undefined && raw.campaign_id !== campaignId)) {
+        throw receiptInvalid('the drill offer');
+    }
+    return { assignment_id: raw.id, attempt_id: raw.attempt_id, device_id: deviceId, descriptor_id: raw.descriptor_id,
+        world_revision_id: raw.world_revision_id, descriptor_sha256: raw.descriptor_digest,
+        approved_plan_digest: raw.approved_plan_digest, state: raw.state, lease_epoch: raw.lease_epoch, state_generation: raw.state_generation,
+        offer_expires_at: raw.offer_expires_at, lease_expires_at: raw.lease_expires_at, deadline_at: raw.deadline_at,
+        control_sequence: raw.control_sequence, observation_sequence: raw.observation_sequence,
+        observation_elapsed_ms: raw.observation_elapsed_ms, campaign_id: campaignId ?? (typeof raw.campaign_id === 'string' ? raw.campaign_id : null),
+        slot_id: slotId };
+}
+/** Storage write: exact signed PUT, no redirects or ambient credentials. 412 means the write-once object already exists. */
+async function putEvidence(upload, bytes, signal) {
+    let destination;
+    const headers = record(upload.headers);
+    try {
+        destination = new URL(String(upload.upload_url));
+        if (upload.method !== 'PUT' || destination.origin !== 'https://storage.googleapis.com' || destination.username
+            || destination.password || destination.hash || !headers
+            || Object.values(headers).some((value) => typeof value !== 'string' || !/^[\x20-\x7e]{1,256}$/.test(value))
+            || headers['Content-Length'] !== undefined && headers['Content-Length'] !== String(bytes.byteLength))
+            throw new Error();
+    }
+    catch {
+        throw receiptInvalid('the evidence upload');
+    }
+    let response;
+    try {
+        response = await fetch(destination, { method: 'PUT', headers: headers, body: new Uint8Array(bytes).buffer,
+            redirect: 'error', credentials: 'omit', signal: AbortSignal.any([signal, AbortSignal.timeout(60_000)]) });
+        await response.body?.cancel();
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        throw new CliError('connection_uncertain', 'The evidence upload was not confirmed. It is retried with the same record.');
+    }
+    if ([200, 201, 412].includes(response.status))
+        return;
+    // An expired or refused signed URL is renewed by declaring the same record again.
+    throw new CliError('connection_uncertain', 'The evidence upload was not accepted. It is retried with the same record.', 1, response.status >= 500 || response.status === 429 || response.status === 408 ? response.status : 503);
+}
+export function httpControlPlane(scope) {
+    if (!scope || typeof scope.workspace !== 'string' || !scope.workspace) {
+        throw new CliError('workspace_required', 'Select a workspace before starting the native companion. Nothing was started.', 2);
+    }
+    const options = (signal) => ({ actor: scope.actor, workspace: scope.workspace, signal });
+    const closeJournalPath = async (assignment) => {
+        const identity = JSON.stringify([scope.workspace, scope.actor ?? null, scope.executor?.device_key,
+            assignment.assignment_id, assignment.attempt_id]);
+        return join(await privateDirectory(), `native-close-${createHash('sha256').update(identity).digest('hex')}.json`);
+    };
+    const retainClose = async (assignment, state) => {
+        const path = await closeJournalPath(assignment);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            // Recovery identity only: no output, process evidence, signed payload,
+            // token or capability is stored locally. The canonical artifact is cloud-owned.
+            await file.writeFile(JSON.stringify({ schema: 'firedrill.native-close-intent.v1',
+                workspace_id: scope.workspace, actor_id: scope.actor ?? null,
+                device_key: scope.executor?.device_key, device_id: scope.executor?.device_id,
+                campaign_id: scope.campaign?.id ?? null, ...fenceOf(assignment),
+                close_artifact_id: state.artifact_id, request_key: state.request_key,
+                observation_sequence: state.observation_sequence, driver_outcome: state.driver_outcome,
+                sha256: state.sha256 }));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, path);
+    };
+    const controls = new Map();
+    /** One claim request key per target action (keyed by attempt and action), so a retried claim replays instead of claiming anew. */
+    const claimKeys = new Map();
+    /** One withdrawal request key per claimed action (keyed by attempt and action), so a retried withdrawal replays the original. */
+    const abandonKeys = new Map();
+    /** The deadline first requested per slot: root refuses a retried offer with a different one. */
+    const offerDeadlines = new Map();
+    /** A slot whose offer was sent but never answered: asked again (same device and deadline) before any other slot. */
+    let unansweredSlot = null;
+    /** The selected campaign was confirmed to run the approved descriptor (checked before any slot is taken). */
+    let campaignConfirmed = false;
+    /** Offers this companion rejected, or whose accept root refused; not returned again while root still lists them (bounded). */
+    const rejected = new Set();
+    const remember = (assignmentId) => {
+        rejected.add(assignmentId);
+        if (rejected.size > OFFER_PAGE * 50)
+            rejected.delete(rejected.values().next().value);
+    };
+    /** The signed close per attempt, so a retried close re-sends the same document and record. */
+    const closes = new Map();
+    /** The signed stop per attempt, so a retried stop re-sends the same request key and document. */
+    const stops = new Map();
+    /** The signed cleanup report per challenge sequence, so a retry re-sends the same request key and document. */
+    const cleanups = new Map();
+    /** The signed readiness per attempt (for one observation sequence), so a retry re-sends the same record. */
+    const readinessRecords = new Map();
+    /**
+     * Once root accepted an attempt's close or confirmed its cleanup report, no retry can need that attempt's
+     * keys or signed records, so they are dropped and a long-lived companion does not keep every drill's bytes.
+     */
+    const actionKey = (assignment, actionId) => `${assignment.assignment_id}\0${assignment.attempt_id}\0${actionId}`;
+    const forget = (assignment) => {
+        const key = `${assignment.assignment_id}\0${assignment.attempt_id}`;
+        closes.delete(key);
+        stops.delete(key);
+        readinessRecords.delete(key);
+        for (const map of [cleanups, claimKeys, abandonKeys]) {
+            for (const entry of map.keys())
+                if (entry.startsWith(`${key}\0`))
+                    map.delete(entry);
+        }
+    };
+    const executor = (operation) => {
+        const value = scope.executor;
+        if (!value)
+            throw new CliError('runner_required', `The ${operation} operation was not sent: no enrolled runner device executes for this companion. Enroll one with firedrill runner enroll. Nothing was submitted.`);
+        return value;
+    };
+    /** The server device id from the runner receipt, which executor routes and offers are keyed on. */
+    const deviceId = (operation) => {
+        const device = executor(operation).device_id;
+        if (!isUuid(device)) {
+            throw new CliError('runner_receipt_invalid', `The ${operation} operation was not sent: the runner receipt has no device id. Nothing was submitted.`);
+        }
+        return device;
+    };
+    /** Executor route for one assignment. */
+    const assignmentPath = (operation, assignmentId, suffix = '') => {
+        const device = deviceId(operation);
+        if (!isUuid(assignmentId))
+            throw new CliError(NATIVE_ERRORS.assignment_invalid, 'The assignment id is malformed. Nothing was submitted.');
+        return `/api/workspaces/${scope.workspace}/native-executors/${device}/assignments/${assignmentId}${suffix}`;
+    };
+    /** Remember root's control cursor for an offer, once; a known cursor (possibly mid-control) is kept. */
+    const track = (offer) => {
+        if (!controls.has(offer.assignment_id))
+            controls.set(offer.assignment_id, { sequence: offer.control_sequence,
+                approved_plan_digest: offer.approved_plan_digest, chain: Promise.resolve(), unconfirmed: null });
+        return offer;
+    };
+    /** POST one signed document; retried byte-identical on transient failures by the caller. */
+    const signedPost = async (path, payload, signal, operation) => {
+        const document = await executor(operation).sign(payload, signal);
+        try {
+            return await api(path, { method: 'POST', body: document, ...options(signal) });
+        }
+        catch (error) {
+            throw translated(error);
+        }
+    };
+    const fenceOf = (assignment) => ({
+        assignment_id: assignment.assignment_id, attempt_id: assignment.attempt_id,
+        lease_epoch: assignment.lease_epoch, state_generation: assignment.state_generation,
+    });
+    /** One control action, serialized per assignment so sequences never race. */
+    const control = (assignment, action, signal) => {
+        const state = controls.get(assignment.assignment_id);
+        if (!state)
+            return Promise.reject(new CliError(NATIVE_ERRORS.assignment_invalid, `The ${action} control was not sent: this companion never read that assignment's offer, so no control cursor is known. Nothing was submitted.`));
+        /** Send one control document (retried byte-identical) and check root's receipt for it. */
+        const send = async (payload) => {
+            state.unconfirmed = payload;
+            const path = assignmentPath('control', assignment.assignment_id, '/control');
+            let raw;
+            try {
+                raw = record(await retryTransient(() => signedPost(path, payload, signal, 'control'), { signal, attempts: 4 }));
+            }
+            catch (error) {
+                // Only an answered refusal is final; an unanswered or cancelled request may have landed.
+                if (!isTransient(error) && !isAbort(error, signal))
+                    state.unconfirmed = null;
+                throw error;
+            }
+            state.unconfirmed = null;
+            if (!raw || raw.id !== assignment.assignment_id || raw.attempt_id !== assignment.attempt_id
+                || raw.control_sequence !== payload.sequence || typeof raw.lease_expires_at !== 'string'
+                || !Number.isFinite(Date.parse(raw.lease_expires_at)))
+                throw receiptInvalid('the assignment control');
+            state.sequence = payload.sequence;
+            // A cancel revokes this attempt and moves the lease epoch on by exactly one; nothing else changes it.
+            if (payload.action === 'cancel') {
+                if (raw.lease_epoch !== assignment.lease_epoch + 1 || raw.state_generation !== assignment.state_generation
+                    || typeof raw.revoked_at !== 'string' || !Number.isFinite(Date.parse(raw.revoked_at)))
+                    throw receiptInvalid('the assignment cancellation');
+                return raw;
+            }
+            if (raw.lease_epoch !== assignment.lease_epoch || raw.state_generation !== assignment.state_generation) {
+                throw nativeError('stale_generation', 'The assignment moved to a newer lease or state generation. This attempt stops before its next step.');
+            }
+            return raw;
+        };
+        const run = state.chain.catch(() => undefined).then(async () => {
+            // A heartbeat whose answer was lost is replayed byte-identical first (root answers a repeated request once),
+            // so liveness alone never blocks a withdrawal; its refusal is final. Any other unconfirmed control still stops here.
+            if (state.unconfirmed !== null && state.unconfirmed.action === 'heartbeat' && action !== 'heartbeat')
+                await send(state.unconfirmed);
+            const prior = state.unconfirmed;
+            const payload = prior !== null && prior.action === action ? prior : { schema: 'firedrill.native-control.v1',
+                ...fenceOf(assignment), request_key: randomUUID(), sequence: state.sequence + 1, action, approved_plan_digest: state.approved_plan_digest };
+            if (prior !== null && prior !== payload) {
+                throw nativeError('stale_generation', 'An earlier execution control is still unconfirmed. This attempt stops before its next step.');
+            }
+            return send(payload);
+        });
+        state.chain = run;
+        return run;
+    };
+    /** The selected campaign's detail, confirmed to run the approved descriptor. */
+    const campaignDetail = async (campaignId, signal) => {
+        if (!scope.campaign || campaignId !== scope.campaign.id)
+            throw new CliError('arguments_invalid', 'Only the selected campaign is read. Nothing was started.', 2);
+        if (!isUuid(campaignId))
+            throw new CliError('arguments_invalid', 'Use the campaign id exactly as Firedrill printed it. Nothing was started.', 2);
+        let detail;
+        try {
+            detail = await api(`/api/workspaces/${scope.workspace}/native/campaigns/${campaignId}`, options(signal));
+        }
+        catch (error) {
+            throw translated(error);
+        }
+        const campaign = record(detail);
+        if (!campaign || campaign.campaign_id !== campaignId)
+            throw receiptInvalid('the campaign');
+        if (typeof campaign.descriptor_digest !== 'string' || !SHA256_HEX.test(campaign.descriptor_digest))
+            throw receiptInvalid('the campaign');
+        if (campaign.descriptor_digest !== scope.campaign.descriptor_sha256) {
+            throw nativeError('plan_changed', 'No drill was requested: this campaign runs a different agent descriptor than the approved plan. No drill slot was taken.', 2);
+        }
+        return campaign;
+    };
+    /** The campaign's local-run route for this device (root `native_local_run_read` / `native_local_run_lifecycle`). */
+    const runPath = (operation, campaignId) => {
+        if (!scope.campaign || campaignId !== scope.campaign.id || !isUuid(campaignId)) {
+            throw new CliError('arguments_invalid', 'A local run belongs to the selected campaign only. Nothing was submitted.', 2);
+        }
+        return `/api/workspaces/${scope.workspace}/native-executors/${deviceId(operation)}/campaigns/${campaignId}/run`;
+    };
+    /** Root's run receipt, checked against this run, campaign and device. */
+    const runReceipt = (raw, campaignId, operation, runId) => {
+        const value = record(raw);
+        if (!value || !isUuid(value.run_id) || (runId !== null && value.run_id !== runId) || value.campaign_id !== campaignId
+            || value.device_id !== deviceId(operation) || !count(value.sequence, 1) || typeof value.state !== 'string'
+            || !LOCAL_RUN_STATES.has(value.state) || (value.closed_at !== null && (typeof value.closed_at !== 'string' || !Number.isFinite(Date.parse(value.closed_at))))
+            || (value.state === 'closed') !== (value.closed_at !== null) || value.process_provenance !== 'customer_device'
+            || value.cloud_cleanup_complete !== false || typeof value.descriptor_digest !== 'string' || !SHA256_HEX.test(value.descriptor_digest)) {
+            throw receiptInvalid('the local run');
+        }
+        const services = runServices(value.services);
+        if (!services)
+            throw receiptInvalid('the local run');
+        return { run_id: value.run_id, sequence: value.sequence, state: value.state,
+            closed_at: value.closed_at, descriptor_digest: value.descriptor_digest, services };
+    };
+    const plane = {
+        // One shared channel for the selected campaign (root keeps one per device); a companion needs a campaign.
+        ...(scope.campaign ? { wakes: companionChannel({ workspace: scope.workspace, actor: scope.actor, campaign: scope.campaign.id,
+                device: () => deviceId('companionChannel') }) } : {}),
+        // Presence of the enrolled runner device stands in for the companion session.
+        // Capabilities stay local: root has no capability route for native executors.
+        async openSession(_capabilities, signal) {
+            const device = executor('openSession');
+            const receipt = await device.pulse('idle', signal).catch((error) => { throw translated(error); });
+            if (['revoked', 'expired', 'access_removed', 'not_retained'].includes(receipt.state)) {
+                throw new CliError(NATIVE_ERRORS.revoked, 'This runner device is no longer authorized. Nothing was started.');
+            }
+            return { session_id: device.device_key, heartbeat_ms: 20_000 };
+        },
+        async heartbeat(_sessionId, signal) {
+            const receipt = await executor('heartbeat').pulse('idle', signal).catch((error) => { throw translated(error); });
+            return { revoked: ['revoked', 'expired', 'access_removed', 'not_retained'].includes(receipt.state) };
+        },
+        async campaignPolicy(campaignId, signal) {
+            const campaign = await campaignDetail(campaignId, signal);
+            if (!count(campaign.max_parallel, 1) || typeof campaign.state !== 'string' || !campaign.state)
+                throw receiptInvalid('the campaign');
+            return { max_parallel: campaign.max_parallel, state: campaign.state };
+        },
+        async readRun(campaignId, signal) {
+            let raw;
+            try {
+                raw = await api(runPath('readRun', campaignId), options(signal));
+            }
+            catch (error) {
+                // Only root's explicit code means "no run"; any other 404 is about this device's binding.
+                if (error instanceof CliError && error.httpStatus === 404 && error.code === 'native_local_run_not_found')
+                    return null;
+                throw translated(error);
+            }
+            return runReceipt(raw, campaignId, 'readRun', null);
+        },
+        async submitRun(campaignId, event, signal) {
+            const services = Array.isArray(event?.services) ? event.services : [];
+            const aliases = services.map((item) => item?.service);
+            const launches = services.map((item) => item?.launch_id);
+            // Root's local-run-lifecycle.v1: full snapshot, unique aliases and launch ids, an exit code exactly when reaped.
+            if (!isUuid(event?.run_id) || !isUuid(event.request_key) || !count(event.sequence, 1) || !['register', 'observe', 'close'].includes(event.action)
+                || services.length < 1 || services.length > LOCAL_RUN_MAX_SERVICES || new Set(aliases).size !== aliases.length
+                || new Set(launches).size !== launches.length || !services.every((item) => READINESS_ALIAS.test(item.service) && isUuid(item.launch_id)
+                && LOCAL_RUN_SERVICE_STATES.has(item.state) && (item.state === 'reaped'
+                ? Number.isSafeInteger(item.exit_code) && item.exit_code >= -255 && item.exit_code <= 255
+                : item.exit_code === null))
+                || (event.action === 'register' && (event.sequence !== 1 || !services.every((item) => item.state === 'planned')))) {
+                throw new CliError('native_local_run_invalid', 'The local run event is malformed. Nothing was submitted.');
+            }
+            const path = runPath('submitRun', campaignId);
+            const payload = {
+                schema: 'firedrill.native-local-run-lifecycle.v1', run_id: event.run_id, campaign_id: campaignId, device_id: deviceId('submitRun'),
+                descriptor_digest: scope.campaign?.descriptor_sha256, request_key: event.request_key, sequence: event.sequence, action: event.action,
+                services: services.map((item) => ({ service: item.service, launch_id: item.launch_id, state: item.state, exit_code: item.exit_code })),
+            };
+            // Ed25519 is deterministic: a re-sent event is byte-identical, so root replays its original receipt.
+            const receipt = runReceipt(await signedPost(path, payload, signal, 'submitRun'), campaignId, 'submitRun', event.run_id);
+            // A lifecycle receipt (first or replayed) carries exactly the snapshot of the event it confirms.
+            const sent = new Map(payload.services.map((item) => [item.service, item]));
+            if (receipt.sequence !== event.sequence || receipt.descriptor_digest !== payload.descriptor_digest || receipt.services.length !== sent.size
+                || !receipt.services.every((item) => {
+                    const own = sent.get(item.service);
+                    return own !== undefined && own.launch_id === item.launch_id && own.state === item.state && own.exit_code === item.exit_code;
+                })) {
+                throw receiptInvalid('the local run');
+            }
+            return receipt;
+        },
+        async closeSession(_sessionId, signal) {
+            await executor('closeSession').pulse('stopped', signal).catch((error) => { throw translated(error); });
+        },
+        async targetDispatchComplete(signal) {
+            if (!scope.campaign)
+                return false;
+            const detail = await campaignDetail(scope.campaign.id, signal);
+            if (detail.target_dispatch_complete === undefined)
+                return false;
+            if (typeof detail.target_dispatch_complete !== 'boolean')
+                throw receiptInvalid('the campaign dispatch closure');
+            return detail.target_dispatch_complete;
+        },
+        async targetWorkComplete(signal) {
+            if (!scope.campaign)
+                return false;
+            const detail = await campaignDetail(scope.campaign.id, signal);
+            if (detail.target_work_complete === undefined)
+                return false;
+            if (typeof detail.target_work_complete !== 'boolean')
+                throw receiptInvalid('the campaign target-work closure');
+            return detail.target_work_complete;
+        },
+        async claimAssignment(_sessionId, signal, claim = {}) {
+            const device = deviceId('claimAssignment');
+            // 1. An offer already made to this device (by this CLI, the web app or MCP), soonest-expiring live one first.
+            // A companion follows the selected campaign over its one channel, so it takes only that campaign's offers
+            // (root names each offer's campaign; one that names none is skipped); another campaign's offer is left for
+            // that campaign's companion. One bound to the campaign's local run takes them only once the run is
+            // registered: root refuses a registration after this device has an offer in the campaign.
+            if (!claim.campaignOnly || scope.campaign) {
+                let listed;
+                try {
+                    listed = await api(`/api/workspaces/${scope.workspace}/native-executors/${device}/assignments?state=offered&page=1&page_size=${OFFER_PAGE}`, options(signal));
+                }
+                catch (error) {
+                    throw translated(error);
+                }
+                const page = record(listed);
+                if (!page || !Array.isArray(page.results))
+                    throw receiptInvalid('the offered drills');
+                const now = Date.now();
+                const live = page.results.map((row) => offerRow(row, device, null, null))
+                    .filter((offer) => offer.state === 'offered' && Date.parse(offer.offer_expires_at) > now && !rejected.has(offer.assignment_id)
+                    && (!scope.campaign || offer.campaign_id === scope.campaign.id)
+                    && (!claim.campaignOnly || (offer.campaign_id === scope.campaign?.id && claim.runRegistered?.() === true)))
+                    .sort((a, b) => Date.parse(a.offer_expires_at) - Date.parse(b.offer_expires_at));
+                // The offer an unanswered slot request created (same campaign and requested deadline) is now taken from the
+                // listing, so that slot is never asked for again: a later replay would only return it in its current state.
+                const pendingSlot = unansweredSlot;
+                const asked = pendingSlot === null ? undefined : offerDeadlines.get(pendingSlot);
+                if (pendingSlot !== null && asked !== undefined
+                    && live.some((offer) => offer.campaign_id === scope.campaign?.id && Date.parse(offer.deadline_at) === Date.parse(asked))) {
+                    offerDeadlines.delete(pendingSlot);
+                    unansweredSlot = null;
+                }
+                if (live.length)
+                    return track(live[0]);
+            }
+            // 2. With a selected campaign, ask for an offer of its next waiting slot to this device.
+            // Every offer consumes a drill, so the campaign must first be shown to run the approved descriptor.
+            if (!scope.campaign)
+                return null;
+            const campaignId = scope.campaign.id;
+            if (!campaignConfirmed) {
+                await campaignDetail(campaignId, signal);
+                campaignConfirmed = true;
+            }
+            // The caller may need to act first (root registers a local run only before this device's first offer).
+            if (claim.beforeOffer && !await claim.beforeOffer(signal))
+                return null;
+            // An offer root may have made without this companion seeing it is no longer a waiting slot (and a
+            // campaign-bound companion skips listed offers), so it is asked for again; root replays it.
+            let slotId = unansweredSlot;
+            const replaying = slotId !== null;
+            if (!slotId) {
+                let waiting;
+                try {
+                    waiting = await api(`/api/workspaces/${scope.workspace}/native/campaigns/${campaignId}/slots?state=waiting&page=1&page_size=1`, options(signal));
+                }
+                catch (error) {
+                    throw translated(error);
+                }
+                const slots = record(waiting);
+                if (!slots || !Array.isArray(slots.results))
+                    throw receiptInvalid('the waiting drill slots');
+                if (!slots.results.length)
+                    return null;
+                const slot = record(slots.results[0]);
+                if (!slot || !isUuid(slot.slot_id) || slot.campaign_id !== campaignId || slot.state !== 'waiting')
+                    throw receiptInvalid('the waiting drill slots');
+                slotId = slot.slot_id;
+            }
+            const deadline = offerDeadlines.get(slotId) ?? new Date(Date.now() + OFFER_DEADLINE_MS).toISOString();
+            offerDeadlines.set(slotId, deadline);
+            let raw;
+            try {
+                raw = await retryTransient(() => api(`/api/workspaces/${scope.workspace}/native/campaigns/${campaignId}/slots/${slotId}/offer`, { method: 'POST', body: { device_id: device, deadline_at: deadline }, ...options(signal) }), { signal, attempts: 3 });
+            }
+            catch (error) {
+                // Unanswered: the offer may exist, so the same request is repeated first next time. Answered: nothing to repeat.
+                const answered = error instanceof CliError && error.httpStatus !== null && !isTransient(error);
+                unansweredSlot = answered ? null : slotId;
+                // An answered request created no offer to replay, so a later one for this slot takes a fresh deadline.
+                if (answered)
+                    offerDeadlines.delete(slotId);
+                // Another executor took the slot, a parallel limit is reached, or the campaign is not runnable now. A slot
+                // just listed that root already offered elsewhere (another device, the web app or MCP) answers
+                // `idempotency_conflict`; only for this client's own unanswered request does that conflict mean something is wrong.
+                if (error instanceof CliError && error.httpStatus === 409
+                    && (NO_OFFER_CODES.has(error.code) || (!replaying && error.code === 'idempotency_conflict')))
+                    return null;
+                throw translated(error);
+            }
+            unansweredSlot = null;
+            offerDeadlines.delete(slotId);
+            const offer = offerRow(raw, device, campaignId, slotId);
+            if (Date.parse(offer.deadline_at) !== Date.parse(deadline))
+                throw receiptInvalid('the drill offer');
+            // Root replays an earlier offer in its current state: one already taken, expired or ended is nothing to claim.
+            if (offer.state !== 'offered')
+                return null;
+            return track(offer);
+        },
+        async acceptAssignment(offer, signal) {
+            track(offer);
+            let raw;
+            try {
+                raw = await control(offer, 'accept', signal);
+            }
+            catch (error) {
+                // An answered refusal (offer expired, state changed, terminal) means not accepted; nothing started.
+                // That offer is not listed to this companion again, so it is never re-accepted in a loop.
+                if (error instanceof CliError && error.httpStatus === 409 && !isTransient(error)) {
+                    remember(offer.assignment_id);
+                    return { accepted: false, reason: error.code, receipt: null };
+                }
+                throw error;
+            }
+            const receipt = offerRow(raw, offer.device_id, offer.campaign_id, offer.slot_id);
+            if (receipt.assignment_id !== offer.assignment_id || receipt.state !== 'accepted') {
+                remember(offer.assignment_id);
+                return { accepted: false, reason: 'native_offer_not_accepted', receipt };
+            }
+            return { accepted: true, reason: null, receipt };
+        },
+        async cancelExecution(assignment, signal) {
+            await control(assignment, 'cancel', signal);
+        },
+        async rejectAssignment(offer, signal) {
+            remember(offer.assignment_id);
+            track(offer);
+            await control(offer, 'reject', signal);
+        },
+        // Target actions: participant and scripted messages, tasks and signed events. Listing carries
+        // no input; the claim returns it once.
+        async nextSteps(assignment, _after, signal) {
+            const base = assignmentPath('nextSteps', assignment.assignment_id, '/actions');
+            const steps = [];
+            let status = null;
+            for (let page = 1; page <= ACTION_PAGES; page++) {
+                let raw;
+                try {
+                    raw = record(await api(`${base}?state=offered&page=${page}`, options(signal)));
+                }
+                catch (error) {
+                    throw translated(error);
+                }
+                if (!raw || !Array.isArray(raw.results) || typeof raw.count !== 'number')
+                    throw receiptInvalid('the target actions');
+                // Root's delivery status is on every page; the first page's read is the one used.
+                status ??= deliveryStatus(raw);
+                for (const row of raw.results) {
+                    const action = record(row);
+                    if (!action || !isUuid(action.action_id) || action.assignment_id !== assignment.assignment_id
+                        || action.attempt_id !== assignment.attempt_id || !Number.isSafeInteger(action.sequence) || action.sequence < 1
+                        || typeof action.input_digest !== 'string' || !SHA256_HEX.test(action.input_digest)
+                        || typeof action.dispatch_available !== 'boolean')
+                        throw receiptInvalid('the target actions');
+                    // A root that predates generic actions lists participant messages only, without a kind.
+                    const kind = action.kind === undefined ? 'participant_message' : action.kind;
+                    if (!TARGET_ACTION_KINDS.includes(kind)
+                        || (kind === 'participant_message' ? !isUuid(action.participant_step_id) : action.participant_step_id !== null)) {
+                        throw receiptInvalid('the target actions');
+                    }
+                    // Only an action root would dispatch now, in this attempt's lease and generation, is a step. Root numbers
+                    // participant turns and its other actions separately, so a sequence is not a cursor: `after` filters nothing,
+                    // and the runner tracks the actions it handled by id.
+                    if (!action.dispatch_available || action.state !== 'offered'
+                        || action.lease_epoch !== assignment.lease_epoch || action.state_generation !== assignment.state_generation)
+                        continue;
+                    const actionKind = kind;
+                    const payload = placeholderPayload(actionKind, action.action_id, participantSession(assignment));
+                    steps.push({ step_id: action.action_id, sequence: action.sequence, kind: payload.kind, intent_id: action.action_id,
+                        idempotent: false, payload, deadline_ms: 0, input_digest: action.input_digest, action_kind: actionKind });
+                }
+                if (raw.next === null || raw.next === undefined)
+                    break;
+            }
+            const delivery = status ?? { done: false, cancelled: false, ending_reason: null, schedule: null };
+            // Root reports an ending only with no offered, claimed or uncertain action; offered steps always run first.
+            return steps.length ? { ...delivery, steps, done: false, ending_reason: null, schedule: null } : { ...delivery, steps };
+        },
+        async stepStarted(assignment, step, signal) {
+            if (step.kind !== STEP_KIND[step.action_kind ?? 'participant_message'] || step.payload.kind !== step.kind || !isUuid(step.step_id)
+                || typeof step.input_digest !== 'string' || !SHA256_HEX.test(step.input_digest)) {
+                throw new CliError('native_target_action_invalid', 'The target action to claim has a malformed id, kind or input digest. Nothing was submitted.');
+            }
+            let requestKey = claimKeys.get(actionKey(assignment, step.step_id));
+            if (!requestKey) {
+                requestKey = randomUUID();
+                claimKeys.set(actionKey(assignment, step.step_id), requestKey);
+            }
+            const payload = { schema: 'firedrill.native-target-control.v1', ...fenceOf(assignment), action_id: step.step_id,
+                action: 'claim', request_key: requestKey, input_digest: step.input_digest };
+            const raw = record(await signedPost(assignmentPath('stepStarted', assignment.assignment_id, `/actions/${step.step_id}/control`), payload, signal, 'stepStarted'));
+            if (!raw || raw.action_id !== step.step_id || typeof raw.recovered !== 'boolean')
+                throw receiptInvalid('the target action claim');
+            if (raw.recovered) {
+                // Root retained an earlier claim: the step may already have run. Never invoke it again.
+                if (raw.dispatch !== null || (raw.dispatch_canonical !== null && raw.dispatch_canonical !== undefined))
+                    throw receiptInvalid('the target action claim');
+                return { recovered: true, payload: null };
+            }
+            // Root's exact frozen bytes are authoritative: they are what input_digest hashes. Re-serializing the
+            // parsed dispatch here would differ from Python for whole-number floats, exponents and key order.
+            const dispatch = frozenDispatch(raw.dispatch_canonical, step.input_digest);
+            const kind = step.action_kind ?? 'participant_message';
+            if (!dispatch || raw.state !== 'claimed'
+                || dispatch.action_id !== step.step_id || dispatch.assignment_id !== assignment.assignment_id
+                || dispatch.attempt_id !== assignment.attempt_id || dispatch.lease_epoch !== assignment.lease_epoch
+                || dispatch.state_generation !== assignment.state_generation || dispatch.sequence !== step.sequence
+                || dispatch.kind !== kind
+                // The parsed compatibility copy, when sent, must hold the same values as the frozen bytes.
+                || (raw.dispatch !== undefined && (!record(raw.dispatch) || rootCanonical(raw.dispatch) !== rootCanonical(dispatch)))) {
+                throw receiptInvalid('the target action claim');
+            }
+            const dispatched = dispatchedPayload(dispatch, kind, step.payload.kind === 'event' ? participantSession(assignment) : step.payload.session_key);
+            if (!dispatched || dispatched.kind !== step.kind)
+                throw receiptInvalid('the target action claim');
+            return { recovered: false, payload: dispatched, claim_key: requestKey };
+        },
+        async abandonStep(assignment, step, reason, signal) {
+            const claimKey = claimKeys.get(actionKey(assignment, step.step_id));
+            // Only this client's own claim, of the exact input it was offered, can be withdrawn.
+            if (!claimKey || !isUuid(step.step_id) || typeof step.input_digest !== 'string' || !SHA256_HEX.test(step.input_digest)
+                || (reason !== 'client_refused' && reason !== 'not_delivered')) {
+                throw new CliError('native_target_withdrawal_invalid', 'Only a step this client claimed can be withdrawn. Nothing was submitted.');
+            }
+            let requestKey = abandonKeys.get(actionKey(assignment, step.step_id));
+            if (!requestKey) {
+                requestKey = randomUUID();
+                abandonKeys.set(actionKey(assignment, step.step_id), requestKey);
+            }
+            const payload = { schema: 'firedrill.native-target-control.v1', ...fenceOf(assignment), action_id: step.step_id,
+                action: 'abandon', request_key: requestKey, claim_key: claimKey, input_digest: step.input_digest, reason };
+            const raw = record(await signedPost(assignmentPath('abandonStep', assignment.assignment_id, `/actions/${step.step_id}/control`), payload, signal, 'abandonStep'));
+            if (!raw || Object.keys(raw).sort().join(',') !== 'action_id,delivery,intent_digest,reason,request_key,schema,state,withdrawn_at'
+                || raw.schema !== 'firedrill.native-target-withdrawal.v1' || raw.action_id !== step.step_id || raw.request_key !== requestKey
+                || typeof raw.intent_digest !== 'string' || !SHA256_HEX.test(raw.intent_digest) || raw.state !== 'cancelled'
+                || raw.reason !== reason || raw.delivery !== 'device_declared_not_delivered'
+                || typeof raw.withdrawn_at !== 'string' || !Number.isFinite(Date.parse(raw.withdrawn_at))) {
+                throw receiptInvalid('the target action withdrawal');
+            }
+            return raw;
+        },
+        async renewLease(assignment, signal) {
+            const receipt = await control(assignment, 'heartbeat', signal);
+            return { lease_expires_at: receipt.lease_expires_at,
+                state: typeof receipt.state === 'string' && /^[a-z_]{1,24}$/.test(receipt.state) ? receipt.state : null };
+        },
+        async uploadArtifact(assignment, upload, signal) {
+            // A screenshot is a metadata-free PNG with root's capture declaration; everything else is filtered JSON.
+            const image = upload.media_type === 'image/png';
+            const capture = image ? upload.capture : null;
+            if (!isUuid(upload.request_key) || !SHA256_HEX.test(upload.sha256) || !(upload.bytes instanceof Uint8Array) || upload.bytes.byteLength < 1
+                || (image ? upload.role !== 'screenshot.observed' || !capture || capture.consent !== true || capture.source !== 'playwright'
+                    || capture.masking_applied !== true || !SHA256_HEX.test(capture.masking_policy_sha256)
+                    || upload.bytes.byteLength > PNG_MAX_BYTES || !isMetadataFreePng(upload.bytes)
+                    : upload.media_type !== 'application/json')) {
+                throw new CliError('native_artifact_invalid', 'The evidence record is malformed. Nothing was submitted.');
+            }
+            const declaration = { schema: 'firedrill.native-artifact.v1', ...fenceOf(assignment), request_key: upload.request_key,
+                role: upload.role, media_kind: upload.media_type, size: upload.bytes.byteLength, sha256: upload.sha256,
+                privacy_profile: image ? 'client-masked-png-v1' : 'client-filtered-v1' };
+            if (capture)
+                declaration.capture = { consent: true, source: 'playwright', masking_applied: true, masking_policy_sha256: capture.masking_policy_sha256 };
+            const declarationSha256 = digestOf(declaration);
+            const declared = record(await signedPost(assignmentPath('uploadArtifact', assignment.assignment_id, '/artifacts'), declaration, signal, 'uploadArtifact'));
+            const artifact = record(declared?.artifact);
+            if (!artifact || !isUuid(artifact.artifact_id) || artifact.assignment_id !== assignment.assignment_id
+                || artifact.request_key !== upload.request_key || artifact.declaration_sha256 !== declarationSha256
+                || artifact.sha256 !== upload.sha256 || artifact.size !== upload.bytes.byteLength || artifact.role !== upload.role
+                || artifact.media_kind !== upload.media_type)
+                throw receiptInvalid('the evidence declaration');
+            const artifactId = artifact.artifact_id;
+            if (artifact.state === 'committed')
+                return { artifact_id: artifactId };
+            const access = record(declared?.upload);
+            if (artifact.state !== 'declared' || !access)
+                throw receiptInvalid('the evidence declaration');
+            await putEvidence(access, upload.bytes, signal);
+            const commit = { schema: 'firedrill.native-artifact-commit.v1', ...fenceOf(assignment), request_key: upload.request_key,
+                artifact_id: artifactId, declaration_sha256: declarationSha256 };
+            const committed = record(await signedPost(assignmentPath('uploadArtifact', assignment.assignment_id, '/artifacts/commit'), commit, signal, 'uploadArtifact'));
+            if (!committed || committed.artifact_id !== artifactId || committed.state !== 'committed' || committed.sha256 !== upload.sha256) {
+                throw receiptInvalid('the evidence commit');
+            }
+            return { artifact_id: artifactId };
+        },
+        async submitObservations(batch, signal) {
+            const raw = record(await signedPost(assignmentPath('submitObservations', batch.assignment_id, '/observations'), batch, signal, 'submitObservations'));
+            const acknowledged = raw?.acknowledged_sequence;
+            if (!raw || raw.assignment_id !== batch.assignment_id || raw.attempt_id !== batch.attempt_id || raw.batch_id !== batch.batch_id
+                || typeof acknowledged !== 'number' || !Number.isSafeInteger(acknowledged) || acknowledged < 0
+                || raw.sha256 !== digestOf(batch))
+                throw receiptInvalid('the observation batch');
+            if (raw.lease_epoch !== batch.lease_epoch || raw.state_generation !== batch.state_generation) {
+                throw nativeError('stale_generation', 'The observation acknowledgement belongs to another lease or state generation.');
+            }
+            return { acknowledged };
+        },
+        /** Completes a claimed target action with its acknowledged v2 reply event; a byte-identical retry returns the same completion. */
+        async completeStep(assignment, result, signal) {
+            const reply = result.reply_event_id;
+            if (!isUuid(result.step_id) || typeof reply !== 'string' || !NATIVE_ID.test(reply)) {
+                throw new CliError('native_target_completion_invalid', 'A target action completes only with its own id and its acknowledged reply event. Nothing was submitted.');
+            }
+            const payload = { schema: 'firedrill.native-target-control.v1', ...fenceOf(assignment), action_id: result.step_id,
+                action: 'complete', reply_event_id: reply };
+            const raw = record(await signedPost(assignmentPath('completeStep', assignment.assignment_id, `/actions/${result.step_id}/control`), payload, signal, 'completeStep'));
+            if (!raw || raw.action_id !== result.step_id || raw.state !== 'completed' || raw.reply_event_id !== reply) {
+                throw receiptInvalid('the target action completion');
+            }
+        },
+        async recordReadiness(assignment, readiness, signal) {
+            const key = `${assignment.assignment_id}\0${assignment.attempt_id}`;
+            let state = readinessRecords.get(key);
+            // A different sequence means the earlier record can no longer be referenced: a new one is signed.
+            if (!state || state.observation_sequence !== readiness.observation_sequence) {
+                const services = readiness.services.map((item) => item.service);
+                const resets = readiness.state_resets.map((item) => item.alias);
+                if (!count(readiness.observation_sequence, 1) || !SHA256_HEX.test(readiness.descriptor_digest)
+                    || services.length < 1 || services.length > READINESS_MAX_SERVICES || new Set(services).size !== services.length
+                    || !readiness.services.every(readinessServiceValid) || resets.length > READINESS_MAX_RESETS
+                    || new Set(resets).size !== resets.length || !readiness.state_resets.every(readinessResetValid)) {
+                    throw new CliError('native_readiness_invalid', 'The drill readiness is malformed. Nothing was submitted.');
+                }
+                // Exactly the schema's fields.
+                const payload = { schema: 'firedrill.native-execution-readiness.v1', request_key: randomUUID(), ...fenceOf(assignment),
+                    observation_sequence: readiness.observation_sequence, descriptor_digest: readiness.descriptor_digest,
+                    services: readiness.services.map((item) => ({ service: item.service, launch_id: item.launch_id, ownership: item.ownership,
+                        run_id: item.run_id, probe: item.probe.kind === 'http' ? { kind: 'http', status_code: item.probe.status_code }
+                            : item.probe.kind === 'process' ? { kind: 'process', observation: 'running' }
+                                : { kind: item.probe.kind, response_sha256: item.probe.response_sha256 } })),
+                    state_resets: readiness.state_resets.map((item) => ({ alias: item.alias, reset: item.reset, hook_sha256: item.hook_sha256,
+                        evidence_artifact_id: item.evidence_artifact_id, evidence_sha256: item.evidence_sha256 })) };
+                const document = await executor('recordReadiness').sign(payload, signal);
+                const bytes = Buffer.from(rootCanonical(document), 'utf8');
+                if (bytes.byteLength > EVIDENCE_RECORD_MAX_BYTES)
+                    throw new CliError('native_readiness_invalid', 'The drill readiness is too large. Nothing was submitted.');
+                state = { upload_key: randomUUID(), bytes, sha256: createHash('sha256').update(bytes).digest('hex'),
+                    observation_sequence: readiness.observation_sequence, artifact_id: null };
+                readinessRecords.set(key, state);
+            }
+            if (!state.artifact_id) {
+                const committed = await plane.uploadArtifact(assignment, { request_key: state.upload_key, role: 'driver.started',
+                    media_type: 'application/json', sha256: state.sha256, bytes: state.bytes }, signal);
+                if (!isUuid(committed?.artifact_id))
+                    throw receiptInvalid('the drill readiness record');
+                state.artifact_id = committed.artifact_id;
+            }
+            return { artifact_id: state.artifact_id, sha256: state.sha256, size: state.bytes.byteLength,
+                observation_sequence: state.observation_sequence };
+        },
+        async dependencyAccess(assignment, alias, signal) {
+            if (typeof alias !== 'string' || !/^[a-z][a-z0-9_-]{0,63}$/.test(alias)) {
+                throw new CliError('native_dependency_invalid', 'The dependency alias is malformed. Nothing was requested.');
+            }
+            const raw = record(await signedPost(assignmentPath('dependencyAccess', assignment.assignment_id, '/dependency-access'), { schema: 'firedrill.native-dependency-access.v1', ...fenceOf(assignment), dependency_alias: alias }, signal, 'dependencyAccess'));
+            const auth = record(raw?.authorization);
+            const origin = (value) => {
+                try {
+                    const url = new URL(String(value));
+                    return url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash ? url : null;
+                }
+                catch {
+                    return null;
+                }
+            };
+            const invoke = origin(raw?.invoke_url), mcp = origin(raw?.mcp_url);
+            const operations = Array.isArray(raw?.operations) ? raw.operations : null;
+            if (!raw || raw.schema !== 'firedrill.native-dependency-access.v1' || raw.assignment_id !== assignment.assignment_id
+                || raw.attempt_id !== assignment.attempt_id || raw.lease_epoch !== assignment.lease_epoch
+                || raw.state_generation !== assignment.state_generation || raw.dependency_alias !== alias
+                || typeof raw.binding_digest !== 'string' || !SHA256_HEX.test(raw.binding_digest)
+                || typeof raw.service_key !== 'string' || !raw.service_key || raw.service_key.length > 200
+                || !operations || operations.length < 1 || !operations.every((item) => typeof item === 'string' && item.length > 0)
+                || !auth || auth.token_type !== 'Bearer' || typeof auth.token !== 'string' || !auth.token || auth.token.length > 100_000
+                || !Number.isSafeInteger(auth.expires_at) || !invoke || !mcp || invoke.origin !== mcp.origin
+                || invoke.pathname !== '/v1/invoke' || mcp.pathname !== `/mcp/${encodeURIComponent(raw.service_key)}`) {
+                throw receiptInvalid('the dependency access');
+            }
+            return { dependency_alias: alias, binding_digest: raw.binding_digest, service_key: raw.service_key,
+                operations: operations, token: new SecretValue(auth.token, `dependency:${alias}`),
+                expires_at: auth.expires_at, invoke_url: invoke.href, mcp_url: mcp.href };
+        },
+        async stopExecution(assignment, signal) {
+            const key = `${assignment.assignment_id}\0${assignment.attempt_id}`;
+            let state = stops.get(key);
+            if (!state) {
+                const payload = { schema: 'firedrill.native-execution-stop.v1', request_key: randomUUID(), ...fenceOf(assignment) };
+                state = { request_key: payload.request_key, document: await executor('stopExecution').sign(payload, signal) };
+                stops.set(key, state);
+            }
+            let raw;
+            try {
+                raw = record(await api(assignmentPath('stopExecution', assignment.assignment_id, '/stop'), { method: 'POST', body: state.document, ...options(signal) }));
+            }
+            catch (error) {
+                throw translated(error);
+            }
+            if (!raw || raw.request_key !== state.request_key || raw.assignment_id !== assignment.assignment_id
+                || raw.attempt_id !== assignment.attempt_id || raw.lease_epoch !== assignment.lease_epoch
+                || raw.state_generation !== assignment.state_generation || (raw.last_action_id !== null && !isUuid(raw.last_action_id))
+                || raw.dispatch_stopped !== true || typeof raw.cleanup_complete !== 'boolean') {
+                throw receiptInvalid('the drill stop');
+            }
+            return { request_key: state.request_key, last_action_id: raw.last_action_id, dispatch_stopped: true,
+                cleanup_complete: raw.cleanup_complete };
+        },
+        async recordClose(assignment, close, signal) {
+            const key = `${assignment.assignment_id}\0${assignment.attempt_id}`;
+            let state = closes.get(key);
+            if (state && (state.observation_sequence !== close.observation_sequence || state.driver_outcome !== close.driver_outcome)) {
+                throw new CliError('native_close_changed', 'A different close was already prepared for this drill. Nothing further was sent.');
+            }
+            if (!state) {
+                const services = close.processes.map((item) => item.service);
+                // Root's execution-close.v1 variants; "not started" only for a drill that did not complete.
+                const valid = (item) => /^[a-zA-Z][a-zA-Z0-9_.-]{0,79}$/.test(item.service) && (item.ownership === 'owned'
+                    ? item.close_kind === 'owned_group_reaped' && isUuid(item.launch_id) && Number.isSafeInteger(item.exit_code) && item.exit_code >= -255 && item.exit_code <= 255
+                    : item.ownership === 'attached' ? item.close_kind === 'transport_detached' && isUuid(item.launch_id)
+                        : item.ownership === 'owned_run' ? item.close_kind === 'transport_detached' && isUuid(item.launch_id) && isUuid(item.run_id)
+                            : item.ownership === 'none' && item.close_kind === 'not_started' && close.driver_outcome !== 'completed');
+                const summary = close.client_summary;
+                const summaryValid = summary === undefined || (STOP_REASONS.includes(summary.stop_reason)
+                    && count(summary.steps_started, 0) && count(summary.steps_completed, 0) && summary.steps_completed <= summary.steps_started
+                    && (summary.dependency_capture_complete === undefined || typeof summary.dependency_capture_complete === 'boolean')
+                    && (summary.dependency_capture_records_complete === undefined || typeof summary.dependency_capture_records_complete === 'boolean'));
+                if (!count(close.observation_sequence, 1) || !['completed', 'failed', 'cancelled'].includes(close.driver_outcome)
+                    || (close.last_action_id !== null && !isUuid(close.last_action_id)) || close.processes.length > 128
+                    || new Set(services).size !== services.length || !close.processes.every(valid) || !summaryValid) {
+                    throw new CliError('native_close_invalid', 'The drill close is malformed. Nothing was submitted.');
+                }
+                // Exactly the schema's fields for each variant.
+                const processes = close.processes.map((item) => item.ownership === 'owned'
+                    ? { service: item.service, launch_id: item.launch_id, ownership: item.ownership, close_kind: item.close_kind, exit_code: item.exit_code }
+                    : item.ownership === 'attached' ? { service: item.service, launch_id: item.launch_id, ownership: item.ownership, close_kind: item.close_kind }
+                        : item.ownership === 'owned_run' ? { service: item.service, launch_id: item.launch_id, run_id: item.run_id, ownership: item.ownership,
+                            close_kind: item.close_kind }
+                            : { service: item.service, ownership: item.ownership, close_kind: item.close_kind });
+                // One signed document per attempt: a retry re-sends the same bytes under the same keys.
+                const payload = { schema: 'firedrill.native-execution-close.v1', request_key: randomUUID(), ...fenceOf(assignment),
+                    observation_sequence: close.observation_sequence, last_action_id: close.last_action_id, driver_outcome: close.driver_outcome, processes,
+                    ...(summary ? { client_summary: { stop_reason: summary.stop_reason, steps_started: summary.steps_started,
+                            steps_completed: summary.steps_completed,
+                            ...(summary.dependency_capture_complete === undefined ? {} : { dependency_capture_complete: summary.dependency_capture_complete }),
+                            ...(summary.dependency_capture_records_complete === undefined ? {} : { dependency_capture_records_complete: summary.dependency_capture_records_complete }) } } : {}) };
+                const document = await executor('recordClose').sign(payload, signal);
+                const bytes = Buffer.from(rootCanonical(document), 'utf8');
+                if (bytes.byteLength > CLOSE_MAX_BYTES)
+                    throw new CliError('native_close_invalid', 'The drill close is too large. Nothing was submitted.');
+                state = { request_key: payload.request_key, upload_key: randomUUID(), bytes, sha256: createHash('sha256').update(bytes).digest('hex'),
+                    observation_sequence: close.observation_sequence, driver_outcome: close.driver_outcome, artifact_id: null };
+                closes.set(key, state);
+            }
+            if (!state.artifact_id) {
+                const committed = await plane.uploadArtifact(assignment, { request_key: state.upload_key, role: `driver.${state.driver_outcome}`,
+                    media_type: 'application/json', sha256: state.sha256, bytes: state.bytes }, signal);
+                if (!isUuid(committed?.artifact_id))
+                    throw receiptInvalid('the drill close record');
+                state.artifact_id = committed.artifact_id;
+            }
+            await retainClose(assignment, state);
+            return { artifact_id: state.artifact_id, sha256: state.sha256, kind: `driver.${state.driver_outcome}`,
+                observation_sequence: state.observation_sequence };
+        },
+        async submitClose(assignment, closeRecord, signal) {
+            const state = closes.get(`${assignment.assignment_id}\0${assignment.attempt_id}`);
+            if (!state || state.artifact_id === null || state.artifact_id !== closeRecord.artifact_id) {
+                throw new CliError('native_close_invalid', 'That close was not recorded for this drill. Nothing was submitted.');
+            }
+            const artifactId = state.artifact_id;
+            let raw;
+            try {
+                raw = record(await api(assignmentPath('submitClose', assignment.assignment_id, '/close'), { method: 'POST', body: { close_artifact_id: artifactId }, ...options(signal) }));
+            }
+            catch (error) {
+                throw translated(error);
+            }
+            if (!raw || !isUuid(raw.close_id) || raw.assignment_id !== assignment.assignment_id || raw.close_artifact_id !== artifactId
+                || raw.request_key !== state.request_key || raw.observation_sequence !== state.observation_sequence
+                || raw.driver_outcome !== state.driver_outcome || raw.state !== 'accepted' || !time(raw.accepted_at)) {
+                throw receiptInvalid('the drill close');
+            }
+            await rm(await closeJournalPath(assignment), { force: true });
+            forget(assignment);
+            return { close_id: raw.close_id, close_artifact_id: artifactId, observation_sequence: state.observation_sequence,
+                driver_outcome: state.driver_outcome, state: 'accepted', accepted_at: raw.accepted_at };
+        },
+        async readCleanup(assignment, signal) {
+            let raw;
+            try {
+                raw = record(await api(assignmentPath('readCleanup', assignment.assignment_id, '/cleanup'), options(signal)));
+            }
+            catch (error) {
+                // Root holds no frozen execution for this drill (not fenced, or not captured yet): nothing to report.
+                if (error instanceof CliError && (error.httpStatus === 404 || error.code === 'native_execution_cleanup_unavailable'))
+                    return null;
+                throw translated(error);
+            }
+            if (!raw || !isUuid(raw.cleanup_id) || raw.assignment_id !== assignment.assignment_id || raw.attempt_id !== assignment.attempt_id
+                || !count(raw.execution_epoch, 1) || !count(raw.state_generation, 1) || !count(raw.observation_sequence, 0)
+                || (raw.last_action_id !== null && !isUuid(raw.last_action_id)) || !['expired', 'revoked', 'cancelled'].includes(raw.reason)
+                || typeof raw.report_received !== 'boolean' || !count(raw.report_sequence, 0) || raw.report_sequence > CLEANUP_MAX_REPORTS
+                || raw.execution_authorized !== false) {
+                throw receiptInvalid('the cleanup challenge');
+            }
+            return { cleanup_id: raw.cleanup_id, assignment_id: assignment.assignment_id, attempt_id: assignment.attempt_id,
+                execution_epoch: raw.execution_epoch, state_generation: raw.state_generation,
+                observation_sequence: raw.observation_sequence, last_action_id: raw.last_action_id,
+                reason: raw.reason, report_received: raw.report_received,
+                report_sequence: raw.report_sequence };
+        },
+        async submitCleanup(assignment, challenge, processes, signal) {
+            // Root's scope is copied exactly; this client reports only for the execution it ran (same epoch and generation).
+            if (challenge.assignment_id !== assignment.assignment_id || challenge.attempt_id !== assignment.attempt_id
+                || challenge.execution_epoch !== assignment.lease_epoch || challenge.state_generation !== assignment.state_generation) {
+                throw new CliError('native_cleanup_scope_changed', 'The frozen execution is not the one this companion ran, so no cleanup was reported.');
+            }
+            const sequence = challenge.report_sequence + 1;
+            const key = `${assignment.assignment_id}\0${assignment.attempt_id}\0${challenge.cleanup_id}`;
+            let state = cleanups.get(key);
+            // A report already received that this companion did not send (or a later one) is not overwritten.
+            if (state ? state.sequence < challenge.report_sequence : challenge.report_received) {
+                throw new CliError('native_cleanup_reported', 'Cleanup for this drill was already reported. Nothing further was sent.');
+            }
+            if (!state) {
+                if (sequence > CLEANUP_MAX_REPORTS)
+                    throw new CliError('native_cleanup_invalid', 'No further cleanup report is accepted for this drill. Nothing was sent.');
+                const services = processes.map((item) => item.service);
+                const valid = (item) => /^[a-zA-Z][a-zA-Z0-9_.-]{0,79}$/.test(item.service) && (item.close_kind === 'unknown'
+                    ? (item.launch_id === null || isUuid(item.launch_id)) && ['owned', 'attached', 'owned_run', 'unknown'].includes(item.ownership)
+                    : item.ownership === 'owned' ? item.close_kind === 'owned_group_reaped' && isUuid(item.launch_id) && Number.isSafeInteger(item.exit_code)
+                        && item.exit_code >= -255 && item.exit_code <= 255
+                        : item.ownership === 'attached' ? item.close_kind === 'transport_detached' && isUuid(item.launch_id)
+                            : item.ownership === 'owned_run' ? item.close_kind === 'transport_detached' && isUuid(item.launch_id) && isUuid(item.run_id)
+                                : item.ownership === 'none' && item.close_kind === 'not_started');
+                if (processes.length > 128 || new Set(services).size !== services.length || !processes.every(valid)) {
+                    throw new CliError('native_cleanup_invalid', 'The cleanup report is malformed. Nothing was sent.');
+                }
+                // Exactly the schema's fields for each variant.
+                const entries = processes.map((item) => item.close_kind === 'unknown'
+                    ? { service: item.service, launch_id: item.launch_id, ownership: item.ownership, close_kind: item.close_kind }
+                    : item.ownership === 'owned' ? { service: item.service, launch_id: item.launch_id, ownership: item.ownership, close_kind: item.close_kind, exit_code: item.exit_code }
+                        : item.ownership === 'attached' ? { service: item.service, launch_id: item.launch_id, ownership: item.ownership, close_kind: item.close_kind }
+                            : item.ownership === 'owned_run' ? { service: item.service, launch_id: item.launch_id, run_id: item.run_id, ownership: item.ownership, close_kind: item.close_kind }
+                                : { service: item.service, ownership: item.ownership, close_kind: item.close_kind });
+                // An unknown end is never reported as stopped: the whole report is then unknown.
+                const outcome = processes.some((item) => item.close_kind === 'unknown') ? 'unknown' : 'cleanup_reported';
+                const payload = { schema: 'firedrill.native-execution-cleanup.v1', cleanup_id: challenge.cleanup_id, request_key: randomUUID(), sequence,
+                    assignment_id: challenge.assignment_id, attempt_id: challenge.attempt_id, execution_epoch: challenge.execution_epoch,
+                    state_generation: challenge.state_generation, observation_sequence: challenge.observation_sequence, last_action_id: challenge.last_action_id,
+                    outcome, processes: entries };
+                state = { request_key: payload.request_key, sequence, outcome, document: await executor('submitCleanup').sign(payload, signal) };
+                cleanups.set(key, state);
+            }
+            let raw;
+            try {
+                raw = record(await api(assignmentPath('submitCleanup', assignment.assignment_id, '/cleanup'), { method: 'POST', body: state.document, ...options(signal) }));
+            }
+            catch (error) {
+                throw translated(error);
+            }
+            if (!raw || raw.cleanup_id !== challenge.cleanup_id || raw.assignment_id !== assignment.assignment_id || raw.request_key !== state.request_key
+                || raw.sequence !== state.sequence || raw.outcome !== state.outcome || raw.process_provenance !== 'customer_device'
+                || raw.execution_authorized !== false || raw.cloud_cleanup_complete !== false
+                || !count(raw.unresolved_actions, 0) || !count(raw.unresolved_participants, 0)) {
+                throw receiptInvalid('the cleanup report');
+            }
+            forget(assignment);
+            return { cleanup_id: challenge.cleanup_id, sequence: state.sequence, outcome: state.outcome,
+                unresolved_actions: raw.unresolved_actions, unresolved_participants: raw.unresolved_participants };
+        },
+    };
+    return plane;
+}
+// ---------------------------------------------------------------------------
+// Error classification.
+/** Codes that mean the cloud did not answer; the same request may be repeated when it is idempotent. */
+const TRANSIENT_CODES = new Set(['connection_uncertain', 'response_unavailable', NATIVE_ERRORS.disconnected]);
+const TRANSIENT_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+export function errorCode(error) {
+    return error instanceof CliError ? error.code : null;
+}
+/** True when the failure is a connectivity or temporary service condition, not a refusal. */
+export function isTransient(error) {
+    if (!(error instanceof CliError))
+        return false;
+    if (TRANSIENT_CODES.has(error.code))
+        return true;
+    return error.httpStatus !== null && TRANSIENT_STATUS.has(error.httpStatus);
+}
+export function isRevocation(error) {
+    return errorCode(error) === NATIVE_ERRORS.revoked;
+}
+/** Lease or generation fence: this attempt may no longer act. */
+export function isFenced(error) {
+    const code = errorCode(error);
+    return code === NATIVE_ERRORS.lease_expired || code === NATIVE_ERRORS.stale_generation;
+}
+export function isAbort(error, signal) {
+    return (signal?.aborted ?? false) || (error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError'));
+}
+// ---------------------------------------------------------------------------
+// Backoff, sleep and bounded retry.
+/** Capped exponential backoff with jitter in [delay/2, delay]. `attempt` starts at 0. */
+export function backoffMs(attempt, baseMs, capMs) {
+    const exp = Math.min(capMs, baseMs * 2 ** Math.min(Math.max(attempt, 0), 30));
+    return Math.round(exp / 2 + Math.random() * (exp / 2));
+}
+/** Interval with jitter in [0.8, 1.0] of `ms`, so the server interval is never exceeded. */
+export function jitteredInterval(ms) {
+    return Math.max(1, Math.round(ms * (0.8 + Math.random() * 0.2)));
+}
+/** Resolves true after `ms`, or false as soon as `signal` aborts. Never rejects. */
+export function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolve(value);
+        };
+        const onAbort = () => finish(false);
+        const timer = setTimeout(() => finish(true), Math.max(0, ms));
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Repeat `operation` only on transient failures, with capped backoff. Use only
+ * for operations the cloud treats idempotently (same ids/intent). Refusals,
+ * fences, revocation and pending contracts are rethrown immediately.
+ */
+export async function retryTransient(operation, options) {
+    const attempts = Math.max(1, options.attempts ?? 5);
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await operation(attempt);
+        }
+        catch (error) {
+            if (!isTransient(error) || options.signal.aborted || attempt + 1 >= attempts)
+                throw error;
+            options.onTransient?.(error, attempt);
+            if (!await sleep(backoffMs(attempt, options.baseMs ?? 500, options.capMs ?? 15_000), options.signal))
+                throw error;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Connection gate: pauses new steps while the companion is disconnected.
+export class ConnectionGate {
+    #connected = true;
+    #waiters = new Set();
+    #listeners = new Set();
+    get connected() { return this.#connected; }
+    /** Mark disconnected. Returns true when this call changed the state. */
+    disconnected() {
+        if (!this.#connected)
+            return false;
+        this.#connected = false;
+        this.#notifyChange();
+        return true;
+    }
+    /** Mark reconnected and release paused waiters. Returns true when this call changed the state. */
+    reconnected() {
+        if (this.#connected)
+            return false;
+        this.#connected = true;
+        for (const resolve of this.#waiters)
+            resolve();
+        this.#waiters.clear();
+        this.#notifyChange();
+        return true;
+    }
+    /** Resolves true once connected, false if `signal` aborts first. */
+    wait(signal) {
+        if (this.#connected)
+            return Promise.resolve(true);
+        if (signal.aborted)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            const onConnected = () => { signal.removeEventListener('abort', onAbort); resolve(true); };
+            const onAbort = () => { this.#waiters.delete(onConnected); resolve(false); };
+            this.#waiters.add(onConnected);
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    /** Subscribe to state changes (used to wake the reconnect loop early). Returns the unsubscribe function. */
+    onChange(listener) {
+        this.#listeners.add(listener);
+        return () => { this.#listeners.delete(listener); };
+    }
+    #notifyChange() {
+        for (const listener of [...this.#listeners])
+            listener();
+    }
+}