firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/native/owned-groups.js

@@ -0,0 +1,46 @@
+/**
+ * Process groups this CLI started and still owns (POSIX only).
+ *
+ * A detached child leads its own process group, so it is not interrupted with
+ * the terminal's foreground group. Ordinary shutdown ends each group through its
+ * owner (the supervisor, a reset hook, a driver). This registry exists for the
+ * one case that cannot wait for that: a second interrupt, which force-exits the
+ * CLI. `killOwnedGroups` then ends every group still registered, so nothing the
+ * drill started outlives it.
+ *
+ * A group is registered once its leader has started and is released as soon as
+ * its leader exits and its members are swept. A registered id is therefore
+ * always a live leader this process spawned, never a reused id, so nothing
+ * unrelated is ever signalled.
+ */
+const OWNED = new Set();
+const POSIX = process.platform !== 'win32';
+/** Record a group whose detached leader `pid` this process just started. */
+export function ownGroup(pid) {
+    if (POSIX && typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 1)
+        OWNED.add(pid);
+}
+/**
+ * The leader `pid` exited: SIGKILL the members it left in its group, then stop
+ * tracking it. Called right at the leader's exit, while no other process can
+ * hold that group id (members still in it keep the id reserved).
+ */
+export function sweepGroup(pid) {
+    if (!POSIX || typeof pid !== 'number' || !OWNED.has(pid))
+        return;
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch { /* group already empty */ }
+    OWNED.delete(pid);
+}
+/** SIGKILL every group still owned. Synchronous, so it is safe in a signal handler before exit. */
+export function killOwnedGroups() {
+    for (const pid of OWNED) {
+        try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch { /* group already empty */ }
+    }
+    OWNED.clear();
+}

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

