kimaki 0.30.1 → 1.0.0

package/src/migrations.ts

@@ -0,0 +1,198 @@
+// Every SQLite migration of kimaki, in one place. Only the bot start runs it
+// (openDb({ migrate: true })); subcommands never migrate.
+//
+//   <dataDir>/kimaki.db present without the DB_VERSION marker, next to a V1 file?
+//     └─ not made by kimaki: rename it to kimaki.db.unknown-<time> (never deleted)
+//   <dataDir>/kimaki.db missing?
+//     └─ <dataDir>/discord-sessions.db (V1) present?
+//          yes ─▶ build kimaki.db.import from schema.sql + the V1 rows of the
+//                 tables kimaki uses, then rename it to kimaki.db (atomic: a
+//                 crash leaves no half-imported kimaki.db, the next start retries)
+//          no  ─▶ empty kimaki.db
+//   then: schema.sql (CREATE ... IF NOT EXISTS) + the marker on kimaki.db
+//
+// The V1 file is opened read-only and never changed or deleted, so V1 keeps
+// working on its own data. There is no downgrade: changes made by kimaki stay in
+// kimaki.db. Future schema changes (ALTER TABLE ... ADD COLUMN) go in
+// migrateSchema() below.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { createClient, type Client } from '@libsql/client'
+import * as errore from 'errore'
+
+import { DbError } from './errors.ts'
+import { createLogger } from './logger.ts'
+import { SCHEMA_SQL } from './schema-sql.ts'
+
+const logger = createLogger('DB')
+
+export const DB_FILE = 'kimaki.db'
+export const LEGACY_DB_FILE = 'discord-sessions.db'
+
+// PRAGMA user_version of every kimaki.db written by migrateSchema(). A stray
+// kimaki.db without it (an empty file from another tool, a pre-marker dev
+// build) must not block the V1 import: then the user gets onboarding again.
+export const DB_VERSION = 1
+
+// Parents first, so imported rows satisfy the foreign keys.
+const IMPORTED_TABLES = [
+  'bot_tokens',
+  'bot_api_keys',
+  'guild_categories',
+  'channel_directories',
+  'channel_models',
+  'global_models',
+  'channel_agents',
+  'channel_worktrees',
+  'channel_verbosity',
+  'channel_mention_mode',
+  'thread_sessions',
+  'scheduled_tasks',
+  'session_sleeps',
+] as const
+
+// V1 values kimaki reads differently. Old V1 rows can carry the DDL default
+// 'self-hosted' (hyphen) or NULL; kimaki only knows 'self_hosted' | 'gateway'.
+const IMPORT_EXPRESSIONS: Partial<Record<(typeof IMPORTED_TABLES)[number], Record<string, string>>> = {
+  bot_tokens: { bot_mode: `CASE WHEN bot_mode = 'gateway' THEN 'gateway' ELSE 'self_hosted' END` },
+}
+
+export function schemaStatements(): string[] {
+  return SCHEMA_SQL.split(';')
+    .map((statement) => {
+      return statement
+        .split('\n')
+        .filter((line) => !line.trimStart().startsWith('--'))
+        .join('\n')
+        .trim()
+    })
+    .filter((statement) => statement.length > 0)
+}
+
+async function columnsOf({ client, schema, table }: { client: Client; schema: 'main' | 'legacy'; table: string }) {
+  const rows = await client.execute(`PRAGMA ${schema}.table_info("${table}")`)
+  return rows.rows.map((row) => ({ name: String(row.name), notNull: Number(row.notnull) === 1 || Number(row.pk) > 0 }))
+}
+
+// One entry per FK column: the schema has only single-column foreign keys
+// with an explicit parent column. A composite FK would need grouping by `id`.
+async function foreignKeysOf({ client, table }: { client: Client; table: string }) {
+  const rows = await client.execute(`PRAGMA main.foreign_key_list("${table}")`)
+  return rows.rows.map((row) => ({ column: String(row.from), parent: String(row.table), parentColumn: String(row.to) }))
+}
+
+// Copies the V1 rows into `client` (an empty file with schema.sql applied).
+// Most V1 tables have no foreign keys, so real installs hold rows that point
+// at deleted channels or threads: a required reference skips the row, an
+// optional one becomes NULL (like ON DELETE SET NULL).
+async function copyLegacyRows({ client, legacyFile }: { client: Client; legacyFile: string }): Promise<void> {
+  await client.execute({ sql: 'ATTACH DATABASE ? AS legacy', args: [`file:${legacyFile}?mode=ro`] })
+  for (const table of IMPORTED_TABLES) {
+    const legacyColumns = (await columnsOf({ client, schema: 'legacy', table })).map((column) => column.name)
+    if (legacyColumns.length === 0) {
+      logger.log(`import ${table}: not in ${LEGACY_DB_FILE}, skipped`)
+      continue
+    }
+    // Columns an older V1 file lacks get the kimaki default.
+    const columns = (await columnsOf({ client, schema: 'main', table })).filter((column) => legacyColumns.includes(column.name))
+    const foreignKeys = (await foreignKeysOf({ client, table })).filter((key) => legacyColumns.includes(key.column))
+    const existsIn = (key: (typeof foreignKeys)[number]) => `"${key.column}" IN (SELECT "${key.parentColumn}" FROM main."${key.parent}")`
+    const expressions = columns.map((column) => {
+      const custom = IMPORT_EXPRESSIONS[table]?.[column.name]
+      if (custom) return custom
+      const key = foreignKeys.find((candidate) => candidate.column === column.name)
+      if (key && !column.notNull) return `CASE WHEN ${existsIn(key)} THEN "${column.name}" END`
+      return `"${column.name}"`
+    })
+    const required = foreignKeys.filter((key) => columns.some((column) => column.name === key.column && column.notNull))
+    const where = required.length > 0 ? ` WHERE ${required.map(existsIn).join(' AND ')}` : ''
+    const inserted = await client.execute(
+      `INSERT INTO main."${table}" (${columns.map((column) => `"${column.name}"`).join(', ')}) SELECT ${expressions.join(', ')} FROM legacy."${table}"${where}`,
+    )
+    const total = await client.execute(`SELECT count(*) FROM legacy."${table}"`)
+    const skipped = Number(total.rows[0]?.[0] ?? 0) - inserted.rowsAffected
+    logger.log(`import ${table}: ${inserted.rowsAffected} rows${skipped > 0 ? `, ${skipped} skipped (missing parent row)` : ''}`)
+  }
+  await client.execute('DETACH DATABASE legacy')
+}
+
+async function readDbVersion({ file }: { file: string }): Promise<DbError | number> {
+  const client = createClient({ url: `file:${file}` })
+  const version = await client
+    .execute('PRAGMA user_version')
+    .then((result) => Number(result.rows[0]?.[0] ?? 0))
+    // Not an SQLite file at all: unmarked too, so it is set aside like any stray file.
+    .catch((e) => (Reflect.get(e, 'code') === 'SQLITE_NOTADB' ? 0 : new DbError({ operation: `read version of ${file}`, cause: e })))
+  client.close()
+  return version
+}
+
+// Renames file and its WAL files. The WAL files go first and keep their
+// suffix, so a crash never leaves a foreign -wal next to a new kimaki.db.
+function setAside({ file }: { file: string }): DbError | string {
+  const target = `${file}.unknown-${new Date().toISOString().replace(/[:.]/g, '-')}`
+  return errore.try(
+    () => {
+      for (const suffix of ['-wal', '-shm', '']) {
+        if (fs.existsSync(`${file}${suffix}`)) fs.renameSync(`${file}${suffix}`, `${target}${suffix}`)
+      }
+      return target
+    },
+    (e) => new DbError({ operation: `rename ${file}`, cause: e }),
+  )
+}
+
+// Picks or creates the database file. Returns its path.
+async function prepareDbFile({ dataDir }: { dataDir: string }): Promise<DbError | string> {
+  const file = path.join(dataDir, DB_FILE)
+  const legacyFile = path.join(dataDir, LEGACY_DB_FILE)
+  const hasLegacy = fs.existsSync(legacyFile)
+  if (fs.existsSync(file)) {
+    // Without a V1 file there is nothing to import: keep it, migrateSchema() marks it.
+    if (!hasLegacy) return file
+    const version = await readDbVersion({ file })
+    if (version instanceof Error) return version
+    if (version >= DB_VERSION) return file
+    const moved = setAside({ file })
+    if (moved instanceof Error) return moved
+    logger.warn(`${file} was not made by kimaki (no version marker), moved it to ${moved}`)
+  }
+  if (!hasLegacy) return file
+  logger.log(`first start of this version: importing ${legacyFile} into ${file}`)
+  const target = `${file}.import`
+  fs.rmSync(target, { force: true })
+  const client = createClient({ url: `file:${target}` })
+  const imported = await migrateSchema({ client })
+    .then(() => copyLegacyRows({ client, legacyFile }))
+    .catch((e) => new DbError({ operation: `import ${legacyFile}`, cause: e }))
+  client.close()
+  if (imported instanceof Error) {
+    fs.rmSync(target, { force: true })
+    return imported
+  }
+  const renamed = errore.try(
+    () => fs.renameSync(target, file),
+    (e) => new DbError({ operation: `rename ${target}`, cause: e }),
+  )
+  if (renamed instanceof Error) return renamed
+  logger.log(`import done, ${legacyFile} is kept unchanged`)
+  return file
+}
+
+// Schema of an open kimaki.db: schema.sql is idempotent. Add future
+// ALTER TABLE migrations here, before schema.sql when a new index needs them.
+async function migrateSchema({ client }: { client: Client }): Promise<void> {
+  for (const statement of schemaStatements()) await client.execute(statement)
+  await client.execute(`PRAGMA user_version = ${DB_VERSION}`)
+}
+
+export async function migrateDb({ dataDir }: { dataDir: string }): Promise<DbError | string> {
+  const file = await prepareDbFile({ dataDir })
+  if (file instanceof Error) return file
+  const client = createClient({ url: `file:${file}` })
+  const migrated = await migrateSchema({ client }).catch((e) => new DbError({ operation: 'migrate schema', cause: e }))
+  client.close()
+  if (migrated instanceof Error) return migrated
+  return file
+}

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

