cc-viewer 1.7.23 → 1.8.1

package/server/lib/adapters/discord-adapter.js

@@ -1,5 +1,5 @@
 // Discord adapter — the platform-specific half of the Discord bridge. The generic orchestration
-// (dedup, access control, queue, inject, chunk, turn-end reply) lives in server/lib/im-bridge-core.js;
+// (dedup, access control, queue, inject, chunk, turn-end reply) lives in server/lib/im/im-bridge-core.js;
 // this module only knows discord.js's Gateway client, inbound message shape, and outbound send.
 //
 // Uses discord.js v14: the bot dials OUT to Discord's Gateway WebSocket (no public URL). Credential is
@@ -12,7 +12,7 @@
 // Console prerequisite (no code equivalent — surfaced in the UI help): in the Discord Developer Portal,
 // create an app + bot, ENABLE the Message Content Intent (else message.content is silently empty), copy
 // the bot token, and invite the bot with the `bot`+`applications.commands` scopes and View/Send perms.
-import { registerAdapter } from '../im-bridge-core.js';
+import { registerAdapter } from '../im/im-bridge-core.js';
 
 // ─── test seam: a fake discord.js factory (zero real gateway / socket) ───
 let sdkFactory = null;

package/server/lib/adapters/feishu-adapter.js

@@ -1,6 +1,6 @@
 // Feishu/Lark adapter — the platform-specific half of the Feishu bridge. The generic
 // orchestration (dedup, access control, queue, inject, chunk, turn-end reply) lives in
-// server/lib/im-bridge-core.js; this module only knows Feishu's WebSocket long-connection event
+// server/lib/im/im-bridge-core.js; this module only knows Feishu's WebSocket long-connection event
 // client, inbound payload shape, and outbound send.
 //
 // Inbound uses the official SDK's WSClient long-connection (NOT a webhook) so it works on
@@ -11,7 +11,7 @@
 // Console prerequisite (no code equivalent — surfaced to the user in the UI/README): the custom
 // app must set Event Subscription to "long connection", subscribe `im.message.receive_v1`, grant
 // the `im:message` send scope, and be published.
-import { registerAdapter } from '../im-bridge-core.js';
+import { registerAdapter } from '../im/im-bridge-core.js';
 
 // ─── test seam: a fake SDK factory ({ Client, WSClient, EventDispatcher, Domain, LoggerLevel })
 // so unit tests never import the real SDK or open a socket. ───

package/server/lib/adapters/wecom-adapter.js

@@ -1,6 +1,6 @@
 // 企业微信 (WeCom) adapter — the platform-specific half of the WeCom bridge. The generic
 // orchestration (dedup, access control, queue, inject, chunk, turn-end reply) lives in
-// server/lib/im-bridge-core.js; this module only knows WeCom's smart-robot long-connection client,
+// server/lib/im/im-bridge-core.js; this module only knows WeCom's smart-robot long-connection client,
 // inbound frame shape, and outbound send.
 //
 // Uses the 企业微信智能机器人长连接 (Smart Robot long-connection) mode via @wecom/aibot-node-sdk:
@@ -12,7 +12,7 @@
 // Console prerequisite (no code equivalent — surfaced in the UI help/README): create a 智能机器人,
 // set its API 接收模式 to 长连接, copy the botId + secret, and add the bot to a chat.
 import { randomUUID } from 'node:crypto';
-import { registerAdapter } from '../im-bridge-core.js';
+import { registerAdapter } from '../im/im-bridge-core.js';
 
 // ─── test seam: a fake SDK factory (zero real SDK / socket) ───
 let sdkFactory = null;

package/server/lib/approval-policy.js

