kimaki 0.21.0 → 0.22.0

package/dist/discord-bot.js

@@ -16,7 +16,7 @@ import { WORKTREE_PREFIX } from './commands/merge-worktree.js';
 import { escapeBackticksInCodeBlocks, splitMarkdownForDiscord, sendThreadMessage, SILENT_MESSAGE_FLAGS, NOTIFY_MESSAGE_FLAGS, reactToThread, stripMentions, hasKimakiBotPermission, hasNoKimakiRole, resolveGuildMessageMember, } from './discord-utils.js';
 import { getOpencodeSystemMessage, isInjectedPromptMarker, } from './system-message.js';
 import YAML from 'yaml';
-import { getTextAttachments, resolveMentions, } from './message-formatting.js';
+import { getFileAttachments, getTextAttachments, resolveMentions, } from './message-formatting.js';
 import { extractBtwSuffix } from './btw-prefix-detection.js';
 import { isVoiceAttachment } from './voice-attachment.js';
 import { forkSessionToBtwThread } from './commands/btw.js';
@@ -523,9 +523,14 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                     ? extractBtwSuffix(message.content || '')
                     : null;
                 if (btwResult?.forceBtw && projectDirectory && !isLeadingMentionToOtherUser) {
+                    const btwSdkDir = worktreeInfo?.status === 'ready' &&
+                        worktreeInfo.workspace_directory
+                        ? worktreeInfo.workspace_directory
+                        : projectDirectory;
                     const result = await forkSessionToBtwThread({
                         sourceThread: thread,
                         projectDirectory,
+                        sdkDirectory: btwSdkDir,
                         prompt: btwResult.prompt,
                         userId: message.author.id,
                         username: message.member?.displayName || message.author.displayName,
@@ -820,6 +825,11 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                 return;
             if (!message.content)
                 return;
+            // Discord fires MESSAGE_UPDATE for embed-only updates (link preview
+            // unfurling) without the user actually editing the message content.
+            // editedTimestamp is null for these; skip them to avoid false queue removals.
+            if (!message.editedTimestamp)
+                return;
             const channel = message.channel;
             const isThread = [
                 ChannelType.PublicThread,
@@ -917,7 +927,10 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                 return; // Not an auto-start thread
             }
             discordLogger.log(`[BOT_SESSION] Detected bot-initiated thread: ${thread.name}`);
-            const textAttachmentsContent = await getTextAttachments(starterMessage);
+            const [textAttachmentsContent, fileAttachments] = await Promise.all([
+                getTextAttachments(starterMessage),
+                getFileAttachments(starterMessage),
+            ]);
             const messageText = resolveMentions(starterMessage).trim();
             const prompt = textAttachmentsContent
                 ? `${messageText}\n\n${textAttachmentsContent}`
@@ -941,22 +954,31 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                 });
                 return;
             }
-            // Start worktree creation concurrently if requested.
+            // Start worktree creation concurrently if requested via marker OR
+            // if the channel/global toggle enables auto-worktrees.
             // The runtime is created immediately so follow-up messages queue
             // naturally; the worktree promise is awaited inside enqueueIncoming.
+            const autoWorktreeEnabled = !marker.worktree &&
+                !marker.cwd &&
+                (store.getState().useWorktrees ||
+                    (await getChannelWorktreesEnabled(parent.id)));
+            const effectiveWorktreeName = marker.worktree ||
+                (autoWorktreeEnabled
+                    ? formatAutoWorktreeName(thread.name.slice(0, 50))
+                    : undefined);
             let worktreePromise;
