firedrill-run 2.2.5 → 3.0.1

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

@@ -0,0 +1,199 @@
+/** Historical run closing evidence. Never launches, signals or guesses process exit. */
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { api } from '../auth.js';
+import { privateDirectory } from '../credentials.js';
+import { CliError } from '../http.js';
+import { withHistoricalRunCleanup } from '../runner-identity.js';
+import { selectedWorkspace } from '../world-access.js';
+import { identifier } from '../world-contracts.js';
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+const fail = (message) => { throw new CliError('native_run_cleanup_unconfirmed', message); };
+function services(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 128)
+        return fail('The retained service snapshot is invalid. It was not replaced.');
+    const aliases = new Set(), launches = new Set();
+    for (const item of value) {
+        if (!record(item) || typeof item.service !== 'string' || !/^[a-z][a-z0-9_-]{0,63}$/.test(item.service)
+            || typeof item.launch_id !== 'string' || !UUID.test(item.launch_id)
+            || aliases.has(item.service) || launches.has(item.launch_id)
+            || !['planned', 'running', 'unknown', 'not_started', 'reaped'].includes(item.state)
+            || (item.state === 'reaped' ? !Number.isInteger(item.exit_code) || item.exit_code < -255 || item.exit_code > 255 : item.exit_code !== null))
+            return fail('The retained service snapshot is invalid. It was not replaced.');
+        aliases.add(item.service);
+        launches.add(item.launch_id);
+    }
+    return value;
+}
+async function readPrivate(path) {
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!info.isFile() || info.isSymbolicLink() || info.size > 262144 || (info.mode & 0o077)
+        || process.getuid && info.uid !== process.getuid())
+        return fail('The cleanup journal is not a bounded private file. Nothing was submitted.');
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const current = await file.stat();
+        if (current.ino !== info.ino || current.dev !== info.dev || current.size !== info.size)
+            return fail('The cleanup journal changed while reading.');
+        const value = record(JSON.parse(await file.readFile('utf8')));
+        if (!value)
+            return fail('The cleanup journal is invalid.');
+        return value;
+    }
+    finally {
+        await file.close();
+    }
+}
+async function persist(path, value) {
+    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();
+    }
+    await rename(temporary, path);
+}
+function sameServices(left, right) {
+    return left.length === right.length && left.every(one => right.some(other => one.service === other.service
+        && one.launch_id === other.launch_id && one.state === other.state && one.exit_code === other.exit_code));
+}
+export async function runCleanupCommand(deviceKey, campaignId, options, emit) {
+    deviceKey = identifier(deviceKey);
+    campaignId = identifier(campaignId);
+    const scope = await selectedWorkspace({ workspace: options.workspace, interactive: !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY,
+        openBrowser: options.openBrowser, signal: options.signal });
+    await withHistoricalRunCleanup(scope, deviceKey, options.signal, async (identity) => {
+        const directory = await privateDirectory();
+        const intentPath = join(directory, `native-run-cleanup-${scope.owner}-${scope.workspace}-${deviceKey}-${campaignId}.json`);
+        const path = `/api/workspaces/${scope.workspace}/native-executors/${identity.deviceId}/campaigns/${campaignId}/run/cleanup`;
+        const auth = { actor: scope.owner, workspace: scope.workspace, signal: identity.signal };
+        const decode = (value) => {
+            const row = record(value);
+            if (!row || typeof row.run_id !== 'string' || !UUID.test(row.run_id) || row.campaign_id !== campaignId
+                || row.device_id !== identity.deviceId || typeof row.descriptor_digest !== 'string' || !/^[a-f0-9]{64}$/.test(row.descriptor_digest)
+                || !Number.isSafeInteger(row.sequence) || Number(row.sequence) < 1 || !['active', 'uncertain', 'closed'].includes(String(row.state))
+                || (row.state === 'closed' ? typeof row.closed_at !== 'string' || !Number.isFinite(Date.parse(row.closed_at)) : row.closed_at !== null)
+                || row.process_provenance !== 'customer_device' || row.cloud_cleanup_complete !== false)
+                return fail('The cleanup response does not match the original run. Keep its journal.');
+            return { ...row, services: services(row.services) };
+        };
+        let current = decode(await api(path, auth));
+        const nextSequence = () => {
+            if (current.sequence >= Number.MAX_SAFE_INTEGER)
+                return fail('The original run sequence is exhausted. No replacement identity or event was created.');
+            return current.sequence + 1;
+        };
+        emit('native_run_cleanup_status', current, `Local run ${current.run_id}: ${current.state}. Cleanup does not start execution or prove cloud cleanup.`);
+        if (!options.approve) {
+            emit('native_run_cleanup_review', { campaign_id: campaignId, device_key: deviceKey }, `To recover saved closing evidence: firedrill runner run-cleanup ${deviceKey} ${campaignId} --approve-change. No process is stopped by this command.`);
+            return;
+        }
+        const send = async (document, sourcePending = false) => {
+            const body = record(document.payload);
+            if (!body || body.schema !== 'firedrill.native-local-run-lifecycle.v1' || body.device_id !== identity.deviceId
+                || body.campaign_id !== campaignId || body.run_id !== current.run_id || body.descriptor_digest !== current.descriptor_digest
+                || !['observe', 'close'].includes(String(body.action)) || typeof body.request_key !== 'string' || !UUID.test(body.request_key)
+                || !Number.isSafeInteger(body.sequence) || Number(body.sequence) < 1 || typeof document.signature !== 'string'
+                || document.signature.length !== 88)
+                return fail('The original cleanup intent has a different scope. It was not submitted.');
+            const snapshot = services(body.services);
+            if (snapshot.length !== current.services.length || snapshot.some(one => !current.services.some(other => one.service === other.service && one.launch_id === other.launch_id)))
+                return fail('The original cleanup intent names different launches.');
+            await persist(intentPath, { schema: 'firedrill.run-cleanup-intent.v1', actor_id: scope.owner, workspace_id: scope.workspace,
+                device_key: deviceKey, campaign_id: campaignId, document, source_pending: sourcePending });
+            let result;
+            try {
+                result = decode(await api(path, { ...auth, method: 'POST', body: document }));
+            }
+            catch (error) {
+                // A historical running observation may not have reached the normal
+                // endpoint. The cleanup endpoint definitively refuses that new event;
+                // keep the original companion journal, but do not trap cleanup on it.
+                if (sourcePending && error instanceof CliError && error.httpStatus === 409 && error.code === 'native_local_run_cleanup_only') {
+                    await unlink(intentPath);
+                    return current;
+                }
+                emit('native_run_cleanup_pending', { campaign_id: campaignId, device_key: deviceKey }, 'Closing evidence is not confirmed. Its exact signed intent is retained; rerun this same cleanup command. No replacement request was sent.');
+                throw error;
+            }
+            if (result.run_id !== current.run_id || result.sequence !== body.sequence || !sameServices(result.services, snapshot)
+                || body.action === 'close' && result.state !== 'closed')
+                return fail('The cleanup receipt did not confirm the exact original event. Keep its journal.');
+            await unlink(intentPath);
+            return result;
+        };
+        const retained = await readPrivate(intentPath);
+        if (retained) {
+            if (retained.schema !== 'firedrill.run-cleanup-intent.v1' || retained.actor_id !== scope.owner || retained.workspace_id !== scope.workspace
+                || retained.device_key !== deviceKey || retained.campaign_id !== campaignId || !record(retained.document))
+                return fail('The saved cleanup intent belongs to another scope.');
+            await send(retained.document, retained.source_pending === true);
+            current = decode(await api(path, auth));
+        }
+        if (current.state !== 'closed') {
+            const local = await readPrivate(join(directory, `native-local-run-${campaignId}-${deviceKey}.json`))
+                ?? await readPrivate(join(directory, `native-local-run-${campaignId}.json`));
+            if (local && local.schema === 'firedrill.native-local-run-state.v1' && local.run_id === current.run_id
+                && local.campaign_id === campaignId && local.descriptor_sha256 === current.descriptor_digest) {
+                const pending = record(local.pending);
+                if (pending && ['observe', 'close'].includes(String(pending.action))) {
+                    const payload = { schema: 'firedrill.native-local-run-lifecycle.v1', campaign_id: campaignId,
+                        device_id: identity.deviceId, descriptor_digest: current.descriptor_digest, ...pending };
+                    await send(await identity.sign(payload), true);
+                    current = decode(await api(path, auth));
+                }
+                if (current.state !== 'closed' && local.observed !== undefined && local.observed !== null) {
+                    const observed = services(local.observed);
+                    if (observed.length !== current.services.length || observed.some(one => !current.services.some(other => one.service === other.service && one.launch_id === other.launch_id)))
+                        return fail('The saved exit observations name different launches.');
+                    const snapshot = current.services.map(prior => {
+                        if (prior.state === 'reaped' || prior.state === 'not_started')
+                            return prior;
+                        const actual = observed.find(one => one.service === prior.service);
+                        if (actual.state === 'reaped')
+                            return actual;
+                        if (actual.state === 'not_started' && prior.state === 'planned')
+                            return actual;
+                        return { ...prior, state: 'unknown', exit_code: null };
+                    });
+                    if (!sameServices(snapshot, current.services)) {
+                        const event = { run_id: current.run_id, request_key: randomUUID(), sequence: nextSequence(),
+                            action: 'observe', services: snapshot };
+                        current = await send(await identity.sign({ schema: 'firedrill.native-local-run-lifecycle.v1', campaign_id: campaignId,
+                            device_id: identity.deviceId, descriptor_digest: current.descriptor_digest, ...event }));
+                    }
+                }
+            }
+        }
+        if (current.state === 'closed') {
+            emit('native_run_cleanup_closed', current, 'The original local run is closed. Cloud cleanup and accounting remain separate.');
+            return;
+        }
+        const snapshot = current.services.map(one => one.state === 'running' || one.state === 'planned'
+            ? { ...one, state: 'unknown', exit_code: null } : one);
+        const closed = snapshot.every(one => one.state === 'reaped' || one.state === 'not_started');
+        if (closed || !sameServices(snapshot, current.services)) {
+            const event = { run_id: current.run_id, request_key: randomUUID(), sequence: nextSequence(),
+                action: closed ? 'close' : 'observe', services: snapshot };
+            current = await send(await identity.sign({ schema: 'firedrill.native-local-run-lifecycle.v1', campaign_id: campaignId,
+                device_id: identity.deviceId, descriptor_digest: current.descriptor_digest, ...event }));
+        }
+        if (!closed)
+            throw new CliError('native_local_run_uncertain', 'Process termination remains unknown. This command does not guess PIDs or manufacture exit evidence. Keep the original run records; campaign completion remains blocked until truthful closing evidence is available.');
+        emit('native_run_cleanup_closed', current, 'The original local run is closed. Cloud cleanup and accounting remain separate.');
+    });
+}

