@idl3/claude-control 0.2.1 → 0.4.0

package/lib/skills.js

@@ -1,17 +1,19 @@
 /**
  * lib/skills.js — discover and list available Claude slash-command skills.
  *
- * Skills are discovered from ~/.claude/skills/<name>/SKILL.md — the synced,
- * authoritative set of invocable slash commands. (Plugin skills are materialised
- * INTO this directory by `olam skills sync` with their correct prefixed names,
- * e.g. `100x:brainstorm`; we deliberately do NOT walk ~/.claude/plugins/cache,
- * whose raw dir names use dashes — `100x-debug` — and are NOT valid slash
- * commands, so prefilling them would not resolve.)
+ * Skills come from three places, lowest → highest priority:
+ *   1. PLUGIN skills — installed Claude Code plugins listed in
+ *      ~/.claude/plugins/installed_plugins.json. Each plugin `<name>@<market>`
+ *      has an installPath under which nested `skills/<skill>/SKILL.md` files
+ *      live; the slash command is `<name>:<skill>` (e.g. `100x` → `100x:plan-hard`).
+ *   2. USER skills — ~/.claude/skills/<name>/SKILL.md (synced/authored). The
+ *      directory name IS the slash slug (e.g. `olam:create`, `api-design`).
+ *   3. PROJECT skills — <cwd>/.claude/skills/<name>/SKILL.md for the session's
+ *      working directory; these override same-named user skills.
  *
- * For each directory that contains a SKILL.md, the skill's invocation name is
- * the directory name (e.g. `100x:brainstorm`, `api-design`). We parse the
- * SKILL.md YAML front-matter for `description` (and optionally `name`, but the
- * dir name is always the invocation slug).
+ * We parse each SKILL.md's YAML front-matter for `description`. Plugin SKILL.md
+ * paths aren't derivable from the slug, so we remember them in `_pluginPaths`
+ * for readSkill().
  *
  * Results are de-duped by name, sorted alphabetically, and cached for 30 s so
  * repeated opens don't cause repeated disk scans.
@@ -25,11 +27,39 @@ import path from 'node:path';
 
 const CACHE_TTL_MS = 30_000;
 
-/** @type {{ skills: SkillEntry[], ts: number } | null} */
-let _cache = null;
+/**
+ * The Claude config home. Honors CLAUDE_HOME_DIR (Claude Code relocates ~/.claude
+ * via this env var — the user sets it per project, e.g. atlas / grain / pleri-org
+ * / personal), falling back to ~/.claude. Skills + plugins are read from here.
+ *
+ * @returns {string}
+ */
+function claudeHome() {
+  const override = process.env.CLAUDE_HOME_DIR;
+  return override && override.trim() ? override : path.join(os.homedir(), '.claude');
+}
 
 /**
- * @typedef {{ name: string, description: string, source: 'user' | 'plugin' }} SkillEntry
+ * Per-cwd cache so different sessions (different cwds) each get their own
+ * merged skill list. Key: cwd string (or '' for the global user-only list).
+ * @type {Map<string, { skills: SkillEntry[], ts: number }>}
+ */
+const _cache = new Map();
+
+/**
+ * Plugin skill command-name → absolute SKILL.md path. Plugin paths can't be
+ * derived from the slug (they live deep under installPath), so we remember them
+ * here during discovery for readSkill(). Rebuilt on each plugin scan.
+ * @type {Map<string, string>}
+ */
+const _pluginPaths = new Map();
+
+// Directories never worth descending into when scanning a plugin tree.
+const _PLUGIN_SKIP = new Set(['node_modules', '.git', '.github', 'dist', 'build', 'coverage']);
+const _PLUGIN_MAX_DEPTH = 6;
+
+/**
+ * @typedef {{ name: string, description: string, source: 'user' | 'project' | 'plugin' }} SkillEntry
  */
 
 /**
@@ -37,14 +67,16 @@ let _cache = null;
  * subagents.js — scalar values only, no yaml dep. Returns null when no valid
  * front-matter block is found.
  *
+ * Returns both the key/value map AND the body text after the closing `---`.
+ *
  * @param {string} content
- * @returns {Record<string,string>|null}
+ * @returns {{ fm: Record<string,string>|null, body: string }}
  */
 function _parseFrontMatter(content) {
   const lines = content.split('\n');
-  if (lines[0].trim() !== '---') return null;
+  if (lines[0].trim() !== '---') return { fm: null, body: content };
   const end = lines.indexOf('---', 1);
-  if (end === -1) return null;
+  if (end === -1) return { fm: null, body: content };
   /** @type {Record<string,string>} */
   const result = {};
   for (let i = 1; i < end; i++) {
@@ -55,7 +87,11 @@ function _parseFrontMatter(content) {
     const val = line.slice(colon + 1).trim();
     if (key) result[key] = val;
   }
-  return Object.keys(result).length > 0 ? result : null;
+  const body = lines.slice(end + 1).join('\n');
+  return {
+    fm: Object.keys(result).length > 0 ? result : null,
+    body,
+  };
 }
 
 /**
@@ -73,7 +109,7 @@ function _readDescription(skillDir) {
   } catch {
     return '';
   }
-  const fm = _parseFrontMatter(content);
+  const { fm } = _parseFrontMatter(content);
   return fm?.description ?? '';
 }
 
@@ -83,10 +119,11 @@ function _readDescription(skillDir) {
  * files) are skipped.
  *
  * @param {string} dir
- * @param {'user' | 'plugin'} source
+ * @param {'user' | 'project'} source
  * @param {Map<string, SkillEntry>} into  de-dup map keyed by skill name
+ * @param {boolean} overwrite  when true, existing entries are replaced (project > user)
  */
-function _collectFrom(dir, source, into) {
+function _collectFrom(dir, source, into, overwrite = false) {
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -104,44 +141,218 @@ function _collectFrom(dir, source, into) {
     } catch {
       continue;
     }
-    // De-dup: first discovery wins (user skills before plugin).
-    if (into.has(skillName)) continue;
+    // De-dup: project skills override same-named user skills when overwrite=true.
+    if (!overwrite && into.has(skillName)) continue;
     const description = _readDescription(skillDir);
     into.set(skillName, { name: skillName, description, source });
   }
 }
 
 /**
- * Discover all available skills. Returns a de-duped, name-sorted array.
- * Result is cached for 30 s.
+ * Register every `<skillsDir>/<skill>/SKILL.md` as `<pluginSlug>:<skill>`.
+ * Lowest priority — never overwrites a user/project (or earlier-plugin) entry.
+ *
+ * @param {string} skillsDir
+ * @param {string} pluginSlug
+ * @param {Map<string, SkillEntry>} into
+ */
+function _registerPluginSkillsIn(skillsDir, pluginSlug, into) {
+  let entries;
+  try {
+    entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const mdPath = path.join(skillsDir, ent.name, 'SKILL.md');
+    let content;
+    try {
+      content = fs.readFileSync(mdPath, 'utf8');
+    } catch {
+      continue;
+    }
+    const cmd = `${pluginSlug}:${ent.name}`;
+    if (into.has(cmd)) continue; // user/project or an earlier plugin path wins
+    const { fm } = _parseFrontMatter(content);
+    into.set(cmd, { name: cmd, description: fm?.description ?? '', source: 'plugin' });
+    _pluginPaths.set(cmd, mdPath);
+  }
+}
+
+/**
+ * Recursively walk a plugin install dir looking for `skills/` directories (the
+ * tree nests them under members/<x>/skills, shared/<x>/skills, etc.). Bounded
+ * depth + skip-list keep it cheap.
+ *
+ * @param {string} dir
+ * @param {string} pluginSlug
+ * @param {Map<string, SkillEntry>} into
+ * @param {number} depth
+ */
+function _scanPluginDir(dir, pluginSlug, into, depth) {
+  if (depth > _PLUGIN_MAX_DEPTH) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const ent of entries) {
+    if (!ent.isDirectory() || _PLUGIN_SKIP.has(ent.name)) continue;
+    const sub = path.join(dir, ent.name);
+    if (ent.name === 'skills') _registerPluginSkillsIn(sub, pluginSlug, into);
+    else _scanPluginDir(sub, pluginSlug, into, depth + 1);
+  }
+}
+
+/**
+ * Discover skills from every installed Claude Code plugin. The slash command is
+ * `<pluginName>:<skillDir>` where pluginName is the part before `@` in the
+ * installed_plugins.json key (e.g. `100x@atlas-one` → `100x:plan-hard`).
  *
+ * @param {Map<string, SkillEntry>} into
+ */
+function _collectPluginSkills(into) {
+  _pluginPaths.clear();
+  const jsonPath = path.join(claudeHome(), 'plugins', 'installed_plugins.json');
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  } catch {
+    return;
+  }
+  const plugins = manifest?.plugins;
+  if (!plugins || typeof plugins !== 'object') return;
+  for (const [key, arr] of Object.entries(plugins)) {
+    const pluginSlug = String(key).split('@')[0];
+    if (!pluginSlug) continue;
+    for (const e of Array.isArray(arr) ? arr : []) {
+      const installPath = e?.installPath;
+      if (typeof installPath === 'string' && installPath) {
+        _scanPluginDir(installPath, pluginSlug, into, 0);
+      }
+    }
+  }
+}
+
+/**
+ * Discover all available skills for a given session cwd. Merges project skills
+ * (from <cwd>/.claude/skills/) on top of user skills (from ~/.claude/skills/),
+ * with plugin skills as the base layer. Project > user > plugin on name clash.
+ * Results are cached per-cwd for 30 s.
+ *
+ * @param {string|null} [cwd]  the session's working directory; null/undefined = user skills only
  * @returns {SkillEntry[]}
  */
