@gobing-ai/ts-runtime 0.4.8 → 0.4.10

package/README.md

@@ -8,15 +8,14 @@ and Cloudflare Workers through a factory pattern that auto-detects the runtime.
 
 ## Overview
 
-
-
 **Key abstractions:**
 
 | Concept | Interface | Bun/Node impl | Cloudflare impl |
-|---------|-----------|---------------|-----------------|
+| --------- | ----------- | --------------- | ----------------- |
 | Runtime factory | `RuntimeFactory` → `loadRuntimeFactory()` | `nodeBunFactory` | `cloudflareWorkersFactory` |
 | File system | `FileSystem` | `createNodeFileSystem()` (sync `node:fs`) | `createCfFileSystem()` (stub) |
-| Process execution | `ProcessExecutor` (class) | `run()` via execa, `runStreaming()` via `Bun.spawn` | throws |
+| Process execution | `ProcessExecutor` (interface) | `NodeProcessExecutor` — `run()` via execa, `runStreaming()` via `Bun.spawn` | throws |
+| Process registry | `ProcessRegistry` (optional) | `InMemoryProcessRegistry` / `createInMemoryProcessRegistry()` — list + subscribe all spawns | n/a (no process exec) |
 | SQL database | `createDbAdapter(config)` → `DbAdapter` | Bun SQLite via `@gobing-ai/ts-db` (optional peer) | throws `D1NotConfiguredError` (D1 round pending) |
 | Configuration | `Config` (Zod schema) | YAML + env vars | CONFIG_YAML blob + env vars |
 | Context | `RuntimeContext` | service locator | service locator |
@@ -88,10 +87,33 @@ classDiagram
     }
 
     class ProcessExecutor {
+        <<interface>>
         +run(options) Promise~ProcessResult~
         +runStreaming(options) PipeProcess
     }
 
