@jhizzard/termdeck 1.8.1 → 1.10.0

package/packages/cli/src/init-mnestra.js

@@ -72,8 +72,9 @@ const HELP = [
   '  --skip-verify     Skip the final memory_status_aggregation() sanity call',
   '',
   'What this does:',
-  '  1. Prompts for Supabase URL, service_role key, direct Postgres connection',
-  '     string, OpenAI API key, and (optional) Anthropic API key — or reuses',
+  '  1. Prompts for Supabase URL, service_role key, Postgres connection',
+  '     string (Shared Pooler; IPv4-safe), OpenAI API key, and (optional)',
+  '     Anthropic API key — or reuses',
   '     saved values if a complete set already exists in secrets.env.',
   '  2. Writes ~/.termdeck/secrets.env IMMEDIATELY (merge-aware) so a later',
   '     pg connect or migration failure does not lose what you typed in.',
@@ -157,6 +158,11 @@ function inputsFromEnv() {
 
   const dbErr = urlHelper.looksLikePostgresUrl(required.DATABASE_URL);
   if (dbErr) throw new Error(`DATABASE_URL: ${dbErr}`);
+  // Sprint 75 T2 (part B): warn-only — a direct-endpoint URL passes
+  // validation (warn ≠ reject) but gets the IPv4 trap warning printed once.
+  for (const line of urlHelper.directEndpointWarningLines(urlHelper.classifyDbEndpoint(required.DATABASE_URL))) {
+    process.stdout.write(`  ${line}\n`);
+  }
 
   const srErr = urlHelper.looksLikeServiceRole(required.SUPABASE_SERVICE_ROLE_KEY);
   if (srErr) throw new Error(`SUPABASE_SERVICE_ROLE_KEY: ${srErr}`);
@@ -188,7 +194,7 @@ TermDeck Mnestra Setup
 
 This wizard configures TermDeck's Tier 2 memory layer (Mnestra) by:
   1. Asking for your Supabase URL and service_role key
-  2. Asking for a direct Postgres connection string
+  2. Asking for a Postgres connection string (Shared Pooler)
   3. Asking for an OpenAI API key (embeddings)
   4. Asking for an Anthropic API key (optional, summaries)
   5. Writing ~/.termdeck/secrets.env (before any database work, so a
@@ -253,6 +259,12 @@ async function collectInputs({ yes, reset }) {
       process.stdout.write(
         `Found saved secrets in ~/.termdeck/secrets.env (project ${ref}, db ${masked}).\n`
       );
+      // Sprint 75 T2 (part B): highest-value warn site — an operator whose
+      // EARLIER install stored a direct-endpoint URL (the Brad case) would
+      // otherwise sail through reuse with zero feedback. Warn-only.
+      for (const line of urlHelper.directEndpointWarningLines(urlHelper.classifyDbEndpoint(found.inputs.databaseUrl))) {
+        process.stdout.write(`  ${line}\n`);
+      }
       const reuse = yes ? true : await prompts.confirm('  Reuse saved secrets?', { defaultYes: true });
       if (reuse) {
         process.stdout.write('  Reusing saved secrets. Skipping prompts.\n\n');
@@ -284,11 +296,19 @@ async function collectInputs({ yes, reset }) {
   );
 
   process.stdout.write(
-    '? Direct Postgres connection string\n' +
-    `  (Supabase dashboard → Project Settings → Database → Connection String → Transaction pooler)\n` +
-    '  postgres://postgres.REF:PW@... '
+    '? Postgres connection string (Shared Pooler)\n' +
+    '  (Supabase dashboard → Connect (green button) → Transaction pooler →\n' +
+    '   toggle ON "Use IPv4 connection (Shared Pooler)" — the OFF default shows an\n' +
+    '   IPv6-only URL that hangs on IPv4-only hosts)\n' +
+    '  postgres://postgres.<project-ref>:PW@aws-<n>-<region>.pooler.supabase.com:6543/postgres '
   );
   const databaseUrl = await promptSecretWithValidation(urlHelper.looksLikePostgresUrl);
+  // Sprint 75 T2 (part B): warn-only endpoint-shape feedback. The validator
+  // above ACCEPTS direct URLs (IPv6-capable hosts use them legitimately);
+  // this prints the IPv4 trap warning without changing acceptance.
+  for (const line of urlHelper.directEndpointWarningLines(urlHelper.classifyDbEndpoint(databaseUrl))) {
+    process.stdout.write(`  ${line}\n`);
+  }
 
   process.stdout.write('? OpenAI API key (starts sk-proj- or sk-): ');
   const openaiKey = await promptSecretWithValidation(urlHelper.looksLikeOpenAiKey);
@@ -713,13 +733,34 @@ function refreshBundledHookIfNewer(opts = {}) {
 // actually run after upgrading the package.
 
 const SETTINGS_JSON_PATH = path.join(require('os').homedir(), '.claude', 'settings.json');
-const HOOK_COMMAND = 'node ~/.claude/hooks/memory-session-end.js';
+
+// Sprint 75 T2 — hook commands are written into ~/.claude/settings.json with
+// ABSOLUTE paths. The pre-1.10 literal `node ~/.claude/hooks/...` shape relied
+// on shell tilde expansion — it worked on macOS/Linux only by luck of how the
+// harness invokes hook commands, and is a hard break on Windows (audit item 4).
+// Computed at CALL time (not require time) from os.homedir() so a process that
+// re-points HOME (tests, sandboxed installs) gets the right path. The path is
+// double-quoted so a home dir containing spaces (`/Users/First Last/`) still
+// produces a command the harness shell can execute. Lockstep twin lives in
+// packages/stack-installer/src/index.js (`_hookCommandFor`) — INSTALLER-
+// PITFALLS Class N: change both or neither.
+function _hookCommandFor(filename) {
+  return `node "${path.join(require('os').homedir(), '.claude', 'hooks', filename)}"`;
+}
+
+// True when an entry's command still carries the legacy tilde shape and
+// should be rewritten to the absolute form.
+function _isTildeHookCommand(command) {
+  return typeof command === 'string' && command.includes('~/');
+}
+
+const HOOK_COMMAND = _hookCommandFor('memory-session-end.js');
 const HOOK_TIMEOUT_SECONDS = 30;
 
 // Sprint 64 T3 — PreCompact hook (Investigation 2 of CRITICAL-READ-FIRST-
 // 2026-05-07.md). Lives alongside the SessionEnd hook; refreshes via the
 // same Sprint 51.6 T3 version-stamp gate.
-const PRECOMPACT_HOOK_COMMAND = 'node ~/.claude/hooks/memory-pre-compact.js';
+const PRECOMPACT_HOOK_COMMAND = _hookCommandFor('memory-pre-compact.js');
 const PRECOMPACT_HOOK_TIMEOUT_SECONDS = 30;
 
 function _isSessionEndHookEntry(entry) {
@@ -734,7 +775,8 @@ function _isSessionEndHookEntry(entry) {
 // `packages/stack-installer/src/index.js:451` byte-for-byte (modulo
 // constants pulled from this file's scope).
 function _mergeSessionEndHookEntry(settings, opts = {}) {
-  const command = opts.command || HOOK_COMMAND;
+  // Command computed at call time (Sprint 75 T2) — see _hookCommandFor.
+  const command = opts.command || _hookCommandFor('memory-session-end.js');
   const timeout = opts.timeout != null ? opts.timeout : HOOK_TIMEOUT_SECONDS;
   const entry = { type: 'command', command, timeout };
 
@@ -759,10 +801,29 @@ function _mergeSessionEndHookEntry(settings, opts = {}) {
 
   if (!Array.isArray(settings.hooks.SessionEnd)) settings.hooks.SessionEnd = [];
 
+  // Sprint 75 T2 — rewrite a stale literal-`~` command (written by installers
+  // ≤ v1.9.x) to the absolute form. The "already wired?" predicate matches by
+  // hook FILENAME substring, so without this rewrite a legacy entry would be
+  // reported already-installed and keep its `~` forever. Idempotent: absolute
+  // commands (and user-custom commands without `~/`) are never touched.
+  let tildeMigrated = false;
+  for (const group of settings.hooks.SessionEnd) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    for (const e of group.hooks) {
+      if (_isSessionEndHookEntry(e) && _isTildeHookCommand(e.command)) {
+        e.command = command;
+        tildeMigrated = true;
+      }
+    }
+  }
+
   for (const group of settings.hooks.SessionEnd) {
     if (!group || !Array.isArray(group.hooks)) continue;
     if (group.hooks.some(_isSessionEndHookEntry)) {
-      return { settings, status: migrated ? 'migrated-from-stop' : 'already-installed' };
+      const status = tildeMigrated ? 'migrated-tilde-path'
+        : migrated ? 'migrated-from-stop'
+        : 'already-installed';
+      return { settings, status };
     }
   }
 
@@ -788,17 +849,30 @@ function _isPreCompactHookEntry(entry) {
 }
 
 function _mergePreCompactHookEntry(settings, opts = {}) {
-  const command = opts.command || PRECOMPACT_HOOK_COMMAND;
+  // Command computed at call time (Sprint 75 T2) — see _hookCommandFor.
+  const command = opts.command || _hookCommandFor('memory-pre-compact.js');
   const timeout = opts.timeout != null ? opts.timeout : PRECOMPACT_HOOK_TIMEOUT_SECONDS;
   const entry = { type: 'command', command, timeout };
 
   if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
   if (!Array.isArray(settings.hooks.PreCompact)) settings.hooks.PreCompact = [];
 
+  // Sprint 75 T2 — same stale literal-`~` rewrite as the SessionEnd merge.
+  let tildeMigrated = false;
+  for (const group of settings.hooks.PreCompact) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    for (const e of group.hooks) {
+      if (_isPreCompactHookEntry(e) && _isTildeHookCommand(e.command)) {
+        e.command = command;
+        tildeMigrated = true;
+      }
+    }
+  }
+
   for (const group of settings.hooks.PreCompact) {
     if (!group || !Array.isArray(group.hooks)) continue;
     if (group.hooks.some(_isPreCompactHookEntry)) {
-      return { settings, status: 'already-installed' };
+      return { settings, status: tildeMigrated ? 'migrated-tilde-path' : 'already-installed' };
     }
   }
 
@@ -934,10 +1008,14 @@ function runSettingsJsonMigration({ dryRun = false } = {}) {
       ok(r.backup ? `installed (SessionEnd; backup: ${path.basename(r.backup)})` : 'installed (SessionEnd)');
     } else if (r.status === 'migrated-from-stop') {
       ok(r.backup ? `migrated Stop → SessionEnd (was firing on every turn; backup: ${path.basename(r.backup)})` : 'migrated Stop → SessionEnd (was firing on every turn)');
+    } else if (r.status === 'migrated-tilde-path') {
+      ok(r.backup ? `rewrote legacy ~ command to absolute path (backup: ${path.basename(r.backup)})` : 'rewrote legacy ~ command to absolute path');
     } else if (r.status === 'would-installed') {
       ok('would install (SessionEnd) (dry-run)');
     } else if (r.status === 'would-migrated-from-stop') {
       ok('would migrate Stop → SessionEnd (dry-run)');
+    } else if (r.status === 'would-migrated-tilde-path') {
+      ok('would rewrite legacy ~ command to absolute path (dry-run)');
     } else if (r.status === 'malformed') {
       ok(`(skipped: settings.json malformed: ${r.error})`);
     } else {
@@ -964,8 +1042,12 @@ function runSettingsJsonMigration({ dryRun = false } = {}) {
       ok('already wired (PreCompact)');
     } else if (r.status === 'installed') {
       ok(r.backup ? `installed (PreCompact; backup: ${path.basename(r.backup)})` : 'installed (PreCompact)');
+    } else if (r.status === 'migrated-tilde-path') {
+      ok(r.backup ? `rewrote legacy ~ command to absolute path (backup: ${path.basename(r.backup)})` : 'rewrote legacy ~ command to absolute path');
     } else if (r.status === 'would-installed') {
       ok('would install (PreCompact) (dry-run)');
+    } else if (r.status === 'would-migrated-tilde-path') {
+      ok('would rewrite legacy ~ command to absolute path (dry-run)');
     } else if (r.status === 'malformed') {
       ok(`(skipped: settings.json malformed: ${r.error})`);
     } else {
@@ -1162,7 +1244,10 @@ async function main(argv) {
   } catch (err) {
     fail(err.message);
     process.stderr.write(
-      '\nDouble-check the connection string from Supabase → Project Settings → Database → Connection String.\n'
+      '\nDouble-check the connection string: Supabase dashboard → Connect → Transaction pooler →\n' +
+      'toggle ON "Use IPv4 connection (Shared Pooler)". If the connect HUNG (timeout rather than\n' +
+      'auth error), the URL is probably the IPv6-only db.<project-ref> endpoint and this host has\n' +
+      'no IPv6 route — use the Shared Pooler URL.\n'
     );
     printResumeHint();
     return 3;
@@ -1233,3 +1318,9 @@ module.exports._isSessionEndHookEntry = _isSessionEndHookEntry;
 module.exports.SETTINGS_JSON_PATH = SETTINGS_JSON_PATH;
 module.exports.HOOK_COMMAND = HOOK_COMMAND;
 module.exports.HOOK_TIMEOUT_SECONDS = HOOK_TIMEOUT_SECONDS;
+// Sprint 75 T2 — absolute-path hook-command builders (lockstep twin in
+// packages/stack-installer/src/index.js; exported for tests).
+module.exports._hookCommandFor = _hookCommandFor;
+module.exports._isTildeHookCommand = _isTildeHookCommand;
+module.exports._mergePreCompactHookEntry = _mergePreCompactHookEntry;
+module.exports.migrateSettingsJsonPreCompactEntry = migrateSettingsJsonPreCompactEntry;

package/packages/cli/src/init-rumen.js

@@ -212,6 +212,13 @@ function preflight() {
     ok();
   }
 
+  // Sprint 75 T2 (part B): warn-only endpoint-shape feedback — the same
+  // stored URL feeds the Edge Function secrets, so a direct-endpoint URL
+  // (IPv6-only) carried over from an earlier install gets flagged here too.
+  for (const line of urlHelper.directEndpointWarningLines(urlHelper.classifyDbEndpoint(secrets.DATABASE_URL))) {
+    process.stdout.write(`  ${line}\n`);
+  }
+
   // OPENAI_API_KEY is optional: when present, Rumen's Relate phase generates
   // real embeddings for semantic+keyword hybrid search. When absent, Rumen
   // falls back to keyword-only matching (still works, but loses cross-project

package/packages/cli/src/init.js

@@ -102,6 +102,7 @@ const HELP = [
   'Sub-mode wizards (callable independently for advanced users):',
   '  termdeck init --mnestra   Configure Tier 2 memory (Supabase + Mnestra)',
   '  termdeck init --rumen     Deploy Tier 3 async learning (Rumen)',
+  '  termdeck init --bridge    Scaffold the Tier 5 Web-Chat Bridge (named tunnel + supervisor)',
   '  termdeck init --project   Scaffold a new project with CLAUDE.md + orchestration docs',
   '',
   'Get a Personal Access Token at: https://supabase.com/dashboard/account/tokens',

package/packages/client/public/app.js

@@ -361,6 +361,80 @@
       }, { capture: true });
     }
 
+    // ===== termdeck#12 input guard (Sprint 73 T3) =====
+    // Runaway-typed-input defense at the single chokepoint every byte of
+    // human browser input flows through (the onData handler registered in
+    // createTerminalPanel). xterm@5.5.0 reconstructs composition input from
+    // its hidden textarea and can re-emit the accumulated buffer-so-far once
+    // per word boundary on IME/mobile/remote keyboards — the #12 cumulative-
+    // prefix runaway (~110 typed chars became a 3,042-char PTY stream).
+    // Detection logic lives in input-guard.js (UMD, unit-tested from node);
+    // these helpers wire it to panel state and the operator surface.
+    // Suppression is loud (console.error + panel toast), never silent;
+    // oversize chunks can be sent anyway from the toast.
+    function shouldSuppressPanelInput(entry, id, data) {
+      if (!entry._inputGuard) entry._inputGuard = InputGuard.createGuard();
+      const result = InputGuard.check(entry._inputGuard, data, Date.now());
+      if (result.verdict === 'pass') return false;
+      console.error(
+        `[input-guard] suppressed ${result.reason} input on panel ${id} ` +
+        `(chunk ${data.length} chars, chain ${result.chainLength}, ` +
+        `total suppressed ${result.suppressedCount} chunks / ${result.suppressedChars} chars):`,
+        JSON.stringify(data.slice(0, 120))
+      );
+      showInputGuardToast(entry, id, result, data);
+      return true;
+    }
+
+    function showInputGuardToast(entry, id, result, data) {
+      if (!entry || !entry.el) return;
+
+      // One toast per panel: repeated suppressions update the counter line
+      // (a runaway fires per word boundary — stacking toasts would bury the
+      // panel) and refresh the held chunk + auto-dismiss timer.
+      const existing = entry.el.querySelector('.input-guard-toast');
+      if (existing) {
+        const counter = existing.querySelector('.t-meta');
+        if (counter) counter.textContent = `${result.suppressedCount} chunks (${result.suppressedChars} chars) suppressed so far.`;
+        if (result.reason === 'oversize') existing._heldChunk = data;
+        clearTimeout(existing._autoTimer);
+        existing._autoTimer = setTimeout(() => existing.remove(), 60000);
+        return;
+      }
+
+      const toast = document.createElement('div');
+      toast.className = 'input-guard-toast';
+      const why = result.reason === 'oversize'
+        ? 'a single typed chunk was implausibly large'
+        : 'the keyboard started re-sending the whole buffer-so-far per keystroke (xterm composition runaway — termdeck#12)';
+      toast.innerHTML = `
+        <button class="t-dismiss" aria-label="Dismiss">×</button>
+        <div class="t-title">Input guard — runaway typing suppressed</div>
+        <div class="t-body">Blocked because ${why}. Check the terminal's input line before pressing Enter; clear it if it shows repeated text.${result.reason === 'oversize' ? ' If this was intentional, send it below.' : ''}</div>
+        <div class="t-meta">${result.suppressedCount} chunks (${result.suppressedChars} chars) suppressed so far.</div>
+        ${result.reason === 'oversize' ? '<button class="t-send-anyway">Send anyway</button>' : ''}
+      `;
+      if (result.reason === 'oversize') toast._heldChunk = data;
+      entry.el.appendChild(toast);
+
+      toast.querySelector('.t-dismiss').addEventListener('click', () => {
+        clearTimeout(toast._autoTimer);
+        toast.remove();
+      });
+      const sendBtn = toast.querySelector('.t-send-anyway');
+      if (sendBtn) {
+        sendBtn.addEventListener('click', () => {
+          const live = state.sessions.get(id);
+          if (toast._heldChunk && live && live.ws && live.ws.readyState === WebSocket.OPEN) {
+            live.ws.send(JSON.stringify({ type: 'input', data: toast._heldChunk }));
+          }
+          clearTimeout(toast._autoTimer);
+          toast.remove();
+        });
+      }
+      toast._autoTimer = setTimeout(() => toast.remove(), 60000);
+    }
+
     // ===== Create Terminal Panel =====
     function createTerminalPanel(sessionData) {
       const id = sessionData.id;
@@ -592,10 +666,20 @@
         }
       };
 
-      // Terminal input → WebSocket
+      // Terminal input → WebSocket. Registered ONCE per Terminal instance and
+      // never re-registered: xterm's onData ADDS listeners, and the
+      // pre-Sprint-73 reconnect path stacked one leaked handler (closed over
+      // its dead socket) per reconnect — the termdeck#12 cause-B family. The
+      // handler dereferences entry.ws at event time, so reconnectSession just
+      // swaps entry.ws and this same registration follows it.
+      // shouldSuppressPanelInput is the #12 runaway chokepoint — every byte
+      // of human browser input to this PTY flows through this closure.
       terminal.onData((data) => {
-        if (ws.readyState === WebSocket.OPEN) {
-          ws.send(JSON.stringify({ type: 'input', data }));
+        const entry = state.sessions.get(id);
+        if (!entry || entry._mounting || !entry.ws) return;
+        if (shouldSuppressPanelInput(entry, id, data)) return;
+        if (entry.ws.readyState === WebSocket.OPEN) {
+          entry.ws.send(JSON.stringify({ type: 'input', data }));
         }
       });
 
@@ -608,6 +692,49 @@
         panel.classList.remove('active-input');
       });
 
+      // termdeck#12 (Sprint 73 T3) — two defenses on xterm's hidden textarea:
+      //
+      // (a) Paste tracking for the input guard: a DOM `paste` event stamps
+      //     the guard so the following chunk is exempt — pastes are
+      //     deliberate bulk input, and without the stamp a large
+      //     un-bracketed paste would false-trip the oversize detector.
+      //
+      // (b) Idle-clear of the textarea. xterm@5.5.0 clears its helper
+      //     textarea only on non-composition Enter/Ctrl+C keydowns
+      //     (Terminal.ts:1066-1068); on composition keyboards (every keydown
+      //     = keyCode 229: mobile/IME/dictation/remote bridges) that clear
+      //     never fires, the textarea accumulates the whole message, and
+      //     CompositionHelper's replace/substring reconstruction can re-emit
+      //     the accumulated buffer once per word boundary — the #12
+      //     cumulative-prefix runaway. Clearing after a short typing lull
+      //     (never mid-composition; composition state tracked via the public
+      //     compositionstart/end events) bounds what those paths can
+      //     reconstruct to a single typing burst. xterm's own deferred
+      //     textarea reads are setTimeout(0) — far inside the 250ms debounce
+      //     — so the clear cannot race them.
+      const guardTa = terminal.textarea;
+      if (guardTa) {
+        let composing = false;
+        let idleClearTimer = null;
+        const armIdleClear = () => {
+          if (idleClearTimer) clearTimeout(idleClearTimer);
+          idleClearTimer = setTimeout(() => {
+            idleClearTimer = null;
+            if (!composing && guardTa.value) guardTa.value = '';
+          }, 250);
+        };
+        guardTa.addEventListener('compositionstart', () => { composing = true; });
+        guardTa.addEventListener('compositionend', () => { composing = false; armIdleClear(); });
+        guardTa.addEventListener('keydown', armIdleClear);
+        guardTa.addEventListener('input', armIdleClear);
+        guardTa.addEventListener('paste', () => {
+          const entry = state.sessions.get(id);
+          if (!entry) return;
+          if (!entry._inputGuard) entry._inputGuard = InputGuard.createGuard();
+          InputGuard.notePaste(entry._inputGuard, Date.now());
+        });
+      }
+
       // Store reference
       state.sessions.set(id, {
         session: sessionData,
@@ -2443,12 +2570,11 @@
         }
       };
 
-      // Re-wire terminal input
-      entry.terminal.onData((data) => {
-        if (ws.readyState === WebSocket.OPEN) {
-          ws.send(JSON.stringify({ type: 'input', data }));
-        }
-      });
+      // No input re-wiring (Sprint 73 T3, termdeck#12): the single onData
+      // handler registered at panel creation dereferences entry.ws at event
+      // time, so the `entry.ws = ws` assignment in onopen above is all a
+      // reconnect needs. Pre-Sprint-73 this function re-ran terminal.onData()
+      // here, leaking one handler (closed over its dead socket) per reconnect.
     }
 
     function halfPanel(id) {

package/packages/client/public/index.html

@@ -393,6 +393,7 @@
   <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/lib/addon-fit.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-web-links@0.11.0/lib/addon-web-links.min.js"></script>
   <script src="launcher-resolver.js" defer></script>
+  <script src="input-guard.js" defer></script>
   <script src="app.js" defer></script>
 </body>
 </html>

package/packages/client/public/input-guard.js

@@ -0,0 +1,192 @@
+// TermDeck input guard — extracted Sprint 73 T3 (termdeck#12, second half)
+//
+// Pure state-machine: given a stream of xterm `onData` chunks for one panel,
+// decide per chunk whether it is plausible human/protocol input (`pass`) or a
+// runaway re-emission of the input buffer (`suppress`). Lives in its own file
+// so the same code runs in the browser (via <script src="input-guard.js">)
+// AND under `node --test` (via `require('.../input-guard')`) — the
+// launcher-resolver.js pattern.
+//
+// Why this exists (termdeck#12, the "input box accumulates buffer-so-far per
+// keystroke" half): on composition-style keyboards — Android/iOS soft
+// keyboards, IMEs, dictation, remote-access keyboard bridges — every keydown
+// reaches xterm as keyCode 229 and xterm@5.5.0 reconstructs the typed data
+// from its hidden helper <textarea>:
+//
+//   1. The textarea is cleared ONLY on a non-composition Enter/Ctrl+C keydown
+//      (xterm src/browser/Terminal.ts:1066-1068). Composition keydowns return
+//      early, so mid-message the textarea accumulates the entire buffer-so-far.
+//   2. CompositionHelper._handleAnyTextareaChanges computes the keystroke as
+//      `newValue.replace(oldValue, '')` (CompositionHelper.ts:191). When the
+//      keyboard REWRITES text (autocorrect / auto-space / predictive commit —
+//      routine at word boundaries) `oldValue` is no longer a substring, the
+//      replace matches nothing, and the ENTIRE accumulated buffer is emitted
+//      as one data event.
+//   3. CompositionHelper._finalizeComposition emits
+//      `textarea.value.substring(start[, end])` spans with offsets captured at
+//      composition boundaries (CompositionHelper.ts:134,163,168) — stale
+//      offsets re-emit accumulated tails per word commit.
+//
+// Net effect observed in #12: a ~110-char message became a 3,042-char PTY
+// stream of cumulative prefixes ("i think" / "i think there" / "i think there
+// is" …). Each individual chunk was small (~5-110 chars) — so a single-chunk
+// size cap can NOT catch the primary shape. Detection keys on the structure:
+// consecutive multi-char chunks where each strictly extends the previous one
+// as a prefix. Legit input never looks like that: typed keys arrive as 1-char
+// deltas, IME commits arrive as sibling words (not superstrings), pastes
+// arrive as one chunk (and are exempted via the DOM `paste` event and/or
+// bracketed-paste markers), and terminal protocol replies are ESC-prefixed.
+//
+// xterm itself is loaded from CDN, version-pinned (index.html) and not
+// patchable in a zero-build client — but every byte of human browser input
+// reaches the PTY through exactly one chokepoint TermDeck owns: the
+// `terminal.onData` handler in app.js. This module is that chokepoint's
+// brain. See tests/input-guard contract: packages/server/tests/input-guard.test.js.
+
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.InputGuard = factory();
+  }
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  const DEFAULTS = {
+    // A single non-paste, non-protocol chunk this large is not human typing.
+    // Largest legit non-paste chunks are IME phrase commits (CJK conversion,
+    // dictation segments) — realistically well under this. Suppressed chunks
+    // are held for an explicit "send anyway" so a false positive costs one
+    // click, while a true positive saves the session.
+    oversizeChunkChars: 512,
+
+    // Chunks shorter than this never participate in chain detection: 1-2
+    // chars is normal typing, 3 covers short escape sequences. Chain
+    // candidates start at 4 chars.
+    chainMinChunkChars: 4,
+
+    // Consecutive strictly-growing prefix-chained chunks before tripping.
+    // 3 means: chunk B extending chunk A passes (a single predictive-commit
+    // rewrite can legitimately look like that once), but a third consecutive
+    // extension is the #12 runaway. Brad's payload chains 20+ deep.
+    prefixChainTripCount: 3,
+
+    // Consecutive IDENTICAL multi-char chunks before tripping. Belt-and-
+    // suspenders for the stacked-handler / stuck-repeat shape. High threshold
+    // because short identical runs are legit ("ha ha ha ha" via IME commits).
+    repeatChainTripCount: 8,
+
+    // Chain links must arrive within this window of each other. Runaway
+    // emissions arrive at typing cadence; a long pause breaks the chain.
+    chainWindowMs: 5000,
+
+    // Grace period after a DOM `paste` event during which any chunk passes.
+    // Pastes are deliberate; they also reset chain state.
+    pasteGraceMs: 1500,
+  };
+
+  function createGuard(opts) {
+    return {
+      cfg: Object.assign({}, DEFAULTS, opts || {}),
+      lastPasteAt: 0,
+      prevChunk: '',
+      prevChunkAt: 0,
+      prefixChainLen: 0,
+      repeatChainLen: 0,
+      suppressedCount: 0,
+      suppressedChars: 0,
+    };
+  }
+
+  // Record a DOM `paste` event on the panel's textarea (timestamp from the
+  // caller so the module stays clock-free and testable).
+  function notePaste(guard, now) {
+    guard.lastPasteAt = now;
+  }
+
+  function resetChains(guard) {
+    guard.prevChunk = '';
+    guard.prevChunkAt = 0;
+    guard.prefixChainLen = 0;
+    guard.repeatChainLen = 0;
+  }
+
+  // Classify one onData chunk. Returns { verdict: 'pass' } or
+  // { verdict: 'suppress', reason: 'prefix-chain'|'repeat-chain'|'oversize',
+  //   chainLength, suppressedCount, suppressedChars }.
+  function check(guard, data, now) {
+    const cfg = guard.cfg;
+
+    // Bracketed paste (xterm wraps pastes in \x1b[200~ … \x1b[201~ when the
+    // app enabled DECSET 2004): deliberate bulk input — pass and reset
+    // chains. Checked before the generic ESC pass-through so the reset fires.
+    if (data.startsWith('\x1b[200~')) {
+      resetChains(guard);
+      return { verdict: 'pass' };
+    }
+
+    // Terminal protocol traffic (cursor/function keys, mouse tracking
+    // reports, DA/DSR query replies) is ESC-prefixed and must NEVER be
+    // suppressed or held — dropping a query reply can hang a TUI. The #12
+    // runaway is plain text reconstructed from the textarea, which cannot
+    // contain ESC. Protocol chunks don't touch chain state either (mouse
+    // wheel bursts emit many near-identical chunks legitimately).
+    if (data.charCodeAt(0) === 0x1b) {
+      return { verdict: 'pass' };
+    }
+
+    // DOM-paste grace: a `paste` event just fired on this panel's textarea
+    // (un-bracketed paste path). Deliberate bulk input — pass and reset
+    // chains. lastPasteAt === 0 means "never pasted", not "pasted at epoch".
+    if (guard.lastPasteAt > 0 && (now - guard.lastPasteAt) <= cfg.pasteGraceMs) {
+      resetChains(guard);
+      return { verdict: 'pass' };
+    }
+
+    // Small chunks are normal typing / control chars: always pass, and leave
+    // chain state alone (runaway prefix emissions can interleave with real
+    // keystroke deltas; a 1-char delta must not amnesty the chain).
+    if (data.length < cfg.chainMinChunkChars) {
+      return { verdict: 'pass' };
+    }
+
+    // Multi-char plain-text chunk: update chain state.
+    const withinWindow = guard.prevChunk && (now - guard.prevChunkAt) <= cfg.chainWindowMs;
+    if (withinWindow && data.length > guard.prevChunk.length && data.startsWith(guard.prevChunk)) {
+      guard.prefixChainLen += 1;
+      guard.repeatChainLen = 1;
+    } else if (withinWindow && data === guard.prevChunk) {
+      guard.repeatChainLen += 1;
+      // An identical re-emission keeps a prefix chain alive but doesn't grow it.
+    } else {
+      guard.prefixChainLen = 1;
+      guard.repeatChainLen = 1;
+    }
+    guard.prevChunk = data;
+    guard.prevChunkAt = now;
+
+    let reason = null;
+    if (guard.prefixChainLen >= cfg.prefixChainTripCount) {
+      reason = 'prefix-chain';
+    } else if (guard.repeatChainLen >= cfg.repeatChainTripCount) {
+      reason = 'repeat-chain';
+    } else if (data.length >= cfg.oversizeChunkChars) {
+      reason = 'oversize';
+    }
+
+    if (reason) {
+      guard.suppressedCount += 1;
+      guard.suppressedChars += data.length;
+      return {
+        verdict: 'suppress',
+        reason,
+        chainLength: reason === 'repeat-chain' ? guard.repeatChainLen : guard.prefixChainLen,
+        suppressedCount: guard.suppressedCount,
+        suppressedChars: guard.suppressedChars,
+      };
+    }
+
+    return { verdict: 'pass' };
+  }
+
+  return { DEFAULTS, createGuard, notePaste, check };
+});