@opensip-cli/core 0.1.0

package/dist/runtime/__tests__/subprocess-transport.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess-transport.test.d.ts","sourceRoot":"","sources":["../../../src/runtime/__tests__/subprocess-transport.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/runtime/__tests__/subprocess-transport.test.js

@@ -0,0 +1,118 @@
+/**
+ * Subprocess ProgressTransport (ADR-0028): forks the fixture worker over real
+ * IPC and asserts the relay contract — event fan-out, pre-subscribe buffering,
+ * result resolution, error propagation (message / throw / premature exit),
+ * advanced-serialization payloads, and the in-process fallback selector.
+ *
+ * These spawn a real child process, so the suite is slower than the in-process
+ * sibling; the fixture is a tiny `.mjs` run directly by node (no transform).
+ */
+import { fileURLToPath } from 'node:url';
+import { describe, it, expect, afterEach } from 'vitest';
+import { createSubprocessProgressRun, runOffThreadOrInProcess } from '../subprocess-transport.js';
+const FIXTURE = fileURLToPath(new URL('fixtures/progress-worker.mjs', import.meta.url));
+function descriptorFor(mode) {
+    return { command: FIXTURE, argv: [mode] };
+}
+describe('createSubprocessProgressRun', () => {
+    it('relays progress events in order and resolves the result', async () => {
+        const run = createSubprocessProgressRun(descriptorFor('emit-and-result'));
+        const events = [];
+        run.onProgress((e) => events.push(e));
+        const result = await run.result;
+        expect(result).toBe('done');
+        expect(events).toEqual([1, 2, 3]);
+    });
+    it('buffers events emitted before subscription and flushes them in order', async () => {
+        // Subscribe only AFTER the result settles: every progress message has been
+        // received and buffered (not dropped), then flushed on onProgress — parity
+        // with the in-process transport's pre-subscribe buffering.
+        const run = createSubprocessProgressRun(descriptorFor('emit-and-result'));
+        await run.result;
+        const events = [];
+        run.onProgress((e) => events.push(e));
+        expect(events).toEqual([1, 2, 3]);
+    });
+    it('rejects the result with the reconstructed message on an error message', async () => {
+        const run = createSubprocessProgressRun(descriptorFor('error-message'));
+        await expect(run.result).rejects.toThrow('worker blew up');
+    });
+    it('rejects when the worker throws and exits non-zero without a result', async () => {
+        const run = createSubprocessProgressRun(descriptorFor('throw'));
+        await expect(run.result).rejects.toThrow(/worker exited/);
+    });
+    it('rejects when the worker exits cleanly without producing a result', async () => {
+        const run = createSubprocessProgressRun(descriptorFor('exit-clean'));
+        await expect(run.result).rejects.toThrow(/before producing a result/);
+    });
+    it('carries a Map across the boundary via advanced serialization', async () => {
+        const run = createSubprocessProgressRun(descriptorFor('map-result'));
+        const result = await run.result;
+        expect(result.tag).toBe('m');
+        expect(result.map).toBeInstanceOf(Map);
+        expect(result.map.get('a')).toBe(1);
+    });
+});
+describe('runOffThreadOrInProcess', () => {
+    afterEach(() => {
+        delete process.env.OPENSIP_CLI_NO_WORKER;
+    });
+    it('runs the worker by default and resolves its result', async () => {
+        const events = [];
+        const run = runOffThreadOrInProcess({
+            descriptor: descriptorFor('emit-and-result'),
+            inProcess: () => Promise.reject(new Error('must not run in-process')),
+        });
+        run.onProgress((e) => events.push(e));
+        expect(await run.result).toBe('done');
+        expect(events).toEqual([1, 2, 3]);
+    });
+    it('runs the in-process closure when preferWorker is false', async () => {
+        const events = [];
+        const run = runOffThreadOrInProcess({
+            descriptor: descriptorFor('throw'), // would reject if forked — proves it is not
+            preferWorker: false,
+            inProcess: (emit) => {
+                emit(10);
+                emit(20);
+                return Promise.resolve('in-process');
+            },
+        });
+        run.onProgress((e) => events.push(e));
+        expect(await run.result).toBe('in-process');
+        expect(events).toEqual([10, 20]);
+    });
+    it('runs the in-process closure when OPENSIP_CLI_NO_WORKER=1', async () => {
+        process.env.OPENSIP_CLI_NO_WORKER = '1';
+        const run = runOffThreadOrInProcess({
+            descriptor: descriptorFor('throw'),
+            inProcess: () => Promise.resolve('env-gated in-process'),
+        });
+        expect(await run.result).toBe('env-gated in-process');
+    });
+    it('yields an identical result whether it ran off-thread or in-process', async () => {
+        // The renderer must not care which path ran. The worker emits the same
+        // [1,2,3]/'done' the in-process closure mirrors here.
+        const worker = runOffThreadOrInProcess({
+            descriptor: descriptorFor('emit-and-result'),
+            inProcess: () => Promise.reject(new Error('unused')),
+        });
+        process.env.OPENSIP_CLI_NO_WORKER = '1';
+        const fallback = runOffThreadOrInProcess({
+            descriptor: descriptorFor('emit-and-result'),
+            inProcess: (emit) => {
+                emit(1);
+                emit(2);
+                emit(3);
+                return Promise.resolve('done');
+            },
+        });
+        const workerEvents = [];
+        const fallbackEvents = [];
+        worker.onProgress((e) => workerEvents.push(e));
+        fallback.onProgress((e) => fallbackEvents.push(e));
+        expect(await worker.result).toBe(await fallback.result);
+        expect(workerEvents).toEqual(fallbackEvents);
+    });
+});
+//# sourceMappingURL=subprocess-transport.test.js.map

