@eyeauras/insight-cli 0.1.0 → 0.2.1

package/dist/src/tool-runtime/installer.js

@@ -0,0 +1,180 @@
+import { mkdir, stat, rm, readdir, writeFile, readFile } from 'node:fs/promises';
+import { join, resolve, sep, dirname } from 'node:path';
+import { cacheArtifact, consumeArchive, extractArchive, fileSha256, archiveName } from './archives.js';
+import { atomicWrite, readJson, toolRoot, withToolLock, installationStage, removeInstallation, treeFingerprint, assertUnused, withToolUse } from './store.js';
+import { listProcesses } from './supervisor.js';
+import { digest, fail, text } from '../model.js';
+/** Read-only verification used by an owned child after the command owner has staged a runtime. */
+export async function verifyManagedInstallation(directory, tool, selected) {
+    const root = join(toolRoot(directory, tool), 'installations', selected.id);
+    if (selected.schema !== 1 || selected.tool !== tool || selected.mode !== 'managed' || selected.uninstalledAt || !/^[a-f0-9]{64}$/.test(selected.id) || selected.root !== root || !resolve(selected.executable).startsWith(resolve(root) + sep))
+        fail('binding', 'Invalid managed tool installation receipt.');
+    const ready = await readJson(join(root, 'ready.json'));
+    const binding = (v) => { const { selectedAt, uninstalledAt, ...rest } = v; return rest; };
+    if (!ready || digest(binding(ready)) !== digest(binding(selected)))
+        fail('binding', 'Managed tool receipt differs from its verified installation.');
+    if (await treeFingerprint(root) !== selected.fingerprint)
+        fail('binding', 'Managed tool code differs from its verified installation.');
+}
+/** Standard archive-based tools supply layout and a real probe; exceptional tools reuse the stage primitives. */
+export class ToolInstaller {
+    c;
+    descriptor;
+    directory;
+    root;
+    cache;
+    constructor(c, descriptor) {
+        this.c = c;
+        this.descriptor = descriptor;
+        this.directory = c.appArguments.AppDataDirectory;
+        this.root = toolRoot(this.directory, descriptor.id);
+        this.cache = join(this.directory, 'runtime/cache');
+    }
+    async receipt() { return readJson(join(this.root, 'selection.json')); }
+    async status() {
+        const selected = await this.receipt();
+        let present = false;
+        if (selected && !selected.uninstalledAt)
+            try {
+                present = (await stat(selected.executable)).isFile() && (selected.mode === 'external' || Boolean(await readJson(join(this.root, 'installations', selected.id, 'ready.json'))));
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT')
+                    throw e;
+            }
+        const stages = await readdir(join(this.root, 'stages')).catch(e => { if (e.code === 'ENOENT')
+            return []; throw e; });
+        const processes = (await listProcesses(this.directory, { tool: this.descriptor.id })).filter(r => !['exited', 'failed'].includes(r.state));
+        return { retainedStages: stages.slice(0, 100), processes, tool: this.descriptor.id, state: present ? 'installed' : 'not_ready', mode: selected?.mode ?? 'unconfigured', installation: selected?.id, executable: selected?.executable, components: selected?.components ?? {}, lastProbe: selected?.lastProbe, recommended: 'managed' };
+    }
+    async download(offline = false, vendorDirect = false) {
+        const items = [];
+        for (const [component, a] of Object.entries(this.descriptor.components()))
+            items.push({ component, path: await cacheArtifact(a, this.cache, this.c.fetch, this.c.signal, offline, vendorDirect), sha256: a.sha256, license: a.license, url: a.url, delivery: a.delivery ?? { kind: 'owned-release' } });
+        return { tool: this.descriptor.id, state: 'downloaded', items };
+    }
+    async install(o) {
+        return withToolLock(this.directory, this.descriptor.id, async () => {
+            await assertUnused(this.directory, this.descriptor.id);
+            if (o.executable && o.archive)
+                fail('invalid', 'Choose --executable or --archive.');
+            const external = o.executable ? resolve(this.c.cwd, text(o.executable, 4096)) : undefined, parts = external ? {} : this.descriptor.components(), consumed = {};
+            for (const [id, artifact] of Object.entries(parts)) {
+                const key = id === this.descriptor.primary ? 'archive' : id + 'Archive', checksum = id === this.descriptor.primary ? 'archiveSha256' : id + 'ArchiveSha256';
+                if (o[checksum] && !o[key])
+                    fail('invalid', 'Archive checksum requires its archive path.');
+                consumed[id] = o[key] ? await consumeArchive(resolve(this.c.cwd, text(o[key], 4096)), this.cache, artifact, o[checksum] === undefined ? undefined : text(o[checksum], 64), this.c.signal) : { path: await cacheArtifact(artifact, this.cache, this.c.fetch, this.c.signal, Boolean(o.offline), Boolean(o.vendorDirect)), artifact };
+            }
+            const components = Object.fromEntries(Object.entries(consumed).map(([id, v]) => [id, v.artifact.sha256]));
+            const externalDigest = external ? await fileSha256(external, this.c.signal) : undefined;
+            const externalInputs = external && this.descriptor.externalInputs ? await this.descriptor.externalInputs(external, this.c) : undefined;
+            const noticeDigest = this.descriptor.noticeFiles ? digest(this.descriptor.noticeFiles) : undefined;
+            const id = digest({ tool: this.descriptor.id, schema: 1, platform: process.platform, architecture: process.arch, external, externalDigest, components, ...(externalInputs ? { externalInputs } : {}), ...(noticeDigest ? { noticeDigest } : {}), ...(this.descriptor.preparationId ? { preparationId: this.descriptor.preparationId } : {}) });
+            const rootsAt = (directory) => Object.fromEntries(Object.entries(consumed).map(([part, v]) => { archiveName(v.artifact.root); return [part, join(directory, part, v.artifact.root)]; }));
+            const selected = await installationStage(this.root, id, async (stage, installed) => {
+                for (const [part, v] of Object.entries(consumed))
+                    await extractArchive(v.path, join(stage, part), v.artifact.format, this.c.signal);
+                if (!external)
+                    await this.descriptor.prepare?.(rootsAt(stage), this.c);
+                const execution = external ? await this.descriptor.prepareExternal?.(external, stage, this.c) : undefined;
+                if (execution && !resolve(execution.executable).startsWith(resolve(stage) + sep))
+                    fail('binding', 'Prepared external execution must use owned staging.');
+                for (const [name, body] of Object.entries(this.descriptor.noticeFiles ?? {})) {
+                    archiveName(name);
+                    if (!name || Buffer.byteLength(body) > 1024 ** 2)
+                        fail('configuration', 'Invalid bundled license notice.');
+                    const destination = join(stage, name);
+                    await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+                    await writeFile(destination, body, { flag: 'wx', mode: 0o600 });
+                }
+                const stageLaunch = external ? { executable: external, arguments: [], environment: {} } : this.descriptor.launch(rootsAt(stage));
+                const lastProbe = await this.descriptor.probe(execution ?? stageLaunch, this.c), launch = external ? stageLaunch : this.descriptor.launch(rootsAt(installed));
+                const fingerprint = external ? await fileSha256(external, this.c.signal) : await treeFingerprint(stage);
+                if (external && fingerprint !== externalDigest)
+                    fail('binding', 'External tool changed during installation.');
+                if (externalInputs && digest(await this.descriptor.externalInputs(external, this.c)) !== digest(externalInputs))
+                    fail('binding', 'External tool family changed during installation.');
+                const installedExecution = execution ? { ...execution, executable: join(installed, execution.executable.slice(stage.length + 1)) } : undefined;
+                return { schema: 1, tool: this.descriptor.id, id, mode: external ? 'external' : 'managed', root: installed, ...launch, roots: rootsAt(installed), components, fingerprint, lastProbe, ...(externalInputs ? { externalInputs } : {}), ...(noticeDigest ? { noticeDigest } : {}), ...(installedExecution ? { execution: installedExecution, executionFingerprint: await treeFingerprint(stage) } : {}), selectedAt: new Date().toISOString() };
+            }, value => this.verify(value), this.c.signal);
+            await atomicWrite(join(this.root, 'selection.json'), { ...selected, selectedAt: new Date().toISOString() });
+            return { tool: this.descriptor.id, state: 'installed', mode: selected.mode, installation: id, executable: selected.executable, components, checks: selected.lastProbe };
+        }, this.c.signal);
+    }
+    async verify(selected) {
+        if (selected.schema !== 1 || selected.tool !== this.descriptor.id || !/^[a-f0-9]{64}$/.test(selected.id))
+            fail('binding', 'Invalid tool installation receipt.');
+        const root = join(this.root, 'installations', selected.id);
+        if (selected.root !== root || selected.mode === 'managed' && !resolve(selected.executable).startsWith(resolve(root) + sep))
+            fail('binding', 'Selected tool points outside its owned installation.');
+        const ready = await readJson(join(root, 'ready.json'));
+        const binding = (v) => { const { selectedAt, uninstalledAt, ...rest } = v; return rest; };
+        if (!ready || digest(binding(ready)) !== digest(binding(selected)))
+            fail('binding', 'Selected tool receipt differs from its verified installation.');
+        if (this.descriptor.noticeFiles) {
+            if (selected.noticeDigest !== digest(this.descriptor.noticeFiles))
+                fail('binding', 'Bundled license notices changed; reinstall the selected tool.');
+            for (const [name, body] of Object.entries(this.descriptor.noticeFiles)) {
+                archiveName(name);
+                try {
+                    if (await readFile(join(root, name), 'utf8') !== body)
+                        fail('binding', 'Installed license notice differs from its retained text.');
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        fail('binding', 'Installed license notice is missing.');
+                    throw error;
+                }
+            }
+        }
+        if (selected.mode === 'managed')
+            await verifyManagedInstallation(this.directory, this.descriptor.id, selected);
+        else if (await fileSha256(selected.executable, this.c.signal) !== selected.fingerprint)
+            fail('binding', 'Selected tool code differs from its verified installation.');
+        if (selected.execution && (!resolve(selected.execution.executable).startsWith(resolve(root) + sep) || await treeFingerprint(root) !== selected.executionFingerprint))
+            fail('binding', 'Owned external-tool execution copy differs from its verified installation.');
+        if (selected.mode === 'external' && this.descriptor.externalInputs && (!selected.externalInputs || digest(await this.descriptor.externalInputs(selected.executable, this.c)) !== digest(selected.externalInputs)))
+            fail('binding', 'External tool family differs from its verified installation.');
+    }
+    async use(action) {
+        const lease = await withToolUse(this.directory, this.descriptor.id, () => this.selected(), this.c.signal);
+        try {
+            return await action({ ...lease.value, ...lease.value.execution });
+        }
+        finally {
+            lease.release();
+        }
+    }
+    async selected() {
+        const selected = await this.receipt();
+        if (!selected || selected.uninstalledAt)
+            fail('configuration', 'Tool is not installed; run insight-cli ' + this.descriptor.id + ' install.');
+        await this.verify(selected);
+        return selected;
+    }
+    async doctor() {
+        return withToolLock(this.directory, this.descriptor.id, async () => {
+            const selected = await this.selected(), checks = await this.descriptor.probe(selected.execution ?? selected, this.c);
+            await atomicWrite(join(this.root, 'last-check.json'), { fingerprint: selected.fingerprint, checkedAt: new Date().toISOString(), checks });
+            return { tool: this.descriptor.id, state: 'verified', installation: selected.id, checks };
+        }, this.c.signal);
+    }
+    async uninstall(purgeCache = false) {
+        return withToolLock(this.directory, this.descriptor.id, async () => {
+            await assertUnused(this.directory, this.descriptor.id);
+            const selected = await this.receipt();
+            if (!selected)
+                fail('configuration', 'No selected tool installation exists.');
+            await removeInstallation(this.root, selected.id);
+            if (purgeCache)
+                for (const sha of Object.values(selected.components)) {
+                    if (!/^[a-f0-9]{64}$/.test(sha))
+                        fail('binding', 'Invalid component digest.');
+                    for (const extension of ['zip', 'tgz'])
+                        await rm(join(this.cache, sha + '.' + extension), { force: true });
+                }
+            await atomicWrite(join(this.root, 'selection.json'), { ...selected, uninstalledAt: new Date().toISOString() });
+            return { tool: this.descriptor.id, state: 'uninstalled', externalInstallationPreserved: selected.mode === 'external', researchPreserved: true, materialsPreserved: true };
+        }, this.c.signal);
+    }
+}

