cli-jaw 1.7.33 → 1.7.34

package/public/js/features/help-content.ts

@@ -0,0 +1,75 @@
+// Contextual help topic registry. Keep this module data-only so tests can import it safely.
+
+export type HelpTopicId =
+    | 'activeCli'
+    | 'model'
+    | 'effort'
+    | 'permissions'
+    | 'flushAgent'
+    | 'employees'
+    | 'skills'
+    | 'activeChannel'
+    | 'telegram'
+    | 'discord'
+    | 'fallbackOrder'
+    | 'mcp'
+    | 'memory'
+    | 'stt'
+    | 'promptTemplates';
+
+export interface HelpTopic {
+    titleKey: string;
+    introKey: string;
+    effectKey: string;
+    useWhenKeys: string[];
+    howToKeys: string[];
+    exampleKeys: string[];
+    avoidWhenKeys?: string[];
+    relatedKeys?: string[];
+}
+
+export const HELP_TOPICS: Record<HelpTopicId, HelpTopic> = {
+    activeCli: topic('activeCli', 2, 1, 2),
+    model: topic('model', 2, 1, 1),
+    effort: topic('effort', 2, 1, 1),
+    permissions: topic('permissions', 2, 1, 1),
+    flushAgent: topic('flushAgent', 2, 1, 1),
+    employees: topic('employees', 3, 3, 2),
+    skills: topic('skills', 2, 1, 1),
+    activeChannel: topic('activeChannel', 2, 1, 1),
+    telegram: topic('telegram', 2, 1, 2),
+    discord: topic('discord', 2, 1, 2),
+    fallbackOrder: topic('fallbackOrder', 2, 1, 1),
+    mcp: topic('mcp', 2, 1, 1),
+    memory: topic('memory', 2, 1, 2),
+    stt: topic('stt', 2, 1, 1),
+    promptTemplates: topic('promptTemplates', 2, 1, 1),
+};
+
+export function isHelpTopicId(value: string | null | undefined): value is HelpTopicId {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(HELP_TOPICS, value);
+}
+
+function topic(
+    id: HelpTopicId,
+    useCount: number,
+    avoidCount: number,
+    relatedCount: number,
+    howToCount = 2,
+    exampleCount = 1,
+): HelpTopic {
+    return {
+        titleKey: `help.${id}.title`,
+        introKey: `help.${id}.intro`,
+        effectKey: `help.${id}.effect`,
+        useWhenKeys: rangeKeys(`help.${id}.use`, useCount),
+        howToKeys: rangeKeys(`help.${id}.howTo`, howToCount),
+        exampleKeys: rangeKeys(`help.${id}.example`, exampleCount),
+        avoidWhenKeys: rangeKeys(`help.${id}.avoid`, avoidCount),
+        relatedKeys: rangeKeys(`help.${id}.related`, relatedCount),
+    };
+}
+
+function rangeKeys(prefix: string, count: number): string[] {
+    return Array.from({ length: count }, (_, i) => `${prefix}.${i + 1}`);
+}

package/public/js/features/help-dialog.ts