package/dist/runtime/__tests__/subprocess-transport.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess-transport.test.js","sourceRoot":"","sources":["../../../src/runtime/__tests__/subprocess-transport.test.ts"],"names":[],"mappings":"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"}

package/dist/runtime/in-process-transport.d.ts

@@ -0,0 +1,20 @@
+/**
+ * In-process ProgressTransport (ADR-0016) — runs the job in the current process
+ * and fans its events out to subscribers. The common case: tools whose execution
+ * already yields to the event loop (fit's async file I/O, sim's awaited
+ * scenarios), so the render thread stays free to animate.
+ *
+ * Pre-subscribe events are buffered and flushed when the first listener attaches.
+ * Ink mounts the renderer's `useEffect` subscription synchronously after
+ * `render(...)`, but the job's first `emit` can still land first — buffering
+ * guarantees no early event is dropped.
+ */
+import type { ProgressTransport } from './progress-transport.js';
+/**
+ * Create an in-process {@link ProgressTransport} that runs each job eagerly in
+ * the current process and fans its events out to a single subscriber. Events
+ * emitted before the first `onProgress` listener attaches are buffered and
+ * flushed in order on subscription, so no early event is dropped.
+ */
+export declare function createInProcessTransport(): ProgressTransport;
+//# sourceMappingURL=in-process-transport.d.ts.map

package/dist/runtime/in-process-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-process-transport.d.ts","sourceRoot":"","sources":["../../src/runtime/in-process-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAA4B,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE3F;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,iBAAiB,CA+B5D"}

package/dist/runtime/in-process-transport.js

