@meistrari/tela-cli 0.7.0 → 0.7.4

package/src/commands/run.ts

@@ -1,1699 +0,0 @@
-import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
-import { basename, join } from 'node:path'
-import {
-    formatClaudeCliVersion,
-    inspectClaudeCli,
-    MIN_CLAUDE_VERSION_FOR_PROJECT_SCOPED_RUN,
-} from '../claude.ts'
-import { getRepositoryRoot } from '../git.ts'
-import { createUserFacingError } from '../errors.ts'
-import {
-    commandExists,
-    runCommand,
-    runInteractiveCommand,
-    runStreamingCommand,
-    spawnStreamingCommand,
-    type CommandResult,
-    type RunStreamingCommandOptions,
-    type StreamingCommandHandle,
-} from '../process.ts'
-import { bulletList, joinBlocks, kvList, resultCard, section, type RenderOptions } from '../ui.ts'
-
-const INITIAL_PROMPT = 'Follow the instructions and return the result.'
-const REQUIRED_AGENT_FILES = [
-    'CLAUDE.md',
-    'instructions.md',
-    'output-format.json',
-    'agent.config.json',
-] as const
-const TOOL_PROGRESS_MILESTONES = [0, 5, 15, 30] as const
-
-export type RunMode = 'chat' | 'one-shot'
-export type RunOutputSurface = 'plain' | 'viewer' | 'json'
-export type RunExecutionStatus = 'starting' | 'running' | 'success' | 'failed' | 'cancelled'
-
-export interface AgentRunConfig {
-    model?: string
-    isMultiturn: boolean
-    maxRounds?: number
-}
-
-export interface PreparedLocalAgentRun {
-    repoRoot: string
-    config: AgentRunConfig
-    resultKind: 'json' | 'markdown'
-    resultPath: string
-    mcpConfigPath?: string
-}
-
-export interface RunStepSummary {
-    id: string
-    kind: 'assistant' | 'tool' | 'status' | 'retry' | 'hook' | 'task' | 'artifact' | 'result'
-    summary: string
-    detail?: string
-    notable?: boolean
-}
-
-export interface RunActiveTool {
-    id: string
-    name: string
-    summary: string
-    detail?: string
-    elapsedSeconds: number
-}
-
-export interface RunExecutionSummary {
-    status: RunExecutionStatus
-    durationMs?: number
-    durationApiMs?: number
-    numTurns?: number
-    stopReason?: string | null
-    totalCostUsd?: number
-    permissionDenials: string[]
-    errors: string[]
-    notableEvents: string[]
-    structuredOutputPresent: boolean
-}
-
-export interface RunArtifactSummary {
-    path: string
-    kind: 'json' | 'markdown'
-    value: unknown
-}
-
-export interface RunCommandResult {
-    ok: true
-    repoRoot: string
-    mode: RunMode
-    config: AgentRunConfig
-    execution: RunExecutionSummary
-    steps: RunStepSummary[]
-    artifact: RunArtifactSummary
-    resultPath: string
-    resultKind: 'json' | 'markdown'
-    resultValue: unknown
-}
-
-export interface RunExecutionSnapshot {
-    repoRoot: string
-    mode: RunMode
-    model?: string
-    artifactPath: string
-    startedAtMs: number
-    status: RunExecutionStatus
-    currentActivity: string
-    steps: RunStepSummary[]
-    activeTools: RunActiveTool[]
-    execution: RunExecutionSummary
-}
-
-export interface RunExecutionControl {
-    interrupt(): void
-    kill(): void
-}
-
-export interface RunLocalAgentCommandOptions {
-    cwd?: string
-    contract?: PreparedLocalAgentRun
-    surface?: RunOutputSurface
-    commandExists?: typeof commandExists
-    inspectClaudeCli?: typeof inspectClaudeCli
-    runCommand?: typeof runCommand
-    runInteractiveCommand?: typeof runInteractiveCommand
-    runStreamingCommand?: typeof runStreamingCommand
-    spawnStreamingCommand?: typeof spawnStreamingCommand
-    writeStdout?: (message: string) => void
-    writeStderr?: (message: string) => void
-    onSnapshot?: (snapshot: RunExecutionSnapshot) => void
-    onControl?: (control: RunExecutionControl) => void
-    stdinIsTTY?: boolean
-    stdoutIsTTY?: boolean
-    verbose?: boolean
-}
-
-interface AssistantToolUse {
-    id: string
-    name: string
-    input: unknown
-    summary: string
-    detail?: string
-}
-
-interface ClaudeResultEvent {
-    type?: string
-    subtype?: string
-    duration_ms?: unknown
-    duration_api_ms?: unknown
-    is_error?: boolean
-    num_turns?: unknown
-    stop_reason?: unknown
-    total_cost_usd?: unknown
-    permission_denials?: unknown
-    errors?: unknown
-    structured_output?: unknown
-}
-
-type RunEvent =
-    | {
-        kind: 'session_init'
-        summary: string
-        detail?: string
-        model?: string
-        recordStep: boolean
-    }
-    | {
-        kind: 'assistant_text'
-        text: string
-        summary: string
-        detail?: string
-        recordStep: true
-    }
-    | {
-        kind: 'tool_batch'
-        summary: string
-        detail?: string
-        tools: RunActiveTool[]
-        recordStep: true
-    }
-    | {
-        kind: 'tool_progress'
-        toolUseId: string
-        toolName: string
-        summary: string
-        detail?: string
-        elapsedSeconds: number
-        recordStep: false
-    }
-    | {
-        kind: 'status_notice'
-        summary: string
-        detail?: string
-        recordStep: boolean
-        notable?: boolean
-    }
-    | {
-        kind: 'retry_notice'
-        summary: string
-        detail?: string
-        recordStep: true
-        notable: true
-    }
-    | {
-        kind: 'hook_notice'
-        summary: string
-        detail?: string
-        recordStep: boolean
-    }
-    | {
-        kind: 'task_notice'
-        summary: string
-        detail?: string
-        recordStep: true
-        notable?: boolean
-    }
-    | {
-        kind: 'artifact_notice'
-        summary: string
-        detail?: string
-        recordStep: boolean
-        notable?: boolean
-    }
-    | {
-        kind: 'result'
-        summary: string
-        detail?: string
-        recordStep: true
-        execution: Partial<RunExecutionSummary> & Pick<RunExecutionSummary, 'status'>
-    }
-
-function writeLine(
-    writer: ((message: string) => void) | undefined,
-    line: string,
-): void {
-    const message = `${line}\n`
-    if (writer) {
-        writer(message)
-        return
-    }
-
-    process.stdout.write(message)
-}
-
-function writeErrorLine(
-    writer: ((message: string) => void) | undefined,
-    line: string,
-): void {
-    const message = `${line}\n`
-    if (writer) {
-        writer(message)
-        return
-    }
-
-    process.stderr.write(message)
-}
-
-function splitVisibleLines(value: string): string[] {
-    return value
-        .split(/\r?\n/)
-        .map(line => line.trim())
-        .filter(Boolean)
-}
-
-function truncate(value: string, maxLength = 96): string {
-    const normalized = value.replace(/\s+/g, ' ').trim()
-    if (normalized.length <= maxLength) {
-        return normalized
-    }
-
-    return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`
-}
-
-function safeString(value: unknown): string | undefined {
-    return typeof value === 'string' && value.trim().length > 0
-        ? value.trim()
-        : undefined
-}
-
-function safeNumber(value: unknown): number | undefined {
-    return typeof value === 'number' && Number.isFinite(value)
-        ? value
-        : undefined
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
-}
-
-function formatDurationMs(durationMs: number | undefined): string {
-    if (!durationMs || durationMs <= 0) {
-        return '<unknown>'
-    }
-
-    if (durationMs < 1000) {
-        return `${durationMs}ms`
-    }
-
-    const seconds = durationMs / 1000
-    if (seconds < 60) {
-        return `${seconds.toFixed(seconds >= 10 ? 1 : 2)}s`
-    }
-
-    const minutes = Math.floor(seconds / 60)
-    const remainingSeconds = Math.round(seconds % 60)
-    return `${minutes}m ${remainingSeconds}s`
-}
-
-function formatElapsedSeconds(seconds: number): string {
-    if (seconds < 60) {
-        return `${seconds}s`
-    }
-
-    const minutes = Math.floor(seconds / 60)
-    const remainder = seconds % 60
-    return `${minutes}m ${remainder}s`
-}
-
-function summarizePermissionDenial(value: unknown): string {
-    if (!isRecord(value)) {
-        return 'Permission denied for a tool call.'
-    }
-
-    const toolName = safeString(value.tool_name) ?? 'tool'
-    if (!isRecord(value.tool_input)) {
-        return `Permission denied: ${toolName}`
-    }
-
-    const inputSummary = summarizeToolInput(toolName, value.tool_input)
-    return inputSummary ? `Permission denied: ${toolName} ${inputSummary}` : `Permission denied: ${toolName}`
-}
-
-function parsePermissionDenials(value: unknown): string[] {
-    if (!Array.isArray(value)) {
-        return []
-    }
-
-    return value.map(summarizePermissionDenial)
-}
-
-function summarizeLines(value: string): { summary: string, detail?: string } {
-    const lines = splitVisibleLines(value)
-    if (lines.length === 0) {
-        return { summary: '<empty>' }
-    }
-
-    const summary = truncate(lines[0] ?? '')
-    if (lines.length === 1 && summary === lines[0]) {
-        return { summary }
-    }
-
-    return {
-        summary,
-        detail: lines.join('\n'),
-    }
-}
-
-function summarizeStructuredOutputPresence(value: unknown): boolean {
-    return value !== undefined
-}
-
-function summarizeToolInput(toolName: string, input: unknown): string | undefined {
-    if (!isRecord(input)) {
-        return undefined
-    }
-
-    const pathValue = [
-        input.file_path,
-        input.path,
-        input.filename,
-        input.file,
-        input.target_file,
-        input.to_path,
-        input.from_path,
-    ].find(candidate => typeof candidate === 'string' && candidate.trim().length > 0)
-    if (typeof pathValue === 'string') {
-        return truncate(basename(pathValue))
-    }
-
-    const commandValue = [
-        input.command,
-        input.cmd,
-        input.script,
-        input.shell_command,
-    ].find(candidate => typeof candidate === 'string' && candidate.trim().length > 0)
-    if (typeof commandValue === 'string') {
-        return truncate(commandValue.replace(/\s+/g, ' '))
-    }
-
-    const queryValue = [
-        input.pattern,
-        input.query,
-        input.q,
-        input.search_query,
-    ].find(candidate => typeof candidate === 'string' && candidate.trim().length > 0)
-    if (typeof queryValue === 'string') {
-        return truncate(queryValue)
-    }
-
-    const urlValue = [
-        input.url,
-        input.href,
-    ].find(candidate => typeof candidate === 'string' && candidate.trim().length > 0)
-    if (typeof urlValue === 'string') {
-        return truncate(urlValue)
-    }
-
-    const locationValue = safeString(input.location)
-    if (locationValue) {
-        return truncate(locationValue)
-    }
-
-    const titleValue = safeString(input.title)
-    if (titleValue) {
-        return truncate(titleValue)
-    }
-
-    const pageIndex = safeNumber(input.page_index)
-    if (pageIndex != null) {
-        return `${toolName} page ${pageIndex}`
-    }
-
-    return undefined
-}
-
-function summarizeToolUse(name: string, input: unknown): { summary: string, detail?: string } {
-    const detail = summarizeToolInput(name, input)
-    return detail
-        ? { summary: truncate(`${name} ${detail}`), detail: `${name}: ${detail}` }
-        : { summary: name }
-}
-
-function extractAssistantText(message: unknown): string {
-    if (!message || typeof message !== 'object') {
-        return ''
-    }
-
-    const content = (message as { content?: unknown }).content
-    if (typeof content === 'string') {
-        return content
-    }
-
-    if (!Array.isArray(content)) {
-        return ''
-    }
-
-    return content
-        .flatMap((block) => {
-            if (!isRecord(block) || block.type !== 'text') {
-                return []
-            }
-
-            return typeof block.text === 'string' ? [block.text] : []
-        })
-        .join('\n')
-}
-
-function extractAssistantToolUses(message: unknown): AssistantToolUse[] {
-    if (!message || typeof message !== 'object') {
-        return []
-    }
-
-    const content = (message as { content?: unknown }).content
-    if (!Array.isArray(content)) {
-        return []
-    }
-
-    return content.flatMap((block, index) => {
-        if (!isRecord(block) || block.type !== 'tool_use') {
-            return []
-        }
-
-        const name = safeString(block.name)
-        if (!name) {
-            return []
-        }
-
-        const { summary, detail } = summarizeToolUse(name, block.input)
-        return [{
-            id: safeString(block.id) ?? `${name}-${index}`,
-            name,
-            input: block.input,
-            summary,
-            detail,
-        }]
-    })
-}
-
-function capitalize(value: string): string {
-    return value.length > 0
-        ? `${value[0]?.toUpperCase() ?? ''}${value.slice(1)}`
-        : value
-}
-
-function pluralize(count: number, singular: string, plural = `${singular}s`): string {
-    return `${count} ${count === 1 ? singular : plural}`
-}
-
-function categorizeToolName(name: string): 'searches' | 'reads' | 'writes' | 'commands' | 'other' {
-    const normalized = name.toLowerCase()
-
-    if (/(grep|glob|search|lsp|find)/.test(normalized)) {
-        return 'searches'
-    }
-
-    if (/(read|fetch|get|open|view)/.test(normalized)) {
-        return 'reads'
-    }
-
-    if (/(write|edit|patch|replace|update|insert|delete|move|format|apply)/.test(normalized)) {
-        return 'writes'
-    }
-
-    if (/(bash|shell|exec|command|tmux|terminal)/.test(normalized)) {
-        return 'commands'
-    }
-
-    return 'other'
-}
-
-function buildDerivedToolSummary(toolUses: AssistantToolUse[]): string {
-    if (toolUses.length === 1) {
-        return toolUses[0]?.summary ?? 'Tool call'
-    }
-
-    const counts = {
-        searches: 0,
-        reads: 0,
-        writes: 0,
-        commands: 0,
-        other: 0,
-    }
-
-    for (const toolUse of toolUses) {
-        counts[categorizeToolName(toolUse.name)] += 1
-    }
-
-    const parts: string[] = []
-    if (counts.searches > 0) {
-        parts.push(`searched ${pluralize(counts.searches, 'pattern')}`)
-    }
-    if (counts.reads > 0) {
-        parts.push(`read ${pluralize(counts.reads, 'file')}`)
-    }
-    if (counts.writes > 0) {
-        parts.push(`wrote ${pluralize(counts.writes, 'file')}`)
-    }
-    if (counts.commands > 0) {
-        parts.push(`ran ${pluralize(counts.commands, 'command')}`)
-    }
-    if (counts.other > 0) {
-        parts.push(`${pluralize(counts.other, 'other tool')}`)
-    }
-
-    return capitalize(parts.join(', '))
-}
-
-function buildToolBatchEvent(
-    summary: string,
-    toolUses: AssistantToolUse[],
-): RunEvent {
-    const detailLines = toolUses
-        .map(toolUse => toolUse.detail ?? toolUse.summary)
-        .filter(Boolean)
-    return {
-        kind: 'tool_batch',
-        summary,
-        detail: detailLines.length > 0 ? detailLines.join('\n') : undefined,
-        tools: toolUses.map(toolUse => ({
-            id: toolUse.id,
-            name: toolUse.name,
-            summary: toolUse.summary,
-            detail: toolUse.detail,
-            elapsedSeconds: 0,
-        })),
-        recordStep: true,
-    }
-}
-
-function normalizeClaudePrintEvent(event: Record<string, unknown>): RunEvent[] {
-    switch (event.type) {
-        case 'system': {
-            switch (event.subtype) {
-                case 'init':
-                    return [{
-                        kind: 'session_init',
-                        summary: 'Claude session started.',
-                        detail: safeString(event.cwd),
-                        model: safeString(event.model),
-                        recordStep: true,
-                    }]
-                case 'status': {
-                    const status = safeString(event.status)
-                    if (!status) {
-                        return []
-                    }
-
-                    return [{
-                        kind: 'status_notice',
-                        summary: status === 'compacting' ? 'Compacting conversation…' : `Status: ${status}`,
-                        recordStep: status === 'compacting',
-                        notable: status === 'compacting',
-                    }]
-                }
-                case 'api_retry': {
-                    const attempt = safeNumber(event.attempt) ?? '?'
-                    const maxRetries = safeNumber(event.max_retries) ?? '?'
-                    const error = safeString(event.error) ?? 'Retrying Claude API request.'
-                    return [{
-                        kind: 'retry_notice',
-                        summary: `Retry ${attempt}/${maxRetries}`,
-                        detail: error,
-                        recordStep: true,
-                        notable: true,
-                    }]
-                }
-                case 'hook_started': {
-                    const hookName = safeString(event.hook_name) ?? 'hook'
-                    const hookEvent = safeString(event.hook_event)
-                    return [{
-                        kind: 'hook_notice',
-                        summary: hookEvent ? `Hook started: ${hookName} (${hookEvent})` : `Hook started: ${hookName}`,
-                        recordStep: false,
-                    }]
-                }
-                case 'hook_progress': {
-                    const hookName = safeString(event.hook_name) ?? 'hook'
-                    const detail = [safeString(event.output), safeString(event.stdout), safeString(event.stderr)]
-                        .find(Boolean)
-                    return [{
-                        kind: 'hook_notice',
-                        summary: `Hook output: ${hookName}`,
-                        detail,
-                        recordStep: true,
-                    }]
-                }
-                case 'task_notification': {
-                    const status = safeString(event.status) ?? 'completed'
-                    const summary = safeString(event.summary)
-                        ?? safeString(event.output_file)
-                        ?? safeString(event.task_id)
-                        ?? 'Task finished'
-                    return [{
-                        kind: 'task_notice',
-                        summary: `Task ${status}: ${summary}`,
-                        detail: safeString(event.output_file),
-                        recordStep: true,
-                        notable: status !== 'completed',
-                    }]
-                }
-                case 'files_persisted': {
-                    const failed = Array.isArray(event.failed)
-                        ? event.failed.filter(isRecord)
-                        : []
-                    if (failed.length === 0) {
-                        const persistedCount = Array.isArray(event.files) ? event.files.length : 0
-                        return [{
-                            kind: 'artifact_notice',
-                            summary: `Persisted ${pluralize(persistedCount, 'file')}.`,
-                            recordStep: false,
-                        }]
-                    }
-
-                    return [{
-                        kind: 'artifact_notice',
-                        summary: 'Some files could not be persisted.',
-                        detail: failed
-                            .map(entry => `${safeString(entry.filename) ?? '<unknown>'}: ${safeString(entry.error) ?? 'Unknown error'}`)
-                            .join('\n'),
-                        recordStep: true,
-                        notable: true,
-                    }]
-                }
-                default:
-                    return []
-            }
-        }
-        case 'assistant': {
-            const normalized: RunEvent[] = []
-            const text = extractAssistantText(event.message)
-            if (text.trim()) {
-                const summary = summarizeLines(text)
-                normalized.push({
-                    kind: 'assistant_text',
-                    text,
-                    summary: summary.summary,
-                    detail: summary.detail,
-                    recordStep: true,
-                })
-            }
-
-            const toolUses = extractAssistantToolUses(event.message)
-            if (toolUses.length > 0) {
-                normalized.push(buildToolBatchEvent(buildDerivedToolSummary(toolUses), toolUses))
-            }
-
-            return normalized
-        }
-        case 'streamlined_text': {
-            const text = safeString(event.text)
-            if (!text) {
-                return []
-            }
-
-            const summary = summarizeLines(text)
-            return [{
-                kind: 'assistant_text',
-                text,
-                summary: summary.summary,
-                detail: summary.detail,
-                recordStep: true,
-            }]
-        }
-        case 'tool_use_summary': {
-            const summary = safeString(event.summary)
-            return summary
-                ? [buildToolBatchEvent(summary, [])]
-                : []
-        }
-        case 'streamlined_tool_use_summary': {
-            const summary = safeString(event.tool_summary)
-            return summary
-                ? [buildToolBatchEvent(summary, [])]
-                : []
-        }
-        case 'tool_progress': {
-            const toolUseId = safeString(event.tool_use_id)
-            const toolName = safeString(event.tool_name)
-            const elapsedSeconds = safeNumber(event.elapsed_time_seconds)
-            if (!toolUseId || !toolName || elapsedSeconds == null) {
-                return []
-            }
-
-            return [{
-                kind: 'tool_progress',
-                toolUseId,
-                toolName,
-                summary: `${toolName} running for ${formatElapsedSeconds(elapsedSeconds)}`,
-                detail: safeString(event.task_id),
-                elapsedSeconds,
-                recordStep: false,
-            }]
-        }
-        case 'result': {
-            const subtype = safeString(event.subtype) ?? 'success'
-            const status: RunExecutionStatus = subtype === 'success'
-                ? 'success'
-                : 'failed'
-            const durationMs = safeNumber(event.duration_ms)
-            const detail = Array.isArray(event.errors)
-                ? event.errors.filter((value): value is string => typeof value === 'string' && value.trim().length > 0).join('\n')
-                : undefined
-
-            return [{
-                kind: 'result',
-                summary: status === 'success'
-                    ? `Run completed in ${formatDurationMs(durationMs)}.`
-                    : `Run failed after ${formatDurationMs(durationMs)}.`,
-                detail,
-                recordStep: true,
-                execution: {
-                    status,
-                    durationMs,
-                    durationApiMs: safeNumber(event.duration_api_ms),
-                    numTurns: safeNumber(event.num_turns),
-                    stopReason: safeString(event.stop_reason) ?? null,
-                    totalCostUsd: safeNumber(event.total_cost_usd),
-                    permissionDenials: parsePermissionDenials(event.permission_denials),
-                    errors: Array.isArray(event.errors)
-                        ? event.errors.filter((value): value is string => typeof value === 'string' && value.trim().length > 0)
-                        : [],
-                    structuredOutputPresent: summarizeStructuredOutputPresence(event.structured_output),
-                    notableEvents: [],
-                },
-            }]
-        }
-        default:
-            return []
-    }
-}
-
-class RunStateTracker {
-    private readonly steps: RunStepSummary[] = []
-    private readonly activeTools = new Map<string, RunActiveTool>()
-    private readonly execution: RunExecutionSummary
-    private stepIndex = 0
-    private status: RunExecutionStatus = 'starting'
-    private currentActivity = 'Preparing Claude run…'
-    private model?: string
-
-    constructor(
-        private readonly prepared: PreparedLocalAgentRun,
-        private readonly mode: RunMode,
-        private readonly startedAtMs = Date.now(),
-    ) {
-        this.execution = {
-            status: 'starting',
-            permissionDenials: [],
-            errors: [],
-            notableEvents: [],
-            structuredOutputPresent: false,
-        }
-        this.model = prepared.config.model
-    }
-
-    private addStep(
-        kind: RunStepSummary['kind'],
-        summary: string,
-        detail?: string,
-        notable = false,
-    ): void {
-        this.steps.push({
-            id: `step-${++this.stepIndex}`,
-            kind,
-            summary,
-            detail,
-            notable,
-        })
-    }
-
-    private note(message: string | undefined): void {
-        if (!message) {
-            return
-        }
-
-        if (!this.execution.notableEvents.includes(message)) {
-            this.execution.notableEvents.push(message)
-        }
-    }
-
-    private clearActiveTools(): void {
-        this.activeTools.clear()
-    }
-
-    update(event: RunEvent): RunExecutionSnapshot {
-        switch (event.kind) {
-            case 'session_init':
-                this.status = 'running'
-                this.execution.status = 'running'
-                this.currentActivity = event.summary
-                this.model = event.model ?? this.model
-                if (event.recordStep) {
-                    this.addStep('status', event.summary, event.detail)
-                }
-                break
-            case 'assistant_text':
-                this.clearActiveTools()
-                this.status = 'running'
-                this.execution.status = 'running'
-                this.currentActivity = event.summary
-                this.addStep('assistant', event.summary, event.detail)
-                break
-            case 'tool_batch':
-                this.clearActiveTools()
-                this.status = 'running'
-                this.execution.status = 'running'
-                this.currentActivity = event.summary
-                this.addStep('tool', event.summary, event.detail)
-                for (const tool of event.tools) {
-                    this.activeTools.set(tool.id, tool)
-                }
-                break
-            case 'tool_progress': {
-                const previous = this.activeTools.get(event.toolUseId)
-                this.activeTools.set(event.toolUseId, {
-                    id: event.toolUseId,
-                    name: event.toolName,
-                    summary: previous?.summary ?? event.toolName,
-                    detail: previous?.detail ?? event.detail,
-                    elapsedSeconds: event.elapsedSeconds,
-                })
-                this.status = 'running'
-                this.execution.status = 'running'
-                this.currentActivity = event.summary
-                break
-            }
-            case 'status_notice':
-                this.status = 'running'
-                this.execution.status = 'running'
-                this.currentActivity = event.summary
-                if (event.recordStep) {
-                    this.addStep('status', event.summary, event.detail, Boolean(event.notable))
-                }
-                if (event.notable) {
-                    this.note(event.summary)
-                }
-                break
-            case 'retry_notice':
-                this.status = 'running'
-                this.execution.status = 'running'
-                this.currentActivity = event.summary
-                this.addStep('retry', event.summary, event.detail, true)
-                this.note(event.summary)
-                break
-            case 'hook_notice':
-                this.status = 'running'
-                this.execution.status = 'running'
-                this.currentActivity = event.summary
-                if (event.recordStep) {
-                    this.addStep('hook', event.summary, event.detail)
-                }
-                break
-            case 'task_notice':
-                this.status = 'running'
-                this.execution.status = 'running'
-                this.currentActivity = event.summary
-                this.addStep('task', event.summary, event.detail, Boolean(event.notable))
-                if (event.notable) {
-                    this.note(event.summary)
-                }
-                break
-            case 'artifact_notice':
-                this.status = 'running'
-                this.execution.status = 'running'
-                this.currentActivity = event.summary
-                if (event.recordStep) {
-                    this.addStep('artifact', event.summary, event.detail, Boolean(event.notable))
-                }
-                if (event.notable) {
-                    this.note(event.summary)
-                }
-                break
-            case 'result':
-                this.clearActiveTools()
-                this.status = event.execution.status
-                this.currentActivity = event.summary
-                this.execution.status = event.execution.status
-                this.execution.durationMs = event.execution.durationMs
-                this.execution.durationApiMs = event.execution.durationApiMs
-                this.execution.numTurns = event.execution.numTurns
-                this.execution.stopReason = event.execution.stopReason
-                this.execution.totalCostUsd = event.execution.totalCostUsd
-                this.execution.permissionDenials = [...(event.execution.permissionDenials ?? [])]
-                this.execution.errors = [...(event.execution.errors ?? [])]
-                this.execution.structuredOutputPresent = Boolean(event.execution.structuredOutputPresent)
-                for (const message of event.execution.notableEvents ?? []) {
-                    this.note(message)
-                }
-                this.addStep('result', event.summary, event.detail, event.execution.status !== 'success')
-                break
-        }
-
-        return this.snapshot()
-    }
-
-    finalize(status: Extract<RunExecutionStatus, 'success' | 'failed' | 'cancelled'>, detail?: {
-        errors?: string[]
-        durationMs?: number
-        durationApiMs?: number
-        numTurns?: number
-        stopReason?: string | null
-        totalCostUsd?: number
-        permissionDenials?: string[]
-        structuredOutputPresent?: boolean
-        summary?: string
-    }): RunExecutionSnapshot {
-        this.clearActiveTools()
-        this.status = status
-        this.execution.status = status
-        this.execution.errors = detail?.errors ?? this.execution.errors
-        this.execution.durationMs = detail?.durationMs ?? this.execution.durationMs
-        this.execution.durationApiMs = detail?.durationApiMs ?? this.execution.durationApiMs
-        this.execution.numTurns = detail?.numTurns ?? this.execution.numTurns
-        this.execution.stopReason = detail?.stopReason ?? this.execution.stopReason
-        this.execution.totalCostUsd = detail?.totalCostUsd ?? this.execution.totalCostUsd
-        this.execution.permissionDenials = detail?.permissionDenials ?? this.execution.permissionDenials
-        this.execution.structuredOutputPresent = detail?.structuredOutputPresent ?? this.execution.structuredOutputPresent
-
-        const summary = detail?.summary ?? (
-            status === 'success'
-                ? `Run completed in ${formatDurationMs(this.execution.durationMs)}.`
-                : status === 'cancelled'
-                    ? 'Run cancelled.'
-                    : `Run failed after ${formatDurationMs(this.execution.durationMs)}.`
-        )
-        this.currentActivity = summary
-
-        const lastStep = this.steps.at(-1)
-        if (!lastStep || lastStep.kind !== 'result' || lastStep.summary !== summary) {
-            this.addStep('result', summary, detail?.errors?.join('\n'), status !== 'success')
-        }
-
-        return this.snapshot()
-    }
-
-    snapshot(): RunExecutionSnapshot {
-        return {
-            repoRoot: this.prepared.repoRoot,
-            mode: this.mode,
-            model: this.model,
-            artifactPath: this.prepared.resultPath,
-            startedAtMs: this.startedAtMs,
-            status: this.status,
-            currentActivity: this.currentActivity,
-            steps: this.steps.map(step => ({ ...step })),
-            activeTools: Array.from(this.activeTools.values()).map(tool => ({ ...tool })),
-            execution: {
-                status: this.execution.status,
-                durationMs: this.execution.durationMs,
-                durationApiMs: this.execution.durationApiMs,
-                numTurns: this.execution.numTurns,
-                stopReason: this.execution.stopReason,
-                totalCostUsd: this.execution.totalCostUsd,
-                permissionDenials: [...this.execution.permissionDenials],
-                errors: [...this.execution.errors],
-                notableEvents: [...this.execution.notableEvents],
-                structuredOutputPresent: this.execution.structuredOutputPresent,
-            },
-        }
-    }
-}
-
-class PlainTranscriptRenderer {
-    private readonly nextMilestoneIndex = new Map<string, number>()
-
-    render(
-        event: RunEvent,
-        snapshot: RunExecutionSnapshot,
-        verbose = false,
-    ): string[] {
-        switch (event.kind) {
-            case 'session_init':
-                return [snapshot.model ? `Claude session started (${snapshot.model}).` : event.summary]
-            case 'assistant_text':
-                return splitVisibleLines(event.text).map(line => `Assistant: ${line}`)
-            case 'tool_batch': {
-                const lines = [`Tools: ${event.summary}`]
-                if (verbose && event.detail) {
-                    lines.push(...splitVisibleLines(event.detail).map(line => `  ${line}`))
-                }
-                return lines
-            }
-            case 'tool_progress': {
-                const nextIndex = this.nextMilestoneIndex.get(event.toolUseId) ?? 0
-                const milestone = TOOL_PROGRESS_MILESTONES[nextIndex]
-                const shouldEmit = milestone != null
-                    ? event.elapsedSeconds >= milestone
-                    : event.elapsedSeconds % 60 === 0
-                if (!shouldEmit) {
-                    return []
-                }
-
-                if (milestone != null) {
-                    this.nextMilestoneIndex.set(event.toolUseId, nextIndex + 1)
-                }
-
-                return [`Working: ${event.toolName} (${formatElapsedSeconds(event.elapsedSeconds)})`]
-            }
-            case 'status_notice':
-                return event.recordStep ? [event.summary] : []
-            case 'retry_notice': {
-                const lines = [event.summary]
-                if (event.detail) {
-                    lines.push(`  ${event.detail}`)
-                }
-                return lines
-            }
-            case 'hook_notice':
-                if (!event.recordStep) {
-                    return []
-                }
-                return [event.summary, ...(verbose && event.detail ? splitVisibleLines(event.detail).map(line => `  ${line}`) : [])]
-            case 'task_notice':
-                return [event.summary, ...(verbose && event.detail ? [`  ${event.detail}`] : [])]
-            case 'artifact_notice':
-                if (!event.recordStep && !verbose) {
-                    return []
-                }
-                return [event.summary, ...(verbose && event.detail ? splitVisibleLines(event.detail).map(line => `  ${line}`) : [])]
-            case 'result':
-                return [event.summary]
-            default:
-                return []
-        }
-    }
-}
-
-function parseJsonObjectFile(
-    path: string,
-    content: string,
-    invalidSummary: string,
-): Record<string, unknown> {
-    let parsed: unknown
-    try {
-        parsed = JSON.parse(content)
-    }
-    catch (error) {
-        throw createUserFacingError({
-            code: 'run_invalid_json',
-            summary: invalidSummary,
-            details: error instanceof Error ? error.message : String(error),
-            fixes: [`Fix the JSON syntax in \`${path}\`.`],
-        })
-    }
-
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw createUserFacingError({
-            code: 'run_invalid_json_shape',
-            summary: invalidSummary,
-            fixes: [`Update \`${path}\` so it contains a JSON object.`],
-        })
-    }
-
-    return parsed as Record<string, unknown>
-}
-
-function parseAgentConfig(path: string, content: string): AgentRunConfig {
-    const parsed = parseJsonObjectFile(path, content, 'agent.config.json must be a valid JSON object.')
-
-    if (parsed.model !== undefined && typeof parsed.model !== 'string') {
-        throw createUserFacingError({
-            code: 'run_invalid_model',
-            summary: 'agent.config.json has an invalid `model` value.',
-            fixes: ['Set `model` to a string, or remove it from agent.config.json.'],
-        })
-    }
-
-    if (parsed.isMultiturn !== undefined && typeof parsed.isMultiturn !== 'boolean') {
-        throw createUserFacingError({
-            code: 'run_invalid_multiturn',
-            summary: 'agent.config.json has an invalid `isMultiturn` value.',
-            fixes: ['Set `isMultiturn` to `true` or `false`, or remove it from agent.config.json.'],
-        })
-    }
-
-    if (parsed.maxRounds !== undefined && (!Number.isInteger(parsed.maxRounds) || Number(parsed.maxRounds) <= 0)) {
-        throw createUserFacingError({
-            code: 'run_invalid_max_rounds',
-            summary: 'agent.config.json has an invalid `maxRounds` value.',
-            fixes: ['Set `maxRounds` to a positive integer, or remove it from agent.config.json.'],
-        })
-    }
-
-    const model = typeof parsed.model === 'string' && parsed.model.trim().length > 0
-        ? parsed.model.trim()
-        : undefined
-
-    return {
-        model,
-        isMultiturn: parsed.isMultiturn === true,
-        maxRounds: typeof parsed.maxRounds === 'number' ? parsed.maxRounds : undefined,
-    }
-}
-
-const CLAUDE_RUN_ENV_DENYLIST = new Set([
-    'CLAUDE_CONFIG_DIR',
-    'CLAUDE_ENV_FILE',
-    'ANTHROPIC_MODEL',
-    'ANTHROPIC_CUSTOM_MODEL_OPTION',
-    'ANTHROPIC_CUSTOM_MODEL_OPTION_NAME',
-    'ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION',
-    'ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES',
-    'ANTHROPIC_DEFAULT_OPUS_MODEL',
-    'ANTHROPIC_DEFAULT_OPUS_MODEL_NAME',
-    'ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION',
-    'ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES',
-    'ANTHROPIC_DEFAULT_SONNET_MODEL',
-    'ANTHROPIC_DEFAULT_SONNET_MODEL_NAME',
-    'ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION',
-    'ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES',
-    'ANTHROPIC_DEFAULT_HAIKU_MODEL',
-    'ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME',
-    'ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION',
-    'ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES',
-    'CLAUDE_CODE_SUBAGENT_MODEL',
-])
-
-function buildClaudeRunEnvironment(
-    baseEnv: NodeJS.ProcessEnv = process.env,
-): Record<string, string | undefined> {
-    return Object.fromEntries(
-        Object.entries(baseEnv).filter(([key]) => !CLAUDE_RUN_ENV_DENYLIST.has(key)),
-    )
-}
-
-function buildUnsupportedClaudeVersionError(detail: string | undefined): ReturnType<typeof createUserFacingError> {
-    const requiredVersion = formatClaudeCliVersion(MIN_CLAUDE_VERSION_FOR_PROJECT_SCOPED_RUN)
-
-    return createUserFacingError({
-        code: 'run_claude_version_unsupported',
-        summary: `\`tela run\` requires Claude CLI ${requiredVersion} or newer for project-scoped runs.`,
-        details: detail,
-        fixes: [
-            'Update Claude CLI before using `tela run`.',
-            'Run `claude --version` to confirm the installed version.',
-        ],
-    })
-}
-
-function buildClaudeBaseCommand(prepared: PreparedLocalAgentRun): string[] {
-    const command = [
-        'claude',
-        '--setting-sources',
-        'project',
-    ]
-
-    if (prepared.mcpConfigPath) {
-        command.push('--strict-mcp-config', '--mcp-config', prepared.mcpConfigPath)
-    }
-
-    if (prepared.config.model) {
-        command.push('--model', prepared.config.model)
-    }
-
-    return command
-}
-
-function buildClaudeCommand(
-    prepared: PreparedLocalAgentRun,
-    mode: RunMode,
-): string[] {
-    const command = buildClaudeBaseCommand(prepared)
-
-    if (mode === 'one-shot') {
-        command.push(
-            '-p',
-            '--output-format',
-            'stream-json',
-            '--verbose',
-        )
-    }
-
-    command.push(INITIAL_PROMPT)
-    return command
-}
-
-async function resolveRepositoryRoot(cwd: string): Promise<string> {
-    try {
-        return await getRepositoryRoot(cwd)
-    }
-    catch (error) {
-        if (error instanceof Error && error.message.startsWith('Not a git repository:')) {
-            throw createUserFacingError({
-                code: 'run_outside_repo',
-                summary: 'Run must be executed from inside a git repository.',
-                fixes: [
-                    'Change into an agent repository, or run `tela sync <repo>` first.',
-                ],
-            })
-        }
-
-        throw error
-    }
-}
-
-async function validateRequiredFiles(repoRoot: string): Promise<void> {
-    const missing: string[] = []
-
-    for (const file of REQUIRED_AGENT_FILES) {
-        try {
-            await readFile(join(repoRoot, file), 'utf-8')
-        }
-        catch {
-            missing.push(file)
-        }
-    }
-
-    if (missing.length === 0) {
-        return
-    }
-
-    throw createUserFacingError({
-        code: 'run_missing_contract_files',
-        summary: 'Agent repository is missing required files.',
-        fixes: missing.map(file => `Add \`${file}\` to the repository root.`),
-        evidence: missing.map(file => `Missing: ${join(repoRoot, file)}`),
-    })
-}
-
-export async function prepareLocalAgentRun(options: {
-    cwd?: string
-    commandExists?: typeof commandExists
-    inspectClaudeCli?: typeof inspectClaudeCli
-    runCommand?: typeof runCommand
-} = {}): Promise<PreparedLocalAgentRun> {
-    const cwd = options.cwd ?? process.cwd()
-    const repoRoot = await resolveRepositoryRoot(cwd)
-    const inspectClaudeCliFn = options.inspectClaudeCli ?? inspectClaudeCli
-
-    const claudeInspection = await inspectClaudeCliFn({
-        commandExistsFn: options.commandExists,
-        runCommandFn: options.runCommand,
-    })
-
-    if (!claudeInspection.available) {
-        throw createUserFacingError({
-            code: 'run_claude_missing',
-            summary: 'Claude CLI is not available on PATH.',
-            fixes: ['Install the Claude CLI before using `tela run`.'],
-        })
-    }
-
-    if (!claudeInspection.supportsProjectScopedRun) {
-        throw buildUnsupportedClaudeVersionError(claudeInspection.detail)
-    }
-
-    await validateRequiredFiles(repoRoot)
-
-    const [outputFormatContent, agentConfigContent] = await Promise.all([
-        readFile(join(repoRoot, 'output-format.json'), 'utf-8'),
-        readFile(join(repoRoot, 'agent.config.json'), 'utf-8'),
-    ])
-
-    const outputFormat = parseJsonObjectFile(
-        'output-format.json',
-        outputFormatContent,
-        'output-format.json must be a valid JSON object.',
-    )
-    const config = parseAgentConfig('agent.config.json', agentConfigContent)
-    const resultKind = Object.keys(outputFormat).length > 0 ? 'json' : 'markdown'
-
-    return {
-        repoRoot,
-        config,
-        resultKind,
-        resultPath: join(repoRoot, 'output', resultKind === 'json' ? 'result.json' : 'result.md'),
-        mcpConfigPath: existsSync(join(repoRoot, '.mcp.json'))
-            ? join(repoRoot, '.mcp.json')
-            : undefined,
-    }
-}
-
-export function createInitialRunSnapshot(
-    prepared: PreparedLocalAgentRun,
-    mode: RunMode = prepared.config.isMultiturn ? 'chat' : 'one-shot',
-): RunExecutionSnapshot {
-    return {
-        repoRoot: prepared.repoRoot,
-        mode,
-        model: prepared.config.model,
-        artifactPath: prepared.resultPath,
-        startedAtMs: Date.now(),
-        status: 'starting',
-        currentActivity: mode === 'chat'
-            ? 'Preparing Claude chat handoff…'
-            : 'Validating repository contract…',
-        steps: [],
-        activeTools: [],
-        execution: {
-            status: 'starting',
-            permissionDenials: [],
-            errors: [],
-            notableEvents: [],
-            structuredOutputPresent: false,
-        },
-    }
-}
-
-function snapshotStepEvidence(snapshot: RunExecutionSnapshot): string[] {
-    return snapshot.steps
-        .slice(-5)
-        .map(step => step.summary)
-}
-
-function buildRunFailureError(
-    result: CommandResult,
-    snapshot: RunExecutionSnapshot,
-): ReturnType<typeof createUserFacingError> {
-    const details = snapshot.execution.errors[0]
-        ?? result.stderr.trim()
-        ?? result.stdout.trim()
-        ?? `Claude exited with code ${result.exitCode}.`
-
-    return createUserFacingError({
-        code: 'run_failed',
-        summary: 'Claude run failed.',
-        details,
-        fixes: [
-            'Review the streamed Claude output above for the failing step.',
-            'Fix the repository instructions or inputs, then rerun `tela run`.',
-        ],
-        evidence: [
-            `Command: ${result.command.join(' ')}`,
-            ...snapshotStepEvidence(snapshot),
-            ...snapshot.execution.errors,
-            result.stderr.trim() ? `stderr: ${result.stderr.trim()}` : '',
-        ].filter(Boolean),
-    })
-}
-
-function buildRunCancelledError(snapshot: RunExecutionSnapshot): ReturnType<typeof createUserFacingError> {
-    return createUserFacingError({
-        code: 'run_cancelled',
-        summary: 'Claude run was cancelled.',
-        details: snapshot.currentActivity,
-        fixes: ['Run `tela run` again when you are ready to continue.'],
-        evidence: snapshotStepEvidence(snapshot),
-        exitCode: 130,
-    })
-}
-
-async function readResultArtifact(
-    prepared: PreparedLocalAgentRun,
-    snapshot: RunExecutionSnapshot,
-): Promise<RunCommandResult> {
-    let content: string
-    try {
-        content = await readFile(prepared.resultPath, 'utf-8')
-    }
-    catch {
-        throw createUserFacingError({
-            code: 'run_missing_result',
-            summary: `Expected result artifact was not created: ${prepared.resultPath}`,
-            details: joinBlocks([
-                `Last activity: ${snapshot.currentActivity}`,
-                snapshot.execution.numTurns != null ? `Turns: ${snapshot.execution.numTurns}` : undefined,
-            ]),
-            fixes: [
-                'Ensure the agent writes the required output file before exiting.',
-                'Rerun `tela run` after fixing the repository instructions.',
-            ],
-            evidence: snapshotStepEvidence(snapshot),
-        })
-    }
-
-    let resultValue: unknown = content
-    if (prepared.resultKind === 'json') {
-        try {
-            resultValue = JSON.parse(content)
-        }
-        catch (error) {
-            throw createUserFacingError({
-                code: 'run_invalid_result_json',
-                summary: 'output/result.json is not valid JSON.',
-                details: error instanceof Error ? error.message : String(error),
-                fixes: ['Ensure the agent writes valid JSON to output/result.json.'],
-                evidence: snapshotStepEvidence(snapshot),
-            })
-        }
-    }
-
-    const executionStatus = snapshot.execution.status === 'cancelled'
-        ? 'cancelled'
-        : snapshot.execution.status === 'failed'
-            ? 'failed'
-            : 'success'
-
-    return {
-        ok: true,
-        repoRoot: prepared.repoRoot,
-        mode: prepared.config.isMultiturn ? 'chat' : 'one-shot',
-        config: prepared.config,
-        execution: {
-            ...snapshot.execution,
-            status: executionStatus,
-        },
-        steps: snapshot.steps,
-        artifact: {
-            path: prepared.resultPath,
-            kind: prepared.resultKind,
-            value: resultValue,
-        },
-        resultPath: prepared.resultPath,
-        resultKind: prepared.resultKind,
-        resultValue,
-    }
-}
-
-async function runInteractiveAgent(
-    prepared: PreparedLocalAgentRun,
-    runInteractiveCommandFn: typeof runInteractiveCommand,
-    options: RunLocalAgentCommandOptions,
-): Promise<void> {
-    if (options.surface === 'json') {
-        throw createUserFacingError({
-            code: 'run_multiturn_json_unsupported',
-            summary: 'Multiturn run requires an interactive TTY in the current hybrid design.',
-            fixes: ['Run `tela run` from an interactive terminal without `--json`.'],
-        })
-    }
-
-    const stdinIsTTY = options.stdinIsTTY ?? Boolean(process.stdin.isTTY)
-    const stdoutIsTTY = options.stdoutIsTTY ?? Boolean(process.stdout.isTTY)
-    if (!stdinIsTTY || !stdoutIsTTY) {
-        throw createUserFacingError({
-            code: 'run_multiturn_tty_required',
-            summary: 'Multiturn run requires an interactive TTY in the current hybrid design.',
-            fixes: ['Run `tela run` from an interactive terminal.'],
-        })
-    }
-
-    if (options.surface === 'plain') {
-        writeLine(options.writeStdout, 'Launching Claude in interactive chat mode. Tela will resume after Claude exits.')
-    }
-
-    await runInteractiveCommandFn(buildClaudeCommand(prepared, 'chat'), {
-        cwd: prepared.repoRoot,
-        env: buildClaudeRunEnvironment(),
-    })
-}
-
-async function runOneShotAgent(
-    prepared: PreparedLocalAgentRun,
-    options: RunLocalAgentCommandOptions,
-    tracker: RunStateTracker,
-): Promise<RunExecutionSnapshot> {
-    const plainRenderer = new PlainTranscriptRenderer()
-    const runStreamingCommandFn = options.runStreamingCommand ?? runStreamingCommand
-    const spawnStreamingCommandFn = options.spawnStreamingCommand ?? ((command: string[], spawnOptions?: RunStreamingCommandOptions): StreamingCommandHandle => ({
-        result: runStreamingCommandFn(command, spawnOptions),
-        interrupt() {},
-        kill() {},
-    }))
-
-    const notifySnapshot = (snapshot: RunExecutionSnapshot) => {
-        options.onSnapshot?.(snapshot)
-    }
-
-    notifySnapshot(tracker.snapshot())
-
-    if (options.surface === 'plain') {
-        writeLine(options.writeStdout, 'Streaming Claude execution in one-shot mode.')
-    }
-
-    let cancelled = false
-    const command = buildClaudeCommand(prepared, 'one-shot')
-
-    const handle = spawnStreamingCommandFn(command, {
-        cwd: prepared.repoRoot,
-        env: buildClaudeRunEnvironment(),
-        allowFailure: true,
-        onStdoutLine: async (line) => {
-            const trimmed = line.trim()
-            if (!trimmed) {
-                return
-            }
-
-            try {
-                const parsed = JSON.parse(trimmed) as Record<string, unknown>
-                const events = normalizeClaudePrintEvent(parsed)
-                for (const event of events) {
-                    const snapshot = tracker.update(event)
-                    notifySnapshot(snapshot)
-                    if (options.surface === 'plain') {
-                        for (const renderedLine of plainRenderer.render(event, snapshot, options.verbose)) {
-                            writeLine(options.writeStdout, renderedLine)
-                        }
-                    }
-                }
-            }
-            catch {
-                if (options.surface === 'plain') {
-                    writeLine(options.writeStdout, `Claude: ${trimmed}`)
-                }
-            }
-        },
-        onStderrLine: async (line) => {
-            const trimmed = line.trim()
-            if (!trimmed) {
-                return
-            }
-
-            if (options.surface === 'plain') {
-                writeErrorLine(options.writeStderr, trimmed)
-            }
-        },
-    })
-
-    options.onControl?.({
-        interrupt() {
-            cancelled = true
-            handle.interrupt()
-        },
-        kill() {
-            cancelled = true
-            handle.kill()
-        },
-    })
-
-    const result = await handle.result
-    let snapshot = tracker.snapshot()
-
-    if (result.exitCode !== 0) {
-        if (cancelled) {
-            snapshot = tracker.finalize('cancelled', {
-                summary: 'Run cancelled.',
-            })
-            notifySnapshot(snapshot)
-            throw buildRunCancelledError(snapshot)
-        }
-
-        snapshot = tracker.finalize('failed')
-        notifySnapshot(snapshot)
-        throw buildRunFailureError(result, snapshot)
-    }
-
-    if (snapshot.execution.status === 'running' || snapshot.execution.status === 'starting') {
-        snapshot = tracker.finalize('success')
-        notifySnapshot(snapshot)
-    }
-
-    if (snapshot.execution.status === 'failed') {
-        throw buildRunFailureError(result, snapshot)
-    }
-
-    return snapshot
-}
-
-export async function runLocalAgentCommand(
-    options: RunLocalAgentCommandOptions = {},
-): Promise<RunCommandResult> {
-    const surface = options.surface ?? 'plain'
-    const effectiveOptions: RunLocalAgentCommandOptions = {
-        ...options,
-        surface,
-    }
-    const prepared = options.contract ?? await prepareLocalAgentRun({
-        cwd: options.cwd ?? process.cwd(),
-        commandExists: options.commandExists,
-        inspectClaudeCli: options.inspectClaudeCli,
-        runCommand: options.runCommand,
-    })
-    const mode: RunMode = prepared.config.isMultiturn ? 'chat' : 'one-shot'
-    const tracker = new RunStateTracker(prepared, mode)
-
-    let snapshot = tracker.snapshot()
-    effectiveOptions.onSnapshot?.(snapshot)
-
-    if (prepared.config.isMultiturn) {
-        await runInteractiveAgent(prepared, options.runInteractiveCommand ?? runInteractiveCommand, effectiveOptions)
-        snapshot = tracker.finalize('success', {
-            summary: 'Claude chat exited. Reading result artifact…',
-        })
-        effectiveOptions.onSnapshot?.(snapshot)
-    }
-    else {
-        snapshot = await runOneShotAgent(prepared, effectiveOptions, tracker)
-    }
-
-    return await readResultArtifact(prepared, snapshot)
-}
-
-function renderExecutionSteps(result: RunCommandResult, options: RenderOptions): string | undefined {
-    const recentSteps = result.steps.slice(-8).map(step => step.summary)
-    if (recentSteps.length === 0) {
-        return undefined
-    }
-
-    return section('Recent steps', bulletList(recentSteps), options)
-}
-
-export function renderRunExecutionRecap(
-    result: RunCommandResult,
-    options: RenderOptions = {},
-): string {
-    return resultCard('Execution recap', [
-        section('Execution', kvList([
-            { label: 'Repo root', value: result.repoRoot },
-            { label: 'Mode', value: result.mode },
-            { label: 'Model', value: result.config.model ?? '<default>' },
-            { label: 'Elapsed', value: formatDurationMs(result.execution.durationMs) },
-            { label: 'Turns', value: result.execution.numTurns != null ? String(result.execution.numTurns) : '<unknown>' },
-            { label: 'Status', value: result.execution.status },
-            { label: 'Stop reason', value: result.execution.stopReason ?? '<none>' },
-            { label: 'Cost', value: result.execution.totalCostUsd != null ? `$${result.execution.totalCostUsd.toFixed(4)}` : '<unknown>' },
-            {
-                label: 'maxRounds',
-                value: result.config.maxRounds != null
-                    ? `${result.config.maxRounds} (ignored in local CLI)`
-                    : '<unspecified>',
-            },
-        ], options), options),
-        result.execution.notableEvents.length > 0
-            ? section('Notable events', bulletList(result.execution.notableEvents), options)
-            : undefined,
-        result.execution.permissionDenials.length > 0
-            ? section('Permission denials', bulletList(result.execution.permissionDenials), options)
-            : undefined,
-        result.execution.errors.length > 0
-            ? section('Errors', bulletList(result.execution.errors), options)
-            : undefined,
-        renderExecutionSteps(result, options),
-    ], options)
-}
-
-export function renderRunArtifactCard(
-    result: RunCommandResult,
-    options: RenderOptions = {},
-): string {
-    const resultContent = result.resultKind === 'json'
-        ? JSON.stringify(result.resultValue, null, 2)
-        : String(result.resultValue)
-
-    return resultCard('Run result', [
-        section('Artifact', kvList([
-            { label: 'Path', value: result.resultPath },
-            { label: 'Kind', value: result.resultKind },
-        ], options), options),
-        section('Result', resultContent, options),
-    ], options)
-}
-
-export function renderRunResult(
-    result: RunCommandResult,
-    options: RenderOptions = {},
-): string {
-    return joinBlocks([
-        renderRunExecutionRecap(result, options),
-        renderRunArtifactCard(result, options),
-    ])
-}