@@ -0,0 +1,29 @@
+/**
+ * approval-policy.js — Shared approval-policy predicates for the two approval paths.
+ *
+ * Single source of truth for:
+ *   - APPROVAL_TOOLS: the six mutating/external tools that require explicit user
+ *     approval (previously duplicated literally at ask/perm-bridge.js and
+ *     sdk-manager.js).
+ *   - isPublishCommand: the npm-publish hard gate. `npm publish` is the one
+ *     irreversible outward-facing command (commits can be rewritten, pushes
+ *     force-pushed back) — it must NEVER be auto-allowed, even under
+ *     --dangerously-skip-permissions. Both consumers force it through the Web UI
+ *     approval modal: perm-bridge.js exempts it from the CCV_BYPASS_PERMISSIONS
+ *     auto-allow; sdk-manager.js routes it into the perm approval branch even in
+ *     bypassPermissions mode.
+ *
+ * Pure leaf module (L1-lib): no imports, no I/O — importable from both L1-lib
+ * (sdk-manager.js) and L1-sub (ask/perm-bridge.js) without boundary-gate edges.
+ */
+
+export const APPROVAL_TOOLS = new Set(['Bash', 'Edit', 'Write', 'NotebookEdit', 'WebFetch', 'WebSearch']);
+
+/**
+ * @param {string} toolName
+ * @param {object} [input] — tool input ({ command } for Bash)
+ * @returns {boolean} true when the call is an `npm publish` invocation
+ */
+export function isPublishCommand(toolName, input) {
+  return toolName === 'Bash' && typeof input?.command === 'string' && /npm\s+publish/i.test(input.command);
+}

package/server/lib/{ask-store.js → ask/ask-store.js}

@@ -12,9 +12,9 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { renameSyncWithRetry } from './file-api.js';
-import { withFileLockAsync } from './async-file-lock.js';
-import { LOG_DIR } from '../../findcc.js';
+import { renameSyncWithRetry } from '../file-api.js';
+import { withFileLockAsync } from '../async-file-lock.js';
+import { LOG_DIR } from '../../../findcc.js';
 
 const SCHEMA_VERSION = 1;
 

package/server/lib/{perm-bridge.js → ask/perm-bridge.js}

@@ -14,7 +14,8 @@
 import { readFileSync } from 'node:fs';
 import http from 'node:http';
 import https from 'node:https';
-import { evaluateImDeny } from './im-deny.js';
+import { evaluateImDeny } from '../im-deny.js';
+import { APPROVAL_TOOLS, isPublishCommand } from '../approval-policy.js';
 
 const port = process.env.CCVIEWER_PORT;
 const rawProtocol = process.env.CCVIEWER_PROTOCOL;