package/dist/src/tool-runtime/launch-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tool-runtime/launch-worker.js

@@ -0,0 +1,58 @@
+/** Internal POSIX exec gate, not a daemon. The record exists before the requested executable runs. */
+import { createReadStream } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { atomicWrite, readJson } from './store.js';
+import { processIdentity } from './identity.js';
+async function main() {
+    const [directory, id, fd] = process.argv.slice(2);
+    if (!directory || !id || !/^[a-f0-9-]{36}$/.test(id))
+        throw Error('Invalid launch identity');
+    const root = await realpath(directory), path = join(root, 'runtime/processes', id + '.json');
+    const record = await readJson(path);
+    if (!record || record.id !== id || record.pid || record.ownerPid !== process.ppid)
+        throw Error('Launch owner changed');
+    let input = '';
+    for await (const b of createReadStream('', { fd: Number(fd), autoClose: true })) {
+        input += b.toString();
+        if (input.length > 4 * 1024 ** 2)
+            throw Error('Launch input exceeds its bound');
+    }
+    if (await realpath(String(record.root)) !== join(root, 'runtime/runs', id))
+        throw Error('Launch storage changed');
+    const plan = JSON.parse(input);
+    if (plan.executable !== record.executable)
+        throw Error('Launch executable changed');
+    const identity = await processIdentity(process.pid);
+    if (!identity)
+        throw Error('Launch process identity unavailable');
+    Object.assign(record, { pid: process.pid, identity: identity.birth, strongIdentity: identity.strong, processGroup: identity.group, phase: 'armed' });
+    await atomicWrite(path, record);
+    await atomicWrite(join(String(record.root), 'armed.json'), { pid: process.pid, nonce: plan.nonce });
+    for (let i = 0; i < 400; i++) {
+        const grant = await readJson(join(String(record.root), 'go.json'));
+        if (grant?.nonce === plan.nonce) {
+            try {
+                process.execve(plan.executable, [plan.executable, ...plan.arguments], plan.environment);
+            }
+            catch (error) {
+                Object.assign(record, { state: 'failed', phase: 'exec_failed', launchError: error.code ?? 'exec', endedAt: new Date().toISOString() });
+                await atomicWrite(path, record);
+                throw Error('Owned executable could not start');
+            }
+        }
+        try {
+            process.kill(Number(record.ownerPid), 0);
+        }
+        catch {
+            Object.assign(record, { state: 'failed', phase: 'owner_lost_before_exec' });
+            await atomicWrite(path, record);
+            return;
+        }
+        await delay(25);
+    }
+    Object.assign(record, { state: 'failed', phase: 'launch_grant_timeout' });
+    await atomicWrite(path, record);
+}
+await main().catch(() => { process.stderr.write('Owned tool launch gate failed.\n'); process.exitCode = 1; });

