pikiloop 0.4.0

package/dist/bot/bot.js

@@ -0,0 +1,2499 @@
+/**
+ * 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';
+import { getActiveUserConfig, loadWorkspaces, onUserConfigChange, resolveUserWorkdir, setUserWorkdir, updateUserConfig } from '../core/config/user-config.js';
+import { doStream, ensureManagedSession, findManagedThreadSession, getSessionStoredConfig, getUsage, initializeProjectSkills, listAgents, resolveAgentModels, resolveDefaultAgent, listSkills, stageSessionFiles, reconcileOrphanedRunningSessions, getAgentBoundModelId, setAgentBoundModelId, collapseSkillPrompt, readGoal, accountTurn, shouldContinueAfterTurn, renderContinuationPrompt, renderBudgetLimitPrompt, bumpContinuationCount, pauseGoal, resumeGoal, setGoal as setGoalState, clearGoal as clearGoalState, setCodexGoal, getCodexGoal, clearCodexGoal, pauseCodexGoal, resumeCodexGoal, getClaudeNativeGoal, buildClaudeSetGoalPrompt, buildClaudeClearGoalPrompt, isPendingSessionId, } from '../agent/index.js';
+import { compactForHandover, describeHandoverRef } from '../agent/handover.js';
+import { getActiveProfileId, setActiveProfile } from '../model/index.js';
+import { querySessions, querySessionTail, updateSession, } from './session-hub.js';
+import { getDriver, hasDriver, allDriverIds, getDriverCapabilities } from '../agent/driver.js';
+import { resolveGuiIntegrationConfig } from '../agent/mcp/bridge.js';
+import { terminateProcessTree } from '../core/process-control.js';
+import { expandTilde } from '../core/platform.js';
+import { VERSION } from '../core/version.js';
+import { buildHumanLoopResponse, createEmptyHumanLoopAnswer, currentHumanLoopQuestion, isHumanLoopAwaitingText, setHumanLoopOption, setHumanLoopText, skipHumanLoopQuestion, summarizeResolvedHumanLoopAnswers, } from './human-loop.js';
+import { writeScopedLog } from '../core/logging.js';
+import { resolveAgentEffort, resolveAgentModel, resolveClaudeAccessMode, DEFAULT_CLAUDE_ACCESS_MODE, } from '../core/config/runtime-config.js';
+import { envBool, envString, envInt, shellSplit, whichSync, fmtTokens, parseAllowedChatIds, ensureGitignore, } from '../core/utils.js';
+import { getHostBatteryData, getHostCpuUsageData, getHostDisplayName, getHostMemoryUsageData, } from './host.js';
+export { updateSession };
+export { envBool, envString, envInt, shellSplit, whichSync, fmtTokens, fmtUptime, fmtBytes, parseAllowedChatIds, listSubdirs, extractThinkingTail, formatThinkingForDisplay, buildPrompt, ensureGitignore } from '../core/utils.js';
+export { getHostBatteryData, getHostCpuUsageData, getHostDisplayName, getHostMemoryUsageData } from './host.js';
+export { readGitStatus, formatGitStatusLine } from '../core/git.js';
+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))
+        throw new Error(`Invalid agent: ${v}. Use: ${allDriverIds().join(', ')}`);
+    return v;
+}
+export function thinkLabel(agent) {
+    try {
+        return getDriver(agent).thinkLabel;
+    }
+    catch {
+        return 'Thinking';
+    }
+}
+// ---------------------------------------------------------------------------
+// Prompt assembly helpers
+// ---------------------------------------------------------------------------
+function appendExtraPrompt(base, extra) {
+    const lhs = String(base || '').trim();
+    const rhs = String(extra || '').trim();
+    if (!lhs)
+        return rhs;
+    if (!rhs)
+        return lhs;
+    return `${lhs}\n\n${rhs}`;
+}
+function buildMcpDeliveryPrompt() {
+    return [
+        '[Artifact Return]',
+        'This is an IM/chat conversation, so pay attention to the IM tools.',
+    ].join('\n');
+}
+function buildClaudeAskUserPrompt() {
+    // Claude is heavily trained on its built-in `AskUserQuestion` tool, so just
+    // registering `mcp__pikiloop__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__pikiloop__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.',
+    ].join('\n');
+}
+function buildBrowserAutomationPrompt(browserEnabled) {
+    if (!browserEnabled) {
+        return [
+            '[Browser Automation]',
+            'Managed browser automation is disabled by default for this session.',
+            process.platform === 'darwin'
+                ? 'On macOS, operate your main browser directly with native commands such as open, osascript, and screencapture when needed.'
+                : 'Use native OS or browser commands directly when browser automation is not enabled.',
+        ].join('\n');
+    }
+    return [
+        '[Browser Automation]',
+        'A Playwright MCP browser server is already configured to use the local Chrome channel with a persistent profile.',
+        'Do not call browser_install unless a browser tool explicitly reports that Chrome or the browser is missing.',
+        'If you need a new tab, use browser_tabs with action="new".',
+    ].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.',
+        'Keep it proportional: do NOT orchestrate trivial or single-file tasks. When a workflow would not add value, just answer directly as a single agent. Workflows can spawn many sub-agents and consume significant tokens, so reserve them for work whose scale genuinely warrants the fan-out.',
+    ].join('\n');
+}
+function normalizeFromPikiloop(goal) {
+    return {
+        source: 'pikiloop',
+        objective: goal.objective,
+        status: goal.status,
+        tokenBudget: goal.tokenBudget,
+        tokensUsed: goal.tokensUsed,
+        timeUsedSeconds: goal.timeUsedSeconds,
+        continuationCount: goal.continuationCount,
+    };
+}
+function normalizeFromCodex(goal) {
+    return {
+        source: 'codex',
+        objective: goal.objective,
+        status: goal.status === 'budgetLimited' ? 'budget_limited' : goal.status,
+        tokenBudget: goal.tokenBudget,
+        tokensUsed: goal.tokensUsed,
+        timeUsedSeconds: goal.timeUsedSeconds,
+        continuationCount: null,
+    };
+}
+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,
+        timeUsedSeconds: 0,
+        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'; }
+    set codexReasoningEffort(v) { this.agentConfigs.codex.reasoningEffort = v; }
+    get codexFullAccess() { return this.agentConfigs.codex?.fullAccess ?? true; }
+    get codexExtraArgs() { return this.agentConfigs.codex?.extraArgs || []; }
+    get claudeModel() { return this.agentConfigs.claude?.model || ''; }
+    set claudeModel(v) { this.agentConfigs.claude.model = v; }
+    get claudePermissionMode() { return this.agentConfigs.claude?.permissionMode || 'bypassPermissions'; }
+    get claudeExtraArgs() { return this.agentConfigs.claude?.extraArgs || []; }
+    get claudeWorkflowEnabled() { return this.agentConfigs.claude?.workflowEnabled ?? false; }
+    get claudeAccessMode() { return this.agentConfigs.claude?.accessMode || DEFAULT_CLAUDE_ACCESS_MODE; }
+    get geminiApprovalMode() { return this.agentConfigs.gemini?.approvalMode || 'yolo'; }
+    get geminiSandbox() { return this.agentConfigs.gemini?.sandbox ?? false; }
+    get geminiExtraArgs() { return this.agentConfigs.gemini?.extraArgs || []; }
+    chats = new Map();
+    sessionStates = new Map();
+    activeTasks = new Map();
+    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();
+        while (!seen.has(key)) {
+            const next = this.promotedSessionKeys.get(key);
+            if (!next || next === key)
+                break;
+            seen.add(key);
+            key = next;
+        }
+        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)
+            for (const alias of aliases)
+                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;
+        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 };
+        }
+        if (next.interactions?.length) {
+            const refreshed = next.interactions.map(snapshotEntry => {
+                const live = this.humanLoopPrompts.get(snapshotEntry.promptId);
+                if (!live)
+                    return snapshotEntry;
+                return { ...snapshotEntry, currentIndex: live.currentIndex };
+            });
+            next = { ...next, interactions: refreshed };
+        }
+        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;
+    }
+    pushSnapshotToSSE(sessionKey, immediate) {
+        if (!this._onStreamSnapshot)
+            return;
+        const snap = this.streamSnapshots.get(sessionKey) ?? null;
+        const cb = this._onStreamSnapshot;
+        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)
+                    cb(alias, enriched ? { ...enriched } : null);
+        };
+        if (immediate) {
+            const timer = this.streamPushTimers.get(sessionKey);
+            if (timer) {
+                clearTimeout(timer);
+                this.streamPushTimers.delete(sessionKey);
+            }
+            this.streamPushPending.delete(sessionKey);
+            emitAll();
+        }
+        else {
+            // Coalesce: if a timer is pending, just mark dirty
+            this.streamPushPending.set(sessionKey, true);
+            if (this.streamPushTimers.has(sessionKey))
+                return;
+            this.streamPushTimers.set(sessionKey, setTimeout(() => {
+                this.streamPushTimers.delete(sessionKey);
+                if (this.streamPushPending.get(sessionKey)) {
+                    this.streamPushPending.delete(sessionKey);
+                    emitAll();
+                }
+            }, 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);
+            this.snapshotCleanupTimers.delete(sessionKey);
+        }
+        const now = Date.now();
+        switch (event.type) {
+            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);
+                    existing.queuedTaskIds = list.length ? list : undefined;
+                    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);
+                    existing.queuedTaskIds = list.length ? list : undefined;
+                    existing.updatedAt = now;
+                }
+                else {
+                    this.streamSnapshots.set(sessionKey, { phase: 'queued', taskId: event.taskId, updatedAt: now });
+                }
+                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, {
+                    phase: 'streaming', taskId: event.taskId,
+                    text: '', thinking: '', activity: '', plan: null, sessionId: event.sessionId, updatedAt: now,
+                    model: event.model, effort: event.effort, previewMeta: null,
+                    startedAt: now,
+                    queuedTaskIds: remainingQueued && remainingQueued.length ? remainingQueued : undefined,
+                });
+                break;
+            }
+            case 'text': {
+                const snap = this.streamSnapshots.get(sessionKey);
+                if (snap) {
+                    snap.text = event.text;
+                    snap.thinking = event.thinking;
+                    snap.activity = event.activity;
+                    snap.plan = event.plan?.steps?.length ? event.plan : null;
+                    if (event.previewMeta)
+                        snap.previewMeta = event.previewMeta;
+                    snap.updatedAt = now;
+                }
+                break;
+            }
+            case 'done': {
+                const prev = this.streamSnapshots.get(sessionKey);
+                this.streamSnapshots.set(sessionKey, {
+                    phase: 'done',
+                    taskId: event.taskId,
+                    sessionId: event.sessionId,
+                    incomplete: !!event.incomplete,
+                    text: prev?.text || '',
+                    thinking: prev?.thinking || '',
+                    activity: prev?.activity || '',
+                    error: event.error,
+                    plan: prev?.plan ?? null,
+                    model: prev?.model ?? null,
+                    effort: prev?.effort ?? null,
+                    previewMeta: prev?.previewMeta ?? null,
+                    startedAt: prev?.startedAt,
+                    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);
+                    this.forgetPromotion(sessionKey);
+                }, 30_000));
+                break;
+            }
+            case 'cancelled': {
+                const snap = this.streamSnapshots.get(sessionKey);
+                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);
+                }
+                break;
+            }
+            case 'interaction': {
+                const snap = this.streamSnapshots.get(sessionKey);
+                if (snap) {
+                    const list = snap.interactions || [];
+                    list.push(event.interaction);
+                    snap.interactions = list;
+                    snap.updatedAt = now;
+                }
+                break;
+            }
+            case 'interaction-resolved': {
+                const snap = this.streamSnapshots.get(sessionKey);
+                if (snap?.interactions) {
+                    snap.interactions = snap.interactions.filter(i => i.promptId !== event.promptId);
+                    if (!snap.interactions.length)
+                        delete snap.interactions;
+                    snap.updatedAt = now;
+                }
+                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.
+     */
+    liveSessionKey(taskId, fallback) {
+        return this.activeTasks.get(taskId)?.sessionKey || fallback;
+    }
+    emitStreamQueued(sessionKey, taskId) {
+        this.emitStream(sessionKey, { type: 'queued', taskId, position: this.getQueuePosition(sessionKey, taskId) });
+    }
+    emitStreamStart(taskId, session) {
+        const cfg = this.resolveSessionStreamConfig(session);
+        const key = this.liveSessionKey(taskId, session.key);
+        this.debug(`[stream-lifecycle] start task=${taskId} key=${key} sessionId=${session.sessionId || '(pending)'} model=${cfg.model || '-'}`);
+        this.emitStream(key, {
+            type: 'start', taskId, agent: session.agent, sessionId: session.sessionId,
+            model: cfg.model, effort: cfg.effort,
+        });
+    }
+    emitStreamText(taskId, fallbackKey, text, thinking, activity = '', meta, plan) {
+        const key = this.liveSessionKey(taskId, fallbackKey);
+        const snap = this.streamSnapshots.get(key);
+        this.debug(`[stream-lifecycle] text task=${taskId} key=${key} bytes=${text.length}/${thinking.length} snap=${snap ? snap.phase : 'NONE'}`);
+        this.emitStream(key, {
+            type: 'text', text, thinking, activity, plan: plan ?? null, previewMeta: meta ?? null,
+        });
+    }
+    emitStreamDone(taskId, fallbackKey, opts) {
+        const key = this.liveSessionKey(taskId, fallbackKey);
+        this.debug(`[stream-lifecycle] done task=${taskId} key=${key} sessionId=${opts.sessionId || '(none)'} incomplete=${opts.incomplete}`);
+        this.emitStream(key, {
+            type: 'done', taskId,
+            sessionId: opts.sessionId,
+            incomplete: opts.incomplete,
+            ...(opts.error ? { error: opts.error } : {}),
+        });
+    }
+    emitStreamCancelled(taskId, fallbackKey) {
+        this.emitStream(this.liveSessionKey(taskId, fallbackKey), { type: 'cancelled', taskId });
+    }
+    keepAliveProc = null;
+    keepAlivePulseTimer = null;
+    sessionChains = new Map();
+    userConfigUnsubscribe = null;
+    taskKeysBySourceMessage = new Map();
+    taskKeysByActionId = new Map();
+    withdrawnSourceMessages = new Set();
+    nextTaskActionId = 1;
+    humanLoopPrompts = new Map();
+    humanLoopPromptIdsByChat = new Map();
+    nextHumanLoopPromptId = 1;
+    constructor() {
+        this.workdir = resolveUserWorkdir();
+        ensureGitignore(this.workdir);
+        initializeProjectSkills(this.workdir);
+        const config = getActiveUserConfig();
+        // Initialize per-agent configs
+        this.agentConfigs = {
+            codex: {
+                model: resolveAgentModel(config, 'codex'),
+                reasoningEffort: resolveAgentEffort(config, 'codex') || 'xhigh',
+                fullAccess: envBool('CODEX_FULL_ACCESS', true),
+                extraArgs: shellSplit(process.env.CODEX_EXTRA_ARGS || ''),
+            },
+            claude: {
+                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 || ''),
+            },
+            gemini: {
+                model: resolveAgentModel(config, 'gemini'),
+                approvalMode: envString('GEMINI_APPROVAL_MODE', 'yolo'),
+                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',
+                extraArgs: shellSplit(process.env.HERMES_EXTRA_ARGS || ''),
+            },
+        };
+        this.defaultAgent = normalizeAgent('codex');
+        this.runTimeout = envInt('PIKILOOP_TIMEOUT', DEFAULT_RUN_TIMEOUT_S);
+        this.allowedChatIds = parseAllowedChatIds(process.env.PIKILOOP_ALLOWED_IDS || '');
+        this.refreshManagedConfig(getActiveUserConfig(), { initial: true });
+        this.userConfigUnsubscribe = onUserConfigChange(config => this.refreshManagedConfig(config));
+    }
+    log(msg, level = 'info') {
+        writeScopedLog('pikiloop', msg, { level });
+    }
+    debug(msg) {
+        this.log(msg, 'debug');
+    }
+    warn(msg) {
+        this.log(msg, 'warn');
+    }
+    error(msg) {
+        this.log(msg, 'error');
+    }
+    chat(chatId) {
+        let s = this.chats.get(chatId);
+        if (!s) {
+            s = { agent: this.defaultAgent, sessionId: null, activeSessionKey: null, activeThreadId: null, modelId: null };
+            this.chats.set(chatId, s);
+        }
+        return s;
+    }
+    /** Effective workdir for a chat — per-chat override or global fallback. */
+    chatWorkdir(chatId) {
+        return this.chats.get(chatId)?.workdir || this.workdir;
+    }
+    sessionKey(agent, sessionId) {
+        return `${agent}:${sessionId}`;
+    }
+    getSessionRuntimeByKey(sessionKey, opts = {}) {
+        if (!sessionKey)
+            return null;
+        const runtime = this.sessionStates.get(this.resolveSessionKey(sessionKey)) || null;
+        if (!runtime)
+            return null;
+        if (!opts.allowAnyWorkdir && runtime.workdir !== this.workdir)
+            return null;
+        return runtime;
+    }
+    getSelectedSession(cs) {
+        return this.getSessionRuntimeByKey(cs.activeSessionKey, { allowAnyWorkdir: true });
+    }
+    hydrateSessionRuntime(session) {
+        if (!session.sessionId)
+            return null;
+        return this.upsertSessionRuntime({
+            agent: session.agent,
+            sessionId: session.sessionId,
+            workdir: session.workdir || this.workdir,
+            workspacePath: session.workspacePath ?? null,
+            threadId: session.threadId ?? null,
+            codexCumulative: session.codexCumulative,
+            modelId: session.modelId ?? null,
+            thinkingEffort: session.thinkingEffort ?? null,
+            handoverFrom: session.handoverFrom ?? null,
+        });
+    }
+    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)
+                existing.threadId = session.threadId ?? null;
+            if (session.codexCumulative !== undefined)
+                existing.codexCumulative = session.codexCumulative;
+            if (session.modelId !== undefined)
+                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;
+            }
+            return existing;
+        }
+        const runtime = {
+            key: requestedKey,
+            workdir,
+            agent: session.agent,
+            sessionId: session.sessionId,
+            workspacePath: session.workspacePath ?? null,
+            threadId: session.threadId ?? null,
+            codexCumulative: session.codexCumulative,
+            modelId: session.modelId ?? null,
+            thinkingEffort: session.thinkingEffort ?? null,
+            runningTaskIds: new Set(),
+            handoverFrom: session.handoverFrom ?? null,
+        };
+        this.sessionStates.set(requestedKey, runtime);
+        return runtime;
+    }
+    applySessionSelection(cs, session, opts = {}) {
+        const previousSessionKey = cs.activeSessionKey ?? null;
+        cs.activeSessionKey = session?.key ?? null;
+        if (session) {
+            cs.agent = session.agent;
+            cs.sessionId = session.sessionId;
+            cs.workspacePath = session.workspacePath;
+            cs.activeThreadId = session.threadId;
+            cs.codexCumulative = session.codexCumulative;
+            cs.modelId = session.modelId ?? null;
+            cs.workdir = session.workdir;
+            if (previousSessionKey && previousSessionKey !== session.key)
+                this.maybeEvictSessionRuntime(previousSessionKey);
+            return;
+        }
+        cs.sessionId = null;
+        cs.workspacePath = null;
+        if (!opts.preserveThread)
+            cs.activeThreadId = null;
+        cs.codexCumulative = undefined;
+        cs.modelId = null;
+        if (previousSessionKey)
+            this.maybeEvictSessionRuntime(previousSessionKey);
+    }
+    resetChatConversation(cs, opts) {
+        this.applySessionSelection(cs, null, { preserveThread: opts?.clearThread === false });
+        if (opts?.clearWorkdir)
+            cs.workdir = null;
+    }
+    adoptSession(cs, session) {
+        if (!session.sessionId) {
+            this.applySessionSelection(cs, null);
+            return;
+        }
+        const managed = ensureManagedSession({
+            agent: session.agent,
+            sessionId: session.sessionId,
+            workdir: 'workdir' in session && session.workdir ? session.workdir : this.workdir,
+            title: session.title ?? null,
+            model: session.model ?? null,
+            thinkingEffort: session.thinkingEffort ?? null,
+            profileId: session.profileId ?? null,
+            threadId: session.threadId ?? null,
+        });
+        const runtime = this.hydrateSessionRuntime({
+            agent: session.agent,
+            sessionId: session.sessionId,
+            workdir: 'workdir' in session ? session.workdir : null,
+            workspacePath: managed.workspacePath ?? session.workspacePath ?? null,
+            threadId: managed.threadId ?? session.threadId ?? null,
+            modelId: session.model ?? managed.model ?? null,
+            thinkingEffort: session.thinkingEffort ?? managed.thinkingEffort ?? null,
+        });
+        if (!runtime) {
+            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);
+    }
+    syncSelectedChats(session) {
+        for (const [, cs] of this.chats) {
+            if (cs.activeSessionKey !== session.key)
+                continue;
+            this.applySessionSelection(cs, session);
+        }
+    }
+    moveSessionStreamSnapshot(previousKey, nextKey) {
+        if (!previousKey || !nextKey || previousKey === nextKey)
+            return;
+        const previousSnapshot = this.streamSnapshots.get(previousKey) || null;
+        const nextSnapshot = this.streamSnapshots.get(nextKey) || null;
+        const mergedSnapshot = previousSnapshot && (!nextSnapshot || previousSnapshot.updatedAt >= nextSnapshot.updatedAt)
+            ? previousSnapshot
+            : nextSnapshot;
+        this.streamSnapshots.delete(previousKey);
+        if (mergedSnapshot)
+            this.streamSnapshots.set(nextKey, mergedSnapshot);
+        const previousTimer = this.snapshotCleanupTimers.get(previousKey);
+        if (previousTimer) {
+            clearTimeout(previousTimer);
+            this.snapshotCleanupTimers.delete(previousKey);
+            if (mergedSnapshot?.phase === 'done') {
+                this.snapshotCleanupTimers.set(nextKey, setTimeout(() => {
+                    this.streamSnapshots.delete(nextKey);
+                    this.snapshotCleanupTimers.delete(nextKey);
+                }, 10_000));
+            }
+        }
+    }
+    promoteSessionRuntime(session, nextSessionId) {
+        const resolvedSessionId = nextSessionId.trim();
+        if (!resolvedSessionId || session.sessionId === resolvedSessionId)
+            return session;
+        const previousKey = session.key;
+        const previousSessionId = session.sessionId;
+        const nextKey = this.sessionKey(session.agent, resolvedSessionId);
+        const existing = this.sessionStates.get(nextKey);
+        if (existing && existing !== session) {
+            session.workspacePath = session.workspacePath ?? existing.workspacePath;
+            session.threadId = session.threadId ?? existing.threadId;
+            session.codexCumulative = session.codexCumulative ?? existing.codexCumulative;
+            session.modelId = session.modelId ?? existing.modelId ?? null;
+            session.thinkingEffort = session.thinkingEffort ?? existing.thinkingEffort ?? null;
+            for (const taskId of existing.runningTaskIds)
+                session.runningTaskIds.add(taskId);
+        }
+        this.sessionStates.delete(previousKey);
+        this.sessionStates.delete(nextKey);
+        session.sessionId = resolvedSessionId;
+        session.key = nextKey;
+        this.sessionStates.set(nextKey, session);
+        for (const [, task] of this.activeTasks) {
+            if (task.sessionKey === previousKey)
+                task.sessionKey = nextKey;
+        }
+        const previousChain = this.sessionChains.get(previousKey);
+        const nextChain = this.sessionChains.get(nextKey);
+        if (previousChain)
+            this.sessionChains.delete(previousKey);
+        if (previousChain || nextChain) {
+            const mergedChain = previousChain && nextChain && previousChain !== nextChain
+                ? Promise.allSettled([previousChain, nextChain]).then(() => { })
+                : (previousChain || nextChain);
+            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);
+        const ancestorAliases = this.promotedFromAliases.get(previousKey);
+        if (ancestorAliases) {
+            for (const alias of ancestorAliases) {
+                aliases.add(alias);
+                this.promotedSessionKeys.set(alias, nextKey);
+            }
+            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));
+        }
+        for (const [, cs] of this.chats) {
+            const matchesPreviousSelection = cs.activeSessionKey === previousKey;
+            const matchesNextSelection = cs.activeSessionKey === nextKey;
+            const matchesSessionId = cs.agent === session.agent && ((previousSessionId ? cs.sessionId === previousSessionId : false)
+                || cs.sessionId === resolvedSessionId);
+            if (!matchesPreviousSelection && !matchesNextSelection && !matchesSessionId)
+                continue;
+            this.applySessionSelection(cs, session);
+        }
+        return session;
+    }
+    isSessionSelected(sessionKey) {
+        if (!sessionKey)
+            return false;
+        for (const [, cs] of this.chats) {
+            if (cs.activeSessionKey === sessionKey)
+                return true;
+        }
+        return false;
+    }
+    maybeEvictSessionRuntime(sessionKey) {
+        const session = this.getSessionRuntimeByKey(sessionKey, { allowAnyWorkdir: true });
+        if (!session)
+            return;
+        if (session.runningTaskIds.size)
+            return;
+        if (session.workdir === this.workdir)
+            return;
+        if (this.isSessionSelected(session.key))
+            return;
+        this.sessionStates.delete(session.key);
+    }
+    findThreadSessionRuntime(chatId, threadId, agent) {
+        if (!threadId)
+            return null;
+        const managed = findManagedThreadSession(this.chatWorkdir(chatId), threadId, agent);
+        if (!managed?.sessionId)
+            return null;
+        return this.hydrateSessionRuntime({
+            agent: managed.agent,
+            sessionId: managed.sessionId,
+            workdir: managed.workdir || this.chatWorkdir(chatId),
+            workspacePath: managed.workspacePath ?? null,
+            threadId: managed.threadId ?? threadId,
+            modelId: managed.model ?? null,
+        });
+    }
+    ensureSessionForChat(chatId, title, files) {
+        const cs = this.chat(chatId);
+        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;
+            this.applySessionSelection(cs, resumed);
+            return resumed;
+        }
+        const wd = this.chatWorkdir(chatId);
+        const handoverFrom = cs.pendingHandoverFrom ?? null;
+        cs.pendingHandoverFrom = null;
+        const staged = stageSessionFiles({
+            agent: cs.agent,
+            workdir: wd,
+            files: [],
+            sessionId: null,
+            title: title || 'New session',
+            threadId: cs.activeThreadId ?? null,
+            handoverFrom,
+        });
+        const runtime = this.upsertSessionRuntime({
+            agent: cs.agent,
+            sessionId: staged.sessionId,
+            workspacePath: staged.workspacePath,
+            threadId: staged.threadId,
+            modelId: this.modelForAgent(cs.agent),
+            thinkingEffort: this.effortForAgent(cs.agent),
+            handoverFrom: staged.handoverFrom,
+        });
+        this.applySessionSelection(cs, runtime);
+        return runtime;
+    }
+    beginTask(task) {
+        const nextTask = {
+            ...task,
+            actionId: task.actionId || `t${(this.nextTaskActionId++).toString(36)}`,
+            status: 'queued',
+            cancelled: false,
+            abort: null,
+            placeholderMessageIds: [...(task.placeholderMessageIds || [])],
+        };
+        this.activeTasks.set(nextTask.taskId, nextTask);
+        this.taskKeysBySourceMessage.set(this.sourceMessageKey(task.chatId, task.sourceMessageId), nextTask.taskId);
+        this.taskKeysByActionId.set(String(nextTask.actionId), nextTask.taskId);
+        const session = this.getSessionRuntimeByKey(task.sessionKey, { allowAnyWorkdir: true });
+        session?.runningTaskIds.add(nextTask.taskId);
+    }
+    finishTask(taskId) {
+        for (const prompt of [...this.humanLoopPrompts.values()]) {
+            if (prompt.taskId !== taskId)
+                continue;
+            this.clearHumanLoopPrompt(prompt.promptId, new Error('Task finished before prompt was answered.'));
+        }
+        const task = this.activeTasks.get(taskId);
+        if (!task)
+            return;
+        this.activeTasks.delete(taskId);
+        this.taskKeysBySourceMessage.delete(this.sourceMessageKey(task.chatId, task.sourceMessageId));
+        if (task.actionId)
+            this.taskKeysByActionId.delete(String(task.actionId));
+        this.withdrawnSourceMessages.delete(this.sourceMessageKey(task.chatId, task.sourceMessageId));
+        const session = this.getSessionRuntimeByKey(task.sessionKey, { allowAnyWorkdir: true });
+        if (!session)
+            return;
+        session.runningTaskIds.delete(taskId);
+        this.maybeEvictSessionRuntime(session.key);
+    }
+    runningTaskForSession(sessionKey) {
+        const session = this.getSessionRuntimeByKey(sessionKey, { allowAnyWorkdir: true });
+        if (!session || !session.runningTaskIds.size)
+            return null;
+        let running = null;
+        for (const taskId of session.runningTaskIds) {
+            const task = this.activeTasks.get(taskId);
+            if (!task || task.status !== 'running')
+                continue;
+            if (!running || task.startedAt < running.startedAt)
+                running = task;
+        }
+        return running;
+    }
+    markTaskRunning(taskId, abort) {
+        const task = this.activeTasks.get(taskId);
+        if (!task)
+            return null;
+        if (task.cancelled)
+            return task;
+        task.status = 'running';
+        task.abort = abort || null;
+        task.steer = null;
+        task.freezePreviewOnAbort = false;
+        return task;
+    }
+    registerTaskPlaceholders(taskId, messageIds) {
+        const task = this.activeTasks.get(taskId);
+        if (!task)
+            return;
+        if (!task.placeholderMessageIds)
+            task.placeholderMessageIds = [];
+        for (const messageId of messageIds) {
+            if (messageId == null)
+                continue;
+            if (!task.placeholderMessageIds.includes(messageId))
+                task.placeholderMessageIds.push(messageId);
+        }
+    }
+    isSourceMessageWithdrawn(chatId, sourceMessageId) {
+        return this.withdrawnSourceMessages.has(this.sourceMessageKey(chatId, sourceMessageId));
+    }
+    actionIdForTask(taskId) {
+        return this.activeTasks.get(taskId)?.actionId || null;
+    }
+    withdrawQueuedTaskBySourceMessage(chatId, sourceMessageId) {
+        const sourceKey = this.sourceMessageKey(chatId, sourceMessageId);
+        this.withdrawnSourceMessages.add(sourceKey);
+        const taskId = this.taskKeysBySourceMessage.get(sourceKey);
+        if (!taskId)
+            return null;
+        const task = this.activeTasks.get(taskId);
+        if (!task || task.status !== 'queued')
+            return null;
+        task.cancelled = true;
+        return task;
+    }
+    stopTasksForSession(sessionKey) {
+        const session = this.getSessionRuntimeByKey(sessionKey, { allowAnyWorkdir: true });
+        if (!session)
+            return { interrupted: false, cancelledQueued: 0 };
+        let interrupted = false;
+        for (const taskId of session.runningTaskIds) {
+            const task = this.activeTasks.get(taskId);
+            if (!task)
+                continue;
+            if (!interrupted && task.status === 'running') {
+                interrupted = true;
+                task.cancelled = true;
+                try {
+                    task.abort?.();
+                }
+                catch { }
+            }
+        }
+        return { interrupted, cancelledQueued: 0 };
+    }
+    stopTaskByActionId(actionId) {
+        const taskId = this.taskKeysByActionId.get(String(actionId));
+        if (!taskId)
+            return { task: null, interrupted: false, cancelled: false };
+        const task = this.activeTasks.get(taskId) || null;
+        if (!task)
+            return { task: null, interrupted: false, cancelled: false };
+        if (task.status === 'queued') {
+            task.cancelled = true;
+            return { task, interrupted: false, cancelled: true };
+        }
+        if (task.status === 'running') {
+            try {
+                task.abort?.();
+            }
+            catch { }
+            return { task, interrupted: true, cancelled: false };
+        }
+        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)
+                t.deferForSteer = false;
+        }
+        const targetIdx = queuedIds.indexOf(targetTaskId);
+        for (let i = 0; i < targetIdx; i++) {
+            const t = this.activeTasks.get(queuedIds[i]);
+            if (t && t.status === 'queued' && !t.cancelled)
+                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)
+            return { task: null, interrupted: false, steered: false };
+        const task = this.activeTasks.get(taskId) || null;
+        if (!task || task.status !== 'queued')
+            return { task, interrupted: false, steered: false };
+        this.markQueueDeferralsForSteer(taskId);
+        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)
+            return false;
+        for (const taskId of session.runningTaskIds) {
+            const task = this.activeTasks.get(taskId);
+            if (!task || task.status !== 'running')
+                continue;
+            task.freezePreviewOnAbort = !!opts.freezePreview;
+            try {
+                task.abort?.();
+            }
+            catch { }
+            return true;
+        }
+        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)
+            return 0;
+        let ahead = 0;
+        for (const otherId of session.runningTaskIds) {
+            if (otherId === taskId)
+                continue;
+            const other = this.activeTasks.get(otherId);
+            if (!other || other.cancelled)
+                continue;
+            if (other.status === 'running' || other.status === 'queued')
+                ahead++;
+        }
+        return ahead;
+    }
+    sourceMessageKey(chatId, sourceMessageId) {
+        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;
+                }
+            }
+            return await task();
+        };
+        const prev = this.sessionChains.get(session.key) || Promise.resolve();
+        const current = prev.catch(() => { }).then(runner);
+        const settled = current.then(() => { }, () => { });
+        const chained = settled.finally(() => {
+            if (this.sessionChains.get(session.key) === chained)
+                this.sessionChains.delete(session.key);
+        });
+        this.sessionChains.set(session.key, chained);
+        return current;
+    }
+    sessionHasPendingWork(session) {
+        return this.sessionChains.has(session.key);
+    }
+    beginHumanLoopPrompt(opts) {
+        const promptId = `h${(this.nextHumanLoopPromptId++).toString(36)}`;
+        let resolvePrompt;
+        let rejectPrompt;
+        const result = new Promise((resolve, reject) => {
+            resolvePrompt = resolve;
+            rejectPrompt = reject;
+        });
+        const answers = {};
+        for (const question of opts.questions)
+            answers[question.id] = createEmptyHumanLoopAnswer();
+        const prompt = {
+            promptId,
+            taskId: opts.taskId,
+            chatId: opts.chatId,
+            title: opts.title,
+            detail: opts.detail ?? null,
+            hint: opts.hint ?? null,
+            questions: opts.questions,
+            currentIndex: 0,
+            answers,
+            resolveWith: opts.resolveWith,
+            resolve: resolvePrompt,
+            reject: rejectPrompt,
+            messageIds: [],
+            silent: opts.silent,
+        };
+        this.humanLoopPrompts.set(promptId, prompt);
+        const chatKey = String(opts.chatId);
+        const promptIds = this.humanLoopPromptIdsByChat.get(chatKey) || [];
+        promptIds.push(promptId);
+        this.humanLoopPromptIdsByChat.set(chatKey, promptIds);
+        return { prompt, result };
+    }
+    pendingHumanLoopPrompt(chatId) {
+        const promptIds = this.humanLoopPromptIdsByChat.get(String(chatId)) || [];
+        for (let i = promptIds.length - 1; i >= 0; i--) {
+            const prompt = this.humanLoopPrompts.get(promptIds[i]) || null;
+            if (prompt && isHumanLoopAwaitingText(prompt))
+                return prompt;
+        }
+        const promptId = promptIds[promptIds.length - 1];
+        return promptId ? (this.humanLoopPrompts.get(promptId) || null) : null;
+    }
+    registerHumanLoopMessage(promptId, messageId) {
+        if (messageId == null)
+            return;
+        const prompt = this.humanLoopPrompts.get(promptId);
+        if (!prompt)
+            return;
+        if (!prompt.messageIds.includes(messageId))
+            prompt.messageIds.push(messageId);
+    }
+    resolveHumanLoopPrompt(promptId) {
+        const prompt = this.humanLoopPrompts.get(promptId) || null;
+        if (!prompt)
+            return null;
+        this.humanLoopPrompts.delete(promptId);
+        this.removeHumanLoopPromptFromChat(prompt.chatId, promptId);
+        prompt.resolve(buildHumanLoopResponse(prompt));
+        this.emitInteractionResolved(prompt.taskId, promptId);
+        this.fireInteractionAnswered(prompt, 'answered');
+        return prompt;
+    }
+    clearHumanLoopPrompt(promptId, error) {
+        const prompt = this.humanLoopPrompts.get(promptId) || null;
+        if (!prompt)
+            return null;
+        this.humanLoopPrompts.delete(promptId);
+        this.removeHumanLoopPromptFromChat(prompt.chatId, promptId);
+        if (error)
+            prompt.reject(error);
+        this.emitInteractionResolved(prompt.taskId, promptId);
+        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;
+        if (prompt.chatId === 'dashboard')
+            return;
+        const summary = summarizeResolvedHumanLoopAnswers(prompt, status);
+        void Promise.resolve()
+            .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);
+        if (task)
+            this.emitStream(task.sessionKey, { type: 'interaction-resolved', promptId });
+    }
+    humanLoopSelectOption(promptId, optionValue, opts = {}) {
+        const prompt = this.humanLoopPrompts.get(promptId) || null;
+        if (!prompt)
+            return null;
+        const result = setHumanLoopOption(prompt, optionValue, opts);
+        if (result.completed)
+            this.resolveHumanLoopPrompt(promptId);
+        return { prompt, ...result };
+    }
+    humanLoopSkip(promptId) {
+        const prompt = this.humanLoopPrompts.get(promptId) || null;
+        if (!prompt)
+            return null;
+        const result = skipHumanLoopQuestion(prompt);
+        if (result.completed)
+            this.resolveHumanLoopPrompt(promptId);
+        return { prompt, ...result };
+    }
+    humanLoopSubmitText(chatId, text) {
+        const prompt = this.pendingHumanLoopPrompt(chatId);
+        if (!prompt)
+            return null;
+        if (!isHumanLoopAwaitingText(prompt))
+            return null;
+        const result = setHumanLoopText(prompt, text);
+        if (result.completed)
+            this.resolveHumanLoopPrompt(prompt.promptId);
+        return { prompt, ...result };
+    }
+    humanLoopCancel(promptId, reason = 'Prompt cancelled.') {
+        return this.clearHumanLoopPrompt(promptId, new Error(reason));
+    }
+    humanLoopCurrentQuestion(promptId) {
+        const prompt = this.humanLoopPrompts.get(promptId);
+        return prompt ? currentHumanLoopQuestion(prompt) : null;
+    }
+    humanLoopPrompt(promptId) {
+        return this.humanLoopPrompts.get(promptId) || null;
+    }
+    removeHumanLoopPromptFromChat(chatId, promptId) {
+        const chatKey = String(chatId);
+        const promptIds = this.humanLoopPromptIdsByChat.get(chatKey) || [];
+        const next = promptIds.filter(id => id !== promptId);
+        if (next.length)
+            this.humanLoopPromptIdsByChat.set(chatKey, next);
+        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({
+                taskId,
+                chatId,
+                title: request.title,
+                hint: request.hint,
+                questions: request.questions,
+                resolveWith: request.resolveWith,
+            });
+            const interactionSnapshot = {
+                promptId: active.prompt.promptId,
+                kind: request.kind,
+                title: request.title,
+                hint: request.hint,
+                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);
+                }
+                catch (error) {
+                    this.humanLoopCancel(active.prompt.promptId, error?.message || 'Failed to send prompt.');
+                    throw error;
+                }
+            }
+            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;
+        const hasOptions = !!question.options?.length;
+        const freeformAllowed = !hasOptions || question.allowFreeform !== false;
+        if (!freeformAllowed && !isHumanLoopAwaitingText(prompt))
+            return null;
+        const result = setHumanLoopText(prompt, text);
+        if (result.completed)
+            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);
+    }
+    selectedSession(chatId) {
+        return this.getSelectedSession(this.chat(chatId));
+    }
+    submitSessionTask(opts) {
+        const session = this.upsertSessionRuntime({
+            agent: opts.agent,
+            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 } : {}),
+        });
+        const taskId = `ext-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        const prompt = opts.prompt.trim();
+        const attachments = opts.attachments || [];
+        const chatId = opts.chatId ?? 'dashboard';
+        this.beginTask({
+            taskId,
+            chatId,
+            agent: session.agent,
+            sessionKey: session.key,
+            prompt,
+            attachments,
+            startedAt: Date.now(),
+            sourceMessageId: opts.sourceMessageId ?? taskId,
+        });
+        this.emitStreamQueued(session.key, taskId);
+        void this.queueSessionTask(session, async () => {
+            const abortController = new AbortController();
+            const task = this.markTaskRunning(taskId, () => abortController.abort());
+            if (task?.cancelled) {
+                this.emitStreamCancelled(taskId, session.key);
+                this.finishTask(taskId);
+                return;
+            }
+            this.emitStreamStart(taskId, session);
+            // 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,
+                }).catch(err => {
+                    this.warn(`[submitSessionTask] presenter setup failed task=${taskId}: ${err?.message || err}`);
+                    return null;
+                })
+                : null;
+            try {
+                const result = await this.runStream(prompt, session, attachments, (text, thinking, activity, meta, plan) => {
+                    opts.onText?.(text, thinking, activity, meta, plan);
+                    presenter?.onText(text, thinking, activity, meta, plan);
+                    this.emitStreamText(taskId, session.key, text, thinking, activity, meta, plan);
+                }, undefined, undefined, abortController.signal, this.createInteractionHandler(chatId, taskId), undefined, undefined, (opts.forkOf || opts.workflowEnabled !== undefined)
+                    ? { ...(opts.forkOf ? { forkOf: opts.forkOf } : {}), ...(opts.workflowEnabled !== undefined ? { workflowEnabled: opts.workflowEnabled } : {}) }
+                    : undefined);
+                this.emitStreamDone(taskId, session.key, {
+                    sessionId: result.sessionId || session.sessionId,
+                    incomplete: !!result.incomplete,
+                    ...(result.ok ? {} : { error: result.error || result.message }),
+                });
+                if (presenter) {
+                    try {
+                        await presenter.onSuccess(result);
+                    }
+                    catch (e) {
+                        this.warn(`[submitSessionTask] presenter onSuccess failed task=${taskId}: ${e?.message || e}`);
+                    }
+                }
+                try {
+                    this.maybeEnqueueGoalContinuation(session, opts, result);
+                }
+                catch (err) {
+                    this.debug(`[goal-continuation] enqueue failed: ${err?.message || err}`);
+                }
+            }
+            catch (error) {
+                const errMsg = error?.message || String(error);
+                this.emitStreamDone(taskId, session.key, {
+                    sessionId: session.sessionId,
+                    incomplete: true,
+                    error: errMsg,
+                });
+                if (presenter) {
+                    try {
+                        await presenter.onFailure(errMsg);
+                    }
+                    catch (e) {
+                        this.warn(`[submitSessionTask] presenter onFailure failed task=${taskId}: ${e?.message || e}`);
+                    }
+                }
+            }
+            finally {
+                presenter?.dispose();
+                this.finishTask(taskId);
+                this.syncSelectedChats(session);
+            }
+        }, taskId).catch(error => {
+            this.finishTask(taskId);
+            this.error(`[submitSessionTask] queue failed task=${taskId} error=${error?.message || error}`);
+        });
+        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 pikiloop 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 pikiloop's goal.json.
+     */
+    maybeEnqueueGoalContinuation(session, opts, result) {
+        if (session.agent === 'codex' || session.agent === 'claude')
+            return;
+        const sessionId = (result.sessionId || session.sessionId || '').trim();
+        if (!sessionId || isPendingSessionId(sessionId))
+            return;
+        const workdir = session.workdir;
+        const agent = session.agent;
+        const goalBefore = readGoal(workdir, agent, sessionId);
+        if (!goalBefore)
+            return;
+        if (!result.ok || result.incomplete) {
+            if (opts.goalContinuation && goalBefore.status === 'active') {
+                pauseGoal(workdir, agent, sessionId);
+                this.debug(`[goal-continuation] paused goal=${goalBefore.goalId} after failed continuation`);
+            }
+            return;
+        }
+        if (goalBefore.status !== 'active')
+            return;
+        const usedTokens = Math.max(0, (result.inputTokens || 0) + (result.outputTokens || 0));
+        const seconds = Math.max(0, Math.floor(result.elapsedS || 0));
+        const { goal, budgetJustCrossed } = accountTurn(workdir, agent, sessionId, {
+            tokens: usedTokens,
+            seconds,
+        });
+        if (!goal)
+            return;
+        if (budgetJustCrossed) {
+            const prompt = renderBudgetLimitPrompt(goal);
+            this.debug(`[goal-continuation] budget exhausted goal=${goal.goalId} — enqueue wrap-up turn`);
+            this.submitSessionTask({
+                agent,
+                sessionId,
+                workdir,
+                prompt,
+                chatId: opts.chatId,
+                modelId: opts.modelId,
+                thinkingEffort: opts.thinkingEffort,
+                goalContinuation: { kind: 'budget_wrapup', goalId: goal.goalId },
+            });
+            return;
+        }
+        const decision = shouldContinueAfterTurn(goal);
+        if (!decision.shouldContinue) {
+            this.debug(`[goal-continuation] stop goal=${goal.goalId} reason=${decision.reason}`);
+            return;
+        }
+        const updated = bumpContinuationCount(workdir, agent, sessionId);
+        if (!updated)
+            return;
+        const prompt = renderContinuationPrompt(updated);
+        this.debug(`[goal-continuation] continue goal=${updated.goalId} count=${updated.continuationCount} tokens=${updated.tokensUsed}/${updated.tokenBudget ?? '∞'}`);
+        this.submitSessionTask({
+            agent,
+            sessionId,
+            workdir,
+            prompt,
+            chatId: opts.chatId,
+            modelId: opts.modelId,
+            thinkingEffort: opts.thinkingEffort,
+            goalContinuation: { kind: 'continuation', goalId: updated.goalId },
+        });
+    }
+    /**
+     * Normalized goal view used by IM/dashboard renderers — same shape regardless
+     * of whether the source is pikiloop'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))
+                return null;
+            const goal = await getCodexGoal(sessionId);
+            return goal ? normalizeFromCodex(goal) : null;
+        }
+        if (agent === 'claude') {
+            if (!sessionId || isPendingSessionId(sessionId))
+                return null;
+            const goal = getClaudeNativeGoal(workdir, sessionId);
+            return goal ? normalizeFromClaudeNative(goal) : null;
+        }
+        const goal = readGoal(workdir, agent, sessionId);
+        return goal ? normalizeFromPikiloop(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, pikiloop 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)) {
+                throw new Error('codex session must exist before /goal — send a first message to create the thread');
+            }
+            const resp = await setCodexGoal({
+                threadId: sessionId,
+                objective: opts.objective,
+                status: 'active',
+                tokenBudget: opts.tokenBudget ?? null,
+            });
+            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');
+            return normalizeFromCodex(goal);
+        }
+        if (agent === 'claude') {
+            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). pikiloop
+            // 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');
+            this.submitSessionTask({
+                agent,
+                sessionId,
+                workdir,
+                prompt: buildClaudeSetGoalPrompt(objective),
+                chatId: opts.chatId,
+                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',
+                met: false,
+                updatedAtMs: Date.now(),
+            });
+        }
+        const goal = setGoalState(workdir, agent, sessionId, {
+            objective: opts.objective,
+            tokenBudget: opts.tokenBudget ?? null,
+        });
+        if (!isPendingSessionId(sessionId)) {
+            const prompt = renderContinuationPrompt(goal);
+            this.submitSessionTask({
+                agent,
+                sessionId,
+                workdir,
+                prompt,
+                chatId: opts.chatId,
+                modelId: opts.modelId,
+                thinkingEffort: opts.thinkingEffort,
+                goalContinuation: { kind: 'continuation', goalId: goal.goalId },
+            });
+        }
+        return normalizeFromPikiloop(goal);
+    }
+    async pauseSessionGoal(workdir, agent, sessionId) {
+        if (agent === 'codex') {
+            if (!sessionId || isPendingSessionId(sessionId))
+                return null;
+            const resp = await pauseCodexGoal(sessionId);
+            if (!resp.ok)
+                throw new Error(resp.error);
+            const goal = resp.goal ?? (await getCodexGoal(sessionId));
+            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);
+        return goal ? normalizeFromPikiloop(goal) : null;
+    }
+    async resumeSessionGoal(workdir, agent, sessionId, opts = {}) {
+        if (agent === 'codex') {
+            if (!sessionId || isPendingSessionId(sessionId))
+                return null;
+            const resp = await resumeCodexGoal(sessionId);
+            if (!resp.ok)
+                throw new Error(resp.error);
+            const goal = resp.goal ?? (await getCodexGoal(sessionId));
+            return goal ? normalizeFromCodex(goal) : null;
+        }
+        if (agent === 'claude') {
+            throw new Error('Claude native /goal does not support pause/resume — re-issue `/goal <objective>` to start fresh.');
+        }
+        const goal = resumeGoal(workdir, agent, sessionId);
+        if (!goal || goal.status !== 'active')
+            return goal ? normalizeFromPikiloop(goal) : null;
+        if (!isPendingSessionId(sessionId)) {
+            const prompt = renderContinuationPrompt(goal);
+            this.submitSessionTask({
+                agent,
+                sessionId,
+                workdir,
+                prompt,
+                chatId: opts.chatId,
+                modelId: opts.modelId,
+                thinkingEffort: opts.thinkingEffort,
+                goalContinuation: { kind: 'continuation', goalId: goal.goalId },
+            });
+        }
+        return normalizeFromPikiloop(goal);
+    }
+    async clearSessionGoal(workdir, agent, sessionId, opts = {}) {
+        if (agent === 'codex') {
+            if (!sessionId || isPendingSessionId(sessionId))
+                return;
+            const resp = await clearCodexGoal(sessionId);
+            if (!resp.ok)
+                throw new Error(resp.error);
+            return;
+        }
+        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;
+            this.submitSessionTask({
+                agent,
+                sessionId,
+                workdir,
+                prompt: buildClaudeClearGoalPrompt(),
+                chatId: opts.chatId,
+                modelId: opts.modelId,
+                thinkingEffort: opts.thinkingEffort,
+            });
+            return;
+        }
+        clearGoalState(workdir, agent, sessionId);
+    }
+    cancelTask(taskId) {
+        const task = this.activeTasks.get(taskId) || null;
+        if (!task)
+            return { task: null, interrupted: false, cancelled: false };
+        if (task.status === 'queued') {
+            task.cancelled = true;
+            this.emitStream(task.sessionKey, { type: 'cancelled', taskId });
+            return { task, interrupted: false, cancelled: true };
+        }
+        if (task.status === 'running') {
+            task.cancelled = true;
+            try {
+                task.abort?.();
+            }
+            catch { }
+            return { task, interrupted: true, cancelled: false };
+        }
+        return { task, interrupted: false, cancelled: false };
+    }
+    async steerTask(taskId) {
+        const task = this.activeTasks.get(taskId) || null;
+        if (!task || task.status !== 'queued')
+            return { task, interrupted: false, steered: false };
+        this.markQueueDeferralsForSteer(taskId);
+        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);
+    }
+    adoptExistingSessionForChat(chatId, session) {
+        const cs = this.chat(chatId);
+        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) {
+            this.switchModelForChat(chatId, session.model, session.profileId ?? null);
+        }
+        else if (session.profileId !== undefined) {
+            this.switchModelForChat(chatId, this.modelForAgent(session.agent), null);
+        }
+        if (session.thinkingEffort) {
+            this.switchEffortForChat(chatId, session.thinkingEffort);
+        }
+        return runtime;
+    }
+    switchAgentForChat(chatId, agent) {
+        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;
+            this.applySessionSelection(cs, resumed);
+            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 };
+        }
+        this.resetChatConversation(cs, { clearThread: false });
+        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);
+        }
+        this.setModelForAgent(cs.agent, modelId);
+        cs.modelId = modelId;
+        const session = this.getSelectedSession(cs);
+        if (session)
+            session.modelId = modelId;
+        this.persistAgentPreference(cs.agent, 'model', modelId);
+        const profileTag = profileId === undefined
+            ? ''
+            : profileId
+                ? ` profile=${profileId}`
+                : ' 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);
+        const session = this.getSelectedSession(cs);
+        if (session)
+            session.thinkingEffort = realEffort;
+        this.persistAgentPreference(cs.agent, 'effort', realEffort);
+        if (getDriverCapabilities(cs.agent).workflow) {
+            this.setWorkflowEnabledForAgent(cs.agent, ultra);
+            this.persistAgentPreference(cs.agent, 'workflow', ultra ? '1' : '0');
+        }
+        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)
+            return null;
+        if (getDriverCapabilities(agent).workflow && this.workflowEnabledForAgent(agent))
+            return 'ultra';
+        return effort;
+    }
+    switchPermissionModeForChat(chatId, mode) {
+        const cs = this.chat(chatId);
+        if (cs.agent === 'claude') {
+            this.agentConfigs.claude.permissionMode = mode;
+            this.resetChatConversation(cs);
+            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) {
+            this.log(`workflow toggle ignored: ${cs.agent} does not support orchestration`);
+            return;
+        }
+        this.setWorkflowEnabledForAgent(cs.agent, enabled);
+        this.persistAgentPreference(cs.agent, 'workflow', enabled ? '1' : '0');
+        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)
+                return bound;
+        }
+        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) {
+        const agentConfig = this.agentConfigs[cs.agent] || {};
+        const sessionWorkdir = cs.workdir || this.workdir;
+        const storedConfig = cs.sessionId && !isPendingSessionId(cs.sessionId)
+            ? getSessionStoredConfig(sessionWorkdir, cs.agent, cs.sessionId)
+            : null;
+        const model = (cs.modelId && cs.modelId.trim())
+            || (storedConfig?.model || '')
+            || this.modelForAgent(cs.agent)
+            || null;
+        const effortRaw = (cs.thinkingEffort && cs.thinkingEffort.trim().toLowerCase())
+            || (storedConfig?.thinkingEffort || '')
+            || agentConfig.reasoningEffort
+            || 'high';
+        const effort = cs.agent === 'gemini' ? null : (effortRaw || null);
+        return { model: model || null, effort };
+    }
+    fetchSessions(agent, workdir) {
+        return querySessions({ agent, workdir: workdir || this.workdir });
+    }
+    fetchSessionTail(agent, sessionId, limit, workdir = this.workdir) {
+        return querySessionTail({ agent, sessionId, workdir, limit });
+    }
+    fetchAgents(options = {}) {
+        return listAgents(options);
+    }
+    fetchSkills(workdir) {
+        const wd = workdir || this.workdir;
+        initializeProjectSkills(wd);
+        return listSkills(wd);
+    }
+    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) {
+        const next = normalizeAgent(agent);
+        const prev = this.defaultAgent;
+        this.defaultAgent = next;
+        for (const [, cs] of this.chats) {
+            if (cs.activeSessionKey || cs.sessionId)
+                continue;
+            if (cs.agent === prev)
+                cs.agent = next;
+        }
+        this.log(`default agent changed to ${next}`);
+    }
+    setModelForAgent(agent, modelId) {
+        const config = this.agentConfigs[agent];
+        if (config)
+            config.model = modelId;
+        this.log(`model for ${agent} changed to ${modelId}`);
+    }
+    effortForAgent(agent) {
+        return this.agentConfigs[agent]?.reasoningEffort || 'high';
+    }
+    setEffortForAgent(agent, effort) {
+        const config = this.agentConfigs[agent];
+        if (config)
+            config.reasoningEffort = effort;
+        this.log(`effort for ${agent} changed to ${effort}`);
+    }
+    workflowEnabledForAgent(agent) {
+        return this.agentConfigs[agent]?.workflowEnabled ?? false;
+    }
+    setWorkflowEnabledForAgent(agent, enabled) {
+        const config = this.agentConfigs[agent];
+        if (config)
+            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)
+            config.accessMode = mode;
+        this.log(`claude access mode changed to ${mode}`);
+    }
+    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' });
+                return;
+            }
+            const patch = {};
+            if (kind === 'model') {
+                if (agent === 'claude')
+                    patch.claudeModel = value;
+                else if (agent === 'codex')
+                    patch.codexModel = value;
+                else if (agent === 'gemini')
+                    patch.geminiModel = value;
+                else if (agent === 'hermes')
+                    patch.hermesModel = value;
+            }
+            else {
+                if (agent === 'claude')
+                    patch.claudeReasoningEffort = value;
+                else if (agent === 'codex')
+                    patch.codexReasoningEffort = value;
+                else if (agent === 'gemini')
+                    patch.geminiReasoningEffort = value;
+                else if (agent === 'hermes')
+                    patch.hermesReasoningEffort = value;
+            }
+            if (Object.keys(patch).length)
+                updateUserConfig(patch);
+        }
+        catch (e) {
+            this.warn(`persistAgentPreference failed: ${e?.message || e}`);
+        }
+    }
+    getStatusData(chatId) {
+        const cs = this.chat(chatId);
+        const selectedSession = this.getSelectedSession(cs);
+        const selectedTask = this.runningTaskForSession(selectedSession?.key ?? null);
+        const fallbackTask = selectedTask || [...this.activeTasks.values()]
+            .sort((a, b) => a.startedAt - b.startedAt)[0] || null;
+        const model = selectedSession?.modelId || this.modelForAgent(cs.agent);
+        const mem = process.memoryUsage();
+        return {
+            version: VERSION, uptime: Date.now() - this.startedAt,
+            memRss: mem.rss, memHeap: mem.heapUsed, pid: process.pid,
+            workdir: this.chatWorkdir(chatId), agent: cs.agent, model, sessionId: cs.sessionId,
+            workspacePath: cs.workspacePath ?? null,
+            running: fallbackTask, activeTasksCount: this.activeTasks.size, stats: this.stats,
+            usage: getUsage({ agent: cs.agent, model }),
+        };
+    }
+    getHostData() {
+        const cpus = os.cpus();
+        const totalMem = os.totalmem(), freeMem = os.freemem();
+        const memory = getHostMemoryUsageData(totalMem, freeMem);
+        const cpuUsage = getHostCpuUsageData();
+        const [loadOne, loadFive, loadFifteen] = os.loadavg();
+        let disk = null;
+        const battery = getHostBatteryData();
+        try {
+            if (process.platform === 'win32') {
+                const driveLetter = this.workdir.charAt(0).toUpperCase();
+                const psOut = execSync(`powershell -NoProfile -Command "Get-PSDrive -Name ${driveLetter} | ForEach-Object { [PSCustomObject]@{Used=$_.Used;Free=$_.Free} } | ConvertTo-Json"`, { encoding: 'utf-8', timeout: 5000 }).trim();
+                const info = JSON.parse(psOut);
+                if (info.Used != null && info.Free != null) {
+                    const used = Number(info.Used), free = Number(info.Free), total = used + free;
+                    const fmt = (b) => b >= 1e12 ? `${(b / 1e12).toFixed(1)}T` : b >= 1e9 ? `${(b / 1e9).toFixed(1)}G` : b >= 1e6 ? `${(b / 1e6).toFixed(1)}M` : `${Math.round(b / 1e3)}K`;
+                    disk = { used: fmt(used), total: fmt(total), percent: `${Math.round(used / total * 100)}%` };
+                }
+            }
+            else {
+                const df = execSync(`df -h "${this.workdir}" | tail -1`, { encoding: 'utf-8', timeout: 3000 }).trim().split(/\s+/);
+                if (df.length >= 5)
+                    disk = { used: df[2], total: df[1], percent: df[4] };
+            }
+        }
+        catch { }
+        let topProcs = [];
+        try {
+            if (process.platform === 'win32') {
+                topProcs = execSync(`powershell -NoProfile -Command "Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 5 | ForEach-Object { \\"$($_.Id) $([math]::Round($_.CPU)) $([math]::Round($_.WorkingSet64/1MB)) $($_.ProcessName)\\"" }"`, { encoding: 'utf-8', timeout: 5000 }).trim().split('\n');
+            }
+            else {
+                topProcs = execSync(`ps -eo pid,pcpu,pmem,comm --sort=-pcpu 2>/dev/null | head -6 || ps -eo pid,%cpu,%mem,comm -r 2>/dev/null | head -6`, { encoding: 'utf-8', timeout: 3000 }).trim().split('\n');
+            }
+        }
+        catch { }
+        const mem = process.memoryUsage();
+        return {
+            hostName: getHostDisplayName(),
+            cpuModel: cpus[0]?.model || 'unknown', cpuCount: cpus.length,
+            cpuUsage,
+            loadAverage: { one: loadOne, five: loadFive, fifteen: loadFifteen },
+            totalMem, freeMem, memoryUsed: memory.usedBytes, memoryAvailable: memory.availableBytes, memoryPercent: memory.percent, memorySource: memory.source,
+            disk, battery, topProcs,
+            selfPid: process.pid, selfRss: mem.rss, selfHeap: mem.heapUsed,
+        };
+    }
+    switchWorkdir(newPath, opts = {}) {
+        const old = this.workdir;
+        const resolvedPath = path.resolve(expandTilde(newPath));
+        if (opts.persist !== false) {
+            setUserWorkdir(resolvedPath, { notify: false });
+        }
+        else {
+            process.env.PIKILOOP_WORKDIR = resolvedPath;
+        }
+        this.workdir = resolvedPath;
+        for (const [, cs] of this.chats) {
+            this.resetChatConversation(cs, { clearWorkdir: true });
+        }
+        for (const [key, session] of this.sessionStates) {
+            if (session.workdir === old && !session.runningTaskIds.size)
+                this.sessionStates.delete(key);
+        }
+        ensureGitignore(resolvedPath);
+        initializeProjectSkills(resolvedPath);
+        this.log(`switch workdir: ${old} -> ${resolvedPath}`);
+        this.afterSwitchWorkdir(old, resolvedPath);
+        return old;
+    }
+    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 pikiloop 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];
+        try {
+            for (const ws of loadWorkspaces())
+                candidates.push(ws.path);
+        }
+        catch { }
+        for (const candidate of candidates) {
+            const resolved = path.resolve(candidate);
+            if (seen.has(resolved))
+                continue;
+            seen.add(resolved);
+            try {
+                reconcileOrphanedRunningSessions(resolved);
+            }
+            catch { }
+        }
+    }
+    refreshManagedConfig(config, opts = {}) {
+        const nextWorkdir = resolveUserWorkdir({ config });
+        if (opts.initial) {
+            this.workdir = nextWorkdir;
+            ensureGitignore(this.workdir);
+            initializeProjectSkills(this.workdir);
+            this.reconcileStaleRunningSessions();
+        }
+        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;
+        else if (nextDefaultAgent !== this.defaultAgent)
+            this.setDefaultAgent(nextDefaultAgent);
+        for (const agent of ['claude', 'codex', 'gemini', 'hermes']) {
+            const nextModel = resolveAgentModel(config, agent);
+            if (nextModel && this.modelForAgent(agent) !== nextModel) {
+                if (opts.initial)
+                    this.agentConfigs[agent].model = nextModel;
+                else
+                    this.setModelForAgent(agent, nextModel);
+            }
+            const nextEffort = resolveAgentEffort(config, agent);
+            if (nextEffort && this.effortForAgent(agent) !== nextEffort) {
+                if (opts.initial)
+                    this.agentConfigs[agent].reasoningEffort = nextEffort;
+                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) {
+                    if (opts.initial)
+                        this.agentConfigs.claude.accessMode = nextAccessMode;
+                    else
+                        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)
+            : null;
+        const resolvedModel = cs.modelId || storedConfig?.model || this.modelForAgent(cs.agent);
+        const resolvedThinkingEffort = ('thinkingEffort' in cs && typeof cs.thinkingEffort === 'string' && cs.thinkingEffort.trim())
+            ? cs.thinkingEffort.trim().toLowerCase()
+            : (storedConfig?.thinkingEffort || agentConfig.reasoningEffort || 'high');
+        const extraArgs = agentConfig.extraArgs || [];
+        const browserEnabled = resolveGuiIntegrationConfig(getActiveUserConfig()).browserEnabled;
+        const sessionWorkdir = 'workdir' in cs && typeof cs.workdir === 'string' && cs.workdir
+            ? path.resolve(cs.workdir)
+            : this.workdir;
+        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 {
+                const result = await compactForHandover({
+                    fromAgent: handoverFrom.agent,
+                    fromSessionId: handoverFrom.sessionId,
+                    workdir: sessionWorkdir,
+                    toAgent: cs.agent,
+                    toModel: resolvedModel,
+                });
+                if (result.ok && result.seed) {
+                    prompt = result.seed + '\n\n' + prompt;
+                    this.debug(`[runStream] handover ${describeHandoverRef(handoverFrom)} → ${cs.agent} `
+                        + `mode=${result.mode} msgs=${result.messagesIncluded}/${result.messagesTotal} `
+                        + `turnsTotal=${result.turnsTotal} chars=${result.charsIncluded}/${result.budgetChars}`);
+                }
+                else {
+                    this.warn(`[runStream] handover ${describeHandoverRef(handoverFrom)} → ${cs.agent} `
+                        + `failed (${result.error || 'unknown'}); proceeding without prior context`);
+                }
+            }
+            catch (e) {
+                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);
+        const mcpSystemPrompt = appendExtraPrompt(appendExtraPrompt(appendExtraPrompt(mcpSendFile ? 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 effectiveSystemPrompt = isFirstTurnOfSession
+            ? appendExtraPrompt(systemPrompt, mcpSystemPrompt)
+            : (mcpSystemPrompt || undefined);
+        const syncNativeSessionId = (nativeSessionId) => {
+            const resolvedSessionId = nativeSessionId.trim();
+            if (!resolvedSessionId)
+                return;
+            if ('key' in cs && typeof cs.key === 'string') {
+                const runtime = this.getSessionRuntimeByKey(cs.key, { allowAnyWorkdir: true });
+                if (runtime) {
+                    this.promoteSessionRuntime(runtime, resolvedSessionId);
+                    return;
+                }
+            }
+            cs.sessionId = resolvedSessionId;
+        };
+        const opts = {
+            agent: cs.agent, prompt, workdir: sessionWorkdir, timeout: this.runTimeout,
+            sessionId: cs.sessionId, model: null,
+            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,
+            abortSignal,
+            onInteraction,
+            onSteerReady,
+            onCodexTurnReady,
+            // Fork lineage — when set, the driver branches off the parent session.
+            forkOf: extras?.forkOf,
+        };
+        const result = await doStream(opts);
+        this.stats.totalTurns++;
+        if (result.inputTokens)
+            this.stats.totalInputTokens += result.inputTokens;
+        if (result.outputTokens)
+            this.stats.totalOutputTokens += result.outputTokens;
+        if (result.cachedInputTokens)
+            this.stats.totalCachedTokens += result.cachedInputTokens;
+        if (result.codexCumulative)
+            cs.codexCumulative = result.codexCumulative;
+        if (result.sessionId)
+            syncNativeSessionId(result.sessionId);
+        if (result.workspacePath)
+            cs.workspacePath = result.workspacePath;
+        if (result.model)
+            cs.modelId = result.model;
+        if ('key' in cs && typeof cs.key === 'string') {
+            const runtime = this.getSessionRuntimeByKey(cs.key, { allowAnyWorkdir: true });
+            if (runtime)
+                this.syncSelectedChats(runtime);
+        }
+        this.debug(`[runStream] completed turn=${this.stats.totalTurns} cumulative: in=${fmtTokens(this.stats.totalInputTokens)} out=${fmtTokens(this.stats.totalOutputTokens)} cached=${fmtTokens(this.stats.totalCachedTokens)}`);
+        return result;
+    }
+    startKeepAlive() {
+        if (process.platform === 'darwin') {
+            if (this.keepAliveProc || this.keepAlivePulseTimer)
+                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})`);
+                const pulseUserActivity = () => {
+                    const pulse = spawn('caffeinate', ['-u', '-t', String(MACOS_USER_ACTIVITY_PULSE_TIMEOUT_S)], {
+                        stdio: 'ignore',
+                        detached: true,
+                    });
+                    pulse.unref();
+                };
+                pulseUserActivity();
+                this.keepAlivePulseTimer = setInterval(pulseUserActivity, MACOS_USER_ACTIVITY_PULSE_INTERVAL_MS);
+                this.keepAlivePulseTimer.unref?.();
+                this.log(`keep-alive: macOS user activity pulse every ${MACOS_USER_ACTIVITY_PULSE_INTERVAL_MS / 1000}s`);
+            }
+        }
+        else if (process.platform === 'linux') {
+            if (this.keepAliveProc)
+                return;
+            const bin = whichSync('systemd-inhibit');
+            if (bin) {
+                this.keepAliveProc = spawn('systemd-inhibit', [
+                    '--what=idle', '--who=pikiloop', '--why=AI coding agent running', 'sleep', 'infinity',
+                ], { stdio: 'ignore', detached: true });
+                this.keepAliveProc.unref();
+                this.log(`keep-alive: systemd-inhibit (PID ${this.keepAliveProc.pid})`);
+            }
+        }
+    }
+    stopKeepAlive() {
+        if (this.keepAlivePulseTimer) {
+            clearInterval(this.keepAlivePulseTimer);
+            this.keepAlivePulseTimer = null;
+        }
+        if (this.keepAliveProc) {
+            terminateProcessTree(this.keepAliveProc, { signal: 'SIGTERM', forceSignal: 'SIGKILL', forceAfterMs: 2000 });
+            this.keepAliveProc = null;
+        }
+    }
+}