@0xmaxma/claude-gateway 1.3.25 → 1.3.31

package/dist/shell/control-channel.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Control channel (Epic #195, Phase 3b — item B2).
+ *
+ * The gateway's recovery executor can ask the PTY wrapper to press a specific
+ * key into the interactive TUI — the raw keystrokes the wrapper otherwise only
+ * generates internally (a single Enter, a menu digit, an arrow). These reach the
+ * wrapper as a NEW stdin message type `{"type":"control","key":...}`, kept
+ * distinct from a `type:"user"` message turn so control keystrokes are never
+ * confused with prompt text.
+ *
+ * The vocabulary is CLOSED and validated here, for the same reason the triage
+ * schema is closed: the only keystrokes the wrapper will ever emit on behalf of
+ * the gateway are the ones in `CONTROL_KEYS`. A malformed or unknown control
+ * message is rejected, so no arbitrary byte sequence can be injected into the
+ * PTY via this path. This module is pure (parse + map to keystrokes); the
+ * wrapper performs the actual `host.writeRaw` and the screen-gated Enter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PTY_INPUT_BYTES = exports.MAX_CONTROL_OPTION = exports.KEY_DOWN = exports.KEY_UP = exports.KEY_ENTER = exports.KEY_ESC = exports.CONTROL_KEYS = void 0;
+exports.parseControlCommand = parseControlCommand;
+exports.keystrokesFor = keystrokesFor;
+exports.isAcceptablePtyInput = isAcceptablePtyInput;
+exports.shouldRoutePtyInput = shouldRoutePtyInput;
+/** Closed set of control keys the gateway may request. */
+exports.CONTROL_KEYS = ['esc', 'esc-esc', 'enter', 'up', 'down', 'select-option'];
+// VT100 keystroke sequences — identical to the ones the wrapper already emits
+// internally (menu-probe arrows, handleMenuReply digit/Enter), so a control key
+// is indistinguishable from a user pressing it.
+exports.KEY_ESC = '\x1b';
+exports.KEY_ENTER = '\r';
+exports.KEY_UP = '\x1b[A';
+exports.KEY_DOWN = '\x1b[B';
+/**
+ * Upper bound for a select-option index. Capped at 9 to match the triage schema:
+ * the wrapper selects by typing the digit, which is only unambiguous single-char,
+ * so a two-digit index could type a wrong immediate selection. Menus are short.
+ */
+exports.MAX_CONTROL_OPTION = 9;
+const KEY_SET = new Set(exports.CONTROL_KEYS);
+/**
+ * Parse and validate a raw stdin control object into a closed ControlCommand,
+ * or null if it cannot be trusted. Never throws. `select-option` requires a
+ * bounded positive-integer `option`; anything else is rejected.
+ */
+function parseControlCommand(obj) {
+    const key = obj['key'];
+    if (typeof key !== 'string' || !KEY_SET.has(key))
+        return null;
+    if (key === 'select-option') {
+        const opt = obj['option'];
+        if (typeof opt !== 'number' ||
+            !Number.isInteger(opt) ||
+            opt < 1 ||
+            opt > exports.MAX_CONTROL_OPTION) {
+            return null;
+        }
+        return { key: 'select-option', option: opt };
+    }
+    return { key: key };
+}
+/**
+ * The raw keystroke sequence(s) a control command maps to. For select-option
+ * this is just the digit — the wrapper sends Enter separately, gated on the
+ * menu still being on screen (a TUI may confirm on the digit alone), mirroring
+ * the existing menu-selection flow.
+ */
+function keystrokesFor(cmd) {
+    switch (cmd.key) {
+        case 'esc':
+            return [exports.KEY_ESC];
+        case 'esc-esc':
+            return [exports.KEY_ESC, exports.KEY_ESC];
+        case 'enter':
+            return [exports.KEY_ENTER];
+        case 'up':
+            return [exports.KEY_UP];
+        case 'down':
+            return [exports.KEY_DOWN];
+        case 'select-option':
+            return [String(cmd.option)];
+    }
+}
+/**
+ * Interactive terminal input (Issue #201). Unlike the closed control vocabulary,
+ * input-mode carries arbitrary raw keystroke bytes so a viewer can type any key.
+ * Access is gated at the gateway (auth + the localhost-default `gateway.bind`);
+ * these pure helpers bound and validate a single frame, and are reused on both
+ * sides of the pipe (the gateway WS handler and the PTY wrapper) so the two never
+ * drift on what counts as an acceptable frame.
+ */
+exports.MAX_PTY_INPUT_BYTES = 8192;
+/**
+ * True when `data` is a non-empty string within the per-frame byte bound. The
+ * bound is measured in real UTF-8 bytes (not UTF-16 code units), so multi-byte
+ * input (emoji, non-Latin scripts) is capped at the same byte budget that will
+ * actually be written to the PTY.
+ */
+function isAcceptablePtyInput(data, maxBytes = exports.MAX_PTY_INPUT_BYTES) {
+    return (typeof data === 'string' &&
+        data.length > 0 &&
+        Buffer.byteLength(data, 'utf8') <= maxBytes);
+}
+/**
+ * Whether one inbound WebSocket frame should be routed into the live PTY.
+ * Requires a text (non-binary) frame and an acceptable payload; binary frames
+ * and oversized/empty payloads are dropped. Pure — no IO. (Whether a browser
+ * sends input at all is a client-side choice via the viewer's mode toggle;
+ * access to the socket is gated upstream by auth + `gateway.bind`.)
+ */
+function shouldRoutePtyInput(isBinary, data, maxBytes = exports.MAX_PTY_INPUT_BYTES) {
+    return !isBinary && isAcceptablePtyInput(data, maxBytes);
+}
+//# sourceMappingURL=control-channel.js.map

package/dist/shell/control-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-channel.js","sourceRoot":"","sources":["../../src/shell/control-channel.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAmCH,kDAgBC;AAQD,sCAeC;AAkBD,oDASC;AASD,kDAMC;AAlHD,0DAA0D;AAC7C,QAAA,YAAY,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,CAAU,CAAA;AAU/F,8EAA8E;AAC9E,gFAAgF;AAChF,gDAAgD;AACnC,QAAA,OAAO,GAAG,MAAM,CAAA;AAChB,QAAA,SAAS,GAAG,IAAI,CAAA;AAChB,QAAA,MAAM,GAAG,QAAQ,CAAA;AACjB,QAAA,QAAQ,GAAG,QAAQ,CAAA;AAEhC;;;;GAIG;AACU,QAAA,kBAAkB,GAAG,CAAC,CAAA;AAEnC,MAAM,OAAO,GAAwB,IAAI,GAAG,CAAC,oBAAY,CAAC,CAAA;AAE1D;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,GAA4B;IAC9D,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAA;IACtB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAC7D,IAAI,GAAG,KAAK,eAAe,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAA;QACzB,IACE,OAAO,GAAG,KAAK,QAAQ;YACvB,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC;YACtB,GAAG,GAAG,CAAC;YACP,GAAG,GAAG,0BAAkB,EACxB,CAAC;YACD,OAAO,IAAI,CAAA;QACb,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,EAAE,CAAA;IAC9C,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,GAAiB,EAAE,CAAA;AACnC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,GAAmB;IAC/C,QAAQ,GAAG,CAAC,GAAG,EAAE,CAAC;QAChB,KAAK,KAAK;YACR,OAAO,CAAC,eAAO,CAAC,CAAA;QAClB,KAAK,SAAS;YACZ,OAAO,CAAC,eAAO,EAAE,eAAO,CAAC,CAAA;QAC3B,KAAK,OAAO;YACV,OAAO,CAAC,iBAAS,CAAC,CAAA;QACpB,KAAK,IAAI;YACP,OAAO,CAAC,cAAM,CAAC,CAAA;QACjB,KAAK,MAAM;YACT,OAAO,CAAC,gBAAQ,CAAC,CAAA;QACnB,KAAK,eAAe;YAClB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;IAC/B,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACU,QAAA,mBAAmB,GAAG,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,SAAgB,oBAAoB,CAClC,IAAa,EACb,WAAmB,2BAAmB;IAEtC,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,CAAC,MAAM,GAAG,CAAC;QACf,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,QAAQ,CAC5C,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,mBAAmB,CACjC,QAAiB,EACjB,IAAa,EACb,WAAmB,2BAAmB;IAEtC,OAAO,CAAC,QAAQ,IAAI,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;AAC1D,CAAC"}

package/dist/types.d.ts

@@ -136,6 +136,14 @@ export interface GatewayConfig {
     gateway: {
         logDir: string;
         timezone: string;
+        /**
+         * Network interface the HTTP/WebSocket server binds to. Defaults to
+         * "127.0.0.1" (localhost-only) so the dashboard and API are not exposed to
+         * the local network out of the box. Set to "0.0.0.0" to expose all
+         * interfaces (e.g. behind a trusted reverse proxy). The `GATEWAY_BIND` env
+         * var, when set, takes precedence over this field.
+         */
+        bind?: string;
         models?: ModelConfig[];
         api?: {
             keys: ApiKey[];
@@ -145,6 +153,19 @@ export interface GatewayConfig {
          * false = interactive backend: claude TUI under the claude-pty-shell PTY wrapper.
          */
         headless?: boolean;
+        /**
+         * Self-healing recovery (Epic #195, Phase 3). When `autoRecover` is true the
+         * turn-trace watchdog may auto-execute a whitelisted recovery action
+         * (keystroke, session/receiver restart, safe-mode fallback, guarded resend)
+         * for a stalled turn. Default false — detection, incident logging, and
+         * notification still run when disabled; only live action execution is gated,
+         * so the feature ships dark and the operator opts in when ready. Safe-mode
+         * auto-fallback on hard PTY failure is independent of this flag (it is always
+         * reversible and never presses keys).
+         */
+        selfHealing?: {
+            autoRecover?: boolean;
+        };
         /** Global history retention/cleanup defaults */
         history?: HistoryConfig & {
             cleanupHour?: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/ui/web-ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web-ui.d.ts","sourceRoot":"","sources":["../../src/ui/web-ui.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,SAAK,GAAG,MAAM,CAkxB5D"}
+{"version":3,"file":"web-ui.d.ts","sourceRoot":"","sources":["../../src/ui/web-ui.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,SAAK,GAAG,MAAM,CAu3B5D"}

package/dist/ui/web-ui.js

@@ -119,6 +119,22 @@ function generateDashboardHtml(dashToken = '') {
     }
     .pty-close:hover { color: #fc8181; }
     .pty-refresh:hover { color: #63b3ed; }
+    /* Keyboard-focus outline on the viewer (it is tabindex focusable so PageUp/
+       PageDown reach the terminal); keep it subtle rather than the default ring. */
+    #pty-terminal:focus, #pty-terminal:focus-visible { outline: 1px solid #2d3748; }
+    .pty-mode-toggle {
+      background: none;
+      border: 1px solid #2d3748;
+      border-radius: 4px;
+      color: #718096;
+      cursor: pointer;
+      font-size: 0.72rem;
+      padding: 1px 7px;
+      margin-right: 6px;
+    }
+    .pty-mode-toggle:hover { color: #63b3ed; border-color: #3d4a5f; }
+    /* Active (input) mode — clearly signals the viewer now types into the PTY. */
+    .pty-mode-toggle.input-active { color: #0d1117; background: #63b3ed; border-color: #63b3ed; font-weight: 600; }
     /* Fixed-size terminal viewport — the server PTY runs at 200x50, so the
        viewer must NOT resize to the panel (that mismatch is what garbles the
        output). We render at the native size and pan horizontally if the 200-col
@@ -233,13 +249,16 @@ function generateDashboardHtml(dashToken = '') {
        in view when streaming. -->
   <div class="pty-viewer" id="pty-viewer">
     <div class="pty-viewer-header">
-      <span>Shell Process Viewer &mdash; <span class="agent-label" id="pty-agent-label"></span><span class="session-label" id="pty-session-label"></span></span>
+      <span><span id="pty-title-text">Terminal Viewer</span> &mdash; <span class="agent-label" id="pty-agent-label"></span><span class="session-label" id="pty-session-label"></span></span>
       <span>
+        <button class="pty-mode-toggle" id="pty-mode-toggle-btn" title="Toggle input mode (type into the live terminal)">&#x2328; View</button>
         <button class="pty-refresh" id="pty-refresh-btn" title="Refresh (reconnect &amp; redraw)">&#x21ba;</button>
         <button class="pty-close" id="pty-close-btn" title="Close">&#x2715;</button>
       </span>
     </div>
-    <div id="pty-terminal"></div>
+    <!-- tabindex makes the viewer keyboard-focusable so PageUp/PageDown reach it
+         even in read-only view mode (xterm stdin is disabled there). -->
+    <div id="pty-terminal" tabindex="0"></div>
   </div>
 
   <!-- Sessions — full width (session-centric, flat list) -->
@@ -350,6 +369,11 @@ function generateDashboardHtml(dashToken = '') {
     // multi-byte char into noise — decode as UTF-8 with {stream:true} so sequences
     // split across WebSocket frames are reassembled instead of corrupted.
     let utf8Decoder = null;
+    // Interactive input mode (Issue #201). When on, keystrokes typed into the
+    // terminal are streamed to the live PTY over the same WebSocket. Off by
+    // default (read-only mirror); the viewer flips it on via the mode toggle.
+    let ptyInputMode = false;
+    let ptyOnDataDisposable = null;
 
     // The agent's TUI enables mouse tracking (DECSET 1000/1002/1003/1006...).
     // While those modes are active, xterm.js forwards wheel/click events to the
@@ -373,6 +397,9 @@ function generateDashboardHtml(dashToken = '') {
       // Append the session id after the agent name, e.g. "claude-founder · 3c01897c…".
       document.getElementById('pty-session-label').textContent = sessionId ? ' \\u00b7 ' + sessionId : '';
       document.getElementById('pty-viewer').style.display = 'block';
+      // Always (re)open a fresh session in read-only view mode; the mode toggle
+      // lets the viewer switch into interactive input on demand.
+      setPtyInputMode(false);
 
       if (!term) {
         term = new Terminal({
@@ -488,12 +515,53 @@ function generateDashboardHtml(dashToken = '') {
       // are about to close intentionally, so it does not schedule a new one.
       if (ptyReconnectTimer) { clearTimeout(ptyReconnectTimer); ptyReconnectTimer = null; }
       ptyReconnectAttempts = 0;
+      setPtyInputMode(false); // always leave input mode when closing/switching
       if (ptyWs) { ptyWs.onclose = null; ptyWs.onerror = null; ptyWs.close(); ptyWs = null; }
       currentPtyAgent = null;
       currentPtySession = null;
       document.getElementById('pty-viewer').style.display = 'none';
     }
 
+    // Switch the viewer between read-only mirror and interactive input. In input
+    // mode the terminal accepts stdin and every keystroke (printable chars,
+    // Enter, arrows, Ctrl-combos, Esc) is streamed to the live PTY over the WS,
+    // like a real terminal; the title and toggle reflect the active mode.
+    function setPtyInputMode(on) {
+      if (!term) on = false;
+      ptyInputMode = !!on;
+      const toggleBtn = document.getElementById('pty-mode-toggle-btn');
+      const titleEl = document.getElementById('pty-title-text');
+      if (term) term.options.disableStdin = !ptyInputMode;
+      // Detach any previous onData listener before (re)attaching, so toggling
+      // off — or toggling on twice — never leaves a duplicate keystroke stream.
+      if (ptyOnDataDisposable) { ptyOnDataDisposable.dispose(); ptyOnDataDisposable = null; }
+      if (ptyInputMode && term) {
+        ptyOnDataDisposable = term.onData(function(data) {
+          if (ptyWs && ptyWs.readyState === WebSocket.OPEN) ptyWs.send(data);
+        });
+      }
+      if (titleEl) titleEl.textContent = ptyInputMode ? 'Interactive Terminal' : 'Terminal Viewer';
+      if (toggleBtn) {
+        toggleBtn.innerHTML = ptyInputMode ? '\\u2328 Input' : '\\u2328 View';
+        toggleBtn.classList.toggle('input-active', ptyInputMode);
+        toggleBtn.title = ptyInputMode
+          ? 'Input mode — keystrokes go to the live terminal (click for read-only)'
+          : 'Toggle input mode (type into the live terminal)';
+      }
+      if (ptyInputMode && term) {
+        term.focus(); // typing goes to xterm's textarea
+      } else {
+        // View mode: focus the container (tabindex) so PageUp/PageDown reach our
+        // key handler instead of scrolling the browser page.
+        const host = document.getElementById('pty-terminal');
+        if (host) host.focus();
+      }
+    }
+
+    function togglePtyInputMode() {
+      setPtyInputMode(!ptyInputMode);
+    }
+
     // Refresh: force a clean reconnect of the CURRENT session. The server replays
     // a freshly-serialized screen frame on subscribe, so this redraws from a clean
     // xterm state — a manual escape hatch if the live stream ever drifts.
@@ -505,8 +573,41 @@ function generateDashboardHtml(dashToken = '') {
       await openPtyViewer(agentId, sessionId);
     }
 
+    // Page Up / Page Down keys (Issue #201): the alt-screen mirror keeps no
+    // scrollback of its own, so a physical PageUp/PageDown key is forwarded to the
+    // live TUI — which holds the history and scrolls itself. In read-only view mode
+    // xterm's stdin is disabled, so without this those keys would just scroll the
+    // browser page; here we intercept ONLY these two keys (never printable input)
+    // and send them to the PTY, so the user can page through earlier output without
+    // enabling the interactive keyboard. In input mode xterm already forwards them
+    // via onData, so we skip to avoid double-send.
+    //
+    // The listener is attached to the document, NOT the viewer container: xterm renders
+    // its own focusable helpers inside #pty-terminal, and with disableStdin the
+    // container rarely holds focus reliably (a reconnect or stray click drops it),
+    // so a container-scoped keydown silently missed the keys. Gating on the viewer
+    // being open + view mode keeps it from hijacking PageUp elsewhere on the page,
+    // and we bail when focus is in a real text field so form paging still works.
+    // \\x1b[5~ = PageUp, \\x1b[6~ = PageDown.
+    function forwardPageKey(e) {
+      if (e.key !== 'PageUp' && e.key !== 'PageDown') return;
+      if (ptyInputMode) return; // input mode: xterm.onData already sends it
+      // Only while THIS viewer is actually open with a live socket.
+      const viewer = document.getElementById('pty-viewer');
+      if (!viewer || viewer.style.display === 'none') return;
+      if (!ptyWs || ptyWs.readyState !== WebSocket.OPEN) return;
+      // Don't steal paging from a genuine editable field (none in view mode today,
+      // but keep the guard so the document-level listener stays well-behaved).
+      const t = e.target;
+      if (t && (t.tagName === 'INPUT' || (t.tagName === 'TEXTAREA' && !t.disabled) || t.isContentEditable)) return;
+      e.preventDefault();
+      ptyWs.send(e.key === 'PageUp' ? '\\x1b[5~' : '\\x1b[6~');
+    }
+    document.addEventListener('keydown', forwardPageKey);
+
     document.getElementById('pty-close-btn').addEventListener('click', closePtyViewer);
     document.getElementById('pty-refresh-btn').addEventListener('click', function() { void refreshPtyViewer(); });
+    document.getElementById('pty-mode-toggle-btn').addEventListener('click', togglePtyInputMode);
 
     // Event delegation for Live buttons (avoids inline onclick + HTML injection)
     document.getElementById('sessions-tbody').addEventListener('click', function(e) {

package/dist/ui/web-ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-ui.js","sourceRoot":"","sources":["../../src/ui/web-ui.ts"],"names":[],"mappings":";;AAIA,sDAkxBC;AAtxBD;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,SAAS,GAAG,EAAE;IAClD,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC3E,OAAO;;;;;qCAK4B,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA0wBtC,CAAC;AACT,CAAC"}
+{"version":3,"file":"web-ui.js","sourceRoot":"","sources":["../../src/ui/web-ui.ts"],"names":[],"mappings":";;AAIA,sDAu3BC;AA33BD;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,SAAS,GAAG,EAAE;IAClD,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC3E,OAAO;;;;;qCAK4B,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA+2BtC,CAAC;AACT,CAAC"}

package/mcp/tools/skills/handlers.ts

@@ -161,8 +161,10 @@ export async function installSkill(params: InstallSkillParams): Promise<string>
     throw new Error(`SKILL.md exceeds ${MAX_SKILL_SIZE / 1024}KB limit (${(content.length / 1024).toFixed(1)}KB)`);
   }
 
-  // Parse frontmatter to extract name
-  const { extractFrontmatter } = await import('../../../src/skills/parser');
+  // Parse frontmatter to extract name. Import compiled dist/, not raw src/ —
+  // src/ is not published (files: ["mcp/"]), so a src/ import throws "Cannot find
+  // module" on installed packages. Enforced by mcp-no-src-imports.test.ts.
+  const { extractFrontmatter } = await import('../../../dist/skills/parser.js');
   const extracted = extractFrontmatter(content);
   if (!extracted) {
     throw new Error('Invalid SKILL.md: no valid YAML frontmatter found.');

package/mcp/tools/telegram/receiver-server.ts

@@ -28,7 +28,15 @@ import { randomBytes } from 'crypto'
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync, chmodSync, existsSync } from 'fs'
 import { homedir } from 'os'
 import { join, extname, sep } from 'path'
+import { execFileSync } from 'child_process'
 import { createWorkingStateManager, drainOrphanForwards } from './typing'
+// Import compiled dist/, not raw src/ — src/ is not published (files: ["mcp/"]),
+// so a src/ import crashes this bun-run receiver on installed packages (the bug
+// that silenced every bot on systemd installs). Enforced by
+// tests/unit/mcp-no-src-imports.test.ts.
+import { formatTurnIncident, type TurnIncident } from '../../../dist/agent/turn-trace.js'
+import { createIncidentStore } from '../../../dist/agent/incident-store.js'
+import type { RecoveryOutcome } from '../../../dist/agent/incident.js'
 import { initDedupDir, isDuplicate as _isDuplicate, pruneDedup as _pruneDedup } from './dedup'
 import { hasMarkdown, toTelegramHtml, migrateAccess } from './pure'
 
@@ -104,6 +112,70 @@ let botUsername = ''
 
 const TYPING_DIR = join(STATE_DIR, 'typing')
 
+// ─── Incident store (Epic #195, Phase 2) ────────────────────────────────────
+// Persist turn-trace stalls as scrubbed on-disk bundles, deduped by fingerprint
+// (stage + failure class + CLI version) with escalation. The store owns all
+// disk IO; the pure decision logic lives in src/agent/incident.ts.
+const INCIDENTS_DIR = join(homedir(), '.claude-gateway', 'incidents')
+
+// The Claude CLI version is part of the fingerprint. Resolve it once and cache
+// it — a new version is a new fingerprint, and the receiver is restarted when
+// the CLI is updated, so a per-process cache is safe.
+let cachedCliVersion: string | null = null
+function getCliVersion(): string {
+  if (cachedCliVersion !== null) return cachedCliVersion
+  try {
+    const out = execFileSync('claude', ['--version'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    const m = out.trim().match(/^(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/)
+    cachedCliVersion = m ? m[1] : 'unknown'
+  } catch {
+    cachedCliVersion = 'unknown'
+  }
+  return cachedCliVersion
+}
+
+// Gateway version, best-effort, for manifest context only (not fingerprinted).
+function readGatewayVersion(): string {
+  for (const rel of ['../../../package.json', '../../package.json']) {
+    try {
+      const raw = readFileSync(join(__dirname, rel), 'utf8')
+      const v = (JSON.parse(raw) as { version?: string }).version
+      if (typeof v === 'string' && v.length > 0) return v
+    } catch {
+      // try next candidate
+    }
+  }
+  return 'unknown'
+}
+
+const incidentStore = createIncidentStore({
+  dir: INCIDENTS_DIR,
+  fs: { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync },
+  now: () => Date.now(),
+  channel: 'telegram',
+  gatewayVersion: readGatewayVersion(),
+  getCliVersion,
+})
+
+// Prune old bundles at startup and daily thereafter (retention is enforced in
+// the store; this just triggers it periodically).
+try {
+  incidentStore.prune()
+} catch {
+  // Non-fatal: a prune failure must not stop the receiver from serving.
+}
+setInterval(() => {
+  try {
+    incidentStore.prune()
+  } catch {
+    /* non-fatal */
+  }
+}, 24 * 60 * 60 * 1000).unref()
+
 const typingManager = createWorkingStateManager(
   TYPING_DIR,
   {
@@ -117,8 +189,99 @@ const typingManager = createWorkingStateManager(
       ]),
   },
   { mkdirSync, writeFileSync, existsSync, rmSync, readFileSync, statSync },
+  // Turn-trace watchdog sink (Epic #195, Phase 2): persist a scrubbed incident
+  // bundle, then notify the affected chat only when the escalation rules say so
+  // (quiet on the first stall, louder once a fingerprint repeats). Any failure
+  // here is swallowed — incident bookkeeping must never break the live channel.
+  (incident, evidence) => {
+    process.stderr.write(`telegram channel: ${formatTurnIncident(incident)}\n`)
+    try {
+      const result = incidentStore.record(incident, evidence)
+      if (result.escalation.notify) {
+        void notifyIncident(incident.chatId, result)
+        incidentStore.markNotified(result.id, result.escalation.level)
+      }
+      // Cross-process recovery bridge (Epic #195, Phase 3b): for stages whose
+      // recovery lives in the runner (session/CLI), ask it to attempt recovery
+      // and persist the outcome. Fire-and-forget — recovery must never block the
+      // channel, and it is a no-op unless the operator enabled autoRecover.
+      void attemptRecover(incident, result.id)
+    } catch (err) {
+      process.stderr.write(
+        `telegram channel: incident persist failed: ${String(err)}\n`,
+      )
+    }
+  },
 )
 
+// Stages whose recovery must run in the runner process (live session control):
+// session injection, CLI startup, and no-output progress wedges. Inbound
+// (channel ingress) and delivery/dispatch (transport) are receiver-side and are
+// not bridged here.
+const RUNNER_RECOVERABLE_STAGES: ReadonlySet<string> = new Set(['inject', 'startup', 'progress'])
+
+// A stable-per-turn key for the runner's intervention budget. Uses the stalled
+// stage's start second (at − sinceMs), so repeated detections of the SAME wedged
+// turn share a budget while a genuinely new turn gets a fresh one.
+function recoveryTurnKey(incident: TurnIncident): string {
+  const startSec = Math.round((incident.at - incident.sinceMs) / 1000)
+  return `${incident.chatId}:${startSec}`
+}
+
+// Ask the runner to attempt recovery for a session/CLI-stage stall, then persist
+// the returned outcome to the incident bundle. Best-effort and non-blocking.
+async function attemptRecover(incident: TurnIncident, incidentId: string): Promise<void> {
+  if (!CALLBACK_URL_BASE) return
+  if (!RUNNER_RECOVERABLE_STAGES.has(incident.stage)) return
+  try {
+    const res = await fetch(CALLBACK_URL_BASE + '/recover', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        incidentId,
+        chatId: incident.chatId,
+        stage: incident.stage,
+        failureClass: incident.failureClass,
+        turnKey: recoveryTurnKey(incident),
+      }),
+    })
+    if (!res.ok) return
+    const data = (await res.json()) as { ok?: boolean; outcome?: RecoveryOutcome }
+    if (data.ok && data.outcome) {
+      incidentStore.appendRecovery(incidentId, data.outcome)
+    }
+  } catch (err) {
+    process.stderr.write(`telegram channel: recover POST failed: ${String(err)}\n`)
+  }
+}
+
+// Short, content-free notice for a stalled turn. No message text or chat id is
+// echoed back — only the pipeline stage and (on repeat) the occurrence count.
+async function notifyIncident(
+  chatId: string,
+  result: { escalation: { level: string }; occurrences: number; manifest: { stage: string } },
+): Promise<void> {
+  const stage = result.manifest.stage
+  let text: string
+  if (result.escalation.level === 'investigate') {
+    text =
+      `⚠️ Recurring stall detected at the "${stage}" stage ` +
+      `(${result.occurrences}× recently). This looks like a persistent issue — ` +
+      `it has been logged for investigation.`
+  } else {
+    // Neutral wording: automatic recovery only runs when the operator has
+    // enabled gateway.selfHealing.autoRecover (off by default), and the receiver
+    // cannot see that runner-side flag — so do not promise it here.
+    text =
+      `⚠️ A turn stalled at the "${stage}" stage and has been logged.`
+  }
+  try {
+    await bot.api.sendMessage(chatId, text)
+  } catch {
+    // Best-effort notify; the incident is already persisted regardless.
+  }
+}
+
 type PendingEntry = {
   senderId: string
   chatId: string