kimaki 0.26.0 → 0.27.0

package/src/system-message.test.ts

@@ -25,6 +25,15 @@ afterEach(async () => {
 })
 
 describe('system-message', () => {
+  test('requires reading the report-bugs guide before filing kimaki issues', () => {
+    const message = getOpencodeSystemMessage({
+      sessionId: 'ses_123',
+    })
+    expect(message).toContain(
+      'Never open a pull request on remorses/kimaki unless remorses asked for one in a comment on the issue',
+    )
+  })
+
   test('includes callout guidance for important content', () => {
     const message = getOpencodeSystemMessage({
       sessionId: 'ses_123',
@@ -48,6 +57,7 @@ describe('system-message', () => {
     expect(message).toContain('NEVER call `question` before your text')
     expect(message).toContain('`kimaki_action_buttons`')
     expect(message).toContain('`kimaki_file_upload`')
+    expect(message).toContain('`kimaki_sleep`')
   })
 
   test('persists and reads session system prompt for command path', async () => {
@@ -100,6 +110,22 @@ describe('system-message', () => {
     ).rejects.toMatchObject({ code: 'EISDIR' })
   })
 
+  test('includes session title update guidance when scope or goal changed', () => {
+    const message = getOpencodeSystemMessage({
+      sessionId: 'ses_123',
+      threadId: 'thread_123',
+    })
+    expect(message).toContain('## updating the session title')
+    expect(message).toContain(
+      "kimaki session title 'Short title' --session ses_123",
+    )
+    expect(message).toContain(
+      'When the session scope or goal changed from the first message, update the title:',
+    )
+    expect(message).toContain('thread-name="..."')
+    expect(message).toContain('Do not retitle every turn')
+  })
+
   test('includes parent session context when parentSessionId is set', () => {
     const message = getOpencodeSystemMessage({
       sessionId: 'ses_child',
@@ -151,6 +177,9 @@ describe('system-message', () => {
     expect(message).toContain(
       'When pulling submodules and they jump to a new commit, commit that submodule pointer update right away before doing other work.',
     )
+    expect(message).toContain(
+      'while kimaki session list --active --exclude ses_123; do sleep 5; done',
+    )
 
     expect(message).toMatchInlineSnapshot(`
       "
@@ -180,7 +209,7 @@ describe('system-message', () => {
       Your current Discord thread ID is: thread_123
       Your current Discord guild ID is: guild_123
 
-      Per-turn Discord metadata like the current user and current agent is delivered in synthetic user message parts.
+      Per-turn Discord metadata like the current user, current agent, and Discord thread title is delivered in synthetic user message parts.
 
       ## permissions
 
@@ -203,6 +232,7 @@ describe('system-message', () => {
 
       ## debugging kimaki issues
 
+      ALWAYS read https://kimaki.dev/docs/guides/report-bugs first before submitting any issue to Kimaki. That page is the source of truth for exporting session jsonl, sharing evidence in a gist, and filing bugs. Never open a pull request on remorses/kimaki unless remorses asked for one in a comment on the issue.
       If there are internal kimaki issues (sessions not responding, bot errors, unexpected behavior), read the log file at \`<data-dir>/kimaki.log\`. This file contains detailed logs of all bot activity including session creation, event handling, errors, and API calls. The log file is reset every time the bot restarts, so it only contains logs from the current run.
 
       ## uploading files to discord
@@ -232,9 +262,16 @@ describe('system-message', () => {
       To ask the user to upload files from their device, use \`kimaki_file_upload\`. This shows a native file picker dialog in Discord. The files are downloaded to the project's \`uploads/\` directory and the tool returns the local file paths.
       You MUST call \`kimaki_file_upload\` LAST, after ALL text.
 
+      ## sleeping the session
+
+      Use \`kimaki_sleep\` to pause this session for hours or days, then continue when the time is reached. The sleep is stored in SQLite and survives bot restarts.
+      Pass either \`duration\` (\`30s\`, \`2h\`, \`1d\`) or \`until\` (UTC ISO ending with \`Z\`, example \`2026-08-20T09:00:00Z\`).
+      You MUST call \`kimaki_sleep\` LAST, after ALL text. Do not call more tools after it.
+      A new user message cancels the sleep. After wake, continue the wait reason.
+
       ## archiving the current thread
 
-      To archive the current Discord thread (hide it from sidebar) and stop the session, run:
+      To archive the current Discord thread (hide it from sidebar) without stopping the session, run:
 
       kimaki session archive thread_123 (or --session ses_123)
 
@@ -249,6 +286,17 @@ describe('system-message', () => {
       This stops the AI from processing but keeps the thread visible in Discord.
       Different from \`kimaki session archive\` which hides the thread.
 
+      ## updating the session title
+
+      When the session scope or goal changed from the first message, update the title:
+
+      kimaki session title 'Short title' --session ses_123
+
+      The current Discord thread title is in the per-turn \`<discord-user thread-name="..." />\` metadata.
+      This updates the OpenCode title. Discord follows automatically.
+      Do not retitle every turn. Discord rate-limits thread renames.
+      Keep titles short. Do not add emoji. Do not copy ⬦, btw:, or Fork: prefixes.
+
       ## discord user mentions
 
       Prefer Discord user IDs for mentions. Discord bots cannot ping by @name; use \`<@userId>\` in message text or pass the ID to \`--user\`.
@@ -480,6 +528,9 @@ describe('system-message', () => {
       kimaki session list
       kimaki session list --json  # machine-readable output
       kimaki session list --project /path/to/project  # specific project
+
+      # List only in-progress sessions. Exit status is 1 when none remain.
+      kimaki session list --active
       \`\`\`
 
       To search past sessions for this project (supports plain text or /regex/flags):
@@ -500,6 +551,29 @@ describe('system-message', () => {
 
       Then use grep/read tools on the file to find what you need.
 
+      ### who edited a file
+
+      To find the session that last edited a file, run:
+
+      \`\`\`bash
+      kimaki session editors src/foo.ts
+      kimaki session editors src/foo.ts --json
+      \`\`\`
+
+      Output is newest first. Each row has:
+
+      - **session ID** (\`ses_xxx\`)
+      - **title** (Discord thread name, so you can tell what that session was doing)
+      - **time ago** (when that session last edited the file)
+
+      Use this before a commit when this session did not edit the file. Put the original session ID as the last line of the commit message:
+
+      \`\`\`
+      Session: ses_xxx
+      \`\`\`
+
+      If this session edited the file, use this session ID instead. If several files come from different sessions, split the commit by session. Do not attribute another session's edits to this one.
+
       ## cross-project commands
 
       When the user references another project by name, run \`kimaki project list\` to find its directory path and channel ID. Then read files, search code, or run commands directly in that directory. If the project is not listed, use \`kimaki project add /path/to/repo\` to register it and create a Discord channel for it. Do not add subfolders of an existing project — only add root project directories.
@@ -566,7 +640,7 @@ describe('system-message', () => {
 
       When the user asks you to wait for an existing session, run \`kimaki session wait <session_id>\` yourself via Bash, then continue from the printed session markdown. Do not tell the user to run the command.
 
-      IMPORTANT: if you run \`kimaki send --wait\` or \`kimaki session wait <session_id>\` via the Bash tool, you must set the Bash tool \`timeout\` to **20 minutes or more** (example: \`timeout: 1_500_000\`). Otherwise the tool will terminate early (default is 2 minutes) and you won't see long sessions.
+      IMPORTANT: if you run \`kimaki send --wait\`, \`kimaki session wait <session_id>\`, or the active-session wait loop via the Bash tool, you must set the Bash tool \`timeout\` to **20 minutes or more** (example: \`timeout: 1_500_000\`). Otherwise the tool will terminate early (default is 2 minutes) and you won't see long sessions.
 
       If your Bash tool timeout triggers anyway, fall back to reading the session output from disk:
 
@@ -581,9 +655,14 @@ describe('system-message', () => {
 
       # Wait for a session that was already started elsewhere
       kimaki session wait <session_id>
+
+      # Wait until every other in-progress session in this project finishes
+      while kimaki session list --active --exclude ses_123; do sleep 5; done
       \`\`\`
 
-      The command exits with the session markdown on stdout once the model finishes responding.
+      \`session list --active\` exits with status 0 while it finds active sessions and status 1 when none remain. Exclude the current session in a wait loop so the loop does not wait for itself.
+
+      \`session wait\` exits with the session markdown on stdout once the model finishes responding.
 
       Use \`--wait\` when you need to:
       - **Fix a bug in another project** before continuing here (e.g. fix a dependency, then resume)
@@ -848,7 +927,7 @@ describe('system-message', () => {
       You MUST call \`question\` LAST, after ALL text parts.
       NEVER call \`question\` before your text. Discord will hide the message.
 
-      The same rule applies to \`kimaki_action_buttons\` and \`kimaki_file_upload\`.
+      The same rule applies to \`kimaki_action_buttons\`, \`kimaki_file_upload\`, and \`kimaki_sleep\`.
       You MUST call them LAST, after ALL text.
 
       ALWAYS use \`question\` when you ask the user a question. Do not write a numbered list in plain text.
@@ -878,6 +957,7 @@ describe('system-message', () => {
         userId: 'user_123',
         sourceMessageId: 'msg_123',
         sourceThreadId: 'thread_123',
+        threadName: 'Fix auth bug',
         repliedMessage: {
           authorUsername: 'alice',
           text: 'Original replied message',
@@ -891,7 +971,7 @@ describe('system-message', () => {
         },
       }),
     ).toMatchInlineSnapshot(`
-      "<discord-user name="Tommy" user-id="user_123" message-id="msg_123" thread-id="thread_123" />
+      "<discord-user name="Tommy" user-id="user_123" message-id="msg_123" thread-id="thread_123" thread-name="Fix auth bug" />
 
       This message was a reply to message
 

package/src/system-message.ts

@@ -316,9 +316,13 @@ export type ThreadStartMarker = {
   /**
    * OpenCode session ID of the parent session that spawned this thread via
    * `kimaki send --parent-session`. Exposed in the child system message so the
-   * child can message the parent only when the user explicitly asks.
-   */
+    * child can message the parent only when the user explicitly asks.
+    */
   parentSessionId?: string
+  /** Wake prompt posted after kimaki_sleep. Ingress must not cancel this sleep. */
+  sleepWake?: boolean
+  /** delivery_id of the session_sleeps row this wake delivers. */
+  sleepId?: string
 }
 
 export function isInjectedPromptMarker({
@@ -357,6 +361,7 @@ export function getOpencodePromptContext({
   userId,
   sourceMessageId,
   sourceThreadId,
+  threadName,
   repliedMessage,
   worktree,
   currentAgent,
@@ -366,6 +371,7 @@ export function getOpencodePromptContext({
   userId?: string
   sourceMessageId?: string
   sourceThreadId?: string
+  threadName?: string
   repliedMessage?: RepliedMessageContext
   worktree?: WorktreeInfo
   currentAgent?: string
@@ -384,6 +390,9 @@ export function getOpencodePromptContext({
     ...(sourceThreadId
       ? [` thread-id="${escapePromptAttribute(sourceThreadId)}"`]
       : []),
+    ...(threadName
+      ? [` thread-name="${escapePromptAttribute(threadName)}"`]
+      : []),
   ].join('')
   const repliedMessageXml = repliedMessage
     ? `This message was a reply to message
@@ -486,7 +495,7 @@ interface BashToolInput {
 
 Your current OpenCode session ID is: ${sessionId}${channelId ? `\nYour current Discord channel ID is: ${channelId}` : ''}${threadId ? `\nYour current Discord thread ID is: ${threadId}` : ''}${guildId ? `\nYour current Discord guild ID is: ${guildId}` : ''}${parentSessionContext}
 
-Per-turn Discord metadata like the current user and current agent is delivered in synthetic user message parts.
+Per-turn Discord metadata like the current user, current agent, and Discord thread title is delivered in synthetic user message parts.
 
 ## permissions
 
@@ -509,6 +518,7 @@ Do not restart the bot unless the user explicitly asks for it.
 
 ## debugging kimaki issues
 
+ALWAYS read https://kimaki.dev/docs/guides/report-bugs first before submitting any issue to Kimaki. That page is the source of truth for exporting session jsonl, sharing evidence in a gist, and filing bugs. Never open a pull request on remorses/kimaki unless remorses asked for one in a comment on the issue.
 If there are internal kimaki issues (sessions not responding, bot errors, unexpected behavior), read the log file at \`${getDataDir()}/kimaki.log\`. This file contains detailed logs of all bot activity including session creation, event handling, errors, and API calls. The log file is reset every time the bot restarts, so it only contains logs from the current run.
 
 ## uploading files to discord
@@ -538,9 +548,16 @@ see --help for options like voice, speed, etc.
 To ask the user to upload files from their device, use \`kimaki_file_upload\`. This shows a native file picker dialog in Discord. The files are downloaded to the project's \`uploads/\` directory and the tool returns the local file paths.
 You MUST call \`kimaki_file_upload\` LAST, after ALL text.
 
+## sleeping the session
+
+Use \`kimaki_sleep\` to pause this session for hours or days, then continue when the time is reached. The sleep is stored in SQLite and survives bot restarts.
+Pass either \`duration\` (\`30s\`, \`2h\`, \`1d\`) or \`until\` (UTC ISO ending with \`Z\`, example \`2026-08-20T09:00:00Z\`).
+You MUST call \`kimaki_sleep\` LAST, after ALL text. Do not call more tools after it.
+A new user message cancels the sleep. After wake, continue the wait reason.
+
 ## archiving the current thread
 
-To archive the current Discord thread (hide it from sidebar) and stop the session, run:
+To archive the current Discord thread (hide it from sidebar) without stopping the session, run:
 
 kimaki session archive ${archiveTarget}
 
@@ -555,6 +572,17 @@ kimaki session abort <session_id>
 This stops the AI from processing but keeps the thread visible in Discord.
 Different from \`kimaki session archive\` which hides the thread.
 
+## updating the session title
+
+When the session scope or goal changed from the first message, update the title:
+
+kimaki session title 'Short title' --session ${sessionId}
+
+The current Discord thread title is in the per-turn \`<discord-user thread-name="..." />\` metadata.
+This updates the OpenCode title. Discord follows automatically.
+Do not retitle every turn. Discord rate-limits thread renames.
+Keep titles short. Do not add emoji. Do not copy ⬦, btw:, or Fork: prefixes.
+
 ## discord user mentions
 
 Prefer Discord user IDs for mentions. Discord bots cannot ping by @name; use \`<@userId>\` in message text or pass the ID to \`--user\`.
@@ -784,6 +812,9 @@ To list all sessions in this project (shows which were started via kimaki):
 kimaki session list
 kimaki session list --json  # machine-readable output
 kimaki session list --project /path/to/project  # specific project
+
+# List only in-progress sessions. Exit status is 1 when none remain.
+kimaki session list --active
 \`\`\`
 
 To search past sessions for this project (supports plain text or /regex/flags):
@@ -804,6 +835,29 @@ kimaki session read <sessionId> > ./tmp/session.md 2>/dev/null
 
 Then use grep/read tools on the file to find what you need.
 
+### who edited a file
+
+To find the session that last edited a file, run:
+
+\`\`\`bash
+kimaki session editors src/foo.ts
+kimaki session editors src/foo.ts --json
+\`\`\`
+
+Output is newest first. Each row has:
+
+- **session ID** (\`ses_xxx\`)
+- **title** (Discord thread name, so you can tell what that session was doing)
+- **time ago** (when that session last edited the file)
+
+Use this before a commit when this session did not edit the file. Put the original session ID as the last line of the commit message:
+
+\`\`\`
+Session: ses_xxx
+\`\`\`
+
+If this session edited the file, use this session ID instead. If several files come from different sessions, split the commit by session. Do not attribute another session's edits to this one.
+
 ## cross-project commands
 
 When the user references another project by name, run \`kimaki project list\` to find its directory path and channel ID. Then read files, search code, or run commands directly in that directory. If the project is not listed, use \`kimaki project add /path/to/repo\` to register it and create a Discord channel for it. Do not add subfolders of an existing project — only add root project directories.
@@ -870,7 +924,7 @@ Use \`--wait\` to block until a session completes and print its full conversatio
 
 When the user asks you to wait for an existing session, run \`kimaki session wait <session_id>\` yourself via Bash, then continue from the printed session markdown. Do not tell the user to run the command.
 
-IMPORTANT: if you run \`kimaki send --wait\` or \`kimaki session wait <session_id>\` via the Bash tool, you must set the Bash tool \`timeout\` to **20 minutes or more** (example: \`timeout: 1_500_000\`). Otherwise the tool will terminate early (default is 2 minutes) and you won't see long sessions.
+IMPORTANT: if you run \`kimaki send --wait\`, \`kimaki session wait <session_id>\`, or the active-session wait loop via the Bash tool, you must set the Bash tool \`timeout\` to **20 minutes or more** (example: \`timeout: 1_500_000\`). Otherwise the tool will terminate early (default is 2 minutes) and you won't see long sessions.
 
 If your Bash tool timeout triggers anyway, fall back to reading the session output from disk:
 
@@ -885,9 +939,14 @@ kimaki send --thread <thread_id> --prompt 'Run the tests' --wait --agent <curren
 
 # Wait for a session that was already started elsewhere
 kimaki session wait <session_id>
+
+# Wait until every other in-progress session in this project finishes
+while kimaki session list --active --exclude ${sessionId}; do sleep 5; done
 \`\`\`
 
-The command exits with the session markdown on stdout once the model finishes responding.
+\`session list --active\` exits with status 0 while it finds active sessions and status 1 when none remain. Exclude the current session in a wait loop so the loop does not wait for itself.
+
+\`session wait\` exits with the session markdown on stdout once the model finishes responding.
 
 Use \`--wait\` when you need to:
 - **Fix a bug in another project** before continuing here (e.g. fix a dependency, then resume)
@@ -1001,7 +1060,7 @@ You MUST write ALL user-visible text FIRST.
 You MUST call \`question\` LAST, after ALL text parts.
 NEVER call \`question\` before your text. Discord will hide the message.
 
-The same rule applies to \`kimaki_action_buttons\` and \`kimaki_file_upload\`.
+The same rule applies to \`kimaki_action_buttons\`, \`kimaki_file_upload\`, and \`kimaki_sleep\`.
 You MUST call them LAST, after ALL text.
 
 ALWAYS use \`question\` when you ask the user a question. Do not write a numbered list in plain text.

package/src/task-runner.ts

@@ -1,6 +1,6 @@
-// Scheduled task runner for executing due `send --send-at` jobs in the bot process.
+// Scheduled task runner for due `send --send-at` jobs and session sleep wakes.
 
-import { type REST, Routes } from 'discord.js'
+import { DiscordAPIError, type REST, Routes } from 'discord.js'
 import { createDiscordRest } from './discord-urls.js'
 import { ensureThreadMember } from './discord-utils.js'
 import YAML from 'yaml'
@@ -20,6 +20,11 @@ import {
   releaseScheduledTaskClaim,
   setScheduledTaskRunThread,
   type ScheduledTask,
+  type SessionSleep,
+  claimSessionSleepAttempt,
+  getDueSessionSleeps,
+  getThreadIdBySessionId,
+  markSessionSleepFailed,
 } from './database.js'
 import { execAsync } from './exec-async.js'
 import { initializeOpencodeForDirectory } from './opencode.js'
@@ -29,6 +34,7 @@ import type { ThreadStartMarker } from './system-message.js'
 import {
   type ScheduledTaskPayload,
   appendTaskCommandOutput,
+  formatSessionSleepWakePrompt,
   getNextCronRun,
   getPromptPreview,
   parseScheduledTaskPayload,
@@ -129,6 +135,132 @@ async function executeThreadScheduledTask({
   return payload.threadId
 }
 
+/** Wait before retrying a wake that ingress has not consumed yet. */
+const SLEEP_WAKE_RETRY_AFTER_MS = 30_000
+const SLEEP_WAKE_MAX_ATTEMPTS = 5
+
+type SleepWakeFailure = { error: Error; permanent: boolean }
+
+export function buildSessionSleepWakeBody({
+  deliveryId,
+  wakeAt,
+  reason,
+}: {
+  deliveryId: string
+  wakeAt: Date
+  reason: string | null
+}) {
+  const marker: ThreadStartMarker = {
+    start: true,
+    sleepWake: true,
+    sleepId: deliveryId,
+  }
+  return {
+    content: formatSessionSleepWakePrompt({ wakeAt, reason }),
+    embeds: [{ color: 0x2b2d31, footer: { text: YAML.stringify(marker) } }],
+    // Discord limits nonces to 25 characters. The full ID stays in the marker.
+    // A stable nonce deduplicates retries when a successful response is lost.
+    nonce: deliveryId.replaceAll('-', '').slice(0, 25),
+    enforce_nonce: true,
+  }
+}
+
+async function postSessionSleepWake({
+  rest,
+  sleep,
+  threadId,
+}: {
+  rest: REST
+  sleep: SessionSleep
+  threadId: string
+}): Promise<SleepWakeFailure | null> {
+  // `.then(() => null)` keeps the success type concrete. Returning the raw post
+  // value would widen the union to `unknown` and erase the failure shape.
+  return await rest
+    .post(Routes.channelMessages(threadId), {
+      body: buildSessionSleepWakeBody({
+        deliveryId: sleep.delivery_id,
+        wakeAt: sleep.wake_at,
+        reason: sleep.reason,
+      }),
+    })
+    .then((): SleepWakeFailure | null => {
+      return null
+    })
+    .catch((error): SleepWakeFailure => {
+      // Only an unknown channel/message is genuinely unrecoverable. A 403 is
+      // often temporary (permissions revoked, thread locked) so it keeps
+      // retrying until the attempt budget runs out.
+      const permanent =
+        error instanceof DiscordAPIError &&
+        error.status === 404
+      return {
+        error: new Error(
+          `Failed to post sleep wake for session ${sleep.session_id}`,
+          { cause: error },
+        ),
+        permanent,
+      }
+    })
+}
+
+export async function wakeDueSessionSleeps({
+  rest,
+  now = new Date(),
+  limit = 20,
+}: {
+  rest: REST
+  now?: Date
+  limit?: number
+}): Promise<void> {
+  const dueSleeps = await getDueSessionSleeps({
+    now,
+    retryAfterMs: SLEEP_WAKE_RETRY_AFTER_MS,
+    limit,
+  })
+  for (const sleep of dueSleeps) {
+    // Reserves an attempt but stays `planned`. The row only leaves `planned`
+    // when ingress consumes the wake, so dying anywhere below costs one retry
+    // delay instead of losing the wake.
+    const claimed = await claimSessionSleepAttempt({
+      sessionId: sleep.session_id,
+      deliveryId: sleep.delivery_id,
+      now,
+      retryAfterMs: SLEEP_WAKE_RETRY_AFTER_MS,
+    })
+    if (!claimed) continue
+
+    // Resolved now, not when the tool ran, so a session rebound by /resume
+    // wakes in the thread that currently owns it.
+    const threadId = await getThreadIdBySessionId(claimed.session_id)
+    if (!threadId) {
+      await markSessionSleepFailed({
+        sessionId: claimed.session_id,
+        deliveryId: claimed.delivery_id,
+      })
+      taskLogger.warn(
+        `[task-runner] no thread owns session ${claimed.session_id}, dropping sleep wake`,
+      )
+      continue
+    }
+
+    // A successful post changes nothing here on purpose: ingress owns the
+    // transition out of `planned` when the wake actually becomes a turn.
+    const postResult = await postSessionSleepWake({ rest, sleep: claimed, threadId })
+    if (!postResult) continue
+
+    const exhausted = claimed.attempts >= SLEEP_WAKE_MAX_ATTEMPTS
+    if (postResult.permanent || exhausted) {
+      await markSessionSleepFailed({
+        sessionId: claimed.session_id,
+        deliveryId: claimed.delivery_id,
+      })
+    }
+    taskLogger.error(`[task-runner] ${formatErrorWithStack(postResult.error)}`)
+    void notifyError(postResult.error, 'Session sleep wake failed')
+  }
+}
+
 async function executeChannelScheduledTask({
   rest,
   task,
@@ -564,6 +696,8 @@ async function runTaskRunnerTick({
     await previous
     await processDueTask({ rest, task })
   }, Promise.resolve())
+
+  await wakeDueSessionSleeps({ rest })
 }
 
 export function startTaskRunner({

package/src/task-schedule.test.ts

@@ -18,6 +18,7 @@ import {
   appendTaskCommandOutput,
   parseScheduledTaskPayload,
   parseSendAtValue,
+  parseSleepWakeAt,
 } from './task-schedule.js'
 
 describe('parseSendAtValue', () => {
@@ -100,6 +101,81 @@ describe('parseSendAtValue', () => {
   })
 })
 
+describe('parseSleepWakeAt', () => {
+  const now = new Date('2026-08-19T12:00:00Z')
+
+  test('adds 2h to now', () => {
+    const result = parseSleepWakeAt({ duration: '2h', now })
+    expect(result).not.toBeInstanceOf(Error)
+    if (result instanceof Error) throw result
+    expect(result.toISOString()).toBe('2026-08-19T14:00:00.000Z')
+  })
+
+  test('adds 30s and 1d', () => {
+    const thirtySeconds = parseSleepWakeAt({ duration: '30s', now })
+    expect(thirtySeconds).not.toBeInstanceOf(Error)
+    if (thirtySeconds instanceof Error) throw thirtySeconds
+    expect(thirtySeconds.toISOString()).toBe('2026-08-19T12:00:30.000Z')
+
+    const oneDay = parseSleepWakeAt({ duration: '1d', now })
+    expect(oneDay).not.toBeInstanceOf(Error)
+    if (oneDay instanceof Error) throw oneDay
+    expect(oneDay.toISOString()).toBe('2026-08-20T12:00:00.000Z')
+  })
+
+  test('accepts until UTC ISO date ending with Z', () => {
+    const result = parseSleepWakeAt({
+      until: '2026-08-20T09:00:00Z',
+      now,
+    })
+    expect(result).not.toBeInstanceOf(Error)
+    if (result instanceof Error) throw result
+    expect(result.toISOString()).toBe('2026-08-20T09:00:00.000Z')
+  })
+
+  test('rejects past until', () => {
+    const result = parseSleepWakeAt({
+      until: '2026-08-19T11:59:59Z',
+      now,
+    })
+    expect(result).toBeInstanceOf(Error)
+    if (result instanceof Error) {
+      expect(result.message).toContain('until must be in the future (UTC)')
+    }
+  })
+
+  test('rejects both duration and until', () => {
+    const result = parseSleepWakeAt({
+      duration: '1h',
+      until: '2026-08-20T09:00:00Z',
+      now,
+    })
+    expect(result).toBeInstanceOf(Error)
+    if (result instanceof Error) {
+      expect(result.message).toContain('either duration or until')
+    }
+  })
+
+  test('rejects neither duration nor until', () => {
+    const result = parseSleepWakeAt({ now })
+    expect(result).toBeInstanceOf(Error)
+    if (result instanceof Error) {
+      expect(result.message).toContain('duration or until')
+    }
+  })
+
+  test('rejects until with a non-UTC offset', () => {
+    const result = parseSleepWakeAt({
+      until: '2026-08-20T09:00:00+01:00',
+      now,
+    })
+    expect(result).toBeInstanceOf(Error)
+    if (result instanceof Error) {
+      expect(result.message).toContain('UTC ISO format ending with Z')
+    }
+  })
+})
+
 describe('scheduled task execution options', () => {
   const tempDirectories: string[] = []