@@ -0,0 +1,49 @@
+/**
+ * In-process ProgressTransport (ADR-0016) — runs the job in the current process
+ * and fans its events out to subscribers. The common case: tools whose execution
+ * already yields to the event loop (fit's async file I/O, sim's awaited
+ * scenarios), so the render thread stays free to animate.
+ *
+ * Pre-subscribe events are buffered and flushed when the first listener attaches.
+ * Ink mounts the renderer's `useEffect` subscription synchronously after
+ * `render(...)`, but the job's first `emit` can still land first — buffering
+ * guarantees no early event is dropped.
+ */
+/**
+ * Create an in-process {@link ProgressTransport} that runs each job eagerly in
+ * the current process and fans its events out to a single subscriber. Events
+ * emitted before the first `onProgress` listener attaches are buffered and
+ * flushed in order on subscription, so no early event is dropped.
+ */
+export function createInProcessTransport() {
+    return {
+        run(job) {
+            let listener;
+            const buffer = [];
+            const emit = (event) => {
+                if (listener) {
+                    listener(event);
+                }
+                else {
+                    buffer.push(event);
+                }
+            };
+            // Start the job eagerly; events emitted before `onProgress` is called are
+            // buffered above.
+            const result = job(emit);
+            return {
+                onProgress(next) {
+                    listener = next;
+                    // Flush anything emitted before subscription, in order.
+                    while (buffer.length > 0) {
+                        const event = buffer.shift();
+                        if (event !== undefined)
+                            next(event);
+                    }
+                },
+                result,
+            };
+        },
+    };
+}
+//# sourceMappingURL=in-process-transport.js.map

package/dist/runtime/in-process-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-process-transport.js","sourceRoot":"","sources":["../../src/runtime/in-process-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO;QACL,GAAG,CAAkB,GAAiC;YACpD,IAAI,QAA+C,CAAC;YACpD,MAAM,MAAM,GAAa,EAAE,CAAC;YAE5B,MAAM,IAAI,GAAG,CAAC,KAAa,EAAQ,EAAE;gBACnC,IAAI,QAAQ,EAAE,CAAC;oBACb,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAClB,CAAC;qBAAM,CAAC;oBACN,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC,CAAC;YAEF,0EAA0E;YAC1E,kBAAkB;YAClB,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;YAEzB,OAAO;gBACL,UAAU,CAAC,IAA6B;oBACtC,QAAQ,GAAG,IAAI,CAAC;oBAChB,wDAAwD;oBACxD,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACzB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;wBAC7B,IAAI,KAAK,KAAK,SAAS;4BAAE,IAAI,CAAC,KAAK,CAAC,CAAC;oBACvC,CAAC;gBACH,CAAC;gBACD,MAAM;aACP,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/runtime/progress-transport.d.ts

