@doguyilmaz/konvoy 0.1.1

package/src/adapters/opencode.ts

@@ -0,0 +1,64 @@
+import type { Binding, KonvoyEvent, SpawnPlan, TurnContext } from '../types'
+import { classifyError, safeJson, stripControlChars, withPrelude, type Adapter } from './types'
+
+export const opencodeAdapter: Adapter = {
+  id: 'opencode',
+  bin: 'opencode',
+  supportsPresetSessionId: false,
+
+  turn(ctx: TurnContext): SpawnPlan {
+    const cmd = [ctx.bin ?? 'opencode', 'run', '--standalone', '--format', 'json']
+    if (ctx.binding?.foreignId) cmd.push('-s', ctx.binding.foreignId)
+    else cmd.push('--title', `konvoy:${ctx.slug}`)
+    if (ctx.model) cmd.push('-m', `${ctx.model}#${ctx.effort}`)
+    if (ctx.permission === 'yolo') cmd.push('--auto')
+    cmd.push('--', withPrelude(ctx))
+    return { cmd, cwd: ctx.cwd }
+  },
+
+  parse(line: string): KonvoyEvent[] {
+    const o = safeJson(line)
+    if (!o) return []
+    const events: KonvoyEvent[] = []
+    if (typeof o.sessionID === 'string') events.push({ t: 'session', foreignId: stripControlChars(o.sessionID) })
+
+    const part = o.part as { text?: string; tool?: string; state?: { status?: string } } | undefined
+    switch (o.type) {
+      case 'text':
+        if (part?.text) events.push({ t: 'text', text: part.text })
+        break
+      case 'reasoning':
+        if (part?.text) events.push({ t: 'thinking', text: part.text })
+        break
+      case 'tool_use':
+        events.push({ t: 'tool', name: part?.tool ?? 'tool', status: part?.state?.status === 'error' ? 'error' : 'ok' })
+        break
+      case 'step_finish': {
+        const step = o.part as
+          | { cost?: number; tokens?: { input?: number; output?: number; cache?: { read?: number; write?: number } } }
+          | undefined
+        const tokens = step?.tokens
+        if (tokens) {
+          // opencode's `input` is the uncached remainder, like claude's and unlike codex's —
+          // its own `total` is input + output + cache, which is what settles that. It also
+          // reports the turn's cost here, on the same part.
+          const input = (tokens.input ?? 0) + (tokens.cache?.read ?? 0) + (tokens.cache?.write ?? 0)
+          events.push({ t: 'usage', inputTokens: input, outputTokens: tokens.output, costUsd: step?.cost })
+        }
+        break
+      }
+      case 'error': {
+        const error = o.error as { message?: string; data?: { message?: string } } | undefined
+        const message = error?.data?.message ?? error?.message ?? ''
+        events.push({ t: 'error', message, kind: classifyError(message) })
+        break
+      }
+    }
+    return events
+  },
+
+  attach(binding: Binding): SpawnPlan {
+    if (!binding.foreignId) return { cmd: ['opencode'] }
+    return { cmd: ['opencode', '--session', binding.foreignId] }
+  },
+}

package/src/adapters/types.ts

