typeclaw 0.6.0 → 0.8.0

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

@@ -1,4 +1,4 @@
-import { SlackBotClient, SlackBotListener } from 'agent-messenger/slackbot'
+import { SlackBotClient, SlackBotListener, type SlackSocketModeSlashCommandArgs } from 'agent-messenger/slackbot'
 
 import {
   MEMBERSHIP_ENUMERATION_CAP,
@@ -33,8 +33,27 @@ import {
   type SlackInboundMessageEvent,
 } from './slack-bot-classify'
 import { createSlackDedupe } from './slack-bot-dedupe'
+import {
+  buildSlashAckPayload,
+  parseSlashCommand,
+  SLACK_SLASH_REPLY_ABORTED,
+  SLACK_SLASH_REPLY_AMBIGUOUS,
+  SLACK_SLASH_REPLY_FAILED,
+  SLACK_SLASH_REPLY_NO_LIVE_SESSION,
+  SLACK_SLASH_REPLY_PERMISSION_DENIED,
+} from './slack-bot-slash-commands'
 import { slackTsToMillis } from './slack-bot-time'
 
+// One slash command per logical agent gesture. Mirrors the discord-bot
+// SLASH_COMMANDS constant so the cross-platform set stays consistent — when
+// we add a new command (e.g. /memory), it appears in both adapters together.
+// The actual registration lives in the Slack App Manifest at src/cli/ui.ts;
+// this constant is the runtime allow-list that gates which delivered
+// slash_commands events we route vs drop. The ui.test.ts manifest-drift
+// test asserts equality between this set and SLACK_APP_MANIFEST.features.
+// slash_commands so the two can never silently diverge.
+export const SLACK_SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(['stop'])
+
 // Resolvers fall back to the raw id on failure, so a name equal to the id
 // means resolution failed; we render the bare id rather than `id(id)`. The
 // prefix is intentionally only applied to the named form so we never log
@@ -44,6 +63,101 @@ function formatLabel(name: string | undefined, id: string, prefix = ''): string
   return `${prefix}${name}(${id})`
 }
 
+export type SlackBotAdapterLoggerLike = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+export type SlashCommandHandlerDeps = {
+  router: Pick<ChannelRouter, 'executeCommand'>
+  knownCommandNames: ReadonlySet<string>
+  logger: SlackBotAdapterLoggerLike
+  formatChannelTag: (workspace: string, chat: string) => Promise<string>
+}
+
+// Ack-first invariant: the handler must call args.ack() exactly once on
+// every path AND must do so before any slow network work (resolver calls,
+// post-ack logging). Slack's 3s ack deadline starts when the slash command
+// envelope arrives on the WebSocket; missing it shows the user
+// "/stop didn't respond in time". The synchronous executeCommand happy
+// path is fast (in-memory map lookup + abort), so ack-after-execute is
+// safe; everything else (formatChannelTag, post-ack logging) runs after.
+//
+// Ack failure handling: a thrown ack on the happy path is logged but does
+// NOT trigger the catch-all error-ack below, which would attempt a second
+// ack call and break the exactly-once contract.
+export function createSlashCommandHandler(
+  deps: SlashCommandHandlerDeps,
+): (args: SlackSocketModeSlashCommandArgs) => Promise<void> {
+  return async ({ ack, body }) => {
+    const parsed = parseSlashCommand(body, deps.knownCommandNames)
+    if (parsed.kind === 'ignore') {
+      deps.logger.warn(`[slack-bot] slash command dropped reason=${parsed.reason} command=${body.command}`)
+      try {
+        ack(buildSlashAckPayload(SLACK_SLASH_REPLY_FAILED))
+      } catch (err) {
+        deps.logger.warn(`[slack-bot] slash command ack (drop path) failed: ${describe(err)}`)
+      }
+      return
+    }
+    const { command } = parsed
+
+    // Pre-ACK log: bare ids only (no formatChannelTag — would burn ack budget
+    // on a slow Slack API minute via the channel-name resolver).
+    deps.logger.info(
+      `[slack-bot] slash /${command.name} invoker=${command.invokerId} team=${command.key.workspace} channel=${command.key.chat}`,
+    )
+
+    let result: Awaited<ReturnType<typeof deps.router.executeCommand>>
+    try {
+      result = await deps.router.executeCommand(command.key, command.name, {
+        invokerId: command.invokerId,
+      })
+    } catch (err) {
+      deps.logger.error(`[slack-bot] slash command handler failed: ${describe(err)}`)
+      try {
+        ack(buildSlashAckPayload(SLACK_SLASH_REPLY_FAILED))
+      } catch (ackErr) {
+        deps.logger.warn(`[slack-bot] slash command error-ack failed: ${describe(ackErr)}`)
+      }
+      return
+    }
+
+    const replyContent =
+      result.kind === 'handled'
+        ? SLACK_SLASH_REPLY_ABORTED
+        : result.kind === 'no-live-session'
+          ? SLACK_SLASH_REPLY_NO_LIVE_SESSION
+          : result.kind === 'permission-denied'
+            ? SLACK_SLASH_REPLY_PERMISSION_DENIED
+            : result.kind === 'ambiguous'
+              ? SLACK_SLASH_REPLY_AMBIGUOUS
+              : SLACK_SLASH_REPLY_FAILED
+
+    // Final ack on the happy path: own try/catch so a thrown ack here does
+    // NOT cascade into the error-path ack above (which would violate the
+    // exactly-once contract). The abort already happened server-side; only
+    // the user-visible confirmation is lost.
+    try {
+      ack(buildSlashAckPayload(replyContent))
+    } catch (err) {
+      deps.logger.warn(`[slack-bot] slash command ack failed: ${describe(err)}`)
+    }
+
+    // Decorative post-ack logging: resolve channel names now that the 3s
+    // budget is no longer a concern. Best-effort.
+    try {
+      const inboundTag = await deps.formatChannelTag(command.key.workspace, command.key.chat)
+      deps.logger.info(`[slack-bot] slash /${command.name} result=${result.kind} ${inboundTag}`)
+    } catch (err) {
+      deps.logger.info(
+        `[slack-bot] slash /${command.name} result=${result.kind} (channel-tag resolution failed: ${describe(err)})`,
+      )
+    }
+  }
+}
+
 // app_mention payloads omit channel_type and never carry a subtype, so we
 // promote them to a message-shaped event for the shared classifier. The
 // promoted event is classified as a regular channel message; the