package/dist/src/tool-runtime/run.d.ts

@@ -0,0 +1,51 @@
+import { type CommandContext } from '@eyeauras/cli-factory';
+export interface RunSpec {
+    tool: string;
+    role: string;
+    installation?: string;
+    executable: string;
+    arguments?: string[];
+    environment?: Record<string, string | undefined>;
+    cwd?: string;
+    input?: string | Uint8Array;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    outputFile?: string;
+    acceptedCodes?: number[];
+    session?: string;
+    target?: string;
+    /** Adapter opt-in only after verifying its native signal/child cleanup contract. */
+    nativeDeadline?: boolean;
+    /** Adapter opt-in for exact bounded stdout/stderr bytes, including failure prefixes. */
+    retainRawOutput?: boolean;
+    /** Adapter's native helper constructor persists per-exec deadline receipts in the run root. */
+    nativeChildDeadlines?: boolean;
+    /** Hold an authenticated borrowed Windows subject handle; never assign it to the owned job. */
+    observedSubject?: {
+        pid: number;
+        birth: string;
+    };
+    /** Serialize the native singleton without introducing another service. */
+    nativeMutex?: 'procmon';
+    /** Private process-local HKCU for the admitted ProcMon child. */
+    nativeRegistry?: 'procmon';
+    metadata?: Record<string, unknown>;
+}
+export interface RunResult {
+    process: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    signal: string | null;
+    elapsedMs: number;
+    truncated: boolean;
+    diagnostics: string;
+    rawStdout?: string;
+    rawStderr?: string;
+}
+export interface RunContext {
+    appArguments: Pick<CommandContext['appArguments'], 'AppDataDirectory'>;
+    signal: AbortSignal;
+    environment: CommandContext['environment'];
+}
+export declare function runTool(c: RunContext, spec: RunSpec): Promise<RunResult>;

