@khorsheed/dsh-local-agent-codex 0.2.0-rc.1 → 0.2.0

package/lib/types/live-driver.js

@@ -24,10 +24,12 @@
 import { randomUUID } from 'node:crypto';
 import { StringDecoder } from 'node:string_decoder';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { SessionId } from '@deepseek-ai/dsh-session';
 import { settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
 import { delegationEnv, persistChildSession, LiveStreamPublisher, LiveFlush, LIVE_FLUSH_INTERVAL_MS } from '@khorsheed/dsh-local-agent';
-import { appendCodexTranscriptLine, codexAssistantEvent, codexLineText, DEFAULT_DISPOSE_GRACE_MS, registerCodexMemberRun, textTask, } from './codex-cli-provider.js';
+import { appendCodexRequestHeader, appendCodexTranscriptLine, codexAssistantEvent, codexLineText, DEFAULT_DISPOSE_GRACE_MS, registerCodexMemberRun, textTask, } from './codex-cli-provider.js';
 import { codexRolloutRoundFacts } from './records.js';
+import { endpointAuthEnv, endpointConfigOverrides } from './endpoint-auth.js';
 /** Default idle lifetime of an unused resident runtime before reclaim. */
 export const DEFAULT_LIVE_IDLE_MS = 30 * 60_000;
 /** Default timeout for a wire request acknowledgement. */
@@ -44,11 +46,6 @@ const RECLAIM_EOF_GRACE_MS = 1_000;
 export const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = LIVE_FLUSH_INTERVAL_MS;
 /** Default minimum text growth between one streaming item's snapshot messages. */
 export const DEFAULT_SNAPSHOT_MIN_CHARS = 0;
-/**
- * The app-server channel could not come up (spawn failure or handshake
- * timeout/mismatch). The provider catches exactly this and falls back to the
- * exec one-shot; any other error is a real round failure.
- */
 export class LiveChannelUnavailableError extends Error {
     constructor(message) {
         super(message);
@@ -137,16 +134,27 @@ export function codexAppServerItemToLine(item) {
             };
         }
         case 'dynamicToolCall': {
-            // Non-shell tools (e.g. the multi-agent `wait`): {id, tool, arguments, status}.
+            // Non-shell tools (e.g. the multi-agent `wait`, the deferred `exec`
+            // discovery tool): {id, tool, arguments, status, contentItems, success}
+            // — the app-server carries the result INLINE on the completed item.
             const tool = typeof item['tool'] === 'string' ? item.tool : 'dynamic';
             const args = item['arguments'] === undefined || item['arguments'] === null
                 ? undefined
                 : typeof item['arguments'] === 'string' ? item['arguments'] : JSON.stringify(item['arguments']);
+            const content = item['contentItems'];
+            const result = Array.isArray(content)
+                ? content
+                    .filter((block) => typeof block === 'object' && block !== null)
+                    .map(block => typeof block['text'] === 'string' ? block['text'] : undefined)
+                    .filter((text) => text !== undefined && text !== '')
+                    .join('\n')
+                : undefined;
             return {
                 kind: 'tool',
                 id: itemId ?? `codex-live-${randomUUID()}`,
                 name: tool,
                 ...args === undefined || args === '' ? {} : { args },
+                ...result === undefined || result === '' ? {} : { result },
             };
         }
         case 'collabAgentToolCall': {
@@ -174,15 +182,22 @@ export function codexAppServerItemToLine(item) {
 function usageFromAppServer(breakdown) {
     const input = Number(breakdown['inputTokens']);
     const cached = Number(breakdown['cachedInputTokens']);
+    const cacheWrite = Number(breakdown['cacheWriteInputTokens']);
     const output = Number(breakdown['outputTokens']);
+    // Codex's input total already contains both cache buckets (total = input +
+    // output); the shared contract keeps the three input buckets disjoint.
     const usage = {
         inputTokens: Number.isFinite(input) && Number.isFinite(cached)
-            ? Math.max(0, input - cached)
+            ? Math.max(0, input - cached - (Number.isFinite(cacheWrite) ? cacheWrite : 0))
             : Number.isFinite(input) ? input : 0,
         outputTokens: Number.isFinite(output) ? output : 0,
     };
-    if (Number.isFinite(cached) && cached > 0)
+    // The field rides every payload (zero included): write it whenever present,
+    // so "no hits" never reads as "not reported".
+    if (Number.isFinite(cached))
         usage.cacheReadTokens = cached;
+    if (Number.isFinite(cacheWrite) && cacheWrite > 0)
+        usage.cacheWriteTokens = cacheWrite;
     return usage;
 }
 /**
@@ -552,10 +567,18 @@ export class CodexLiveDriver {
         const startModel = spec.startModel?.trim();
         const model = spec.configuration !== undefined ? spec.configuration.model
             : startModel !== undefined && startModel !== '' ? startModel : this.config.model?.(key)?.trim();
+        // The endpoint credential routes the resident process too: with a key the
+        // app-server spawns onto the relay's custom provider (the same `-c`
+        // overrides the exec path carries), so a live round never consults
+        // auth.json either. Read per spawn — a card write reaches the next respawn.
+        const endpoint = this.config.endpoint === undefined
+            ? undefined
+            : await this.config.endpoint(spec.homeDir).catch(() => undefined);
         const spawnSpec = {
             argv: [
                 'codex', 'app-server',
                 ...member === undefined ? [] : ['-c', member.configOverride],
+                ...endpointConfigOverrides(endpoint),
                 ...model === undefined || model === '' ? [] : ['-c', `model=${JSON.stringify(model)}`],
                 ...spec.configuration?.effort === undefined ? [] : ['-c', `model_reasoning_effort=${JSON.stringify(spec.configuration.effort)}`],
                 '--stdio',
@@ -563,7 +586,7 @@ export class CodexLiveDriver {
             cwd: spec.cwd,
             stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' },
             graceMs: DEFAULT_DISPOSE_GRACE_MS,
-            env: delegationEnv({ CODEX_HOME: spec.homeDir }),
+            env: delegationEnv({ CODEX_HOME: spec.homeDir, ...endpointAuthEnv(endpoint) }),
         };
         let child;
         try {
@@ -772,27 +795,31 @@ export class CodexLiveDriver {
         const lines = [];
         let mirrored = 0;
         let usage;
-        /** Whether a folded line already carries the round's usage (no backfill event exists). */
-        let usageCarried = false;
+        /** The cumulative turn total the wire's `tokenUsage.total` names, for the settled report. */
+        let totalUsage;
         /**
-         * The step ledger: `reservedSteps` holds every step a stream reservation
-         * consumed (in increasing order — permanently, whether the stream later
-         * completes or stays an orphan snapshot), and a sequential line folds at
-         * its index shifted past every reservation before it. A tool completed
-         * mid-stream therefore folds ABOVE the stream's step and the projection
-         * renders the round's chronological order.
+         * Per-call usage by transcript line: each `thread/tokenUsage/updated`
+         * notification closes one API call (its items have all completed), and
+         * the call's LAST line carries its `tokenUsage.last`. The map is
+         * authoritative per line, independent of the flush's withUsage flag.
          */
-        const reservedSteps = [];
+        const usageByLine = new Map();
+        /** Whether a folded line already carries usage (per-call, or the round's fallback — no backfill event exists). */
+        let usageCarried = false;
         /**
-         * The streaming items seen this round by item id:
-         * deltas accumulate into throttled snapshot assistant/messages appended
-         * at the item's reserved (turn, step) — the host folds repeated settles
-         * at one coordinate into one live-updating chat node, which is the only
-         * streaming channel left after 0.1.5 retired the durable per-chunk event.
-         * The item's completion folds at the same step and finalizes it; an entry
-         * whose completion never arrives is force-finalized at settle.
+         * The streaming items seen this round by item id: deltas accumulate into
+         * throttled snapshots at the item's step once it may open in the log
+         * (previewed live before that) — the host folds repeated settles at one
+         * coordinate into one live-updating chat node. The item's completion
+         * folds at the same step and finalizes it; an entry whose completion
+         * never arrives is force-finalized at settle. A tool that completes
+         * mid-stream folds after the stream, keeping the round's chronology.
          */
         const streams = new Map();
+        /** Provisional stream keys (live flush and preview identity), never log steps. */
+        let streamKeys = 0;
+        /** Line indexes already written (a line may fold ahead of an earlier one it chronologically precedes). */
+        const folded = new Set();
         /** The item deltas currently accumulate into (items stream sequentially). */
         let activeStream;
         /** Items/completions that arrived before the turn id was known. */
@@ -840,6 +867,29 @@ export class CodexLiveDriver {
         const streamPublisher = localAgent?.liveStreams === undefined ? undefined
             : new LiveStreamPublisher(localAgent.liveStreams, childSession, turn, persist, error => this.ctx.logger.warn(`live checkpoint failed: ${String(error)}`));
         const liveFlush = new LiveFlush(error => this.ctx.logger.warn(`live mirror flush failed: ${String(error)}`), this.config.snapshotMinIntervalMs ?? DEFAULT_SNAPSHOT_MIN_INTERVAL_MS);
+        // The step ledger. The log admits steps strictly in sequence — one open
+        // at a time, numbered when it is WRITTEN (`lastStep`) — while the round's
+        // chronology is kept by start order: a stream sorts before every line
+        // that completed after its first delta (`after` = lines completed before
+        // it began). A stream's step opens in the log only once it is the oldest
+        // unfinished stream and everything before it is written; until then the
+        // browser previews it (`preview`), and its fold writes the text anyway.
+        let lastStep = 0;
+        let openStep;
+        const openStreamStep = (stream) => {
+            lastStep += 1;
+            childSession.append('step/start', { turn, step: lastStep });
+            stream.durable = lastStep;
+            stream.opened = true;
+            openStep = lastStep;
+        };
+        const closeOpenStep = () => {
+            if (openStep === undefined)
+                return;
+            childSession.append('step/end', { turn, step: openStep });
+            openStep = undefined;
+        };
+        const canOpenStream = (stream) => openStep === undefined && mirrored >= stream.after && streams.keys().next().value === stream.itemId;
         const pendingStreamArrival = new Map();
         const appendStreamSnapshot = (stream, force, interrupted, withUsage = false, final = false) => {
             if (stream.text.trim() === '')
@@ -854,31 +904,39 @@ export class CodexLiveDriver {
             liveFlush.cancel(stream.step);
             const receivedAt = pendingStreamArrival.get(stream.step) ?? now;
             pendingStreamArrival.delete(stream.step);
-            if (streamPublisher !== undefined && !final) {
-                if (!stream.opened) {
-                    childSession.append('step/start', { turn, step: stream.step });
-                    stream.opened = true;
+            if (!stream.opened) {
+                if (canOpenStream(stream))
+                    openStreamStep(stream);
+                else if (!final) {
+                    // Not its turn in the log yet: show it live, write it later.
+                    streamPublisher?.preview(stream.step, stream.kind, stream.text, { itemId: stream.itemId, receivedAt });
+                    return;
                 }
-                streamPublisher.update(stream.step, stream.kind, stream.text, { receivedAt });
+                else {
+                    // Settle: every line has folded; take the next step.
+                    closeOpenStep();
+                    openStreamStep(stream);
+                }
+            }
+            if (streamPublisher !== undefined && !final) {
+                streamPublisher.update(stream.durable, stream.kind, stream.text, { receivedAt });
                 stream.lastSnapshotAt = now;
                 stream.lastSnapshotLen = stream.text.length;
                 return;
             }
-            if (!stream.opened) {
-                childSession.append('step/start', { turn, step: stream.step });
-                stream.opened = true;
-            }
-            const attachUsage = withUsage && !usageCarried && usage !== undefined;
+            // Per-call folds carry the accounting; a final snapshot only falls back
+            // to the last-call read when the wire named no per-call usage at all.
+            const attachUsage = withUsage && !usageCarried && usageByLine.size === 0 && usage !== undefined;
             childSession.append('assistant/message', {
                 turn,
-                step: stream.step,
+                step: stream.durable,
                 message: codexAssistantEvent([
                     stream.kind === 'think'
                         ? { type: 'reasoning', text: stream.text }
                         : { type: 'text', text: stream.text },
                 ]),
                 stream: [],
-                ...withUsage && !usageCarried && usage !== undefined ? { usage } : {},
+                ...withUsage && !usageCarried && usageByLine.size === 0 && usage !== undefined ? { usage } : {},
                 ...interrupted ? { interrupted: true } : {},
             }, { surfaceOp: 'append' });
             if (attachUsage)
@@ -887,11 +945,21 @@ export class CodexLiveDriver {
             stream.lastSnapshotLen = stream.text.length;
             persist();
         };
+        /** Close a stream's live presentation once its final text is in the log. */
+        const finishStream = (stream) => {
+            liveFlush.cancel(stream.step);
+            streams.delete(stream.itemId);
+            if (activeStream === stream.itemId)
+                activeStream = undefined;
+            streamPublisher?.finish(stream.step);
+            if (stream.durable !== undefined)
+                streamPublisher?.finish(stream.durable);
+        };
         /**
-         * Reserve the step one new streaming item will occupy — past every
-         * completed line (folded or held back) and every earlier reservation. A
-         * different item's deltas force one final snapshot of the current stream
-         * (its completion still folds at its own reserved step when it lands).
+         * Track one new streaming item: its provisional key (live flush and
+         * preview identity) and how many lines had completed when it began. A
+         * different item's deltas force one freshness snapshot of the current
+         * stream.
          */
         const reserveStream = (itemId, kind) => {
             if (activeStream !== undefined && activeStream !== itemId) {
@@ -905,75 +973,96 @@ export class CodexLiveDriver {
             }
             let stream = streams.get(itemId);
             if (stream === undefined) {
-                const step = lines.length + reservedSteps.length + 1;
-                reservedSteps.push(step);
-                stream = { itemId, kind, step, text: '', lastSnapshotAt: 0, lastSnapshotLen: 0, opened: false };
+                streamKeys += 1;
+                stream = { itemId, kind, step: streamKeys, after: lines.length, text: '', lastSnapshotAt: 0, lastSnapshotLen: 0, opened: false };
                 streams.set(itemId, stream);
             }
             activeStream = itemId;
         };
-        /** The sequential fold step for `lines[index]`: its position shifted past every reservation before it. */
-        const foldStep = (index) => {
-            let step = index + 1;
-            for (const reserved of reservedSteps) {
-                if (reserved <= step)
-                    step += 1;
-                else
-                    break;
+        /** The stream a completed line finalizes, if it was streamed. */
+        const streamOfLine = (line) => line === undefined || line.kind === 'tool' ? undefined : streams.get(line.itemId ?? '');
+        /** Write lines[index] at the next step(s). */
+        const foldLine = (index, lineUsage) => {
+            const line = lines[index];
+            const stream = streamOfLine(line);
+            if (stream !== undefined) {
+                // A streamed item finalizes its own step (opening it now if no
+                // snapshot ever could) and closes it.
+                if (!stream.opened) {
+                    closeOpenStep();
+                    openStreamStep(stream);
+                }
+                const blocks = stream.kind === 'think'
+                    ? [{ type: 'reasoning', text: line.kind === 'tool' ? '' : line.text }]
+                    : [{ type: 'text', text: line.kind === 'tool' ? '' : line.text }];
+                childSession.append('assistant/message', {
+                    turn,
+                    step: stream.durable,
+                    message: codexAssistantEvent(blocks),
+                    stream: [],
+                    ...lineUsage === undefined ? {} : { usage: lineUsage },
+                }, { surfaceOp: 'append' });
+                finishStream(stream);
+                closeOpenStep();
+            }
+            else {
+                closeOpenStep();
+                lastStep += 1;
+                appendCodexTranscriptLine(childSession, turn, lastStep, line, lineUsage);
             }
-            return step;
+            folded.add(index);
+            localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: codexLineText(line) });
         };
-        /** Mirror folded lines [mirrored, upto); the last line is held back until completion. */
+        /**
+         * Mirror the completed lines before `upto` in chronological order; the
+         * last line is held back until completion. A line waits behind every
+         * stream that began before it completed: that stream's line folds first,
+         * or — while it is still streaming — the mirror stops until it lands.
+         */
         const mirrorUpTo = (upto, withUsage) => {
-            // The usage rides the last NON-tool line (tool events carry no usage
-            // slot, and a kill mid-command ends the transcript with a tool line).
-            // A carrier mirrored in an earlier flush (before the usage was knowable)
-            // loses the accounting — host 0.1.5 has no usage-backfill event.
+            // Per-call usage rides the line its notification stamped, whenever that
+            // line folds. The fallback (a wire that never named per-call usage)
+            // rides the last NON-tool line once — tool/call and tool/result events
+            // carry no usage slot, and a kill mid-command ends the transcript with
+            // a tool line. A carrier mirrored in an earlier flush (before the usage
+            // was knowable) loses the accounting — host 0.1.5 has no usage-backfill
+            // event.
             let usageIndex = -1;
-            if (withUsage) {
+            if (withUsage && usageByLine.size === 0) {
                 for (let index = 0; index < lines.length; index += 1) {
                     if (lines[index]?.kind !== 'tool')
                         usageIndex = index;
                 }
             }
-            for (let index = mirrored; index < upto; index += 1) {
-                const line = lines[index];
-                if (line === undefined)
-                    continue;
+            const usageFor = (index) => {
+                const own = usageByLine.get(index);
+                if (own !== undefined) {
+                    usageCarried = true;
+                    return own;
+                }
                 const lineUsage = withUsage && index === usageIndex ? usage : undefined;
                 if (lineUsage !== undefined)
                     usageCarried = true;
-                const itemId = line.kind === 'tool' ? undefined : line.itemId;
-                const stream = itemId === undefined ? undefined : streams.get(itemId);
-                if (itemId !== undefined && stream !== undefined) {
-                    // A streamed item folds at its reserved step, finalizing the
-                    // snapshots: the step opens only if no snapshot ever landed (a
-                    // fast item that stayed under the throttle), and closes here.
-                    liveFlush.cancel(stream.step);
-                    streams.delete(itemId);
-                    if (activeStream === itemId)
-                        activeStream = undefined;
-                    if (!stream.opened)
-                        childSession.append('step/start', { turn, step: stream.step });
-                    const blocks = stream.kind === 'think'
-                        ? [{ type: 'reasoning', text: line.kind === 'tool' ? '' : line.text }]
-                        : [{ type: 'text', text: line.kind === 'tool' ? '' : line.text }];
-                    childSession.append('assistant/message', {
-                        turn,
-                        step: stream.step,
-                        message: codexAssistantEvent(blocks),
-                        stream: [],
-                        ...lineUsage === undefined ? {} : { usage: lineUsage },
-                    }, { surfaceOp: 'append' });
-                    streamPublisher?.finish(stream.step);
-                    childSession.append('step/end', { turn, step: stream.step });
-                }
-                else {
-                    appendCodexTranscriptLine(childSession, turn, foldStep(index), line, lineUsage);
+                return lineUsage;
+            };
+            outer: for (let index = mirrored; index < upto; index += 1) {
+                if (folded.has(index))
+                    continue;
+                const own = streamOfLine(lines[index]);
+                // Streams order among themselves by start; a plain line follows every
+                // stream that began before it completed.
+                const all = [...streams.values()];
+                const before = own === undefined ? all.filter(stream => stream.after <= index) : all.slice(0, all.indexOf(own));
+                for (const earlier of before) {
+                    const at = lines.findIndex((line, position) => position > index && position < upto && !folded.has(position) && streamOfLine(line) === earlier);
+                    if (at < 0)
+                        break outer;
+                    foldLine(at, usageFor(at));
                 }
-                mirrored = index + 1;
-                localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: codexLineText(line) });
+                foldLine(index, usageFor(index));
             }
+            while (folded.has(mirrored))
+                mirrored += 1;
             if (upto > 0)
                 persist();
         };
@@ -983,6 +1072,17 @@ export class CodexLiveDriver {
             // The boundary opens after the accept ack (a definitive reject leaves no
             // dangling turn/start); the prompt and any early items flush inside it.
             childSession.append('turn/start', { turn });
+            // The provider's own launch facts are the child log's request config —
+            // codex's notifications never carry model/effort, so the turn/start
+            // request parameters the provider sends are the authoritative source.
+            // The header contract requires a model: without one nothing is recorded.
+            if (spec.configuration?.model !== undefined) {
+                appendCodexRequestHeader(childSession, {
+                    provider: 'codex-local',
+                    model: spec.configuration.model,
+                    ...spec.configuration.effort === undefined ? {} : { reasoningEffort: spec.configuration.effort },
+                });
+            }
             childSession.append('user/message', createUserMessage({
                 content: [{ type: 'text', text: task }],
                 source: { kind: 'user' },
@@ -1010,8 +1110,9 @@ export class CodexLiveDriver {
                 if (line === undefined)
                     return;
                 lines.push(line);
-                // Hold back the volatile last line until turn/completed (it is the
-                // round's usage carrier) — the exec live mirror's exact rule.
+                // Hold back the volatile last line (a tool result may still merge
+                // into it) — per-call usage arrives on thread/tokenUsage/updated and
+                // folds with the line whenever it lands.
                 mirrorUpTo(lines.length - 1, false);
                 return;
             }
@@ -1040,19 +1141,41 @@ export class CodexLiveDriver {
             if (method === 'thread/tokenUsage/updated') {
                 const tokenUsage = params['tokenUsage'];
                 const last = tokenUsage?.['last'];
-                if (last !== undefined)
+                const total = tokenUsage?.['total'];
+                // A total with no numbers is "not reported" (never override the
+                // per-call read with an empty object).
+                if (total !== undefined && (Number.isFinite(Number(total['inputTokens'])) || Number.isFinite(Number(total['outputTokens'])))) {
+                    totalUsage = usageFromAppServer(total);
+                }
+                if (last !== undefined) {
                     usage = usageFromAppServer(last);
+                    // One notification closes one API call (the rollout's token_count
+                    // position: right after the call's last item). Stamp the call's own
+                    // usage on its last line and flush the completed prefix with it;
+                    // the volatile last line keeps its hold (a tool result may still
+                    // merge into it) and folds with its mapped usage whenever it lands.
+                    if (lines.length > 0) {
+                        usageByLine.set(lines.length - 1, usage);
+                        mirrorUpTo(lines.length - 1, true);
+                    }
+                }
                 return;
             }
             if (method === 'turn/completed') {
                 const turnData = params['turn'];
-                mirrorUpTo(lines.length, true);
-                resolveCompletion({
-                    status: String(turnData['status']),
-                    ...(turnData['error'] === null || turnData['error'] === undefined
-                        ? {}
-                        : { error: turnData['error'] }),
-                });
+                // A fold failure must never skip the completion: the round settles
+                // with its mirrored prefix instead of hanging forever.
+                try {
+                    mirrorUpTo(lines.length, true);
+                }
+                finally {
+                    resolveCompletion({
+                        status: String(turnData['status']),
+                        ...(turnData['error'] === null || turnData['error'] === undefined
+                            ? {}
+                            : { error: turnData['error'] }),
+                    });
+                }
             }
         };
         /** Route one wire notification: round-scoped, turn-id tagged, early ones buffered. */
@@ -1174,6 +1297,15 @@ export class CodexLiveDriver {
                 // flush it now (the exec settle-mirror's partial-work contract).
                 if (mirrored < lines.length)
                     mirrorUpTo(lines.length, true);
+                // A line still waiting behind a stream whose completion never came:
+                // finalize that stream from its last snapshot, then keep folding.
+                while (mirrored < lines.length && streams.size > 0) {
+                    const oldest = streams.values().next().value;
+                    appendStreamSnapshot(oldest, true, settled.stopReason !== 'completed', false, true);
+                    finishStream(oldest);
+                    closeOpenStep();
+                    mirrorUpTo(lines.length, true);
+                }
                 // Streams whose item/completed never arrived (abort, or the server
                 // ended the turn mid-item) still finalize INSIDE the turn window:
                 // one forced snapshot each — interrupted on a non-completed round,
@@ -1183,9 +1315,8 @@ export class CodexLiveDriver {
                     const remaining = [...streams.values()];
                     for (const [position, stream] of remaining.entries()) {
                         appendStreamSnapshot(stream, true, settled.stopReason !== 'completed', position === remaining.length - 1, true);
-                        streamPublisher?.finish(stream.step);
-                        if (stream.opened)
-                            childSession.append('step/end', { turn, step: stream.step });
+                        finishStream(stream);
+                        closeOpenStep();
                     }
                     streams.clear();
                     activeStream = undefined;
@@ -1238,7 +1369,11 @@ export class CodexLiveDriver {
                         windowStart: startedAtMs,
                         cwd: spec.cwd,
                     });
-                    const settledUsage = usage ?? facts.usage;
+                    // The settled report wants the round TOTAL: prefer the wire's
+                    // cumulative tokenUsage.total (the per-call `last` under-reports a
+                    // multi-call round); the rollout read is the non-completed turn's
+                    // fallback, as before.
+                    const settledUsage = totalUsage ?? usage ?? facts.usage;
                     const round = {
                         ...facts.model === undefined ? {} : { observedModel: facts.model },
                         ...facts.cliVersion === undefined ? {} : { cliVersion: facts.cliVersion },
@@ -1261,7 +1396,11 @@ export class CodexLiveDriver {
         // hostage to the slow windows — a cancel returns the run immediately.
         await Promise.race([accepted, abortBranch.catch(() => undefined)]);
         return subprocessRunHandle({
-            id: childSession.id,
+            // Host 0.2.1: a fresh PER-EXECUTION run id — the activation manager
+            // rejects a run id naming a live Session (this child session is live),
+            // and resume rounds reuse the child session id. The family's durable
+            // tracking key (the child session id) rides the staged intent instead.
+            id: SessionId(randomUUID()),
             result,
             signal: request.signal,
             onAbort,

package/lib/types/live-switch.d.ts

@@ -13,6 +13,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { SettingsFace } from '@khorsheed/dsh-local-agent';
 import type { Config } from './index.ts';
+import type { CodexEndpointAuth } from './endpoint-auth.ts';
 import { CodexLiveDriver } from './live-driver.ts';
 import type { CodexLiveMirrorGranularity } from './live-driver.ts';
 /** The resolved live settings (schema defaults ← YAML base ← user layer). */
@@ -41,6 +42,12 @@ export declare class LiveDriverSwitch {
          * outrank the settings value.
          */
         model?: (childSessionId: string) => string | undefined;
+        /**
+         * Per-spawn endpoint credential resolver, handed to every driver
+         * generation: a resolution carrying a key routes the app-server at the
+         * relay (see the driver's own contract).
+         */
+        endpoint?: (scopeHome: string) => Promise<CodexEndpointAuth>;
     });
     /**
      * Resolve the live driver for one round's member (the provider's call

package/lib/types/live-switch.js

@@ -69,6 +69,7 @@ export class LiveDriverSwitch {
                 ...this.options.sandbox === undefined ? {} : { sandbox: this.options.sandbox },
                 ...this.options.liveIdleMs === undefined ? {} : { liveIdleMs: this.options.liveIdleMs },
                 ...this.options.model === undefined ? {} : { model: this.options.model },
+                ...this.options.endpoint === undefined ? {} : { endpoint: this.options.endpoint },
             })
             : undefined;
         if (retiring !== undefined) {

package/lib/types/model-broker.d.ts

@@ -31,8 +31,18 @@ import type { LocalAgentModelBroker, LocalAgentModelInfo, LocalAgentModelDirecto
 export interface CodexModelBrokerDeps {
     /** Host context carrying the family registry (in-flight reads, delegation records). */
     readonly ctx: Context;
-    /** The plugin-config `model` resolver — the settings layer, blank reads unset. */
-    readonly settingsModel: () => string | undefined;
+    /**
+     * The settings-layer model for one scoped home: the curated model list's
+     * FIRST entry (models.json, edited on the card), then the plugin-config
+     * `model` key — blank reads unset.
+     */
+    readonly settingsModel: (homeDir: string) => string | undefined;
+    /**
+     * The scope's curated model list (models.json) for the choice vocabulary:
+     * non-empty it is the COMPLETE vocabulary (nothing outside the endpoint's
+     * served catalog sneaks in); empty falls back to the pre-list chain.
+     */
+    readonly modelList?: (homeDir: string) => readonly string[];
     /** The card's recent-model memory (the suggestion vocabulary's tail). */
     readonly recentModels: () => readonly string[];
     /**