kimaki 1.4.0 → 1.6.0

package/src/cli/bot.ts

@@ -10,7 +10,7 @@ import { setTimeout as sleep } from 'node:timers/promises'
 import dedent from 'string-dedent'
 import { wrapJsonSchema, type Goke } from 'goke'
 
-import { distCliEntry, writeAutostartScript } from '../autostart.ts'
+import { distCliEntry, removeAutostartScript, stableNodePath, writeAutostartScript } from '../autostart.ts'
 import { parseDisabledPromptSections, parseDisabledSkills, PROMPT_SECTIONS } from '../builtin-skills.ts'
 import { callBot, DEFAULT_LOCK_PORT, RESTART_EXIT_CODE, startLockServer } from '../lock-server.ts'
 import { parseDuration } from '../duration.ts'
@@ -59,8 +59,10 @@ async function supervise(): Promise<never> {
   for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) {
     process.on(signal, () => state.child?.kill('SIGTERM'))
   }
+  // Resolved before any Node upgrade: `kimaki restart` must not spawn the deleted binary.
+  const node = stableNodePath()
   while (true) {
-    const child = spawn(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {
+    const child = spawn(node, [...process.execArgv, ...process.argv.slice(1)], {
       stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
       env: { ...process.env, KIMAKI_SUPERVISED: '1' },
     })
@@ -93,6 +95,8 @@ export function registerStartCommand(cli: Goke) {
     .option('--disable-skills <list>', 'Built-in Kimaki skills to turn off: "all" or a comma separated list (kimaki-debug,kimaki-tunnel)')
     .option('--disable-prompt <section>', wrapJsonSchema<string[]>({ type: 'array', items: { type: 'string' }, description: `System prompt section to remove from new sessions (repeatable): ${PROMPT_SECTIONS.join(', ')}` }))
     .option('--no-analytics', 'Disable anonymous usage analytics (same as KIMAKI_STRADA_ENABLED=0)')
+    .option('--coordinator [enabled]', wrapJsonSchema<boolean>({ type: 'boolean', default: true, description: 'Channel messages go to one long coordinator session that starts threads for the work. "false" turns it off (/toggle-coordinator sets one channel)' }))
+    .option('--no-autostart', 'Do not open a terminal with the bot when OpenCode starts (for bots run by launchd, systemd or pm2)')
     .option('--if-not-running', 'Start only if no bot runs; never stop the running one (used by autostart)')
     .action(async (options) => {
       // The IPC check ignores a KIMAKI_SUPERVISED leaked into a shell by an older bot.
@@ -103,7 +107,7 @@ export function registerStartCommand(cli: Goke) {
       // Bot code loads only here: the other subcommands start without it.
       const [
         { startBot },
-        { ensureOpencode, kimakiShellCommand, runOnboarding, startCaffeinate },
+        { ensureOpencode, runOnboarding, startCaffeinate },
         { emitEvent, gatewayCredentials, gatewayUrlsFromEnv, installUrlFor, readSavedCredentials, resolveCredentials, restApiUrl },
         { openDb },
         { createAnalytics },
@@ -201,14 +205,13 @@ export function registerStartCommand(cli: Goke) {
       // The agent calls this same install. Prefer the built dist entry, so agent
       // commands skip the tsx loader also when the bot runs from src.
       const distCli = distCliEntry()
-      const kimaki = kimakiShellCommand({
-        command: fs.existsSync(distCli)
-          ? [process.execPath, distCli]
-          : [process.execPath, ...process.execArgv, process.argv[1] ?? 'kimaki'],
-      })
+      const node = stableNodePath()
+      const kimakiArgv = fs.existsSync(distCli)
+        ? [node, distCli]
+        : [node, ...process.execArgv, process.argv[1] ?? 'kimaki']
 
       const bot = await startBot({
-        kimakiCommand: kimaki,
+        kimakiArgv,
         dataDir,
         token: credentials.token,
         appId: credentials.appId,
@@ -223,6 +226,7 @@ export function registerStartCommand(cli: Goke) {
         allowAllUsers: Boolean(options.allowAllUsers),
         disabledSkills,
         disabledPrompt,
+        coordinator: options.coordinator,
       })
       if (bot instanceof Error) failStartup(bot)
       // exit() keeps process.exitCode: the restart route sets RESTART_EXIT_CODE before its SIGTERM.
@@ -235,25 +239,30 @@ export function registerStartCommand(cli: Goke) {
       process.once('disconnect', shutdown)
 
       const gateway = credentials.mode === 'gateway'
-      const onboarded = await runOnboarding({ bot, dataDir, guildId: options.guild ?? install?.guildId, installUrl, kimaki, gateway, installerId: install?.installerId, machine })
+      const onboarded = await runOnboarding({ bot, dataDir, guildId: options.guild ?? install?.guildId, installUrl, gateway, installerId: install?.installerId, machine })
       // The bot keeps running; the next start retries onboarding.
       if (onboarded instanceof Error) {
         logger.error(`onboarding failed`, onboarded)
         if (!process.stdin.isTTY) emitEvent({ type: 'error', message: `Onboarding failed: ${onboarded.message}. The bot is running; restart kimaki to retry.` })
         return
       }
-      if (onboarded) process.stderr.write(`Onboarding thread: https://discord.com/channels/${onboarded.guildId}/${onboarded.threadId}\n`)
+      if (onboarded) process.stderr.write(`Onboarding: https://discord.com/channels/${onboarded.guildId}/${onboarded.threadId}\n`)
       const voiceChannels = await ensureVoiceChannels(bot, { machine })
       if (voiceChannels instanceof Error) logger.warn('cannot create the Kimaki voice channel', voiceChannels)
-      // Only the default port: the plugin checks that one. Runtime flags only;
-      // credentials, onboarding and --voice are saved in SQLite.
-      if (lock.port === DEFAULT_LOCK_PORT) {
+      // --no-autostart removes the script on every start, so the opt-out sticks while
+      // launchd or systemd passes the flag. Only the default port: the plugin checks
+      // that one. Runtime flags only; credentials, onboarding and --voice are saved in SQLite.
+      if (options.noAutostart) {
+        const removed = await removeAutostartScript({ dataDir })
+        if (removed instanceof Error) logger.warn('cannot remove the autostart script', removed)
+      } else if (lock.port === DEFAULT_LOCK_PORT) {
         const autostart = await writeAutostartScript({ dataDir, args: [
           ...(options.worktrees ? ['--worktrees'] : []),
           ...(options.allowAllUsers ? ['--allow-all-users'] : []),
           ...(options.disableSkills ? ['--disable-skills', options.disableSkills] : []),
           ...disabledPrompt.flatMap((section) => ['--disable-prompt', section]),
           ...(options.noAnalytics ? ['--no-analytics'] : []),
+          ...(options.coordinator ? [] : ['--coordinator', 'false']),
           ...(options.machineName ? ['--machine-name', options.machineName] : []),
         ] })
         if (autostart instanceof Error) logger.warn('cannot write the autostart script', autostart)

package/src/cli/discord.ts

@@ -1,6 +1,8 @@
 // Discord-facing commands: agent UI (buttons, upload requests) through the
 // running bot, plus thread/user lookups and uploads with the saved bot token.
 
+import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import { ChannelType } from 'discord-api-types/v10'
 import { wrapJsonSchema, type Goke } from 'goke'
@@ -15,22 +17,23 @@ function agentShell() {
   return { fromShell: Boolean(process.env['OPENCODE_SESSION_ID']), toolCall: process.env['KIMAKI_TOOL_CALL'] }
 }
 
-// The model reads this after `kimaki buttons`: a reminder to explain the buttons if it did not.
+// The model reads this after `kimaki buttons`. Text planned before a tool call
+// is sometimes never written (#256), so it asks for a missing answer or explanation.
 const BUTTONS_SHOWN = dedent`
 
   Buttons shown in Discord.
 
-  NB: never show only buttons with short labels.
-  The user cannot see tool calls, command outputs, or subagent and task results. They only see your text.
-  Check the text you wrote before this call. It must explain:
+  The user cannot see tool calls, command outputs, your reasoning, or subagent and task results. They only see your text.
+  If this turn has no text yet that answers the user and explains the buttons, write it now:
+  - your answer to what the user asked, if anything
   - what was done in this session, concisely, including any findings from tool or task outputs that the choice depends on
   - what each button does and its tradeoffs
-  If anything is missing, write it now. Be concise: a few short lines, no walls of text. Do not only repeat the button labels. Then stop and wait for the click.
+  Be concise: a few short lines in plain sentences, no walls of text. Do not only repeat the button labels. Then stop and wait for the click.
 
 `
 // buttons, upload-request
 export function registerAgentUiCommands(cli: Goke) {
-  cli.command('buttons', 'Show 1-3 action buttons. Call last, after visible text')
+  cli.command('buttons', 'Show 1-3 action buttons. Explain them in your text')
     .option('--data-dir <path>', DATA_DIR_HELP)
     .option('-s, --session <id>', SESSION_HELP)
     .option('-b, --button <spec>', wrapJsonSchema<string[]>({ type: 'array', items: { type: 'string' }, description: "Repeatable: Label[:white|blue|green|red]" }))
@@ -113,4 +116,25 @@ export function registerDiscordCommands(cli: Goke) {
       // Waits for Discord: big files and a busy thread take longer than the 30s default.
       await action({ route: 'upload', dataDir: options.dataDir, input, signal: AbortSignal.timeout(5 * 60_000) })
     })
+
+  cli.command('diagram <input>', 'Render a Mermaid diagram (file path, or - for stdin) to a light themed PNG. Upload it with upload-to-discord')
+    .option('-o, --output <path>', 'PNG file to write (default: input path with .png, or a temp file for stdin)')
+    .option('--dark', 'Dark theme instead of light')
+    .action(async (input, options) => {
+      const source = input === '-' ? await readStdin() : await fs.promises.readFile(input, 'utf8').catch((error: Error) => error)
+      if (source instanceof Error) fail(source)
+      const { renderDiagram } = await import('../diagram.ts')
+      const png = renderDiagram(source, { theme: options.dark ? 'dark' : 'light' })
+      if (png instanceof Error) fail(png)
+      const output = path.resolve(options.output ?? (input === '-' ? path.join(os.tmpdir(), `kimaki-diagram-${Date.now()}.png`) : input.replace(/(\.\w+)?$/, '.png')))
+      const written = await fs.promises.writeFile(output, png).catch((error: Error) => error)
+      if (written instanceof Error) fail(written)
+      process.stdout.write(`${output}\n`)
+    })
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk))
+  return Buffer.concat(chunks).toString('utf8')
 }

package/src/cli/schedule.ts

@@ -7,7 +7,10 @@ import { wrapJsonSchema, type Goke } from 'goke'
 
 import { BotNotRunningError } from '../errors.ts'
 import { callBot } from '../lock-server.ts'
-import { action, DATA_DIR_HELP, dataDirOrDefault, discordApi, fail, openCliDb, parseTarget, printJson, readClient, SESSION_HELP, targetOrEnv, waitAndPrintSession } from './shared.ts'
+import { action, DATA_DIR_HELP, dataDirOrDefault, discordApi, fail, openCliDb, parseTarget, printJson, readClient, SESSION_HELP, targetOrEnv, waitAndPrintSessions } from './shared.ts'
+
+// Bare `--wait`: long enough that the shell timeout ends it first.
+const DEFAULT_WAIT_SECONDS = 24 * 60 * 60
 
 export function registerSendCommand(cli: Goke) {
   cli.command('send', 'Start a session in a channel, or continue a thread')
@@ -16,7 +19,7 @@ export function registerSendCommand(cli: Goke) {
     .option('-d, --project <path>', 'Project directory of the new thread')
     .option('--thread <id>', 'Continue this thread (ID or URL)')
     .option('-s, --session <id>', 'Continue this session: session ID, thread ID or thread URL')
-    .option('-p, --prompt <text>', 'Prompt; thread suffixes . queue and . btw are supported')
+    .option('-p, --prompt <text>', 'Prompt; thread suffixes . queue and . btw are supported').required()
     .option('-f, --file <path>', wrapJsonSchema<string[]>({ type: 'array', items: { type: 'string' }, description: 'Attach a local file (repeatable)' }))
     .option('-n, --name <text>', 'Thread name')
     .option('--agent <name>', 'Agent ID')
@@ -28,12 +31,14 @@ export function registerSendCommand(cli: Goke) {
     .option('--parent-session <id>', 'Record the parent session in session metadata')
     .option('--permission <rule>', wrapJsonSchema<string[]>({ type: 'array', items: { type: 'string' }, description: 'Repeatable: tool[:pattern]:allow|deny|ask' }))
     .option('--notify-only', 'Post a notification thread without a model turn')
-    .option('--wait', 'Wait until idle or input is needed, then print the session')
+    .option('--wait [seconds]', 'Wait until idle or input is needed (at most this many seconds, default 1 day), then print the session')
     .option('--send-at <when>', 'Schedule: UTC ISO date ending in Z, or cron expression (UTC)')
     .option('--pre-run <command>', 'Scheduled only: run first in the project. Exit 0 starts, stdout is appended')
     .option('--allow-concurrency', 'Scheduled only: allow overlapping runs of this routine')
     .action(async (options) => {
-      if (options.wait && options.sendAt) fail(new Error('--wait cannot be used with --send-at: the routine runs later'))
+      const wait = options.wait === undefined ? undefined : options.wait === '' ? DEFAULT_WAIT_SECONDS : Number(options.wait)
+      if (wait !== undefined && !(Number.isFinite(wait) && wait > 0 && wait <= DEFAULT_WAIT_SECONDS)) fail(new Error('--wait takes a positive number of seconds, at most 86400'))
+      if (wait !== undefined && options.sendAt) fail(new Error('--wait cannot be used with --send-at: the routine runs later'))
       if (options.thread !== undefined && options.session !== undefined) fail(new Error('Use exactly one of --channel, --thread, --session, --project'))
       const continued = options.thread ?? options.session
       const target = continued === undefined ? {} : parseTarget(continued)
@@ -49,11 +54,14 @@ export function registerSendCommand(cli: Goke) {
         dataDir: dataDirOrDefault(options.dataDir),
         route: 'send',
         signal: AbortSignal.timeout(25 * 60_000),
-        input: { ...input, sendAt: options.sendAt, preRun: options.preRun, allowConcurrency: options.allowConcurrency },
+        input: {
+          ...input, wait, sendAt: options.sendAt, preRun: options.preRun, allowConcurrency: options.allowConcurrency,
+          senderSessionId: process.env['OPENCODE_SESSION_ID'] || undefined,
+        },
       })
       if (result instanceof BotNotRunningError) {
         // No local bot (CI, another machine): the bot that owns the channel runs it (remote-send.ts).
-        if (options.sendAt || options.wait) fail(new Error('Kimaki bot is not running here. --send-at and --wait need a local bot.'))
+        if (options.sendAt || wait !== undefined) fail(new Error('Kimaki bot is not running here. --send-at and --wait need a local bot.'))
         const [{ sendInput }, { sendWithoutBot }] = await Promise.all([import('../lock-routes.ts'), import('../remote-send.ts')])
         const parsed = sendInput.safeParse(input)
         if (!parsed.success) fail(new Error(parsed.error.issues.map((issue) => issue.message).join('; ')))
@@ -65,10 +73,16 @@ export function registerSendCommand(cli: Goke) {
       }
       if (result instanceof Error) fail(result)
       process.stdout.write(`${JSON.stringify(result.data)}\n`)
-      if (!options.wait) return
+      if (wait === undefined) return
       const data = result.data
       if (!data || typeof data !== 'object' || !('sessionId' in data) || typeof data.sessionId !== 'string') fail(new Error('--wait requires an AI session, not --notify-only'))
-      await waitAndPrintSession({ client: await readClient(), sessionId: data.sessionId })
+      await waitAndPrintSessions({
+        client: await readClient(),
+        sessionIds: [data.sessionId],
+        dataDir: options.dataDir,
+        signal: AbortSignal.timeout(wait * 1000),
+        timeout: `${wait}s`,
+      })
     })
 }
 
@@ -134,7 +148,7 @@ export function registerScheduleCommands(cli: Goke) {
     }
   }
 
-  cli.command('sleep', 'Wake this session later with a new message in the same thread. Run it last, after your text. To monitor slow events (email replies, PR reviews), wait 2h or more; never poll every few minutes')
+  cli.command('sleep', 'Wake this session later with a new message in the same thread. Run it last, after your text. To monitor slow events (email replies, PR reviews), wait 2h or more; never poll every few minutes. When blocked on a user action outside the chat (a sudo or permission dialog, a login), ask for it, assume they will do it, and sleep 5m, then check and continue on your own')
     .option('--data-dir <path>', DATA_DIR_HELP)
     .option('--duration <duration>', 'Relative wait, e.g. 30m, 2h, 1d')
     .option('--until <date>', 'UTC ISO date ending in Z')

package/src/cli/session.ts

@@ -26,7 +26,7 @@ import {
   SESSION_HELP,
   resolveTarget,
   targetOrEnv,
-  waitAndPrintSession,
+  waitAndPrintSessions,
 } from './shared.ts'
 
 const execFileAsync = promisify(execFile)
@@ -44,8 +44,11 @@ export function registerSessionQueryCommands(cli: Goke) {
       const errorCode = options.active ? 64 : 1
       const client = await readClient(errorCode)
       const directory = options.all ? undefined : await projectDirectory({ project: options.project, channel: undefined, dataDir: options.dataDir })
+      // By project ID, not directory: sessions in linked worktrees of the same clone belong to the project too.
+      const location = directory ? await client.location.get({ location: { directory } }).catch((error: Error) => error) : undefined
+      if (location instanceof Error) fail(location, errorCode)
       const [sessions, active, forms, permissions] = await Promise.all([
-        allSessions({ client, directory }),
+        allSessions({ client, project: location?.project.id }),
         client.session.active().catch((error: Error) => error),
         client.form.list().catch((error: Error) => error),
         client.permission.request.list().catch((error: Error) => error),
@@ -82,15 +85,30 @@ export function registerSessionQueryCommands(cli: Goke) {
       process.stdout.write(`${transcriptsDir({ dataDir })}: ${result.written} written, ${result.skipped} skipped, ${result.failed} failed\n`)
     })
 
-  cli.command('session wait <id>', 'Wait until idle or waiting for input, then print the session')
+  cli.command('session wait [...ids]', 'Wait until every session is idle or waits for the user, then print each one and why it returned')
+    .example('kimaki session wait ses_abc 1495130000000000000')
+    .example(`kimaki session wait $(kimaki session list --all --active | awk '{print $1}')`)
     .option('--data-dir <path>', DATA_DIR_HELP)
-    .option('--timeout <duration>', 'Timeout, for example 30m or 2h')
-    .action(async (id, options) => {
-      const { sessionId } = await resolveTarget(id, options.dataDir)
+    .option('--timeout <duration>', 'Timeout, for example 30m or 2h; exit 1 when a session still runs')
+    .action(async (ids, options) => {
       const timeout = options.timeout ? parseDuration(options.timeout) : undefined
       if (timeout instanceof Error) fail(new Error('Use --timeout 30m, 2h, or another positive duration'))
+      // Empty when `$(kimaki session list --active)` found nothing.
+      if (ids.length === 0) {
+        process.stdout.write('No sessions to wait for\n')
+        return
+      }
+      const sessionIds: string[] = []
+      for (const id of ids) sessionIds.push((await resolveTarget(id, options.dataDir)).sessionId)
       const client = await readClient()
-      await waitAndPrintSession({ client, sessionId, signal: timeout === undefined ? undefined : AbortSignal.timeout(timeout) })
+      const done = await waitAndPrintSessions({
+        client,
+        sessionIds: [...new Set(sessionIds)],
+        dataDir: options.dataDir,
+        signal: timeout === undefined ? undefined : AbortSignal.timeout(timeout),
+        timeout: options.timeout ?? '',
+      })
+      if (!done) process.exitCode = 1
     })
 
   cli.command('session editors <file>', 'List sessions that last edited a file, newest first')
@@ -147,7 +165,7 @@ export function registerSessionQueryCommands(cli: Goke) {
     })
 }
 
-// abort, archive, title, queue, command, shell, btw, fork, resume: all through the bot.
+// abort, archive, compact, title, queue, command, shell, btw, fork, resume: all through the bot.
 export function registerSessionActionCommands(cli: Goke) {
   cli.command('session abort [id]', 'Stop the running turn and clear its queue')
     .option('--data-dir <path>', DATA_DIR_HELP)
@@ -157,6 +175,10 @@ export function registerSessionActionCommands(cli: Goke) {
     .option('--data-dir <path>', DATA_DIR_HELP)
     .action(async (id, options) => action({ route: 'session.archive', dataDir: options.dataDir, input: targetOrEnv(id) }))
 
+  cli.command('session compact [id]', 'Summarize the session history after its current turn (default: this session)')
+    .option('--data-dir <path>', DATA_DIR_HELP)
+    .action(async (id, options) => action({ route: 'session.compact', dataDir: options.dataDir, input: targetOrEnv(id) }))
+
   cli.command('session title <title>', 'Rename the session and its Discord thread')
     .option('--data-dir <path>', DATA_DIR_HELP)
     .option('-s, --session <id>', SESSION_HELP)
@@ -224,10 +246,11 @@ export function registerSessionHistoryCommands(cli: Goke) {
       await pipeline(fs.createReadStream(file), process.stdout)
     })
 
-  cli.command('session read <id>', 'Print the messages of a session from OpenCode as markdown')
+  cli.command('session read <id>', 'Print the prompts and final answers of a session as markdown')
     .option('--data-dir <path>', DATA_DIR_HELP)
-    .option('--thinking', 'Include reasoning')
-    .option('--verbose', 'Include full tool inputs and outputs')
+    .option('--full', 'Every message with tool calls')
+    .option('--thinking', 'Full output with reasoning')
+    .option('--verbose', 'Full output with tool inputs and outputs')
     .option('--json', 'Print raw OpenCode messages')
     .action(async (id, options) => {
       // Subagent sessions are not in SQLite: resolveTarget keeps their ID.
@@ -238,7 +261,7 @@ export function registerSessionHistoryCommands(cli: Goke) {
         if (messages instanceof Error) fail(messages)
         return printJson(messages)
       }
-      const markdown = await readSessionMarkdown({ client, sessionId, thinking: options.thinking, verbose: options.verbose })
+      const markdown = await readSessionMarkdown({ client, sessionId, full: options.full, thinking: options.thinking, verbose: options.verbose })
       if (markdown instanceof Error) fail(markdown)
       process.stdout.write(`${markdown}\n`)
     })

package/src/cli/shared.ts

@@ -10,12 +10,12 @@ import path from 'node:path'
 import type { OpenCodeClient } from '@opencode/client'
 import { ChannelType } from 'discord-api-types/v10'
 
-import { DbError } from '../errors.ts'
+import { BotNotRunningError, DbError } from '../errors.ts'
 import { canonicalPath } from '../file-edit-log.ts'
 import type { LockRouteInput, LockRouteName } from '../lock-routes.ts'
 import { callBot } from '../lock-server.ts'
 import { resolveOpencode } from '../opencode-server.ts'
-import { readSessionMarkdown, resolveSession, waitForSessionReady } from '../session-events.ts'
+import { readSessionMarkdown, resolveSession, waitForSessions, type WaitStatus } from '../session-events.ts'
 
 export const DATA_DIR_HELP = 'Data directory (default: ~/.kimaki)'
 export const SESSION_HELP = 'Session ID, Discord thread ID or thread URL (default: OPENCODE_SESSION_ID)'
@@ -90,12 +90,47 @@ export async function resolveTarget(value: string, dataDir: string | undefined):
   fail(result)
 }
 
-export async function waitAndPrintSession({ client, sessionId, signal }: { client: OpenCodeClient; sessionId: string; signal?: AbortSignal }) {
-  const waited = await waitForSessionReady({ client, sessionId, signal })
-  if (waited instanceof Error) fail(waited)
-  const markdown = await readSessionMarkdown({ client, sessionId })
-  if (markdown instanceof Error) fail(markdown)
-  process.stdout.write(`${markdown}\n`)
+function statusText({ sessionId, status, buttons, timeout }: { sessionId: string; status: WaitStatus; buttons: string[]; timeout: string }): string {
+  // `kimaki buttons` ends the turn, so the run looks finished while the session waits for a click.
+  if (buttons.length > 0 && status !== 'running' && status !== 'question' && status !== 'permission') {
+    return `is paused: it showed buttons (${buttons.join(', ')}) and waits for the user to click one, so its work may not be done`
+  }
+  if (status === 'finished') return 'finished its run'
+  if (status === 'failed') return 'ended its run with an error'
+  if (status === 'interrupted') return 'was interrupted, by an abort or by a new user message that started another run'
+  if (status === 'idle') return 'was already idle: its last run ended before the wait started'
+  if (status === 'question') return 'is paused: it waits for the user to answer a question, so its work is not done'
+  if (status === 'permission') return 'is paused: it waits for the user to allow a permission, so its work is not done'
+  return `is still running after ${timeout}. Run kimaki session wait ${sessionId} to wait for the rest`
+}
+
+// Waits until every session ended its run or paused for the user, then prints each one in
+// order under a header that says why it returned. Returns false when `signal` ended the wait first.
+export async function waitAndPrintSessions({ client, sessionIds, dataDir, signal, timeout }: {
+  client: OpenCodeClient
+  sessionIds: readonly string[]
+  dataDir: string | undefined
+  signal?: AbortSignal
+  timeout: string
+}): Promise<boolean> {
+  const statuses = await waitForSessions({ client, sessionIds, signal })
+  if (statuses instanceof Error) fail(statuses)
+  // Buttons live in the bot's memory. Without a bot nothing can show them.
+  const buttons = await callBot({ dataDir: dataDirOrDefault(dataDir), route: 'session.buttons', input: { sessionIds: [...sessionIds] } })
+  if (buttons instanceof Error && !(buttons instanceof BotNotRunningError)) process.stderr.write(`cannot read pending buttons: ${buttons.message}\n`)
+  for (const sessionId of sessionIds) {
+    const status = statuses.get(sessionId) ?? 'running'
+    const text = statusText({ sessionId, status, buttons: buttons instanceof Error ? [] : buttons.data[sessionId] ?? [], timeout })
+    const header = `=== ${sessionId} ${text} ===`
+    if (status === 'running') {
+      process.stdout.write(`${header}\n\n`)
+      continue
+    }
+    const markdown = await readSessionMarkdown({ client, sessionId })
+    if (markdown instanceof Error) fail(markdown)
+    process.stdout.write(`${header}\n\n${markdown}\n\n`)
+  }
+  return [...statuses.values()].every((status) => status !== 'running')
 }
 
 // Discord REST with the bot token: KIMAKI_BOT_TOKEN (no kimaki.db needed, e.g. CI), else saved credentials.

package/src/cli-discord.e2e.test.ts

@@ -40,7 +40,12 @@ test('independent Discord CLI lists threads and users, uploads a file, and reads
   // Many files keep argument order, numbered, images and files mixed.
   fs.mkdirSync(path.join(server.root, 'other'), { recursive: true })
   for (const name of ['b.png', 'my shot.png', 'other/b.png']) fs.writeFileSync(path.join(server.root, name), 'png')
-  await cli(['upload-to-discord', ...['b.png', 'report.txt', 'my shot.png', 'other/b.png'].map((name) => path.join(server.root, name)), '--session', started.sessionId])
+  const uploaded = await cli(['upload-to-discord', ...['b.png', 'report.txt', 'my shot.png', 'other/b.png'].map((name) => path.join(server.root, name)), '--session', started.sessionId])
+  // Each file with its Discord URL, in argument order, so a coordinator can repost them (the twin uses data: URLs).
+  expect(uploaded.stdout).toMatchInlineSnapshot(`
+    "{"uploaded":[{"name":"b.png","url":"data:application/octet-stream;base64,cG5n"},{"name":"report.txt","url":"data:application/octet-stream;base64,cmVwb3J0"},{"name":"my shot.png","url":"data:application/octet-stream;base64,cG5n"},{"name":"b.png","url":"data:application/octet-stream;base64,cG5n"}]}
+    "
+  `)
   // The agent learns that nothing was posted.
   const missing = await cli(['upload-to-discord', path.join(server.root, 'missing.png'), '--session', started.sessionId]).catch((error: { stderr: string }) => error)
   expect(missing.stderr.replace(server.root, '<root>')).toMatchInlineSnapshot(`
@@ -51,20 +56,20 @@ test('independent Discord CLI lists threads and users, uploads a file, and reads
   const install = await cli(['bot', 'install-url'])
   expect(await twin.discord.thread(started.threadId).text()).toMatchInlineSnapshot(`
     "--- from: assistant (TestBot)
-    » **CLI:** Discord CLI flow
+    -# » **CLI:** Discord CLI flow
     -# *using deterministic-provider/deterministic-v2 ⋅ build*
     ok
-    -# *project ⋅ main ⋅ Ns ⋅ deterministic-v2*
-    [file: attachment://report.txt]
+    -# *main ⋅ Ns ⋅ deterministic-v2*
+    [file: data:application/octet-stream;base64,cmVwb3J0]
     [attachment: report.txt]
     -# 1. \`b.png\`
-    [media: attachment://b.png]
+    [media: data:application/octet-stream;base64,cG5n]
     -# 2. \`report.txt\`
-    [file: attachment://report.txt]
+    [file: data:application/octet-stream;base64,cmVwb3J0]
     -# 3. \`my shot.png\`
-    [media: attachment://my_shot.png]
+    [media: data:application/octet-stream;base64,cG5n]
     -# 4. \`b.png\`
-    [media: attachment://4-b.png]
+    [media: data:application/octet-stream;base64,cG5n]
     [attachment: b.png]
     [attachment: report.txt]
     [attachment: my_shot.png]