@@ -0,0 +1,164 @@
+import { t } from './i18n.js';
+import { HELP_TOPICS, isHelpTopicId, type HelpTopic, type HelpTopicId } from './help-content.js';
+
+let initialized = false;
+let overlay: HTMLDivElement | null = null;
+let titleEl: HTMLSpanElement | null = null;
+let bodyEl: HTMLDivElement | null = null;
+let closeBtn: HTMLButtonElement | null = null;
+let lastOpener: HTMLElement | null = null;
+let openState = false;
+
+export function initHelpDialog(): void {
+    if (initialized) return;
+    initialized = true;
+    document.addEventListener('click', handleDocumentClick);
+    document.addEventListener('keydown', handleKeydownCapture, true);
+}
+
+export function openHelpDialog(topicId: HelpTopicId, opener: HTMLElement | null = null): void {
+    const topic = HELP_TOPICS[topicId];
+    if (!topic) {
+        console.warn('[help-dialog] unknown topic:', topicId);
+        return;
+    }
+    ensureDialog();
+    lastOpener = opener;
+    renderTopic(topic);
+    overlay?.classList.add('open');
+    overlay?.setAttribute('aria-hidden', 'false');
+    openState = true;
+    requestAnimationFrame(() => closeBtn?.focus());
+}
+
+export function closeHelpDialog(): void {
+    if (!openState) return;
+    overlay?.classList.remove('open');
+    overlay?.setAttribute('aria-hidden', 'true');
+    openState = false;
+    const opener = lastOpener;
+    lastOpener = null;
+    opener?.focus();
+}
+
+export function isHelpDialogOpen(): boolean {
+    return openState;
+}
+
+function handleDocumentClick(event: MouseEvent): void {
+    const trigger = (event.target as HTMLElement | null)?.closest('[data-help-topic]') as HTMLElement | null;
+    if (!trigger) return;
+    const topicId = trigger.getAttribute('data-help-topic');
+    if (!isHelpTopicId(topicId)) {
+        console.warn('[help-dialog] invalid topic:', topicId);
+        return;
+    }
+    event.preventDefault();
+    openHelpDialog(topicId, trigger);
+}
+
+function handleKeydownCapture(event: KeyboardEvent): void {
+    if (!openState || event.key !== 'Escape') return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    closeHelpDialog();
+}
+
+function ensureDialog(): void {
+    if (overlay && titleEl && bodyEl && closeBtn) return;
+
+    overlay = document.createElement('div');
+    overlay.id = 'helpDialog';
+    overlay.className = 'modal-overlay help-dialog-overlay';
+    overlay.setAttribute('role', 'presentation');
+    overlay.setAttribute('aria-hidden', 'true');
+    overlay.addEventListener('click', (event: MouseEvent) => {
+        if (event.target === overlay) closeHelpDialog();
+    });
+
+    const box = document.createElement('div');
+    box.className = 'modal-box help-dialog-box';
+    box.setAttribute('role', 'dialog');
+    box.setAttribute('aria-modal', 'true');
+    box.setAttribute('aria-labelledby', 'helpDialogTitle');
+    box.addEventListener('click', (event: MouseEvent) => event.stopPropagation());
+
+    const header = document.createElement('div');
+    header.className = 'modal-header help-dialog-header';
+
+    titleEl = document.createElement('span');
+    titleEl.id = 'helpDialogTitle';
+
+    closeBtn = document.createElement('button');
+    closeBtn.type = 'button';
+    closeBtn.className = 'btn-modal-close help-dialog-close';
+    closeBtn.setAttribute('aria-label', t('help.close'));
+    closeBtn.textContent = 'x';
+    closeBtn.addEventListener('click', () => closeHelpDialog());
+
+    bodyEl = document.createElement('div');
+    bodyEl.className = 'help-dialog-body';
+
+    const footer = document.createElement('div');
+    footer.className = 'modal-footer help-dialog-footer';
+
+    const done = document.createElement('button');
+    done.type = 'button';
+    done.className = 'btn-save help-dialog-done';
+    done.textContent = t('help.close');
+    done.addEventListener('click', () => closeHelpDialog());
+
+    header.append(titleEl, closeBtn);
+    footer.append(done);
+    box.append(header, bodyEl, footer);
+    overlay.append(box);
+    document.body.append(overlay);
+}
+
+function renderTopic(topic: HelpTopic): void {
+    if (!titleEl || !bodyEl || !closeBtn) return;
+    titleEl.textContent = t(topic.titleKey);
+    closeBtn.setAttribute('aria-label', t('help.close'));
+    bodyEl.replaceChildren();
+
+    appendTextSection(t('help.section.what'), t(topic.introKey));
+    appendTextSection(t('help.section.effect'), t(topic.effectKey), 'help-effect-text');
+    appendListSection(t('help.section.useWhen'), topic.useWhenKeys);
+    appendListSection(t('help.section.howTo'), topic.howToKeys);
+    appendListSection(t('help.section.example'), topic.exampleKeys, false, 'help-example-list');
+    if (topic.avoidWhenKeys?.length) appendListSection(t('help.section.avoidWhen'), topic.avoidWhenKeys);
+    if (topic.relatedKeys?.length) appendListSection(t('help.section.related'), topic.relatedKeys, true);
+}
+
+function appendTextSection(heading: string, text: string, className?: string): void {
+    if (!bodyEl) return;
+    const section = createSection(heading);
+    const p = document.createElement('p');
+    if (className) p.className = className;
+    p.textContent = text;
+    section.append(p);
+    bodyEl.append(section);
+}
+
+function appendListSection(heading: string, keys: string[], related = false, className?: string): void {
+    if (!bodyEl) return;
+    const section = createSection(heading);
+    const list = document.createElement('ul');
+    list.className = className ?? (related ? 'help-related-list' : 'help-dialog-list');
+    for (const key of keys) {
+        const item = document.createElement('li');
+        item.textContent = t(key);
+        list.append(item);
+    }
+    section.append(list);
+    bodyEl.append(section);
+}
+
+function createSection(heading: string): HTMLElement {
+    const section = document.createElement('section');
+    section.className = 'help-dialog-section';
+    const h3 = document.createElement('h3');
+    h3.textContent = heading;
+    section.append(h3);
+    return section;
+}

