@eyeauras/insight-cli 0.2.0 → 0.2.1

package/dist/src/sevenzip.d.ts

@@ -0,0 +1,15 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+export interface ArchiveEntry {
+    path: string;
+    directory: boolean;
+    size: number;
+    encrypted: boolean;
+    attributes: string;
+}
+/** Technical listing is bounded, not a general line-escaping format. Extraction never trusts native paths. */
+export declare function parseArchiveListing(content: string): ArchiveEntry[];
+export declare function safeArchivePath(path: string): string;
+export declare function sevenzipInstaller(c: CommandContext): ToolInstaller;
+export declare function sevenzipCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/sevenzip.js

@@ -0,0 +1,119 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { join, resolve, dirname } from 'node:path';
+import { mkdir, lstat } from 'node:fs/promises';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { runTool } from './tool-runtime/run.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const archiveSha = '7bb52641f2e0dc9b8f5b180be4b0ab46b6d3127361a4e817938175603850c714';
+/** Technical listing is bounded, not a general line-escaping format. Extraction never trusts native paths. */
+export function parseArchiveListing(content) {
+    const entries = [];
+    for (const block of content.replaceAll('\r\n', '\n').trim().split(/\n\n+/)) {
+        if (!block)
+            continue;
+        const fields = new Map();
+        for (const line of block.split('\n')) {
+            const at = line.indexOf(' = ');
+            if (at < 1)
+                fail('unsupported', 'Archive listing contains a multiline or unsupported field.');
+            const key = line.slice(0, at);
+            if (fields.has(key))
+                fail('unsupported', 'Archive listing contains ambiguous fields.');
+            fields.set(key, line.slice(at + 3));
+        }
+        if (['Symbolic Link', 'Hard Link', 'Reparse'].some(key => fields.has(key)))
+            fail('unsupported', 'Archive links are not supported for ordinary-file recovery.');
+        const path = fields.get('Path'), size = Number(fields.get('Size'));
+        if (!path || !Number.isSafeInteger(size) || size < 0 || !['+', '-'].includes(fields.get('Folder') ?? ''))
+            fail('unsupported', 'Archive entry omitted its path, size or kind.');
+        if (entries.length >= 10000)
+            fail('limit', 'Archive inventory exceeds 10000 entries.');
+        entries.push({ path, size, directory: fields.get('Folder') === '+', encrypted: fields.get('Encrypted') === '+', attributes: fields.get('Attributes') ?? '' });
+    }
+    return entries;
+}
+export function safeArchivePath(path) {
+    if (!path || /[\\\x00-\x1f\x7f:]/.test(path) || path.startsWith('/') || path.split('/').some(p => !p || p === '.' || p === '..') || path.length > 2048)
+        fail('invalid', 'Archive entry has an unsafe or unsupported output path.');
+    return path;
+}
+export function sevenzipInstaller(c) {
+    return new ToolInstaller(c, { id: 'sevenzip', primary: 'sevenzip', components: () => {
+            if (process.platform !== 'darwin' || !['arm64', 'x64'].includes(process.arch))
+                fail('unsupported', 'Managed 7-Zip is currently provided for macOS ARM64/x64; select an external 7zz 26.04 on another host.');
+            return { sevenzip: catalogArtifact(archiveSha) };
+        }, launch: roots => ({ executable: join(roots.sevenzip, '7zz'), arguments: [], environment: {} }),
+        probe: async (launch, context) => {
+            const r = await runTool(context, { tool: 'sevenzip', role: 'version', executable: launch.executable, arguments: [...launch.arguments, 'i'], environment: launch.environment, maxOutputBytes: 65536, timeoutMs: 30000 });
+            if (!/7-Zip \(z\) 26\.04 /.test(r.stdout))
+                fail('configuration', 'The selected executable must provide 7zz 26.04.');
+            return { version: '26.04' };
+        } });
+}
+export function sevenzipCommands(workspace) {
+    const definition = defineTool({ id: 'sevenzip', description: 'Inventory, verify and recover files from containers', components: [{ id: 'sevenzip', version: '26.04', artifacts: [] }], lifecycle: {
+            download: (o, c) => sevenzipInstaller(c).download(Boolean(o.offline)), install: (o, c) => sevenzipInstaller(c).install(o), uninstall: (o, c) => sevenzipInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => sevenzipInstaller(c).doctor(), status: (_o, c) => sevenzipInstaller(c).status()
+        } });
+    const common = [{ flags: '--target <id>', description: 'Reuse an immutable input target' }, { flags: '--timeout-seconds <seconds>', description: 'Per-process deadline (1–600)', defaultValue: 120 }];
+    const operation = (name) => command(name + ' [input]', name === 'list' ? 'Inspect a bounded archive inventory' : name === 'test' ? 'Check container integrity without extracting' : 'Recover regular files into a new ordinary directory', async ({ args, options: o }, c) => {
+        if (Boolean(args.input) === Boolean(o.target))
+            fail('invalid', 'Supply exactly one input path or --target.');
+        const w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target));
+        const input = await w.artifacts.verify(target.input), timeoutMs = number(o.timeoutSeconds, 600, 1) * 1000;
+        return sevenzipInstaller(c).use(async (selected) => {
+            const invoke = (role, parameters, extra = {}) => runTool(c, { tool: 'sevenzip', role, installation: selected.id, executable: selected.executable, arguments: [...selected.arguments, ...parameters], environment: selected.environment, target: target.id, timeoutMs, ...extra });
+            if (name === 'test') {
+                const result = await invoke('test', ['t', '-bd', '-y', '-p', '--', input]);
+                return { state: 'verified', target: target.id, inputSha256: target.binarySha256, process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics, content: result.stdout };
+            }
+            const listing = await invoke('inventory', ['l', '-slt', '-ba', '-sccUTF-8', '-p', '--', input]);
+            const entries = parseArchiveListing(listing.stdout);
+            const base = { target: target.id, inputSha256: target.binarySha256, process: listing.process, diagnostics: listing.diagnostics, total: entries.length };
+            if (name === 'list') {
+                const limit = number(o.limit, 100, 1), offset = number(o.offset, 10000, 0);
+                return { ...base, items: entries.slice(offset, offset + limit), limit, offset, truncated: offset + limit < entries.length };
+            }
+            const chosen = o.entry ? entries.filter(e => e.path === text(o.entry, 2048)) : entries;
+            if (!chosen.length)
+                fail('notFound', 'No matching archive entry.');
+            if (chosen.length > 512)
+                fail('limit', 'Select an entry; bulk recovery is limited to 512 entries.');
+            const paths = new Set();
+            let bytes = 0;
+            for (const entry of chosen) {
+                safeArchivePath(entry.path);
+                const key = entry.path.normalize('NFC').toLowerCase();
+                if (paths.has(key))
+                    fail('unsupported', 'Archive output paths collide.');
+                paths.add(key);
+                if (entry.encrypted)
+                    fail('unsupported', 'Encrypted recovery is not supported by this adapter.');
+                if (entry.size > 64 * 1024 ** 2 || (bytes += entry.size) > 256 * 1024 ** 2)
+                    fail('limit', 'Recovery exceeds its 64-MiB per-file/256-MiB total bound.');
+                if (/(?:^|\s)[bclps][rwx-]{9}/.test(entry.attributes))
+                    fail('unsupported', 'Only ordinary archive files and directories can be recovered.');
+            }
+            const output = resolve(c.cwd, text(o.output, 4096));
+            await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+            await mkdir(output, { mode: 0o700 });
+            const files = [];
+            for (const entry of chosen) {
+                const destination = join(output, entry.path);
+                if (entry.directory) {
+                    await mkdir(destination, { recursive: true, mode: 0o700 });
+                    continue;
+                }
+                await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+                const result = await invoke('recover', ['x', '-so', '-spd', '-bd', '-y', '-p', '--', input, entry.path], { maxOutputBytes: Math.max(65536, entry.size + 65536), outputFile: destination });
+                if ((await lstat(destination)).size !== entry.size)
+                    fail('binding', 'Recovered file size differs from the inventory; retained partial output requires inspection.');
+                files.push({ path: entry.path, size: entry.size, process: result.process });
+            }
+            return { ...base, state: 'extracted', outputDirectory: output, files, bytes, publication: 'ordinary files; no shared analysis merge' };
+        });
+    }, { permission: Permission.Update, options: [...common, ...(name === 'list' ? [{ flags: '--limit <count>', description: 'Page size (1–100)', defaultValue: 50 }, { flags: '--offset <count>', description: 'Skip entries', defaultValue: 0 }] : name === 'extract' ? [{ flags: '--entry <path>', description: 'Recover one exact regular entry' }, { flags: '--output <directory>', description: 'New output directory', required: true }] : [])] });
+    return [command('sevenzip', definition.description, [...lifecycleCommands(definition), operation('list'), operation('test'), operation('extract')])];
+}

