switchroom 0.15.12 → 0.15.13

package/telegram-plugin/dist/server.js

@@ -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

@@ -420,6 +420,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 +475,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 +3659,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 +4262,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 +5610,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 +6005,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 +6049,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
@@ -6720,6 +6778,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 +6826,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 +6863,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 +19027,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 +19042,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 +19269,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/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/scoped-approval.ts

@@ -0,0 +1,253 @@
+/**
+ * Scoped, time-boxed approval — the "⏱ 30 min" tier, the middle rung
+ * between "✅ Allow once" (re-prompts on the very next call) and
+ * "🔁 Always…" (a durable `tools.allow` write that lasts forever). After
+ * the operator taps "⏱ 30 min" on a permission card, byte-identical
+ * in-scope requests auto-allow for a fixed window without re-carding.
+ *
+ * Design contract (reference/access-model.md — "you hold the leash"):
+ *
+ *  - **Operator-authored only.** Every cache entry is created by an
+ *    `allowFrom`-authenticated Telegram tap. No tool call can seed an
+ *    entry (first contact always cards) or extend one (the window is a
+ *    FIXED box — `recordScopedGrant` sets `expiresAt` once; a matching
+ *    request never moves it). So an agent can never author its own
+ *    authorization.
+ *  - **Gateway-side only.** This store lives in the gateway process. It
+ *    must NOT be pushed down to the bridge's `sessionAllowRules`
+ *    (`bridge.ts`) — that cache is agent-uid, untimed, and would silently
+ *    promote a 30-min grant to session-forever. The gateway dispatches
+ *    the in-flight allow WITHOUT the `rule` field for exactly this reason.
+ *  - **Conservative scope (this tier, v1).** Only the *narrow* scope is
+ *    ever time-boxed: an exact file path (`Edit(/x.ts)`) or a Bash
+ *    command-family (`Bash(git:*)`). Broad scopes ("any file", resource-
+ *    blind MCP, "any command") are NOT offered the ⏱ button — they stay
+ *    once / always. This covers the real fatigue (re-editing the same
+ *    file, re-running a safe command) without fanning one tap across an
+ *    unbounded action set.
+ *  - **Fail-closed on irreversible.** A Bash family grant (`Bash(git:*)`)
+ *    must never auto-allow a destructive member of that family
+ *    (`git push --force`, `git reset --hard`). `isDestructiveBashCommand`
+ *    is re-checked at BOTH grant time (don't offer ⏱) and match time
+ *    (a cached family grant fails closed → re-cards) so per-call consent
+ *    for irreversible actions is preserved.
+ *
+ * Pure + side-effect-free so it unit-tests under vitest AND bun without a
+ * Grammy context (mirrors permission-rule.ts). Callers pass `now`/`ttlMs`
+ * explicitly; nothing reads the clock here.
+ */
+
+import { basename } from "node:path";
+import { matchesAllowRule, type ScopedAllowChoices } from "./permission-rule.js";
+
+/** Default time-box window: 30 minutes. */
+export const SCOPED_APPROVAL_DEFAULT_TTL_MS = 30 * 60 * 1000;
+
+/**
+ * Resolve the configured window from the environment. `0` (or negative)
+ * disables the tier — the gateway hides the ⏱ button and never
+ * short-circuits. A blank/garbage value falls back to the 30-min default.
+ * Kill-switch: `SWITCHROOM_SCOPED_APPROVAL_TTL_MS=0`.
+ */
+export function scopedApprovalTtlMs(
+  env: Record<string, string | undefined> = process.env,
+): number {
+  const raw = env.SWITCHROOM_SCOPED_APPROVAL_TTL_MS;
+  if (raw === undefined || raw.trim() === "") return SCOPED_APPROVAL_DEFAULT_TTL_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return SCOPED_APPROVAL_DEFAULT_TTL_MS;
+  return Math.floor(n);
+}
+
+/** A single operator-tapped, time-boxed grant. */
+export interface ScopedGrant {
+  /** Narrow allow-rule, e.g. `Edit(/state/x.ts)` or `Bash(git:*)`. */
+  readonly rule: string;
+  /** Unix-ms when this grant stops auto-allowing. Fixed at grant time. */
+  readonly expiresAt: number;
+}
+
+/** Per-agent store of live time-boxed grants. Keyed by agent name. */
+export type ScopedGrantStore = Map<string, ScopedGrant[]>;
+
+/** The narrow rule + an honest operator-facing breadth phrase for the card. */
+export interface TimeBoxDecision {
+  readonly rule: string;
+  /** e.g. "edits to x.ts" / "any `git` command" — states the real breadth. */
+  readonly breadth: string;
+}
+
+const FILE_RULE = /^(Edit|Write|MultiEdit|NotebookEdit|Read)\((.+)\)$/;
+const BASH_FAMILY_RULE = /^Bash\(([^:]+):\*\)$/;
+
+/**
+ * Conservative time-box eligibility. Given the already-resolved scope
+ * choices for a permission request, return the NARROW rule to time-box
+ * plus an honest breadth phrase — or `null` when this request must not
+ * get a ⏱ button (broad-only tools, MCP, Skill, a destructive Bash
+ * command, or any tool with no narrow sub-scope).
+ *
+ *  - File tools with an exact path → time-boxable (bounded to the one
+ *    operator-seen file).
+ *  - Bash with a first-token family → time-boxable ONLY when the
+ *    triggering command itself is non-destructive. The family grant
+ *    still covers the whole `<tok>` family for matching, but match-time
+ *    re-checks each later command (see `lookupScopedGrant`).
+ */
+export function resolveTimeBox(
+  toolName: string,
+  inputPreview: string | undefined,
+  choices: ScopedAllowChoices | null,
+): TimeBoxDecision | null {
+  // Only ever time-box the narrow scope, and only when one exists.
+  const specific = choices?.specific;
+  if (!specific || specific.broad) return null;
+  const rule = specific.rule;
+
+  const fileMatch = FILE_RULE.exec(rule);
+  if (fileMatch) {
+    const verb = fileMatch[1] === "Read" ? "reads of" : "edits to";
+    return { rule, breadth: `${verb} ${basename(fileMatch[2]!)}` };
+  }
+
+  const bashMatch = BASH_FAMILY_RULE.exec(rule);
+  if (bashMatch) {
+    const cmd = readBashCommand(inputPreview);
+    // No command text to vet, or a destructive triggering command → don't
+    // offer the time-box at all (fall through to once / always).
+    if (!cmd || isDestructiveBashCommand(cmd)) return null;
+    return { rule, breadth: `any \`${bashMatch[1]}\` command` };
+  }
+
+  // MCP (resource-blind), Skill, broad-only tools → not time-boxed in the
+  // conservative tier.
+  return null;
+}
+
+/**
+ * Record an operator-tapped 30-min grant. The window is a FIXED box: a
+ * re-tap on the same rule resets it (the operator just re-approved), but
+ * nothing else ever moves `expiresAt`. Re-tapping the same rule replaces
+ * the prior entry rather than accumulating duplicates. A non-positive
+ * `ttlMs` is a no-op (tier disabled).
+ */
+export function recordScopedGrant(
+  store: ScopedGrantStore,
+  agent: string,
+  rule: string,
+  now: number,
+  ttlMs: number,
+): void {
+  if (ttlMs <= 0) return;
+  const list = store.get(agent) ?? [];
+  const others = list.filter((g) => g.rule !== rule);
+  others.push({ rule, expiresAt: now + ttlMs });
+  store.set(agent, others);
+}
+
+/**
+ * Is there a LIVE operator-tapped grant covering this request? Returns the
+ * matching rule (for the audit log line) or `null`.
+ *
+ * FAIL-CLOSED in two ways:
+ *   1. an expired grant never matches (→ re-card);
+ *   2. a destructive Bash command never auto-allows even when its family
+ *      grant (`Bash(git:*)`) matches — `git push --force` re-cards even
+ *      after `git status` was time-boxed.
+ *
+ * Never mutates the store (no window-sliding). Pure read.
+ */
+export function lookupScopedGrant(
+  store: ScopedGrantStore,
+  agent: string,
+  toolName: string,
+  inputPreview: string | undefined,
+  now: number,
+): string | null {
+  const list = store.get(agent);
+  if (!list || list.length === 0) return null;
+  for (const g of list) {
+    if (g.expiresAt <= now) continue; // expired → fail closed
+    if (!matchesAllowRule(g.rule, toolName, inputPreview)) continue;
+    if (toolName === "Bash") {
+      const cmd = readBashCommand(inputPreview);
+      // Family grant matched, but re-vet THIS command: destructive or
+      // un-vettable → fail closed, re-card.
+      if (!cmd || isDestructiveBashCommand(cmd)) return null;
+    }
+    return g.rule;
+  }
+  return null;
+}
+
+/** Drop expired grants. Call from the gateway's periodic sweep. */
+export function sweepScopedGrants(store: ScopedGrantStore, now: number): void {
+  for (const [agent, list] of store) {
+    const live = list.filter((g) => g.expiresAt > now);
+    if (live.length === 0) store.delete(agent);
+    else if (live.length !== list.length) store.set(agent, live);
+  }
+}
+
+/**
+ * Heuristic destructive/irreversible-command detector. FAIL-CLOSED: when
+ * a command can't be read or looks risky, return `true` so it is never
+ * time-boxed (it re-prompts instead). Better to re-card a safe command
+ * than auto-allow a destructive one. Covers the access-model crown-jewel
+ * cases that ride the tool-permission channel: pipe-to-shell, privilege
+ * escalation, destructive coreutils/disk ops, recursive perms, device
+ * redirects, destructive git, power/process control, and bulk
+ * docker/package teardown.
+ */
+export function isDestructiveBashCommand(command: string): boolean {
+  if (!command || !command.trim()) return true;
+  const c = command.toLowerCase();
+
+  // Backtick command substitution is un-vettable: the destructive op can
+  // hide inside `…` where the command-position anchors below (which include
+  // `$(` but not the backtick) would miss it — e.g. `git status \`rm -rf x\``
+  // matches the `Bash(git:*)` family but its first token is the harmless
+  // `git`. There is no need to time-box a backtick-substituted command, so
+  // fail closed (re-card). `$(…)` substitution stays handled by the `(`
+  // anchor in the rules below.
+  if (c.includes("`")) return true;
+
+  // download-and-execute: ... | sh|bash|python|node
+  if (/\|\s*(sudo\s+)?(sh|bash|zsh|fish|python\d?|perl|ruby|node)\b/.test(c)) return true;
+  // privilege escalation
+  if (/(^|\s|;|&&|\|\||\()sudo\b/.test(c)) return true;
+  if (/(^|\s|;|&&|\|\||\()(su|doas)\s/.test(c)) return true;
+  // destructive coreutils / disk
+  if (/(^|\s|;|&&|\|\||\()(rm|rmdir|dd|shred|truncate|fdisk|mkfs\S*|wipefs|blkdiscard|fallocate)\b/.test(c)) return true;
+  // recursive permission / ownership changes (-R / --recursive)
+  if (/\b(chmod|chown|chgrp)\b[^|;&]*(\s-(-recursive|[a-z]*r[a-z]*)\b)/.test(c)) return true;
+  // redirection clobbering devices or system dirs
+  if (/>\s*\/(dev|etc|boot|sys|proc)\b/.test(c)) return true;
+  // destructive git
+  if (/\bgit\b/.test(c) &&
+      /(push\b[^|;&]*(--force|-f\b|--force-with-lease)|push\s+[^\s]*\s+\+|reset\s+--hard|clean\s+-[a-z]*[fd]|filter-branch|reflog\s+expire|update-ref\s+-d|branch\s+-d{1,2}\b|checkout\s+--\s|restore\b)/.test(c)) return true;
+  // power / process control
+  if (/(^|\s|;|&&|\|\||\()(shutdown|reboot|halt|poweroff|kill|killall|pkill)\b/.test(c)) return true;
+  if (/(^|\s)init\s+0\b/.test(c)) return true;
+  // bulk docker teardown / package removal
+  if (/\bdocker\b[^|;&]*\b(rm|prune)\b/.test(c)) return true;
+  if (/(^|\s)(apt|apt-get|yum|dnf|brew|pacman|npm|pnpm|yarn|pip\d?)\b[^|;&]*\b(remove|uninstall|purge|prune)\b/.test(c)) return true;
+  // fork bomb
+  if (/:\s*\(\s*\)\s*\{/.test(c)) return true;
+
+  return false;
+}
+
+/** Extract the `command` string from a permission_request input preview. */
+function readBashCommand(inputPreview: string | undefined): string | null {
+  if (!inputPreview || typeof inputPreview !== "string") return null;
+  const trimmed = inputPreview.trim();
+  if (!trimmed.startsWith("{")) return null;
+  try {
+    const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+    const cmd = parsed?.command;
+    return typeof cmd === "string" && cmd.length > 0 ? cmd : null;
+  } catch {
+    return null;
+  }
+}

package/telegram-plugin/tests/linear-agent-activity.test.ts

@@ -51,7 +51,7 @@ describe('linear_agent_activity — gateway wiring (#2298)', () => {
   })
 
   it('is allow-listed and dispatched', () => {
-    expect(gw).toMatch(/'linear_agent_activity',\n\]\)/)
+    expect(gw).toMatch(/'linear_agent_activity',/)
     expect(gw).toMatch(/case 'linear_agent_activity':\s*\n\s*return executeLinearAgentActivity\(args\)/)
   })
 })