agent-nuvira 3.3.3 → 3.3.5

package/dist/cli/chat.js

@@ -15,6 +15,12 @@ import { maybeAutoRecall, recallContextBlock } from '../context/session-recall.j
 import { getMemoryManager } from '../memory/manager.js';
 import { logger } from '../utils/logger.js';
 import { printOrchestrationResult } from './execute.js';
+// WS5 (#27) — isolation (a git worktree around the turn) and resume (replaying
+// recorded steps instead of re-paying for them). See the module headers for why
+// the worktree is created HERE, around the whole turn, and why a replay is
+// keyed on the step's whole input rather than its position alone.
+import { beginIsolation, endIsolation, resolveIsolationRequest, worktreeNotice, } from '../tools/worktree.js';
+import { closeResume, openResume, resolveResumeRequest, } from '../learning/step-checkpoint.js';
 import { applyActiveModel } from './model.js';
 import { getProviderFallback, classifyFallbackError, isRetryableError, isTransientForRetry, recordRegistrySuccess } from '../learning/provider-fallback.js';
 import { recordActionFailure } from '../learning/failure-bookkeeping.js';
@@ -35,8 +41,10 @@ import { recordMetricTime, getMetrics } from '../enterprise/metrics.js';
 import { resolveDispatch } from '../nlu/actions.js';
 import { hasCodingAction, resolveAskKind } from '../nlu/conversation-gate.js';
 import { runToolLoop, extractFallbackToolCalls } from '../tools/tool-loop.js';
+// WS3 (#25) — the turn as a span, when an operator has asked for OTLP export.
+import { flushSpans, otelNoticeOnce, startTurnSpan } from '../observability/otel.js';
 import { detectAnswerQualityFailure, answerQualityError, toUserFacingGenerationError, isToolCallingUnsupported, stripToolCallArtifacts, } from '../inference/tool-call-utils.js';
-import { beginTrace, endTrace, recordStep, recordTraceEvent, buildTraceOutcome } from '../learning/reasoning-trace.js';
+import { beginTrace, endTrace, recordStep, recordTraceEvent, recordTraceFindings, buildTraceOutcome } from '../learning/reasoning-trace.js';
 import { recordWorkingState, getWorkingState, formatWorkingState } from '../learning/working-state.js';
 import { getLoopExposureMode } from '../tools/toolsets.js';
 import { resolveModelHarnessProfile, shouldSkipNativeTools } from '../learning/model-harness.js';
@@ -46,6 +54,9 @@ import { sweepTransientFailures, collectionRevivalStore } from '../learning/prov
 import { analyzeComplexity } from '../learning/hybrid-router.js';
 import { routingCacheSignature, withRoutingCache } from '../learning/routing-cache.js';
 import { getTool, TOOL_CONTRACT_JSON } from '../tools/registry.js';
+// WS1 — the finding tool's bus event, and the wire shape every surface reports.
+import { FINDING_EVENT } from '../tools/finding-tool.js';
+import { debugLogNotice, sessionDebugLog } from '../observability/debug-log.js';
 import { buildFollowupContinuationPrompt, isSuggestedFollowup, } from '../tools/followup-utils.js';
 // S2/S3 — the shared tool-call reliability helpers (salvage failed_generation,
 // compact fallback schemas). One copy for every tool-calling surface, not
@@ -447,21 +458,48 @@ export class ChatCommand extends BaseCommand {
         }
         const parsed = parseRequestSync(message);
         const dispatchDecision = resolvePipelineDispatch(parsed, { dev: opts.dev, text: message });