@@ -661,6 +775,13 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
 
   const dedupe = createSlackDedupe()
 
+  const handleSlashCommand = createSlashCommandHandler({
+    router: options.router,
+    knownCommandNames: SLACK_SLASH_COMMAND_NAMES,
+    logger,
+    formatChannelTag,
+  })
+
   const handleMessageEvent = async (
     event: SlackInboundMessageEvent,
     source: 'message' | 'app_mention',
@@ -777,6 +898,23 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
         ack()
         void handleMessageEvent(promoteAppMentionToMessage(event as SlackInboundAppMentionEvent), 'app_mention')
       })
+      listener.on('slash_commands', (args) => {
+        // The handler owns the ack call itself (the ack payload carries the
+        // user-visible reply text), so we do NOT ack here. inflightInbounds
+        // wrapping mirrors handleMessageEvent so stop() can drain the
+        // handler before tearing down the listener — otherwise a /stop
+        // arriving during stop() would lose its ack and the user sees
+        // "didn't respond in time" even though the abort succeeded.
+        inflightInbounds++
+        void handleSlashCommand(args).finally(() => {
+          inflightInbounds--
+          if (inflightInbounds === 0 && stopWaiters.length > 0) {
+            const waiters = stopWaiters
+            stopWaiters = []
+            for (const w of waiters) w()
+          }
+        })
+      })
 
       options.router.registerOutbound('slack-bot', outboundCallback)
       options.router.registerTyping('slack-bot', typingCallback)

package/src/channels/router.ts

@@ -297,9 +297,30 @@ type LiveSession = {
   unsubProviderErrors: (() => void) | null
 }
 
+// `event` is null for command invocations that originated outside the inbound
+// pipeline (e.g. Discord native slash commands fired from listener.on
+// ('interaction_create')). Handlers that need a real inbound — for some
+// future hypothetical command like `/quote` — must guard on event !== null
+// instead of assuming it.
 type ChannelCommandContext = {
   live: LiveSession
-  event: InboundMessage
+  event: InboundMessage | null
+}
+
+export type ExecuteCommandResult =
+  | { kind: 'handled'; name: string }
+  | { kind: 'unknown-command'; name: string }
+  | { kind: 'no-live-session' }
+  | { kind: 'permission-denied' }
+  | { kind: 'ambiguous'; matchCount: number }
+
+// Identifies who invoked an adapter-driven command. Required so the router
+// can run the same channel.respond permission gate the text-prefix command
+// path runs (isChannelRespondDenied in route()). Without it, a guest user
+// in a public Slack channel could /stop an owner-created session that
+// happened to be live, bypassing role gating entirely.
+export type ExecuteCommandOptions = {
+  invokerId: string
 }
 
 export type SendSource = 'tool' | 'system'