-            if (marker.worktree && (await isGitRepositoryRoot(projectDirectory))) {
-                discordLogger.log(`[BOT_SESSION] Creating worktree: ${marker.worktree}`);
+            if (effectiveWorktreeName && (await isGitRepositoryRoot(projectDirectory))) {
+                discordLogger.log(`[BOT_SESSION] Creating worktree: ${effectiveWorktreeName}`);
                 const worktreeStatusMessage = await thread
                     .send({
-                    content: worktreeCreatingMessage(marker.worktree),
+                    content: worktreeCreatingMessage(effectiveWorktreeName),
                     flags: SILENT_MESSAGE_FLAGS,
                 })
                     .catch(() => undefined);
                 worktreePromise = createWorktreeInBackground({
                     thread,
                     starterMessage: worktreeStatusMessage,
-                    worktreeName: marker.worktree,
+                    worktreeName: effectiveWorktreeName,
                     projectDirectory,
                     rest: discordClient.rest,
                 });
@@ -964,6 +986,9 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
             else if (marker.worktree) {
                 discordLogger.warn(`[BOT_SESSION] Skipping requested worktree for non-git project directory: ${projectDirectory}`);
             }
+            else if (autoWorktreeEnabled) {
+                discordLogger.warn(`[BOT_SESSION] Skipping auto-worktree for non-git project directory: ${projectDirectory}`);
+            }
             // --cwd: reuse an existing project subfolder or worktree directory. Revalidate at bot-time
             // (CLI validated at send-time but the path could become stale).
             // Only worktree directories are stored in thread_workspaces. Project
@@ -1054,7 +1079,12 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                     const permissionRules = await getChannelReferencePermissionRules({
                         message: starterMessage,
                     });
-                    return { prompt, permissionRules, mode: 'opencode' };
+                    return {
+                        prompt,
+                        permissionRules,
+                        mode: 'opencode',
+                        ...(fileAttachments.length > 0 && { images: fileAttachments }),
+                    };
                 },
             });
         }

package/dist/message-preprocessing.js

@@ -276,15 +276,22 @@ export async function preprocessNewSessionMessage({ message, thread, projectDire
         }
     }
     const qs = extractQueueSuffix(prompt);