package/dist/src/tool-runtime/run.js

@@ -0,0 +1,159 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, isAbsolute, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { CliError } from '@eyeauras/cli-factory';
+import { atomicWrite, withToolUse, toolRoot, readJson } from './store.js';
+import { launchProcess } from './supervisor.js';
+import { digest } from '../model.js';
+import { deadlineLaunch } from './deadline.js';
+import { windowsJobLaunch, windowsJobResult } from './windows-job.js';
+export async function runTool(c, spec) {
+    c.signal.throwIfAborted();
+    const directory = c.appArguments.AppDataDirectory;
+    toolRoot(directory, spec.tool);
+    if (!isAbsolute(spec.executable))
+        throw new CliError('Tool executable must be an absolute path.', { code: 'tool.configuration' });
+    if ((spec.observedSubject || spec.nativeMutex || spec.nativeRegistry) && (!spec.nativeDeadline || process.platform !== 'win32'))
+        throw new CliError('Native subject/mutex/registry binding requires an owned Windows job.', { code: 'tool.configuration' });
+    if (spec.nativeChildDeadlines && !spec.nativeDeadline)
+        throw new CliError('Native child deadlines require the native collector deadline.', { code: 'tool.configuration' });
+    let launch = { executable: spec.executable, arguments: spec.arguments ?? [] };
+    const id = randomUUID(), root = join(directory, 'runtime/runs', id), path = join(directory, 'runtime/processes', id + '.json');
+    const started = performance.now(), limit = spec.maxOutputBytes ?? 4 * 1024 ** 2;
+    let child, outcome, truncated = false, bytes = 0;
+    const stdout = [], stderr = [], record = { schema: 1, id, tool: spec.tool, role: spec.role, installation: spec.installation ?? 'probe', state: 'starting', executable: spec.executable, createdAt: new Date().toISOString(), root, ownerPid: process.pid, profileBinding: digest(resolve(directory)), gated: process.platform !== 'win32' && typeof process.execve === 'function', phase: 'reserved', ...(spec.session ? { session: spec.session } : {}), ...(spec.target ? { target: spec.target } : {}) };
+    const lease = await withToolUse(directory, spec.tool, async () => { await mkdir(root, { recursive: true, mode: 0o700 }); }, c.signal);
+    const environment = { PATH: c.environment.PATH ?? process.env.PATH, HOME: root, TMPDIR: root, ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot, WINDIR: process.env.WINDIR, ComSpec: process.env.ComSpec, TEMP: root, TMP: root, USERPROFILE: root, LOCALAPPDATA: root, APPDATA: root } : {}), ...spec.environment };
+    const secrets = Object.entries(environment).filter(([key, value]) => /TOKEN|PASSWORD|SECRET|KEY/i.test(key) && value && value.length >= 4).map(([, v]) => v);
+    const redact = (value) => secrets.reduce((text, secret) => text.split(secret).join('[redacted]'), value);
+    let timer, force, drain, hard, settled = false, abandon;
+    const signal = (name) => {
+        if (!child?.pid || settled)
+            return;
+        try {
+            if (process.platform !== 'win32')
+                process.kill(-child.pid, name);
+            else if (child.exitCode === null && child.signalCode === null)
+                child.kill(name);
+        }
+        catch (e) {
+            if (e.code === 'ESRCH')
+                return;
+            record.terminationError = e.code ?? 'signal_failed';
+            if (child.exitCode === null && child.signalCode === null)
+                try {
+                    child.kill(name);
+                }
+                catch { }
+        }
+    };
+    const stop = (reason) => { if (settled)
+        return; outcome ??= reason; signal('SIGTERM'); force ??= setTimeout(() => { signal('SIGKILL'); hard = setTimeout(() => { if (settled)
+        return; outcome = 'termination_unverified'; record.state = 'unverified'; child?.stdin?.destroy(); child?.stdout?.destroy(); child?.stderr?.destroy(); child?.unref(); abandon?.(new Error('termination_unverified')); }, 1000); hard.unref(); }, 1000); force.unref(); };
+    const aborted = () => stop('cancelled');
+    try {
+        c.signal.throwIfAborted();
+        if (spec.nativeDeadline)
+            launch = process.platform === 'win32' ? await windowsJobLaunch(root, id, spec.executable, spec.arguments ?? [], spec.cwd ?? root, spec.timeoutMs ?? 120000, { observedSubject: spec.observedSubject, nativeMutex: spec.nativeMutex, nativeRegistry: spec.nativeRegistry }) : await deadlineLaunch(spec.executable, spec.arguments ?? [], spec.timeoutMs ?? 120000);
+        child = await launchProcess(directory, { tool: spec.tool, role: spec.role, installation: spec.installation ?? 'probe', session: spec.session, target: spec.target, ...(spec.metadata || spec.nativeDeadline ? { metadata: { ...spec.metadata, ...(spec.observedSubject ? { observedSubject: spec.observedSubject } : {}), ...(spec.nativeMutex ? { nativeMutex: spec.nativeMutex } : {}), ...(spec.nativeRegistry ? { nativeRegistry: spec.nativeRegistry } : {}), ...(spec.nativeDeadline ? { nativeDeadlineSeconds: Math.ceil((spec.timeoutMs ?? 120000) / 1000), nativeExecutable: spec.executable, ...(spec.nativeChildDeadlines ? { nativeChildDeadlines: true } : {}) } : {}) } } : {}) }, launch.executable, launch.arguments, { cwd: spec.cwd ?? root, env: environment, windowsHide: true, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] }, { id, finalize: false, signal: c.signal, onSpawn: launched => {
+                child = launched;
+                child.once('close', () => { settled = true; });
+                child.once('exit', () => { drain = setTimeout(() => stop('background_output'), 300); drain.unref(); });
+                const capture = (chunks, b) => { const available = Math.max(0, limit - bytes); if (available)
+                    chunks.push(Buffer.from(b.subarray(0, available))); bytes += b.length; if (bytes > limit) {
+                    truncated = true;
+                    stop('output_limit');
+                } };
+                child.stdout.on('data', b => capture(stdout, b));
+                child.stderr.on('data', b => capture(stderr, b));
+                child.stdin.on('error', () => { });
+                child.stdin.end(spec.input);
+                c.signal.addEventListener('abort', aborted, { once: true });
+                if (c.signal.aborted)
+                    aborted();
+                timer = setTimeout(() => stop('timeout'), spec.timeoutMs ?? 120000);
+                timer.unref();
+            } });
+        await Promise.race([child.toolClosed, new Promise((_ok, bad) => { abandon = bad; })]);
+        settled = true;
+        Object.assign(record, await readJson(path));
+        if (record.launchError)
+            outcome = 'launch_failed';
+        let exitCode = child.exitCode;
+        if (spec.nativeDeadline && process.platform === 'win32' && !outcome) {
+            try {
+                const job = await windowsJobResult(root, id, child.pid, Boolean(spec.nativeRegistry));
+                exitCode = job.childExitCode;
+                Object.assign(record, { windowsJob: job });
+                if (job.phase !== 'completed')
+                    outcome = job.phase;
+            }
+            catch {
+                outcome = 'job_result_unverified';
+            }
+        }
+        if (!outcome && spec.nativeDeadline && child.signalCode === 'SIGALRM')
+            outcome = 'timeout';
+        if (!outcome && (exitCode === null || !(spec.acceptedCodes ?? [0]).includes(exitCode)))
+            outcome = 'exit_code';
+        const result = { process: id, stdout: redact(Buffer.concat(stdout).toString('utf8')), stderr: redact(Buffer.concat(stderr).toString('utf8')), exitCode, signal: child.signalCode, elapsedMs: Math.round(performance.now() - started), truncated, diagnostics: root };
+        if (spec.retainRawOutput) {
+            result.rawStdout = join(root, 'stdout.bin');
+            result.rawStderr = join(root, 'stderr.bin');
+            await writeFile(result.rawStdout, Buffer.concat(stdout), { mode: 0o600 });
+            await writeFile(result.rawStderr, Buffer.concat(stderr), { mode: 0o600 });
+        }
+        await writeFile(join(root, 'stdout.log'), result.stdout, { mode: 0o600 });
+        await writeFile(join(root, 'stderr.log'), result.stderr, { mode: 0o600 });
+        Object.assign(record, { state: outcome ? 'failed' : 'exited', outcome: outcome ?? 'completed', exitCode: result.exitCode, signal: result.signal, elapsedMs: result.elapsedMs, endedAt: new Date().toISOString() });
+        await atomicWrite(path, record);
+        if (outcome)
+            throw new CliError('Tool execution did not complete successfully: ' + outcome + '.', { code: 'tool.' + outcome.replaceAll('_', '.'), result });
+        if (spec.outputFile)
+            try {
+                await writeFile(spec.outputFile, Buffer.concat(stdout), { flag: 'wx', mode: 0o600 });
+            }
+            catch (error) {
+                throw new CliError('Tool completed, but its binary output could not be written to a new file.', { code: 'tool.output', cause: error, result: { process: id, diagnostics: root } });
+            }
+        return result;
+    }
+    catch (error) {
+        const failure = error;
+        await atomicWrite(join(root, 'error.json'), { name: failure.name, code: failure.code, message: redact(failure.message ?? String(error)), ...(failure.cause ? { cause: { name: failure.cause.name, message: redact(failure.cause.message) } } : {}) });
+        if (child && !settled && record.state !== 'unverified') {
+            stop('failed');
+            await new Promise(ok => { if (settled) {
+                ok();
+                return;
+            } child.once('close', () => ok()); setTimeout(() => { signal('SIGKILL'); ok(); }, 1500).unref(); });
+        }
+        Object.assign(record, await readJson(path));
+        if (c.signal.aborted && !outcome)
+            outcome = 'cancelled';
+        if (record.state === 'starting' || record.state === 'running' || record.state === 'failed') {
+            Object.assign(record, { state: 'failed', outcome: outcome ?? 'launch_failed', endedAt: new Date().toISOString(), elapsedMs: Math.round(performance.now() - started) });
+            await atomicWrite(path, record);
+        }
+        if (record.state === 'unverified')
+            await atomicWrite(path, record);
+        if (error instanceof CliError)
+            throw error;
+        if (record.state === 'unverified')
+            throw new CliError('Tool termination could not be verified; its process record blocks removal.', { code: 'tool.termination.unverified', result: { process: id, diagnostics: root } });
+        throw new CliError('Tool execution failed; inspect its retained process record.', { code: outcome ? 'tool.' + outcome.replaceAll('_', '.') : 'tool.launch', cause: error, result: { process: id, diagnostics: root } });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (force)
+            clearTimeout(force);
+        if (drain)
+            clearTimeout(drain);
+        if (hard)
+            clearTimeout(hard);
+        c.signal.removeEventListener('abort', aborted);
+        lease.release();
+    }
+}

package/dist/src/tool-runtime/store.d.ts

@@ -0,0 +1,15 @@
+export declare function atomicWrite(path: string, value: unknown): Promise<void>;
+export declare function readJson<T>(path: string): Promise<T | undefined>;
+export declare function toolRoot(directory: string, tool: string): string;
+/** CLI clients already share Factory's elected owner. Do not create another IPC/lease protocol. */
+export declare function withToolLock<T>(directory: string, tool: string, action: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+export declare function toolProfileBusy(directory: string): boolean;
+export declare function toolUseCount(directory: string, tool: string): number;
+export declare function withToolUse<T>(directory: string, tool: string, acquire: () => Promise<T>, signal?: AbortSignal): Promise<{
+    value: T;
+    release: () => void;
+}>;
+export declare function assertUnused(directory: string, tool: string): Promise<void>;
+export declare function installationStage<T>(root: string, id: string, prepare: (stage: string, installed: string) => Promise<T>, verify: (receipt: T) => Promise<void>, signal?: AbortSignal): Promise<T>;
+export declare function removeInstallation(root: string, id: string): Promise<void>;
+export declare function treeFingerprint(root: string): Promise<string>;