kimaki 0.20.1 → 0.22.0

package/dist/queue-delete-message.e2e.test.js

@@ -0,0 +1,75 @@
+// E2e tests for deleting queued Discord messages.
+// Covers the MessageDelete path that removes pending local queue items before drain.
+import { describe, test, expect } from 'vitest';
+import { setupQueueAdvancedSuite, TEST_USER_ID, } from './queue-advanced-e2e-setup.js';
+import { waitForBotMessageContaining, waitForFooterMessage, waitForThreadState, } from './test-utils.js';
+const TEXT_CHANNEL_ID = '200000000000001071';
+const e2eTest = describe;
+e2eTest('queue delete message', () => {
+    const ctx = setupQueueAdvancedSuite({
+        channelId: TEXT_CHANNEL_ID,
+        channelName: 'queue-delete-message-e2e',
+        dirName: 'queue-delete-message-e2e',
+        username: 'queue-delete-tester',
+    });
+    test('deleting a queued Discord message removes it from queue', async () => {
+        await ctx.discord.channel(TEXT_CHANNEL_ID).user(TEST_USER_ID).sendMessage({
+            content: 'SLOW_BUSY_MARKER Reply with exactly: delete-queue-setup',
+        });
+        const thread = await ctx.discord.channel(TEXT_CHANNEL_ID).waitForThread({
+            timeout: 4_000,
+            predicate: (t) => {
+                return t.name === 'SLOW_BUSY_MARKER Reply with exactly: delete-queue-setup';
+            },
+        });
+        const th = ctx.discord.thread(thread.id);
+        await th.waitForBotReply({ timeout: 4_000 });
+        const queuedMsg = await th.user(TEST_USER_ID).sendMessage({
+            content: 'Reply with exactly: deleted-queue. queue',
+        });
+        await waitForThreadState({
+            threadId: thread.id,
+            predicate: (state) => {
+                return state.queueItems.some((item) => {
+                    return item.sourceMessageId === queuedMsg.id;
+                });
+            },
+            timeout: 4_000,
+            description: 'queue has item to delete',
+        });
+        await th.user(TEST_USER_ID).deleteMessage({ messageId: queuedMsg.id });
+        await waitForThreadState({
+            threadId: thread.id,
+            predicate: (state) => {
+                return !state.queueItems.some((item) => {
+                    return item.sourceMessageId === queuedMsg.id;
+                });
+            },
+            timeout: 4_000,
+            description: 'queued item removed after Discord delete',
+        });
+        await waitForBotMessageContaining({
+            discord: ctx.discord,
+            threadId: thread.id,
+            text: 'removed message from queue',
+            timeout: 4_000,
+        });
+        await waitForFooterMessage({
+            discord: ctx.discord,
+            threadId: thread.id,
+            timeout: 8_000,
+        });
+        expect(await th.text()).toMatchInlineSnapshot(`
+        "--- from: user (queue-delete-tester)
+        SLOW_BUSY_MARKER Reply with exactly: delete-queue-setup
+        --- from: assistant (TestBot)
+        *using deterministic-provider/deterministic-v2*
+        Queued at position 1. Edit or delete your message to update the queue
+        ⬦ **queue-delete-tester** removed message from queue
+        ⬥ slow-busy-reply
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+      `);
+        const finalText = await th.text();
+        expect(finalText).not.toContain('» **queue-delete-tester:** Reply with exactly: deleted-queue');
+    }, 12_000);
+});

package/dist/schema.js