+    const fileAttachments = await getFileAttachments(message);
+    const textAttachmentsContent = await getTextAttachments(message);
+    const finalPrompt = textAttachmentsContent
+        ? `${qs.prompt}\n\n${textAttachmentsContent}`
+        : qs.prompt;
     if (shouldSkipEmptyPrompt({
         message,
-        prompt: qs.prompt,
+        prompt: finalPrompt,
+        images: fileAttachments,
         hasVoiceAttachment,
     })) {
         return { prompt: '', mode: 'opencode', skip: true };
     }
     return {
-        prompt: qs.prompt,
+        prompt: finalPrompt,
+        images: fileAttachments.length > 0 ? fileAttachments : undefined,
         repliedMessage,
         permissionRules,
         mode: qs.forceQueue || voiceResult?.queueMessage ? 'local-queue' : 'opencode',

package/dist/system-message.js

@@ -226,6 +226,9 @@ ${escapePromptText(repliedMessage.text)}
 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>`
         : '';
@@ -320,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.
 
@@ -366,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:
 
@@ -398,6 +401,11 @@ Important:
 - 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${parentSessionArg}${userArg}
@@ -450,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:
 
@@ -466,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.
 
@@ -573,7 +581,11 @@ If you don't know which project the thread belongs to, try each project from \`k
 \`\`\`bash
 # List all registered projects with their channel IDs and guild names
 kimaki project list
-kimaki project list --json  # machine-readable output with guild_id, guild_name
+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'

package/dist/system-message.test.js

@@ -137,7 +137,7 @@ describe('system-message', () => {
 
       To archive the current Discord thread (hide it from sidebar) and stop the session, run:
 
-      kimaki session archive --session ses_123
+      kimaki session archive thread_123 (or --session ses_123)
 
       Only do this when the user explicitly asks to close or archive the thread, and only after your final message.
 
@@ -182,13 +182,13 @@ describe('system-message', () => {
 
       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:
 
@@ -214,6 +214,11 @@ describe('system-message', () => {
       - 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 chan_123 --prompt 'Review this screenshot' --file /path/to/screenshot.png --agent <current_agent> --parent-session ses_123 --user '<discord-user-id>'
+      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 chan_123 --prompt 'Plan the refactor of the auth module' --agent plan --parent-session ses_123 --user '<discord-user-id>'
@@ -270,7 +275,7 @@ describe('system-message', () => {
       - 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 ses_123\`
+      - Example no-op cleanup command: \`kimaki session archive thread_123 (or --session ses_123)\`
 
       Manage scheduled tasks with:
 
@@ -286,10 +291,10 @@ describe('system-message', () => {
       - 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 ses_123\`. 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 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:
 
-      kimaki send --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>
+      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.
 
@@ -393,7 +398,11 @@ describe('system-message', () => {
       \`\`\`bash
       # List all registered projects with their channel IDs and guild names
       kimaki project list
-      kimaki project list --json  # machine-readable output with guild_id, guild_name
+      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'

package/dist/worktree-lifecycle.e2e.test.js

@@ -9,7 +9,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import url from 'node:url';
 import { describe, beforeAll, afterAll, test, expect } from 'vitest';
-import { ChannelType, Client, GatewayIntentBits, Partials } from 'discord.js';
+import { ChannelType, Client, GatewayIntentBits, Partials, Routes } from 'discord.js';
+import YAML from 'yaml';
 import { DigitalDiscord } from 'discord-digital-twin/src';
 import { buildDeterministicOpencodeConfig, } from 'opencode-deterministic-provider';
 import { setDataDir } from './config.js';
@@ -35,6 +36,7 @@ function normalizeWorktreeLifecycleText(text) {
         .replaceAll(CHANNEL_WORKTREE_NAME, 'CHANNEL_WORKTREE_NAME')
         .replaceAll(AUTO_WORKTREE_SUFFIX, 'AUTO_WORKTREE_NAME')
         .replaceAll(WORKTREE_NAME, 'WORKTREE_NAME')
+        .replaceAll(WORKTREE_SUFFIX, 'SUFFIX')
         .replace(/ses_[a-zA-Z0-9]+/g, 'ses_TEST')
         .replace(/<#\d+>/g, '<#THREAD_ID>')
         .replace(/`[^`\n]*\/worktrees\/[^`\n]*`/g, '`/tmp/worktrees/WORKTREE_NAME`');
@@ -630,4 +632,71 @@ describe('worktree lifecycle', () => {
         const okCount = (text.match(/⬥ ok/g) || []).length;
         expect(okCount).toBe(2);
     }, 20_000);
+    test('kimaki send --channel auto-creates worktree when channel toggle is enabled', async () => {
+        // Simulate `kimaki send --channel AUTO_WORKTREE_CHANNEL_ID --prompt '...'`
+        // WITHOUT --worktree flag. The bot-side ThreadCreate handler should detect
+        // the channel toggle and auto-create a worktree.
+        const prompt = `Reply with exactly: send-auto-wt-${WORKTREE_SUFFIX}`;
+        const embedMarker = {
+            start: true,
+            username: 'worktree-tester',
+            userId: TEST_USER_ID,
+        };
+        // Post starter message (what `kimaki send` does)
+        const starterMessage = await discord
+            .channel(AUTO_WORKTREE_CHANNEL_ID)
+            .bot()
+            .sendMessage({
+            content: `» **kimaki-cli:**\n${prompt}`,
+            embeds: [
+                { color: 0x2b2d31, footer: { text: YAML.stringify(embedMarker) } },
+            ],
+        });
+        // Create thread on that message (what `kimaki send` does via REST)
+        const threadData = (await botClient.rest.post(Routes.threads(AUTO_WORKTREE_CHANNEL_ID, starterMessage.id), {
+            body: {
+                name: prompt.slice(0, 80),
+                auto_archive_duration: 1440,
+            },
+        }));
+        // Wait for worktree creation status message (Branch:)
+        await waitForBotMessageContaining({
+            discord,
+            threadId: threadData.id,
+            userId: TEST_USER_ID,
+            text: 'Branch:',
+            timeout: 25_000,
+        });
+        // Wait for the bot reply to the prompt. The starter message is from
+        // the bot (kimaki-cli), not a user, so just wait for the text to appear.
+        await waitForBotMessageContaining({
+            discord,
+            threadId: threadData.id,
+            userId: discord.botUserId,
+            text: '⬥ ok',
+            timeout: 10_000,
+        });
+        // Snapshot the thread content
+        const th = discord.thread(threadData.id);
+        expect(normalizeWorktreeLifecycleText(await th.text())).toMatchInlineSnapshot(`
+        "--- from: assistant (TestBot)
+        » **kimaki-cli:**
+        Reply with exactly: send-auto-wt-SUFFIX
+        [embed]
+        🌳 **Worktree: opencode/kimaki-rply-wth-exctly-snd-at-wt-l8kct**
+        📁 \`/tmp/worktrees/WORKTREE_NAME\`
+        🌿 Branch: \`opencode/kimaki-rply-wth-exctly-snd-at-wt-l8kct\`
+        *using deterministic-provider/deterministic-v2*
+        ⬥ ok"
+      `);
+        // Verify DB has worktree info
+        const worktreeInfo = await getThreadWorktreeOrWorkspace(threadData.id);
+        expect(worktreeInfo?.status).toBe('ready');
+        expect(worktreeInfo?.workspace_directory).toBeTruthy();
+        // Verify runtime is in the worktree directory
+        const runtime = getRuntime(threadData.id);
+        expect(runtime).toBeDefined();
+        expect(runtime.sdkDirectory).toContain(`${path.sep}worktrees${path.sep}`);
+        expect(runtime.sdkDirectory).not.toBe(directories.projectDirectory);
+    }, 35_000);
 });

package/dist/worktrees.js

@@ -713,6 +713,69 @@ export async function mergeWorktree({ worktreeDir, mainRepoDir, worktreeName, ta
         shortSha: shortSha instanceof Error ? 'unknown' : shortSha,
     };
 }
+/**
+ * Resolve the best git ref for a base branch by checking remote tracking refs.
+ * Prefers upstream/<branch> over origin/<branch> over local <branch>.
+ * Fetches the remote first so tracking refs are up to date.
+ *
+ * If the remote is strictly ahead of local, returns the remote ref.
+ * If local and remote have diverged (local is both ahead and behind),
+ * returns the local branch to avoid needing a merge/rebase.
+ * If the branch is already an explicit remote ref (e.g. `origin/main`), skips resolution.
+ * Uses `git remote` to distinguish real remote prefixes from local branches
+ * containing `/` like `feature/foo`.
+ */
+export async function resolveBestBaseRef({ directory, branch, }) {
+    // Check if branch is already an explicit remote ref like "origin/main".
+    // Local branches can contain `/` (e.g. "feature/foo"), so we check
+    // against actual remote names instead of a naive slash check.
+    if (branch.includes('/')) {
+        const remotes = await git(directory, 'remote');
+        if (!(remotes instanceof Error)) {
+            const prefix = branch.slice(0, branch.indexOf('/'));
+            if (remotes.split('\n').some((r) => r.trim() === prefix)) {
+                return branch;
+            }
+        }
+    }
+    for (const remote of ['upstream', 'origin']) {
+        // Best-effort fetch with short timeout
+        const fetchResult = await git(directory, `fetch ${remote} ${branch}`, {
+            timeout: 15_000,
+        });
+        if (fetchResult instanceof Error)
+            continue;
+        const remoteRef = `${remote}/${branch}`;
+        const refExists = await git(directory, `rev-parse --verify refs/remotes/${remoteRef}`);
+        if (refExists instanceof Error)
+            continue;
+        // Check if local branch exists
+        const localExists = await git(directory, `rev-parse --verify refs/heads/${branch}`);
+        if (localExists instanceof Error) {
+            // No local branch but remote exists — use remote
+            return remoteRef;
+        }
+        // Count commits: remote ahead of local, and local ahead of remote
+        const [remoteAhead, localAhead] = await Promise.all([
+            git(directory, `rev-list --count refs/heads/${branch}..refs/remotes/${remoteRef}`),
+            git(directory, `rev-list --count refs/remotes/${remoteRef}..refs/heads/${branch}`),
+        ]);
+        if (remoteAhead instanceof Error || localAhead instanceof Error)
+            continue;
+        const remoteAheadCount = parseInt(remoteAhead, 10);
+        const localAheadCount = parseInt(localAhead, 10);
+        // Diverged (both ahead): use local to avoid needing a merge
+        if (remoteAheadCount > 0 && localAheadCount > 0)
+            return branch;
+        // Remote is strictly ahead: use remote ref
+        if (remoteAheadCount > 0)
+            return remoteRef;
+        // Equal or local is ahead — check next remote instead of returning early,
+        // because origin might be ahead even when upstream is equal.
+    }
+    // No usable remote found — use local branch as-is
+    return branch;
+}
 /**
  * List branches sorted by most recent commit date.
  * Returns branch short names (e.g. "main", "origin/feature-x").

package/package.json

@@ -2,7 +2,7 @@
   "name": "kimaki",
   "module": "index.ts",
   "type": "module",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "repository": "https://github.com/remorses/kimaki",
   "bin": "bin.js",
   "exports": {
@@ -31,10 +31,10 @@
     "lintcn": "^0.7.1",
     "tsx": "^4.20.5",
     "undici": "^8.0.2",
-    "db": "^0.0.0",
     "discord-digital-twin": "^0.1.1",
+    "opencode-deterministic-provider": "^0.0.1",
     "opencode-cached-provider": "^0.0.1",
-    "opencode-deterministic-provider": "^0.0.1"
+    "db": "^0.0.0"
   },
   "dependencies": {
     "@ai-sdk/google": "^3.0.53",
@@ -70,9 +70,9 @@
     "zod": "^4.3.6",
     "zustand": "^5.0.11",
     "errore": "^0.14.1",
-    "libsqlproxy": "^0.1.0",
+    "traforo": "^0.7.1",
     "opencode-injection-guard": "^0.2.1",
-    "traforo": "^0.7.1"
+    "libsqlproxy": "^0.1.0"
   },
   "optionalDependencies": {
     "@snazzah/davey": "^0.1.10",

package/skills/holocron/SKILL.md

@@ -705,6 +705,29 @@ Accordion apply `no-bleed` automatically to keep descendants inside their frame.
 
 See https://holocron.so/docs/customize/bleed.md for the full reference.
 
+## Custom CSS — prefer CSS variables over class selectors
+
+When customizing the look of a Holocron site, **always use CSS variable overrides** in `:root` instead of targeting internal class names, DOM structure, or aria labels. Holocron exposes a set of documented CSS variables for colors, typography, spacing, code blocks, blockquotes, and sidebar navigation. These are stable across Holocron updates; internal markup is not.
+
+```css
+/* style.css */
+:root {
+  --weight-heading: 700;
+  --code-block-background: var(--muted);
+  --code-block-border: 1px solid var(--border-subtle);
+  --sidebar-link-radius: var(--radius-sm);
+  --blockquote-border-color: var(--border-subtle);
+}
+```
+
+Fetch the full list of available tokens:
+
+```bash
+curl -fsSL https://holocron.so/docs/customize/theme.md
+```
+
+If a user wants to customize something that has no CSS variable, **do not hack it with fragile selectors**. Instead, open an issue on the Holocron repo (https://github.com/remorses/holocron/issues) requesting a new CSS variable for that use case. Holocron actively adds new variables based on user needs. Internal selectors like `.slot-sidebar-left nav > div:first-child > a` or `figure[class~='group/code'] button[aria-label='Copy code']` will break on any refactor and should never be used.
+
 ## Agent rules
 
 - **Always place MDX pages inside the Holocron `pagesDir`.** Before creating or