switchroom 0.15.12 → 0.15.14

package/telegram-plugin/dist/server.js

@@ -24221,7 +24221,7 @@ async function main() {
     onStatus,
     log: (msg) => process.stderr.write(`telegram bridge: ipc: ${msg}
 `),
-    livenessFilePath: join5(STATE_DIR, ".bridge-alive")
+    livenessFilePath: process.env.SWITCHROOM_BRIDGE_ALIVE_PATH ?? join5(STATE_DIR, ".bridge-alive")
   });
   if (ipc.isConnected()) {
     process.stderr.write(`telegram bridge: connected to gateway at ${SOCKET_PATH}
@@ -24654,6 +24654,36 @@ var init_bridge = __esm(async () => {
         },
         required: ["agent_session_id", "type"]
       }
+    },
+    {
+      name: "linear_create_issue",
+      description: 'File a new Linear issue from a Telegram message the operator flagged for capture (#2312). Use this when a turn was triggered by a capture reaction (the inbound carries event="reaction" with a capture emoji like \uD83D\uDC68\u200d\uD83D\uDCBB or \uD83D\uDCCC) \u2014 turn the reacted message + any relevant thread context into a well-formed issue. Write a crisp imperative title and a body that captures the ask, the context, and any acceptance criteria you can infer; the agent files it AS its own Linear app actor. Team is auto-resolved when the workspace has a single team; if there are multiple it returns text asking for an explicit team_id. Pass dedup_key (e.g. the chat_id:message_id of the reacted message) so a re-react of the same message does not file a duplicate. Resolves the agent\'s Linear app token from the vault; on VAULT-BROKER-DENIED it returns text instructing you to vault_request_access for `linear/<agent>/token`. Returns "Filed: <title> \u2192 <url>" on success \u2014 reply that link to the operator in plain text.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: {
+            type: "string",
+            description: 'Issue title \u2014 a crisp, imperative one-liner (e.g. "Fix duplicate webhook retries on Brevo sync").'
+          },
+          body: {
+            type: "string",
+            description: "Issue description (Markdown). Capture the ask, relevant context from the message/thread, and any acceptance criteria you can infer."
+          },
+          team_id: {
+            type: "string",
+            description: "Optional Linear team id. Omit to auto-resolve when the workspace has a single team; required only when the workspace has multiple teams."
+          },
+          dedup_key: {
+            type: "string",
+            description: 'Optional idempotency key (use the reacted message identity, e.g. "<chat_id>:<message_id>"). A prior capture with the same key short-circuits to "Already filed: <url>".'
+          },
+          priority: {
+            type: "number",
+            description: "Optional Linear priority (0 none, 1 urgent, 2 high, 3 normal, 4 low)."
+          }
+        },
+        required: ["title", "body"]
+      }
     }
   ];
   mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_SCHEMAS }));

package/telegram-plugin/gateway/gateway.ts

@@ -363,6 +363,7 @@ import type {
   PtyPartialForward,
   InboundMessage,
   InjectInboundMessage,
+  SendOutboundMessage,
   QuotaWallDetectedMessage,
   PermissionEvent,
 } from './ipc-protocol.js'
@@ -420,6 +421,14 @@ import { startIssuesWatcher, type IssuesWatcherHandle } from '../issues-watcher.
 import { list as listIssues, resolve as resolveIssue } from '../../src/issues/index.js'
 import { formatPermissionCardBody, describeGrant, naturalAction, formatPermissionResumeMessage } from '../permission-title.js'
 import { resolveScopedAllowChoices, isRulePersisted } from '../permission-rule.js'
+import {
+  type ScopedGrantStore,
+  scopedApprovalTtlMs,
+  resolveTimeBox,
+  recordScopedGrant,
+  lookupScopedGrant,
+  sweepScopedGrants,
+} from '../scoped-approval.js'
 import { synthesizeAllowRuleDiff, extractAddedAllowRule } from '../permission-diff.js'
 import {
   readClaudeJsonOverage,
@@ -467,7 +476,7 @@ import {
   listGrantsViaBroker,
   revokeGrantViaBroker,
 } from '../../src/vault/broker/client.js'
-import { emitLinearAgentActivity } from './linear-activity.js'
+import { emitLinearAgentActivity, createLinearIssue } from './linear-activity.js'
 import {
   approvalRequest,
   approvalConsume,
@@ -3651,6 +3660,14 @@ function sweepStaleAlwaysAllowCorrelations(now = Date.now()): void {
   }
 }
 
+// "⏱ 30 min" scoped-approval store (the middle tier between Allow-once and
+// 🔁 Always). Operator-tapped, gateway-side ONLY (never pushed to the
+// bridge's untimed sessionAllowRules), fixed-window, fail-closed. Keyed by
+// agent name for per-agent isolation. All policy lives in
+// ../scoped-approval.ts (pure + unit-tested); this gateway only wires it.
+const scopedGrants: ScopedGrantStore = new Map()
+const selfAgentName = (): string => process.env.SWITCHROOM_AGENT_NAME ?? ''
+
 // `ask_user` MCP tool — open prompts awaiting a user button-tap.
 // Keyed by askId (8 hex chars from generateAskId). Each entry holds
 // the deferred promise that resolves the originating tool call, the
@@ -4246,6 +4263,9 @@ const pendingStateReaper = setInterval(() => {
   for (const [k, v] of vaultPassphraseCache) {
     if (now > v.expiresAt) vaultPassphraseCache.delete(k)
   }
+  // Drop expired "⏱ 30 min" scoped grants. (Lookup already fails closed on
+  // expiry; this just keeps the map from accumulating dead entries.)
+  sweepScopedGrants(scopedGrants, now)
   for (const [k, v] of deferredSecrets) {
     if (now - v.staged_at > DEFERRED_SECRET_TTL_MS) deferredSecrets.delete(k)
   }
@@ -5591,10 +5611,18 @@ const pendingPermissionBuffer = createPendingPermissionBuffer()
  * rebuilds this row. callback_data stays tiny (verb + 5-char id) so we
  * never approach Telegram's 64-byte ceiling.
  */
-function buildPermissionActionRow(requestId: string, showAlways: boolean): InlineKeyboard {
+function buildPermissionActionRow(
+  requestId: string,
+  showAlways: boolean,
+  showTimeBox = false,
+): InlineKeyboard {
   const kb = new InlineKeyboard()
     .text('❌ Deny', `perm:deny:${requestId}`)
     .text('✅ Allow once', `perm:allow:${requestId}`)
+  // "⏱ 30 min" sits between once and always. Only shown for a narrow,
+  // non-destructive scope (resolveTimeBox decides); broad/MCP/destructive
+  // requests get once/always only.
+  if (showTimeBox) kb.text('⏱ 30 min', `perm:tmb:${requestId}`)
   if (showAlways) kb.text('🔁 Always…', `perm:always:${requestId}`)
   return kb
 }
@@ -5978,6 +6006,32 @@ const ipcServer: IpcServer = createIpcServer({
 
   onPermissionRequest(_client: IpcClient, msg: PermissionRequestForward) {
     const { requestId, toolName, description, inputPreview } = msg
+    // "⏱ 30 min" short-circuit: if the operator tapped a live scoped grant
+    // covering this exact request, auto-allow without posting a card. CRITICAL:
+    // dispatch WITHOUT a `rule` so the bridge does NOT cache it untimed
+    // (sessionAllowRules has no TTL — a `rule` here would silently promote the
+    // 30-min window to session-forever). The fixed window lives only in
+    // scopedGrants. lookupScopedGrant fails closed on expiry and on a
+    // destructive Bash command matching a family grant. No card, no pending
+    // entry, no awaiting reaction — the turn just continues, silently.
+    const scopedTtl = scopedApprovalTtlMs()
+    if (scopedTtl > 0) {
+      const hit = lookupScopedGrant(scopedGrants, selfAgentName(), toolName, inputPreview, Date.now())
+      if (hit) {
+        // Silent auto-allow — no card was posted and the turn was never parked
+        // on the awaiting glyph, so we intentionally OMIT the resume-glyph flip
+        // and the agent-voiced resume message (posting "got it, continuing" on
+        // every auto-allowed call is the exact noise this tier removes). The
+        // `no-card-verdict` sentinel below exempts this callsite from the
+        // resume-guard pairing test.
+        dispatchPermissionVerdict({ type: 'permission', requestId, behavior: 'allow' }) // no-card-verdict
+        process.stderr.write(
+          `telegram gateway: scoped-approval auto-allow tool=${toolName} rule="${hit}" ` +
+          `request=${requestId} (time-boxed window)\n`,
+        )
+        return
+      }
+    }
     pendingPermissions.set(requestId, { tool_name: toolName, description, input_preview: inputPreview, startedAt: Date.now() })
     // Natural-language card body — a plain sentence ("Gymbro wants to
     // edit: supplement-log.md" + a why-line), never a raw tool id.
@@ -5996,8 +6050,13 @@ const ipcServer: IpcServer = createIpcServer({
     // any file ⚠️). The "🔁 Always…" button only appears when we can
     // synthesize a meaningful rule for this tool; unknown tools get the
     // two-button row only.
-    const showAlways = resolveScopedAllowChoices(toolName, inputPreview) != null
-    const keyboard = buildPermissionActionRow(requestId, showAlways)
+    const scopeChoices = resolveScopedAllowChoices(toolName, inputPreview)
+    const showAlways = scopeChoices != null
+    // Offer "⏱ 30 min" only for a narrow, non-destructive scope, and only
+    // when the tier is enabled (TTL > 0).
+    const showTimeBox = scopedApprovalTtlMs() > 0 &&
+      resolveTimeBox(toolName, inputPreview, scopeChoices) != null
+    const keyboard = buildPermissionActionRow(requestId, showAlways, showTimeBox)
     // Route the card to the SAME place the post-verdict resume message
     // lands (resolvePermissionCardTargets): the ORIGINATING chat+topic when
     // there's an active turn — so a supergroup agent's card appears IN the
@@ -6488,6 +6547,10 @@ const ipcServer: IpcServer = createIpcServer({
       process.stderr.write(
         `telegram gateway: cron fire fell back to main session (no cron bridge) agent=${msg.agentName} prompt_key=${promptKey}\n`,
       )
+      // #2307 Tier-1 observability: a climbing counter means the cron session is
+      // down (registered then died, or never came up) — the Tier-1 saving is
+      // lost for this fire. Surfaced via the unified runtime-metrics fan-out.
+      emitRuntimeMetric({ kind: 'cron_fell_back_to_main', agent: msg.agentName, prompt_key: promptKey })
     }
     // Status-silent (§2.4): a cron fire delivered to the CRON session must NOT
     // set the MAIN agent's currentTurn. But a fire that LANDED on the main
@@ -6506,6 +6569,47 @@ const ipcServer: IpcServer = createIpcServer({
     }
   },
 
+  // #2307 Tier-0 action tier — a MODEL-FREE outbound post. The agent-scheduler
+  // fires this for a `kind: action` `telegram-message`; the gateway posts the
+  // (already-substituted) text to the agent's OWN chat with NO model: no
+  // inject_inbound, no session wake, no currentTurn mutation. Two fences:
+  //   1. agentName must match this gateway's own SWITCHROOM_AGENT_NAME.
+  //   2. chatId must be an allowlisted chat for this agent (assertAllowedChat).
+  // An action carries no chat target of its own — the scheduler supplies the
+  // agent's own chat — so 2 is belt-and-braces against a malformed/foreign id.
+  onSendOutbound(_client: IpcClient, msg: SendOutboundMessage) {
+    const self = process.env.SWITCHROOM_AGENT_NAME
+    if (self && msg.agentName !== self) {
+      process.stderr.write(
+        `telegram gateway: send_outbound rejected — agent mismatch (${msg.agentName} != ${self})\n`,
+      )
+      return
+    }
+    try {
+      assertAllowedChat(msg.chatId)
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: send_outbound rejected — ${(err as Error).message}\n`,
+      )
+      return
+    }
+    const threadId = msg.threadId
+    const parseMode = msg.parseMode === 'text' ? undefined : 'HTML'
+    // allow-raw-bot-api: wrapped in swallowingApiCall (retry policy); thread-aware send.
+    // General topic (thread 1) sends omit message_thread_id per the outbound convention.
+    void swallowingApiCall(
+      () =>
+        bot.api.sendMessage(msg.chatId, msg.text, {
+          ...(parseMode ? { parse_mode: parseMode } : {}),
+          ...(threadId != null && threadId !== 1 ? { message_thread_id: threadId } : {}),
+        }),
+      { chat_id: msg.chatId, verb: 'cron-action-send', ...(threadId != null ? { threadId } : {}) },
+    )
+    process.stderr.write(
+      `telegram gateway: send_outbound agent=${msg.agentName} chat=${msg.chatId} thread=${threadId ?? '-'} len=${msg.text.length}\n`,
+    )
+  },
+
   // The wedge-watchdog detected claude's /rate-limit-options weekly-quota menu
   // (a TUI wall that never produced a 429, so the inference-path auto-fallback
   // never fired). Trigger the SAME fleet auto-fallback the 429 path uses,