@@ -0,0 +1,215 @@
+// Non-interactive gateway onboarding through the real CLI process, like a
+// cloud sandbox: stdout carries SSE events (install_url, authorized, ready).
+// A local fake kimaki.dev answers /api/onboarding/status and, like the real
+// OAuth callback, authorizes the new client in the twin, which plays
+// gateway-proxy (REST scope rules enforced).
+
+import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import fs from 'node:fs'
+import http from 'node:http'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import { afterAll, beforeAll, expect, test } from 'vitest'
+
+import { createApi } from './project.ts'
+import {
+  freePort,
+  startOpencodeTestServer,
+  startTwin,
+  tempDataDir,
+  TEST_USER_ID,
+  textParts,
+  waitFor,
+  waitForFooter,
+  warmUp,
+  type OpencodeTestServer,
+  type TestTwin,
+} from './test/harness.ts'
+
+const execFileAsync = promisify(execFile)
+let server: OpencodeTestServer
+let twin: TestTwin
+let website: http.Server
+let websiteUrl: string
+let dataDir: string
+let child: ChildProcessWithoutNullStreams | null = null
+
+beforeAll(async () => {
+  dataDir = tempDataDir()
+  ;[server, twin] = await Promise.all([
+    startOpencodeTestServer({
+      matchers: [
+        {
+          id: 'onboarding-greeting',
+          priority: 50,
+          when: { latestUserTextIncludes: 'This is the Kimaki onboarding thread' },
+          then: { parts: textParts('Want channels for your projects?') },
+        },
+      ],
+    }),
+    startTwin({ gateway: true }),
+  ])
+  await warmUp({ server })
+  // Fake kimaki.dev: the user "installs" the bot as soon as the CLI polls.
+  website = http.createServer((request, response) => {
+    const url = new URL(request.url ?? '/', 'http://localhost')
+    if (url.pathname !== '/api/onboarding/status') {
+      response.writeHead(404).end()
+      return
+    }
+    twin.discord.authorizeGatewayClient({
+      token: `${url.searchParams.get('client_id')}:${url.searchParams.get('secret')}`,
+      guildIds: [twin.discord.guildId],
+    })
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({ guild_id: twin.discord.guildId, discord_user_id: TEST_USER_ID }))
+  })
+  const port = await freePort()
+  await new Promise<void>((resolve) => website.listen(port, '127.0.0.1', resolve))
+  websiteUrl = `http://127.0.0.1:${port}`
+}, 60_000)
+
+afterAll(async () => {
+  if (child && child.exitCode === null) {
+    const exited = new Promise((resolve) => child?.once('exit', resolve))
+    child.kill('SIGTERM')
+    await exited
+  }
+  await new Promise<void>((resolve) => website?.close(() => resolve()))
+  await twin?.stop()
+  await server?.stop()
+  fs.rmSync(dataDir, { recursive: true, force: true })
+})
+
+function sseEvents(stdout: string): Array<Record<string, unknown>> {
+  return stdout
+    .split('\n\n')
+    .filter((chunk) => chunk.startsWith('data: '))
+    .map((chunk) => JSON.parse(chunk.slice('data: '.length)) as Record<string, unknown>)
+}
+
+test('kimaki --gateway without a TTY installs, onboards and reports ready on stdout', async () => {
+  const require = createRequire(import.meta.url)
+  const proxy = new URL('/', twin.discord.restUrl).toString()
+  const lockPort = await freePort()
+  child = spawn(
+    process.execPath,
+    ['--import', require.resolve('tsx'), path.resolve('src/cli.ts'), '--data-dir', dataDir, '--gateway', '--machine-name', 'test-machine'],
+    {
+      env: {
+        ...process.env,
+        KIMAKI_WEBSITE_URL: websiteUrl,
+        KIMAKI_GATEWAY_PROXY_URL: proxy,
+        KIMAKI_LOCK_PORT: String(lockPort),
+        KIMAKI_OPENCODE_SERVICE_FILE: server.serviceFile,
+        OPENCODE_CONFIG_DIR: server.configDir,
+      },
+    },
+  )
+  const output = { stdout: '', stderr: '' }
+  child.stdout.on('data', (chunk: Buffer) => (output.stdout += chunk.toString()))
+  child.stderr.on('data', (chunk: Buffer) => (output.stderr += chunk.toString()))
+  await waitFor({
+    label: `ready event (stderr: ${output.stderr.slice(-500)})`,
+    timeout: 10_000,
+    check: async () => sseEvents(output.stdout).some((event) => event['type'] === 'ready'),
+  })
+
+  const token = (sseEvents(output.stdout)[0]?.['url'] as string).match(/clientId=([^&]+)&clientSecret=([^&]+)/)
+  expect(
+    sseEvents(output.stdout).map((event) =>
+      JSON.parse(
+        JSON.stringify(event)
+          .replaceAll(websiteUrl, '<website>')
+          .replaceAll(token?.[1] ?? '-', '<clientId>')
+          .replaceAll(token?.[2] ?? '-', '<secret>')
+          .replaceAll(twin.discord.guildId, '<guild>'),
+      ),
+    ),
+  ).toMatchInlineSnapshot(`
+    [
+      {
+        "type": "install_url",
+        "url": "<website>/discord-install?clientId=<clientId>&clientSecret=<secret>",
+      },
+      {
+        "guild_id": "<guild>",
+        "type": "authorized",
+      },
+      {
+        "app_id": "1477605701202481173",
+        "guild_ids": [
+          "<guild>",
+        ],
+        "type": "ready",
+      },
+    ]
+  `)
+
+  const channels = await createApi({ token: twin.discord.botToken, restUrl: twin.discord.restUrl }).guilds.getChannels(twin.discord.guildId)
+  const names = new Map(channels.map((channel) => [channel.id, channel.name]))
+  expect(channels.map((channel) => `${channel.name}${channel.parent_id ? ` (in ${names.get(channel.parent_id)})` : ''}`)).toMatchInlineSnapshot(`
+    [
+      "project",
+      "random",
+      "quiet",
+      "Kimaki test-machine",
+      "kimaki (in Kimaki test-machine)",
+      "Kimaki voice test-machine",
+    ]
+  `)
+
+  const kimakiChannel = channels.find((channel) => channel.name === 'kimaki')!
+  const thread = await twin.discord.channel(kimakiChannel.id).waitForThread({ timeout: 8_000 })
+  await waitForFooter({ discord: twin.discord, threadId: thread.id })
+  expect(await twin.discord.thread(thread.id).text()).toMatchInlineSnapshot(`
+    "--- from: assistant (TestBot)
+    **Kimaki** lets you code from Discord. Each project channel is linked to a folder on your computer. A message there starts an AI coding session in that folder.
+    Reply in the thread below to add channels for your projects. <@200000000000000001>
+    -# *using deterministic-provider/deterministic-v2 ⋅ build*
+    Want channels for your projects?
+    -# *kimaki ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+  `)
+
+  // `kimaki restart`: the supervisor starts a new bot process, which reports ready again.
+  const cli = (args: string[]) => execFileAsync(process.execPath, ['--import', require.resolve('tsx'), path.resolve('src/cli.ts'), ...args, '--data-dir', dataDir], {
+    env: { ...process.env, KIMAKI_LOCK_PORT: String(lockPort) },
+  })
+  const before = JSON.parse((await cli(['status', '--json'])).stdout) as { pid: number }
+  await cli(['restart'])
+  await waitFor({
+    label: `second ready event (stderr: ${output.stderr.slice(-500)})`,
+    check: async () => sseEvents(output.stdout).filter((event) => event['type'] === 'ready').length === 2,
+  })
+  const after = JSON.parse((await cli(['status', '--json'])).stdout) as { pid: number }
+  expect({ newPid: after.pid !== before.pid, supervisorAlive: child.exitCode === null }).toEqual({ newPid: true, supervisorAlive: true })
+}, 40_000)
+
+test('--install-url --gateway prints the install URL with the callback and exits', async () => {
+  const otherDataDir = tempDataDir()
+  const require = createRequire(import.meta.url)
+  const result = await new Promise<{ code: number | null; stdout: string }>((resolve) => {
+    const process_ = spawn(
+      process.execPath,
+      [
+        '--import', require.resolve('tsx'), path.resolve('src/cli.ts'),
+        '--data-dir', otherDataDir, '--install-url', '--gateway', '--gateway-callback-url', 'https://example.com/done',
+      ],
+      { env: { ...process.env, KIMAKI_WEBSITE_URL: 'https://kimaki.test' } },
+    )
+    const output = { stdout: '' }
+    process_.stdout.on('data', (chunk: Buffer) => (output.stdout += chunk.toString()))
+    process_.once('exit', (code) => resolve({ code, stdout: output.stdout }))
+  })
+  fs.rmSync(otherDataDir, { recursive: true, force: true })
+  expect({
+    code: result.code,
+    url: result.stdout.trim().replace(/clientId=[^&]+&clientSecret=[^&]+/, 'clientId=<clientId>&clientSecret=<secret>'),
+  }).toMatchInlineSnapshot(`
+    {
+      "code": 0,
+      "url": "https://kimaki.test/discord-install?clientId=<clientId>&clientSecret=<secret>&kimakiCallbackUrl=https%3A%2F%2Fexample.com%2Fdone",
+    }
+  `)
+})

