@gobing-ai/ts-runtime 0.4.9 → 0.4.10

package/README.md

@@ -15,6 +15,7 @@ and Cloudflare Workers through a factory pattern that auto-detects the runtime.
 | Runtime factory | `RuntimeFactory` → `loadRuntimeFactory()` | `nodeBunFactory` | `cloudflareWorkersFactory` |
 | File system | `FileSystem` | `createNodeFileSystem()` (sync `node:fs`) | `createCfFileSystem()` (stub) |
 | 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 |
@@ -96,6 +97,23 @@ classDiagram
         +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?
@@ -138,6 +156,8 @@ classDiagram
     FileSystem <|.. createCfFileSystem : implements
     ProcessExecutor --> PipeProcess : creates
     ProcessExecutor <|.. NodeProcessExecutor : implements
+    ProcessRegistry <|.. InMemoryProcessRegistry : implements
+    NodeProcessExecutor ..> ProcessRegistry : optional registry
     nodeBunFactory --> createNodeFileSystem : creates
     nodeBunFactory --> NodeProcessExecutor : creates
     cloudflareWorkersFactory --> createCfFileSystem : creates
@@ -536,9 +556,11 @@ const config = buildConfigFromObject({
 `ProcessExecutor` is the canonical interface for process execution. `NodeProcessExecutor` is the concrete implementation wrapping `execa` (buffered) and `Bun.spawn` (streaming):
 
 ```ts
-import { NodeProcessExecutor } from '@gobing-ai/ts-runtime';
+import { NodeProcessExecutor, createInMemoryProcessRegistry } from '@gobing-ai/ts-runtime';
 
-const exec = new NodeProcessExecutor({ 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({
@@ -546,21 +568,38 @@ 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.

package/dist/index.d.ts

@@ -10,6 +10,8 @@ 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 { 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';

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,mBAAmB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1E,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"}
+{"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

@@ -8,6 +8,7 @@ export { atomicWriteFile, atomicWriteJson, createLogStream, ensureDirForFile, re
 export * from './path.js';
 export { _resetRuntimeFactory, isCloudflareWorkerRuntime, loadRuntimeFactory } from './platform.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';

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>;
@@ -134,6 +156,8 @@ export declare class NodeProcessExecutor implements ProcessExecutor {
      */
     runStreaming(options: PipeProcessOptions): PipeProcess;
     private trace;
+    private beginRegistry;
+    private completeRegistry;
     private emitExitedFromResult;
     private emitProcessEvent;
 }

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

@@ -34,17 +34,26 @@ export class NodeProcessExecutor {
             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,
@@ -54,6 +63,7 @@ export class NodeProcessExecutor {
                 ...(result.signalDescription !== undefined ? { signal: result.signalDescription } : {}),
                 durationMs: result.durationMs,
             };
+            this.completeRegistry(registryId, processResult.exitCode);
             this.emitExitedFromResult(options, processResult, result);
             return processResult;
         }
@@ -72,6 +82,7 @@ export class NodeProcessExecutor {
                         : {}),
                 durationMs: failed.durationMs ?? Date.now() - startedAt,
             };
+            this.completeRegistry(registryId, processResult.exitCode);
             this.emitExitedFromResult(options, processResult, error, error);
             if (options.rejectOnError)
                 throw error;
@@ -87,15 +98,24 @@ export class NodeProcessExecutor {
     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({
@@ -106,14 +126,21 @@ export class NodeProcessExecutor {
                 ...(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,
@@ -132,6 +159,28 @@ export class NodeProcessExecutor {
             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'
@@ -163,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,

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-runtime",
-    "version": "0.4.9",
+    "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.9",
+        "@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.9",
+        "@gobing-ai/ts-db": "^0.4.10",
         "@types/bun": "1.3.14"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.4.9"
+        "@gobing-ai/ts-db": "^0.4.10"
     },
     "peerDependenciesMeta": {
         "@gobing-ai/ts-db": {

package/src/index.ts

@@ -31,6 +31,18 @@ export type {
     TracerPort,
 } 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';

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. */
@@ -164,18 +186,27 @@ export class NodeProcessExecutor implements 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,
@@ -185,6 +216,7 @@ export class NodeProcessExecutor implements ProcessExecutor {
                 ...(result.signalDescription !== undefined ? { signal: result.signalDescription } : {}),
                 durationMs: result.durationMs,
             };
+            this.completeRegistry(registryId, processResult.exitCode);
             this.emitExitedFromResult(options, processResult, result);
             return processResult;
         } catch (error) {
@@ -211,6 +243,7 @@ export class NodeProcessExecutor implements 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;
@@ -226,15 +259,24 @@ export class NodeProcessExecutor implements 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({
@@ -245,13 +287,20 @@ export class NodeProcessExecutor implements 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,
@@ -271,6 +320,38 @@ export class NodeProcessExecutor implements 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,
@@ -315,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,

package/src/process-registry.ts

@@ -0,0 +1,263 @@
+/**
+ * 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;
+}
+
+let nextIdSeq = 0;
+
+function allocateId(): string {
+    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 implements ProcessRegistry {
+    private readonly maxEntries: number;
+    private readonly byId = new Map<string, ProcessExecution>();
+    /** Insertion order for retention / list ordering. */
+    private readonly order: string[] = [];
+    private readonly listeners = new Set<(event: ProcessRegistryEvent) => void>();
+
+    constructor(options: InMemoryProcessRegistryOptions = {}) {
+        this.maxEntries = options.maxEntries ?? 1000;
+    }
+
+    listExecutions(filter?: ProcessExecutionFilter): readonly ProcessExecution[] {
+        const out: ProcessExecution[] = [];
+        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: string): ProcessExecution | undefined {
+        return this.byId.get(id);
+    }
+
+    subscribe(listener: (event: ProcessRegistryEvent) => void): () => void {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+
+    begin(input: ProcessExecutionBegin): string {
+        const id = allocateId();
+        const execution: ProcessExecution = {
+            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: string, patch: Pick<Partial<ProcessExecution>, 'pid' | 'label'>): void {
+        const current = this.byId.get(id);
+        if (!current) return;
+        const next: ProcessExecution = {
+            ...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: string, update: ProcessExecutionComplete = {}): void {
+        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: ProcessExecution = { ...current, pid: update.pid };
+                this.byId.set(id, patched);
+                this.emit({ type: 'updated', execution: patched });
+            }
+            return;
+        }
+        const next: ProcessExecution = {
+            ...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(): void {
+        this.byId.clear();
+        this.order.length = 0;
+    }
+
+    private emit(event: ProcessRegistryEvent): void {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            } catch {
+                // Listener errors must not break process tracking.
+            }
+        }
+    }
+
+    private enforceCap(): void {
+        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?: InMemoryProcessRegistryOptions): ProcessRegistry {
+    return new InMemoryProcessRegistry(options);
+}