@meistrari/tela-cli 0.1.0

package/src/program.ts

@@ -0,0 +1,1872 @@
+import { existsSync, mkdirSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import React from 'react'
+import { Command } from 'commander'
+import {
+    createInkBarkSession,
+    shouldShowBarkIntro,
+    type BarkIntroSession,
+} from './ink/bark.tsx'
+import {
+    FeedbackClaudeHandoffScreen,
+    FeedbackOutcomeScreen,
+    FeedbackSelectionScreen,
+} from './ink/screens/feedback-screen.tsx'
+import { PushScreen } from './ink/screens/push-screen.tsx'
+import { RunChatHandoffScreen, RunScreen } from './ink/screens/run-screen.tsx'
+import { SetupScreen, type SetupScreenResult } from './ink/screens/setup-screen.tsx'
+import { SyncScreen, type SyncProgressItem } from './ink/screens/sync-screen.tsx'
+import { renderCommandScreen } from './ink/runtime.tsx'
+import {
+    checkAgentApiReachability,
+    getAgentApiOriginCheckStatus,
+    getAgentApiOriginWarning,
+} from './diagnostics.ts'
+import { createUserFacingError } from './errors.ts'
+import {
+    getCommandMetadata,
+    listCommandMetadata,
+    type CommandMetadata,
+} from './commands/metadata.ts'
+import {
+    buildFeedbackRunResult,
+    buildFeedbackNextActions,
+    buildFeedbackReviewModel,
+    buildClaudeFeedbackPrompt,
+    describeFeedbackEmptyState,
+    describeFeedbackSelectionMode,
+    getFeedbackSelectionMode,
+    launchFeedbackClaude,
+    loadFeedbackData,
+    runFeedbackCommand,
+    type FeedbackCommandFlags,
+    type FeedbackData,
+    type FeedbackRunResult,
+    type PromptModule as FeedbackPromptModule,
+} from './commands/feedback.ts'
+import {
+    previewPush,
+    pushRepository,
+    type PushPreview,
+} from './commands/push.ts'
+import {
+    createInitialRunSnapshot,
+    prepareLocalAgentRun,
+    renderRunArtifactCard,
+    renderRunExecutionRecap,
+    runLocalAgentCommand,
+    type RunCommandResult,
+} from './commands/run.ts'
+import {
+    categorizeSyncError,
+    listCloneRootRepositories,
+    syncAllRepositories,
+    syncCurrentRepository,
+    syncRepository,
+    type SyncAllProgressEvent,
+    type SyncFailureCategory,
+} from './commands/sync.ts'
+import { getDoctorReport, renderDoctorReport } from './commands/doctor.ts'
+import { getStatusReport, renderStatusReport } from './commands/status.ts'
+import {
+    AGENT_API_BROWSER_HELP,
+    DEFAULT_AGENT_API_URL,
+    ensureConfigInteractive,
+    getDefaultCloneRoot,
+    inspectSavedConfig,
+    redactApiKey,
+    saveConfig,
+    validateAgentApiUrl,
+    validateApiKey,
+    validateCloneRoot,
+    setupConfigInteractive,
+    type ConfigInspection,
+} from './config.ts'
+import { findRepositoryRoot, getDiffStatAgainstHead } from './git.ts'
+import { commandExists, runInteractiveCommand, runStreamingCommand } from './process.ts'
+import { CommandRuntime } from './runtime.ts'
+import type {
+    BatchSyncFailure,
+    SyncResult,
+    TelaCliConfig,
+} from './types.ts'
+import {
+    bulletList,
+    bootstrapPane,
+    joinBlocks,
+    kvList,
+    nextActions,
+    resultCard,
+    section,
+    stepList,
+    table,
+} from './ui.ts'
+
+type PromptModule = FeedbackPromptModule
+
+function promptValue<T>(value: T | symbol): T {
+    return value as T
+}
+
+interface CliDeps {
+    prompts?: PromptModule
+    ensureConfigInteractive?: typeof ensureConfigInteractive
+    setupConfigInteractive?: typeof setupConfigInteractive
+    inspectSavedConfig?: typeof inspectSavedConfig
+    findRepositoryRoot?: typeof findRepositoryRoot
+    syncRepository?: typeof syncRepository
+    syncAllRepositories?: typeof syncAllRepositories
+    syncCurrentRepository?: typeof syncCurrentRepository
+    listCloneRootRepositories?: typeof listCloneRootRepositories
+    previewPush?: typeof previewPush
+    pushRepository?: typeof pushRepository
+    runLocalAgentCommand?: typeof runLocalAgentCommand
+    runFeedbackCommand?: typeof runFeedbackCommand
+    loadFeedbackData?: typeof loadFeedbackData
+    launchFeedbackClaude?: typeof launchFeedbackClaude
+    prepareLocalAgentRun?: typeof prepareLocalAgentRun
+    getDiffStatAgainstHead?: typeof getDiffStatAgainstHead
+    getStatusReport?: typeof getStatusReport
+    getDoctorReport?: typeof getDoctorReport
+    createInkBarkSession?: typeof createInkBarkSession
+    commandExists?: typeof commandExists
+    runInteractiveCommand?: typeof runInteractiveCommand
+    runStreamingCommand?: typeof runStreamingCommand
+    fetchFn?: typeof fetch
+    writeStdout?: (message: string) => void
+    writeStderr?: (message: string) => void
+}
+
+interface GlobalCliOptions {
+    json?: boolean
+    verbose?: boolean
+    silentBark?: boolean
+}
+
+interface SyncCommandOptions extends GlobalCliOptions {
+    all?: boolean
+    current?: boolean
+    dryRun?: boolean
+}
+
+interface PushCommandOptions extends GlobalCliOptions {
+    message?: string
+    claude?: boolean
+    manual?: boolean
+    dryRun?: boolean
+}
+
+interface SetupCommandResult {
+    ok: true
+    config: TelaCliConfig
+    warnings: string[]
+    nextActions: string[]
+}
+
+interface SyncCommandResult {
+    ok: boolean
+    mode: 'current' | 'repository' | 'all'
+    successes: SyncResult[]
+    failures: BatchSyncFailure[]
+    nextActions: string[]
+}
+
+interface PushCommandResult {
+    ok: boolean
+    branch?: string
+    commitMessage?: string
+    commitSha?: string
+    retriedCommit?: boolean
+    nextActions: string[]
+}
+
+type StatusCommandOptions = GlobalCliOptions
+type DoctorCommandOptions = GlobalCliOptions
+interface RunCommandOptions extends GlobalCliOptions {
+    plain?: boolean
+}
+
+function renderOptionsForStdout(): { decorate: boolean } {
+    return { decorate: Boolean(process.stdout.isTTY) }
+}
+
+function isInteractiveInkSession(options: GlobalCliOptions = {}): boolean {
+    return !options.json && Boolean(process.stdout.isTTY && process.stdin.isTTY)
+}
+
+function resolveRunSurface(options: RunCommandOptions = {}): 'plain' | 'viewer' | 'json' {
+    if (options.json) {
+        return 'json'
+    }
+
+    if (options.plain || !isInteractiveInkSession(options)) {
+        return 'plain'
+    }
+
+    return 'viewer'
+}
+
+function getPromptModule(deps: CliDeps): PromptModule {
+    if (!deps.prompts) {
+        throw createUserFacingError({
+            code: 'interactive_prompt_unavailable',
+            summary: 'This command requires an interactive TTY for the requested flow.',
+            fixes: [
+                'Run the command in a terminal, or provide the flags needed for non-interactive execution.',
+            ],
+        })
+    }
+
+    return deps.prompts
+}
+
+function createRuntime(deps: CliDeps, options: GlobalCliOptions = {}): CommandRuntime {
+    return new CommandRuntime({
+        json: options.json,
+        verbose: options.verbose,
+        prompts: deps.prompts,
+        writeStdout: deps.writeStdout,
+        writeStderr: deps.writeStderr,
+    })
+}
+
+function renderExamples(command: CommandMetadata): string {
+    return command.examples
+        .map(example => `${example.command.padEnd(36, ' ')} ${example.description}`)
+        .join('\n')
+}
+
+function renderRootHelp(program: Command): string {
+    const renderOptions = renderOptionsForStdout()
+    const commands = listCommandMetadata().map(command => [
+        `tela ${command.name}${command.argumentHint ? ` ${command.argumentHint}` : ''}`,
+        command.summary,
+    ])
+
+    return joinBlocks([
+        bootstrapPane('Tela CLI', [
+            'One-shot workflows for setting up Tela, syncing repositories, running local agents, preparing pushes, and applying commit feedback.',
+            '',
+            'First successful path:',
+            stepList([
+                'tela setup',
+                'tela status',
+                'tela sync <repo> or tela sync --current',
+                'tela run',
+                'tela push',
+                'tela feedback --list',
+            ]),
+        ], renderOptions),
+        section('Commands', table(['Command', 'Summary'], commands, renderOptions), renderOptions),
+        section('Global flags', table(
+            ['Flag', 'Description'],
+            [
+                ['--silent-bark', 'Disable bark audio during interactive Ink startup'],
+                ['--verbose', 'Include raw evidence for failures where available'],
+                ['-h, --help', 'Show command help'],
+            ],
+            renderOptions,
+        ), renderOptions),
+    ])
+}
+
+function renderCommandHelp(command: Command): string {
+    const renderOptions = renderOptionsForStdout()
+    const metadata = getCommandMetadata(command.name())
+    if (!metadata) {
+        return renderRootHelp(command.parent ?? command)
+    }
+
+    const usage = `tela ${metadata.name}${metadata.argumentHint ? ` ${metadata.argumentHint}` : ''}`
+    const localOptionRows = command.options
+        .filter(option => option.long !== '--help')
+        .map(option => [option.flags, option.description || ''])
+    const globalOptionRows = (command.parent?.options ?? [])
+        .filter(option => option.long !== '--help')
+        .map(option => [option.flags, option.description || ''])
+    const optionRows = [...localOptionRows, ...globalOptionRows]
+
+    return joinBlocks([
+        bootstrapPane(`tela ${metadata.name}`, [
+            metadata.summary,
+            '',
+            `Usage: ${usage}`,
+            '',
+            metadata.whenToUse,
+        ], renderOptions),
+        optionRows.length > 0
+            ? section('Flags', table(['Flag', 'Description'], optionRows, renderOptions), renderOptions)
+            : undefined,
+        section('Examples', renderExamples(metadata), renderOptions),
+        section('Related', metadata.relatedCommands.map(name => `tela ${name}`).join('\n'), renderOptions),
+        nextActions([
+            `Run \`${usage}\` when the command inputs are ready.`,
+            `Use \`tela doctor\` if the command fails unexpectedly.`,
+        ], renderOptions),
+    ])
+}
+
+function installCustomHelp(program: Command): void {
+    program.configureHelp({
+        formatHelp: (command) => command.parent ? renderCommandHelp(command) : renderRootHelp(command),
+    })
+}
+
+function createBarkSession(
+    deps: CliDeps,
+    options: GlobalCliOptions,
+    commandTitle: string,
+): BarkIntroSession {
+    const createSession = deps.createInkBarkSession ?? createInkBarkSession
+    return createSession({
+        commandTitle,
+        enabled: shouldShowBarkIntro({
+            json: options.json,
+            stdinIsTTY: process.stdin.isTTY,
+            stdoutIsTTY: process.stdout.isTTY,
+        }),
+        silentBark: options.silentBark,
+        env: process.env,
+        platform: process.platform,
+    })
+}
+
+function emitBootstrap(runtime: CommandRuntime, title: string, summary: string): void {
+    runtime.emit(bootstrapPane(title, summary, { decorate: runtime.decorate }))
+}
+
+function ensureNotCancelled(prompts: PromptModule, value: unknown, message: string): void {
+    if (!prompts.isCancel(value)) {
+        return
+    }
+
+    prompts.cancel(message)
+    throw createUserFacingError({
+        code: 'cancelled',
+        summary: message,
+        fixes: ['Run the command again when you are ready.'],
+    })
+}
+
+function summarizeConfigInspection(inspection: ConfigInspection): string {
+    if (!inspection.exists) {
+        return kvList([
+            { label: 'Config path', value: inspection.path },
+            { label: 'Status', value: 'missing' },
+            { label: 'Clone root', value: getDefaultCloneRoot() },
+        ])
+    }
+
+    if (!inspection.valid || !inspection.config) {
+        return kvList([
+            { label: 'Config path', value: inspection.path },
+            { label: 'Status', value: 'invalid' },
+            { label: 'Error', value: inspection.error ?? 'Unknown config error' },
+        ])
+    }
+
+    return kvList([
+        { label: 'Config path', value: inspection.path },
+        { label: 'Agent API origin', value: inspection.config.agentApiUrl },
+        { label: 'Clone root', value: inspection.config.cloneRoot },
+        { label: 'API key', value: redactApiKey(inspection.config.apiKey) },
+    ])
+}
+
+function buildSetupChecksRows(checks: Array<{ label: string, status: string, detail: string }>): string[][] {
+    return checks.map(check => [check.label, check.status, check.detail])
+}
+
+function ensureCloneRootReady(prompts: PromptModule, cloneRoot: string): { created: boolean, warning?: string } {
+    if (!existsSync(cloneRoot)) {
+        return { created: false }
+    }
+
+    const stats = statSync(cloneRoot)
+    if (!stats.isDirectory()) {
+        throw createUserFacingError({
+            code: 'clone_root_invalid',
+            summary: `Clone root exists but is not a directory: ${cloneRoot}`,
+            fixes: [
+                `Move or remove \`${cloneRoot}\`, then rerun \`tela setup\`.`,
+            ],
+        })
+    }
+
+    return { created: false }
+}
+
+async function executeSetupFlow(
+    input: {
+        agentApiUrl: string
+        cloneRoot: string
+        apiKey: string
+        createCloneRoot: boolean
+    },
+    deps: CliDeps = {},
+): Promise<SetupScreenResult> {
+    const commandExistsFn = deps.commandExists ?? commandExists
+    const fetchFn = deps.fetchFn ?? fetch
+    const inspection = (deps.inspectSavedConfig ?? inspectSavedConfig)()
+    const config = {
+        agentApiUrl: input.agentApiUrl,
+        cloneRoot: input.cloneRoot,
+        apiKey: input.apiKey.trim() || inspection.config?.apiKey || '',
+    }
+
+    const cloneRootExists = existsSync(config.cloneRoot)
+    if (!cloneRootExists && input.createCloneRoot) {
+        mkdirSync(config.cloneRoot, { recursive: true, mode: 0o755 })
+    }
+
+    saveConfig(config)
+
+    const [gitAvailable, claudeAvailable, reachability] = await Promise.all([
+        commandExistsFn('git'),
+        commandExistsFn('claude'),
+        checkAgentApiReachability(config.agentApiUrl, fetchFn),
+    ])
+
+    const warnings = [
+        !existsSync(config.cloneRoot) ? `Clone root does not exist yet: ${config.cloneRoot}` : undefined,
+        gitAvailable ? undefined : '`git` is not available on PATH.',
+        claudeAvailable ? undefined : '`claude` is not available on PATH.',
+        getAgentApiOriginWarning(reachability),
+    ].filter((warning): warning is string => Boolean(warning))
+    const checks = [
+        { label: 'clone-root', status: existsSync(config.cloneRoot) ? 'ready' : 'missing', detail: config.cloneRoot },
+        { label: 'git', status: gitAvailable ? 'available' : 'missing', detail: gitAvailable ? 'ready' : 'install git' },
+        { label: 'claude', status: claudeAvailable ? 'available' : 'missing', detail: claudeAvailable ? 'ready' : 'install Claude CLI' },
+        { label: 'agent-api-origin', status: getAgentApiOriginCheckStatus(reachability), detail: reachability.detail },
+    ]
+
+    return {
+        ok: true,
+        config,
+        warnings,
+        nextActions: [
+            'Run `tela status` to review the saved environment.',
+            existsSync(config.cloneRoot)
+                ? 'Run `tela sync <repo>` or `tela sync --current` when you need a checkout.'
+                : 'Create the clone root or rerun setup before the first repository sync.',
+            claudeAvailable
+                ? 'Use `tela run`, `tela push`, and `tela feedback` when you want Claude-assisted workflows.'
+                : 'Install the Claude CLI before using `tela run`, `tela feedback`, or Claude-generated commit messages.',
+        ],
+        checks,
+    }
+}
+
+async function runSetupInk(
+    deps: CliDeps = {},
+    options: GlobalCliOptions = {},
+    barkSession = createBarkSession(deps, options, 'Setup'),
+): Promise<SetupScreenResult> {
+    const inspection = (deps.inspectSavedConfig ?? inspectSavedConfig)()
+    await barkSession.playOnce()
+    return await renderCommandScreen<SetupScreenResult>((controller) => React.createElement(SetupScreen, {
+        controller,
+        currentConfigSummary: summarizeConfigInspection(inspection).split('\n'),
+        defaults: {
+            agentApiUrl: inspection.config?.agentApiUrl ?? DEFAULT_AGENT_API_URL,
+            cloneRoot: inspection.config?.cloneRoot ?? getDefaultCloneRoot(),
+            apiKey: inspection.config?.apiKey ?? '',
+        },
+        hasExistingApiKey: Boolean(inspection.config?.apiKey),
+        validateAgentApiUrl,
+        validateCloneRoot,
+        validateApiKey,
+        inspectCloneRoot: (path: string) => {
+            if (!existsSync(path)) {
+                return { exists: false, isDirectory: false }
+            }
+
+            return {
+                exists: true,
+                isDirectory: statSync(path).isDirectory(),
+            }
+        },
+        execute: async (input: {
+            agentApiUrl: string
+            cloneRoot: string
+            apiKey: string
+            createCloneRoot: boolean
+        }) => await executeSetupFlow(input, deps),
+    }))
+}
+
+async function ensureConfigForCommand(
+    deps: CliDeps,
+    options: GlobalCliOptions,
+    barkSession?: BarkIntroSession,
+): Promise<TelaCliConfig> {
+    const inspection = (deps.inspectSavedConfig ?? inspectSavedConfig)()
+    if (inspection.valid && inspection.config) {
+        return inspection.config
+    }
+
+    if (isInteractiveInkSession(options)) {
+        const setupResult = await runSetupInk(
+            deps,
+            options,
+            barkSession ?? createBarkSession(deps, options, 'Setup'),
+        )
+        return setupResult.config
+    }
+
+    if (deps.prompts) {
+        const ensureConfig = deps.ensureConfigInteractive ?? ensureConfigInteractive
+        return await ensureConfig({ prompts: deps.prompts })
+    }
+
+    throw createUserFacingError({
+        code: 'config_required',
+        summary: 'Tela CLI is not configured.',
+        fixes: [
+            'Run `tela setup` in an interactive terminal first.',
+        ],
+    })
+}
+
+export async function runSetup(
+    deps: CliDeps = {},
+    options: GlobalCliOptions = {},
+): Promise<SetupCommandResult> {
+    if (isInteractiveInkSession(options)) {
+        return await runSetupInk(deps, options)
+    }
+
+    const prompts = getPromptModule(deps)
+    const runtime = createRuntime(deps, options)
+    const setup = deps.setupConfigInteractive ?? setupConfigInteractive
+    const inspect = deps.inspectSavedConfig ?? inspectSavedConfig
+    const commandExistsFn = deps.commandExists ?? commandExists
+    const fetchFn = deps.fetchFn ?? fetch
+    const inspection = inspect()
+
+    prompts.intro('Tela CLI setup')
+    emitBootstrap(runtime, 'Tela setup', 'Bootstrap the local Tela environment before the first sync or push.')
+    runtime.emit(resultCard('Setup preflight', [
+        section('Current config', summarizeConfigInspection(inspection), { decorate: runtime.decorate }),
+        section('Agent API', AGENT_API_BROWSER_HELP, { decorate: runtime.decorate }),
+        section('What setup updates', bulletList([
+            'Agent API target and origin URL',
+            'Clone root directory',
+            'API key',
+        ]), { decorate: runtime.decorate }),
+    ], { decorate: runtime.decorate }))
+
+    const config = await setup({
+        prompts,
+        existingConfig: inspection.config ?? null,
+        skipLifecycle: true,
+    })
+
+    let cloneRootCreated = false
+    let cloneRootWarning: string | undefined
+    const cloneRootStatus = ensureCloneRootReady(prompts, config.cloneRoot)
+    cloneRootWarning = cloneRootStatus.warning
+
+    if (!existsSync(config.cloneRoot)) {
+        const createCloneRoot = await prompts.confirm({
+            message: `Create clone root directory at ${config.cloneRoot}?`,
+            active: 'create',
+            inactive: 'skip',
+            initialValue: true,
+        })
+        ensureNotCancelled(prompts, createCloneRoot, 'Setup cancelled.')
+
+        if (promptValue(createCloneRoot)) {
+            mkdirSync(config.cloneRoot, { recursive: true, mode: 0o755 })
+            cloneRootCreated = true
+        }
+        else {
+            cloneRootWarning = `Clone root does not exist yet: ${config.cloneRoot}`
+        }
+    }
+
+    const [gitAvailable, claudeAvailable, reachability] = await Promise.all([
+        commandExistsFn('git'),
+        commandExistsFn('claude'),
+        checkAgentApiReachability(config.agentApiUrl, fetchFn),
+    ])
+
+    const warnings = [
+        cloneRootWarning,
+        gitAvailable ? undefined : '`git` is not available on PATH.',
+        claudeAvailable ? undefined : '`claude` is not available on PATH.',
+        getAgentApiOriginWarning(reachability),
+    ].filter((warning): warning is string => Boolean(warning))
+
+    const nextSetupActions = [
+        'Run `tela status` to review the saved environment.',
+        cloneRootCreated
+            ? 'Run `tela sync <repo>` to clone a repository into the new clone root.'
+            : 'Run `tela sync <repo>` or `tela sync --current` when you need a checkout.',
+        claudeAvailable
+            ? 'Use `tela run`, `tela push`, and `tela feedback` when you want Claude-assisted workflows.'
+            : 'Install the Claude CLI before using `tela run`, `tela feedback`, or Claude-generated commit messages.',
+    ]
+
+    runtime.emit(resultCard('Setup complete', [
+        section('Saved config', kvList([
+            { label: 'Agent API origin', value: config.agentApiUrl },
+            { label: 'Clone root', value: config.cloneRoot },
+            { label: 'API key', value: redactApiKey(config.apiKey) },
+        ]), { decorate: runtime.decorate }),
+        section('Agent API', AGENT_API_BROWSER_HELP, { decorate: runtime.decorate }),
+        section('Checks', table(
+            ['Check', 'Status', 'Detail'],
+            buildSetupChecksRows([
+                { label: 'clone-root', status: cloneRootCreated ? 'created' : (existsSync(config.cloneRoot) ? 'ready' : 'missing'), detail: config.cloneRoot },
+                { label: 'git', status: gitAvailable ? 'available' : 'missing', detail: gitAvailable ? 'ready' : 'install git' },
+                { label: 'claude', status: claudeAvailable ? 'available' : 'missing', detail: claudeAvailable ? 'ready' : 'install Claude CLI' },
+                { label: 'agent-api-origin', status: getAgentApiOriginCheckStatus(reachability), detail: reachability.detail },
+            ]),
+            { decorate: runtime.decorate },
+        ), { decorate: runtime.decorate }),
+        warnings.length > 0
+            ? section('Warnings', bulletList(warnings), { decorate: runtime.decorate })
+            : undefined,
+        nextActions(nextSetupActions, { decorate: runtime.decorate }),
+    ], { decorate: runtime.decorate }))
+    prompts.outro('Tela CLI configured')
+
+    return {
+        ok: true,
+        config,
+        warnings,
+        nextActions: nextSetupActions,
+    }
+}
+
+function syncCategoryFixes(category: SyncFailureCategory): string[] {
+    switch (category) {
+        case 'dirty_worktree':
+            return ['Review or stash local changes before syncing again.']
+        case 'detached_head':
+            return ['Check out a branch before syncing.']
+        case 'origin_mismatch':
+            return ['Verify the repository remote or reclone the checkout with `tela sync <repo>`.']
+        case 'missing_upstream':
+            return ['Push the branch once or set an upstream before syncing the current checkout.']
+        case 'missing_default_branch':
+            return ['Check the remote repository defaults or clone a fresh checkout.']
+        case 'not_git_repository':
+            return ['Remove the path and rerun `tela sync <repo>`, or initialize a valid repository there.']
+        default:
+            return ['Rerun `tela doctor` for more detailed remediation steps.']
+    }
+}
+
+function renderSyncPlan(input: {
+    mode: SyncCommandResult['mode']
+    target: string
+    cloneRoot?: string
+    repositories?: string[]
+    dryRun?: boolean
+}, decorate: boolean): string {
+    return resultCard(input.dryRun ? 'Sync dry run' : 'Sync plan', [
+        section('What will happen', kvList([
+            { label: 'Mode', value: input.mode },
+            { label: 'Target', value: input.target },
+            ...(input.cloneRoot ? [{ label: 'Clone root', value: input.cloneRoot }] : []),
+        ]), { decorate }),
+        input.repositories && input.repositories.length > 0
+            ? section('Repositories', input.repositories.map(repo => `- ${repo}`).join('\n'), { decorate })
+            : undefined,
+        section('Steps', stepList([
+            'Fetch remote updates or clone a missing checkout',
+            'Validate the local repository state before pulling',
+            'Fast-forward the branch when the checkout is clean',
+        ]), { decorate }),
+    ], { decorate })
+}
+
+function groupSyncFailures(failures: BatchSyncFailure[]): string {
+    const grouped = new Map<string, BatchSyncFailure[]>()
+    for (const failure of failures) {
+        const key = failure.category ?? 'other'
+        const current = grouped.get(key) ?? []
+        current.push(failure)
+        grouped.set(key, current)
+    }
+
+    return Array.from(grouped.entries())
+        .map(([category, entries]) => {
+            const fixes = syncCategoryFixes(category as SyncFailureCategory)
+                .map(fix => `  remedy: ${fix}`)
+                .join('\n')
+            const lines = entries.map(entry => `- ${basename(entry.targetDir)}: ${entry.error}`)
+            return [`${category}:`, ...lines, fixes].join('\n')
+        })
+        .join('\n\n')
+}
+
+function renderSyncResult(result: SyncCommandResult, decorate: boolean): string {
+    const successLines = result.successes.map(entry => `- ${basename(entry.targetDir)} (${entry.branch} @ ${entry.head})`)
+    return resultCard(result.ok ? 'Sync complete' : 'Sync finished with recoverable failures', [
+        section('Summary', kvList([
+            { label: 'Mode', value: result.mode },
+            { label: 'Succeeded', value: String(result.successes.length) },
+            { label: 'Failed', value: String(result.failures.length) },
+        ]), { decorate }),
+        successLines.length > 0
+            ? section('Successful repositories', successLines.join('\n'), { decorate })
+            : undefined,
+        result.failures.length > 0
+            ? section('Failures by fix path', groupSyncFailures(result.failures), { decorate })
+            : undefined,
+        nextActions(result.nextActions, { decorate }),
+    ], { decorate })
+}
+
+async function resolveSyncRepositoryName(
+    prompts: PromptModule,
+    cloneRoot: string,
+    listRepositories: typeof listCloneRootRepositories,
+    json: boolean,
+): Promise<string> {
+    const repositories = listRepositories(cloneRoot)
+
+    if (json) {
+        throw createUserFacingError({
+            code: 'sync_repo_required',
+            summary: 'Repository name is required when --json is used outside a git repository.',
+            fixes: [
+                'Pass an explicit repository name, or run `tela sync --current` from inside a repository.',
+            ],
+        })
+    }
+
+    if (repositories.length > 0) {
+        const selection = await prompts.select<string>({
+            message: 'Which repository do you want to sync?',
+            options: [
+                ...repositories.map(repo => ({ value: repo, label: repo })),
+                { value: '__manual__', label: 'Enter a repository name manually' },
+            ],
+            initialValue: repositories[0],
+        })
+        ensureNotCancelled(prompts, selection, 'Sync cancelled.')
+
+        if (promptValue(selection) !== '__manual__') {
+            return promptValue(selection)
+        }
+    }
+
+    const manual = await prompts.text({
+        message: 'Repository name',
+        placeholder: 'agent-api',
+    })
+    ensureNotCancelled(prompts, manual, 'Sync cancelled.')
+
+    const repository = promptValue(manual).trim()
+    if (!repository) {
+        throw createUserFacingError({
+            code: 'sync_repo_required',
+            summary: 'Repository name is required when not running inside a git repository.',
+            fixes: [
+                'Pass a repository name like `tela sync agent-api`, or run `tela sync --current` from inside a repository.',
+            ],
+        })
+    }
+
+    return repository
+}
+
+function buildSyncNextActions(result: SyncCommandResult): string[] {
+    if (result.failures.length > 0) {
+        return [
+            'Fix the repositories listed in the failure section, then rerun `tela sync`.',
+            'Run `tela doctor` if the same checkout keeps failing.',
+        ]
+    }
+
+    return [
+        result.mode === 'all'
+            ? 'Change into one of the synced repositories and start working.'
+            : 'Run `tela push` after you review or update the synced checkout.',
+        'Use `tela status` if you want a fresh environment snapshot.',
+    ]
+}
+
+function validateSyncOptions(
+    repository: string | undefined,
+    options: SyncCommandOptions,
+): void {
+    if (options.all && options.current) {
+        throw createUserFacingError({
+            code: 'sync_flag_conflict',
+            summary: '`--all` cannot be combined with `--current`.',
+            fixes: ['Choose either `tela sync --all` or `tela sync --current`.'],
+        })
+    }
+
+    if (options.all && repository) {
+        throw createUserFacingError({
+            code: 'sync_flag_conflict',
+            summary: 'Repository name cannot be combined with --all.',
+            fixes: ['Use `tela sync <repo>` for one repository, or `tela sync --all` for every checkout.'],
+        })
+    }
+
+    if (options.current && repository) {
+        throw createUserFacingError({
+            code: 'sync_flag_conflict',
+            summary: 'Repository name cannot be combined with --current.',
+            fixes: ['Use `tela sync --current`, or remove `--current` and pass a repository name.'],
+        })
+    }
+}
+
+function resolveSyncMode(
+    repository: string | undefined,
+    options: SyncCommandOptions,
+    repoRoot: string | null,
+): SyncCommandResult['mode'] {
+    if (options.all) {
+        return 'all'
+    }
+
+    if (options.current || (!repository && repoRoot)) {
+        return 'current'
+    }
+
+    return 'repository'
+}
+
+async function runSyncInk(
+    repository: string | undefined,
+    deps: CliDeps,
+    options: SyncCommandOptions,
+): Promise<SyncCommandResult> {
+    const barkSession = createBarkSession(deps, options, 'Sync')
+    await barkSession.playOnce()
+    const findRepo = deps.findRepositoryRoot ?? findRepositoryRoot
+    const listRepositories = deps.listCloneRootRepositories ?? listCloneRootRepositories
+    const syncAll = deps.syncAllRepositories ?? syncAllRepositories
+    const syncLocal = deps.syncCurrentRepository ?? syncCurrentRepository
+    const syncNamed = deps.syncRepository ?? syncRepository
+    const repoRoot = await findRepo(process.cwd())
+    const mode = resolveSyncMode(repository, options, repoRoot)
+    const config = mode === 'current'
+        ? undefined
+        : await ensureConfigForCommand(deps, options, barkSession)
+    const availableRepositories = config ? listRepositories(config.cloneRoot) : undefined
+
+    return await renderCommandScreen<SyncCommandResult>((controller) => React.createElement(SyncScreen, {
+        controller,
+        mode,
+        dryRun: options.dryRun,
+        targetLabel: mode === 'current'
+            ? (repoRoot ?? process.cwd())
+            : mode === 'all'
+                ? `${availableRepositories?.length ?? 0} repositories`
+                : (repository ?? 'selected repository'),
+        cloneRoot: config?.cloneRoot,
+        initialRepository: repository,
+        availableRepositories,
+        execute: async (selectedRepository, onProgress) => {
+            if (mode === 'all') {
+                const syncResult = await syncAll(config!.cloneRoot, {
+                    onProgress: (event: SyncAllProgressEvent) => {
+                        onProgress({
+                            id: event.targetDir,
+                            label: basename(event.targetDir),
+                            status: event.status,
+                            detail: event.result
+                                ? `${event.result.branch} @ ${event.result.head}`
+                                : event.error,
+                        })
+                    },
+                })
+
+                const result: SyncCommandResult = {
+                    ok: syncResult.failures.length === 0,
+                    mode,
+                    successes: syncResult.successes,
+                    failures: syncResult.failures,
+                    nextActions: buildSyncNextActions({
+                        ok: syncResult.failures.length === 0,
+                        mode,
+                        successes: syncResult.successes,
+                        failures: syncResult.failures,
+                        nextActions: [],
+                    }),
+                }
+
+                if (!result.ok) {
+                    process.exitCode = 1
+                }
+
+                return result
+            }
+
+            try {
+                const syncResult = mode === 'current'
+                    ? await syncLocal(repoRoot ?? process.cwd())
+                    : await syncNamed(selectedRepository!, config!)
+
+                return {
+                    ok: true,
+                    mode,
+                    successes: [syncResult],
+                    failures: [],
+                    nextActions: buildSyncNextActions({
+                        ok: true,
+                        mode,
+                        successes: [syncResult],
+                        failures: [],
+                        nextActions: [],
+                    }),
+                }
+            }
+            catch (error) {
+                const category = categorizeSyncError(error)
+                throw createUserFacingError({
+                    code: `sync_${category}`,
+                    summary: error instanceof Error ? error.message : String(error),
+                    fixes: syncCategoryFixes(category),
+                    cause: error,
+                })
+            }
+        },
+    }))
+}
+
+export async function runSync(
+    repository: string | undefined,
+    deps: CliDeps = {},
+    options: SyncCommandOptions = {},
+): Promise<SyncCommandResult> {
+    validateSyncOptions(repository, options)
+
+    if (isInteractiveInkSession(options)) {
+        return await runSyncInk(repository, deps, options)
+    }
+
+    const prompts = deps.prompts
+    const runtime = createRuntime(deps, options)
+    const findRepo = deps.findRepositoryRoot ?? findRepositoryRoot
+    const ensureConfig = deps.ensureConfigInteractive ?? ensureConfigInteractive
+    const syncAll = deps.syncAllRepositories ?? syncAllRepositories
+    const syncLocal = deps.syncCurrentRepository ?? syncCurrentRepository
+    const syncNamed = deps.syncRepository ?? syncRepository
+    const listRepositories = deps.listCloneRootRepositories ?? listCloneRootRepositories
+
+    emitBootstrap(runtime, 'Tela sync', 'Refresh a checkout or clone a repository into the configured Tela workspace.')
+
+    const repoRoot = await findRepo(process.cwd())
+    const config = options.all || !repoRoot || Boolean(repository)
+        ? await ensureConfig({ prompts })
+        : undefined
+
+    if (options.all) {
+        const repositories = listRepositories(config!.cloneRoot)
+        runtime.emit(renderSyncPlan({
+            mode: 'all',
+            target: `${repositories.length} repositories under ${config!.cloneRoot}`,
+            cloneRoot: config!.cloneRoot,
+            repositories,
+            dryRun: options.dryRun,
+        }, runtime.decorate))
+
+        if (options.dryRun) {
+            const dryRunResult: SyncCommandResult = {
+                ok: true,
+                mode: 'all',
+                successes: [],
+                failures: [],
+                nextActions: ['Run `tela sync --all` without `--dry-run` when you are ready to refresh every checkout.'],
+            }
+
+            if (options.json) {
+                runtime.emitJson(dryRunResult)
+            }
+            return dryRunResult
+        }
+
+        const syncResult = await syncAll(config!.cloneRoot)
+        const result: SyncCommandResult = {
+            ok: syncResult.failures.length === 0,
+            mode: 'all',
+            successes: syncResult.successes,
+            failures: syncResult.failures,
+            nextActions: buildSyncNextActions({
+                ok: syncResult.failures.length === 0,
+                mode: 'all',
+                successes: syncResult.successes,
+                failures: syncResult.failures,
+                nextActions: [],
+            }),
+        }
+
+        if (options.json) {
+            runtime.emitJson(result)
+        }
+        else {
+            runtime.emit(renderSyncResult(result, runtime.decorate))
+        }
+
+        if (!result.ok) {
+            process.exitCode = 1
+        }
+
+        return result
+    }
+
+    let mode: SyncCommandResult['mode']
+    let targetRepository = repository
+
+    if (options.current || (!repository && repoRoot)) {
+        mode = 'current'
+    }
+    else {
+        mode = 'repository'
+        if (!targetRepository) {
+            if (options.json) {
+                throw createUserFacingError({
+                    code: 'sync_repo_required',
+                    summary: 'Repository name is required when --json is used outside a git repository.',
+                    fixes: [
+                        'Pass an explicit repository name, or run `tela sync --current` from inside a repository.',
+                    ],
+                })
+            }
+            const promptModule = prompts ?? getPromptModule(deps)
+            targetRepository = await resolveSyncRepositoryName(
+                promptModule,
+                config!.cloneRoot,
+                listRepositories,
+                false,
+            )
+        }
+    }
+
+    runtime.emit(renderSyncPlan({
+        mode,
+        target: mode === 'current'
+            ? (repoRoot ?? process.cwd())
+            : targetRepository!,
+        cloneRoot: config?.cloneRoot,
+        dryRun: options.dryRun,
+    }, runtime.decorate))
+
+    if (options.dryRun) {
+        const dryRunResult: SyncCommandResult = {
+            ok: true,
+            mode,
+            successes: [],
+            failures: [],
+            nextActions: [
+                mode === 'current'
+                    ? 'Run `tela sync --current` without `--dry-run` to update this checkout.'
+                    : `Run \`tela sync ${targetRepository}\` without \`--dry-run\` to clone or update the repository.`,
+            ],
+        }
+
+        if (options.json) {
+            runtime.emitJson(dryRunResult)
+        }
+        return dryRunResult
+    }
+
+    try {
+        const syncResult = mode === 'current'
+            ? await syncLocal(repoRoot ?? process.cwd())
+            : await syncNamed(targetRepository!, config!)
+
+        const result: SyncCommandResult = {
+            ok: true,
+            mode,
+            successes: [syncResult],
+            failures: [],
+            nextActions: buildSyncNextActions({
+                ok: true,
+                mode,
+                successes: [syncResult],
+                failures: [],
+                nextActions: [],
+            }),
+        }
+
+        if (options.json) {
+            runtime.emitJson(result)
+        }
+        else {
+            runtime.emit(renderSyncResult(result, runtime.decorate))
+        }
+
+        return result
+    }
+    catch (error) {
+        const category = categorizeSyncError(error)
+        throw createUserFacingError({
+            code: `sync_${category}`,
+            summary: error instanceof Error ? error.message : String(error),
+            fixes: syncCategoryFixes(category),
+            cause: error,
+        })
+    }
+}
+
+function resolvePushMode(options: PushCommandOptions): 'manual' | 'claude' {
+    const explicit = [Boolean(options.message), Boolean(options.claude), Boolean(options.manual)].filter(Boolean)
+    if (explicit.length > 1) {
+        throw createUserFacingError({
+            code: 'push_flag_conflict',
+            summary: 'Only one of --message, --claude, or --manual can be used at a time.',
+            fixes: ['Choose one commit-message mode for `tela push`.'],
+        })
+    }
+
+    if (options.message || options.manual) {
+        return 'manual'
+    }
+
+    if (options.claude) {
+        return 'claude'
+    }
+
+    return 'manual'
+}
+
+function renderPushPreview(preview: PushPreview, decorate: boolean): string {
+    const plan = [
+        `Stage all changes in ${preview.repoRoot}`,
+        `Create a commit on ${preview.detached ? '<detached>' : (preview.branch ?? '<unknown>')}`,
+        preview.upstream
+            ? 'Push the branch to its existing upstream'
+            : 'Push the branch and set the upstream on origin',
+    ]
+
+    return resultCard('Push preview', [
+        section('Repository', kvList([
+            { label: 'Repo root', value: preview.repoRoot },
+            { label: 'Branch', value: preview.detached ? '<detached>' : (preview.branch ?? '<unknown>') },
+            { label: 'Upstream', value: preview.upstream ?? '<none>' },
+            { label: 'Changed files', value: String(preview.statusCounts.total) },
+            { label: 'Staged', value: String(preview.statusCounts.staged) },
+            { label: 'Unstaged', value: String(preview.statusCounts.unstaged) },
+            { label: 'Untracked', value: String(preview.statusCounts.untracked) },
+        ]), { decorate }),
+        preview.worktreeStatus
+            ? section('Worktree', preview.worktreeStatus, { decorate })
+            : undefined,
+        preview.suggestedMessage
+            ? section('Commit message', [
+                preview.suggestedMessage,
+                preview.messageSource === 'fallback'
+                    ? `source: deterministic fallback (${preview.fallbackReason ?? 'Claude did not produce a usable message'})`
+                    : `source: ${preview.messageSource}`,
+            ].join('\n'), { decorate })
+            : undefined,
+        section('Plan', stepList(plan), { decorate }),
+    ], { decorate })
+}
+
+async function runPushInk(
+    deps: CliDeps,
+    options: PushCommandOptions,
+): Promise<PushCommandResult> {
+    const barkSession = createBarkSession(deps, options, 'Push')
+    await barkSession.playOnce()
+    const findRepo = deps.findRepositoryRoot ?? findRepositoryRoot
+    const preview = deps.previewPush ?? previewPush
+    const push = deps.pushRepository ?? pushRepository
+    const repoRoot = await findRepo(process.cwd())
+
+    if (!repoRoot) {
+        throw createUserFacingError({
+            code: 'push_outside_repo',
+            summary: 'Push must be run from inside a git repository.',
+            fixes: ['Change into a repository, or run `tela sync <repo>` first.'],
+        })
+    }
+
+    const initialMode = (options.message || options.claude || options.manual)
+        ? resolvePushMode(options)
+        : undefined
+    const initialManualMessage = options.message?.trim() || undefined
+
+    return await renderCommandScreen<PushCommandResult>((controller) => React.createElement(PushScreen, {
+        controller,
+        initialMode,
+        initialManualMessage,
+        dryRun: options.dryRun,
+        loadPreview: async (input) => {
+            const previewResult = await preview({
+                cwd: repoRoot,
+                mode: input.mode,
+                manualMessage: input.manualMessage,
+            })
+
+            if (!previewResult.hasChanges) {
+                throw createUserFacingError({
+                    code: 'push_no_changes',
+                    summary: 'No changes to push.',
+                    fixes: ['Modify files first, or review the worktree with `git status`.'],
+                })
+            }
+
+            if (previewResult.detached) {
+                throw createUserFacingError({
+                    code: 'push_detached_head',
+                    summary: 'Detached HEAD; check out a branch before pushing.',
+                    fixes: ['Check out a branch before running `tela push`.'],
+                })
+            }
+
+            return previewResult
+        },
+        execute: async (input) => {
+            const pushResult = await push({
+                cwd: repoRoot,
+                mode: input.messageSource === 'manual' ? 'manual' : 'claude',
+                manualMessage: input.messageSource === 'manual' ? input.commitMessage : undefined,
+                resolvedMessage: {
+                    message: input.commitMessage,
+                    source: input.messageSource,
+                    fallbackReason: input.fallbackReason,
+                },
+            })
+
+            return pushResult
+        },
+    }))
+}
+
+export async function runPush(
+    deps: CliDeps = {},
+    options: PushCommandOptions = {},
+): Promise<PushCommandResult> {
+    if (isInteractiveInkSession(options)) {
+        return await runPushInk(deps, options)
+    }
+
+    const prompts = deps.prompts
+    const runtime = createRuntime(deps, options)
+    const findRepo = deps.findRepositoryRoot ?? findRepositoryRoot
+    const preview = deps.previewPush ?? previewPush
+    const push = deps.pushRepository ?? pushRepository
+    const repoRoot = await findRepo(process.cwd())
+
+    emitBootstrap(runtime, 'Tela push', 'Stage, preview, and publish the current repository with a reviewed commit message.')
+
+    if (!repoRoot) {
+        throw createUserFacingError({
+            code: 'push_outside_repo',
+            summary: 'Push must be run from inside a git repository.',
+            fixes: ['Change into a repository, or run `tela sync <repo>` first.'],
+        })
+    }
+
+    let mode = resolvePushMode(options)
+    let manualMessage = options.message?.trim() || undefined
+
+    if (!options.message && !options.claude && !options.manual && !options.json && prompts) {
+        const modeResult = await prompts.select<'manual' | 'claude'>({
+            message: 'How do you want to create the commit message?',
+            options: [
+                { value: 'manual', label: 'Write it myself' },
+                { value: 'claude', label: 'Generate with Claude' },
+            ],
+            initialValue: 'manual',
+        })
+        ensureNotCancelled(prompts, modeResult, 'Push cancelled.')
+        mode = promptValue(modeResult)
+    }
+
+    if (mode === 'manual' && !manualMessage && !options.json && prompts) {
+        const messageResult = await prompts.text({
+            message: 'Commit message',
+            placeholder: 'Leave blank to generate from Claude or the deterministic fallback',
+        })
+        ensureNotCancelled(prompts, messageResult, 'Push cancelled.')
+        manualMessage = promptValue(messageResult).trim() || undefined
+    }
+
+    const previewResult = await preview({
+        cwd: repoRoot,
+        mode,
+        manualMessage,
+    })
+
+    if (!previewResult.hasChanges) {
+        throw createUserFacingError({
+            code: 'push_no_changes',
+            summary: 'No changes to push.',
+            fixes: ['Modify files first, or review the worktree with `git status`.'],
+        })
+    }
+
+    if (previewResult.detached) {
+        throw createUserFacingError({
+            code: 'push_detached_head',
+            summary: 'Detached HEAD; check out a branch before pushing.',
+            fixes: ['Check out a branch before running `tela push`.'],
+        })
+    }
+
+    runtime.emit(renderPushPreview(previewResult, runtime.decorate))
+
+    let resolvedMessage = previewResult.suggestedMessage?.trim() || manualMessage
+    if (!resolvedMessage) {
+        throw createUserFacingError({
+            code: 'push_message_missing',
+            summary: 'Unable to determine a commit message for the current worktree.',
+            fixes: ['Pass `--message`, or retry with `--claude` after reviewing the current diff.'],
+        })
+    }
+
+    let messageSource = previewResult.messageSource ?? (manualMessage ? 'manual' : 'fallback')
+    let fallbackReason = previewResult.fallbackReason
+
+    if (mode === 'claude' && !options.json && prompts) {
+        const editedMessage = await prompts.text({
+            message: 'Confirm or edit the commit message',
+            defaultValue: resolvedMessage,
+        })
+        ensureNotCancelled(prompts, editedMessage, 'Push cancelled.')
+        resolvedMessage = promptValue(editedMessage).trim() || resolvedMessage
+        messageSource = previewResult.messageSource ?? 'claude'
+    }
+
+    if (options.dryRun) {
+        const dryRunResult: PushCommandResult = {
+            ok: true,
+            branch: previewResult.branch,
+            commitMessage: resolvedMessage,
+            nextActions: ['Run `tela push` without `--dry-run` when the plan looks correct.'],
+        }
+
+        if (options.json) {
+            runtime.emitJson(dryRunResult)
+        }
+
+        return dryRunResult
+    }
+
+    const pushResult = await push({
+        cwd: repoRoot,
+        mode: 'manual',
+        manualMessage: resolvedMessage,
+        resolvedMessage: {
+            message: resolvedMessage,
+            source: messageSource,
+            fallbackReason,
+        },
+    })
+
+    const result: PushCommandResult = {
+        ok: true,
+        branch: pushResult.branch,
+        commitMessage: pushResult.message,
+        commitSha: pushResult.commitSha,
+        retriedCommit: pushResult.retriedCommit,
+        nextActions: [
+            'Run `tela feedback --list` to inspect feedback for the pushed commit.',
+            'Use `tela status` if you want to verify the repository is clean afterward.',
+        ],
+    }
+
+    if (options.json) {
+        runtime.emitJson(result)
+    }
+    else {
+        runtime.emit(resultCard('Push complete', [
+            section('Commit', kvList([
+                { label: 'Branch', value: pushResult.branch },
+                { label: 'Commit', value: pushResult.commitSha },
+                { label: 'Upstream', value: pushResult.upstream ?? '<set on push>' },
+                { label: 'Retry', value: pushResult.retriedCommit ? 'yes' : 'no' },
+            ]), { decorate: runtime.decorate }),
+            section('Message', [
+                pushResult.message,
+                pushResult.messageSource === 'fallback'
+                    ? `source: deterministic fallback (${pushResult.fallbackReason ?? 'Claude did not return a usable message'})`
+                    : `source: ${pushResult.messageSource}`,
+            ].join('\n'), { decorate: runtime.decorate }),
+            nextActions(result.nextActions, { decorate: runtime.decorate }),
+        ], { decorate: runtime.decorate }))
+    }
+
+    return result
+}
+
+function renderFeedbackResult(result: FeedbackRunResult, decorate: boolean): string {
+    const selected = result.selectedIds?.length ? result.selectedIds.join(', ') : '<none>'
+    return resultCard('Feedback workflow', [
+        section('Summary', kvList([
+            { label: 'Repository', value: `${result.organizationName}/${result.repository}` },
+            { label: 'Commit', value: result.commitHash },
+            { label: 'Mode', value: describeFeedbackSelectionMode(result.selectionMode) },
+            { label: 'Feedbacks', value: String(result.summary.totalFeedbacks) },
+            { label: 'Actionable', value: String(result.summary.actionableCount) },
+            { label: 'Informational', value: String(result.summary.informationalCount) },
+            { label: 'Review state', value: describeFeedbackEmptyState(result.emptyState) },
+            { label: 'Selected', value: selected },
+            { label: 'Claude launched', value: result.launchedClaude ? 'yes' : 'no' },
+        ]), { decorate }),
+        result.diffStat
+            ? section('Local diff summary', result.diffStat, { decorate })
+            : undefined,
+        nextActions(result.nextActions, { decorate }),
+    ], { decorate })
+}
+
+function validateFeedbackOptions(options: FeedbackCommandFlags & GlobalCliOptions): FeedbackCommandFlags & GlobalCliOptions {
+    if (options.apply && options.apply !== 'all' && options.apply !== 'select') {
+        throw createUserFacingError({
+            code: 'feedback_apply_invalid',
+            summary: '`--apply` must be either `all` or `select`.',
+            fixes: ['Use `tela feedback --apply all` or `tela feedback --apply select`.'],
+        })
+    }
+
+    if (options.json && options.apply === 'select') {
+        throw createUserFacingError({
+            code: 'feedback_json_select_conflict',
+            summary: '`--json` cannot be combined with `--apply select` because selection is interactive.',
+            fixes: ['Use `tela feedback --list --json`, or run the interactive command without `--json`.'],
+        })
+    }
+
+    return {
+        ...options,
+        list: options.json && !options.list && !options.apply
+            ? true
+            : options.list,
+    }
+}
+
+async function runFeedbackServiceFlow(
+    repoRoot: string,
+    deps: CliDeps,
+    options: FeedbackCommandFlags & GlobalCliOptions,
+): Promise<FeedbackRunResult> {
+    const config = await ensureConfigForCommand(deps, options)
+    const loadFeedbackDataFn = deps.loadFeedbackData ?? loadFeedbackData
+    const launchFeedbackClaudeFn = deps.launchFeedbackClaude ?? launchFeedbackClaude
+    const commandExistsFn = deps.commandExists ?? commandExists
+    const getDiffStatAgainstHeadFn = deps.getDiffStatAgainstHead ?? getDiffStatAgainstHead
+    const selectionMode = getFeedbackSelectionMode(options)
+    const data = await loadFeedbackDataFn({
+        cwd: repoRoot,
+        config,
+    })
+    const review = buildFeedbackReviewModel(data)
+
+    if (selectionMode === 'list' || review.emptyState !== 'none') {
+        return buildFeedbackRunResult({
+            data,
+            selectionMode,
+            launchedClaude: false,
+        })
+    }
+
+    if (!await commandExistsFn('claude')) {
+        throw createUserFacingError({
+            code: 'feedback_claude_missing',
+            summary: 'Claude CLI is not available on PATH.',
+            fixes: ['Install the Claude CLI before using `tela feedback --apply ...`.'],
+        })
+    }
+
+    const selectedFeedbacks = data.actionableEntries
+    const prompt = buildClaudeFeedbackPrompt({
+        repoRoot: data.repoRoot,
+        organizationName: data.organizationName,
+        repository: data.repository,
+        commitHash: data.commitHash,
+        selectedFeedbacks,
+    })
+
+    await launchFeedbackClaudeFn({
+        repoRoot: data.repoRoot,
+        prompt,
+    })
+
+    const diffStat = await getDiffStatAgainstHeadFn(repoRoot)
+
+    return buildFeedbackRunResult({
+        data,
+        selectionMode,
+        launchedClaude: true,
+        selectedFeedbacks,
+        diffStat,
+    })
+}
+
+async function runFeedbackInk(
+    repoRoot: string,
+    deps: CliDeps,
+    options: FeedbackCommandFlags & GlobalCliOptions,
+): Promise<FeedbackRunResult> {
+    const barkSession = createBarkSession(deps, options, 'Feedback')
+    await barkSession.playOnce()
+    const config = await ensureConfigForCommand(deps, options, barkSession)
+    const loadFeedbackDataFn = deps.loadFeedbackData ?? loadFeedbackData
+    const launchFeedbackClaudeFn = deps.launchFeedbackClaude ?? launchFeedbackClaude
+    const commandExistsFn = deps.commandExists ?? commandExists
+    const getDiffStatAgainstHeadFn = deps.getDiffStatAgainstHead ?? getDiffStatAgainstHead
+    const selectionMode = getFeedbackSelectionMode(options)
+    const data = await loadFeedbackDataFn({
+        cwd: repoRoot,
+        config,
+    })
+
+    const selection = await renderCommandScreen<{
+        selectedFeedbacks: FeedbackData['entries']
+        prompt?: string
+        launchedClaude: boolean
+        selectionMode: ReturnType<typeof getFeedbackSelectionMode>
+    }>((controller) => React.createElement(FeedbackSelectionScreen, {
+        controller,
+        data,
+        mode: selectionMode,
+    }))
+
+    if (!selection.prompt || selection.selectedFeedbacks.length === 0) {
+        return buildFeedbackRunResult({
+            data,
+            selectionMode,
+            launchedClaude: false,
+            selectedFeedbacks: selection.selectedFeedbacks,
+        })
+    }
+
+    if (!await commandExistsFn('claude')) {
+        throw createUserFacingError({
+            code: 'feedback_claude_missing',
+            summary: 'Claude CLI is not available on PATH.',
+            fixes: ['Install the Claude CLI before using `tela feedback --apply ...`.'],
+        })
+    }
+
+    await renderCommandScreen<void>((controller) => React.createElement(FeedbackClaudeHandoffScreen, {
+        controller,
+        repoRoot: data.repoRoot,
+        commitHash: data.commitHash,
+        selectedFeedbacks: selection.selectedFeedbacks,
+    }))
+
+    await launchFeedbackClaudeFn({
+        repoRoot: data.repoRoot,
+        prompt: selection.prompt,
+    })
+
+    const diffStat = await getDiffStatAgainstHeadFn(repoRoot)
+
+    await renderCommandScreen<void>((controller) => React.createElement(FeedbackOutcomeScreen, {
+        controller,
+        commitHash: data.commitHash,
+        selectionMode,
+        diffStat: diffStat || 'No local diff detected after Claude exited.',
+        selectedFeedbacks: selection.selectedFeedbacks,
+    }))
+
+    return buildFeedbackRunResult({
+        data,
+        selectionMode,
+        launchedClaude: true,
+        selectedFeedbacks: selection.selectedFeedbacks,
+        diffStat,
+    })
+}
+
+export async function runFeedback(
+    deps: CliDeps = {},
+    options: FeedbackCommandFlags & GlobalCliOptions = {},
+): Promise<FeedbackRunResult> {
+    const normalizedOptions = validateFeedbackOptions(options)
+    const runtime = createRuntime(deps, options)
+    const findRepo = deps.findRepositoryRoot ?? findRepositoryRoot
+    const feedbackCommand = deps.runFeedbackCommand ?? runFeedbackCommand
+    const repoRoot = await findRepo(process.cwd())
+
+    if (!repoRoot) {
+        throw createUserFacingError({
+            code: 'feedback_outside_repo',
+            summary: 'Feedback must be run from inside a git repository.',
+            fixes: ['Change into a repository, or run `tela sync <repo>` first.'],
+        })
+    }
+
+    const interactive = isInteractiveInkSession(normalizedOptions)
+    if (!interactive) {
+        emitBootstrap(runtime, 'Tela feedback', 'Review commit feedback and optionally hand selected fixes to Claude.')
+    }
+
+    const result = interactive
+        ? await runFeedbackInk(repoRoot, deps, normalizedOptions)
+        : deps.prompts
+            ? await feedbackCommand({
+                cwd: repoRoot,
+                prompts: deps.prompts,
+                list: normalizedOptions.list,
+                apply: normalizedOptions.apply,
+            })
+            : await runFeedbackServiceFlow(repoRoot, deps, normalizedOptions)
+
+    if (normalizedOptions.json) {
+        runtime.emitJson(result)
+    }
+    else {
+        runtime.emit(renderFeedbackResult(result, runtime.decorate))
+    }
+
+    return result
+}
+
+export async function runAgent(
+    deps: CliDeps = {},
+    options: RunCommandOptions = {},
+): Promise<RunCommandResult> {
+    const runtime = createRuntime(deps, options)
+    const runAgentCommandFn = deps.runLocalAgentCommand ?? runLocalAgentCommand
+    const prepareRunFn = deps.prepareLocalAgentRun ?? prepareLocalAgentRun
+    const surface = resolveRunSurface(options)
+
+    let result: RunCommandResult
+
+    if (surface === 'viewer') {
+        const prepared = await prepareRunFn({
+            cwd: process.cwd(),
+            commandExists: deps.commandExists,
+        })
+        const barkSession = createBarkSession(deps, options, 'Run')
+        await barkSession.playOnce()
+
+        if (prepared.config.isMultiturn) {
+            await renderCommandScreen<void>((controller) => React.createElement(RunChatHandoffScreen, {
+                controller,
+                snapshot: createInitialRunSnapshot(prepared, 'chat'),
+            }), {
+                exitOnCtrlC: false,
+            })
+
+            result = await runAgentCommandFn({
+                cwd: process.cwd(),
+                contract: prepared,
+                surface: 'viewer',
+                commandExists: deps.commandExists,
+                runInteractiveCommand: deps.runInteractiveCommand,
+                runStreamingCommand: deps.runStreamingCommand,
+                writeStdout: deps.writeStdout,
+                writeStderr: deps.writeStderr,
+                stdinIsTTY: process.stdin.isTTY,
+                stdoutIsTTY: process.stdout.isTTY,
+                verbose: options.verbose,
+            })
+        }
+        else {
+            result = await renderCommandScreen<RunCommandResult>((controller) => React.createElement(RunScreen, {
+                controller,
+                initialSnapshot: createInitialRunSnapshot(prepared, 'one-shot'),
+                execute: async ({ onSnapshot, onControl }) => {
+                    return await runAgentCommandFn({
+                        cwd: process.cwd(),
+                        contract: prepared,
+                        surface: 'viewer',
+                        commandExists: deps.commandExists,
+                        runInteractiveCommand: deps.runInteractiveCommand,
+                        runStreamingCommand: deps.runStreamingCommand,
+                        writeStdout: deps.writeStdout,
+                        writeStderr: deps.writeStderr,
+                        onSnapshot,
+                        onControl,
+                        stdinIsTTY: process.stdin.isTTY,
+                        stdoutIsTTY: process.stdout.isTTY,
+                        verbose: options.verbose,
+                    })
+                },
+            }), {
+                exitOnCtrlC: false,
+            })
+        }
+    }
+    else {
+        emitBootstrap(runtime, 'Tela run', 'Run the local agent repository with Claude.')
+
+        result = await runAgentCommandFn({
+            cwd: process.cwd(),
+            surface,
+            commandExists: deps.commandExists,
+            runInteractiveCommand: deps.runInteractiveCommand,
+            runStreamingCommand: deps.runStreamingCommand,
+            writeStdout: deps.writeStdout,
+            writeStderr: deps.writeStderr,
+            stdinIsTTY: process.stdin.isTTY,
+            stdoutIsTTY: process.stdout.isTTY,
+            verbose: options.verbose,
+        })
+    }
+
+    if (options.json) {
+        runtime.emitJson(result)
+    }
+    else {
+        runtime.emit(renderRunExecutionRecap(result, { decorate: runtime.decorate }))
+        runtime.emit(renderRunArtifactCard(result, { decorate: runtime.decorate }))
+    }
+
+    return result
+}
+
+export async function runStatus(
+    deps: CliDeps = {},
+    options: StatusCommandOptions = {},
+): Promise<Awaited<ReturnType<typeof getStatusReport>>> {
+    const runtime = createRuntime(deps, options)
+    const getReport = deps.getStatusReport ?? getStatusReport
+    emitBootstrap(runtime, 'Tela status', 'Inspect config, tool availability, repository state, and agent reachability.')
+    const report = await getReport(process.cwd(), deps.fetchFn ?? fetch)
+
+    if (options.json) {
+        runtime.emitJson(report)
+    }
+    else {
+        runtime.emit(renderStatusReport(report, { decorate: runtime.decorate }))
+    }
+
+    return report
+}
+
+export async function runDoctor(
+    deps: CliDeps = {},
+    options: DoctorCommandOptions = {},
+): Promise<Awaited<ReturnType<typeof getDoctorReport>>> {
+    const runtime = createRuntime(deps, options)
+    const getReport = deps.getDoctorReport ?? getDoctorReport
+    emitBootstrap(runtime, 'Tela doctor', 'Run a full environment diagnosis with explicit remediation steps.')
+    const report = await getReport(process.cwd(), deps.fetchFn ?? fetch)
+
+    if (options.json) {
+        runtime.emitJson(report)
+    }
+    else {
+        runtime.emit(renderDoctorReport(report, { decorate: runtime.decorate }))
+    }
+
+    if (!report.ok) {
+        process.exitCode = 1
+    }
+
+    return report
+}
+
+function addStandardReadOptions(command: Command): Command {
+    return command
+        .option('--json', 'emit machine-readable JSON')
+}
+
+export function createProgram(deps: CliDeps = {}): Command {
+    const program = new Command()
+        .name('tela')
+        .description('Tela CLI workspace helper')
+        .showHelpAfterError()
+        .option('--silent-bark', 'disable bark audio during interactive Ink startup')
+        .option('--verbose', 'include raw evidence on failures')
+
+    installCustomHelp(program)
+
+    program
+        .command('setup')
+        .description('Configure Tela CLI settings and choose the Agent API target')
+        .action(async () => {
+            const globalOptions = program.opts<GlobalCliOptions>()
+            await runSetup(deps, globalOptions)
+        })
+
+    addStandardReadOptions(
+        program
+            .command('sync')
+            .argument('[repo]', 'repository name')
+            .option('--current', 'sync the current checkout')
+            .option('--all', 'sync every repository under the configured clone root')
+            .option('--dry-run', 'show what would happen without changing anything')
+            .description('Clone or update a workspace repository, or sync the current checkout'),
+    ).action(async (repository: string | undefined, commandOptions: SyncCommandOptions) => {
+        const globalOptions = program.opts<GlobalCliOptions>()
+        await runSync(repository, deps, {
+            ...globalOptions,
+            ...commandOptions,
+        })
+    })
+
+    addStandardReadOptions(
+        program
+            .command('run')
+            .option('--plain', 'force scrollback-first text output instead of the live viewer')
+            .description('Run the local agent repository with Claude'),
+    ).action(async (commandOptions: RunCommandOptions) => {
+        const globalOptions = program.opts<GlobalCliOptions>()
+        await runAgent(deps, {
+            ...globalOptions,
+            ...commandOptions,
+        })
+    })
+
+    addStandardReadOptions(
+        program
+            .command('push')
+            .option('--message <text>', 'use an explicit commit message')
+            .option('--claude', 'generate the commit message with Claude')
+            .option('--manual', 'enter the commit message manually')
+            .option('--dry-run', 'show the push plan without committing or pushing')
+            .description('Stage, commit, and push the current repository'),
+    ).action(async (commandOptions: PushCommandOptions) => {
+        const globalOptions = program.opts<GlobalCliOptions>()
+        await runPush(deps, {
+            ...globalOptions,
+            ...commandOptions,
+        })
+    })
+
+    addStandardReadOptions(
+        program
+            .command('feedback')
+            .option('--list', 'list feedback for the current commit without launching Claude')
+            .option('--apply <mode>', 'launch Claude for `all` or `select` feedback suggestions')
+            .description('List commit feedback and address selected suggestions with Claude'),
+    ).action(async (commandOptions: FeedbackCommandFlags & GlobalCliOptions) => {
+        const globalOptions = program.opts<GlobalCliOptions>()
+        await runFeedback(deps, {
+            ...globalOptions,
+            ...commandOptions,
+        })
+    })
+
+    addStandardReadOptions(
+        program
+            .command('status')
+            .description('Show Tela config, repo state, tool availability, and Agent API origin reachability'),
+    ).action(async (commandOptions: StatusCommandOptions) => {
+        const globalOptions = program.opts<GlobalCliOptions>()
+        await runStatus(deps, {
+            ...globalOptions,
+            ...commandOptions,
+        })
+    })
+
+    addStandardReadOptions(
+        program
+            .command('doctor')
+            .alias('diag')
+            .description('Diagnose config, tools, filesystem permissions, repo health, and Agent API origin reachability'),
+    ).action(async (commandOptions: DoctorCommandOptions) => {
+        const globalOptions = program.opts<GlobalCliOptions>()
+        await runDoctor(deps, {
+            ...globalOptions,
+            ...commandOptions,
+        })
+    })
+
+    return program
+}
+
+export async function main(argv = process.argv): Promise<void> {
+    await createProgram().parseAsync(argv)
+}