package/dist/src/strace.d.ts

@@ -0,0 +1,10 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+export declare function straceInstaller(c: CommandContext): ToolInstaller;
+export declare function stracePlan(o: Record<string, unknown>): {
+    events: string[];
+    arguments: string[];
+    programArguments: string[];
+};
+export declare function straceCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/strace.js

@@ -0,0 +1,71 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { dirname, join, resolve } from 'node:path';
+import { mkdir, writeFile, open, copyFile, chmod } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { runTool } from './tool-runtime/run.js';
+import { fileSha256 } from './tool-runtime/archives.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+// Exact binary from the reviewed reproducible Linux source build.
+const archiveSha = '3f01b360952f9c81dee07b640916115f937685df6d3004f5a3227cb0582d8ca3';
+function supported() { if (process.platform !== 'linux' || process.arch !== 'x64')
+    fail('unsupported', 'The strace facade requires Linux x64, glibc 2.35+ and permission to trace its owned child.'); }
+export function straceInstaller(c) {
+    return new ToolInstaller(c, { id: 'strace', primary: 'strace', components: () => { supported(); return { strace: catalogArtifact(archiveSha) }; }, launch: roots => ({ executable: join(roots.strace, 'bin/strace'), arguments: [], environment: {} }), probe: async (launch, context) => {
+            supported();
+            const r = await runTool(context, { tool: 'strace', role: 'version', executable: launch.executable, arguments: ['--version'], maxOutputBytes: 65536, timeoutMs: 10000, nativeDeadline: true });
+            if (!/strace -- version 7\.2\b/.test(r.stdout + '\n' + r.stderr))
+                fail('configuration', 'Select strace 7.2 with --kill-on-exit support.');
+            return { version: '7.2', ownedChildOnly: true, killOnExit: true, kernelOwnerDeadline: true };
+        } });
+}
+export function stracePlan(o) {
+    const requested = text(o.events ?? 'file,process,io', 128).split(','), groups = { file: '%file', process: '%process', network: '%network', io: 'read,write,readv,writev' };
+    if (!requested.length || requested.length > 4 || requested.some(x => !groups[x]) || new Set(requested).size !== requested.length)
+        fail('invalid', '--events must contain unique file, process, network or io categories.');
+    const args = o.arg === undefined ? [] : Array.isArray(o.arg) ? o.arg : [o.arg];
+    if (args.length > 64)
+        fail('limit', 'At most 64 literal program arguments are supported.');
+    return { events: requested, arguments: ['--kill-on-exit', '-f', '-yy', '-s', String(number(o.stringBytes ?? 128, 1024, 1)), '-e', 'trace=' + requested.map(x => groups[x]).join(','), ...(o.path ? ['-P', resolve(text(o.path, 4096))] : [])], programArguments: args.map(v => text(v, 4096)) };
+}
+export function straceCommands(workspace) {
+    const definition = defineTool({ id: 'strace', description: 'Observe file, process, I/O and network syscalls in an owned native Linux launch', components: [{ id: 'strace', version: '7.2', artifacts: [] }], lifecycle: { download: (o, c) => straceInstaller(c).download(Boolean(o.offline)), install: (o, c) => straceInstaller(c).install(o), uninstall: (o, c) => straceInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => straceInstaller(c).doctor(), status: (_o, c) => straceInstaller(c).status() } });
+    return [command('strace', definition.description, [...lifecycleCommands(definition), command('trace [input]', 'Run an authorized owned ELF copy and retain bounded syscall observations', async ({ args, options: o }, c) => {
+                supported();
+                if (Boolean(args.input) === Boolean(o.target))
+                    fail('invalid', 'Supply exactly one executable input or --target.');
+                if (o.path)
+                    o = { ...o, path: resolve(c.cwd, text(o.path, 4096)) };
+                const plan = stracePlan(o), limit = number(o.limit ?? 200, 1000, 1), offset = number(o.offset ?? 0, 1000000), timeoutMs = number(o.timeoutSeconds ?? 30, 600, 1) * 1000;
+                const w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target)), input = await w.artifacts.verify(target.input), header = Buffer.alloc(64), handle = await open(input, 'r');
+                try {
+                    const { bytesRead } = await handle.read(header, 0, 64, 0);
+                    if (bytesRead < 64 || header.subarray(0, 4).toString('hex') !== '7f454c46' || header[4] !== 2 || header[5] !== 1 || header.readUInt16LE(18) !== 62)
+                        fail('unsupported', 'An owned launch requires a native little-endian x64 ELF executable.');
+                }
+                finally {
+                    await handle.close();
+                }
+                const directory = join(c.appArguments.AppDataDirectory, 'runtime/strace/subjects', randomUUID()), subject = join(directory, 'subject');
+                await mkdir(directory, { recursive: true, mode: 0o700 });
+                await copyFile(input, subject, constants.COPYFILE_EXCL);
+                await chmod(subject, 0o700);
+                if (await fileSha256(subject) !== target.binarySha256)
+                    fail('binding', 'Owned ELF bytes differ from the immutable target.');
+                return straceInstaller(c).use(async (selected) => {
+                    const result = await runTool(c, { tool: 'strace', role: 'trace', installation: selected.id, executable: selected.executable, arguments: [...plan.arguments, '--', subject, ...plan.programArguments], cwd: c.cwd, target: target.id, timeoutMs, nativeDeadline: true, metadata: { inputSha256: target.binarySha256, events: plan.events } }), lines = result.stderr.trimEnd().split(/\r?\n/);
+                    const base = { state: 'completed', target: target.id, inputSha256: target.binarySha256, process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics, events: plan.events, programStdout: result.stdout, coverage: 'Observed syscalls from one owned launch and its traced descendants. Native trace and program stderr share the stderr stream. Strings and category/path filters are bounded; unobserved operations are unknown. Application side effects require authorization; adjacent executable sidecars are not copied.' };
+                    if (o.output) {
+                        const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, lines }, null, 2) + '\n';
+                        await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+                        await writeFile(output, content, { flag: 'wx', mode: 0o600 });
+                        return { ...base, output, bytes: Buffer.byteLength(content), totalLines: lines.length };
+                    }
+                    return { ...base, lines: lines.slice(offset, offset + limit), offset, limit, totalLines: lines.length, truncated: offset + limit < lines.length };
+                });
+            }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse an immutable captured native ELF' }, { flags: '--arg <literal...>', description: 'Literal arguments, without shell expansion' }, { flags: '--events <categories>', description: 'Comma-separated file, process, io or network', defaultValue: 'file,process,io' }, { flags: '--path <path>', description: 'Optional literal path filter; combines with selected categories' }, { flags: '--string-bytes <bytes>', description: 'Maximum native string bytes (1–1024)', defaultValue: 128 }, { flags: '--output <file>', description: 'Save bounded trace and program stdout to a new ordinary JSON file' }, { flags: '--limit <count>', description: 'Maximum trace lines (1–1000)', defaultValue: 200 }, { flags: '--offset <count>', description: 'Skip trace lines', defaultValue: 0 }, { flags: '--timeout-seconds <seconds>', description: 'Owned launch deadline (1–600)', defaultValue: 30 }] })])];
+}