package/dist/cli/src/native/scratch.js

@@ -0,0 +1,117 @@
+/**
+ * Run-scoped private scratch (Plan20 W09, spec 3.5).
+ *
+ * One private directory per companion run under the OS temporary directory
+ * (mkdtemp, 0700, owned by the current user), with one private subdirectory per
+ * drill. Scratch holds only run-scoped material (driver files, MCP client
+ * configuration, bounded captures); it is not an evidence journal and is removed
+ * when the drill or run ends. A synchronous removal is registered for process
+ * exit so a crash path that still reaches `exit` does not leave it behind.
+ *
+ * On Windows POSIX modes are not enforced by the OS; `permissions` reports
+ * `platform-default` so callers can disclose that limitation.
+ */
+import { rmSync } from 'node:fs';
+import { chmod, lstat, mkdir, mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CliError } from '../http.js';
+import { NATIVE_ID } from './contracts.js';
+const POSIX = process.platform !== 'win32';
+function refused() {
+    return new CliError('native_scratch_unavailable', 'The private scratch directory could not be created safely. Nothing was started.');
+}
+function checkPrivateDirectory(stats) {
+    if (!stats.isDirectory() || stats.isSymbolicLink())
+        throw refused();
+    if (POSIX) {
+        if (typeof process.getuid === 'function' && stats.uid !== process.getuid())
+            throw refused();
+        if ((stats.mode & 0o077) !== 0)
+            throw refused();
+    }
+}
+export async function createRunScratch() {
+    let created;
+    try {
+        // realpath first so the directory path is stable (e.g. macOS /var -> /private/var).
+        const base = await realpath(tmpdir());
+        created = await mkdtemp(join(base, 'firedrill-native-'));
+        if (POSIX)
+            await chmod(created, 0o700);
+        checkPrivateDirectory(await lstat(created));
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw refused();
+    }
+    const root = created;
+    let removed = false;
+    const drills = new Map();
+    const onExit = () => { if (!removed) {
+        try {
+            rmSync(root, { recursive: true, force: true });
+        }
+        catch { /* best effort at exit */ }
+    } };
+    process.once('exit', onExit);
+    const cleanup = async () => {
+        if (removed)
+            return;
+        removed = true;
+        process.removeListener('exit', onExit);
+        drills.clear();
+        await rm(root, { recursive: true, force: true, maxRetries: 3 }).catch(() => undefined);
+    };
+    return {
+        path: root,
+        permissions: POSIX ? 'posix-0700' : 'platform-default',
+        async drill(key) {
+            if (removed)
+                throw refused();
+            if (typeof key !== 'string' || !NATIVE_ID.test(key)) {
+                throw new CliError('native_scratch_unavailable', 'The drill scratch directory was not created: its key is malformed.');
+            }
+            if (drills.has(key))
+                throw new CliError('native_scratch_unavailable', 'The drill scratch directory was not created: it already exists for this run.');
+            const path = join(root, key);
+            try {
+                await mkdir(path, { mode: 0o700 });
+                if (POSIX)
+                    await chmod(path, 0o700);
+                checkPrivateDirectory(await lstat(path));
+            }
+            catch (error) {
+                await rm(path, { recursive: true, force: true }).catch(() => undefined);
+                if (error instanceof CliError)
+                    throw error;
+                throw refused();
+            }
+            let drillRemoved = false;
+            const entry = {
+                path,
+                async cleanup() {
+                    if (drillRemoved)
+                        return;
+                    drillRemoved = true;
+                    drills.delete(key);
+                    await rm(path, { recursive: true, force: true, maxRetries: 3 }).catch(() => undefined);
+                },
+            };
+            drills.set(key, entry);
+            return entry;
+        },
+        cleanup,
+    };
+}
+/** Run `work` with a fresh run scratch that is always removed afterwards. */
+export async function withRunScratch(work) {
+    const scratch = await createRunScratch();
+    try {
+        return await work(scratch);
+    }
+    finally {
+        await scratch.cleanup();
+    }
+}

