@eyeauras/insight-cli 0.1.0 → 0.2.1

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

@@ -0,0 +1,219 @@
+import { mkdir, open, rename, rm, readFile, readdir, lstat, realpath } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { dirname, join, resolve, relative, sep } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { CliError } from '@eyeauras/cli-factory';
+import { fail } from '../model.js';
+export async function atomicWrite(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = path + '.new-' + randomUUID(), file = await open(temporary, 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value, null, 2) + '\n');
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await rename(temporary, path);
+    if (process.platform !== 'win32') {
+        const parent = await open(dirname(path), 'r');
+        try {
+            await parent.sync();
+        }
+        finally {
+            await parent.close();
+        }
+    }
+}
+export async function readJson(path) { try {
+    return JSON.parse(await readFile(path, 'utf8'));
+}
+catch (e) {
+    if (e.code === 'ENOENT')
+        return;
+    throw e;
+} }
+export function toolRoot(directory, tool) { if (!/^[a-z][a-z0-9-]*$/.test(tool))
+    fail('invalid', 'Invalid tool identity.'); return tool === 'ghidra' ? join(directory, 'runtime') : join(directory, 'runtime', 'tools', tool); }
+const queues = new Map(), held = new AsyncLocalStorage(), uses = new Map();
+const key = (directory, tool) => resolve(directory) + '\0' + tool;
+/** CLI clients already share Factory's elected owner. Do not create another IPC/lease protocol. */
+export async function withToolLock(directory, tool, action, signal) {
+    signal?.throwIfAborted();
+    const k = key(directory, tool);
+    if (held.getStore()?.has(k))
+        return action();
+    const previous = queues.get(k) ?? Promise.resolve();
+    let started = false;
+    const execution = previous.then(() => { signal?.throwIfAborted(); started = true; return held.run(new Set([...(held.getStore() ?? []), k]), action); });
+    const tail = execution.then(() => { }, () => { });
+    queues.set(k, tail);
+    void tail.then(() => { if (queues.get(k) === tail)
+        queues.delete(k); });
+    if (!signal)
+        return execution;
+    return new Promise((ok, bad) => {
+        const aborted = () => { if (!started)
+            bad(signal.reason); };
+        signal.addEventListener('abort', aborted, { once: true });
+        if (signal.aborted)
+            aborted();
+        execution.then(ok, bad).finally(() => signal.removeEventListener('abort', aborted));
+    });
+}
+export function toolProfileBusy(directory) { const prefix = resolve(directory) + '\0'; return [...queues.keys(), ...uses.keys()].some(k => k.startsWith(prefix)); }
+export function toolUseCount(directory, tool) { return uses.get(key(directory, tool)) ?? 0; }
+export async function withToolUse(directory, tool, acquire, signal) {
+    return withToolLock(directory, tool, async () => {
+        const value = await acquire();
+        signal?.throwIfAborted();
+        const k = key(directory, tool);
+        uses.set(k, (uses.get(k) ?? 0) + 1);
+        let released = false;
+        return { value, release() { if (released)
+                return; released = true; const n = (uses.get(k) ?? 1) - 1; if (n)
+                uses.set(k, n);
+            else
+                uses.delete(k); } };
+    }, signal);
+}
+export async function assertUnused(directory, tool) {
+    if (toolUseCount(directory, tool))
+        fail('busy', 'Tool installation is reserved by an active operation.');
+    let names;
+    const root = join(directory, 'runtime/processes');
+    try {
+        names = await readdir(root);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+    for (const name of names) {
+        if (!/^[a-f0-9-]{36}\.json$/.test(name))
+            continue;
+        const retained = await readJson(join(root, name));
+        if (!retained || retained.tool !== tool)
+            continue;
+        const { processStatus } = await import('./supervisor.js'), record = await processStatus(directory, name.slice(0, -5));
+        if (['exited', 'failed'].includes(record.state))
+            continue;
+        if (record.phase === 'native_children_pending' || record.phase === 'native_children_unverified')
+            fail('busy', 'Tool has an active or unverified native helper; inspect its retained records before changing installations.');
+        if (!record.pid) {
+            if (record.gated && record.ownerPid)
+                try {
+                    process.kill(record.ownerPid, 0);
+                }
+                catch (e) {
+                    if (e.code === 'ESRCH')
+                        continue;
+                    throw e;
+                }
+            fail('busy', 'Tool has an unresolved process launch; inspect its process record.');
+        }
+        try {
+            process.kill(record.pid, 0);
+            fail('busy', 'Tool has an active or unverified process; stop it before changing installations.');
+        }
+        catch (e) {
+            if (e.code !== 'ESRCH')
+                throw e;
+        }
+    }
+}
+export async function installationStage(root, id, prepare, verify, signal) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        fail('invalid', 'Invalid installation identity.');
+    signal?.throwIfAborted();
+    const installed = join(root, 'installations', id), receipt = await readJson(join(installed, 'ready.json'));
+    if (receipt) {
+        await verify(receipt);
+        return receipt;
+    }
+    const stage = join(root, 'stages', randomUUID());
+    await mkdir(stage, { recursive: true, mode: 0o700 });
+    try {
+        const value = await prepare(stage, installed);
+        signal?.throwIfAborted();
+        await atomicWrite(join(stage, 'ready.json'), value);
+        await mkdir(dirname(installed), { recursive: true, mode: 0o700 });
+        try {
+            await lstat(installed);
+            fail('binding', 'Incomplete installation is retained; inspect it before removing it.');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        await rename(stage, installed);
+        if (process.platform !== 'win32') {
+            const p = await open(dirname(installed), 'r');
+            try {
+                await p.sync();
+            }
+            finally {
+                await p.close();
+            }
+        }
+        return value;
+    }
+    catch (error) {
+        const code = error instanceof CliError ? error.code : 'installation';
+        await atomicWrite(join(stage, 'failure.json'), { state: 'failed', code });
+        if (error instanceof CliError)
+            throw new CliError(error.message, { code: error.code, result: { ...(error.result && typeof error.result === 'object' ? error.result : {}), diagnostics: stage } });
+        throw new CliError('Tool installation failed; the prior selection and diagnostic stage are retained.', { code: 'tool.installation', cause: error, result: { diagnostics: stage } });
+    }
+}
+export async function removeInstallation(root, id) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        fail('binding', 'Invalid installation identity.');
+    const path = join(root, 'installations', id);
+    let actual;
+    try {
+        actual = await realpath(path);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+    if (actual !== join(await realpath(root), 'installations', id))
+        fail('binding', 'Owned installation path was replaced by an external link.');
+    await rm(path, { recursive: true, force: true });
+}
+export async function treeFingerprint(root) {
+    const hash = createHash('sha256'), canonicalRoot = await realpath(root);
+    let count = 0;
+    async function visit(path) {
+        for (const name of (await readdir(path)).sort()) {
+            if (path === root && name === 'ready.json')
+                continue;
+            const at = join(path, name), st = await lstat(at);
+            if (++count > 100000)
+                fail('limit', 'Tool installation exceeds its file bound.');
+            hash.update(relative(root, at).replaceAll('\\', '/') + '\0');
+            if (st.isDirectory())
+                await visit(at);
+            else if (st.isSymbolicLink()) {
+                const destination = await realpath(at);
+                if (!destination.startsWith(canonicalRoot + sep))
+                    fail('binding', 'Installed component link escapes its owned directory.');
+                hash.update('link:' + relative(canonicalRoot, destination));
+            }
+            else if (st.isFile()) {
+                const leaf = createHash('sha256');
+                for await (const b of createReadStream(at))
+                    leaf.update(b);
+                hash.update('file:' + st.size + ':' + leaf.digest('hex') + '\0');
+            }
+            else
+                fail('binding', 'Unsupported tool installation entry.');
+        }
+    }
+    await visit(root);
+    return hash.digest('hex');
+}

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

@@ -0,0 +1,57 @@
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import type { ToolProcess } from './definition.js';
+export interface ProcessRecord extends ToolProcess {
+    root: string;
+    ownerPid: number;
+    profileBinding: string;
+    phase?: string;
+    strongIdentity?: boolean;
+    processGroup?: number;
+    gated: boolean;
+    metadata?: Record<string, unknown>;
+    outcome?: string;
+    requestedStop?: 'stop' | 'kill';
+    launchError?: string;
+}
+export interface ProcessSpec {
+    tool: string;
+    role: string;
+    installation: string;
+    session?: string;
+    target?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TrackedChild extends ChildProcess {
+    toolProcessId: string;
+    toolClosed: Promise<void>;
+}
+export type OwnershipVerifier = (record: ProcessRecord) => Promise<boolean | undefined>;
+export declare function launchProcess(directory: string, spec: ProcessSpec, executable: string, args: string[], options?: SpawnOptions, control?: {
+    id?: string;
+    finalize?: boolean;
+    onSpawn?: (child: TrackedChild) => void | Promise<void>;
+    signal?: AbortSignal;
+}): Promise<TrackedChild>;
+export declare function processStatus(directory: string, id: string, verify?: OwnershipVerifier): Promise<ProcessRecord>;
+export declare function listProcesses(directory: string, filter?: {
+    tool?: string;
+    session?: string;
+    target?: string;
+}, verify?: OwnershipVerifier): Promise<ProcessRecord[]>;
+export declare function terminateProcess(directory: string, id: string, force: boolean, verify?: OwnershipVerifier, graceful?: (record: ProcessRecord) => Promise<void>): Promise<{
+    process: string;
+    state: string;
+    interrupted?: undefined;
+    tool?: undefined;
+    session?: undefined;
+    target?: undefined;
+} | {
+    process: string;
+    state: string;
+    interrupted: boolean;
+    tool: string;
+    session: string | undefined;
+    target: string | undefined;
+}>;
+/** Migration/reconnection only: an adapter must authenticate a known existing tool before registration. */
+export declare function registerExistingProcess(directory: string, spec: ProcessSpec, executable: string, pid: number, verify: OwnershipVerifier): Promise<string>;

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

@@ -0,0 +1,266 @@
+import { spawn } from 'node:child_process';
+import { access, mkdir, readdir } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join, isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { CliError } from '@eyeauras/cli-factory';
+import { atomicWrite, readJson, toolRoot, withToolLock } from './store.js';
+import { processIdentity } from './identity.js';
+import { digest } from '../model.js';
+const owned = new Map();
+const ownedKey = (directory, id) => resolve(directory) + '\0' + id;
+/** Receipts report pending lifetime only; they never authorize a signal to another PID. */
+async function nativeChildren(record) {
+    if (record.metadata?.nativeChildDeadlines !== true)
+        return [];
+    let names;
+    try {
+        names = await readdir(join(record.root, 'native-deadlines'));
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    if (names.length > 100)
+        throw new CliError('Native helper receipt count exceeds its bound.', { code: 'tool.process.unverified' });
+    return Promise.all(names.map(async (name) => {
+        const value = await readJson(join(record.root, 'native-deadlines', name));
+        if (!/^\d+\.json$/.test(name) || !value || value.protocol !== 1 || !Number.isSafeInteger(value.pid) || value.pid < 1 || value.pid > 2147483647 || name !== value.pid + '.json' || !Number.isSafeInteger(value.parentPid) || value.parentPid < 1 || !Number.isSafeInteger(value.birthSeconds) || value.birthSeconds < 1 || !Number.isSafeInteger(value.birthMicroseconds) || value.birthMicroseconds < 0 || value.birthMicroseconds >= 1000000 || !Number.isSafeInteger(value.deadlineUnixSeconds) || value.deadlineUnixSeconds <= 0)
+            throw new CliError('Native helper receipt is invalid; no cleanup was assumed.', { code: 'tool.process.unverified' });
+        const receiptDigest = digest(value), acknowledgment = join(record.root, 'native-deadline-exits', name), previous = await readJson(acknowledgment);
+        if (previous?.receiptDigest === receiptDigest)
+            return { ...value, state: 'exited' };
+        const identity = await processIdentity(value.pid), seconds = identity && process.platform === 'darwin' ? Date.parse(identity.birth + ' GMT') / 1000 : NaN;
+        // A different observable birth proves reuse, without granting permission to signal that PID.
+        const exited = !identity || Number.isFinite(seconds) && seconds !== value.birthSeconds;
+        if (exited)
+            await atomicWrite(acknowledgment, { receiptDigest, observedAt: new Date().toISOString() });
+        return { ...value, state: exited ? 'exited' : 'pending' };
+    }));
+}
+export async function launchProcess(directory, spec, executable, args, options = {}, control = {}) {
+    return withToolLock(directory, spec.tool, async () => {
+        control.signal?.throwIfAborted();
+        toolRoot(directory, spec.tool);
+        if (!isAbsolute(executable))
+            throw new CliError('Tool executable must be absolute.', { code: 'tool.configuration' });
+        const id = control.id ?? randomUUID();
+        if (!/^[a-f0-9-]{36}$/.test(id))
+            throw Error('Invalid process identity');
+        const root = join(directory, 'runtime/runs', id), path = join(directory, 'runtime/processes', id + '.json');
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const gated = process.platform !== 'win32' && typeof process.execve === 'function';
+        const record = { schema: 1, id, ...spec, state: 'starting', executable, root, ownerPid: process.pid, profileBinding: digest(resolve(directory)), gated, phase: 'reserved', createdAt: new Date().toISOString() };
+        await atomicWrite(path, record);
+        try {
+            control.signal?.throwIfAborted();
+            await access(executable, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+        }
+        catch (error) {
+            Object.assign(record, { state: 'failed', phase: 'preflight_failed' });
+            await atomicWrite(path, record);
+            throw error;
+        }
+        const environment = options.env ?? { PATH: process.env.PATH, HOME: root, TMPDIR: root };
+        const stdio = Array.isArray(options.stdio) ? [...options.stdio] : Array(3).fill(options.stdio ?? 'pipe'), fd = stdio.length, nonce = randomUUID();
+        if (gated)
+            stdio.push('pipe');
+        let child;
+        try {
+            child = spawn(gated ? process.execPath : executable, gated ? ['--no-warnings', fileURLToPath(new URL('./launch-worker.js', import.meta.url)), directory, id, String(fd)] : args, { cwd: root, ...options, stdio, windowsHide: true, env: gated ? { PATH: environment.PATH, HOME: root, TMPDIR: root } : environment });
+        }
+        catch (error) {
+            Object.assign(record, { state: 'failed', phase: 'spawn_failed' });
+            await atomicWrite(path, record);
+            throw error;
+        }
+        const closed = new Promise((ok, bad) => { child.on('error', error => { if (!child.pid)
+            bad(error); }); child.once('close', ok); });
+        void closed.catch(() => { });
+        const handle = { child, closed, record };
+        owned.set(ownedKey(directory, id), handle);
+        const finalized = control.finalize === false ? closed : closed.then(async () => {
+            const current = await readJson(path) ?? record;
+            if (current.state !== 'failed' && current.state !== 'unverified')
+                Object.assign(current, { state: 'exited', exitCode: child.exitCode, signal: child.signalCode, endedAt: new Date().toISOString(), outcome: current.requestedStop === 'kill' ? 'killed' : current.requestedStop === 'stop' ? 'stopped' : 'completed' });
+            await atomicWrite(path, current);
+        }, async () => { Object.assign(record, { state: 'failed', phase: 'spawn_failed' }); await atomicWrite(path, record); });
+        handle.closed = finalized.finally(() => { owned.delete(ownedKey(directory, id)); });
+        void handle.closed.catch(() => { });
+        Object.assign(child, { toolProcessId: id, toolClosed: handle.closed });
+        try {
+            await control.onSpawn?.(child);
+            if (!child.pid)
+                throw Error('Owned tool spawn did not obtain a PID');
+            if (gated) {
+                const channel = child.stdio[fd];
+                channel.on('error', () => { });
+                channel.end(JSON.stringify({ executable, arguments: args, environment: Object.fromEntries(Object.entries(environment).filter(([, v]) => v !== undefined)), nonce }));
+                let armed = false;
+                for (let i = 0; i < 400; i++) {
+                    control.signal?.throwIfAborted();
+                    const ready = await readJson(join(root, 'armed.json'));
+                    if (ready && ready.pid === child.pid && ready.nonce === nonce) {
+                        armed = true;
+                        break;
+                    }
+                    if (child.exitCode !== null || child.signalCode !== null)
+                        break;
+                    await delay(25);
+                }
+                if (!armed)
+                    throw Error('Owned launch did not become armed');
+                Object.assign(record, await readJson(path), { state: 'running', phase: 'exec_authorized' });
+                await atomicWrite(path, record);
+                await atomicWrite(join(root, 'go.json'), { nonce });
+            }
+            else {
+                if (!child.pid)
+                    throw Error('No child process');
+                const identity = await processIdentity(child.pid);
+                Object.assign(record, { pid: child.pid, identity: identity?.birth, strongIdentity: identity?.strong, processGroup: identity?.group, state: 'running', phase: 'direct_child_only' });
+                await atomicWrite(path, record);
+            }
+            return child;
+        }
+        catch (error) {
+            if (child.exitCode === null && child.signalCode === null)
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { }
+            await Promise.race([handle.closed.catch(() => { }), delay(2000)]);
+            Object.assign(record, { state: child.exitCode !== null || child.signalCode !== null ? 'failed' : 'unverified', phase: 'launch_failed' });
+            await atomicWrite(path, record);
+            throw error;
+        }
+    }, control.signal);
+}
+export async function processStatus(directory, id, verify) {
+    if (!/^[a-f0-9-]{36}$/.test(id))
+        throw new CliError('Invalid process identity.', { code: 'tool.process.invalid' });
+    const record = await readJson(join(directory, 'runtime/processes', id + '.json'));
+    if (!record || record.id !== id)
+        throw new CliError('Unknown tool process.', { code: 'tool.process.missing' });
+    if (record.root !== join(directory, 'runtime/runs', id) || record.profileBinding !== digest(resolve(directory)))
+        return { ...record, state: 'unverified', phase: 'profile_binding_changed' };
+    const finishing = owned.get(ownedKey(directory, id));
+    if (finishing && (finishing.child.exitCode !== null || finishing.child.signalCode !== null)) {
+        await finishing.closed;
+        return processStatus(directory, id, verify);
+    }
+    let children;
+    try {
+        children = await nativeChildren(record);
+    }
+    catch {
+        return { ...record, state: 'unverified', phase: 'native_children_unverified' };
+    }
+    const pending = children.some(c => c.state === 'pending');
+    const observed = { ...record, ...(children.length ? { nativeChildren: children } : {}) };
+    if (['exited', 'failed'].includes(record.state))
+        return pending ? { ...observed, state: 'unverified', phase: 'native_children_pending' } : observed;
+    if (!record.pid) {
+        try {
+            process.kill(record.ownerPid, 0);
+            return record;
+        }
+        catch {
+            return { ...record, state: record.gated ? 'failed' : 'unverified', phase: 'owner_lost_before_pid' };
+        }
+    }
+    const identity = await processIdentity(record.pid);
+    if (!identity)
+        return { ...observed, state: pending ? 'unverified' : 'exited', phase: pending ? 'native_children_pending' : 'observed_exit', outcome: 'unknown' };
+    if (identity.birth !== record.identity)
+        return { ...record, state: 'unverified', phase: 'pid_identity_changed' };
+    const current = owned.get(ownedKey(directory, id)), local = current?.child.pid === record.pid && current.record.identity === record.identity && current.child.exitCode === null && current.child.signalCode === null;
+    const proof = verify ? await verify(record) : undefined;
+    if (local || proof === true || proof === undefined && record.strongIdentity && identity.strong)
+        return { ...observed, state: 'running' };
+    return { ...observed, state: 'unverified', phase: 'tool_identity_required' };
+}
+export async function listProcesses(directory, filter = {}, verify) {
+    let names;
+    try {
+        names = await readdir(join(directory, 'runtime/processes'));
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    const items = [];
+    for (const name of names) {
+        if (!/^[a-f0-9-]{36}\.json$/.test(name))
+            continue;
+        const record = await processStatus(directory, name.slice(0, -5), verify);
+        if (filter.tool && record.tool !== filter.tool || filter.session && record.session !== filter.session || filter.target && record.target !== filter.target)
+            continue;
+        items.push(record);
+    }
+    return items.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+export async function terminateProcess(directory, id, force, verify, graceful) {
+    const path = join(directory, 'runtime/processes', id + '.json'), record = await processStatus(directory, id, verify);
+    if (['exited', 'failed'].includes(record.state))
+        return { process: id, state: 'already_exited' };
+    if (record.state !== 'running' || !record.pid)
+        throw new CliError('Process ownership is unverified; no signal was sent.', { code: 'tool.process.unverified' });
+    if (!force && graceful)
+        await graceful(record);
+    let current = await processStatus(directory, id, verify);
+    if (!['exited', 'failed'].includes(current.state)) {
+        if (current.state !== 'running' || current.pid !== record.pid)
+            throw new CliError('Process identity changed during stop.', { code: 'tool.process.unverified' });
+        current.requestedStop = force ? 'kill' : 'stop';
+        await atomicWrite(path, current);
+        const identity = await processIdentity(record.pid);
+        if (!identity || identity.birth !== record.identity)
+            throw new CliError('Process identity changed before signalling.', { code: 'tool.process.unverified' });
+        try {
+            if (process.platform !== 'win32' && record.processGroup === record.pid && identity.group === record.pid)
+                process.kill(-record.pid, force ? 'SIGKILL' : 'SIGTERM');
+            else
+                process.kill(record.pid, force ? 'SIGKILL' : 'SIGTERM');
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw error;
+        }
+        for (let i = 0; i < 100; i++) {
+            if (!await processIdentity(record.pid))
+                break;
+            await delay(50);
+        }
+        if (await processIdentity(record.pid))
+            throw new CliError('Owned process did not stop; its record is retained.', { code: 'tool.process.busy' });
+    }
+    await owned.get(ownedKey(directory, id))?.closed;
+    current = { ...(await readJson(path) ?? record), state: 'exited', outcome: force ? 'killed' : 'stopped', endedAt: new Date().toISOString() };
+    await atomicWrite(path, current);
+    return { process: id, state: force ? 'killed' : 'stopped', interrupted: force, tool: record.tool, session: record.session, target: record.target };
+}
+/** Migration/reconnection only: an adapter must authenticate a known existing tool before registration. */
+export async function registerExistingProcess(directory, spec, executable, pid, verify) {
+    toolRoot(directory, spec.tool);
+    const identity = await processIdentity(pid);
+    if (!identity)
+        throw new CliError('Existing tool process has exited.', { code: 'tool.process.missing' });
+    const hex = digest({ profile: resolve(directory), ...spec, pid, identity: identity.birth }).slice(0, 32), id = [hex.slice(0, 8), hex.slice(8, 12), hex.slice(12, 16), hex.slice(16, 20), hex.slice(20)].join('-');
+    const root = join(directory, 'runtime/runs', id), path = join(directory, 'runtime/processes', id + '.json');
+    const record = { schema: 1, id, ...spec, root, ownerPid: process.pid, profileBinding: digest(resolve(directory)), gated: false, state: 'running', phase: 'adopted_verified', createdAt: new Date().toISOString(), executable, pid, identity: identity.birth, strongIdentity: identity.strong, processGroup: identity.group };
+    if (!await verify(record))
+        throw new CliError('Existing process did not authenticate as the owned tool.', { code: 'tool.process.unverified' });
+    if ((await processIdentity(pid))?.birth !== identity.birth)
+        throw new CliError('Existing process identity changed during registration.', { code: 'tool.process.unverified' });
+    const previous = await readJson(path);
+    if (previous)
+        return id;
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    await atomicWrite(path, record);
+    return id;
+}

package/dist/src/tool-runtime/windows-job.d.ts

@@ -0,0 +1,22 @@
+/** Stock Windows PowerShell loads the packaged first-party Job Object executor; no runtime compiler. */
+export declare function windowsJobLaunch(root: string, nonce: string, executable: string, args: string[], cwd: string, timeoutMs: number, options?: {
+    observedSubject?: {
+        pid: number;
+        birth: string;
+    };
+    nativeMutex?: 'procmon';
+    nativeRegistry?: 'procmon';
+}): Promise<{
+    executable: string;
+    arguments: string[];
+}>;
+export declare function windowsJobResult(root: string, nonce: string, launcherPid: number, registryExpected?: boolean): Promise<{
+    registryIsolated?: boolean | undefined;
+    schema: number;
+    nonce: string;
+    launcherPid: number;
+    phase: string;
+    childExitCode: number;
+    childPid: number;
+    childBirthTicks: string;
+}>;

package/dist/src/tool-runtime/windows-job.js

@@ -0,0 +1,43 @@
+import { fileURLToPath } from 'node:url';
+import { readFile } from 'node:fs/promises';
+import { join, isAbsolute } from 'node:path';
+import { CliError } from '@eyeauras/cli-factory';
+import { fileSha256 } from './archives.js';
+import { atomicWrite, readJson } from './store.js';
+import { processIdentity } from './identity.js';
+/** Stock Windows PowerShell loads the packaged first-party Job Object executor; no runtime compiler. */
+export async function windowsJobLaunch(root, nonce, executable, args, cwd, timeoutMs, options = {}) {
+    if (process.platform !== 'win32' || !Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000)
+        throw new CliError('Owned Windows job deadline must be 1–600 seconds.', { code: 'tool.configuration' });
+    const native = fileURLToPath(new URL('../../../runtime/native/windows-job/', import.meta.url));
+    const proof = await readJson(join(native, 'provenance.json'));
+    if (!proof || await fileSha256(join(native, 'Insight.WindowsJob.dll')) !== proof.sha256 || await fileSha256(join(native, 'windows-job.ps1')) !== proof.launcherSha256)
+        throw new CliError('Packaged Windows job differs from its reviewed build.', { code: 'tool.binding' });
+    const identity = await processIdentity(process.pid), system = process.env.SystemRoot ?? process.env.WINDIR;
+    if (!identity?.strong || !/^\d+$/.test(identity.birth) || !system || !isAbsolute(system))
+        throw new CliError('Windows owner birth identity or system directory is unavailable.', { code: 'tool.process.unverified' });
+    if (options.observedSubject && (!Number.isSafeInteger(options.observedSubject.pid) || options.observedSubject.pid < 1 || !/^\d+$/.test(options.observedSubject.birth)))
+        throw new CliError('Borrowed Windows subject identity is invalid.', { code: 'tool.process.unverified' });
+    let registry = {};
+    if (options.nativeRegistry) {
+        const registryShim = join(native, '../insight-registry-win-x64.dll'), proof = await readJson(join(native, '../windows-registry.provenance.json'));
+        if (!proof || await fileSha256(registryShim) !== proof.sha256)
+            throw new CliError('Private Windows registry helper is missing or differs from its reviewed build.', { code: 'tool.binding' });
+        registry = { registryShim, registryShimSha256: proof.sha256 };
+    }
+    const specification = join(root, 'job-specification.json');
+    await atomicWrite(specification, { schema: 1, nonce, executable, arguments: args, cwd, timeoutMs, ownerPid: process.pid, ownerBirthTicks: identity.birth, ...registry, ...(options.observedSubject ? { observedPid: options.observedSubject.pid, observedBirthTicks: options.observedSubject.birth } : {}), ...(options.nativeMutex ? { nativeMutex: 'Local\\insight-cli-procmon-capture' } : {}) });
+    return { executable: join(system, 'System32/WindowsPowerShell/v1.0/powershell.exe'), arguments: ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', join(native, 'windows-job.ps1'), '-Specification', specification] };
+}
+export async function windowsJobResult(root, nonce, launcherPid, registryExpected = false) {
+    const result = await readJson(join(root, 'job-result.json'));
+    const started = await readJson(join(root, 'job-started.json'));
+    if (!result || !started || result.schema !== 1 || started.schema !== 1 || result.nonce !== nonce || started.nonce !== nonce || result.launcherPid !== launcherPid || started.launcherPid !== launcherPid || !['completed', 'timeout', 'owner_lost'].includes(result.phase) || !Number.isSafeInteger(result.childExitCode) || result.childExitCode < 0 || result.childExitCode > 0xffffffff || !Number.isSafeInteger(result.childPid) || result.childPid < 1 || result.childPid !== started.childPid || !/^\d+$/.test(result.childBirthTicks) || result.childBirthTicks !== started.childBirthTicks || started.phase !== 'assigned_suspended')
+        throw new CliError('Owned Windows job result is missing or unverified; no successful outcome was assumed.', { code: 'tool.process.unverified' });
+    if (registryExpected) {
+        const proof = await readFile(join(root, 'registry-isolated.bin'));
+        if (proof.length !== 48 || proof.readUInt32LE(0) !== 0x49484b31 || proof.readUInt32LE(4) !== result.childPid || proof.readUInt32LE(8) !== 0 || proof.subarray(12).toString('ascii') !== nonce)
+            throw new CliError('Private Windows registry initialization is unverified.', { code: 'tool.process.unverified' });
+    }
+    return { ...result, ...(registryExpected ? { registryIsolated: true } : {}) };
+}