@@ -0,0 +1,73 @@
+/**
+ * ProgressTransport — the seam that decouples *where a tool's work runs* from
+ * *how its progress reaches the renderer* (ADR-0016).
+ *
+ * Two implementations:
+ *   - in-process (this directory) — a plain in-memory fan-out, for tools whose
+ *     execution already yields to the event loop (fit, sim).
+ *   - subprocess (added with the graph subprocess work) — forks a child and
+ *     relays IPC messages, for tools whose work is a synchronous CPU blast that
+ *     would otherwise starve the render thread (graph).
+ *
+ * The interface is generic over the event and result types so core — the kernel,
+ * which imports nothing from the workspace — never names cli-ui's concrete
+ * `ProgressEvent`. Callers bind `TEvent` to `ProgressEvent` at the tool layer.
+ */
+/** A live run in progress: subscribe for events, await the final result. */
+export interface ProgressRun<TEvent, TResult> {
+    /**
+     * Register a listener for streamed events. Events emitted before the first
+     * listener attaches are buffered and flushed on subscription, so a fast job
+     * cannot race the renderer's mount and drop early events.
+     */
+    readonly onProgress: (listener: (event: TEvent) => void) => void;
+    /** Resolves with the tool's final result; rejects if the run fails. */
+    readonly result: Promise<TResult>;
+}
+/**
+ * In-process job: a closure that emits events as it runs and resolves a result.
+ * The subprocess transport accepts a serializable descriptor instead (it cannot
+ * ship a closure across the process boundary); both satisfy
+ * {@link ProgressTransport} via distinct `run` overloads at their call sites.
+ */
+export type ProgressJob<TEvent, TResult> = (emit: (event: TEvent) => void) => Promise<TResult>;
+/** Runs a job and streams its progress to subscribers. */
+export interface ProgressTransport {
+    run<TEvent, TResult>(job: ProgressJob<TEvent, TResult>): ProgressRun<TEvent, TResult>;
+}
+/**
+ * A description of off-main-PROCESS work (ADR-0028). The off-thread variant runs
+ * the engine in a forked child that re-bootstraps the full CLI scope (language +
+ * tool registries, project, config) — a worker *thread* can't, because that
+ * bootstrap is CLI-owned and a partial registry would diverge a polyglot run's
+ * results. So the descriptor names the node module to fork (the CLI entry) + argv
+ * (a worker subcommand + a temp spec path). No closure and no live handle (e.g.
+ * the datastore) crosses the boundary; persistence + egress stay on the main
+ * process after the run returns.
+ */
+export interface SubprocessJobDescriptor {
+    /** Node module to fork — the CLI entry (`process.argv[1]`). */
+    readonly command: string;
+    /** Argv for the fork — typically `[<worker-subcommand>, <specPath>]`. */
+    readonly argv: readonly string[];
+    /** Extra environment for the child (merged over the parent's). */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/**
+ * The child→parent IPC message protocol. The forked worker posts these via
+ * `process.send`; the subprocess {@link ProgressRun} maps `progress` to
+ * subscribers, resolves on `result`, and rejects on `error`. One source of truth
+ * for both ends.
+ */
+export type WorkerMessage<TEvent, TResult> = {
+    readonly kind: 'progress';
+    readonly event: TEvent;
+} | {
+    readonly kind: 'result';
+    readonly value: TResult;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+    readonly stack?: string;
+};
+//# sourceMappingURL=progress-transport.d.ts.map

package/dist/runtime/progress-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-transport.d.ts","sourceRoot":"","sources":["../../src/runtime/progress-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,WAAW,CAAC,MAAM,EAAE,OAAO;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,KAAK,IAAI,CAAC;IACjE,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE/F,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,EAAE,OAAO,IACrC;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/runtime/progress-transport.js

@@ -0,0 +1,17 @@
+/**
+ * ProgressTransport — the seam that decouples *where a tool's work runs* from
+ * *how its progress reaches the renderer* (ADR-0016).
+ *
+ * Two implementations:
+ *   - in-process (this directory) — a plain in-memory fan-out, for tools whose
+ *     execution already yields to the event loop (fit, sim).
+ *   - subprocess (added with the graph subprocess work) — forks a child and
+ *     relays IPC messages, for tools whose work is a synchronous CPU blast that
+ *     would otherwise starve the render thread (graph).
+ *
+ * The interface is generic over the event and result types so core — the kernel,
+ * which imports nothing from the workspace — never names cli-ui's concrete
+ * `ProgressEvent`. Callers bind `TEvent` to `ProgressEvent` at the tool layer.
+ */
+export {};
+//# sourceMappingURL=progress-transport.js.map

package/dist/runtime/progress-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-transport.js","sourceRoot":"","sources":["../../src/runtime/progress-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/runtime/subprocess-transport.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Subprocess ProgressTransport (ADR-0028) — runs a tool's engine in a forked
+ * child process and relays its progress back to the main-process renderer, so
+ * the Ink reconciler + the 80ms live-progress clock never block on a synchronous
+ * CPU blast (AST walks, rule passes, the TS type-checker). This is the
+ * off-process variant `progress-transport.ts` always described.
+ *
+ * Why a child PROCESS, not a worker thread: the engine reads `currentScope()`
+ * (the language + tool registries, project, config), which only the CLI bootstrap
+ * populates — and a worker thread in an engine package can't re-run that bootstrap
+ * (layering) without a partial registry that would diverge a polyglot run's
+ * results. A forked CLI subcommand re-bootstraps the whole scope for free (the
+ * pattern graph's shard workers already use). The boundary is IPC JSON only.
+ *
+ * Generic over `TEvent`/`TResult`: core never names cli-ui's `ProgressEvent`.
+ */
+import type { ProgressJob, ProgressRun, SubprocessJobDescriptor } from './progress-transport.js';
+/**
+ * Fork `descriptor.command` (the CLI entry) with `descriptor.argv` (a worker
+ * subcommand + spec path) and adapt its {@link WorkerMessage} IPC stream to a
+ * {@link ProgressRun}. The child's stdout is suppressed (it must not corrupt the
+ * parent's Ink frames); stderr is inherited (logs/diagnostics) and the `ipc`
+ * channel carries progress/result/error. Buffers events emitted before the
+ * renderer subscribes (parity with the in-process transport), and settles
+ * `result` exactly once — on a `result`/`error` message, a child `error`, or a
+ * premature `exit`. The child is killed on settle so the short-lived CLI exits.
+ */
+export declare function createSubprocessProgressRun<TEvent, TResult>(descriptor: SubprocessJobDescriptor): ProgressRun<TEvent, TResult>;
+/**
+ * Run work off the main process when possible, else in-process — with an
+ * identical {@link ProgressRun} either way, so the renderer doesn't care which
+ * ran. The caller supplies BOTH a {@link SubprocessJobDescriptor} (the forked
+ * worker) and the equivalent in-process {@link ProgressJob} (the same work as a
+ * local closure). Subprocess is preferred unless `preferWorker: false` or
+ * `OPENSIP_CLI_NO_WORKER=1`, and a synchronous fork failure degrades to
+ * in-process.
+ */
+export declare function runOffThreadOrInProcess<TEvent, TResult>(opts: {
+    readonly descriptor: SubprocessJobDescriptor;
+    readonly inProcess: ProgressJob<TEvent, TResult>;
+    readonly preferWorker?: boolean;
+}): ProgressRun<TEvent, TResult>;
+//# sourceMappingURL=subprocess-transport.d.ts.map

package/dist/runtime/subprocess-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess-transport.d.ts","sourceRoot":"","sources":["../../src/runtime/subprocess-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,uBAAuB,EAExB,MAAM,yBAAyB,CAAC;AAmBjC;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,EACzD,UAAU,EAAE,uBAAuB,GAClC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAwD9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE;IAC7D,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAmB/B"}

package/dist/runtime/subprocess-transport.js

@@ -0,0 +1,134 @@
+/**
+ * Subprocess ProgressTransport (ADR-0028) — runs a tool's engine in a forked
+ * child process and relays its progress back to the main-process renderer, so
+ * the Ink reconciler + the 80ms live-progress clock never block on a synchronous
+ * CPU blast (AST walks, rule passes, the TS type-checker). This is the
+ * off-process variant `progress-transport.ts` always described.
+ *
+ * Why a child PROCESS, not a worker thread: the engine reads `currentScope()`
+ * (the language + tool registries, project, config), which only the CLI bootstrap
+ * populates — and a worker thread in an engine package can't re-run that bootstrap
+ * (layering) without a partial registry that would diverge a polyglot run's
+ * results. A forked CLI subcommand re-bootstraps the whole scope for free (the
+ * pattern graph's shard workers already use). The boundary is IPC JSON only.
+ *
+ * Generic over `TEvent`/`TResult`: core never names cli-ui's `ProgressEvent`.
+ */
+import { fork } from 'node:child_process';
+import { EnvRegistry } from '../lib/env-registry.js';
+import { logger } from '../lib/logger.js';
+import { createInProcessTransport } from './in-process-transport.js';
+/** Governed escape hatch (env-via-registry): force in-process execution. */
+const WORKER_ENV = new EnvRegistry([
+    {
+        canonical: 'OPENSIP_CLI_NO_WORKER',
+        coerce: (raw) => raw === '1',
+        default: false,
+        docs: 'Set to 1 to run a tool engine in the main process instead of a forked worker (debugging / constrained runtimes). The live view may stutter; output is unchanged.',
+    },
+]);
+/** Reconstruct an Error from a worker's `error` message (preserving stack). */
+function workerError(message, stack) {
+    const err = new Error(message);
+    if (stack !== undefined)
+        err.stack = stack;
+    return err;
+}
+/**
+ * Fork `descriptor.command` (the CLI entry) with `descriptor.argv` (a worker
+ * subcommand + spec path) and adapt its {@link WorkerMessage} IPC stream to a
+ * {@link ProgressRun}. The child's stdout is suppressed (it must not corrupt the
+ * parent's Ink frames); stderr is inherited (logs/diagnostics) and the `ipc`
+ * channel carries progress/result/error. Buffers events emitted before the
+ * renderer subscribes (parity with the in-process transport), and settles
+ * `result` exactly once — on a `result`/`error` message, a child `error`, or a
+ * premature `exit`. The child is killed on settle so the short-lived CLI exits.
+ */
+export function createSubprocessProgressRun(descriptor) {
+    let listener;
+    const buffer = [];
+    const emit = (event) => {
+        if (listener)
+            listener(event);
+        else
+            buffer.push(event);
+    };
+    let settle;
+    const result = new Promise((resolve, reject) => {
+        settle = { resolve, reject };
+    });
+    const child = fork(descriptor.command, [...descriptor.argv], {
+        // stdout ignored (no child render bytes in the parent's live view); stderr
+        // inherited (logs surface); ipc channel for the WorkerMessage protocol.
+        stdio: ['ignore', 'ignore', 'inherit', 'ipc'],
+        // Structured-clone IPC instead of the default JSON serializer: progress
+        // events and tool results stay safe even if a payload grows a Map/Set/Date
+        // (the JSON serializer would silently drop or mangle those). Workers send
+        // slim, plain-data results today; this keeps the transport robust regardless.
+        serialization: 'advanced',
+        // @fitness-ignore-next-line env-secret-exposure -- fork() REPLACES the child env wholesale when `env` is set, so the parent env must be spread in to preserve it; this object is passed to fork, never logged.
+        ...(descriptor.env === undefined ? {} : { env: { ...process.env, ...descriptor.env } }),
+    });
+    let settled = false;
+    const done = (apply) => {
+        if (settled)
+            return;
+        settled = true;
+        apply();
+        child.kill();
+    };
+    child.on('message', (msg) => {
+        if (msg.kind === 'progress')
+            emit(msg.event);
+        else if (msg.kind === 'result')
+            done(() => settle.resolve(msg.value));
+        else
+            done(() => settle.reject(workerError(msg.message, msg.stack)));
+    });
+    child.on('error', (err) => done(() => settle.reject(err)));
+    child.on('exit', (code) => {
+        done(() => settle.reject(new Error(`worker exited (code ${code ?? 'null'}) before producing a result`)));
+    });
+    return {
+        onProgress(next) {
+            listener = next;
+            while (buffer.length > 0) {
+                const event = buffer.shift();
+                if (event !== undefined)
+                    next(event);
+            }
+        },
+        result,
+    };
+}
+/**
+ * Run work off the main process when possible, else in-process — with an
+ * identical {@link ProgressRun} either way, so the renderer doesn't care which
+ * ran. The caller supplies BOTH a {@link SubprocessJobDescriptor} (the forked
+ * worker) and the equivalent in-process {@link ProgressJob} (the same work as a
+ * local closure). Subprocess is preferred unless `preferWorker: false` or
+ * `OPENSIP_CLI_NO_WORKER=1`, and a synchronous fork failure degrades to
+ * in-process.
+ */
+export function runOffThreadOrInProcess(opts) {
+    const envDisablesWorker = WORKER_ENV.get('OPENSIP_CLI_NO_WORKER') === true;
+    const preferWorker = (opts.preferWorker ?? true) && !envDisablesWorker;
+    if (preferWorker) {
+        try {
+            return createSubprocessProgressRun(opts.descriptor);
+        }
+        catch (error) {
+            // The child could not be forked — degrade to in-process so the run still
+            // completes (the live view may stutter; output is unchanged). Log the
+            // degradation so it is observable rather than a silent swallow.
+            logger.warn({
+                evt: 'transport.worker.fork_failed',
+                module: 'core:subprocess-transport',
+                command: opts.descriptor.command,
+                err: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return createInProcessTransport().run(opts.inProcess);
+}
+//# sourceMappingURL=subprocess-transport.js.map

package/dist/runtime/subprocess-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess-transport.js","sourceRoot":"","sources":["../../src/runtime/subprocess-transport.ts"],"names":[],"mappings":"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"}

package/dist/signals/comment-openers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Shared comment-opener table for inline-directive scanning.
+ *
+ * The kernel home (ADR-0014) of the comment-opener prefixes the inline
+ * suppression scanner recognizes. Fitness's directive parsers re-export this
+ * table so there is a single source of truth across the platform — the two
+ * lists historically drifted (the suppression parser recognized `//`, `/*`,
+ * `<!--`, and `#` while the inventory only recognized `//` and `/*`), causing
+ * HTML/hash-style directives to suppress findings yet vanish from the
+ * inventory. One table prevents that.
+ *
+ * Tuple shape: `[opener, length]`. The length is encoded once so scanners
+ * don't repeat it per opener — `<!--` is 4 chars; the others are 1 or 2.
+ */
+/**
+ * Comment-opener prefixes the directive scanner recognizes:
+ *
+ *   - `//`   — TypeScript / JavaScript / C-family
+ *   - `/* `  — same family, block form
+ *   - `<!--` — Markdown / HTML doc files (READMEs, arch docs)
+ *   - `#`    — shell / YAML / Python configs and scripts
+ */
+export declare const COMMENT_OPENERS: readonly (readonly [string, number])[];
+/**
+ * Strip a comment opener from the start of a (trimmed) line. Returns `null`
+ * when the line doesn't start with any known opener.
+ */
+export declare function stripCommentOpener(trimmedLine: string): string | null;
+//# sourceMappingURL=comment-openers.d.ts.map

package/dist/signals/comment-openers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-openers.d.ts","sourceRoot":"","sources":["../../src/signals/comment-openers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAKxD,CAAC;AAEX;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOrE"}

package/dist/signals/comment-openers.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Shared comment-opener table for inline-directive scanning.
+ *
+ * The kernel home (ADR-0014) of the comment-opener prefixes the inline
+ * suppression scanner recognizes. Fitness's directive parsers re-export this
+ * table so there is a single source of truth across the platform — the two
+ * lists historically drifted (the suppression parser recognized `//`, `/*`,
+ * `<!--`, and `#` while the inventory only recognized `//` and `/*`), causing
+ * HTML/hash-style directives to suppress findings yet vanish from the
+ * inventory. One table prevents that.
+ *
+ * Tuple shape: `[opener, length]`. The length is encoded once so scanners
+ * don't repeat it per opener — `<!--` is 4 chars; the others are 1 or 2.
+ */
+/**
+ * Comment-opener prefixes the directive scanner recognizes:
+ *
+ *   - `//`   — TypeScript / JavaScript / C-family
+ *   - `/* `  — same family, block form
+ *   - `<!--` — Markdown / HTML doc files (READMEs, arch docs)
+ *   - `#`    — shell / YAML / Python configs and scripts
+ */
+export const COMMENT_OPENERS = [
+    ['//', 2],
+    ['/*', 2],
+    ['<!--', 4],
+    ['#', 1],
+];
+/**
+ * Strip a comment opener from the start of a (trimmed) line. Returns `null`
+ * when the line doesn't start with any known opener.
+ */
+export function stripCommentOpener(trimmedLine) {
+    for (const [opener, length] of COMMENT_OPENERS) {
+        if (trimmedLine.startsWith(opener)) {
+            return trimmedLine.slice(length);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=comment-openers.js.map

package/dist/signals/comment-openers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-openers.js","sourceRoot":"","sources":["../../src/signals/comment-openers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAA2C;IACrE,CAAC,IAAI,EAAE,CAAC,CAAC;IACT,CAAC,IAAI,EAAE,CAAC,CAAC;IACT,CAAC,MAAM,EAAE,CAAC,CAAC;IACX,CAAC,GAAG,EAAE,CAAC,CAAC;CACA,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,eAAe,EAAE,CAAC;QAC/C,IAAI,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACnC,OAAO,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/signals/comment-openers.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * comment-openers — the shared comment-opener table (ADR-0014) and the
+ * `stripCommentOpener` helper that removes a recognized opener from the start
+ * of a trimmed line.
+ */
+export {};
+//# sourceMappingURL=comment-openers.test.d.ts.map

package/dist/signals/comment-openers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-openers.test.d.ts","sourceRoot":"","sources":["../../src/signals/comment-openers.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/signals/comment-openers.test.js

@@ -0,0 +1,41 @@
+/**
+ * comment-openers — the shared comment-opener table (ADR-0014) and the
+ * `stripCommentOpener` helper that removes a recognized opener from the start
+ * of a trimmed line.
+ */
+import { describe, it, expect } from 'vitest';
+import { COMMENT_OPENERS, stripCommentOpener } from './comment-openers.js';
+describe('COMMENT_OPENERS', () => {
+    it('encodes each opener with its correct character length', () => {
+        expect(COMMENT_OPENERS).toEqual([
+            ['//', 2],
+            ['/*', 2],
+            ['<!--', 4],
+            ['#', 1],
+        ]);
+        for (const [opener, length] of COMMENT_OPENERS) {
+            expect(opener.length).toBe(length);
+        }
+    });
+});
+describe('stripCommentOpener', () => {
+    it('strips a line-comment opener', () => {
+        expect(stripCommentOpener('// fitness-disable foo')).toBe(' fitness-disable foo');
+    });
+    it('strips a block-comment opener', () => {
+        expect(stripCommentOpener('/* fitness-disable foo */')).toBe(' fitness-disable foo */');
+    });
+    it('strips an HTML/markdown opener (4 chars)', () => {
+        expect(stripCommentOpener('<!-- fitness-disable foo -->')).toBe(' fitness-disable foo -->');
+    });
+    it('strips a hash opener (1 char)', () => {
+        expect(stripCommentOpener('# fitness-disable foo')).toBe(' fitness-disable foo');
+    });
+    it('returns null for a line that does not start with any known opener', () => {
+        expect(stripCommentOpener('const x = 1;')).toBeNull();
+    });
+    it('returns null for the empty string', () => {
+        expect(stripCommentOpener('')).toBeNull();
+    });
+});
+//# sourceMappingURL=comment-openers.test.js.map

package/dist/signals/comment-openers.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-openers.test.js","sourceRoot":"","sources":["../../src/signals/comment-openers.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE3E,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,MAAM,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC;YAC9B,CAAC,IAAI,EAAE,CAAC,CAAC;YACT,CAAC,IAAI,EAAE,CAAC,CAAC;YACT,CAAC,MAAM,EAAE,CAAC,CAAC;YACX,CAAC,GAAG,EAAE,CAAC,CAAC;SACT,CAAC,CAAC;QACH,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,eAAe,EAAE,CAAC;YAC/C,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,kBAAkB,CAAC,wBAAwB,CAAC,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACpF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,kBAAkB,CAAC,2BAA2B,CAAC,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC1F,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,kBAAkB,CAAC,8BAA8B,CAAC,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAC9F,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,kBAAkB,CAAC,uBAAuB,CAAC,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC3E,MAAM,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}