typeclaw 0.17.0 → 0.19.0

package/src/channels/adapters/github/index.ts

@@ -1,9 +1,10 @@
+import type { GithubTokenBridge } from '@/channels/github-token-bridge'
 import type { ChannelRouter } from '@/channels/router'
 import type { ChannelAdapterConfig, GithubAdapterConfig } from '@/channels/schema'
 import { resolveSecret } from '@/secrets/resolve'
 import type { GithubSecretsBlock } from '@/secrets/schema'
 
-import { buildAuthStrategy } from './auth'
+import { buildAuthStrategy, type GithubAuthContext } from './auth'
 import { createGithubChannelNameResolver } from './channel-resolver'
 import { createDeliveryDedup } from './dedup'
 import { findPermissionGaps } from './event-permissions'
@@ -61,6 +62,12 @@ export type GithubAdapterOptions = {
   // Test-only: replaces `setInterval` so tests can control when the
   // background refresh fires without waiting on real wall-clock time.
   setInterval?: (handler: () => void, ms: number) => { clear: () => void }
+  // Write-side of the GithubTokenBridge. On App-auth start the adapter
+  // registers a per-repo minter here so plugin hooks can resolve a token for
+  // ad-hoc `gh` commands; it unregisters on stop and on start rollback. PAT
+  // auth does not register (the seeded GH_TOKEN already covers every repo a
+  // classic PAT can reach, and a fine-grained PAT cannot be re-minted per repo).
+  githubTokenBridge?: GithubTokenBridge
 }
 
 export type GithubAdapter = {
@@ -93,35 +100,37 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
   let started = false
   let managedHooks: ReadonlyArray<{ repo: string; hookId: number }> = []
   let tokenRefreshTimer: { clear: () => void } | null = null
+  let unregisterTokenBridge: (() => void) | null = null
   const workspaceByChat = new Map<string, string>()
 
   const rememberWorkspace = (workspace: string, chat: string): void => {
     workspaceByChat.set(chat, workspace)
   }
 
-  const tokenFn = async () => {
-    const t = await auth.token()
-    process.env.GH_TOKEN = t
-    return t
-  }
+  // Repo/owner-aware token resolver. A single GitHub App can span multiple
+  // installations (one per owner); each consumer passes its repo/owner so the
+  // right installation token is minted. Unlike the old single-token path, this
+  // does NOT mutate process.env.GH_TOKEN — that global is seeded separately and
+  // only when exactly one installation applies (see seedGhTokenIfSingle).
+  const authToken = (context?: GithubAuthContext) => auth.token(context)
   const outbound = createGithubOutboundCallback({
-    token: tokenFn,
+    token: authToken,
     authType: options.secrets.auth.type,
     logger,
     fetchImpl,
   })
   const history = createGithubHistoryCallback({
-    token: tokenFn,
+    token: authToken,
     fetchImpl,
     workspaceForChat: (chat) => workspaceByChat.get(chat) ?? null,
   })
-  const membership = createGithubMembershipResolver({ token: tokenFn, fetchImpl })
-  const channelNameResolver = createGithubChannelNameResolver({ token: tokenFn, fetchImpl })
+  const membership = createGithubMembershipResolver({ token: authToken, fetchImpl })
+  const channelNameResolver = createGithubChannelNameResolver({ token: authToken, fetchImpl })
   const fetchAttachment = createGithubFetchAttachmentCallback()
   // No-op typing callback: GitHub has no typing indicator API.
   const typing = async (): Promise<void> => {}
   const dedup = createDeliveryDedup()
-  const isBotInTeam = createTeamMembershipChecker({ token: tokenFn, fetchImpl })
+  const isBotInTeam = createTeamMembershipChecker({ token: authToken, fetchImpl })
   const handler = createGithubWebhookHandler({
     webhookSecret,
     dedup,
@@ -174,35 +183,64 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         selfLogin = null
         throw err
       }
-      // Seed GH_TOKEN so `gh` CLI calls in the container are pre-authenticated.
-      // tokenFn keeps it current on every adapter API call; App tokens refresh
-      // automatically when within 5 minutes of expiry.
-      process.env.GH_TOKEN = await auth.token()
       started = true
-      // Keep GH_TOKEN warm even when the adapter is only receiving inbound
-      // webhooks and not making outbound API calls. This prevents `gh` CLI
-      // calls from the agent from failing with 401 after the token expires.
-      const tokenRefreshIntervalMs = options.tokenRefreshIntervalMs ?? DEFAULT_TOKEN_REFRESH_INTERVAL_MS
-      if (tokenRefreshIntervalMs > 0) {
-        const refresh = () => {
-          tokenFn().catch((err) => {
-            logger.error(`[github] periodic token refresh failed: ${err instanceof Error ? err.message : String(err)}`)
-          })
+      // Seed the process-wide GH_TOKEN when it's unambiguous; skip otherwise.
+      // See ghTokenSeedDecision for why one owner is required. On skip, authToken
+      // still resolves a repo-scoped token per call for the adapter's own traffic.
+      const seed = ghTokenSeedDecision(options.secrets.auth.type, options.configRef().repos ?? [])
+      if (seed.kind === 'seed') {
+        const seedContext = seed.context
+        const seedGhToken = async (): Promise<void> => {
+          process.env.GH_TOKEN = await auth.token(seedContext)
+        }
+        await seedGhToken()
+        const tokenRefreshIntervalMs = options.tokenRefreshIntervalMs ?? DEFAULT_TOKEN_REFRESH_INTERVAL_MS
+        if (tokenRefreshIntervalMs > 0) {
+          const refresh = () => {
+            seedGhToken().catch((err) => {
+              logger.error(
+                `[github] periodic token refresh failed: ${err instanceof Error ? err.message : String(err)}`,
+              )
+            })
+          }
+          const setIntervalFn =
+            options.setInterval ??
+            ((handler: () => void, ms: number) => {
+              const timer = setInterval(handler, ms)
+              return { clear: () => clearInterval(timer) }
+            })
+          tokenRefreshTimer = setIntervalFn(refresh, tokenRefreshIntervalMs)
         }
-        const setIntervalFn =
-          options.setInterval ??
-          ((handler: () => void, ms: number) => {
-            const timer = setInterval(handler, ms)
-            return { clear: () => clearInterval(timer) }
-          })
-        tokenRefreshTimer = setIntervalFn(refresh, tokenRefreshIntervalMs)
+      } else {
+        logger.info(
+          `${GH_TOKEN_SKIP_LOG[seed.reason]} Ad-hoc \`gh\` commands should set a repo-scoped token explicitly.`,
+        )
+      }
+      if (options.secrets.auth.type === 'app' && options.githubTokenBridge !== undefined) {
+        // Gate ad-hoc `gh` minting on the configured repos[]. The slug arrives
+        // from an attacker-controllable -R/--repo flag (untrusted PR/issue
+        // content can prompt-inject it); without this an injected `-R any/repo`
+        // would mint an installation-wide token for any repo the App is installed
+        // on — a cross-tenant leak under a multi-owner App. Enforced here, not in
+        // the parser, because this adapter is the authority that owns repos[].
+        unregisterTokenBridge = options.githubTokenBridge.registerResolver((repoSlug) => {
+          const allowed = new Set((options.configRef().repos ?? []).map(canonicalRepoSlug))
+          if (!allowed.has(canonicalRepoSlug(repoSlug))) {
+            throw new Error(
+              `repo \`${repoSlug}\` is not in this agent's configured \`channels.github.repos[]\`; ` +
+                'refusing to mint a GitHub App token for it. Target a configured repo, ' +
+                'or add it to `repos[]` if the agent is meant to operate there.',
+            )
+          }
+          return auth.token({ repoSlug })
+        })
       }
       logger.info(`[github] webhook listening on port ${options.configRef().webhookPort} as @${self.login}`)
       // Best-effort: App-only preflight that compares the installation's granted
       // permissions against the configured eventAllowlist and warns about gaps.
       // Catches the most common misconfiguration (App installed with the default
       // metadata-only permission set) before any event fires a 403.
-      await runAppPermissionPreflight(logger, auth, options.configRef().eventAllowlist)
+      await runAppPermissionPreflight(logger, auth, options.configRef().eventAllowlist, options.configRef().repos ?? [])
       // Repository webhook registration is best-effort: failures are logged
       // per-repo, the adapter stays up. A misconfigured PAT or App that
       // can't manage hooks must not prevent the adapter from accepting
@@ -225,6 +263,9 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         })
       } else if (repos.length > 0) {
         const legacyProviderHostSuffix = detectLegacyProviderHostSuffix(effectiveUrl)
+        logger.info(
+          `[github] registering webhook for ${repos.length} repo(s) [${repos.join(', ')}] -> ${effectiveUrl} (events: ${cfg.eventAllowlist.join(', ')})`,
+        )
         if (webhookRegistrationDelayMs > 0) {
           logger.info(
             `[github] waiting ${webhookRegistrationDelayMs}ms before registering webhook so the Cloudflare edge can warm up`,
@@ -232,7 +273,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
           await sleep(webhookRegistrationDelayMs)
         }
         const registration = await registerGithubWebhooks({
-          token: tokenFn,
+          token: (repoSlug: string) => auth.token({ repoSlug }),
           webhookUrl: effectiveUrl,
           webhookSecret,
           repos,
@@ -263,7 +304,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       // last to clear the cached App-installation token.
       if (managedHooks.length > 0) {
         const deregistration = await deregisterGithubWebhooks({
-          token: tokenFn,
+          token: (repoSlug: string) => auth.token({ repoSlug }),
           hooks: managedHooks,
           fetchImpl,
         })
@@ -274,6 +315,10 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         tokenRefreshTimer.clear()
         tokenRefreshTimer = null
       }
+      if (unregisterTokenBridge !== null) {
+        unregisterTokenBridge()
+        unregisterTokenBridge = null
+      }
       await auth.dispose()
       delete process.env.GH_TOKEN
       server = null
@@ -367,18 +412,36 @@ async function runAppPermissionPreflight(
   logger: GithubAdapterLogger,
   auth: ReturnType<typeof buildAuthStrategy>,
   eventAllowlist: readonly string[],
+  repos: readonly string[],
 ): Promise<void> {
   if (auth.getInstallationGrants === undefined) return
-  let grants
-  try {
-    grants = await auth.getInstallationGrants()
-  } catch (err) {
-    logger.warn(`[github] permission preflight skipped: ${err instanceof Error ? err.message : String(err)}`)
-    return
+  const getGrants = (context: GithubAuthContext | undefined) => auth.getInstallationGrants?.(context)
+  // One grants check per distinct owner: installations are owner-scoped, so
+  // repos sharing an owner share an installation. The first repo per owner is
+  // the resolution key. With no repos, fall back to a single context-free check.
+  const reposByOwner = new Map<string, string>()
+  for (const repo of repos) {
+    const owner = repo.split('/')[0]
+    if (owner !== undefined && owner !== '' && !reposByOwner.has(owner)) reposByOwner.set(owner, repo)
+  }
+  const contexts: Array<{ label: string; context: { repoSlug: string } | undefined }> =
+    reposByOwner.size === 0
+      ? [{ label: 'app', context: undefined }]
+      : [...reposByOwner.values()].map((repo) => ({ label: repo, context: { repoSlug: repo } }))
+  for (const { label, context } of contexts) {
+    let grants
+    try {
+      grants = await getGrants(context)
+    } catch (err) {
+      logger.warn(
+        `[github] permission preflight skipped for ${label}: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      continue
+    }
+    if (grants === undefined) continue
+    const gaps = findPermissionGaps(eventAllowlist, grants.permissions)
+    if (gaps.length > 0) logger.warn(buildAppPermissionPreflightGuidance(gaps))
   }
-  const gaps = findPermissionGaps(eventAllowlist, grants.permissions)
-  if (gaps.length === 0) return
-  logger.warn(buildAppPermissionPreflightGuidance(gaps))
 }
 
 function logDeregistrationOutcome(
@@ -392,6 +455,47 @@ function logDeregistrationOutcome(
   }
 }
 
+type GhTokenSeedDecision =
+  | { kind: 'seed'; context?: GithubAuthContext }
+  | { kind: 'skip'; reason: 'no-repos' | 'multiple-owners' }
+
+const GH_TOKEN_SKIP_LOG: Record<'no-repos' | 'multiple-owners', string> = {
+  'no-repos':
+    '[github] no repos[] configured; GH_TOKEN not seeded globally (cannot prove which App installation to use).',
+  'multiple-owners': '[github] repos span multiple owners (multiple App installations); GH_TOKEN not seeded globally.',
+}
+
+// Decides how to seed the process-wide GH_TOKEN. PATs aren't installation-scoped
+// (seed context-free). For App auth we seed from a configured repo slug, which
+// resolves the installation via repos/{owner}/{repo}/installation — the only
+// lookup that works for both org- and user-owned repos. One owner is required:
+// no-repos can't prove an installation, multi-owner needs >1 token.
+function ghTokenSeedDecision(authType: 'pat' | 'app', repos: readonly string[]): GhTokenSeedDecision {
+  if (authType === 'pat') return { kind: 'seed' }
+  const slugs = [...new Set(repos.filter(isWellFormedSlug))].sort()
+  if (slugs.length === 0) return { kind: 'skip', reason: 'no-repos' }
+  const owners = new Set(slugs.map((slug) => slug.split('/')[0]))
+  if (owners.size > 1) return { kind: 'skip', reason: 'multiple-owners' }
+  return { kind: 'seed', context: { repoSlug: slugs[0] } }
+}
+
+function isWellFormedSlug(repo: string): boolean {
+  const [owner, name, ...rest] = repo.split('/')
+  return owner !== undefined && owner !== '' && name !== undefined && name !== '' && rest.length === 0
+}
+
+// Canonical form for repos[] allowlist comparison so the gate can't be bypassed
+// by case, a trailing slash, or a `.git` suffix (GitHub treats owner/name
+// case-insensitively). Applied identically to both configured repos[] and the
+// runtime slug before exact Set membership.
+function canonicalRepoSlug(repo: string): string {
+  return repo
+    .trim()
+    .replace(/\/+$/, '')
+    .replace(/\.git$/i, '')
+    .toLowerCase()
+}
+
 function defaultSleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }

package/src/channels/adapters/github/membership.ts

@@ -1,10 +1,11 @@
 import type { MembershipResolver, MembershipResolverResult } from '@/channels/membership'
 
+import type { GithubAuthContext } from './auth'
 import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
 import { parseRepo } from './outbound'
 
 export function createGithubMembershipResolver(options: {
-  token: () => Promise<string>
+  token: (context?: GithubAuthContext) => Promise<string>
   fetchImpl?: typeof fetch
 }): MembershipResolver {
   const fetchImpl = options.fetchImpl ?? fetch
@@ -16,7 +17,7 @@ export function createGithubMembershipResolver(options: {
       const response = await fetchImpl(
         `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/collaborators?per_page=100`,
         {
-          headers: githubJsonHeaders(await options.token()),
+          headers: githubJsonHeaders(await options.token({ repoSlug: key.workspace })),
         },
       )
       if (!response.ok) return response.status >= 500 ? { kind: 'transient' } : { kind: 'permanent' }
@@ -27,6 +28,10 @@ export function createGithubMembershipResolver(options: {
         if (user.type === 'Bot') bots++
         else humans++
       }
+      // Counts only, no humanMemberIds: GitHub membership is the repo
+      // collaborator list, a different population from the authors that can
+      // comment into a PR/issue turn, so it is not a basis for the channel
+      // grant-role relaxation (see provesOnlyAgentBotPresent in grant-role.ts).
       return { humans, bots, fetchedAt: Date.now(), truncated: users.length >= 100 }
     } catch {
       return { kind: 'transient' }

package/src/channels/adapters/github/outbound.ts

@@ -1,5 +1,6 @@
 import type { OutboundCallback, OutboundMessage, SendResult } from '@/channels/types'
 
+import type { GithubAuthContext } from './auth'
 import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
 import {
   buildOutboundPermissionGuidance,
@@ -11,7 +12,7 @@ import {
 export type GithubOutboundLogger = { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
 
 export function createGithubOutboundCallback(deps: {
-  token: () => Promise<string>
+  token: (context?: GithubAuthContext) => Promise<string>
   authType: GithubAuthType
   logger: GithubOutboundLogger
   fetchImpl?: typeof fetch
@@ -28,9 +29,12 @@ export function createGithubOutboundCallback(deps: {
     const target = parseChat(msg.chat)
     if (target === null) return { ok: false, error: `invalid GitHub chat: ${msg.chat}` }
 
+    const token = () => deps.token({ repoSlug: msg.workspace })
+
     if (target.kind === 'discussion') {
       return await postDiscussionComment({
         ...deps,
+        token,
         fetchImpl,
         repo,
         discussionNumber: target.number,
@@ -44,7 +48,7 @@ export function createGithubOutboundCallback(deps: {
       : `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/issues/${target.number}/comments`
     return await postJson(
       fetchImpl,
-      await deps.token(),
+      await token(),
       endpoint,
       { body },
       {

package/src/channels/adapters/github/team-membership.ts

@@ -7,12 +7,14 @@
 // request rebuilds it). Errors fall closed (return false): we'd rather drop
 // a real review request than wake the agent on a team the bot isn't in.
 
+import type { GithubAuthContext } from './auth'
+
 const ACTIVE_MEMBERSHIP_STATE = 'active'
 
 export type TeamMembershipChecker = (input: { org: string; slug: string; login: string }) => Promise<boolean>
 
 export function createTeamMembershipChecker(options: {
-  token: () => Promise<string>
+  token: (context?: GithubAuthContext) => Promise<string>
   fetchImpl?: typeof fetch
 }): TeamMembershipChecker {
   const fetchImpl = options.fetchImpl ?? fetch
@@ -23,7 +25,7 @@ export function createTeamMembershipChecker(options: {
     const cached = cache.get(key)
     if (cached !== undefined) return cached
 
-    const result = await lookup(fetchImpl, await options.token(), org, slug, login)
+    const result = await lookup(fetchImpl, await options.token({ owner: org }), org, slug, login)
     cache.set(key, result)
     return result
   }

package/src/channels/adapters/github/webhook-register.ts

@@ -1,7 +1,10 @@
 import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
 
 export type RegisterGithubWebhooksOptions = {
-  token: () => Promise<string>
+  // Resolves an installation token scoped to the given "owner/name" repo. A
+  // single GitHub App may span multiple owners (separate installations), so
+  // each repo's hook must be created/listed with that repo's own token.
+  token: (repoSlug: string) => Promise<string>
   webhookUrl: string
   webhookSecret: string
   repos: readonly string[]
@@ -51,22 +54,22 @@ export async function registerGithubWebhooks(
   options: RegisterGithubWebhooksOptions,
 ): Promise<WebhookRegistrationResult> {
   const fetchImpl = options.fetchImpl ?? fetch
-  let token: string
-  try {
-    token = await options.token()
-  } catch (err) {
-    const error = describe(err)
-    return { repos: options.repos.map((repo) => ({ repo, action: 'failed' as const, error })) }
-  }
   const repos: WebhookRepoResult[] = []
   for (const repo of options.repos) {
+    let token: string
+    try {
+      token = await options.token(repo)
+    } catch (err) {
+      repos.push({ repo, action: 'failed', error: describe(err) })
+      continue
+    }
     repos.push(await registerOne(fetchImpl, token, repo, options))
   }
   return { repos }
 }
 
 export type DeregisterGithubWebhooksOptions = {
-  token: () => Promise<string>
+  token: (repoSlug: string) => Promise<string>
   hooks: ReadonlyArray<{ repo: string; hookId: number }>
   fetchImpl?: typeof fetch
 }
@@ -79,15 +82,15 @@ export async function deregisterGithubWebhooks(
   options: DeregisterGithubWebhooksOptions,
 ): Promise<WebhookDeregistrationResult> {
   const fetchImpl = options.fetchImpl ?? fetch
-  let token: string
-  try {
-    token = await options.token()
-  } catch (err) {
-    const error = describe(err)
-    return { hooks: options.hooks.map((h) => ({ ...h, action: 'failed', error })) }
-  }
   const hooks: WebhookDeregistrationResult['hooks'] = []
   for (const hook of options.hooks) {
+    let token: string
+    try {
+      token = await options.token(hook.repo)
+    } catch (err) {
+      hooks.push({ ...hook, action: 'failed', error: describe(err) })
+      continue
+    }
     hooks.push(await deleteOne(fetchImpl, token, hook))
   }
   return { hooks }

package/src/channels/adapters/slack-bot-slash-commands.ts

@@ -1,5 +1,6 @@
 import type { SlackSocketModeSlashCommandArgs } from 'agent-messenger/slackbot'
 
+import type { ExecuteCommandResult } from '@/channels/router'
 import type { ChannelKey } from '@/channels/types'
 
 // Slack channel ids: 'C' = public, 'G' = private/legacy multi-party DM,
@@ -64,13 +65,89 @@ export function parseSlashCommand(
   }
 }
 
+// Slack blocks native slash commands inside threads ("/stop is not supported
+// in threads. Sorry!"), so the only way to abort a thread-scoped turn from
+// inside that thread is a normal message. We recognise a leading `!` as an
+// alternate command prefix and route it through the same router.executeCommand
+// path as native slashes. The guard is strict: only a first token that resolves
+// to a known command name is rewritten, so casual messages like "!nice work"
+// pass through untouched as regular agent input.
+//
+// Unlike native slash payloads (which never carry a thread and rely on the
+// router's workspace+chat fallback), a thread message carries `thread_ts`,
+// letting us target the exact thread session and skip the ambiguous-match case
+// entirely.
+export const THREAD_COMMAND_PREFIX = '!'
+
+export type ThreadCommandInput = {
+  text: string
+  channel: string
+  threadTs: string | null
+  isDm: boolean
+  teamId: string
+  invokerId: string
+}
+
+export type ParseThreadCommandResult =
+  | { kind: 'parsed'; command: ParsedSlackSlashCommand }
+  | { kind: 'ignore'; reason: 'no-prefix' | 'unknown-command' }
+
+// Both ignore reasons (`no-prefix`, `unknown-command`) are non-fatal: the
+// caller lets the message flow through as ordinary agent input.
+export function parseThreadCommand(
+  input: ThreadCommandInput,
+  knownCommands: ReadonlySet<string>,
+): ParseThreadCommandResult {
+  const trimmed = input.text.trimStart()
+  if (!trimmed.startsWith(THREAD_COMMAND_PREFIX)) {
+    return { kind: 'ignore', reason: 'no-prefix' }
+  }
+  const firstToken = trimmed.slice(THREAD_COMMAND_PREFIX.length).split(/\s/, 1)[0] ?? ''
+  const name = firstToken.toLowerCase()
+  if (name === '' || !knownCommands.has(name)) {
+    return { kind: 'ignore', reason: 'unknown-command' }
+  }
+
+  const workspace = input.isDm ? '@dm' : input.teamId
+  return {
+    kind: 'parsed',
+    command: {
+      name,
+      key: { adapter: 'slack-bot', workspace, chat: input.channel, thread: input.threadTs },
+      invokerId: input.invokerId,
+    },
+  }
+}
+
 export const SLACK_SLASH_REPLY_ABORTED = 'Stopped the current turn.'
 export const SLACK_SLASH_REPLY_NO_LIVE_SESSION = 'Nothing to stop — no active turn in this channel.'
 export const SLACK_SLASH_REPLY_FAILED = 'Could not stop the current turn (internal error).'
 export const SLACK_SLASH_REPLY_PERMISSION_DENIED =
   'You do not have permission to stop the current turn in this channel.'
+// Native slash commands cannot be invoked from a thread, so the only way to
+// disambiguate is the `!stop` thread-message fallback — advise that, not the
+// impossible `/stop`-in-thread.
 export const SLACK_SLASH_REPLY_AMBIGUOUS =
-  'Multiple active turns in this channel. Reply `/stop` from inside the specific thread you want to stop.'
+  'Multiple active turns in this channel. Reply `!stop` inside the specific thread you want to stop.'
+
+// Single outcome→reply mapping shared by the native-slash (ack payload) and
+// `!cmd` thread (postMessage) delivery paths so the two never drift.
+export function commandResultReply(result: ExecuteCommandResult): string {
+  switch (result.kind) {
+    case 'handled':
+      // Dynamic commands (e.g. /help) carry their own reply; static control
+      // commands (/stop) leave it undefined and fall back to the fixed string.
+      return result.reply ?? SLACK_SLASH_REPLY_ABORTED
+    case 'no-live-session':
+      return SLACK_SLASH_REPLY_NO_LIVE_SESSION
+    case 'permission-denied':
+      return SLACK_SLASH_REPLY_PERMISSION_DENIED
+    case 'ambiguous':
+      return SLACK_SLASH_REPLY_AMBIGUOUS
+    case 'unknown-command':
+      return SLACK_SLASH_REPLY_FAILED
+  }
+}
 
 // Slack's ack callback accepts an optional response payload that becomes
 // the user-visible reply. `response_type: 'ephemeral'` keeps the reply