@@ -0,0 +1,594 @@
+/**
+ * Local approved plan: parsing, validation, digest and approval (Plan20 W09).
+ *
+ * The plan is a session input written by the operator (a coding agent or the
+ * user) and supplied by path or stdin. It names the exact argv, roots, hooks and
+ * environment variable names that may run on this machine. Only its digest over
+ * the portable form (root paths replaced by alias + identity) is ever sent to
+ * the cloud; commands are never accepted from a cloud message.
+ *
+ * Approved processes run natively with the user's permissions. Native mode is
+ * not an OS sandbox and nothing here claims otherwise.
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { z } from 'zod';
+import { CliError } from '../http.js';
+import { selectOne, terminalText } from '../prompts.js';
+import { canonicalJson, normalizeDescriptor, sha256Hex } from './canonical.js';
+import { ALIAS, DRIVER_PROFILES, FRAME_INTERVAL_MAX_MS, FRAME_INTERVAL_MIN_MS, MAX_FRAMES_PER_STEP, SHA256_HEX, nativeError } from './contracts.js';
+import { insideRoot, isSafeRelativePath } from './roots.js';
+import { MASK_SELECTOR_MAX_CHARS, MAX_MASK_SELECTORS, describeScreenshots, describeTrace, maskingPolicy } from './screenshots.js';
+// ---------------------------------------------------------------------------
+// Shared limits and patterns.
+/** Environment variable name accepted in plans and bindings. */
+export const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+/** Inherited names that would switch off TLS verification (the user's own proxy and CA settings may still be inherited). */
+const TLS_OFF_ENV = new Set(['NODE_TLS_REJECT_UNAUTHORIZED', 'GIT_SSL_NO_VERIFY', 'PYTHONHTTPSVERIFY']);
+/**
+ * Names a fixed plan value may never set: TLS switches, added certificate
+ * authorities, proxies and loader preloads. Firedrill never changes the target's
+ * network trust; simulated dependencies are reached through declared routes. The
+ * comparison is case-insensitive because Windows env names are.
+ */
+const TRUST_ENV = new Set([...TLS_OFF_ENV, 'NODE_OPTIONS', 'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'REQUESTS_CA_BUNDLE',
+    'CURL_CA_BUNDLE', 'GIT_SSL_CAINFO', 'GIT_SSL_CAPATH', 'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY', 'FTP_PROXY',
+    'GLOBAL_AGENT_HTTP_PROXY', 'GLOBAL_AGENT_HTTPS_PROXY']);
+const TRUST_ENV_PREFIXES = ['LD_', 'DYLD_', 'FIREDRILL_'];
+/** Known platform limits of process control, shown before approval and in status. */
+export function processControlLimitations(platform = process.platform) {
+    return platform === 'win32'
+        ? ['Process groups are not used on Windows: only each started process is stopped, and processes it started may keep running.']
+        : [];
+}
+function isTrustOverride(name) {
+    const upper = name.toUpperCase();
+    return TRUST_ENV.has(upper) || TRUST_ENV_PREFIXES.some((prefix) => upper.startsWith(prefix));
+}
+/** Names that look like credentials; refused as fixed plan values. */
+export const SECRET_LIKE_NAME = /(?:^|_)(?:SECRET|SECRETS|TOKEN|TOKENS|PASSWORD|PASSWD|PASSPHRASE|PWD|APIKEY|API_KEY|KEY|PRIVATE_KEY|ACCESS_KEY|CREDENTIAL|CREDENTIALS|AUTH|AUTHORIZATION|COOKIE|SESSION)(?:_|$)/i;
+const HEADER_NAME = /^[A-Za-z][A-Za-z0-9-]{0,63}$/;
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+const MAX_PLAN_BYTES = 1_048_576;
+const MAX_FILE_BYTES = 16 * 1024 * 1024;
+const planInvalid = (where) => new CliError('native_plan_invalid', `The local plan is not valid${where ? ` at ${where}` : ''}. Nothing was approved or started.`, 2);
+const planMismatch = (message) => new CliError('native_plan_invalid', `${message} Nothing was approved or started.`, 2);
+// ---------------------------------------------------------------------------
+// Parsing (closed fields, bounded sizes).
+const noNul = (max) => z.string().max(max).regex(/^[^\u0000]*$/);
+const aliasSchema = z.string().max(64).regex(ALIAS);
+const shaSchema = z.string().regex(SHA256_HEX);
+const envNameSchema = z.string().regex(ENV_NAME);
+const relativePath = noNul(4096).refine(value => isSafeRelativePath(value));
+const argvSchema = z.object({
+    executable: noNul(4096).min(1),
+    args: z.array(noNul(32_768)).max(256),
+}).strict();
+const timeoutSchema = z.number().int().min(1).max(600_000);
+const readinessSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('http'), url: z.string().min(1).max(2048), expect_status: z.array(z.number().int().min(100).max(599)).min(1).max(32) }).strict(),
+    z.object({ kind: z.literal('tcp'), port: z.number().int().min(0).max(65_535) }).strict(),
+    z.object({ kind: z.literal('stdout'), pattern: noNul(512).min(1) }).strict(),
+    z.object({ kind: z.literal('none') }).strict(),
+]);
+const serviceSchema = z.object({
+    alias: aliasSchema,
+    root_alias: aliasSchema,
+    mode: z.enum(['launch', 'attach']),
+    command: argvSchema.nullable(),
+    cwd: relativePath,
+    env_passthrough: z.array(envNameSchema).max(256),
+    env_static: z.record(envNameSchema, noNul(32_768)).refine(value => Object.keys(value).length <= 256),
+    readiness: readinessSchema,
+    readiness_timeout_ms: timeoutSchema,
+    stop_timeout_ms: z.number().int().min(0).max(120_000),
+    per_drill: z.boolean(),
+    port_env: envNameSchema.nullable(),
+    local_secret_env: z.array(envNameSchema).max(32).optional(),
+    mcp_config_env: envNameSchema.nullable().optional(),
+    /** Env names that receive this service's loopback dependency URLs (the companion proxy; never a credential). */
+    dependency_env: z.array(z.object({ alias: aliasSchema, name: envNameSchema, url: z.enum(['invoke', 'mcp']) }).strict()).max(64).optional(),
+}).strict();
+const driverSchema = z.discriminatedUnion('profile', [
+    z.object({
+        profile: z.literal('http.v1'), service_alias: aliasSchema, path: noNul(2048), method: z.enum(['POST', 'PUT']),
+        stream: z.enum(['none', 'sse', 'ndjson']), session_header: z.string().regex(HEADER_NAME).nullable(),
+        request_template: z.enum(['message-text', 'task-json']), response_pointer: noNul(1024).nullable(),
+    }).strict(),
+    z.object({ profile: z.literal('jsonl-process.v1'), service_alias: aliasSchema }).strict(),
+    z.object({ profile: z.literal('function-wrapper.v1'), root_alias: aliasSchema, wrapper: relativePath, runtime: argvSchema }).strict(),
+    z.object({ profile: z.literal('playwright.v1'), root_alias: aliasSchema, flow: relativePath, service_alias: aliasSchema, start_path: noNul(2048),
+        // Masked PNG screenshots: on only when the plan says so; the selectors add to the form fields always masked.
+        // `frames` adds masked frames while each step runs (captured frames, never a video).
+        screenshots: z.object({
+            mask_selectors: z.array(noNul(MASK_SELECTOR_MAX_CHARS).min(1)).max(MAX_MASK_SELECTORS),
+            frames: z.object({
+                interval_ms: z.number().int().min(FRAME_INTERVAL_MIN_MS).max(FRAME_INTERVAL_MAX_MS),
+                max_per_step: z.number().int().min(1).max(MAX_FRAMES_PER_STEP),
+            }).strict().optional(),
+        }).strict().optional(),
+        // Root's sanitized action trace: operation kinds, outcomes and times only. Raw Playwright traces, HAR and
+        // video are not supported: they would carry values, network bodies or unmasked frames.
+        trace: z.literal('sanitized-actions').optional() }).strict(),
+    // Every event root dispatches names the signature header, so the receiver's signing secret is required.
+    z.object({ profile: z.literal('signed-http-event.v1'), service_alias: aliasSchema, path_prefix: noNul(2048),
+        signing_secret_env: envNameSchema }).strict(),
+]);
+const hookSchema = z.object({
+    domain_alias: aliasSchema, root_alias: aliasSchema, path: relativePath, sha256: shaSchema,
+    runtime: argvSchema, timeout_ms: timeoutSchema,
+}).strict();
+const planSchema = z.object({
+    version: z.literal(1),
+    descriptor_sha256: shaSchema,
+    roots: z.array(z.object({ alias: aliasSchema, path: noNul(4096).min(1), identity_sha256: shaSchema }).strict()).min(1).max(128),
+    services: z.array(serviceSchema).min(1).max(128),
+    driver: driverSchema,
+    state_hooks: z.array(hookSchema).max(256),
+    max_parallel_drills: z.number().int().min(1).max(64),
+}).strict();
+/** Bound size, depth and node count, and refuse prototype-bearing keys, before schema work. */
+function boundedDocument(value) {
+    const pending = [[value, 0]];
+    let nodes = 0;
+    while (pending.length) {
+        const [item, depth] = pending.pop();
+        if (++nodes > 65_536 || depth > 16)
+            throw planInvalid();
+        if (Array.isArray(item)) {
+            if (item.length > 1024)
+                throw planInvalid();
+            for (const child of item)
+                pending.push([child, depth + 1]);
+        }
+        else if (item && typeof item === 'object') {
+            const keys = Object.keys(item);
+            if (keys.length > 512 || keys.some(key => key === '__proto__' || key === 'constructor' || key === 'prototype' || key.length > 128))
+                throw planInvalid();
+            for (const key of keys)
+                pending.push([item[key], depth + 1]);
+        }
+    }
+}
+/** Describe an issue location using only schema field names and indices, never values. */
+function issueLocation(path) {
+    if (!path.length)
+        return undefined;
+    return path.map(part => typeof part === 'number' ? String(part)
+        : typeof part === 'string' && /^[a-z_]{1,40}$/.test(part) ? part : '*').join('.');
+}
+/**
+ * Parse a local plan JSON document strictly: closed fields, bounded sizes, no
+ * NUL characters, safe relative paths. Throws `native_plan_invalid` (exit 2)
+ * naming the failing field location, never the rejected value.
+ */
+export function parsePlan(raw) {
+    if (typeof raw !== 'string' || Buffer.byteLength(raw, 'utf8') > MAX_PLAN_BYTES)
+        throw planInvalid();
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw planInvalid();
+    }
+    boundedDocument(value);
+    const parsed = planSchema.safeParse(value);
+    if (!parsed.success)
+        throw planInvalid(issueLocation(parsed.error.issues[0]?.path ?? []));
+    return parsed.data;
+}
+/** Replace session-local absolute root paths with `{alias, identity_sha256}`. */
+export function portablePlan(plan) {
+    return {
+        version: plan.version,
+        descriptor_sha256: plan.descriptor_sha256,
+        roots: plan.roots.map(root => ({ alias: root.alias, identity_sha256: root.identity_sha256 })),
+        services: plan.services,
+        driver: plan.driver,
+        state_hooks: plan.state_hooks,
+        max_parallel_drills: plan.max_parallel_drills,
+    };
+}
+/** sha256 of the canonical JSON of the portable plan. The only plan value the cloud learns. */
+export function planDigest(plan) {
+    return sha256Hex(canonicalJson(portablePlan(plan)));
+}
+/** Parse and check a loopback readiness URL; returns null when it is not acceptable. */
+export function loopbackUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'http:' || !LOOPBACK_HOSTS.has(url.hostname) || url.username || url.password || url.hash)
+        return null;
+    return url;
+}
+/** True when a service's port is known before or at start (allocated, or fixed in readiness). */
+export function serviceHasPort(service) {
+    return service.port_env !== null || service.readiness.kind === 'http' || service.readiness.kind === 'tcp';
+}
+function checkReadiness(service, readiness) {
+    const allocated = service.port_env !== null;
+    if (readiness.kind === 'http') {
+        const url = loopbackUrl(readiness.url);
+        if (!url)
+            throw planMismatch('A readiness URL must be plain http on 127.0.0.1, localhost or [::1].');
+        // Port 0 stands for the allocated port and is valid only with port_env.
+        if (allocated ? url.port !== '0' : !url.port || url.port === '0') {
+            throw planMismatch('A readiness URL must use port 0 when the port is allocated (port_env), and an explicit port otherwise.');
+        }
+    }
+    else if (readiness.kind === 'tcp') {
+        if (allocated ? readiness.port !== 0 : readiness.port < 1) {
+            throw planMismatch('A readiness TCP port must be 0 when the port is allocated (port_env), and a real port otherwise.');
+        }
+    }
+}
+function checkPath(value, label) {
+    if (!value.startsWith('/') || value.startsWith('//') || value.includes('\\') || value.includes('#') || /[\u0000-\u001f]/.test(value)) {
+        throw planMismatch(`The driver ${label} must be an absolute request path starting with a single "/".`);
+    }
+}
+function checkArgv(command) {
+    // argv only (spawned with shell:false). Batch files would be run through a
+    // command interpreter on Windows, so they are refused everywhere.
+    if (/\.(?:bat|cmd)$/i.test(command.executable.trim())) {
+        throw planMismatch('Use a real executable, not a batch file, for approved commands.');
+    }
+}
+/**
+ * Validate a parsed plan against the (re-normalized) descriptor: every
+ * descriptor service has exactly one plan entry; launch services have argv,
+ * attach services none and are never per-drill; roots, hooks and driver profile
+ * match the descriptor; env names are identifiers; no secret-named configuration
+ * appears in `env_static`, and descriptor secrets are never passed through from
+ * the user environment. Returns the plan digest. Does not touch the filesystem;
+ * see `verifyPlanFiles` for on-disk checks at use time.
+ */
+export function validatePlan(plan, descriptor) {
+    const normalized = normalizeDescriptor(descriptor);
+    const document = normalized.descriptor;
+    if (plan.version !== 1)
+        throw planInvalid('version');
+    if (plan.descriptor_sha256 !== normalized.descriptor_sha256)
+        throw planMismatch('The plan was written for a different local descriptor.');
+    const roots = new Map(plan.roots.map(root => [root.alias, root]));
+    if (roots.size !== plan.roots.length)
+        throw planMismatch('Use distinct root aliases in the plan.');
+    if (roots.size !== document.source_roots.length || document.source_roots.some(root => roots.get(root.alias)?.identity_sha256 !== root.identity_sha256)) {
+        throw planMismatch('The plan roots must match the descriptor source roots and their identities.');
+    }
+    for (const root of plan.roots) {
+        if (!/^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(root.path))
+            throw planMismatch('Plan root paths must be absolute.');
+    }
+    const services = new Map(plan.services.map(service => [service.alias, service]));
+    if (services.size !== plan.services.length || services.size !== document.services.length) {
+        throw planMismatch('The plan must contain exactly one entry for each descriptor service.');
+    }
+    for (const declared of document.services) {
+        const service = services.get(declared.alias);
+        if (!service)
+            throw planMismatch('The plan must contain exactly one entry for each descriptor service.');
+        if (service.root_alias !== declared.root_alias)
+            throw planMismatch('Each plan service must use its descriptor root.');
+        if (!isSafeRelativePath(service.cwd))
+            throw planInvalid('services.cwd');
+        if (service.mode === 'launch') {
+            if (!service.command)
+                throw planMismatch('Each launched service needs an approved command in argv form.');
+            checkArgv(service.command);
+            if (service.per_drill && service.port_env === null && serviceHasPort(service)) {
+                throw planMismatch('A per-drill network service needs port_env for its own loopback port.');
+            }
+            if (service.port_env !== null && isTrustOverride(service.port_env))
+                throw planMismatch(`${service.port_env} cannot carry the allocated port.`);
+        }
+        else {
+            if (service.command !== null)
+                throw planMismatch('An attached service is already running and cannot carry a command.');
+            if (service.per_drill || service.port_env !== null)
+                throw planMismatch('An attached service cannot be per-drill or receive an allocated port.');
+        }
+        checkReadiness(service, service.readiness);
+        const passthrough = new Set(service.env_passthrough);
+        if (passthrough.size !== service.env_passthrough.length)
+            throw planMismatch('List each passed-through environment name once.');
+        const secretNames = new Set(declared.configuration.filter(item => item.secret).map(item => item.name));
+        const localSecrets = service.local_secret_env ?? [];
+        const folded = (name) => name.toUpperCase();
+        const occupied = new Set([...service.env_passthrough, ...Object.keys(service.env_static),
+            ...[service.port_env, service.mcp_config_env].filter((name) => typeof name === 'string'),
+            ...(service.dependency_env ?? []).map(route => route.name)].map(folded));
+        if (new Set(localSecrets.map(folded)).size !== localSecrets.length || localSecrets.some(name => service.mode !== 'launch' || !service.per_drill || occupied.has(folded(name)) || isTrustOverride(name)
+            || !declared.configuration.some(item => item.name === name && item.secret && item.phase !== 'build'))) {
+            throw planMismatch('Local secret bindings must be distinct declared runtime secrets on a fresh per-drill process. They cannot override routing or other configuration.');
+        }
+        for (const name of Object.keys(service.env_static)) {
+            if (!ENV_NAME.test(name))
+                throw planInvalid('services.env_static');
+            if (secretNames.has(name) || SECRET_LIKE_NAME.test(name)) {
+                throw planMismatch('Secret configuration cannot be a fixed plan value. Supply it through a binding instead.');
+            }
+            if (isTrustOverride(name)) {
+                throw planMismatch(`${name} would change how the target trusts or routes network traffic, or what it preloads. A plan never disables TLS verification, adds a certificate authority, sets a proxy or injects a loader.`);
+            }
+        }
+        for (const name of passthrough) {
+            if (!ENV_NAME.test(name))
+                throw planInvalid('services.env_passthrough');
+            if (secretNames.has(name))
+                throw planMismatch('Descriptor secret configuration is never inherited from your environment. Supply it through a binding instead.');
+            if (TLS_OFF_ENV.has(name.toUpperCase()) || name.toUpperCase().startsWith('FIREDRILL_')) {
+                throw planMismatch(`${name} is never inherited: it would switch off TLS verification or impersonate a Firedrill value.`);
+            }
+        }
+    }
+    const driver = plan.driver;
+    if (!DRIVER_PROFILES.includes(driver.profile) || driver.profile !== document.driver.profile) {
+        throw planMismatch('The plan driver profile must equal the descriptor driver profile.');
+    }
+    const serviceFor = (alias) => {
+        const service = services.get(alias);
+        if (!service)
+            throw planMismatch('The driver must use a service declared in the plan.');
+        return service;
+    };
+    const rootFor = (alias) => {
+        if (!roots.has(alias))
+            throw planMismatch('The driver must use a root declared in the plan.');
+    };
+    switch (driver.profile) {
+        case 'http.v1': {
+            if (!serviceHasPort(serviceFor(driver.service_alias)))
+                throw planMismatch('The driver service needs a known loopback port.');
+            checkPath(driver.path, 'path');
+            if (driver.response_pointer !== null && driver.response_pointer !== '' && !driver.response_pointer.startsWith('/')) {
+                throw planMismatch('The response pointer must be a JSON pointer.');
+            }
+            break;
+        }
+        case 'jsonl-process.v1': {
+            const service = serviceFor(driver.service_alias);
+            // The JSON-lines driver itself starts and owns this process (its stdin/stdout).
+            if (service.mode !== 'launch' || (service.readiness.kind !== 'none' && service.readiness.kind !== 'stdout')) {
+                throw planMismatch('A JSON-lines service must be launched by the plan and use "none" or "stdout" readiness.');
+            }
+            break;
+        }
+        case 'function-wrapper.v1':
+            rootFor(driver.root_alias);
+            checkArgv(driver.runtime);
+            break;
+        case 'playwright.v1':
+            rootFor(driver.root_alias);
+            if (!serviceHasPort(serviceFor(driver.service_alias)))
+                throw planMismatch('The driver service needs a known loopback port.');
+            checkPath(driver.start_path, 'start path');
+            break;
+        case 'signed-http-event.v1':
+            if (!serviceHasPort(serviceFor(driver.service_alias)))
+                throw planMismatch('The driver service needs a known loopback port.');
+            checkPath(driver.path_prefix, 'path prefix');
+            // The receiver's signing secret is read from this environment by name; it is never a trust or Firedrill setting.
+            if (driver.signing_secret_env !== undefined && isTrustOverride(driver.signing_secret_env)) {
+                throw planMismatch(`${driver.signing_secret_env} cannot hold the event signing secret.`);
+            }
+            break;
+    }
+    const hooked = new Map(document.state_domains.filter(domain => domain.reset === 'approved-hook').map(domain => [domain.alias, domain]));
+    const hookDomains = new Set();
+    for (const hook of plan.state_hooks) {
+        const domain = hooked.get(hook.domain_alias);
+        if (!domain || hookDomains.has(hook.domain_alias))
+            throw planMismatch('Each state hook must belong to one approved-hook state domain.');
+        if (domain.hook_sha256 !== hook.sha256)
+            throw planMismatch('A state hook digest does not match the descriptor.');
+        if (!roots.has(hook.root_alias) || !isSafeRelativePath(hook.path))
+            throw planMismatch('A state hook must be a file inside a plan root.');
+        checkArgv(hook.runtime);
+        hookDomains.add(hook.domain_alias);
+    }
+    if (hookDomains.size !== hooked.size)
+        throw planMismatch('Every approved-hook state domain needs exactly one plan hook.');
+    return { plan_sha256: planDigest(plan), normalized };
+}
+// ---------------------------------------------------------------------------
+// On-disk checks at use time.
+/** sha256 of a file's bytes (bounded size). */
+export async function hashFile(path, maxBytes = MAX_FILE_BYTES) {
+    const hash = createHash('sha256');
+    let size = 0;
+    for await (const chunk of createReadStream(path)) {
+        size += chunk.length;
+        if (size > maxBytes)
+            throw new CliError('native_file_too_large', 'An approved file exceeds the accepted size. Nothing was run from it.', 2);
+        hash.update(chunk);
+    }
+    return hash.digest('hex');
+}
+const fileChanged = () => nativeError('plan_changed', 'An approved file changed since the plan was approved. Review and approve the plan again; nothing was run from it.', 2);
+/**
+ * Re-hash an approved file inside its root and return its real path. A digest
+ * mismatch is `native_plan_changed`. Call immediately before each use; the hash
+ * is evidence of what was approved, not a lock against later edits.
+ */
+export async function verifyRootFile(roots, rootAlias, relative, expectedSha256) {
+    const root = roots.get(rootAlias);
+    if (!root)
+        throw nativeError('root_outside', 'An approved file names a root that is not part of this session. Nothing was run from it.', 2);
+    const path = await insideRoot(root, relative);
+    let digest;
+    try {
+        digest = await hashFile(path);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw fileChanged();
+    }
+    if (digest !== expectedSha256)
+        throw fileChanged();
+    return path;
+}
+/** Re-hash a state hook file (descriptor `hook_sha256`) and return its real path. */
+export function verifyHookFile(roots, hook) {
+    return verifyRootFile(roots, hook.root_alias, hook.path, hook.sha256);
+}
+/**
+ * Verify every on-disk input the plan pins: state hook files, and for the
+ * function-wrapper and playwright profiles the wrapper or flow module against
+ * the descriptor `adapter_sha256`. Throws `native_plan_changed` on any mismatch.
+ */
+export async function verifyPlanFiles(plan, normalized, roots) {
+    for (const hook of plan.state_hooks)
+        await verifyHookFile(roots, hook);
+    const driver = plan.driver;
+    if (driver.profile === 'function-wrapper.v1') {
+        await verifyRootFile(roots, driver.root_alias, driver.wrapper, normalized.descriptor.driver.adapter_sha256);
+    }
+    else if (driver.profile === 'playwright.v1') {
+        await verifyRootFile(roots, driver.root_alias, driver.flow, normalized.descriptor.driver.adapter_sha256);
+    }
+}
+const minted = new WeakSet();
+const quote = (value) => terminalText(JSON.stringify(value));
+const argvText = (command) => [command.executable, ...command.args].map(quote).join(' ');
+function readinessText(readiness, timeout) {
+    const within = `within ${timeout} ms`;
+    switch (readiness.kind) {
+        case 'http': return `HTTP GET ${terminalText(readiness.url)} expecting ${readiness.expect_status.join('/')} ${within}`;
+        case 'tcp': return `TCP connect to 127.0.0.1:${readiness.port === 0 ? '<allocated>' : readiness.port} ${within}`;
+        case 'stdout': return `output contains ${quote(readiness.pattern)} ${within}`;
+        case 'none': return 'none';
+    }
+}
+/**
+ * Human-readable summary of everything approval allows: roots, exact argv,
+ * working directories, environment variable names (never values), readiness,
+ * driver and hooks. Port 0 in readiness means the allocated port.
+ */
+export function describePlan(plan, validated) {
+    const lines = [];
+    lines.push(`Local plan ${validated.plan_sha256}`);
+    lines.push(`Descriptor ${validated.normalized.descriptor_sha256}`);
+    lines.push('These commands run as trusted processes with your user permissions. Native mode is not an OS sandbox.');
+    lines.push(...processControlLimitations());
+    lines.push('Roots:');
+    for (const root of plan.roots)
+        lines.push(`  ${root.alias}: ${terminalText(root.path)}`);
+    lines.push('Services, in startup order:');
+    const byAlias = new Map(plan.services.map(service => [service.alias, service]));
+    for (const alias of validated.normalized.startup_order) {
+        const service = byAlias.get(alias);
+        if (!service)
+            continue;
+        if (service.mode === 'attach') {
+            lines.push(`  ${alias}: attach to an already running service (readiness check only; never signalled)`);
+        }
+        else {
+            lines.push(`  ${alias}: launch${service.per_drill ? ' one copy per drill' : ' one shared copy'}`);
+            if (service.command)
+                lines.push(`    argv: ${argvText(service.command)}`);
+        }
+        lines.push(`    cwd: ${service.root_alias}:${terminalText(service.cwd || '.')}`);
+        if (service.env_passthrough.length)
+            lines.push(`    inherits from your environment: ${service.env_passthrough.join(', ')}`);
+        const fixed = Object.keys(service.env_static);
+        if (fixed.length)
+            lines.push(`    fixed environment names: ${fixed.join(', ')}`);
+        if (service.port_env)
+            lines.push(`    allocated loopback port in: ${service.port_env}`);
+        if (service.local_secret_env?.length)
+            lines.push(`    local secret bindings: ${service.local_secret_env.join(', ')} (values stay on this machine)`);
+        lines.push(`    readiness: ${readinessText(service.readiness, service.readiness_timeout_ms)}`);
+    }
+    const driver = plan.driver;
+    switch (driver.profile) {
+        case 'http.v1':
+            lines.push(`Driver: ${driver.profile} ${driver.method} ${terminalText(driver.path)} on ${driver.service_alias}`);
+            break;
+        case 'jsonl-process.v1':
+            lines.push(`Driver: ${driver.profile} over the standard input and output of ${driver.service_alias}`);
+            break;
+        case 'function-wrapper.v1':
+            lines.push(`Driver: ${driver.profile} ${driver.root_alias}:${terminalText(driver.wrapper)} with argv ${argvText(driver.runtime)}`);
+            break;
+        case 'playwright.v1':
+            lines.push(`Driver: ${driver.profile} flow ${driver.root_alias}:${terminalText(driver.flow)} on ${driver.service_alias}`);
+            lines.push(`  screenshots: ${terminalText(describeScreenshots(driver.screenshots))}`);
+            if (driver.screenshots)
+                lines.push(`  masking policy sha256 ${maskingPolicy(driver.screenshots).sha256}`);
+            lines.push(`  action trace: ${terminalText(describeTrace(driver.trace))}`);
+            break;
+        case 'signed-http-event.v1':
+            lines.push(`Driver: ${driver.profile} ${terminalText(driver.path_prefix)} on ${driver.service_alias}`);
+            lines.push(`  signs each event with the secret in ${driver.signing_secret_env} from your environment (the value is never shown or uploaded)`);
+            break;
+    }
+    if (plan.state_hooks.length) {
+        lines.push('State reset hooks:');
+        for (const hook of plan.state_hooks) {
+            lines.push(`  ${hook.domain_alias}: ${hook.root_alias}:${terminalText(hook.path)} sha256 ${hook.sha256}`);
+            lines.push(`    argv: ${argvText(hook.runtime)} (timeout ${hook.timeout_ms} ms)`);
+        }
+    }
+    lines.push(`Parallel drills: at most ${validated.normalized.requires_serial_execution ? 1 : plan.max_parallel_drills}`);
+    return lines.join('\n');
+}
+/**
+ * Validate, show and approve a plan. With `approve: true` (for agents, the
+ * `--approve` flag) consent is explicit and no prompt is shown. Otherwise an
+ * interactive terminal choice is required; without one this throws
+ * `native_plan_unapproved` (exit 2). The approval lives in memory only; the
+ * cloud learns just `plan_sha256`. Any later change voids it (see
+ * `assertPlanApproved`).
+ */
+export async function approvePlan(plan, descriptor, options) {
+    const validated = validatePlan(plan, descriptor);
+    const write = options.output ?? ((text) => { process.stderr.write(text); });
+    write(describePlan(plan, validated) + '\n');
+    let method;
+    if (options.approve)
+        method = 'flag';
+    else if (!options.interactive) {
+        throw nativeError('plan_unapproved', 'The local plan was not approved, so nothing was started. Review it and pass --approve, or approve it in an interactive terminal.', 2);
+    }
+    else {
+        const accepted = await selectOne('Approve running these commands on this machine?', [
+            { value: false, label: 'Do not approve', detail: 'Nothing is started.' },
+            { value: true, label: 'Approve this plan', detail: `Digest ${validated.plan_sha256.slice(0, 16)}` },
+        ], options.signal);
+        if (!accepted)
+            throw nativeError('plan_unapproved', 'The local plan was not approved, so nothing was started.', 2);
+        method = 'interactive';
+    }
+    const approval = Object.freeze({
+        plan_sha256: validated.plan_sha256,
+        descriptor_sha256: validated.normalized.descriptor_sha256,
+        startup_order: Object.freeze([...validated.normalized.startup_order]),
+        approved_at: Date.now(),
+        method,
+    });
+    minted.add(approval);
+    return approval;
+}
+/**
+ * Throw unless `approval` was issued by `approvePlan` in this process and the
+ * plan still has the approved digest (`native_plan_unapproved` /
+ * `native_plan_changed`). Call before any start and when a cloud message
+ * references a plan digest.
+ */
+export function assertPlanApproved(approval, plan, expectedSha256) {
+    if (!approval || !minted.has(approval)) {
+        throw nativeError('plan_unapproved', 'The local plan has not been approved in this session, so nothing was started.', 2);
+    }
+    const digest = planDigest(plan);
+    if (digest !== approval.plan_sha256 || (expectedSha256 !== undefined && expectedSha256 !== digest)) {
+        throw nativeError('plan_changed', 'The local plan differs from the approved plan. Review and approve it again; nothing was started.', 2);
+    }
+}