@@ -23,6 +23,9 @@ export const thread_sessions = sqliteCore.sqliteTable('thread_sessions', {
     session_id: sqliteCore.text('session_id').notNull(),
     source: sqliteCore.text('source', { enum: ['kimaki', 'external_poll'] }).notNull().default('kimaki'),
     last_synced_name: sqliteCore.text('last_synced_name'),
+    // Parent OpenCode session that spawned this thread via kimaki send --parent-session.
+    // Survives bot restarts so child multi-turn system prompts keep the parent ID.
+    parent_session_id: sqliteCore.text('parent_session_id'),
     created_at: datetime('created_at').default(orm.sql `CURRENT_TIMESTAMP`),
 });
 export const session_events = sqliteCore.sqliteTable('session_events', {

package/dist/session-handler/thread-runtime-state.js

@@ -17,6 +17,7 @@ export function initialThreadState() {
         sessionId: undefined,
         sessionUsername: undefined,
         sessionUserId: undefined,
+        parentSessionId: undefined,
         queueItems: [],
         sentPartIds: new Set(),
     };
@@ -77,6 +78,14 @@ export function setSessionUserId(threadId, userId) {
         return { ...t, sessionUserId: userId };
     });
 }
+export function setParentSessionId(threadId, parentSessionId) {
+    updateThread(threadId, (t) => {
+        if (t.parentSessionId) {
+            return t;
+        }
+        return { ...t, parentSessionId };
+    });
+}
 export function enqueueItem(threadId, item) {
     updateThread(threadId, (t) => ({
         ...t,

package/dist/session-handler/thread-session-runtime.js

@@ -17,7 +17,7 @@ import { registerEventListener, unregisterEventListener, } from './global-event-
 import { createLogger, LogPrefix } from '../logger.js';
 import { sendThreadMessage, SILENT_MESSAGE_FLAGS, NOTIFY_MESSAGE_FLAGS, } from '../discord-utils.js';
 import { formatPart } from '../message-formatting.js';
-import { getChannelVerbosity, getPartMessageIds, getDb, setPartMessage, getThreadSession, setThreadSession, getThreadWorktreeOrWorkspace, setSessionAgent, clearSessionModel, getVariantCascade, setSessionStartSource, appendSessionEventsSinceLastTimestamp, getSessionEventSnapshot, } from '../database.js';
+import { getChannelVerbosity, getPartMessageIds, getDb, setPartMessage, getThreadSession, setThreadSession, getThreadParentSessionId, setThreadParentSessionId, getThreadWorktreeOrWorkspace, setSessionAgent, clearSessionModel, getVariantCascade, setSessionStartSource, appendSessionEventsSinceLastTimestamp, getSessionEventSnapshot, } from '../database.js';
 import * as orm from 'drizzle-orm';
 import * as schema from '../schema.js';
 import { showPermissionButtons, addPermissionRequestToContext, arePatternsCoveredBy, pendingPermissionContexts, } from '../commands/permissions.js';
@@ -2274,6 +2274,7 @@ export class ThreadSessionRuntime {
                     agents: availableAgents,
                     username: this.state?.sessionUsername || input.username,
                     userId: this.state?.sessionUserId || input.userId,
+                    parentSessionId: this.state?.parentSessionId || input.parentSessionId,
                 }),
                 ...(resolvedAgent ? { agent: resolvedAgent } : {}),
                 ...(modelField ? { model: modelField } : {}),
@@ -2321,6 +2322,7 @@ export class ThreadSessionRuntime {
             permissions: input.permissions,
             permissionRules: input.permissionRules,
             injectionGuardPatterns: input.injectionGuardPatterns,
+            parentSessionId: input.parentSessionId,
             sourceMessageId: input.sourceMessageId,
             sourceThreadId: input.sourceThreadId,
             repliedMessage: input.repliedMessage,
@@ -2363,6 +2365,9 @@ export class ThreadSessionRuntime {
     async enqueueIncoming(input) {
         threadState.setSessionUsername(this.threadId, input.username);
         threadState.setSessionUserId(this.threadId, input.userId);
+        await this.ensureParentSessionId({
+            parentSessionId: input.parentSessionId,
+        });
         // When a preprocessor is provided, we must resolve it inside
         // dispatchAction before we know the final mode for routing.
         if (input.preprocess) {
@@ -2383,6 +2388,33 @@ export class ThreadSessionRuntime {
         }
         return this.submitViaOpencodeQueue(input);
     }
+    /**
+     * Resolve parent session ID for child system prompts.
+     * Prefer in-memory state, then SQLite, then the ingress marker.
+     * Persist once so multi-turn child sessions keep the parent after restart.
+     */
+    async ensureParentSessionId({ parentSessionId, }) {
+        if (this.state?.parentSessionId) {
+            return;
+        }
+        const storedParentSessionId = await getThreadParentSessionId(this.threadId);
+        if (storedParentSessionId) {
+            threadState.setParentSessionId(this.threadId, storedParentSessionId);
+            return;
+        }
+        if (!parentSessionId) {
+            return;
+        }
+        threadState.setParentSessionId(this.threadId, parentSessionId);
+        // Row may not exist yet on first ingress before ensureSession creates it.
+        // Best-effort write; ensureSession path also persists after setThreadSession.
+        await setThreadParentSessionId({
+            threadId: this.threadId,
+            parentSessionId,
+        }).catch((error) => {
+            logger.warn(`[PARENT SESSION] Failed to persist parent session for thread ${this.threadId}: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
     /**
      * Serialize the preprocess callback via a lightweight promise chain, then
      * route the resolved input through the normal enqueue paths.
@@ -2586,6 +2618,10 @@ export class ThreadSessionRuntime {
             return { found: true, removed: true };
         return { found: true, removed: false };
     }
+    /** Remove a queued message identified by its Discord source message ID. */
+    removeQueuedMessage(sourceMessageId) {
+        return threadState.updateQueueItemBySourceMessageId(this.threadId, sourceMessageId, () => null);
+    }
     // ── Queue Drain ─────────────────────────────────────────────
     /**
      * Check if we can dispatch the next queued message. If so, dequeue and
@@ -2964,6 +3000,7 @@ export class ThreadSessionRuntime {
                 agents: earlyAvailableAgents,
                 username: this.state?.sessionUsername || input.username,
                 userId: this.state?.sessionUserId || input.userId,
+                parentSessionId: this.state?.parentSessionId || input.parentSessionId,
             }),
             model: earlyModelParam,
             agent: earlyAgentPreference,
@@ -3103,6 +3140,17 @@ export class ThreadSessionRuntime {
         // Store session in DB and thread state
         await setThreadSession(this.thread.id, session.id);
         threadState.setSessionId(this.threadId, session.id);
+        // Parent may have been set on ingress before the thread_sessions row
+        // existed; write it now that the row is guaranteed.
+        const parentSessionId = this.state?.parentSessionId;
+        if (parentSessionId) {
+            await setThreadParentSessionId({
+                threadId: this.thread.id,
+                parentSessionId,
+            }).catch((error) => {
+                logger.warn(`[PARENT SESSION] Failed to persist parent session for thread ${this.threadId}: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
         await this.hydrateSessionEventsFromDatabase({ sessionId: session.id });
         // Store session start source for scheduled tasks
         if (createdNewSession && sessionStartScheduleKind) {

package/dist/system-message.js

@@ -78,45 +78,6 @@ No code is stored permanently, diffs are ephemeral. The tool and website are ful
 If the user asks about critique or expresses concern about their code being uploaded,
 reassure them: their data is safe, URLs are unique and not indexed, and they can disable
 this feature by restarting kimaki with the \`--no-critique\` flag.
-
-### reviewing diffs with AI
-
-\`bunx critique review --web\` generates an AI-powered review of a diff and uploads it as a shareable URL.
-It spawns a separate opencode session that analyzes the diff, groups related changes, and produces
-a structured review with explanations, diagrams, and suggestions. This is useful when the user
-asks you to explain or review a diff — the output is much richer than a plain diff URL.
-
-**WARNING: This command is very slow (up to 20 minutes for large diffs).** Only run it when the
-user explicitly asks for a code review or diff explanation. Always warn the user it will take
-a while before running it. Set Bash tool timeout to at least 25 minutes (\`timeout: 1_500_000\`).
-
-Always pass \`--agent opencode\` and \`--session ${sessionId}\` so the reviewer has context about
-why the changes were made. If you know other session IDs that produced the diff (e.g. from
-\`kimaki session list\` or from the thread history), pass them too with additional \`--session\` flags.
-
-Examples:
-
-\`\`\`bash
-# Review working tree changes
-bunx critique review --web --agent opencode --session ${sessionId}
-
-# Review staged changes
-bunx critique review --staged --web --agent opencode --session ${sessionId}
-
-# Review a specific commit
-bunx critique review --commit HEAD --web --agent opencode --session ${sessionId}
-
-# Review branch changes compared to main
-bunx critique review main...HEAD --web --agent opencode --session ${sessionId}
-
-# Review with multiple session contexts (current + the session that made the changes)
-bunx critique review --commit abc1234 --web --agent opencode --session ${sessionId} --session ses_other_session_id
-
-# Review only specific files
-bunx critique review --web --agent opencode --session ${sessionId} --filter "src/**/*.ts"
-\`\`\`
-
-The command prints a preview URL when done — share that URL with the user.
 `;
 }
 const KIMAKI_TUNNEL_INSTRUCTIONS = `
@@ -262,8 +223,12 @@ ${escapePromptText(repliedMessage.text)}
     // model concatenates message parts.
     return `${sections.join('\n\n')}\n`;
 }
-export function getOpencodeSystemMessage({ sessionId, channelId, guildId, threadId, channelTopic, agents, userId, }) {
+export function getOpencodeSystemMessage({ sessionId, channelId, guildId, threadId, channelTopic, agents, userId, parentSessionId, }) {
     const userArg = ` --user '${userId || '<discord-user-id>'}'`;
+    const parentSessionArg = ` --parent-session ${sessionId}`;
+    // Prefer thread ID for cross-machine compatibility; fall back to session ID.
+    const archiveTarget = threadId ? `${threadId} (or --session ${sessionId})` : `--session ${sessionId}`;
+    const sendToSelfTarget = threadId ? `--thread ${threadId} (or --session ${sessionId})` : `--session ${sessionId}`;
     const topicContext = channelTopic?.trim()
         ? `\n\n<channel-topic>\n${channelTopic.trim()}\n</channel-topic>`
         : '';
@@ -274,6 +239,11 @@ export function getOpencodeSystemMessage({ sessionId, channelId, guildId, thread
         })
             .join('\n')}`
         : '';
+    // Opt-in only. Empty by default so /btw, task subagents, and normal sessions
+    // keep the same system prompt prefix as their parent for cache hits.
+    const parentSessionContext = parentSessionId
+        ? `\nYour parent OpenCode session ID is: ${parentSessionId}\nYou can send a message back to the parent session with:\nkimaki send --session ${parentSessionId} --prompt 'your update here' --agent <current_agent>\nDo NOT message the parent session unless the user explicitly asks you to.`
+        : '';
     return `
 The user is reading your messages from inside Discord, via kimaki.dev
 
@@ -296,7 +266,7 @@ interface BashToolInput {
 \`description\` is shown to the user in Discord as a summary of the bash call.
 \`hasSideEffect\` distinguishes essential bash calls from read-only ones in low-verbosity mode.
 
-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}` : ''}
+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.
 
@@ -353,7 +323,7 @@ To ask the user to upload files from their device, use the \`kimaki_file_upload\
 
 To archive the current Discord thread (hide it from sidebar) and stop the session, run:
 
-kimaki session archive --session ${sessionId}
+kimaki session archive ${archiveTarget}
 
 Only do this when the user explicitly asks to close or archive the thread, and only after your final message.
 
@@ -382,9 +352,10 @@ ${channelId
 
 To start a new thread/session in this channel pro-grammatically, run:
 
-kimaki send --channel ${channelId} --prompt 'your prompt here' --agent <current_agent>${userArg}
+kimaki send --channel ${channelId} --prompt 'your prompt here' --agent <current_agent>${parentSessionArg}${userArg}
 
 You can use this to "spawn" parallel helper sessions like teammates: start new threads with focused prompts, then come back and collect the results.
+ALWAYS pass \`--parent-session ${sessionId}\` (your current session ID) when starting a new session from this one. The child system message will include the parent session ID so it can message back only if the user asks.
 Prefer passing the current agent with \`--agent <current_agent>\` so spawned or scheduled sessions keep the same agent unless you are intentionally switching. Replace \`<current_agent>\` with the value from the per-turn \`Current agent\` reminder.
 When writing \`kimaki send\` shell commands, use single quotes around \`--prompt\`, \`--user\`, \`--send-at\`, and other literal arguments so backticks inside prompts are not interpreted by the shell. Prefer \`--user '<discord-user-id>'\` over \`--user 'name'\` because name lookup depends on optional Server Members Intent.
 
@@ -398,13 +369,13 @@ To send a prompt to an existing thread instead of creating a new one:
 
 kimaki send --thread <thread_id> --prompt 'follow-up prompt' --agent <current_agent>
 
-Use this when you already have the Discord thread ID.
+Use this when you already have the Discord thread ID. Prefer \`--thread\` over \`--session\` because thread IDs work across machines while session IDs only resolve on the machine that created the session.
 
-To send to the thread associated with a known session:
+To send to the thread associated with a known session (same machine only):
 
 kimaki send --session <session_id> --prompt 'follow-up prompt' --agent <current_agent>
 
-Use this when you have the OpenCode session ID.
+Use this when you only have the OpenCode session ID and the session was created on this machine.
 
 Use --notify-only to create a notification thread without starting an AI session:
 
@@ -412,26 +383,32 @@ kimaki send --channel ${channelId} --prompt 'User cancelled subscription' --noti
 
 Use --user with a Discord user ID or raw mention to add a specific Discord user to the new thread:
 
-kimaki send --channel ${channelId} --prompt 'Review the latest CI failure' --agent <current_agent>${userArg}
+kimaki send --channel ${channelId} --prompt 'Review the latest CI failure' --agent <current_agent>${parentSessionArg}${userArg}
 
 Use --worktree to create a git worktree for the session (ONLY when the user explicitly asks for a worktree):
 
-kimaki send --channel ${channelId} --prompt 'Add dark mode support' --worktree dark-mode --agent <current_agent>${userArg}
+kimaki send --channel ${channelId} --prompt 'Add dark mode support' --worktree dark-mode --agent <current_agent>${parentSessionArg}${userArg}
 
 Use --cwd to start a session in an existing project subfolder or git worktree directory:
 
-kimaki send --channel ${channelId} --prompt 'Run the restricted task' --cwd /path/to/project/restricted-task --agent <current_agent>${userArg}
+kimaki send --channel ${channelId} --prompt 'Run the restricted task' --cwd /path/to/project/restricted-task --agent <current_agent>${parentSessionArg}${userArg}
 
 Important:
+- ALWAYS pass \`--parent-session ${sessionId}\` when spawning a new session from this one so the child knows who started it.
 - NEVER use \`--worktree\` unless the user explicitly requests a worktree. Most tasks should use normal threads without worktrees.
 - Use \`--cwd\` to reuse an existing project subfolder or worktree directory. Use \`--worktree\` to create a new worktree.
 - The prompt passed to \`--worktree\` is the task for the new thread running inside that worktree.
 - Do NOT tell that prompt to "create a new worktree" again, or it can create recursive worktree threads.
 - Ask the new session to operate on its current checkout only (e.g. "validate current worktree", "run checks in this repo").
 
+Use --file to attach local files (images, text files, PDFs) to the message:
+
+kimaki send --channel ${channelId} --prompt 'Review this screenshot' --file /path/to/screenshot.png --agent <current_agent>${parentSessionArg}${userArg}
+kimaki send --thread <thread_id> --prompt 'Here is the error log' --file ./error.log --file ./stack-trace.txt --agent <current_agent>
+
 Use --agent to specify which agent to use for the session:
 
-kimaki send --channel ${channelId} --prompt 'Plan the refactor of the auth module' --agent plan${userArg}
+kimaki send --channel ${channelId} --prompt 'Plan the refactor of the auth module' --agent plan${parentSessionArg}${userArg}
 ${availableAgentsContext}
 
 ## running opencode commands via kimaki send
@@ -439,7 +416,7 @@ ${availableAgentsContext}
 You can trigger registered opencode commands (slash commands, skills, MCP prompts) by starting the \`--prompt\` with \`/commandname\`:
 
 kimaki send --thread <thread_id> --prompt '/review fix the auth module' --agent <current_agent>
-kimaki send --channel ${channelId} --prompt '/build-cmd update dependencies' --agent <current_agent>${userArg}
+kimaki send --channel ${channelId} --prompt '/build-cmd update dependencies' --agent <current_agent>${parentSessionArg}${userArg}
 
 The command name must match a registered opencode command. If the command is not recognized, the prompt is sent as plain text to the model. This works for both new threads (\`--channel\`) and existing threads (\`--thread\`/\`--session\`).
 
@@ -455,8 +432,8 @@ kimaki send --thread <thread_id> --prompt '/<agentname>-agent' --agent <current_
 
 Use \`--send-at\` to schedule a one-time or recurring task:
 
-kimaki send --channel ${channelId} --prompt 'Reminder: review open PRs' --send-at '2026-03-01T09:00:00Z' --agent <current_agent>${userArg}
-kimaki send --channel ${channelId} --prompt 'Run weekly test suite and summarize failures' --send-at '0 9 * * 1' --agent <current_agent>${userArg}
+kimaki send --channel ${channelId} --prompt 'Reminder: review open PRs' --send-at '2026-03-01T09:00:00Z' --agent <current_agent>${parentSessionArg}${userArg}
+kimaki send --channel ${channelId} --prompt 'Run weekly test suite and summarize failures' --send-at '0 9 * * 1' --agent <current_agent>${parentSessionArg}${userArg}
 
 ALL scheduling is in UTC. Dates must be UTC ISO format ending with \`Z\`. Cron expressions also fire in UTC (e.g. \`0 9 * * 1\` means 9:00 UTC every Monday).
 When the user specifies a time without a timezone, ask them to confirm their timezone or the UTC equivalent. Never guess the user's timezone.
@@ -465,6 +442,7 @@ When the user specifies a time without a timezone, ask them to confirm their tim
 - \`--notify-only\` to create a reminder thread without auto-starting a session
 - \`--worktree\` to create the scheduled thread as a worktree session (only if the user explicitly asks for a worktree)
 - \`--agent\` and \`--model\` to control scheduled session behavior
+- \`--parent-session\` to pass this session as parent of the scheduled child
 - \`--user\` to add a specific user to the scheduled thread
 
 \`--wait\` is incompatible with \`--send-at\` because scheduled tasks run in the future.
@@ -480,7 +458,7 @@ Notification strategy for scheduled tasks:
 - 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 --session ${sessionId}\`
+- Example no-op cleanup command: \`kimaki session archive ${archiveTarget}\`
 
 Manage scheduled tasks with:
 
@@ -496,10 +474,10 @@ Use case patterns:
 - 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 --session ${sessionId}\`. Example: a scheduled email triage run that finds no new emails should archive itself so it does not add noise to Discord.
+- 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 ${archiveTarget}\`. 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:
 
-kimaki send --session ${sessionId} --prompt 'Reminder: <@USER_ID> you asked to be reminded about this thread.' --send-at '<future_UTC_time>' --notify-only --agent <current_agent>
+kimaki send ${sendToSelfTarget} --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.
 
@@ -514,7 +492,7 @@ ONLY create worktrees when the user explicitly asks for one. Never proactively u
 When the user asks to "create a worktree" or "make a worktree", they mean you should use the kimaki CLI to create it. Do NOT use raw \`git worktree add\` commands. Instead use:
 
 \`\`\`bash
-kimaki send --channel ${channelId} --prompt 'your task description' --worktree worktree-name --agent <current_agent>${userArg}
+kimaki send --channel ${channelId} --prompt 'your task description' --worktree worktree-name --agent <current_agent>${parentSessionArg}${userArg}
 \`\`\`
 
 This creates a new Discord thread with an isolated git worktree and starts a session in it. The worktree name should be kebab-case and descriptive of the task.
@@ -530,7 +508,7 @@ Critical recursion guard:
 Use \`--cwd\` to start a session in an existing project subfolder or git worktree directory instead of the project root:
 
 \`\`\`bash
-kimaki send --channel ${channelId} --prompt 'Run restricted task X' --cwd /path/to/project/restricted-task --agent <current_agent>${userArg}
+kimaki send --channel ${channelId} --prompt 'Run restricted task X' --cwd /path/to/project/restricted-task --agent <current_agent>${parentSessionArg}${userArg}
 \`\`\`
 
 The path must be inside the project or be a git worktree of the project (validated via \`git worktree list\`). The session resolves to the correct project channel but uses that path as its working directory, so subfolder \`opencode.json\` config can apply. Passing the project root itself is allowed and behaves like the default. Use \`--worktree\` to create a new worktree, \`--cwd\` to reuse an existing directory.
@@ -544,7 +522,7 @@ This is useful for automation (cron jobs, GitHub webhooks, n8n, etc.)
 When you are approaching the **context window limit** or the user explicitly asks to **handoff to a new thread**, use the \`kimaki send\` command to start a fresh session with context:
 
 \`\`\`bash
-kimaki send --channel ${channelId} --prompt 'Continuing from previous session: <summary of current task and state>' --agent <current_agent>${userArg}
+kimaki send --channel ${channelId} --prompt 'Continuing from previous session: <summary of current task and state>' --agent <current_agent>${parentSessionArg}${userArg}
 \`\`\`
 
 The command automatically handles long prompts (over 2000 chars) by sending them as file attachments. With \`--notify-only\`, long prompts are split into multiple messages instead so the content is directly visible.
@@ -586,7 +564,7 @@ Then use grep/read tools on the file to find what you need.
 
 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.
 
-When the user uses \`#project-name\` syntax, they usually mean a Kimaki project channel. Use \`kimaki project list --json\` to resolve the \`channel_name\` to its repo working directory. Try the lookup yourself before acting, for example filter by \`channel_name\` with jq: \`kimaki project list --json | jq -r '.[] | select(.channel_name == "project-name") | .directory'\`.
+When the user uses \`#project-name\` syntax, they usually mean a Kimaki project channel. Use \`kimaki project list --json\` to resolve the \`channel_name\` to its repo working directory. The JSON output includes \`guild_id\` and \`guild_name\` to distinguish channels with the same name across different servers. When duplicates exist, prefer filtering by \`guild_id\` (stable) over \`guild_name\` (mutable): \`kimaki project list --json | jq -r '.[] | select(.channel_name == "project-name" and .guild_id == "123456") | .channel_id'\`.
 
 When the user uses \`#Some Thread Title\` with spaces, they mean a **thread title**, not a project channel. Find the session by searching across projects, then read the session markdown:
 
@@ -601,16 +579,25 @@ kimaki session read <sessionId> > ./tmp/session.md 2>/dev/null
 If you don't know which project the thread belongs to, try each project from \`kimaki project list --json\`.
 
 \`\`\`bash
-# List all registered projects with their channel IDs
+# List all registered projects with their channel IDs and guild names
 kimaki project list
-kimaki project list --json  # machine-readable output
-kimaki project list --json | jq -r '.[] | select(.channel_name == "project-name") | .directory'
+kimaki project list --json  # machine-readable output with guild_id, guild_name, is_local
+
+# Include projects from other machines (scans Kimaki category in Discord)
+kimaki project list --all
+kimaki project list --all --json  # remote projects have is_local: false and directory: null
+
+# Resolve by channel name (prefer adding guild_name filter if duplicates exist)
+kimaki project list --json | jq -r '.[] | select(.channel_name == "project-name") | .channel_id + " " + .guild_name + " " + .directory'
 
 # Create a new project in ~/.kimaki/projects/<name> (folder + git init + Discord channel)
 kimaki project create my-new-app
 
 # Add an existing directory as a project
 kimaki project add /path/to/repo
+
+# Remove a stale or duplicate channel mapping (local DB only, does not delete Discord channel)
+kimaki project remove <channel_id>
 \`\`\`
 
 To send a task to another project: