pikiloom 0.4.26 → 0.4.27

package/dist/bot/bot.js

@@ -1,8 +1,3 @@
-/**
- * Shared Bot base class: chat state, session lifecycle, task queue, streaming bridge.
- *
- * Channel-agnostic. Subclassed per IM channel (see channels/telegram/bot.ts, etc.).
- */
 import os from 'node:os';
 import path from 'node:path';
 import { execSync, spawn } from 'node:child_process';
@@ -29,9 +24,6 @@ import { BOT_TIMEOUTS } from '../core/constants.js';
 export const DEFAULT_RUN_TIMEOUT_S = BOT_TIMEOUTS.defaultRunTimeoutS;
 const MACOS_USER_ACTIVITY_PULSE_INTERVAL_MS = BOT_TIMEOUTS.macosUserActivityPulseInterval;
 const MACOS_USER_ACTIVITY_PULSE_TIMEOUT_S = BOT_TIMEOUTS.macosUserActivityPulseTimeoutS;
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
 export function normalizeAgent(raw) {
     const v = raw.trim().toLowerCase();
     if (!hasDriver(v))
@@ -46,9 +38,6 @@ export function thinkLabel(agent) {
         return 'Thinking';
     }
 }
-// ---------------------------------------------------------------------------
-// Prompt assembly helpers
-// ---------------------------------------------------------------------------
 function appendExtraPrompt(base, extra) {
     const lhs = String(base || '').trim();
     const rhs = String(extra || '').trim();
@@ -58,10 +47,6 @@ function appendExtraPrompt(base, extra) {
         return lhs;
     return `${lhs}\n\n${rhs}`;
 }
-// NOTE: the `[Artifact Return]` header is a load-bearing marker — both
-// `stripInjectedPrompts` (bot/streaming.ts) and Gemini's
-// `GEMINI_SYSTEM_BLOCK_SENTINELS` key on it to strip this injected block from
-// displayed user messages. Keep the token in sync if you ever change it.
 function buildMcpDeliveryPrompt() {
     return [
         '[Artifact Return]',
@@ -69,13 +54,6 @@ function buildMcpDeliveryPrompt() {
     ].join('\n');
 }
 function buildClaudeAskUserPrompt() {
-    // Claude is heavily trained on its built-in `AskUserQuestion` tool, so just
-    // registering `mcp__pikiloom__im_ask_user` alongside it isn't enough — the
-    // model still picks the native one, the CLI rejects it in -p mode with
-    // `is_error: true content: "Answer questions?"`, and the turn dies without
-    // ever firing the human-loop. This directive redirects calls *if* the model
-    // chooses to ask. It deliberately does not nudge the default ask-less
-    // behaviour — only the routing.
     return [
         '[Asking the user]',
         'The built-in `AskUserQuestion` tool is disabled here and will fail. If you would otherwise call it, call `mcp__pikiloom__im_ask_user` instead — same intent (a question plus optional choices), it blocks until the user replies via the IM/dashboard channel. Default behaviour is unchanged: infer obvious decisions yourself and only ask when you genuinely cannot proceed.',
@@ -99,11 +77,6 @@ function buildBrowserAutomationPrompt(browserEnabled) {
     ].join('\n');
 }
 function buildWorkflowOptInPrompt() {
-    // Standing opt-in injected only when the user explicitly enabled workflow
-    // orchestration for this agent. The Workflow tool is left enabled (not
-    // disallowed) in this mode; this directive tells the model it may reach for
-    // it proactively on genuinely large work, while preserving the default
-    // single-agent behaviour for everything else (no baseline regression).
     return [
         '[Multi-agent Workflow]',
         'Workflow orchestration is enabled for this session. For substantial multi-step work — broad research, large refactors or audits, fan-out reviews across many files — you may proactively author and run a Workflow to decompose and parallelise it.',
@@ -136,7 +109,6 @@ function normalizeFromClaudeNative(goal) {
     return {
         source: 'claude',
         objective: goal.condition,
-        // Native /goal exposes no pause/budget — it's either active or absent.
         status: 'active',
         tokenBudget: null,
         tokensUsed: 0,
@@ -144,17 +116,12 @@ function normalizeFromClaudeNative(goal) {
         continuationCount: null,
     };
 }
-// ---------------------------------------------------------------------------
-// Bot
-// ---------------------------------------------------------------------------
 export class Bot {
     workdir;
     defaultAgent;
     runTimeout;
     allowedChatIds;
-    // Per-agent config — keyed by agent id
     agentConfigs = {};
-    // Convenience accessors (backward-compat)
     get codexModel() { return this.agentConfigs.codex?.model || ''; }
     set codexModel(v) { this.agentConfigs.codex.model = v; }
     get codexReasoningEffort() { return this.agentConfigs.codex?.reasoningEffort || 'xhigh'; }
@@ -176,21 +143,10 @@ export class Bot {
     startedAt = Date.now();
     connected = false;
     stats = { totalTurns: 0, totalInputTokens: 0, totalOutputTokens: 0, totalCachedTokens: 0 };
-    /* ── Dashboard stream state (polling-friendly snapshots) ── */
     streamSnapshots = new Map();
     snapshotCleanupTimers = new Map();
-    /** Maps promoted session keys (old → new) so poll endpoints can resolve pending IDs. */
     promotedSessionKeys = new Map();
-    /** Reverse map (new → old[]) so pushSnapshotToSSE can broadcast on promoted-from aliases. */
     promotedFromAliases = new Map();
-    /**
-     * Walk the promotion chain so callers passing a stale (pending or
-     * pre-rotation) key always resolve to the current canonical key for the same
-     * logical session. Multi-hop chains (pending → id_a → id_b after Claude
-     * `--resume` rotates twice) are followed end-to-end. Used by every
-     * sessionStates / streamSnapshots lookup so the rest of the codebase never
-     * has to special-case promotion.
-     */
     resolveSessionKey(sessionKey) {
         let key = sessionKey;
         const seen = new Set();
@@ -203,13 +159,6 @@ export class Bot {
         }
         return key;
     }
-    /**
-     * Drop all promotion bookkeeping that pointed at a now-retired canonical key.
-     * `promotedFromAliases.get(key)` is exactly the set of stale keys whose forward
-     * `promotedSessionKeys` entries resolve to `key`, so clearing them here keeps
-     * that map from growing for the whole process lifetime (otherwise one entry
-     * leaks per new session + per Claude `--resume` rotation, never reclaimed).
-     */
     forgetPromotion(canonicalKey) {
         const aliases = this.promotedFromAliases.get(canonicalKey);
         if (aliases)
@@ -217,32 +166,18 @@ export class Bot {
                 this.promotedSessionKeys.delete(alias);
         this.promotedFromAliases.delete(canonicalKey);
     }
-    /** Get the current streaming snapshot for a session (used by polling endpoint).
-     *  Follows the promotion chain so a pending or pre-rotation key still resolves. */
     getStreamSnapshot(sessionKey) {
         const snap = this.streamSnapshots.get(this.resolveSessionKey(sessionKey));
         return snap ? this.enrichSnapshot(snap) : null;
     }
-    /**
-     * Attach per-queued-task prompts and refresh interaction `currentIndex` from
-     * live prompt state — both are derived data the cached snapshot can't carry
-     * on its own (queued prompts come from RunningTask records; currentIndex
-     * advances asynchronously after select/skip/text without re-emitting the
-     * interaction event).
-     */
     enrichSnapshot(snap) {
         let next = snap;
-        // Attach the running turn's prompt so a watching terminal can render the
-        // user message for a follow-up it didn't originate (no local optimistic
-        // bubble). The RunningTask record is the source of truth while it's live.
         const runningPrompt = next.taskId ? this.activeTasks.get(next.taskId)?.prompt : '';
         if (runningPrompt)
             next = { ...next, question: collapseSkillPrompt(runningPrompt) ?? runningPrompt };
         if (next.queuedTaskIds?.length) {
             const queuedTasks = next.queuedTaskIds.map(taskId => {
                 const raw = this.activeTasks.get(taskId)?.prompt || '';
-                // Show `/skillname` instead of the long expansion we synthesized for the
-                // agent — matches what the user actually typed in the queued row.
                 return { taskId, prompt: collapseSkillPrompt(raw) ?? raw };
             });
             next = { ...next, queuedTasks };
@@ -258,11 +193,9 @@ export class Bot {
         }
         return next;
     }
-    /* ── Dashboard SSE push (injected by dashboard layer to avoid circular import) ── */
     _onStreamSnapshot = null;
     streamPushTimers = new Map();
     streamPushPending = new Map();
-    /** Called by the dashboard layer to subscribe to stream snapshot changes. */
     onStreamSnapshot(cb) {
         this._onStreamSnapshot = cb;
     }
@@ -274,8 +207,6 @@ export class Bot {
         const emitAll = () => {
             const enriched = snap ? this.enrichSnapshot(snap) : null;
             cb(sessionKey, enriched);
-            // Also broadcast on promoted-from aliases so clients still listening
-            // on the old (pending) key receive updates after session promotion.
             const aliases = this.promotedFromAliases.get(sessionKey);
             if (aliases)
                 for (const alias of aliases)
@@ -291,7 +222,6 @@ export class Bot {
             emitAll();
         }
         else {
-            // Coalesce: if a timer is pending, just mark dirty
             this.streamPushPending.set(sessionKey, true);
             if (this.streamPushTimers.has(sessionKey))
                 return;
@@ -304,9 +234,7 @@ export class Bot {
             }, 80));
         }
     }
-    /** Emit a streaming event — updates the polling snapshot. */
     emitStream(sessionKey, event) {
-        // Clear any pending cleanup timer
         const pending = this.snapshotCleanupTimers.get(sessionKey);
         if (pending) {
             clearTimeout(pending);
@@ -317,7 +245,6 @@ export class Bot {
             case 'queued': {
                 const existing = this.streamSnapshots.get(sessionKey);
                 if (existing && (existing.phase === 'streaming' || existing.phase === 'done')) {
-                    // Don't overwrite active stream — append to the queued list (deduped).
                     const list = existing.queuedTaskIds ? [...existing.queuedTaskIds] : [];
                     if (existing.taskId !== event.taskId && !list.includes(event.taskId))
                         list.push(event.taskId);
@@ -325,7 +252,6 @@ export class Bot {
                     existing.updatedAt = now;
                 }
                 else if (existing && existing.phase === 'queued') {
-                    // Already in queued phase with no active task — append additional queued IDs.
                     const list = existing.queuedTaskIds ? [...existing.queuedTaskIds] : [];
                     if (existing.taskId !== event.taskId && !list.includes(event.taskId))
                         list.push(event.taskId);
@@ -338,8 +264,6 @@ export class Bot {
                 break;
             }
             case 'start': {
-                // Preserve any tasks still queued behind the new active one. Drop the
-                // task that's now starting from that list since it has graduated.
                 const prev = this.streamSnapshots.get(sessionKey);
                 const remainingQueued = prev?.queuedTaskIds?.filter(id => id !== event.taskId);
                 this.streamSnapshots.set(sessionKey, {
@@ -392,9 +316,6 @@ export class Bot {
                     queuedTaskIds: prev?.queuedTaskIds,
                     updatedAt: now,
                 });
-                // Auto-clean 'done' snapshot after 30s so stale state doesn't linger.
-                // Extended from 10s to give clients time to pick up the final state
-                // after session promotion or WS reconnects.
                 this.snapshotCleanupTimers.set(sessionKey, setTimeout(() => {
                     this.streamSnapshots.delete(sessionKey);
                     this.snapshotCleanupTimers.delete(sessionKey);
@@ -407,14 +328,11 @@ export class Bot {
                 if (!snap)
                     break;
                 if (snap.queuedTaskIds?.includes(event.taskId)) {
-                    // Cancelled one of the queued-behind tasks — keep the running/done
-                    // snapshot, just remove this entry from the list.
                     const next = snap.queuedTaskIds.filter(id => id !== event.taskId);
                     snap.queuedTaskIds = next.length ? next : undefined;
                     snap.updatedAt = now;
                 }
                 else {
-                    // Cancelled the currently displayed task — drop the whole snapshot.
                     this.streamSnapshots.delete(sessionKey);
                     this.forgetPromotion(sessionKey);
                 }
@@ -441,24 +359,11 @@ export class Bot {
                 break;
             }
         }
-        // Push to dashboard SSE — throttle text events, push everything else immediately
         try {
             this.pushSnapshotToSSE(sessionKey, event.type !== 'text');
         }
-        catch { /* dashboard not loaded yet — ignore */ }
-    }
-    /**
-     * Stream-lifecycle helpers. The dashboard mirrors a running turn by reading
-     * `streamSnapshots`, which is built exclusively from `emitStream` calls.
-     * IM channels run `runStream` directly (not via `submitSessionTask`), so
-     * without these calls the dashboard never sees IM-initiated turns. Routing
-     * every IM handler through these helpers (and refactoring submitSessionTask
-     * to use them) keeps the two surfaces consistent: each side can observe
-     * whatever the other side started.
-     *
-     * Each helper resolves the live `task.sessionKey` so the event lands on the
-     * current snapshot after a pending→native session id promotion.
-     */
+        catch { }
+    }
     liveSessionKey(taskId, fallback) {
         return this.activeTasks.get(taskId)?.sessionKey || fallback;
     }
@@ -495,26 +400,12 @@ export class Bot {
     emitStreamCancelled(taskId, fallbackKey) {
         this.emitStream(this.liveSessionKey(taskId, fallbackKey), { type: 'cancelled', taskId });
     }
-    /**
-     * Wrap a per-turn `im_send_file` callback so every artifact delivery is
-     * recorded to the session's durable manifest (agent/artifacts.ts) and
-     * mirrored live into the running turn's snapshot — on top of whatever
-     * terminal-specific push the caller supplied (`inner`, e.g. an IM chat
-     * upload). The returned callback is always safe to register, so the tool is
-     * available for dashboard / headless turns that have no `inner` (the
-     * dashboard serves the recorded copy over HTTP). Recording is best-effort and
-     * never propagates an error back into the delivery result.
-     */
     buildArtifactSendFile(agent, sessionKey, cs, inner) {
         return async (filePath, sendOpts) => {
-            // Terminal-specific push first (IM chat). Dashboard / headless has no inner.
             const result = inner ? await inner(filePath, sendOpts) : { ok: true };
             if (!result.ok)
                 return result;
             try {
-                // Resolve the freshest session id at delivery time — send_file fires
-                // late in a turn, after a pending→native promotion has normally already
-                // happened, so the manifest lands under the canonical id.
                 let sid = '';
                 if (sessionKey) {
                     const rt = this.getSessionRuntimeByKey(sessionKey, { allowAnyWorkdir: true });
@@ -563,7 +454,6 @@ export class Bot {
         ensureGitignore(this.workdir);
         initializeProjectSkills(this.workdir);
         const config = getActiveUserConfig();
-        // Initialize per-agent configs
         this.agentConfigs = {
             codex: {
                 model: resolveAgentModel(config, 'codex'),
@@ -575,12 +465,7 @@ export class Bot {
                 model: resolveAgentModel(config, 'claude'),
                 reasoningEffort: resolveAgentEffort(config, 'claude') || 'high',
                 permissionMode: (process.env.CLAUDE_PERMISSION_MODE || 'bypassPermissions').trim(),
-                // Workflow orchestration is a per-session/per-turn choice (composer
-                // toggle / IM /mode), never a persisted default — always boot off.
                 workflowEnabled: false,
-                // Access mode (TUI subscription vs `claude -p` Agent SDK credits) IS a
-                // persisted preference — hydrate it from config so the boot value
-                // matches the dashboard toggle / env default.
                 accessMode: resolveClaudeAccessMode(config),
                 extraArgs: shellSplit(process.env.CLAUDE_EXTRA_ARGS || ''),
             },
@@ -590,12 +475,6 @@ export class Bot {
                 sandbox: envBool('GEMINI_SANDBOX', false),
                 extraArgs: shellSplit(process.env.GEMINI_EXTRA_ARGS || ''),
             },
-            // Hermes was missing from this map for a long time. Without an entry,
-            // `modelForAgent('hermes')` returned '' and `setModelForAgent('hermes',
-            // ...)` silently no-op'd because `if (config)` short-circuited — so any
-            // /models switch in IM looked successful in the log but never reached
-            // the hermes driver. Adding the entry lets the same machinery the other
-            // three agents already rely on apply to hermes too.
             hermes: {
                 model: resolveAgentModel(config, 'hermes'),
                 reasoningEffort: resolveAgentEffort(config, 'hermes') || 'medium',
@@ -628,7 +507,6 @@ export class Bot {
         }
         return s;
     }
-    /** Effective workdir for a chat — per-chat override or global fallback. */
     chatWorkdir(chatId) {
         return this.chats.get(chatId)?.workdir || this.workdir;
     }
@@ -666,17 +544,10 @@ export class Bot {
     upsertSessionRuntime(session) {
         const workdir = path.resolve(session.workdir || this.workdir);
         const requestedKey = this.sessionKey(session.agent, session.sessionId);
-        // Follow the promotion chain. Without this, an insertion that races a
-        // pending→native promotion would `new` a phantom runtime under the stale
-        // pending key and the queued message would land in a session the dashboard
-        // can never reach again.
         const resolvedKey = this.resolveSessionKey(requestedKey);
         const existing = this.sessionStates.get(resolvedKey);
         if (existing) {
             existing.workdir = workdir;
-            // Do NOT overwrite agent/sessionId/key here — the existing record IS the
-            // canonical identity post-promotion. Letting upserts re-stamp the old
-            // pending id back over the native id would unwind the promotion.
             if (session.workspacePath !== undefined)
                 existing.workspacePath = session.workspacePath ?? null;
             if (session.threadId !== undefined)
@@ -687,7 +558,6 @@ export class Bot {
                 existing.modelId = session.modelId ?? null;
             if (session.thinkingEffort !== undefined)
                 existing.thinkingEffort = session.thinkingEffort ?? null;
-            // handoverFrom is one-shot: only set if not already set (the first staging wins).
             if (session.handoverFrom !== undefined && !existing.handoverFrom) {
                 existing.handoverFrom = session.handoverFrom;
             }
@@ -766,9 +636,6 @@ export class Bot {
             this.applySessionSelection(cs, null);
             return;
         }
-        // Adopting an existing session is an explicit user pick — drop any
-        // queued handover from a prior agent toggle so we don't accidentally
-        // prepend the wrong context to the resumed session's next turn.
         cs.pendingHandoverFrom = null;
         this.applySessionSelection(cs, runtime);
     }
@@ -839,11 +706,6 @@ export class Bot {
             this.sessionChains.set(nextKey, mergedChain);
         }
         this.moveSessionStreamSnapshot(previousKey, nextKey);
-        // Track promotion so poll endpoints + insertions can resolve pending →
-        // native. When the chain hops more than once (Claude `--resume` rotating
-        // session ids back-to-back), pull ancestor aliases forward AND re-point
-        // them at the latest key so a single lookup is O(1) and every WS listener
-        // that subscribed to any earlier key still receives updates.
         this.promotedSessionKeys.set(previousKey, nextKey);
         const aliases = new Set(this.promotedFromAliases.get(nextKey) || []);
         aliases.add(previousKey);
@@ -856,12 +718,9 @@ export class Bot {
             this.promotedFromAliases.delete(previousKey);
         }
         this.promotedFromAliases.set(nextKey, [...aliases]);
-        // Update the promoted snapshot's sessionId to reflect the native ID
         const promotedSnap = this.streamSnapshots.get(nextKey);
         if (promotedSnap)
             promotedSnap.sessionId = resolvedSessionId;
-        // Notify dashboard clients still tracking the old (pending) key via SSE
-        // so they can detect the promotion and navigate to the correct session
         if (this._onStreamSnapshot && promotedSnap) {
             this._onStreamSnapshot(previousKey, this.enrichSnapshot(promotedSnap));
         }
@@ -917,10 +776,6 @@ export class Bot {
         const selected = this.getSelectedSession(cs);
         if (selected)
             return selected;
-        // Auto-resume an existing same-thread session of this agent (back-and-forth
-        // toggling). The handover queued on `cs.pendingHandoverFrom` is intentionally
-        // dropped here — the resumed session already has its own history; replaying
-        // an external handover on top would just be duplicate context.
         const resumed = this.findThreadSessionRuntime(chatId, cs.activeThreadId, cs.agent);
         if (resumed) {
             cs.pendingHandoverFrom = null;
@@ -1083,19 +938,12 @@ export class Bot {
         }
         return { task, interrupted: false, cancelled: false };
     }
-    /**
-     * Mark all queued tasks ahead of `targetTaskId` (in this session) so their
-     * chain wrappers re-enqueue and yield to the steered task. Repeated steers
-     * reset prior defer flags so only the latest target's predecessors defer.
-     */
     markQueueDeferralsForSteer(targetTaskId) {
         const target = this.activeTasks.get(targetTaskId);
         if (!target)
             return;
         const snapshot = this.streamSnapshots.get(target.sessionKey);
         const queuedIds = snapshot?.queuedTaskIds || [];
-        // Reset any previous defer flags for this session's queued tasks first so
-        // a new steer call doesn't stack on top of an earlier (now-stale) decision.
         for (const id of queuedIds) {
             const t = this.activeTasks.get(id);
             if (t)
@@ -1108,11 +956,6 @@ export class Bot {
                 t.deferForSteer = true;
         }
     }
-    /**
-     * Steer hands off to the queued task's own placeholder card. Interrupt the
-     * active task so the queued task can run next and the current preview can be
-     * frozen in place instead of being rewritten as an error.
-     */
     async steerTaskByActionId(actionId) {
         const taskId = this.taskKeysByActionId.get(String(actionId));
         if (!taskId)
@@ -1124,10 +967,6 @@ export class Bot {
         const interrupted = this.interruptRunningTask(task.sessionKey, { freezePreview: true });
         return { task, interrupted, steered: false };
     }
-    /**
-     * Interrupt only the currently running task for a session, leaving queued tasks intact.
-     * Used by the "Steer" action to let a queued task run next.
-     */
     interruptRunningTask(sessionKey, opts = {}) {
         const session = this.getSessionRuntimeByKey(sessionKey, { allowAnyWorkdir: true });
         if (!session)
@@ -1145,10 +984,6 @@ export class Bot {
         }
         return false;
     }
-    /**
-     * Return the number of tasks ahead of the given task in its session queue.
-     * Counts running + queued (non-cancelled) tasks that were started before this one.
-     */
     getQueuePosition(sessionKey, taskId) {
         const session = this.getSessionRuntimeByKey(sessionKey, { allowAnyWorkdir: true });
         if (!session)
@@ -1169,20 +1004,11 @@ export class Bot {
         return `${String(chatId)}:${String(sourceMessageId)}`;
     }
     queueSessionTask(session, task, taskId) {
-        // Wrap the user task with a defer check. When steerTask() flags this task
-        // to yield its chain slot to a steered task, the wrapper re-enqueues the
-        // same fn at the tail and returns immediately so the next chain wrapper
-        // (the steered task's) fires next. Tasks without a taskId (e.g. file
-        // staging) skip the check.
         const runner = async () => {
             if (taskId) {
                 const t = this.activeTasks.get(taskId);
                 if (t?.deferForSteer && !t.cancelled) {
                     t.deferForSteer = false;
-                    // Re-enqueue at the tail. Don't await — let the current slot finish
-                    // immediately so the chain advances to the steered task. The new
-                    // wrapper preserves the original fn so the deferred task still runs
-                    // (just after the steered one).
                     void this.queueSessionTask(session, task, taskId);
                     return undefined;
                 }
@@ -1278,13 +1104,6 @@ export class Bot {
         this.fireInteractionAnswered(prompt, 'cancelled');
         return prompt;
     }
-    /**
-     * Unified post-resolution hook for human-loop prompts. Each IM channel
-     * overrides `onInteractionAnswered` to (1) collapse the original prompt card
-     * to an answered/cancelled state and (2) echo the decision as a new chat
-     * message so scrolling back shows what the user picked. Dashboard sessions
-     * (chatId='dashboard') and channels that opt out remain silent.
-     */
     fireInteractionAnswered(prompt, status) {
         if (prompt.silent)
             return;
@@ -1295,13 +1114,7 @@ export class Bot {
             .then(() => this.onInteractionAnswered(prompt, summary))
             .catch(err => this.warn(`onInteractionAnswered failed: ${err?.message || err}`));
     }
-    /**
-     * Channel hook fired after a human-loop prompt resolves (answered or
-     * cancelled). Default: no-op. Override in channel subclasses to update the
-     * original card and post a decision-echo message.
-     */
     async onInteractionAnswered(_prompt, _summary) {
-        // Default: no-op.
     }
     emitInteractionResolved(taskId, promptId) {
         const task = this.activeTasks.get(taskId);
@@ -1356,14 +1169,6 @@ export class Bot {
         else
             this.humanLoopPromptIdsByChat.delete(chatKey);
     }
-    /**
-     * Create an interaction handler that bridges agent requests to the human-loop
-     * state machine and pushes SSE events to the dashboard.
-     *
-     * IM channel subclasses override `renderInteractionPrompt()` to render
-     * buttons/cards in their native UI.  Dashboard clients receive the
-     * `interaction` SSE event and respond via REST.
-     */
     createInteractionHandler(chatId, taskId) {
         return async (request) => {
             const active = this.beginHumanLoopPrompt({
@@ -1382,19 +1187,9 @@ export class Bot {
                 questions: request.questions,
                 currentIndex: active.prompt.currentIndex,
             };
-            // Resolve sessionKey live at emit time — the task entry tracks promotion
-            // (pending → native id), so a key captured at handler-creation time would
-            // go stale on the very first turn of a fresh session and the dashboard
-            // SSE event would land on an already-moved snapshot.
             const task = this.activeTasks.get(taskId);
             if (task)
                 this.emitStream(task.sessionKey, { type: 'interaction', taskId, interaction: interactionSnapshot });
-            // Dashboard sessions reply through SSE + REST (no IM render). When an IM
-            // bot is also attached, its renderInteractionPrompt override would still
-            // fire here with chatId='dashboard' — sending the prompt to the IM API
-            // with an invalid receive_id, which surfaces as "Request failed with
-            // status code 400" from the axios-based SDK. Skip the render for
-            // dashboard chats; the SSE event is the canonical delivery.
             if (chatId !== 'dashboard') {
                 try {
                     await this.renderInteractionPrompt(active.prompt, chatId);
@@ -1407,31 +1202,15 @@ export class Bot {
             return active.result;
         };
     }
-    /**
-     * Render an interaction prompt in the IM channel.
-     * Override in channel subclasses (Telegram, Feishu, etc.).
-     * Dashboard-only sessions (chatId='dashboard') are a no-op by default.
-     */
     async renderInteractionPrompt(_prompt, _chatId) {
-        // Default: no-op (dashboard-only sessions use SSE events instead)
     }
-    // ---- Public interaction API (used by dashboard routes) --------------------
-    /** Respond to a pending interaction prompt with a selected option. */
     interactionSelectOption(promptId, optionValue, opts) {
         return this.humanLoopSelectOption(promptId, optionValue, opts);
     }
-    /** Submit freeform text to a pending interaction prompt. */
     interactionSubmitText(promptId, text) {
         const prompt = this.humanLoopPrompt(promptId);
         if (!prompt)
             return null;
-        // The dashboard modal submits a custom answer via an explicit Submit button,
-        // so accept the text whenever the current question PERMITS freeform — not
-        // only after an "Other" chip flipped `awaitingFreeform` (the IM-card flow,
-        // which `isHumanLoopAwaitingText` gates on). An options question only allows
-        // it when `allowFreeform` is set; an option-less question is freeform by
-        // definition. (The IM passive-text path keeps the stricter check so a normal
-        // chat message isn't silently captured as an answer.)
         const question = currentHumanLoopQuestion(prompt);
         if (!question)
             return null;
@@ -1444,15 +1223,12 @@ export class Bot {
             this.resolveHumanLoopPrompt(prompt.promptId);
         return { prompt, ...result };
     }
-    /** Skip the current question in a pending interaction prompt. */
     interactionSkip(promptId) {
         return this.humanLoopSkip(promptId);
     }
-    /** Cancel a pending interaction prompt. */
     interactionCancel(promptId, reason = 'Cancelled from dashboard.') {
         return this.humanLoopCancel(promptId, reason);
     }
-    /** Get a specific interaction prompt by ID. */
     interactionPrompt(promptId) {
         return this.humanLoopPrompt(promptId);
     }
@@ -1465,7 +1241,6 @@ export class Bot {
             sessionId: opts.sessionId,
             workdir: opts.workdir,
             workspacePath: null,
-            // Only override when explicitly provided — undefined skips the overwrite in upsertSessionRuntime
             ...(opts.modelId !== undefined ? { modelId: opts.modelId } : {}),
             ...(opts.thinkingEffort !== undefined ? { thinkingEffort: opts.thinkingEffort } : {}),
             ...(opts.handoverFrom !== undefined ? { handoverFrom: opts.handoverFrom } : {}),
@@ -1493,12 +1268,7 @@ export class Bot {
                 this.finishTask(taskId);
                 return;
             }
-            // Thread the per-send Workflow choice so the live divider folds to `ultra`
-            // immediately (the dashboard composer picks ultra per-send without flipping
-            // the agent-global flag resolveSessionStreamConfig would otherwise read).
             this.emitStreamStart(taskId, session, { workflowEnabled: opts.workflowEnabled });
-            // Wire up IM rendering for non-dashboard chats so /goal-driven tasks stream
-            // to the same channel that submitted them, matching handleMessage's UX.
             const presenter = chatId !== 'dashboard'
                 ? await this.createImTaskPresenter({
                     chatId, taskId, session, agent: session.agent, prompt, attachments,
@@ -1562,28 +1332,9 @@ export class Bot {
         });
         return { ok: true, taskId, sessionKey: session.key, queued: true };
     }
-    /**
-     * Channel hook — returns a presenter that streams the task's runStream
-     * output to the IM chat that submitted it. Default: null (dashboard-only
-     * chats and channels that haven't opted in stay silent in IM).
-     */
     async createImTaskPresenter(_opts) {
         return null;
     }
-    /**
-     * Goal continuation: after a turn ends, if a goal is still active for the
-     * session, account token + wall-clock usage, then enqueue one more task with
-     * the rendered continuation prompt. If the budget was just crossed, enqueue a
-     * single wrap-up turn with the budget-limit prompt instead. Goal-continuation
-     * tasks that get cancelled or errored auto-pause the goal so the loop does
-     * not silently resume on the user's next message.
-     *
-     * Codex and Claude sessions short-circuit: each runs its own native `/goal`
-     * lifecycle (codex's app-server state machine; claude's in-process Stop
-     * hook), so pikiloom stays out to avoid a double loop. See setSessionGoal
-     * et al — they bridge to codex's `thread/goal/*` RPC and to claude's
-     * `/goal <condition>` slash command instead of writing pikiloom's goal.json.
-     */
     maybeEnqueueGoalContinuation(session, opts, result) {
         if (session.agent === 'codex' || session.agent === 'claude')
             return;
@@ -1648,16 +1399,6 @@ export class Bot {
             goalContinuation: { kind: 'continuation', goalId: updated.goalId },
         });
     }
-    /**
-     * Normalized goal view used by IM/dashboard renderers — same shape regardless
-     * of whether the source is pikiloom's goal.json (claude / gemini / …) or
-     * codex's native SQLite state machine.
-     */
-    // SessionGoalView is exported below the class.
-    /**
-     * Read the current goal for a session. For codex this hits codex's native
-     * `thread/goal/get`; for other drivers, reads goal.json.
-     */
     async getSessionGoal(workdir, agent, sessionId) {
         if (agent === 'codex') {
             if (!sessionId || isPendingSessionId(sessionId))
@@ -1674,12 +1415,6 @@ export class Bot {
         const goal = readGoal(workdir, agent, sessionId);
         return goal ? normalizeFromPikiloom(goal) : null;
     }
-    /**
-     * Set (or replace) the goal for a session. For codex this routes through
-     * codex's native `thread/goal/set` and codex auto-starts a continuation turn
-     * internally. For other drivers, pikiloom writes goal.json and enqueues the
-     * first continuation turn so the agent starts working immediately.
-     */
     async setSessionGoal(workdir, agent, sessionId, opts) {
         if (agent === 'codex') {
             if (!sessionId || isPendingSessionId(sessionId)) {
@@ -1693,7 +1428,6 @@ export class Bot {
             });
             if (!resp.ok)
                 throw new Error(resp.error);
-            // codex returns a snapshot; if for some reason it's null, re-fetch.
             const goal = resp.goal ?? (await getCodexGoal(sessionId));
             if (!goal)
                 throw new Error('codex did not return a goal snapshot');
@@ -1703,12 +1437,6 @@ export class Bot {
             if (!sessionId || isPendingSessionId(sessionId)) {
                 throw new Error('claude session must exist before /goal — send a first message to create the transcript');
             }
-            // Native /goal owns its own continuation engine (Stop hook). pikiloom
-            // just submits the slash command as the next task; claude internally
-            // sets up the goal_status attachment, injects its meta directive, and
-            // keeps looping until the Haiku completion check returns met. Token
-            // budget is accepted in the API for shape parity with codex/portable
-            // but ignored — claude native /goal has no budget concept.
             const objective = opts.objective.trim();
             if (!objective)
                 throw new Error('objective must be non-empty');
@@ -1721,8 +1449,6 @@ export class Bot {
                 modelId: opts.modelId,
                 thinkingEffort: opts.thinkingEffort,
             });
-            // Return an optimistic snapshot — the actual goal_status attachment is
-            // written by claude during the task; readers can poll getSessionGoal.
             return normalizeFromClaudeNative({
                 condition: objective,
                 status: 'active',
@@ -1760,8 +1486,6 @@ export class Bot {
             return goal ? normalizeFromCodex(goal) : null;
         }
         if (agent === 'claude') {
-            // Claude's native /goal exposes no pause/resume — only set and clear.
-            // Surface a clear error so the IM layer can render a friendly message.
             throw new Error('Claude native /goal does not support pause/resume — only `/goal clear`. Re-issue `/goal <objective>` to start fresh.');
         }
         const goal = pauseGoal(workdir, agent, sessionId);
@@ -1810,7 +1534,6 @@ export class Bot {
         if (agent === 'claude') {
             if (!sessionId || isPendingSessionId(sessionId))
                 return;
-            // Read goal-status first to avoid spawning a no-op turn when nothing is set.
             const existing = getClaudeNativeGoal(workdir, sessionId);
             if (!existing)
                 return;
@@ -1854,24 +1577,9 @@ export class Bot {
         const interrupted = this.interruptRunningTask(task.sessionKey, { freezePreview: true });
         return { task, interrupted, steered: interrupted || !!task };
     }
-    /**
-     * Stop only the currently running task for a session. Queued tasks are
-     * intentionally left intact and run normally once the chain advances — the
-     * stop button means "abort what's running right now", not "throw away the
-     * queue". To drop a specific queued entry, use the per-row × button which
-     * routes through `cancelTask`.
-     */
     stopAllSessionTasks(sessionKey) {
         return this.stopTasksForSession(sessionKey);
     }
-    /**
-     * Public "start a fresh session" entry point — wired to the "+ New" button
-     * and the `/new` command. Only clears the chat's session selection so the
-     * next user message lands in a fresh session; the previously selected
-     * session keeps running independently (matching dashboard behaviour, where
-     * each session is its own card and is never aborted by creating another).
-     * Use `cancelTask` / `/stop` to actually interrupt a running task.
-     */
     resetConversationForChat(chatId) {
         const cs = this.chat(chatId);
         this.resetChatConversation(cs);
@@ -1881,13 +1589,6 @@ export class Bot {
         this.adoptSession(cs, session);
         return this.getSelectedSession(cs);
     }
-    /**
-     * Resume an existing session in a chat and restore the agent's persistent
-     * model / effort / BYOK Profile binding so the next stream — and the IM
-     * picker chips — match the session that was just adopted. This is the
-     * shared "click a row from the workspace list" path used by both the
-     * interactive selector and the text-command `/sessions <#>` flow.
-     */
     resumeSessionForChat(chatId, session) {
         const runtime = this.adoptExistingSessionForChat(chatId, session);
         if (session.model) {
@@ -1905,15 +1606,9 @@ export class Bot {
         const cs = this.chat(chatId);
         if (cs.agent === agent)
             return false;
-        // Capture the live session of the *outgoing* agent so the next message to
-        // the new agent can replay it as a handover. We capture BEFORE flipping
-        // cs.agent so the ref is honest about which agent it points at.
         const prevAgent = cs.agent;
         const prevSessionId = cs.sessionId && !isPendingSessionId(cs.sessionId) ? cs.sessionId : null;
         cs.agent = agent;
-        // Pre-existing session of the new agent in this thread — back-and-forth
-        // toggling resumes it without handover. The user's intent is "continue what
-        // I had", not "translate cross-agent".
         const resumed = this.findThreadSessionRuntime(chatId, cs.activeThreadId, agent);
         if (resumed) {
             cs.pendingHandoverFrom = null;
@@ -1921,11 +1616,6 @@ export class Bot {
             this.log(`agent switched to ${agent} chat=${chatId} resumed=${resumed.sessionId}`);
             return true;
         }
-        // No existing session of the new agent → next message will stage a fresh
-        // one. Park the outgoing session as the handover source. If the outgoing
-        // agent had no live session (e.g. the user is rapidly toggling agents
-        // before sending anything), keep any already-pending handover so the
-        // original source isn't lost across intermediate switches.
         if (prevSessionId) {
             cs.pendingHandoverFrom = { agent: prevAgent, sessionId: prevSessionId };
         }
@@ -1933,26 +1623,8 @@ export class Bot {
         this.log(`agent switched to ${agent} chat=${chatId} handoverFrom=${describeHandoverRef(cs.pendingHandoverFrom)}`);
         return true;
     }
-    /**
-     * Switch the active model for a chat. Supports both native (agent CLI's own
-     * auth) and BYOK Profile selections:
-     *   - `profileId === undefined` (default) — set native model only; pre-union
-     *     callers (text-command channels) keep working unchanged.
-     *   - `profileId === null` — explicit clear: drop any active Profile, fall
-     *     back to native model.
-     *   - `profileId === '<uuid>'` — bind that Profile; `modelId` should match
-     *     the Profile's modelId so display surfaces stay in sync.
-     *
-     * The native model field (`agentConfigs[agent].model`) always tracks the
-     * effective model id used by the agent CLI — when a Profile is bound, this
-     * lets `modelForAgent()` return the right display string without an extra
-     * lookup. When unbinding, we leave the field alone so the user's prior
-     * native pick is preserved.
-     */
     switchModelForChat(chatId, modelId, profileId) {
         const cs = this.chat(chatId);
-        // Update activeProfileByAgent first — resolveSessionStreamConfig downstream
-        // reads it via getActiveProfile() during spawn.
         if (profileId !== undefined) {
             setActiveProfile(cs.agent, profileId || null);
         }
@@ -1969,25 +1641,11 @@ export class Bot {
                 : ' profile=(cleared)';
         this.log(`model switched to ${modelId} for ${cs.agent} chat=${chatId} session=${cs.activeSessionKey || '(none)'}${profileTag}`);
     }
-    /**
-     * The Profile id currently bound to this agent, if any. Used by the IM
-     * picker to flag "current selection" when the user has a Profile bound —
-     * since multiple Profiles may share the same modelId, a model-id match
-     * alone is ambiguous.
-     */
     activeProfileIdForAgent(agent) {
         return getActiveProfileId(agent);
     }
     switchEffortForChat(chatId, effort) {
         const cs = this.chat(chatId);
-        // "ultra" is a synthetic top rung in the effort picker, NOT a real --effort
-        // value (the claude CLI rejects anything outside low|medium|high|xhigh|max).
-        // It bundles "max reasoning depth + permit multi-agent Workflow
-        // orchestration" — the same pairing as Claude's own `ultracode` mode. Decode
-        // it here, the single apply choke point, so the rest of the pipeline only
-        // ever sees a concrete effort value plus the orthogonal workflow flag.
-        // Because the rungs are mutually exclusive, picking any concrete level also
-        // clears the workflow opt-in (capability-gated — only claude advertises it).
         const ultra = effort === 'ultra';
         const realEffort = ultra ? 'max' : effort;
         this.setEffortForAgent(cs.agent, realEffort);
@@ -2001,12 +1659,6 @@ export class Bot {
         }
         this.log(`effort switched to ${effort} (effort=${realEffort}, workflow=${ultra}) for ${cs.agent} chat=${chatId}`);
     }
-    /**
-     * Effort value to *display* in the picker. Workflow is orthogonal under the
-     * hood, but the UI folds "max depth + workflow on" into the single synthetic
-     * `ultra` rung (see {@link switchEffortForChat}), so report it as current when
-     * the agent has orchestration enabled. Mirrors the decomposition above.
-     */
     effortSelectionForAgent(agent) {
         const effort = this.effortForAgent(agent);
         if (!effort)
@@ -2023,13 +1675,6 @@ export class Bot {
             this.log(`permission mode switched to ${mode} for claude chat=${chatId}`);
         }
     }
-    /**
-     * Toggle multi-agent Workflow orchestration for the chat's current agent.
-     * Unlike permission-mode it does NOT reset the conversation — the tool set is
-     * resolved per-invocation, so the change cleanly takes effect on the next
-     * turn without invalidating the session transcript. No-op for agents whose
-     * driver doesn't advertise the capability.
-     */
     switchWorkflowForChat(chatId, enabled) {
         const cs = this.chat(chatId);
         if (!getDriverCapabilities(cs.agent).workflow) {
@@ -2041,12 +1686,6 @@ export class Bot {
         this.log(`workflow ${enabled ? 'enabled' : 'disabled'} for ${cs.agent} chat=${chatId}`);
     }
     modelForAgent(agent) {
-        // For agents whose CLIs cannot switch model via flags (Hermes uses ACP
-        // session/set_model, which only fires when a BYOK Profile is bound), the
-        // active Profile is the only meaningful source of truth — falling back to
-        // `agentConfigs[agent].model` would surface a stale value the runtime
-        // never actually uses. For agents with native model selectors
-        // (Claude/Codex/Gemini), the user-config field is still authoritative.
         if (agent === 'hermes') {
             const bound = getAgentBoundModelId('hermes');
             if (bound)
@@ -2054,11 +1693,6 @@ export class Bot {
         }
         return this.agentConfigs[agent]?.model || '';
     }
-    /**
-     * Resolve the effective model + thinking effort that a stream for `cs` will run with.
-     * Mirrors the fallback chain used inside runStream() so callers (e.g. submitSessionTask
-     * emitting a 'start' event) can label the active turn before runStream resolves it.
-     */
     resolveSessionStreamConfig(cs, opts) {
         const agentConfig = this.agentConfigs[cs.agent] || {};
         const sessionWorkdir = cs.workdir || this.workdir;
@@ -2074,12 +1708,6 @@ export class Bot {
             || agentConfig.reasoningEffort
             || 'high';
         const effort = cs.agent === 'gemini' ? null : (effortRaw || null);
-        // Fold to the synthetic 'ultra' rung for display when Workflow is on (mirrors
-        // effortSelectionForAgent / the dashboard's foldUltraEffort), so the live reply
-        // badge and IM running footer label the turn 'ultra' instead of a bare 'max'.
-        // Prefer the per-turn workflow choice when the caller threads one (dashboard
-        // composer sends ultra per-send without flipping the agent-global flag);
-        // fall back to the agent-global flag (IM /mode, agent card).
         const workflowOn = opts?.workflowEnabled ?? this.workflowEnabledForAgent(cs.agent);
         const displayEffort = effort && getDriverCapabilities(cs.agent).workflow && workflowOn
             ? 'ultra'
@@ -2102,9 +1730,6 @@ export class Bot {
     }
     fetchModels(agent, workdir) {
         const wd = workdir || this.workdir;
-        // Provider-aware: when the agent is bound to a BYOK Profile, the
-        // returned model list is the provider's enumerable models. This keeps
-        // IM /models consistent with the dashboard agent card.
         return resolveAgentModels(agent, { workdir: wd, currentModel: this.modelForAgent(agent) });
     }
     setDefaultAgent(agent) {
@@ -2143,12 +1768,6 @@ export class Bot {
             config.workflowEnabled = enabled;
         this.log(`workflow for ${agent} changed to ${enabled}`);
     }
-    /**
-     * Switch Claude's access mode (subscription TUI vs `claude -p` Agent SDK
-     * credits). Persisted preference — takes effect on the NEXT spawned turn
-     * (in-flight streams keep their own opts); does not reset any conversation
-     * since both modes resume the same native session transcript.
-     */
     setClaudeAccessMode(mode) {
         const config = this.agentConfigs.claude;
         if (config)
@@ -2157,13 +1776,8 @@ export class Bot {
     }
     persistAgentPreference(agent, kind, value) {
         try {
-            // Hermes model writes go to the active BYOK Profile (the runtime's only
-            // model-switching surface). Falls through to the legacy `hermesModel`
-            // user-config field when no Profile is bound.
             if (kind === 'model' && agent === 'hermes' && setAgentBoundModelId('hermes', value))
                 return;
-            // Workflow orchestration opt-in is a boolean field, and only claude
-            // advertises the capability, so it bypasses the string patch below.
             if (kind === 'workflow') {
                 if (agent === 'claude')
                     updateUserConfig({ claudeWorkflowEnabled: value === '1' });
@@ -2286,34 +1900,13 @@ export class Bot {
     }
     afterSwitchWorkdir(_oldPath, _newPath) { }
     onManagedConfigChange(_config, _opts = {}) { }
-    /**
-     * Subclass entry point — connect to the channel and block on its
-     * listen loop. Each channel implementation overrides this; calling it
-     * on the base class is a programming error.
-     */
     run() {
         throw new Error('Bot.run() must be implemented by a channel subclass');
     }
-    /**
-     * Subclass hook: tear down the channel transport so `run()` can resolve.
-     * Subclasses override to disconnect their specific channel — the base
-     * implementation only cleans up the bot-level subscriptions that don't
-     * belong to any one channel.
-     *
-     * Used by ChannelSupervisor when a channel must be stopped or replaced
-     * in-process (channel removal, credential rotation) without restarting
-     * the entire pikiloom runtime.
-     */
     requestStop() {
         this.userConfigUnsubscribe?.();
         this.userConfigUnsubscribe = null;
     }
-    /**
-     * Scan registered workspaces + the active workdir for sessions stuck in
-     * 'running' state after a crash/restart and downgrade them to 'incomplete'.
-     * Safe to call at any time — only touches records whose owning process is
-     * no longer alive (or that have gone stale past the age threshold).
-     */
     reconcileStaleRunningSessions() {
         const seen = new Set();
         const candidates = [this.workdir];
@@ -2344,10 +1937,6 @@ export class Bot {
         else if (nextWorkdir !== this.workdir) {
             this.switchWorkdir(nextWorkdir, { persist: false });
         }
-        // The configured value is a *preference* (baseline 'codex' when unset);
-        // clamp it to an installed agent so a fresh machine whose preferred CLI
-        // isn't installed still routes new conversations to one that can actually
-        // run, instead of surfacing an uninstalled default.
         const nextDefaultAgent = resolveDefaultAgent(config.defaultAgent || 'codex', listAgents().agents);
         if (opts.initial)
             this.defaultAgent = nextDefaultAgent;
@@ -2368,10 +1957,6 @@ export class Bot {
                 else
                     this.setEffortForAgent(agent, nextEffort);
             }
-            // Access mode (claude only) IS reconciled — unlike workflow, it's a
-            // persisted preference, so an external setting.json edit or a dashboard
-            // save (which both flow through here via onUserConfigChange) must push
-            // the new value onto the running bot so the next turn spawns accordingly.
             if (agent === 'claude') {
                 const nextAccessMode = resolveClaudeAccessMode(config);
                 if (this.claudeAccessMode !== nextAccessMode) {
@@ -2381,16 +1966,12 @@ export class Bot {
                         this.setClaudeAccessMode(nextAccessMode);
                 }
             }
-            // Workflow is intentionally NOT reconciled from config here: it's an
-            // in-memory per-session toggle (composer / IM /mode), so a config-sync
-            // tick must not clobber a deliberate in-session choice.
         }
         if (!opts.initial)
             this.onManagedConfigChange(config, opts);
     }
     async runStream(prompt, cs, attachments, onText, systemPrompt, mcpSendFile, abortSignal, onInteraction, onSteerReady, onCodexTurnReady, extras) {
         const agentConfig = this.agentConfigs[cs.agent] || {};
-        // Session-level config stored on disk — used as fallback between explicit override and global defaults
         const sessionWorkdirForConfig = 'workdir' in cs && typeof cs.workdir === 'string' && cs.workdir ? cs.workdir : this.workdir;
         const storedConfig = cs.sessionId && !isPendingSessionId(cs.sessionId)
             ? getSessionStoredConfig(sessionWorkdirForConfig, cs.agent, cs.sessionId)
@@ -2407,11 +1988,6 @@ export class Bot {
         this.debug(`[runStream] agent=${cs.agent} session=${cs.sessionId || '(new)'} workdir=${sessionWorkdir} timeout=${this.runTimeout}s attachments=${attachments.length}`);
         this.debug(`[runStream] ${cs.agent} config: model=${resolvedModel} extraArgs=[${extraArgs.join(' ')}]`);
         const isFirstTurnOfSession = !cs.sessionId || isPendingSessionId(cs.sessionId);
-        // ── Cross-agent handover ──
-        // First turn of a session created by an agent switch: read the prior agent's
-        // session, compact it, and prepend the seed to this turn's prompt. After this
-        // single injection the new agent owns the canonical session file and `--resume`
-        // takes over. See agent/handover.ts.
         const handoverFrom = ('handoverFrom' in cs && cs.handoverFrom) ? cs.handoverFrom : null;
         if (isFirstTurnOfSession && handoverFrom) {
             try {
@@ -2437,32 +2013,10 @@ export class Bot {
                 this.warn(`[runStream] handover threw: ${e?.message || e}; proceeding without prior context`);
             }
         }
-        // Per-turn workflow opt-in (dashboard composer passes it explicitly);
-        // falls back to the agent's in-memory flag (IM /mode) when unspecified.
-        // Default off — never read from a persisted config default.
         const workflowEnabled = cs.agent === 'claude' && (extras?.workflowEnabled ?? this.claudeWorkflowEnabled);
-        // ── Artifact delivery (terminal-agnostic) ──
-        // `im_send_file` is the single "hand a file to the user" verb. Whatever the
-        // caller wired as `mcpSendFile` (an IM channel push, or nothing for a
-        // dashboard / headless turn) is wrapped so every delivery ALSO records the
-        // file into the session's delivered-artifact manifest — the durable SSOT
-        // that survives reload + workspace cleanup and is servable over HTTP — and
-        // surfaces it live in the running turn's snapshot for any watching
-        // dashboard. Always provided, so the tool + delivery prompt light up even
-        // when there is no IM channel (the dashboard is the delivery surface then).
         const deliverySessionKey = ('key' in cs && typeof cs.key === 'string') ? cs.key : null;
         const wrappedSendFile = this.buildArtifactSendFile(cs.agent, deliverySessionKey, cs, mcpSendFile);
-        const mcpSystemPrompt = appendExtraPrompt(appendExtraPrompt(appendExtraPrompt(
-        // Always-on: `wrappedSendFile` is provided for every turn (see above),
-        // so artifact delivery is available regardless of terminal.
-        buildMcpDeliveryPrompt(), onInteraction && cs.agent === 'claude' ? buildClaudeAskUserPrompt() : ''), buildBrowserAutomationPrompt(browserEnabled)), workflowEnabled ? buildWorkflowOptInPrompt() : '');
-        // mcpSystemPrompt carries behaviour directives (use im_ask_user instead of
-        // built-in AskUserQuestion, browser automation status, artifact delivery)
-        // that must apply on every turn, not just the first — on resume the CLI
-        // does not automatically re-inject the previous --append-system-prompt
-        // contents, so Claude silently regresses to the built-in tools on turn 2+.
-        // The caller-supplied `systemPrompt` (per-task scaffolding) remains
-        // first-turn-only since later turns inherit it via the session transcript.
+        const mcpSystemPrompt = appendExtraPrompt(appendExtraPrompt(appendExtraPrompt(buildMcpDeliveryPrompt(), onInteraction && cs.agent === 'claude' ? buildClaudeAskUserPrompt() : ''), buildBrowserAutomationPrompt(browserEnabled)), workflowEnabled ? buildWorkflowOptInPrompt() : '');
         const effectiveSystemPrompt = isFirstTurnOfSession
             ? appendExtraPrompt(systemPrompt, mcpSystemPrompt)
             : (mcpSystemPrompt || undefined);
@@ -2485,45 +2039,31 @@ export class Bot {
             thinkingEffort: resolvedThinkingEffort, onText,
             onSessionId: syncNativeSessionId,
             attachments: attachments.length ? attachments : undefined,
-            // codex-specific
             codexModel: cs.agent === 'codex' ? resolvedModel : this.codexModel,
             codexFullAccess: this.codexFullAccess,
             codexDeveloperInstructions: effectiveSystemPrompt || undefined,
             codexExtraArgs: this.codexExtraArgs.length ? this.codexExtraArgs : undefined,
             codexPrevCumulative: cs.codexCumulative,
-            // claude-specific
             claudeModel: cs.agent === 'claude' ? resolvedModel : this.claudeModel,
             claudePermissionMode: this.claudePermissionMode,
             claudeWorkflowEnabled: workflowEnabled,
-            // Resolved per-stream so a live access-mode switch applies to new turns
-            // while in-flight streams keep the mode they spawned with.
             claudeAccessMode: cs.agent === 'claude' ? this.claudeAccessMode : undefined,
             claudeAppendSystemPrompt: effectiveSystemPrompt || undefined,
             claudeExtraArgs: this.claudeExtraArgs.length ? this.claudeExtraArgs : undefined,
-            // gemini-specific
             geminiModel: cs.agent === 'gemini' ? resolvedModel : (this.agentConfigs.gemini?.model || ''),
             geminiApprovalMode: this.geminiApprovalMode,
             geminiSandbox: this.geminiSandbox,
             geminiSystemInstruction: effectiveSystemPrompt || undefined,
             geminiExtraArgs: this.geminiExtraArgs.length ? this.geminiExtraArgs : undefined,
-            // hermes-specific. Wire the chat's current model so /models switching in
-            // IM takes effect even without a BYOK Profile (the BYOK injector in
-            // stream.ts overrides this with the ACP-encoded `provider:model` when
-            // a Profile is bound).
             hermesModel: cs.agent === 'hermes' && resolvedModel ? resolvedModel : undefined,
-            // MCP bridge
             mcpSendFile: wrappedSendFile,
             abortSignal,
             onInteraction,
             onSteerReady,
             onCodexTurnReady,
-            // Fork lineage — when set, the driver branches off the parent session.
             forkOf: extras?.forkOf,
         };
         const result = await doStream(opts);
-        // 'ultra' is a display-only rung (max reasoning + Workflow). The command ran on
-        // concrete max+workflow; relabel the result effort so the reply footer (IM
-        // final card, etc.) matches the picker. Display-only — never re-fed into a run.
         if (cs.agent === 'claude' && workflowEnabled && result.thinkingEffort) {
             result.thinkingEffort = 'ultra';
         }
@@ -2556,11 +2096,6 @@ export class Bot {
                 return;
             const bin = whichSync('caffeinate');
             if (bin) {
-                // `-dis` = prevent display sleep + idle sleep + system sleep. The `-d`
-                // (display) flag is intentional: the agent uses macOS `screencapture`
-                // for desktop screenshots, which returns a black frame once the
-                // display sleeps. Users who would rather let the screen turn off
-                // should drop brightness or close the lid against an external display.
                 this.keepAliveProc = spawn('caffeinate', ['-dis'], { stdio: 'ignore', detached: true });
                 this.keepAliveProc.unref();
                 this.log(`keep-alive: caffeinate (PID ${this.keepAliveProc.pid})`);