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

package/lib/types/live-driver.js

@@ -12,12 +12,10 @@ import { claudeDirectory } from './model-catalog.js';
  * continuable) and the same-shape push stream folded live per turn.
  *
  * Auth discipline (a hard requirement): the resident process runs under the
- * family's scoped `CLAUDE_CONFIG_DIR` and nothing else — the OAuth marker in
- * the scoped `.claude.json` and the keychain entry hashed to that path are
- * exactly what the exec mode's one-shot processes already use. The driver
- * never touches the user's global `~/.claude`, never runs any `auth` verb,
- * and only adds `ANTHROPIC_BASE_URL` when the plugin config supplies it (the
- * exec path's exact env rule).
+ * family's scoped `CLAUDE_CONFIG_DIR` plus the resolved endpoint credential's
+ * `ANTHROPIC_*` variables (the scope's endpoint-auth.json over the plugin
+ * config — the exec path's exact env rule, resolved per spawn). The driver
+ * never touches the user's global `~/.claude` and never runs any `auth` verb.
  *
  * Protocol facts (all probed): the first stdin `user` message triggers
  * `system/init` carrying the server-assigned session id (EVERY turn emits a
@@ -30,8 +28,9 @@ import { claudeDirectory } from './model-catalog.js';
  * Fold: the resident stream speaks the exec path's exact event vocabulary
  * (`system`/`assistant`/`user`/`result`), so each turn folds through the
  * shared `ClaudeStreamParser` with the exec live mirror's hold-back rule (the
- * volatile last line waits for `result`, which carries the round's usage).
- * Every line folds 1:1. The always-enabled
+ * volatile last line waits for `result`, which carries the round's usage, and
+ * an unresulted tool line holds the fold until its result merges in place —
+ * the native lifecycle folds as one closed step). Every line folds 1:1. The always-enabled
  * `--include-partial-messages` adds incremental output on top: each `stream_event` partial accumulates into its kind's
  * stream (native message id + block index, with ordered legacy fallback),
  * which reserves a (turn, step) at its first delta and
@@ -62,11 +61,13 @@ import { claudeDirectory } from './model-catalog.js';
  */
 import { ClaudeControlRequests } from './control-requests.js';
 import { StringDecoder } from 'node:string_decoder';
+import { randomUUID } from 'node:crypto';
 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 { appendClaudeTranscriptLine, assistantEvent, claudeLineText, ClaudeStreamParser, claudeVersionFromInit, DEFAULT_DISPOSE_GRACE_MS, registerClaudeMemberRun, textTask, toolCallsOf, } from './claude-cli-provider.js';
-import { syncClaudeCredentialFile } from './records.js';
+import { appendClaudeTranscriptLine, assistantEvent, appendClaudeRequestHeader, claudeLineText, ClaudeStreamParser, claudeVersionFromInit, DEFAULT_DISPOSE_GRACE_MS, registerClaudeMemberRun, MEMBER_TOOL_TIMEOUT_MS, textTask, toolCallsOf, usageFromClaude, } from './claude-cli-provider.js';
+import { endpointAuthEnv } 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 the turn's system/init ack (a cold boot can be slow). */
@@ -81,11 +82,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 kind's snapshot messages. */
 export const DEFAULT_SNAPSHOT_MIN_CHARS = 0;
-/**
- * The stream-json channel could not come up (spawn failure or the first
- * turn's init never arrived). 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);
@@ -419,14 +415,10 @@ export class ClaudeLiveDriver {
         if (this.disposed) {
             throw new LiveChannelUnavailableError('the live driver is disposed');
         }
-        // Keychain→file sync before EVERY spawn: claude 2.1.236 reads
-        // <home>/.credentials.json at runtime while login and the process's own
-        // refresh write the keychain — the file goes stale on every rotation
-        // (single-rotation refresh tokens make a consumed copy poison for the
-        // next spawn). The login watch's sync alone cannot keep a resident
-        // runtime authenticatable across rotations. Best-effort: a missing grant
-        // fails the turn with the CLI's own "Not logged in", not here.
-        await syncClaudeCredentialFile(spec.homeDir, message => { this.ctx.logger.warn(message); }).catch(() => false);
+        // The endpoint credential is resolved per spawn (the scope's
+        // endpoint-auth.json over the plugin config): a key rotation reaches the
+        // resident runtime at its next respawn, with no reload and no reconcile.
+        const endpoint = await this.config.endpoint?.(spec.homeDir);
         // The member bridge rides the spawn argv (`--mcp-config` + `--allowedTools`),
         // exactly as in the exec path; the resident process serves one member, so
         // its token lives with the process.
@@ -460,11 +452,14 @@ export class ClaudeLiveDriver {
             stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' },
             graceMs: DEFAULT_DISPOSE_GRACE_MS,
             // The auth discipline: exactly the exec path's env — the scoped config
-            // dir, plus the configured base URL override only.
+            // dir plus the resolved endpoint credential's `ANTHROPIC_*` variables.
             env: delegationEnv({
                 CLAUDE_CONFIG_DIR: spec.homeDir,
+                // A bridge call may wait for the human (ask_user_question, a mode
+                // tool's approval); give MCP calls the bridge's own 30-minute bound.
+                ...member === undefined ? {} : { MCP_TOOL_TIMEOUT: MEMBER_TOOL_TIMEOUT_MS },
                 ...spec.configuration === undefined ? {} : { CLAUDE_CODE_EFFORT_LEVEL: spec.configuration.effort ?? 'auto' },
-                ...this.config.baseUrl === undefined ? {} : { ANTHROPIC_BASE_URL: this.config.baseUrl },
+                ...endpointAuthEnv(endpoint),
             }),
         };
         let child;
@@ -579,27 +574,22 @@ export class ClaudeLiveDriver {
          */
         let roundModel;
         let roundCliVersion;
-        /** Whether a folded line already carries the round's usage (no backfill event exists). */
+        /** Whether a folded line already carried usage (per-call inline, or the round's total as the fallback — no backfill event exists). */
         let usageCarried = false;
         /**
-         * 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.
-         */
-        const reservedSteps = [];
-        /**
-         * The streaming kinds seen this round by stream key:
-         * deltas accumulate into throttled snapshot assistant/messages appended
-         * at the kind'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 kind's completed line folds at the same step and finalizes it; an
-         * entry whose completion never arrives is force-finalized at settle.
+         * The streaming blocks seen this round by stream key: deltas accumulate
+         * into throttled snapshots at the block'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 block's completed
+         * line 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 (chronological order).
          */
         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 one it chronologically precedes). */
+        const folded = new Set();
         /** The stream deltas currently accumulate into (kinds stream sequentially). */
         let activeStream;
         let persistQueue = Promise.resolve();
@@ -635,6 +625,44 @@ export class ClaudeLiveDriver {
         // key, paired with their completion in arrival order.
         let messageKey;
         let legacyMessage = 0;
+        // One API call per native message id. Claude emits an `assistant` event
+        // per content block, each repeating the usage snapshot taken at
+        // message_start (output counted only that far); the call's final count
+        // arrives in its message_delta. A call's lines therefore fold only once
+        // the call ended (or the round settles), and its usage — the start
+        // snapshot completed by the delta — rides its last line alone.
+        const callUsage = new Map();
+        const openCalls = new Set();
+        let currentCall;
+        const endCall = (usage) => {
+            if (currentCall === undefined)
+                return;
+            if (typeof usage === 'object' && usage !== null) {
+                const merged = { ...callUsage.get(currentCall) };
+                for (const [key, value] of Object.entries(usage))
+                    if (value !== null && value !== undefined)
+                        merged[key] = value;
+                callUsage.set(currentCall, merged);
+            }
+            openCalls.delete(currentCall);
+        };
+        /**
+         * A line's usage when its call is known: `skip` on every line but the
+         * call's last, the call's final usage (or, without stream events, the
+         * line's own report) on the last; `null` for an id-less line.
+         */
+        const callLineUsage = (index) => {
+            const id = parser.lines[index]?.messageId;
+            if (id === undefined)
+                return null;
+            let last = -1;
+            parser.lines.forEach((line, position) => { if (line.messageId === id)
+                last = position; });
+            if (index !== last)
+                return { skip: true };
+            const raw = callUsage.get(id);
+            return { usage: raw !== undefined ? usageFromClaude(raw) : parser.lines[index].usage };
+        };
         const streamKey = (kind, index) => `${messageKey ?? `legacy-${turn}-${legacyMessage}`}:${typeof index === 'number' ? index : kind}`;
         /**
          * Append one snapshot of a streaming kind at its reserved (turn, step).
@@ -646,6 +674,28 @@ export class ClaudeLiveDriver {
         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 WRITTEN (`lastStep`) — while chronology is
+        // kept by start order: a stream sorts before every line that completed
+        // after its first delta (`after`). 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 and its fold writes it.
+        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() === '')
@@ -660,44 +710,62 @@ export class ClaudeLiveDriver {
             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 usage = parser.usage;
+            // Per-call folds carry the accounting; the round total only ever
+            // back-fills a stream that named none (a sum would double count).
+            const totalFallback = withUsage && !usageCarried && usage !== undefined && !parser.lines.some(line => line.usage !== undefined);
             childSession.append('assistant/message', {
                 turn,
-                step: stream.step,
+                step: stream.durable,
                 message: assistantEvent([
                     stream.kind === 'think'
                         ? { type: 'reasoning', text: stream.text }
                         : { type: 'text', text: stream.text },
                 ]),
                 stream: [],
-                ...withUsage && !usageCarried && usage !== undefined ? { usage } : {},
+                ...totalFallback ? { usage } : {},
                 ...interrupted ? { interrupted: true } : {},
             }, { surfaceOp: 'append' });
-            if (withUsage && !usageCarried && usage !== undefined)
+            if (totalFallback)
                 usageCarried = true;
             stream.lastSnapshotAt = now;
             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 streaming kind will occupy — past every completed
-         * line (folded or held back) and every earlier reservation. A different
-         * kind'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 block: its provisional key and how many lines
+         * had completed when it began. A different block's deltas force one
+         * freshness snapshot of the current stream.
          */
         const reserveStream = (itemId, kind) => {
             if (activeStream !== undefined && activeStream !== itemId) {
@@ -711,78 +779,121 @@ export class ClaudeLiveDriver {
             }
             let stream = streams.get(itemId);
             if (stream === undefined) {
-                const step = parser.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: parser.lines.length, text: '', lastSnapshotAt: 0, lastSnapshotLen: 0, opened: false };
                 streams.set(itemId, stream);
             }
             activeStream = itemId;
         };
-        /** The sequential fold step for `parser.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
+            : (line.streamId === undefined ? undefined : streams.get(line.streamId))
+                ?? [...streams.values()].find(candidate => candidate.kind === line.kind && (line.streamId === undefined || candidate.itemId.startsWith('legacy-')));
+        /** Write parser.lines[index] at the next step(s). */
+        const foldLine = (index, lineUsage) => {
+            const line = parser.lines[index];
+            // The fold's per-call usage (the assistant event's inline report) wins
+            // over the round-total fallback; once any line carries its own, the
+            // round total never joins the log (a sum would double count).
+            const perCall = callLineUsage(index);
+            const effectiveUsage = perCall === null ? line.usage ?? lineUsage
+                : 'skip' in perCall ? undefined : perCall.usage ?? lineUsage;
+            if (effectiveUsage !== undefined)
+                usageCarried = true;
+            const stream = streamOfLine(line);
+            if (stream !== undefined) {
+                // A streamed line 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: assistantEvent(blocks),
+                    stream: [],
+                    ...effectiveUsage === undefined ? {} : { usage: effectiveUsage },
+                }, { surfaceOp: 'append' });
+                finishStream(stream);
+                closeOpenStep();
+            }
+            else {
+                closeOpenStep();
+                lastStep += 1;
+                // The fold decided the usage; the line's own (per-block snapshot) must not override it.
+                const { usage: _snapshot, ...bare } = line;
+                appendClaudeTranscriptLine(childSession, turn, lastStep, bare, effectiveUsage);
             }
-            return step;
+            folded.add(index);
+            localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: claudeLineText(line) });
         };