package/dist/src/text-window.d.ts

@@ -0,0 +1,11 @@
+/** Public text coordinates are Unicode code points, never native bytes or UTF-16 halves. */
+export declare function textWindow(source: string, limit: number, offset: number, sourceTruncated?: boolean): {
+    content: string;
+    textSha256: string;
+    totalCharacters: number;
+    limit: number;
+    offset: number;
+    sourceTruncated: boolean;
+    truncated: boolean;
+    coordinates: string;
+};

package/dist/src/text-window.js

@@ -0,0 +1,6 @@
+import { createHash } from 'node:crypto';
+/** Public text coordinates are Unicode code points, never native bytes or UTF-16 halves. */
+export function textWindow(source, limit, offset, sourceTruncated = false) {
+    const characters = Array.from(source);
+    return { content: characters.slice(offset, offset + limit).join(''), textSha256: createHash('sha256').update(source).digest('hex'), totalCharacters: characters.length, limit, offset, sourceTruncated, truncated: sourceTruncated || offset + limit < characters.length, coordinates: 'Unicode characters in the returned native text; hash binds that text, which may itself be a truncated prefix' };
+}

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

@@ -0,0 +1,10 @@
+import type { ToolArtifact } from './definition.js';
+export declare function fileSha256(path: string, signal?: AbortSignal): Promise<string>;
+export declare function archiveName(name: string): string;
+export declare function extractArchive(file: string, destination: string, format: 'tgz' | 'zip', signal?: AbortSignal): Promise<void>;
+export declare function cacheArtifact(artifact: ToolArtifact, cache: string, fetcher: typeof fetch, signal: AbortSignal, offline?: boolean, vendorDirect?: boolean): Promise<string>;
+/** Consume local input once; extraction never races later edits to the caller's archive. */
+export declare function consumeArchive(path: string, cache: string, artifact: ToolArtifact, checksum?: string, signal?: AbortSignal): Promise<{
+    path: string;
+    artifact: ToolArtifact;
+}>;