package/src/onboarding.e2e.test.ts

@@ -0,0 +1,171 @@
+// First start in gateway mode (the twin plays gateway-proxy): the bot creates
+// the default channel with an onboarding thread, the onboarding session adds a
+// project channel with `kimaki project add` (real CLI process, run by the
+// agent's shell tool, reading the saved gateway credentials), and the new
+// channel answers without a bot restart.
+
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { API } from '@discordjs/core/http-only'
+import { ChannelType } from 'discord.js'
+import { afterAll, beforeAll, expect, test } from 'vitest'
+
+import type { BotHandle } from './main.ts'
+import { kimakiShellCommand, runOnboarding } from './onboarding.ts'
+import {
+  TEST_USER_ID,
+  scriptedTurn,
+  startOpencodeTestServer,
+  startTestBot,
+  startTwin,
+  tempDataDir,
+  textParts,
+  waitFor,
+  waitForFooter,
+  warmUp,
+  type OpencodeTestServer,
+  type TestTwin,
+} from './test/harness.ts'
+
+let server: OpencodeTestServer
+let twin: TestTwin
+let bot: BotHandle
+let dataDir: string
+let kimaki: string
+let otherProject: string
+
+beforeAll(async () => {
+  dataDir = tempDataDir()
+  twin = await startTwin({ gateway: true })
+  const require = createRequire(import.meta.url)
+  kimaki = kimakiShellCommand({
+    command: [process.execPath, require.resolve('tsx/cli'), path.join(import.meta.dirname, 'cli.ts')],
+  })
+  otherProject = path.join(dataDir, 'other-project')
+  fs.mkdirSync(otherProject)
+  execFileSync('git', ['init', '-q'], { cwd: otherProject })
+  server = await startOpencodeTestServer({
+    matchers: [
+      {
+        id: 'onboarding-greeting',
+        priority: 50,
+        when: { latestUserTextIncludes: 'This is the Kimaki onboarding thread' },
+        then: { parts: textParts('Want channels for your projects? I can search for git repositories.') },
+      },
+      ...scriptedTurn({
+        marker: 'add-other-project',
+        steps: [
+          {
+            id: 'call-project-add',
+            tool: 'shell',
+            input: { command: `${kimaki} project add ${otherProject}`, description: 'add project channel' },
+          },
+        ],
+        finalText: 'Added the channel for other-project.',
+      }),
+    ],
+  })
+  await warmUp({ server })
+  bot = await startTestBot({ dataDir, twin, server })
+}, 120_000)
+
+afterAll(async () => {
+  await bot?.stop()
+  await twin?.stop()
+  await server?.stop()
+  fs.rmSync(dataDir, { recursive: true, force: true })
+})
+
+async function guildChannels() {
+  const channels = await new API(bot.discord.rest).guilds.getChannels(twin.discord.guildId)
+  const names = new Map(channels.map((channel) => [channel.id, channel.name]))
+  return channels.map((channel) => {
+    const parent = channel.parent_id ? names.get(channel.parent_id) : null
+    return `${channel.name}${parent ? ` (in ${parent})` : ''}`
+  })
+}
+
+test('onboarding thread adds a project channel through the kimaki CLI, which answers at once', async () => {
+  const { discord } = twin
+  const guild = bot.discord.guilds.cache.get(discord.guildId)!
+  const onboarded = await runOnboarding({ bot, dataDir, guild, kimaki, gateway: true, installerId: TEST_USER_ID, machine: 'test-machine' })
+  if (!onboarded || onboarded instanceof Error) throw new Error(`onboarding failed: ${onboarded?.message}`, { cause: onboarded })
+  await waitForFooter({ discord, threadId: onboarded.threadId })
+
+  await discord.thread(onboarded.threadId).user(TEST_USER_ID).sendMessage({ content: 'yes, add-other-project' })
+  await waitForFooter({ discord, threadId: onboarded.threadId, count: 2 })
+
+  expect(await discord.channel(onboarded.channelId).text()).toMatchInlineSnapshot(`
+    "--- from: assistant (TestBot)
+    **Kimaki** lets you code from Discord. Each project channel is linked to a folder on your computer. A message there starts an AI coding session in that folder.
+    Reply in the thread below to add channels for your projects. <@200000000000000001>"
+  `)
+  expect(await discord.thread(onboarded.threadId).text()).toMatchInlineSnapshot(`
+    "--- from: assistant (TestBot)
+    **Kimaki** lets you code from Discord. Each project channel is linked to a folder on your computer. A message there starts an AI coding session in that folder.
+    Reply in the thread below to add channels for your projects. <@200000000000000001>
+    -# *using deterministic-provider/deterministic-v2 ⋅ build*
+    Want channels for your projects? I can search for git repositories.
+    -# *kimaki ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
+    --- from: user (tommy)
+    yes, add-other-project
+    --- from: assistant (TestBot)
+    -# ┣ shell _add project channel_
+
+    Added the channel for other-project.
+    -# *kimaki ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+  `)
+  expect(await guildChannels()).toMatchInlineSnapshot(`
+    [
+      "project",
+      "random",
+      "quiet",
+      "Kimaki test-machine",
+      "kimaki (in Kimaki test-machine)",
+      "other-project (in Kimaki test-machine)",
+    ]
+  `)
+
+  const rows = await bot.db.query.channel_directories.findMany({ orderBy: { created_at: 'asc' } })
+  expect(rows.map((row) => path.relative(dataDir, row.directory))).toMatchInlineSnapshot(`
+    [
+      "projects/kimaki",
+      "other-project",
+    ]
+  `)
+
+  // The new channel answers without restarting the bot.
+  const added = rows.find((row) => row.directory === otherProject)!
+  await discord.channel(added.channel_id).user(TEST_USER_ID).sendMessage({ content: 'hello new channel' })
+  const thread = await discord.channel(added.channel_id).waitForThread({ timeout: 8_000 })
+  await waitForFooter({ discord, threadId: thread.id })
+
+  // Second start: nothing is created again.
+  expect(await runOnboarding({ bot, dataDir, guild, kimaki, gateway: true, machine: 'test-machine' })).toBe(null)
+  await waitFor({ label: 'no extra channels', check: async () => (await guildChannels()).length === 6 })
+
+  // An empty default channel means an earlier onboarding failed: retry in the same channel.
+  const defaultChannel = rows.find((row) => row.directory !== otherProject)!
+  const channel = await bot.discord.channels.fetch(defaultChannel.channel_id)
+  if (channel?.type !== ChannelType.GuildText) throw new Error('default channel is not a text channel')
+  for (const message of (await channel.messages.fetch()).values()) await message.delete()
+  const retried = await runOnboarding({ bot, dataDir, guild, kimaki, gateway: true, installerId: TEST_USER_ID, machine: 'test-machine' })
+  if (retried instanceof Error || !retried) throw new Error(`expected a retried onboarding, got ${retried}`)
+  expect(retried.channelId).toBe(defaultChannel.channel_id)
+  await waitForFooter({ discord, threadId: retried.threadId })
+  expect((await guildChannels()).length).toBe(6)
+}, 30_000)
+
+test('an upgraded setup with project mappings skips onboarding without selecting a server', async () => {
+  const before = await guildChannels()
+  expect(await runOnboarding({
+    bot,
+    dataDir: path.join(dataDir, 'upgraded-layout'),
+    kimaki,
+    gateway: true,
+    machine: 'test-machine',
+  })).toBe(null)
+  expect(await guildChannels()).toEqual(before)
+})