@integrity-labs/agt-cli 0.27.94 → 0.27.95

package/dist/mcp/telegram-channel.js

@@ -15154,8 +15154,296 @@ function createCrossTeamPeerAuditClient(args) {
   };
 }
 
-// src/observed-chat-client.ts
+// src/diagnostic-event-client.ts
 var REQUEST_TIMEOUT_MS2 = 1e4;
+function createDiagnosticEventClient(args) {
+  if (!args.agtHost || !args.agtApiKey || !args.agentId) return null;
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const log = args.log ?? (() => {
+  });
+  const base = args.agtHost.replace(/\/+$/, "");
+  const agentId = args.agentId;
+  const apiKey = args.agtApiKey;
+  let cachedToken = null;
+  let cachedTokenExpiresAt = 0;
+  async function getToken() {
+    if (cachedToken && Date.now() < cachedTokenExpiresAt) return cachedToken;
+    const resp = await fetchImpl(`${base}/host/exchange`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ host_key: apiKey }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS2)
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(`/host/exchange failed (${resp.status}): ${body.slice(0, 200)}`);
+    }
+    const data = await resp.json();
+    cachedToken = data.token;
+    cachedTokenExpiresAt = data.expires_at ? new Date(data.expires_at).getTime() - 12e4 : Date.now() + 55 * 6e4;
+    return cachedToken;
+  }
+  async function postOnce(event) {
+    const token = await getToken();
+    return fetchImpl(`${base}/host/diagnostic-command-event`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ agent_id: agentId, ...event }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS2)
+    });
+  }
+  async function emitAsync(event) {
+    try {
+      let resp = await postOnce(event);
+      if (resp.status === 401) {
+        cachedToken = null;
+        cachedTokenExpiresAt = 0;
+        resp = await postOnce(event);
+      }
+      if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        log(
+          `diagnostic-event: POST failed (${resp.status}) outcome=${event.outcome}: ${body.slice(0, 200)}`
+        );
+      }
+    } catch (err) {
+      log(`diagnostic-event: emit threw outcome=${event.outcome}: ${err.message}`);
+    }
+  }
+  return {
+    emit(event) {
+      void emitAsync(event);
+    }
+  };
+}
+
+// src/telegram-investigate.ts
+var INVESTIGATE_SYNTAX_RE = /^\/investigate(?:[-_]([A-Za-z0-9_-]{1,64}))?(?:@([A-Za-z0-9_]{1,64}))?(?:\s|$)/;
+function isInvestigateSyntax(text) {
+  return INVESTIGATE_SYNTAX_RE.test(text);
+}
+function classifyInvestigateText(text, opts) {
+  const m = INVESTIGATE_SYNTAX_RE.exec(text);
+  if (!m) return "ignore";
+  const codeSuffix = m[1];
+  if (codeSuffix) {
+    const normalise = (s) => s.toLowerCase().replace(/_/g, "-");
+    if (normalise(codeSuffix) !== normalise(opts.codeName)) return "ignore";
+  }
+  const botSuffix = m[2]?.toLowerCase();
+  if (!botSuffix) return "act";
+  if (!opts.botUsername) return "verification_failed";
+  return botSuffix === opts.botUsername.toLowerCase() ? "act" : "ignore";
+}
+function evaluateInvestigateGate(opts) {
+  if (opts.chatType !== "private") return { ok: false, reason: "not-dm" };
+  if (opts.diagnosticChatIds.size === 0) return { ok: false, reason: "allowlist-empty" };
+  if (!opts.senderId || !opts.diagnosticChatIds.has(opts.senderId)) {
+    return { ok: false, reason: "not-allowed" };
+  }
+  return { ok: true };
+}
+function createSingleTailSlot() {
+  let expiresAtMs = null;
+  return {
+    reserve(windowMs, nowMs = Date.now()) {
+      if (expiresAtMs !== null && expiresAtMs > nowMs) return null;
+      expiresAtMs = nowMs + windowMs;
+      return expiresAtMs;
+    },
+    remainingMs(nowMs = Date.now()) {
+      if (expiresAtMs === null) return 0;
+      return Math.max(0, expiresAtMs - nowMs);
+    },
+    release() {
+      expiresAtMs = null;
+    }
+  };
+}
+
+// src/pane-tail.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { open, stat } from "fs/promises";
+
+// src/session-probe-runtime.ts
+import { execFileSync } from "child_process";
+function agentTmuxSessionName(codeName) {
+  return `agt-${codeName}`;
+}
+function escapePgrepRegex(value) {
+  return value.replace(/[.[\]{}()*+?^$|\\]/g, "\\$&");
+}
+function probeClaudeProcessInTmux(tmuxSession) {
+  const escapedSession = escapePgrepRegex(tmuxSession);
+  const pattern = `(^|[[:space:]])--name ${escapedSession}([[:space:]]|$)`;
+  try {
+    const out = execFileSync("pgrep", ["-f", "--", pattern], {
+      encoding: "utf-8",
+      timeout: 3e3
+    }).trim();
+    return out.length > 0 ? "alive" : "dead";
+  } catch (err) {
+    const e = err;
+    if (e?.code === "ENOENT") return "unknown";
+    return e?.status === 1 ? "dead" : "unknown";
+  }
+}
+function probeTmuxSession(tmuxSession) {
+  try {
+    execFileSync("tmux", ["has-session", "-t", tmuxSession], {
+      stdio: "ignore",
+      timeout: 3e3
+    });
+    return "alive";
+  } catch (err) {
+    const e = err;
+    if (e?.code === "ENOENT") return "unknown";
+    return "dead";
+  }
+}
+function probeAgentSession(codeName) {
+  const session = agentTmuxSessionName(codeName);
+  const tmux = probeTmuxSession(session);
+  const claude = tmux === "alive" ? probeClaudeProcessInTmux(session) : tmux;
+  return { tmux, claude };
+}
+var probeCache = /* @__PURE__ */ new Map();
+var SESSION_PROBE_TTL_MS = 15e3;
+function probeAgentSessionCached(codeName, ttlMs = SESSION_PROBE_TTL_MS, now = Date.now()) {
+  const cached2 = probeCache.get(codeName);
+  if (cached2 && now - cached2.at < ttlMs) return cached2.value;
+  const value = probeAgentSession(codeName);
+  probeCache.set(codeName, { at: now, value });
+  return value;
+}
+
+// src/pane-tail.ts
+var execFileAsync = promisify(execFile);
+var PANE_LOG_TAIL_BYTES = 64 * 1024;
+var TMUX_CAPTURE_TIMEOUT_MS = 2e3;
+async function capturePaneSnapshot(opts) {
+  const scrollback = opts.scrollbackLines ?? 200;
+  try {
+    const { stdout } = await execFileAsync(
+      "tmux",
+      ["capture-pane", "-p", "-t", agentTmuxSessionName(opts.codeName), "-S", `-${scrollback}`],
+      { timeout: TMUX_CAPTURE_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 }
+    );
+    return { source: "tmux", text: stdout };
+  } catch {
+  }
+  if (!opts.agentDir) return null;
+  const paneLogPath = `${opts.agentDir}/pane.log`;
+  try {
+    const tail = await readFileTail(paneLogPath, PANE_LOG_TAIL_BYTES);
+    if (tail === null) return null;
+    return { source: "pane-log", text: stripAnsi(tail) };
+  } catch {
+    return null;
+  }
+}
+async function readFileTail(path, maxBytes) {
+  const st = await stat(path);
+  if (!st.isFile()) return null;
+  const start = Math.max(0, st.size - maxBytes);
+  const length = st.size - start;
+  if (length === 0) return "";
+  const handle = await open(path, "r");
+  try {
+    const buf = Buffer.alloc(length);
+    await handle.read(buf, 0, length, start);
+    let text = buf.toString("utf8");
+    if (start > 0) {
+      const nl = text.indexOf("\n");
+      if (nl !== -1) text = text.slice(nl + 1);
+    }
+    return text;
+  } finally {
+    await handle.close();
+  }
+}
+function stripAnsi(text) {
+  return text.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, "").replace(/\x1b\[[0-9;?<=>!]*[ -\/]*[@-~]/g, "").replace(/\x1b./g, "").replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+}
+var SECRET_PATTERNS = [
+  // Augmented host API keys
+  { re: /tlk_[A-Za-z0-9]{8,}/g, label: "agt-api-key" },
+  // Slack tokens: bot/app/user/refresh/config
+  { re: /x(?:ox[abprs]|app)-[A-Za-z0-9-]{8,}/g, label: "slack-token" },
+  // JWTs (three base64url segments, first one always starts with eyJ)
+  { re: /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, label: "jwt" },
+  // OpenAI / Anthropic-style keys (sk-..., sk-ant-...)
+  { re: /sk-[A-Za-z0-9_-]{16,}/g, label: "sk-key" },
+  // AWS access key IDs
+  { re: /(?:AKIA|ASIA)[0-9A-Z]{16}/g, label: "aws-key" },
+  // GitHub tokens
+  { re: /gh[pousr]_[A-Za-z0-9]{20,}/g, label: "github-token" }
+];
+function redactPaneText(text) {
+  let out = redactAugmentedPaths(text);
+  for (const { re, label } of SECRET_PATTERNS) {
+    out = out.replace(re, `<redacted:${label}>`);
+  }
+  return out;
+}
+var DEFAULT_MAX_CHARS = 3900;
+var REFLOW_COLS = 80;
+function formatPaneSnapshot(opts) {
+  const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
+  const commandName = opts.commandName ?? "/debug";
+  const header = opts.status.kind === "live" ? `\u{1F50E} Live pane tail for \`${opts.codeName}\` \u2014 captured ${opts.capturedAtLabel} \xB7 updates ~3s \xB7 expires in ${formatCountdown(opts.status.secondsRemaining)}` : `\u{1F50E} Pane tail for \`${opts.codeName}\` \u2014 captured ${opts.capturedAtLabel} \xB7 *expired* \u2014 run \`${commandName}\` to restart`;
+  const fenceOverhead = header.length + "\n```\n".length + "\n```".length + 16;
+  const contentBudget = Math.max(0, maxChars - fenceOverhead);
+  const lines = reflowLines(sanitizeForCodeBlock(opts.text), REFLOW_COLS);
+  const kept = [];
+  let used = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const cost = lines[i].length + 1;
+    if (used + cost > contentBudget) break;
+    kept.unshift(lines[i]);
+    used += cost;
+  }
+  const truncated = kept.length < lines.length;
+  const body = kept.join("\n").trimEnd();
+  const block = body.length > 0 ? `\`\`\`
+${truncated ? "\u2026\n" : ""}${body}
+\`\`\`` : "_(pane is empty)_";
+  return `${header}
+${block}`;
+}
+function formatCountdown(totalSeconds) {
+  const s = Math.max(0, Math.floor(totalSeconds));
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+}
+function sanitizeForCodeBlock(text) {
+  return text.replace(/```/g, "`\u200B`\u200B`");
+}
+function reflowLines(text, cols) {
+  const out = [];
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.replace(/\s+$/, "");
+    if (line.length <= cols) {
+      out.push(line);
+      continue;
+    }
+    for (let i = 0; i < line.length; i += cols) {
+      out.push(line.slice(i, i + cols));
+    }
+  }
+  const collapsed = [];
+  for (const line of out) {
+    if (line === "" && collapsed[collapsed.length - 1] === "") continue;
+    collapsed.push(line);
+  }
+  return collapsed;
+}
+
+// src/observed-chat-client.ts
+var REQUEST_TIMEOUT_MS3 = 1e4;
 function createObservedChatClient(args) {
   if (!args.agtHost || !args.agtApiKey || !args.agentId) return null;
   const fetchImpl = args.fetchImpl ?? fetch;
@@ -15173,7 +15461,7 @@ function createObservedChatClient(args) {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ host_key: apiKey }),
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS2)
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS3)
     });
     if (!resp.ok) {
       const body = await resp.text().catch(() => "");
@@ -15190,7 +15478,7 @@ function createObservedChatClient(args) {
       method: "POST",
       headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
       body: JSON.stringify({ agent_id: agentId, ...chat }),
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS2)
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS3)
     });
   }
   async function emitAsync(chat) {
@@ -15237,7 +15525,7 @@ function createObservedChatClient(args) {
 }
 
 // src/conversation-ingest-client.ts
-var REQUEST_TIMEOUT_MS3 = 1e4;
+var REQUEST_TIMEOUT_MS4 = 1e4;
 function createConversationIngestClient(args) {
   if (!args.agtHost || !args.agtApiKey || !args.agentId) return null;
   const fetchImpl = args.fetchImpl ?? fetch;
@@ -15254,7 +15542,7 @@ function createConversationIngestClient(args) {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ host_key: apiKey }),
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS3)
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS4)
     });
     if (!resp.ok) {
       const body = await resp.text().catch(() => "");
@@ -15277,7 +15565,7 @@ function createConversationIngestClient(args) {
       method: "POST",
       headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
       body: JSON.stringify({ agent_id: agentId, ...payload }),
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS3)
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS4)
     });
   }
   function refKey(payload) {
@@ -15309,7 +15597,7 @@ function createConversationIngestClient(args) {
 }
 
 // src/inbound-context-client.ts
-var REQUEST_TIMEOUT_MS4 = 1e4;
+var REQUEST_TIMEOUT_MS5 = 1e4;
 function createInboundContextClient(args) {
   if (!args.agtHost || !args.agtApiKey || !args.agentId) return null;
   const fetchImpl = args.fetchImpl ?? fetch;
@@ -15326,7 +15614,7 @@ function createInboundContextClient(args) {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ host_key: apiKey }),
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS4)
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS5)
     });
     if (!resp.ok) {
       const body = await resp.text().catch(() => "");
@@ -15343,7 +15631,7 @@ function createInboundContextClient(args) {
       method: "POST",
       headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
       body: JSON.stringify(body),
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS4)
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS5)
     });
   }
   async function emit(args2) {
@@ -15579,58 +15867,6 @@ function shouldReplayMarker(i) {
   return i.replayCount < (i.maxReplays ?? MAX_MARKER_REPLAYS);
 }
 
-// src/session-probe-runtime.ts
-import { execFileSync } from "child_process";
-function agentTmuxSessionName(codeName) {
-  return `agt-${codeName}`;
-}
-function escapePgrepRegex(value) {
-  return value.replace(/[.[\]{}()*+?^$|\\]/g, "\\$&");
-}
-function probeClaudeProcessInTmux(tmuxSession) {
-  const escapedSession = escapePgrepRegex(tmuxSession);
-  const pattern = `(^|[[:space:]])--name ${escapedSession}([[:space:]]|$)`;
-  try {
-    const out = execFileSync("pgrep", ["-f", "--", pattern], {
-      encoding: "utf-8",
-      timeout: 3e3
-    }).trim();
-    return out.length > 0 ? "alive" : "dead";
-  } catch (err) {
-    const e = err;
-    if (e?.code === "ENOENT") return "unknown";
-    return e?.status === 1 ? "dead" : "unknown";
-  }
-}
-function probeTmuxSession(tmuxSession) {
-  try {
-    execFileSync("tmux", ["has-session", "-t", tmuxSession], {
-      stdio: "ignore",
-      timeout: 3e3
-    });
-    return "alive";
-  } catch (err) {
-    const e = err;
-    if (e?.code === "ENOENT") return "unknown";
-    return "dead";
-  }
-}
-function probeAgentSession(codeName) {
-  const session = agentTmuxSessionName(codeName);
-  const tmux = probeTmuxSession(session);
-  const claude = tmux === "alive" ? probeClaudeProcessInTmux(session) : tmux;
-  return { tmux, claude };
-}
-var probeCache = /* @__PURE__ */ new Map();
-var SESSION_PROBE_TTL_MS = 15e3;
-function probeAgentSessionCached(codeName, ttlMs = SESSION_PROBE_TTL_MS, now = Date.now()) {
-  const cached2 = probeCache.get(codeName);
-  if (cached2 && now - cached2.at < ttlMs) return cached2.value;
-  const value = probeAgentSession(codeName);
-  probeCache.set(codeName, { at: now, value });
-  return value;
-}
-
 // src/telegram-channel.ts
 function redactId(id) {
   return createHash("sha256").update(String(id)).digest("hex").slice(0, 8);
@@ -15644,6 +15880,9 @@ var AGT_AGENT_ID = process.env.AGT_AGENT_ID ?? null;
 var ALLOWED_CHATS = new Set(
   (process.env.TELEGRAM_ALLOWED_CHATS ?? "").split(",").map((s) => s.trim()).filter(Boolean)
 );
+var DIAGNOSTIC_CHAT_IDS = new Set(
+  (process.env.TELEGRAM_DIAGNOSTIC_CHAT_IDS ?? "").split(",").map((s) => s.trim()).filter(Boolean)
+);
 var PEER_CLASSIFIER_CONFIG = {
   peer_agent_mode: parsePeerAgentModeEnv(process.env.TELEGRAM_PEER_AGENT_MODE),
   peer_group_ids: parsePeerGroupIdsEnv(process.env.TELEGRAM_PEER_GROUP_IDS),
@@ -15679,6 +15918,13 @@ var crossTeamPeerAuditClient = createCrossTeamPeerAuditClient({
   log: (line) => process.stderr.write(`telegram-channel(${AGENT_CODE_NAME}): ${line}
 `)
 });
+var diagnosticEventClient = createDiagnosticEventClient({
+  agtHost: AGT_HOST,
+  agtApiKey: AGT_API_KEY,
+  agentId: process.env.AGT_AGENT_ID ?? null,
+  log: (line) => process.stderr.write(`telegram-channel(${AGENT_CODE_NAME}): ${line}
+`)
+});
 var observedChatClient = createObservedChatClient({
   agtHost: AGT_HOST,
   agtApiKey: AGT_API_KEY,
@@ -15878,7 +16124,8 @@ function buildTelegramHelpMessage(codeName) {
     "",
     `_Type these in any chat where the bot is present (intercepted by the agent):_`,
     `\u2022 /help \u2014 show this help`,
-    `\u2022 /restart \u2014 restart this agent`
+    `\u2022 /restart \u2014 restart this agent`,
+    `\u2022 /investigate-${codeName} \u2014 live tail of this agent's terminal pane (DM only; team owners/admins and the agent's reports-to person)`
   ].join("\n");
 }
 async function handleHelpCommand(opts) {
@@ -15973,6 +16220,261 @@ async function handleRestartCommand(opts) {
     }
   }
 }
+var INVESTIGATE_TAIL_WINDOW_MS = 12e4;
+var INVESTIGATE_TAIL_INTERVAL_MS = 3e3;
+var INVESTIGATE_TAIL_MAX_CONSECUTIVE_FAILURES = 4;
+var INVESTIGATE_MAX_CHARS = 3800;
+var investigateTailSlot = createSingleTailSlot();
+function investigateAuditLog(line) {
+  process.stderr.write(`telegram-channel(${AGENT_CODE_NAME}): /investigate ${line}
+`);
+}
+function investigateNowUtcLabel() {
+  return `${(/* @__PURE__ */ new Date()).toISOString().slice(11, 19)} UTC`;
+}
+function investigateSleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function classifyInvestigateCommand(text) {
+  const needsUsername = /@[A-Za-z0-9_]{1,64}(?:\s|$)/.test(text);
+  const ours = needsUsername ? await resolveBotUsername() : null;
+  return classifyInvestigateText(text, { codeName: AGENT_CODE_NAME, botUsername: ours });
+}
+async function sendInvestigateReply(chatId, messageId, text) {
+  try {
+    const resp = await telegramApiCall(
+      "sendMessage",
+      {
+        chat_id: chatId,
+        text,
+        parse_mode: "Markdown",
+        reply_to_message_id: Number(messageId)
+      },
+      1e4
+    );
+    if (!resp.ok) {
+      investigateAuditLog(`reply rejected by Telegram: ${resp.description ?? "unknown"}`);
+    }
+  } catch (err) {
+    investigateAuditLog(`reply send failed: ${redactAugmentedPaths(err.message)}`);
+  }
+}
+async function runInvestigateTailLoop(opts) {
+  const investigateCmd = `/investigate-${AGENT_CODE_NAME}`;
+  let last = opts.initialFrame;
+  let consecutiveFailures = 0;
+  let delayMs = INVESTIGATE_TAIL_INTERVAL_MS;
+  try {
+    while (Date.now() + delayMs < opts.expiresAtMs) {
+      await investigateSleep(delayMs);
+      delayMs = INVESTIGATE_TAIL_INTERVAL_MS;
+      const snapshot = await capturePaneSnapshot({
+        codeName: AGENT_CODE_NAME,
+        agentDir: TELEGRAM_AGENT_DIR
+      });
+      if (!snapshot) {
+        consecutiveFailures++;
+        if (consecutiveFailures >= INVESTIGATE_TAIL_MAX_CONSECUTIVE_FAILURES) {
+          investigateAuditLog(`tail aborted after ${consecutiveFailures} consecutive capture failures`);
+          break;
+        }
+        continue;
+      }
+      const frame = {
+        body: redactPaneText(snapshot.text),
+        source: snapshot.source,
+        capturedAtLabel: investigateNowUtcLabel()
+      };
+      if (frame.body === last.body) continue;
+      const text = formatPaneSnapshot({
+        codeName: AGENT_CODE_NAME,
+        text: frame.body,
+        source: frame.source,
+        capturedAtLabel: frame.capturedAtLabel,
+        status: {
+          kind: "live",
+          secondsRemaining: Math.max(0, Math.round((opts.expiresAtMs - Date.now()) / 1e3))
+        },
+        maxChars: INVESTIGATE_MAX_CHARS,
+        commandName: investigateCmd
+      });
+      try {
+        const resp = await telegramApiCall(
+          "editMessageText",
+          {
+            chat_id: opts.chatId,
+            message_id: opts.messageId,
+            text,
+            parse_mode: "Markdown"
+          },
+          1e4
+        );
+        if (resp.ok) {
+          last = frame;
+          consecutiveFailures = 0;
+          continue;
+        }
+        const retryAfter = resp.parameters?.retry_after;
+        if (typeof retryAfter === "number" && retryAfter > 0) {
+          delayMs = Math.max(INVESTIGATE_TAIL_INTERVAL_MS, retryAfter * 1e3);
+          continue;
+        }
+        consecutiveFailures++;
+        if (consecutiveFailures >= INVESTIGATE_TAIL_MAX_CONSECUTIVE_FAILURES) {
+          investigateAuditLog(
+            `tail aborted after ${consecutiveFailures} consecutive update failures (last: ${resp.description ?? "unknown"})`
+          );
+          break;
+        }
+      } catch (err) {
+        consecutiveFailures++;
+        if (consecutiveFailures >= INVESTIGATE_TAIL_MAX_CONSECUTIVE_FAILURES) {
+          investigateAuditLog(
+            `tail aborted after ${consecutiveFailures} consecutive update failures (last: ${redactAugmentedPaths(err.message)})`
+          );
+          break;
+        }
+      }
+    }
+  } finally {
+    investigateTailSlot.release();
+    try {
+      await telegramApiCall(
+        "editMessageText",
+        {
+          chat_id: opts.chatId,
+          message_id: opts.messageId,
+          text: formatPaneSnapshot({
+            codeName: AGENT_CODE_NAME,
+            text: last.body,
+            source: last.source,
+            capturedAtLabel: last.capturedAtLabel,
+            status: { kind: "expired" },
+            maxChars: INVESTIGATE_MAX_CHARS,
+            commandName: investigateCmd
+          }),
+          parse_mode: "Markdown"
+        },
+        1e4
+      );
+    } catch (err) {
+      investigateAuditLog(`expired-edit failed: ${redactAugmentedPaths(err.message)}`);
+    }
+  }
+}
+async function handleInvestigateCommand(opts) {
+  const investigateCmd = `/investigate-${AGENT_CODE_NAME}`;
+  const emitAudit = (outcome, reason) => {
+    diagnosticEventClient?.emit({
+      channel: "telegram",
+      command: "investigate",
+      outcome,
+      reason,
+      chat_id: opts.chatId,
+      sender_chat_id: opts.senderId
+    });
+  };
+  const verdict = evaluateInvestigateGate({
+    chatType: opts.chatType,
+    senderId: opts.senderId,
+    diagnosticChatIds: DIAGNOSTIC_CHAT_IDS
+  });
+  if (!verdict.ok) {
+    investigateAuditLog(
+      `denied reason=${verdict.reason} sender=${opts.senderId ? redactId(opts.senderId) : "unknown"}`
+    );
+    emitAudit("denied", verdict.reason);
+    const denialText = verdict.reason === "not-dm" ? `\u26A0\uFE0F \`${investigateCmd}\` only works in a direct message with \`${AGENT_CODE_NAME}\` \u2014 it shows the agent's raw terminal, so it stays 1:1. Open a DM with the bot and run it there.` : verdict.reason === "allowlist-empty" ? `\u{1F6AB} \`${investigateCmd}\` is disabled for \`${AGENT_CODE_NAME}\` \u2014 no diagnostic allowlist reached this host. It is derived from team owners/admins and the agent's reports-to person; if that's you, link your Telegram in your Augmented Team contact preferences and wait for the next refresh.` : `\u{1F6AB} \`${investigateCmd}\` denied \u2014 it's limited to team owners/admins and the person this agent reports to. If that's you, link your Telegram in your Augmented Team contact preferences and wait for the next refresh.`;
+    await sendInvestigateReply(opts.chatId, opts.messageId, denialText);
+    return;
+  }
+  const reservedExpiresAtMs = investigateTailSlot.reserve(INVESTIGATE_TAIL_WINDOW_MS);
+  if (reservedExpiresAtMs === null) {
+    const remaining = formatCountdown(investigateTailSlot.remainingMs() / 1e3);
+    investigateAuditLog(
+      `not-started reason=tail-already-running sender=${redactId(opts.senderId ?? "unknown")} remaining=${remaining}`
+    );
+    emitAudit("not_started", "tail-already-running");
+    await sendInvestigateReply(
+      opts.chatId,
+      opts.messageId,
+      `\u23F3 A \`${investigateCmd}\` tail is already running for \`${AGENT_CODE_NAME}\` (one at a time) \u2014 it expires in ${remaining}.`
+    );
+    return;
+  }
+  const snapshot = await capturePaneSnapshot({
+    codeName: AGENT_CODE_NAME,
+    agentDir: TELEGRAM_AGENT_DIR
+  });
+  if (!snapshot) {
+    investigateTailSlot.release();
+    investigateAuditLog(`not-started reason=no-pane-output sender=${redactId(opts.senderId ?? "unknown")}`);
+    emitAudit("not_started", "no-pane-output");
+    await sendInvestigateReply(
+      opts.chatId,
+      opts.messageId,
+      `\u26A0\uFE0F No pane output available for \`${AGENT_CODE_NAME}\` yet \u2014 the agent session may not have started. (If the whole host is wedged, \`${investigateCmd}\` can't reach it either \u2014 fall back to the SSM diagnostics runbook.)`
+    );
+    return;
+  }
+  investigateAuditLog(`granted sender=${redactId(opts.senderId ?? "unknown")} \u2014 starting live tail (source=${snapshot.source})`);
+  emitAudit("granted", null);
+  const initialFrame = {
+    body: redactPaneText(snapshot.text),
+    source: snapshot.source,
+    capturedAtLabel: investigateNowUtcLabel()
+  };
+  let postedMessageId = null;
+  try {
+    const posted = await telegramApiCall(
+      "sendMessage",
+      {
+        chat_id: opts.chatId,
+        text: formatPaneSnapshot({
+          codeName: AGENT_CODE_NAME,
+          text: initialFrame.body,
+          source: initialFrame.source,
+          capturedAtLabel: initialFrame.capturedAtLabel,
+          status: {
+            kind: "live",
+            secondsRemaining: Math.max(0, Math.round((reservedExpiresAtMs - Date.now()) / 1e3))
+          },
+          maxChars: INVESTIGATE_MAX_CHARS,
+          commandName: investigateCmd
+        }),
+        parse_mode: "Markdown",
+        reply_to_message_id: Number(opts.messageId)
+      },
+      1e4
+    );
+    const result = posted.result;
+    if (posted.ok && typeof result?.message_id === "number") {
+      postedMessageId = result.message_id;
+    } else {
+      investigateAuditLog(`not-started reason=post-failed error=${posted.description ?? "unknown"}`);
+    }
+  } catch (err) {
+    investigateAuditLog(`not-started reason=post-failed error=${redactAugmentedPaths(err.message)}`);
+  }
+  if (postedMessageId === null) {
+    investigateTailSlot.release();
+    await sendInvestigateReply(
+      opts.chatId,
+      opts.messageId,
+      `\u274C Failed to post the pane snapshot. Try again in a moment.`
+    );
+    return;
+  }
+  void runInvestigateTailLoop({
+    chatId: opts.chatId,
+    messageId: postedMessageId,
+    initialFrame,
+    expiresAtMs: reservedExpiresAtMs
+  }).catch((err) => {
+    investigateTailSlot.release();
+    investigateAuditLog(`tail loop crashed: ${redactAugmentedPaths(err.message)}`);
+  });
+}
 var cachedBotUsername = null;
 var cachedBotId = null;
 async function refreshBotIdentity() {
@@ -17204,6 +17706,35 @@ async function pollLoop() {
             } catch (err) {
               process.stderr.write(
                 `telegram-channel(${AGENT_CODE_NAME}): /restart verification-failed ack send failed: ${redactAugmentedPaths(err.message)}
+`
+              );
+            }
+          }
+          continue;
+        }
+        if (isInvestigateSyntax(trimmedContent)) {
+          const disposition = await classifyInvestigateCommand(trimmedContent);
+          if (disposition === "act") {
+            await handleInvestigateCommand({
+              chatId,
+              messageId: String(msg.message_id),
+              chatType: msg.chat.type ?? null,
+              senderId: msg.from?.id != null ? String(msg.from.id) : null
+            });
+          } else if (disposition === "verification_failed") {
+            try {
+              await telegramApiCall(
+                "sendMessage",
+                {
+                  chat_id: chatId,
+                  text: `\u274C Couldn't verify the investigate target. Please retry in a few seconds.`,
+                  reply_to_message_id: Number(msg.message_id)
+                },
+                1e4
+              );
+            } catch (err) {
+              process.stderr.write(
+                `telegram-channel(${AGENT_CODE_NAME}): /investigate verification-failed ack send failed: ${redactAugmentedPaths(err.message)}
 `
               );
             }