@gobing-ai/ts-runtime 0.4.8 → 0.4.10

package/dist/process-registry.d.ts

@@ -0,0 +1,143 @@
+/**
+ * In-process registry of ProcessExecutor invocations (spur#0264 / M1).
+ *
+ * Tracks every `run` / `runStreaming` so board UIs (and other observers) can
+ * list all harness-launched processes — not only supervisor-owned agent loops.
+ * In-memory only; not durable across process restarts.
+ */
+/** Who initiated the spawn — used for filtering/grouping in consumers. */
+export type ProcessExecutionSource = 'supervisor' | 'one-shot' | 'other';
+/** Lifecycle status of a tracked execution. */
+export type ProcessExecutionStatus = 'running' | 'exited';
+/**
+ * One ProcessExecutor invocation — the minimum metadata Spur's Processes tab
+ * (and similar consumers) need for a full watch list.
+ */
+export interface ProcessExecution {
+    /** Unique id for this execution (stable for the process lifetime). */
+    readonly id: string;
+    /** Optional human label (e.g. `agent:alpha-claude`). */
+    readonly label?: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    /** OS pid when known (may arrive after spawn for buffered runs). */
+    readonly pid?: number;
+    /** ISO-8601 start time. */
+    readonly startedAt: string;
+    /** ISO-8601 end time when exited. */
+    readonly exitedAt?: string;
+    /** Exit code when exited (`null` for signal/timeout/error without code). */
+    readonly exitCode?: number | null;
+    readonly source: ProcessExecutionSource;
+    /** Optional team association for board grouping. */
+    readonly teamId?: string;
+    /** Optional agent id when the spawn is agent-scoped. */
+    readonly agentId?: string;
+    readonly status: ProcessExecutionStatus;
+}
+/** Filter for {@link ProcessRegistry.listExecutions}. */
+export interface ProcessExecutionFilter {
+    readonly source?: ProcessExecutionSource;
+    /** When true, only running; when false, only exited; omit for all. */
+    readonly running?: boolean;
+    readonly teamId?: string;
+    readonly agentId?: string;
+}
+/** Events emitted by {@link ProcessRegistry.subscribe}. */
+export type ProcessRegistryEvent = {
+    readonly type: 'started';
+    readonly execution: ProcessExecution;
+} | {
+    readonly type: 'exited';
+    readonly execution: ProcessExecution;
+} | {
+    readonly type: 'updated';
+    readonly execution: ProcessExecution;
+};
+/** Input for {@link ProcessRegistry.begin}. */
+export interface ProcessExecutionBegin {
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly label?: string;
+    readonly source?: ProcessExecutionSource;
+    readonly teamId?: string;
+    readonly agentId?: string;
+    readonly pid?: number;
+    /** Override start timestamp (ISO-8601); defaults to now. */
+    readonly startedAt?: string;
+}
+/** Completion patch for {@link ProcessRegistry.complete}. */
+export interface ProcessExecutionComplete {
+    readonly exitCode?: number | null;
+    readonly pid?: number;
+    /** Override end timestamp (ISO-8601); defaults to now. */
+    readonly exitedAt?: string;
+}
+/**
+ * Queryable registry of process executions.
+ *
+ * Implementations are process-local. Share one instance across every
+ * {@link import('./process-executor').NodeProcessExecutor} that should appear
+ * in the same watch list.
+ */
+export interface ProcessRegistry {
+    /** Snapshot of tracked executions (newest-last), optionally filtered. */
+    listExecutions(filter?: ProcessExecutionFilter): readonly ProcessExecution[];
+    /** Lookup by id. */
+    getExecution(id: string): ProcessExecution | undefined;
+    /**
+     * Subscribe to start / exit / field-update events.
+     * @returns unsubscribe function
+     */
+    subscribe(listener: (event: ProcessRegistryEvent) => void): () => void;
+    /** Record a new execution as running; returns its id. */
+    begin(input: ProcessExecutionBegin): string;
+    /** Patch mutable fields while running (e.g. pid once available). */
+    update(id: string, patch: Pick<Partial<ProcessExecution>, 'pid' | 'label'>): void;
+    /** Mark an execution exited (idempotent if already exited). */
+    complete(id: string, update?: ProcessExecutionComplete): void;
+    /** Drop all tracked executions (tests / shutdown). */
+    clear(): void;
+}
+/**
+ * Configuration for {@link createInMemoryProcessRegistry}.
+ */
+export interface InMemoryProcessRegistryOptions {
+    /**
+     * Maximum retained executions. When exceeded, oldest **exited** entries
+     * are dropped first; if still over limit, oldest entries overall.
+     * Default: 1000.
+     */
+    readonly maxEntries?: number;
+}
+/**
+ * Default in-memory {@link ProcessRegistry}.
+ *
+ * Create one per process (or per spur-serve) and inject it into every
+ * `NodeProcessExecutor` that should contribute to the shared watch list:
+ *
+ * ```ts
+ * const registry = createInMemoryProcessRegistry();
+ * const exec = new NodeProcessExecutor({ registry });
+ * ```
+ */
+export declare class InMemoryProcessRegistry implements ProcessRegistry {
+    private readonly maxEntries;
+    private readonly byId;
+    /** Insertion order for retention / list ordering. */
+    private readonly order;
+    private readonly listeners;
+    constructor(options?: InMemoryProcessRegistryOptions);
+    listExecutions(filter?: ProcessExecutionFilter): readonly ProcessExecution[];
+    getExecution(id: string): ProcessExecution | undefined;
+    subscribe(listener: (event: ProcessRegistryEvent) => void): () => void;
+    begin(input: ProcessExecutionBegin): string;
+    update(id: string, patch: Pick<Partial<ProcessExecution>, 'pid' | 'label'>): void;
+    complete(id: string, update?: ProcessExecutionComplete): void;
+    clear(): void;
+    private emit;
+    private enforceCap;
+}
+/** Factory for a default in-memory registry (preferred public constructor). */
+export declare function createInMemoryProcessRegistry(options?: InMemoryProcessRegistryOptions): ProcessRegistry;
+//# sourceMappingURL=process-registry.d.ts.map