@@ -345,6 +366,22 @@ export type ChannelRouter = {
   registerFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
   unregisterFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
   fetchAttachment: (adapter: ChannelKey['adapter'], args: FetchAttachmentArgs) => Promise<FetchAttachmentResult>
+  // Execute a command by name against an existing live session, bypassing
+  // the inbound classifier, engagement gate, debounce, and prompt queue.
+  // Used by adapters that receive commands through a native surface
+  // (Discord application-command interactions) rather than text. Gates
+  // the invoker on channel.respond — same permission gate the text-prefix
+  // command path runs — so a guest user cannot abort an owner's session
+  // by clicking the slash-command picker. Adapters MUST forward the
+  // invoker's platform-specific user id; without it the gate cannot
+  // identify the actor and resolves to 'guest' which denies. Returns:
+  //   - handled: command ran
+  //   - permission-denied: invoker lacks channel.respond
+  //   - no-live-session: channel has no active session
+  //   - ambiguous: multiple thread-keyed sessions in same chat (Slack);
+  //     caller should refuse to act rather than abort an arbitrary one
+  //   - unknown-command: name is not registered
+  executeCommand: (key: ChannelKey, name: string, options: ExecuteCommandOptions) => Promise<ExecuteCommandResult>
   // Lowered self-aliases (configured + implicit dir-name). Adapters use
   // this to anchor outbound threading on alias-only inbounds — see
   // slack-bot-classify.ts. Read live so a reload of `alias` propagates
@@ -1733,6 +1770,48 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  const executeCommand = async (
+    key: ChannelKey,
+    name: string,
+    options: ExecuteCommandOptions,
+  ): Promise<ExecuteCommandResult> => {
+    const lowered = name.toLowerCase()
+    if (!commands.has(lowered)) {
+      return { kind: 'unknown-command', name: lowered }
+    }
+    // Permission gate runs BEFORE the live-session lookup so a guest user
+    // invoking /stop on a non-existent session gets 'permission-denied'
+    // (consistent answer regardless of session state) rather than leaking
+    // session presence via the 'no-live-session' vs 'permission-denied'
+    // distinction.
+    const partial: SessionOrigin = {
+      kind: 'channel',
+      adapter: key.adapter,
+      workspace: key.workspace,
+      chat: key.chat,
+      thread: key.thread,
+      lastInboundAuthorId: options.invokerId,
+    }
+    if (!permissions.has(partial, CORE_PERMISSIONS.channelRespond)) {
+      return { kind: 'permission-denied' }
+    }
+    const resolved = resolveLiveSessionForCommand(liveSessions, key)
+    if (resolved.kind === 'none') {
+      return { kind: 'no-live-session' }
+    }
+    if (resolved.kind === 'ambiguous') {
+      return { kind: 'ambiguous', matchCount: resolved.count }
+    }
+    const result = await commands.execute(`/${lowered}`, { live: resolved.session, event: null })
+    if (result.kind === 'handled') {
+      return { kind: 'handled', name: result.name }
+    }
+    // commands.execute can only return not-command (impossible — we pass a
+    // leading slash), unknown-command (impossible — we just checked has()),
+    // or handled. Any other outcome is a bug.
+    return { kind: 'unknown-command', name: lowered }
+  }
+
   return {
     route,
     send,
@@ -1752,6 +1831,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     registerFetchAttachment,
     unregisterFetchAttachment,
     fetchAttachment,
+    executeCommand,
     getSelfAliases: computeSelfAliases,
     stop,
     liveCount: () => liveSessions.size,
@@ -1912,6 +1992,52 @@ function consecutiveSendKey(chat: string, thread: string | null | undefined): st
   return `${chat}:${thread ?? ''}`
 }
 
+export type ResolveLiveSessionResult =
+  | { kind: 'found'; session: LiveSession }
+  | { kind: 'none' }
+  | { kind: 'ambiguous'; count: number }
+
+// Lookup policy for adapter-driven commands. Exact-key match always wins.
+// On miss, fall back to (adapter, workspace, chat) without thread — but
+// only when EXACTLY ONE non-destroyed candidate exists. Ambiguous matches
+// return 'ambiguous' so the caller can refuse to act rather than abort an
+// arbitrary session.
+//
+// Why the fallback: Slack slash commands carry channel_id but no thread_ts,
+// so a slash invocation from a thread-keyed live session would otherwise
+// report no-live-session. Discord doesn't hit this — Discord treats threads
+// as channels, so the exact-key path already resolves.
+//
+// Why ambiguity-rejection: "first match wins" map-iteration semantics would
+// abort an arbitrary thread when multiple thread-keyed sessions coexist in
+// one channel (plausible on Slack: bot mentioned in multiple threads). The
+// user's slash command picker doesn't know about threads; we don't know
+// which they meant; refusing is safer than guessing.
+export function resolveLiveSessionForCommand(
+  liveSessions: ReadonlyMap<string, LiveSession>,
+  key: ChannelKey,
+): ResolveLiveSessionResult {
+  const exact = liveSessions.get(channelKeyId(key))
+  if (exact && !exact.destroyed) return { kind: 'found', session: exact }
+
+  const matches: LiveSession[] = []
+  for (const candidate of liveSessions.values()) {
+    if (candidate.destroyed) continue
+    if (
+      candidate.key.adapter === key.adapter &&
+      candidate.key.workspace === key.workspace &&
+      candidate.key.chat === key.chat
+    ) {
+      matches.push(candidate)
+      if (matches.length > 1) {
+        return { kind: 'ambiguous', count: matches.length }
+      }
+    }
+  }
+  if (matches.length === 1) return { kind: 'found', session: matches[0]! }
+  return { kind: 'none' }
+}
+
 function normalizeSendText(text: string | undefined): string | undefined {
   if (text === undefined) return undefined
   if (text === '') return undefined

package/src/cli/init.ts

@@ -374,7 +374,14 @@ export const defaultWizardPrompts: WizardPrompts = {
   hasExistingChannelSecrets,
   askReuseExistingChannel,
   runChannelFlow,
-  runOAuthLogin: (provider, cwd, model) => makeOAuthLoginRunner(buildOAuthCallbacks(provider.name))({ cwd, model }),
+  runOAuthLogin: async (provider, cwd, model) => {
+    const { callbacks, dispose } = buildOAuthCallbacks(provider.name)
+    try {
+      return await makeOAuthLoginRunner(callbacks)({ cwd, model })
+    } finally {
+      dispose()
+    }
+  },
   askOAuthFailureRecovery,
 }
 

package/src/cli/oauth-callbacks.ts

@@ -9,41 +9,71 @@ import type { OAuthCallbacks } from '@/init/oauth-login'
 // concurrent `onManualCodeInput` prompt for users whose browser is on a
 // different host than the CLI. See src/init/oauth-login.ts for the contract
 // on each callback and why onManualCodeInput is required for cross-device.
-export function buildOAuthCallbacks(providerName: string): OAuthCallbacks {
+//
+// Returns `{ callbacks, dispose }` rather than bare callbacks because of a
+// pi-ai contract gap: pi-ai races `onManualCodeInput()` against the local
+// callback server (packages/ai/src/utils/oauth/anthropic.ts:210-253). When
+// the browser wins the race, pi-ai sets `result.code` and falls through to
+// token exchange WITHOUT calling `server.cancelWait()` on the manual side —
+// the manual `text()` prompt is left dangling in clack's render pipeline,
+// re-appearing after every subsequent log line. Without the dispose hook,
+// the user sees "Logged in to {Provider}" immediately followed by the stale
+// "paste the redirect URL here" prompt that's now meaningless. Each call
+// site (init/provider) MUST call `dispose()` in a finally after the OAuth
+// runner returns so the orphaned prompt aborts cleanly; clack honors the
+// signal by resolving the prompt with cancel state, the cancel branch
+// throws inside our callback, and pi-ai's outer `.catch()` swallows it
+// (since it stops awaiting the manual promise on the winning-browser path).
+export type OAuthCallbackHandle = {
+  callbacks: OAuthCallbacks
+  dispose: () => void
+}
+
+export function buildOAuthCallbacks(providerName: string): OAuthCallbackHandle {
+  const controller = new AbortController()
+  const { signal } = controller
   return {
-    onAuth: (url, instructions) => {
-      // Don't put the URL inside note(): clack wraps long lines with the box
-      // border `│` on each wrapped segment, which corrupts the URL when the
-      // user copy-pastes it. Keep instructional text in the box, but print
-      // the URL itself as a bare console.log line that any terminal will
-      // hyperlink intact.
-      const preamble = [
-        `Open this URL in your browser to sign in to ${providerName}.`,
-        '',
-        'If your browser shows "this site can\'t be reached" after you sign in,',
-        'copy the full address from the top of the browser and paste it below.',
-      ]
-      if (instructions) preamble.push('', instructions)
-      note(preamble.join('\n'), 'Browser login')
-      console.log(url)
-      console.log('')
-    },
-    onProgress: (message) => {
-      log.info(message)
-    },
-    onPrompt: async (message, placeholder) => {
-      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
-      if (isCancel(value)) return null
-      return value
-    },
-    onManualCodeInput: async () => {
-      const value = await text({
-        message:
-          'If your browser shows "this site can\'t be reached" after you sign in, copy the full address from the top of the browser and paste it here:',
-        placeholder: 'http://localhost:1455/auth/callback?code=...&state=...',
-      })
-      if (isCancel(value)) throw new Error('Login cancelled by user')
-      return value
+    dispose: () => controller.abort(),
+    callbacks: {
+      onAuth: (url, instructions) => {
+        // Don't put the URL inside note(): clack wraps long lines with the box
+        // border `│` on each wrapped segment, which corrupts the URL when the
+        // user copy-pastes it. Keep instructional text in the box, but print
+        // the URL itself as a bare console.log line that any terminal will
+        // hyperlink intact.
+        const preamble = [
+          `Open this URL in your browser to sign in to ${providerName}.`,
+          '',
+          'If your browser shows "this site can\'t be reached" after you sign in,',
+          'copy the full address from the top of the browser and paste it below.',
+        ]
+        if (instructions) preamble.push('', instructions)
+        note(preamble.join('\n'), 'Browser login')
+        console.log(url)
+        console.log('')
+      },
+      onProgress: (message) => {
+        log.info(message)
+      },
+      onPrompt: async (message, placeholder) => {
+        const value = await text({
+          message,
+          signal,
+          ...(placeholder !== undefined ? { placeholder } : {}),
+        })
+        if (isCancel(value)) return null
+        return value
+      },
+      onManualCodeInput: async () => {
+        const value = await text({
+          message:
+            'If your browser shows "this site can\'t be reached" after you sign in, copy the full address from the top of the browser and paste it here:',
+          placeholder: 'http://localhost:1455/auth/callback?code=...&state=...',
+          signal,
+        })
+        if (isCancel(value)) throw new Error('Login cancelled by user')
+        return value
+      },
     },
   }
 }

package/src/cli/provider.ts

@@ -367,10 +367,15 @@ async function runOAuthLogin(cwd: string, providerId: KnownProviderId): Promise<
   }
   const modelRef = `${providerId}/${ref}` as const
 
-  const runner = makeOAuthLoginRunner(buildOAuthCallbacks(provider.name))
-  const result = await runner({ cwd, model: modelRef as Parameters<typeof runner>[0]['model'] })
-  if (!result.ok) return { ok: false, reason: result.reason }
-  return { ok: true }
+  const { callbacks, dispose } = buildOAuthCallbacks(provider.name)
+  try {
+    const runner = makeOAuthLoginRunner(callbacks)
+    const result = await runner({ cwd, model: modelRef as Parameters<typeof runner>[0]['model'] })
+    if (!result.ok) return { ok: false, reason: result.reason }
+    return { ok: true }
+  } finally {
+    dispose()
+  }
 }
 
 function authHint(id: KnownProviderId): string {

package/src/cli/role.ts

@@ -95,8 +95,13 @@ const listSub = defineCommand({
   },
   async run() {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
-    const { loadConfigSync } = await import('@/config')
-    const config = loadConfigSync(cwd)
+    // Diagnostic command: route through `loadConfigSyncOrDefaults` (same
+    // soft-fail pattern as PR #288's `status`/`doctor` and the follow-up for
+    // `model list`) so a broken `typeclaw.json` doesn't crash the very
+    // command users reach for to see which roles the agent thinks it has.
+    // Defaults have no `roles` block, so the empty-state hint fires next.
+    const { loadConfigSyncOrDefaults } = await import('@/config')
+    const config = loadConfigSyncOrDefaults(cwd)
     if (!config.roles || Object.keys(config.roles).length === 0) {
       console.log(c.dim('No roles declared. Run `typeclaw role claim` to add one, or edit typeclaw.json by hand.'))
       return

package/src/cli/tunnel.ts

@@ -4,7 +4,7 @@ import { join } from 'node:path'
 import { select, text, isCancel, cancel, log } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
-import { loadConfigSync } from '@/config'
+import { loadConfigSync, validateConfig } from '@/config'
 import { resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir, isInitialized } from '@/init'
 import type { ClientMessage, ServerMessage, TunnelLogsServerMessage, TunnelSnapshot } from '@/shared'
@@ -168,6 +168,15 @@ export async function runTunnelAddFlow(
   args: AddArgs,
   prompts: TunnelPrompts = defaultPrompts,
 ): Promise<LiveResult<TunnelConfig>> {
+  // Strict gate before any read: a malformed or schema-invalid `typeclaw.json`
+  // would otherwise throw out of the subsequent `loadConfigSync` and surface
+  // as an uncaught exception instead of the clean exit-1-with-reason that
+  // every other LiveResult consumer expects. Same fence PR #288 documented
+  // for the `start`/`restart`/`reload` path: destructive paths route through
+  // `validateConfig` so the file's invariants are checked once, up front,
+  // and the rest of the flow can lean on them.
+  const validation = validateConfig(cwd)
+  if (!validation.ok) return { ok: false, reason: validation.reason }
   const config = loadConfigSync(cwd)
   if (config.tunnels.some((entry) => entry.name === args.name))
     return { ok: false, reason: `tunnel "${args.name}" already exists` }
@@ -206,6 +215,9 @@ export async function runTunnelAddFlow(
 }
 
 export function runTunnelRemoveFlow(cwd: string, args: RemoveArgs): LiveResult<{ removed: TunnelConfig }> {
+  // Same strict gate as `runTunnelAddFlow`. See the comment there for why.
+  const validation = validateConfig(cwd)
+  if (!validation.ok) return { ok: false, reason: validation.reason }
   const config = loadConfigSync(cwd)
   const tunnel = config.tunnels.find((entry) => entry.name === args.name)
   if (tunnel === undefined) return { ok: false, reason: `unknown tunnel: ${args.name}` }

package/src/cli/ui.ts

@@ -142,6 +142,27 @@ export const SLACK_APP_MANIFEST = {
       messages_tab_enabled: true,
       messages_tab_read_only_enabled: false,
     },
+    // Slash commands listed here appear in Slack's compose-box picker with
+    // their description as a tooltip. `url` is required by Slack's manifest
+    // schema even for Socket Mode bots, but is ignored at runtime when the
+    // app is in Socket Mode — Slack delivers `slash_commands` envelopes
+    // over the same WebSocket as message events. We point it at a
+    // deliberately-invalid placeholder (RFC 6761 reserved .invalid TLD)
+    // so a misconfigured (non-Socket-Mode) deployment fails fast rather
+    // than silently routing real slash invocations to a third-party URL.
+    slash_commands: [
+      {
+        command: '/stop',
+        description: 'Abort the current turn in this channel',
+        // usage_hint is intentionally omitted. Slack's manifest validator
+        // rejects an empty string ("Must be more than 0 characters") but
+        // the field is optional, so the cleanest answer is to leave it out
+        // rather than invent placeholder text for a command that takes no
+        // arguments.
+        url: 'https://example.invalid/typeclaw-uses-socket-mode',
+        should_escape: false,
+      },
+    ],
   },
   oauth_config: {
     scopes: {
@@ -150,13 +171,16 @@ export const SLACK_APP_MANIFEST = {
       // write scopes (chat, files, im/mpim/groups, pins, reactions) let the
       // agent post replies, upload attachments, open DMs, pin messages, and
       // react to messages. `channels:join` lets the bot self-join public
-      // channels it's invited to discuss in.
+      // channels it's invited to discuss in. `commands` is required for
+      // Slack to deliver `slash_commands` envelopes — without it, slash
+      // commands registered in `features` would silently fail to route.
       bot: [
         'app_mentions:read',
         'channels:history',
         'channels:join',
         'channels:read',
         'chat:write',
+        'commands',
         'emoji:read',
         'files:read',
         'files:write',

package/src/config/config.ts

@@ -420,15 +420,39 @@ export function expandMountPath(input: string, cwd: string): string {
 
 // Loaded eagerly from process.cwd()/typeclaw.json at module-import time so
 // citty arg defaults (e.g. config.port in src/cli/*.ts) see real values, not
-// hardcoded fallbacks. Missing file → schema defaults; malformed file → throw,
-// which surfaces during CLI startup instead of silently reverting to defaults
-// and confusing the user.
+// hardcoded fallbacks. Missing file → schema defaults; malformed file → ALSO
+// schema defaults plus a stderr warning.
+//
+// Why soft-fail and not throw: every CLI command — including diagnostic ones
+// (`typeclaw status`, `typeclaw doctor`, `typeclaw logs`, `typeclaw stop`,
+// `typeclaw usage`, `typeclaw tui`) — pays this eager-load cost through its
+// import graph, regardless of whether the command actually reads config. A
+// hard throw here turns every read-only diagnostic into a crash exactly when
+// the user needs the diagnostic to figure out what's wrong with their config.
+// `validateConfig` (called by `start`/`restart`/`reload`/host-side mutations)
+// is the strict gate for destructive paths; that's where malformed-config
+// errors should surface, not at module-import time.
 //
 // `config` is a module-import-time snapshot. Container-stage code that must
 // observe `typeclaw run` reloads should call `getConfig()` instead, which
 // returns the current swapped-in value. Host-stage CLI processes are
 // short-lived, so they keep using `config` directly.
-export const config: Config = loadConfigSync(process.cwd())
+export const config: Config = loadConfigSyncOrDefaults(process.cwd())
+
+export function loadConfigSyncOrDefaults(cwd: string, options: { warn?: (message: string) => void } = {}): Config {
+  try {
+    return loadConfigSync(cwd)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    const warn = options.warn ?? ((message: string) => process.stderr.write(message))
+    warn(
+      `warning: ${detail}\n` +
+        `warning: continuing with default config so diagnostic commands still work; ` +
+        `run \`typeclaw doctor\` or fix ${CONFIG_FILE} before \`typeclaw start\`/\`restart\`/\`reload\`.\n`,
+    )
+    return configSchema.parse({})
+  }
+}
 
 let current: Config = config
 

package/src/config/index.ts

@@ -10,6 +10,7 @@ export {
   gitSchema,
   gitignoreSchema,
   loadConfigSync,
+  loadConfigSyncOrDefaults,
   loadPluginConfigsSync,
   migrateLegacyConfigShape,
   modelsSchema,

package/src/config/models-mutation.ts

@@ -3,7 +3,7 @@ import { join } from 'node:path'
 
 import { commitSystemFileSync } from '@/git/system-commit'
 
-import { configSchema, loadConfigSync, validateConfig } from './config'
+import { configSchema, loadConfigSyncOrDefaults, validateConfig } from './config'
 import {
   KNOWN_PROVIDERS,
   listKnownModelRefs,
@@ -33,8 +33,16 @@ export type ModelProfileEntry = {
 
 export type ModelMutationResult = { ok: true } | { ok: false; reason: string }
 
+// `listModelProfiles` is the read-only path behind `typeclaw model list`, a
+// diagnostic command. It routes through `loadConfigSyncOrDefaults` (same
+// soft-fail pattern as `typeclaw status` / `doctor`, PR #288) so a broken
+// `typeclaw.json` doesn't crash the command users reach for to see what
+// model config the agent thinks it has. Mutation paths (`setProfile`,
+// `addProfile`, `removeProfile`) stay on the strict gate via `validateConfig`
+// in `writeModels`, because writing through a broken-on-disk file would
+// silently land schema-invalid bytes.
 export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.env): ModelProfileEntry[] {
-  const models = loadConfigSync(cwd).models
+  const models = loadConfigSyncOrDefaults(cwd).models
   const out: ModelProfileEntry[] = []
   for (const [profile, refs] of Object.entries(models)) {
     const headRef = refs[0]!