typeclaw 0.1.1 → 0.1.2

package/src/bundled-plugins/backup/runner.ts

@@ -0,0 +1,231 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const COMMIT_TIMEOUT_MS = 30_000
+export const NETWORK_TIMEOUT_MS = 60_000
+
+const RUNTIME_OWNED_PREFIXES = ['memory/'] as const
+const FORCE_ADD_PREFIXES = ['sessions/'] as const
+
+const NONINTERACTIVE_ENV = {
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_PAGER: 'cat',
+  PAGER: 'cat',
+  GCM_INTERACTIVE: 'never',
+} as const
+
+export type GitSpawnResult = {
+  exitCode: number
+  stdout: string
+  stderr: string
+  timedOut: boolean
+}
+
+export type GitSpawn = (args: readonly string[], opts: { cwd: string; timeoutMs: number }) => Promise<GitSpawnResult>
+
+export type BackupRunnerDeps = {
+  gitSpawn: GitSpawn
+  pickCommitMessage: (input: { status: string; diffstat: string }) => Promise<string>
+  diagnoseFailure?: (input: BackupFailureInput) => Promise<void>
+  now?: () => number
+}
+
+export type BackupRunnerOptions = {
+  cwd: string
+  pushToOrigin: boolean
+}
+
+export type BackupFailureInput = {
+  cwd: string
+  stage: 'push' | 'rebase'
+  exitCode: number
+  stderr: string
+  stdout: string
+}
+
+export type BackupResult =
+  | { ok: true; kind: 'no-repo' | 'clean' | 'committed' | 'pushed' | 'rebased-and-pushed' }
+  | { ok: false; kind: 'commit-failed' | 'push-failed' | 'rebase-failed' | 'aborted'; reason: string }
+
+export async function runBackup(options: BackupRunnerOptions, deps: BackupRunnerDeps): Promise<BackupResult> {
+  const { cwd, pushToOrigin } = options
+
+  if (!existsSync(join(cwd, '.git'))) return { ok: true, kind: 'no-repo' }
+
+  const status = await deps.gitSpawn(['status', '--porcelain=v1', '--untracked-files=all'], {
+    cwd,
+    timeoutMs: COMMIT_TIMEOUT_MS,
+  })
+  if (status.exitCode !== 0) return { ok: false, kind: 'aborted', reason: `git status failed: ${shortErr(status)}` }
+  const dirty = filterAgentOwned(parsePorcelain(status.stdout))
+  const force = filterForceAdd(parsePorcelain(status.stdout))
+  if (dirty.length === 0 && force.length === 0) return { ok: true, kind: 'clean' }
+
+  if (dirty.length > 0) {
+    const add = await deps.gitSpawn(['add', '--', ...dirty], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+    if (add.exitCode !== 0) return { ok: false, kind: 'commit-failed', reason: `git add failed: ${shortErr(add)}` }
+  }
+  if (force.length > 0) {
+    const present = force.filter((p) => existsSync(join(cwd, p)))
+    if (present.length > 0) {
+      const addF = await deps.gitSpawn(['add', '-f', '--', ...present], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+      if (addF.exitCode !== 0) {
+        return { ok: false, kind: 'commit-failed', reason: `git add -f failed: ${shortErr(addF)}` }
+      }
+    }
+  }
+
+  const stagedCheck = await deps.gitSpawn(['diff', '--cached', '--quiet'], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+  if (stagedCheck.exitCode === 0) return { ok: true, kind: 'clean' }
+
+  const diffstat = await deps.gitSpawn(['diff', '--cached', '--stat'], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+  const message = await deps.pickCommitMessage({
+    status: status.stdout.slice(0, 4096),
+    diffstat: diffstat.stdout.slice(0, 4096),
+  })
+
+  const safeMessage = sanitizeCommitMessage(message)
+  const commit = await deps.gitSpawn(['commit', '-m', safeMessage], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+  if (commit.exitCode !== 0)
+    return { ok: false, kind: 'commit-failed', reason: `git commit failed: ${shortErr(commit)}` }
+
+  if (!pushToOrigin) return { ok: true, kind: 'committed' }
+
+  const upstream = await deps.gitSpawn(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], {
+    cwd,
+    timeoutMs: COMMIT_TIMEOUT_MS,
+  })
+  if (upstream.exitCode !== 0) return { ok: true, kind: 'committed' }
+
+  const upstreamRef = upstream.stdout.trim()
+  if (upstreamRef.length === 0) return { ok: true, kind: 'committed' }
+
+  const push = await deps.gitSpawn(['push'], { cwd, timeoutMs: NETWORK_TIMEOUT_MS })
+  if (push.exitCode === 0) return { ok: true, kind: 'pushed' }
+
+  if (!isNonFastForward(push)) {
+    await maybeDiagnose(deps, { cwd, stage: 'push', exitCode: push.exitCode, stderr: push.stderr, stdout: push.stdout })
+    return { ok: false, kind: 'push-failed', reason: shortErr(push) }
+  }
+
+  const fetch = await deps.gitSpawn(['fetch'], { cwd, timeoutMs: NETWORK_TIMEOUT_MS })
+  if (fetch.exitCode !== 0) {
+    await maybeDiagnose(deps, {
+      cwd,
+      stage: 'push',
+      exitCode: fetch.exitCode,
+      stderr: fetch.stderr,
+      stdout: fetch.stdout,
+    })
+    return { ok: false, kind: 'push-failed', reason: `git fetch failed: ${shortErr(fetch)}` }
+  }
+
+  const rebase = await deps.gitSpawn(['rebase', upstreamRef], { cwd, timeoutMs: NETWORK_TIMEOUT_MS })
+  if (rebase.exitCode !== 0) {
+    await deps.gitSpawn(['rebase', '--abort'], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+    await maybeDiagnose(deps, {
+      cwd,
+      stage: 'rebase',
+      exitCode: rebase.exitCode,
+      stderr: rebase.stderr,
+      stdout: rebase.stdout,
+    })
+    return { ok: false, kind: 'rebase-failed', reason: `git rebase failed: ${shortErr(rebase)}` }
+  }
+
+  const push2 = await deps.gitSpawn(['push'], { cwd, timeoutMs: NETWORK_TIMEOUT_MS })
+  if (push2.exitCode !== 0) {
+    await maybeDiagnose(deps, {
+      cwd,
+      stage: 'push',
+      exitCode: push2.exitCode,
+      stderr: push2.stderr,
+      stdout: push2.stdout,
+    })
+    return { ok: false, kind: 'push-failed', reason: `git push (post-rebase) failed: ${shortErr(push2)}` }
+  }
+  return { ok: true, kind: 'rebased-and-pushed' }
+}
+
+async function maybeDiagnose(deps: BackupRunnerDeps, input: BackupFailureInput): Promise<void> {
+  if (!deps.diagnoseFailure) return
+  try {
+    await deps.diagnoseFailure(input)
+  } catch {
+    // Diagnosis is advisory; never let it mask the original failure.
+  }
+}
+
+function shortErr(r: GitSpawnResult): string {
+  if (r.timedOut) return `timed out (exit ${r.exitCode})`
+  const text = r.stderr.trim() || r.stdout.trim() || `exit ${r.exitCode}`
+  return text.length > 400 ? `${text.slice(0, 400)}…` : text
+}
+
+function isNonFastForward(r: GitSpawnResult): boolean {
+  const blob = `${r.stderr}\n${r.stdout}`.toLowerCase()
+  return blob.includes('non-fast-forward') || blob.includes('updates were rejected')
+}
+
+export function parsePorcelain(stdout: string): string[] {
+  const out: string[] = []
+  for (const raw of stdout.split('\n')) {
+    if (raw.length < 4) continue
+    const rest = raw.slice(3)
+    const arrowIdx = rest.indexOf(' -> ')
+    out.push(arrowIdx === -1 ? rest : rest.slice(arrowIdx + 4))
+  }
+  return out
+}
+
+function filterAgentOwned(paths: readonly string[]): string[] {
+  return paths.filter((p) => !RUNTIME_OWNED_PREFIXES.some((pre) => p.startsWith(pre)))
+}
+
+function filterForceAdd(paths: readonly string[]): string[] {
+  return paths.filter((p) => FORCE_ADD_PREFIXES.some((pre) => p.startsWith(pre)))
+}
+
+function sanitizeCommitMessage(raw: string): string {
+  const trimmed = raw.trim()
+  if (trimmed.length === 0) return 'Backup'
+  const subject = trimmed.split('\n')[0]?.slice(0, 200) ?? 'Backup'
+  const rest = trimmed.split('\n').slice(1).join('\n').trim()
+  return rest.length > 0 ? `${subject}\n\n${rest}` : subject
+}
+
+export function makeDefaultGitSpawn(): GitSpawn {
+  return async (args, { cwd, timeoutMs }) => {
+    const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
+    if (!bun) {
+      return { exitCode: 127, stdout: '', stderr: 'Bun runtime not available', timedOut: false }
+    }
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    try {
+      const proc = bun.spawn({
+        cmd: ['git', ...args],
+        cwd,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: { ...process.env, ...NONINTERACTIVE_ENV },
+        signal: controller.signal,
+      })
+      const exitCode = await proc.exited
+      const stdout = await new Response(proc.stdout).text()
+      const stderr = await new Response(proc.stderr).text()
+      const timedOut = controller.signal.aborted
+      return { exitCode, stdout, stderr, timedOut }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      return {
+        exitCode: 1,
+        stdout: '',
+        stderr: message,
+        timedOut: controller.signal.aborted,
+      }
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+}

package/src/bundled-plugins/backup/subagents.ts

@@ -0,0 +1,200 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { z } from 'zod'
+
+import { bashTool, readTool, type Subagent, writeTool } from '@/plugin'
+
+const messagePayloadSchema = z.object({
+  agentDir: z.string(),
+  status: z.string(),
+  diffstat: z.string(),
+  outputPath: z.string(),
+})
+
+export type CommitMessagePayload = z.infer<typeof messagePayloadSchema>
+
+const diagnosePayloadSchema = z.object({
+  agentDir: z.string(),
+  stage: z.enum(['push', 'rebase']),
+  exitCode: z.number(),
+  stderr: z.string(),
+  stdout: z.string(),
+})
+
+export type DiagnoseFailurePayload = z.infer<typeof diagnosePayloadSchema>
+
+export const COMMIT_MESSAGE_SYSTEM_PROMPT = `You are typeclaw's backup commit-message subagent.
+
+A periodic backup is about to commit dirty files in the agent folder. Your only job is to produce a clear, conventional commit message describing those changes.
+
+# Input
+
+The user message gives you:
+- The output of \`git status --porcelain=v1 --untracked-files=all\` (truncated)
+- The output of \`git diff --cached --stat\` (truncated)
+- An absolute file path you must write the commit message to
+
+# What to write
+
+A single commit message in conventional-commit-ish style:
+- Subject line under 72 characters, imperative mood, lowercase first word, no trailing period.
+- Pick a sensible prefix when one fits: \`docs:\`, \`test:\`, \`refactor:\`, \`chore:\`, \`fix:\`, \`feat:\`. Default to \`chore: backup\` if nothing fits.
+- Optionally a blank line and a short body (1-3 lines) summarizing what changed and why if the diff makes the why obvious.
+
+Examples:
+- \`docs: update setup instructions\`
+- \`feat: add user search endpoint\`
+- \`chore: backup workspace state\`
+
+# Hard rules
+
+1. **Write exactly one file.** Use the \`write\` tool with the absolute path the user gave you. Do not write anywhere else. Do not read other files. Do not run commands.
+2. **Output is the file contents only.** No prose to the user, no explanation, no apologies. The runner ignores everything except the file you wrote.
+3. **Be honest about uncertainty.** If the diff looks like a mix of unrelated changes, write \`chore: backup\` rather than guessing a misleading subject.
+4. **Never include secrets, API keys, or paths that would identify the user's machine.** Stick to repo-relative descriptions.
+5. **Stop when the file is written.** Do not continue after the \`write\` succeeds.`
+
+export const DIAGNOSE_FAILURE_SYSTEM_PROMPT = `You are typeclaw's backup failure-diagnosis subagent.
+
+The deterministic backup runner just hit a git failure (push or rebase). The runner has already aborted any half-done state. Your job is to look at the git repo, figure out what went wrong, and either FIX IT or write a clear human-readable explanation.
+
+# Input
+
+The user message gives you:
+- The agent folder absolute path
+- The stage that failed (\`push\` or \`rebase\`)
+- The git exit code, stderr, and stdout
+
+# Tools
+
+You have \`bash\`, \`read\`, and \`write\`. Use \`bash\` to inspect git state (\`git status\`, \`git remote -v\`, \`git log -5 --oneline\`, \`git config --get remote.origin.url\`).
+
+# Allowed actions
+
+You MAY:
+- Inspect git state (read-only commands).
+- Set up a missing upstream branch via \`git push -u origin <branch>\` if it's clear that's the only issue.
+- Retry \`git push\` once after fixing a clear, narrow issue.
+
+You MUST NOT:
+- Force-push (\`--force\`, \`--force-with-lease\`).
+- Resolve merge conflicts by editing files. If a rebase had conflicts, the runner already aborted it. Leave the repo as-is and explain.
+- Mutate \`.git/config\` for credentials, signing keys, or remote URLs.
+- Touch any file outside \`.git/\` housekeeping.
+
+# Output
+
+Write a brief diagnosis (3-8 lines) describing:
+1. What the actual cause was (e.g. "no upstream tracking branch", "remote is ahead and rebase conflicted", "auth failed").
+2. What you did about it (or why you didn't).
+3. What the user should do next, if anything.
+
+Append your diagnosis to \`<agentDir>/sessions/backup-diagnostics.log\` with a timestamp prefix. Keep it short — this log is for the human, not the model.
+
+# When in doubt
+
+Do nothing destructive. Write the diagnosis and stop. The user can recover manually.`
+
+export type CreateCommitMessageSubagentOptions = {
+  fallbackMessage?: string
+}
+
+export function createCommitMessageSubagent(
+  options: CreateCommitMessageSubagentOptions = {},
+): Subagent<CommitMessagePayload> {
+  const fallback = options.fallbackMessage ?? 'chore: backup'
+  return {
+    systemPrompt: COMMIT_MESSAGE_SYSTEM_PROMPT,
+    tools: [writeTool],
+    payloadSchema: messagePayloadSchema,
+    inFlightKey: (payload) => payload.agentDir,
+    handler: async (ctx, runSession) => {
+      const userPrompt = buildCommitMessagePrompt(ctx.payload)
+      try {
+        await runSession({ userPrompt })
+      } catch {
+        await writeFile(ctx.payload.outputPath, fallback, 'utf8').catch(() => undefined)
+      }
+    },
+  }
+}
+
+export function createDiagnoseFailureSubagent(): Subagent<DiagnoseFailurePayload> {
+  return {
+    systemPrompt: DIAGNOSE_FAILURE_SYSTEM_PROMPT,
+    tools: [bashTool, readTool, writeTool],
+    payloadSchema: diagnosePayloadSchema,
+    inFlightKey: (payload) => payload.agentDir,
+    handler: async (ctx, runSession) => {
+      const userPrompt = buildDiagnosePrompt(ctx.payload)
+      try {
+        await runSession({ userPrompt })
+      } catch {
+        // Diagnosis is advisory; failures here must not propagate.
+      }
+    },
+  }
+}
+
+function buildCommitMessagePrompt(p: CommitMessagePayload): string {
+  return [
+    `Agent folder: ${p.agentDir}`,
+    `Write the commit message to: ${p.outputPath}`,
+    '',
+    '## git status --porcelain=v1 --untracked-files=all',
+    '```',
+    p.status.trim() || '(empty)',
+    '```',
+    '',
+    '## git diff --cached --stat',
+    '```',
+    p.diffstat.trim() || '(empty)',
+    '```',
+    '',
+    'Write the commit message and stop.',
+  ].join('\n')
+}
+
+function buildDiagnosePrompt(p: DiagnoseFailurePayload): string {
+  return [
+    `Agent folder: ${p.agentDir}`,
+    `Failed stage: ${p.stage}`,
+    `Exit code: ${p.exitCode}`,
+    '',
+    '## stderr',
+    '```',
+    p.stderr.trim() || '(empty)',
+    '```',
+    '',
+    '## stdout',
+    '```',
+    p.stdout.trim() || '(empty)',
+    '```',
+    '',
+    'Inspect the repo, do the smallest safe action if any, and write your diagnosis to the log file.',
+  ].join('\n')
+}
+
+export async function readMessageFile(path: string): Promise<string | null> {
+  try {
+    const raw = await readFile(path, 'utf8')
+    return raw.trim().length > 0 ? raw : null
+  } catch {
+    return null
+  }
+}
+
+export async function ensureMessageDir(outputPath: string): Promise<void> {
+  const dir = outputPath.slice(0, outputPath.lastIndexOf('/'))
+  if (dir.length === 0) return
+  await mkdir(dir, { recursive: true }).catch(() => undefined)
+}
+
+export async function cleanupMessageFile(path: string): Promise<void> {
+  await rm(path, { force: true }).catch(() => undefined)
+}
+
+export function messageFilePath(agentDir: string): string {
+  return join(agentDir, '.typeclaw', 'backup-message.tmp')
+}

package/src/bundled-plugins/memory/index.ts

@@ -1,4 +1,6 @@
-import { stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { access, constants as fsConstants, mkdir, stat, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
 
 import { CronExpressionParser } from 'cron-parser'
 import { z } from 'zod'
@@ -212,6 +214,45 @@ export default definePlugin({
           bytesAtLastRun.delete(event.sessionId)
         },
       },
+      doctorChecks: {
+        'dir-writable': {
+          description: 'memory/ exists and is writable',
+          run: async (dctx) => {
+            const dir = join(dctx.agentDir, 'memory')
+            try {
+              await access(dir, fsConstants.W_OK)
+              return { status: 'ok', message: `${dir} writable` }
+            } catch {
+              return {
+                status: 'error',
+                message: `${dir} is missing or not writable`,
+                fix: { description: 'Create memory/ in the agent folder or fix its permissions on the host.' },
+              }
+            }
+          },
+        },
+        'daily-stream-current': {
+          description: "today's daily stream file exists",
+          run: async (dctx) => {
+            const today = new Date().toISOString().slice(0, 10)
+            const rel = `memory/${today}.md`
+            const abs = join(dctx.agentDir, rel)
+            if (existsSync(abs)) return { status: 'ok', message: `${rel} present` }
+            return {
+              status: 'warning',
+              message: `${rel} missing`,
+              fix: {
+                description: `Create empty ${rel} so memory-logger has a target.`,
+                apply: async () => {
+                  await mkdir(dirname(abs), { recursive: true })
+                  await writeFile(abs, '', 'utf8')
+                  return { summary: `created ${rel}`, changedPaths: [rel] }
+                },
+              },
+            }
+          },
+        },
+      },
     }
   },
 })

package/src/channels/router.ts

@@ -776,6 +776,32 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  const fireSessionTurnStart = async (live: LiveSession): Promise<void> => {
+    if (!live.hooks) return
+    try {
+      await live.hooks.runSessionTurnStart({
+        sessionId: live.sessionId,
+        agentDir: options.agentDir,
+        origin: buildLiveOrigin(live),
+      })
+    } catch (err) {
+      logger.warn(`[channels] session.turn.start hook threw for ${live.keyId}: ${describe(err)}`)
+    }
+  }
+
+  const fireSessionTurnEnd = async (live: LiveSession): Promise<void> => {
+    if (!live.hooks) return
+    try {
+      await live.hooks.runSessionTurnEnd({
+        sessionId: live.sessionId,
+        agentDir: options.agentDir,
+        origin: buildLiveOrigin(live),
+      })
+    } catch (err) {
+      logger.warn(`[channels] session.turn.end hook threw for ${live.keyId}: ${describe(err)}`)
+    }
+  }
+
   const buildLiveOrigin = (live: LiveSession): SessionOrigin => {
     const membership = readMembership(live.key)
     return {
@@ -848,6 +874,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(`[channels] ${live.keyId} prompting batch=${batch.length} text_len=${text.length}`)
         const promptStart = now()
         const successfulSendsBeforePrompt = live.successfulChannelSends
+        await fireSessionTurnStart(live)
         try {
           await live.session.prompt(text)
           await validateChannelTurn(live, successfulSendsBeforePrompt)
@@ -856,6 +883,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         } catch (err) {
           logger.warn(`[channels] ${live.keyId}: prompt threw: ${describe(err)}`)
           live.consecutiveSends.clear()
+        } finally {
+          await fireSessionTurnEnd(live)
         }
         await fireSessionIdle(live)
         live.lastTurnAuthorIds = new Set(live.currentTurnAuthorIds)

package/src/cli/compose.ts

@@ -1,7 +1,17 @@
 import { defineCommand } from 'citty'
 
-import { composeLogs, composeRestart, composeStart, composeStatus, composeStop, type AgentResult } from '@/compose'
+import {
+  composeDoctor,
+  composeLogs,
+  composeRestart,
+  composeStart,
+  composeStatus,
+  composeStop,
+  type AgentResult,
+  type ComposeDoctorReport,
+} from '@/compose'
 import { config } from '@/config'
+import { formatJson, formatReport } from '@/doctor'
 
 import { formatComposeStatus } from './compose-status'
 import { c, spinner } from './ui'
@@ -156,6 +166,41 @@ const logsSub = defineCommand({
   },
 })
 
+const doctorSub = defineCommand({
+  meta: { name: 'doctor', description: 'diagnose every agent in immediate subdirectories of cwd' },
+  args: {
+    verbose: { type: 'boolean', alias: 'v', default: false, description: 'show check details' },
+    json: { type: 'boolean', default: false, description: 'emit the report as JSON' },
+    fix: {
+      type: 'boolean',
+      default: false,
+      description: 'attempt auto-fixes per agent and commit changes in each agent folder',
+    },
+    only: { type: 'string', description: 'comma-separated category filter' },
+    shallow: {
+      type: 'boolean',
+      default: false,
+      description: 'run cross-agent checks only; skip per-agent doctor runs',
+    },
+  },
+  async run({ args }) {
+    const only = args.only
+      ? args.only
+          .split(',')
+          .map((s) => s.trim())
+          .filter((s) => s.length > 0)
+      : undefined
+    const report = await composeDoctor({
+      rootCwd: process.cwd(),
+      fix: args.fix,
+      shallow: args.shallow,
+      ...(only !== undefined ? { only } : {}),
+    })
+    emitComposeDoctor(report, { verbose: args.verbose, json: args.json })
+    if (!report.ok) process.exit(1)
+  },
+})
+
 export const composeCommand = defineCommand({
   meta: {
     name: 'compose',
@@ -167,6 +212,7 @@ export const composeCommand = defineCommand({
     restart: restartSub,
     status: statusSub,
     logs: logsSub,
+    doctor: doctorSub,
   },
 })
 
@@ -238,3 +284,48 @@ function formatRestartDone<T extends { start: { hostPort: number } }>(result: Ag
   if (!result.ok) return `${c.red('✖')} ${c.red('failed:')} ${result.reason}`
   return `${c.green('✔')} restarted on host port ${c.cyan(String(result.data.start.hostPort))}`
 }
+
+function emitComposeDoctor(report: ComposeDoctorReport, opts: { verbose: boolean; json: boolean }): void {
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return
+  }
+  const useColor = Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined
+  const sectionHead = useColor ? c.bold : (s: string) => s
+
+  process.stdout.write(`${sectionHead('compose doctor')}  ${c.dim(report.rootCwd)}\n\n`)
+
+  process.stdout.write(`${sectionHead('Cross-agent checks')}\n`)
+  for (const check of report.crossChecks) {
+    const marker = checkMarker(check.status)
+    process.stdout.write(`  ${marker} ${check.message} ${c.dim(`(${check.name})`)}\n`)
+    if (opts.verbose && check.details !== undefined) {
+      for (const d of check.details) process.stdout.write(`      ${c.dim(`• ${d}`)}\n`)
+    }
+  }
+  process.stdout.write('\n')
+
+  for (const agent of report.agents) {
+    process.stdout.write(`${sectionHead(`Agent: ${agent.entry.name}`)}  ${c.dim(agent.entry.cwd)}\n`)
+    process.stdout.write(
+      `${opts.json ? formatJson(agent.result.final ?? agent.result.initial) : formatReport(agent.result.initial, { useColor, verbose: opts.verbose })}\n\n`,
+    )
+  }
+
+  process.stdout.write(
+    `${report.ok ? c.green('●') : c.red('●')} compose doctor ${report.ok ? 'passed' : 'found issues'}\n`,
+  )
+}
+
+function checkMarker(status: 'ok' | 'warning' | 'error' | 'info'): string {
+  switch (status) {
+    case 'ok':
+      return c.green('✓')
+    case 'warning':
+      return c.yellow('!')
+    case 'error':
+      return c.red('✗')
+    case 'info':
+      return c.cyan('i')
+  }
+}