package/dist/process-registry.d.ts.map

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

package/dist/process-registry.js

@@ -0,0 +1,146 @@
+/**
+ * In-process registry of ProcessExecutor invocations (spur#0264 / M1).
+ *
+ * Tracks every `run` / `runStreaming` so board UIs (and other observers) can
+ * list all harness-launched processes — not only supervisor-owned agent loops.
+ * In-memory only; not durable across process restarts.
+ */
+let nextIdSeq = 0;
+function allocateId() {
+    nextIdSeq += 1;
+    return `pe_${Date.now().toString(36)}_${nextIdSeq.toString(36)}`;
+}
+/**
+ * Default in-memory {@link ProcessRegistry}.
+ *
+ * Create one per process (or per spur-serve) and inject it into every
+ * `NodeProcessExecutor` that should contribute to the shared watch list:
+ *
+ * ```ts
+ * const registry = createInMemoryProcessRegistry();
+ * const exec = new NodeProcessExecutor({ registry });
+ * ```
+ */
+export class InMemoryProcessRegistry {
+    maxEntries;
+    byId = new Map();
+    /** Insertion order for retention / list ordering. */
+    order = [];
+    listeners = new Set();
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 1000;
+    }
+    listExecutions(filter) {
+        const out = [];
+        for (const id of this.order) {
+            const exec = this.byId.get(id);
+            if (!exec)
+                continue;
+            if (filter?.source !== undefined && exec.source !== filter.source)
+                continue;
+            if (filter?.running === true && exec.status !== 'running')
+                continue;
+            if (filter?.running === false && exec.status !== 'exited')
+                continue;
+            if (filter?.teamId !== undefined && exec.teamId !== filter.teamId)
+                continue;
+            if (filter?.agentId !== undefined && exec.agentId !== filter.agentId)
+                continue;
+            out.push(exec);
+        }
+        return out;
+    }
+    getExecution(id) {
+        return this.byId.get(id);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    begin(input) {
+        const id = allocateId();
+        const execution = {
+            id,
+            command: input.command,
+            args: Object.freeze([...(input.args ?? [])]),
+            source: input.source ?? 'other',
+            startedAt: input.startedAt ?? new Date().toISOString(),
+            status: 'running',
+            ...(input.label !== undefined ? { label: input.label } : {}),
+            ...(input.teamId !== undefined ? { teamId: input.teamId } : {}),
+            ...(input.agentId !== undefined ? { agentId: input.agentId } : {}),
+            ...(input.pid !== undefined ? { pid: input.pid } : {}),
+        };
+        this.byId.set(id, execution);
+        this.order.push(id);
+        this.enforceCap();
+        this.emit({ type: 'started', execution });
+        return id;
+    }
+    update(id, patch) {
+        const current = this.byId.get(id);
+        if (!current)
+            return;
+        const next = {
+            ...current,
+            ...(patch.pid !== undefined ? { pid: patch.pid } : {}),
+            ...(patch.label !== undefined ? { label: patch.label } : {}),
+        };
+        this.byId.set(id, next);
+        this.emit({ type: 'updated', execution: next });
+    }
+    complete(id, update = {}) {
+        const current = this.byId.get(id);
+        if (!current)
+            return;
+        if (current.status === 'exited') {
+            // Already completed — still allow pid fill-in if missing.
+            if (update.pid !== undefined && current.pid === undefined) {
+                const patched = { ...current, pid: update.pid };
+                this.byId.set(id, patched);
+                this.emit({ type: 'updated', execution: patched });
+            }
+            return;
+        }
+        const next = {
+            ...current,
+            status: 'exited',
+            exitedAt: update.exitedAt ?? new Date().toISOString(),
+            exitCode: update.exitCode !== undefined ? update.exitCode : null,
+            ...(update.pid !== undefined ? { pid: update.pid } : {}),
+        };
+        this.byId.set(id, next);
+        this.emit({ type: 'exited', execution: next });
+    }
+    clear() {
+        this.byId.clear();
+        this.order.length = 0;
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listener errors must not break process tracking.
+            }
+        }
+    }
+    enforceCap() {
+        while (this.order.length > this.maxEntries) {
+            // Prefer dropping oldest exited entries.
+            let dropIdx = this.order.findIndex((id) => this.byId.get(id)?.status === 'exited');
+            if (dropIdx < 0)
+                dropIdx = 0;
+            const [removed] = this.order.splice(dropIdx, 1);
+            if (removed !== undefined)
+                this.byId.delete(removed);
+        }
+    }
+}
+/** Factory for a default in-memory registry (preferred public constructor). */
+export function createInMemoryProcessRegistry(options) {
+    return new InMemoryProcessRegistry(options);
+}

