@eyeauras/insight-cli 0.1.0 → 0.2.1

package/.cli-package-build.json

@@ -1 +1 @@
-{"version":1,"artifact":"c3714e4dd4db303fdccc352327ce7c7f5dff074726238298a6953be70aca1db3"}
+{"version":1,"artifact":"b65915991d87f45608bceba8cc7afa48b2e04f292149acf604aaf91ec2d2d6ba"}

package/README.md

@@ -17,14 +17,40 @@ The executable is `insight-cli`. Its global npm executable directory must be on
 No source checkout, TypeScript build or separate Factory installation is required.
 The pinned Factory IPC runtime is a normal npm dependency fetched from an immutable
 GitHub tarball URL; installation therefore needs npm registry and GitHub access.
-Ghidra 12.1.2 and Java 21 are external dependencies for Ghidra commands.
+Use `insight-cli ghidra install` to deliver the pinned Ghidra/JDK/native/server runtime.
+External Ghidra launchers and Java paths are also supported.
+`insight-cli ilspy install` delivers ILSpy and its private .NET runtime for managed-code
+research. Tool downloads use pinned assets retained in our GitHub Releases.
+Use `insight-cli tools processes` to inspect owned executions across tools.
 Help, skill discovery and saving ordinary files do not need Ghidra or Java.
 
+Downloading a tool does not expose it in an agent's tool list. Connect the packaged skills
+to your agent host, or explicitly give the agent the path returned by `insight-cli skill
+insight-re --json`. See [agent setup](references/agent-setup.md) for tested project-local
+Codex setup and a practical usability check. Installation leaves agent settings unchanged.
+
+## Discover the toolbox
+
+```sh
+insight-cli tools list --json
+insight-cli tools show die --json
+insight-cli skill insight-die --json
+```
+
+The catalog describes the adapters and their packaged skills before any runtime is downloaded.
+Use each tool's `status` to check the selected profile, then follow its skill and generated help.
+The toolbox includes Ghidra, ILSpy, 7-Zip, LLVM utilities, DiE, LLDB, Frida, WinDbg, strace and .NET dump/stack/trace; platform
+and capability limits are explicit per tool. A partial classification or a failed native process
+is not a complete finding. Preserve useful output in ordinary project files and checkpoint it
+with `artifacts save` when useful. Existing project RE instructions retain precedence.
+
 ## Start
 
 ```sh
-insight-cli profile create local --java /path/to/java --ghidra-home /path/to/ghidra
+insight-cli profile create local
 insight-cli --profile local permissions grant Update
+insight-cli --profile local ghidra install
+insight-cli --profile local ghidra status
 insight-cli --profile local ghidra open ./client.exe --session new --json
 ```
 