package/dist/cli/src/native/screenshots.js

@@ -0,0 +1,60 @@
+/**
+ * Approved screenshot capture for the browser driver (Plan20 W12, root
+ * `client-masked-png-v1`, 2026-11-10).
+ *
+ * Screenshots are off unless the approved local plan turns them on for the
+ * `playwright.v1` driver (`screenshots`). When on, every capture masks the
+ * policy's elements before the image is taken: form fields always, plus the
+ * selectors the human approved. The policy's digest is part of the plan the
+ * human approved and goes to root with each image. Masking covers only those
+ * elements in the page's main frame; any other text on screen is uploaded as
+ * shown. Nothing here detects secrets in pixels, and root does not either.
+ *
+ * `frames` (optional, 2026-11-10) adds masked frames while each step runs: one
+ * every `interval_ms` (1 to 10 seconds), at most `max_per_step` (1 to 30) per
+ * step, plus the screenshot after the step. These are captured frames, not a
+ * video: nothing between two frames is recorded.
+ */
+import { canonicalJson, sha256Hex } from './canonical.js';
+export const MASKING_POLICY_SCHEMA = 'firedrill.screenshot-masking.v1';
+/** Always masked: every form field and editable region, whatever the plan adds. */
+export const BASE_MASK_SELECTORS = Object.freeze([
+    'input', 'textarea', 'select', '[contenteditable]:not([contenteditable="false"])',
+]);
+export const MASK_COLOR = '#000000';
+export const MAX_MASK_SELECTORS = 64;
+export const MASK_SELECTOR_MAX_CHARS = 256;
+/** The effective policy (base selectors first, then the plan's, without repeats) and its digest. */
+export function maskingPolicy(plan) {
+    const selectors = [];
+    for (const selector of [...BASE_MASK_SELECTORS, ...plan.mask_selectors])
+        if (!selectors.includes(selector))
+            selectors.push(selector);
+    const policy = { schema: MASKING_POLICY_SCHEMA, selectors, mask_color: MASK_COLOR };
+    return { policy, sha256: sha256Hex(canonicalJson(policy)) };
+}
+/** Plain words for the approval screen: what is masked and what is not. */
+export function describeScreenshots(plan) {
+    if (!plan)
+        return 'no screenshots are captured';
+    const extra = plan.mask_selectors.length ? `, plus ${plan.mask_selectors.map((item) => JSON.stringify(item)).join(', ')}` : '';
+    const frames = plan.frames
+        ? `, and while each step runs it also captures up to ${plan.frames.max_per_step} masked frame${plan.frames.max_per_step === 1 ? '' : 's'}, `
+            + `one every ${seconds(plan.frames.interval_ms)} (captured frames, not a video: nothing between frames is recorded)`
+        : '';
+    return `captures a PNG screenshot of the visible page after each step${frames} and uploads them as evidence. Before each capture it `
+        + `blacks out every form field and editable region${extra}. Anything else on screen, including text outside those elements and inside `
+        + `embedded frames, is uploaded as shown; masking is not secret detection. Remove "screenshots" from the plan to turn this off`;
+}
+function seconds(ms) {
+    const value = ms / 1000;
+    return `${Number.isInteger(value) ? value : value.toFixed(1)} second${value === 1 ? '' : 's'}`;
+}
+/** Plain words for the approval screen: what the sanitized action trace records and what it never does. */
+export function describeTrace(trace) {
+    if (!trace)
+        return 'no action trace is recorded';
+    return 'records which kind of browser operation the flow ran (navigate, click, fill, press, select, check, uncheck, wait or observe), '
+        + 'how it ended and when, and uploads that as evidence. It never records selectors, addresses, typed values, page text or errors, '
+        + 'and it is not a Playwright trace, network log or video. Remove "trace" from the plan to turn this off';
+}