switchroom 0.15.11 → 0.15.13

package/telegram-plugin/dist/server.js

@@ -24631,6 +24631,59 @@ var init_bridge = __esm(async () => {
         },
         required: ["chat_id", "key"]
       }
+    },
+    {
+      name: "linear_agent_activity",
+      description: 'Emit a structured Linear AgentActivity against an agent session (#2298). Use this ONLY inside a turn that was woken by a Linear agent session (the inbound carries meta.source="linear" and meta.agent_session_id) \u2014 pass that agent_session_id back here. Linear renders activities as status chips + a timeline on the issue, so the human sees acknowledge \u2192 work \u2192 result. Emit a `thought` within ~10s of being woken so the session does not look dead, then `message`(s) as you make progress, and finally exactly one terminal `complete` (work done) or `error` (you could not proceed). body is required for thought/message/error and optional for complete. Resolves the agent\'s Linear app token from the vault; on VAULT-BROKER-DENIED it returns an error instructing you to vault_request_access for `linear/<agent>/token`.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          agent_session_id: {
+            type: "string",
+            description: "The Linear AgentSession id \u2014 copy it verbatim from the woken turn's meta.agent_session_id."
+          },
+          type: {
+            type: "string",
+            enum: ["thought", "message", "complete", "error"],
+            description: "Activity kind. thought = visible reasoning ack (emit within ~10s); message = progress update; complete = terminal success; error = terminal failure."
+          },
+          body: {
+            type: "string",
+            description: "Activity text (Markdown). Required for thought/message/error; optional for complete (a closing summary)."
+          }
+        },
+        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,6 +475,7 @@ import {
   listGrantsViaBroker,
   revokeGrantViaBroker,
 } from '../../src/vault/broker/client.js'
+import { emitLinearAgentActivity, createLinearIssue } from './linear-activity.js'
 import {
   approvalRequest,
   approvalConsume,
@@ -3650,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
@@ -4245,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)
   }
@@ -5590,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
 }
@@ -5977,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.
@@ -5995,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
@@ -6718,6 +6777,8 @@ const ALLOWED_TOOLS = new Set([
   'vault_request_save',
   'vault_request_access',
   'request_secret',
+  'linear_agent_activity',
+  'linear_create_issue',
 ])
 
 async function executeToolCall(tool: string, args: Record<string, unknown>): Promise<unknown> {
@@ -6763,6 +6824,10 @@ async function executeToolCall(tool: string, args: Record<string, unknown>): Pro
       return executeVaultRequestAccess(args)
     case 'request_secret':
       return executeRequestSecret(args)
+    case 'linear_agent_activity':
+      return executeLinearAgentActivity(args)
+    case 'linear_create_issue':
+      return executeLinearCreateIssue(args)
     default:
       throw new Error(`unknown tool: ${tool}`)
   }
@@ -6794,6 +6859,14 @@ async function executeSendChecklist(args: Record<string, unknown>): Promise<{ co
   return { content: [{ type: 'text', text: `checklist sent (id: ${sent.message_id})` }] }
 }
 
