firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/native/local-run.js

@@ -0,0 +1,667 @@
+/**
+ * The campaign's local run on this device (Plan20 FIR-492, root
+ * `local-run-lifecycle.v1`).
+ *
+ * Shared services the plan launches once (not per drill) outlive any one drill,
+ * so root tracks them as one run per campaign and device:
+ *  - `register` before this device's first offer in the campaign, with a fixed
+ *    launch id per service, every service `planned`. It grants no launch: a shared
+ *    service still starts only inside a drill root has prepared;
+ *  - `observe` each change (first launch -> `running`, an end -> `reaped` with its
+ *    exit code, or `unknown` when the end cannot be attested), confirmed before
+ *    the drill that needs it reports readiness;
+ *  - each drill's close reports these services as `owned_run`/`transport_detached`
+ *    from the state root last confirmed;
+ *  - `close` at shutdown, once every service was stopped, after root sealed every
+ *    accepted drill of the campaign on this device (seals arrive asynchronously,
+ *    so the close is retried for a bounded time while the device session is live).
+ *
+ * Root never infers a reap and keeps one run per campaign and device forever, so
+ * the run's identity, confirmed snapshot and any unconfirmed event are persisted
+ * per campaign and runner device in the private profile directory and re-sent
+ * byte-identical after a restart. Root accepts the run's events only signed by
+ * that device, so only a later start with the same runner can close it.
+ * A run left with services running by an earlier companion cannot be continued:
+ * those processes are reported `unknown` (never invented as reaped) and the
+ * companion stops. Nothing here starts or stops a process; the supervisor does.
+ */
+import { randomUUID } from 'node:crypto';
+import { open, readFile, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { privateDirectory } from '../credentials.js';
+import { CliError } from '../http.js';
+import { LOCAL_RUN_MAX_SERVICES } from './contracts.js';
+import { backoffMs, errorCode, isAbort, isTransient, retryTransient, sleep } from './control-plane.js';
+export const LOCAL_RUN_ERRORS = {
+    /** Shared launched services need a selected campaign: root keeps their run per campaign. */
+    campaign_required: 'native_local_run_campaign_required',
+    /** Root runs shared services only for a campaign that runs one drill at a time. */
+    serial_required: 'native_local_run_serial_required',
+    /** A shared service whose state is not serial and reset per drill (fresh session or approved hook). */
+    reset_required: 'native_local_run_reset_required',
+    /** Root registers a run only while the campaign is allocating or queued. */
+    registration_closed: 'native_local_run_registration_closed',
+    /**
+     * Only the registering runner device can close the run, and a session-only runner's key lives only in
+     * its process, so shared services are refused for it before any runner is enrolled or anything starts.
+     */
+    persistent_runner_required: 'native_local_run_persistent_runner_required',
+    /** The run cannot be continued from this machine (no record, a different plan, or processes left by an earlier companion). */
+    unrecoverable: 'native_local_run_unrecoverable',
+    /** The run is closed; this device takes no more drills of the campaign. */
+    closed: 'native_local_run_closed',
+    /** A shared service's end could not be attested; root keeps the run uncertain. */
+    uncertain: 'native_local_run_uncertain',
+    /** A shared service ended; it is never started again under the run's identity. */
+    service_ended: 'native_local_run_service_ended',
+    /** The run is not registered yet (or no longer reported), so a shared service cannot be reported truthfully. */
+    unregistered: 'native_local_run_unregistered',
+};
+const REGISTER_STATES = new Set(['allocating', 'queued']);
+const STATE_SCHEMA = 'firedrill.native-local-run-state.v1';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const RUN_ALIAS = /^[a-z][a-z0-9_-]{0,63}$/;
+/** Root's seals arrive asynchronously; the run close is retried between these bounds. */
+const CLOSE_RETRY_BASE_MS = 2_000;
+const CLOSE_RETRY_CAP_MS = 15_000;
+/** Shared services that belong to a campaign's local run: launched once (not per drill), not attached, not driver-owned. */
+export function runOwnedAliases(plan) {
+    const driverAlias = plan.driver.profile === 'jsonl-process.v1' ? plan.driver.service_alias : null;
+    return plan.services.filter((service) => service.mode === 'launch' && !service.per_drill && service.alias !== driverAlias)
+        .map((service) => service.alias);
+}
+/**
+ * Root admits a shared service into a run only when every state domain on it is
+ * serial and reset per drill by a fresh session or an approved hook (and it has
+ * at least one). Checked before anything opens, with root's own rule.
+ */
+export function checkRunCompatible(descriptor, aliases) {
+    if (aliases.length > LOCAL_RUN_MAX_SERVICES) {
+        throw new CliError(LOCAL_RUN_ERRORS.reset_required, `The service runs at most ${LOCAL_RUN_MAX_SERVICES} shared services per campaign. Nothing was started.`, 2);
+    }
+    for (const alias of aliases) {
+        const domains = descriptor.state_domains.filter((domain) => domain.service_alias === alias);
+        const resettable = domains.length > 0 && RUN_ALIAS.test(alias) && domains.every((domain) => domain.concurrency === 'serial'
+            && (domain.reset === 'fresh-session' || (domain.reset === 'approved-hook' && typeof domain.hook_sha256 === 'string' && domain.hook_sha256.length > 0)));
+        if (!resettable) {
+            throw new CliError(LOCAL_RUN_ERRORS.reset_required, `Shared service "${alias}" cannot be kept running across drills: each of its declared state domains must be serial and reset per drill by a fresh session or an approved hook. Make it per-drill in the plan, or declare its state. Nothing was started.`, 2);
+        }
+    }
+}
+export class LocalRun {
+    #options;
+    #aliases;
+    #path;
+    /** Where records were kept per campaign only, before they named the device. */
+    #legacyPath;
+    #state = null;
+    #chain = Promise.resolve();
+    /** Why this run serves no further drills on this device; null while it may. */
+    #retired = null;
+    constructor(options, path, legacyPath) {
+        this.#options = options;
+        this.#aliases = new Set(options.aliases);
+        this.#path = path;
+        this.#legacyPath = legacyPath;
+    }
+    /**
+     * Load what this machine knows about the run and reconcile it with root before
+     * any offer is taken. A fresh run is registered later, just before the first
+     * slot offer (`beforeOffer`).
+     */
+    static async open(options, signal) {
+        if (!UUID.test(options.campaignId))
+            throw new CliError(LOCAL_RUN_ERRORS.campaign_required, 'Shared services need the campaign id exactly as Firedrill printed it. Nothing was started.', 2);
+        const deviceKey = typeof options.deviceKey === 'string' ? options.deviceKey.toLowerCase() : '';
+        if (!UUID.test(deviceKey))
+            throw new CliError('runner_receipt_invalid', 'Shared services need the runner device key exactly as Firedrill printed it. Nothing was started.', 2);
+        const directory = await privateDirectory();
+        const run = new LocalRun({ ...options, deviceKey }, join(directory, `native-local-run-${options.campaignId}-${deviceKey}.json`), join(directory, `native-local-run-${options.campaignId}.json`));
+        await run.#recover(signal);
+        return run;
+    }
+    /** The one way to close the run after this companion: root accepts its close only signed by this runner device. */
+    get closeLaterHint() {
+        return `Run the companion again later for campaign ${this.#options.campaignId} with --runner ${this.#options.deviceKey} to close it; `
+            + 'only this runner device can.';
+    }
+    /** Why the run takes no further drills, or null. */
+    get retired() { return this.#retired; }
+    /** Root confirmed the run's registration and it can still take drills. */
+    get registered() { return !this.#retired && !!this.#state && this.#state.sequence >= 1 && !this.#state.closed; }
+    /** The launch id registered for a run-owned alias, once root confirmed the registration. */
+    launchId(alias) {
+        const state = this.#state;
+        return state && state.sequence >= 1 && this.#aliases.has(alias) ? state.launches[alias] ?? null : null;
+    }
+    beforeLaunch(alias) {
+        return this.#serial(async () => {
+            const state = this.#state;
+            if (!state || state.sequence < 1 || state.closed || this.#retired || !this.#aliases.has(alias)
+                || state.launch_intents.includes(alias)
+                || state.observed?.some((item) => item.service === alias && item.state !== 'planned'))
+                throw new CliError(LOCAL_RUN_ERRORS.uncertain, 'The original shared-service launch must be reconciled before another launch. Nothing was started.');
+            state.launch_intents.push(alias);
+            await this.#persist();
+        });
+    }
+    captureObserved(final = false) {
+        return this.#serial(async () => {
+            if (!this.#state || this.#state.closed)
+                return;
+            this.#state.observed = this.#snapshot(final);
+            await this.#persist();
+        });
+    }
+    notStarted(alias) {
+        return this.#serial(async () => {
+            const state = this.#state;
+            if (!state || !state.launch_intents.includes(alias)
+                || (this.#options.observe().get(alias)?.state ?? 'planned') !== 'planned'
+                || state.confirmed?.some((item) => item.service === alias && item.state !== 'planned')) {
+                throw new CliError(LOCAL_RUN_ERRORS.uncertain, 'The original launch cannot be recorded as never started.');
+            }
+            const observed = this.#snapshot(false);
+            state.observed = observed.map((item) => item.service === alias
+                ? { ...item, state: 'not_started', exit_code: null } : item);
+            await this.#persist();
+        });
+    }
+    /** A run-owned alias root currently knows as running: its identity for a drill's readiness. */
+    runService = (alias) => {
+        const state = this.#state;
+        const entry = state?.confirmed?.find((item) => item.service === alias);
+        return state && entry?.state === 'running' ? { run_id: state.run_id, launch_id: entry.launch_id } : null;
+    };
+    closeEntry(alias, outcome) {
+        if (!this.#aliases.has(alias))
+            return null;
+        const state = this.#state;
+        const entry = state?.confirmed?.find((item) => item.service === alias);
+        if (!state || !entry)
+            return LOCAL_RUN_ERRORS.unregistered;
+        if (entry.state === 'running' || entry.state === 'reaped') {
+            return { service: alias, launch_id: entry.launch_id, run_id: state.run_id, ownership: 'owned_run', close_kind: 'transport_detached' };
+        }
+        if (entry.state === 'unknown')
+            return LOCAL_RUN_ERRORS.uncertain;
+        // Launched here but root never confirmed it: "not started" would contradict the launch once reported.
+        if (entry.state === 'planned' && (state.launch_intents.includes(alias)
+            || (this.#options.observe().get(alias)?.state ?? 'planned') !== 'planned'))
+            return LOCAL_RUN_ERRORS.unregistered;
+        return outcome === 'completed' ? 'native_close_service_not_launched' : { service: alias, ownership: 'none', close_kind: 'not_started' };
+    }
+    /**
+     * Before each slot offer: the run must be registered first (root refuses a
+     * registration once this device has any offer in the campaign). Throws when
+     * the run can take no further drills, so the companion stops and closes it.
+     */
+    beforeOffer = (signal) => this.#serial(async () => {
+        if (this.#retired)
+            throw new CliError(this.#retired.code, this.#retired.message);
+        if (this.#state && this.#state.sequence < 1 && this.#state.pending?.action !== 'register')
+            this.#state = null;
+        const existing = this.#state;
+        if (existing && existing.sequence >= 1)
+            return true;
+        if (!existing) {
+            const policy = await this.#options.controlPlane.campaignPolicy(this.#options.campaignId, signal);
+            if (policy.max_parallel !== 1) {
+                throw new CliError(LOCAL_RUN_ERRORS.serial_required, 'This plan keeps shared services running across drills, which the service allows only for a campaign that runs one drill at a time. Make those services per-drill, or use a campaign with max parallel 1. No drill was requested.', 2);
+            }
+            if (!REGISTER_STATES.has(policy.state)) {
+                throw new CliError(LOCAL_RUN_ERRORS.registration_closed, `The campaign is ${policy.state}; its shared services can be registered only while it is allocating or queued. No drill was requested.`, 2);
+            }
+            const runId = randomUUID();
+            const launches = Object.fromEntries(this.#options.aliases.map((alias) => [alias, randomUUID()]));
+            const services = this.#options.aliases.map((alias) => ({ service: alias, launch_id: launches[alias], state: 'planned', exit_code: null }));
+            this.#state = { schema: STATE_SCHEMA, campaign_id: this.#options.campaignId, descriptor_sha256: this.#options.descriptorSha256,
+                run_id: runId, launches, confirmed: null, sequence: 0, pending: { run_id: runId, request_key: randomUUID(), sequence: 1, action: 'register', services },
+                closed: false, launch_intents: [], observed: null };
+            await this.#persist();
+        }
+        const state = this.#state;
+        try {
+            await this.#submit(state.pending, signal);
+        }
+        catch (error) {
+            // An answered refusal stored nothing on root: forget the registration so a later start does not resend it.
+            if (refused(error)) {
+                this.#state = null;
+                await this.#persist();
+            }
+            throw error;
+        }
+        this.#options.output('native_local_run_registered', { campaign_id: this.#options.campaignId, run_id: state.run_id, services: this.#options.aliases }, `Registered this campaign's shared services (${this.#options.aliases.join(', ')}) with the service. They start with the first drill.`);
+        return true;
+    });
+    /** Report each run-owned service's current state to root (nothing when unchanged); resolves once root confirmed it. */
+    sync(signal) {
+        return this.#serial(async () => {
+            const state = this.#state;
+            if (!state || state.sequence < 1 || state.closed)
+                return;
+            state.observed = this.#snapshot(false);
+            await this.#persist();
+            if (state.pending)
+                await this.#submit(state.pending, signal);
+            const next = this.#snapshot(false);
+            if (sameSnapshot(next, state.confirmed))
+                return;
+            await this.#send('observe', next, signal);
+        });
+    }
+    /**
+     * At shutdown, after every service was stopped: close the run once root sealed
+     * every accepted drill of the campaign on this device. Waits (retrying the same
+     * event) while root reports drills pending, until `until` aborts. Returns
+     * whether the run is closed; a run that cannot be closed now is left for a
+     * later start of the companion with the same runner device to close.
+     */
+    close(signal, until) {
+        return this.#serial(async () => {
+            const state = this.#state;
+            if (!state)
+                return true;
+            if (state.closed)
+                return true;
+            state.observed = this.#snapshot(true);
+            await this.#persist();
+            if (state.sequence < 1) {
+                // A registration that was never confirmed. Re-sending it could create a run only to close it, which
+                // would end the campaign on this device for good; reading root tells whether it landed instead.
+                const pending = state.pending;
+                if (!pending)
+                    return true;
+                let receipt;
+                try {
+                    receipt = await this.#options.controlPlane.readRun(this.#options.campaignId, signal);
+                }
+                catch {
+                    return false;
+                }
+                // Not landed: the record stays, so a later start re-sends it byte-identical (or forgets it when refused).
+                if (!receipt)
+                    return true;
+                if (receipt.run_id !== state.run_id || receipt.sequence !== pending.sequence)
+                    return false;
+                state.confirmed = pending.services;
+                state.sequence = pending.sequence;
+                state.pending = null;
+                await this.#persist();
+            }
+            if (state.pending) {
+                try {
+                    await this.#submit(state.pending, signal);
+                }
+                catch (error) {
+                    if (!refused(error))
+                        return false;
+                    // Refused: root stored nothing; the report is rebuilt from what root holds.
+                    state.pending = null;
+                    await this.#persist();
+                }
+                // The unconfirmed event was itself the close.
+                if (state.closed)
+                    return true;
+            }
+            const final = this.#snapshot(true);
+            // How each service ended is recorded with root first: a close refused while drills are still
+            // being sealed stores nothing, and the next start must not find these services "running".
+            if (!sameSnapshot(final, state.confirmed)) {
+                try {
+                    await this.#send('observe', final, signal);
+                }
+                catch (error) {
+                    this.#options.output('native_local_run_close_pending', { campaign_id: this.#options.campaignId, run_id: state.run_id, error_code: errorCode(error) }, `How the campaign's shared services ended was not confirmed by the service. ${this.closeLaterHint}`);
+                    return false;
+                }
+            }
+            if (final.some((item) => item.state === 'unknown' || item.state === 'running')) {
+                // Root keeps the run uncertain until each end is attested; nothing is invented.
+                this.#options.output('native_local_run_uncertain', { campaign_id: this.#options.campaignId, run_id: state.run_id }, 'A shared service did not end in a way this client could attest, so the campaign\'s local run stays open and uncertain. It needs the service\'s help to close.');
+                return false;
+            }
+            const event = { run_id: state.run_id, request_key: randomUUID(), sequence: state.sequence + 1, action: 'close', services: final };
+            state.pending = event;
+            await this.#persist();
+            let announced = false;
+            for (let attempt = 0;; attempt++) {
+                try {
+                    await this.#submit(event, signal);
+                    this.#options.output('native_local_run_closed', { campaign_id: this.#options.campaignId, run_id: state.run_id }, 'Closed this campaign\'s local run: every shared service was stopped and reported.');
+                    return true;
+                }
+                catch (error) {
+                    const code = errorCode(error);
+                    const waiting = code === 'native_local_run_drills_pending';
+                    if (isAbort(error, signal)) {
+                        // The close may have landed: it stays recorded and a later start re-sends it byte-identical.
+                        this.#options.output('native_local_run_close_pending', { campaign_id: this.#options.campaignId, run_id: state.run_id }, `The campaign's local run close was not confirmed. ${this.closeLaterHint}`);
+                        return false;
+                    }
+                    if (!waiting && refused(error)) {
+                        // Root stored nothing; every end is already recorded, so a later start only closes.
+                        state.pending = null;
+                        await this.#persist();
+                        this.#options.output('native_local_run_close_refused', { campaign_id: this.#options.campaignId, error_code: code }, `The service refused to close this campaign's local run. ${this.closeLaterHint}`);
+                        return false;
+                    }
+                    if (!waiting && !isTransient(error)) {
+                        // An answer this client could not confirm: the close may have landed, so it stays recorded and is re-sent.
+                        this.#options.output('native_local_run_close_pending', { campaign_id: this.#options.campaignId, run_id: state.run_id, error_code: code }, `The campaign's local run close was not confirmed. ${this.closeLaterHint}`);
+                        return false;
+                    }
+                    if (waiting && !announced) {
+                        announced = true;
+                        this.#options.output('native_local_run_closing', { campaign_id: this.#options.campaignId }, 'Waiting for the service to seal this device\'s drills before it closes the campaign\'s local run.');
+                    }
+                    if (until.aborted || !await sleep(backoffMs(attempt, CLOSE_RETRY_BASE_MS, CLOSE_RETRY_CAP_MS), until)) {
+                        // A refused attempt stored nothing (every end is already recorded); an unanswered one is re-sent unchanged by a later start.
+                        if (waiting) {
+                            state.pending = null;
+                            await this.#persist();
+                        }
+                        this.#options.output('native_local_run_close_pending', { campaign_id: this.#options.campaignId, run_id: state.run_id }, `The campaign's local run is not closed yet (its drills are not all sealed). ${this.closeLaterHint}`);
+                        return false;
+                    }
+                }
+            }
+        });
+    }
+    // -------------------------------------------------------------------------
+    async #recover(signal) {
+        let state = await this.#load(this.#path);
+        const receipt = await retryTransient(() => this.#options.controlPlane.readRun(this.#options.campaignId, signal), { signal, attempts: 4 });
+        if (!state && receipt)
+            state = await this.#claimLegacy(receipt);
+        if (!state) {
+            if (!receipt)
+                return;
+            // This machine lost its record (or never kept one), but root holds the run's descriptor and service
+            // snapshot: for the same plan the run is taken over from that snapshot. No process is relaunched from it.
+            const adopted = this.#adopt(receipt, null);
+            if (!adopted) {
+                this.#retire(LOCAL_RUN_ERRORS.unrecoverable, 'This device already has a local run for this campaign, registered for a different plan (other shared services or descriptor), so it can be neither continued nor closed from here. Approve that plan again, or use another campaign.');
+                return;
+            }
+            state = adopted;
+            this.#options.output('native_local_run_recovered', { campaign_id: this.#options.campaignId, run_id: state.run_id, sequence: state.sequence }, 'This machine had no record of the campaign\'s local run, so it continues from the service\'s record of its shared services.');
+        }
+        this.#state = state;
+        if (!receipt) {
+            if (state.sequence === 0)
+                return; // registration never confirmed: re-sent before the first offer
+            this.#retire(LOCAL_RUN_ERRORS.unrecoverable, 'This machine recorded a local run for this campaign that the service does not have for this device. Nothing was started.');
+            this.#state = null;
+            return;
+        }
+        if (receipt.run_id !== state.run_id) {
+            this.#retire(LOCAL_RUN_ERRORS.unrecoverable, 'The service holds a different local run for this campaign and device than this machine recorded. Nothing was started.');
+            this.#state = null;
+            return;
+        }
+        // An unconfirmed event either landed (root is at its sequence) or not (root is where this machine left off).
+        if (state.pending && receipt.sequence === state.pending.sequence) {
+            state.confirmed = state.pending.services;
+            state.sequence = state.pending.sequence;
+            if (state.pending.action === 'close')
+                state.closed = true;
+            state.pending = null;
+        }
+        else if (receipt.sequence === state.sequence) {
+            // Not landed. How the services ended must not be lost with it: an observe is re-sent unchanged below,
+            // and a close (root stored neither) becomes the observe of the same ends; the run is closed at the next stop.
+            const pending = state.pending;
+            state.pending = pending?.action === 'observe' ? pending
+                : pending?.action === 'close' && !sameSnapshot(pending.services, state.confirmed)
+                    ? { run_id: state.run_id, request_key: randomUUID(), sequence: state.sequence + 1, action: 'observe', services: pending.services }
+                    : null;
+        }
+        else if (receipt.sequence > state.sequence) {
+            // Root is ahead of this machine (an event confirmed after this record was written): its snapshot
+            // of the same services and launches is authoritative, and any unconfirmed event here is superseded.
+            const adopted = this.#adopt(receipt, state);
+            if (!adopted) {
+                this.#retire(LOCAL_RUN_ERRORS.unrecoverable, 'The service\'s record of this campaign\'s local run is ahead of this machine\'s and names other services or launches. Nothing was started.');
+                return;
+            }
+            state = adopted;
+            this.#state = state;
+        }
+        else {
+            this.#retire(LOCAL_RUN_ERRORS.unrecoverable, 'The service\'s record of this campaign\'s local run is behind this machine\'s. Nothing was started.');
+            return;
+        }
+        if (receipt.state === 'closed')
+            state.closed = true;
+        await this.#persist();
+        if (state.closed) {
+            this.#retire(LOCAL_RUN_ERRORS.closed, 'This campaign\'s local run on this device is closed, so it takes no more drills here. Use another campaign.');
+            return;
+        }
+        if (state.pending) {
+            // Reported before the earlier companion stopped but not confirmed: confirm it before judging what is left.
+            // Unconfirmed again (no answer), the start fails and the record keeps it for the next one.
+            const pending = state.pending;
+            try {
+                await this.#serial(() => this.#submit(pending, signal));
+            }
+            catch (error) {
+                if (!refused(error))
+                    throw error;
+                state.pending = null;
+                await this.#persist();
+            }
+        }
+        const confirmed = this.#snapshot(false);
+        state.observed = confirmed;
+        await this.#persist();
+        if (confirmed.some((item) => item.state === 'running')) {
+            // Processes started by an earlier companion are not this one's to report as ended.
+            const orphaned = confirmed.map((item) => item.state === 'running' ? { ...item, state: 'unknown', exit_code: null } : item);
+            await this.#serial(() => this.#send('observe', orphaned, signal)).catch(() => undefined);
+            this.#retire(LOCAL_RUN_ERRORS.unrecoverable, 'Shared services have an unresolved original launch. Their state remains unknown and settlement cannot finish until truthful cleanup evidence is available. This campaign takes no more drills on this device.');
+            return;
+        }
+        if (confirmed.some((item) => item.state === 'unknown')) {
+            this.#retire(LOCAL_RUN_ERRORS.uncertain, 'A shared service of this campaign ended without an attested exit, so the service keeps the local run uncertain and this device takes no more of its drills.');
+            return;
+        }
+        if (confirmed.some((item) => item.state === 'reaped' || item.state === 'not_started')) {
+            this.#retire(LOCAL_RUN_ERRORS.service_ended, 'This campaign\'s shared services already ended, so this device takes no more of its drills. The companion only closes the local run.');
+        }
+    }
+    /**
+     * A record kept per campaign only (before records named the device) may be
+     * another runner's. It is this device's only when root holds the same run for
+     * this device (run ids are unique); it then moves to this device's record.
+     * Otherwise it is left untouched for the device that wrote it.
+     */
+    async #claimLegacy(receipt) {
+        let legacy;
+        try {
+            legacy = await this.#load(this.#legacyPath);
+        }
+        catch {
+            return null;
+        }
+        if (!legacy || legacy.run_id !== receipt.run_id)
+            return null;
+        this.#state = legacy;
+        await this.#persist();
+        await rm(this.#legacyPath, { force: true });
+        return legacy;
+    }
+    /**
+     * A record rebuilt from root's receipt: only for this plan's descriptor and
+     * exactly its shared services, and (with a record) the launches it fixed.
+     * Root's snapshot is the device's own earlier report, not proof of a process.
+     */
+    #adopt(receipt, recorded) {
+        const byAlias = new Map(receipt.services.map((item) => [item.service, item]));
+        if (receipt.descriptor_digest !== this.#options.descriptorSha256 || byAlias.size !== this.#options.aliases.length
+            || !this.#options.aliases.every((alias) => byAlias.has(alias))
+            || (recorded && (recorded.run_id !== receipt.run_id
+                || !this.#options.aliases.every((alias) => recorded.launches[alias] === byAlias.get(alias)?.launch_id))))
+            return null;
+        const confirmed = this.#options.aliases.map((alias) => byAlias.get(alias));
+        return { schema: STATE_SCHEMA, campaign_id: this.#options.campaignId, descriptor_sha256: this.#options.descriptorSha256,
+            run_id: receipt.run_id, launches: Object.fromEntries(confirmed.map((item) => [item.service, item.launch_id])),
+            confirmed, sequence: receipt.sequence, pending: null, closed: receipt.state === 'closed',
+            launch_intents: recorded?.launch_intents ?? confirmed.map((item) => item.service),
+            observed: recorded?.observed ?? confirmed };
+    }
+    /** The snapshot to report: what the supervisor observes, never contradicting what root already holds. */
+    #snapshot(final) {
+        const state = this.#state;
+        const observed = this.#options.observe();
+        const confirmed = new Map((state.confirmed ?? []).map((item) => [item.service, item]));
+        const services = this.#options.aliases.map((alias) => {
+            let seen = observed.get(alias) ?? { state: 'planned' };
+            const retained = state.observed?.find((item) => item.service === alias);
+            if (retained?.state === 'reaped' || retained?.state === 'not_started')
+                return retained;
+            if (seen.state === 'planned' && retained && retained.state !== 'planned') {
+                seen = { state: 'unknown' };
+            }
+            if (seen.state === 'planned' && state.launch_intents.includes(alias))
+                seen = { state: 'unknown' };
+            const prior = confirmed.get(alias)?.state ?? 'planned';
+            const launch = state.launches[alias];
+            // Reaped and never-started entries are immutable; an ended or lost process never becomes running again.
+            if (prior === 'reaped' || prior === 'not_started')
+                return confirmed.get(alias);
+            let next = seen.state === 'planned' && final ? 'not_started' : seen.state;
+            if ((prior === 'running' || prior === 'unknown') && (next === 'planned' || next === 'not_started'))
+                next = 'unknown';
+            if (prior === 'unknown' && next === 'running')
+                next = 'unknown';
+            return { service: alias, launch_id: launch, state: next, exit_code: next === 'reaped' && seen.state === 'reaped' ? seen.exit_code : null };
+        });
+        // While drills may still follow, an ended service retires the run (at shutdown every service ends by design).
+        for (const item of final ? [] : services) {
+            if ((item.state === 'reaped' || item.state === 'unknown') && !this.#retired) {
+                this.#retire(item.state === 'reaped' ? LOCAL_RUN_ERRORS.service_ended : LOCAL_RUN_ERRORS.uncertain, `Shared service ${item.service} ended, so this campaign takes no more drills on this device; its local run is closed when the companion stops.`);
+            }
+        }
+        return services;
+    }
+    async #send(action, services, signal) {
+        const state = this.#state;
+        state.observed = services;
+        const event = { run_id: state.run_id, request_key: randomUUID(), sequence: state.sequence + 1, action, services };
+        state.pending = event;
+        await this.#persist();
+        try {
+            await this.#submit(event, signal);
+        }
+        catch (error) {
+            // An answered refusal stored nothing: the next report is built afresh. Anything else may have landed and is re-sent unchanged.
+            if (refused(error)) {
+                state.pending = null;
+                await this.#persist();
+            }
+            throw error;
+        }
+    }
+    /** Submit one event and record root's confirmation. */
+    async #submit(event, signal) {
+        const state = this.#state;
+        const receipt = await this.#options.controlPlane.submitRun(this.#options.campaignId, event, signal);
+        state.confirmed = event.services;
+        state.sequence = event.sequence;
+        state.pending = null;
+        if (event.action === 'close' || receipt.state === 'closed')
+            state.closed = true;
+        await this.#persist();
+        if (receipt.state === 'uncertain' && !this.#retired) {
+            this.#retire(LOCAL_RUN_ERRORS.uncertain, 'The service keeps this campaign\'s local run uncertain, so this device takes no more of its drills.');
+        }
+    }
+    #retire(code, message) {
+        if (this.#retired)
+            return;
+        this.#retired = { code, message };
+        this.#options.output('native_local_run_retired', { campaign_id: this.#options.campaignId, reason: code }, message);
+    }
+    #serial(work) {
+        const run = this.#chain.catch(() => undefined).then(work);
+        this.#chain = run;
+        return run;
+    }
+    async #load(path) {
+        let text;
+        try {
+            text = await readFile(path, 'utf8');
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT')
+                return null;
+            throw new CliError(LOCAL_RUN_ERRORS.unrecoverable, 'This machine\'s record of the campaign\'s local run could not be read. Nothing was started.');
+        }
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            value = null;
+        }
+        const launches = value?.launches && typeof value.launches === 'object' ? value.launches : null;
+        const aliases = launches ? Object.keys(launches).sort() : [];
+        if (!value || value.schema !== STATE_SCHEMA || value.campaign_id !== this.#options.campaignId || !UUID.test(value.run_id)
+            || !Number.isSafeInteger(value.sequence) || value.sequence < 0 || typeof value.closed !== 'boolean' || !launches
+            || !aliases.every((alias) => UUID.test(launches[alias]))) {
+            throw new CliError(LOCAL_RUN_ERRORS.unrecoverable, 'This machine\'s record of the campaign\'s local run is damaged, so the run cannot be continued. Nothing was started.');
+        }
+        if (value.descriptor_sha256 !== this.#options.descriptorSha256 || aliases.join('\0') !== [...this.#options.aliases].sort().join('\0')) {
+            throw new CliError(LOCAL_RUN_ERRORS.unrecoverable, 'This campaign\'s local run was registered for a different plan (other shared services or descriptor). Approve that plan again, or use another campaign. Nothing was started.', 2);
+        }
+        if (value.launch_intents === undefined)
+            value.launch_intents = value.sequence > 0 ? aliases : [];
+        if (value.observed === undefined)
+            value.observed = value.pending?.services ?? value.confirmed;
+        if (!Array.isArray(value.launch_intents) || value.launch_intents.some((alias) => !aliases.includes(alias))
+            || (value.observed !== null && (!Array.isArray(value.observed) || value.observed.length !== aliases.length
+                || new Set(value.observed.map((item) => item.service)).size !== aliases.length
+                || value.observed.some((item) => !aliases.includes(item.service) || item.launch_id !== launches[item.service]
+                    || !['planned', 'running', 'unknown', 'reaped', 'not_started'].includes(item.state)
+                    || (item.state === 'reaped' ? !Number.isSafeInteger(item.exit_code) : item.exit_code !== null))))) {
+            throw new CliError(LOCAL_RUN_ERRORS.unrecoverable, 'The retained local process evidence is invalid. Nothing was started.');
+        }
+        return value;
+    }
+    /** Atomic, private write: a crash leaves the previous record or the new one, never half of one. No record: the file is removed. */
+    async #persist() {
+        if (!this.#state) {
+            await rm(this.#path, { force: true });
+            return;
+        }
+        const temporary = `${this.#path}.${randomUUID()}.tmp`;
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(this.#state));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, this.#path);
+    }
+}
+/**
+ * An answered refusal: root stored nothing (a 4xx that is not a rate or timing
+ * condition), or the event never left this client. Anything else (no answer, a
+ * 5xx, an answer this client could not confirm) may have landed.
+ */
+function refused(error) {
+    if (errorCode(error) === 'native_local_run_invalid')
+        return true;
+    return error instanceof CliError && error.httpStatus !== null && error.httpStatus >= 400 && error.httpStatus < 500 && !isTransient(error);
+}
+function sameSnapshot(a, b) {
+    if (!b || a.length !== b.length)
+        return false;
+    return a.every((item, index) => item.service === b[index].service && item.launch_id === b[index].launch_id
+        && item.state === b[index].state && item.exit_code === b[index].exit_code);
+}