@meistrari/tela-cli 0.1.0

package/src/commands/run.ts

@@ -0,0 +1,1601 @@
+import { readFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { getRepositoryRoot } from '../git.ts'
+import { createUserFacingError } from '../errors.ts'
+import {
+    commandExists,
+    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
+}
+
+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
+    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,
+    }
+}
+
+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
+} = {}): Promise<PreparedLocalAgentRun> {
+    const cwd = options.cwd ?? process.cwd()
+    const commandExistsFn = options.commandExists ?? commandExists
+    const repoRoot = await resolveRepositoryRoot(cwd)
+
+    if (!await commandExistsFn('claude')) {
+        throw createUserFacingError({
+            code: 'run_claude_missing',
+            summary: 'Claude CLI is not available on PATH.',
+            fixes: ['Install the Claude CLI before using `tela run`.'],
+        })
+    }
+
+    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'),
+    }
+}
+
+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.')
+    }
+
+    const command = [
+        'claude',
+        ...(prepared.config.model ? ['--model', prepared.config.model] : []),
+        INITIAL_PROMPT,
+    ]
+
+    await runInteractiveCommandFn(command, { cwd: prepared.repoRoot })
+}
+
+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 = [
+        'claude',
+        '-p',
+        '--output-format',
+        'stream-json',
+        '--verbose',
+        ...(prepared.config.model ? ['--model', prepared.config.model] : []),
+        INITIAL_PROMPT,
+    ]
+
+    const handle = spawnStreamingCommandFn(command, {
+        cwd: prepared.repoRoot,
+        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,
+    })
+    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),
+    ])
+}