@parall/codex-agent 1.59.0 → 1.60.0

package/dist/app-server-protocol.d.ts

@@ -15,5 +15,18 @@ export type CodexTurnInput = {
 export declare function buildTurnInput(body: string, images: PreparedLocalImage[]): CodexTurnInput[];
 export declare function extractThreadId(result: unknown): string | undefined;
 export declare function extractTurnId(result: unknown): string | undefined;
+/**
+ * The `thread` object a `thread/started` notification carries. Subagent
+ * threads (`spawn_agent`) report `threadSource: "subAgent"` plus the parent
+ * thread and the agent's nickname/role; other fields are tolerated absent.
+ */
+export type CodexThreadInfo = {
+    id: string;
+    parentThreadId?: string;
+    source?: string;
+    nickname?: string;
+    role?: string;
+};
+export declare function extractThreadInfo(params: unknown): CodexThreadInfo | undefined;
 export declare function extractThreadIdFromNotification(params: unknown): string | undefined;
 //# sourceMappingURL=app-server-protocol.d.ts.map

package/dist/app-server-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-server-protocol.d.ts","sourceRoot":"","sources":["../src/app-server-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAEvF;;;;;GAKG;AAEH,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,cAAc,EAAE,CAK3F;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOnE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOjE;AAED,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASnF"}
+{"version":3,"file":"app-server-protocol.d.ts","sourceRoot":"","sources":["../src/app-server-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAEvF;;;;;GAKG;AAEH,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,cAAc,EAAE,CAK3F;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOnE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOjE;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAsB9E;AAED,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASnF"}

package/dist/app-server-protocol.js

@@ -26,6 +26,27 @@ export function extractTurnId(result) {
         return turn.id;
     return undefined;
 }
+export function extractThreadInfo(params) {
+    if (!params || typeof params !== 'object')
+        return undefined;
+    const p = params;
+    const thread = (p.thread && typeof p.thread === 'object' ? p.thread : p);
+    const id = typeof thread.id === 'string'
+        ? thread.id
+        : typeof p.threadId === 'string'
+            ? p.threadId
+            : undefined;
+    if (!id)
+        return undefined;
+    const str = (value) => (typeof value === 'string' && value.trim() ? value : undefined);
+    return {
+        id,
+        parentThreadId: str(thread.parentThreadId),
+        source: str(thread.threadSource) ?? str(thread.source),
+        nickname: str(thread.agentNickname),
+        role: str(thread.agentRole),
+    };
+}
 export function extractThreadIdFromNotification(params) {
     if (!params || typeof params !== 'object')
         return undefined;

package/dist/compact.d.ts

@@ -0,0 +1,33 @@
+import type { CompactOpts, CompactResult, GatewayLogger } from '@parall/agent-core';
+import type { OpenDispatchOutcome } from './dispatch.js';
+import { type MainThreadInstructionsRefresher, type NotificationTapSource } from './instructions-refresh.js';
+/**
+ * Idle auto-compact on the Codex bridge (idle-auto-compact-design.md §3.4):
+ * open the MAIN thread exactly the way a dispatch would (start/resume + the
+ * instructions reconcile), then run the unconditional compaction primitive
+ * as a tap-only turn — no TurnSink, no activeTurnIds entry, so it is neither
+ * a user turn nor a steer target (PFB-84 bookkeeping untouched). Outcomes
+ * follow the refresh path's posture: a stalled compaction quarantines the
+ * main lane and bounces the subprocess; -32601 latches unsupported for the
+ * subprocess lifetime.
+ *
+ * The host is the narrow slice of CodexAppServerAdapter this needs; the
+ * adapter's `compact()` is a thin delegate.
+ */
+export interface CodexCompactHost {
+    log?: GatewayLogger;
+    taps: NotificationTapSource;
+    refresher: Pick<MainThreadInstructionsRefresher, 'isCompactUnsupported' | 'runCompaction' | 'recordCompacted'>;
+    isMainSession(sessionKey: string): boolean;
+    isMainLaneQuarantined(): boolean;
+    /** Quarantine the main lane and request a subprocess restart (applied when free). */
+    quarantineAndBounce(log?: GatewayLogger): Promise<void>;
+    applyPendingRestart(log?: GatewayLogger): Promise<void>;
+    /** Open the main thread with restart gating (openingDispatches) held. */
+    openMainThread(sessionKey: string, log?: GatewayLogger): Promise<OpenDispatchOutcome>;
+    hasActiveTurn(threadId: string): boolean;
+    /** Run `fn` as tap-only work on the thread: restart-gated, no unrouted-notification warnings. */
+    withTapOnlyTurn<T>(threadId: string, fn: () => Promise<T>): Promise<T>;
+}
+export declare function runCodexCompact(host: CodexCompactHost, { sessionKey, signal, log }: CompactOpts): Promise<CompactResult>;
+//# sourceMappingURL=compact.d.ts.map

package/dist/compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../src/compact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAEL,KAAK,+BAA+B,EACpC,KAAK,qBAAqB,EAC3B,MAAM,2BAA2B,CAAC;AAGnC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,SAAS,EAAE,IAAI,CACb,+BAA+B,EAC/B,sBAAsB,GAAG,eAAe,GAAG,iBAAiB,CAC7D,CAAC;IACF,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C,qBAAqB,IAAI,OAAO,CAAC;IACjC,qFAAqF;IACrF,mBAAmB,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,mBAAmB,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,yEAAyE;IACzE,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtF,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC,iGAAiG;IACjG,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,gBAAgB,EACtB,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,WAAW,GACvC,OAAO,CAAC,aAAa,CAAC,CAkFxB"}

package/dist/compact.js

@@ -0,0 +1,92 @@
+import { CompactionStalledError, } from './instructions-refresh.js';
+import { JSON_RPC_METHOD_NOT_FOUND, JsonRpcError } from './jsonrpc-client.js';
+export async function runCodexCompact(host, { sessionKey, signal, log }) {
+    const logger = log ?? host.log;
+    if (!host.isMainSession(sessionKey)) {
+        return { status: 'unsupported', detail: 'compact is only supported on the main session' };
+    }
+    if (signal.aborted)
+        return { status: 'timeout' };
+    if (host.isMainLaneQuarantined()) {
+        await host.applyPendingRestart(logger);
+        if (host.isMainLaneQuarantined()) {
+            return {
+                status: 'failed',
+                detail: 'main lane quarantined after a stalled compaction; the subprocess restart is still deferred behind an active turn',
+            };
+        }
+    }
+    if (host.refresher.isCompactUnsupported()) {
+        return {
+            status: 'unsupported',
+            detail: 'thread/compact/start not supported by this codex CLI',
+        };
+    }
+    await host.applyPendingRestart(logger);
+    const opened = await host.openMainThread(sessionKey, logger);
+    if (!opened.ok)
+        return { status: 'failed', detail: opened.message };
+    if (opened.reconcile === 'stalled') {
+        // Same posture as dispatch(): the refresh compaction may still be
+        // running on the thread — never rotate it; quarantine and bounce.
+        await host.quarantineAndBounce(logger);
+        return {
+            status: 'timeout',
+            detail: 'instructions-refresh compaction stalled while opening the thread; subprocess bounced',
+        };
+    }
+    if (opened.reconcile === 'unsupported') {
+        return {
+            status: 'unsupported',
+            detail: 'thread/compact/start not supported by this codex CLI',
+        };
+    }
+    if (opened.reconcile === 'refreshed') {
+        // The open just ran a compaction of this very thread (instructions
+        // refresh) — the history is already folded; a second one is waste.
+        return { status: 'done', detail: 'compacted by the instructions refresh during open' };
+    }
+    if (signal.aborted) {
+        return { status: 'timeout', detail: 'budget elapsed while opening the thread' };
+    }
+    const { client, threadId } = opened;
+    if (host.hasActiveTurn(threadId)) {
+        return { status: 'failed', detail: 'a turn is active on the main thread' };
+    }
+    let stalled = false;
+    try {
+        return await host.withTapOnlyTurn(threadId, async () => {
+            try {
+                await host.refresher.runCompaction({ client, taps: host.taps, threadId, signal });
+                host.refresher.recordCompacted(sessionKey, threadId);
+                return { status: 'done' };
+            }
+            catch (err) {
+                if (err instanceof CompactionStalledError) {
+                    // Budget elapsed (the gateway's abort or the refresher's own
+                    // ceiling) and the turn ignored the interrupt: the compaction is
+                    // torn down with the subprocess below.
+                    stalled = true;
+                    return { status: 'timeout', detail: errToString(err) };
+                }
+                if (err instanceof JsonRpcError && err.code === JSON_RPC_METHOD_NOT_FOUND) {
+                    return { status: 'unsupported', detail: errToString(err) };
+                }
+                return { status: 'failed', detail: errToString(err) };
+            }
+        });
+    }
+    finally {
+        if (stalled) {
+            // The compaction turn may still be running: quarantine the main lane
+            // and bounce the subprocess (deferred behind an active fork turn,
+            // retried by the next main dispatch) — exactly the dispatch posture.
+            await host.quarantineAndBounce(logger);
+        }
+    }
+}
+function errToString(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}

package/dist/dispatch.d.ts

@@ -1,6 +1,7 @@
-import type { CleanupForkOpts, DispatchAdapter, DispatchInputLifecycle, DispatchOpts, ForkOpts, ForkSessionHandle, GatewayLogger, RuntimeEvent } from '@parall/agent-core';
+import type { CleanupForkOpts, CompactOpts, CompactResult, DispatchAdapter, DispatchInputLifecycle, DispatchOpts, ForkOpts, ForkSessionHandle, GatewayLogger, RuntimeActivityEvent, RuntimeBusyState, RuntimeEvent } from '@parall/agent-core';
 import type { CodexAgentConfig } from './config.js';
-import { type NotificationTap } from './instructions-refresh.js';
+import { type NotificationTap, type RefreshOutcome } from './instructions-refresh.js';
+import { JsonRpcStdioClient } from './jsonrpc-client.js';
 import type { CodexSessionManager } from './session-manager.js';
 type CodexAppServerAdapterOptions = Pick<CodexAgentConfig, 'approvalPolicy' | 'codexBin' | 'codexHome' | 'model' | 'reasoningEffort' | 'sandbox' | 'workspaceDir'> & {
     sessionManager: CodexSessionManager;
@@ -80,6 +81,9 @@ export declare class CodexAppServerAdapter implements DispatchAdapter {
     private readonly instructionsRefresher;
     private stopping;
     private lastUnroutedNotificationWarnAt;
+    /** Subagent threads and their runtime-initiated turns (foreign-threads.ts). */
+    private readonly foreignThreads;
+    private readonly activity;
     /**
      * Store an active turn sink keyed by threadId. If a sink already exists for
      * the same threadId, log a warning and fail the existing sink — this
@@ -107,9 +111,26 @@ export declare class CodexAppServerAdapter implements DispatchAdapter {
     private threadConfigOverrides;
     enqueueDuringDispatch(sessionKey: string, body: string, inputLifecycle?: DispatchInputLifecycle): Promise<boolean>;
     abortDispatch(sessionKey: string): void;
+    /** Idle auto-compact (compact.ts): the compaction primitive as a tap-only main-thread turn. */
+    compact(opts: CompactOpts): Promise<CompactResult>;
+    /**
+     * Real work on the subprocess that predates any TurnSink (thread open,
+     * a tap-only compaction turn): counted so applyPendingRestart cannot
+     * stop() the subprocess out from under it.
+     */
+    private withOpening;
     hasPendingInjections(sessionKey: string): boolean;
     hasUnsettledInjections(sessionKey: string): boolean;
     acknowledgeDiscardedInjection(sessionKey: string, deliveryKey: string): void;
+    subscribeRuntimeActivity(handler: (event: RuntimeActivityEvent) => void): () => void;
+    /**
+     * Busy = a dispatch turn, a dispatch opening its thread (possibly running
+     * the instructions-refresh compaction turn), or a subagent thread's turn
+     * is executing. Live subagent threads between turns are reported as
+     * background work, not busy.
+     */
+    isBusy(): boolean;
+    busyState(): RuntimeBusyState;
     dispatch({ event, bodyForAgent, sessionKey, context, inputLifecycle, noteActivity, }: DispatchOpts): AsyncIterable<RuntimeEvent>;
     /**
      * Bring the app-server up and open (start or resume) the thread for this
@@ -152,5 +173,14 @@ export declare class CodexAppServerAdapter implements DispatchAdapter {
     private openThread;
     private routeNotification;
 }
+export type OpenDispatchOutcome = {
+    ok: true;
+    client: JsonRpcStdioClient;
+    threadId: string;
+    reconcile?: RefreshOutcome;
+} | {
+    ok: false;
+    message: string;
+};
 export {};
 //# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

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

package/dist/dispatch.js

@@ -1,10 +1,13 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import * as path from 'node:path';
+import { isRuntimeBusy, projectRuntimeEvent, RuntimeActivityPort } from '@parall/agent-core';
 import { appendPreparedLocalAttachmentRefs, pinLocalAttachmentPaths, } from '@parall/agent-core/internal/attachment-input';
 import { ensureGitRepo, IS_WIN32, killWin32Tree, quoteWin32Arg } from './app-server-process.js';
 import { buildTurnInput, extractThreadId, extractThreadIdFromNotification, extractTurnId, } from './app-server-protocol.js';
 import { normalizeApprovalPolicy, normalizeSandbox } from './config.js';
+import { runCodexCompact } from './compact.js';
+import { ForeignThreadRegistry } from './foreign-threads.js';
 import { CodexInjectionRegistry } from './injection-registry.js';
 import { MainThreadInstructionsRefresher, } from './instructions-refresh.js';
 import { JsonRpcStdioClient } from './jsonrpc-client.js';
@@ -51,6 +54,9 @@ export class CodexAppServerAdapter {
     instructionsRefresher;
     stopping = false;
     lastUnroutedNotificationWarnAt = 0;
+    /** Subagent threads and their runtime-initiated turns (foreign-threads.ts). */
+    foreignThreads;
+    activity;
     /**
      * Store an active turn sink keyed by threadId. If a sink already exists for
      * the same threadId, log a warning and fail the existing sink — this
@@ -76,6 +82,18 @@ export class CodexAppServerAdapter {
             compactTimeoutMs: opts.instructionsCompactTimeoutMs,
             interruptGraceMs: opts.instructionsInterruptGraceMs,
         });
+        this.activity = new RuntimeActivityPort('CodexAppServerAdapter', opts.log);
+        this.foreignThreads = new ForeignThreadRegistry({
+            sessionManager: opts.sessionManager,
+            log: opts.log,
+            activity: this.activity,
+            // A restart deferred behind subagent work must not starve once it ends.
+            afterTurnClosed: () => {
+                if (!this.restartRequested)
+                    return;
+                void this.applyPendingRestart().catch((err) => this.opts.log?.warn?.(`deferred restart failed: ${errToString(err)}`));
+            },
+        });
     }
     /** Register a listener for every server notification; returns unregister. */
     addNotificationTap(tap) {
@@ -167,6 +185,47 @@ export class CodexAppServerAdapter {
         sink.push({ kind: 'error', message: 'dispatch inactivity deadline exceeded' });
         sink.close();
     }
+    /** Idle auto-compact (compact.ts): the compaction primitive as a tap-only main-thread turn. */
+    compact(opts) {
+        return runCodexCompact({
+            log: this.opts.log,
+            taps: this,
+            refresher: this.instructionsRefresher,
+            isMainSession: (sessionKey) => this.opts.sessionManager.isMain(sessionKey),
+            isMainLaneQuarantined: () => this.mainLaneQuarantined,
+            quarantineAndBounce: async (log) => {
+                this.mainLaneQuarantined = true;
+                this.requestProcessRestart();
+                await this.applyPendingRestart(log);
+            },
+            applyPendingRestart: (log) => this.applyPendingRestart(log),
+            openMainThread: (sessionKey, log) => this.withOpening(() => this.openDispatchTarget(sessionKey, true, log)),
+            hasActiveTurn: (threadId) => this.activeTurns.has(threadId),
+            withTapOnlyTurn: async (threadId, fn) => {
+                this.reconcilingThreadIds.add(threadId);
+                try {
+                    return await this.withOpening(fn);
+                }
+                finally {
+                    this.reconcilingThreadIds.delete(threadId);
+                }
+            },
+        }, opts);
+    }
+    /**
+     * Real work on the subprocess that predates any TurnSink (thread open,
+     * a tap-only compaction turn): counted so applyPendingRestart cannot
+     * stop() the subprocess out from under it.
+     */
+    async withOpening(fn) {
+        this.openingDispatches += 1;
+        try {
+            return await fn();
+        }
+        finally {
+            this.openingDispatches -= 1;
+        }
+    }
     hasPendingInjections(sessionKey) {
         return this.injections.hasPending(sessionKey);
     }
@@ -176,6 +235,27 @@ export class CodexAppServerAdapter {
     acknowledgeDiscardedInjection(sessionKey, deliveryKey) {
         this.injections.markDrained(sessionKey, deliveryKey);
     }
+    // --- runtime-initiated work -------------------------------------------------
+    subscribeRuntimeActivity(handler) {
+        return this.activity.subscribe(handler);
+    }
+    /**
+     * Busy = a dispatch turn, a dispatch opening its thread (possibly running
+     * the instructions-refresh compaction turn), or a subagent thread's turn
+     * is executing. Live subagent threads between turns are reported as
+     * background work, not busy.
+     */
+    isBusy() {
+        return isRuntimeBusy(this.busyState());
+    }
+    busyState() {
+        return {
+            activeTurns: this.activeTurns.size +
+                (this.openingDispatches > 0 || this.reconcilingThreadIds.size > 0 ? 1 : 0) +
+                this.foreignThreads.openTurns(),
+            backgroundWork: this.foreignThreads.size,
+        };
+    }
     async *dispatch({ event, bodyForAgent, sessionKey, context, inputLifecycle, noteActivity, }) {
         // This dispatch drains the injected copies it lists; it ALWAYS runs its own
         // turn — never skipped on outstanding injections (PFB-84, injection-registry.ts).
@@ -228,14 +308,7 @@ export class CodexAppServerAdapter {
             // compaction turn BEFORE any TurnSink exists, and a concurrent fork
             // dispatch hitting a pending restart in that window would otherwise
             // stop() the subprocess out from under it.
-            this.openingDispatches += 1;
-            let opened;
-            try {
-                opened = await this.openDispatchTarget(sessionKey, isMainSession, log);
-            }
-            finally {
-                this.openingDispatches -= 1;
-            }
+            const opened = await this.withOpening(() => this.openDispatchTarget(sessionKey, isMainSession, log));
             if (!opened.ok) {
                 yield { type: 'error', message: opened.message };
                 return;
@@ -422,34 +495,11 @@ export class CodexAppServerAdapter {
                     sawTurnEnd = true;
                     break;
                 }
-                if (envelope.kind === 'error') {
-                    yield { type: 'error', message: envelope.message };
-                    continue;
-                }
-                const runtimeEvent = envelope.event;
-                if (runtimeEvent.type === 'error') {
-                    yield runtimeEvent;
-                    continue;
-                }
-                if (runtimeEvent.type === 'runtime_session') {
-                    yield runtimeEvent;
-                    continue;
-                }
-                if (runtimeEvent.type === 'text') {
-                    // Layer 0 symmetric output contract: Codex's plain text is never
-                    // projected as a chat message. Outbound messages must come from the
-                    // agent explicitly invoking `@parall/cli messages send` / `dm` via
-                    // the shell/exec tool. Text events are still yielded so agent-core
-                    // records them as suppressed session steps for audit.
-                    yield { ...runtimeEvent, project: false, groupKey };
-                    continue;
-                }
-                if (runtimeEvent.type === 'turn_outcome') {
-                    // Turn-boundary summary — no groupKey, passed through as-is.
-                    yield runtimeEvent;
-                    continue;
-                }
-                yield { ...runtimeEvent, groupKey };
+                // Layer 0 symmetric output contract (projectRuntimeEvent): Codex's
+                // plain text is never projected as a chat message — outbound
+                // messages come from the agent invoking `parall messages send` /
+                // `dm`; text is still yielded as a suppressed audit step.
+                yield projectRuntimeEvent(envelope.kind === 'error' ? { type: 'error', message: envelope.message } : envelope.event, groupKey);
             }
         }
         finally {
@@ -652,7 +702,9 @@ export class CodexAppServerAdapter {
      */
     openingDispatches = 0;
     async applyPendingRestart(log) {
-        if (!this.restartRequested || this.activeTurns.size > 0 || this.openingDispatches > 0)
+        // isBusy folds in subagent turns: a capability change must not SIGTERM
+        // the app-server under a running spawn_agent thread.
+        if (!this.restartRequested || this.isBusy())
             return;
         this.restartRequested = false;
         (log ?? this.opts.log)?.info?.('restarting codex app-server after a capability change (the fresh-process thread/resume applies the refreshed developerInstructions to the persisted thread configuration; the model-visible context is reconciled before the next turn)');
@@ -676,6 +728,9 @@ export class CodexAppServerAdapter {
         this.instructionsRefresher.clearThreadState();
         // The (possible) zombie compaction turn dies with the subprocess.
         this.mainLaneQuarantined = false;
+        // Subagent threads die with the app-server: end their open turns
+        // (runtime_crash) and close their child sessions before the client goes.
+        this.foreignThreads.dropAll('lost: Codex app-server stopped');
         this.notifyTapsDisposed('Codex app-server stopped');
         if (client)
             client.dispose(new Error('adapter stopped'));
@@ -694,6 +749,7 @@ export class CodexAppServerAdapter {
             this.activeTurns.clear();
             this.activeTurnIds.clear();
             this.injections.clear();
+            this.foreignThreads.dropAll('lost: Codex app-server disposed');
             this.client = null;
             this.proc = null;
             this.initialized = false;
@@ -861,6 +917,7 @@ export class CodexAppServerAdapter {
         this.resumedThreadIds.clear();
         this.instructionsRefresher.clearThreadState();
         this.mainLaneQuarantined = false;
+        this.foreignThreads.dropAll(`lost: Codex app-server ${reason}`);
         this.notifyTapsDisposed(`Codex app-server ${reason}`);
         this.client = null;
         this.proc = null;
@@ -949,6 +1006,11 @@ export class CodexAppServerAdapter {
             // window that exists to surface REAL orphaned turns.
             if (this.reconcilingThreadIds.has(threadId))
                 return;
+            // Subagent threads and their turns are runtime-initiated work: routed
+            // into their own sinks and surfaced to the gateway as child-session
+            // turns instead of being dropped.
+            if (this.foreignThreads.route(method, params, threadId))
+                return;
             // Notifications for a thread with no registered sink are dropped. A
             // sustained stream of these means a turn is running that nothing is
             // consuming (threadId mismatch, sink torn down early) — the dispatch

package/dist/foreign-threads.d.ts

@@ -0,0 +1,49 @@
+import type { GatewayLogger, RuntimeActivityPort } from '@parall/agent-core';
+import { CodexRuntimeTurn } from './runtime-turn.js';
+import type { CodexSessionManager } from './session-manager.js';
+/**
+ * Threads the app-server runs that no dispatch opened — `spawn_agent`
+ * subagent threads (`thread/started` with `threadSource: "subAgent"`), or a
+ * thread whose turn showed up with no `thread/started` (bridge restarted
+ * mid-subagent). Each is a child session of its parent thread's session;
+ * every `turn/started`…`turn/completed` on it is a RuntimeInitiatedTurn
+ * (runtime-initiated-turns-design.md §5).
+ */
+export type ForeignThread = {
+    threadId: string;
+    sessionKey: string;
+    parentThreadId?: string;
+    parentSessionKey: string;
+    nickname?: string;
+    role?: string;
+    turn?: CodexRuntimeTurn;
+};
+export type ForeignThreadHost = {
+    sessionManager: CodexSessionManager;
+    log?: GatewayLogger;
+    /** Turns opened and child sessions closed go to the gateway through it. */
+    activity: RuntimeActivityPort;
+    /** A subagent turn ended — a deferred restart may apply now. */
+    afterTurnClosed(): void;
+};
+export declare class ForeignThreadRegistry {
+    private readonly host;
+    private readonly threads;
+    constructor(host: ForeignThreadHost);
+    /** Live (registered, not closed) subagent threads. */
+    get size(): number;
+    openTurns(): number;
+    /**
+     * Notifications for a thread no dispatch owns. Returns false when the
+     * caller should keep treating the frame as unroutable.
+     */
+    route(method: string, params: unknown, threadId: string): boolean;
+    /** Subagent threads die with the app-server: end open turns, close child sessions. */
+    dropAll(reason: string): void;
+    private register;
+    private openTurn;
+    /** The thread's open turn is over: last envelope, sink closed, restart re-driven. */
+    private endTurn;
+    private close;
+}
+//# sourceMappingURL=foreign-threads.d.ts.map

package/dist/foreign-threads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foreign-threads.d.ts","sourceRoot":"","sources":["../src/foreign-threads.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGhE;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,mBAAmB,CAAC;IACpC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,gEAAgE;IAChE,eAAe,IAAI,IAAI,CAAC;CACzB,CAAC;AAEF,qBAAa,qBAAqB;IAGpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;gBAE/B,IAAI,EAAE,iBAAiB;IAEpD,sDAAsD;IACtD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,SAAS,IAAI,MAAM;IAMnB;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAmDjE,sFAAsF;IACtF,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM7B,OAAO,CAAC,QAAQ;IA4BhB,OAAO,CAAC,QAAQ;IAyBhB,qFAAqF;IACrF,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,KAAK;CAYd"}