package/dist/runtime-node-bun.js

@@ -2,7 +2,7 @@ import { parse as parseYaml } from 'yaml';
 import { buildConfigFromObject, getProcessEnv } from './config.js';
 import { DbModuleNotInstalledError } from './db-errors.js';
 import { createNodeFileSystem } from './file-system-node.js';
-import { ProcessExecutor } from './process-executor.js';
+import { NodeProcessExecutor } from './process-executor.js';
 // Lazy re-initialisable singleton for test isolation.
 let _nodeFileSystem;
 function getNodeFileSystem() {
@@ -26,7 +26,7 @@ export const nodeBunFactory = {
         hasSqlDatabase: true,
     },
     createFileSystem: () => getNodeFileSystem(),
-    createProcessExecutor: (config) => new ProcessExecutor(config),
+    createProcessExecutor: (config) => new NodeProcessExecutor(config),
     async loadConfig(options) {
         return loadNodeConfig(options);
     },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-runtime",
-    "version": "0.4.8",
+    "version": "0.4.10",
     "description": "@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.",
     "keywords": [
         "typescript",
@@ -58,17 +58,17 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-runtime-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-utils": "^0.4.8",
+        "@gobing-ai/ts-utils": "^0.4.10",
         "execa": "^9.5.0",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.4.8",
+        "@gobing-ai/ts-db": "^0.4.10",
         "@types/bun": "1.3.14"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.4.8"
+        "@gobing-ai/ts-db": "^0.4.10"
     },
     "peerDependenciesMeta": {
         "@gobing-ai/ts-db": {

package/src/context.ts

@@ -4,7 +4,7 @@ import type { FileSystem } from './file-system';
 import { createNodeFileSystem } from './file-system-node';
 import { loadRuntimeFactory } from './platform';
 import type { ProcessExecutor as ProcessExecutorService } from './process-executor';
-import { ProcessExecutor } from './process-executor';
+import { nodeBunFactory } from './runtime-node-bun';
 import type { RuntimeCapabilities, RuntimeName } from './types';
 /** Execution scope of a runtime context — determines service lifecycle and availability. */
 export type RuntimeScope = 'process' | 'server-request' | 'scheduled-event' | 'test';
@@ -50,7 +50,7 @@ export class RuntimeContext<TServices extends RuntimeServiceMap = RuntimeService
             (options.services?.fileSystem ?? createNodeFileSystem()) as TServices['fileSystem'],
         );
         if (this.capabilities.hasProcessExecution && options.services?.processExecutor === undefined) {
-            this.register('processExecutor', new ProcessExecutor() as TServices['processExecutor']);
+            this.register('processExecutor', nodeBunFactory.createProcessExecutor() as TServices['processExecutor']);
         }
 
         for (const [key, value] of Object.entries(options.services ?? {})) {

package/src/index.ts

@@ -30,7 +30,19 @@ export type {
     ProcessSignal,
     TracerPort,
 } from './process-executor';
-export { ProcessExecutor } from './process-executor';
+export { NodeProcessExecutor, ProcessExecutor } from './process-executor';
+export type {
+    InMemoryProcessRegistryOptions,
+    ProcessExecution,
+    ProcessExecutionBegin,
+    ProcessExecutionComplete,
+    ProcessExecutionFilter,
+    ProcessExecutionSource,
+    ProcessExecutionStatus,
+    ProcessRegistry,
+    ProcessRegistryEvent,
+} from './process-registry';
+export { createInMemoryProcessRegistry, InMemoryProcessRegistry } from './process-registry';
 export { cloudflareWorkersFactory } from './runtime-cf';
 export type { RuntimeFactory } from './runtime-factory';
 export { _resetNodeFileSystem, nodeBunFactory } from './runtime-node-bun';
@@ -39,7 +51,7 @@ export * from './types';
 
 // ── Deprecated re-exports (backward compatibility) ──────────────────────
 
-export { BunPipeProcessSpawner, BunSyncProcessExecutor, NodeProcessExecutor } from './process-executor';
+export { BunPipeProcessSpawner, BunSyncProcessExecutor } from './process-executor';
 
 /**
  * @deprecated Use {@link ProcessExecutor} directly for async execution.

package/src/process-executor.ts

@@ -1,5 +1,6 @@
 import { isatty } from 'node:tty';
 import { type Options as ExecaOptions, execa } from 'execa';
+import type { ProcessExecutionSource, ProcessRegistry } from './process-registry';
 
 // ── Types ────────────────────────────────────────────────────────────────
 
@@ -13,6 +14,12 @@ export interface ProcessExecutorConfig {
     output?: OutputPolicy;
     events?: ProcessEventSink;
     tracer?: TracerPort;
+    /**
+     * Optional process registry (spur#0264). When set, every `run` / `runStreaming`
+     * invocation is recorded for list/subscribe consumers (e.g. Spur Processes tab).
+     * Share one registry across all executors that should appear in the same watch list.
+     */
+    registry?: ProcessRegistry;
 }
 
 /** Options for spawning a child process. */
@@ -28,6 +35,14 @@ export interface ProcessOptions {
     forceBuffered?: boolean;
     /** AbortSignal forwarded to execa as `cancelSignal` — aborts the child process when fired. */
     signal?: AbortSignal;
+    /**
+     * Registry metadata (spur#0264). Defaults: source `'one-shot'` for `run`.
+     * Pass `source: 'supervisor'` (and optional teamId/agentId) when the spawn is
+     * a supervised team agent loop.
+     */
+    source?: ProcessExecutionSource;
+    teamId?: string;
+    agentId?: string;
 }
 
 /** Result of a completed child process, including exit code, captured output, and duration. */
@@ -80,6 +95,13 @@ export interface PipeProcessOptions {
     cwd?: string;
     env?: Record<string, string>;
     label?: string;
+    /**
+     * Registry metadata (spur#0264). Defaults: source `'other'` for streaming.
+     * Supervised agent loops should pass `source: 'supervisor'` + agentId.
+     */
+    source?: ProcessExecutionSource;
+    teamId?: string;
+    agentId?: string;
 }
 
 /** Signal values accepted by subprocess kill. */
@@ -99,15 +121,44 @@ export interface PipeProcess {
     kill(signal?: ProcessSignal): void;
 }
 
-// ── ProcessExecutor ───────────────────────────────────────────────────────
+// ── ProcessExecutor (canonical interface) ────────────────────────────────
 
 /**
- * Runtime-agnostic process executor wrapping `execa`.
+ * Runtime-agnostic process executor contract.
  *
  * Every invocation supports timeout enforcement, output capture, and
- * configurable output policy (buffered vs streamed).
+ * configurable output policy (buffered vs streamed). Concrete implementations
+ * are obtained through `RuntimeFactory.createProcessExecutor`; the Node/Bun
+ * implementation is {@link NodeProcessExecutor}. Test doubles implement this
+ * interface structurally — no concrete subclassing required.
+ */
+export interface ProcessExecutor {
+    /**
+     * Run a command, buffered by default. Returns a structured {@link ProcessResult}.
+     * Does NOT throw on non-zero exit codes unless `rejectOnError` is set.
+     */
+    run(options: ProcessOptions): Promise<ProcessResult>;
+
+    /**
+     * Spawn a long-running interactive process with streaming I/O.
+     *
+     * Returns a {@link PipeProcess} handle with streaming stdout/stderr and
+     * stdin write support.
+     */
+    runStreaming(options: PipeProcessOptions): PipeProcess;
+}
+
+// ── NodeProcessExecutor (concrete Node/Bun implementation) ───────────────
+
+/**
+ * Concrete Node/Bun implementation of {@link ProcessExecutor}, wrapping `execa`
+ * for buffered execution and `Bun.spawn` for streaming pipe execution.
+ *
+ * Obtain a default instance through `RuntimeFactory.createProcessExecutor`
+ * (e.g. `nodeBunFactory.createProcessExecutor()`); construct directly only in
+ * runtime-factory wiring or concrete implementation tests.
  */
-export class ProcessExecutor {
+export class NodeProcessExecutor implements ProcessExecutor {
     private readonly config: ProcessExecutorConfig;
 
     constructor(config: ProcessExecutorConfig = {}) {
@@ -135,18 +186,27 @@ export class ProcessExecutor {
             signal: options.signal,
         });
         const startedAt = Date.now();
+        const startedIso = new Date(startedAt).toISOString();
+        const registryId = this.beginRegistry(options.command, args, {
+            label: options.label,
+            source: options.source ?? 'one-shot',
+            teamId: options.teamId,
+            agentId: options.agentId,
+            startedAt: startedIso,
+        });
         this.emitProcessEvent('process.started', {
             command: options.command,
             args,
             exitCode: null,
             durationMs: 0,
             reason: 'exit',
-            timestamp: new Date(startedAt).toISOString(),
+            timestamp: startedIso,
             ...(options.label !== undefined ? { label: options.label } : {}),
         });
 
         try {
             const result = await execa(options.command, args, execaOptions);
+            // execa@9 Result does not expose pid — buffered runs leave pid unset.
             const processResult = {
                 command: options.command,
                 args,
@@ -156,6 +216,7 @@ export class ProcessExecutor {
                 ...(result.signalDescription !== undefined ? { signal: result.signalDescription } : {}),
                 durationMs: result.durationMs,
             };
+            this.completeRegistry(registryId, processResult.exitCode);
             this.emitExitedFromResult(options, processResult, result);
             return processResult;
         } catch (error) {
@@ -182,6 +243,7 @@ export class ProcessExecutor {
                       : {}),
                 durationMs: failed.durationMs ?? Date.now() - startedAt,
             };
+            this.completeRegistry(registryId, processResult.exitCode);
             this.emitExitedFromResult(options, processResult, error, error);
             if (options.rejectOnError) throw error;
             return processResult;
@@ -197,15 +259,24 @@ export class ProcessExecutor {
     runStreaming(options: PipeProcessOptions): PipeProcess {
         const args = options.args ?? [];
         void this.config.tracer?.traceAsync('process.runStreaming', async () => undefined).catch(() => undefined);
+        const startedAt = Date.now();
+        const startedIso = new Date(startedAt).toISOString();
+        // Begin registry before spawn so failed spawns still appear (then complete as error).
+        const registryId = this.beginRegistry(options.command, args, {
+            label: options.label,
+            source: options.source ?? 'other',
+            teamId: options.teamId,
+            agentId: options.agentId,
+            startedAt: startedIso,
+        });
         try {
-            const startedAt = Date.now();
             this.emitProcessEvent('process.started', {
                 command: options.command,
                 args,
                 exitCode: null,
                 durationMs: 0,
                 reason: 'exit',
-                timestamp: new Date(startedAt).toISOString(),
+                timestamp: startedIso,
                 ...(options.label !== undefined ? { label: options.label } : {}),
             });
             const subprocess = Bun.spawn({
@@ -216,13 +287,20 @@ export class ProcessExecutor {
                 ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
                 ...(options.env !== undefined ? { env: options.env } : {}),
             });
-            return new ObservedPipeProcess(new BunPipeProcess(subprocess), this.config.events, {
+            const pipe = new BunPipeProcess(subprocess);
+            if (pipe.pid !== null) {
+                this.config.registry?.update(registryId, { pid: pipe.pid });
+            }
+            return new ObservedPipeProcess(pipe, this.config.events, {
                 command: options.command,
                 args,
                 startedAt,
+                registry: this.config.registry,
+                registryId,
                 ...(options.label !== undefined ? { label: options.label } : {}),
             });
         } catch (error) {
+            this.completeRegistry(registryId, null);
             this.emitProcessEvent('process.exited', {
                 command: options.command,
                 args,
@@ -242,6 +320,38 @@ export class ProcessExecutor {
         return await this.config.tracer.traceAsync(name, async () => await fn());
     }
 
+    private beginRegistry(
+        command: string,
+        args: string[],
+        meta: {
+            label?: string;
+            source: ProcessExecutionSource;
+            teamId?: string;
+            agentId?: string;
+            startedAt: string;
+        },
+    ): string {
+        const registry = this.config.registry;
+        if (!registry) return '';
+        return registry.begin({
+            command,
+            args,
+            source: meta.source,
+            startedAt: meta.startedAt,
+            ...(meta.label !== undefined ? { label: meta.label } : {}),
+            ...(meta.teamId !== undefined ? { teamId: meta.teamId } : {}),
+            ...(meta.agentId !== undefined ? { agentId: meta.agentId } : {}),
+        });
+    }
+
+    private completeRegistry(id: string, exitCode: number | null, pid?: number): void {
+        if (!id || !this.config.registry) return;
+        this.config.registry.complete(id, {
+            exitCode,
+            ...(pid !== undefined ? { pid } : {}),
+        });
+    }
+
     private emitExitedFromResult(
         options: ProcessOptions,
         result: ProcessResult,
@@ -286,9 +396,17 @@ class ObservedPipeProcess implements PipeProcess {
             args: string[];
             startedAt: number;
             label?: string;
+            registry?: ProcessRegistry;
+            registryId: string;
         },
     ) {
         this.exited = inner.exited.then((exitCode) => {
+            if (context.registry && context.registryId) {
+                context.registry.complete(context.registryId, {
+                    exitCode,
+                    ...(inner.pid !== null ? { pid: inner.pid } : {}),
+                });
+            }
             events?.emit('process.exited', {
                 command: context.command,
                 args: context.args,
@@ -374,13 +492,18 @@ class BunPipeProcess implements PipeProcess {
     }
 }
 
-// ── Deprecated backward-compatible subclasses ─────────────────────────────
+// ── Deprecated constructible ProcessExecutor value alias ──────────────────
 
 /**
- * @deprecated Use {@link ProcessExecutor} directly.
- * This subclass is kept for backward compatibility.
+ * @deprecated Construct {@link NodeProcessExecutor} directly or obtain a default
+ * through `RuntimeFactory.createProcessExecutor` (e.g. `nodeBunFactory.createProcessExecutor()`).
+ * This value alias preserves source compatibility for `new ProcessExecutor(...)` callers
+ * during the interface extraction release; it will be removed in a future release.
+ * `import type { ProcessExecutor }` resolves to the canonical interface, not this alias.
  */
-export class NodeProcessExecutor extends ProcessExecutor {}
+export const ProcessExecutor = NodeProcessExecutor;
+
+// ── Deprecated backward-compatible helpers ────────────────────────────────
 
 /**
  * @deprecated Use `Bun.spawnSync` or `child_process.spawnSync` directly.