+async function executeLinearAgentActivity(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
+  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')
@@ -18954,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)
@@ -18969,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) {
@@ -19193,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

@@ -0,0 +1,305 @@
+/**
+ * Linear AgentActivity emission (#2298).
+ *
+ * The `linear_agent_activity` MCP tool lets an agent that was woken by a
+ * Linear agent session respond with structured activities (thought /
+ * message / complete / error) that Linear renders as status chips + a
+ * timeline on the issue. This module owns the pure logic — token
+ * resolution + the `agentActivityCreate` GraphQL POST — behind injectable
+ * deps so it is testable without a vault broker or the network. The
+ * gateway wires it into `executeToolCall`.
+ *
+ * The agent's Linear app token is resolved from the vault under
+ * `linear/<agent>/token` via the broker (never an inline literal, never an
+ * env file). On a vault denial the tool returns actionable text telling the
+ * agent to `vault_request_access` for that key rather than failing opaquely.
+ */
+
+import {
+  getViaBrokerStructured,
+  readVaultTokenFile,
+} from '../../src/vault/broker/client.js'
+
+export const LINEAR_GRAPHQL_ENDPOINT = 'https://api.linear.app/graphql'
+
+export type LinearTokenResult =
+  | { ok: true; token: string }
+  | { ok: false; reason: 'denied' | 'unreachable' | 'not_found' | 'unknown' }
+
+export interface LinearActivityDeps {
+  /** Resolve the Linear app token for `agent` from the vault. */
+  resolveToken?: (agent: string) => Promise<LinearTokenResult>
+  /** Injectable fetch (tests). */
+  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
+}
+
+export type ToolTextResult = { content: Array<{ type: string; text: string }> }
+
+/** Default token resolver: vault broker get on `linear/<agent>/token`. */
+export async function defaultResolveLinearToken(agent: string): Promise<LinearTokenResult> {
+  const key = `linear/${agent}/token`
+  const token = readVaultTokenFile(agent) ?? undefined
+  const result = await getViaBrokerStructured(key, token ? { token } : {})
+  if (result.kind === 'ok' && result.entry.kind === 'string') {
+    return { ok: true, token: result.entry.value }
+  }
+  if (result.kind === 'unreachable') return { ok: false, reason: 'unreachable' }
+  if (result.kind === 'not_found') return { ok: false, reason: 'not_found' }
+  if (result.kind === 'denied') return { ok: false, reason: 'denied' }
+  return { ok: false, reason: 'unknown' }
+}
+
+/**
+ * Emit a Linear AgentActivity. Validates args, resolves the token, POSTs
+ * the `agentActivityCreate` mutation, and returns an MCP text result. Never
+ * throws on a vault/network failure — returns actionable error text so the
+ * agent can recover (e.g. via vault_request_access).
+ */
+export async function emitLinearAgentActivity(
+  args: Record<string, unknown>,
+  deps: LinearActivityDeps = {},
+): Promise<ToolTextResult> {
+  const log = deps.log ?? ((s) => process.stderr.write(s))
+
+  const sessionId = args.agent_session_id as string | undefined
+  if (!sessionId) throw new Error('linear_agent_activity: agent_session_id is required')
+  const type = args.type as string | undefined
+  if (!type || !['thought', 'message', 'complete', 'error'].includes(type)) {
+    throw new Error('linear_agent_activity: type must be one of thought|message|complete|error')
+  }
+  const body = args.body as string | undefined
+  if (type !== 'complete' && (body == null || body === '')) {
+    throw new Error(`linear_agent_activity: body is required for type='${type}'`)
+  }
+
+  const agent = deps.agent ?? process.env.SWITCHROOM_AGENT_NAME ?? '-'
+  const resolveToken = deps.resolveToken ?? defaultResolveLinearToken
+  const tokenResult = await resolveToken(agent)
+  if (!tokenResult.ok) {
+    if (tokenResult.reason === 'denied' || tokenResult.reason === 'not_found') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              `linear_agent_activity failed: no Linear token (vault ${tokenResult.reason}). ` +
+              `Call vault_request_access for key 'linear/${agent}/token' (scope read), then retry.`,
+          },
+        ],
+      }
+    }
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `linear_agent_activity failed: vault broker ${tokenResult.reason} resolving 'linear/${agent}/token'.`,
+        },
+      ],
+    }
+  }
+
+  // AgentActivity content discriminated by type. thought/message/error carry
+  // a body; complete is terminal with an optional summary body.
+  const content: Record<string, unknown> = { type }
+  if (body != null && body !== '') content.body = body
+
+  const mutation =
+    'mutation AgentActivityCreate($input: AgentActivityCreateInput!) { ' +
+    'agentActivityCreate(input: $input) { success agentActivity { id } } }'
+  const variables = { input: { agentSessionId: sessionId, content } }
+
+  const fetchImpl = deps.fetchImpl ?? fetch
+  let resp: Response
+  try {
+    resp = await fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: tokenResult.token,
+      },
+      body: JSON.stringify({ query: mutation, variables }),
+    })
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `linear_agent_activity failed: request error: ${(err as Error).message}` }],
+    }
+  }
+
+  if (!resp.ok) {
+    const txt = await resp.text().catch(() => '')
+    return {
+      content: [
+        { type: 'text', text: `linear_agent_activity failed: Linear API ${resp.status}${txt ? ` — ${txt.slice(0, 200)}` : ''}` },
+      ],
+    }
+  }
+
+  let json: { data?: { agentActivityCreate?: { success?: boolean } }; errors?: Array<{ message?: string }> }
+  try {
+    json = (await resp.json()) as typeof json
+  } catch {
+    return { content: [{ type: 'text', text: 'linear_agent_activity failed: malformed Linear API response' }] }
+  }
+  if (json.errors && json.errors.length > 0) {
+    return {
+      content: [
+        { type: 'text', text: `linear_agent_activity failed: ${json.errors.map((e) => e.message ?? 'error').join('; ').slice(0, 300)}` },
+      ],
+    }
+  }
+  if (json.data?.agentActivityCreate?.success === false) {
+    return { content: [{ type: 'text', text: 'linear_agent_activity failed: Linear reported success=false' }] }
+  }
+
+  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/gateway/model-command.ts

@@ -33,12 +33,20 @@ import {
 } from '../../src/agents/model-picker.js'
 
 /**
- * Aliases the claude CLI resolves natively. Listed in help text only —
- * the handler does NOT restrict to these (a full model id like
- * `claude-opus-4-8` passes through and claude itself validates it, so
- * new aliases/models work without a switchroom release).
+ * Aliases the claude CLI resolves natively (`claude --help`: "an alias for
+ * the latest model (e.g. 'fable', 'opus', or 'sonnet')"). Listed in help
+ * text only — the handler does NOT restrict to these (a full model id like
+ * `claude-opus-4-8` passes through and claude itself validates it, so new
+ * aliases/models work without a switchroom release).
+ *
+ * `fable` is the latest flagship (Fable 5) — kept selectable here on
+ * purpose. NB the alias is NOT the full codename: `claude-fable-5` (a
+ * pinned pre-launch id) was retired server-side and 4xx'd the whole fleet
+ * on 2026-06-13, while the `fable` alias keeps resolving to the current
+ * model. Aliases are the durable way to pick a model — see the model
+ * regression tests.
  */
-export const MODEL_ALIASES = ['opus', 'sonnet', 'haiku', 'default'] as const
+export const MODEL_ALIASES = ['opus', 'sonnet', 'haiku', 'fable', 'default'] as const
 
 /**
  * Shape gate for the model argument. This string is typed literally