@khorsheed/dsh-local-agent-codex 0.1.0-rc.6

package/lib/types/codex-cli-provider.js

@@ -0,0 +1,1225 @@
+/**
+ * One-shot Codex CLI subagent lifecycle: spawn `codex exec "<task>"` through
+ * the subprocess seam under the harness's scoped home, capture its printed
+ * response as the run output, and dispose to whole-tree quiescence. Mirrors
+ * the kimi-cli provider: every accepted run is a fresh process and a fresh
+ * codex session; there is no continuation across runs.
+ *
+ * The provider name `codex-local` avoids colliding with the official
+ * `subagent-codex` package's provider name `codex` — a composition that
+ * mounts both would fail loud with DUPLICATE_PROVIDER. The tool row in this
+ * bundle's patch takes the official model-facing name `subagent_codex`
+ * instead: the official preset row ships disabled, and the patch disables
+ * it too (a deliberate user re-enable conflicts loud, by design).
+ * @module @khorsheed/dsh-local-agent-codex/codex-cli-provider
+ */
+import { randomUUID } from 'node:crypto';
+import { createAssistantMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { NO_START_CAPABILITIES, settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
+import { assertResumeCwdUnchanged, assertResumeScopeUnchanged, resolveRoundModel, containerExecSpawn, containerScopedHome, delegationEnv, establishSubagentCatalogChild, persistChildSession, probeCliVersion, resolveChildCwd, subagentDelegationLabel, } from '@khorsheed/dsh-local-agent';
+import { MEMBER_BRIDGE_SOCKET_ENV, MEMBER_BRIDGE_TOKEN_ENV } from '@khorsheed/dsh-local-agent/types';
+import { LiveChannelUnavailableError } from './live-driver.js';
+import { readCodexBaseUrl } from './provision.js';
+import { codexRolloutRoundFacts, usageFromCodex } from './records.js';
+/** Quote one TOML basic string for the `-c` config override. */
+function tomlString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** Default POSIX grace between subprocess termination tiers. */
+export const DEFAULT_DISPOSE_GRACE_MS = 3_000;
+/**
+ * Auth-shaped failure signatures in codex's stderr or event stream: the
+ * endpoint rejected the credential. Narrow on purpose — matched against
+ * provider-controlled error output only.
+ */
+export const CODEX_AUTH_FAILURE = /401 unauthorized|unauthorized|authentication failed|not logged in|access token/i;
+/** Register one member run with the channel; see {@link CodexMemberRunHandle}. */
+export function registerCodexMemberRun(ctx, childSessionId, parentSessionId) {
+    const registry = ctx.localAgent;
+    if (typeof registry.registerMemberRun !== 'function'
+        || typeof registry.memberBridgeSocketPath !== 'function'
+        || typeof registry.memberBridgeCommand !== 'function')
+        return undefined;
+    const token = registry.registerMemberRun({ childSessionId, parentSessionId, provider: 'codex-local' });
+    // Dashed server names are valid TOML bare keys (spike-verified parse).
+    const serverName = `dsh-member-${token.slice(0, 8)}`;
+    const bridge = registry.memberBridgeCommand();
+    const configOverride = `mcp_servers.${serverName}={`
+        + `command=${tomlString(bridge.command)},`
+        + `args=[${bridge.args.map(tomlString).join(',')}],`
+        + `env={${MEMBER_BRIDGE_SOCKET_ENV}=${tomlString(registry.memberBridgeSocketPath())},${MEMBER_BRIDGE_TOKEN_ENV}=${tomlString(token)}},`
+        + `default_tools_approval_mode=${tomlString('approve')}`
+        + `}`;
+    let released = false;
+    return {
+        token,
+        configOverride,
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            registry.unregisterMemberRun(token);
+        },
+    };
+}
+/**
+ * One-shot and resumable Codex CLI subagent provider: every accepted FRESH run
+ * starts a `codex exec` process in the delegating Session's workspace, under
+ * the harness scoped home; a resume round (the family tool's staged resume
+ * intent) continues the SAME thread with `codex exec --json resume <thread_id>`
+ * inside the SAME dsh child session. With the live driver configured
+ * (`live: true`), rounds instead go to the resident app-server process (see
+ * live-driver.ts); the exec path below stays the fallback.
+ */
+/**
+ * Mark the harness credential verified after a completed round, degrading
+ * silently on a core that predates the mark (the family's companion-pair
+ * rule: a provider paired with an older core loses the grade, never the run).
+ * @param ctx - host context carrying the family registry.
+ */
+function markCredentialVerified(ctx, scope) {
+    const registry = ctx.get('localAgent');
+    if (registry === undefined || typeof registry.reportAuthSuccess !== 'function')
+        return;
+    // The grade belongs to the scope the round ran against: each scoped home
+    // holds its own account, so a verified credential in one says nothing about
+    // another's.
+    registry.reportAuthSuccess('codex', scope);
+}
+/**
+ * The codex build `codex --version` reports, probed through the shared
+ * subprocess seam inside the SCOPED home (never the user's own installation)
+ * and cached by the family probe against the executable's identity. Both the
+ * effective-settings snapshot and a settled round's read-back use it — the
+ * round prefers its own rollout head, which names the build that actually ran.
+ * @param ctx - host context carrying the subprocess seam.
+ * @param homeDir - the harness's scoped home.
+ * @returns the version, or undefined when the CLI cannot be asked.
+ */
+export function codexCliVersion(ctx, homeDir) {
+    // Degrade, don't explode: a composition without the subprocess seam simply
+    // reports no version, exactly as an unaskable CLI does.
+    const subprocess = ctx.get('subprocess');
+    if (subprocess === undefined)
+        return Promise.resolve(undefined);
+    return probeCliVersion({
+        argv: ['codex', '--version'],
+        cwd: homeDir,
+        spawn: spec => subprocess.spawn(spec),
+        env: delegationEnv({ CODEX_HOME: homeDir }),
+    });
+}
+export class CodexCliProvider {
+    ctx;
+    sandbox;
+    live;
+    model;
+    overrides;
+    name = 'codex-local';
+    capabilities = NO_START_CAPABILITIES;
+    inheritsParentContext = false;
+    /**
+     * @param live - the live driver, or a resolver returning the current
+     *   generation's driver per member (the settings toggle swaps generations;
+     *   a resolver may return undefined to steer one member's round to exec
+     *   while a retiring generation still hosts it).
+     * @param model - resolver for the configured model, read PER ROUND so a
+     *   settings-card write takes effect on the next delegation without a
+     *   reload. Undefined (the resolver absent, or returning undefined) leaves
+     *   the argv exactly as it was before the key existed — the scoped
+     *   config.toml's own `model` then decides, as it always did.
+     * @param overrides - resolver for the member's session-level model override
+     *   (the composer picker, owned by the model broker). It outranks BOTH the
+     *   delegation's recorded model and the configured one: on the exec path it
+     *   re-points the next round's `-m`, and on the live path it is the member's
+     *   start model — a resident runtime bound to a different model is retired
+     *   so the round respawns onto the override.
+     */
+    constructor(ctx, sandbox = 'workspace-write', live, model, overrides) {
+        this.ctx = ctx;
+        this.sandbox = sandbox;
+        this.live = live;
+        this.model = model;
+        this.overrides = overrides;
+    }
+    /** Resolve the live driver for one round's member, if live is on for it. */
+    liveDriver(childSessionId) {
+        const live = this.live;
+        if (live === undefined)
+            return undefined;
+        return typeof live === 'function' ? live(childSessionId) : live;
+    }
+    /** Per-round member-channel registration for the exec path (see {@link registerCodexMemberRun}). */
+    memberRun(childSessionId, parentSessionId) {
+        return registerCodexMemberRun(this.ctx, childSessionId, parentSessionId);
+    }
+    async start(request) {
+        // The family tool stages exactly one intent per delegation call; the
+        // provider consumes exactly one per start. A resume intent continues the
+        // recorded thread inside the existing child session.
+        const intent = this.ctx.localAgent.takeDelegationIntent(request.parent.session.id, this.name);
+        // The scoped home this round runs against: the staged intent's scope
+        // names a sibling directory under the homes root, absent means the
+        // default one — the directory every round used before scopes existed.
+        const scope = intent?.scope;
+        const homeDir = this.ctx.localAgent.homeDir('codex', scope);
+        // The effective cwd: the caller's override (the staged intent's `cwd`,
+        // riding DelegationCallOptions.cwd) when present, else the parent
+        // session's workspace — the behavior before overrides existed.
+        const cwd = resolveChildCwd(request.parent.session.header.cwd, intent?.cwd);
+        if (cwd === undefined) {
+            throw new Error('subagent-codex: the parent session has no working directory to run the CLI in');
+        }
+        // Container exec target: the same round, spawned through `docker exec`
+        // inside a unit the caller acquired. Validated here so a target missing
+        // the in-container scoped home fails before any session record is made.
+        const exec = intent?.exec;
+        if (exec !== undefined)
+            containerScopedHome(exec, 'CODEX_HOME', 'subagent-codex');
+        if (intent !== undefined && intent.kind === 'resume') {
+            // A CLI session continues in the directory its first round ran in; a
+            // round resolving elsewhere is rejected before any process spawns.
+            const record = this.ctx.localAgent.getDelegation(intent.childSessionId);
+            assertResumeCwdUnchanged(record, cwd, 'subagent-codex');
+            // …and in the scoped home its first round ran in: a resume naming
+            // another scope would continue the thread under another account.
+            assertResumeScopeUnchanged(record, scope, 'subagent-codex');
+            // A resume re-requests the model the FIRST round recorded — the caller
+            // cannot name one (the facade refuses it), and a record without one is
+            // a delegation that named none, which this round repeats.
+            if (typeof this.ctx.localAgent.withMemberConfigurationRound !== 'function')
+                return this.startCodexResume(request, intent, cwd, homeDir, exec, scope, record?.model);
+            return this.ctx.localAgent.withMemberConfigurationRound({
+                childSessionId: intent.childSessionId, provider: this.name, parentSessionId: request.parent.session.id, cwd,
+                ...scope === undefined ? {} : { scope },
+                ...record?.model === undefined ? {} : { model: record.model },
+                ...record?.effort === undefined ? {} : { effort: record.effort },
+                ...record?.configurationLock === undefined ? {} : { configurationLock: record.configurationLock },
+            }, configuration => this.startCodexResume(request, intent, cwd, homeDir, exec, scope, record?.model, configuration), request.signal, intent?.onAdmitted);
+        }
+        const childSessionId = SessionId(intent?.preparedMemberId ?? randomUUID());
+        if (typeof this.ctx.localAgent.withMemberConfigurationRound !== 'function') {
+            if (intent?.effort !== undefined)
+                throw new Error('Codex effort requires the configuration admission core');
+            return this.startCodexFresh(request, cwd, homeDir, exec, scope, intent?.model, childSessionId);
+        }
+        return this.ctx.localAgent.withMemberConfigurationRound({
+            childSessionId, provider: this.name, parentSessionId: request.parent.session.id, cwd,
+            ...scope === undefined ? {} : { scope },
+            ...intent?.model === undefined ? {} : { model: intent.model },
+            ...intent?.effort === undefined ? {} : { effort: intent.effort },
+            ...intent?.configurationLock === undefined ? {} : { configurationLock: intent.configurationLock },
+        }, configuration => this.startCodexFresh(request, cwd, homeDir, exec, scope, intent?.model, childSessionId, configuration), request.signal, intent?.onAdmitted);
+    }
+    /** Fresh round: record the child session, spawn `codex exec`, append after settle. */
+    async startCodexFresh(request, cwd, homeDir, exec, scope, 
+    /** The model this DELEGATION requested, when the caller named one. */
+    requestedModel, runId, configuration) {
+        let childSession;
+        try {
+            const sessions = this.ctx.get('sessions');
+            if (sessions === undefined) {
+                throw new Error('the sessions service is not mounted');
+            }
+            childSession = sessions.get(runId) ?? sessions.create(runId, {
+                meta: {
+                    cwd,
+                    parentSession: request.parent.session.id,
+                    origin: 'subagent',
+                    delegationDepth: (request.parent.session.header.delegationDepth ?? 0) + 1,
+                },
+            });
+            const harness = this.ctx.localAgent.get('codex');
+            const label = subagentDelegationLabel(harness?.displayName ?? 'codex', request.descriptor.label);
+            childSession.append('subagent/descriptor', {
+                ...request.descriptor,
+                label,
+            });
+            // The official runtime appends the parent-side subagent/catalog
+            // discovery row only for in-process children (run.localAgent); this run
+            // is remote, so the provider appends it here — once per child, where
+            // the descriptor lands. A failure degrades to the warn below; a missing
+            // row never blocks the delegation.
+            establishSubagentCatalogChild(request.parent.session, childSession.header, label);
+            // No persistence create here: the stored session is materialized by the
+            // first persistChildSession sync through the CORE's cached write handle.
+            // A fire-and-forget create from the provider used to hold (and leak) a
+            // second write handle, which blocks the core's claim with
+            // SessionAlreadyOwnedError.
+        }
+        catch (error) {
+            this.ctx.logger.warn(`subagent-codex: subagent session record failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Resolve the effective custom endpoint from the scoped config.toml for
+        // diagnostics: codex reads it directly (a user manually editing the
+        // config to route through a custom provider is authoritative). Logged
+        // BEFORE the drive-mode branch so live rounds report their endpoint too.
+        const baseUrl = await readCodexBaseUrl(homeDir).catch(() => undefined);
+        this.ctx.logger.info(`subagent-codex: delegating via ${baseUrl ?? 'codex default endpoint'}`);
+        // Live driver: the round goes to the resident app-server process (one per
+        // member). A channel that fails at spawn/handshake falls through to the
+        // exec one-shot below — and stays there until the breaker cools down.
+        // A container target always takes the exec one-shot: the live driver runs
+        // a resident app-server on the HOST, which is the transport the target
+        // exists to replace.
+        const live = exec === undefined ? this.liveDriver(runId) : undefined;
+        if (live !== undefined && childSession !== undefined && !live.disabled) {
+            // The member-bound live driver receives this exact scoped home.
+            // A round that names its own model is NOT refused: it becomes the
+            // member's start model, bound at the runtime spawn (a runtime bound to
+            // a different model is retired first, so the fresh thread spawns onto
+            // the asked-for model). The session-level override outranks even this.
+            const startModel = configuration === undefined ? this.overrides?.(runId) ?? requestedModel : configuration.resolved.model;
+            try {
+                return await live.startRound(request, {
+                    cwd,
+                    homeDir,
+                    childSession,
+                    parentSessionId: request.parent.session.id,
+                    ...startModel === undefined ? {} : { startModel },
+                    ...configuration === undefined ? {} : { configuration: configuration.resolved },
+                    // The thread id arrives with thread/start (server-assigned), far
+                    // earlier than the exec path's settle-time parse.
+                    onThreadId: (threadId) => {
+                        this.ctx.localAgent.recordDelegation({
+                            childSessionId: runId,
+                            provider: this.name,
+                            parentSessionId: request.parent.session.id,
+                            cliSessionId: threadId,
+                            // The round's resolved working directory anchors the
+                            // resume-consistency check.
+                            cwd,
+                            // …and its scoped home anchors the resume-scope check.
+                            ...scope === undefined ? {} : { scope },
+                            // The model this delegation asked for: every resume round reads
+                            // it back from here instead of the caller restating it.
+                            ...requestedModel === undefined ? {} : { model: requestedModel },
+                        });
+                    },
+                });
+            }
+            catch (error) {
+                if (!(error instanceof LiveChannelUnavailableError) || request.signal.aborted)
+                    throw error;
+                this.ctx.logger.warn(`subagent-codex: live driver unavailable, using the exec one-shot: ${error.message}`);
+            }
+        }
+        // Member channel: register this run and carry the bridge declaration on
+        // the spawn argv, so the CLI session starts with member_message available.
+        // The member bridge is a host unix socket the container cannot reach, and
+        // its MCP declaration names a host node path — a containerized round
+        // therefore runs WITHOUT the member channel rather than with a broken one.
+        const member = exec === undefined ? this.memberRun(runId, request.parent.session.id) : undefined;
+        try {
+            const run = await startCodexCliRun(request, {
+                cwd,
+                env: delegationEnv({ CODEX_HOME: homeDir }),
+                ...exec === undefined ? {} : { exec },
+                endpointLabel: baseUrl,
+                sandbox: this.sandbox,
+                ...(configuration?.resolved ?? resolveRoundModel(this.overrides?.(runId) ?? requestedModel, this.model)),
+                disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
+                spawn: spec => this.ctx.subprocess.spawn(spec),
+                onError: (error, stopReason) => {
+                    this.ctx.logger.warn(`subagent-codex: child run failed (${stopReason}) via ${baseUrl ?? 'codex default endpoint'}: ${error instanceof Error ? error.message : String(error)}`);
+                },
+                onAuthFailure: (detail) => { this.ctx.localAgent.reportAuthFailure('codex', detail, scope); },
+                onAuthSuccess: () => { markCredentialVerified(this.ctx, scope); },
+                cliVersion: () => codexCliVersion(this.ctx, homeDir),
+                ...member === undefined ? {} : { member: { configOverride: member.configOverride } },
+                childSession,
+                ctx: this.ctx,
+                // The first round records the thread id so a later resume round can
+                // continue it.
+                onThreadId: (threadId) => {
+                    if (threadId === undefined)
+                        return;
+                    this.ctx.localAgent.recordDelegation({
+                        childSessionId: runId,
+                        provider: this.name,
+                        parentSessionId: request.parent.session.id,
+                        cliSessionId: threadId,
+                        // The round's resolved working directory anchors the
+                        // resume-consistency check.
+                        cwd,
+                        // …and its scoped home anchors the resume-scope check.
+                        ...scope === undefined ? {} : { scope },
+                        // The model this delegation asked for (see the live branch).
+                        ...requestedModel === undefined ? {} : { model: requestedModel },
+                    });
+                },
+                // Every settled round reports its observed model and usage through the
+                // registry's observation channel (record merge + `settled` event).
+                onRoundSettled: (round) => {
+                    this.ctx.localAgent.recordRoundSettled(runId, round);
+                },
+            });
+            // The member-channel token dies with the run, whatever its stop reason.
+            if (member !== undefined)
+                void run.result.then(member.release, member.release);
+            return run;
+        }
+        catch (error) {
+            member?.release();
+            throw error;
+        }
+    }
+    /** Resume round: continue the recorded thread inside the existing child session. */
+    async startCodexResume(request, intent, cwd, homeDir, exec, scope, 
+    /** The model the delegation's FIRST round recorded, re-requested here. */
+    requestedModel, configuration) {
+        // One in-flight resume per child session: a second resume of the same
+        // child fails loud instead of racing the first process. The lock releases
+        // on every settle path (the run.result handler below) and on the error
+        // path, so a deadlock never strands a later resume.
+        if (!this.ctx.localAgent.acquireResumeLock(intent.childSessionId)) {
+            throw new Error(`subagent-codex: 该子会话有进行中的委派，等其完成后再追问 (child session ${intent.childSessionId})`);
+        }
+        try {
+            const sessions = this.ctx.get('sessions');
+            const childSession = sessions?.get(SessionId(intent.childSessionId));
+            if (childSession === undefined) {
+                throw new Error(`subagent-codex: resume target child session ${intent.childSessionId} is not live — start a fresh delegation instead`);
+            }
+            const nextTurn = childSession.snapshotEvents().filter(event => event.type === 'turn/start').length + 1;
+            const baseUrl = await readCodexBaseUrl(homeDir).catch(() => undefined);
+            // Logged BEFORE the drive-mode branch so live rounds report their endpoint too.
+            this.ctx.logger.info(`subagent-codex: resuming via ${baseUrl ?? 'codex default endpoint'}`);
+            // Live driver: continue the member's resident app-server thread. Channel
+            // spawn/handshake failure falls through to the exec one-shot below.
+            // See the fresh path: a container target is exec-only.
+            const live = exec === undefined ? this.liveDriver(intent.childSessionId) : undefined;
+            if (live !== undefined && !live.disabled) {
+                // Resume retains the recorded scope and its native session.
+                // The resume re-requests its recorded model as the member's start
+                // model (the session-level override outranks it): a runtime bound to
+                // a different model is retired so the thread respawns onto this one.
+                const startModel = configuration === undefined ? this.overrides?.(intent.childSessionId) ?? requestedModel : configuration.resolved.model;
+                try {
+                    const liveRun = await live.startRound(request, {
+                        cwd,
+                        homeDir,
+                        childSession,
+                        parentSessionId: request.parent.session.id,
+                        resume: { cliSessionId: intent.cliSessionId, turn: nextTurn },
+                        ...startModel === undefined ? {} : { startModel },
+                        ...configuration === undefined ? {} : { configuration: configuration.resolved },
+                    });
+                    void liveRun.result.then(() => { this.ctx.localAgent.releaseResumeLock(intent.childSessionId); }, () => { this.ctx.localAgent.releaseResumeLock(intent.childSessionId); });
+                    return liveRun;
+                }
+                catch (error) {
+                    if (!(error instanceof LiveChannelUnavailableError) || request.signal.aborted)
+                        throw error;
+                    this.ctx.logger.warn(`subagent-codex: live driver unavailable, using the exec one-shot: ${error.message}`);
+                }
+            }
+            // Member channel: register the resume round (same child session, fresh
+            // per-run token) before the spawn.
+            // See the fresh path: no member channel across the container boundary.
+            const member = exec === undefined ? this.memberRun(intent.childSessionId, request.parent.session.id) : undefined;
+            let run;
+            try {
+                run = await startCodexCliRun(request, {
+                    cwd,
+                    env: delegationEnv({ CODEX_HOME: homeDir }),
+                    ...exec === undefined ? {} : { exec },
+                    endpointLabel: baseUrl,
+                    sandbox: this.sandbox,
+                    ...(configuration?.resolved ?? resolveRoundModel(this.overrides?.(intent.childSessionId) ?? requestedModel, this.model)),
+                    disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
+                    spawn: spec => this.ctx.subprocess.spawn(spec),
+                    onError: (error, stopReason) => {
+                        this.ctx.logger.warn(`subagent-codex: child run failed (${stopReason}) via ${baseUrl ?? 'codex default endpoint'}: ${error instanceof Error ? error.message : String(error)}`);
+                    },
+                    onAuthFailure: (detail) => { this.ctx.localAgent.reportAuthFailure('codex', detail, scope); },
+                    onAuthSuccess: () => { markCredentialVerified(this.ctx, scope); },
+                    cliVersion: () => codexCliVersion(this.ctx, homeDir),
+                    ...member === undefined ? {} : { member: { configOverride: member.configOverride } },
+                    childSession,
+                    ctx: this.ctx,
+                    resume: { cliSessionId: intent.cliSessionId, turn: nextTurn },
+                    // Every settled round reports its observed model and usage through
+                    // the registry's observation channel.
+                    onRoundSettled: (round) => {
+                        this.ctx.localAgent.recordRoundSettled(intent.childSessionId, round);
+                    },
+                });
+            }
+            catch (error) {
+                member?.release();
+                throw error;
+            }
+            void run.result.then(() => {
+                this.ctx.localAgent.releaseResumeLock(intent.childSessionId);
+                member?.release();
+            }, () => {
+                this.ctx.localAgent.releaseResumeLock(intent.childSessionId);
+                member?.release();
+            });
+            return run;
+        }
+        catch (error) {
+            this.ctx.localAgent.releaseResumeLock(intent.childSessionId);
+            throw error;
+        }
+    }
+}
+function thrown(value) {
+    /* v8 ignore next -- typed subprocess failures reject with Error. */
+    return value instanceof Error ? value : new Error(String(value));
+}
+/**
+ * Validate and join the one-shot task before crossing the process boundary.
+ * @param prompt - task content accepted from the shared subagent service.
+ * @returns the joined non-empty text.
+ */
+export function textTask(prompt) {
+    if (prompt.length === 0) {
+        throw new Error('subagent-codex: the one-shot task must contain only text blocks');
+    }
+    const texts = [];
+    for (const block of prompt) {
+        if (block.type !== 'text') {
+            throw new Error('subagent-codex: the one-shot task must contain only text blocks');
+        }
+        texts.push(block.text);
+    }
+    if (texts.every(text => text.trim().length === 0)) {
+        throw new Error('subagent-codex: the one-shot task must not be empty');
+    }
+    return texts.join('\n');
+}
+/** Count one tool call under the CLI's own name for the item. */
+function countToolCall(state, name) {
+    state.toolCalls.set(name, (state.toolCalls.get(name) ?? 0) + 1);
+}
+/**
+ * Fold a tool-call counter into the settled shape: `{count, byName}` with the
+ * per-name values summing to `count`. An empty map yields undefined — a
+ * stream that named no tool call reports nothing rather than a zero it did
+ * not observe.
+ * @param counts - the fold's per-name tally.
+ * @returns the settled accounting, or undefined when nothing was counted.
+ */
+export function toolCallsOf(counts) {
+    if (counts.size === 0)
+        return undefined;
+    let count = 0;
+    const byName = {};
+    for (const [name, value] of counts) {
+        count += value;
+        byName[name] = value;
+    }
+    return { count, byName };
+}
+/**
+ * Fold one NDJSON line into the stream state. Shared by
+ * {@link parseCodexJsonStream} (settle-time whole-stream parse) and
+ * {@link CodexStreamParser} (live incremental parse) so the two paths cannot
+ * drift.
+ */
+function foldCodexStreamLine(state, raw) {
+    const line = raw.trim();
+    if (line === '')
+        return;
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return;
+    }
+    if (event.type === 'thread.started' && typeof event.thread_id === 'string') {
+        state.threadId = event.thread_id;
+        if (typeof event.model === 'string' && event.model !== '')
+            state.model = event.model;
+        return;
+    }
+    if (event.type === 'turn.completed') {
+        state.completed = true;
+        if (event.usage !== undefined)
+            state.usage = usageFromCodex(event.usage);
+        if (typeof event.model === 'string' && event.model !== '')
+            state.model = event.model;
+        return;
+    }
+    if (event.type !== 'item.completed' || event.item === undefined)
+        return;
+    const item = event.item;
+    if (item.type === 'reasoning' && typeof item.text === 'string' && item.text.trim() !== '') {
+        state.lines.push({ kind: 'think', text: item.text });
+    }
+    else if (item.type === 'agent_message' && typeof item.text === 'string') {
+        state.lines.push({ kind: 'text', text: item.text });
+        state.text = item.text;
+    }
+    else if (item.type === 'command_execution') {
+        // Counted before the fold's own "did it carry anything to show" filter: a
+        // command with neither text nor output is still a call the CLI made.
+        countToolCall(state, 'command_execution');
+        const command = typeof item.command === 'string' ? item.command : undefined;
+        const output = typeof item.aggregated_output === 'string' && item.aggregated_output.trim() !== ''
+            ? item.aggregated_output
+            : undefined;
+        if (command !== undefined || output !== undefined) {
+            state.lines.push({
+                kind: 'tool',
+                id: typeof item.id === 'string' ? item.id : `codex-tool-${state.lines.length}`,
+                name: 'Bash',
+                ...command === undefined ? {} : { args: command },
+                ...output === undefined ? {} : { result: output },
+            });
+        }
+    }
+    else if (item.type === 'web_search_call') {
+        countToolCall(state, 'web_search_call');
+        state.lines.push({
+            kind: 'tool',
+            id: typeof item.id === 'string' ? item.id : `codex-tool-${state.lines.length}`,
+            name: 'WebSearch',
+        });
+    }
+    else if (item.type === 'file_change') {
+        // A patch application ({changes: [{path, kind}]}): without this case
+        // codex's file edits were invisible in the mirror.
+        countToolCall(state, 'file_change');
+        const args = (item.changes ?? [])
+            .map(change => `${change.kind ?? 'update'}: ${change.path ?? '?'}`)
+            .join('\n');
+        if (args !== '') {
+            state.lines.push({
+                kind: 'tool',
+                id: typeof item.id === 'string' ? item.id : `codex-tool-${state.lines.length}`,
+                name: 'ApplyPatch',
+                args,
+            });
+        }
+    }
+    else if (item.type === 'function_call') {
+        // Non-shell calls (e.g. the multi-agent wait): the result rides the
+        // function_call_output item, which attaches to this pending line.
+        countToolCall(state, 'function_call');
+        state.lines.push({
+            kind: 'tool',
+            id: typeof item.id === 'string' ? item.id : `codex-tool-${state.lines.length}`,
+            name: item.name ?? 'function',
+            ...typeof item.arguments === 'string' && item.arguments !== '' ? { args: item.arguments } : {},
+        });
+    }
+    else if (item.type === 'function_call_output') {
+        // A function/command result; attach to the previous tool line when one
+        // is pending (web search or command output).
+        const output = typeof item.output === 'string' ? item.output : undefined;
+        if (output !== undefined && output.trim() !== '') {
+            const last = state.lines[state.lines.length - 1];
+            if (last !== undefined && last.kind === 'tool') {
+                state.lines[state.lines.length - 1] = {
+                    ...last,
+                    result: last.result === undefined ? output : `${last.result}\n${output}`,
+                };
+            }
+        }
+    }
+}
+/**
+ * Incremental `codex exec --json` parser: feed stdout chunks as they arrive
+ * and the folded transcript accumulates line by line. The last line is
+ * volatile until the terminal `turn.completed` — a `function_call_output`
+ * merges into a pending tool line — so live consumers hold it back (see the
+ * run's live mirror).
+ */
+export class CodexStreamParser {
+    buffer = '';
+    lines = [];
+    text;
+    usage;
+    threadId;
+    model;
+    completed = false;
+    toolCalls = new Map();
+    /** Fold every complete NDJSON line in the chunk; the tail stays buffered. */
+    push(chunk) {
+        this.buffer += chunk;
+        const parts = this.buffer.split('\n');
+        this.buffer = parts.pop() ?? '';
+        for (const raw of parts)
+            foldCodexStreamLine(this, raw);
+    }
+}
+/**
+ * Parse a `codex exec --json` NDJSON event stream into an ordered transcript
+ * (thinking, agent text, tool/command activity in event order), plus the final
+ * answer text, token usage, the thread id a later resume round continues, and
+ * the model identifier the stream named (usually absent — codex 0.144.0 does
+ * not put one on the wire; the settle path then reads the rollout's
+ * turn_context). Item types covered: `reasoning` (thinking), `agent_message`
+ * (reply text), `command_execution` (shell command with aggregated output),
+ * `web_search_call`, and `function_call_output`. The last `agent_message`
+ * wins as the run output (the final answer), and `turn.completed` carries the
+ * turn's usage. Malformed lines are skipped.
+ * @param stream - the collected stdout NDJSON text.
+ * @returns the ordered transcript, final answer text, usage, thread id, and
+ *   any stream-named model.
+ */
+export function parseCodexJsonStream(stream) {
+    const state = { lines: [], text: undefined, usage: undefined, threadId: undefined, model: undefined, completed: false, toolCalls: new Map() };
+    for (const raw of stream.split('\n'))
+        foldCodexStreamLine(state, raw);
+    const toolCalls = toolCallsOf(state.toolCalls);
+    return {
+        lines: state.lines,
+        ...state.text === undefined ? {} : { text: state.text },
+        ...state.usage === undefined ? {} : { usage: state.usage },
+        ...state.threadId === undefined ? {} : { threadId: state.threadId },
+        ...state.model === undefined ? {} : { model: state.model },
+        ...toolCalls === undefined ? {} : { toolCalls },
+    };
+}
+/**
+ * Start the real `codex exec` child and publish its run. The codex
+ * reply arrives as an NDJSON event stream on stdout (`--json`): the final
+ * `agent_message` item is the run output and the `turn.completed` usage is
+ * the token accounting. stderr is piped for diagnostics and never folded
+ * into the run output. A resume round spawns `codex exec --json resume
+ * <thread_id>` instead, continuing the same thread. The run id is the child
+ * session id for a session-backed run.
+ * @param request - resolved shared subagent request.
+ * @param spec - workspace, environment, process service, and diagnostic policy.
+ * @returns the published run after the child starts.
+ */
+export function startCodexCliRun(request, spec) {
+    const task = textTask(request.prompt);
+    if (request.signal.aborted) {
+        throw new Error('subagent-codex: request was aborted before the CLI started');
+    }
+    const turn = spec.resume?.turn ?? 1;
+    // The member bridge rides a per-process `-c` override placed right after
+    // `exec` (the spike-verified position; `codex exec resume` accepts it too).
+    const memberArgv = spec.member === undefined ? [] : ['-c', spec.member.configOverride];
+    // `--skip-git-repo-check` rides every exec argv. Codex refuses to start
+    // outside a Git repository ("Not inside a trusted directory and
+    // --skip-git-repo-check was not specified") and exits before producing a
+    // single stream event, so the run fails with no diagnosable output. The
+    // delegation cwd is the CALLER's choice — a scratch directory, an eval
+    // cell, any path the `cwd` option names — and none of those are required
+    // to be repositories. The check is codex's own guard for interactive use
+    // in a stray directory; a delegation has already been directed at its
+    // workspace by the caller, so the guard can only reject work the caller
+    // asked for. Sandboxing stays with `--sandbox`, which this does not touch.
+    // The configured model rides `-m`, an option of `codex exec` itself, so the
+    // SAME position serves the fresh and the resume argv (the `resume`
+    // subcommand declares no `-m` of its own — verified against codex-cli
+    // 0.144.0). Nothing configured appends nothing: the argv below is then
+    // byte-for-byte the shape that shipped before the key existed.
+    const modelArgv = [
+        ...spec.model === undefined ? [] : ['-m', spec.model],
+        ...spec.effort === undefined ? [] : ['-c', `model_reasoning_effort=${JSON.stringify(spec.effort)}`],
+    ];
+    const argv = spec.resume === undefined
+        ? ['codex', 'exec', ...memberArgv, ...modelArgv, '--sandbox', spec.sandbox, '--skip-git-repo-check', '--json', task]
+        : ['codex', 'exec', ...memberArgv, ...modelArgv, '--sandbox', spec.sandbox, '--skip-git-repo-check', '--json', 'resume', spec.resume.cliSessionId, task];
+    // Container target: the same argv, wrapped in `docker exec`. The host cwd
+    // still applies — it is the docker CLIENT's working directory now, while
+    // the CLI's own is the target's in-container workdir.
+    const launch = spec.exec === undefined
+        ? { argv, env: spec.env }
+        : containerExecSpawn(spec.exec, { argv, env: spec.env }, 'subagent-codex');
+    const child = spec.spawn({
+        argv: launch.argv,
+        cwd: spec.cwd,
+        stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
+        graceMs: spec.disposeGraceMs,
+        env: launch.env,
+    });
+    // The spawn moment anchors the rollout-locator time window: the run's
+    // rollout file starts around here (thread creation ≈ turn start ≈ spawn),
+    // so the usage fallback can find it even when a kill truncated the stream
+    // before `thread.started` ever reached stdout.
+    const startedAtMs = Date.now();
+    // The turn opens at the real spawn moment so the timing projection
+    // measures actual CLI runtime, not the post-hoc append time.
+    spec.childSession?.append('turn/start', { turn });
+    // Live mirror: fold the NDJSON stream as chunks arrive so the child session
+    // shows the run's progress before settle; the settle mirror below resumes
+    // from the live counters and stays a no-op when live mirroring kept up.
+    const liveMirror = spec.childSession !== undefined && spec.ctx !== undefined
+        ? createCodexLiveMirror(spec, task, turn)
+        : undefined;
+    let output = '';
+    child.stdout?.on('data', (chunk) => {
+        const text = chunk.toString();
+        output += text;
+        liveMirror?.push(text);
+    });
+    let stderr = '';
+    child.stderr?.on('data', (chunk) => { stderr += chunk.toString(); });
+    const disposeProcess = async () => {
+        // Host 0.1.5 hides the child pid (the managed range owns termination):
+        // terminate() is an idempotent no-op once the range is gone, so a failed
+        // spawn needs no guard; done rejects there, which dispose must swallow.
+        child.terminate();
+        await child.waitForExit().catch(() => false);
+        await child.done.catch(() => { });
+    };
+    const runAbort = new AbortController();
+    const requestCancel = () => {
+        if (runAbort.signal.aborted)
+            return;
+        runAbort.abort(new Error('subagent-codex: run cancelled locally'));
+    };
+    const onAbort = () => { requestCancel(); };
+    request.signal.addEventListener('abort', onAbort, { once: true });
+    // Abort branch: the moment the run is cancelled locally, the attempt settles
+    // immediately — settleRunResult observes `cancelled()` and resolves the
+    // result with 'aborted' WITHOUT waiting for the child to exit. The actual
+    // process kill is dispose's job (SIGTERM → grace → SIGKILL teardown ladder),
+    // per the subprocessRunHandle contract: requestCancel settles the result,
+    // teardown reaps the process. Without this branch the result would only
+    // settle after the child exits, and dispose (which runs after the result)
+    // would never fire — a dead wait on a long-running CLI.
+    const abortBranch = new Promise((_, reject) => {
+        runAbort.signal.addEventListener('abort', () => reject(new Error('subagent-codex: run cancelled locally')), { once: true });
+    });
+    const processFailure = child.done.then(outcome => Promise.reject(new Error('subagent-codex: CLI exited before the run settled '
+        + `(code ${String(outcome.exitCode)}, signal ${String(outcome.signal)})`)), (error) => Promise.reject(thrown(error)));
+    // A normal post-result dispose also closes the process; keep the expected
+    // late rejection observed after the result race has already settled.
+    processFailure.catch(() => { });
+    const collectOutput = () => {
+        // Parse fresh at call time: stdout 'data' events may still be flushing
+        // when the settle callback computes its first output, and the consumer
+        // may poll output again later. Post-exit the seam's collected buffer is
+        // authoritative — a fast-exiting process can settle `done` before the
+        // streamed data events land.
+        const drained = child.collected.stdout?.readFrom(0).text;
+        const text = parseCodexJsonStream(drained !== undefined && drained !== '' ? drained : output).text?.trim();
+        return text === undefined || text === '' ? [] : [{ type: 'text', text }];
+    };
+    // Captured from the child's exit so the error turn/end can name the real
+    // code without the settle chain re-deriving it.
+    let exitCode = null;
+    /** The flattened failure's own message, snapshotted for the diagnostic. */
+    let settleFailure;
+    const result = settleRunResult({
+        attempt: () => Promise.race([
+            child.done.then((outcome) => {
+                if (outcome.exitCode !== 0) {
+                    const via = spec.endpointLabel ?? 'codex default endpoint';
+                    exitCode = outcome.exitCode;
+                    throw new Error(`subagent-codex: codex exec exited with code ${String(outcome.exitCode)} via ${via}`);
+                }
+                // A zero exit with no parsed answer is a silent failure, not a
+                // success: the NDJSON stream yielded no agent_message (internal
+                // error, truncated stdout, or a schema drift — the exec --json event
+                // field names are not contract-backed). Throwing here settles 'error'
+                // through the seam instead of reporting an empty 'completed' (which
+                // the upstream settleRunResult does not re-check). The abort path is
+                // untouched: it settles 'aborted' through abortBranch before this
+                // branch is ever reached.
+                const parsed = parseCodexJsonStream(output);
+                if (parsed.lines.length === 0) {
+                    // Format-drift early warning: a normally-exited stream with no
+                    // item.completed at all means the parser and the CLI disagreed on
+                    // the event shape. Warn once per run (not per line) without
+                    // changing the settle semantics — the empty output above still
+                    // reports 'error' either way.
+                    spec.onError?.(new Error('subagent-codex: exited 0 but parsed no codex events — check the codex --json event schema'), 'error');
+                    throw new Error('subagent-codex: codex exec exited 0 but produced no answer');
+                }
+                const answer = collectOutput();
+                if (answer.length === 0) {
+                    throw new Error('subagent-codex: codex exec exited 0 but produced no answer');
+                }
+                return { output: answer, stopReason: 'completed' };
+            }),
+            processFailure,
+            abortBranch,
+        ]),
+        collectOutput,
+        // The seam surfaces this as `SubagentResult.diagnostic` (bounded): the
+        // failure's own message, the stderr tail, and where the run's rollout
+        // file lands — "subagent run failed" alone sent every caller hunting.
+        collectDiagnostic: () => {
+            const detail = [];
+            if (settleFailure !== undefined)
+                detail.push(settleFailure);
+            const stderrTail = (child.collected.stderr?.readFrom(0).text || stderr).trim();
+            if (stderrTail !== '')
+                detail.push(`stderr: ${stderrTail.slice(-500)}`);
+            const homeDir = spec.env['CODEX_HOME'];
+            if (homeDir !== undefined && homeDir !== '') {
+                const threadId = parseCodexJsonStream(output).threadId;
+                const when = new Date(startedAtMs);
+                const dir = `${homeDir}/sessions/${String(when.getFullYear())}/${String(when.getMonth() + 1).padStart(2, '0')}/${String(when.getDate()).padStart(2, '0')}`;
+                detail.push(threadId === undefined ? `rollout 目录: ${dir}` : `rollout: ${dir}/rollout-*-${threadId}.jsonl`);
+            }
+            return detail.length === 0 ? undefined : detail.join('\n');
+        },
+        cancelled: () => runAbort.signal.aborted,
+        onError: (error, stopReason) => {
+            settleFailure = error instanceof Error ? error.message : String(error);
+            spec.onError?.(error instanceof Error ? error : new Error(String(error)), stopReason);
+        },
+        signal: request.signal,
+        onAbort,
+    }).then((settled) => {
+        // Every terminal path closes the turn so the timing window never stays
+        // open on a failed or cancelled run: success settles 'completed', a
+        // non-zero exit 'error', and a locally cancelled run 'aborted'. The
+        // turn/end timestamp is the real settle moment.
+        // A completed round proves the scoped credential is live — the endpoint
+        // answered. Reported here rather than from the mirror so it lands whether
+        // or not the round is session-backed.
+        if (settled.stopReason === 'completed')
+            spec.onAuthSuccess?.();
+        if (spec.childSession !== undefined) {
+            if (settled.stopReason === 'completed') {
+                spec.childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
+            }
+            else if (settled.stopReason === 'aborted') {
+                spec.childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
+            }
+            else {
+                spec.childSession.append('turn/end', {
+                    turn,
+                    reason: { kind: 'error', error: { message: `codex exec exited with code ${String(exitCode)}`, code: 'UNKNOWN' } },
+                });
+            }
+        }
+        return settled;
+    });
+    // After the child EXITS — however it ended (completed, killed by dispose, or
+    // crashed) — mirror whatever the NDJSON stream already produced into the dsh
+    // subagent session, so a cancelled round still preserves its partial work
+    // (reasoning, commands, replies) and real token usage. The thread id is
+    // recorded even on abort so the partial thread stays resumable. Waits for
+    // the settle chain first (so turn/end is already appended) AND for the
+    // process to actually exit (so stdout is drained before parsing).
+    void result.then(() => child.done).then(() => {
+        if (spec.onAuthFailure !== undefined) {
+            // The seam's collected buffers are complete at process exit; the
+            // streamed variables can lag `done` by a tick.
+            const drainedStderr = child.collected.stderr?.readFrom(0).text || stderr;
+            const drainedStdout = child.collected.stdout?.readFrom(0).text || output;
+            const authDetail = `${drainedStderr}\n${drainedStdout}`;
+            if (CODEX_AUTH_FAILURE.test(authDetail)) {
+                spec.onAuthFailure(authDetail.split('\n').find(line => line.trim() !== '') ?? 'auth failure');
+            }
+        }
+        return mirrorCodexAfterExit(spec, task, turn, output, liveMirror, startedAtMs);
+    }, () => { });
+    return Promise.resolve(subprocessRunHandle({
+        // A session-backed run's id is the child session id (the seam's local-run
+        // contract), so the tool's resume self-description names the same handle
+        // the delegation registry records.
+        id: spec.childSession?.id ?? SessionId(randomUUID()),
+        result,
+        signal: request.signal,
+        onAbort,
+        requestCancel,
+        teardown: disposeProcess,
+    }));
+}
+/** One assistant-role message event, attributed to the codex route. */
+export function codexAssistantEvent(blocks) {
+    return createAssistantMessage({
+        content: blocks,
+        source: { provider: 'codex-local', model: 'codex' },
+    });
+}
+/**
+ * Fold one transcript line into the child session as one assistant step,
+ * wrapped in the step/start–step/end boundary pair the live conversation
+ * assembler requires: without a boundary the step never enters the location
+ * index, the line's assistant message resolves to a turn-level location, and
+ * the real-time view renders nothing (only a full rebuild, which mints step
+ * drafts from the explicit coordinates, recovers it). Tool cards escape that
+ * fate only because their definition does not consult the step location.
+ * @returns whether the line folded (false when the options skipped it).
+ */
+export function appendCodexTranscriptLine(childSession, turn, step, line, usage) {
+    childSession.append('step/start', { turn, step });
+    if (line.kind === 'tool') {
+        // Native tool card: the call event now, the result event when the stream
+        // already carries it. Tool lines never carry the round's usage — the
+        // callers attach usage to the round's final line, which is an agent
+        // message on every well-formed stream.
+        const call = childSession.append('tool/call', {
+            turn,
+            step,
+            callId: line.id,
+            name: line.name,
+            arguments: line.args ?? '',
+        });
+        if (line.result !== undefined) {
+            childSession.append('tool/result', {
+                turn,
+                step,
+                message: createToolResultMessage({
+                    callId: line.id,
+                    content: [{ type: 'text', text: line.result }],
+                    isError: false,
+                }),
+            }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] });
+        }
+        childSession.append('step/end', { turn, step });
+        return true;
+    }
+    const blocks = line.kind === 'think'
+        ? [{ type: 'reasoning', text: line.text }]
+        : [{ type: 'text', text: line.text }];
+    childSession.append('assistant/message', {
+        turn,
+        step,
+        message: codexAssistantEvent(blocks),
+        stream: [],
+        ...usage === undefined ? {} : { usage },
+    }, { surfaceOp: 'append' });
+    childSession.append('step/end', { turn, step });
+    return true;
+}
+/** Fold one transcript line into the run's child session as one assistant step. */
+function appendCodexLine(spec, turn, step, line, usage) {
+    if (spec.childSession === undefined)
+        return;
+    appendCodexTranscriptLine(spec.childSession, turn, step, line, usage);
+}
+/** The delta-progress text for one transcript line. */
+export function codexLineText(line) {
+    return line.kind === 'tool'
+        ? `[工具 ${line.name}]${line.args !== undefined ? ` ${line.args}` : ''}${line.result !== undefined ? `\n${line.result}` : ''}`
+        : line.text;
+}
+/**
+ * Persist the child session's mirrored events. Thin wrapper over the core's
+ * {@link persistChildSession}: a live session syncs through the core's cached
+ * per-child write handle (host 0.1.5's live write-behind never checkpoints a
+ * mirror session — it has no agent loop — so production child logs stayed
+ * header-only until the explicit sync), a standalone one through a one-shot
+ * handle flow. Kept under the historical name for the live driver.
+ */
+export async function persistIfStandalone(ctx, childSession) {
+    await persistChildSession(ctx, childSession);
+}
+/** Create the per-run live mirror over the incremental parser. */
+function createCodexLiveMirror(spec, task, turn) {
+    const parser = new CodexStreamParser();
+    const childSession = spec.childSession;
+    const ctx = spec.ctx;
+    let mirrored = 0;
+    let userMirrored = false;
+    let queue = Promise.resolve();
+    const mirror = {
+        get mirroredLines() { return mirrored; },
+        get userMirrored() { return userMirrored; },
+        enqueue(task) {
+            queue = queue.then(task);
+            return queue;
+        },
+        push(chunk) {
+            parser.push(chunk);
+            const upto = parser.completed ? parser.lines.length : parser.lines.length - 1;
+            if (upto <= mirrored)
+                return;
+            void mirror.enqueue(async () => {
+                try {
+                    const localAgent = ctx.get('localAgent');
+                    if (!userMirrored) {
+                        userMirrored = true;
+                        childSession.append('user/message', createUserMessage({
+                            content: [{ type: 'text', text: task }],
+                            source: { kind: 'user' },
+                        }), { surfaceOp: 'append' });
+                        localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: task });
+                    }
+                    // The usage rides the last NON-tool line (tool events carry no
+                    // usage slot); a stream ending on a tool line would otherwise drop
+                    // the round's accounting. When that carrier was mirrored in an
+                    // earlier flush (before the usage was knowable), the accounting is
+                    // lost — host 0.1.5 has no usage-backfill event.
+                    let carrier = -1;
+                    if (parser.completed && parser.usage !== undefined) {
+                        for (let scan = 0; scan < parser.lines.length; scan += 1) {
+                            if (parser.lines[scan]?.kind !== 'tool')
+                                carrier = scan;
+                        }
+                    }
+                    for (let index = mirrored; index < upto; index += 1) {
+                        const line = parser.lines[index];
+                        if (line === undefined)
+                            continue;
+                        const usage = index === carrier ? parser.usage : undefined;
+                        appendCodexLine(spec, turn, index + 1, line, usage);
+                        mirrored = index + 1;
+                        localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: codexLineText(line) });
+                    }
+                    await persistChildSession(ctx, childSession);
+                    localAgent?.reportRunProgress(childSession.id, { kind: 'mirror', mirroredLines: mirrored });
+                }
+                catch (error) {
+                    ctx.logger.warn(`subagent-codex: live mirror failed: ${thrown(error).message}`);
+                }
+            });
+        },
+    };
+    return mirror;
+}
+/**
+ * Mirror the delegation's user prompt and the codex event transcript into the
+ * dsh subagent session, then persist. Runs detached from the settle race — the
+ * run result settles with the child exit, and a failure here is
+ * diagnostic-only (the subagent record degrades to a final-text-only view).
+ * The transcript's reasoning folds to `reasoning` blocks, agent text and tool
+ * activity to text blocks (tool lines render `[工具 Bash] <command> → output`),
+ * and the final assistant message carries the round's usage when codex
+ * reported it, so the tokenUsage projection counts the delegation.
+ * @param spec - the run spec carrying the child session and host context.
+ * @param task - the one-shot task text (the user prompt).
+ * @param turn - the round's turn number (1 for a fresh round, incremented on resume).
+ * @param parsed - the parsed NDJSON transcript, final output, and usage.
+ * @param fromLines - transcript lines the live mirror already appended.
+ * @param userMirrored - whether the live mirror already appended the prompt.
+ */
+async function appendCodexResponse(spec, task, turn, parsed, fromLines = 0, userMirrored = false) {
+    if (spec.childSession === undefined || spec.ctx === undefined)
+        return;
+    const childSession = spec.childSession;
+    const localAgent = spec.ctx.get('localAgent');
+    if (!userMirrored) {
+        childSession.append('user/message', createUserMessage({
+            content: [{ type: 'text', text: task }],
+            source: { kind: 'user' },
+        }), { surfaceOp: 'append' });
+        localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: task });
+    }
+    // The round's usage rides the last NON-tool line: tool activity folds to
+    // `tool/call`/`tool/result` events (which carry no usage slot), and a kill
+    // mid-command ends the transcript with a tool line — exactly the case the
+    // rollout-usage recovery exists for.
+    let usageIndex = -1;
+    for (let index = 0; index < parsed.lines.length; index += 1) {
+        if (parsed.lines[index]?.kind !== 'tool')
+            usageIndex = index;
+    }
+    let step = fromLines + 1;
+    for (const line of parsed.lines.slice(fromLines)) {
+        appendCodexLine(spec, turn, step, line, step - 1 === usageIndex ? parsed.usage : undefined);
+        localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: codexLineText(line) });
+        step += 1;
+    }
+    if (parsed.usage !== undefined && usageIndex !== -1 && usageIndex < fromLines) {
+        // The carrier line went out through the live mirror before the usage was
+        // knowable (a killed run recovers it from the rollout at settle). Host
+        // 0.1.5 has no usage-backfill event (the per-chunk event is gone and
+        // appended messages are immutable), so the round's accounting is lost in
+        // this race — log it instead of dropping it silently.
+        spec.ctx?.logger.warn(`subagent-codex: round ${turn} usage arrived after its carrier line was mirrored; the accounting is dropped`);
+    }
+    await persistChildSession(spec.ctx, childSession);
+    localAgent?.reportRunProgress(childSession.id, { kind: 'mirror', mirroredLines: parsed.lines.length });
+}
+/**
+ * Mirror the codex NDJSON stream into the child session AFTER the CLI process
+ * has exited, whatever its stop reason. A cancelled or failed round still
+ * preserves the events the stream already emitted (reasoning, commands,
+ * replies, usage) instead of leaving the child blank — the run result settles
+ * 'aborted'/'error' at the cancel moment, but codex may have produced content
+ * before the kill landed. Also records the thread id (fresh rounds) so a
+ * later resume can continue the partial thread.
+ *
+ * **Usage recovery**: a non-completed terminal state never emits
+ * `turn.completed`, so the parsed stream carries no usage even though codex
+ * wrote the run's real token spend to its rollout file. When the stream's
+ * usage is absent, the mirror falls back to the run's rollout file — located
+ * by the thread id (the `session_meta` head id) or by the spawn-time window —
+ * and attaches the file's LAST `token_count` entry (same
+ * `input − cached` caliber as `turn.completed`, via the shared
+ * {@link usageFromCodex}), so a killed or failed run still books its tokens.
+ * The fallback is best-effort and silent: no rollout file, an unreadable
+ * home, or a hard kill that wrote no token_count leaves the child without
+ * usage, exactly as before.
+ *
+ * **Model observation**: the exec --json wire carries no model field (codex
+ * 0.144.0), so the run's model identifier is read from the located rollout
+ * file's LAST `turn_context` line whose timestamp falls inside this run's
+ * window — the turn codex actually started for this round. When the stream
+ * itself names a model (a future CLI), the stream wins. Absent on any miss;
+ * the observation rides {@link CodexCliRunSpec.onRoundSettled} along with the
+ * round's usage.
+ * @param spec - the run spec carrying the child session and host context.
+ * @param task - the one-shot task text (the user prompt).
+ * @param turn - the round's turn number.
+ * @param output - the collected NDJSON stdout.
+ * @param startedAtMs - the spawn moment, anchoring the rollout time window.
+ */
+async function mirrorCodexAfterExit(spec, task, turn, output, live, startedAtMs) {
+    if (spec.childSession === undefined || spec.ctx === undefined)
+        return;
+    const work = async () => {
+        const parsed = parseCodexJsonStream(output);
+        if (spec.resume === undefined)
+            spec.onThreadId?.(parsed.threadId);
+        const fromLines = live?.mirroredLines ?? 0;
+        const userMirrored = live?.userMirrored ?? false;
+        // Non-completed terminal states (aborted/error) never emit turn.completed,
+        // so parsed.usage is absent; the exec wire never names a model at all
+        // (codex 0.144.0). Both come back from the run's own rollout file —
+        // located by thread id, and under concurrency disambiguated by the run's
+        // cwd, since several cells' files share one time window. The head of the
+        // same file names the codex build that served the round, which is a
+        // stronger answer than a later `--version` probe of the executable: it is
+        // what actually ran.
+        let usage = parsed.usage;
+        let observedModel = parsed.model;
+        let cliVersion;
+        const homeDir = spec.env['CODEX_HOME'];
+        if (homeDir !== undefined && homeDir !== '') {
+            const facts = await codexRolloutRoundFacts(homeDir, {
+                threadId: parsed.threadId,
+                windowStart: startedAtMs,
+                cwd: spec.cwd,
+            });
+            usage ??= facts.usage;
+            observedModel ??= facts.model;
+            cliVersion = facts.cliVersion;
+        }
+        // A rollout that named no build still reports one: the probe of the
+        // executable this round spawned. Absent only when neither channel answers.
+        cliVersion ??= await spec.cliVersion?.();
+        // The round's settled observation rides out even when nothing streamed:
+        // an empty stream is still a settled round, and the rollout may already
+        // name the model and the spend.
+        spec.onRoundSettled?.({
+            ...observedModel === undefined ? {} : { observedModel },
+            ...cliVersion === undefined ? {} : { cliVersion },
+            ...usage === undefined ? {} : { usage },
+            ...parsed.toolCalls === undefined ? {} : { toolCalls: parsed.toolCalls },
+        });
+        // Nothing streamed at all (e.g. the CLI died before the first item): keep
+        // the pre-live-mirror behavior of recording nothing.
+        if (parsed.lines.length === 0 && !userMirrored)
+            return;
+        await appendCodexResponse(spec, task, turn, {
+            lines: parsed.lines,
+            output: collectOutputBlocks(parsed.text),
+            ...usage === undefined ? {} : { usage },
+        }, fromLines, userMirrored);
+    };
+    try {
+        // Behind the live mirror's queue so a flush in flight cannot interleave.
+        if (live === undefined)
+            await work();
+        else
+            await live.enqueue(work);
+    }
+    catch (error) {
+        spec.onError?.(thrown(error), 'error');
+    }
+}
+/** Build the run-output blocks from the final codex answer text. */
+function collectOutputBlocks(text) {
+    const trimmed = text?.trim();
+    return trimmed === undefined || trimmed === '' ? [] : [{ type: 'text', text: trimmed }];
+}