firedrill-run 2.2.5 → 3.0.0

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

@@ -0,0 +1,235 @@
+/** Replacement marker written in place of a redacted value. */
+export const REDACTED = '[redacted]';
+/** Largest input a single `redact` call processes; longer text is truncated. */
+export const MAX_REDACT_CHARS = 4 * 1024 * 1024;
+const TRUNCATED = '[truncated]';
+const MAX_SECRET_CHARS = 65_536;
+const MAX_SECRETS = 512;
+/** Exact strings to redact for each secret: the value plus URL/base64 encodings. */
+function secretVariants(secrets) {
+    if (secrets.length > MAX_SECRETS)
+        return null;
+    const variants = new Set();
+    let total = 0;
+    for (const secret of secrets.slice(0, MAX_SECRETS)) {
+        const value = secret.reveal();
+        if (typeof value !== 'string' || !value || value.length > MAX_SECRET_CHARS)
+            return null;
+        variants.add(value);
+        let encoded;
+        try {
+            encoded = encodeURIComponent(value);
+        }
+        catch {
+            return null;
+        }
+        if (encoded !== value)
+            variants.add(encoded);
+        if (value.length >= 6) {
+            const bytes = Buffer.from(value, 'utf8');
+            variants.add(bytes.toString('base64'));
+            variants.add(bytes.toString('base64url'));
+            variants.add(bytes.toString('base64').replace(/=+$/, ''));
+        }
+        total += value.length * 12;
+        if (total > MAX_REDACT_CHARS)
+            return null;
+    }
+    // Longest first, so a value never leaves a partial copy of a longer variant.
+    return [...variants].sort((a, b) => b.length - a.length);
+}
+const SECRET_KEY = '(?:secret|token|passw(?:or)?d|pwd|passphrase|api[_-]?key|access[_-]?key|private[_-]?key|credentials?|authorization|session[_-]?id|cookie)';
+const KEY_VALUE = new RegExp(`(?<![A-Za-z0-9_.-])([A-Za-z0-9_.-]{0,40}${SECRET_KEY}[A-Za-z0-9_.-]{0,40}["']?\\s{0,4}[:=]\\s{0,4}["']?)(?!\\[redacted\\])([^\\s"'&,;<>}\\]]{1,4096})`, 'gi');
+const AUTH_SCHEME = /\b(Bearer|Basic|Token|Digest)(\s+)(?!\[redacted\])[A-Za-z0-9._~+/=-]{8,}/gi;
+const JWT_LIKE = /\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]*/g;
+const PRIVATE_KEY_BLOCK = /-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]{0,40}PRIVATE KEY-----|$)/g;
+const URL_CREDENTIAL = /(\b[a-z][a-z0-9+.-]{0,30}:\/\/[^\s:/@]{1,256}:)([^\s@/]{1,1024})(@)/gi;
+const LONG_HEX = /\b[A-Fa-f0-9]{32,}\b/g;
+const LONG_MIXED = /[A-Za-z0-9+/_-]{32,}={0,2}/g;
+const count = (value, pattern) => value.match(pattern)?.length ?? 0;
+/** A long run looks like key material: mixed case and digits, and not path-like. */
+function looksLikeKey(value) {
+    if (value.startsWith('/') || count(value, /\//g) > 2)
+        return false;
+    return count(value, /[A-Z]/g) >= 2 && count(value, /[a-z]/g) >= 2 && count(value, /[0-9]/g) >= 2;
+}
+function keyValue(_match, prefix, value) {
+    // Keep small numeric settings and literals readable (for example a length limit).
+    if (/^(?:\d{1,9}|true|false|null|none)$/i.test(value))
+        return prefix + value;
+    return prefix + REDACTED;
+}
+/** Token-shape rules in application order. Exported for streaming cut checks. */
+export const TOKEN_SHAPES = [
+    [PRIVATE_KEY_BLOCK, REDACTED],
+    [URL_CREDENTIAL, `$1${REDACTED}$3`],
+    [AUTH_SCHEME, `$1$2${REDACTED}`],
+    [JWT_LIKE, REDACTED],
+    [KEY_VALUE, keyValue],
+    [LONG_HEX, REDACTED],
+    [LONG_MIXED, (match) => looksLikeKey(match) ? REDACTED : match],
+];
+function redactWith(text, variants) {
+    let out = text;
+    for (const value of variants)
+        if (out.includes(value))
+            out = out.split(value).join(REDACTED);
+    for (const [pattern, replacement] of TOKEN_SHAPES) {
+        pattern.lastIndex = 0;
+        out = typeof replacement === 'string' ? out.replace(pattern, replacement) : out.replace(pattern, replacement);
+    }
+    return out;
+}
+/**
+ * Replace exact secret values and common token shapes in `text`. Bounded:
+ * input beyond MAX_REDACT_CHARS is truncated (after redaction of the retained
+ * part, so a secret straddling the limit is still removed).
+ */
+export function redact(text, secrets) {
+    const input = typeof text === 'string' ? text : String(text);
+    const variants = secretVariants(secrets);
+    if (variants === null)
+        return REDACTED;
+    const longest = variants.length ? variants[0].length : 0;
+    const truncated = input.length > MAX_REDACT_CHARS;
+    const out = redactWith(truncated ? input.slice(0, MAX_REDACT_CHARS + longest + 1024) : input, variants);
+    return truncated ? out.slice(0, MAX_REDACT_CHARS) + TRUNCATED : out;
+}
+/**
+ * Replace only exact secret values (and their encodings), never token shapes.
+ * For short values whose public shape is known, such as a sha256 digest field,
+ * which the long-hex shape would otherwise erase.
+ */
+export function redactSecrets(text, secrets) {
+    let out = typeof text === 'string' ? text : String(text);
+    const variants = secretVariants(secrets);
+    if (variants === null)
+        return REDACTED;
+    for (const value of variants)
+        if (out.includes(value))
+            out = out.split(value).join(REDACTED);
+    return out;
+}
+/**
+ * Largest cut point <= `cut` such that no exact secret occurrence or token-shape
+ * match straddles it, and no secret that may still be arriving starts before it.
+ */
+function prefixTable(value) {
+    const table = new Int32Array(value.length);
+    for (let index = 1, matched = 0; index < value.length; index++) {
+        while (matched && value[index] !== value[matched])
+            matched = table[matched - 1];
+        if (value[index] === value[matched])
+            matched++;
+        table[index] = matched;
+    }
+    return table;
+}
+function safeCut(text, cut, variants, prefixes) {
+    let point = cut;
+    for (let changed = true; changed && point > 0;) {
+        changed = false;
+        for (let variant = 0; variant < variants.length; variant++) {
+            const value = variants[variant], table = prefixes[variant];
+            const full = text.indexOf(value, Math.max(0, point - value.length + 1));
+            if (full >= 0 && full < point) {
+                point = full;
+                changed = true;
+            }
+            // Linear suffix/prefix matching avoids quadratic repeated-character
+            // scans for long values, including encoded secrets split across chunks.
+            let matched = 0;
+            for (let index = Math.max(0, text.length - value.length + 1); index < text.length; index++) {
+                while (matched && text[index] !== value[matched])
+                    matched = table[matched - 1];
+                if (text[index] === value[matched])
+                    matched++;
+            }
+            const partial = text.length - matched;
+            if (matched && partial < point) {
+                point = partial;
+                changed = true;
+            }
+        }
+        for (const [pattern] of TOKEN_SHAPES) {
+            pattern.lastIndex = 0;
+            for (const match of text.matchAll(pattern)) {
+                const start = match.index ?? 0, end = start + match[0].length;
+                if (start < point && (end > point || end === text.length)) {
+                    point = start;
+                    changed = true;
+                }
+            }
+        }
+    }
+    return point;
+}
+/**
+ * Streaming redaction for process output. Text is emitted to `sink` only after
+ * redaction, at line boundaries when possible; a line longer than `maxLine` is
+ * cut at a point no secret straddles. Incomplete matches are retained within a
+ * finite budget; overflow suppresses the remaining capture rather than leaking
+ * an incomplete credential. Call `flush()` only at end of the stream.
+ */
+export class RedactingCapture {
+    #variants;
+    #prefixes;
+    #sink;
+    #maxLine;
+    #pending = '';
+    #suppressed = false;
+    #pendingLimit;
+    constructor(secrets, sink, maxLine = 16_384) {
+        const variants = secretVariants(secrets);
+        this.#variants = variants ?? [];
+        this.#prefixes = this.#variants.map(prefixTable);
+        this.#sink = sink;
+        this.#maxLine = Number.isFinite(maxLine) ? Math.max(1024, Math.min(Math.floor(maxLine), 1_048_576)) : 16_384;
+        this.#pendingLimit = Math.max(this.#maxLine * 4, (this.#variants[0]?.length ?? 0) * 2 + 1024);
+        if (variants === null) {
+            this.#suppressed = true;
+            this.#sink(REDACTED);
+        }
+    }
+    /** Add decoded text; complete, safe portions are redacted and emitted. */
+    push(chunk) {
+        if (!chunk || this.#suppressed)
+            return;
+        for (let offset = 0; offset < chunk.length && !this.#suppressed; offset += 32768) {
+            this.#pushBounded(chunk.slice(offset, offset + 32768));
+        }
+    }
+    #pushBounded(chunk) {
+        this.#pending += chunk;
+        let cut = this.#pending.lastIndexOf('\n') + 1;
+        if (!cut && this.#pending.length > this.#maxLine)
+            cut = Math.max(0, this.#pending.length - 256);
+        if (!cut)
+            return;
+        cut = safeCut(this.#pending, cut, this.#variants, this.#prefixes);
+        if (!cut) {
+            // An incomplete secret/token is not safe merely because the buffer is
+            // full. Suppress this capture rather than exposing its prefix or suffix.
+            if (this.#pending.length > this.#pendingLimit) {
+                this.#pending = '';
+                this.#suppressed = true;
+                this.#sink(REDACTED + TRUNCATED);
+            }
+            return;
+        }
+        const ready = this.#pending.slice(0, cut);
+        this.#pending = this.#pending.slice(cut);
+        this.#sink(redactWith(ready, this.#variants));
+    }
+    /** Redact and emit everything still pending. */
+    flush() {
+        if (!this.#pending)
+            return;
+        const ready = this.#pending;
+        this.#pending = '';
+        // EOF may cut off a credential mid-value. Do not expose the withheld
+        // prefix just because no more process bytes will arrive.
+        const cut = safeCut(ready, ready.length, this.#variants, this.#prefixes);
+        this.#sink(redactWith(ready.slice(0, cut), this.#variants) + (cut < ready.length ? REDACTED : ''));
+    }
+}

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

@@ -0,0 +1,155 @@
+// Consumer for the root-released native metadata registration producer
+// (docs: platform docs/implementation/plan20-contracts.md, operation ids
+// native_agent_register, native_descriptors_list, native_descriptor_register,
+// native_descriptor_get). Registration sends declared metadata only: no
+// source upload, no absolute paths, no secret values, and nothing executes.
+// Producer source exists; it is not deployed or qualified, so these calls are
+// wiring-ready rather than verified.
+import { randomUUID } from 'node:crypto';
+import { api } from '../auth.js';
+import { CliError } from '../http.js';
+import { normalizeDescriptor } from './canonical.js';
+import { SHA256_HEX } from './contracts.js';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NAME_LIMIT = 120;
+const RESPONSE_LIMIT = 1024 * 1024;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const unconfirmed = () => new CliError('native_registration_unconfirmed', 'The registration response could not be confirmed. Nothing local changed; rerun with the same request key to read the saved receipt.');
+/** Returns a new idempotency key, or validates a caller-supplied one for replay. */
+export function registrationKey(supplied) {
+    if (supplied === undefined)
+        return randomUUID();
+    if (!UUID.test(supplied))
+        throw new CliError('native_request_key_invalid', 'Use the request key printed by the earlier attempt. Nothing was submitted.', 2);
+    return supplied.toLowerCase();
+}
+const DECLARED_NAME_LIMIT = 120;
+/**
+ * The optional self-reported coding-agent name sent with a registration or
+ * revision, trimmed the same way every time so a replay keeps the same request.
+ * It is what the caller says it is, never inferred (from a user agent or
+ * anything else) and never verified.
+ */
+export function declaredAgentName(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > DECLARED_NAME_LIMIT || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new CliError('native_descriptor_agent_name_invalid', `Use a coding-agent name of 1 to ${DECLARED_NAME_LIMIT} characters without control characters or credentials. Nothing was submitted.`, 2);
+    }
+    return trimmed;
+}
+function attributionMatches(value) {
+    if (value === undefined || value === null)
+        return true;
+    return object(value) && Object.keys(value).length === 4 && typeof value.actor_id === 'string' && UUID.test(value.actor_id)
+        && (value.channel === 'browser' || value.channel === 'terminal' || value.channel === 'management_mcp')
+        && value.verified_client_name === null
+        && (value.declared_agent_name === null || (typeof value.declared_agent_name === 'string' && value.declared_agent_name.length >= 1
+            && value.declared_agent_name.length <= DECLARED_NAME_LIMIT));
+}
+/** The name this request declared is the one root recorded (none when none was declared). */
+export function declaredNameRecorded(row, declared) {
+    return (row.caller_attribution?.declared_agent_name ?? null) === (declared ?? null);
+}
+function agentName(name) {
+    const trimmed = name.trim();
+    if (!trimmed || name.length > NAME_LIMIT || /[\u0000-\u001f\u007f]/.test(name)) {
+        throw new CliError('native_registration_invalid', `Use an agent name of up to ${NAME_LIMIT} characters without control characters. Nothing was submitted.`, 2);
+    }
+    return trimmed;
+}
+export function descriptorRevisionRow(value, expectedDigest, withDocument) {
+    if (!object(value) || typeof value.id !== 'string' || !UUID.test(value.id) || typeof value.agent_id !== 'string' || !UUID.test(value.agent_id)
+        || typeof value.revision !== 'number' || !Number.isSafeInteger(value.revision) || value.revision < 1
+        || typeof value.descriptor_sha256 !== 'string' || !SHA256_HEX.test(value.descriptor_sha256)
+        || value.origin !== 'local_descriptor' || value.provenance !== 'customer_declared'
+        || typeof value.requires_serial_execution !== 'boolean' || typeof value.created_at !== 'string'
+        || !attributionMatches(value.caller_attribution))
+        throw unconfirmed();
+    if (expectedDigest !== null && value.descriptor_sha256 !== expectedDigest) {
+        throw new CliError('native_descriptor_digest_mismatch', 'The service recorded a different descriptor digest than this CLI computed. Do not run a plan against it; update the CLI or report the mismatch.');
+    }
+    if (withDocument && (!object(value.descriptor) || !Array.isArray(value.startup_order)
+        || value.startup_order.some(alias => typeof alias !== 'string')))
+        throw unconfirmed();
+    return value;
+}
+/**
+ * Registers a new local agent from a descriptor. The descriptor is normalized
+ * locally first so invalid input never leaves the machine and the returned
+ * digest can be checked against the local computation.
+ */
+export async function registerNativeAgent(scope, input) {
+    const name = agentName(input.name);
+    const declared = declaredAgentName(input.declaredAgentName);
+    const local = normalizeDescriptor(input.descriptor);
+    const requestKey = registrationKey(input.requestKey);
+    const raw = await api(`/api/workspaces/${scope.workspace}/native-agents`, {
+        method: 'POST', actor: scope.owner, workspace: scope.workspace, signal: input.signal, maximumResponseBytes: RESPONSE_LIMIT,
+        body: { request_key: requestKey, name, descriptor: local.descriptor, ...(declared === undefined ? {} : { declared_agent_name: declared }) },
+    });
+    const receipt = registrationReceiptRow(raw, local.descriptor_sha256);
+    if (!declaredNameRecorded(receipt.descriptor, declared))
+        throw unconfirmed();
+    return { ...receipt, request_key: requestKey };
+}
+/** A registration receipt `{agent_id, descriptor}`: the new agent and its first descriptor revision, with its document. */
+export function registrationReceiptRow(raw, expectedDigest) {
+    if (!object(raw) || typeof raw.agent_id !== 'string' || !UUID.test(raw.agent_id))
+        throw unconfirmed();
+    const descriptor = descriptorRevisionRow(raw.descriptor, expectedDigest, true);
+    if (descriptor.agent_id !== raw.agent_id || descriptor.revision !== 1)
+        throw unconfirmed();
+    return { agent_id: raw.agent_id, descriptor };
+}
+/**
+ * Records a new immutable descriptor revision for an existing agent. Fails with
+ * native_descriptor_revision_conflict (from the producer) if another revision
+ * landed after `expectedRevision`.
+ */
+export async function reviseNativeDescriptor(scope, input) {
+    if (!UUID.test(input.agentId))
+        throw new CliError('native_agent_invalid', 'Use the agent id from `firedrill status`. Nothing was submitted.', 2);
+    if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0) {
+        throw new CliError('native_revision_invalid', 'Use the latest descriptor revision number. Nothing was submitted.', 2);
+    }
+    const declared = declaredAgentName(input.declaredAgentName);
+    const local = normalizeDescriptor(input.descriptor);
+    const requestKey = registrationKey(input.requestKey);
+    const raw = await api(`/api/workspaces/${scope.workspace}/agents/${input.agentId}/native-descriptors`, {
+        method: 'POST', actor: scope.owner, workspace: scope.workspace, signal: input.signal, maximumResponseBytes: RESPONSE_LIMIT,
+        body: { request_key: requestKey, expected_revision: input.expectedRevision, descriptor: local.descriptor,
+            ...(declared === undefined ? {} : { declared_agent_name: declared }) },
+    });
+    const row = descriptorRevisionRow(raw, local.descriptor_sha256, true);
+    if (row.agent_id !== input.agentId.toLowerCase() || row.revision !== input.expectedRevision + 1 || !declaredNameRecorded(row, declared))
+        throw unconfirmed();
+    return { ...row, request_key: requestKey };
+}
+/** Lists descriptor history, newest first, without full documents. */
+export async function listNativeDescriptors(scope, input) {
+    if (!UUID.test(input.agentId))
+        throw new CliError('native_agent_invalid', 'Use the agent id from `firedrill status`.', 2);
+    const page = input.page ?? 1;
+    if (!Number.isSafeInteger(page) || page < 1)
+        throw new CliError('native_page_invalid', 'Use a page number of 1 or more.', 2);
+    const raw = await api(`/api/workspaces/${scope.workspace}/agents/${input.agentId}/native-descriptors?page=${page}`, {
+        actor: scope.owner, workspace: scope.workspace, signal: input.signal, maximumResponseBytes: RESPONSE_LIMIT,
+    });
+    if (!object(raw) || typeof raw.count !== 'number' || !Array.isArray(raw.results))
+        throw unconfirmed();
+    return { count: raw.count, next: typeof raw.next === 'string' ? raw.next : null,
+        previous: typeof raw.previous === 'string' ? raw.previous : null,
+        results: raw.results.map(one => descriptorRevisionRow(one, null, false)) };
+}
+/** Reads one descriptor revision with its full document and startup order. */
+export async function getNativeDescriptor(scope, input) {
+    if (!UUID.test(input.agentId) || !UUID.test(input.descriptorId)) {
+        throw new CliError('native_descriptor_invalid_id', 'Use the agent and descriptor ids from the descriptor history.', 2);
+    }
+    const raw = await api(`/api/workspaces/${scope.workspace}/agents/${input.agentId}/native-descriptors/${input.descriptorId}`, {
+        actor: scope.owner, workspace: scope.workspace, signal: input.signal, maximumResponseBytes: RESPONSE_LIMIT,
+    });
+    return descriptorRevisionRow(raw, null, true);
+}

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

@@ -0,0 +1,110 @@
+/**
+ * Local source roots (Plan20 W09).
+ *
+ * A root is a directory on this machine that the user approved for the local
+ * plan. Its identity digest binds the session plan to the exact directory
+ * (real path plus device and inode) without sending the path to the cloud.
+ * Paths inside a root are resolved with realpath and refused if they escape it,
+ * including through symbolic links. This is path discipline, not an OS sandbox:
+ * approved processes still run with the user's full permissions.
+ */
+import { createHash } from 'node:crypto';
+import { realpath, stat } from 'node:fs/promises';
+import { isAbsolute, join, posix, resolve, sep, win32 } from 'node:path';
+import { CliError } from '../http.js';
+import { nativeError } from './contracts.js';
+const ROOT_IDENTITY_PREFIX = 'firedrill.root-identity.v1\0';
+const MAX_PATH = 4096;
+const rootInvalid = () => new CliError('native_root_invalid', 'The selected root is not an existing directory owned by you. No plan was prepared for it.', 2);
+const outside = () => nativeError('root_outside', 'An approved path resolves outside its root, or is absolute or uses "..". Nothing was started from it.', 2);
+/**
+ * True when `relative` is a syntactically safe path inside a root: not absolute
+ * on any platform, no drive prefix, no ".." segment, no NUL, bounded length.
+ * Empty and "." mean the root itself. Symlinks are checked later by `insideRoot`.
+ */
+export function isSafeRelativePath(relative) {
+    if (typeof relative !== 'string' || relative.length > MAX_PATH || relative.includes('\0'))
+        return false;
+    if (posix.isAbsolute(relative) || win32.isAbsolute(relative) || /^[A-Za-z]:/.test(relative))
+        return false;
+    return !relative.split(/[\\/]+/).some(segment => segment === '..');
+}
+function samePath(a, b) {
+    return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+function contains(root, candidate) {
+    if (samePath(root, candidate))
+        return true;
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    return process.platform === 'win32'
+        ? candidate.toLowerCase().startsWith(prefix.toLowerCase())
+        : candidate.startsWith(prefix);
+}
+/**
+ * Resolve a root directory: realpath, must be a directory, and on POSIX must be
+ * owned by the current user. Identity is sha256 over the v1 prefix, the real
+ * path, a NUL separator and `<device>:<inode>`. Windows has no comparable owner
+ * check here; ownership is not asserted there.
+ */
+export async function resolveRoot(path) {
+    if (typeof path !== 'string' || !path || path.length > MAX_PATH || path.includes('\0'))
+        throw rootInvalid();
+    let real;
+    let details;
+    try {
+        real = await realpath(resolve(path));
+        details = await stat(real, { bigint: true });
+    }
+    catch {
+        throw rootInvalid();
+    }
+    if (!details.isDirectory())
+        throw rootInvalid();
+    if (typeof process.getuid === 'function' && details.uid !== BigInt(process.getuid()))
+        throw rootInvalid();
+    const identity = createHash('sha256').update(ROOT_IDENTITY_PREFIX).update(real).update('\0')
+        .update(`${details.dev}:${details.ino}`).digest('hex');
+    return { path: real, identity_sha256: identity };
+}
+/**
+ * Resolve `relative` inside `root` and return its real path. Refuses absolute
+ * input, ".." segments and any symbolic link that resolves outside the root
+ * (`native_root_outside`). The target must exist (`native_path_unavailable`).
+ */
+export async function insideRoot(root, relative) {
+    if (!isSafeRelativePath(relative) || typeof root !== 'string' || !isAbsolute(root))
+        throw outside();
+    let realRoot;
+    try {
+        realRoot = await realpath(root);
+    }
+    catch {
+        throw rootInvalid();
+    }
+    let real;
+    try {
+        real = await realpath(join(realRoot, relative));
+    }
+    catch {
+        throw new CliError('native_path_unavailable', 'An approved path does not exist inside its root. Nothing was started from it.', 2);
+    }
+    if (!contains(realRoot, real))
+        throw outside();
+    return real;
+}
+/**
+ * Resolve every plan root and confirm it is still the same directory the plan
+ * was approved for. Returns alias -> real path. A changed identity is
+ * `native_plan_changed`: the plan must be reviewed and approved again.
+ */
+export async function resolvePlanRoots(plan) {
+    const roots = new Map();
+    for (const entry of plan.roots) {
+        const resolved = await resolveRoot(entry.path);
+        if (resolved.identity_sha256 !== entry.identity_sha256) {
+            throw nativeError('plan_changed', 'A plan root no longer matches the directory it was approved for. Review and approve the plan again; nothing was started.', 2);
+        }
+        roots.set(entry.alias, resolved.path);
+    }
+    return roots;
+}