@byokit/openclaw 0.5.1 → 0.6.2

package/dist/device.js

@@ -1,8 +1,6 @@
-// The device side (7.2): portable — browsers, React Native, Node; no node:* or Node-only imports may reach here
-// (test/portable.test.ts guards it). Only type imports from @byokit/link; the seal crypto bundles cleanly.
-import { boxKeyPairFromSeed } from '@byokit/seal';
+import { openBoxFromSeed, boxKeyPairFromSeed } from '@byokit/seal';
 import { toAccountView } from "./words.js";
-import { b64urlEncode, openNotice } from "./notices.js";
+import { b64urlDecode, b64urlEncode, openNotice } from "./notices.js";
 /**
  * The host ended a stream with its own words (e.g. a refusal). Portable twin of link's PublicLinkError:
  * same shape ({ code: 'failed', sealed: true }) so a screen can show .message the same way. A device-side
@@ -16,6 +14,10 @@ export class LinkRefused extends Error {
         this.name = 'LinkRefused';
     }
 }
+export class BrowserRefused extends LinkRefused {
+    why;
+    constructor(why) { super(`Sign-in refused: ${why}`); this.why = why; }
+}
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 /**
  * Newline-delimited JSON frames off a link stream, in order. A host end with an error becomes a
@@ -115,8 +117,223 @@ function liveStream(open) {
         },
     };
 }
+/** A sealed hint, never an authorization or a lease. Re-fetch signIns() before taking any action. */
+export function openSignInNotice(data, seed) {
+    if (data.v !== 1 || typeof data.sealed !== 'string' || !(seed instanceof Uint8Array) || seed.length !== 32)
+        return null;
+    const bundle = b64urlDecode(data.sealed);
+    const bytes = bundle && openBoxFromSeed(bundle, seed);
+    if (!bytes)
+        return null;
+    try {
+        const v = JSON.parse(new TextDecoder().decode(bytes));
+        if (!isRecord(v) || v.source !== 'signin' || typeof v.id !== 'string' || !Number.isSafeInteger(v.gen)
+            || typeof v.member !== 'string' || typeof v.site !== 'string')
+            return null;
+        return { source: 'signin', id: v.id, gen: v.gen, member: v.member, site: v.site };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        bytes.fill(0);
+    }
+}
+function decodeBrowserFrame(value) {
+    if (!isRecord(value) || typeof value.jpeg !== 'string' || value.jpeg.length > 8 * 1024 * 1024
+        || !Number.isSafeInteger(value.seq) || !Number.isSafeInteger(value.w) || !Number.isSafeInteger(value.h)
+        || value.w < 1 || value.h < 1 || typeof value.at !== 'number' || !Number.isFinite(value.at))
+        throw new LinkRefused('Invalid browser frame');
+    const jpeg = b64urlDecode(value.jpeg);
+    if (!jpeg)
+        throw new LinkRefused('Invalid browser frame');
+    return { seq: value.seq, w: value.w, h: value.h, at: value.at, jpeg };
+}
+/** Transient streams bypass link's durable request/answer cache: no lease nonce or frame is persisted. */
+export function browserDevice(link) {
+    const call = async (op, args = {}) => {
+        const it = liveStream(() => link.stream(`oc.browser.${op}`, args))[Symbol.asyncIterator]();
+        try {
+            const reply = await it.next();
+            if (!reply.done && isRecord(reply.value) && typeof reply.value.refused === 'string')
+                throw new BrowserRefused(reply.value.refused);
+            if (reply.done || !isRecord(reply.value) || !('value' in reply.value))
+                throw new LinkRefused('Browser request ended');
+            return reply.value.value;
+        }
+        finally {
+            await it.return?.();
+        }
+    };
+    return {
+        state: member => call('state', { member }),
+        signIns: () => call('signins'),
+        takeover: (id, gen, o) => call('takeover', { id, gen, ...o }),
+        confirmOrigin: async (lease, origin) => { await call('confirmorigin', { lease, origin }); },
+        done: lease => call('done', { lease }),
+        notNow: (id, gen) => call('notnow', { id, gen }),
+        reopen: (id, gen) => call('reopen', { id, gen }),
+        retry: (id, gen) => call('retry', { id, gen }),
+        cancel: (id, gen) => call('cancel', { id, gen }),
+        forget: async (member, site) => { await call('forget', { member, site }); },
+        thumbnail: async (source) => {
+            const result = await call('thumb', { source });
+            return result.state === 'ok' ? { state: 'ok', frame: decodeBrowserFrame(result.frame) } : result;
+        },
+        live: (source, o) => {
+            let stream;
+            let closed = false;
+            let ended = false;
+            let inputBusy = false;
+            let inputBytes = 0;
+            const inputs = [];
+            let text = '';
+            let frame;
+            let state = { source, mode: o?.lease ? 'control' : 'observe', phase: 'connecting' };
+            const frameWaiters = new Set();
+            const stateWaiters = new Set();
+            const wake = () => {
+                for (const w of [...frameWaiters, ...stateWaiters])
+                    w();
+                frameWaiters.clear();
+                stateWaiters.clear();
+            };
+            const close = () => {
+                closed = ended = true;
+                frame = undefined;
+                state = undefined;
+                text = '';
+                inputs.length = 0;
+                inputBytes = 0;
+                stream?.end('closed');
+                wake();
+            };
+            const finish = (error) => {
+                if (closed || ended)
+                    return;
+                ended = true;
+                frame = undefined;
+                text = '';
+                inputs.length = 0;
+                inputBytes = 0;
+                state = { source, mode: o?.lease ? 'control' : 'observe',
+                    phase: error === 'unreachable' ? 'reconnecting' : error ? 'failed' : 'ended',
+                    ...(error === 'removed' ? { why: 'revoked' } : {}) };
+                wake();
+            };
+            const flushInput = async () => {
+                if (inputBusy || !stream || closed || ended)
+                    return;
+                inputBusy = true;
+                try {
+                    while (inputs.length && !closed && !ended) {
+                        const value = inputs.shift();
+                        await stream.write(value);
+                        if (!closed && !ended)
+                            inputBytes -= new TextEncoder().encode(value).byteLength;
+                    }
+                }
+                catch {
+                    finish('failed');
+                    stream.end('failed');
+                }
+                finally {
+                    inputBusy = false;
+                }
+            };
+            const decoder = new TextDecoder();
+            void link.stream('oc.browser.live', { source, mode: o?.lease ? 'control' : 'observe', ...o }).then(s => {
+                if (closed) {
+                    s.end();
+                    return;
+                }
+                stream = s;
+                s.onData = chunk => {
+                    if (closed || ended)
+                        return;
+                    try {
+                        text += decoder.decode(chunk, { stream: true });
+                        if (text.length > 9 * 1024 * 1024)
+                            throw new Error();
+                        let at;
+                        while ((at = text.indexOf('\n')) >= 0) {
+                            const v = JSON.parse(text.slice(0, at));
+                            text = text.slice(at + 1);
+                            if (!isRecord(v))
+                                throw new Error();
+                            if ('frame' in v)
+                                frame = decodeBrowserFrame(v.frame);
+                            else if (isRecord(v.state)) {
+                                state = v.state;
+                                if (state.phase !== 'live')
+                                    frame = undefined;
+                                if (state.phase === 'ended' || state.phase === 'failed') {
+                                    ended = true;
+                                    inputs.length = 0;
+                                    inputBytes = 0;
+                                }
+                            }
+                            else
+                                throw new Error();
+                        }
+                        wake();
+                    }
+                    catch {
+                        finish('failed');
+                        s.end('failed');
+                    }
+                };
+                s.onEnd = finish;
+            }, () => finish('failed'));
+            const channel = (take, waiters) => ({
+                [Symbol.asyncIterator]() {
+                    return {
+                        async next() {
+                            for (;;) {
+                                if (closed)
+                                    return { value: undefined, done: true };
+                                const value = take();
+                                if (value !== undefined)
+                                    return { value, done: false };
+                                if (ended)
+                                    return { value: undefined, done: true };
+                                await new Promise(resolve => waiters.add(resolve));
+                            }
+                        },
+                        async return() { close(); return { value: undefined, done: true }; },
+                    };
+                },
+            });
+            return {
+                states: channel(() => { const s = state; state = undefined; return s; }, stateWaiters),
+                frames: channel(() => { const f = frame; frame = undefined; return f; }, frameWaiters),
+                input: i => {
+                    // Ordered, bounded memory-only input while online. Never replay secret input after a drop.
+                    if (closed || ended || !o?.lease)
+                        return;
+                    if (!stream) {
+                        finish('failed');
+                        return;
+                    }
+                    const value = `${JSON.stringify(i)}\n`;
+                    const bytes = new TextEncoder().encode(value).byteLength;
+                    if (inputBytes + bytes > 65536) {
+                        finish('failed');
+                        stream.end('failed');
+                        return;
+                    }
+                    inputs.push(value);
+                    inputBytes += bytes;
+                    void flushInput();
+                },
+                close,
+            };
+        },
+    };
+}
 export function openclawDevice(link) {
     return {
+        browser: browserDevice(link),
         state: () => link.request('oc.state'),
         routes: () => link.request('oc.routes'),
         signIn: {
@@ -186,10 +403,13 @@ export function openclawDevice(link) {
             await link.request('oc.notices.register', { boxPublicKey: b64urlEncode(boxKeyPairFromSeed(seed).publicKey) });
         },
         openNotice,
+        callDynamic: (method, params) => link.request('oc.call', { method, params }),
         call: (method, params) => link.request('oc.call', { method, params }),
     };
 }
 // Portable, re-exported by ./device (7.3).
 export { openNotice } from "./notices.js";
+export { readAgentUsage, agentUsageOf } from "./usage.js";
+export { readAgentDayUsage } from "./day-usage.js";
 // The kit's sentences, so a phone or browser shows the same words the computer does (5.14).
 export { stateWords, toAccountView, words } from "./words.js";

package/dist/engine-patches.d.ts

@@ -0,0 +1,36 @@
+export type PatchFile = {
+    path: string;
+    before: string;
+    after: string;
+    edits: {
+        find: string;
+        replace: string;
+    }[];
+};
+export type PatchSet = {
+    v: 1;
+    id: string;
+    upstream: {
+        name: string;
+        version: string;
+        integrity: string;
+        commit: string;
+        license: string;
+    };
+    files: PatchFile[];
+};
+export declare class EnginePatchError extends Error {
+    readonly code = "engine-patch";
+    readonly cause: 'spec' | 'drift' | 'drift-after-build' | 'write';
+    readonly file?: string;
+    constructor(cause: EnginePatchError['cause'], file?: string);
+}
+export declare const sha256: (text: string | Buffer) => string;
+export declare const patchId: (files: PatchFile[]) => string;
+export declare function readPatchSet(path: string, version: string, integrity: string): PatchSet;
+export declare function editText(text: string, file: PatchFile): string;
+export declare function atomic(path: string, text: string): void;
+export declare function processStartTime(pid: number): string;
+export declare function verifyEngineSet(dir: string, set: PatchSet, installMatches: (dir: string) => boolean): void;
+export declare function engineSetName(set: PatchSet): string;
+export declare function prepareEngineSet(engineDir: string, set: PatchSet, install: (dir: string) => void | Promise<void>, installMatches: (dir: string) => boolean): Promise<string>;

package/dist/engine-patches.js

@@ -0,0 +1,320 @@
+// Internal artifact seam. Published patch semantics live only in engine/patches.json.
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { chmod, cp, open, readdir, rm } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+export class EnginePatchError extends Error {
+    code = 'engine-patch';
+    cause;
+    file;
+    constructor(cause, file) {
+        super(`engine-patch: ${cause}${file ? ` (${file})` : ''}`);
+        this.name = 'EnginePatchError';
+        this.cause = cause;
+        this.file = file;
+    }
+}
+export const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, canonical(item)]));
+    return value;
+}
+export const patchId = (files) => sha256(JSON.stringify(canonical(files))).slice(0, 16);
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const keys = (v, expected) => Object.keys(v).sort().join(',') === expected.sort().join(',');
+function validateFiles(id, files) {
+    if (typeof id !== 'string' || !Array.isArray(files))
+        throw new EnginePatchError('spec');
+    const paths = new Set();
+    for (const f of files) {
+        if (!object(f) || !keys(f, ['path', 'before', 'after', 'edits']) || typeof f.path !== 'string' ||
+            !/^dist\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_.-]+\.m?js$/.test(f.path) || f.path.split('/').some(p => p === '.' || p === '..') || paths.has(f.path) ||
+            typeof f.before !== 'string' || !/^[a-f0-9]{64}$/.test(f.before) || typeof f.after !== 'string' || !/^[a-f0-9]{64}$/.test(f.after) || f.before === f.after ||
+            !Array.isArray(f.edits) || !f.edits.length)
+            throw new EnginePatchError('spec');
+        paths.add(f.path);
+        for (const e of f.edits)
+            if (!object(e) || !keys(e, ['find', 'replace']) || typeof e.find !== 'string' || !e.find || typeof e.replace !== 'string' || !e.replace || e.find === e.replace)
+                throw new EnginePatchError('spec');
+    }
+    if (id !== patchId(files))
+        throw new EnginePatchError('spec');
+}
+export function readPatchSet(path, version, integrity) {
+    try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        if (!object(value) || !keys(value, ['v', 'id', 'upstream', 'files']) || value.v !== 1 || !object(value.upstream) ||
+            !keys(value.upstream, ['name', 'version', 'integrity', 'commit', 'license']) || value.upstream.name !== 'openclaw' || value.upstream.version !== version ||
+            value.upstream.integrity !== integrity || value.upstream.license !== 'MIT' || typeof value.upstream.commit !== 'string' || !/^[a-f0-9]{40}$/.test(value.upstream.commit))
+            throw new Error();
+        validateFiles(value.id, value.files);
+        return value;
+    }
+    catch {
+        throw new EnginePatchError('spec', path);
+    }
+}
+export function editText(text, file) {
+    for (const edit of file.edits) {
+        const at = text.indexOf(edit.find);
+        if (at < 0 || text.indexOf(edit.find, at + 1) >= 0)
+            throw new EnginePatchError('spec', file.path);
+        text = text.slice(0, at) + edit.replace + text.slice(at + edit.find.length);
+    }
+    return text;
+}
+export function atomic(path, text) {
+    const temp = `${path}.${randomUUID()}.tmp`;
+    let fd;
+    try {
+        fd = openSync(temp, 'wx', 0o600);
+        writeFileSync(fd, text);
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        renameSync(temp, path);
+        syncDir(dirname(path));
+    }
+    catch {
+        throw new EnginePatchError('write', path);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        rmSync(temp, { force: true });
+    }
+}
+const syncDir = (path) => { const fd = openSync(path, 'r'); try {
+    fsyncSync(fd);
+}
+finally {
+    closeSync(fd);
+} };
+export function processStartTime(pid) {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const startTime = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+    if (!startTime || !/^\d+$/.test(startTime))
+        throw new EnginePatchError('write');
+    return startTime;
+}
+const noLink = (path) => { if (lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink())
+    throw new EnginePatchError('spec', path); };
+const inside = (root, path) => { const rel = relative(root, path); return rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep); };
+function tree(dir) {
+    const result = [];
+    const root = realpathSync(dir);
+    const walk = (path, rel) => {
+        const info = lstatSync(path);
+        if (info.isSymbolicLink()) {
+            const link = readlinkSync(path);
+            if (resolve(link) === link || !inside(root, realpathSync(path)))
+                throw new EnginePatchError('spec', rel);
+            result.push({ path: rel, kind: 'link', mode: info.mode & 0o777, size: info.size, hash: sha256(link) });
+            return;
+        }
+        if (info.isDirectory()) {
+            for (const name of readdirSync(path).sort()) {
+                if (!rel && ['.byokit-tree', '.byokit-patches'].includes(name))
+                    continue;
+                walk(join(path, name), rel ? `${rel}/${name}` : name);
+            }
+            result.push({ path: rel, kind: 'dir', mode: info.mode & 0o777, size: 0, hash: '' });
+            return;
+        }
+        if (!info.isFile())
+            throw new EnginePatchError('spec', rel);
+        const hash = sha256(readFileSync(path));
+        result.push({ path: rel, kind: 'file', mode: info.mode & 0o777, size: info.size, hash });
+    };
+    walk(dir, '');
+    return result.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+function metadata(dir, set) {
+    const root = join(dir, 'node_modules/openclaw');
+    const build = JSON.parse(readFileSync(join(root, 'dist/build-info.json'), 'utf8'));
+    if (build.version !== set.upstream.version || build.commit !== set.upstream.commit || JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version !== set.upstream.version)
+        throw new EnginePatchError('drift', 'dist/build-info.json');
+    for (const file of set.files) {
+        const path = join(root, file.path);
+        if (!inside(realpathSync(root), realpathSync(path)) || lstatSync(path).isSymbolicLink() || sha256(readFileSync(path)) !== file.after)
+            throw new EnginePatchError('drift', file.path);
+    }
+}
+// Full verification on EVERY prepare/adoption, not just listed patched files or the directory mode.
+export function verifyEngineSet(dir, set, installMatches) {
+    noLink(dir);
+    try {
+        for (const name of ['.byokit-tree', '.byokit-patches']) {
+            const info = lstatSync(join(dir, name));
+            if (!info.isFile() || (info.mode & 0o777) !== 0o444)
+                throw new Error();
+        }
+        const bytes = readFileSync(join(dir, '.byokit-tree'), 'utf8');
+        const marker = JSON.parse(readFileSync(join(dir, '.byokit-patches'), 'utf8'));
+        if (!object(marker) || !keys(marker, ['id', 'files', 'tree']) || marker.id !== set.id || JSON.stringify(marker.files) !== JSON.stringify(set.files) || marker.tree !== sha256(bytes))
+            throw new Error();
+        metadata(dir, set);
+        if (!installMatches(dir) || bytes !== JSON.stringify(tree(dir)))
+            throw new Error();
+    }
+    catch (error) {
+        if (error instanceof EnginePatchError && error.cause === 'spec')
+            throw error;
+        throw new EnginePatchError('drift', dir);
+    }
+}
+// chmod/remove only this invocation's unlaunched private temp, never a final set or the base install.
+async function removeTemp(dir) {
+    if (!existsSync(dir))
+        return;
+    const walk = async (path) => {
+        if (!lstatSync(path).isDirectory())
+            return;
+        await chmod(path, 0o700);
+        for (const name of await readdir(path))
+            await walk(join(path, name));
+    };
+    await walk(dir);
+    await rm(dir, { recursive: true, force: true });
+}
+async function freeze(dir) {
+    const entries = tree(dir);
+    // Bound descriptors/I/O while yielding the host event loop. Every regular file and directory is fsynced.
+    const paths = [...entries.filter(e => e.kind === 'file'), ...entries.filter(e => e.kind === 'dir').reverse()];
+    for (let i = 0; i < paths.length; i += 16)
+        await Promise.all(paths.slice(i, i + 16).map(async (entry) => {
+            const path = join(dir, entry.path);
+            await chmod(path, entry.kind === 'dir' ? 0o555 : 0o444);
+            const fd = await open(path, 'r');
+            try {
+                await fd.sync();
+            }
+            finally {
+                await fd.close();
+            }
+        }));
+}
+export function engineSetName(set) { return `${sha256(set.upstream.integrity).slice(0, 16)}-${set.id}`; }
+export async function prepareEngineSet(engineDir, set, install, installMatches) {
+    validateFiles(set.id, set.files);
+    const sets = `${engineDir}.sets`;
+    noLink(sets);
+    mkdirSync(sets, { recursive: true, mode: 0o700 });
+    const name = engineSetName(set);
+    for (const candidate of readdirSync(sets).filter(n => n === name || n.startsWith(`${name}.`)).sort()) {
+        const dir = join(sets, candidate);
+        try {
+            verifyEngineSet(dir, set, installMatches);
+            return dir;
+        }
+        catch (error) {
+            if (!(error instanceof EnginePatchError) || error.cause !== 'drift')
+                throw error;
+        }
+    }
+    const stock = { ...set, id: patchId([]), files: [] };
+    const stockDir = set.files.length ? await prepareEngineSet(engineDir, stock, install, installMatches) : undefined;
+    const tmp = join(sets, `.tmp-${process.pid}-${process.platform === 'linux' ? processStartTime(process.pid) : 'unknown'}-${randomUUID()}`);
+    const final = join(sets, existsSync(join(sets, name)) ? `${name}.${randomUUID()}` : name);
+    try {
+        if (stockDir) {
+            // ponytail: reflink or plain copy, never hardlinks; no GC without per-launch leases (~889 MB/set).
+            await cp(stockDir, tmp, { recursive: true, verbatimSymlinks: true, mode: constants.COPYFILE_FICLONE });
+            // The copy is private and unlaunched. Make only it writable, and drop inherited provenance.
+            const writable = async (path) => {
+                const info = lstatSync(path);
+                if (info.isSymbolicLink())
+                    return;
+                await chmod(path, info.isDirectory() ? 0o700 : 0o600);
+                if (info.isDirectory())
+                    for (const name of await readdir(path))
+                        await writable(join(path, name));
+            };
+            await writable(tmp);
+            rmSync(join(tmp, '.byokit-tree'));
+            rmSync(join(tmp, '.byokit-patches'));
+        }
+        else {
+            mkdirSync(tmp, { mode: 0o700 });
+            await install(tmp);
+        }
+        if (!installMatches(tmp))
+            throw new EnginePatchError('drift-after-build', tmp);
+        const root = join(tmp, 'node_modules/openclaw');
+        for (const file of set.files) {
+            const path = join(root, file.path);
+            if (!inside(realpathSync(root), realpathSync(path)) || lstatSync(path).isSymbolicLink())
+                throw new EnginePatchError('spec', file.path);
+            const before = readFileSync(path, 'utf8');
+            if (sha256(before) !== file.before)
+                throw new EnginePatchError('drift-after-build', file.path);
+            const after = editText(before, file);
+            if (sha256(after) !== file.after)
+                throw new EnginePatchError('spec', file.path);
+            atomic(path, after);
+        }
+        metadata(tmp, set);
+        await freeze(tmp);
+        const bytes = JSON.stringify(tree(tmp));
+        // Root alone is writable while publishing metadata, then made read-only too.
+        await chmod(tmp, 0o700);
+        atomic(join(tmp, '.byokit-tree'), bytes);
+        atomic(join(tmp, '.byokit-patches'), JSON.stringify({ id: set.id, files: set.files, tree: sha256(bytes) }));
+        for (const file of ['.byokit-tree', '.byokit-patches']) {
+            const path = join(tmp, file);
+            await chmod(path, 0o444);
+            const fd = await open(path, 'r');
+            try {
+                await fd.sync();
+            }
+            finally {
+                await fd.close();
+            }
+        }
+        await chmod(tmp, 0o555);
+        const directory = await open(tmp, 'r');
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+        try {
+            verifyEngineSet(tmp, set, installMatches);
+        }
+        catch (error) {
+            if (error instanceof EnginePatchError && error.cause === 'drift')
+                throw new EnginePatchError('drift-after-build', error.file);
+            throw error;
+        }
+        try {
+            renameSync(tmp, final);
+            syncDir(sets);
+        }
+        catch (error) {
+            if (!['ENOTEMPTY', 'EEXIST', 'EPERM'].includes(error.code ?? ''))
+                throw error;
+            try {
+                verifyEngineSet(final, set, installMatches);
+            }
+            catch {
+                throw new EnginePatchError('drift-after-build', final);
+            }
+        }
+        return final;
+    }
+    catch (error) {
+        if (error instanceof EnginePatchError) {
+            if (error.cause === 'drift')
+                throw new EnginePatchError('drift-after-build', error.file);
+            throw error;
+        }
+        throw new EnginePatchError('write', tmp);
+    }
+    finally {
+        await removeTemp(tmp);
+    }
+}

package/dist/engine-status.d.ts

@@ -1,3 +1,16 @@
+import type { ChildProcess } from 'node:child_process';
+/** Every process the kit itself spawned, held for shutdown by pid. */
+export declare class StartedProcesses {
+    private readonly started;
+    /** Record a spawn. Its pid is the kit's to signal; nothing else about it is. */
+    add(child: ChildProcess): void;
+    forget(child: ChildProcess | undefined): void;
+    /** SIGTERM each recorded pid, wait, SIGKILL the ones still running, wait. Never signals a process group. */
+    terminate(wait: (ms: number) => Promise<void>, graceMs?: number): Promise<void>;
+    private live;
+    private signal;
+    private settle;
+}
 /** A live or unverifiable writer still owns the isolated engine state. Retry after it stops. */
 export declare class EngineAlreadyRunningError extends Error {
     readonly code = "engine-already-running";

package/dist/engine-status.js

@@ -1,4 +1,35 @@
 import { readFileSync } from 'node:fs';
+/** Every process the kit itself spawned, held for shutdown by pid. */
+export class StartedProcesses {
+    started = new Set();
+    /** Record a spawn. Its pid is the kit's to signal; nothing else about it is. */
+    add(child) { this.started.add(child); }
+    forget(child) { if (child)
+        this.started.delete(child); }
+    /** SIGTERM each recorded pid, wait, SIGKILL the ones still running, wait. Never signals a process group. */
+    async terminate(wait, graceMs = 3000) {
+        for (const child of this.live())
+            this.signal(child, 'SIGTERM');
+        await this.settle(wait, graceMs);
+        for (const child of this.live())
+            this.signal(child, 'SIGKILL');
+        await this.settle(wait, graceMs);
+    }
+    live() { return [...this.started].filter(child => child.exitCode === null && child.signalCode === null); }
+    signal(child, sig) {
+        const { pid } = child;
+        if (pid === undefined)
+            return;
+        try {
+            process.kill(pid, sig);
+        }
+        catch { /* already gone */ }
+    }
+    async settle(wait, graceMs) {
+        for (let waited = 200; waited <= graceMs && this.live().length; waited += 200)
+            await wait(200);
+    }
+}
 /** A live or unverifiable writer still owns the isolated engine state. Retry after it stops. */
 export class EngineAlreadyRunningError extends Error {
     code = 'engine-already-running';