mixdog 0.9.125 → 0.9.126

package/README.md

@@ -163,8 +163,16 @@ host behavioral config and personal state out of the run:
 ```bash
 mixdog exec --provider anthropic-oauth --model claude-opus-5 "fix the failing test"
 mixdog exec --provider openai-oauth --model gpt-5.6-sol --effort xhigh --fast "review the current diff"
+mixdog exec --provider openai-oauth --model gpt-5.6-sol --json "fix the failing test"
 ```
 
+`--json` emits timestamped JSONL. The stream contains thread/turn lifecycle,
+provider request timing, reasoning and assistant messages, tool start/completion
+with arguments/output and queue/dispatch/execution/batch-wait/postprocess timing,
+background notifications, final usage, and a
+terminal success/error result. Without `--json`, stdout remains final text only.
+In JSON mode stdout is JSONL-only; runtime diagnostics remain on stderr.
+
 ## TUI basics
 
 Common slash commands:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.125",
+  "version": "0.9.126",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",

package/src/app.mjs

@@ -86,6 +86,7 @@ export async function run(argv = [], classifiedInvocation = null) {
       model: opts.model,
       effort: opts.effort,
       fast: opts.fast,
+      json: opts.json,
       cwd: process.cwd(),
     });
   }

package/src/headless-command.mjs