package/public/js/features/memory.ts

@@ -349,7 +349,7 @@ export async function upgradeSoulMemory(): Promise<void> {
     }
     await openMemoryModal();
     switchMemTab('status');
-    const freshStatus = await apiJson<any>('/api/memory/status');
+    const freshStatus = await api<any>('/api/memory/status');
     syncSidebarBadge(freshStatus, 0);
     renderStatusBanner(freshStatus);
 }
@@ -375,7 +375,7 @@ export async function synthesizeSoul(): Promise<void> {
     setAdvBanner('✓ Soul 최적화 프롬프트 전송됨. 채팅창을 확인하세요.');
     await openMemoryModal();
     switchMemTab('status');
-    const freshStatus = await apiJson<any>('/api/memory/status');
+    const freshStatus = await api<any>('/api/memory/status');
     syncSidebarBadge(freshStatus, 0);
     renderStatusBanner(freshStatus);
 }

package/public/js/features/orchestrate-scope.ts

@@ -0,0 +1,4 @@
+export function shouldApplyOrcStateEvent(eventScope: unknown, currentScope: string): boolean {
+    if (!eventScope || !currentScope) return true;
+    return eventScope === 'all' || eventScope === currentScope;
+}

package/public/js/features/settings-core.ts

@@ -12,6 +12,28 @@ import { loadActiveChannel, loadFallbackOrder } from './settings-channel.js';
 import { loadMcpServers } from './settings-mcp.js';
 import { providerIcon } from '../provider-icons.js';
 
+let activeSettingsSave: Promise<void> | null = null;
+
+function setHeaderCli(cli: string): void {
+    const hdr = document.getElementById('headerCli');
+    if (!hdr) return;
+    const ico = providerIcon(cli);
+    hdr.innerHTML = ico ? `${ico} ${escapeHtml(cli)}` : escapeHtml(cli);
+}
+
+function trackSettingsSave(promise: Promise<void>): Promise<void> {
+    const tracked = promise.finally(() => {
+        if (activeSettingsSave === tracked) activeSettingsSave = null;
+    });
+    activeSettingsSave = tracked;
+    return tracked;
+}
+
+export async function waitForSettingsSaveIdle(): Promise<void> {
+    const pending = activeSettingsSave;
+    if (pending) await pending;
+}
+
 function toCap(cli: string): string {
     return cli.charAt(0).toUpperCase() + cli.slice(1);
 }