@@ -6720,6 +6824,7 @@ const ALLOWED_TOOLS = new Set([
   'vault_request_access',
   'request_secret',
   'linear_agent_activity',
+  'linear_create_issue',
 ])
 
 async function executeToolCall(tool: string, args: Record<string, unknown>): Promise<unknown> {
@@ -6767,6 +6872,8 @@ async function executeToolCall(tool: string, args: Record<string, unknown>): Pro
       return executeRequestSecret(args)
     case 'linear_agent_activity':
       return executeLinearAgentActivity(args)
+    case 'linear_create_issue':
+      return executeLinearCreateIssue(args)
     default:
       throw new Error(`unknown tool: ${tool}`)
   }
@@ -6802,6 +6909,10 @@ async function executeLinearAgentActivity(args: Record<string, unknown>): Promis
   return emitLinearAgentActivity(args)
 }
 
+async function executeLinearCreateIssue(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
+  return createLinearIssue(args)
+}
+
 async function executeUpdateChecklist(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
   const chat_id = args.chat_id as string
   if (!chat_id) throw new Error('update_checklist: chat_id is required')
@@ -18962,7 +19073,7 @@ bot.on('callback_query:data', async ctx => {
   }
 
   // Permission request buttons.
-  const m = /^perm:(allow|deny|always|asn|asb|back):([a-km-z]{5})$/.exec(data)
+  const m = /^perm:(allow|deny|always|asn|asb|back|tmb):([a-km-z]{5})$/.exec(data)
   if (!m) { await ctx.answerCallbackQuery().catch(() => {}); return }
   const access = loadAccess()
   const senderId = String(ctx.from.id)
@@ -18977,7 +19088,10 @@ bot.on('callback_query:data', async ctx => {
     if (!details) { await ctx.answerCallbackQuery({ text: 'Details no longer available.' }).catch(() => {}); return }
     let keyboard: InlineKeyboard
     if (behavior === 'back') {
-      keyboard = buildPermissionActionRow(request_id, true)
+      const backChoices = resolveScopedAllowChoices(details.tool_name, details.input_preview)
+      const backTimeBox = scopedApprovalTtlMs() > 0 &&
+        resolveTimeBox(details.tool_name, details.input_preview, backChoices) != null
+      keyboard = buildPermissionActionRow(request_id, true, backTimeBox)
     } else {
       const choices = resolveScopedAllowChoices(details.tool_name, details.input_preview)
       if (choices == null) {
@@ -19201,6 +19315,55 @@ bot.on('callback_query:data', async ctx => {
     return
   }
 
+  // "⏱ 30 min" — record a fixed-window scoped grant for the NARROW scope,
+  // then allow the in-flight call. Mirrors the asn/asb structure: dispatch
+  // the verdict immediately, then edit the card. CRITICAL: the verdict
+  // carries NO `rule` (unlike asn/asb), so the bridge does not cache it
+  // untimed — the window lives only in scopedGrants, gateway-side.
+  if (behavior === 'tmb') {
+    const details = pendingPermissions.get(request_id)
+    if (!details) { await ctx.answerCallbackQuery({ text: 'Details no longer available.' }).catch(() => {}); return }
+    const ttl = scopedApprovalTtlMs()
+    if (ttl <= 0) { await ctx.answerCallbackQuery({ text: 'Time-boxed approvals are disabled.' }).catch(() => {}); return }
+    const choices = resolveScopedAllowChoices(details.tool_name, details.input_preview)
+    const tb = resolveTimeBox(details.tool_name, details.input_preview, choices)
+    if (!tb) { await ctx.answerCallbackQuery({ text: 'This action can\'t be time-boxed.' }).catch(() => {}); return }
+    const agentName = selfAgentName()
+    if (!agentName) { await ctx.answerCallbackQuery({ text: 'Time-box needs SWITCHROOM_AGENT_NAME — gateway is misconfigured.' }).catch(() => {}); return }
+
+    pendingPermissions.delete(request_id)
+    // (1) Allow the in-flight call NOW — no `rule` (keeps the window
+    // strictly gateway-side; the bridge must not cache it untimed).
+    dispatchPermissionVerdict({ type: 'permission', requestId: request_id, behavior: 'allow' })
+    // (2) Record the fixed-window grant so matching calls auto-allow.
+    recordScopedGrant(scopedGrants, agentName, tb.rule, Date.now(), ttl)
+    resumeReactionAfterVerdict()
+    postPermissionResumeMessage({
+      behavior: 'allow',
+      action: naturalAction(details.tool_name, details.input_preview),
+    })
+    process.stderr.write(
+      `telegram gateway: scoped-approval granted rule="${tb.rule}" agent=${agentName} ` +
+      `ttl_ms=${ttl} (request_id=${request_id})\n`,
+    )
+
+    const mins = Math.max(1, Math.round(ttl / 60_000))
+    // Honest card: state the real BREADTH (e.g. "any `git` command"), not
+    // just the rule, plus the window — consent covers both (access-model
+    // honest-card contract).
+    const sourceMsg = ctx.callbackQuery?.message
+    const baseText = sourceMsg && 'text' in sourceMsg && sourceMsg.text
+      ? escapeHtmlForTg(sourceMsg.text)
+      : ''
+    const editLabel = `⏱ <b>Allowed for ${mins} min — ${escapeHtmlForTg(tb.breadth)}</b> · re-asks after that, and now for anything else`
+    await finalizeCallback(ctx, {
+      ackText: `⏱ Allowed for ${mins} min`.slice(0, 200),
+      newText: baseText ? `${baseText}\n\n${editLabel}` : editLabel,
+      parseMode: 'HTML',
+    })
+    return
+  }
+
   // Forward permission decision to connected bridges. Capture the work
   // phrase BEFORE deleting the pending entry — postPermissionResumeMessage
   // (fired in synthInbound below) names the resumed work.

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -413,6 +413,35 @@ export interface QuotaWallDetectedMessage {
   resetAt?: number;
 }
 
+/**
+ * #2307 (Tier-0 action tier) — a MODEL-FREE outbound post. Sent by the
+ * in-agent scheduler when a `kind: action` cron's `telegram-message` fires:
+ * the gateway posts `text` to the agent's OWN chat with no model involvement
+ * (NO `inject_inbound`, NO session wake, NO `currentTurn` mutation). This is
+ * the deliberate counterpart to `inject_inbound` — the one ClientToGateway
+ * verb that produces an outbound WITHOUT a turn.
+ *
+ * Trust model: same as `inject_inbound` — the socket is per-agent inside the
+ * container, only that-UID processes can connect. `agentName` is validated
+ * server-side, and the gateway FENCES `chatId` to the agent's own configured
+ * chat (DM allowlist / forum_chat_id) and rejects a foreign chat — an action
+ * can never post elsewhere (the action spec carries no chat target; the
+ * scheduler supplies the agent's own).
+ */
+export interface SendOutboundMessage {
+  type: "send_outbound";
+  /** Target agent — gateway verifies it matches its own SWITCHROOM_AGENT_NAME. */
+  agentName: string;
+  /** Agent's own chat id (fenced server-side against the agent's config). */
+  chatId: string;
+  /** Forum topic thread id (General/unset omitted; 1 is stripped on send). */
+  threadId?: number;
+  /** Message body — already substitution-resolved by the action engine. */
+  text: string;
+  /** Telegram parse mode. Defaults to HTML. */
+  parseMode?: "html" | "text";
+}
+
 export type ClientToGateway =
   | RegisterMessage
   | ToolCallMessage
@@ -428,4 +457,5 @@ export type ClientToGateway =
   | RequestMs365ApprovalMessage
   | RequestConfigApprovalMessage
   | RequestConfigFinalizeMessage
-  | QuotaWallDetectedMessage;
+  | QuotaWallDetectedMessage
+  | SendOutboundMessage;

package/telegram-plugin/gateway/ipc-server.ts

@@ -4,6 +4,7 @@ import type {
   GatewayToClient,
   HeartbeatMessage,
   InjectInboundMessage,
+  SendOutboundMessage,
   QuotaWallDetectedMessage,
   OperatorEventForward,
   PermissionRequestForward,
@@ -45,6 +46,15 @@ export interface IpcServerOptions {
    * inline scheduler simply ignore inject_inbound messages.
    */
   onInjectInbound?: (client: IpcClient, msg: InjectInboundMessage) => void;
+  /**
+   * #2307 Tier-0 action tier — a model-free outbound post. Invoked when the
+   * agent-scheduler sibling fires a `kind: action` `telegram-message`. The
+   * handler is expected to post `msg.text` to `msg.chatId` (fenced to the
+   * agent's own chat) via the locked bot — with NO model, NO inject_inbound,
+   * NO session wake. Optional: gateways that don't run the inline scheduler
+   * ignore it.
+   */
+  onSendOutbound?: (client: IpcClient, msg: SendOutboundMessage) => void;
   /**
    * The autoaccept-poll wedge-watchdog detected claude's `/rate-limit-options`
    * weekly-quota menu (no 429 ever reached the gateway). Handler is expected to
@@ -246,6 +256,21 @@ export function validateClientMessage(msg: unknown): msg is ClientToGateway {
         && typeof inb.meta === "object"
         && inb.meta !== null;
     }
+    case "send_outbound": {
+      // #2307 Tier-0 action tier — a model-free outbound post. Validate the
+      // wire shape; the gateway handler fences chatId to the agent's own chat.
+      if (typeof m.agentName !== "string"
+        || !AGENT_NAME_RE.test(m.agentName as string)) return false;
+      if (typeof m.chatId !== "string" || (m.chatId as string).length === 0) return false;
+      // text non-empty and bounded — Telegram caps a message at 4096 chars;
+      // reject over-long here (defense in depth against a malformed payload).
+      if (typeof m.text !== "string" || (m.text as string).length === 0
+        || (m.text as string).length > 4096) return false;
+      if (m.threadId !== undefined
+        && (typeof m.threadId !== "number" || !Number.isInteger(m.threadId as number))) return false;
+      if (m.parseMode !== undefined && m.parseMode !== "html" && m.parseMode !== "text") return false;
+      return true;
+    }
     case "quota_wall_detected": {
       // wedge-watchdog detected the /rate-limit-options weekly-quota menu.
       if (typeof m.agentName !== "string"
@@ -335,6 +360,7 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     onOperatorEvent,
     onPtyPartial,
     onInjectInbound,
+    onSendOutbound,
     onQuotaWallDetected,
     onRequestDriveApproval,
     onRequestMs365Approval,
@@ -444,6 +470,9 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
       case "inject_inbound":
         if (onInjectInbound) onInjectInbound(client, msg as InjectInboundMessage);
         break;
+      case "send_outbound":
+        if (onSendOutbound) onSendOutbound(client, msg as SendOutboundMessage);
+        break;
       case "quota_wall_detected":
         if (onQuotaWallDetected) onQuotaWallDetected(client, msg as QuotaWallDetectedMessage);
         break;

package/telegram-plugin/gateway/linear-activity.ts

@@ -33,6 +33,9 @@ export interface LinearActivityDeps {
   fetchImpl?: typeof fetch
   /** Agent slug (defaults to SWITCHROOM_AGENT_NAME). */
   agent?: string
+  /** Default Linear team id for captured issues (multi-team workspaces);
+   *  defaults to SWITCHROOM_LINEAR_DEFAULT_TEAM_ID. Tests inject directly. */
+  defaultTeamId?: string
   /** Log sink — stderr in production. */
   log?: (line: string) => void
 }
@@ -158,3 +161,145 @@ export async function emitLinearAgentActivity(
   log(`telegram gateway: linear_agent_activity: emitted type=${type} session=${sessionId} agent=${agent}\n`)
   return { content: [{ type: 'text', text: `Linear ${type} emitted on session ${sessionId}` }] }
 }
+
+/** Hidden marker appended to a captured issue's description so a re-capture of
+ *  the same Telegram message can be detected (dedup backstop; the gateway-side
+ *  seen-set is the primary, race-free guard). */
+export function captureDedupMarker(dedupKey: string): string {
+  return `\n\n<!-- switchroom-capture: ${dedupKey} -->`
+}
+
+/**
+ * Create a Linear issue (capture-on-reaction → Linear). Mirrors
+ * emitLinearAgentActivity: validates, resolves the agent's Linear app token,
+ * POSTs `issueCreate`, returns an MCP text result; never throws on vault/
+ * network failure. The issue is filed AS the agent's app actor.
+ *
+ * Team: Linear requires a teamId. If `team_id` is omitted we auto-resolve —
+ * the zero-config single-team case uses the workspace's only team; a
+ * multi-team workspace returns actionable text asking for an explicit team_id.
+ *
+ * Dedup: when `dedup_key` is given we (a) best-effort search for a prior
+ * capture carrying the same marker and short-circuit to "already filed", and
+ * (b) embed the marker in the new issue's description as a durable backstop.
+ */
+export async function createLinearIssue(
+  args: Record<string, unknown>,
+  deps: LinearActivityDeps = {},
+): Promise<ToolTextResult> {
+  const log = deps.log ?? ((s) => process.stderr.write(s))
+  const fetchImpl = deps.fetchImpl ?? fetch
+
+  const title = args.title as string | undefined
+  if (!title || title.trim() === '') throw new Error('linear_create_issue: title is required')
+  const body = (args.body as string | undefined) ?? ''
+  // Explicit team_id wins; otherwise the operator's configured default team
+  // (scaffold injects SWITCHROOM_LINEAR_DEFAULT_TEAM_ID for multi-team
+  // workspaces); otherwise we auto-resolve below (zero-config single team).
+  const teamIdArg =
+    (args.team_id as string | undefined) ??
+    (deps.defaultTeamId ?? process.env.SWITCHROOM_LINEAR_DEFAULT_TEAM_ID) ??
+    undefined
+  const dedupKey = (args.dedup_key as string | undefined) ?? undefined
+  const priority = typeof args.priority === 'number' ? (args.priority as number) : undefined
+
+  const agent = deps.agent ?? process.env.SWITCHROOM_AGENT_NAME ?? '-'
+  const resolveToken = deps.resolveToken ?? defaultResolveLinearToken
+  const tokenResult = await resolveToken(agent)
+  if (!tokenResult.ok) {
+    const hint =
+      tokenResult.reason === 'denied' || tokenResult.reason === 'not_found'
+        ? ` Call vault_request_access for key 'linear/${agent}/token' (scope read), then retry.`
+        : ''
+    return {
+      content: [
+        { type: 'text', text: `Couldn't file to Linear: no token (vault ${tokenResult.reason}).${hint}` },
+      ],
+    }
+  }
+  const token = tokenResult.token
+
+  const gql = async (query: string, variables: Record<string, unknown>): Promise<{ ok: true; data: any } | { ok: false; text: string }> => {
+    let resp: Response
+    try {
+      resp = await fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: token },
+        body: JSON.stringify({ query, variables }),
+      })
+    } catch (err) {
+      return { ok: false, text: `request error: ${(err as Error).message}` }
+    }
+    if (!resp.ok) {
+      const txt = await resp.text().catch(() => '')
+      return { ok: false, text: `Linear API ${resp.status}${txt ? ` — ${txt.slice(0, 200)}` : ''}` }
+    }
+    let json: { data?: any; errors?: Array<{ message?: string }> }
+    try {
+      json = (await resp.json()) as typeof json
+    } catch {
+      return { ok: false, text: 'malformed Linear API response' }
+    }
+    if (json.errors && json.errors.length > 0) {
+      return { ok: false, text: json.errors.map((e) => e.message ?? 'error').join('; ').slice(0, 300) }
+    }
+    return { ok: true, data: json.data }
+  }
+
+  // Dedup backstop: search for a prior capture of the same Telegram message.
+  if (dedupKey) {
+    const search = await gql(
+      'query($term: String!) { searchIssues(term: $term) { nodes { id url title } } }',
+      { term: dedupKey },
+    )
+    if (search.ok) {
+      const hit = (search.data?.searchIssues?.nodes ?? [])[0] as { url?: string } | undefined
+      if (hit?.url) {
+        log(`telegram gateway: linear_create_issue: dedup hit key=${dedupKey} agent=${agent}\n`)
+        return { content: [{ type: 'text', text: `Already filed: ${hit.url}` }] }
+      }
+    }
+    // a failed search is non-fatal — fall through to create (gateway seen-set is primary).
+  }
+
+  // Resolve the team.
+  let teamId = teamIdArg
+  if (!teamId) {
+    const teams = await gql('query { teams(first: 50) { nodes { id key name } } }', {})
+    if (!teams.ok) {
+      return { content: [{ type: 'text', text: `Couldn't file to Linear: ${teams.text}` }] }
+    }
+    const nodes = (teams.data?.teams?.nodes ?? []) as Array<{ id: string; key: string; name: string }>
+    if (nodes.length === 0) {
+      return { content: [{ type: 'text', text: 'Couldn\'t file to Linear: the workspace has no teams.' }] }
+    }
+    if (nodes.length > 1) {
+      const list = nodes.map((t) => `${t.key} (${t.name})`).join(', ')
+      return {
+        content: [
+          { type: 'text', text: `Couldn't file to Linear: multiple teams (${list}) — set a default team (linear_agent.default_team_id) or pass team_id.` },
+        ],
+      }
+    }
+    teamId = nodes[0].id
+  }
+
+  const description = dedupKey ? `${body}${captureDedupMarker(dedupKey)}` : body
+  const input: Record<string, unknown> = { teamId, title, description }
+  if (priority !== undefined) input.priority = priority
+
+  const create = await gql(
+    'mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier url } } }',
+    { input },
+  )
+  if (!create.ok) {
+    return { content: [{ type: 'text', text: `Couldn't file to Linear: ${create.text}` }] }
+  }
+  const issue = create.data?.issueCreate?.issue as { identifier?: string; url?: string } | undefined
+  if (create.data?.issueCreate?.success === false || !issue?.url) {
+    return { content: [{ type: 'text', text: 'Couldn\'t file to Linear: issue not created (success=false).' }] }
+  }
+
+  log(`telegram gateway: linear_create_issue: filed ${issue.identifier} agent=${agent}${dedupKey ? ` dedup=${dedupKey}` : ''}\n`)
+  return { content: [{ type: 'text', text: `Filed: ${title} → ${issue.url}` }] }
+}

package/telegram-plugin/runtime-metrics.ts

@@ -137,6 +137,20 @@ export type RuntimeMetricEvent =
       // executeReply scrub site. The two new sites close that gap.
       site: 'reply' | 'edit_message' | 'progress_update' | 'answer_stream' | 'stream_reply' | 'turn_flush'
     }
+  /**
+   * #2307 Tier-1: a cron fire routed to the `<agent>-cron` cheap session
+   * (meta.session=cron) fell back to the MAIN session because the cron bridge
+   * wasn't registered (wedged boot, crashed session, or hot-added cron with no
+   * live session yet). Each occurrence means the Tier-1 saving was NOT realised
+   * for that fire — a climbing counter is the runtime signal that a cron
+   * session is down (the doctor check catches a permanently-wedged one at boot;
+   * this catches a session that registered then died).
+   */
+  | {
+      kind: 'cron_fell_back_to_main'
+      agent: string
+      prompt_key: string
+    }
 
 /**
  * The JSONL sink lives under the runtime state dir so it's per-agent