@@ -1,7 +1,7 @@
 const VALUE_OPTIONS = new Set(['--provider', '--model', '--effort', '--workflow']);
 const FLAG_OPTIONS = new Set([
   '--readonly', '--help', '-h', '--plain', '--react', '--remote', '--onboarding', '--fast',
-  '--web-search', '--memory',
+  '--web-search', '--memory', '--json',
 ]);
 const EXEC_UNSUPPORTED_FLAGS = new Set([
   '--readonly', '--remote', '--onboarding', '--web-search', '--memory',
@@ -101,6 +101,7 @@ export function classifyCliInvocation(argv = []) {
     fast: argv.includes('--fast'),
     webSearch: argv.includes('--web-search'),
     memory: argv.includes('--memory'),
+    json: argv.includes('--json'),
     toolMode: argv.includes('--readonly') ? 'readonly' : 'full',
     remote: argv.includes('--remote'),
     forceOnboarding: argv.includes('--onboarding'),
@@ -130,6 +131,13 @@ export function classifyCliInvocation(argv = []) {
     }
     return { kind: 'exec', exec, options, skipHostPrelude: true };
   }
+  if (argv.includes('--json')) {
+    return {
+      kind: 'error',
+      error: 'option --json is only supported for mixdog exec',
+      skipHostPrelude: true,
+    };
+  }
   return { kind: 'general', options };
 }
 

package/src/headless-exec.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import {
   mkdirSync,
   renameSync,
@@ -22,6 +23,472 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function nonNegativeNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.max(0, number) : 0;
+}
+
+function jsonValue(value) {
+  if (value === undefined) return null;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return String(value);
+  }
+}
+
+function toolCallName(call) {
+  return clean(
+    call?.name
+    ?? call?.toolName
+    ?? call?.function?.name
+    ?? call?.tool?.name,
+  ) || 'tool';
+}
+
+function toolCallArguments(call) {
+  const raw = call?.arguments
+    ?? call?.input
+    ?? call?.function?.arguments
+    ?? call?.tool?.arguments
+    ?? call?.args
+    ?? {};
+  if (typeof raw !== 'string') return jsonValue(raw);
+  const text = raw.trim();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { input: raw };
+  }
+}
+
+function usageSummary(stats, toolCallCount = 0) {
+  return {
+    input_tokens: nonNegativeNumber(stats.inputTokens),
+    cached_input_tokens: nonNegativeNumber(stats.cachedTokens),
+    cache_write_input_tokens: nonNegativeNumber(stats.cacheWriteTokens),
+    output_tokens: nonNegativeNumber(stats.outputTokens),
+    tool_calls: nonNegativeNumber(toolCallCount),
+  };
+}
+
+function usageDeltaSummary(delta = {}) {
+  return {
+    input_tokens: nonNegativeNumber(delta.deltaInput),
+    cached_input_tokens: nonNegativeNumber(delta.deltaCachedRead),
+    cache_write_input_tokens: nonNegativeNumber(delta.deltaCacheWrite),
+    output_tokens: nonNegativeNumber(delta.deltaOutput),
+  };
+}
+
+function createJsonLifecycle({
+  write,
+  stats,
+  provider,
+  model,
+  effort,
+  fast,
+  cwd,
+}) {
+  let threadId = `exec_${randomUUID().replace(/-/g, '')}`;
+  const turnId = 'turn_1';
+  let resolvedProvider = clean(provider);
+  let resolvedModel = clean(model);
+  let resolvedEffort = clean(effort) || null;
+  let resolvedFast = fast === true;
+  let resolvedCwd = clean(cwd);
+  let started = false;
+  let turnStartedAt = 0;
+  let itemSequence = 0;
+  let toolCallCount = 0;
+  let providerRequestCount = 0;
+  let providerDurationMs = 0;
+  let activeProviderRequest = null;
+  let activeToolBatch = null;
+  let reasoningText = '';
+  let lastAssistantText = '';
+  const pendingTools = new Map();
+  const completedTools = new Set();
+
+  const nowIso = (value = Date.now()) => new Date(value).toISOString();
+  const emit = (event, at = Date.now()) => {
+    write(`${JSON.stringify({
+      schema_version: 1,
+      timestamp: nowIso(at),
+      ...event,
+    })}\n`);
+  };
+  const nextItemId = (prefix = 'item') => `${prefix}_${++itemSequence}`;
+
+  function start(runtime = null) {
+    if (started) return;
+    threadId = clean(runtime?.id) || threadId;
+    resolvedProvider = clean(runtime?.provider) || resolvedProvider;
+    resolvedModel = clean(runtime?.model) || resolvedModel;
+    resolvedEffort = clean(runtime?.effort) || resolvedEffort;
+    resolvedFast = runtime?.fast === true || resolvedFast;
+    resolvedCwd = clean(runtime?.cwd) || resolvedCwd;
+    turnStartedAt = Date.now();
+    started = true;
+    emit({
+      type: 'thread.started',
+      thread_id: threadId,
+      session: {
+        provider: resolvedProvider,
+        model: resolvedModel,
+        effort: resolvedEffort,
+        fast: resolvedFast,
+        cwd: resolvedCwd,
+        tool_mode: 'full',
+        approval_mode: 'implicit',
+        delegation: false,
+      },
+    }, turnStartedAt);
+    emit({
+      type: 'turn.started',
+      thread_id: threadId,
+      turn_id: turnId,
+    }, turnStartedAt);
+  }
+
+  function completeProviderRequest(status, delta = null, at = Date.now()) {
+    if (!activeProviderRequest) return;
+    const request = activeProviderRequest;
+    activeProviderRequest = null;
+    const durationMs = Math.max(0, at - request.startedAt);
+    providerDurationMs += durationMs;
+    emit({
+      type: `model.request.${status}`,
+      thread_id: threadId,
+      turn_id: turnId,
+      request_id: request.id,
+      request_index: request.index,
+      duration_ms: durationMs,
+      ...(delta ? { usage: usageDeltaSummary(delta) } : {}),
+    }, at);
+  }
+
+  function flushReasoning(at = Date.now()) {
+    const text = reasoningText;
+    reasoningText = '';
+    if (!text.trim()) return;
+    emit({
+      type: 'item.completed',
+      thread_id: threadId,
+      turn_id: turnId,
+      item: {
+        id: nextItemId('reasoning'),
+        type: 'reasoning',
+        text,
+        status: 'completed',
+      },
+    }, at);
+  }
+
+  function emitAssistant(text, at = Date.now()) {
+    const value = String(text ?? '');
+    if (!value.trim()) return;
+    flushReasoning(at);
+    lastAssistantText = value;
+    emit({
+      type: 'item.completed',
+      thread_id: threadId,
+      turn_id: turnId,
+      item: {
+        id: nextItemId('message'),
+        type: 'agent_message',
+        text: value,
+        status: 'completed',
+      },
+    }, at);
+  }
+
+  function startTool(call, at = Date.now()) {
+    const callId = clean(call?.id) || nextItemId('tool');
+    if (pendingTools.has(callId) || completedTools.has(callId)) return;
+    const entry = {
+      id: callId,
+      name: toolCallName(call),
+      arguments: toolCallArguments(call),
+      startedAt: at,
+      startedAtIso: nowIso(at),
+    };
+    pendingTools.set(callId, entry);
+    toolCallCount += 1;
+    emit({
+      type: 'item.started',
+      thread_id: threadId,
+      turn_id: turnId,
+      item: {
+        id: entry.id,
+        type: 'tool_call',
+        name: entry.name,
+        arguments: entry.arguments,
+        status: 'in_progress',
+        started_at: entry.startedAtIso,
+      },
+    }, at);
+  }
+
+  function completeTool(message, at = Date.now()) {
+    const callId = clean(message?.toolCallId);
+    if (!callId || completedTools.has(callId)) return;
+    let entry = pendingTools.get(callId);
+    if (!entry) {
+      startTool({ id: callId, name: message?.toolName || 'tool', arguments: {} }, at);
+      entry = pendingTools.get(callId);
+    }
+    if (!entry) return;
+    if (message?.__earlyNotify === true) {
+      entry.earlyCompletedAt = at;
+      entry.earlyTiming = message?.toolTiming || null;
+      return;
+    }
+    pendingTools.delete(callId);
+    completedTools.add(callId);
+    const failed = message?.isError === true || message?.toolKind === 'error';
+    const skipped = message?.toolKind === 'skipped';
+    const rawTiming = message?.toolTiming || entry.earlyTiming || {};
+    const dispatchStartedAt = nonNegativeNumber(rawTiming.dispatchStartedAt || entry.startedAt);
+    const executionStartedAt = nonNegativeNumber(
+      rawTiming.executionStartedAt || dispatchStartedAt,
+    );
+    const executionCompletedAt = nonNegativeNumber(
+      rawTiming.executionCompletedAt || entry.earlyCompletedAt || at,
+    );
+    const postprocessStartedAt = nonNegativeNumber(
+      rawTiming.postprocessStartedAt || executionCompletedAt,
+    );
+    const resultCompletedAt = nonNegativeNumber(rawTiming.resultCompletedAt || at);
+    const timing = {
+      queue_ms: Math.max(0, dispatchStartedAt - entry.startedAt),
+      dispatch_ms: Math.max(0, executionStartedAt - dispatchStartedAt),
+      execution_ms: Math.max(0, executionCompletedAt - executionStartedAt),
+      batch_wait_ms: Math.max(0, postprocessStartedAt - executionCompletedAt),
+      postprocess_ms: Math.max(0, resultCompletedAt - postprocessStartedAt),
+      total_ms: Math.max(0, resultCompletedAt - entry.startedAt),
+    };
+    emit({
+      type: 'item.completed',
+      thread_id: threadId,
+      turn_id: turnId,
+      item: {
+        id: entry.id,
+        type: 'tool_call',
+        name: entry.name,
+        arguments: entry.arguments,
+        output: jsonValue(message?.content),
+        status: failed ? 'failed' : (skipped ? 'skipped' : 'completed'),
+        started_at: entry.startedAtIso,
+        completed_at: nowIso(at),
+        duration_ms: timing.total_ms,
+        timing,
+      },
+    }, at);
+  }
+
+  function closePendingTools(status, output, at = Date.now()) {
+    for (const entry of pendingTools.values()) {
+      completedTools.add(entry.id);
+      emit({
+        type: 'item.completed',
+        thread_id: threadId,
+        turn_id: turnId,
+        item: {
+          id: entry.id,
+          type: 'tool_call',
+          name: entry.name,
+          arguments: entry.arguments,
+          output,
+          status,
+          started_at: entry.startedAtIso,
+          completed_at: nowIso(at),
+          duration_ms: Math.max(0, at - entry.startedAt),
+        },
+      }, at);
+    }
+    pendingTools.clear();
+  }
+
+  return {
+    get threadId() {
+      return threadId;
+    },
+    get toolCallCount() {
+      return toolCallCount;
+    },
+    start,
+    onProviderSendStarted() {
+      start();
+      if (activeProviderRequest) completeProviderRequest('failed');
+      const startedAt = Date.now();
+      providerRequestCount += 1;
+      activeProviderRequest = {
+        id: `model_request_${providerRequestCount}`,
+        index: providerRequestCount,
+        startedAt,
+      };
+      emit({
+        type: 'model.request.started',
+        thread_id: threadId,
+        turn_id: turnId,
+        request_id: activeProviderRequest.id,
+        request_index: activeProviderRequest.index,
+      }, startedAt);
+    },
+    onUsageDelta(delta) {
+      completeProviderRequest('completed', delta);
+    },
+    onReasoningDelta(chunk) {
+      reasoningText += String(chunk ?? '');
+    },
+    onAssistantText(text) {
+      emitAssistant(text);
+    },
+    onAssistantToolCallObserved(call) {
+      start();
+      flushReasoning();
+      startTool(call);
+    },
+    onToolCall(_iteration, calls) {
+      start();
+      flushReasoning();
+      for (const call of calls || []) startTool(call);
+    },
+    onToolResult(message) {
+      completeTool(message);
+    },
+    onToolBatchStarted() {
+      const startedAt = Date.now();
+      activeToolBatch = {
+        id: `tool_batch_${providerRequestCount || 1}`,
+        startedAt,
+      };
+      emit({
+        type: 'tool.batch.started',
+        thread_id: threadId,
+        turn_id: turnId,
+        batch_id: activeToolBatch.id,
+      }, startedAt);
+    },
+    onToolBatchCompleted(detail = {}) {
+      const completedAt = Date.now();
+      const batch = activeToolBatch || {
+        id: `tool_batch_${providerRequestCount || 1}`,
+        startedAt: completedAt,
+      };
+      activeToolBatch = null;
+      emit({
+        type: 'tool.batch.completed',
+        thread_id: threadId,
+        turn_id: turnId,
+        batch_id: batch.id,
+        iteration: nonNegativeNumber(detail.iteration),
+        calls: nonNegativeNumber(detail.calls),
+        duration_ms: nonNegativeNumber(
+          detail.elapsedMs ?? (completedAt - batch.startedAt),
+        ),
+      }, completedAt);
+    },
+    onStageChange(stage, detail = null) {
+      emit({
+        type: 'turn.status',
+        thread_id: threadId,
+        turn_id: turnId,
+        stage: clean(stage) || 'unknown',
+        ...(detail == null ? {} : { detail: jsonValue(detail) }),
+      });
+    },
+    onNotification(event = {}) {
+      emit({
+        type: 'notification',
+        thread_id: threadId,
+        turn_id: turnId,
+        content: String(event?.content ?? ''),
+        meta: jsonValue(event?.meta ?? {}),
+      });
+      return false;
+    },
+    succeed(text, result = null) {
+      start();
+      const completedAt = Date.now();
+      flushReasoning(completedAt);
+      completeProviderRequest('completed', null, completedAt);
+      closePendingTools('incomplete', null, completedAt);
+      const finalText = String(text ?? '');
+      if (finalText.trim() && finalText !== lastAssistantText) {
+        emitAssistant(finalText, completedAt);
+      }
+      const durationMs = Math.max(0, completedAt - turnStartedAt);
+      const usage = usageSummary(stats, toolCallCount);
+      emit({
+        type: 'turn.completed',
+        thread_id: threadId,
+        turn_id: turnId,
+        duration_ms: durationMs,
+        duration_api_ms: providerDurationMs,
+        provider_requests: providerRequestCount,
+        tool_calls: toolCallCount,
+        usage,
+      }, completedAt);
+      emit({
+        type: 'result',
+        subtype: 'success',
+        thread_id: threadId,
+        turn_id: turnId,
+        session_id: threadId,
+        model: resolvedModel,
+        is_error: false,
+        duration_ms: durationMs,
+        duration_api_ms: providerDurationMs,
+        num_turns: 1,
+        provider_requests: providerRequestCount,
+        tool_calls: toolCallCount,
+        result: finalText,
+        stop_reason: result?.stopReason ?? result?.stop_reason ?? null,
+        usage,
+      }, completedAt);
+    },
+    fail(error) {
+      start();
+      const completedAt = Date.now();
+      const message = error?.message || String(error || 'execution failed');
+      flushReasoning(completedAt);
+      completeProviderRequest('failed', null, completedAt);
+      closePendingTools('failed', message, completedAt);
+      const durationMs = Math.max(0, completedAt - turnStartedAt);
+      const usage = usageSummary(stats, toolCallCount);
+      emit({
+        type: 'turn.failed',
+        thread_id: threadId,
+        turn_id: turnId,
+        duration_ms: durationMs,
+        duration_api_ms: providerDurationMs,
+        error: { message },
+        usage,
+      }, completedAt);
+      emit({
+        type: 'result',
+        subtype: 'error_during_execution',
+        thread_id: threadId,
+        turn_id: turnId,
+        session_id: threadId,
+        model: resolvedModel,
+        is_error: true,
+        duration_ms: durationMs,
+        duration_api_ms: providerDurationMs,
+        num_turns: 1,
+        provider_requests: providerRequestCount,
+        tool_calls: toolCallCount,
+        stop_reason: null,
+        errors: [message],
+        usage,
+      }, completedAt);
+    },
+  };
+}
+
 export async function waitForTrackedTasks({
   sessionId,
   clientHostPid = process.pid,
@@ -37,7 +504,7 @@ export async function waitForTrackedTasks({
   }
 }
 
-function writeUsageDocument(path, stats, runtime) {
+function writeUsageDocument(path, stats, runtime, toolCallCount = 0) {
   const target = clean(path);
   if (!target) return;
   const session = {
@@ -48,7 +515,7 @@ function writeUsageDocument(path, stats, runtime) {
     cacheTokens: stats.cachedTokens,
     cacheWriteTokens: stats.cacheWriteTokens,
     outputTokens: stats.outputTokens,
-    toolCallCountApprox: 0,
+    toolCallCountApprox: nonNegativeNumber(toolCallCount),
   };
   const document = {
     schemaVersion: 1,
@@ -58,7 +525,7 @@ function writeUsageDocument(path, stats, runtime) {
       cacheTokens: stats.cachedTokens,
       cacheWriteTokens: stats.cacheWriteTokens,
       outputTokens: stats.outputTokens,
-      toolCallCountApprox: 0,
+      toolCallCountApprox: nonNegativeNumber(toolCallCount),
     },
   };
   const temp = `${target}.tmp-${process.pid}`;
@@ -73,6 +540,7 @@ export async function runHeadlessExec({
   model,
   effort,
   fast,
+  json = false,
   cwd = process.cwd(),
   write = (text) => stdout.write(text),
   writeErr = (text) => stderr.write(text),
@@ -95,10 +563,23 @@ export async function runHeadlessExec({
   }
 
   const stats = createSessionStats();
+  const lifecycle = json ? createJsonLifecycle({
+    write,
+    stats,
+    provider,
+    model,
+    effort,
+    fast,
+    cwd,
+  }) : null;
   let boundary = null;
   let runtime = null;
   let signalCleanup = null;
+  let unsubscribeNotification = null;
   let cleanupPromise = null;
+  let result = null;
+  let resultText = '';
+  let executionError = null;
   let code = 1;
   const cleanup = (reason = 'exec-exit') => {
     cleanupPromise ??= (async () => {
@@ -130,35 +611,76 @@ export async function runHeadlessExec({
       disallowDelegation: true,
       initialConfig: boundary.loadConfig(),
     });
-    const { result } = await runtime.ask(prompt, {
+    if (lifecycle && !clean(runtime?.id) && typeof runtime?.reserveSessionId === 'function') {
+      runtime.reserveSessionId(lifecycle.threadId);
+    }
+    lifecycle?.start(runtime);
+    if (lifecycle && typeof runtime?.onNotification === 'function') {
+      unsubscribeNotification = runtime.onNotification(
+        (event) => lifecycle.onNotification(event),
+      );
+    }
+    ({ result } = await runtime.ask(prompt, {
       onTextReset: () => true,
-      onUsageDelta: (delta) => applyUsageDelta(stats, delta),
-    });
+      onUsageDelta: (delta) => {
+        applyUsageDelta(stats, delta);
+        lifecycle?.onUsageDelta(delta);
+      },
+      ...(lifecycle ? {
+        onProviderSendStarted: () => lifecycle.onProviderSendStarted(),
+        onReasoningDelta: (chunk) => lifecycle.onReasoningDelta(chunk),
+        onAssistantText: (text) => lifecycle.onAssistantText(text),
+        onAssistantToolCallObserved: (call) => lifecycle.onAssistantToolCallObserved(call),
+        onToolCall: (iteration, calls) => lifecycle.onToolCall(iteration, calls),
+        onToolResult: (message) => lifecycle.onToolResult(message),
+        onToolPhaseStarted: () => lifecycle.onToolBatchStarted(),
+        onToolPhaseCompleted: (detail) => lifecycle.onToolBatchCompleted(detail),
+        onStageChange: (stage, detail) => lifecycle.onStageChange(stage, detail),
+      } : {}),
+    }));
     await waitForTrackedTasks({
       sessionId: runtime.id,
       clientHostPid: runtime.clientHostPid,
       hasActiveTasks,
       pollMs: idlePollMs,
     });
-    const text = String(result?.content ?? result?.text ?? '');
-    if (text) write(text.endsWith('\n') ? text : `${text}\n`);
+    resultText = String(result?.content ?? result?.text ?? '');
+    if (!json && resultText) {
+      write(resultText.endsWith('\n') ? resultText : `${resultText}\n`);
+    }
     code = 0;
   } catch (error) {
+    executionError = error;
     writeErr(`mixdog: ${error?.message || error}\n`);
   } finally {
     try {
-      writeUsageDocument(usageLogPath, stats, runtime);
+      unsubscribeNotification?.();
+    } catch {
+      // Listener cleanup is best-effort.
+    }
+    try {
+      writeUsageDocument(
+        usageLogPath,
+        stats,
+        runtime,
+        lifecycle?.toolCallCount || 0,
+      );
     } catch (error) {
       writeErr(`mixdog: usage log write failed: ${error?.message || error}\n`);
     }
     try {
       await cleanup('exec-exit');
     } catch (error) {
+      executionError ??= error;
       writeErr(`mixdog: shutdown failed: ${error?.message || error}\n`);
       code = 1;
     } finally {
       signalCleanup?.uninstall();
     }
   }
+  if (lifecycle) {
+    if (code === 0) lifecycle.succeed(resultText, result);
+    else lifecycle.fail(executionError || new Error('execution failed'));
+  }
   return code;
 }

package/src/headless-exec.test.mjs

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
 
+import { classifyCliInvocation } from './headless-command.mjs';
 import { runHeadlessExec } from './headless-exec.mjs';
 
 test('headless exec runs one implicit-approval session and waits for tracked tasks', async () => {
@@ -81,3 +82,196 @@ test('headless exec runs one implicit-approval session and waits for tracked tas
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+test('headless exec emits a timestamped JSONL lifecycle and exact tool count', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'mixdog-headless-json-test-'));
+  const usageLogPath = join(root, 'usage.json');
+  const output = [];
+  const errors = [];
+  let notificationListener = null;
+  try {
+    const code = await runHeadlessExec({
+      message: 'fix it',
+      provider: 'openai-oauth',
+      model: 'gpt-test',
+      effort: 'high',
+      fast: true,
+      json: true,
+      usageLogPath,
+      write: (text) => output.push(text),
+      writeErr: (text) => errors.push(text),
+      boundaryFactory: () => ({
+        loadConfig: () => ({ providers: { 'openai-oauth': { enabled: true } } }),
+        cleanup() {},
+      }),
+      runtimeFactory: async () => ({
+        id: 'sess_json_test',
+        provider: 'openai-oauth',
+        model: 'gpt-test',
+        effort: 'high',
+        fast: true,
+        cwd: '/app',
+        clientHostPid: 123,
+        onNotification(listener) {
+          notificationListener = listener;
+          return () => { notificationListener = null; };
+        },
+        async ask(_prompt, options) {
+          options.onProviderSendStarted();
+          options.onReasoningDelta('inspect first');
+          options.onUsageDelta({
+            deltaInput: 11,
+            deltaCachedRead: 7,
+            deltaCacheWrite: 3,
+            deltaOutput: 5,
+          });
+          const call = {
+            id: 'call_1',
+            name: 'shell',
+            arguments: { command: 'echo ok' },
+          };
+          options.onAssistantToolCallObserved(call);
+          await options.onToolCall(1, [call]);
+          options.onToolPhaseStarted();
+          const toolClock = Date.now();
+          options.onToolResult({
+            role: 'tool',
+            toolCallId: 'call_1',
+            content: 'ok\n',
+            __earlyNotify: true,
+            toolTiming: {
+              dispatchStartedAt: toolClock,
+              executionStartedAt: toolClock + 2,
+              executionCompletedAt: toolClock + 5,
+            },
+          });
+          options.onToolResult({
+            role: 'tool',
+            toolCallId: 'call_1',
+            content: 'ok\n',
+            toolKind: 'normal',
+            toolTiming: {
+              dispatchStartedAt: toolClock,
+              executionStartedAt: toolClock + 2,
+              executionCompletedAt: toolClock + 5,
+              postprocessStartedAt: toolClock + 6,
+              resultCompletedAt: toolClock + 8,
+            },
+          });
+          options.onToolPhaseCompleted({ iteration: 1, calls: 1, elapsedMs: 2 });
+          notificationListener?.({
+            content: 'background task completed',
+            meta: { status: 'completed' },
+          });
+          options.onProviderSendStarted();
+          options.onAssistantText('done');
+          options.onUsageDelta({
+            deltaInput: 5,
+            deltaCachedRead: 0,
+            deltaCacheWrite: 0,
+            deltaOutput: 2,
+          });
+          return { result: { content: 'done', stopReason: 'end_turn' } };
+        },
+        async close() {},
+      }),
+      hasActiveTasks: () => false,
+      installSignalCleanupFn: () => ({ uninstall() {} }),
+    });
+
+    assert.equal(code, 0);
+    assert.deepEqual(errors, []);
+    const events = output.join('').trim().split('\n').map((line) => JSON.parse(line));
+    assert.equal(events[0].type, 'thread.started');
+    assert.equal(events[1].type, 'turn.started');
+    assert.ok(events.every((event) => event.schema_version === 1 && event.timestamp));
+    const toolStarted = events.find(
+      (event) => event.type === 'item.started' && event.item?.type === 'tool_call',
+    );
+    const toolCompleted = events.find(
+      (event) => event.type === 'item.completed' && event.item?.id === 'call_1',
+    );
+    assert.equal(toolStarted.item.name, 'shell');
+    assert.equal(toolCompleted.item.output, 'ok\n');
+    assert.equal(toolCompleted.item.status, 'completed');
+    assert.ok(toolCompleted.item.duration_ms >= 0);
+    assert.equal(toolCompleted.item.timing.dispatch_ms, 2);
+    assert.equal(toolCompleted.item.timing.execution_ms, 3);
+    assert.equal(toolCompleted.item.timing.batch_wait_ms, 1);
+    assert.equal(toolCompleted.item.timing.postprocess_ms, 2);
+    assert.equal(events.filter(
+      (event) => event.type === 'item.completed' && event.item?.id === 'call_1',
+    ).length, 1);
+    assert.ok(events.some((event) => event.type === 'notification'));
+    assert.equal(events.filter((event) => event.type === 'model.request.completed').length, 2);
+    const terminal = events.at(-1);
+    assert.equal(terminal.type, 'result');
+    assert.equal(terminal.subtype, 'success');
+    assert.equal(terminal.session_id, 'sess_json_test');
+    assert.equal(terminal.provider_requests, 2);
+    assert.equal(terminal.tool_calls, 1);
+    assert.deepEqual(terminal.usage, {
+      input_tokens: 16,
+      cached_input_tokens: 7,
+      cache_write_input_tokens: 3,
+      output_tokens: 7,
+      tool_calls: 1,
+    });
+    const usage = JSON.parse(readFileSync(usageLogPath, 'utf8'));
+    assert.equal(usage.totals.toolCallCountApprox, 1);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('headless exec emits structured JSONL failure before returning exit 1', async () => {
+  const output = [];
+  const errors = [];
+  const code = await runHeadlessExec({
+    message: 'fail',
+    provider: 'openai-oauth',
+    model: 'gpt-test',
+    json: true,
+    usageLogPath: '',
+    write: (text) => output.push(text),
+    writeErr: (text) => errors.push(text),
+    boundaryFactory: () => ({
+      loadConfig: () => ({ providers: { 'openai-oauth': { enabled: true } } }),
+      cleanup() {},
+    }),
+    runtimeFactory: async () => ({
+      id: 'sess_json_failure',
+      model: 'gpt-test',
+      clientHostPid: 123,
+      async ask() {
+        throw new Error('boom');
+      },
+      async close() {},
+    }),
+    installSignalCleanupFn: () => ({ uninstall() {} }),
+  });
+
+  const events = output.join('').trim().split('\n').map((line) => JSON.parse(line));
+  assert.equal(code, 1);
+  assert.ok(events.some((event) => event.type === 'turn.failed'));
+  assert.equal(events.at(-1).type, 'result');
+  assert.equal(events.at(-1).subtype, 'error_during_execution');
+  assert.deepEqual(events.at(-1).errors, ['boom']);
+  assert.deepEqual(errors, ['mixdog: boom\n']);
+});
+
+test('--json is accepted for exec and rejected for the interactive command', () => {
+  const exec = classifyCliInvocation([
+    'exec',
+    '--provider', 'openai-oauth',
+    '--model', 'gpt-test',
+    '--json',
+    'fix it',
+  ]);
+  assert.equal(exec.kind, 'exec');
+  assert.equal(exec.options.json, true);
+
+  const interactive = classifyCliInvocation(['--json']);
+  assert.equal(interactive.kind, 'error');
+  assert.equal(interactive.error, 'option --json is only supported for mixdog exec');
+});

package/src/help.mjs

@@ -6,7 +6,7 @@ export const HELP_LINES = [
   '',
   'Usage:',
   '  mixdog [options]           start the TUI in the current project',
-  '  mixdog exec --provider <name> --model <name> [--effort <level>] [--fast] <message...>',
+  '  mixdog exec --provider <name> --model <name> [--effort <level>] [--fast] [--json] <message...>',
   '  mixdog --help',
   '',
   'Options:',
@@ -14,6 +14,7 @@ export const HELP_LINES = [
   '  --model <name>      model route for this session',
   '  --effort <level>    reasoning effort for the selected model',
   '  --fast              enable Fast mode for the selected model',
+  '  --json              emit headless exec events as JSONL',
   '  --workflow <name>   start with the given workflow active',
   '  --readonly          read-only tool surface',
   '  --remote            enable remote/channel mode for this session',

package/src/runtime/agent/orchestrator/session/agent-loop.mjs

@@ -636,13 +636,12 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         opts.onToolCall = _capFinalToolsDisabled
             ? undefined
             : (call) => {
-                const result = eager.onToolCall(call);
                 try {
                     opts.onAssistantToolCallObserved?.(call, {
-                        eagerStarted: !!call?.id && eager.pending.has(call.id),
+                        eagerStarted: false,
                     });
                 } catch {}
-                return result;
+                return eager.onToolCall(call);
             };
         const sendStartedAt = Date.now();
         const preSendMs = sendStartedAt - _iterT0;

package/src/runtime/agent/orchestrator/session/eager-dispatch.mjs

@@ -112,8 +112,11 @@ export function createEagerDispatcher({
             // serial path below. If any role/permission guard would reject
             // this call there, never start it eagerly here.
             if (preDispatchDenyForSession(sessionRef, call, toolKind) !== null) return null;
+            const dispatchedAt = Date.now();
             const entry = {
-                startedAt: Date.now(),
+                startedAt: dispatchedAt,
+                dispatchStartedAt: dispatchedAt,
+                executionStartedAt: null,
                 endedAt: null,
                 mutationEpoch: epoch.mutation,
                 localSearchTelemetry: {},
@@ -134,6 +137,7 @@ export function createEagerDispatcher({
                         }
                     }
                     await opts.beforeToolExecution?.();
+                    entry.executionStartedAt = Date.now();
                     return { ok: true, value: await executeToolFn(call.name, call.arguments, cwd, sessionId, sessionRef, { toolCallId: call.id, signal, notifyFn: opts.notifyFn, toolApprovalHook: opts.onToolApproval, iteration: getNextIteration(), localSearchTelemetry: entry.localSearchTelemetry, resultTelemetry: entry.resultTelemetry }) };
                 } catch (error) {
                     return { ok: false, error };
@@ -182,6 +186,11 @@ export function createEagerDispatcher({
                             content: _earlyContent,
                             isError: !(settled && settled.ok),
                             __earlyNotify: true,
+                            toolTiming: {
+                                dispatchStartedAt: entry.dispatchStartedAt,
+                                executionStartedAt: entry.executionStartedAt ?? entry.endedAt,
+                                executionCompletedAt: entry.endedAt,
+                            },
                         });
                     } catch { /* best-effort — UI notify must never break the eager path */ }
                     // Intentionally do NOT delete _sig here — see the block

package/src/runtime/agent/orchestrator/session/manager/ask-session.mjs

@@ -640,6 +640,7 @@ export async function askSession(sessionId, prompt, context, onToolCall, cwdOver
                     onAssistantToolCallObserved: (call, detail) => {
                         _turnInterruption.recordToolCalls([call], detail);
                         _scheduleTurnCheckpoint(true);
+                        try { askOpts?.onAssistantToolCallObserved?.(call, detail); } catch {}
                     },
                     onProviderSendStarted: () => {
                         _turnInterruption.markProviderSendStarted();

package/src/runtime/agent/orchestrator/session/tool-batch.mjs

@@ -196,6 +196,8 @@ export async function processToolBatch(ctx) {
                 }
             }
             if (sessionId) markSessionToolCall(sessionId, call.name, resolveToolSelfDeadlineMs(call.name, call.arguments));
+            let dispatchStartedAt = Date.now();
+            let executionStartedAt;
             let result;
             let toolStartedAt;
             let toolEndedAt;
@@ -234,12 +236,14 @@ export async function processToolBatch(ctx) {
             try {
                 if (_invalidArgs) {
                     toolStartedAt = Date.now();
+                    executionStartedAt = toolStartedAt;
                     toolEndedAt = toolStartedAt;
                     result = formatInvalidToolArgsResult(call);
                     _resultKind = 'error';
                     _executeOk = false;
                 } else if (_readCacheHit !== null) {
                     toolStartedAt = Date.now();
+                    executionStartedAt = toolStartedAt;
                     toolEndedAt = toolStartedAt;
                     const _body = _readCacheHit.content;
                     // Return the cached body byte-for-byte instead of a
@@ -251,6 +255,7 @@ export async function processToolBatch(ctx) {
                     _executeOk = true;
                 } else if (_scopedCacheHit !== null) {
                     toolStartedAt = Date.now();
+                    executionStartedAt = toolStartedAt;
                     toolEndedAt = toolStartedAt;
                     const _body = _scopedCacheHit.content;
                     result = _body;
@@ -276,6 +281,8 @@ export async function processToolBatch(ctx) {
                 }
                 if (eager !== undefined) {
                     toolStartedAt = eager.startedAt;
+                    dispatchStartedAt = eager.dispatchStartedAt ?? eager.startedAt;
+                    executionStartedAt = eager.executionStartedAt ?? eager.endedAt;
                     _localSearchTelemetry = eager.localSearchTelemetry || null;
                     _resultTelemetry = eager.resultTelemetry || {};
                     const settled = await eager.promise;
@@ -306,11 +313,13 @@ export async function processToolBatch(ctx) {
                     // both paths.
                     const _denyMsg = preDispatchDenyForSession(sessionRef, call, toolKind);
                     if (_denyMsg !== null) {
+                        executionStartedAt = toolStartedAt;
                         result = _denyMsg;
                         toolEndedAt = Date.now();
                         _resultKind = 'error';
                     } else {
                         await opts.beforeToolExecution?.();
+                        executionStartedAt = Date.now();
                         _localSearchTelemetry = {};
                         result = await executeToolFn(call.name, call.arguments, cwd, sessionId, sessionRef, { toolCallId: call.id, signal, notifyFn: opts.notifyFn, toolApprovalHook: opts.onToolApproval, iteration: iterations, localSearchTelemetry: _localSearchTelemetry, resultTelemetry: _resultTelemetry });
                         toolEndedAt = Date.now();
@@ -330,6 +339,7 @@ export async function processToolBatch(ctx) {
             }
             catch (err) {
                 if (toolStartedAt === undefined) toolStartedAt = Date.now();
+                if (executionStartedAt === undefined) executionStartedAt = toolStartedAt;
                 toolEndedAt = Date.now();
                 result = `Error: ${err instanceof Error ? err.message : String(err)}`;
                 _resultKind = 'error';
@@ -484,6 +494,8 @@ export async function processToolBatch(ctx) {
             _batchCompleted.push({
                 call,
                 result,
+                dispatchStartedAt,
+                executionStartedAt,
                 toolStartedAt,
                 toolEndedAt,
                 toolKind,
@@ -528,10 +540,11 @@ export async function processToolBatch(ctx) {
         for (let completedIndex = 0; completedIndex < _batchCompleted.length; completedIndex += 1) {
             const completed = _batchCompleted[completedIndex];
             const {
-                call, toolStartedAt, toolEndedAt, toolKind,
+                call, dispatchStartedAt, executionStartedAt, toolStartedAt, toolEndedAt, toolKind,
                 executeOk: _executeOk, resultKind: _resultKind,
                 readCacheHit: _readCacheHit, scopedCacheHit: _scopedCacheHit,
             } = completed;
+            const postprocessStartedAt = Date.now();
             let _ctSig = completed.crossTurnSig;
             let result = completed.result;
             const _nativeToolSearch = completed.nativeToolSearch;
@@ -604,11 +617,19 @@ export async function processToolBatch(ctx) {
                 const _applyPatchUiDiff = _stripMcpPrefix(call.name) === 'apply_patch'
                     ? takeApplyPatchUiDiff(call.id)
                     : null;
+                const resultCompletedAt = Date.now();
                 _stageToolResultMessage({
                     role: 'tool',
                     content: result,
                     toolCallId: call.id,
                     toolKind: _resultKind,
+                    toolTiming: {
+                        dispatchStartedAt,
+                        executionStartedAt: executionStartedAt ?? toolStartedAt,
+                        executionCompletedAt: toolEndedAt,
+                        postprocessStartedAt,
+                        resultCompletedAt,
+                    },
                     ...(_nativeToolSearch ? { nativeToolSearch: _nativeToolSearch } : {}),
                     ...(_applyPatchUiDiff !== null ? { uiDiff: _applyPatchUiDiff } : {}),
                 });
@@ -651,11 +672,19 @@ export async function processToolBatch(ctx) {
                     resultText: _postMsg,
                     resultKind: 'error',
                 });
+                const resultCompletedAt = Date.now();
                 _stageToolResultMessage({
                     role: 'tool',
                     content: _postMsg,
                     toolCallId: call.id,
                     toolKind: 'error',
+                    toolTiming: {
+                        dispatchStartedAt,
+                        executionStartedAt: executionStartedAt ?? toolStartedAt,
+                        executionCompletedAt: toolEndedAt,
+                        postprocessStartedAt,
+                        resultCompletedAt,
+                    },
                 });
             }
             throwIfAborted();

package/src/runtime/agent/orchestrator/tools/builtin/native-search-client.mjs

@@ -29,7 +29,14 @@ function _setServerReferenced(server, referenced) {
 
 function _resolveBinary() {
   if (_binaryPath !== undefined) return _binaryPath;
-  const explicit = String(process.env.MIXDOG_SEARCH_SERVER_BIN || '').trim();
+  // The graph and resident-search protocols ship in the same executable.
+  // Honor either override synchronously so a first grep never races the lazy
+  // graph module import while an explicitly injected binary already exists.
+  const explicit = String(
+    process.env.MIXDOG_SEARCH_SERVER_BIN
+    || process.env.MIXDOG_GRAPH_BIN
+    || '',
+  ).trim();
   if (explicit && existsSync(explicit)) {
     _binaryPath = explicit;
     return _binaryPath;
@@ -305,7 +312,12 @@ export async function tryServeSearch(argsList, execOptions = {}, opts = {}) {
       ? Math.floor(Number(opts.limit))
       : 0,
   }, execOptions, requestDeadlineMs);
-  if (!response || response.unsupported || response.error) return null;
+  if (!response) return null;
+  if (response.unsupported || response.error) {
+    const rejected = new Error(String(response.error || response.unsupported));
+    rejected.code = response.error ? 'NATIVE_SEARCH_ERROR' : 'NATIVE_SEARCH_UNSUPPORTED';
+    throw rejected;
+  }
   if (!Array.isArray(response.lines)) return null;
   return {
     lines: response.lines,

package/src/runtime/agent/orchestrator/tools/graph-manifest.json

@@ -1,26 +1,26 @@
 {
-  "version": "0.1.8",
+  "version": "0.1.9",
   "_comment": "Synced from immutable graph-v release assets.",
   "assets": {
     "darwin-arm64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.8/mixdog-graph-darwin-arm64",
-      "sha256": "3b0f1607394a542df99ac1a226fa8c0cc413cb2ea2714fe8e72184f4f1dc99ff"
+      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.9/mixdog-graph-darwin-arm64",
+      "sha256": "1533e65d40a9392833dee78f771771c176d376a6001f1905aa4b25d3fda49041"
     },
     "darwin-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.8/mixdog-graph-darwin-x64",
-      "sha256": "bac512530c83f3cf45b542ae45fb50cb4d1c5fa5de4cfdede9865208d23fa4a4"
+      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.9/mixdog-graph-darwin-x64",
+      "sha256": "9fb70b2109683945d26fc3ba49d71d991aaa26d3513cb50048bf9539ec01fd31"
     },
     "linux-arm64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.8/mixdog-graph-linux-arm64",
-      "sha256": "10df41dd7c0a68cdc2f6430b83e15d928a4f446b9f7b34504aef3ab05a32f514"
+      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.9/mixdog-graph-linux-arm64",
+      "sha256": "e41aad50f20a22d170ca9850988cc327d77eea264fbbabed6ff98cc840fc2c0f"
     },
     "linux-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.8/mixdog-graph-linux-x64",
-      "sha256": "8a3b77fc830e169f0b2f553c67d3a2ecb4e3a91aa27706185749f38dcebe1482"
+      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.9/mixdog-graph-linux-x64",
+      "sha256": "750c8ed55ab077b052ae76e222a3ebefe6a137a18f8790948e2b33a4ce4aa915"
     },
     "win32-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.8/mixdog-graph-win32-x64.exe",
-      "sha256": "d748a4f9b0deb39fbcb3387f54a6773eba76bbfa7749ed8376a1d3e5c0cddcdd"
+      "url": "https://github.com/tribgames/mixdog/releases/download/graph-v0.1.9/mixdog-graph-win32-x64.exe",
+      "sha256": "99b12dd8f10245e0aabc2e5ffc5ae25299d01127a51ebc433dbca9bd36814c75"
     }
   }
 }

package/src/session-runtime/prewarm.mjs

@@ -34,12 +34,24 @@ export function createPrewarmSchedulers({
     }
     if (isCloseRequested()) return;
     state.codeGraphPrewarmQueuedCwd = getCurrentCwd();
-    if (timers.codeGraphPrewarmTimer) return;
+    if (timers.codeGraphPrewarmTimer) {
+      // Upgrade a pending idle/cwd warm when the first visible provider token
+      // arrives. Keeping the older timer would preserve its non-overlap reason
+      // and defer the graph until after the active turn.
+      if (reason !== 'first-visible') return;
+      clearTimeout(timers.codeGraphPrewarmTimer);
+      timers.codeGraphPrewarmTimer = null;
+    }
     timers.codeGraphPrewarmTimer = setTimeout(() => {
       timers.codeGraphPrewarmTimer = null;
       if (isCloseRequested()) return;
-      if (getActiveTurnCount() > 0 || getSessionCreatePromise()) {
-        bootProfile('code-graph:prewarm-deferred', { reason: getActiveTurnCount() > 0 ? 'turn-active' : 'session-create' });
+      const activeTurn = getActiveTurnCount() > 0;
+      // first-visible is armed only after TTFT. Let that warm overlap the
+      // provider's remaining generation instead of retrying until the turn
+      // ends, which made first-turn code_graph calls pay the full cold build.
+      const canOverlapActiveTurn = reason === 'first-visible';
+      if ((activeTurn && !canOverlapActiveTurn) || getSessionCreatePromise()) {
+        bootProfile('code-graph:prewarm-deferred', { reason: activeTurn ? 'turn-active' : 'session-create' });
         scheduleCodeGraphPrewarm(backgroundBusyRetryMs, 'busy');
         return;
       }

package/src/session-runtime/prewarm.test.mjs

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createPrewarmSchedulers } from './prewarm.mjs';
+
+test('first-visible code graph prewarm overlaps an active turn', async () => {
+  const timers = {};
+  const calls = [];
+  const profiles = [];
+  const cwd = process.cwd();
+  const schedulers = createPrewarmSchedulers({
+    timers,
+    bootProfile: (event, detail) => profiles.push([event, detail]),
+    getCurrentCwd: () => cwd,
+    isCloseRequested: () => false,
+    getActiveTurnCount: () => 1,
+    getSessionCreatePromise: () => null,
+    getSession: () => null,
+    isRemoteEnabled: () => false,
+    channelsEnabled: () => false,
+    hasActiveAutomation: () => false,
+    getCodeGraphModule: async () => ({
+      prewarmCodeGraphIfProject(root) {
+        calls.push(root);
+        return true;
+      },
+    }),
+    createCurrentSession: async () => null,
+    channels: {},
+    envFlag: () => false,
+    delays: {
+      codeGraphPrewarmDelayMs: 0,
+      channelStartDelayMs: 0,
+      backgroundBusyRetryMs: 50,
+    },
+    flags: { codeGraphPrewarmEnabled: true },
+    state: {
+      codeGraphPrewarmQueuedCwd: '',
+      codeGraphPrewarmInFlight: false,
+    },
+  });
+
+  schedulers.scheduleCodeGraphPrewarm(100, 'cwd');
+  schedulers.scheduleCodeGraphPrewarm(0, 'first-visible');
+  await new Promise((resolve) => setTimeout(resolve, 25));
+
+  assert.deepEqual(calls, [cwd]);
+  assert.equal(
+    profiles.some(([event, detail]) =>
+      event === 'code-graph:prewarm-deferred' && detail?.reason === 'turn-active'),
+    false,
+  );
+});

package/src/session-runtime/session-turn-api.mjs

@@ -339,6 +339,7 @@ export function createSessionTurnApi(deps) {
               return options.onAssistantText?.(text);
             },
             onUsageDelta: options.onUsageDelta,
+            onAssistantToolCallObserved: options.onAssistantToolCallObserved,
             onToolResult: (message) => {
               if (getRemoteEnabled() && getTranscriptWriter()) {
                 try {