@@ -59,9 +60,8 @@ if (!toolName || !toolInput) {
 // 硬拦截：npm publish 即使在 --d (bypass) 模式下也强制走 Web UI 审批
 // 这是安全底线，不受 --dangerously-skip-permissions 影响
 // 注：git commit / git push 不在硬拦截范围内 —— 提交可重写、push 可 force-push 回退,
-// 真正不可撤销的对外发布(npm publish)才走硬闸
-const isPublishCmd = toolName === 'Bash' && toolInput.command &&
-  /npm\s+publish/i.test(toolInput.command);
+// 真正不可撤销的对外发布(npm publish)才走硬闸。谓词共享自 approval-policy.js(SDK 链路同用)。
+const isPublishCmd = isPublishCommand(toolName, toolInput);
 
 // IM worker (skip-permissions) 硬拦截 —— 必须在下面的 bypass auto-allow 之前求值，
 // 否则 CCV_BYPASS_PERMISSIONS=1 会把一切先放行（见 plan §安全 2）。仅对 IM worker 生效。
@@ -95,7 +95,7 @@ if (toolName === 'AskUserQuestion') {
 }
 
 // These tools need explicit user approval via Web UI (mutating or external access).
-const APPROVAL_TOOLS = new Set(['Bash', 'Edit', 'Write', 'NotebookEdit', 'WebFetch', 'WebSearch']);
+// The six-tool set is shared with the SDK canUseTool path via approval-policy.js.
 if (!APPROVAL_TOOLS.has(toolName)) {
   process.stdout.write(JSON.stringify({
     hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' },

package/server/lib/builtin-model-prompts.js

@@ -0,0 +1,198 @@
+// 内置模型提示词层：让 packages/app/server/system-prompt-templates/presets/ 的 6 个预设
+// 成为「默认生效」的模型 system prompt——spawn 时模型匹配且用户无对应文件（workspace >
+// global 两级用户文件优先）时自动注入；用户可通过墓碑文件禁用某个内置条目。
+//
+// 数据源复用 system-prompt-presets.js 的 listSystemPromptPresets()（manifest 读取 +
+// renderPresetTemplate 边界剥离都已在里面，且注释承诺不触发 createSystemPromptVariables/
+// git 子进程）。本模块函数对非法入参会 throw（setBuiltinDisabled/materializeBuiltinPrompt），
+// spawn 注入链路的安全由调用点整层 try-catch 保证（system-prompt-files.js 失败回落
+// sentinel，注入链路永不 throw）。
+//
+// Built-in model prompt layer: the shipped presets act as default-effective model
+// system prompts. User files (workspace > global) always win; a per-scope tombstone
+// file disables individual built-in entries.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { expandModelIdVariants, normalizeModelName } from './model-system-prompts.js';
+import { listSystemPromptPresets } from './system-prompt-presets.js';
+import { renameSyncWithRetry } from './file-api.js';
+import { reportSwallowed } from '@ccv/core/error-report';
+
+// 墓碑文件名：放在对应 scope 的 modelPromptDir 里，内容是规范大写名的 JSON 数组。
+// parseModelPromptFileName 对非 *_SYSTEM.md 文件名返回 null，天然不干扰条目列表。
+// Tombstone file inside a scope's model-prompt dir: a JSON array of canonical names.
+export const BUILTIN_DISABLED_FILE = '.builtin-disabled.json';
+
+// 物化目录：preset 文本（边界已剥离、${...} 保持字面量，spawn 渲染管线再替换变量）
+// 写成内容寻址的临时文件，供 --system-prompt-file 注入（文件对形式是快照钉扎的前提）。
+// 惰性读取 env 覆盖（测试用）：node --test 多进程并行时共享目录会被彼此的 GC 竞态误删。
+// Materialized temp dir for boundary-stripped preset texts (content-addressed).
+const materializeDir = () => process.env.CCV_BUILTIN_PROMPT_MATERIALIZE_DIR || join(tmpdir(), 'cc-viewer-builtin-prompts');
+
+/**
+ * 列出全部内置模型条目。name = manifest match 的大写规范化（与用户条目同名体系，
+ * 用户同名文件天然形成覆盖）；text = renderPresetTemplate 输出（无边界标记）。
+ * List all built-in model entries derived from the preset manifest.
+ *
+ * @returns {Array<{ id: string, title: string, name: string, mode: 'override'|'append', matchLower: string, text: string }>}
+ */
+export function listBuiltinModelPrompts() {
+  let presets;
+  try {
+    presets = listSystemPromptPresets();
+  } catch {
+    return []; // manifest 损坏等：内置层整体缺席，调用方回落 sentinel
+  }
+  const out = [];
+  for (const p of presets) {
+    const name = normalizeModelName(typeof p?.match === 'string' ? p.match : '');
+    if (!name || typeof p.text !== 'string' || p.text.trim().length === 0) continue;
+    out.push({
+      id: p.id,
+      title: p.title || p.id,
+      name,
+      mode: p.defaultMode === 'override' ? 'override' : 'append',
+      matchLower: p.match.toLowerCase(),
+      text: p.text,
+    });
+  }
+  return out;
+}
+
+/**
+ * 按 modelId 匹配内置条目：别名展开（expandModelIdVariants，先 lowercase）后任一变体
+ * 包含 preset 的 match 即命中；多命中取 match 最长者、等长字典序（对齐 matchModelPrompt
+ * 的消歧规则）。
+ * Match a model id against built-in entries (alias-expanded substring, longest wins).
+ *
+ * @param {string|null} modelId
+ * @returns {{ id: string, name: string, mode: 'override'|'append', text: string } | null}
+ */
+export function matchBuiltinModelPrompt(modelId) {
+  const variants = expandModelIdVariants(modelId);
+  if (!variants.length) return null;
+  const hits = listBuiltinModelPrompts().filter((e) => variants.some((v) => v.includes(e.matchLower)));
+  if (!hits.length) return null;
+  hits.sort((a, b) => b.matchLower.length - a.matchLower.length || a.name.localeCompare(b.name));
+  const e = hits[0];
+  return { id: e.id, name: e.name, mode: e.mode, text: e.text };
+}
+
+/**
+ * 读某 scope 目录的墓碑名单。目录/文件缺失 → []（良性静默）；文件存在但 JSON 损坏或
+ * 形状非法 → console.warn + reportSwallowed 后仍宽容返回 []（fail-open 是刻意的：
+ * 墓碑是辅助状态，宁可恢复注入也不因损坏阻断功能——但用户显式 opt-out 被静默逆转
+ * 必须有诊断痕迹，三方审查一致要求）。
+ * Read a scope dir's tombstone list. Missing dir/file → []; corrupt file → warn +
+ * reportSwallowed, still [] (deliberate fail-open, but never silently).
+ *
+ * @param {string|null|undefined} modelPromptDir
+ * @returns {string[]} 规范大写名数组（已排序）
+ */
+export function readBuiltinDisabled(modelPromptDir) {
+  if (!modelPromptDir) return [];
+  const target = join(modelPromptDir, BUILTIN_DISABLED_FILE);
+  if (!existsSync(target)) return [];
+  try {
+    const raw = readFileSync(target, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) throw new Error('tombstone file is not a JSON array');
+    const names = parsed.map((n) => normalizeModelName(typeof n === 'string' ? n : '')).filter(Boolean);
+    return [...new Set(names)].sort();
+  } catch (err) {
+    console.warn(`[CC Viewer] built-in prompt tombstone ${target} unreadable (${err.message}); treating as no disables`);
+    reportSwallowed('builtin-model-prompts.readDisabled', err);
+    return [];
+  }
+}
+
+/**
+ * 写墓碑：disabled=true 把 name 加入名单，false 移出。tmp+rename 原子写，数组去重排序。
+ * Add/remove a name in a scope dir's tombstone list (atomic tmp+rename write).
+ *
+ * @param {string} modelPromptDir 目标 scope 的 modelPromptDir（自动 mkdir -p）
+ * @param {string} name 条目名（经 normalizeModelName 规范化，非法 throw）
+ * @param {boolean} disabled
+ * @returns {{ name: string, disabled: boolean, list: string[] }}
+ */
+export function setBuiltinDisabled(modelPromptDir, name, disabled) {
+  if (!modelPromptDir) throw new Error('no target directory');
+  const canonical = normalizeModelName(name);
+  if (!canonical) throw new Error('invalid model prompt name');
+  const list = readBuiltinDisabled(modelPromptDir);
+  const next = disabled ? [...new Set([...list, canonical])].sort() : list.filter((n) => n !== canonical);
+  mkdirSync(modelPromptDir, { recursive: true });
+  const target = join(modelPromptDir, BUILTIN_DISABLED_FILE);
+  const tmp = `${target}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
+  renameSyncWithRetry(tmp, target); // Windows 杀软/索引瞬时 EPERM 重试（与仓库写路径一致）
+  return { name: canonical, disabled: !!disabled, list: next };
+}
+
+/**
+ * 多 scope 合成判断：任一目录的墓碑名单含 name 即视为禁用（workspace 墓碑禁本工作区、
+ * global 墓碑全局禁用；对单次启动而言两者都是「该禁」）。
+ * Combine tombstones across scopes: disabled when ANY dir's list contains the name.
+ *
+ * @param {string} name 规范大写名
+ * @param {...(string|null|undefined)} modelPromptDirs
+ * @returns {boolean}
+ */
+export function isBuiltinDisabled(name, ...modelPromptDirs) {
+  const canonical = normalizeModelName(name);
+  if (!canonical) return false;
+  return modelPromptDirs.some((dir) => readBuiltinDisabled(dir).includes(canonical));
+}
+
+/**
+ * 把内置条目文本物化为内容寻址的临时文件（不存在才写，避并发截断；顺手清同 id
+ * 旧 hash 文件）。返回文件路径。
+ * Materialize a built-in entry's text into a content-addressed temp file.
+ *
+ * @param {string} id preset id（文件名安全字符校验）
+ * @param {string} text renderPresetTemplate 输出（边界已剥离、${...} 字面量保留）
+ * @returns {string} 物化文件绝对路径
+ */
+export function materializeBuiltinPrompt(id, text) {
+  if (typeof id !== 'string' || !/^[A-Za-z0-9._-]+$/.test(id)) throw new Error('invalid preset id');
+  if (typeof text !== 'string' || text.trim().length === 0) throw new Error('empty preset text');
+  const hash = createHash('sha256').update(text).digest('hex').slice(0, 8);
+  const fileName = `${id}-${hash}.md`;
+  const dir = materializeDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 }); // 仅属主可读写：Linux 多用户 /tmp 下防跨用户预植
+  const target = join(dir, fileName);
+  // write-if-absent 必须回读校验内容 hash：可预测路径 + 预置恶意文件（hash 可算，
+  // preset 文本随包公开）会把注入内容掉包——不一致则覆盖。写入用 tmp+rename 原子落盘，
+  // 进程在写中途崩溃留下截断文件时 write-if-absent 永不愈合。
+  const writeAtomic = () => {
+    const tmp = `${target}.${process.pid}.tmp`;
+    writeFileSync(tmp, text, 'utf-8');
+    renameSyncWithRetry(tmp, target);
+  };
+  if (!existsSync(target)) {
+    writeAtomic();
+  } else {
+    try {
+      const existing = readFileSync(target, 'utf-8');
+      if (createHash('sha256').update(existing).digest('hex').slice(0, 8) !== hash) writeAtomic();
+    } catch {
+      writeAtomic(); // 读失败（截断/权限）→ 覆盖重写
+    }
+  }
+  // best-effort GC：同 id 的旧 hash 文件（版本升级后残留）。精确匹配 8 位 hex hash 防
+  // id 前缀误删（如未来 kimi-k3-turbo）；只清 mtime 足够旧的文件，避免跨版本并发
+  // （新旧实例同跑）时删掉旧实例正要读的文件。失败无碍。
+  try {
+    const idRe = new RegExp(`^${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-[0-9a-f]{8}\\.md$`);
+    for (const f of readdirSync(dir)) {
+      if (!idRe.test(f) || f === fileName) continue;
+      const p = join(dir, f);
+      try {
+        if (Date.now() - statSync(p).mtimeMs > 10 * 60_000) rmSync(p, { force: true });
+      } catch { /* ignore */ }
+    }
+  } catch { /* ignore */ }
+  return target;
+}

package/server/lib/chat-queue.js

@@ -0,0 +1,341 @@
+/**
+ * chat-queue.js — Server-side busy queue for chat-composer messages (PTY / terminal-hidden mode).
+ *
+ * When Claude is mid-run and the user presses Enter in the web chat composer, the message is
+ * held here instead of being typed into the TUI immediately. The server broadcasts the queue
+ * (`queue-state`) so every client can render floating bubbles above the composer, and drains
+ * the queue into the PTY (bracketed paste + Enter) once the turn really ends.
+ *
+ * Per-bubble actions:
+ * - "Send now" (queue-send-now) interrupts the running turn (focus-in + ESC, same bytes as the
+ *   web Stop button) and injects that message as soon as the TUI is observably idle.
+ * - "Remove" (queue-remove) drops it.
+ * Stop keeps the queue parked (product decision): `suppressNextDrain()` blocks the automatic
+ * turn-end drain until a NEW turn starts (streaming rising edge) or a message is sent now.
+ *
+ * Design notes:
+ * - This module NEVER imports pty-manager / server.js. All PTY access + state probes are
+ *   injected via initChatQueue(deps), so unit tests run without node-pty (im-bridge-core
+ *   convention).
+ * - Injection is single-flight (`_injecting`) and mutually exclusive with the IM bridge's
+ *   own injection slot via the injected `hasExternalInjection` probe (im-bridge-core's
+ *   anyActiveInjection).
+ * - Known limitation: keystrokes typed directly into a VISIBLE terminal are not serialized
+ *   against an in-flight inject (same accepted risk class as the IM bridge today).
+ */
+
+import { reportSwallowed } from '@ccv/core/error-report';
+import { bracketPasteSubmit, sanitizeInbound } from './im/im-bridge-core.js';
+
+const MAX_ITEMS = 50;             // im-bridge-core MAX_QUEUE parity
+const STOP_ESC_DELAY_MS = 50;     // focus-in → ESC gap, mirrors ChatView's STOP_FOCUS_IN_ESC_DELAY_MS
+const INJECT_POLL_MS = 100;       // idle poll cadence before injecting
+const INJECT_POLL_MAX_MS = 2000;  // give up polling after this; NEVER inject unconditionally
+const RESCUE_AFTER_MS = 3000;     // stale-busy rescue: frontend guessed busy while the turn already ended
+
+// Injected deps (see initChatQueue). Null until wired; every public entry no-ops safely then.
+let _deps = null;
+let _items = [];            // [{ id, text, ts }] FIFO
+let _injecting = false;     // single-flight guard around one bracket-paste inject sequence
+let _rescueTimer = null;    // stale-busy rescue timer
+let _pollTimer = null;      // active idle-poll interval (single slot — see _pollUntilSafe)
+let _escTimer = null;       // sendNow's focus-in → ESC gap timer
+let _suppressDrain = false; // Stop pressed → park the queue until a new turn starts
+let _gen = 0;               // generation counter: clear()/stop() invalidate in-flight injects
+
+/**
+ * @param {object} deps
+ * @param {function} deps.writeToPty — (data:string) => void
+ * @param {function} deps.writeToPtySequential — (chunks:string[], onComplete:(ok:boolean)=>void, opts?) => void
+ * @param {function} deps.getPtyKind — () => 'claude' | 'shell' | null
+ * @param {function} deps.isStreaming — () => boolean (per-API-call streaming flag; flickers between tool calls)
+ * @param {function} deps.hasPendingApproval — () => boolean (web-visible ask/perm modal open)
+ * @param {function} [deps.hasExternalInjection] — () => boolean (IM bridge injection slot busy)
+ * @param {function} deps.broadcastWs — (msg:object) => void
+ */
+export function initChatQueue(deps) {
+  _deps = deps;
+}
+
+export function getSnapshot() {
+  return _items.map(({ id, text, ts }) => ({ id, text, ts }));
+}
+
+function _broadcast() {
+  if (!_deps || !_deps.broadcastWs) return;
+  try { _deps.broadcastWs({ type: 'queue-state', items: getSnapshot() }); }
+  catch (err) { reportSwallowed('chat-queue.broadcast', err); }
+}
+
+function _makeItem(text) {
+  return {
+    id: 'q_' + Date.now().toString(36) + '_' + Math.random().toString(36).slice(2, 8),
+    text,
+    ts: Date.now(),
+  };
+}
+
+function _clearRescueTimer() {
+  if (_rescueTimer) { clearTimeout(_rescueTimer); _rescueTimer = null; }
+}
+
+function _clearPollTimer() {
+  if (_pollTimer) { clearInterval(_pollTimer); _pollTimer = null; }
+}
+
+function _clearEscTimer() {
+  if (_escTimer) { clearTimeout(_escTimer); _escTimer = null; }
+}
+
+/**
+ * True only when injecting is observably safe: claude TUI (not a bare shell), no API call in
+ * flight, no web-visible approval modal, no external (IM) injection holding the PTY.
+ * NOTE: a TUI-native fallback question (ask-bridge terminal fallback) is invisible to
+ * hasPendingApproval — which is why poll timeouts must NEVER fall through to an inject.
+ * NOTE 2: `isStreaming` (streamingState.active) flickers false between tool calls mid-turn;
+ * injecting into that gap is harmless (the TUI natively queues the paste) but it means an
+ * "immediate" inject can land inside the current turn's chain — accepted risk class.
+ */
+function _safeToInject() {
+  if (!_deps) return false;
+  if (_injecting) return false;
+  // A throwing probe means the wiring regressed — fail safe (no inject) but never silently:
+  // an untagged swallow here would wedge the whole queue with no diagnostic.
+  try { if (_deps.getPtyKind && _deps.getPtyKind() !== 'claude') return false; }
+  catch (err) { reportSwallowed('chat-queue.probe', err); return false; }
+  try { if (_deps.isStreaming && _deps.isStreaming()) return false; }
+  catch (err) { reportSwallowed('chat-queue.probe', err); return false; }
+  try { if (_deps.hasPendingApproval && _deps.hasPendingApproval()) return false; }
+  catch (err) { reportSwallowed('chat-queue.probe', err); return false; }
+  try { if (_deps.hasExternalInjection && _deps.hasExternalInjection()) return false; }
+  catch (err) { reportSwallowed('chat-queue.probe', err); return false; }
+  return true;
+}
+
+/**
+ * Inject the head item. Caller must have verified _safeToInject() first (except the internal
+ * re-checks here, which keep this self-guarding for direct calls).
+ * Broadcasts on shift (so the bubble disappears the moment the message starts typing into the
+ * TUI) and again if the write fails and the item returns to the head.
+ */
+function _injectHead() {
+  if (!_safeToInject()) return false;
+  const item = _items.shift();
+  if (!item) return false;
+  _broadcast();
+  _injecting = true;
+  const gen = _gen; // invalidate on clear()/stop(): a stale completion must not re-park
+  try {
+    _deps.writeToPtySequential(bracketPasteSubmit(item.text), (ok) => {
+      _injecting = false;
+      if (gen !== _gen) return;
+      if (!ok) {
+        // Dead PTY / write failure — never lose the message silently; put it back.
+        _items.unshift(item);
+        _broadcast();
+      }
+    }, { settleMs: 250 });
+  } catch (err) {
+    _injecting = false;
+    if (gen === _gen) {
+      _items.unshift(item);
+      _broadcast();
+    }
+    reportSwallowed('chat-queue.inject', err);
+  }
+  return true;
+}
+
+/**
+ * Poll (≤ INJECT_POLL_MAX_MS) until _safeToInject(), then run fn. On timeout: do NOT inject —
+ * invoke onTimeout instead (caller decides: keep queued / restore item). A timed-out blind
+ * write could land in a TUI-native question prompt and be submitted as its answer.
+ * Tick-counted (not Date-based) so mock.timers without Date mocking can drive it in tests.
+ */
+function _pollUntilSafe(fn, onTimeout) {
+  _clearPollTimer();
+  const maxTicks = Math.ceil(INJECT_POLL_MAX_MS / INJECT_POLL_MS);
+  let ticks = 0;
+  _pollTimer = setInterval(() => {
+    ticks += 1;
+    if (ticks > maxTicks) {
+      _clearPollTimer();
+      if (onTimeout) onTimeout();
+      return;
+    }
+    if (!_safeToInject()) return;
+    _clearPollTimer();
+    fn();
+  }, INJECT_POLL_MS);
+  if (typeof _pollTimer.unref === 'function') _pollTimer.unref();
+}
+
+/**
+ * Enqueue a chat-composer message (Claude believed busy). Sanitizes control bytes (a crafted
+ * `\x1b[201~` would otherwise break the paste frame), broadcasts, and arms a rescue timer for
+ * the stale-busy case (frontend's isStreaming lags the real turn end by up to its debounce).
+ */
+export function enqueue(text) {
+  if (!_deps) return null;
+  const clean = sanitizeInbound(text == null ? '' : String(text)).trim();
+  if (!clean) return null;
+  if (_items.length >= MAX_ITEMS) {
+    // Negative ack: the frontend cleared the composer optimistically — never fail silently.
+    console.warn('[chat-queue] queue full, rejecting message');
+    try { _deps.broadcastWs({ type: 'queue-rejected', reason: 'full' }); }
+    catch (err) { reportSwallowed('chat-queue.reject-broadcast', err); }
+    return null;
+  }
+  const item = _makeItem(clean);
+  _items.push(item);
+  _clearRescueTimer();
+  _broadcast();
+  let streaming = false;
+  try { streaming = !!(_deps.isStreaming && _deps.isStreaming()); } catch { streaming = false; }
+  if (!streaming) {
+    // Frontend guessed busy but the server sees no API call in flight: the turn may have ended
+    // just before enqueue and its turn-end hook already ran. Rescue after a short settle —
+    // falling back to the idle poll (not a single shot) so a transient busy/approval state
+    // retries within the poll budget instead of stranding the item.
+    _rescueTimer = setTimeout(() => {
+      _rescueTimer = null;
+      if (_suppressDrain || _pollTimer) return; // parked, or a drain/send-now poll already owns it
+      if (_safeToInject()) { _injectHead(); return; }
+      _pollUntilSafe(() => { if (!_suppressDrain) _injectHead(); }, () => { /* keep queued */ });
+    }, RESCUE_AFTER_MS);
+    if (typeof _rescueTimer.unref === 'function') _rescueTimer.unref();
+  }
+  return item;
+}
+
+/** Remove one queued item by id. Returns true when found. */
+export function remove(id) {
+  const idx = _items.findIndex((it) => it.id === id);
+  if (idx < 0) return false;
+  _items.splice(idx, 1);
+  _broadcast();
+  return true;
+}
+
+/** Drop all queued items (session switch). Also cancels pending timers and invalidates any
+ *  in-flight inject (gen bump) so an old-session message can never land in a fresh PTY.
+ *  Cannot cancel bytes already written to the PTY (best-effort, ~330ms window). */
+export function clear() {
+  _gen++;
+  _clearRescueTimer();
+  _clearPollTimer();
+  _clearEscTimer();
+  if (_items.length === 0) return;
+  _items = [];
+  _broadcast();
+}
+
+/**
+ * Send-now: interrupt the running turn and inject this item immediately.
+ * Guard order matters (review P0): refuse BEFORE touching the queue when an inject is in
+ * flight, so a double-action can never strand a removed-but-unsent message.
+ */
+export function sendNow(id) {
+  if (!_deps) return false;
+  // Guard order matters (review P0): refuse BEFORE touching the queue. `_injecting` covers an
+  // in-flight paste; `_pollTimer` covers a prior send-now still in its ESC/idle-poll phase —
+  // a second poll would clobber the first one's timer and strand its already-removed item.
+  if (_injecting || _pollTimer) return false;
+  try { if (_deps.hasExternalInjection && _deps.hasExternalInjection()) return false; } catch { return false; }
+  const idx = _items.findIndex((it) => it.id === id);
+  if (idx < 0) return false;
+  const [item] = _items.splice(idx, 1);
+  _clearRescueTimer();
+  _broadcast();
+
+  const gen = _gen; // a clear()/stop() mid-flight invalidates the completion handler below
+  const inject = () => {
+    _injecting = true;
+    try {
+      _deps.writeToPtySequential(bracketPasteSubmit(item.text), (ok) => {
+        _injecting = false;
+        if (gen !== _gen) return;
+        if (!ok) { _items.unshift(item); _broadcast(); }
+      }, { settleMs: 250 });
+    } catch (err) {
+      _injecting = false;
+      if (gen === _gen) {
+        _items.unshift(item);
+        _broadcast();
+      }
+      reportSwallowed('chat-queue.send-now.inject', err);
+    }
+  };
+  const restore = () => {
+    // Never blind-inject (see _pollUntilSafe). Park the item back at the head.
+    if (gen !== _gen) return;
+    if (!_items.some((it) => it.id === item.id)) {
+      _items.unshift(item);
+      _broadcast();
+    }
+  };
+
+  let streaming = false;
+  try { streaming = !!(_deps.isStreaming && _deps.isStreaming()); } catch { streaming = false; }
+  if (streaming) {
+    // Interrupt first: focus-in (a hidden xterm is unfocused; Ink ignores ESC then) then ESC —
+    // byte-identical to the web Stop button (ChatView handleInputStop). The gap timer is
+    // tracked so stop()/clear() can cancel it before it lands in a fresh PTY.
+    try { _deps.writeToPty('\x1b[I'); } catch (err) { reportSwallowed('chat-queue.send-now.focus', err); }
+    _escTimer = setTimeout(() => {
+      _escTimer = null;
+      try { _deps.writeToPty('\x1b'); } catch (err) { reportSwallowed('chat-queue.send-now.esc', err); }
+      _pollUntilSafe(inject, restore);
+    }, STOP_ESC_DELAY_MS);
+    if (typeof _escTimer.unref === 'function') _escTimer.unref();
+  } else if (_safeToInject()) {
+    // Idle / parked queue (e.g. after Stop): no interrupt needed — inject right away.
+    inject();
+  } else {
+    _pollUntilSafe(inject, restore);
+  }
+  return true;
+}
+
+/**
+ * Turn-end hook (Stop-hook POST arrival + debounced emit; idempotent). Drains the head item
+ * once the TUI is observably idle. Suppressed after a user Stop until a new turn starts.
+ */
+export function onTurnEnd() {
+  if (!_deps || _items.length === 0 || _injecting) return;
+  // A send-now poll is already pending — it owns the next inject; let it finish rather than
+  // clear its timer out from under it (clearing would strand the removed item).
+  if (_pollTimer) return;
+  _clearRescueTimer();
+  if (_suppressDrain) return;
+  if (_safeToInject()) { _injectHead(); return; }
+  _pollUntilSafe(() => { if (!_suppressDrain) _injectHead(); }, () => { /* keep queued; next turn-end retries */ });
+}
+
+/** Park the queue: the next turn-end(s) must not auto-drain (user pressed Stop). */
+export function suppressNextDrain() {
+  _suppressDrain = true;
+  _clearRescueTimer();
+}
+
+/** A new turn started (streaming rising edge): re-arm automatic draining. */
+export function onStreamingActivated() {
+  _suppressDrain = false;
+}
+
+/** Server shutdown: drop timers AND queue state — parked items belong to the dying session
+ *  and must not drain into the fresh PTY after a stop/start cycle. */
+export function stop() {
+  _clearRescueTimer();
+  _clearPollTimer();
+  _clearEscTimer();
+  _injecting = false;
+  _items = [];
+  _suppressDrain = false;
+  _gen++;
+}
+
+export function __resetForTests() {
+  stop();
+  _deps = null;
+}