-        const answer = await this.runChatAnswer(message, opts.history ?? [], { type, provider, model }, { provider: mergedOpts.provider, model: mergedOpts.model, dev: mergedOpts.dev, cache: true }, true, { auto: autoMode }, parsed, { askUser: opts.askUser, onProgress: opts.onProgress, onToolCall: opts.onToolCall, onPlanChange: opts.onPlanChange, onGitDiff: opts.onGitDiff, onSkillDraft: opts.onSkillDraft, planStore: opts.planStore ?? this.planStore, gateway: opts.gateway, projectContext: opts.projectContext, recallContext: recallBlock, projectPath: opts.projectPath, onToken: opts.onToken, signal: opts.signal, continuation: opts.continuation, systemPolicy: opts.systemPolicy });
+        const answer = await this.runChatAnswer(message, opts.history ?? [], { type, provider, model }, { provider: mergedOpts.provider, model: mergedOpts.model, dev: mergedOpts.dev, cache: true }, true, { auto: autoMode }, parsed, { askUser: opts.askUser, onProgress: opts.onProgress, onToolCall: opts.onToolCall, onPlanChange: opts.onPlanChange, onGitDiff: opts.onGitDiff, onSkillDraft: opts.onSkillDraft, onFinding: opts.onFinding, planStore: opts.planStore ?? this.planStore, gateway: opts.gateway, projectContext: opts.projectContext, recallContext: recallBlock, projectPath: opts.projectPath, onToken: opts.onToken, signal: opts.signal, continuation: opts.continuation, systemPolicy: opts.systemPolicy, debugSurface: opts.debugSurface ?? 'cli-chat', debugSession: opts.debugSession, worktree: opts.worktree, keepWorktree: opts.keepWorktree, resume: opts.resume });
         // No-model fallback: the tool loop could not generate a single response
         // AND the rules assessed a high-confidence pipeline intent — run the
         // pipeline directly (rules decide only when the model is unavailable; the
         // pipeline resolves its own working provider/model).
