@brimveyn/aimux 1.20.1 → 1.20.3

package/README.md

@@ -36,6 +36,12 @@ bun install -g @brimveyn/aimux
 
 Requires [Bun](https://bun.sh).
 
+Shell completion (bash, zsh, fish) installs itself the first time you launch
+the TUI — one file in your shell's completions directory, no dotfile edits.
+Run `aimux doctor` to see where it landed, or
+`aimux completion install --shell zsh` to place it yourself. Opt out with
+`AIMUX_NO_COMPLETION_INSTALL=1`. See [docs/reference/cli.md](docs/reference/cli.md#aimux-completion).
+
 ## Quick Start
 
 Create the default profile and install the typed config package into it:
@@ -170,7 +176,9 @@ See [`docs/reference/cli.md`](docs/reference/cli.md) for behavior details.
 
 For agent orchestration, prefer the named `aimux worker` commands. They combine
 isolated worktree creation, prompt dispatch, authoritative turn waiting, fleet
-inspection, and guarded cleanup without shell wrappers or `jq`.
+inspection, and guarded cleanup without shell wrappers or `jq`. Pin the target
+with `--workspace` (or `AIMUX_WORKSPACE`) for anything long-running: the default
+follows whichever workspace the UI opened last.
 
 ## Runtime Model
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.20.1",
+  "version": "1.20.3",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode, Kimi side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",

package/skills/aimux-orchestrator/SKILL.md

@@ -12,7 +12,7 @@ Own the plan and quality gate. Let aimux own worker transport and lifecycle.
 Run once:
 
 ```bash
-aimux worker doctor
+aimux worker doctor --workspace <target>
 aimux worker --help
 ```
 
@@ -20,6 +20,14 @@ Stop if the doctor reports missing worker capabilities, the wrong workspace, or
 an unavailable assistant. Restart/update aimux as instructed; do not fall back
 to screen scraping or the legacy shell wrappers.
 
+**Pin the workspace and verify the repo before dispatching anything.** Without
+`--workspace` (or `AIMUX_WORKSPACE`) aimux targets whichever workspace the UI
+opened last, and that can change under you mid-run — including to a different
+project. Check `checks.workspace.repoRoot` in the doctor output against the
+repository you mean, then pass `--workspace <id|name>` on **every** call (all
+examples below do). Every worker response echoes `workspace.repoRoot`; read it on
+the first dispatch instead of assuming.
+
 ## Orchestration loop
 
 1. Parse the plan into independently reviewable units and dependencies.
@@ -29,19 +37,20 @@ to screen scraping or the legacy shell wrappers.
 
 ```bash
 aimux worker run \
+  --workspace <target> \
   --name feat-auth \
   --assistant claude \
   --prompt-file /tmp/feat-auth.md \
   --detach
 ```
 
-5. Inspect the fleet with `aimux worker list`.
-6. Await a detached worker with `aimux worker await feat-auth`.
+5. Inspect the fleet with `aimux worker list --workspace <target>`.
+6. Await a detached worker with `aimux worker await feat-auth --workspace <target>`.
 7. If a worker asks a question, answer only when the plan already determines the
    answer:
 
 ```bash
-aimux worker prompt feat-auth --prompt-file /tmp/answer.md
+aimux worker prompt feat-auth --workspace <target> --replace --prompt-file /tmp/answer.md
 ```
 
 Escalate design choices, irreversible operations, deployments, pushes,
@@ -54,9 +63,32 @@ migrations, spending, and external communication to the human.
 10. After integration, close and clean up:
 
 ```bash
-aimux worker stop feat-auth --cleanup-worktree
+aimux worker stop feat-auth --workspace <target> --cleanup-worktree
 ```
 
+## Dispatch failure modes
+
+Read these before the first dispatch; each one otherwise reads as a lost fleet.
+
+- **`status: "pending-submit"` (exit 11)** — the prompt is sitting unsubmitted in
+  the worker's composer. The worker is alive and healthy. Recover with
+  `aimux worker submit <name> --workspace <target>`; never re-dispatch, which
+  would double the fleet onto the same branches. Widen the confirmation window
+  with `--uptake-timeout <ms>` for slow-booting assistants.
+- **An empty `worker list`** — read the `workspace` field in the response. An
+  empty fleet in the wrong workspace is not a dead fleet. Add
+  `--all-workspaces` to answer "are they really gone?" in one call;
+  `git worktree list` in the target repo is the on-disk cross-check.
+- **Composer contamination** — a human typing in a worker's tab leaves text that
+  `worker prompt` would append to, merging both into one incoherent instruction.
+  Use `--replace` (clears with `<C-u>`) for every correction, and
+  `aimux tab snapshot <tabId>` when a worker's behaviour doesn't match the
+  prompt you believe you sent.
+- **Fresh worktrees are not provisioned** — a new worktree has no installed
+  dependencies and no generated files. Every dispatch prompt must tell the worker
+  to bootstrap before running any gate (see `references/prompts.md`), or it will
+  report environment failures as its own.
+
 ## Isolation
 
 `worker run` creates a fresh worktree by default. Keep that default when writes
@@ -78,6 +110,8 @@ may overlap or scope is uncertain.
 - Prefer `--prompt-file` for multiline prompts; it avoids shell quoting hazards.
 - Use `--detach` for parallel launch. Without it, `worker run` waits and returns
   a completed/question/timeout/error outcome.
+- Pass `--workspace` on every call, and confirm the `repoRoot` the first response
+  reports is the repository you intend to change.
 
 ## Quality and safety
 

package/skills/aimux-orchestrator/references/prompts.md

@@ -23,6 +23,12 @@
 
 - <machine-checkable criterion>
 
+## Environment
+
+This is a fresh worktree: it has no installed dependencies and no generated
+files. Run <the repo's install + codegen commands> before any verification gate,
+and report a bootstrap failure as a bootstrap failure — never as a failing gate.
+
 ## Verification
 
 Run the repository's tests, typecheck, lint, and build commands that apply.
@@ -32,6 +38,11 @@ Report changed files, commands run, results, and remaining risks.
 Tell the worker to read repository instructions before editing. Do not ask it to
 merge, push, deploy, or clean up its worktree.
 
+Keep the **Environment** block. A fresh `git worktree` shares history, not build
+state: no `node_modules`, no generated clients or route files. Without it workers
+run the gates in a half-provisioned tree, fail for environment reasons, and report
+those failures as if they were their own.
+
 ## Correction
 
 ```markdown

package/src/auto-rename/coordinator.ts

@@ -1,13 +1,18 @@
 import type { AssistantId } from '../state/types'
 
 import { isSupportedProvider } from '../auto-commit/headless-commands'
+import { heuristicTitle } from './heuristic-title'
 import { PromptCapture } from './prompt-capture'
+import { classifyPrompt } from './prompt-gate'
 import { generateTabTitle, type TitleSpawnFn } from './title-runner'
 
 export interface AutoRenameConfigSnapshot {
   enabled: boolean
   timeoutMs: number
   models: Partial<Record<string, string>>
+  settleMs?: number
+  maxAttempts?: number
+  minPromptWords?: number
 }
 
 export interface AutoRenameTab {
@@ -27,6 +32,35 @@ export interface AutoRenameCoordinatorOptions {
   spawn?: TitleSpawnFn
 }
 
+const DEFAULT_SETTLE_MS = 2_500
+const DEFAULT_MAX_ATTEMPTS = 3
+const DEFAULT_MIN_PROMPT_WORDS = 3
+/** Opening prompts folded into one title request. */
+const MAX_PENDING_PROMPTS = 3
+/** Headless CLIs running at once, so opening a burst of tabs does not fork one per tab. */
+const MAX_CONCURRENT_GENERATIONS = 2
+
+interface TabRenameState {
+  capture: PromptCapture
+  /** Title-worthy prompts collected for the next generation, oldest first. */
+  prompts: string[]
+  /** First title-worthy prompt seen, kept as the source for the local fallback. */
+  firstPrompt: string | null
+  attempts: number
+  settleTimer: ReturnType<typeof setTimeout> | null
+  controller: AbortController | null
+  /**
+   * True once a provider hook delivered a real prompt. Hook payloads are ground
+   * truth — dialog keystrokes never reach them — so keystroke reconstruction is
+   * ignored from then on.
+   */
+  hookDriven: boolean
+}
+
+function normalize(text: string): string {
+  return text.replaceAll(/\s+/gu, ' ').trim().toLowerCase()
+}
+
 export function initialAutoRenameStatus(
   config: AutoRenameConfigSnapshot,
   assistant: AssistantId,
@@ -35,63 +69,203 @@ export function initialAutoRenameStatus(
   return config.enabled && candidate && isSupportedProvider(assistant) ? 'eligible' : undefined
 }
 
+/**
+ * Owns the "name this tab after what it is doing" behaviour.
+ *
+ * Two properties drive the design:
+ *
+ * - A tab only leaves `eligible` on success, on an exhausted attempt budget, or
+ *   on a manual rename. Anything transient — an unreadable keystroke stream, a
+ *   failed CLI, a timeout — leaves the tab armed for the next prompt, so a tab
+ *   never gets stuck on its assistant label because of one bad submission.
+ * - Nothing is titled from a prompt that carries no intent, and a prompt that
+ *   does starts a settle window rather than an immediate request, so a rapid
+ *   multi-message opening produces one title from the whole opening.
+ */
 export class AutoRenameCoordinator {
-  private readonly captures = new Map<string, PromptCapture>()
-  private readonly controllers = new Map<string, AbortController>()
+  private readonly states = new Map<string, TabRenameState>()
+  private running = 0
+  private readonly waiting: (() => void)[] = []
 
   constructor(private readonly options: AutoRenameCoordinatorOptions) {}
 
   register(tab: AutoRenameTab): void {
-    if (tab.autoRenameStatus === 'eligible' && !this.captures.has(tab.id)) {
-      this.captures.set(tab.id, new PromptCapture())
+    if (tab.autoRenameStatus === 'eligible' && !this.states.has(tab.id)) {
+      this.states.set(tab.id, createState())
     }
   }
 
   unregister(tabId: string): void {
-    this.controllers.get(tabId)?.abort()
-    this.controllers.delete(tabId)
-    this.captures.delete(tabId)
+    const state = this.states.get(tabId)
+    if (!state) return
+    state.controller?.abort()
+    if (state.settleTimer) clearTimeout(state.settleTimer)
+    this.states.delete(tabId)
   }
 
   manualRename(tabId: string): void {
     this.unregister(tabId)
   }
 
+  /** Keystroke fallback: reconstruct submissions from the bytes written to the PTY. */
   observeWrite(tabId: string, input: string): void {
-    const tab = this.options.getTab(tabId)
-    if (!tab || tab.autoRenameStatus !== 'eligible') return
-    let capture = this.captures.get(tabId)
-    if (!capture) {
-      capture = new PromptCapture()
-      this.captures.set(tabId, capture)
-    }
-    const result = capture.feed(input)
+    const tab = this.eligibleTab(tabId)
+    if (!tab) return
+    const state = this.ensureState(tabId)
+    if (state.hookDriven) return
+
+    const result = state.capture.feed(input)
     if (result.type === 'pending') return
+    // A submission we could not reconstruct faithfully is dropped, not counted:
+    // history recall, Tab completion and unknown escapes must not cost the tab
+    // its only chance at a name.
+    if (result.prompt === null) return
+    this.acceptPrompt(tabId, state, result.prompt)
+  }
+
+  /**
+   * Ground truth from a provider hook (Claude's `UserPromptSubmit`): the exact
+   * prompt text, delivered only for real submissions.
+   */
+  observePrompt(tabId: string, prompt: string): void {
+    const tab = this.eligibleTab(tabId)
+    if (!tab) return
+    const state = this.ensureState(tabId)
+    if (!state.hookDriven) {
+      state.hookDriven = true
+      state.capture.reset()
+    }
+    this.acceptPrompt(tabId, state, prompt)
+  }
+
+  private eligibleTab(tabId: string): AutoRenameTab | undefined {
+    const tab = this.options.getTab(tabId)
+    return tab?.autoRenameStatus === 'eligible' ? tab : undefined
+  }
+
+  private ensureState(tabId: string): TabRenameState {
+    const existing = this.states.get(tabId)
+    if (existing) return existing
+    const created = createState()
+    this.states.set(tabId, created)
+    return created
+  }
+
+  private acceptPrompt(tabId: string, state: TabRenameState, prompt: string): void {
+    const minWords = this.options.config.minPromptWords ?? DEFAULT_MIN_PROMPT_WORDS
+    if (classifyPrompt(prompt, minWords) === 'skip') return
+
+    state.firstPrompt ??= prompt
+    appendPrompt(state, prompt)
+    // A generation already in flight covers this prompt's window; a settled
+    // title is never rewritten.
+    if (state.controller) return
+    this.scheduleGeneration(tabId, state)
+  }
+
+  private scheduleGeneration(tabId: string, state: TabRenameState): void {
+    if (state.settleTimer) clearTimeout(state.settleTimer)
+    const settleMs = this.options.config.settleMs ?? DEFAULT_SETTLE_MS
+    const timer = setTimeout(() => {
+      state.settleTimer = null
+      void this.generate(tabId, state)
+    }, settleMs)
+    // Never hold the process open for a pending title.
+    timer.unref?.()
+    state.settleTimer = timer
+  }
+
+  private async generate(tabId: string, state: TabRenameState): Promise<void> {
+    const tab = this.eligibleTab(tabId)
+    if (!tab || this.states.get(tabId) !== state || state.prompts.length === 0) return
 
-    this.captures.delete(tabId)
-    this.options.updateTab(tabId, { autoRenameStatus: 'attempted' })
-    const prompt = result.prompt
-    if (prompt === null) return
     const controller = new AbortController()
-    this.controllers.set(tabId, controller)
-    const originalTitle = tab.title
+    state.controller = controller
+    state.attempts++
 
-    void (async () => {
-      const title = await generateTabTitle({
-        firstPrompt: prompt,
+    const release = await this.acquireSlot()
+    let result: Awaited<ReturnType<typeof generateTabTitle>>
+    try {
+      // The tab may have been closed or renamed while queued behind another
+      // generation; drop out before spending a process on it.
+      if (this.states.get(tabId) !== state || controller.signal.aborted) return
+      result = await generateTabTitle({
+        firstPrompt: state.prompts.join('\n\n'),
         model: this.options.config.models[tab.assistant],
         provider: tab.assistant,
         signal: controller.signal,
         spawn: this.options.spawn,
         timeoutMs: this.options.config.timeoutMs,
       })
-      if (this.controllers.get(tabId) !== controller) return
-      this.controllers.delete(tabId)
-      if (title == null || title === '') return
-      const current = this.options.getTab(tabId)
-      if (!current || current.autoRenameStatus !== 'attempted' || current.title !== originalTitle)
-        return
-      this.options.updateTab(tabId, { autoRenameStatus: 'attempted', title })
-    })()
+    } finally {
+      release()
+    }
+
+    if (this.states.get(tabId) !== state) return
+    state.controller = null
+
+    if (result.status === 'ok') {
+      this.finish(tabId, result.title)
+      return
+    }
+
+    const maxAttempts = this.options.config.maxAttempts ?? DEFAULT_MAX_ATTEMPTS
+    // `unavailable` means no retry can ever succeed; otherwise keep the tab
+    // armed so the next prompt tries again with more context.
+    if (result.status === 'failed' && state.attempts < maxAttempts) return
+
+    this.finish(tabId, heuristicTitle(state.firstPrompt ?? state.prompts[0] ?? ''))
+  }
+
+  /** Apply the final outcome and stop watching the tab. */
+  private finish(tabId: string, title: string | null): void {
+    this.unregister(tabId)
+    this.options.updateTab(tabId, {
+      autoRenameStatus: 'attempted',
+      ...(title != null && title !== '' ? { title } : {}),
+    })
+  }
+
+  private async acquireSlot(): Promise<() => void> {
+    if (this.running >= MAX_CONCURRENT_GENERATIONS) {
+      await new Promise<void>((resolve) => this.waiting.push(resolve))
+    }
+    this.running++
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      this.running--
+      this.waiting.shift()?.()
+    }
   }
 }
+
+function createState(): TabRenameState {
+  return {
+    attempts: 0,
+    capture: new PromptCapture(),
+    controller: null,
+    firstPrompt: null,
+    hookDriven: false,
+    prompts: [],
+    settleTimer: null,
+  }
+}
+
+/**
+ * Add a prompt, keeping the pending set free of restatements of the same text.
+ * The keystroke and hook paths can both report one submission, and a user often
+ * rephrases; either way the title request should see the content once.
+ */
+function appendPrompt(state: TabRenameState, prompt: string): void {
+  const incoming = normalize(prompt)
+  if (incoming === '') return
+  // Already covered by a pending prompt (the same submission seen through both
+  // the keystroke and hook paths, or a restatement of it).
+  if (state.prompts.some((existing) => normalize(existing).includes(incoming))) return
+  // Supersede the shorter pending prompts this one subsumes.
+  state.prompts = state.prompts.filter((existing) => !incoming.includes(normalize(existing)))
+  if (state.prompts.length >= MAX_PENDING_PROMPTS) return
+  state.prompts.push(prompt)
+}

package/src/auto-rename/heuristic-title.ts

@@ -0,0 +1,57 @@
+// Last-resort title, derived locally from the prompt when every model
+// generation attempt failed (binary missing, non-zero exit, timeout,
+// unusable output). A rough title beats a tab that stays "Claude" forever.
+
+import { clampTitle } from './title-format'
+
+/** Openers that carry no intent; dropped so the title starts at the verb. */
+const LEADING_FILLERS = [
+  /^(?:hey|hi|hello|yo|salut|bonjour|coucou)\b[\s,]*/iu,
+  /^(?:please|pls|plz|stp|svp)\b[\s,]*/iu,
+  /^(?:s'il te (?:plait|plaît)|s'il vous (?:plait|plaît))\b[\s,]*/iu,
+  /^(?:can|could|would|will)\s+you\s+(?:please\s+)?/iu,
+  /^(?:i(?:'d| would)\s+like\s+you\s+to|i\s+want\s+you\s+to|i\s+need\s+you\s+to)\s+/iu,
+  /^(?:j'aimerais\s+que\s+tu|je\s+voudrais\s+que\s+tu|peux[- ]tu|pourrais[- ]tu|tu\s+peux)\s+/iu,
+  /^(?:let'?s|on\s+va)\s+/iu,
+  /^(?:ok|okay|alors|bon|donc|so|now)\b[\s,]*/iu,
+]
+
+/** Markdown noise that would otherwise land inside the title. */
+const LEADING_MARKUP = /^(?:[-*+>#]+|\d+[.)])\s*/u
+
+export function heuristicTitle(prompt: string): string | null {
+  // First prose line: fenced code is pasted context, never the request itself.
+  let inFence = false
+  let firstLine: string | undefined
+  for (const raw of prompt.split(/\r?\n/u)) {
+    const line = raw.trim()
+    if (line.startsWith('```')) {
+      inFence = !inFence
+      continue
+    }
+    if (inFence || line === '') continue
+    firstLine = line
+    break
+  }
+  if (firstLine == null) return null
+
+  let text = firstLine.replaceAll('`', '').replace(LEADING_MARKUP, '').trim()
+  // Fillers stack ("hey, could you please …"), so keep peeling until stable.
+  let stripped = true
+  while (stripped) {
+    stripped = false
+    for (const filler of LEADING_FILLERS) {
+      const next = text.replace(filler, '')
+      if (next !== text) {
+        text = next.trim()
+        stripped = true
+      }
+    }
+  }
+
+  // Only the opening clause describes the task; the rest is detail.
+  const clause = text.split(/(?<=[.!?;:])\s|\s+(?:and|then|puis|et)\s+/iu)[0] ?? text
+  const title = clampTitle(clause)
+  if (title == null) return null
+  return title.charAt(0).toLocaleUpperCase() + title.slice(1)
+}

