firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/runner-identity.js

@@ -0,0 +1,615 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { api } from './auth.js';
+import { localRunnerLookupMatches, localRunnersMatch } from '../../contracts/local-runner-contracts.js';
+import { privateDirectory } from './credentials.js';
+import { withBootstrapProcessLock } from './bootstrap-process-lock.js';
+import { API_ORIGIN, CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const object = value;
+        return '{' + Object.keys(object).sort().map(key => canonical(key) + ':' + canonical(object[key])).join(',') + '}';
+    }
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new CliError('runner_journal_invalid', 'The runner request contains an unsupported value.');
+    // Root signs and digests Python json.dumps(ensure_ascii=True): every code unit outside space..tilde is \u-escaped.
+    return encoded.replace(/[\u007f-\uffff]/g, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+const digest = (value) => createHash('sha256').update(canonical(value)).digest('hex');
+const pathFor = (scope, key) => `/api/workspaces/${identifier(scope.workspace)}/local-runners/${identifier(key)}`;
+const auth = (scope, signal) => ({ actor: scope.owner, workspace: scope.workspace, signal });
+async function runnerReceipt(scope, key, options, suffix = '') {
+    const value = await api(pathFor(scope, key) + suffix, options);
+    if (!localRunnerLookupMatches(value, scope.owner, scope.workspace, key))
+        throw new CliError('runner_receipt_invalid', 'The runner response does not match this account, workspace and original device. No local work was started.');
+    return value;
+}
+const fileFor = async (scope, key) => join(await privateDirectory(), `runner-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}.json`);
+/**
+ * Private keys of session-only runners enrolled by this process. Runners are
+ * bound to one native session, and a session-only sign-in keeps nothing in the
+ * OS credential store, so its runner key lives here and is gone when the process
+ * exits. It is never written to disk, logged or sent; only its public key is
+ * enrolled. The runner then stops being usable with its session.
+ */
+const MEMORY_KEYS = new Map();
+async function store(scope, key) {
+    try {
+        const { Entry } = await import('@napi-rs/keyring');
+        return new Entry('run.firedrill.simulation.runner-key.v1', `${API_ORIGIN}/${identifier(scope.owner)}/${identifier(scope.workspace)}/${identifier(key)}`, process.platform === 'linux' ? { linux: { store: 'secret-service' } } : undefined);
+    }
+    catch {
+        throw new CliError('runner_key_store_unavailable', 'Unlock your OS credential store. Runner keys are never saved in project files.');
+    }
+}
+async function persist(value) {
+    const path = await fileFor(value, value.key);
+    const temporary = path + '.' + randomUUID() + '.tmp';
+    const file = await open(temporary, 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    try {
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+async function saved(scope, key) {
+    const path = await fileFor(scope, key);
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384 || (stat.mode & 0o077) !== 0
+        || process.getuid && stat.uid !== process.getuid())
+        throw new CliError('runner_journal_unsafe', 'Runner metadata must be private and owned by this OS user.');
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const actual = await file.stat();
+        if (actual.ino !== stat.ino || actual.dev !== stat.dev || actual.size !== stat.size)
+            throw new Error();
+        const value = JSON.parse(await file.readFile('utf8'));
+        if (value.schema !== 'firedrill.runner-identity.v1' || value.owner !== scope.owner || value.workspace !== scope.workspace
+            || value.key !== identifier(key) || value.enrollment?.schema !== 'firedrill.local-runner-enroll.v1'
+            || value.enrollment.device_key !== value.key || value.enrollment.actor_id !== scope.owner || value.enrollment.workspace_id !== scope.workspace
+            || !['enrollment_dispatched', 'enrolled', 'revoked'].includes(value.stage))
+            throw new Error();
+        identifier(value.enrollment.native_session_id);
+        return value;
+    }
+    catch {
+        throw new CliError('runner_journal_invalid', 'The runner journal could not be read safely. It was not replaced.');
+    }
+    finally {
+        await file.close();
+    }
+}
+async function lock(scope, key, signal, work) {
+    const directory = join(await privateDirectory(), `runner-lock-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}`);
+    return withBootstrapProcessLock(directory, signal, work);
+}
+async function proof(value, payload) {
+    try {
+        const encoded = MEMORY_KEYS.get(value.key) ?? (await store(value, value.key)).getPassword();
+        if (!encoded || encoded.length > 2048)
+            throw new Error();
+        const key = createPrivateKey({ key: Buffer.from(encoded, 'base64'), format: 'der', type: 'pkcs8' });
+        if (key.asymmetricKeyType !== 'ed25519')
+            throw new Error();
+        const publicKey = createPublicKey(key).export({ format: 'jwk' });
+        if (!publicKey.x || Buffer.from(publicKey.x, 'base64url').toString('base64') !== value.enrollment.public_key)
+            throw new Error();
+        return { payload, signature: sign(null, Buffer.from('firedrill.local-runner-proof.v1\n' + canonical(payload)), key).toString('base64') };
+    }
+    catch {
+        throw new CliError('runner_key_unavailable', 'This runner key could not be read from the OS credential store. It was not regenerated.');
+    }
+}
+export async function signRunnerRequest(scope, key, payload, signal) {
+    return (await runnerRequestSigner(scope, key, signal))(payload);
+}
+/** Closing facts only, under the same process lock as the live companion. */
+export async function withHistoricalRunCleanup(scope, key, signal, work, purpose = 'run') {
+    key = identifier(key);
+    return lock(scope, key, signal, async (active) => {
+        const value = await saved(scope, key);
+        const session = await api('/api/auth/native/session', auth(scope, active));
+        if (session.workspace?.can_write !== true || value.stage === 'revoked')
+            throw new CliError('runner_cleanup_unavailable', 'Sign in with current write access to this workspace. A revoked device cannot report new cleanup facts.');
+        const retained = await runnerReceipt(scope, key, auth(scope, active));
+        if (retained.state === 'revoked' || retained.state === 'not_retained')
+            throw new CliError('runner_cleanup_unavailable', 'The original non-revoked device is required. No new identity was enrolled.');
+        matches(value, retained);
+        const deviceId = deviceIdOf(retained);
+        if (!deviceId)
+            throw new CliError('runner_receipt_invalid', 'The original device identifier is unavailable.');
+        return work({ deviceId, signal: active, sign: async (payload) => {
+                active.throwIfAborted();
+                const allowed = purpose === 'run'
+                    ? payload.schema === 'firedrill.native-local-run-lifecycle.v1' && payload.device_id === deviceId
+                        && ['observe', 'close'].includes(String(payload.action))
+                    : payload.schema === 'firedrill.native-execution-cleanup.v1';
+                if (!allowed)
+                    throw new CliError('runner_cleanup_only', 'This signer accepts only the original run closing evidence.');
+                return proof(value, payload);
+            } });
+    });
+}
+/** Bounded caller-owned transfer session. Server checks current authority for
+ * EVERY signed operation; this removes repeated preflight GETs, not revocation.
+ * Only public enrollment metadata is captured, never a personal access token.
+ */
+export async function runnerRequestSigner(scope, key, signal) {
+    const value = await saved(scope, identifier(key));
+    const session = await api('/api/auth/native/session', auth(scope, signal));
+    if (session.id !== value.enrollment.native_session_id || value.stage === 'revoked') {
+        throw new CliError('runner_scope_changed', 'This runner belongs to another terminal session or was revoked.');
+    }
+    // Signing another scoped approval must not rewrite the live presence
+    // process's pending-pulse journal from this independently read snapshot.
+    const receipt = await runnerReceipt(scope, key, auth(scope, signal));
+    if (['not_retained', 'revoked', 'expired', 'access_removed'].includes(receipt.state)) {
+        throw new CliError('runner_access_removed', 'This runner identity is not currently available for approval.');
+    }
+    matches(value, receipt);
+    return async (payload) => { signal.throwIfAborted(); return proof(value, payload); };
+}
+/** Historical evidence/closing facts only, authenticated to the current account.
+ * An expired original device session cannot heartbeat, claim or obtain runtime
+ * inputs through this signer. Revoked devices retain only original cleanup
+ * signing, not private evidence publication. Server scope remains independently
+ * authoritative for every submitted proof.
+ */
+export async function historicalRunnerSigner(scope, key, signal) {
+    const value = await saved(scope, identifier(key));
+    const session = await api('/api/auth/native/session', auth(scope, signal));
+    const receipt = await runnerReceipt(scope, key, auth(scope, signal));
+    matches(value, receipt);
+    const cleanupOnly = receipt.state === 'revoked' || value.stage === 'revoked' || session.workspace?.can_write !== true;
+    return { nativeSession: session.id, cleanupOnly, sign: async (payload) => {
+            signal.throwIfAborted();
+            const document = payload.document;
+            if (cleanupOnly && (payload.schema !== 'firedrill.local-completion.v1'
+                || !['firedrill.local-container-receipt.v1', 'firedrill.local-trial-container-receipt.v1',
+                    'firedrill.local-world-container-receipt.v1'].includes(String(document?.schema)))) {
+                throw new CliError('runner_cleanup_only', 'Runner execution or write access ended. Only the exact saved cleanup receipt may be signed.');
+            }
+            if (!['firedrill.local-evidence-write.v1', 'firedrill.local-trial-evidence-write.v1', 'firedrill.local-completion.v1',
+                'firedrill.local-world-closing-command-result.v1', 'firedrill.local-world-closing-file-write.v1',
+                'firedrill.local-world-final-write.v1'].includes(String(payload.schema))
+                || payload.native_session_id !== session.id || payload.device_key !== key)
+                throw new CliError('historical_scope_invalid', 'Use the exact saved evidence or completion identity.');
+            return proof(value, payload);
+        } };
+}
+function matches(value, receipt) {
+    if (receipt.state === 'not_retained' || receipt.device_key !== value.key || receipt.enrollment_digest !== digest(value.enrollment)
+        || receipt.native_session_id !== value.enrollment.native_session_id)
+        throw new CliError('runner_identity_changed', 'The saved runner receipt does not match this device identity.');
+}
+async function reconcile(value, signal) {
+    const receipt = await runnerReceipt(value, value.key, auth(value, signal));
+    if (receipt.state === 'not_retained')
+        return receipt;
+    if (receipt.state === 'revoked') {
+        value.stage = 'revoked';
+        value.pending = null;
+        await persist(value);
+        return receipt;
+    }
+    matches(value, receipt);
+    if (value.stage === 'enrollment_dispatched') {
+        value.stage = 'enrolled';
+        await persist(value);
+    }
+    return receipt;
+}
+function describe(receipt) {
+    return receipt.state === 'not_retained'
+        ? `Runner ${receipt.device_key}: no retained receipt yet. A delayed enrollment may still arrive. Revoke this exact key to withdraw it.`
+        : `Runner ${receipt.device_key}: ${receipt.state.replaceAll('_', ' ')}.\nEnrollment and presence do not grant execution permission.`;
+}
+export async function enrollLocalRunner(scope, options, output) {
+    if (!['darwin', 'linux'].includes(process.platform) || !['arm64', 'x64'].includes(process.arch)) {
+        throw new CliError('runner_host_unsupported', 'Local runner enrollment currently supports macOS or Linux on arm64 or x64.');
+    }
+    if (!options.enroll) {
+        if (options.json || !process.stdin.isTTY || !process.stderr.isTTY)
+            throw new CliError('runner_consent_required', 'Pass --enroll-device to register this local runner identity. No execution is authorized by enrollment.', 2);
+        const approved = await selectOne('Register this local runner?', [{ value: true, label: 'Register', detail: options.ephemeral
+                    ? 'Share its name and OS/architecture. Its private key stays in this process\'s memory and is discarded when this run ends.'
+                    : 'Share its name and OS/architecture. The private device key stays in the OS credential store.' },
+            { value: false, label: 'Cancel' }], options.signal);
+        if (!approved)
+            throw new CliError('canceled', 'No runner was enrolled.', 130);
+    }
+    const session = await api('/api/auth/native/session', auth(scope, options.signal));
+    const label = options.name ?? 'Local runner';
+    if (!/^[\x20-\x7e]{1,80}$/.test(label) || label !== label.trim())
+        throw new CliError('runner_name_invalid', 'Use a runner name of 1 to 80 plain characters.', 2);
+    const key = randomUUID();
+    const pair = generateKeyPairSync('ed25519');
+    const publicKey = pair.publicKey.export({ format: 'jwk' });
+    if (!publicKey.x)
+        throw new CliError('runner_key_unavailable', 'A runner identity could not be created.');
+    const value = { schema: 'firedrill.runner-identity.v1', ...scope, key, stage: 'enrollment_dispatched', pending: null,
+        enrollment: { schema: 'firedrill.local-runner-enroll.v1', device_key: key, actor_id: scope.owner,
+            workspace_id: scope.workspace, native_session_id: identifier(session.id), public_key: Buffer.from(publicKey.x, 'base64url').toString('base64'),
+            label, host: { os: process.platform, arch: process.arch } } };
+    if (options.ephemeral)
+        MEMORY_KEYS.set(key, pair.privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64'));
+    else
+        try {
+            const entry = await store(scope, key);
+            if (entry.getPassword() !== null)
+                throw new Error();
+            const encoded = pair.privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64');
+            entry.setPassword(encoded);
+            if (entry.getPassword() !== encoded)
+                throw new Error();
+        }
+        catch {
+            throw new CliError('runner_key_store_unavailable', 'The runner key was not confirmed in the OS credential store. No enrollment was sent.');
+        }
+    await persist(value);
+    output('runner_request', { device_key: key }, `Runner request ${key}. Recover with firedrill runner status ${key}.`);
+    return lock(scope, key, options.signal, async (active) => {
+        options = { ...options, signal: active };
+        try {
+            const receipt = await runnerReceipt(scope, key, { ...auth(scope, options.signal), method: 'PUT', body: await proof(value, value.enrollment) });
+            matches(value, receipt);
+            value.stage = 'enrolled';
+            await persist(value);
+            output('runner_enrolled', receipt, describe(receipt));
+            return receipt;
+        }
+        catch (error) {
+            if (error instanceof CliError && ['connection_uncertain', 'response_unavailable'].includes(error.code)) {
+                const receipt = await reconcile(value, options.signal);
+                output('runner_receipt', receipt, describe(receipt));
+                return receipt;
+            }
+            throw error;
+        }
+    });
+}
+export async function localRunnerSelectionPage(scope, page, signal) {
+    if (!Number.isSafeInteger(page) || page < 1 || page > 100000000)
+        throw new CliError('query_invalid', 'Choose a positive runner page.', 2);
+    const session = await api('/api/auth/native/session', auth(scope, signal));
+    const directory = await api(`/api/workspaces/${identifier(scope.workspace)}/local-runners?page=${page}&q=`, auth(scope, signal));
+    if (!localRunnersMatch(directory, scope.owner, scope.workspace, '', page))
+        throw new CliError('runner_receipt_invalid', 'The runner directory did not match this account, workspace and page.');
+    return { directory, candidates: directory.results.filter(row => row.native_session_id === session.id
+            && !['revoked', 'expired', 'access_removed'].includes(row.state)
+            && row.host.os === process.platform && row.host.arch === process.arch) };
+}
+export async function currentLocalRunner(scope, key, signal) {
+    let value;
+    try {
+        value = await saved(scope, identifier(key));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new CliError('runner_identity_not_local', 'This runner has no private identity in this OS account. Choose this device’s original runner or register this device after review. No key was regenerated.', 2);
+        throw error;
+    }
+    const session = await api('/api/auth/native/session', auth(scope, signal));
+    if (value.stage === 'revoked' || value.enrollment.native_session_id !== session.id
+        || value.enrollment.host.os !== process.platform || value.enrollment.host.arch !== process.arch) {
+        throw new CliError('runner_scope_changed', 'Choose the original runner for this terminal session and device. No new identity was enrolled.');
+    }
+    const receipt = await runnerReceipt(scope, key, auth(scope, signal));
+    matches(value, receipt);
+    if (['revoked', 'expired', 'access_removed'].includes(receipt.state))
+        throw new CliError('runner_access_removed', 'This runner is no longer eligible for a new local permission.');
+    return receipt;
+}
+async function pendingPulse(value, signal) {
+    while (true) {
+        const receipt = await reconcile(value, signal);
+        if (['not_retained', 'revoked', 'expired', 'access_removed'].includes(receipt.state))
+            throw new CliError('runner_access_removed', 'Runner access ended. No local work was started.');
+        matches(value, receipt);
+        if (!value.pending)
+            return receipt;
+        const pending = value.pending.payload;
+        if (pending.schema !== 'firedrill.local-runner-presence.v1' || pending.device_key !== value.key
+            || pending.native_session_id !== value.enrollment.native_session_id || !Number.isSafeInteger(pending.sequence)
+            || !Number.isSafeInteger(pending.sent_at_ms))
+            throw new CliError('runner_journal_invalid', 'The pending runner record is invalid. It was not replayed.');
+        if (receipt.last_sequence === pending.sequence && receipt.last_pulse_digest === digest(pending)) {
+            value.pending = null;
+            await persist(value);
+            return receipt;
+        }
+        if (receipt.last_sequence !== pending.sequence - 1)
+            throw new CliError('runner_sequence_conflict', 'Runner presence changed in another process. Inspect the exact saved runner.');
+        const remaining = pending.sent_at_ms + 60000 - Date.parse(receipt.server_time);
+        if (!Number.isFinite(remaining))
+            throw new CliError('runner_receipt_invalid', 'The runner receipt is incomplete.');
+        if (remaining <= 0) {
+            // An older delayed record now fails its server expiry check. Only then
+            // may the same next sequence carry a new record; no uncertain pulse replay.
+            value.pending = null;
+            await persist(value);
+            return receipt;
+        }
+        await sleep(Math.min(remaining + 100, 20000), undefined, { signal });
+    }
+}
+async function pulse(value, state, signal) {
+    const previous = await pendingPulse(value, signal);
+    if (!Number.isSafeInteger(previous.last_sequence) || previous.last_sequence < 0 || previous.last_sequence >= Number.MAX_SAFE_INTEGER) {
+        throw new CliError('runner_receipt_invalid', 'The runner sequence is unavailable.');
+    }
+    const sentAt = Date.parse(previous.server_time);
+    if (!Number.isSafeInteger(sentAt))
+        throw new CliError('runner_receipt_invalid', 'The runner service time is unavailable.');
+    const pending = await proof(value, { schema: 'firedrill.local-runner-presence.v1', device_key: value.key,
+        native_session_id: value.enrollment.native_session_id, sequence: previous.last_sequence + 1, sent_at_ms: sentAt, state });
+    value.pending = pending;
+    await persist(value); // Before dispatch; response loss never becomes a fresh pulse.
+    const receipt = await runnerReceipt(value, value.key, { ...auth(value, signal), method: 'POST', body: pending }, '/presence');
+    matches(value, receipt);
+    if (receipt.last_sequence !== pending.payload.sequence || receipt.last_pulse_digest !== digest(pending.payload)) {
+        throw new CliError('runner_receipt_invalid', 'The runner presence response did not match its request.');
+    }
+    value.pending = null;
+    await persist(value);
+    return receipt;
+}
+/** One foreground owner maintains device presence while its approved work runs.
+ * This issues no execution grant, chooses no job and never steals a live lock.
+ */
+export async function withRunnerPresence(scope, key, signal, output, work) {
+    key = identifier(key);
+    return lock(scope, key, signal, async (active, ownership) => {
+        signal = active;
+        const value = await saved(scope, key);
+        const session = await api('/api/auth/native/session', auth(scope, signal));
+        if (session.id !== value.enrollment.native_session_id || value.stage === 'revoked') {
+            throw new CliError('runner_scope_changed', 'This runner belongs to another terminal session or was revoked.');
+        }
+        await pulse(value, 'idle', signal);
+        const stop = new AbortController(), combined = AbortSignal.any([signal, stop.signal]);
+        let failure;
+        const keeping = (async () => {
+            while (!combined.aborted) {
+                await sleep(20000, undefined, { signal: combined });
+                await pulse(value, 'idle', combined);
+            }
+        })().catch(error => { if (!combined.aborted) {
+            failure = error;
+            stop.abort();
+        } });
+        try {
+            const result = await work(combined);
+            if (failure)
+                throw failure;
+            signal.throwIfAborted();
+            return result;
+        }
+        catch (error) {
+            throw failure ?? error;
+        }
+        finally {
+            stop.abort();
+            await keeping;
+            if (!value.pending) {
+                try {
+                    await pulse(value, 'stopped', AbortSignal.any([AbortSignal.timeout(8000), ownership]));
+                }
+                catch {
+                    output('runner_disconnect_pending', { device_key: key }, 'Disconnect is not confirmed. The saved presence lease will expire.');
+                }
+            }
+            else
+                output('runner_disconnect_pending', { device_key: key }, 'A presence response is unresolved. The exact journal is retained.');
+        }
+    });
+}
+/**
+ * Root's server id for this device (`LocalRunnerDevice.id`, distinct from the
+ * client `device_key`), which native executor routes are keyed on. Null when
+ * the receipt does not carry one (`not_retained`, or an older service).
+ */
+function deviceIdOf(receipt) {
+    const value = receipt.device_id;
+    return typeof value === 'string' && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value) ? value : null;
+}
+/** Closing work already owned by this device is allowed during graceful stop. */
+function shutdownProof(payload) {
+    switch (payload.schema) {
+        case 'firedrill.native-control.v1':
+            return payload.action === 'cancel' || payload.action === 'heartbeat';
+        case 'firedrill.native-target-control.v1':
+            return payload.action === 'complete' || payload.action === 'abandon';
+        case 'firedrill.native-local-run-lifecycle.v1':
+            return payload.action === 'observe' || payload.action === 'close';
+        case 'firedrill.native-execution-stop.v1':
+        case 'firedrill.native-execution-close.v1':
+        case 'firedrill.native-execution-cleanup.v1':
+        case 'firedrill.native-artifact.v1':
+        case 'firedrill.native-artifact-commit.v1':
+            return true;
+        case undefined:
+            // ObservationBatch has a numeric version rather than a schema field.
+            return payload.version === 1 && typeof payload.assignment_id === 'string'
+                && typeof payload.attempt_id === 'string' && typeof payload.batch_id === 'string'
+                && typeof payload.previous_ack === 'number' && Array.isArray(payload.events);
+        default:
+            return false;
+    }
+}
+/**
+ * The enrolled runner device as a native executor (Plan20). One process owns
+ * the device's presence (process lock and pending-pulse journal unchanged) and
+ * signs its executor requests with the OS-stored device key. Pulses are
+ * serialized. `device_id` comes from the retained runner receipt; a later
+ * receipt naming a different id ends the executor.
+ */
+export async function withNativeExecutor(scope, key, signal, work) {
+    key = identifier(key);
+    return lock(scope, key, signal, async (active, ownership) => {
+        const value = await saved(scope, key);
+        const session = await api('/api/auth/native/session', auth(scope, active));
+        if (session.id !== value.enrollment.native_session_id || value.stage === 'revoked'
+            || value.enrollment.host.os !== process.platform || value.enrollment.host.arch !== process.arch) {
+            throw new CliError('runner_scope_changed', 'Choose the original runner for this terminal session and device. No new identity was enrolled.');
+        }
+        const retained = await runnerReceipt(scope, key, auth(scope, active));
+        // Eligibility first: a revoked receipt carries no enrollment digest, so it would read as an identity change.
+        if (['not_retained', 'revoked', 'expired', 'access_removed'].includes(retained.state)) {
+            throw new CliError('runner_access_removed', 'This runner is no longer eligible to execute. No drill was started.');
+        }
+        matches(value, retained);
+        const deviceId = deviceIdOf(retained);
+        let chain = Promise.resolve();
+        const executor = {
+            device_key: key,
+            device_id: deviceId,
+            sign: async (payload, requestSignal) => {
+                requestSignal.throwIfAborted();
+                ownership.throwIfAborted();
+                // Ctrl+C stops new work immediately. The companion's own bounded
+                // shutdown signal still controls signatures needed to attest cleanup.
+                if (!shutdownProof(payload))
+                    active.throwIfAborted();
+                return proof(value, payload);
+            },
+            pulse: (state, requestSignal) => {
+                const next = chain.catch(() => undefined).then(async () => {
+                    const receipt = await pulse(value, state, AbortSignal.any([state === 'idle' ? active : ownership, requestSignal]));
+                    const reported = deviceIdOf(receipt);
+                    if (deviceId !== null && reported !== null && reported !== deviceId) {
+                        throw new CliError('runner_scope_changed', 'The runner device identity changed. This executor stops; no new identity was enrolled.');
+                    }
+                    return { state: receipt.state };
+                });
+                chain = next;
+                return next;
+            },
+        };
+        return work(executor);
+    });
+}
+/**
+ * Pick this terminal session's runner device for native execution: the given
+ * key, else the only runner of this session and platform with a private
+ * identity on this machine. Enrollment stays an explicit, consented step.
+ */
+export async function nativeExecutorKey(scope, requested, signal) {
+    if (requested !== undefined)
+        return (await currentLocalRunner(scope, identifier(requested), signal)).device_key;
+    const usable = [];
+    for (let page = 1; page <= 5; page++) {
+        const { directory, candidates } = await localRunnerSelectionPage(scope, page, signal);
+        for (const candidate of candidates) {
+            try {
+                usable.push((await currentLocalRunner(scope, candidate.device_key, signal)).device_key);
+            }
+            catch (error) {
+                if (!(error instanceof CliError) || !['runner_identity_not_local', 'runner_scope_changed', 'runner_access_removed'].includes(error.code))
+                    throw error;
+            }
+        }
+        if (page * directory.page_size >= directory.count)
+            break;
+    }
+    if (usable.length === 1)
+        return usable[0];
+    if (usable.length === 0)
+        throw new CliError('runner_required', 'Register this device first with firedrill runner enroll, then run again. No drill was started.', 2);
+    throw new CliError('runner_ambiguous', 'Several runner devices are registered for this terminal session. Choose one with --runner <device-key>. No drill was started.', 2);
+}
+export async function runnerCommand(action, key, options, output) {
+    const scope = await selectedWorkspace({ workspace: options.workspace, interactive: !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY,
+        openBrowser: options.openBrowser, signal: options.signal });
+    if (action === 'enroll')
+        return enrollLocalRunner(scope, options, output);
+    if (action === 'list') {
+        const page = options.page ?? '1';
+        if (!/^[1-9][0-9]{0,8}$/.test(page) || (options.search?.length ?? 0) > 200)
+            throw new CliError('query_invalid', 'Choose a positive page number and shorter search.', 2);
+        const result = await api(`/api/workspaces/${scope.workspace}/local-runners?page=${page}&q=${encodeURIComponent(options.search ?? '')}`, auth(scope, options.signal));
+        if (!localRunnersMatch(result, scope.owner, scope.workspace, options.search ?? '', Number(page)))
+            throw new CliError('runner_receipt_invalid', 'The runner history does not match this account, workspace or selected page.');
+        output('runner_list', result, result.results.map(item => `${item.device_key}  ${item.label}  ${item.state}`).join('\n') || 'No registered local runners.');
+        return;
+    }
+    if (!key)
+        throw new CliError('runner_key_required', 'Choose the exact runner key from firedrill runner list.', 2);
+    key = identifier(key);
+    if (action === 'revoke') {
+        output('runner_revocation_notice', { device_key: key }, 'Revocation prevents new native cleanup reports from this device. Finish cleanup before revoking when safe; security revocation proceeds immediately and does not stop local processes.');
+        // Authenticated revocation works even if the local private key/journal was lost.
+        const receipt = await runnerReceipt(scope, key, { ...auth(scope, options.signal), method: 'DELETE' });
+        if (receipt.device_key !== key || receipt.state !== 'revoked')
+            throw new CliError('runner_receipt_invalid', 'Runner revocation was not confirmed. Inspect its saved receipt.');
+        // Revocation is an immediate server-side authority fence, not proof that a
+        // claimed host container is absent. Preserve the original OS-stored key
+        // and journals for historical records; their retention does not authorize
+        // native cleanup submissions after revocation.
+        // Remote revocation also remains possible without this host's key/journal.
+        output('runner_revoked', receipt, describe(receipt) + '\nThe saved key and journals are retained, but this revoked device cannot submit new native cleanup reports. Revocation does not prove that local processes stopped.');
+        return;
+    }
+    if (action === 'status') {
+        const receipt = await runnerReceipt(scope, key, auth(scope, options.signal));
+        output('runner_receipt', receipt, describe(receipt));
+        return;
+    }
+    return lock(scope, key, options.signal, async (active, ownership) => {
+        options = { ...options, signal: active };
+        const value = await saved(scope, key);
+        const session = await api('/api/auth/native/session', auth(scope, options.signal));
+        if (session.id !== value.enrollment.native_session_id || value.stage === 'revoked') {
+            throw new CliError('runner_scope_changed', 'This runner belongs to another terminal session or was revoked. Enroll a new identity.');
+        }
+        const receipt = await pulse(value, 'idle', options.signal);
+        output('runner_connected', receipt, 'Runner presence connected. No execution permission has been granted. Press Ctrl+C to disconnect.');
+        try {
+            while (!options.signal.aborted) {
+                await sleep(20000, undefined, { signal: options.signal });
+                await pulse(value, 'idle', options.signal);
+            }
+        }
+        catch (error) {
+            if (!options.signal.aborted)
+                throw error;
+        }
+        finally {
+            // Never wait on/replay an uncertain pulse while shutting down. Its short
+            // server presence lease expires; the journal remains for reconciliation.
+            if (!value.pending) {
+                const stop = new AbortController();
+                const timer = setTimeout(() => stop.abort(), 8000);
+                try {
+                    output('runner_disconnected', await pulse(value, 'stopped', AbortSignal.any([stop.signal, ownership])), 'Runner presence disconnected.');
+                }
+                catch {
+                    output('runner_disconnect_pending', { device_key: value.key }, 'Disconnect was not confirmed. The presence lease expires; inspect this runner before reconnecting.');
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            else
+                output('runner_disconnect_pending', { device_key: value.key }, 'A presence response is unresolved. Its lease expires; the exact journal is retained for reconnection.');
+        }
+    });
+}