-        if (answer.generationFailed && dispatchDecision.dispatch && !dispatchDecision.needConfirm) {
+        // WS5 (#27) — `!answer.refused` is not an optimisation, it is the guard: a
+        // turn that REFUSED to run (see `runChatAnswer`) is failed, but it is not
+        // UNANSWERED, and the no-model fallback exists for the second case. Re-
+        // dispatching it here would run the ask on another engine entirely — the one
+        // path that can run it UNISOLATED while the caller asked for isolation.
+        if (answer.generationFailed && !answer.refused && dispatchDecision.dispatch && !dispatchDecision.needConfirm) {
             const r = await runPipelineTool(message, this.configManager, { provider: type, model, board: false });
             // `success`, not `error`: a pipeline that RAN and failed reports its
             // outcome in `summary` and only sometimes sets `error`, so keying off
             // `error` alone returned a failed run's summary with NO failure flag —
             // i.e. reported it as a successful turn on every surface.
             if (!r.success) {
-                return { content: '', followups: [], generationFailed: true, provider: type, model };
+                return {
+                    content: '',
+                    followups: [],
+                    generationFailed: true,
+                    provider: type,
+                    model,
+                    transport: 'none',
+                    // WS5 — the isolation/resume this turn had, carried even on this path:
+                    // the worktree was made and measured before the fallback ran, and a
+                    // caller that never hears about it cannot tell an isolated turn from one
+                    // that ran in the real tree.
+                    ...this.turnEnvelopeOf(answer),
+                };
             }
-            return { content: r.result?.summary ?? '', followups: [], provider: type, model };
+            // A pipeline turn carries no tool transport at all — reported as `none`
+            // rather than left silent, so a caller can tell "no transport" apart from
+            // "this surface never said".
+            return {
+                content: r.result?.summary ?? '',
+                followups: [],
+                provider: type,
+                model,
+                transport: 'none',
+                ...this.turnEnvelopeOf(answer),
+            };
         }
         // E3b: strip raw suggest_followups JSON embedded in content by the model
         const cleanContent = stripToolCallArtifacts(answer.content || '');
@@ -475,8 +513,37 @@ export class ChatCommand extends BaseCommand {
             unverifiedActionClaim: answer.unverifiedActionClaim,
             unfulfilledPromise: answer.unfulfilledPromise,
             undeliveredArtifact: answer.undeliveredArtifact,
+            // WS1 — the findings this turn recorded (empty when it recorded none).
+            findings: answer.findings ?? [],
             provider: type,
             model,
+            // R2 — the transport the loop's model-call seam reported for this turn.
+            transport: answer.transport,
+            // WS5 — and the isolation/resume the turn had. The engine reports them on
+            // ITS result; this method builds a new object, so without this spread they
+            // were dropped at the boundary — measured as a surface that isolated its
+            // turn correctly and then told its caller nothing about it.
+            ...this.turnEnvelopeOf(answer),
+            // WS5 — and whether the turn refused to run at all, for the same reason:
+            // a caller that cannot tell a refusal from a failed generation retries it,
+            // and there is nothing to retry (see the refusal return in `runChatAnswer`).
+            ...(answer.refused ? { refused: true } : {}),
+        };
+    }
+    /**
+     * WS5 (#27) — the isolation/resume facts of a finished turn, in the shape this
+     * command's callers read.
+     *
+     * Extracted because THREE returns in `answerOnce` hand back a turn the engine
+     * produced (the final answer, and the two no-model pipeline fallbacks), and a
+     * fact that travelled on only one of them would be a capability that disappears
+     * exactly when the model was unavailable — which is a failure mode, not an edge
+     * case.
+     */
+    turnEnvelopeOf(answer) {
+        return {
+            ...(answer.worktree ? { worktree: answer.worktree } : {}),
+            ...(answer.resume ? { resume: answer.resume } : {}),
         };
     }
     create() {
@@ -488,11 +555,41 @@ export class ChatCommand extends BaseCommand {
             .option('-m, --model <model>', 'Model to use (if omitted, an interactive picker will appear)')
             .option('--no-cache', 'Disable response caching')
             .option('-d, --dev', 'Always dispatch requests to the coding pipeline (no confirmation)', false)
+            // WS5 (#27) — isolation and partial resume, as the two things an operator
+            // asks for by hand. Both default to OFF and both are also readable from the
+            // environment (`NUVIRA_ISOLATE` / `NUVIRA_RESUME`), which is how the
+            // surfaces with no command line ask.
+            // NO `false` DEFAULT on any of the three, and that is load-bearing: commander
+            // would then hand this command `worktree: false` for a flag the operator never
+            // typed, an explicit FALSE outranks the environment in
+            // `resolveIsolationRequest`, and `NUVIRA_ISOLATE=1` would be silently ignored
+            // on the one surface whose flags outrank it. Absent is `undefined` — "nobody
+            // said" — which is what lets the environment ask for these on the CLI too.
+            .option('--worktree', 'Run this turn in its own git worktree of the project and report the diff against the base commit. Refuses rather than running unisolated when the directory cannot be isolated (also asked for by NUVIRA_ISOLATE=1)')
+            .option('--keep-worktree', 'Keep the isolated worktree after the turn instead of removing it')
+            .option('--resume [id]', 'Replay the recorded steps of this ask whose input is unchanged instead of paying for them again (defaults to the record for this goal + directory; also asked for by NUVIRA_RESUME=1)')
             .action(async (prompt, options) => {
             await this.execute(prompt, options || {});
         });
         return command;
     }
+    /**
+     * WS5 (#27) — the isolation/resume request the CLI's own flags carry.
+     *
+     * One place, because three call sites in this command hand the request to the
+     * shared engine (the one-shot turn, its picked followups, and every REPL
+     * message) and a request that reached only some of them would be a flag that
+     * worked until the second message. `undefined` (no flag) is passed through as
+     * `undefined` rather than `false`, which is what lets the environment ask for
+     * isolation on a surface the CLI did not.
+     */
+    ws5Overrides(options) {
+        return {
+            worktree: options?.worktree,
+            keepWorktree: options?.keepWorktree,
+            resume: options?.resume,
+        };
+    }
     async execute(prompt, options) {
         // Apply the active model state from `nuvira model switch` as defaults
         const activeOpts = applyActiveModel({ provider: options?.provider, model: options?.model });
@@ -536,7 +633,7 @@ export class ChatCommand extends BaseCommand {
         const available = await provider.isAvailable();
         if (!available) {
             logger.error(`${provider.name} is not available. Check your configuration.`);
-            logger.info(`Run: agent-baba-d config --help`);
+            logger.info(`Run: agent-nuvira config --help`);
             return;
         }
         // ── Setup SIGINT (Ctrl+C) handler for graceful exit ──────────────
@@ -583,12 +680,17 @@ export class ChatCommand extends BaseCommand {
             // failed entirely), never as a bypass.
             const parsed = parseRequestSync(prompt);
             const dispatchDecision = resolvePipelineDispatch(parsed, { dev: options?.dev, text: prompt });
-            const answer = await this.runChatAnswer(prompt, [], { type, provider, model }, options || {}, cacheEnabled, { auto: autoMode }, parsed);
+            const answer = await this.runChatAnswer(prompt, [], { type, provider, model }, options || {}, cacheEnabled, { auto: autoMode }, parsed, 
+            // WS5 (#27) — isolation and resume ride on the CLI's own flags. Passed
+            // per turn: in the REPL each message is its own turn (see the manual).
+            this.ws5Overrides(options));
             // No-model fallback: the tool loop could not generate a single response
             // AND the rules assessed a high-confidence pipeline intent — run the
             // pipeline directly (rules decide only when the model is unavailable;
             // the pipeline resolves its own working provider/model).
-            if (answer.generationFailed && dispatchDecision.dispatch && !dispatchDecision.needConfirm) {
+            // WS5 — never on a REFUSED turn: the pipeline would run it in the real tree
+            // (see the guard in `answerOnce`).
+            if (answer.generationFailed && !answer.refused && dispatchDecision.dispatch && !dispatchDecision.needConfirm) {
                 await runDeveloperMode(prompt, this.configManager, { provider: type, model });
                 // After pipeline execution, show followups and continue conversation
                 // (don't just return — keep user engaged with next steps)
@@ -628,7 +730,7 @@ export class ChatCommand extends BaseCommand {
                     break;
                 const next = await this.runChatAnswer(picked, history, { type, provider, model }, options || {}, cacheEnabled, { auto: autoMode }, parseRequestSync(picked), 
                 // P5 — a picked followup continues the previous execution.
-                { continuation: true });
+                { continuation: true, ...this.ws5Overrides(options) });
                 const nextText = stripToolCallArtifacts(next.content);
                 if (nextText) {
                     console.log('\n' + nextText + '\n');
@@ -719,11 +821,15 @@ export class ChatCommand extends BaseCommand {
             const answer = await withLogCorrelation({ sessionId: chatSessionId }, () => recordMetricTime('llm.answer.ms', () => this.runChatAnswer(message, history, session, options || {}, cacheEnabled, { auto: autoMode }, parsed, 
             // P5 — a picked followup (or a typed one that matches the last
             // suggestions) is a continuation, not a fresh independent request.
-            { continuation: pickedFollowup || isSuggestedFollowup(message, lastFollowups) })));
+            {
+                continuation: pickedFollowup || isSuggestedFollowup(message, lastFollowups),
+                ...this.ws5Overrides(options),
+            })));
             // No-model fallback: the tool loop could not generate a single response
             // AND the rules assessed a high-confidence pipeline intent — run the
             // pipeline directly (rules decide only when the model is unavailable).
-            if (answer.generationFailed && dispatchDecision.dispatch && !dispatchDecision.needConfirm) {
+            // WS5 — never on a REFUSED turn, for the same reason as above.
+            if (answer.generationFailed && !answer.refused && dispatchDecision.dispatch && !dispatchDecision.needConfirm) {
                 await runDeveloperMode(message, this.configManager, { provider: type, model });
                 // After pipeline execution, continue conversation (don't just ask "press Enter")
                 // The user can keep chatting or type /exit
@@ -819,6 +925,24 @@ export class ChatCommand extends BaseCommand {
      * interactive mode turns a chosen followup into the next message).
      */
     async runChatAnswer(message, history, session, options, cacheEnabled, mode, parsed, ctxOverrides) {
+        // WS2 (#24) — the optional session debug log for this turn. Null unless
+        // `NUVIRA_DEBUG_LOG` is set, so the off path is one boolean check; when on,
+        // the events below are redacted and bounded, and the file is written at the
+        // END so its header can name the backend that actually served the turn.
+        const debugLog = sessionDebugLog({
+            surface: ctxOverrides?.debugSurface ?? 'cli-chat',
+            goal: message,
+            ...(ctxOverrides?.debugSession ? { session: ctxOverrides.debugSession } : {}),
+            backend: { engine: 'loop', provider: session.type, ...(session.model ? { model: session.model } : {}) },
+        });
+        debugLog?.event('turn.start', { provider: session.type });
+        // WS3 (#25) — the turn's span root, when span export is on (else null). Same
+        // identity as the log's: one surface, one conversation, one turn.
+        const otelSpan = await startTurnSpan({
+            surface: ctxOverrides?.debugSurface ?? 'cli-chat',
+            ...(ctxOverrides?.debugSession ? { session: ctxOverrides.debugSession } : {}),
+            goal: message,
+        });
         // Cache check first (same as the legacy path).
         const cache = getCache();
         const cacheModel = this.cacheModelFor(session);
@@ -833,6 +957,12 @@ export class ChatCommand extends BaseCommand {
                     history.push({ role: 'user', content: message });
                     history.push({ role: 'assistant', content: cachedResult });
                     this.memoryNoteTurn(message, cachedResult);
+                    // WS2 — a cache replay reached no model, so the log says exactly that
+                    // rather than borrowing an attribution from a turn that did not run.
+                    debugLog?.event('cache.hit', { chars: cachedResult.length });
+                    const cacheNotice = debugLogNotice(ctxOverrides?.debugSurface ?? 'cli-chat', debugLog?.write() ?? null);
+                    if (cacheNotice)
+                        logger.info(cacheNotice);
                     return { content: cachedResult };
                 }
             }
@@ -840,6 +970,107 @@ export class ChatCommand extends BaseCommand {
                 // Cache must never break the turn.
             }
         }
+        // ─── WS5 (#27) — ISOLATION AND RESUME, the whole turn's envelope ────────
+        //
+        // HERE, and not in each caller, because this is the seam every in-process
+        // surface already shares: the CLI's interactive REPL and one-shot answer, the
+        // dashboard console, the gateway's inbound chat and `execute`'s direct-answer
+        // arm all reach the tool loop through this method. A wrapper in each caller
+        // would be four copies of one policy, and the one that drifted would be the
+        // surface that quietly ran in the real tree.
+        //
+        // It sits AFTER the response-cache check on purpose: a cached answer does no
+        // work, so there is nothing to isolate and no step to replay — paying for a
+        // git checkout to replay a cached string would be pure cost.
+        /**
+         * Where a WS5 notice goes: the surface's own progress channel when it has one
+         * (the dashboard renders it, the gateway logs it), else this process's log.
+         *
+         * Deliberately NOT `ctxOverrides.onProgress` directly: the CLI passes no
+         * progress sink for a one-shot turn, and a notice that reached nothing would
+         * hide exactly the facts it exists for — which directory the turn is isolated
+         * in, and what it changed.
+         */
+        const report = ctxOverrides?.onProgress ?? ((line) => void logger.info(line));
+        const projectDir = ctxOverrides?.projectPath || process.cwd();
+        const isolationRequest = resolveIsolationRequest({
+            worktree: ctxOverrides?.worktree,
+            keepWorktree: ctxOverrides?.keepWorktree,
+        });
+        const isolation = beginIsolation({ request: isolationRequest, repoCwd: projectDir, label: message });
+        if (isolation && !isolation.ok) {
+            // REFUSED, not degraded: the operator asked for isolation on purpose, and a
+            // turn that ran unisolated while its result said otherwise would be the one
+            // outcome this capability exists to prevent. Reported as a FAILED turn, so
+            // no surface presents it as an answer.
+            report(isolation.refusal);
+            return {
+                content: isolation.refusal,
+                followups: [],
+                // BOTH flags, and they say different things. `generationFailed` keeps the
+                // turn a FAILED one, so no surface renders the refusal as an answer.
+                // `refused` says WHY it failed — the turn never ran, no model was called —
+                // and that distinction is load-bearing: the caller's no-model fallback
+                // keys off `generationFailed` alone, so without this a refused turn was
+                // silently re-dispatched to the PIPELINE, which ran the ask in the real
+                // tree. Measured: `nuvira chat "write a file…" --worktree` outside a git
+                // repository printed a three-task pipeline board and never mentioned the
+                // refusal — the exact outcome isolation exists to prevent.
+                generationFailed: true,
+                refused: true,
+            };
+        }
+        const worktree = isolation?.ok ? isolation.worktree : null;
+        /**
+         * The directory this turn works in: the worktree when isolated, the attached
+         * project when one was given, else the process's own cwd.
+         *
+         * EVERY path that resolves a directory from here on reads this — the tools'
+         * `cwd`, the ambient project snapshot, the working-state ledger — because a
+         * turn that is isolated for its tools but reads its context from the original
+         * tree is not isolated, it is confused.
+         */
+        const turnCwd = worktree?.dir ?? projectDir;
+        // The ledger is only opened when a resume was asked for (a `--resume`, or the
+        // environment asking for every turn on this surface). An ordinary turn never
+        // touches the record store: no read, no write, no directory created.
+        const resumeRequest = resolveResumeRequest({ resume: ctxOverrides?.resume });
+        const resume = resumeRequest
+            ? openResume({ goal: message, cwd: turnCwd, resume: resumeRequest })
+            : null;
+        if (worktree)
+            report(worktreeNotice(worktree));
+        // WS5 — what the RECORD holds, said before the turn. The outcome (what was
+        // replayed, what it cost) is reported in `finish` below, where it is knowable —
+        // this line used to state the outcome here, which meant every resumed turn
+        // announced "nothing to replay" before it had tried anything.
+        if (resume)
+            report(resume.ledger.openNotice());
+        /**
+         * Attach this turn's isolation and resume outcomes to whatever it returns.
+         *
+         * A helper at every return rather than a `finally`, because the outcomes have
+         * to ride ON the result a caller is waiting for: a diff reported later (or by
+         * a separate command) is a diff most callers never see, and `endIsolation`
+         * never throws, so a cleanup failure cannot replace the turn's own answer
+         * with a git error.
+         */
+        const finish = (result) => {
+            const extra = {};
+            if (worktree) {
+                const outcome = endIsolation(worktree, { keep: isolationRequest.keep });
+                extra.worktree = outcome;
+                report(outcome.notice);
+            }
+            if (resume) {
+                const outcome = closeResume(resume, { goal: message, cwd: turnCwd });
+                extra.resume = outcome;
+                // The wording lives in `ResumeOutcome.notice` — one sentence, every
+                // surface, including the reason when nothing replayed.
+                report(outcome.notice);
+            }
+            return { ...result, ...extra };
+        };
         history.push({ role: 'user', content: message });
         // System prompt: base identity + the tool contract — the
         // model clarifies with ask_user and ends every response with followups.
@@ -895,7 +1126,7 @@ export class ChatCommand extends BaseCommand {
         let ambientProjectContext;
         if (!ctxOverrides?.projectContext) {
             try {
-                const built = await buildLoopProjectContext(ctxOverrides?.projectPath || process.cwd());
+                const built = await buildLoopProjectContext(turnCwd);
                 if (built)
                     ambientProjectContext = built;
             }
@@ -908,7 +1139,7 @@ export class ChatCommand extends BaseCommand {
         // what previous turns already established. This is the fix for the
         // calculator session's core drift (it re-diagnosed the same root cause six
         // times, then undid its own earlier fixes).
-        const workingStatePath = ctxOverrides?.projectPath || process.cwd();
+        const workingStatePath = turnCwd;
         const workingStateBlock = formatWorkingState(getWorkingState(workingStatePath));
         // Session 3 — channel/format policy lives in the STABLE layer. It is
         // identical on every message, so keeping it here makes the system prompt
@@ -961,6 +1192,15 @@ export class ChatCommand extends BaseCommand {
         // G3 — the files this turn mutates, observed on the tool event stream so
         // the ledger can remember them (the loop reports tool NAMES, not paths).
         const touchedFiles = new Set();
+        /**
+         * WS1 — the findings this turn RECORDED, in call order.
+         *
+         * Collected from the same `finding:recorded` event the GUI hears, so the
+         * result the caller returns and the live card a user watches are fed by one
+         * source rather than two that can disagree. Empty is a real answer ("this
+         * surface reports findings, and this turn recorded none"), never silence.
+         */
+        const findings = [];
         /**
          * G18 — the turn's trace id, for the autonomy-gate events that tools emit
          * DURING the loop. Assigned a few lines below (the trace begins once the
@@ -973,7 +1213,7 @@ export class ChatCommand extends BaseCommand {
             loadedExtraTools,
             // P4 — when a project is attached, scope tools to its root so the
             // agent operates inside the project (not the dashboard server's cwd).
-            cwd: ctxOverrides?.projectPath || process.cwd(),
+            cwd: turnCwd,
             emit: (event, data, source) => {
                 // G3 — collect mutated file paths from `tool:started` (which carries
                 // the arguments) so the working-state ledger knows what changed.
@@ -991,6 +1231,19 @@ export class ChatCommand extends BaseCommand {
                 if (ctxOverrides?.onToolCall && (event === 'tool:started' || event === 'tool:called')) {
                     ctxOverrides.onToolCall(event === 'tool:started' ? 'started' : 'called', data);
                 }
+                // WS2 — the same lifecycle into the session debug log: a bug report
+                // needs the tool NAMES and their outcomes, in order. `write()` is never
+                // called here (the log is buffered and written once at turn end); this
+                // records, it does not persist per call.
+                if (debugLog && (event === 'tool:started' || event === 'tool:called')) {
+                    const call = data;
+                    if (call?.tool) {
+                        debugLog.event(event === 'tool:started' ? 'tool.start' : 'tool.end', {
+                            tool: call.tool,
+                            ...(call.ok === undefined ? {} : { ok: call.ok }),
+                        });
+                    }
+                }
                 // P0.7 — forward plan mutations to the GUI (structured checklist).
                 if (ctxOverrides?.onPlanChange && event === 'plan:changed') {
                     ctxOverrides.onPlanChange(data);
@@ -1004,6 +1257,23 @@ export class ChatCommand extends BaseCommand {
                 if (ctxOverrides?.onSkillDraft && event === 'skill:draft') {
                     ctxOverrides.onSkillDraft(data);
                 }
+                // WS1 — a finding the turn recorded. Kept on this surface's own result
+                // (so a caller that never sees the GUI still gets the verdict) AND
+                // forwarded to the caller's live view, one event, two readers.
+                if (event === FINDING_EVENT) {
+                    const finding = data;
+                    findings.push(finding);
+                    ctxOverrides?.onFinding?.(finding);
+                    // WS2 — a verdict is exactly the kind of fact a bug report is missing.
+                    debugLog?.event('finding', `${finding.verdict} ${finding.claim}`);
+                    // WS3 — and a span EVENT rather than a span: a finding has no
+                    // duration, so a point-in-time fact is the honest shape for it.
+                    otelSpan?.event('nuvira.finding', {
+                        'nuvira.verdict': finding.verdict,
+                        'nuvira.claim': finding.claim,
+                        'nuvira.outcome': finding.outcome,
+                    });
+                }
                 // G18 — an autonomy gate DECIDING to proceed is a fact about the turn
                 // ("this change was applied without asking, and here is why"), not just
                 // a bus notification: record it on the turn's trace so the decision is
@@ -1150,6 +1420,13 @@ export class ChatCommand extends BaseCommand {
                 // and is now additionally gated on the model having the context for it.
                 toolExposure: harness.exposure,
                 maxParallelReads: harness.maxParallelReads,
+                // WS3 — the turn span the loop hangs each tool call under.
+                otel: otelSpan,
+                // WS4 — the label a tool hook reports this call under.
+                surface: ctxOverrides?.debugSurface ?? 'cli-chat',
+                // WS5 — the resume ledger, when this turn was asked to resume. Omitted
+                // entirely otherwise, so an ordinary turn never consults it.
+                ...(resume ? { resume: resume.ledger } : {}),
                 onToken: ctxOverrides?.onToken,
                 signal: ctxOverrides?.signal,
                 // G18 — the same sink the execute loop uses: tool calls, gate decisions
@@ -1220,6 +1497,12 @@ export class ChatCommand extends BaseCommand {
             unverifiedEditClaim: result.unverifiedEditClaim,
             undeliveredArtifact: result.undeliveredArtifact,
         }));
+        // WS1 (#23) — persist the turn's findings (claim, outcome, evidence and the
+        // gate's verdict) on the trace, so the verdicts can be audited from the
+        // Trace tab after the run instead of only existing in this turn's return.
+        // Best-effort by construction; `endTrace` above cleared the in-progress id,
+        // so the trace id is passed explicitly.
+        recordTraceFindings(chatTraceId, findings);
         // G3 — record what this turn actually did so the NEXT turn starts from it
         // (files changed, whether anything verified the work, and whether the user
         // reported a regression). Best-effort: the ledger must never break a turn.
@@ -1301,7 +1584,50 @@ export class ChatCommand extends BaseCommand {
         // directly, so a model that wrote the tool JSON as text used to leak it
         // into the chat. The loop already salvages such blocks into real tool
         // calls; this is the belt-and-braces strip for any residue.
-        return {
+        // WS2 — close the session debug log. The header names the backend that
+        // ACTUALLY served the turn (`lastAttempt`, updated by the provider walk),
+        // not the pair this surface merely resolved before the turn started — those
+        // diverge exactly when failover happens, which is when a bug report needs
+        // the right answer. Best-effort: a log that cannot be written must never
+        // affect the answer.
+        if (debugLog) {
+            const servedModel = this.lastAttempt?.model ?? session.model;
+            debugLog.backendOf({
+                provider: this.lastAttempt?.provider ?? session.type,
+                ...(servedModel ? { model: servedModel } : {}),
+                transport: result.transport ?? null,
+            });
+            debugLog.event('turn.end', {
+                generationFailed: result.generationFailed === true,
+                cancelled: result.cancelled === true,
+                bounded: result.bounded === true,
+                contentChars: result.content.length,
+                toolCalls: result.toolCalls?.length ?? 0,
+                findings: findings.length,
+            });
+            const notice = debugLogNotice(ctxOverrides?.debugSurface ?? 'cli-chat', debugLog.write());
+            if (notice)
+                logger.info(notice);
+        }
+        // WS3 (#25) — close the turn span and ship it. The status is the turn's own
+        // outcome, so a failed turn is a RED span in the collector rather than an
+        // absent one — the same rule the debug log follows for a crash.
+        if (otelSpan) {
+            otelSpan.attr('nuvira.findings', findings.length);
+            otelSpan.end({
+                ok: result.generationFailed !== true && result.cancelled !== true,
+                ...(result.generationFailed === true
+                    ? { message: 'the turn did not produce a usable answer' }
+                    : result.cancelled === true
+                        ? { message: 'the turn was cancelled' }
+                        : {}),
+            });
+            const otelLine = otelNoticeOnce(ctxOverrides?.debugSurface ?? 'cli-chat');
+            if (otelLine)
+                logger.info(otelLine);
+            await flushSpans();
+        }
+        return finish({
             content: stripToolCallArtifacts(result.content),
             generationFailed: result.generationFailed,
             cancelled: result.cancelled,
@@ -1311,7 +1637,11 @@ export class ChatCommand extends BaseCommand {
             unverifiedActionClaim: result.unverifiedActionClaim,
             unfulfilledPromise: result.unfulfilledPromise,
             undeliveredArtifact: result.undeliveredArtifact,
-        };
+            // R2 — the transport this turn travelled on (interactive REPL path).
+            transport: result.transport,
+            // WS1 — the findings this turn recorded, with their verdicts.
+            findings,
+        });
     }
     /**
      * E3b — the model-call step for the tool loop:
@@ -1473,13 +1803,13 @@ export class ChatCommand extends BaseCommand {
                         if (sink && typeof prov.generateToolsStream === 'function') {
                             const result = await prov.generateToolsStream(messages, schemas, { ...options, model: effectiveModel, signal: abort }, sink);
                             confuseCheck(result.content, result.toolCalls.length > 0);
-                            return answered(result);
+                            return answered({ ...result, transport: 'native' });
                         }
                         const result = await prov.generateTools(messages, schemas, { ...options, model: effectiveModel, signal: abort });
                         confuseCheck(result.content, result.toolCalls.length > 0);
                         if (sink && result.content)
                             sink(result.content);
-                        return answered(result);
+                        return answered({ ...result, transport: 'native' });
                     }
                     catch (err) {
                         // S3: a tool-call 400 often carries the model's COMPLETE answer in
@@ -1498,7 +1828,9 @@ export class ChatCommand extends BaseCommand {
                             const toolCalls = salvaged.followups?.length
                                 ? [{ id: 'call_salvage_1', name: 'suggest_followups', arguments: { followups: salvaged.followups } }]
                                 : [];
-                            return answered({ content: salvaged.content, toolCalls });
+                            // R2 — the answer was excavated from a NATIVE tool-call attempt's
+                            // 400 payload, so it is still the native transport's output.
+                            return answered({ content: salvaged.content, toolCalls, transport: 'native' });
                         }
                         // The MODEL itself cannot do native tool calling — Groq answers
                         // 400 "`tool calling` is not supported with this model". That is
@@ -1532,7 +1864,9 @@ export class ChatCommand extends BaseCommand {
                 }
                 const { text, calls } = extractFallbackToolCalls(raw);
                 confuseCheck(text, calls.length > 0);
-                return answered({ content: text, toolCalls: calls });
+                // R2 — this IS the fallback transport, so say so: the same fact the
+                // subagent child announces, and what makes a chat turn comparable with it.
+                return answered({ content: text, toolCalls: calls, transport: 'json' });
             };
             try {
                 // Same-provider transient retry FIRST (see the helper's contract): a