@@ -0,0 +1,108 @@
+import type { AgentId, Binding, KonvoyEvent, SpawnPlan, TurnContext } from '../types'
+
+export interface Adapter {
+  id: AgentId
+  bin: string
+  supportsPresetSessionId: boolean
+  turn(ctx: TurnContext): SpawnPlan
+  parse(line: string): KonvoyEvent[]
+  attach(binding: Binding): SpawnPlan
+  prepare?(ctx: TurnContext): Promise<void>
+}
+
+// konvoy's own instruction, owned here rather than vendored from any installed skill — a
+// user's own such skill is already reachable via `harness: inherit`. It shapes what the user
+// reads, not what agents exchange, so it asks for omission, never compression.
+export const BRIEF_INSTRUCTION =
+  'Lead with the action. Number multi-step work. End with one concrete next step. Skip preamble, recap, and closing pleasantries.'
+
+// konvoy has no model and cannot decide when a turn hands off — only the agent running it
+// knows. This instruction is what asks it to say so. A turn not handing work over must emit
+// nothing: the envelope costs output tokens only on the turns that actually use it.
+export const DELEGATION_INSTRUCTION =
+  'If you are handing work to another agent, end your reply with a block like:\n' +
+  '<<<konvoy\n' +
+  'to: <agent id or role>\n' +
+  'task: <imperative, one line>\n' +
+  'open: <optional list>\n' +
+  'decisions: <optional list>\n' +
+  '>>>\n' +
+  'If this turn is not handing work over, emit nothing — no block at all.'
+
+// One composition point rather than four: the adapters cannot drift in how they join these,
+// and the prelude leads because a stable prefix is what prompt caching discounts. The style
+// and delegation instructions trail the prompt for the same reason — they must never join
+// the cached prefix.
+export function withPrelude(ctx: TurnContext): string {
+  const base = ctx.prelude ? `${ctx.prelude}\n\n${ctx.prompt}` : ctx.prompt
+  const styled = ctx.style === 'brief' ? `${base}\n\n${BRIEF_INSTRUCTION}` : base
+  return ctx.delegation ? `${styled}\n\n${DELEGATION_INSTRUCTION}` : styled
+}
+
+export function safeJson(line: string): Record<string, unknown> | null {
+  const trimmed = line.trim()
+  if (!trimmed.startsWith('{')) return null
+  try {
+    return JSON.parse(trimmed) as Record<string, unknown>
+  } catch {
+    return null
+  }
+}
+
+// foreignId, the model a CLI echoes back, and the auth detail string are konvoy's own metadata,
+// read from a CLI's stdout and later printed to the terminal or stored. Control bytes (OSC/SGR
+// escapes) have no legitimate use there, so they are stripped at the parse boundary rather than
+// wherever the value later gets printed.
+// CSI (ESC [ … final), OSC (ESC ] … BEL or ST) and two-byte ESC sequences. Their parameters
+// are printable, so dropping only the ESC byte would leave "[2K" behind in an id or a notice.
+const ANSI = /\x1b\[[0-?]*[ -\/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g
+
+export function stripControlChars(value: string): string {
+  return value.replace(ANSI, '').replace(/[\x00-\x1f\x7f]/g, '')
+}
+
+// For a notice or a table cell: one line, no control bytes, capped — an agent's own words or a
+// CLI's stderr can run to kilobytes and can carry escapes that rewrite what konvoy printed.
+export function oneLine(value: string, max = 200): string {
+  const flat = stripControlChars(value.replace(/\r?\n/g, ' ')).replace(/ {2,}/g, ' ').trim()
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat
+}
+
+// For an agent's final text: keep newlines and tabs, drop every other control byte — CR
+// included, which would let a line overwrite the one before it.
+export function safeText(value: string): string {
+  return value.replace(ANSI, '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '')
+}
+
+// Extracted from the four installed binaries on 2026-09-20. Expiry is phrased around
+// "session" or "token" — "Cloud gateway session expired", "AWS session has expired",
+// "Login token is expired", "MCP OAuth access token is expired" — so requiring the literal
+// word "credentials" missed every real expiry. The noun must sit next to the state, or a
+// parser's "Unexpected token" and "Invalid token in JSON" read as auth failures.
+const AUTH =
+  /invalid api key|authentication failed|not authenticated|not (?:logged|signed) in|unauthorized|bad credentials|\b401\b|please run \/?login|(?:credential|token|session)s? (?:are |is |has |have )?(?:expired|revoked|invalid|missing)|token refresh failed|unable to refresh token/
+// `hit your <window> limit` and `rate_limit` are captured verbatim from Claude Code on
+// 2026-09-20: "You've hit your weekly limit · resets 7am" and "You've hit your session limit
+// · resets 12:40am", both carrying error type rate_limit / HTTP 429. The remaining
+// alternatives are conjecture from other vendors' wording and have never been observed here.
+// kiro-cli emits no rate-limit prose at all, only AWS exception type names, and those carry
+// no separators once lowercased — hence the optional separators below. codex's five-hour
+// window is worded "5-hour usage limit", which "usage limit" already covers.
+const RATE =
+  /hit your \w+ limit|rate[_ ]?limit|quota exceeded|too ?many ?requests|usage limit|weekly limit|\d+[- ]hour (?:usage )?limit|throttl|\b429\b/
+// Captured verbatim from opencode's embedded overload classifier, recovered from its binary on
+// 2026-09-20: "the service is at capacity", "Overloaded", "temporarily unavailable", "503
+// Service Unavailable", "server is busy, try again", "Internal Server Error", and "upstream
+// connect error". These describe an API that is reachable but refusing — the one failure worth
+// retrying before giving up on an agent, unlike a rate limit (checked first: a message that is
+// both rate-limited and mentions 503 is a rate limit, since that window is hours, not seconds).
+const UPSTREAM =
+  /service is at capacity|overloaded?|temporarily unavailable|\b503\b|server is busy|internal server error|upstream connect error/
+
+export function classifyError(message: string): 'auth' | 'rate' | 'upstream' | 'crash' | 'unknown' {
+  const m = message.toLowerCase()
+  if (AUTH.test(m)) return 'auth'
+  if (RATE.test(m)) return 'rate'
+  if (UPSTREAM.test(m)) return 'upstream'
+  return 'unknown'
+}

package/src/args.ts

@@ -0,0 +1,42 @@
+export interface Args {
+  _: string[]
+  flags: Record<string, string | boolean>
+}
+
+// Flags that are switches, so `konvoy rm --yes <slug>` keeps its slug. Their consumers are the
+// `=== true` checks in cli.ts; a value flag (--session, --port) is anything not listed here.
+const SWITCHES = new Set(['all', 'yes', 'global', 'chart', 'help'])
+
+export function parseArgs(argv: string[]): Args {
+  const positional: string[] = []
+  const flags: Record<string, string | boolean> = {}
+  let flagsEnded = false
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]!
+    if (flagsEnded || !token.startsWith('-') || token === '-') {
+      positional.push(token)
+      continue
+    }
+    // the POSIX convention, and the only way to send a message that starts with a dash
+    if (token === '--') {
+      flagsEnded = true
+      continue
+    }
+    const name = token.replace(/^--?/, '')
+    if (name.includes('=')) {
+      const [key, ...rest] = name.split('=')
+      flags[key!] = rest.join('=')
+      continue
+    }
+    const next = argv[i + 1]
+    if (!SWITCHES.has(name) && next !== undefined && !next.startsWith('-')) {
+      flags[name] = next
+      i++
+    } else {
+      flags[name] = true
+    }
+  }
+
+  return { _: positional, flags }
+}

package/src/chart.ts

@@ -0,0 +1,91 @@
+const BLOCKS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'] as const
+const DENSITY = ['·', '▫', '▪', '▩', '█'] as const
+const DAY_LABELS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as const
+
+export function sparkline(values: number[], max?: number): string {
+  if (values.length === 0) return ''
+  // an explicit max lets several series share one scale (see agentSparklines); omitted, a
+  // series scales to its own peak, as a lone sparkline always has
+  const m = max ?? Math.max(...values)
+  // counts have a fixed baseline of zero, not the series' own minimum — a flat run of busy
+  // days must render full, not empty. Guard only the case where there's no signal at all.
+  if (m <= 0) return BLOCKS[0]!.repeat(values.length)
+  // a nonzero count is never the zero glyph: below m/14 Math.round lands on 0, and a quiet day
+  // must still read as a day with turns
+  return values
+    .map((v) => (v <= 0 ? BLOCKS[0]! : BLOCKS[Math.min(BLOCKS.length - 1, Math.max(1, Math.round((v / m) * (BLOCKS.length - 1))))]!))
+    .join('')
+}
+
+export function shareBars(rows: { label: string; value: number }[], width = 18): string {
+  const total = rows.reduce((sum, r) => sum + r.value, 0)
+  const labelWidth = Math.max(...rows.map((r) => r.label.length), 1)
+  return (
+    rows
+      .map((r) => {
+        const share = total > 0 ? r.value / total : 0
+        const filled = Math.round(share * width)
+        const bar = '█'.repeat(filled) + '░'.repeat(width - filled)
+        return `${r.label.padEnd(labelWidth)}  ${bar}  ${Math.round(share * 100)}%`
+      })
+      .join('\n') + '\n'
+  )
+}
+
+// a lone agent's sparkline can't reveal whether it's the busy one or the quiet one — every
+// agent must be drawn against the same peak, and every row must span the same dense day
+// range (gaps filled with zero) so the columns line up between agents
+export function agentSparklines(rows: { agent: string; day: string; count: number }[]): { agent: string; line: string }[] {
+  if (rows.length === 0) return []
+  const days = [...new Set(rows.map((r) => r.day))].sort()
+  const start = days[0]!
+  const end = days[days.length - 1]!
+
+  const denseDays: string[] = []
+  for (
+    const cursor = new Date(`${start}T00:00:00Z`);
+    cursor <= new Date(`${end}T00:00:00Z`);
+    cursor.setUTCDate(cursor.getUTCDate() + 1)
+  ) {
+    denseDays.push(cursor.toISOString().slice(0, 10))
+  }
+
+  const byAgent = new Map<string, Map<string, number>>()
+  for (const r of rows) {
+    if (!byAgent.has(r.agent)) byAgent.set(r.agent, new Map())
+    byAgent.get(r.agent)!.set(r.day, r.count)
+  }
+
+  const series = [...byAgent.entries()].map(([agent, dayCounts]) => ({
+    agent,
+    values: denseDays.map((d) => dayCounts.get(d) ?? 0),
+  }))
+
+  const sharedMax = Math.max(...series.flatMap((s) => s.values), 0)
+  return series.map(({ agent, values }) => ({ agent, line: sparkline(values, sharedMax) }))
+}
+
+export function heatmap(days: { day: string; count: number }[]): string {
+  if (days.length === 0) return ''
+  const max = Math.max(...days.map((d) => d.count), 1)
+  const byDay = new Map(days.map((d) => [d.day, d.count]))
+
+  const first = new Date(`${days[0]!.day}T00:00:00Z`)
+  const last = new Date(`${days[days.length - 1]!.day}T00:00:00Z`)
+  const start = new Date(first)
+  start.setUTCDate(start.getUTCDate() - start.getUTCDay())
+
+  const rows: string[] = []
+  for (let weekday = 0; weekday < 7; weekday++) {
+    let line = `${DAY_LABELS[weekday]} `
+    for (const cursor = new Date(start); cursor <= last; cursor.setUTCDate(cursor.getUTCDate() + 7)) {
+      const cell = new Date(cursor)
+      cell.setUTCDate(cell.getUTCDate() + weekday)
+      const key = cell.toISOString().slice(0, 10)
+      const count = byDay.get(key) ?? 0
+      line += count === 0 ? DENSITY[0] : DENSITY[Math.min(DENSITY.length - 1, Math.ceil((count / max) * (DENSITY.length - 1)))]
+    }
+    rows.push(line)
+  }
+  return rows.join('\n')
+}

package/src/cli.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env bun
+import type { Database } from 'bun:sqlite'
+import { parseArgs, type Args } from './args'
+import { loadConfig, resolveAgent } from './config/load'
+import { getSessionBySlug } from './store/queries'
+import { agentIds } from './config/schema'
+import type { Config } from './config/schema'
+import { openDb } from './store/db'
+import { dbPath } from './paths'
+import { cmdNew } from './commands/new'
+import { cmdSend } from './commands/send'
+import { cmdLs } from './commands/ls'
+import { cmdRoster } from './commands/roster'
+import { cmdStatus } from './commands/status'
+import { cmdAttach } from './commands/attach'
+import { cmdDoctor } from './commands/doctor'
+import { cmdUpdate } from './commands/update'
+import { cmdConfig } from './commands/config'
+import { cmdResume } from './commands/resume'
+import { cmdRm } from './commands/rm'
+import { cmdUsage } from './commands/usage'
+import { cmdDashboard } from './commands/dashboard'
+import { formatCommandList, resolveCommandName, type CommandName } from './commands/table'
+import type { AgentId } from './types'
+import pkg from '../package.json'
+
+const VERSION = pkg.version
+
+export const USAGE = `konvoy ${VERSION}
+
+${formatCommandList()}
+
+agents: ${agentIds.join(', ')}
+flags:  --session <slug>
+`
+
+interface CommandContext {
+  db: Database
+  cfg: Config
+  cwd: string
+  args: Args
+  slug: string | undefined
+}
+
+type Handler = (ctx: CommandContext, rest: string[]) => number | Promise<number>
+
+// Every key of CommandName must be handled here — TypeScript's excess/missing property
+// checks on an object literal assigned to Record<CommandName, Handler> make an
+// undocumented-yet-dispatched or dispatched-yet-undocumented command a compile error.
+const handlers: Record<CommandName, Handler> = {
+  new: (ctx, rest) => cmdNew(ctx.db, ctx.cfg, ctx.cwd, rest.join(' ')),
+  send: (ctx, rest) => {
+    const [agent, ...prompt] = rest
+    if (!agent || prompt.length === 0) {
+      console.error('usage: konvoy send <agent> "<message>"')
+      console.error('a message beginning with a dash goes after --, as in: konvoy send codex -- "-1 first"')
+      return 2
+    }
+    return cmdSend(ctx.db, ctx.cfg, ctx.cwd, agent, prompt.join(' '), ctx.slug)
+  },
+  ls: (ctx) => cmdLs(ctx.db),
+  roster: (ctx) => cmdRoster(ctx.db, ctx.cfg, ctx.cwd, ctx.slug),
+  status: (ctx) => cmdStatus(ctx.db, ctx.cfg, ctx.cwd, ctx.slug),
+  attach: (ctx, rest) => {
+    const [agent] = rest
+    if (!agent) {
+      console.error('usage: konvoy attach <agent> [--id <session-id>]')
+      return 2
+    }
+    const settings = resolveAgent(ctx.cfg, agent as AgentId)
+    const id = typeof ctx.args.flags.id === 'string' ? ctx.args.flags.id : undefined
+    return cmdAttach(ctx.db, ctx.cwd, agent, { slug: ctx.slug, bin: settings.bin, id, effort: settings.effort, permission: settings.permission })
+  },
+  doctor: (ctx) => cmdDoctor(ctx.cfg),
+  update: (ctx) => cmdUpdate(ctx.cfg, { all: ctx.args.flags.all === true }),
+  resume: (ctx, rest) => cmdResume(ctx.db, ctx.cfg, ctx.cwd, rest[0] ?? ctx.slug),
+  config: (ctx, rest) => {
+    const [action, key, value] = rest
+    return cmdConfig(ctx.cfg, ctx.cwd, action ?? 'get', key, value, { global: ctx.args.flags.global === true })
+  },
+  rm: (ctx, rest) => {
+    const [target] = rest
+    if (!target) {
+      console.error('usage: konvoy rm <session> --yes')
+      return 2
+    }
+    return cmdRm(ctx.db, ctx.cwd, target, { yes: ctx.args.flags.yes === true })
+  },
+  usage: (ctx) =>
+    cmdUsage(ctx.db, ctx.cfg, ctx.cwd, {
+      all: ctx.args.flags.all === true,
+      slug: ctx.slug,
+      chart: ctx.args.flags.chart === true,
+    }),
+  version: (ctx) => {
+    console.log(`konvoy ${VERSION}`)
+    return cmdStatus(ctx.db, ctx.cfg, ctx.cwd, ctx.slug, { roster: false })
+  },
+  dashboard: ({ db, cfg, cwd, args, slug }) =>
+    cmdDashboard(db, cfg, cwd, {
+      port: typeof args.flags.port === 'string' ? Number(args.flags.port) : undefined,
+      slug,
+    }),
+}
+
+export async function main(argv: string[]): Promise<number> {
+  const args = parseArgs(argv)
+  const [command, ...rest] = args._
+  const cwd = process.cwd()
+  const slug = typeof args.flags.session === 'string' ? args.flags.session : undefined
+
+  if (!command || command === 'help' || args.flags.help) {
+    console.log(USAGE)
+    // asking for help is not a usage error; running konvoy with nothing is
+    return command || args.flags.help ? 0 : 1
+  }
+
+  try {
+    return await dispatch(command, rest, cwd, slug, args)
+  } catch (error) {
+    if (Bun.env.KONVOY_DEBUG === '1') throw error
+    console.error(`konvoy: ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+}
+
+async function dispatch(command: string, rest: string[], cwd: string, slug: string | undefined, args: Args): Promise<number> {
+  const db = openDb(dbPath())
+  // a session named from another directory carries its own project config, not the shell's:
+  // model, effort, roles and the failover chain follow the repository the turn runs in
+  const projectCwd = (slug ? getSessionBySlug(db, slug)?.cwd : undefined) ?? cwd
+  const cfg = await loadConfig({ cwd: projectCwd })
+
+  const name = resolveCommandName(command)
+  if (!name) {
+    console.error(`unknown command "${command}"`)
+    console.log(USAGE)
+    return 2
+  }
+
+  return handlers[name]({ db, cfg, cwd, args, slug }, rest)
+}
+
+if (import.meta.main) {
+  process.exitCode = await main(Bun.argv.slice(2))
+}

package/src/commands/attach.ts

@@ -0,0 +1,85 @@
+import type { Database } from 'bun:sqlite'
+import type { AgentId, Effort, Permission, Session, SpawnPlan } from '../types'
+import { agentIds, getAdapter } from '../adapters'
+import { currentSession, getBinding, getSessionBySlug, upsertBinding } from '../store/queries'
+import { oneLine } from '../adapters/types'
+import { detect } from '../core/detect'
+
+export function attachPlan(db: Database, session: Session, agent: AgentId, bin?: string): SpawnPlan {
+  const binding = getBinding(db, session.id, agent)
+  const plan = getAdapter(agent).attach(
+    binding ?? {
+      sessionId: session.id,
+      agent,
+      foreignId: null,
+      model: null,
+      effort: 'high',
+      permission: 'edit',
+      status: 'unbound',
+      turns: 0,
+      costUsd: 0,
+      credits: 0,
+      lastSeen: null,
+    },
+  )
+  const cmd = bin ? [bin, ...plan.cmd.slice(1)] : plan.cmd
+  return { ...plan, cmd, cwd: session.cwd }
+}
+
+// Bind a session the user started outside konvoy — the id a CLI prints for its own resume
+// command. The same shape check as every stream-captured id applies at the write path; the
+// binding is only reported as adopted if it actually holds the id.
+export function adoptForeignSession(
+  db: Database,
+  session: Session,
+  agent: AgentId,
+  foreignId: string,
+  settings: { effort: Effort; permission: Permission },
+): boolean {
+  upsertBinding(db, { sessionId: session.id, agent, foreignId, effort: settings.effort, permission: settings.permission })
+  return getBinding(db, session.id, agent)?.foreignId === foreignId
+}
+
+export interface AttachOptions {
+  slug?: string
+  bin?: string
+  /** a session id from the CLI itself, adopted into this konvoy session before opening */
+  id?: string
+  effort?: Effort
+  permission?: Permission
+}
+
+export async function cmdAttach(db: Database, cwd: string, agent: string, opts: AttachOptions = {}): Promise<number> {
+  const { slug, bin } = opts
+  if (!agentIds.includes(agent as AgentId)) {
+    console.error(`unknown agent "${agent}" — expected one of ${agentIds.join(', ')}`)
+    return 2
+  }
+  const session = slug ? getSessionBySlug(db, slug) : currentSession(db, cwd)
+  if (!session) {
+    console.error('no konvoy session here — run `konvoy new "<goal>"` first')
+    return 2
+  }
+
+  const detection = await detect(agent as AgentId, { bin })
+  if (!detection.installed) {
+    console.error(`${agent}: not installed`)
+    return 2
+  }
+
+  if (opts.id) {
+    const adopted = adoptForeignSession(db, session, agent as AgentId, opts.id, {
+      effort: opts.effort ?? 'high',
+      permission: opts.permission ?? 'edit',
+    })
+    if (!adopted) {
+      console.error(`konvoy: ${agent} not bound — the id was refused; nothing opened`)
+      return 2
+    }
+    console.error(`konvoy: ${agent} bound to session ${oneLine(opts.id, 60)} — the next turn resumes it; opening it now`)
+  }
+
+  const plan = attachPlan(db, session, agent as AgentId, bin)
+  const proc = Bun.spawn(plan.cmd, { cwd: plan.cwd, stdio: ['inherit', 'inherit', 'inherit'] })
+  return await proc.exited
+}

package/src/commands/config.ts

@@ -0,0 +1,113 @@
+import type { Config } from '../config/schema'
+import { configSchema } from '../config/schema'
+import { explain, globalConfigPath, projectConfigPath, readLayer, resolveAgent } from '../config/load'
+import { agentIds } from '../adapters'
+
+export function coerce(raw: string): string | number | boolean {
+  if (raw === 'true') return true
+  if (raw === 'false') return false
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw)
+  return raw
+}
+
+// `__proto__` resolves to Object.prototype through an ordinary property read, so a dotted path
+// containing it writes onto the shared prototype — poisoning every object in the process while
+// the config itself stays empty. `constructor` and `prototype` are blocked for the same reason.
+const RESERVED = new Set(['__proto__', 'constructor', 'prototype'])
+
+function assertSafe(dotted: string): void {
+  for (const key of dotted.split('.')) {
+    if (RESERVED.has(key)) throw new Error(`"${key}" is not a valid config key`)
+  }
+}
+
+export function getPath(obj: unknown, dotted: string): unknown {
+  assertSafe(dotted)
+  let node: unknown = obj
+  for (const key of dotted.split('.')) {
+    if (typeof node !== 'object' || node === null) return undefined
+    node = (node as Record<string, unknown>)[key]
+  }
+  return node
+}
+
+export function setPath(
+  obj: Record<string, unknown>,
+  dotted: string,
+  raw: string,
+): Record<string, unknown> {
+  assertSafe(dotted)
+  const keys = dotted.split('.')
+  const out = structuredClone(obj)
+  let node: Record<string, unknown> = out
+  for (const key of keys.slice(0, -1)) {
+    const child = node[key]
+    if (typeof child !== 'object' || child === null) node[key] = {}
+    node = node[key] as Record<string, unknown>
+  }
+  node[keys.at(-1)!] = coerce(raw)
+  return out
+}
+
+export async function cmdConfig(
+  cfg: Config,
+  cwd: string,
+  action: string,
+  key?: string,
+  value?: string,
+  opts: { global?: boolean } = {},
+): Promise<number> {
+  if (action === 'get') {
+    if (key) {
+      let found: unknown
+      try {
+        found = getPath(cfg, key)
+      } catch (e) {
+        console.error((e as Error).message)
+        return 2
+      }
+      if (found === undefined) {
+        console.error(`no such config key: ${key}`)
+        return 2
+      }
+      console.log(typeof found === 'string' ? found : JSON.stringify(found, null, 2))
+      return 0
+    }
+    for (const agent of agentIds) {
+      const s = resolveAgent(cfg, agent)
+      const effort = explain(cfg, agent, 'effort')
+      console.log(
+        `${agent}: model=${s.model ?? '-'} effort=${s.effort} (${effort.source}) permission=${s.permission} enabled=${s.enabled}`,
+      )
+    }
+    return 0
+  }
+
+  if (action === 'set') {
+    if (!key || value === undefined) {
+      console.error('usage: konvoy config set <key> <value> [--global]')
+      return 2
+    }
+    const path = opts.global ? globalConfigPath() : projectConfigPath(cwd)
+    const raw = ((await readLayer(path)) ?? {}) as Record<string, unknown>
+    let next: Record<string, unknown>
+    try {
+      next = setPath(raw, key, value)
+    } catch (e) {
+      console.error((e as Error).message)
+      return 2
+    }
+    const parsed = configSchema.safeParse(next)
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0]
+      console.error(`refusing to write: ${issue?.path.join('.')} — ${issue?.message}`)
+      return 2
+    }
+    await Bun.write(path, JSON.stringify(next, null, 2) + '\n')
+    console.log(`${key} = ${value}  (${path})`)
+    return 0
+  }
+
+  console.error('usage: konvoy config get|set')
+  return 2
+}

package/src/commands/dashboard.ts

@@ -0,0 +1,26 @@
+import type { Database } from 'bun:sqlite'
+import { currentSession, getSessionBySlug } from '../store/queries'
+import type { Config } from '../config/schema'
+import { collect, renderPage } from '../dashboard/page'
+
+export async function cmdDashboard(
+  db: Database,
+  cfg: Config,
+  cwd: string,
+  opts: { port?: number; slug?: string },
+): Promise<number> {
+  const session = opts.slug ? getSessionBySlug(db, opts.slug) : currentSession(db, cwd)
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: opts.port ?? 0,
+    fetch: () => {
+      const data = collect(db, cfg, session?.id)
+      return new Response(renderPage({ ...data, title: session?.slug ?? 'all sessions' }), {
+        headers: { 'content-type': 'text/html; charset=utf-8' },
+      })
+    },
+  })
+  console.log(`konvoy dashboard on http://127.0.0.1:${server.port} — ctrl-c to stop`)
+  await new Promise(() => {})
+  return 0
+}