-        /** Mirror folded lines [mirrored, upto); the last line is held back until `result`. */
-        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 to the settle's final snapshot — host 0.1.5 has
-            // no usage-backfill event.
+        /**
+         * Mirror the completed lines before `upto` in chronological order; the
+         * last line is held back until `result`. A line waits behind every stream
+         * that began before it completed (that stream's line folds first, or the
+         * mirror stops while it still streams). A tool line whose result the
+         * stream has not recorded yet HOLDS the fold mid-round: the fold writes
+         * the native lifecycle as one closed step (the released-log reader
+         * resolves every advertised call before step/end), and the result merges
+         * into the call's line in place, so a later pass retries from here. The
+         * settle flushes (`settle: true` — the turn's result event, or the final
+         * flush after a cancel/failure) never hold: a result that will never
+         * arrive folds as the interrupted placeholder.
+         */
+        const mirrorUpTo = (upto, withUsage, settle = false) => {
+            // Fallback carrier only: when the fold stamped per-call usage onto any
+            // line, the round total never joins the log (a sum would double count);
+            // otherwise it rides the last NON-tool line (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 to the settle's
+            // final snapshot — host 0.1.5 has no usage-backfill event.
             let usageIndex = -1;
-            if (withUsage) {
+            if (withUsage && !parser.lines.some(line => line.usage !== undefined)) {
                 for (let index = 0; index < parser.lines.length; index += 1) {
                     if (parser.lines[index]?.kind !== 'tool')
                         usageIndex = index;
                 }
             }
-            for (let index = mirrored; index < upto; index += 1) {
-                const line = parser.lines[index];
-                if (line === undefined)
-                    continue;
+            const usageFor = (index) => {
                 const lineUsage = withUsage && index === usageIndex ? parser.usage : undefined;
                 if (lineUsage !== undefined)
                     usageCarried = true;
-                const stream = line.kind === 'tool' ? undefined
-                    : (line.streamId === undefined ? undefined : streams.get(line.streamId))
-                        ?? [...streams.values()].find(candidate => candidate.kind === line.kind && (line.streamId === undefined || candidate.itemId.startsWith('legacy-')));
-                const itemId = stream?.itemId;
-                if (itemId !== undefined && stream !== undefined) {
-                    // A streamed line folds at its reserved step, finalizing the
-                    // snapshots: the step opens only if no snapshot ever landed (a
-                    // fast stream 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: assistantEvent(blocks),
-                        stream: [],
-                        ...lineUsage === undefined ? {} : { usage: lineUsage },
-                    }, { surfaceOp: 'append' });
-                    streamPublisher?.finish(stream.step);
-                    childSession.append('step/end', { turn, step: stream.step });
-                }
-                else {
-                    appendClaudeTranscriptLine(childSession, turn, foldStep(index), line, lineUsage);
+                return lineUsage;
+            };
+            outer: for (let index = mirrored; index < upto; index += 1) {
+                if (folded.has(index))
+                    continue;
+                const line = parser.lines[index];
+                if (line === undefined)
+                    continue;
+                if (!settle && line.kind === 'tool' && line.result === undefined)
+                    break;
+                // A call still streaming more blocks folds once it ends (its usage is final then).
+                if (!settle && line.messageId !== undefined && openCalls.has(line.messageId))
+                    break;
+                const own = streamOfLine(line);
+                // 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 = parser.lines.findIndex((candidate, position) => position > index && position < upto && !folded.has(position) && streamOfLine(candidate) === earlier);
+                    if (at < 0)
+                        break outer;
+                    const atCall = parser.lines[at]?.messageId;
+                    if (!settle && atCall !== undefined && openCalls.has(atCall))
+                        break outer;
+                    foldLine(at, usageFor(at));
                 }
-                mirrored = index + 1;
-                localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: claudeLineText(line) });
+                foldLine(index, usageFor(index));
             }
