firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/native/drill-runner.js

@@ -0,0 +1,1562 @@
+/**
+ * One native drill attempt (Plan20 W09, spec 3.5).
+ *
+ * `runDrill(assignment, deps)`:
+ *  1. verify the attempt (ids, lease epoch, state generation, expiry, descriptor,
+ *     plan and adapter digests, budgets);
+ *  2. check that the approved plan routes every declared dependency (before
+ *     waiting for root); once root prepared the drill, start the per-drill
+ *     loopback dependency proxy, validate the synthetic identity, and build
+ *     per-service dependency env (and the drill-scoped MCP client configuration
+ *     when the plan names its variable);
+ *  3. apply target state resets (approved hooks) through target-state;
+ *  4. ensure shared services, start per-drill service copies;
+ *  5. prepare the driver; loop `nextSteps` (root's offered actions) within budgets. For
+ *     each step: lease/expiry check, `intent_id` required for non-idempotent
+ *     steps, `stepStarted` (the claim) before invoke, invoke only the dispatch
+ *     the claim returned, with a bounded timeout; buffer observations; for a
+ *     message step, record the reply as a v2 target message and wait for its
+ *     acknowledgement; then `completeStep`. A recovered claim is never invoked,
+ *     and an `unknown` outcome is never replayed: both are marked handled by id.
+ *     A claimed input the driver itself says never reached the target (refused
+ *     here, or nothing written) is withdrawn with a signed `abandon`, and the
+ *     drill ends; unknown delivery is never declared;
+ *  6. stop on cloud cancel, local stop, lease expiry, budget exhaustion or
+ *     revocation; close driver sessions; stop and reap owned per-drill services;
+ *     flush observations; then close the execution with a signed close that
+ *     states, for every declared service, whether its owned process group was
+ *     reaped (with its exit code) or an attached process was only detached.
+ *
+ * Commands, argv and paths come only from the locally approved plan; nothing in
+ * the assignment or a step is executed. `runDrill` never throws: every failure
+ * becomes a reported outcome with a stable reason code.
+ */
+import { CliError } from '../http.js';
+import { COMPLETE_ENDINGS, ENDING_TEXT, NATIVE_ERRORS, NATIVE_ID, SHA256_HEX, SecretValue, activeTime, nativeError } from './contracts.js';
+import { sha256Hex } from './canonical.js';
+import { dependencyEnv, mcpServers, validateDependencyRoutes } from './bindings.js';
+import { DEPENDENCY_ERRORS, DependencyProxy } from './dependency-proxy.js';
+import { writeMcpConfig } from './mcp-config.js';
+import { applyDrillState, planStateActions } from './target-state.js';
+import { READINESS_ERRORS, readinessDomains, readinessServices, resetEvidence } from './readiness.js';
+import { identitySecrets, validateIdentityGrant } from './target-auth.js';
+import { buildServiceEnv, exitCode } from './supervisor.js';
+import { localSecretBindings } from './local-secrets.js';
+import { allocateLoopbackPort } from './ports.js';
+import { driverFor } from './drivers/index.js';
+import { DRIVER_ERRORS } from './drivers/types.js';
+import { ObservationBuffer } from './observations.js';
+import { Wakeup } from './companion-channel.js';
+import { backoffMs, errorCode, isFenced, isRevocation, isTransient, retryTransient, sleep } from './control-plane.js';
+/** Reason codes for drill outcomes that are not thrown errors (proposed additions to NATIVE_ERRORS). */
+export const DRILL_REASONS = {
+    companion_stopped: 'native_companion_stopped',
+    intent_missing: 'native_intent_missing',
+    step_invalid: 'native_step_invalid',
+    assignment_invalid: 'native_assignment_invalid',
+    state_reset_failed: 'native_state_reset_failed',
+    drill_failed: 'native_drill_failed',
+    step_report_failed: 'native_step_report_failed',
+    /** A message step finished but its reply was not acknowledged as evidence (or there was none). */
+    reply_undelivered: 'native_target_reply_undelivered',
+    /** A task or event step finished but its result was not acknowledged as evidence. */
+    result_undelivered: 'native_target_result_undelivered',
+    /** The target's retained task or event result said it failed; root then ends the input. */
+    target_failed: 'native_target_failed',
+    /** The target's retained task or event result said it was cancelled; root then ends the input. */
+    target_cancelled: 'native_target_cancelled',
+    /**
+     * Root ended the input because it could not generate the simulated participant's next message in time
+     * (`participant_unavailable`). An infrastructure ending: the drill closes incomplete, never as a result.
+     */
+    participant_unavailable: 'native_participant_unavailable',
+    /** The service never reported the accepted drill as prepared before it had to stop. */
+    not_prepared: 'native_drill_not_prepared',
+    /** The service began draining the drill (cancelled, or capacity or startup refused) before it started. */
+    draining: 'native_assignment_draining',
+    /** The service did not confirm the stop, so the drill has no exact cutoff to close on. */
+    stop_unconfirmed: 'native_stop_unconfirmed',
+};
+/** Root execution states in which the local target may start (after capacity and dependency bindings are prepared). */
+const PREPARED_STATES = new Set(['starting', 'ready', 'executing']);
+/** States after root admitted the drill's readiness: target actions may follow. */
+const ADMITTED_STATES = new Set(['ready', 'executing']);
+/** States in which an accepted drill is still being prepared by the service. */
+const PREPARING_STATES = new Set(['accepted', 'provisioning']);
+const ROOT_TERMINAL_STATES = new Set(['rejected', 'expired', 'completed', 'failed', 'cancelled']);
+const PREPARE_CHECK_MS = 1_000;
+/** Lease renewal (which also reports root's state) backs off from 2s to 15s while the drill is being prepared. */
+const PREPARE_RENEW_MIN_MS = 2_000;
+const PREPARE_RENEW_MAX_MS = 15_000;
+const LEASE_MARGIN_MS = 2_000;
+/**
+ * Root refuses a close while a participant response it already dispatched is
+ * unfinished (`native_execution_close_pending`) or its ending projection is
+ * still pending. Those end within root's
+ * participant deadline (at most 90 s), so the same close is resubmitted for
+ * this long while the lease holds.
+ */
+const CLOSE_PENDING_WAIT_MS = 120_000;
+const MAX_DRIVER_SESSIONS = 64;
+const EVENT_SESSION_KEY = 'events';
+// ---------------------------------------------------------------------------
+// Service pool: one Supervisor per companion run. Shared services (attach, or
+// launch with per_drill false) start once; per_drill launch services start a
+// fresh copy per drill with that drill's binding env.
+function isPerDrill(service) {
+    return service.mode === 'launch' && service.per_drill;
+}
+/** Topological order of plan services following descriptor depends_on (stable by plan order). */
+function startupOrder(plan, descriptor) {
+    const depends = new Map(descriptor.services.map((service) => [service.alias, service.depends_on]));
+    const order = [];
+    const state = new Map();
+    const visit = (alias) => {
+        const mark = state.get(alias);
+        if (mark === 'done')
+            return;
+        if (mark === 'visiting')
+            throw nativeError('plan_changed', 'Services were not started: the descriptor service dependencies form a cycle.');
+        state.set(alias, 'visiting');
+        for (const dependency of depends.get(alias) ?? [])
+            visit(dependency);
+        state.set(alias, 'done');
+        order.push(alias);
+    };
+    for (const service of plan.services)
+        visit(service.alias);
+    const planned = new Set(plan.services.map((service) => service.alias));
+    return order.filter((alias) => planned.has(alias));
+}
+export class ServicePool {
+    supervisor;
+    #plan;
+    #order;
+    #signal;
+    constructor(options) {
+        this.supervisor = options.supervisor;
+        this.#plan = options.plan;
+        this.#signal = options.signal;
+        this.#order = startupOrder(options.plan, options.descriptor);
+        const perDrill = new Set(options.plan.services.filter(isPerDrill).map((service) => service.alias));
+        const depends = new Map(options.descriptor.services.map((service) => [service.alias, service.depends_on]));
+        for (const service of options.plan.services) {
+            if (perDrill.has(service.alias))
+                continue;
+            if ((depends.get(service.alias) ?? []).some((dependency) => perDrill.has(dependency))) {
+                throw nativeError('plan_changed', `Services were not started: shared service "${service.alias}" depends on a per-drill service. Make it per-drill or change the plan.`);
+            }
+        }
+    }
+    get perDrillAliases() {
+        const perDrill = new Set(this.#plan.services.filter(isPerDrill).map((service) => service.alias));
+        return this.#order.filter((alias) => perDrill.has(alias));
+    }
+    /**
+     * Start or reuse every shared service. Not cached here: the supervisor reuses
+     * live shared entries and dedupes concurrent starts, so each drill gets current
+     * handles rather than a dead one. A shared service of the campaign's local run
+     * starts once under its registered launch id and is never restarted (an ended
+     * one fails the drill with `native_local_run_service_ended`).
+     */
+    async shared() {
+        const perDrill = new Set(this.perDrillAliases);
+        const aliases = this.#order.filter((alias) => !perDrill.has(alias));
+        if (aliases.length === 0)
+            return new Map();
+        const handles = await this.supervisor.start(aliases, { drillKey: 'shared', env: {}, secrets: [], signal: this.#signal });
+        return new Map(handles.map((handle) => [handle.alias, handle]));
+    }
+    /**
+     * Start one fresh copy of each per-drill service, in dependency order, one
+     * supervisor call per service so each receives only its own binding env
+     * (dependencies already started for this drill key are reused by the
+     * supervisor). The jsonl-process driver's own service is skipped by the
+     * supervisor; the driver starts it with the driver env.
+     */
+    async startPerDrill(drillKey, envFor, signal, onStarted) {
+        for (const alias of this.perDrillAliases) {
+            if (signal.aborted)
+                throw nativeError('disconnected', 'Per-drill services were not all started: the drill was stopped.');
+            const { env, secrets } = envFor(alias);
+            const handles = await this.supervisor.start([alias], { drillKey, env, secrets, signal });
+            for (const handle of handles)
+                onStarted(handle);
+        }
+    }
+    /** Stop every per-drill copy this drill key owns (reverse start order). Shared services keep running. */
+    async stopDrill(drillKey, reason) {
+        await this.supervisor.stopDrill(drillKey, reason.slice(0, 64)).catch(() => undefined);
+    }
+    /** Every per-drill process launched for this drill key, ready or not (once, after stopDrill), for the signed close. */
+    takeLaunches(drillKey) {
+        return this.supervisor.takeDrillLaunches(drillKey);
+    }
+}
+// ---------------------------------------------------------------------------
+// Attempt verification.
+function leaseRemainingMs(assignment) {
+    const expires = Date.parse(assignment.lease_expires_at);
+    return Number.isFinite(expires) ? expires - Date.now() : -1;
+}
+function verifyAssignment(assignment, deps) {
+    const invalid = (what) => new CliError(DRILL_REASONS.assignment_invalid, `The drill was not started: the assignment ${what}.`);
+    const int = (value, min) => typeof value === 'number' && Number.isSafeInteger(value) && value >= min;
+    if (!NATIVE_ID.test(assignment.assignment_id ?? '') || !NATIVE_ID.test(assignment.attempt_id ?? ''))
+        throw invalid('identity is malformed');
+    if (!int(assignment.lease_epoch, 1))
+        throw invalid('lease epoch is malformed');
+    if (!int(assignment.state_generation, 1))
+        throw invalid('state generation is malformed');
+    if (!int(assignment.step_cursor, 0) || !int(assignment.observation_ack, 0))
+        throw invalid('cursor is malformed');
+    if (leaseRemainingMs(assignment) <= LEASE_MARGIN_MS)
+        throw nativeError('lease_expired', 'The drill was not started: its lease has expired.');
+    if (!SHA256_HEX.test(assignment.descriptor_sha256 ?? '') || assignment.descriptor_sha256 !== deps.plan.descriptor_sha256) {
+        throw nativeError('plan_changed', 'The drill was not started: it targets a different descriptor than the approved plan.');
+    }
+    const driver = assignment.driver;
+    if (!driver || driver.profile !== deps.descriptor.driver.profile || driver.profile !== deps.plan.driver.profile
+        || driver.adapter_sha256 !== deps.descriptor.driver.adapter_sha256) {
+        throw nativeError('plan_changed', 'The drill was not started: its driver or adapter digest differs from the approved plan.');
+    }
+    const budgets = assignment.budgets;
+    if (!budgets || !int(budgets.max_steps, 1) || !int(budgets.max_elapsed_ms, 1) || !int(budgets.step_timeout_ms, 1)
+        || !int(budgets.max_observation_bytes, 1))
+        throw invalid('budgets are malformed');
+}
+/**
+ * A service whose process starts afresh for every drill, so it can receive the
+ * drill's dependency URLs: a per-drill launch, or the service the jsonl-process
+ * driver starts itself for each drill. Shared and attached processes cannot.
+ */
+export function freshForDrill(plan) {
+    return (service) => isPerDrill(service)
+        || (plan.driver.profile === 'jsonl-process.v1' && plan.driver.service_alias === service.alias);
+}
+/**
+ * Env for driver-owned child processes (jsonl-process service, function wrapper),
+ * built with the supervisor's rules (empty base, passthrough names, env_static,
+ * binding env; undeclared secret configuration stripped).
+ */
+async function driverEnv(service, descriptor, binding, plan, services, signal) {
+    if (!service) {
+        const base = process.platform === 'win32'
+            ? ['PATH', 'SystemRoot', 'TEMP', 'TMP', 'USERPROFILE', 'PATHEXT', 'ComSpec', 'LANG']
+            : ['PATH', 'HOME', 'LANG', 'TMPDIR'];
+        const env = {};
+        for (const name of base) {
+            const value = process.env[name];
+            if (typeof value === 'string')
+                env[name] = value;
+        }
+        return { ...env, ...binding };
+    }
+    const declared = descriptor.services.find((entry) => entry.alias === service.alias);
+    const configuration = declared?.configuration ?? [];
+    const secretNames = new Set(configuration.filter((item) => item.secret).map((item) => item.name));
+    // Same port rules as supervisor-launched services: an allocated loopback port
+    // under port_env, and each started dependency's port under its own port_env.
+    const port = service.port_env ? await allocateLoopbackPort(signal) : null;
+    const dependencyPorts = [];
+    for (const dependency of declared?.depends_on ?? []) {
+        const handle = services.get(dependency), dependencyPlan = plan.services.find((entry) => entry.alias === dependency);
+        if (handle?.port && dependencyPlan?.port_env)
+            dependencyPorts.push([dependencyPlan.port_env, handle.port]);
+    }
+    return buildServiceEnv({ service, secretNames, bindingEnv: binding, port, dependencyPorts });
+}
+/** Step shape checks before anything is sent. Returns a reason code or null. */
+function stepProblem(step) {
+    if (!step || typeof step !== 'object' || typeof step.step_id !== 'string' || !NATIVE_ID.test(step.step_id))
+        return DRILL_REASONS.step_invalid;
+    if (!Number.isSafeInteger(step.sequence) || step.sequence < 1)
+        return DRILL_REASONS.step_invalid;
+    if (!step.payload || step.payload.kind !== step.kind || !['message', 'task', 'event'].includes(step.kind))
+        return DRILL_REASONS.step_invalid;
+    if (typeof step.idempotent !== 'boolean')
+        return DRILL_REASONS.step_invalid;
+    if (!step.idempotent && (typeof step.intent_id !== 'string' || !NATIVE_ID.test(step.intent_id)))
+        return DRILL_REASONS.intent_missing;
+    if (step.payload.kind !== 'event' && (typeof step.payload.session_key !== 'string' || !NATIVE_ID.test(step.payload.session_key))) {
+        return DRILL_REASONS.step_invalid;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// The drill.
+/** Driver codes for an input the client declined to send (versus one it tried and could not deliver). */
+const REFUSAL_CODES = new Set([DRIVER_ERRORS.intent_missing, DRIVER_ERRORS.step_unsupported,
+    DRIVER_ERRORS.session_mismatch, DRIVER_ERRORS.session_closed, DRIVER_ERRORS.event_invalid, DRIVER_ERRORS.not_loopback,
+    DRIVER_ERRORS.driver_plan_invalid]);
+export async function runDrill(assignment, deps) {
+    const startedAt = Date.now();
+    const { controlPlane, plan, descriptor, output } = deps;
+    const drillKey = `d${sha256Hex(`${assignment.assignment_id}\0${assignment.attempt_id}`).slice(0, 24)}`;
+    const label = `drill ${typeof assignment.drill_id === 'string' && NATIVE_ID.test(assignment.drill_id) ? assignment.drill_id : 'assignment'}`;
+    const transport = deps.abortSignal;
+    const retry = { signal: transport, attempts: 5, onTransient: () => { deps.gate.disconnected(); } };
+    const secrets = [];
+    const sessions = new Map();
+    const drillController = new AbortController();
+    const onStop = () => drillController.abort();
+    deps.abortSignal.addEventListener('abort', onStop, { once: true });
+    let stop = null;
+    /** Why root said the participant's input ended, when it did. */
+    let endingReason = null;
+    let schedule = null;
+    const stopWith = (outcome, reason) => { if (!stop)
+        stop = { outcome, reason }; };
+    /** Set when lease renewal was refused (fence or revocation); checked before every step. */
+    let leaseStop = null;
+    let leaseDeadlineTimer;
+    const watchLeaseDeadline = () => {
+        if (drillController.signal.aborted)
+            return;
+        const remaining = leaseRemainingMs(assignment) - LEASE_MARGIN_MS;
+        if (!Number.isFinite(remaining) || remaining <= 0) {
+            leaseStop ??= { outcome: 'incomplete', reason: NATIVE_ERRORS.lease_expired };
+            drillController.abort();
+            return;
+        }
+        // Renewal mutates the original assignment expiry. Re-read it when this
+        // deadline wakes rather than treating the first short lease as a turn limit.
+        leaseDeadlineTimer = setTimeout(watchLeaseDeadline, Math.min(remaining, 2_147_483_647));
+    };
+    drillController.signal.addEventListener('abort', () => {
+        if (leaseDeadlineTimer !== undefined)
+            clearTimeout(leaseDeadlineTimer);
+    }, { once: true });
+    const leaseControl = new AbortController();
+    let leaseKeeper = Promise.resolve();
+    /**
+     * The companion's campaign channel (one per device), when this drill is in its campaign. Nothing is read, stepped
+     * or started while it waits for a valid resync; without it (no channel) the drill re-reads on bounded timers.
+     */
+    const channel = controlPlane.wakes && assignment.campaign_id === controlPlane.wakes.campaign_id ? controlPlane.wakes : null;
+    /** Root's wake-ups for this assignment from the channel. */
+    let assignmentWake = null;
+    let unwatchChannel = () => { };
+    /**
+     * The drill's local waits: woken by the channel (this assignment, a resync, a state change) and by local news (root's
+     * state from a lease renewal, a lost lease, a failed dependency), so a wait never polls root.
+     */
+    const progress = new Wakeup();
+    /** Until the next time-based halt (the lease margin or the drill's elapsed budget), so a local wait re-checks it on time. */
+    const haltDue = () => AbortSignal.timeout(Math.max(1, Math.min(2_147_483_647, leaseRemainingMs(assignment) - LEASE_MARGIN_MS, assignment.budgets.max_elapsed_ms - (Date.now() - startedAt))));
+    let buffer = null;
+    let tracker = null;
+    let driver = null;
+    let mcpConfigs = [];
+    /** The per-drill loopback proxy to root's tool gateway, when the target declares dependencies. */
+    let proxy = null;
+    /** Set when root refused dependency access for good (fence, revocation, closed, changed binding); checked before every step. */
+    let dependencyStop = null;
+    let scratch = null;
+    let steps = 0;
+    /** Invoked steps whose invocation completed, for the close's client summary. */
+    let completedSteps = 0;
+    let unknownSteps = 0;
+    let cursor = assignment.step_cursor;
+    /**
+     * Actions this attempt claimed (invoked or recovered): never claimed or invoked again. Root numbers participant
+     * turns and scripted, task and event actions separately, so two actions can share a sequence; ids are the cursor.
+     */
+    const handled = new Set();
+    /** A step whose claim got no answer: root hides a claimed action from the offered list, so it is replayed with the same key. */
+    let unconfirmed = null;
+    /** A step result the cloud has not confirmed yet (transient failure); re-sent before the next step, never re-invoked. */
+    let pendingReport = null;
+    /** This client claimed a target action that root has not seen completed; root refuses a close until it is resolved. */
+    let claimOpen = false;
+    /** Every service handle this drill used (shared and per-drill), for the signed close. */
+    let drillServices = new Map();
+    /** Root's execution state as last reported by a lease renewal; an accepted offer starts as `accepted`. */
+    let rootState = 'accepted';
+    /** Root reported the drill prepared, so it accepts evidence and a close. */
+    let prepared = false;
+    const requireLaunchAuthority = async () => {
+        for (;;) {
+            const halt = leaseStop ?? dependencyStop ?? preStepHalt(assignment, deps, startedAt, steps) ?? prepareHalt(rootState);
+            if (halt)
+                throw new CliError(halt.reason ?? DRILL_REASONS.not_prepared, 'The drill can no longer start local work.');
+            if (drillController.signal.aborted || channel?.state === 'closed') {
+                throw new CliError('native_stream_disconnected', 'The runner connection closed before launch. No new process was started.');
+            }
+            if (deps.gate.connected && (!channel || channel.state === 'live'))
+                return;
+            // A wake timer is a snapshot of the current lease, not a revocation.
+            // The server may renew while the notification channel is reconnecting.
+            // Re-read the live lease and budget before waiting again or launching.
+            const signal = AbortSignal.any([deps.stopSignal, transport, drillController.signal, haltDue()]);
+            if (await deps.gate.wait(signal) && channel)
+                await channel.live(signal);
+        }
+    };
+    const observe = (observation) => { buffer?.add(observation); };
+    /**
+     * Withdraw this client's claim of a step whose input never reached the target, with the device's signed
+     * declaration (refused here, or not delivered). Root cancels the action and drains the drill, so the close
+     * no longer waits on it. It is never proof of a target failure, and a refused withdrawal leaves the claim
+     * for root's normal close and cleanup to settle.
+     */
+    const withdrawClaim = async (step, code) => {
+        const reason = code !== null && REFUSAL_CODES.has(code) ? 'client_refused' : 'not_delivered';
+        try {
+            const withdrawal = await retryTransient(() => controlPlane.abandonStep(assignment, step, reason, transport), retry);
+            claimOpen = false;
+            observe({ kind: 'action.observed', at_ms: Date.now(), content: { type: 'target.withdrawn', step_id: step.step_id, reason } });
+            // The code says why (a driver refusal or delivery failure, or a runner-side halt such as a reconnecting
+            // stream, lease, budget or dependency stop), since `reason` alone cannot tell them apart.
+            output('native_step_withdrawn', { assignment_id: assignment.assignment_id, step_id: step.step_id, sequence: step.sequence,
+                reason, error_code: code, withdrawn_at: withdrawal.withdrawn_at }, `${label}: step ${step.sequence} never reached the target (${reason === 'client_refused' ? 'refused on this machine' : 'not delivered'}`
+                + `${code ? `, ${code}` : ''}); its claim was withdrawn and the drill is ending.`);
+        }
+        catch (error) {
+            output('native_step_withdraw_failed', { assignment_id: assignment.assignment_id, step_id: step.step_id, error_code: errorCode(error) }, `${label}: step ${step.sequence}'s claim could not be withdrawn (${errorCode(error) ?? 'unknown error'}); inspect its original cleanup status. Do not repeat the target action.`);
+        }
+    };
+    try {
+        verifyAssignment(assignment, deps);
+        watchLeaseDeadline();
+        if (channel) {
+            assignmentWake = channel.subscribe({ kind: 'assignment', id: assignment.assignment_id });
+            assignmentWake.onWake(() => progress.wake());
+            unwatchChannel = channel.onState(() => progress.wake());
+        }
+        // Root leases last about a minute; keep this one live until the evidence is flushed.
+        leaseKeeper = keepLease(assignment, controlPlane, AbortSignal.any([leaseControl.signal, transport]), (state) => { leaseStop = state; drillController.abort(); progress.wake(); }, (state) => { if (state !== rootState) {
+            rootState = state;
+            progress.wake();
+        } }, () => !ADMITTED_STATES.has(rootState), assignmentWake);
+        buffer = new ObservationBuffer({
+            controlPlane, assignment, startedAtMs: startedAt, signal: transport,
+            maxBufferedBytes: deps.observationBufferBytes, onTransient: () => { deps.gate.disconnected(); },
+        });
+        // Root admits a drill only with reset evidence for every local state domain:
+        // one this client cannot reset is refused before anything is waited for or started.
+        const statePlan = planStateActions(descriptor, plan);
+        const resetDomains = readinessDomains(descriptor, statePlan);
+        // Every declared dependency must reach the target only through this drill's
+        // proxy; an unrouted one is refused now, never left to reach a live service.
+        const routes = validateDependencyRoutes(descriptor, plan, { freshForDrill: freshForDrill(plan) });
+        // Accepting does not start the drill: root's controller reserves capacity and
+        // prepares bindings, then reports it as starting. Nothing starts locally before that,
+        // nor while the campaign channel waits for a valid resync.
+        if (!PREPARED_STATES.has(rootState)) {
+            output('native_drill_waiting', { assignment_id: assignment.assignment_id, state: rootState }, `Waiting for the service to prepare ${label}.`);
+        }
+        for (;;) {
+            const seen = progress.generation;
+            if (PREPARED_STATES.has(rootState) && (!channel || channel.state === 'live'))
+                break;
+            const halt = leaseStop ?? dependencyStop ?? preStepHalt(assignment, deps, startedAt, steps) ?? prepareHalt(rootState);
+            if (halt) {
+                stopWith(halt.outcome, halt.reason ?? DRILL_REASONS.not_prepared);
+                throw new CliError(halt.reason ?? DRILL_REASONS.not_prepared, `${label} stopped before the service prepared it. Nothing started locally.`);
+            }
+            // Local only: a renewal reporting root's state, the channel or a time-based halt wakes it.
+            await progress.wait(seen, AbortSignal.any([deps.stopSignal, transport, channel ? haltDue() : AbortSignal.timeout(PREPARE_CHECK_MS)]));
+        }
+        prepared = true;
+        output('native_drill_started', { assignment_id: assignment.assignment_id, attempt_id: assignment.attempt_id,
+            drill_id: assignment.drill_id ?? null }, `Started ${label}.`);
+        // Identity, validated before anything starts.
+        const identity = validateIdentityGrant(assignment.identity ?? null, descriptor);
+        secrets.push(...identitySecrets(identity));
+        scratch = await deps.scratch.drill(drillKey);
+        // Dependencies: stable loopback URLs now; root's tokens are fetched lazily once
+        // the drill is admitted and never leave this process.
+        if (routes.length > 0) {
+            proxy = await DependencyProxy.start({
+                controlPlane, assignment, descriptor, signal: drillController.signal,
+                onExchange: (exchange) => {
+                    if (exchange)
+                        buffer?.add({ kind: 'action.observed', at_ms: Date.now(), content: {}, dependency_exchange: exchange });
+                    else
+                        buffer?.dependencyCaptureUnavailable();
+                },
+                // Root's 503 "no gateway" is permanent for the run, not a disconnection.
+                onFatal: (error) => {
+                    dependencyStop ??= errorCode(error) === DEPENDENCY_ERRORS.unavailable
+                        ? { outcome: 'failed', reason: DEPENDENCY_ERRORS.unavailable } : classify(error);
+                    progress.wake();
+                },
+            });
+            secrets.push(proxy.secret);
+        }
+        const urls = proxy ?? { url: () => { throw nativeError('binding_invalid', 'No dependency proxy runs for this drill.'); } };
+        const serviceEnv = new Map();
+        for (const service of plan.services) {
+            const mapped = dependencyEnv(routes, service.alias, urls);
+            const env = { ...mapped.env };
+            const own = [...mapped.secrets];
+            const mcp = await writeServiceMcpConfig(routes, service, urls, scratch.path);
+            if (mcp) {
+                mcpConfigs.push(mcp);
+                Object.assign(env, mcp.env);
+                own.push(...mcp.secrets);
+            }
+            const local = localSecretBindings(service, env);
+            own.push(...local.secrets);
+            serviceEnv.set(service.alias, { env: local.env, secrets: own });
+            secrets.push(...own);
+        }
+        // Target state resets (approved hooks) before the target starts.
+        await requireLaunchAuthority();
+        tracker = await applyDrillState(statePlan, {
+            plan, signal: AbortSignal.any([deps.stopSignal, transport]), drillKey,
+        });
+        for (const run of tracker.hookRuns) {
+            if (run.result === 'applied')
+                continue; // applied hooks are recorded as reset evidence once the drill is ready
+            observe({ kind: 'state.observed', at_ms: Date.now(), content: { type: 'state.reset', domain: run.domain_alias, result: run.result,
+                    error_code: run.error_code, exit_code: run.exit_code, duration_ms: run.duration_ms } });
+        }
+        if (tracker.planChanged())
+            throw nativeError('plan_changed', 'The drill was not continued: an approved reset hook changed on disk. Approve the plan again.');
+        if (tracker.failures().length > 0)
+            throw new CliError(DRILL_REASONS.state_reset_failed, 'The drill was not started: a declared state reset failed.');
+        // Services: shared once per run, per-drill copies for this drill.
+        const startSignal = AbortSignal.any([deps.stopSignal, transport]);
+        await requireLaunchAuthority();
+        const services = new Map(await deps.services.shared());
+        drillServices = services;
+        // Root admits run-owned services only once it knows them running: report a
+        // first launch (or any change) and have it confirmed before readiness.
+        const localRun = deps.localRun ?? null;
+        if (localRun)
+            await retryTransient(() => localRun.sync(transport), retry);
+        const activeTracker = tracker;
+        await requireLaunchAuthority();
+        await deps.services.startPerDrill(drillKey, (alias) => serviceEnv.get(alias) ?? { env: {}, secrets: [] }, startSignal, (handle) => {
+            services.set(handle.alias, handle);
+            if (handle.drillKey === drillKey)
+                activeTracker.markFreshProcess(handle.alias);
+        });
+        // Driver.
+        driver = driverFor(plan.driver.profile, { plan });
+        const availability = await driver.describe();
+        if (!availability.available)
+            throw nativeError('driver_unavailable', `The drill was not started: the ${plan.driver.profile} driver is unavailable locally.`);
+        const driverService = 'service_alias' in plan.driver ? plan.driver.service_alias : descriptor.entry_service;
+        // The event receiver's signing secret: read here, by the name the approved plan gives, never from the cloud.
+        const signingName = plan.driver.profile === 'signed-http-event.v1' ? plan.driver.signing_secret_env ?? null : null;
+        const signingValue = signingName === null ? undefined : process.env[signingName];
+        if (signingName !== null && (typeof signingValue !== 'string' || signingValue.length === 0 || signingValue.includes('\0'))) {
+            throw nativeError('driver_unavailable', `The drill was not started: the approved event signing secret ${signingName} is not set in this environment.`);
+        }
+        const eventSigningKey = signingName === null ? null : new SecretValue(signingValue);
+        if (eventSigningKey)
+            secrets.push(eventSigningKey);
+        const ctx = {
+            plan, driver: plan.driver, adapterSha256: descriptor.driver.adapter_sha256, services, roots: deps.roots,
+            env: await driverEnv(plan.services.find((service) => service.alias === driverService), descriptor, serviceEnv.get(driverService)?.env ?? {}, plan, services, startSignal),
+            identity, eventSigningKey, secrets, scratch: scratch.path, signal: drillController.signal, observe,
+        };
+        await requireLaunchAuthority();
+        await driver.prepare(ctx);
+        // The jsonl-process driver starts its own service afresh for every drill
+        // (the supervisor skips it), so that service's fresh-process reset applied.
+        if (plan.driver.profile === 'jsonl-process.v1')
+            activeTracker.markFreshProcess(plan.driver.service_alias);
+        // Readiness. Each local domain's reset is committed as evidence; the signed
+        // readiness record cites those records, every service and the entry probe,
+        // and goes to root with the drill's only driver.started observation. Root then
+        // admits the drill (ready) on its own; this client never sets it. A resumed
+        // drill root already admitted does not send a second one.
+        const activeBuffer = buffer;
+        const activeDriver = driver;
+        const ownedLaunches = new Map((driver.ownedProcesses?.() ?? []).map((item) => [item.alias, item.launch_id]));
+        const freshLaunch = (alias) => {
+            const handle = services.get(alias);
+            return handle?.mode === 'launch' && handle.drillKey === drillKey ? handle.launchId : ownedLaunches.get(alias) ?? null;
+        };
+        const resetRecords = resetDomains.map((action) => ({ action, event_id: activeBuffer.add({ kind: 'state.observed', at_ms: Date.now(),
+                content: resetEvidence(action, activeTracker, freshLaunch) }, true) }));
+        if (!ADMITTED_STATES.has(rootState)) {
+            const entryProbe = await activeDriver.readinessProbe(ctx);
+            const readyServices = readinessServices(descriptor, plan, services, activeDriver, entryProbe, drillKey, deps.localRun?.runService ?? (() => null));
+            const undelivered = await activeBuffer.submitReadiness(async (sequence) => {
+                const stateResets = [];
+                for (const { action, event_id: eventId } of resetRecords) {
+                    const record = eventId ? activeBuffer.record(eventId) : null;
+                    if (!record || action.action === 'unavailable' || action.action === 'not-applicable')
+                        return READINESS_ERRORS.evidence_missing;
+                    stateResets.push({ alias: action.alias, reset: action.action, hook_sha256: action.descriptor_hook_sha256,
+                        evidence_artifact_id: record.artifact_id, evidence_sha256: record.sha256 });
+                }
+                return retryTransient(() => controlPlane.recordReadiness(assignment, { observation_sequence: sequence,
+                    descriptor_digest: assignment.descriptor_sha256, services: readyServices, state_resets: stateResets }, transport), retry);
+            });
+            if (undelivered !== null)
+                throw new CliError(undelivered, `${label} did not report readiness to the service, so no step was taken.`);
+            output('native_drill_admitting', { assignment_id: assignment.assignment_id, state: rootState }, `Ready locally; waiting for the service to admit ${label}.`);
+            for (;;) {
+                const seen = progress.generation;
+                if (ADMITTED_STATES.has(rootState))
+                    break;
+                const halt = leaseStop ?? dependencyStop ?? preStepHalt(assignment, deps, startedAt, steps) ?? admissionHalt(rootState);
+                if (halt) {
+                    stopWith(halt.outcome, halt.reason);
+                    throw new CliError(halt.reason ?? DRILL_REASONS.draining, `${label} stopped before the service admitted it. No step was taken.`);
+                }
+                await progress.wait(seen, AbortSignal.any([deps.stopSignal, transport, channel ? haltDue() : AbortSignal.timeout(PREPARE_CHECK_MS)]));
+            }
+        }
+        const openSession = async (key) => {
+            const existing = sessions.get(key);
+            if (existing)
+                return existing;
+            if (sessions.size >= MAX_DRIVER_SESSIONS)
+                throw new CliError(DRILL_REASONS.step_invalid, 'The step was not sent: the drill opened too many target sessions.');
+            const opened = await driver.openSession(ctx, key);
+            sessions.set(key, opened);
+            activeTracker.markFreshSession();
+            return opened;
+        };
+        // Step loop.
+        let idle = 0;
+        while (!stop) {
+            const halt = leaseStop ?? dependencyStop ?? preStepHalt(assignment, deps, startedAt, steps) ?? executionHalt(rootState);
+            if (halt) {
+                stopWith(halt.outcome, halt.reason);
+                break;
+            }
+            const wake = AbortSignal.any([deps.stopSignal, transport, AbortSignal.timeout(Math.max(1, leaseRemainingMs(assignment) - LEASE_MARGIN_MS))]);
+            if (!await deps.gate.wait(wake))
+                continue;
+            // Nothing is read or stepped while the campaign channel waits for a valid resync.
+            if (channel && !await channel.live(wake))
+                continue;
+            if (buffer)
+                await buffer.room(wake);
+            if (pendingReport) {
+                try {
+                    await reportStep(controlPlane, assignment, pendingReport, retry);
+                    pendingReport = null;
+                    claimOpen = false;
+                }
+                catch (error) {
+                    if (isTransient(error)) {
+                        deps.gate.disconnected();
+                        continue;
+                    }
+                    const halted = classify(error);
+                    stopWith(halted.outcome === 'failed' ? 'incomplete' : halted.outcome, halted.reason ?? DRILL_REASONS.step_report_failed);
+                    break;
+                }
+            }
+            // Read before the canonical read of root's actions, so a wake-up that lands during it is not lost.
+            const seen = progress.generation;
+            let batch;
+            try {
+                batch = await retryTransient(() => controlPlane.nextSteps(assignment, cursor, transport), retry);
+            }
+            catch (error) {
+                if (isTransient(error)) {
+                    deps.gate.disconnected();
+                    continue;
+                }
+                throw error;
+            }
+            if (batch.cancelled) {
+                stopWith('cancelled', null);
+                break;
+            }
+            // Root's latest coverage (sent only while nothing is in flight, so a page with steps clears it): a v3 scenario
+            // may be waiting on a timed event, and a drill that stops before its input ends still says what was never applied.
+            schedule = batch.schedule ?? null;
+            // Steps this attempt already claimed (including `unknown` ones) are never re-invoked.
+            if (batch.reconciliation_required === 'participant_outcome_unknown') {
+                // Do not replay an unconfirmed claim or infer that cloud inference did
+                // not run. Cleanup is local; cloud close/accounting may remain pending.
+                stopWith('incomplete', 'native_participant_outcome_unknown');
+                break;
+            }
+            const ordered = (Array.isArray(batch.steps) ? batch.steps : [])
+                .filter((step) => !(typeof step?.step_id === 'string' && handled.has(step.step_id)))
+                .sort((a, b) => a.sequence - b.sequence);
+            // A claim whose answer was lost: if it landed, root lists nothing offered (the action is claimed) and the
+            // input cannot end, so the same claim is replayed (root answers `recovered`). If root offers another action
+            // or says the input ended, that claim never landed and is dropped.
+            if (unconfirmed && !ordered.some((step) => step.step_id === unconfirmed?.step_id)) {
+                if (ordered.length === 0 && !batch.done)
+                    ordered.push(unconfirmed);
+                else
+                    unconfirmed = null;
+            }
+            if (ordered.length === 0) {
+                // Root says the drill's input ended. The drill ran to the end of its input; that is not a pass,
+                // and root's frozen completion evidence, not this client, decides coverage. Root refuses a
+                // completed close over a retained target failure or cancellation, so those close as the target ended.
+                if (batch.done) {
+                    endingReason = batch.ending_reason;
+                    schedule = batch.schedule ?? null;
+                    if (endingReason === 'target_failed')
+                        stopWith('failed', DRILL_REASONS.target_failed);
+                    else if (endingReason === 'target_cancelled')
+                        stopWith('cancelled', DRILL_REASONS.target_cancelled);
+                    // Root's own infrastructure ending (root refuses it as completed): cleaned up and closed incomplete.
+                    else if (endingReason === 'participant_unavailable')
+                        stopWith('incomplete', DRILL_REASONS.participant_unavailable);
+                    else
+                        stopWith('completed', null);
+                    break;
+                }
+                // Nothing offered yet: root's next change for this assignment (an action, a timed event, a cancellation)
+                // or a resync wakes the drill; it does not poll.
+                if (channel)
+                    await progress.wait(seen, AbortSignal.any([deps.stopSignal, transport, haltDue()]));
+                else
+                    await sleep(Math.min(250 * 2 ** Math.min(idle++, 3), 2_000), AbortSignal.any([deps.stopSignal, transport]));
+                continue;
+            }
+            idle = 0;
+            for (const step of ordered) {
+                if (handled.has(step?.step_id))
+                    continue;
+                const stepHalt = leaseStop ?? dependencyStop ?? preStepHalt(assignment, deps, startedAt, steps) ?? executionHalt(rootState);
+                if (stepHalt) {
+                    stopWith(stepHalt.outcome, stepHalt.reason);
+                    break;
+                }
+                if (!deps.gate.connected || (channel && channel.state !== 'live'))
+                    break; // paused: re-enter the outer loop and wait
+                const problem = stepProblem(step);
+                if (problem) {
+                    // Never invoke a malformed step or a non-idempotent step without a persisted intent.
+                    await reportStep(controlPlane, assignment, failedResult(step, problem), retry).catch(() => undefined);
+                    stopWith('failed', problem);
+                    break;
+                }
+                if (stepTimeout(step, assignment, startedAt) <= 0) {
+                    stopWith('incomplete', NATIVE_ERRORS.budget_exhausted);
+                    break;
+                }
+                // Open (or reuse) the target session first: a driver failure here records no start.
+                const session = await openSession(step.payload.kind === 'event' ? EVENT_SESSION_KEY : step.payload.session_key);
+                // Session setup can span a channel loss. Do not claim new work until a
+                // current resync, and leave this still-unclaimed step to the outer loop.
+                if (!deps.gate.connected || (channel && channel.state !== 'live'))
+                    break;
+                const setupHalt = leaseStop ?? dependencyStop ?? preStepHalt(assignment, deps, startedAt, steps) ?? executionHalt(rootState);
+                if (setupHalt) {
+                    stopWith(setupHalt.outcome, setupHalt.reason);
+                    break;
+                }
+                let claimed;
+                try {
+                    // The same claim is replayed on a transient failure (one request key per step).
+                    claimed = await retryTransient(() => controlPlane.stepStarted(assignment, step, transport), retry);
+                }
+                catch (error) {
+                    // No invocation without a recorded start. A transient failure pauses; the same
+                    // claim is re-sent with its key, whether root still offers the step or hides it as claimed.
+                    if (isTransient(error)) {
+                        unconfirmed = step;
+                        deps.gate.disconnected();
+                        break;
+                    }
+                    const halted = classify(error);
+                    stopWith(halted.outcome, halted.reason);
+                    break;
+                }
+                unconfirmed = null;
+                handled.add(step.step_id);
+                claimOpen = true;
+                if (claimed?.recovered === true) {
+                    // Root kept an earlier claim of this step (its first answer was lost), so the
+                    // step may have reached the target. It is never invoked again.
+                    cursor = Math.max(cursor, step.sequence);
+                    unknownSteps++;
+                    observe({ kind: 'action.observed', at_ms: Date.now(), content: { type: 'target.claim_recovered', step_id: step.step_id, outcome: 'unknown' } });
+                    stopWith('incomplete', NATIVE_ERRORS.unknown_outcome);
+                    break;
+                }
+                // Invoke exactly the dispatch root froze for this claim, when it returned one.
+                const dispatched = claimed?.payload ? { ...step, payload: claimed.payload } : step;
+                if (dispatched.payload.kind !== step.kind) {
+                    stopWith('failed', DRILL_REASONS.step_invalid);
+                    break;
+                }
+                // Session setup and claim recovery consume elapsed budget too. A renewing
+                // lease is not a fixed turn deadline; lease loss aborts drillController.
+                const halts = () => leaseStop ?? dependencyStop ?? preStepHalt(assignment, deps, startedAt, steps) ?? executionHalt(rootState);
+                const confirmed = () => deps.gate.connected && (!channel || channel.state === 'live');
+                let timeoutMs = stepTimeout(dispatched, assignment, startedAt);
+                let dispatchHalt = halts();
+                if (!dispatchHalt && timeoutMs > 0 && !confirmed()) {
+                    // The channel rotates about once a minute and is briefly not live while it reconnects; a claim answered in
+                    // that window waits for the next valid resync (or a transport reconnect), bounded by the next lease or
+                    // budget halt, instead of being withdrawn. Nothing is invoked until the connection is confirmed again.
+                    while (!confirmed()) {
+                        dispatchHalt = halts();
+                        timeoutMs = stepTimeout(dispatched, assignment, startedAt);
+                        if (dispatchHalt || timeoutMs <= 0 || deps.stopSignal.aborted || transport.aborted
+                            || drillController.signal.aborted || channel?.state === 'closed')
+                            break;
+                        // This timer snapshots the current lease. A renewal can move its
+                        // deadline while resync is pending, so expiry only wakes this loop.
+                        // Keep the same acknowledged claim and re-check live authority;
+                        // never withdraw or invoke solely because an old timer elapsed.
+                        const waitFor = AbortSignal.any([deps.stopSignal, transport, drillController.signal, haltDue()]);
+                        if (await deps.gate.wait(waitFor) && channel)
+                            await channel.live(waitFor);
+                    }
+                    timeoutMs = stepTimeout(dispatched, assignment, startedAt);
+                    dispatchHalt = halts();
+                }
+                if (dispatchHalt || timeoutMs <= 0 || !confirmed()) {
+                    const reason = dispatchHalt?.reason ?? (timeoutMs <= 0 ? NATIVE_ERRORS.budget_exhausted : 'native_stream_disconnected');
+                    // Only this freshly acknowledged, never-invoked claim can be withdrawn.
+                    // Recovered/uncertain claims took the earlier unknown-outcome path.
+                    if (controlPlane.abandonStep)
+                        await withdrawClaim(step, reason);
+                    stopWith(dispatchHalt?.outcome ?? 'incomplete', reason);
+                    break;
+                }
+                const { result, evidenceLost } = await invokeStep(session, { ...dispatched, deadline_ms: timeoutMs }, timeoutMs, drillController.signal);
+                // The driver itself returned and says nothing was written: the client refused the input or could not
+                // deliver it. A step the runner had to interrupt, or any unknown outcome, never counts as undelivered.
+                const neverDelivered = !evidenceLost && result.delivered !== true && (result.outcome === 'failed' || result.outcome === 'cancelled');
+                steps++;
+                cursor = Math.max(cursor, step.sequence);
+                if (result.outcome === 'unknown')
+                    unknownSteps++;
+                if (result.outcome === 'completed')
+                    completedSteps++;
+                for (const observation of result.observations ?? [])
+                    observe(observation);
+                if (evidenceLost)
+                    buffer?.noteLostStepEvidence();
+                // The evidence root completes the action with: the target's reply to a message, as cloud
+                // participants read it (v2: names the claimed action, which is this step), or the retained
+                // result of a task or event. An unknown outcome has neither and never completes the action.
+                let evidenceId = null;
+                if (buffer && step.kind === 'message') {
+                    const reply = result.outcome === 'completed' ? replyText(result.output) : null;
+                    evidenceId = reply ? buffer.add({ kind: 'conversation.observed', at_ms: result.finished_ms, content: {},
+                        target_message: { schema: 'firedrill.native-target-message.v2', action_id: step.step_id, role: 'assistant', content: reply } }) : null;
+                    if (!reply && result.outcome === 'failed' && result.delivered === true && claimed?.claim_key
+                        && typeof step.input_digest === 'string' && (step.action_kind === 'participant_message' || step.action_kind === 'scenario_message')) {
+                        evidenceId = buffer.add({ kind: 'action.observed', at_ms: result.finished_ms, content: {},
+                            target_result: { schema: 'firedrill.native-target-result.v1', action_id: step.step_id,
+                                input_digest: step.input_digest, kind: step.action_kind, claim_key: claimed.claim_key,
+                                outcome: 'failed', output: { error_code: 'native_target_error' }, output_coverage: 'complete',
+                                completion: { kind: 'target_returned', delivery_id: null } } });
+                    }
+                }
+                else if (buffer && result.outcome !== 'unknown' && (result.outcome === 'completed' || result.delivered === true)
+                    && typeof step.input_digest === 'string') {
+                    // Only an input that reached the target has a target result. A step the client refused or could not
+                    // deliver is never recorded as the target's own failure: root would end the input as target_failed.
+                    evidenceId = buffer.add({ kind: 'action.observed', at_ms: result.finished_ms, content: {},
+                        target_result: targetResult(step, result.outcome, result.output, result.output_coverage) });
+                }
+                // Root completes a target action only with an acknowledged evidence event.
+                const evidenceAcknowledged = evidenceId && buffer ? await buffer.delivered(evidenceId, AbortSignal.any([transport, AbortSignal.timeout(Math.max(1, leaseRemainingMs(assignment) - LEASE_MARGIN_MS))])) : false;
+                result.reply_event_id = evidenceAcknowledged ? evidenceId : null;
+                output('native_step', { assignment_id: assignment.assignment_id, step_id: step.step_id, sequence: step.sequence,
+                    outcome: result.outcome, error_code: result.error_code, duration_ms: Math.max(0, result.finished_ms - result.started_ms),
+                    reply_event_id: result.reply_event_id }, `${label}: step ${step.sequence} ${result.outcome}${result.error_code ? ` (${result.error_code})` : ''}.`);
+                if (!result.reply_event_id) {
+                    // Without acknowledged evidence root cannot complete the action, and offers
+                    // no next input while it is claimed: the drill ends here.
+                    // Evidence was lost only for a completed step or a task or event that reached the target; any other
+                    // step ended on its own error (refused, not delivered, or a failed message), which is the reason.
+                    const undelivered = step.kind === 'message' ? DRILL_REASONS.reply_undelivered : DRILL_REASONS.result_undelivered;
+                    const evidenceLost = result.outcome === 'completed' || (step.kind !== 'message' && result.delivered === true);
+                    if (neverDelivered && controlPlane.abandonStep)
+                        await withdrawClaim(step, result.error_code);
+                    stopWith('incomplete', result.outcome === 'unknown' ? NATIVE_ERRORS.unknown_outcome
+                        : evidenceLost ? undelivered : result.error_code ?? undelivered);
+                    break;
+                }
+                try {
+                    await reportStep(controlPlane, assignment, result, retry);
+                    claimOpen = false;
+                    if (step.kind === 'message' && result.outcome === 'failed') {
+                        stopWith('failed', result.error_code ?? 'native_target_error');
+                        break;
+                    }
+                }
+                catch (error) {
+                    if (isTransient(error)) {
+                        pendingReport = result;
+                        deps.gate.disconnected();
+                        break;
+                    }
+                    const halted = classify(error);
+                    stopWith(halted.outcome === 'failed' ? 'incomplete' : halted.outcome, halted.reason ?? DRILL_REASONS.step_report_failed);
+                    break;
+                }
+            }
+        }
+    }
+    catch (error) {
+        const halted = classify(error);
+        stopWith(halted.outcome, halted.reason);
+    }
+    finally {
+        deps.abortSignal.removeEventListener('abort', onStop);
+        // Teardown needs no wake-ups: the signed stop, close and cleanup carry their own receipts.
+        unwatchChannel();
+        assignmentWake?.close();
+    }
+    // Teardown: sessions, driver, owned services, observations, scratch, then the signed close.
+    const final = leaseStop ?? stop ?? { outcome: 'failed', reason: DRILL_REASONS.drill_failed };
+    const driverOutcome = final.outcome === 'completed' ? 'completed'
+        : final.outcome === 'cancelled' ? 'cancelled' : 'failed';
+    // Root stops dispatching first (withdrawing only offers never claimed) while local
+    // work stops; its receipt names the cutoff the close must carry. Root refuses a stop
+    // before it prepared the drill, and a revoked device cannot sign one.
+    const stopping = prepared && !deps.isRevoked()
+        ? retryTransient(() => controlPlane.stopExecution(assignment, transport), retry)
+            .then((receipt) => ({ receipt, error: null }), (error) => ({ receipt: null, error }))
+        : null;
+    drillController.abort();
+    let driverCleanupUnknown = false;
+    for (const session of sessions.values())
+        await session.close().catch(() => { driverCleanupUnknown = true; });
+    if (driver)
+        await driver.dispose().catch(() => { driverCleanupUnknown = true; });
+    // Driver-owned helper processes need not be descriptor services. They still
+    // must end before claiming that the target is closed.
+    if (driver?.ownedProcesses?.().some(process => process.exit === null))
+        driverCleanupUnknown = true;
+    await deps.services.stopDrill(drillKey, final.reason ?? final.outcome);
+    // The target is stopped, so nothing may reach root's gateway for this drill any more;
+    // the proxy's tokens are dropped with it, before the close is recorded.
+    if (proxy)
+        await proxy.close().catch(() => undefined);
+    proxy = null;
+    // After every owned process was stopped: how each declared service ended, or why that cannot be attested.
+    // A shared run service that ended during the drill is reported to root first, so the close names what root retains.
+    if (prepared && deps.localRun && !deps.isRevoked()) {
+        const localRun = deps.localRun;
+        await retryTransient(() => localRun.sync(transport), retry).catch(() => undefined);
+    }
+    const ends = serviceEnds(plan, descriptor, drillServices, deps.services.takeLaunches(drillKey), driver, driverOutcome, deps.localRun ?? null);
+    if (driverCleanupUnknown) {
+        const entry = ends.findIndex(end => ('known' in end ? end.known.service : end.unknown.service) === descriptor.entry_service);
+        const previous = entry >= 0 ? ends[entry] : null;
+        const process = previous && ('known' in previous ? previous.known : previous.unknown);
+        const unknown = { problem: 'native_driver_cleanup_unconfirmed', unknown: {
+                service: descriptor.entry_service, launch_id: process && 'launch_id' in process ? process.launch_id : null,
+                ownership: 'unknown', close_kind: 'unknown',
+            } };
+        if (entry >= 0)
+            ends[entry] = unknown;
+        else
+            ends.push(unknown);
+    }
+    const closed = processCloses(ends);
+    let evidence = buffer ? await buffer.close() : null;
+    for (const config of mcpConfigs)
+        await config.cleanup().catch(() => undefined);
+    mcpConfigs = [];
+    if (scratch)
+        await scratch.cleanup();
+    const stateCoverage = tracker ? tracker.coverage() : descriptor.state_domains.map((domain) => ({
+        alias: domain.alias, reset: domain.reset, result: 'unavailable',
+    }));
+    let closeId = null;
+    let completionError = null;
+    let reported = false;
+    let withdrawn = false;
+    let withdrawCode = null;
+    let stepReportLost = false;
+    const stopped = stopping ? await stopping : null;
+    if (deps.isRevoked()) {
+        completionError = NATIVE_ERRORS.revoked;
+    }
+    else {
+        if (pendingReport) {
+            // Last attempt to record an invoked step's result; the step itself is never re-invoked.
+            try {
+                await reportStep(controlPlane, assignment, pendingReport, retry);
+                pendingReport = null;
+                claimOpen = false;
+            }
+            catch {
+                stepReportLost = true;
+            }
+        }
+        if (!prepared) {
+            // Before root prepared the drill it accepts no evidence, and nothing ran locally to close.
+            completionError = final.reason ?? DRILL_REASONS.not_prepared;
+            // Withdraw it with a signed cancel while root still holds it accepted or provisioning, so it keeps no
+            // capacity and the campaign's local run can close; how its services ended goes on the cleanup-only path.
+            if (PREPARING_STATES.has(rootState)) {
+                try {
+                    await retryTransient(() => controlPlane.cancelExecution(assignment, transport), retry);
+                    withdrawn = true;
+                    output('native_drill_withdrawn', { assignment_id: assignment.assignment_id, attempt_id: assignment.attempt_id }, `${label} was withdrawn before the service prepared it. Nothing started locally.`);
+                }
+                catch (error) {
+                    withdrawCode = errorCode(error);
+                    output('native_drill_withdraw_failed', { assignment_id: assignment.assignment_id, error_code: errorCode(error) }, `${label} could not be withdrawn; the service releases it when its lease ends.`);
+                }
+            }
+        }
+        else if (closed.problem !== null) {
+            // Never attest a process ending that did not happen; root keeps the drill until it is reconciled.
+            completionError = closed.problem;
+        }
+        else if (pendingReport) {
+            // Root refuses a close while a claimed action is unfinished; the drill is left to root's reconciliation.
+            completionError = DRILL_REASONS.step_report_failed;
+        }
+        else if (!stopped?.receipt) {
+            // Without root's stop receipt there is no exact cutoff to close on; none is guessed.
+            completionError = errorCode(stopped?.error) ?? DRILL_REASONS.stop_unconfirmed;
+        }
+        else if (!buffer || !evidence || evidence.unacknowledged > 0 || evidence.failure_code !== null) {
+            // The final outcome event must directly follow everything root acknowledged.
+            completionError = evidence?.failure_code ?? 'native_observation_delivery_failed';
+        }
+        else {
+            // Root's order: commit the signed close as the driver.<outcome> record, send the final
+            // outcome observation referencing it as the next sequence, and once root acknowledged
+            // that event, submit the close. Nothing is observed after it.
+            const close = {
+                observation_sequence: evidence.last_sequence + 1,
+                last_action_id: stopped.receipt.last_action_id,
+                driver_outcome: driverOutcome,
+                processes: closed.processes,
+            };
+            const reason = stopReason(final, steps, assignment, endingReason);
+            if (reason)
+                close.client_summary = { stop_reason: reason, steps_started: steps, steps_completed: completedSteps,
+                    ...(descriptor.dependencies.some(dependency => dependency.mode === 'synthetic')
+                        ? { dependency_capture_complete: evidence.evidence_complete,
+                            dependency_capture_records_complete: evidence.dependency_capture_records_complete } : {}) };
+            let closeStage = 'prepare_record';
+            try {
+                // Retry only the cached signed close and its original upload keys.
+                // Five fast attempts can end before an authority refresh finishes.
+                // This finite window never repeats a target or the outcome observation.
+                // The control plane caps each renewed lease at the original deadline.
+                const preparationDeadline = Date.now() + CLOSE_PENDING_WAIT_MS;
+                let record;
+                for (let attempt = 0;; attempt++) {
+                    const remaining = Math.min(preparationDeadline - Date.now(), leaseRemainingMs(assignment) - LEASE_MARGIN_MS * 2);
+                    if (deps.isRevoked())
+                        throw new CliError(NATIVE_ERRORS.revoked, 'The executor authority has ended.');
+                    if (leaseStop || leaseRemainingMs(assignment) <= LEASE_MARGIN_MS * 2) {
+                        throw new CliError(leaseStop?.reason ?? NATIVE_ERRORS.lease_expired, 'The original execution lease has ended.');
+                    }
+                    if (transport.aborted || remaining <= 0) {
+                        throw new CliError('native_execution_close_pending', 'The original close remains unconfirmed. Do not run the target again.');
+                    }
+                    const closeSignal = AbortSignal.any([transport, AbortSignal.timeout(remaining)]);
+                    try {
+                        record = await controlPlane.recordClose(assignment, close, closeSignal);
+                        break;
+                    }
+                    catch (error) {
+                        if (!isTransient(error) || transport.aborted || deps.isRevoked() || leaseStop
+                            || Date.now() >= preparationDeadline || leaseRemainingMs(assignment) <= LEASE_MARGIN_MS * 2)
+                            throw error;
+                        deps.gate.disconnected();
+                        const delay = Math.min(backoffMs(attempt, 1_000, 10_000), preparationDeadline - Date.now(), leaseRemainingMs(assignment) - LEASE_MARGIN_MS * 2);
+                        if (delay <= 0 || !await sleep(delay, transport))
+                            throw error;
+                    }
+                }
+                closeStage = 'outcome_observation';
+                const undelivered = await buffer.submitOutcome(record.kind, record);
+                evidence = buffer.summary();
+                if (undelivered !== null)
+                    throw new CliError(undelivered, 'The final outcome observation was not acknowledged, so the drill was not closed.');
+                // Root returns the original close for a repeated submit, so waiting out its pending participant work is safe.
+                // A target action this client left claimed (or whose claim got no answer) never finishes by waiting, so
+                // then root's refusal stands at once.
+                const waitable = !claimOpen && unconfirmed === null && final.reason !== 'native_participant_outcome_unknown';
+                const closeDeadline = Date.now() + CLOSE_PENDING_WAIT_MS;
+                closeStage = 'submit_close';
+                let receipt;
+                for (let attempt = 0;; attempt++) {
+                    const remainingClose = closeDeadline - Date.now();
+                    if (remainingClose <= 0)
+                        throw new CliError('native_execution_close_pending', 'The original close remains unconfirmed. Its evidence is retained; do not run the target again.');
+                    const closeSignal = AbortSignal.any([transport, AbortSignal.timeout(remainingClose)]);
+                    try {
+                        receipt = await controlPlane.submitClose(assignment, record, closeSignal);
+                        break;
+                    }
+                    catch (error) {
+                        const pending = ['native_execution_close_pending', 'native_execution_ending_pending'].includes(errorCode(error) ?? '');
+                        // Same retained artifact only. A lost submit reply is recoverable;
+                        // no claim, target invocation, outcome or observation is repeated.
+                        if ((!isTransient(error) && !(pending && waitable)) || transport.aborted || leaseStop
+                            || Date.now() >= closeDeadline || leaseRemainingMs(assignment) <= LEASE_MARGIN_MS * 2)
+                            throw error;
+                        if (isTransient(error))
+                            deps.gate.disconnected();
+                        if (!await sleep(Math.min(backoffMs(attempt, 1_000, 10_000), closeDeadline - Date.now()), transport))
+                            throw error;
+                    }
+                }
+                closeId = receipt.close_id;
+                reported = true;
+            }
+            catch (error) {
+                completionError = errorCode(error) ?? DRILL_REASONS.drill_failed;
+                output('native_close_stage_unconfirmed', { assignment_id: assignment.assignment_id,
+                    stage: closeStage, error_code: completionError }, `${label}: the original close remains unconfirmed at ${closeStage}. Do not repeat the target.`);
+            }
+        }
+    }
+    // Root fenced this execution (its lease expired or it was revoked), so no close is possible:
+    // how each service ended goes on root's cleanup-only path instead. It completes nothing.
+    let cleanupOutcome = null;
+    const fenceCodes = new Set([NATIVE_ERRORS.lease_expired, NATIVE_ERRORS.stale_generation]);
+    // Before root prepared the drill it may also have fenced it (lease lost, so the withdrawal was refused) or revoked
+    // it (capacity refused): root seals it only with this device's cleanup report, even though nothing started.
+    const fenced = [final.reason, completionError, errorCode(stopped?.error), withdrawCode].some((code) => fenceCodes.has(code));
+    const endedUnprepared = !prepared && (rootState === 'draining' || rootState === 'paused' || final.reason === DRILL_REASONS.draining);
+    if (!reported && !deps.isRevoked() && (withdrawn || fenced || endedUnprepared)) {
+        try {
+            const receipt = await reportCleanup(controlPlane, assignment, ends, retry);
+            if (receipt) {
+                cleanupOutcome = receipt.outcome;
+                output('native_cleanup_reported', { assignment_id: assignment.assignment_id, cleanup_id: receipt.cleanup_id, outcome: receipt.outcome,
+                    unresolved_actions: receipt.unresolved_actions, unresolved_participants: receipt.unresolved_participants }, `${label}: ${withdrawn ? 'the drill was withdrawn' : 'the service fenced this drill'}, so how its services ended was reported for cleanup only`
+                    + `${receipt.outcome === 'unknown' ? ' (some ends could not be attested and stay unknown)' : ''}. Cleanup itself is the service's.`);
+            }
+        }
+        catch (error) {
+            output('native_cleanup_unreported', { assignment_id: assignment.assignment_id, error_code: errorCode(error) }, `${label}: the service fenced this drill and the cleanup report was not confirmed.`);
+        }
+    }
+    const completion = {
+        outcome: final.outcome,
+        reason_code: final.reason ?? (final.outcome === 'completed' && unknownSteps > 0 ? NATIVE_ERRORS.unknown_outcome : null),
+        state_coverage: stateCoverage,
+        last_sequence: evidence?.last_sequence ?? assignment.observation_ack,
+        evidence_complete: (evidence?.evidence_complete ?? false) && !stepReportLost,
+    };
+    // End the lease keeper only after an accepted close/cleanup, or after the
+    // bounded reconciliation attempt explicitly leaves the original uncertain.
+    // Never describe deadline/shutdown/authority refusal as successful closure.
+    if (!reported && cleanupOutcome === null && prepared) {
+        output('native_close_unconfirmed', { assignment_id: assignment.assignment_id,
+            attempt_id: assignment.attempt_id, error_code: completionError }, `${label}: original closing evidence remains unconfirmed. Do not repeat the target; cloud cleanup and accounting are still pending.`);
+    }
+    leaseControl.abort();
+    await leaseKeeper;
+    const report = {
+        assignment_id: assignment.assignment_id, attempt_id: assignment.attempt_id,
+        outcome: completion.outcome, reason_code: completion.reason_code, ending_reason: endingReason, schedule, steps, unknown_steps: unknownSteps,
+        evidence, state_coverage: stateCoverage, completion: reported ? 'reported' : 'not-reported',
+        completion_error: completionError, close_id: closeId, cleanup_outcome: cleanupOutcome,
+    };
+    const evidenceText = evidence?.evidence_complete ? 'evidence complete' : 'evidence incomplete';
+    output('native_drill_finished', report, `Finished ${label}: ${completion.outcome}${completion.reason_code ? ` (${completion.reason_code})` : ''}`
+        + `${endingReason ? `; input ended because ${ENDING_TEXT[endingReason]} (not a result)` : ''}${coverageText(endingReason, schedule, prepared)}, ${steps} step(s), `
+        + `${unknownSteps} unknown, ${evidenceText}${reported ? '; closed with the service' : `; not closed with the service (${completionError})`}.`);
+    return report;
+}
+// ---------------------------------------------------------------------------
+// Helpers.
+const LEASE_RENEW_MS = 20_000;
+/** Renewals prompted by the channel are at least this far apart. */
+const WAKE_RENEW_SPACING_MS = 1_000;
+/**
+ * Renew the assignment lease (signed control `heartbeat`) until `signal`
+ * aborts, updating `assignment.lease_expires_at` in place so every lease check
+ * sees the renewed expiry. A fence or revocation stops renewal and reports why
+ * the drill must stop; a pending contract stops renewal quietly (the lease then
+ * simply runs out); transient failures are retried on the next tick. Never throws.
+ *
+ * The renewal also reports root's execution state. While the drill is being
+ * prepared or admitted, a channel wake-up for this assignment prompts a renewal
+ * at once (root's heartbeat control raises no wake-up itself); otherwise renewal
+ * keeps its lease interval. Without a channel it backs off from 2 s to 15 s then.
+ */
+async function keepLease(assignment, controlPlane, signal, onLost, onState, preparing, wake) {
+    let preparingRenewals = 0;
+    let seen = wake?.generation ?? 0;
+    let renewedAt = 0;
+    while (!signal.aborted) {
+        const remaining = leaseRemainingMs(assignment);
+        const prompted = wake !== null && !wake.closed && preparing() ? wake : null;
+        const interval = preparing() && !prompted
+            ? Math.min(PREPARE_RENEW_MAX_MS, PREPARE_RENEW_MIN_MS * 2 ** Math.min(preparingRenewals++, 3))
+            : LEASE_RENEW_MS;
+        const due = Math.max(1_000, Math.min(interval, Math.floor(remaining / 3)));
+        if (prompted) {
+            await prompted.wait(seen, AbortSignal.any([signal, AbortSignal.timeout(due)]));
+            const spacing = WAKE_RENEW_SPACING_MS - (Date.now() - renewedAt);
+            if (spacing > 0 && !await sleep(spacing, signal))
+                return;
+            if (signal.aborted)
+                return;
+        }
+        else if (!await sleep(due, signal))
+            return;
+        // Read before the renewal, so a wake-up that lands during it prompts the next one.
+        seen = wake?.generation ?? 0;
+        renewedAt = Date.now();
+        try {
+            const renewed = await controlPlane.renewLease(assignment, signal);
+            const expires = Date.parse(renewed?.lease_expires_at);
+            if (Number.isFinite(expires) && expires > Date.parse(assignment.lease_expires_at))
+                assignment.lease_expires_at = renewed.lease_expires_at;
+            if (typeof renewed?.state === 'string')
+                onState(renewed.state);
+        }
+        catch (error) {
+            if (signal.aborted)
+                return;
+            if (isTransient(error))
+                continue;
+            // The cloud ended this assignment (completed, cancelled or failed there): stop, without blaming the target.
+            if (errorCode(error) === 'native_assignment_terminal') {
+                onLost({ outcome: 'incomplete', reason: 'native_assignment_terminal' });
+                return;
+            }
+            onLost(classify(error));
+            return;
+        }
+    }
+}
+/** The target's reply as message text, or null when there is none. */
+function replyText(output) {
+    if (typeof output === 'string')
+        return output.trim() ? output : null;
+    if (output === null || output === undefined)
+        return null;
+    try {
+        const text = JSON.stringify(output);
+        return typeof text === 'string' && text.length > 0 ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * How every declared service ended for this drill, or why it cannot be stated
+ * truthfully: a process still running after stop, a shared launched service
+ * outside a local run (neither reaped nor attached), a run service root keeps
+ * uncertain, or, for a drill that completed, a service it never reached. A
+ * failed or cancelled drill reports a service it never launched or attached as
+ * not started. `launches` holds every per-drill process the supervisor launched
+ * for this drill, including one stopped because it never became ready.
+ */
+function serviceEnds(plan, descriptor, handles, launches, driver, outcome, localRun) {
+    const driverOwned = new Map((driver?.ownedProcesses?.() ?? []).map((item) => [item.alias, item]));
+    const driverAlias = plan.driver.profile === 'jsonl-process.v1' ? plan.driver.service_alias : null;
+    const planned = new Map(plan.services.map((service) => [service.alias, service]));
+    const launched = new Map();
+    for (const handle of launches)
+        launched.set(handle.alias, [...(launched.get(handle.alias) ?? []), handle]);
+    const ends = [];
+    for (const { alias } of descriptor.services) {
+        const owned = driverOwned.get(alias);
+        const runs = launched.get(alias) ?? [];
+        const handle = handles.get(alias);
+        const service = planned.get(alias);
+        // A run-owned service: reported by what root retains for the campaign's local run, never as drill-owned.
+        const runEntry = localRun?.closeEntry(alias, outcome) ?? null;
+        if (typeof runEntry === 'string') {
+            ends.push({ problem: runEntry, unknown: { service: alias, launch_id: localRun?.launchId(alias) ?? null, ownership: 'owned_run', close_kind: 'unknown' } });
+            continue;
+        }
+        if (runEntry) {
+            ends.push({ known: runEntry });
+            continue;
+        }
+        if (owned) {
+            const code = exitCode(owned.exit);
+            ends.push(code === null
+                ? { problem: 'native_close_process_running', unknown: { service: alias, launch_id: owned.launch_id, ownership: 'owned', close_kind: 'unknown' } }
+                : { known: { service: alias, launch_id: owned.launch_id, ownership: 'owned', close_kind: 'owned_group_reaped', exit_code: code } });
+        }
+        else if (runs.length) {
+            // A per-drill service relaunched within the drill reports its latest launch; every launch must have ended.
+            const codes = runs.map((run) => exitCode(run.exit()));
+            const last = codes[codes.length - 1];
+            const launchId = runs[runs.length - 1].launchId;
+            ends.push(codes.some((code) => code === null) || last === null
+                ? { problem: 'native_close_process_running', unknown: { service: alias, launch_id: launchId, ownership: 'owned', close_kind: 'unknown' } }
+                : { known: { service: alias, launch_id: launchId, ownership: 'owned', close_kind: 'owned_group_reaped', exit_code: last } });
+        }
+        else if (handle?.mode === 'attach') {
+            ends.push({ known: { service: alias, launch_id: handle.launchId, ownership: 'attached', close_kind: 'transport_detached' } });
+        }
+        else if (alias !== driverAlias && (handle?.mode === 'launch' || (service?.mode === 'launch' && !service.per_drill))) {
+            ends.push({ problem: 'native_close_shared_service', unknown: { service: alias, launch_id: handle?.launchId ?? null, ownership: 'unknown', close_kind: 'unknown' } });
+        }
+        else if (outcome !== 'completed') {
+            ends.push({ known: { service: alias, ownership: 'none', close_kind: 'not_started' } });
+        }
+        else {
+            ends.push({ problem: 'native_close_service_not_launched', unknown: { service: alias, launch_id: null, ownership: 'unknown', close_kind: 'unknown' } });
+        }
+    }
+    return ends;
+}
+/** The signed close's processes, or the first reason they cannot be stated truthfully. */
+function processCloses(ends) {
+    const processes = [];
+    for (const end of ends) {
+        if ('problem' in end)
+            return { processes: null, problem: end.problem };
+        processes.push(end.known);
+    }
+    return { processes, problem: null };
+}
+/** How long teardown waits for root to freeze a fenced execution (root expires a lease on its own schedule). */
+const CLEANUP_WAIT_MS = 90_000;
+/**
+ * Root fenced this execution, so it accepts no close: report how each service
+ * ended on root's cleanup-only path, scoped exactly to the execution root froze.
+ * An end that cannot be attested is reported `unknown`, never as stopped. Waits
+ * (bounded) for root to freeze the execution; null when root holds none for it.
+ */
+async function reportCleanup(controlPlane, assignment, ends, retry) {
+    const until = AbortSignal.any([retry.signal, AbortSignal.timeout(CLEANUP_WAIT_MS)]);
+    for (let attempt = 0;; attempt++) {
+        const challenge = await retryTransient(() => controlPlane.readCleanup(assignment, until), { ...retry, signal: until });
+        if (challenge) {
+            const processes = ends.map((end) => 'known' in end ? end.known : end.unknown);
+            return await retryTransient(() => controlPlane.submitCleanup(assignment, challenge, processes, retry.signal), retry);
+        }
+        if (!await sleep(backoffMs(attempt, 2_000, 10_000), until))
+            return null;
+    }
+}
+/** While waiting for the service to prepare an accepted drill: why it must stop instead, or null to keep waiting. */
+function prepareHalt(state) {
+    if (PREPARING_STATES.has(state) || PREPARED_STATES.has(state))
+        return null;
+    if (ROOT_TERMINAL_STATES.has(state))
+        return { outcome: 'incomplete', reason: 'native_assignment_terminal' };
+    return { outcome: 'incomplete', reason: DRILL_REASONS.draining };
+}
+/** While waiting for root to admit a drill that reported readiness: why it must stop instead, or null to keep waiting. */
+function admissionHalt(state) {
+    if (state === 'starting' || ADMITTED_STATES.has(state))
+        return null;
+    if (ROOT_TERMINAL_STATES.has(state))
+        return { outcome: 'incomplete', reason: 'native_assignment_terminal' };
+    // A lease lost while starting pauses the drill under a new epoch; this attempt cannot continue.
+    if (state === 'paused')
+        return { outcome: 'incomplete', reason: NATIVE_ERRORS.lease_expired };
+    return { outcome: 'incomplete', reason: DRILL_REASONS.draining };
+}
+/**
+ * While executing: the service began draining (a stop or cancel on its side) or
+ * ended the drill, so no further step is taken. Paused keeps waiting.
+ */
+function executionHalt(state) {
+    if (ROOT_TERMINAL_STATES.has(state))
+        return { outcome: 'incomplete', reason: 'native_assignment_terminal' };
+    if (state === 'draining' || state === 'reconciling')
+        return { outcome: 'incomplete', reason: DRILL_REASONS.draining };
+    return null;
+}
+/** Codes that name a local process, driver or target failure (anything not listed is reported as unknown). */
+const DRIVER_ERROR_CODES = new Set([NATIVE_ERRORS.process_exited, NATIVE_ERRORS.process_start_failed,
+    NATIVE_ERRORS.process_limit, NATIVE_ERRORS.port_unavailable, NATIVE_ERRORS.readiness_timeout, NATIVE_ERRORS.driver_unavailable,
+    NATIVE_ERRORS.unknown_outcome, DRILL_REASONS.state_reset_failed, DRILL_REASONS.drill_failed, READINESS_ERRORS.service_missing,
+    'native_readiness_unattested', 'native_local_run_service_ended']);
+/** Local approval and policy refusals. */
+const POLICY_CODES = new Set([NATIVE_ERRORS.plan_changed, NATIVE_ERRORS.plan_unapproved, NATIVE_ERRORS.root_outside,
+    NATIVE_ERRORS.auth_unsupported, DRILL_REASONS.intent_missing]);
+/**
+ * The close's client stop reason, or null when how the drill stopped does not
+ * map truthfully onto root's reasons (then no client summary is sent). Step
+ * failures carry the driver's own `native_target_*`/`native_step_*`/
+ * `native_session_*`/`native_response_*` codes.
+ */
+function stopReason(final, steps, assignment, ending) {
+    // Every root input ending is its own stop reason. A retained target failure or cancellation
+    // closes as failed or cancelled (root refuses it as completed); any other ending as completed,
+    // except root's `participant_unavailable`, which closes incomplete under its own stop reason.
+    if (final.outcome === 'completed') {
+        if (ending === null)
+            return 'completed';
+        return ending === 'target_failed' || ending === 'target_cancelled' || ending === 'participant_unavailable' ? null : ending;
+    }
+    if (ending === 'participant_unavailable' && final.reason === DRILL_REASONS.participant_unavailable)
+        return 'participant_unavailable';
+    if (ending === 'target_failed' && final.reason === DRILL_REASONS.target_failed)
+        return 'target_failed';
+    if (ending === 'target_cancelled' && final.reason === DRILL_REASONS.target_cancelled)
+        return 'target_cancelled';
+    if (final.outcome === 'cancelled')
+        return 'user_cancelled';
+    const reason = final.reason ?? '';
+    if (reason === NATIVE_ERRORS.budget_exhausted)
+        return steps >= assignment.budgets.max_steps ? 'step_limit' : 'deadline';
+    if (reason === NATIVE_ERRORS.disconnected || reason === NATIVE_ERRORS.lease_expired)
+        return 'connection_lost';
+    if (POLICY_CODES.has(reason))
+        return 'policy_denied';
+    if (DRIVER_ERROR_CODES.has(reason))
+        return 'driver_error';
+    if (!ROOT_SIDE_CODES.has(reason) && /^native_(target|step|session|response|driver)_/.test(reason))
+        return 'driver_error';
+    return null;
+}
+/**
+ * What root's ending already says about coverage, in words. Root's frozen
+ * completion evidence decides it; this only names what is certainly partial:
+ * any ending other than a finished participant or delivered inputs, or a
+ * scheduled scenario event that was due, never reached or still timed for later.
+ */
+function coverageText(ending, schedule, ran) {
+    const unapplied = schedule ? schedule.due_remaining + schedule.future_conditions + (schedule.future_timers ?? 0) : 0;
+    const counted = schedule && unapplied > 0 ? `${unapplied} of ${schedule.scheduled} scheduled scenario event(s) not applied`
+        + (typeof schedule.next_after_active_ms === 'number' && schedule.active_elapsed_ms !== undefined
+            ? `; the next timed event was set for ${activeTime(schedule.next_after_active_ms)} of active time, ${activeTime(schedule.active_elapsed_ms)} had run` : '')
+        : '';
+    // Root freezes a drill whose input had not ended as partial coverage.
+    if (ending === null)
+        return ran ? `; coverage is partial (the input had not ended when the drill stopped${counted ? `; ${counted}` : ''})` : '';
+    if (COMPLETE_ENDINGS.has(ending) && unapplied === 0)
+        return '';
+    return `; coverage is partial${counted ? ` (${counted})` : ''}`;
+}
+/** Step-related codes about the service's steps or reports, not the local target. */
+const ROOT_SIDE_CODES = new Set([DRILL_REASONS.step_invalid, DRILL_REASONS.step_report_failed, DRILL_REASONS.reply_undelivered,
+    DRILL_REASONS.result_undelivered]);
+/**
+ * Root's retained result for a task or event step: the target's own answer, never
+ * an assessment. A task returned; an event's receiver acknowledged the delivery
+ * (this client observes no later correlated result).
+ */
+function targetResult(step, outcome, output, coverage) {
+    return { schema: 'firedrill.native-target-result.v1', action_id: step.step_id, input_digest: step.input_digest,
+        kind: step.kind === 'event' ? 'event' : 'task', outcome, output: output ?? null, output_coverage: coverage,
+        completion: step.kind === 'event' ? { kind: 'delivery_acknowledged', delivery_id: step.step_id } : { kind: 'target_returned', delivery_id: null } };
+}
+/** Checks before admitting the next step. Returns why the drill must stop, or null. */
+function preStepHalt(assignment, deps, startedAt, steps) {
+    if (deps.isRevoked())
+        return { outcome: 'incomplete', reason: NATIVE_ERRORS.revoked };
+    if (deps.abortSignal.aborted || deps.stopSignal.aborted)
+        return { outcome: 'cancelled', reason: DRILL_REASONS.companion_stopped };
+    if (leaseRemainingMs(assignment) <= LEASE_MARGIN_MS)
+        return { outcome: 'incomplete', reason: NATIVE_ERRORS.lease_expired };
+    if (steps >= assignment.budgets.max_steps)
+        return { outcome: 'incomplete', reason: NATIVE_ERRORS.budget_exhausted };
+    if (Date.now() - startedAt >= assignment.budgets.max_elapsed_ms)
+        return { outcome: 'incomplete', reason: NATIVE_ERRORS.budget_exhausted };
+    return null;
+}
+/** The live lease signal fences work; the renewed lease is not a fixed step timeout. */
+function stepTimeout(step, assignment, startedAt) {
+    const limits = [assignment.budgets.step_timeout_ms,
+        assignment.budgets.max_elapsed_ms - (Date.now() - startedAt)];
+    if (Number.isSafeInteger(step.deadline_ms) && step.deadline_ms > 0)
+        limits.push(step.deadline_ms);
+    return Math.floor(Math.min(...limits));
+}
+function classify(error) {
+    if (isRevocation(error))
+        return { outcome: 'incomplete', reason: NATIVE_ERRORS.revoked };
+    if (isFenced(error))
+        return { outcome: 'incomplete', reason: errorCode(error) };
+    if (isTransient(error))
+        return { outcome: 'incomplete', reason: NATIVE_ERRORS.disconnected };
+    return { outcome: 'failed', reason: errorCode(error) ?? DRILL_REASONS.drill_failed };
+}
+function failedResult(step, code) {
+    const now = Date.now();
+    return {
+        step_id: typeof step?.step_id === 'string' ? step.step_id : '', intent_id: typeof step?.intent_id === 'string' ? step.intent_id : '',
+        outcome: 'failed', started_ms: now, finished_ms: now, output: null, error_code: code, observations: [],
+    };
+}
+async function reportStep(controlPlane, assignment, result, retry) {
+    const { observations: _observations, ...record } = result;
+    await retryTransient(() => controlPlane.completeStep(assignment, record, retry.signal), retry);
+}
+/**
+ * Invoke one step with a hard bound. A driver that ignores the abort is not
+ * awaited past the bound. Interrupted or thrown non-idempotent steps are
+ * `unknown` (the request may have reached the target) and are never replayed.
+ *
+ * Drivers return a step's own observations with its result, so when the driver
+ * never returns one (bound reached, or it threw) those observations are lost:
+ * the runner records a terminal `driver.failed` observation for the step and
+ * reports `evidenceLost` so the drill's evidence is marked incomplete.
+ */
+async function invokeStep(session, step, timeoutMs, drillSignal) {
+    const startedMs = Date.now();
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; controller.abort(new DOMException('The step budget ran out.', 'TimeoutError')); }, timeoutMs);
+    const onDrillAbort = () => controller.abort();
+    drillSignal.addEventListener('abort', onDrillAbort, { once: true });
+    const interrupted = (code, cause) => {
+        const outcome = step.idempotent ? 'failed' : 'unknown';
+        const errorCodeValue = step.idempotent ? code : NATIVE_ERRORS.unknown_outcome;
+        const finishedMs = Date.now();
+        const result = {
+            step_id: step.step_id, intent_id: step.intent_id, outcome, started_ms: startedMs, finished_ms: finishedMs, output: null,
+            error_code: errorCodeValue,
+            observations: [{ kind: 'driver.failed', at_ms: finishedMs, content: {
+                        step_id: step.step_id, type: 'step.interrupted', cause, interrupt_code: code, outcome, error_code: errorCodeValue,
+                    } }],
+        };
+        return { result, evidenceLost: true };
+    };
+    try {
+        // Grace beyond the bound lets a cooperating driver return its own (more precise) result.
+        const graceMs = 2_000;
+        const bound = new Promise((resolve) => {
+            const onAbort = () => setTimeout(() => resolve('bound'), graceMs).unref?.();
+            if (controller.signal.aborted)
+                onAbort();
+            else
+                controller.signal.addEventListener('abort', onAbort, { once: true });
+        });
+        const raced = await Promise.race([session.invoke(step, controller.signal), bound]);
+        if (raced === 'bound')
+            return interrupted(timedOut ? 'native_step_timeout' : 'native_step_cancelled', 'not_returned');
+        return { result: normalizeResult(raced, step, startedMs), evidenceLost: false };
+    }
+    catch (error) {
+        return interrupted(errorCode(error) ?? 'native_target_error', 'thrown');
+    }
+    finally {
+        clearTimeout(timer);
+        drillSignal.removeEventListener('abort', onDrillAbort);
+    }
+}
+const OUTCOMES = new Set(['completed', 'failed', 'cancelled', 'unknown']);
+/** Keep the driver's result but bind it to this step; an unrecognised outcome on a non-idempotent step is `unknown`. */
+function normalizeResult(result, step, startedMs) {
+    const outcome = result && OUTCOMES.has(result.outcome) ? result.outcome : (step.idempotent ? 'failed' : 'unknown');
+    return {
+        step_id: step.step_id,
+        intent_id: step.intent_id,
+        outcome,
+        started_ms: Number.isFinite(result?.started_ms) ? result.started_ms : startedMs,
+        finished_ms: Number.isFinite(result?.finished_ms) ? result.finished_ms : Date.now(),
+        output: result?.output ?? null,
+        output_coverage: result?.output_coverage === 'complete' || result?.output_coverage === 'redacted'
+            || result?.output_coverage === 'omitted' ? result.output_coverage : undefined,
+        error_code: typeof result?.error_code === 'string' ? result.error_code
+            : outcome === 'unknown' ? NATIVE_ERRORS.unknown_outcome : null,
+        observations: Array.isArray(result?.observations) ? result.observations : [],
+        delivered: result?.delivered === true,
+    };
+}
+/**
+ * Write the MCP client configuration for one per-drill service whose MCP
+ * dependencies the plan routes through it (`mcp_config_env` names the variable
+ * that receives its path). Returns null when the service has none.
+ */
+async function writeServiceMcpConfig(routes, service, urls, scratchDir) {
+    const servers = mcpServers(routes, service.alias, urls);
+    if (servers.length === 0)
+        return null;
+    return writeMcpConfig(servers, scratchDir, { envName: service.mcp_config_env });
+}