kimaki 0.22.0 → 0.23.0

package/src/database.ts

@@ -193,10 +193,9 @@ export async function recoverStaleRunningScheduledTasks({ staleBefore }: { stale
   return countRows(rows)
 }
 
-export async function markScheduledTaskOneShotCompleted({ taskId, completedAt }: { taskId: number; completedAt: Date }) {
+export async function deleteScheduledTask(taskId: number) {
   const db = await getDb()
-  await db.update(schema.scheduled_tasks)
-    .set({ status: 'completed', last_run_at: completedAt, running_started_at: null, last_error: null })
+  await db.delete(schema.scheduled_tasks)
     .where(orm.eq(schema.scheduled_tasks.id, taskId))
 }
 
@@ -762,20 +761,20 @@ export async function getAnyAudioApiKey(): Promise<{ provider: 'openai' | 'gemin
 
 
 
-export async function setChannelDirectory({ channelId, directory, channelType, skipIfExists = false }: { channelId: string; directory: string; channelType: DatabaseChannelType; skipIfExists?: boolean }) {
+export async function setChannelDirectory({ channelId, directory, channelType, guildId, skipIfExists = false }: { channelId: string; directory: string; channelType: DatabaseChannelType; guildId?: string; skipIfExists?: boolean }) {
   const db = await getDb()
   if (skipIfExists) {
     await db.insert(schema.channel_directories)
-      .values({ channel_id: channelId, directory, channel_type: channelType })
+      .values({ channel_id: channelId, directory, channel_type: channelType, guild_id: guildId })
       .onConflictDoNothing({ target: schema.channel_directories.channel_id })
     return
   }
   await db.insert(schema.channel_directories)
-    .values({ channel_id: channelId, directory, channel_type: channelType })
-    .onConflictDoUpdate({ target: schema.channel_directories.channel_id, set: { directory, channel_type: channelType } })
+    .values({ channel_id: channelId, directory, channel_type: channelType, guild_id: guildId })
+    .onConflictDoUpdate({ target: schema.channel_directories.channel_id, set: { directory, channel_type: channelType, guild_id: guildId } })
 }
 
-export async function findChannelsByDirectory({ directory, channelType }: { directory?: string; channelType?: DatabaseChannelType }): Promise<Array<{ channel_id: string; directory: string; channel_type: string }>> {
+export async function findChannelsByDirectory({ directory, channelType }: { directory?: string; channelType?: DatabaseChannelType }): Promise<Array<{ channel_id: string; directory: string; channel_type: string; guild_id: string | null }>> {
   const db = await getDb()
   const where = directory && channelType
     ? { directory, channel_type: channelType }
@@ -784,7 +783,7 @@ export async function findChannelsByDirectory({ directory, channelType }: { dire
       : channelType
         ? { channel_type: channelType }
         : undefined
-  return db.query.channel_directories.findMany({ where, columns: { channel_id: true, directory: true, channel_type: true } })
+  return db.query.channel_directories.findMany({ where, columns: { channel_id: true, directory: true, channel_type: true, guild_id: true } })
 }
 
 export async function getAllTextChannelDirectories() {

package/src/db.ts

@@ -159,6 +159,7 @@ async function migrateSchema({
     "ALTER TABLE thread_sessions ADD COLUMN source TEXT DEFAULT 'kimaki'",
     'ALTER TABLE thread_sessions ADD COLUMN last_synced_name TEXT',
     'ALTER TABLE thread_sessions ADD COLUMN parent_session_id TEXT',
+    'ALTER TABLE channel_directories ADD COLUMN guild_id TEXT',
   ]
   for (const stmt of alterStatements) {
     await client.execute(stmt).catch(() => undefined)

package/src/discord-bot.ts

@@ -97,6 +97,7 @@ import { markDiscordGatewayReady, stopHranaServer } from './hrana-server.js'
 import { notifyError } from './sentry.js'
 import { flushDebouncedProcessCallbacks } from './debounced-process-flush.js'
 import { startRuntimeIdleSweeper } from './runtime-idle-sweeper.js'
+import { getDefaultKimakiDirectory } from './channel-management.js'
 import { store } from './store.js'
 import {
   startExternalOpencodeSessionSync,
@@ -1455,6 +1456,17 @@ export async function startDiscordBot({
   // channel are disposed by their own ThreadDelete events from Discord.
   discordClient.on(Events.ChannelDelete, async (channel) => {
     try {
+      // Check if this is the default kimaki channel. If so, preserve the
+      // channel_directories row as a tombstone so we don't recreate it.
+      const mapping = await getChannelDirectory(channel.id)
+      const defaultDir = getDefaultKimakiDirectory()
+      if (mapping && mapping.directory === defaultDir) {
+        discordLogger.log(
+          `Preserving channel_directories row for deleted default channel ${channel.id} as tombstone`,
+        )
+        return
+      }
+
       const deleted = await deleteChannelDirectoryById(channel.id)
       if (deleted) {
         discordLogger.log(

package/src/hrana-server.ts

@@ -24,6 +24,11 @@ import { createLogger, LogPrefix } from './logger.js'
 import { ServerStartError, FetchError } from './errors.js'
 import { getLockPort } from './config.js'
 import { store } from './store.js'
+// Circular import: opencode.ts → hrana-server.ts → opencode.ts.
+// Safe because both sides only use lazy runtime function calls, never
+// top-level initialization values. The cycle could be broken by moving
+// the port into store.ts, but the current approach is simpler.
+import { getOpencodeServerPort } from './opencode.js'
 
 const hranaLogger = createLogger(LogPrefix.DB)
 
@@ -175,6 +180,20 @@ export async function startHranaServer({
       res.end(JSON.stringify({ status: 'ok', pid: process.pid }))
       return
     }
+    // OpenCode server port discovery — no auth required (localhost only).
+    // CLI subcommands query this to reuse the bot's running OpenCode server
+    // instead of spawning a redundant second server process.
+    if (pathname === '/kimaki/opencode-port') {
+      const port = getOpencodeServerPort()
+      if (port === null) {
+        res.writeHead(404, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ error: 'no_opencode_server' }))
+        return
+      }
+      res.writeHead(200, { 'content-type': 'application/json' })
+      res.end(JSON.stringify({ port }))
+      return
+    }
     // Hrana routes: /v2, /v2/pipeline — require auth
     if (pathname === '/v2' || pathname === '/v2/pipeline') {
       if (!isAuthorizedRequest(req)) {

package/src/oauth-rotation-shared.ts

@@ -279,6 +279,28 @@ export function isTokenRefreshError(message: string) {
   )
 }
 
+/** Permanent OAuth refresh death (invalid_grant / expired refresh). Remove account, do not rotate. */
+export function isPermanentOAuthRefreshFailure(error: unknown): boolean {
+  const message =
+    typeof error === 'string'
+      ? error
+      : error instanceof Error
+        ? error.message
+        : ''
+  const haystack = message.toLowerCase()
+  if (!haystack) return false
+  if (haystack.includes('invalid_grant')) return true
+  if (haystack.includes('refresh token expired')) return true
+  if (haystack.includes('refresh_token') || haystack.includes('refresh token')) {
+    return (
+      haystack.includes('expired') ||
+      haystack.includes('invalid') ||
+      haystack.includes('revoked')
+    )
+  }
+  return false
+}
+
 // --- Auth file helpers ---
 
 export function isOAuthStored(value: unknown): value is OAuthStored {

package/src/opencode.ts

@@ -30,7 +30,10 @@ import {
   type PermissionRuleset,
 } from '@opencode-ai/sdk/v2'
 
-import { restartGlobalEventListener } from './session-handler/global-event-listener.js'
+import {
+  restartGlobalEventListener,
+  waitForGlobalEventListener,
+} from './session-handler/global-event-listener.js'
 import {
   getDataDir,
   getLockPort,
@@ -281,9 +284,12 @@ function buildStartupTimeoutReason({
 // Clients are created per-directory with the x-opencode-directory header.
 
 type SingleServer = {
-  process: ChildProcess
+  process: ChildProcess | null
   port: number
   baseUrl: string
+  /** True when this server was discovered from the bot's hrana endpoint,
+   *  not spawned by this process. We must not kill it on cleanup. */
+  discovered?: boolean
 }
 
 type ServerLifecycleEvent =
@@ -321,6 +327,11 @@ function killSingleServerProcessNow({
     return
   }
 
+  // Never kill a server we didn't spawn (discovered from another process)
+  if (singleServer.discovered || !singleServer.process) {
+    return
+  }
+
   const serverProcess = singleServer.process
   const pid = serverProcess.pid
   if (!pid || serverProcess.killed) {
@@ -559,22 +570,82 @@ function ensureOpencodeHomeDirectories({
   })
 }
 
+/**
+ * Try to discover an OpenCode server already running in the bot process.
+ * Queries the hrana server on the lock port for the OpenCode server port,
+ * then verifies the server is healthy. Returns null if no server found.
+ */
+async function discoverExistingServer(): Promise<SingleServer | null> {
+  const lockPort = getLockPort()
+  try {
+    const portResponse = await requestHealthcheck({
+      url: `http://127.0.0.1:${lockPort}/kimaki/opencode-port`,
+      timeoutMs: 2000,
+    })
+    if (portResponse.status !== 200) {
+      return null
+    }
+    const parsed = JSON.parse(portResponse.body)
+    const port = parsed?.port
+    if (typeof port !== 'number') {
+      return null
+    }
+
+    // Verify the OpenCode server is actually healthy
+    const healthResponse = await requestHealthcheck({
+      url: `http://127.0.0.1:${port}/api/health`,
+      timeoutMs: 2000,
+    })
+    if (healthResponse.status >= 500) {
+      return null
+    }
+
+    opencodeLogger.log(
+      `Discovered existing OpenCode server on port ${port} via hrana lock port ${lockPort}`,
+    )
+    return {
+      process: null,
+      port,
+      baseUrl: `http://127.0.0.1:${port}`,
+      discovered: true,
+    }
+  } catch {
+    // Connection refused or other network error — no bot running
+    return null
+  }
+}
+
 async function ensureSingleServer({
   directory,
 }: {
   directory?: string
 } = {}): Promise<ServerStartError | SingleServer> {
   const startupDirectory = directory || preferredStartupDirectory || undefined
-  if (singleServer && !singleServer.process.killed) {
+  if (singleServer && !singleServer.process?.killed) {
     return singleServer
   }
 
-  // Deduplicate concurrent startup attempts
+  // Deduplicate concurrent startup attempts (covers both discovery and spawn)
   if (startingServer) {
     return startingServer
   }
 
-  startingServer = startSingleServer({ directory: startupDirectory })
+  // Wrap discovery + spawn in a single shared promise so concurrent callers
+  // don't each run discoverExistingServer() and then each spawn a server.
+  startingServer = (async () => {
+    // Try to discover an already-running server from the bot process via
+    // the hrana server's /kimaki/opencode-port endpoint. This lets CLI
+    // subcommands (kimaki session list, archive, wait, etc.) reuse the
+    // bot's OpenCode server instead of spawning a redundant one.
+    const discovered = await discoverExistingServer()
+    if (discovered) {
+      singleServer = discovered
+      return discovered
+    }
+
+    return startSingleServer({ directory: startupDirectory })
+  })()
+
   try {
     return await startingServer
   } finally {
@@ -788,6 +859,7 @@ async function startSingleServer({
         OPENCODE_PORT: port.toString(),
         KIMAKI: '1',
         OPENCODE_EXPERIMENTAL_WORKSPACES: 'true',
+        OPENCODE_ENABLE_EXA: '1',
         KIMAKI_DATA_DIR: getDataDir(),
         KIMAKI_LOCK_PORT: getLockPort().toString(),
         KIMAKI_PARENT_LOCK_PORT: getLockPort().toString(),
@@ -1316,13 +1388,23 @@ export async function stopOpencodeServer(): Promise<boolean> {
   }
 
   const server = singleServer
+
+  // For discovered servers (from another process), just clear local state
+  // without killing the process we don't own.
+  if (server.discovered || !server.process) {
+    singleServer = null
+    clientCache.clear()
+    serverRetryCount = 0
+    return true
+  }
+
   opencodeLogger.log(
     `Stopping opencode server (pid: ${server.process.pid}, port: ${server.port})`,
   )
   if (!server.process.killed) {
     const killResult = errore.try(
       () => {
-        server.process.kill('SIGTERM')
+        server.process!.kill('SIGTERM')
       },
       (error) => {
         return new Error('Failed to send SIGTERM to opencode server', {
@@ -1366,5 +1448,7 @@ export async function restartOpencodeServer(): Promise<OpenCodeErrors | true> {
 
   const result = await ensureSingleServer()
   if (result instanceof Error) return result
+  restartGlobalEventListener()
+  await waitForGlobalEventListener()
   return true
 }

package/src/schema.sql

@@ -31,6 +31,7 @@ CREATE TABLE IF NOT EXISTS `channel_directories` (
 	`channel_id` text PRIMARY KEY,
 	`directory` text NOT NULL,
 	`channel_type` text NOT NULL,
+	`guild_id` text,
 	`created_at` datetime DEFAULT CURRENT_TIMESTAMP
 );
 

package/src/schema.ts

@@ -69,6 +69,9 @@ export const channel_directories = sqliteCore.sqliteTable('channel_directories',
   channel_id: sqliteCore.text('channel_id').primaryKey().notNull(),
   directory: sqliteCore.text('directory').notNull(),
   channel_type: sqliteCore.text('channel_type', { enum: ['text', 'voice'] }).notNull(),
+  // Guild that owns this channel. Used to scope the default-channel tombstone
+  // check so multi-guild setups don't cross-block each other.
+  guild_id: sqliteCore.text('guild_id'),
   created_at: datetime('created_at').default(orm.sql`CURRENT_TIMESTAMP`),
 })
 

package/src/session-handler/global-event-listener.ts

@@ -22,8 +22,18 @@ function isAbortError(err: unknown): boolean {
   return false
 }
 
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms))
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve()
+      return
+    }
+    const timeout = setTimeout(resolve, ms)
+    signal.addEventListener('abort', () => {
+      clearTimeout(timeout)
+      resolve()
+    }, { once: true })
+  })
 }
 
 // ── Types ──────────────────────────────────────────────────────
@@ -36,6 +46,8 @@ const callbacks = new Map<string, EventCallback>()
 let loopRunning = false
 let disposed = false
 let controller: AbortController | null = null
+let connected = false
+const connectionWaiters = new Set<() => void>()
 
 // ── Public API ─────────────────────────────────────────────────
 
@@ -70,6 +82,7 @@ export function unregisterEventListener(threadId: string): void {
 export function disposeGlobalEventListener(): void {
   disposed = true
   loopRunning = false
+  connected = false
   controller?.abort()
   controller = null
   callbacks.clear()
@@ -81,9 +94,19 @@ export function disposeGlobalEventListener(): void {
  */
 export function restartGlobalEventListener(): void {
   if (disposed) return
+  connected = false
   controller?.abort()
 }
 
+/** Wait until the event stream is connected before starting event-producing work. */
+export function waitForGlobalEventListener(): Promise<void> {
+  if (callbacks.size === 0 || connected) return Promise.resolve()
+  ensureListenerRunning()
+  return new Promise((resolve) => {
+    connectionWaiters.add(resolve)
+  })
+}
+
 // ── Internals ──────────────────────────────────────────────────
 
 // Lazy subscription to opencode server lifecycle. Deferred to avoid
@@ -161,7 +184,7 @@ async function runEventLoop(): Promise<void> {
       logger.warn(
         `[GLOBAL LISTENER] No OpenCode server available, retrying in ${backoffMs}ms`,
       )
-      await delay(backoffMs)
+      await delay(backoffMs, signal)
       backoffMs = Math.min(backoffMs * 2, maxBackoffMs)
       continue
     }
@@ -181,13 +204,16 @@ async function runEventLoop(): Promise<void> {
         `[GLOBAL LISTENER] Subscribe failed, retrying in ${backoffMs}ms:`,
         subscribeResult.message,
       )
-      await delay(backoffMs)
+      await delay(backoffMs, signal)
       backoffMs = Math.min(backoffMs * 2, maxBackoffMs)
       continue
     }
 
     const events = subscribeResult.stream
 
+    connected = true
+    for (const resolve of connectionWaiters) resolve()
+    connectionWaiters.clear()
     logger.log('[GLOBAL LISTENER] Connected to global event stream')
 
     let receivedAnyEvent = false
@@ -199,6 +225,8 @@ async function runEventLoop(): Promise<void> {
     })()
       .catch((e) => new OpenCodeSdkError({ operation: 'event.iterate', cause: e }))
 
+    connected = false
+
     if (receivedAnyEvent) {
       backoffMs = 500
     }
@@ -213,13 +241,17 @@ async function runEventLoop(): Promise<void> {
         `[GLOBAL LISTENER] Stream broke, reconnecting in ${backoffMs}ms:`,
         iterResult.message,
       )
-      await delay(backoffMs)
+      await delay(backoffMs, signal)
       backoffMs = Math.min(backoffMs * 2, maxBackoffMs)
     } else {
+      if (signal.aborted) {
+        backoffMs = 500
+        continue
+      }
       logger.log(
         `[GLOBAL LISTENER] Stream ended normally, reconnecting in ${backoffMs}ms`,
       )
-      await delay(backoffMs)
+      await delay(backoffMs, signal)
       backoffMs = Math.min(backoffMs * 2, maxBackoffMs)
     }
   }

package/src/session-handler/thread-runtime-state.ts

@@ -224,8 +224,11 @@ export function dequeueItem(threadId: string): QueuedMessage | undefined {
   return next
 }
 
-export function clearQueueItems(threadId: string): void {
+export function clearQueueItems(threadId: string): QueuedMessage[] {
+  const items =
+    store.getState().threads.get(threadId)?.queueItems.slice() ?? []
   updateThread(threadId, (t) => ({ ...t, queueItems: [] }))
+  return items
 }
 
 export function removeQueueItemAtPosition(

package/src/session-handler/thread-session-runtime.ts

@@ -34,6 +34,7 @@ import { isAbortError } from '../utils.js'
 import {
   registerEventListener,
   unregisterEventListener,
+  waitForGlobalEventListener,
 } from './global-event-listener.js'
 import { createLogger, LogPrefix } from '../logger.js'
 import {
@@ -2309,6 +2310,25 @@ export class ThreadSessionRuntime {
       repulseTyping: false,
     })
 
+    // Skip footer if model produced no visible output (no text, no tool calls,
+    // just step-start/step-finish lifecycle parts). This happens when the model
+    // decides not to respond.
+    const hasVisibleOutput = assistantMessageIds.some((msgId) => {
+      const parts = this.getBufferedParts(msgId)
+      return parts.some(
+        (part) => part.type !== 'step-start' && part.type !== 'step-finish',
+      )
+    })
+    if (!hasVisibleOutput) {
+      this.stopTyping()
+      this.resetPerRunState()
+      this.clearBufferedPartsForMessages(assistantMessageIds)
+      logger.log(
+        `[ASSISTANT COMPLETED] no visible output, skipping footer for message ${completedMessageId} sessionId=${sessionId}`,
+      )
+      return
+    }
+
     this.stopTyping()
 
     const turnStartTime = getCurrentTurnStartTime({
@@ -3094,6 +3114,7 @@ export class ThreadSessionRuntime {
         ...variantField,
         ...(input.noReply ? { noReply: true } : {}),
       }
+      await waitForGlobalEventListener()
       const promptResult = await getClient().session.promptAsync(request)
         .catch((e) => new OpenCodeSdkError({ operation: 'session.promptAsync', cause: e }))
       if (promptResult instanceof Error || promptResult.error) {
@@ -3482,9 +3503,9 @@ export class ThreadSessionRuntime {
       : NOTIFY_MESSAGE_FLAGS
   }
 
-  /** Clear all queued messages. */
-  clearQueue(): void {
-    threadState.clearQueueItems(this.threadId)
+  /** Clear all queued messages. Returns the removed items. */
+  clearQueue(): threadState.QueuedMessage[] {
+    return threadState.clearQueueItems(this.threadId)
   }
 
   /** Remove a queued message by its 1-based position. */
@@ -3972,6 +3993,7 @@ export class ThreadSessionRuntime {
       return
     }
 
+    await waitForGlobalEventListener()
     const promptResponse = await getClient().session.promptAsync({
       sessionID: session.id,
       directory: this.sdkDirectory,

package/src/system-message.test.ts

@@ -282,18 +282,30 @@ describe('system-message', () => {
 
       \`--wait\` is incompatible with \`--send-at\` because scheduled tasks run in the future.
 
-      For scheduled tasks, use long and detailed prompts with goal, constraints, expected output format, and explicit completion criteria.
+      Keep scheduled task prompts **short**. The prompt text becomes the first message in the Discord thread, so long prompts clutter the channel. Instead of inlining the full task description in \`--prompt\`, write a markdown file in the project's \`tasks/\` folder and reference it:
 
-      Notification prompts must be very detailed. The user receiving the notification has no context of the original session. Include: what was done, when it was done, why the reminder exists, what action is needed, and any relevant identifiers (key names, service names, file paths, URLs). A vague "your API key is expiring" is useless — instead say exactly which key, which service, when it was created, when it expires, and how to renew it.
+      \`\`\`bash
+      kimaki send --channel chan_123 --prompt 'Read tasks/weekly-test-suite.md and follow instructions' --send-at '0 9 * * 1' --agent <current_agent> --parent-session ses_123 --user '<discord-user-id>'
+      \`\`\`
+
+      The task file should contain all the detail: goal, constraints, expected output, completion criteria. Use this frontmatter format:
+
+      \`\`\`yaml
+      ---
+      title: Weekly test suite
+      description: >
+        Managed by kimaki scheduled task. Do not move or delete this file
+        without also updating the kimaki task (kimaki task list / kimaki task edit).
+      ---
+      \`\`\`
+
+      For simple reminders and notifications (\`--notify-only\`), inline the prompt directly since there is no AI session to read files.
 
-      Notification strategy for scheduled tasks:
+      Notification strategy:
       - NEVER use \`@username\` (e.g. \`@Tommy\`) directly in task prompts. The prompt text becomes the first message in the thread, so a raw \`@\` mention triggers an actual Discord ping every time the task fires. Instead, wrap it in inline code like \`\\\`@Tommy\\\`\`, or use Discord user ID mentions like \`<@USER_ID>\` only in the body of the prompt where the agent will process it, not in the opening line.
-      - Prefer selective mentions in the prompt instead of relying on broad thread notifications.
-      - If a task needs user attention, include this instruction in the prompt: "mention the user via Discord user ID when task requires user review or notification".
-      - Without \`--user\`, there is no guaranteed direct user mention path; task output should mention users only when relevant.
-      - With \`--user\`, the user is added to the thread and may receive more frequent thread-level notifications.
-      - If a scheduled task completes with no actionable result and no user-visible change, prefer archiving the session after the final message so Discord does not keep a no-op thread highlighted.
-      - Example no-op cleanup command: \`kimaki session archive thread_123 (or --session ses_123)\`
+      - If a task needs user attention, add "mention the user via Discord user ID when task requires user review" in the task md file.
+      - With \`--user\`, the user is added to the thread and receives thread-level notifications.
+      - If a scheduled task completes with no actionable result, archive the session: \`kimaki session archive thread_123 (or --session ses_123)\`
 
       Manage scheduled tasks with:
 
@@ -303,20 +315,22 @@ describe('system-message', () => {
 
       \`kimaki session list\` also shows if a session was started by a scheduled \`delay\` or \`cron\` task, including task ID when available.
 
+      **Never duplicate tasks to run more frequently.** If a task should run twice a day (morning and evening), edit the existing task's cron expression instead of creating a second task. Cron supports comma-separated hours:
+
+      \`\`\`bash
+      # runs at 9:00 UTC and 18:00 UTC every day
+      kimaki task edit <id> --send-at '0 9,18 * * *'
+      \`\`\`
+
       Use case patterns:
-      - Reminder flows: create deadline reminders in this channel with one-time \`--send-at\`; mention only if action is required.
-      - Proactive reminders: when you encounter time-sensitive information during your work (e.g. creating an API key that expires in 90 days, a certificate with an expiration date, a trial period ending, a deadline mentioned in code comments), proactively schedule a \`--notify-only\` reminder before the expiration so the user gets notified in time. For example, if you generate an API key expiring on 2026-06-01, schedule a reminder a few days before: \`kimaki send --channel chan_123 --prompt 'Reminder: <@USER_ID> the API key created on 2026-03-01 expires on 2026-06-01. Renew it before it breaks production.' --send-at '2026-05-28T09:00:00Z' --notify-only --agent <current_agent>\`. Always tell the user you scheduled the reminder so they know.
-      - Weekly QA: schedule "run full test suite, inspect failures, post summary, and mention the user via Discord ID only when failures require review".
-      - Weekly benchmark automation: schedule a benchmark prompt that runs model evals, writes JSON outputs in the repo, commits results, and mentions only for regressions.
-      - Recurring maintenance: use cron \`--send-at\` for repetitive tasks like rotating secrets, checking dependency updates, running security audits, or cleaning up stale branches. Example: \`--send-at "0 9 1 * *"\` to run on the 1st of every month.
-      - Quiet no-op checks: if a recurring task checks something and finds nothing to report, let it post a brief final summary and then archive the session with \`kimaki session archive thread_123 (or --session ses_123)\`. Example: a scheduled email triage run that finds no new emails should archive itself so it does not add noise to Discord.
-      - Thread reminders: when the user says "remind me about this in 2 hours" (or any duration), use \`--send-at\` with \`--thread\` to resurface the current thread. Compute the future UTC time and send a mention so Discord shows a notification:
+      - Reminder flows: create deadline reminders with one-time \`--send-at\` and \`--notify-only\`; mention only if action is required.
+      - Proactive reminders: when you encounter time-sensitive information (API key expiration, certificate renewal, trial ending), schedule a \`--notify-only\` reminder before the deadline. Always tell the user you scheduled the reminder so they know.
+      - Weekly QA / recurring maintenance: write the full task spec in \`tasks/\` and schedule a short prompt pointing to it.
+      - Thread reminders: when the user says "remind me about this in 2 hours", use \`--send-at\` with \`--thread\` to resurface the current thread:
 
       kimaki send --thread thread_123 (or --session ses_123) --prompt 'Reminder: <@USER_ID> you asked to be reminded about this thread.' --send-at '<future_UTC_time>' --notify-only --agent <current_agent>
 
-      Replace \`<future_UTC_time>\` with the computed UTC ISO timestamp. The \`--notify-only\` flag creates just a notification message without starting a new AI session. The \`<@userId>\` mention ensures the user gets a Discord notification.
-
-      Scheduled tasks can maintain project memory by reading and updating an md file in the repository (for example \`docs/automation-notes.md\`) on each run.
+      Replace \`<future_UTC_time>\` with the computed UTC ISO timestamp.
 
       Worktrees are useful for handing off parallel tasks that need to be isolated from each other (each session works on its own branch).
 
@@ -798,7 +812,7 @@ describe('system-message', () => {
       - Main repo path (previous folder, DO NOT TOUCH): /repo
       - To find the base branch (the branch this worktree was created from): \`git -C /repo symbolic-ref --short HEAD\`
       - To find the base commit (the commit this worktree diverged from): \`git merge-base <base-branch> HEAD\`
-      You MUST read, write, and edit files only under the new worktree path /repo/.worktrees/prompt-cache. You MUST NOT read, write, or edit any files under the main repo path /repo — even though it is the same project, that folder is a separate checkout and the user or another agent may be actively working there, so writing to it would override their unrelated changes. Run all checks (tests, builds, lint) inside the new worktree. Do not create another worktree by default. Ask before merging changes back to the main branch.
+      You MUST read, write, and edit files only under the new worktree path /repo/.worktrees/prompt-cache. You MUST NOT read, write, or edit any files under the main repo path /repo — even though it is the same project, that folder is a separate checkout and the user or another agent may be actively working there, so writing to it would override their unrelated changes. Run all checks (tests, builds, lint) inside the new worktree. Do not create another worktree by default. To merge this worktree into the main branch, run \`kimaki merge-worktree\`. If it reports rebase conflicts, resolve them and rerun until it succeeds.
       </system-reminder>
       "
     `)