+    class NodeProcessExecutor {
+        +run(options) Promise~ProcessResult~
+        +runStreaming(options) PipeProcess
+    }
+
+    class ProcessRegistry {
+        <<interface>>
+        +listExecutions(filter?) ProcessExecution[]
+        +getExecution(id) ProcessExecution?
+        +subscribe(listener) unsub
+        +begin(input) string
+        +update(id, patch) void
+        +complete(id, update?) void
+        +clear() void
+    }
+
+    class InMemoryProcessRegistry {
+        +listExecutions(filter?) ProcessExecution[]
+        +begin(input) string
+        +complete(id, update?) void
+    }
+
     class PipeProcess {
         <<interface>>
         +pid number?
@@ -133,8 +155,11 @@ classDiagram
     FileSystem <|.. createNodeFileSystem : implements
     FileSystem <|.. createCfFileSystem : implements
     ProcessExecutor --> PipeProcess : creates
+    ProcessExecutor <|.. NodeProcessExecutor : implements
+    ProcessRegistry <|.. InMemoryProcessRegistry : implements
+    NodeProcessExecutor ..> ProcessRegistry : optional registry
     nodeBunFactory --> createNodeFileSystem : creates
-    nodeBunFactory --> ProcessExecutor : creates
+    nodeBunFactory --> NodeProcessExecutor : creates
     cloudflareWorkersFactory --> createCfFileSystem : creates
     RuntimeContext --> FileSystem : "fileSystem"
     RuntimeContext --> Config : "config"
@@ -232,7 +257,7 @@ There are three ways a config file can name its schema. **Prefer the bundled pac
 the most secure and performant default:
 
 | Style | Example | Resolution | Notes |
-|-------|---------|------------|-------|
+| ------- | --------- | ------------ | ------- |
 | **Package specifier** (recommended) | `$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"` | Resolved through `node_modules` via the module resolver, then read from disk | No network, no path guessing; survives hoisting/pnpm/monorepo layouts. Schemas ship in each package's `schemas/` (declared in `files`). **Quote the value** — YAML treats a leading `@` as reserved. |
 | Relative path | `$schema: ./schemas/rule-file.schema.json` | Resolved against the config file's directory | Fine for repo-local schemas; brittle if the config moves. |
 | Remote URL | `$schema: https://json-schema.org/.../rule-file.schema.json` | Fetched over HTTP(S) — **off by default** | SSRF/DoS surface for third-party configs. Opt in with `{ allowRemote: true }` (5s timeout) or supply your own `fetch`. |
@@ -251,7 +276,6 @@ await loadStructuredConfig('rules.yaml', { fetch: myFetch });           // or in
 > `node_modules` keeps validation entirely local — no outbound request, no dependency on a schema host's
 > availability, and no chance for a malicious config to point validation at an internal URL.
 
-
 ### 5. Path utilities
 
 Runtime-portable path math that avoids `node:path` so the same logic works on Cloudflare Workers
@@ -284,6 +308,7 @@ The `./extension` subpath exposes a generic, domain-agnostic extension/capabilit
 with origin metadata, a trust-gated extension loader, and a path guard — without knowing anything
 about evaluators, resolvers, actions, or guards. Each engine owns its domain-specific kinds,
 schemas, error types, and override semantics.
+
 #### Capability registry
 
 ```ts
@@ -462,6 +487,7 @@ process.on('SIGTERM', async () => {
     await ctx.dispose();
     process.exit(0);
 });
+
 ```
 
 ## Usage
@@ -513,6 +539,7 @@ const config = buildConfigFromObject({
     database: { url: ':memory:' },
 });
 ```
+
 // From YAML file
 const config = buildConfigFromYaml(yamlText);
 
@@ -521,16 +548,19 @@ const config = buildConfigFromObject({
     app: { name: 'api', env: 'production', port: 3000 },
     database: { url: ':memory:' },
 });
+
 ```
 
 ### Process execution
 
-`ProcessExecutor` is a single class wrapping `execa` (buffered) and `Bun.spawn` (streaming):
+`ProcessExecutor` is the canonical interface for process execution. `NodeProcessExecutor` is the concrete implementation wrapping `execa` (buffered) and `Bun.spawn` (streaming):
 
 ```ts
-import { ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { NodeProcessExecutor, createInMemoryProcessRegistry } from '@gobing-ai/ts-runtime';
 
-const exec = new ProcessExecutor({ defaultTimeout: 30_000 });
+// Optional: shared registry so every run/runStreaming is listable (spur#0264 / M1).
+const registry = createInMemoryProcessRegistry();
+const exec = new NodeProcessExecutor({ defaultTimeout: 30_000, registry });
 
 // Buffered — captures stdout/stderr, no throw on non-zero
 const result = await exec.run({
@@ -538,27 +568,45 @@ const result = await exec.run({
     args: ['status', '--short'],
     cwd: '/path/to/repo',
     rejectOnError: true,
+    // Optional registry metadata (defaults: run → source 'one-shot')
+    label: 'git.status',
 });
 
 console.log(result.stdout);          // 'M src/index.ts\n'
 console.log(`Duration: ${result.durationMs}ms`);
 
 // Streaming — interactive subprocess with stdin control
-const proc = exec.runStreaming({ command: 'cat' });
+const proc = exec.runStreaming({
+    command: 'cat',
+    source: 'supervisor', // tag supervised agent loops
+    agentId: 'alpha-claude',
+});
 proc.writeStdin('hello\n');
 proc.endStdin();
 const exitCode = await proc.exited; // 0
+
+// Watch list snapshot + live subscription
+console.log(registry.listExecutions());
+const unsub = registry.subscribe((event) => {
+    if (event.type === 'started' || event.type === 'exited') {
+        console.log(event.type, event.execution.id, event.execution.command);
+    }
+});
+unsub();
 ```
 
 `rejectOnError: true` throws on non-zero exits. `OutputPolicy` controls
 buffered vs streamed output. `ProcessOptions` supports timeout, env, cwd,
-maxOutput, and forceBuffered.
+maxOutput, forceBuffered, and optional registry fields (`source`, `teamId`,
+`agentId`). Inject the same `ProcessRegistry` into every executor that should
+appear in one watch list; without a registry, behavior is unchanged.
 
 Cloudflare Workers do not expose process execution; check
 `factory.capabilities.hasProcessExecution` first.
 
-Old classes (`NodeProcessExecutor`, `BunSyncProcessExecutor`, `BunPipeProcessSpawner`)
-are kept as deprecated backward-compatible wrappers.
+The `ProcessExecutor` const (value alias for `NodeProcessExecutor`), `BunSyncProcessExecutor`,
+and `BunPipeProcessSpawner` are kept as deprecated backward-compatible wrappers. Prefer
+`NodeProcessExecutor` or `nodeBunFactory.createProcessExecutor()` in new code.
 
 ### SpanContext (for telemetry)
 

package/dist/context.js

@@ -1,7 +1,7 @@
 import { buildConfigFromObject } from './config.js';
 import { createNodeFileSystem } from './file-system-node.js';
 import { loadRuntimeFactory } from './platform.js';
-import { ProcessExecutor } from './process-executor.js';
+import { nodeBunFactory } from './runtime-node-bun.js';
 /** Injectable service container scoped to a runtime environment (process, request, event, or test). */
 export class RuntimeContext {
     scope;
@@ -22,7 +22,7 @@ export class RuntimeContext {
         this.register('config', (options.services?.config ?? buildConfigFromObject({})));
         this.register('fileSystem', (options.services?.fileSystem ?? createNodeFileSystem()));
         if (this.capabilities.hasProcessExecution && options.services?.processExecutor === undefined) {
-            this.register('processExecutor', new ProcessExecutor());
+            this.register('processExecutor', nodeBunFactory.createProcessExecutor());
         }
         for (const [key, value] of Object.entries(options.services ?? {})) {
             if (value !== undefined) {

package/dist/index.d.ts

@@ -9,13 +9,15 @@ export { atomicWriteFile, atomicWriteJson, createLogStream, ensureDirForFile, re
 export * from './path';
 export { _resetRuntimeFactory, isCloudflareWorkerRuntime, loadRuntimeFactory } from './platform';
 export type { OutputPolicy, PipeProcess, PipeProcessOptions, ProcessEventDetail, ProcessEventSink, ProcessEvents, ProcessExecutorConfig, ProcessExitReason, ProcessOptions, ProcessResult, 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';
 export * from './schema-validation';
 export * from './types';
-export { BunPipeProcessSpawner, BunSyncProcessExecutor, NodeProcessExecutor } from './process-executor';
+export { BunPipeProcessSpawner, BunSyncProcessExecutor } from './process-executor';
 /**
  * @deprecated Use {@link ProcessExecutor} directly for async execution.
  * Use `Bun.spawnSync` or `child_process.spawnSync` for sync.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC9E,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACH,eAAe,EACf,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,OAAO,EACP,aAAa,GAChB,MAAM,MAAM,CAAC;AACd,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjG,YAAY,EACR,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,UAAU,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1E,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AAIxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAExG;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;AAE3G;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC9E,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACH,eAAe,EACf,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,OAAO,EACP,aAAa,GAChB,MAAM,MAAM,CAAC;AACd,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjG,YAAY,EACR,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,UAAU,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1E,YAAY,EACR,8BAA8B,EAC9B,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,oBAAoB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC5F,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1E,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AAIxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEnF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;AAE3G;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,qBAAqB,CAAC,CAAC"}

package/dist/index.js

@@ -7,10 +7,11 @@ export { createNodeFileSystem, findProjectRoot } from './file-system-node.js';
 export { atomicWriteFile, atomicWriteJson, createLogStream, ensureDirForFile, readJsonFile, walkDir, writeJsonFile, } from './fs.js';
 export * from './path.js';
 export { _resetRuntimeFactory, isCloudflareWorkerRuntime, loadRuntimeFactory } from './platform.js';
-export { ProcessExecutor } from './process-executor.js';
+export { NodeProcessExecutor, ProcessExecutor } from './process-executor.js';
+export { createInMemoryProcessRegistry, InMemoryProcessRegistry } from './process-registry.js';
 export { cloudflareWorkersFactory } from './runtime-cf.js';
 export { _resetNodeFileSystem, nodeBunFactory } from './runtime-node-bun.js';
 export * from './schema-validation.js';
 export * from './types.js';
 // ── Deprecated re-exports (backward compatibility) ──────────────────────
-export { BunPipeProcessSpawner, BunSyncProcessExecutor, NodeProcessExecutor } from './process-executor.js';
+export { BunPipeProcessSpawner, BunSyncProcessExecutor } from './process-executor.js';

package/dist/process-executor.d.ts

@@ -1,3 +1,4 @@
+import type { ProcessExecutionSource, ProcessRegistry } from './process-registry';
 /** Controls how stdout/stderr is captured: buffered in memory or streamed to the caller's terminal. */
 export type OutputPolicy = {
     mode: 'buffered';
@@ -12,6 +13,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. */
 export interface ProcessOptions {
@@ -26,6 +33,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. */
 export interface ProcessResult {
@@ -71,6 +86,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. */
 type BunSubprocess = ReturnType<typeof Bun.spawn>;
@@ -87,12 +109,37 @@ export interface PipeProcess {
     kill(signal?: ProcessSignal): void;
 }
 /**
- * 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 declare class ProcessExecutor {
+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;
+}
+/**
+ * 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 declare class NodeProcessExecutor implements ProcessExecutor {
     private readonly config;
     constructor(config?: ProcessExecutorConfig);
     /**
@@ -109,15 +156,19 @@ export declare class ProcessExecutor {
      */
     runStreaming(options: PipeProcessOptions): PipeProcess;
     private trace;
+    private beginRegistry;
+    private completeRegistry;
     private emitExitedFromResult;
     private emitProcessEvent;
 }
 /**
- * @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 declare class NodeProcessExecutor extends ProcessExecutor {
-}
+export declare const ProcessExecutor: typeof NodeProcessExecutor;
 /**
  * @deprecated Use `Bun.spawnSync` or `child_process.spawnSync` directly.
  * Synchronous process execution is no longer recommended from ts-runtime.

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

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

package/dist/process-executor.js

@@ -1,13 +1,15 @@
 import { isatty } from 'node:tty';
 import { execa } from 'execa';
-// ── ProcessExecutor ───────────────────────────────────────────────────────
+// ── NodeProcessExecutor (concrete Node/Bun implementation) ───────────────
 /**
- * Runtime-agnostic process executor wrapping `execa`.
+ * Concrete Node/Bun implementation of {@link ProcessExecutor}, wrapping `execa`
+ * for buffered execution and `Bun.spawn` for streaming pipe execution.
  *
- * Every invocation supports timeout enforcement, output capture, and
- * configurable output policy (buffered vs streamed).
+ * 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 {
     config;
     constructor(config = {}) {
         this.config = config;
@@ -32,17 +34,26 @@ 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,
@@ -52,6 +63,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;
         }
@@ -70,6 +82,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;
@@ -85,15 +98,24 @@ export class ProcessExecutor {
     runStreaming(options) {
         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({
@@ -104,14 +126,21 @@ 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,
@@ -130,6 +159,28 @@ export class ProcessExecutor {
             return await fn();
         return await this.config.tracer.traceAsync(name, async () => await fn());
     }
+    beginRegistry(command, args, meta) {
+        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 } : {}),
+        });
+    }
+    completeRegistry(id, exitCode, pid) {
+        if (!id || !this.config.registry)
+            return;
+        this.config.registry.complete(id, {
+            exitCode,
+            ...(pid !== undefined ? { pid } : {}),
+        });
+    }
     emitExitedFromResult(options, result, completion, error) {
         const reason = isTimedOut(completion)
             ? 'timeout'
@@ -161,6 +212,12 @@ class ObservedPipeProcess {
     constructor(inner, events, context) {
         this.inner = inner;
         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,
@@ -224,13 +281,16 @@ class BunPipeProcess {
         this.subprocess.kill(signal);
     }
 }
-// ── 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.
  * Synchronous process execution is no longer recommended from ts-runtime.