@@ -53,3 +79,8 @@ and `insight-cli skill insight-re` to locate packaged instructions and reference
 
 Full documentation and verification: [GitHub](https://github.com/iXab3r/insight-cli).
 License: MIT. The bundled GhidraMCP bridge has its own Apache-2.0 license and notice.
+
+Runtime management, local archives and external paths: [managed runtime](references/managed-runtime.md).
+The host debugger and OS permissions are checked separately by `ghidra doctor`.
+
+Static .NET commands and ordinary output files: [ILSpy](references/ilspy.md).

package/SKILL.md

@@ -1,55 +1,42 @@
 ---
 name: insight-cli
-description: Research several executable inputs through durable independent sessions and isolated Ghidra contexts using the matching insight-cli facade. Agents supply the investigation and interpret results.
+description: Choose and prepare reverse-engineering capabilities from the insight-cli toolbox for binary, managed-code and runtime investigations. Use to discover the appropriate tool or its packaged skill before installing native runtimes.
 ---
 
-# insight-cli 0.1.0
-
-This skill and its executable helper are one npm package. Run `insight-cli skill` to locate
-these installed resources. Use generated `--help` for syntax; read the references as needed.
-Follow applicable project RE rules for tools, source of truth, evidence layout and format;
-this package's walkthroughs fill gaps rather than replacing those conventions.
-
-For coordinating a reverse-engineering investigation with ordinary files, external tools
-and multiple agents, read the packaged [Insight RE skill](skills/insight-re/SKILL.md),
-also located by `insight-cli skill insight-re`. When a retained checkpoint is useful, save
-a completed project file or folder with
-`insight-cli artifacts save <path>`; [save semantics](references/artifacts.md) describe the
-ordinary saved copy and its receipt. Neither operation requires a Ghidra installation.
-
-1. Select the configured runtime profile. Ordinary work uses a managed local server; an external
-   server is optional. See [setup](references/setup.md). Factory permissions authorize changes.
-2. Open the input with `ghidra open <input> --session new`. Retain the returned session and target.
-   Another agent chooses `new` independently; one session can open several inputs.
-3. Pass both `--session` and `--target` on research calls. Follow strings to xrefs and their
-   function addresses, then inspect/decompile. See [research](references/research.md).
-4. Rename functions or set/clear comments through ordinary commands. An `applied` result means
-   verified saved private work. Other sessions keep their own views; local edits remain unpublished in the default manual mode.
-5. By default, publish explicitly with `ghidra merge`; receive safe shared changes with `ghidra refresh`.
-   Resolve overlapping names/comments against an explicitly observed shared value. A conflict
-   prevents the whole selected merge and retains local work.
-6. Continue with `ghidra open --session <id> --target <id>`. For uncertain outcomes inspect
-   `sessions status <id> --target <id>` and [recovery](references/recovery.md). Supplying a stable
-   optional `--request-id` lets a repeated changing intent retrieve its outcome without rerunning.
-
-The facade exposes the pinned static research/editing catalog, merge/refresh, project/server/GUI
-controls, debugger, archive exchange and supported recovery. Preserve private work
-and journals while an outcome is unresolved. The CLI supplies the investigation tools; agents
-choose research goals and interpret findings.
-Installing this package does not register this skill in an agent's configuration.
-
-For project files, program export/import and configured-server administration, read
-[administration](references/administration.md). These operations preserve separate research views;
-their external effects do not participate in program merge.
-
-For owned GUI execution, CPU state, breakpoints and retained traces, read
-[debugger](references/debugger.md). Execution side effects remain separate from program publication.
-
-For explicit external documentation exchange and retained submission outcomes, read
-[archive](references/archive.md).
-
-For selected native SDK extensions (VT, DB differences, byte/assembly edits, formats, GDT,
-FID/BSim, namespaces and typed IR), read [native workflows](references/native-workflows.md).
-
-For managed SDK extension modules, actual language/analyzer/plugin discovery and opt-in
-automatic synchronization, read [extensions and sync](references/extensions-and-sync.md).
+# insight-cli 0.2.1
+
+If local help/status reports AppData or IPC access denied, retry that **read-only probe**
+with the agent host's normal permission escalation, then use that route for later authorized
+CLI calls too. An explicit **no command was sent** denial is known undispatched and can be
+retried through that route. Keep HOME, profile and owner state; see
+[host execution permissions](references/agent-execution.md). A lost mutation reply needs
+request/status recovery, never blind retry.
+
+Read the project's RE instructions and existing findings first. They own tool choices,
+evidence layout, formats and source of truth. These skills fill the remaining gaps.
+
+1. Run `insight-cli tools list --json` to discover the capabilities shipped in this version.
+   The catalog works before profile configuration, downloads or IPC startup. A downloaded
+   runtime is not needed to discover what a tool does.
+2. Use `insight-cli tools show <tool> --json` for tasks, supported inputs/platforms,
+   dependencies and its skill path. Read that skill before preparing or using the tool.
+3. Select a profile for execution. Run the selected application's `status` and generated
+   `--help`. `install` prepares its private runtime; archives/offline and external paths
+   are tool-specific and described in its skill. Update permission is required for tool
+   preparation/execution and saved changes: `insight-cli permissions grant Update`.
+4. Answer the question with focused queries and ordinary project files. Follow results to
+   useful detail; a large raw dump is not an interpretation. External tools remain welcome.
+5. Preserve completed files with `insight-cli artifacts save <path> --json` when a retained
+   checkpoint helps. For several agents sharing Ghidra analysis, use separate sessions,
+   then explicit merge/refresh as described by its skill.
+
+`insight-cli skill` locates this entry point. `skill insight-re` gives investigation and
+multi-agent guidance; `skill insight-ghidra`, `skill insight-ilspy` and
+`skill insight-artifacts` locate the relevant instructions. Skills ship with the CLI;
+installing npm binaries does not register them in an agent host. See
+[agent connection](references/agent-setup.md) for current setup and access requirements.
+
+Use generated help as the syntax authority. Catalog metadata describes shipped capabilities;
+profile runtime readiness comes from the selected tool's `status`. Unavailable profile/IPC
+access means execution readiness is unknown. Preserve work and diagnose access before trying
+again; stopping a shared owner does not grant a denied agent access to it.

package/dist/src/administration-results.js

@@ -12,7 +12,7 @@ export function administrationResult(operation, p, raw) {
     const value = object(raw);
     if (JSON.stringify(value).length > 1048576)
         fail('limit', 'Administration result exceeds one MiB.');
-    if (['status', 'connect', 'disconnect'].includes(operation)) {
+    if (['status', 'connect', 'disconnect', 'stop'].includes(operation)) {
         if (typeof value.connected !== 'boolean' || !['local', 'external'].includes(String(value.mode)))
             fail('partial', 'Server status is incomplete.');
         if (value.connected && typeof value.repository !== 'string')

package/dist/src/administration.d.ts

@@ -11,4 +11,4 @@ export declare class Administration {
     read(operation: string, parameters: Record<string, unknown>): Promise<Record<string, unknown>>;
     change(operation: string, parameters: Record<string, unknown>, callerId?: string): Promise<unknown>;
 }
-export declare function administrationCommands(service: (context: CommandContext) => Administration): CommandDefinition[];
+export declare function administrationCommands(service: (context: CommandContext) => Administration, unconfiguredStatus?: (context: CommandContext) => Promise<Record<string, unknown> | undefined>): CommandDefinition[];

package/dist/src/administration.js

@@ -1,6 +1,7 @@
 import { command, Permission } from '@eyeauras/cli-factory';
 import { fail, id, text } from './model.js';
 import { option, parsed, key } from './arguments.js';
+import { runtimeProcesses } from './runtime-manager.js';
 import { administrationResult } from './administration-results.js';
 const repository = (value) => { const name = text(value, 128); if (name !== name.trim() || /[\\/\0]/.test(name) || name.startsWith('.'))
     fail('invalid', 'Repository name must be a single bounded name.'); return name; };
@@ -67,6 +68,8 @@ export class Administration {
 const repo = { name: 'repository', type: 'string', required: true }, path = { name: 'path', type: 'string', required: false, default: '/' };
 const leaves = [
     { names: ['status'], operation: 'status', gate: Permission.ReadOnly, params: [] },
+    { names: ['start'], operation: 'connect', gate: Permission.Update, params: [] },
+    { names: ['stop'], operation: 'stop', gate: Permission.Update, params: [] },
     { names: ['connect'], operation: 'connect', gate: Permission.Update, params: [] },
     { names: ['disconnect'], operation: 'disconnect', gate: Permission.Update, params: [] },
     { names: ['repositories', 'list'], operation: 'repositories', gate: Permission.ReadOnly, params: [] },
@@ -81,11 +84,22 @@ const leaves = [
     { names: ['admin', 'terminate-checkout'], operation: 'terminate_checkout', gate: 'Destructive', params: [repo, { ...path, required: true, default: undefined }, { name: 'checkout_id', type: 'string', required: false }] },
     { names: ['admin', 'terminate-all-checkouts'], operation: 'terminate_all_checkouts', gate: 'Destructive', params: [repo, path] },
 ];
-export function administrationCommands(service) {
+export function administrationCommands(service, unconfiguredStatus) {
     const children = [];
     for (const leaf of leaves) {
         const changing = leaf.gate !== Permission.ReadOnly;
-        const definition = command(leaf.names.at(-1), 'Operate on the configured server and explicit repository', ({ options: o }, c) => {
+        const definition = command(leaf.names.at(-1), 'Operate on the configured server and explicit repository', async ({ options: o }, c) => {
+            if (leaf.operation === 'stop') {
+                if (c.profile.values.server)
+                    fail('authorization', 'External server lifecycle is owned by its operator. Use server disconnect.');
+                if ((await runtimeProcesses(c.appArguments.AppDataDirectory)).some(p => p.kind !== 'server'))
+                    fail('busy', 'Close active Ghidra contexts before stopping their server.');
+            }
+            if (leaf.operation === 'status' && unconfiguredStatus) {
+                const passive = await unconfiguredStatus(c);
+                if (passive)
+                    return passive;
+            }
             const parameters = {};
             for (const p of leaf.params) {
                 const value = o[key(p.name)];

package/dist/src/binary.d.ts

@@ -0,0 +1,3 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import type { Workspace } from './workspace.js';
+export declare function binaryCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/binary.js

@@ -0,0 +1,74 @@
+import { command, Permission, CliError } from '@eyeauras/cli-factory';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir, writeFile, copyFile, readFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { release } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { runTool } from './tool-runtime/run.js';
+import { atomicWrite } from './tool-runtime/store.js';
+import { fileSha256 } from './tool-runtime/archives.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const helper = fileURLToPath(new URL('../../runtime/native/binary/insight-binary-darwin-arm64', import.meta.url));
+export function binaryCommands(workspace) {
+    const run = (mode) => command(mode + ' [input]', mode === 'query' ? 'Inspect bounded PE, ELF or thin Mach-O metadata without executing the input' : 'Change one expected PE subsystem field in a new copy and independently read it back', async ({ args, options: o }, c) => {
+        if (process.platform !== 'darwin' || process.arch !== 'arm64' || Number(release().split('.')[0]) < 23)
+            fail('unsupported', 'The packaged LIEF facade is currently verified on macOS14+ ARM64; input formats are PE, ELF and thin Mach-O.');
+        if (Boolean(args.input) === Boolean(o.target))
+            fail('invalid', 'Supply one binary input or --target.');
+        const view = mode === 'query' ? text(o.view ?? 'overview', 16) : undefined;
+        if (view && !['overview', 'sections', 'libraries', 'imports', 'exports'].includes(view))
+            fail('invalid', 'Use overview, sections, libraries, imports or exports.');
+        const limit = number(o.limit ?? 50, 500, 1), offset = number(o.offset ?? 0, 1000000), w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target));
+        if (target.input.size > 64 * 1024 ** 2)
+            fail('limit', 'Structured binary input exceeds 64 MiB.');
+        const input = await w.artifacts.verify(target.input);
+        const directory = join(c.appArguments.AppDataDirectory, 'runtime/binary/queries', randomUUID()), plan = join(directory, 'plan.json'), edited = join(directory, 'edited.exe');
+        let edit;
+        if (mode === 'edit-subsystem') {
+            if (!o.output)
+                fail('invalid', 'Copy-only editing requires --output FILE.');
+            const values = { gui: 2, console: 3 }, expected = values[text(o.expectSubsystem, 16)], value = values[text(o.subsystem, 16)];
+            if (!expected || !value || expected === value)
+                fail('invalid', 'Choose a different gui/console subsystem and an explicit --expect-subsystem.');
+            edit = { expectedSubsystem: expected, subsystem: value, output: edited };
+        }
+        await atomicWrite(plan, { schema: 1, mode, input, view, filter: o.filter === undefined ? undefined : text(o.filter, 4096), limit, offset, ...edit });
+        const result = await runTool(c, { tool: 'binary', role: mode, executable: helper, arguments: [plan], timeoutMs: 60000, maxOutputBytes: 8 * 1024 ** 2, nativeDeadline: true, target: target.id, metadata: { view, helperSha256: await fileSha256(helper) } });
+        let observation;
+        try {
+            observation = JSON.parse(result.stdout);
+        }
+        catch {
+            throw new CliError('Binary parser did not return complete bounded JSON.', { code: 'tool.partial', result: { process: result.process, diagnostics: result.diagnostics } });
+        }
+        if (!['completed', 'partial'].includes(observation?.state) || typeof observation.complete !== 'boolean')
+            fail('partial', 'Binary query receipt was not verified.', { process: result.process, diagnostics: result.diagnostics });
+        if (await fileSha256(input) !== target.binarySha256)
+            fail('binding', 'Immutable binary changed during inspection.');
+        const warnings = result.stderr.trim(), value = { ...observation, ...(warnings ? { state: 'partial', complete: false, reason: 'native_parser_diagnostics', warnings: warnings.slice(0, 4096), warningsTruncated: warnings.length > 4096 } : {}), target: target.id, inputSha256: target.binarySha256, process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics };
+        if (mode === 'edit-subsystem') {
+            if (!value.complete)
+                fail('partial', 'Native parser diagnostics prevent accepting the copied edit.', value);
+            const before = await readFile(input), after = await readFile(edited), at = Number(BigInt(observation.fieldOffset));
+            if (after.length !== before.length || !Number.isSafeInteger(at) || at < 0 || at + 2 > before.length)
+                fail('binding', 'Copied PE edit did not retain its field bounds.');
+            for (let n = 0; n < before.length; n++)
+                if (n !== at && n !== at + 1 && before[n] !== after[n])
+                    fail('binding', 'Copied PE edit changed bytes outside the declared field.');
+            const output = resolve(c.cwd, text(o.output, 4096));
+            await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+            await copyFile(edited, output, constants.COPYFILE_EXCL);
+            return { ...value, output, outputSha256: await fileSha256(output), originalPreserved: true };
+        }
+        if (o.output) {
+            const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify(value, null, 2) + '\n';
+            await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+            await writeFile(output, content, { flag: 'wx', mode: 0o600 });
+            return { state: value.state, complete: value.complete, reason: value.reason, target: target.id, output, bytes: Buffer.byteLength(content), process: result.process, diagnostics: result.diagnostics };
+        }
+        return value;
+    }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse immutable input bytes' }, { flags: '--output <file>', description: mode === 'query' ? 'Save this bounded page to a new JSON file' : 'Required new executable copy; never overwrite an existing file' }, ...(mode === 'query' ? [{ flags: '--view <kind>', description: 'overview, sections, libraries, imports or exports', defaultValue: 'overview' }, { flags: '--filter <text>', description: 'Literal metadata name substring before pagination' }, { flags: '--limit <count>', description: 'Return 1–500 rows', defaultValue: 50 }, { flags: '--offset <count>', description: 'Skip matching rows', defaultValue: 0 }] : [{ flags: '--expect-subsystem <kind>', description: 'Required current PE subsystem: gui or console', required: true }, { flags: '--subsystem <kind>', description: 'Required different PE subsystem: gui or console', required: true }])] });
+    return [command('binary', 'Structured binary metadata and guarded copy-only edits', [run('query'), run('edit-subsystem')])];
+}

package/dist/src/capture.d.ts

@@ -0,0 +1,3 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import type { Workspace } from './workspace.js';
+export declare function captureCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/capture.js

@@ -0,0 +1,220 @@
+import { command, Permission, CliError } from '@eyeauras/cli-factory';
+import { join, resolve, dirname, basename, sep } from 'node:path';
+import { mkdir, writeFile, copyFile, chmod, open, realpath, lstat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { release } from 'node:os';
+import { createHash } from 'node:crypto';
+import { runTool } from './tool-runtime/run.js';
+import { atomicWrite, readJson } from './tool-runtime/store.js';
+import { listProcesses } from './tool-runtime/supervisor.js';
+import { fileSha256 } from './tool-runtime/archives.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const sha = (b) => createHash('sha256').update(b).digest('hex');
+const list = (v) => v === undefined ? [] : (Array.isArray(v) ? v : [v]).map(s => text(s, 4096));
+const root = (c, request) => { if (!/^a_[a-f0-9-]{36}$/.test(request))
+    fail('invalid', 'Select a capture request returned by capture run.'); return join(c.appArguments.AppDataDirectory, 'runtime/capture', request); };
+function relativeFile(value) { const name = text(value, 1024); if (name.includes('\\') || name.startsWith('/') || name.split('/').some(p => !p || p === '.' || p === '..') || name.toLowerCase() === 'subject')
+    fail('invalid', 'Watch paths must be ordinary relative files inside the owned working directory.'); return name; }
+async function boundedFile(path, max = 16 * 1024 ** 2) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.size > max)
+            fail('limit', 'Selected file must be regular and within its byte bound.');
+        const chunks = [];
+        let bytes = 0;
+        for await (const chunk of handle.createReadStream({ autoClose: false })) {
+            bytes += chunk.length;
+            if (bytes > max)
+                fail('limit', 'Selected file grew beyond its capture bound.');
+            chunks.push(chunk);
+        }
+        const after = await handle.stat();
+        if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || before.ino !== after.ino)
+            fail('binding', 'Selected file changed while being read.');
+        return Buffer.concat(chunks);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function snapshot(directory, name) {
+    const file = join(directory, name);
+    try {
+        const parent = await realpath(dirname(file)), base = await realpath(directory);
+        if (parent !== base && !parent.startsWith(base + sep))
+            return { path: name, state: 'unavailable', reason: 'parent_outside_owned_directory' };
+        const info = await lstat(file);
+        if (!info.isFile() || info.isSymbolicLink())
+            return { path: name, state: 'unavailable', reason: 'not_regular_file' };
+        const bytes = await boundedFile(file);
+        return { path: name, state: 'present', bytes: bytes.length, sha256: sha(bytes) };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { path: name, state: 'absent' };
+        return { path: name, state: 'unavailable', reason: error.code ?? 'unreadable' };
+    }
+}
+function pageStream(value, offset, limit) { if (!value)
+    return { available: false }; const all = Buffer.from(value.base64, 'base64'), bytes = all.subarray(offset, offset + limit); return { available: true, totalBytes: value.bytes, sha256: value.sha256, offset, limit, base64: bytes.toString('base64'), text: bytes.toString('utf8'), textEncoding: 'UTF-8 preview with replacement; base64 preserves exact selected bytes', truncated: offset + limit < all.length }; }
+function overview(receipt) { const { stdout, stderr, files, ...rest } = receipt; return { ...rest, stdout: pageStream(stdout, 0, 256), stderr: pageStream(stderr, 0, 256), declaredFiles: files.length, fileChanges: files.filter(f => f.change !== 'unchanged').map(f => ({ path: f.path, change: f.change })) }; }
+async function exportReceipt(c, value, option) { const output = resolve(c.cwd, text(option, 4096)), content = JSON.stringify(value, null, 2) + '\n'; await mkdir(dirname(output), { recursive: true, mode: 0o700 }); await writeFile(output, content, { flag: 'wx', mode: 0o600 }); return output; }
+async function receiptFor(c, w, request) { const stored = w.administration(request); if (stored.operation !== 'capture.run')
+    fail('invalid', 'Request is not an owned process capture.'); const file = join(root(c, request), 'capture.json'), receipt = await readJson(file); if (receipt && stored.state === 'applied') {
+    const result = stored.result;
+    if (result?.receiptSha256 !== await fileSha256(file))
+        fail('binding', 'Capture receipt differs from its durable outcome.');
+    validateReport(receipt);
+    if (receipt.request !== request)
+        fail('binding', 'Capture receipt has a different request identity.');
+    return receipt;
+} return { state: stored.state === 'accepted' ? 'prepared' : 'unknown', complete: false, request, intent: stored.intent, processes: (await listProcesses(c.appArguments.AppDataDirectory, { tool: 'capture' })).filter(p => p.metadata?.request === request), directory: root(c, request), workingDirectory: join(root(c, request), 'working'), scope: 'No completed capture receipt. Inspect retained process/input/files explicitly; never rerun this request to manufacture a result.' }; }
+function validateReport(value) {
+    const hash = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+    if (value?.schema !== 1 || value.kind !== 'insight-process-capture' || typeof value.complete !== 'boolean' || value.state !== (value.complete ? 'completed' : 'partial') || !hash(value.inputSha256) || !Array.isArray(value.files) || value.files.length > 32 || !value.execution || !Array.isArray(value.arguments) || value.arguments.length > 64 || value.arguments.some(a => typeof a !== 'string' || a.length > 4096) || !Array.isArray(value.inputs) || value.inputs.length > 32)
+        fail('invalid', 'Select a structured insight process capture report.');
+    if (value.execution.exitCode !== null && (!Number.isInteger(value.execution.exitCode) || value.execution.exitCode < 0 || value.execution.exitCode > 255))
+        fail('invalid', 'Invalid captured exit code.');
+    let bytes = 0;
+    for (const stream of [value.stdout, value.stderr])
+        if (stream) {
+            if (!hash(stream.sha256) || typeof stream.base64 !== 'string')
+                fail('invalid', 'Malformed capture byte stream.');
+            const raw = Buffer.from(stream.base64, 'base64');
+            if (raw.toString('base64') !== stream.base64 || raw.length !== stream.bytes || sha(raw) !== stream.sha256 || (bytes += raw.length) > 4 * 1024 ** 2)
+                fail('binding', 'Capture byte stream differs from its bounds/hash.');
+        }
+    if (value.complete && (!value.stdout || !value.stderr || value.execution.exitCode === null || value.execution.signal !== null))
+        fail('invalid', 'A complete capture requires known terminal output and exit.');
+    const seen = new Set();
+    for (const file of value.files) {
+        const name = relativeFile(file.path);
+        if (seen.has(name))
+            fail('invalid', 'Duplicate declared capture path.');
+        seen.add(name);
+        for (const observed of [file.before, file.after])
+            if (!observed || observed.path !== name || !['present', 'absent', 'unavailable'].includes(observed.state) || observed.state === 'present' && (!hash(observed.sha256) || !Number.isSafeInteger(observed.bytes) || observed.bytes < 0 || observed.bytes > 16 * 1024 ** 2))
+                fail('invalid', 'Malformed declared file observation.');
+    }
+}
+export function captureCommands(workspace) {
+    const run = command('run [input]', 'Capture one explicitly selected owned native execution and declared file snapshots', async ({ args, options: o }, c) => {
+        if (process.platform !== 'darwin' || process.arch !== 'arm64' || Number(release().split('.')[0]) < 23)
+            fail('unsupported', 'Process capture is verified on macOS14+ ARM64 thin native executables.');
+        if (Boolean(args.input) === Boolean(o.target))
+            fail('invalid', 'Supply one native program or --target.');
+        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);
+        if (target.input.size > 64 * 1024 ** 2)
+            fail('limit', 'Owned executable exceeds 64 MiB.');
+        const header = (await boundedFile(input, 64 * 1024 ** 2)).subarray(0, 32);
+        if (header.length < 32 || header.subarray(0, 4).toString('hex') !== 'cffaedfe' || header.readUInt32LE(4) !== 0x0100000c || header.readUInt32LE(12) !== 2)
+            fail('unsupported', 'Select a thin ARM64 Mach-O executable, not a PE/ELF, script, library or universal container.');
+        const argv = list(o.arg), selected = list(o.inputFile), watched = [...new Set(list(o.watch).map(relativeFile))];
+        if (argv.length > 64 || selected.length > 32 || watched.length > 32)
+            fail('limit', 'Capture permits 64 literal arguments, 32 selected input files and 32 watch paths.');
+        const timeoutMs = number(o.timeoutSeconds ?? 10, 600, 1) * 1000, files = [];
+        let total = 0;
+        for (const option of selected) {
+            const path = resolve(c.cwd, option), name = basename(path);
+            if (name.toLowerCase() === 'subject' || files.some(f => f.name.normalize('NFD').toLowerCase() === name.normalize('NFD').toLowerCase()) || !/^[^/\\\0]+$/.test(name))
+                fail('invalid', 'Selected input basenames must be ordinary and unique.');
+            const data = await boundedFile(path);
+            if ((total += data.length) > 64 * 1024 ** 2)
+                fail('limit', 'Selected input files exceed 64 MiB.');
+            files.push({ name, sha256: sha(data), bytes: data.length, data });
+        }
+        const stdin = o.stdinFile ? await boundedFile(resolve(c.cwd, text(o.stdinFile, 4096)), 1024 ** 2) : Buffer.alloc(0);
+        if (o.output && !(o.requestId && w.administrationByCaller(id(o.requestId))))
+            try {
+                await lstat(resolve(c.cwd, text(o.output, 4096)));
+                fail('invalid', 'Capture output already exists.');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        const intent = { target: target.id, inputSha256: target.binarySha256, arguments: argv, inputs: files.map(({ data, ...f }) => f), stdin: { sha256: sha(stdin), bytes: stdin.length }, watch: watched, timeoutMs, output: o.output ? resolve(c.cwd, text(o.output, 4096)) : undefined };
+        const reservation = w.reserveAdministration('capture.run', intent, o.requestId === undefined ? undefined : id(o.requestId)), request = reservation.request.id;
+        if (reservation.replay) {
+            const previous = await receiptFor(c, w, request);
+            if (reservation.request.state === 'applied' && 'kind' in previous) {
+                if (!previous.complete)
+                    throw new CliError('Prior capture remains partial; no execution was repeated.', { code: 'tool.capture.partial', result: overview(previous) });
+                return { ...overview(previous), replayed: true };
+            }
+            throw new CliError('Capture request already exists without a verified complete outcome; no execution was repeated.', { code: 'tool.capture.unknown', result: previous });
+        }
+        const directory = root(c, request), working = join(directory, 'working'), subject = join(working, 'subject');
+        await mkdir(working, { recursive: true, mode: 0o700 });
+        await copyFile(input, subject, constants.COPYFILE_EXCL);
+        await chmod(subject, 0o700);
+        if (await fileSha256(subject) !== target.binarySha256)
+            fail('binding', 'Owned executable differs from captured input.');
+        for (const f of files)
+            await writeFile(join(working, f.name), f.data, { flag: 'wx', mode: 0o600 });
+        const before = await Promise.all(watched.map(name => snapshot(working, name)));
+        await atomicWrite(join(directory, 'intent.json'), { request, ...intent });
+        w.administrationState(request, 'running', { directory });
+        let result, failure;
+        try {
+            result = await runTool(c, { tool: 'capture', role: 'run', executable: subject, arguments: argv, cwd: working, input: stdin, timeoutMs, maxOutputBytes: 4 * 1024 ** 2, retainRawOutput: true, nativeDeadline: true, acceptedCodes: Array.from({ length: 127 }, (_, n) => n), target: target.id, metadata: { request, working, scope: 'Owned program copy; selected input copies and declared file snapshots; no shell or OS sandbox' } });
+        }
+        catch (error) {
+            failure = error;
+            if (error instanceof CliError && error.result && typeof error.result === 'object' && 'stdout' in error.result)
+                result = error.result;
+        }
+        const after = await Promise.all(watched.map(name => snapshot(working, name))), unavailable = [...before, ...after].some(f => f.state === 'unavailable');
+        const stream = async (file) => { if (!file)
+            return; const b = await boundedFile(file, 4 * 1024 ** 2); return { bytes: b.length, sha256: sha(b), base64: b.toString('base64') }; };
+        const value = { schema: 1, kind: 'insight-process-capture', request, state: failure || unavailable ? 'partial' : 'completed', complete: !failure && !unavailable, ...(failure ? { reason: failure instanceof CliError ? failure.code : 'capture_failed' } : unavailable ? { reason: 'declared_file_unavailable' } : {}), target: target.id, inputSha256: target.binarySha256, timeoutMs, arguments: argv, inputs: intent.inputs, stdin: intent.stdin, stdout: await stream(result?.rawStdout), stderr: await stream(result?.rawStderr), execution: { process: result?.process, exitCode: result?.exitCode ?? null, signal: result?.signal ?? null, elapsedMs: result?.elapsedMs, diagnostics: result?.diagnostics }, files: watched.map((path, n) => { const a = before[n], b = after[n]; return { path, before: a, after: b, change: a.state === 'unavailable' || b.state === 'unavailable' ? 'unknown' : a.state === b.state && (a.state === 'absent' || a.sha256 === b.sha256) ? 'unchanged' : a.state === 'absent' ? 'created' : b.state === 'absent' ? 'deleted' : 'changed' }; }), scope: 'One owned program copy with literal argv, exact bounded stdout/stderr bytes and selected file snapshots. This is not an OS sandbox, a trace of all filesystem/network effects or proof of causality. Native deadline assumes the subject does not deliberately replace the inherited alarm. Known nonzero subject exits are captured outcomes; interrupted/overflow/unknown capture stays partial.' };
+        if (!value.stdout || !value.stderr) {
+            value.complete = false;
+            value.state = 'partial';
+            value.reason ??= 'raw_output_unavailable';
+        }
+        const path = join(directory, 'capture.json');
+        await atomicWrite(path, value);
+        w.administrationState(request, 'applied', { receipt: path, receiptSha256: await fileSha256(path), complete: value.complete });
+        const output = o.output ? await exportReceipt(c, value, o.output) : undefined;
+        if (!value.complete)
+            throw new CliError('Capture is partial; retained output/files are available and execution was not replayed.', { code: 'tool.capture.partial', result: { ...overview(value), directory, ...(output ? { output } : {}) } });
+        return { ...overview(value), directory, ...(output ? { output } : {}) };
+    }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse immutable native program bytes' }, { flags: '--arg <text...>', description: 'Literal subject arguments; no shell string or expansion' }, { flags: '--input-file <file...>', description: 'Copy selected regular files by unique basename into owned cwd' }, { flags: '--stdin-file <file>', description: 'Optional bounded input byte stream (up to 1 MiB)' }, { flags: '--watch <path...>', description: 'Declared relative regular files to snapshot before and after execution' }, { flags: '--timeout-seconds <seconds>', description: 'Owned execution deadline (1–600)', defaultValue: 10 }, { flags: '--output <file>', description: 'Save a new portable bounded JSON capture, including exact output base64' }, { flags: '--request-id <id>', description: 'Retrieve this exact capture intent without executing it again' }] });
+    const show = command('show <request>', 'Inspect retained capture bytes or an unresolved intent without rerunning a program', async ({ args, options: o }, c) => { const request = text(args.request, 128), value = await receiptFor(c, workspace(c), request); if (!('kind' in value))
+        return value; if (o.output)
+        return { request, complete: value.complete, output: await exportReceipt(c, value, o.output) }; const view = text(o.view ?? 'overview', 16), limit = number(o.limit ?? 50, 1000, 1), offset = number(o.offset ?? 0, 8 * 1024 ** 2); if (view === 'overview')
+        return overview(value); if (view === 'stdout' || view === 'stderr')
+        return { request, state: value.state, complete: value.complete, view, ...pageStream(value[view], offset, limit) }; if (view === 'files')
+        return { request, state: value.state, complete: value.complete, items: value.files.slice(offset, offset + limit), total: value.files.length, offset, limit, truncated: offset + limit < value.files.length }; fail('invalid', 'Use overview, stdout, stderr or files.'); }, { permission: Permission.Update, options: [{ flags: '--view <kind>', description: 'overview, stdout, stderr or files', defaultValue: 'overview' }, { flags: '--limit <count>', description: '1–1000 output bytes or file rows', defaultValue: 50 }, { flags: '--offset <count>', description: 'Skip output bytes or file rows', defaultValue: 0 }, { flags: '--output <file>', description: 'Export portable retained capture to a new ordinary JSON file' }] });
+    const compare = command('compare <left> <right>', 'Compare two retained capture reports without re-executing their subjects', async ({ args, options: o }, c) => {
+        async function load(path) { const file = resolve(c.cwd, text(path, 4096)), bytes = await boundedFile(file, 8 * 1024 ** 2); let value; try {
+            value = JSON.parse(bytes.toString('utf8'));
+        }
+        catch {
+            fail('invalid', 'Capture report must be bounded JSON.');
+        } validateReport(value); return { value, sha256: sha(bytes) }; }
+        const left = await load(args.left), right = await load(args.right), a = left.value, b = right.value, changes = [], unknown = [];
+        for (const field of ['stdout', 'stderr']) {
+            if (!a[field] || !b[field])
+                unknown.push(field);
+            else if (a[field].sha256 !== b[field].sha256)
+                changes.push({ field, left: a[field].sha256, right: b[field].sha256 });
+        }
+        if (a.execution.exitCode !== b.execution.exitCode || a.execution.signal !== b.execution.signal)
+            changes.push({ field: 'exit', left: a.execution, right: b.execution });
+        const af = new Map(a.files.map(f => [f.path, f])), bf = new Map(b.files.map(f => [f.path, f]));
+        for (const name of [...new Set([...af.keys(), ...bf.keys()])].sort()) {
+            const l = af.get(name)?.after, r = bf.get(name)?.after;
+            if (!l || !r || l.state === 'unavailable' || r.state === 'unavailable')
+                unknown.push('file:' + name);
+            else if (l.state !== r.state || l.sha256 !== r.sha256)
+                changes.push({ field: 'file:' + name, left: l, right: r });
+        }
+        const limit = number(o.limit ?? 50, 500, 1), offset = number(o.offset ?? 0, 1000000), complete = a.complete && b.complete && !unknown.length;
+        return { state: complete ? 'completed' : 'partial', complete, left: { reportSha256: left.sha256, inputSha256: a.inputSha256 }, right: { reportSha256: right.sha256, inputSha256: b.inputSha256 }, sameDeclaredIntent: JSON.stringify({ target: a.inputSha256, argv: a.arguments, inputs: a.inputs, stdin: a.stdin, watch: a.files.map(f => f.path), timeoutMs: a.timeoutMs }) === JSON.stringify({ target: b.inputSha256, argv: b.arguments, inputs: b.inputs, stdin: b.stdin, watch: b.files.map(f => f.path), timeoutMs: b.timeoutMs }), items: changes.slice(offset, offset + limit), total: changes.length, unknown, offset, limit, truncated: offset + limit < changes.length, scope: 'Literal retained field/byte comparison; no subject rerun, causal equivalence or execution-time speedup claim. Partial reports cannot prove global equality.' };
+    }, { permission: Permission.ReadOnly, options: [{ flags: '--limit <count>', description: 'Return 1–500 changed fields', defaultValue: 50 }, { flags: '--offset <count>', description: 'Skip changed fields', defaultValue: 0 }] });
+    return [command('capture', 'Own bounded native executions and compare explicitly retained observations', [run, show, compare])];
+}