@@ -224,12 +246,19 @@ export async function updateSettings(): Promise<void> {
     const s = {
         cli: (document.getElementById('selCli') as HTMLSelectElement)?.value || 'claude',
     };
-    const hdr = document.getElementById('headerCli');
-    if (hdr) {
-        const ico = providerIcon(s.cli);
-        hdr.innerHTML = ico ? `${ico} ${escapeHtml(s.cli)}` : escapeHtml(s.cli);
-    }
-    await apiJson('/api/settings', 'PUT', s);
+    return trackSettingsSave((async () => {
+        const result = await apiJson<SettingsData>('/api/settings', 'PUT', s);
+        if (!result) {
+            await loadSettings();
+            return;
+        }
+        const confirmedCli = result.cli || s.cli;
+        const selCli = document.getElementById('selCli') as HTMLSelectElement | null;
+        if (selCli && Array.from(selCli.options).some(o => o.value === confirmedCli)) {
+            selCli.value = confirmedCli;
+        }
+        setHeaderCli(confirmedCli);
+    })());
 }
 
 export function setPerm(_p: string, save = true): void {
@@ -308,11 +337,7 @@ export function onCliChange(save = true): void {
     const models = MODEL_MAP[cli] || [];
     const modelSel = document.getElementById('selModel') as HTMLSelectElement | null;
     setSelectOptions(modelSel, models, { includeCustom: true, includeDefault: true });
-    const hdrCli = document.getElementById('headerCli');
-    if (hdrCli) {
-        const ico = providerIcon(cli);
-        hdrCli.innerHTML = ico ? `${ico} ${escapeHtml(cli)}` : escapeHtml(cli);
-    }
+    setHeaderCli(cli);
     syncActiveEffortOptions(cli);
 
     const oldInput = document.getElementById('selModelCustom');

package/public/js/main.ts

@@ -83,6 +83,8 @@ import { toggleRecording, cancelRecording } from './features/voice-recorder.js';
 import { ICONS, hydrateIcons } from './icons.js';
 import { hydrateProviderIcons } from './provider-icons.js';
 import { initPendingQueue } from './features/pending-queue.js';
+import { initAttentionBadge } from './features/attention-badge.js';
+import { initHelpDialog } from './features/help-dialog.js';
 
 // ── Chat Actions ──
 document.getElementById('btnSend')?.addEventListener('click', sendMessage);
@@ -449,6 +451,8 @@ async function bootstrap(): Promise<void> {
     if (langBtn) langBtn.innerHTML = `${ICONS.web} ${t('lang.' + getLang())}`;
     await loadCliRegistry();
     bindPerCliControlEvents();
+    initHelpDialog();
+    initAttentionBadge();
     connect();
     initDragDrop();
     initAutoResize();

package/public/js/ui.ts

@@ -8,7 +8,7 @@ import { getAgentAvatarMarkup, getUserAvatarMarkup } from './features/avatar.js'
 import { t } from './features/i18n.js';
 import { api } from './api.js';
 import { cacheMessages, getCachedMessages, appendCachedMessage, upsertMessage, setMessageScope, getScopedMessages } from './features/idb-cache.js';
-import { getVirtualScroll, VS_THRESHOLD, type VirtualItem } from './virtual-scroll.js';
+import { getVirtualScroll, VS_THRESHOLD, type RestoreReason, type VirtualItem } from './virtual-scroll.js';
 import { bootstrapVirtualHistory, type VirtualHistoryBootstrapDeps } from './virtual-scroll-bootstrap.js';
 import { createStreamRenderer, appendChunk, finalizeStream, hydrateStreamRenderer, type StreamState } from './streaming-render.js';
 import { activateWidgets } from './diagram/iframe-renderer.js';
@@ -506,6 +506,26 @@ export function reconcileChatBottomAfterLayout(shouldFollow = isChatNearBottom()
     });
 }
 
+export function reconcileChatBottomAfterRestore(reason: string): void {
+    ensureScrollTracking();
+    userNearBottom = true;
+    const vs = getVirtualScroll();
+    if (vs.active) {
+        vs.forceBottomAfterRestore(reason as RestoreReason);
+        return;
+    }
+    const scroll = () => {
+        const c = document.getElementById('chatMessages');
+        if (c) c.scrollTop = c.scrollHeight;
+    };
+    scroll();
+    requestAnimationFrame(scroll);
+    requestAnimationFrame(() => requestAnimationFrame(scroll));
+    window.setTimeout(scroll, 250);
+    window.setTimeout(scroll, 1000);
+    void document.fonts?.ready.then(scroll);
+}
+
 /** Scroll chat to bottom.
  *  @param force - bypass user-scroll detection (use for explicit user actions) */
 export function scrollToBottom(force = false): void {

package/public/js/virtual-scroll.ts

@@ -15,6 +15,17 @@ const EST_HEIGHT = 80;
 const OVERSCAN = 5;
 const BOTTOM_THRESHOLD = 80;
 
+export type RestoreReason =
+    | 'pageshow'
+    | 'visibility'
+    | 'focus'
+    | 'pagehide'
+    | 'freeze'
+    | 'resume'
+    | 'discard'
+    | 'reconnect'
+    | 'manual';
+
 export interface VirtualItem {
     id: string;
     html: string;
@@ -60,6 +71,7 @@ export class VirtualScroll {
     private cleanupFn: (() => void) | null = null;
     private mounted = new Map<number, HTMLElement>();
     private itemGap = 0;
+    private restorePassTimers = new Set<number>();
 
     onLazyRender: LazyRenderCallback | null = null;
     onPostRender: ((viewport: HTMLElement) => void) | null = null;
@@ -182,7 +194,7 @@ export class VirtualScroll {
         return dist < threshold;
     }
 
-    reconcileBottomAfterLayout(reason: 'pageshow' | 'visibility' | 'focus' | 'reconnect' | 'manual', shouldFollow = this.isNearBottom()): void {
+    reconcileBottomAfterLayout(reason: RestoreReason, shouldFollow = this.isNearBottom()): void {
         if (!shouldFollow) return;
         void reason;
         requestAnimationFrame(() => {
@@ -193,6 +205,44 @@ export class VirtualScroll {
         });
     }
 
+    forceBottomAfterRestore(reason: RestoreReason): void {
+        this.scheduleRestoreReconcile(reason);
+    }
+
+    private scheduleRestoreReconcile(reason: RestoreReason): void {
+        this.runRestoreReconcilePass(reason);
+        requestAnimationFrame(() => this.runRestoreReconcilePass(reason));
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => this.runRestoreReconcilePass(reason));
+        });
+        this.scheduleRestoreTimer(reason, 250);
+        this.scheduleRestoreTimer(reason, 1000);
+        void document.fonts?.ready.then(() => this.runRestoreReconcilePass(reason));
+    }
+
+    private scheduleRestoreTimer(reason: RestoreReason, delayMs: number): void {
+        const timer = window.setTimeout(() => {
+            this.restorePassTimers.delete(timer);
+            this.runRestoreReconcilePass(reason);
+        }, delayMs);
+        this.restorePassTimers.add(timer);
+    }
+
+    private runRestoreReconcilePass(reason: RestoreReason): void {
+        if (!this.virtualizer) return;
+        void reason;
+        this.invalidateLayout();
+        remeasureMountedVirtualItems(this.items, this.mounted, this.virtualizer);
+        this.scrollToBottom();
+    }
+
+    private clearRestoreTimers(): void {
+        for (const timer of this.restorePassTimers) {
+            window.clearTimeout(timer);
+        }
+        this.restorePassTimers.clear();
+    }
+
     flushToDOM(): void {
         if (!this._active) return;
         this.deactivate();
@@ -286,14 +336,12 @@ export class VirtualScroll {
             cleanupFns.push(() => containerObserver.disconnect());
         }
 
-        // ── bfcache restoration ──
-        // pageshow fires when page is restored from bfcache (persisted=true).
-        // Regular reload goes through normal activate() flow, but bfcache
-        // restores the JS heap with stale cached measurements.
-        const restoreBottomAfterLayout = (reason: 'pageshow' | 'visibility' | 'focus') => {
+        // ── Browser restore reconciliation ──
+        // Resume/discard paths can restore stale virtualizer measurements.
+        // Product policy: browser restore/reconnect forces the newest message.
+        const restoreBottomAfterLayout = (reason: RestoreReason) => {
             if (!this.virtualizer) return;
-            const shouldFollow = this.isNearBottom();
-            this.reconcileBottomAfterLayout(reason, shouldFollow);
+            this.forceBottomAfterRestore(reason);
         };
         const onPageShow = (e: PageTransitionEvent) => {
             if (!e.persisted) return;
@@ -307,11 +355,21 @@ export class VirtualScroll {
         document.addEventListener('visibilitychange', onVisibilityChange);
         const onFocus = () => restoreBottomAfterLayout('focus');
         window.addEventListener('focus', onFocus);
+        const onResume = () => restoreBottomAfterLayout('resume');
+        document.addEventListener('resume', onResume);
+        const onPageHide = () => { /* diagnostic hook: restore happens on pageshow/resume */ };
+        window.addEventListener('pagehide', onPageHide);
+        const onFreeze = () => { /* diagnostic hook: restore happens on resume */ };
+        document.addEventListener('freeze', onFreeze);
         this.cleanupFn = () => {
             window.removeEventListener('pageshow', onPageShow);
             document.removeEventListener('visibilitychange', onVisibilityChange);
             window.removeEventListener('focus', onFocus);
+            document.removeEventListener('resume', onResume);
+            window.removeEventListener('pagehide', onPageHide);
+            document.removeEventListener('freeze', onFreeze);
             for (const cleanup of cleanupFns.reverse()) cleanup();
+            this.clearRestoreTimers();
         };
 
         this.virtualizer._willUpdate();
@@ -334,9 +392,15 @@ export class VirtualScroll {
         } else {
             this.renderItems();
         }
+        const wasDiscarded = 'wasDiscarded' in document
+            && Boolean((document as Document & { wasDiscarded?: boolean }).wasDiscarded);
+        if (wasDiscarded) {
+            this.forceBottomAfterRestore('discard');
+        }
     }
 
     private deactivate(): void {
+        this.clearRestoreTimers();
         if (this.cleanupFn) {
             this.cleanupFn();
             this.cleanupFn = null;

package/public/js/ws.ts

@@ -1,12 +1,14 @@
 // ── WebSocket Connection ──
 import { state } from './state.js';
-import { setStatus, updateQueueBadge, addSystemMsg, appendAgentText, finalizeAgent, addMessage, showProcessStep, cleanupToolActivity, applyQueuedOverlay, hydrateActiveRun, isChatNearBottom, reconcileChatBottomAfterLayout } from './ui.js';
+import { setStatus, updateQueueBadge, addSystemMsg, appendAgentText, finalizeAgent, addMessage, showProcessStep, cleanupToolActivity, applyQueuedOverlay, hydrateActiveRun, reconcileChatBottomAfterRestore } from './ui.js';
 import { renderPendingQueue } from './features/pending-queue.js';
 import { t, getLang } from './features/i18n.js';
 import { getVirtualScroll } from './virtual-scroll.js';
 import { ICONS, emojiToIcon } from './icons.js';
 import { escapeHtml, cancelPostRender } from './render.js';
 import type { OrcStateName } from './state.js';
+import { notifyUnreadResponse } from './features/attention-badge.js';
+import { shouldApplyOrcStateEvent } from './features/orchestrate-scope.js';
 
 const ROADMAP_PHASES = ['P', 'A', 'B', 'C'] as const;
 
@@ -68,6 +70,7 @@ interface WsMessage {
     state?: string;
     title?: string;
     isEmployee?: boolean;
+    fromQueue?: boolean;
 }
 
 // Agent phase state (populated by agent_status events from orchestrator)
@@ -75,6 +78,10 @@ const agentPhaseState: Record<string, { phase: string; phaseLabel: string }> = {
 
 let currentOrcScope = '';
 let lastLoadTs = 0;
+let snapshotSyncInFlight: Promise<void> | null = null;
+let lastSnapshotSyncAt = 0;
+let restoreHooksRegistered = false;
+const SNAPSHOT_SYNC_THROTTLE_MS = 750;
 
 async function refreshRuntimeSnapshot(options: { hydrateRun?: boolean } = {}): Promise<void> {
     const response = await fetch('/api/orchestrate/snapshot');
@@ -92,6 +99,41 @@ async function refreshRuntimeSnapshot(options: { hydrateRun?: boolean } = {}): P
     });
 }
 
+export function syncOrchestrateSnapshot(reason = 'manual', options: { hydrateRun?: boolean } = {}): Promise<void> {
+    const now = Date.now();
+    if (!options.hydrateRun) {
+        if (snapshotSyncInFlight) return snapshotSyncInFlight;
+        if (now - lastSnapshotSyncAt < SNAPSHOT_SYNC_THROTTLE_MS) return Promise.resolve();
+        lastSnapshotSyncAt = now;
+        snapshotSyncInFlight = refreshRuntimeSnapshot(options)
+            .catch(error => {
+                console.warn(`[ws] orchestrate snapshot sync failed (${reason})`, error);
+                throw error;
+            })
+            .finally(() => {
+                snapshotSyncInFlight = null;
+            });
+        return snapshotSyncInFlight;
+    }
+    return refreshRuntimeSnapshot(options);
+}
+
+function registerOrchestrateRestoreHooks(): void {
+    if (restoreHooksRegistered) return;
+    restoreHooksRegistered = true;
+    window.addEventListener('focus', () => {
+        syncOrchestrateSnapshot('focus').catch(() => {});
+    });
+    window.addEventListener('pageshow', () => {
+        syncOrchestrateSnapshot('pageshow').catch(() => {});
+    });
+    document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'visible') {
+            syncOrchestrateSnapshot('visibilitychange').catch(() => {});
+        }
+    });
+}
+
 /** Hydrate agent phase cache from snapshot (used after reconnect) */
 export function hydrateAgentPhases(workers: Array<{
     agentId: string;
@@ -210,6 +252,7 @@ function applyOrcState(orcState: string, title?: string) {
 }
 
 export function connect(): void {
+    registerOrchestrateRestoreHooks();
     const wsBase = import.meta.env?.DEV ? 'ws://localhost:3458' : `ws://${location.host}`;
     state.ws = new WebSocket(`${wsBase}?lang=${getLang()}`);
     state.ws.onmessage = (e: MessageEvent) => {
@@ -237,7 +280,7 @@ export function connect(): void {
             }
         } else if (msg.type === 'queue_update') {
             updateQueueBadge(msg.pending || 0);
-            refreshRuntimeSnapshot().catch(() => { /* snapshot not critical — UI recovers on next event */ });
+            syncOrchestrateSnapshot('queue_update').catch(() => { /* snapshot not critical — UI recovers on next event */ });
         } else if (msg.type === 'worklog_created') {
             addSystemMsg(`${ICONS.clipboard} Worklog: ${escapeHtml(msg.path || '')}`);
         } else if (msg.type === 'round_start') {
@@ -278,8 +321,10 @@ export function connect(): void {
             addSystemMsg(`${ICONS.warning} ${escapeHtml(msg.cli || 'agent')}: smoke response detected — auto-continuing`, 'tool-activity');
         } else if (msg.type === 'agent_done') {
             finalizeAgent(msg.text || '', msg.toolLog);
+            notifyUnreadResponse();
         } else if (msg.type === 'orchestrate_done') {
             finalizeAgent(msg.text || '');
+            notifyUnreadResponse();
         } else if (msg.type === 'clear') {
             cancelPostRender();
             cleanupToolActivity();
@@ -293,7 +338,7 @@ export function connect(): void {
         } else if (msg.type === 'agent_added' || msg.type === 'agent_updated' || msg.type === 'agent_deleted') {
             import('./features/employees.js').then(m => m.loadEmployees());
         } else if (msg.type === 'orc_state') {
-            if (msg.scope && currentOrcScope && msg.scope !== currentOrcScope) return;
+            if (!shouldApplyOrcStateEvent(msg.scope, currentOrcScope)) return;
             applyOrcState(typeof msg.state === 'string' ? msg.state : 'IDLE', msg.title);
         } else if (msg.type === 'memory_status') {
             import('./features/memory.js').then(m => m.refreshMemorySidebar());
@@ -307,7 +352,6 @@ export function connect(): void {
         console.log('[ws] connected');
         const now = Date.now();
         const skipReload = now - lastLoadTs < 10000;
-        const shouldFollowBottom = isChatNearBottom();
         import('./ui.js').then(async m => {
             m.cleanupToolActivity();
             if (!skipReload) {
@@ -318,9 +362,9 @@ export function connect(): void {
                     console.error('[ws] loadMessages failed', error);
                 }
             }
-            refreshRuntimeSnapshot({ hydrateRun: true })
+            syncOrchestrateSnapshot('reconnect', { hydrateRun: true })
                 .catch(() => { /* snapshot not critical — UI recovers on next WS event */ })
-                .finally(() => reconcileChatBottomAfterLayout(shouldFollowBottom));
+                .finally(() => m.reconcileChatBottomAfterRestore('reconnect'));
         });
     };
     state.ws.onclose = () => {