package/src/auto-rename/prompt-capture.ts

@@ -121,6 +121,14 @@ export class PromptCapture {
     this.escapeBuffer += char
     const sequence = this.escapeBuffer
 
+    // Alt/Shift+Enter — a newline inside the prompt, not a submission and not a
+    // reason to distrust what we captured.
+    if (sequence.length === 2 && (char === '\r' || char === '\n')) {
+      this.escapeBuffer = ''
+      this.insert('\n')
+      return
+    }
+
     if (
       sequence.length === 2 &&
       sequence !== '\x1b[' &&
@@ -169,6 +177,17 @@ export class PromptCapture {
 
     const final = sequence.at(-1) ?? ''
     const parameters = sequence.slice(2, -1)
+    // Modified Enter under the kitty keyboard protocol (`CSI 13;2 u`) or
+    // xterm's modifyOtherKeys (`CSI 27;2;13 ~`): another way to type a newline
+    // inside the prompt.
+    const fields = parameters.split(';')
+    if (
+      (final === 'u' && fields[0] === '13') ||
+      (final === '~' && fields[0] === '27' && fields[2] === '13')
+    ) {
+      this.insert('\n')
+      return
+    }
     if ((final === 'C' || final === 'D') && parameters.includes(';')) {
       this.invalidateCurrentSubmission()
       return

package/src/auto-rename/prompt-gate.ts

@@ -0,0 +1,82 @@
+// Decides whether a submitted prompt says anything about what the tab is for.
+//
+// The first Enter in an assistant tab is very often not a task: a trust-folder
+// dialog, a theme picker, a slash-command menu, a permission answer, or a bare
+// "y". Titling from those is the "renamed too early / wrong intent" failure, so
+// they are skipped — and skipping is free: it never consumes a rename attempt.
+
+import { usesUnspacedScript } from './title-format'
+
+/** Answers that only advance a dialog; never a description of the work. */
+const CONFIRMATIONS: ReadonlySet<string> = new Set([
+  'a',
+  'accept',
+  'again',
+  'allow',
+  'annuler',
+  'cancel',
+  'continue',
+  'continue please',
+  'd',
+  'do it',
+  'encore',
+  'exit',
+  'go',
+  'go ahead',
+  'go on',
+  'k',
+  'merci',
+  'n',
+  'next',
+  'no',
+  'non',
+  'nope',
+  'ok',
+  'okay',
+  'oui',
+  'proceed',
+  'quit',
+  'retry',
+  'skip',
+  'stop',
+  'sure',
+  'thanks',
+  'thank you',
+  'undo',
+  'vas-y',
+  'y',
+  'yep',
+  'yes',
+  'yes please',
+])
+
+/** `/model`, `/init`, `/clear`… — a command, not a request. `/home/x/y.ts` is not one. */
+const SLASH_COMMAND = /^\/[a-z][\w:-]*(?:\s|$)/iu
+/** `!ls -la` runs a shell command in Claude Code. */
+const SHELL_ESCAPE = /^!/u
+/** `#` memorizes a note in Claude Code. */
+const MEMORY_NOTE = /^#/u
+
+export type PromptVerdict = 'title-worthy' | 'skip'
+
+export function classifyPrompt(prompt: string, minWords: number): PromptVerdict {
+  const trimmed = prompt.trim()
+  if (trimmed === '') return 'skip'
+  if (SLASH_COMMAND.test(trimmed) || SHELL_ESCAPE.test(trimmed) || MEMORY_NOTE.test(trimmed)) {
+    return 'skip'
+  }
+
+  const normalized = trimmed
+    .replaceAll(/\s+/gu, ' ')
+    .replace(/[.!?,;:…]+$/u, '')
+    .toLowerCase()
+  if (CONFIRMATIONS.has(normalized)) return 'skip'
+  // Menu selections: a lone digit, or "1" / "2." style picks.
+  if (/^\d{1,2}$/u.test(normalized)) return 'skip'
+
+  // Languages without spaces between words defeat the word count; fall back to
+  // a character floor so Japanese or Chinese prompts are not all skipped.
+  if (usesUnspacedScript(trimmed)) return trimmed.length >= 4 ? 'title-worthy' : 'skip'
+
+  return trimmed.split(/\s+/u).filter(Boolean).length >= minWords ? 'title-worthy' : 'skip'
+}

package/src/auto-rename/title-format.ts

@@ -0,0 +1,38 @@
+// Shared shaping rules for tab titles, whether they come from a model
+// (`title-runner`) or from the local fallback (`heuristic-title`). Both must
+// produce the same silhouette: 2 to 6 words, at most 48 characters, no
+// trailing punctuation.
+
+export const MAX_TITLE_WORDS = 6
+export const MAX_TITLE_LENGTH = 48
+
+/** Scripts that do not separate words with spaces, where a one-"word" title is legitimate. */
+export function usesUnspacedScript(text: string): boolean {
+  return /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Script=Thai}]/u.test(
+    text
+  )
+}
+
+/**
+ * Collapse whitespace, drop trailing punctuation, and clamp to the title
+ * budget. Returns null when nothing usable is left.
+ */
+export function clampTitle(raw: string): string | null {
+  const clean = raw
+    .replaceAll(/\s+/gu, ' ')
+    .replace(/[.!?,;:…]+$/u, '')
+    .trim()
+  const words = clean.split(' ').filter(Boolean)
+  const unspaced = usesUnspacedScript(clean)
+  if (words.length < 2 && !unspaced) return null
+
+  let title = words.slice(0, MAX_TITLE_WORDS).join(' ')
+  if (title.length > MAX_TITLE_LENGTH) {
+    title = title
+      .slice(0, MAX_TITLE_LENGTH)
+      .replace(/\s+\S*$/u, '')
+      .trim()
+  }
+  if (title === '') return null
+  return title.split(' ').filter(Boolean).length < 2 && !unspaced ? null : title
+}