+            while (folded.has(mirrored))
+                mirrored += 1;
             if (upto > 0)
                 persist();
         };
@@ -794,6 +905,16 @@ export class ClaudeLiveDriver {
         /** The round's event sink (installed on the runtime while it runs). */
         const onEvent = (event) => {
             const type = event['type'];
+            // Once settled, the turn/end is written: the sink stays only so a late
+            // result converges the chain. Anything else (the CLI's interrupt notice
+            // after a cancel) would land after the turn closed and corrupt the log.
+            if (roundSettled) {
+                if (type === 'result') {
+                    awaitingResult = false;
+                    resolveResult(event);
+                }
+                return;
+            }
             if (type === 'system' && typeof event['session_id'] === 'string') {
                 // EVERY turn emits an init; the first one mints the delegation id.
                 // Its model/build fields are this round's settled observation (the
@@ -811,9 +932,11 @@ export class ClaudeLiveDriver {
                 // The turn closes: fold the result event itself (it carries the
                 // round's usage — the fold's usage carrier rule needs it in both
                 // granularities), then flush the held-back last line WITH the usage.
+                // Settle semantics: a tool call whose result never arrived folds with
+                // the interrupted placeholder — the turn is over, so it never will.
                 awaitingResult = false;
                 parser.push(JSON.stringify(event) + '\n');
-                mirrorUpTo(parser.lines.length, true);
+                mirrorUpTo(parser.lines.length, true, true);
                 resolveResult(event);
                 return;
             }
@@ -822,6 +945,18 @@ export class ClaudeLiveDriver {
                 if (inner?.['type'] === 'message_start') {
                     const message = inner['message'];
                     messageKey = typeof message?.['id'] === 'string' ? message['id'] : `legacy-${turn}-${++legacyMessage}`;
+                    currentCall = typeof message?.['id'] === 'string' ? message['id'] : undefined;
+                    if (currentCall !== undefined) {
+                        openCalls.add(currentCall);
+                        const usage = message?.['usage'];
+                        if (typeof usage === 'object' && usage !== null)
+                            callUsage.set(currentCall, { ...usage });
+                    }
+                    return;
+                }
+                if (inner?.['type'] === 'message_delta' || inner?.['type'] === 'message_stop') {
+                    endCall(inner['usage']);
+                    mirrorUpTo(parser.lines.length - 1, false);
                     return;
                 }
                 const delta = inner?.['delta'];
@@ -905,6 +1040,17 @@ export class ClaudeLiveDriver {
             // The turn boundary opens before the message goes out (exec parity: the
             // exec path opens at spawn).
             childSession.append('turn/start', { turn });
+            // The provider's own launch facts are the child log's request config —
+            // claude's wire never carries effort, so the env the provider sets is
+            // the authoritative source. The header contract requires a model: an
+            // unconfigured round records nothing rather than inventing one.
+            if (spec.configuration?.model !== undefined) {
+                appendClaudeRequestHeader(childSession, {
+                    provider: 'claude-local',
+                    model: spec.configuration.model,
+                    reasoningEffort: (spec.configuration.effort ?? 'auto'),
+                });
+            }
             childSession.append('user/message', createUserMessage({
                 content: [{ type: 'text', text: task }],
                 source: { kind: 'user' },
@@ -960,7 +1106,16 @@ export class ClaudeLiveDriver {
                 // held-back line (and the usage already observed) would be lost —
                 // flush it now (the exec settle-mirror's partial-work contract).
                 if (mirrored < parser.lines.length)
-                    mirrorUpTo(parser.lines.length, true);
+                    mirrorUpTo(parser.lines.length, true, true);
+                // A line still waiting behind a stream whose completion never came:
+                // finalize that stream from its last snapshot, then keep folding.
+                while (mirrored < parser.lines.length && streams.size > 0) {
+                    const oldest = streams.values().next().value;
+                    appendStreamSnapshot(oldest, true, settled.stopReason !== 'completed', false, true);
+                    finishStream(oldest);
+                    closeOpenStep();
+                    mirrorUpTo(parser.lines.length, true, true);
+                }
                 // Streams whose completion never arrived (abort, or the turn ended
                 // mid-message) still finalize INSIDE the turn window: one forced
                 // snapshot each — interrupted on a non-completed round, the LAST one
@@ -969,9 +1124,8 @@ export class ClaudeLiveDriver {
                     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;
@@ -1039,7 +1193,11 @@ export class ClaudeLiveDriver {
         // never hold it hostage — a cancel returns 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 { ClaudeEndpointAuth } from './endpoint-auth.ts';
 import { ClaudeLiveDriver } from './live-driver.ts';
 import type { ClaudeLiveMirrorGranularity } from './live-driver.ts';
 /** The resolved live settings (rc.1: volatile row config; 0.1.5: schema defaults ← YAML base ← user layer). */
@@ -25,8 +26,10 @@ export interface ClaudeLiveSettings {
     recentModels?: readonly string[];
 }
 /** The Cordis-config inputs every driver generation shares. */
-type DriverBase = Pick<Config, 'permissionMode' | 'baseUrl'> & {
+type DriverBase = Pick<Config, 'permissionMode'> & {
     liveIdleMs?: number;
+    /** Per-spawn endpoint credential resolver, handed to every driver generation. */
+    endpoint?: (homeDir: string) => Promise<ClaudeEndpointAuth>;
     /**
      * Per-spawn member model resolver, handed to every driver generation:
      * answers the member's effective model from its session-level override, the

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

@@ -70,8 +70,10 @@ export interface ClaudeModelBrokerDeps {
         home: string;
         directory: (refresh?: boolean) => LocalAgentModelDirectory | Promise<LocalAgentModelDirectory>;
     };
-    /** The settings layer: the plugin-config model, read per call. */
-    readonly settingsModel: () => string | undefined;
+    /** The settings layer: the curated list's first entry, else the plugin-config model, read per call. */
+    readonly settingsModel: (scope?: string) => string | undefined;
+    /** The scope's curated model list, read per call (empty = the fallback chain decides the vocabulary too). */
+    readonly modelList?: (scope?: string) => readonly string[];
     /** The scoped settings.json's own model, minus live-spawn scratch writes. */
     readonly cliDefault: (childSessionId?: string) => Promise<string | undefined>;
     readonly directory?: (childSessionId?: string, refresh?: boolean) => LocalAgentModelDirectory | Promise<LocalAgentModelDirectory>;