package/dist/src/{runtime-archives.js → tool-runtime/archives.js}

@@ -1,26 +1,27 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { createReadStream, createWriteStream } from 'node:fs';
-import { mkdir, open, rename, rm, stat } from 'node:fs/promises';
+import { createReadStream, createWriteStream, constants } from 'node:fs';
+import { mkdir, open, rename, rm, lstat } from 'node:fs/promises';
 import { dirname, join, posix } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import * as tar from 'tar';
 import * as zip from 'yauzl';
-import { fail } from './model.js';
-export async function fileSha256(path) { const hash = createHash('sha256'); for await (const chunk of createReadStream(path))
+import { fail } from '../model.js';
+export async function fileSha256(path, signal) { const hash = createHash('sha256'); for await (const chunk of createReadStream(path, { signal }))
     hash.update(chunk); return hash.digest('hex'); }
 export function archiveName(name) {
     if (!name || name.includes('\\') || name.includes('\0') || name.startsWith('/') || /^[a-zA-Z]:/.test(name) || name.split('/').includes('..'))
         fail('invalid', 'Runtime archive contains an unsafe path.');
     return name.replace(/^(\.\/)+/, '');
 }
-export async function extractArchive(file, destination, format) {
+export async function extractArchive(file, destination, format, signal) {
+    signal?.throwIfAborted();
     await mkdir(destination, { recursive: true, mode: 0o700 });
     let count = 0, bytes = 0;
     const bound = (name, size) => { archiveName(name); if (++count > 100000 || !Number.isSafeInteger(size) || size < 0 || (bytes += size) > 8 * 1024 ** 3)
         fail('limit', 'Runtime archive exceeds extraction bounds.'); };
     if (format === 'tgz') {
         let unsafe;
-        await tar.t({ file, strict: true, filter: (path, entry) => {
+        await readTar(file, tar.t({ strict: true, filter: (path, entry) => {
                 try {
                     if (!('type' in entry))
                         fail('invalid', 'Unsupported runtime archive metadata.');
@@ -42,10 +43,10 @@ export async function extractArchive(file, destination, format) {
                     unsafe ??= error;
                     return false;
                 }
-            } });
+            } }), 'end', signal);
         if (unsafe)
             throw unsafe;
-        await tar.x({ file, cwd: destination, strict: true, preserveOwner: false, noChmod: false });
+        await readTar(file, tar.x({ cwd: destination, strict: true, preserveOwner: false, noChmod: false }), 'close', signal);
         return;
     }
     const archive = await new Promise((ok, bad) => zip.open(file, { lazyEntries: true, strictFileNames: true }, (e, z) => e ? bad(e) : ok(z)));
@@ -55,6 +56,7 @@ export async function extractArchive(file, destination, format) {
         archive.on('end', ok);
         archive.on('entry', (entry) => {
             void (async () => {
+                signal?.throwIfAborted();
                 bound(entry.fileName, entry.uncompressedSize);
                 const mode = entry.externalFileAttributes >>> 16, type = mode & 0o170000;
                 if (type && type !== 0o100000 && type !== 0o040000)
@@ -65,7 +67,7 @@ export async function extractArchive(file, destination, format) {
                 else {
                     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
                     const stream = await new Promise((ok, bad) => archive.openReadStream(entry, (e, s) => e ? bad(e) : ok(s)));
-                    await pipeline(stream, createWriteStream(path, { flags: 'wx', mode: mode & 0o111 ? 0o755 : 0o644 }));
+                    await pipeline(stream, createWriteStream(path, { flags: 'wx', mode: mode & 0o111 ? 0o755 : 0o644 }), { signal });
                 }
                 archive.readEntry();
             })().catch(failed);
@@ -73,11 +75,13 @@ export async function extractArchive(file, destination, format) {
         archive.readEntry();
     });
 }
-export async function cacheArtifact(artifact, cache, fetcher, signal, offline = false) {
+export async function cacheArtifact(artifact, cache, fetcher, signal, offline = false, vendorDirect = false) {
+    signal.throwIfAborted();
     await mkdir(cache, { recursive: true, mode: 0o700 });
     const path = join(cache, artifact.sha256 + '.' + artifact.format);
     try {
-        if ((await stat(path)).isFile() && await fileSha256(path) === artifact.sha256)
+        const cached = await lstat(path);
+        if (cached.isFile() && (artifact.size === undefined || cached.size === artifact.size) && await fileSha256(path, signal) === artifact.sha256)
             return path;
         fail('binding', 'Cached runtime archive failed its SHA256 check; remove the corrupt cache entry before retrying.');
     }
@@ -86,27 +90,20 @@ export async function cacheArtifact(artifact, cache, fetcher, signal, offline =
             throw error;
     }
     if (offline)
-        fail('configuration', 'Required runtime archive is not cached; run ghidra download before using --offline.', { artifact: artifact.name, sha256: artifact.sha256 });
+        fail('configuration', 'Required runtime archive is not cached; run the tool download command before using --offline.', { artifact: artifact.name, sha256: artifact.sha256 });
+    if (artifact.delivery?.kind === 'vendor-direct' && !vendorDirect)
+        fail('configuration', 'This non-redistributable runtime requires explicit vendor download; use --vendor-direct or supply a local archive.', { artifact: artifact.name, publisher: artifact.delivery.publisher, termsUrl: artifact.delivery.termsUrl });
     const temporary = path + '.partial-' + randomUUID();
     try {
-        let headers = {};
-        if (artifact.url.startsWith('https://ghcr.io/v2/homebrew/core/ghidra/')) {
-            const response = await fetcher('https://ghcr.io/token?service=ghcr.io&scope=repository:homebrew/core/ghidra:pull', { signal, redirect: 'error' });
-            if (!response.ok)
-                fail('download', 'Anonymous runtime registry authorization failed.');
-            const value = await response.json();
-            if (!value.token || value.token.length > 8192)
-                fail('download', 'Invalid anonymous runtime registry token.');
-            headers = { Authorization: 'Bearer ' + value.token };
-        }
-        const response = await fetcher(artifact.url, { signal, headers });
+        const response = await fetcher(artifact.url, { signal, cache: 'no-store' });
         if (!response.ok || !response.body)
             fail('download', 'Pinned runtime download failed.', { artifact: artifact.name, status: response.status });
         let size = 0;
         const hash = createHash('sha256'), handle = await open(temporary, 'wx', 0o600);
         try {
             for await (const chunk of response.body) {
-                if ((size += chunk.byteLength) > 2 * 1024 ** 3)
+                signal.throwIfAborted();
+                if ((size += chunk.byteLength) > (artifact.size ?? 2 * 1024 ** 3))
                     fail('limit', 'Runtime download exceeds two GiB.');
                 hash.update(chunk);
                 await handle.writeFile(chunk);
@@ -116,6 +113,8 @@ export async function cacheArtifact(artifact, cache, fetcher, signal, offline =
         finally {
             await handle.close();
         }
+        if (artifact.size !== undefined && size !== artifact.size)
+            fail('binding', 'Downloaded runtime archive has an unexpected size.');
         if (hash.digest('hex') !== artifact.sha256)
             fail('binding', 'Downloaded runtime archive failed its pinned SHA256 check.');
         await rename(temporary, path);
@@ -125,3 +124,71 @@ export async function cacheArtifact(artifact, cache, fetcher, signal, offline =
         await rm(temporary, { force: true });
     }
 }
+/** tar streams expose their own abort instead of Node's AbortSignal option. */
+async function readTar(file, parser, event, signal) {
+    signal?.throwIfAborted();
+    const input = createReadStream(file, { signal });
+    await new Promise((ok, bad) => {
+        let settled = false;
+        const failed = (error) => { if (settled)
+            return; settled = true; input.unpipe(); input.destroy(); parser.abort(error); bad(error); };
+        parser.on('error', failed);
+        input.on('error', failed);
+        parser.once(event, () => { if (!settled) {
+            settled = true;
+            ok();
+        } });
+        input.pipe(parser);
+    });
+}
+/** Consume local input once; extraction never races later edits to the caller's archive. */
+export async function consumeArchive(path, cache, artifact, checksum, signal) {
+    const { realpath, stat } = await import('node:fs/promises');
+    const source = await realpath(path), input = await open(source, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)), temporary = join(cache, 'local.partial-' + randomUUID());
+    try {
+        const metadata = await input.stat();
+        if (!metadata.isFile() || metadata.size > 2 * 1024 ** 3)
+            fail('invalid', 'Local runtime archive must be a regular file below two GiB.');
+        await mkdir(cache, { recursive: true, mode: 0o700 });
+        let size = 0;
+        const file = await open(temporary, 'wx', 0o600), hash = createHash('sha256');
+        try {
+            for await (const b of input.createReadStream({ signal, autoClose: false })) {
+                size += b.length;
+                if (size > 2 * 1024 ** 3)
+                    fail('limit', 'Local archive grew beyond two GiB.');
+                hash.update(b);
+                await file.writeFile(b);
+            }
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        const sha256 = hash.digest('hex');
+        if (checksum !== undefined && checksum.toLowerCase() !== sha256)
+            fail('binding', 'Local runtime archive differs from its expected SHA256.');
+        const handle = await open(temporary, 'r'), magic = Buffer.alloc(2);
+        try {
+            await handle.read(magic, 0, 2, 0);
+        }
+        finally {
+            await handle.close();
+        }
+        const format = magic.toString('hex') === '504b' ? 'zip' : 'tgz', owned = join(cache, sha256 + '.' + format);
+        try {
+            if (await fileSha256(owned) !== sha256)
+                fail('binding', 'Existing local-archive cache is corrupt.');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+            await rename(temporary, owned);
+        }
+        return { path: owned, artifact: { ...artifact, sha256, size, format } };
+    }
+    finally {
+        await input.close();
+        await rm(temporary, { force: true });
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { ToolArtifact } from './definition.js';
+/** Expected bytes come from the installed package, never a replaceable remote manifest. */
+export declare function catalogArtifact(sha256: string): ToolArtifact;

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

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+import { fail } from '../model.js';
+const catalog = JSON.parse(readFileSync(new URL('../../../runtime/tool-catalog.json', import.meta.url), 'utf8'));
+/** Expected bytes come from the installed package, never a replaceable remote manifest. */
+export function catalogArtifact(sha256) {
+    const a = catalog[sha256];
+    const dnspy = a?.url === 'https://github.com/dnSpyEx/dnSpy/releases/download/v6.6.0/dnSpy-net-win64.zip' && a.sha256 === '8ed48f165dc355e869f3a0037ad4f9216147f995a5ae0258b296eeef1f73aab0' && a.delivery?.publisher === 'dnSpyEx' && a.delivery.termsUrl === 'https://visualstudio.microsoft.com/license-terms/mlt552233/';
+    const microsoft = a?.delivery?.publisher === 'Microsoft' && new URL(a.delivery.termsUrl).hostname === 'learn.microsoft.com' && new URL(a.delivery.termsUrl).protocol === 'https:' && new URL(a.url).protocol === 'https:' && ['download.sysinternals.com', 'windbg.download.prss.microsoft.com'].includes(new URL(a.url).hostname);
+    const vendor = a?.delivery?.kind === 'vendor-direct' && Boolean(a.delivery.reason) && (dnspy || microsoft);
+    if (!a || a.sha256 !== sha256 || !(a.url.startsWith('https://github.com/iXab3r/insight-cli/releases/download/tool-') || vendor) || !Number.isSafeInteger(a.size) || a.size < 1)
+        fail('binding', 'Pinned tool distribution is absent or invalid in the retained catalog.');
+    return { ...a };
+}

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

@@ -0,0 +1,9 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { type ProcessRecord } from './supervisor.js';
+export interface ToolProcessHooks {
+    discover?: (c: CommandContext) => Promise<void>;
+    verify?: (record: ProcessRecord, c: CommandContext) => Promise<boolean | undefined>;
+    stop?: (record: ProcessRecord, c: CommandContext) => Promise<void>;
+    beforeKill?: (record: ProcessRecord, c: CommandContext) => Promise<void>;
+}
+export declare function toolProcessCommands(hooks?: Record<string, ToolProcessHooks>, metadata?: readonly CommandDefinition[]): CommandDefinition[];

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

@@ -0,0 +1,39 @@
+import { command, Permission, CliError } from '@eyeauras/cli-factory';
+import { listProcesses, processStatus, terminateProcess } from './supervisor.js';
+import { text } from '../model.js';
+const number = (value, max, min = 0) => { const n = Number(value); if (!Number.isSafeInteger(n) || n < min || n > max)
+    throw new CliError('Invalid process page bound.', { code: 'tool.input' }); return n; };
+export function toolProcessCommands(hooks = {}, metadata = []) {
+    const verifier = (c) => (record) => hooks[record.tool]?.verify?.(record, c) ?? Promise.resolve(undefined);
+    const discover = async (c) => { for (const h of Object.values(hooks))
+        await h.discover?.(c); };
+    const processes = {
+        name: 'processes', description: 'List owned tool processes; inspect or stop one recorded execution', permission: Permission.ReadOnly,
+        options: [{ flags: '--tool <name>', description: 'Filter by tool' }, { flags: '--session <id>', description: 'Filter by research session' }, { flags: '--target <id>', description: 'Filter by input target' },
+            { flags: '--all', description: 'Include completed and failed executions' }, { flags: '--limit <count>', description: 'Maximum records in this page', defaultValue: 50, parse: v => number(v, 1000, 1) },
+            { flags: '--offset <count>', description: 'Skip records before this page', defaultValue: 0, parse: v => number(v, 2147483647) }],
+        async run({ options: o }, c) {
+            await discover(c);
+            let items = await listProcesses(c.appArguments.AppDataDirectory, { tool: o.tool === undefined ? undefined : text(o.tool, 64), session: o.session === undefined ? undefined : text(o.session, 128), target: o.target === undefined ? undefined : text(o.target, 128) }, verifier(c));
+            if (!o.all)
+                items = items.filter(r => !['exited', 'failed'].includes(r.state));
+            const limit = number(o.limit, 1000, 1), offset = number(o.offset, 2147483647);
+            return { items: items.slice(offset, offset + limit), total: items.length, limit, offset, truncated: items.length > offset + limit };
+        },
+        children: [
+            command('show <process>', 'Inspect a recorded execution and its diagnostic paths', async ({ args }, c) => { await discover(c); return processStatus(c.appArguments.AppDataDirectory, text(args.process, 64), verifier(c)); }, { permission: Permission.ReadOnly }),
+            command('stop <process>', 'Request tool-aware graceful shutdown of an owned process', async ({ args }, c) => {
+                await discover(c);
+                return terminateProcess(c.appArguments.AppDataDirectory, text(args.process, 64), false, verifier(c), r => hooks[r.tool]?.stop?.(r, c) ?? Promise.resolve());
+            }, { permission: Permission.Update }),
+            command('kill <process>', 'Force termination of a verified owned process; preserve uncertain work', async ({ args }, c) => {
+                await discover(c);
+                const id = text(args.process, 64), r = await processStatus(c.appArguments.AppDataDirectory, id, verifier(c));
+                if (r.state === 'running')
+                    await hooks[r.tool]?.beforeKill?.(r, c);
+                return terminateProcess(c.appArguments.AppDataDirectory, id, true, verifier(c));
+            }, { permission: 'Destructive' }),
+        ],
+    };
+    return [command('tools', 'Inspect research tools and executions', [...metadata, processes])];
+}

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

@@ -0,0 +1,11 @@
+/** For reviewed native helper execs started inside an adapter worker, never an external target. */
+export declare function inheritedDeadlineEnvironment(deadlineUnixSeconds: number, receipts: string): Promise<{
+    DYLD_INSERT_LIBRARIES: string;
+    INSIGHT_NATIVE_DEADLINE_UNIX_SECONDS: string;
+    INSIGHT_NATIVE_DEADLINE_RECEIPTS: string;
+}>;
+/** Internal, first-party exec helper. No service or timer in the owner is needed after exec. */
+export declare function deadlineLaunch(executable: string, args: string[], timeoutMs: number): Promise<{
+    executable: string;
+    arguments: string[];
+}>;

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

@@ -0,0 +1,32 @@
+import { fileURLToPath } from 'node:url';
+import { CliError } from '@eyeauras/cli-factory';
+import { fileSha256 } from './archives.js';
+import { isAbsolute } from 'node:path';
+/** For reviewed native helper execs started inside an adapter worker, never an external target. */
+export async function inheritedDeadlineEnvironment(deadlineUnixSeconds, receipts) {
+    if (process.platform !== 'darwin' || process.arch !== 'arm64' || !Number.isInteger(deadlineUnixSeconds) || deadlineUnixSeconds <= Date.now() / 1000 || deadlineUnixSeconds > Date.now() / 1000 + 600 || !isAbsolute(receipts))
+        throw new CliError('Invalid inherited native deadline.', { code: 'tool.configuration' });
+    const library = fileURLToPath(new URL('../../../runtime/native/deadline-alarm-darwin-universal.dylib', import.meta.url));
+    if (library.includes(':') || await fileSha256(library) !== 'cd5ebd65aa419b79cb327f2ae872f98f3fd222b93049c909e409776eab65b8ef')
+        throw new CliError('Inherited deadline library differs from its reviewed build or has an unsupported loader path.', { code: 'tool.binding' });
+    return { DYLD_INSERT_LIBRARIES: library, INSIGHT_NATIVE_DEADLINE_UNIX_SECONDS: String(deadlineUnixSeconds), INSIGHT_NATIVE_DEADLINE_RECEIPTS: receipts };
+}
+/** Internal, first-party exec helper. No service or timer in the owner is needed after exec. */
+export async function deadlineLaunch(executable, args, timeoutMs) {
+    if (process.platform === 'linux' && process.arch === 'x64') {
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000)
+            throw new CliError('Native deadline must be 1–600 seconds.', { code: 'tool.configuration' });
+        const helper = fileURLToPath(new URL('../../../runtime/native/child-deadline-linux-x64', import.meta.url));
+        if (await fileSha256(helper) !== 'e070e2de9a21aea78f224062877cdc0264be11229af314d3b88ff3b6bd77e26f')
+            throw new CliError('Packaged Linux launcher differs from its reviewed build.', { code: 'tool.binding' });
+        return { executable: helper, arguments: [String(Math.ceil(timeoutMs / 1000)), String(process.pid), executable, ...args] };
+    }
+    if (process.platform !== 'darwin' || process.arch !== 'arm64')
+        throw new CliError('A packaged native deadline is unavailable on this host.', { code: 'tool.unsupported' });
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000)
+        throw new CliError('Native deadline must be between one and 600 seconds.', { code: 'tool.configuration' });
+    const helper = fileURLToPath(new URL('../../../runtime/native/deadline-exec-darwin-arm64', import.meta.url));
+    if (await fileSha256(helper) !== '32c146075d1c83422b068eeedd4a244d5e30cb768b279b185756c5d3b8008d88')
+        throw new CliError('Packaged native deadline differs from its reviewed build.', { code: 'tool.binding' });
+    return { executable: helper, arguments: [String(Math.ceil(timeoutMs / 1000)), '--', executable, ...args] };
+}