-export function listSkills() {
+export function listSkills(cwd) {
+  const cacheKey = cwd ?? '';
   const now = Date.now();
-  if (_cache && now - _cache.ts < CACHE_TTL_MS) {
-    return _cache.skills;
+  const hit = _cache.get(cacheKey);
+  if (hit && now - hit.ts < CACHE_TTL_MS) {
+    return hit.skills;
   }
 
-  const home = os.homedir();
   /** @type {Map<string, SkillEntry>} */
   const byName = new Map();
 
-  // ~/.claude/skills/<name>/SKILL.md — the synced, correctly-named invocable set.
-  const userSkillsDir = path.join(home, '.claude', 'skills');
-  _collectFrom(userSkillsDir, 'user', byName);
+  // 1. Plugin skills — the base layer (e.g. 100x:plan-hard from installed plugins).
+  _collectPluginSkills(byName);
+
+  // 2. User skills override plugins on name clash.
+  const userSkillsDir = path.join(claudeHome(), 'skills');
+  _collectFrom(userSkillsDir, 'user', byName, true);
+
+  // 3. Project skills override user + plugin.
+  if (cwd) {
+    const projectSkillsDir = path.join(cwd, '.claude', 'skills');
+    _collectFrom(projectSkillsDir, 'project', byName, true);
+  }
 
   const skills = [...byName.values()].sort((a, b) =>
     a.name.localeCompare(b.name),
   );
 
-  _cache = { skills, ts: now };
+  _cache.set(cacheKey, { skills, ts: now });
   return skills;
 }
 
+/**
+ * Read a single skill's SKILL.md content, validated against the discovered set
+ * for the given session cwd (traversal guard: only reads files in known dirs).
+ *
+ * @param {string} name  skill name (directory name, e.g. '100x:brainstorm')
+ * @param {string|null} [cwd]  session working directory
+ * @returns {{ name: string, source: 'user'|'project', frontMatter: Record<string,string>, body: string }|null}
+ */
+export function readSkill(name, cwd) {
+  // Validate name: must appear in the discovered set for this cwd.
+  const discovered = listSkills(cwd);
+  const entry = discovered.find((s) => s.name === name);
+  if (!entry) return null;
+
+  // Plugin skills: resolve from the remembered SKILL.md path, guarded to stay
+  // under the claude home plugins dir (defence in depth — path came from our scan).
+  if (entry.source === 'plugin') {
+    const md = _pluginPaths.get(name);
+    if (!md) return null;
+    const pluginsRoot = path.resolve(path.join(claudeHome(), 'plugins'));
+    const resolved = path.resolve(md);
+    if (!resolved.startsWith(pluginsRoot + path.sep)) return null;
+    let content;
+    try {
+      content = fs.readFileSync(resolved, 'utf8');
+    } catch {
+      return null;
+    }
+    const { fm, body } = _parseFrontMatter(content);
+    return { name, source: 'plugin', frontMatter: fm ?? {}, body: body.trimStart() };
+  }
+
+  // User/project skills: resolve the correct directory WITHOUT interpolating
+  // `name` or `cwd` into an arbitrary path. We only look in the two known roots.
+  const userSkillsDir = path.join(claudeHome(), 'skills');
+  const projectSkillsDir = cwd ? path.join(cwd, '.claude', 'skills') : null;
+
+  // Security: resolve the canonical path of the SKILL.md and ensure it stays
+  // inside the expected root (prevents any path-traversal via name).
+  function safeRead(root) {
+    if (!root) return null;
+    // path.join normalises '..' segments; then we check the result is still
+    // inside root.
+    const candidate = path.join(root, name, 'SKILL.md');
+    const resolvedRoot = path.resolve(root);
+    const resolvedCandidate = path.resolve(candidate);
+    if (!resolvedCandidate.startsWith(resolvedRoot + path.sep)) return null;
+    let content;
+    try {
+      content = fs.readFileSync(resolvedCandidate, 'utf8');
+    } catch {
+      return null;
+    }
+    return content;
+  }
+
+  // Prefer project skill over user skill (matches listing precedence).
+  const content =
+    (projectSkillsDir ? safeRead(projectSkillsDir) : null) ??
+    safeRead(userSkillsDir);
+  if (content === null) return null;
+
+  const { fm, body } = _parseFrontMatter(content);
+
+  return {
+    name,
+    source: entry.source,
+    frontMatter: fm ?? {},
+    body: body.trimStart(),
+  };
+}
+
 /**
  * Bust the in-process cache. Used in tests.
  */
 export function _bustCache() {
-  _cache = null;
+  _cache.clear();
+  _pluginPaths.clear();
 }

package/lib/subagents.js

@@ -26,8 +26,15 @@ import { TranscriptTailer } from './transcript.js';
 const META_RE = /^agent-(.+)\.meta\.json$/;
 // A sub-agent whose transcript hasn't grown in this long is treated as finished,
 // even if we never saw the parent's tool_result (e.g. it predates the parent's
-// bounded message buffer). Live sub-agents append continuously.
-const RUNNING_WINDOW_MS = 45_000;
+// bounded message buffer). Live sub-agents append whenever the LLM produces a
+// token or tool result, but long inference calls (extended thinking, slow tools)
+// can pause writes for several minutes. 600 s (10 min) covers realistic worst-case
+// LLM pauses while still expiring stale-but-finished agents whose tool_result
+// predates the bounded parent buffer. doneByParent always wins when available.
+const RUNNING_WINDOW_MS = 600_000;
+// A file written within this window is treated as actively-running, overriding a
+// (possibly premature, e.g. background-launch-ack) doneByParent flag.
+const ACTIVE_WINDOW_MS = 20_000;
 
 // ---------------------------------------------------------------------------
 // Agent definition front-matter cache + discovery
@@ -134,6 +141,109 @@ function _lookupAgentDef(agentType) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Agent listing — mirrors lib/skills.js `listSkills` pattern
+// ---------------------------------------------------------------------------
+
+/** 30-second TTL for the agent list cache. */
+const AGENTS_CACHE_TTL_MS = 30_000;
+
+/**
+ * Per-cwd cache so different sessions each get their own merged agent list.
+ * Key: cwd string (or '' for the process-cwd-only list).
+ * @type {Map<string, { agents: AgentEntry[], ts: number }>}
+ */
+const _agentsCache = new Map();
+
+/**
+ * @typedef {{ name: string, description: string, source: 'user' | 'project' | 'plugin' }} AgentEntry
+ */
+
+/**
+ * Discover all available agent definitions for a given session cwd.
+ * Merges roots from `_agentSearchRoots()` (user + plugin + process.cwd agents)
+ * plus the session-specific cwd agents dir when provided.
+ *
+ * Priority (highest → lowest): project > user > plugin.
+ * Implemented by processing roots in order plugin → user → project and
+ * overwriting on name clash (later entry wins), which yields project-last = wins.
+ *
+ * Results are cached per-cwd for AGENTS_CACHE_TTL_MS.
+ *
+ * @param {string|null} [cwd]  the session's working directory; null = no project agents
+ * @returns {AgentEntry[]}
+ */
+export function listAgents(cwd) {
+  const cacheKey = cwd ?? '';
+  const now = Date.now();
+  const hit = _agentsCache.get(cacheKey);
+  if (hit && now - hit.ts < AGENTS_CACHE_TTL_MS) {
+    return hit.agents;
+  }
+
+  const home = os.homedir();
+  const pluginCacheRoot = path.join(home, '.claude', 'plugins', 'cache');
+
+  // Collect roots from _agentSearchRoots() (includes user + plugin cache + process.cwd agents).
+  const baseRoots = _agentSearchRoots();
+
+  // Also include the session-specific cwd agents dir when it differs from process.cwd().
+  const cwdAgentsDir = cwd ? path.join(cwd, '.claude', 'agents') : null;
+  const allRoots = cwdAgentsDir && !baseRoots.includes(cwdAgentsDir)
+    ? [...baseRoots, cwdAgentsDir]
+    : baseRoots;
+
+  /**
+   * Classify a root by source priority.
+   * Plugin roots live under ~/.claude/plugins/cache.
+   * The user root is ~/.claude/agents.
+   * Everything else is treated as project (cwd-local).
+   *
+   * We process in order: plugin → user → project so that when names clash
+   * the last write wins, giving project > user > plugin precedence.
+   */
+  const classifyRoot = (/** @type {string} */ dir) => {
+    if (dir.startsWith(pluginCacheRoot + path.sep) || dir === pluginCacheRoot) return 'plugin';
+    if (dir === path.join(home, '.claude', 'agents')) return 'user';
+    return 'project';
+  };
+
+  // Sort roots: plugin first, then user, then project (so project overwrites on clash).
+  const priority = { plugin: 0, user: 1, project: 2 };
+  const sortedRoots = [...allRoots].sort((a, b) => priority[classifyRoot(a)] - priority[classifyRoot(b)]);
+
+  /** @type {Map<string, AgentEntry>} */
+  const byName = new Map();
+
+  for (const dir of sortedRoots) {
+    const source = classifyRoot(dir);
+    let files;
+    try { files = fs.readdirSync(dir); } catch { continue; }
+    for (const filename of files) {
+      if (!filename.endsWith('.md')) continue;
+      const filePath = path.join(dir, filename);
+      let content;
+      try { content = fs.readFileSync(filePath, 'utf8'); } catch { continue; }
+      const fm = _parseFrontMatter(content);
+      const name = fm?.name?.trim() || filename.slice(0, -3); // sans .md
+      const description = fm?.description ?? '';
+      // Overwrite unconditionally — sortedRoots ordering ensures project wins last.
+      byName.set(name, { name, description, source });
+    }
+  }
+
+  const agents = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+  _agentsCache.set(cacheKey, { agents, ts: now });
+  return agents;
+}
+
+/**
+ * Bust the in-process agents cache. Used in tests.
+ */
+export function _bustAgentsCache() {
+  _agentsCache.clear();
+}
+
 export class SubAgentsWatcher extends EventEmitter {
   /**
    * @param {string} transcriptPath  absolute path to the PARENT transcript
@@ -257,13 +367,23 @@ export class SubAgentsWatcher extends EventEmitter {
    * even when their parent tool_result predates the bounded message buffer.
    */
   _statusFor(a) {
-    if (a.doneByParent) return 'done';
+    let mtimeMs = null;
     try {
-      const mtimeMs = fs.statSync(a.jsonlPath).mtimeMs;
-      return Date.now() - mtimeMs < RUNNING_WINDOW_MS ? 'running' : 'done';
+      mtimeMs = fs.statSync(a.jsonlPath).mtimeMs;
     } catch {
       return 'done';
     }
+    const age = Date.now() - mtimeMs;
+    // Actively being written → RUNNING, even if the parent already emitted a
+    // tool_result for this agent. A BACKGROUND agent's launch-ack tool_result
+    // lands IMMEDIATELY (setting doneByParent) while the agent keeps writing for
+    // minutes — without this override it would wrongly read as done the whole run.
+    if (age < ACTIVE_WINDOW_MS) return 'running';
+    // Quiet file: the parent's tool_result is now authoritative (foreground agents
+    // go quiet exactly at completion → done within ACTIVE_WINDOW). Otherwise fall
+    // back to the longer freshness window (covers long mid-inference pauses).
+    if (a.doneByParent) return 'done';
+    return age < RUNNING_WINDOW_MS ? 'running' : 'done';
   }
 
   _entry(a) {

package/lib/terminal.js

@@ -151,12 +151,36 @@ export async function ensureTerminal(id, target) {
       clearTimeout(existing.idleTimer);
       existing.idleTimer = null;
     }
+    existing.lastUsed = Date.now();
     const port = await existing.ready;
     return { port };
   }
 
-  if (terminals.size >= MAX_TERMINALS) {
-    throw new Error(`terminal cap reached (${MAX_TERMINALS} live); close one and retry`);
+  // LRU bound: keep at most MAX_TERMINALS live. When full, evict the
+  // least-recently-used terminal (preferring ones with no connected clients)
+  // instead of erroring — the UI keeps the latest few warm and expects older
+  // ones to be offloaded silently.
+  while (terminals.size >= MAX_TERMINALS) {
+    let victimId = null;
+    let victim = null;
+    for (const [vid, t] of terminals) {
+      if (!victim) {
+        victimId = vid;
+        victim = t;
+        continue;
+      }
+      const vIdle = victim.clients.size === 0;
+      const tIdle = t.clients.size === 0;
+      if (tIdle && !vIdle) {
+        victimId = vid;
+        victim = t;
+      } else if (tIdle === vIdle && (t.lastUsed || 0) < (victim.lastUsed || 0)) {
+        victimId = vid;
+        victim = t;
+      }
+    }
+    if (victimId == null) break;
+    reap(victimId);
   }
 
   const tmuxBin = await tmux.resolveTmuxBin();
@@ -229,10 +253,13 @@ export async function ensureTerminal(id, target) {
   });
 
   /** @type {Terminal} */
-  const term = { proc, port, target, clients: new Set(), idleTimer: null, ready };
+  const term = { proc, port, target, clients: new Set(), idleTimer: null, ready, lastUsed: Date.now() };
   terminals.set(id, term);
 
   const readyPort = await ready;
+  // Pin the window to its largest client so this extra (cockpit) attach never
+  // shrinks the user's real terminal. Best-effort — don't fail the open on it.
+  tmux.setWindowSizeLargest(target).catch(() => {});
   return { port: readyPort };
 }
 
@@ -248,6 +275,7 @@ export function addClient(id, client) {
   const term = terminals.get(id);
   if (!term) return;
   term.clients.add(client);
+  term.lastUsed = Date.now();
   if (term.idleTimer) {
     clearTimeout(term.idleTimer);
     term.idleTimer = null;

package/lib/tmux.js

@@ -92,8 +92,13 @@ export async function getSocketPath() {
 // Target validation
 // ---------------------------------------------------------------------------
 
-/** Pattern from CONTRACT: ^[A-Za-z0-9_.-]+:\d+(\.\d+)?$ */
-const TARGET_RE = /^[A-Za-z0-9_.-]+:\d+(\.\d+)?$/;
+// tmux session names allow spaces and punctuation (e.g. a grouped session named
+// "claude-control & olam"). The session-name part is therefore any run of
+// printable chars EXCEPT the `:` target delimiter and control chars; then
+// `:window(.pane)`. Targets only ever reach tmux as an execFile/spawn argv (never
+// a shell), so spaces/`&` can't inject — and ids from clients must additionally
+// resolve via sessionById. Window/pane segments stay strictly numeric.
+const TARGET_RE = /^[^\x00-\x1f:]+:\d+(\.\d+)?$/;
 
 /**
  * Returns true when `target` is a syntactically valid tmux target string.
@@ -429,6 +434,21 @@ export async function setPaneOption(target, name, value) {
   await runTmux(['set-option', '-p', '-t', target, name, String(value)]);
 }
 
+/**
+ * Size the window to its LARGEST attached client, not the latest/smallest. The
+ * cockpit's ttyd attaches as an extra client; with tmux's default `window-size
+ * latest` that extra client shrinks the user's real terminal ("cramped"). With
+ * `largest`, the user's full-size terminal wins and the cockpit view just
+ * letterboxes. Best-effort; window option set via the pane's target.
+ *
+ * @param {string} target  pane/window target
+ * @returns {Promise<void>}
+ */
+export async function setWindowSizeLargest(target) {
+  assertTarget(target);
+  await runTmux(['set-option', '-w', '-t', target, 'window-size', 'largest']);
+}
+
 // ---------------------------------------------------------------------------
 // Rename window
 // ---------------------------------------------------------------------------

package/lib/transcribe.js

@@ -61,11 +61,15 @@ export function resolveWhisperBin() {
 export function resolveWhisperModel() {
   const e = process.env.WHISPER_MODEL;
   if (e && e.trim() && fs.existsSync(e.trim())) return e.trim();
+  // Prefer multilingual models (no `.en`) when present: a `.en` model can ONLY
+  // do English, so if the user dropped in a multilingual ggml they want the mix
+  // (English + Chinese + Singlish/…). English-only models are the fallback.
   const prefs = [
+    'ggml-medium.bin',
+    'ggml-small.bin',
+    'ggml-base.bin',
     'ggml-base.en.bin',
     'ggml-small.en.bin',
-    'ggml-base.bin',
-    'ggml-small.bin',
     'ggml-tiny.en.bin',
   ];
   for (const m of prefs) {
@@ -121,13 +125,16 @@ function run(bin, args) {
 }
 
 /**
- * Transcribe an audio file (any ffmpeg-readable format) to text.
+ * Transcribe an audio file (any ffmpeg-readable format) to text — always in
+ * English. A multilingual model uses Whisper's TRANSLATE task, so Chinese,
+ * Singlish, and mixed speech all come back as English. English-only (`.en`)
+ * models are already English; nothing to translate.
  *
  * @param {string} inputPath - path to the recorded audio file.
  * @param {{ lang?: string }} [opts]
  * @returns {Promise<string>}
  */
-export async function transcribe(inputPath, { lang = 'en' } = {}) {
+export async function transcribe(inputPath, { lang } = {}) {
   const ffmpeg = resolveFfmpeg();
   const whisper = resolveWhisperBin();
   const model = resolveWhisperModel();
@@ -135,6 +142,13 @@ export async function transcribe(inputPath, { lang = 'en' } = {}) {
   if (!whisper) throw new Error('whisper-cli not found (brew install whisper-cpp)');
   if (!model) throw new Error(`no whisper model found in ${MODELS_DIR}`);
 
+  // `.en` models do English only; multilingual models auto-detect the source then
+  // translate it to English. Source language is overridable (lang / WHISPER_LANG)
+  // for the rare case you want to pin detection; output stays English.
+  const englishOnly = /\.en\.bin$/i.test(path.basename(model));
+  const effLang = lang || process.env.WHISPER_LANG || (englishOnly ? 'en' : 'auto');
+  const translate = !englishOnly; // → always-English output
+
   const wav = path.join(
     os.tmpdir(),
     `cc-stt-${Date.now()}-${process.pid}.wav`,
@@ -147,7 +161,8 @@ export async function transcribe(inputPath, { lang = 'en' } = {}) {
       '-f', 'wav', wav,
     ]);
     const { stdout } = await run(whisper, [
-      '-m', model, '-f', wav, '-np', '-nt', '-l', lang,
+      '-m', model, '-f', wav, '-np', '-nt', '-l', effLang,
+      ...(translate ? ['--translate'] : []),
     ]);
     return cleanTranscript(stdout);
   } finally {