typeclaw 0.4.0 → 0.5.0

package/src/bundled-plugins/security/policies/git-exfil.ts

@@ -1,8 +1,28 @@
+import type { SecuritySeverity } from '../permissions'
 import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
 import { getRemoteTaint, recordRemoteTaint } from './remote-taint-state'
 
 export const GUARD_GIT_EXFIL = 'gitExfil'
+// Classified `high` (audience-leak axis): `git push` sends every tracked
+// file to a remote git host. The host (GitHub/GitLab/attacker-controlled
+// box) is a third-party audience outside the operator's control loop.
+// Even a private remote owned by an attacker is now outside the
+// perimeter. No role auto-bypasses high — owner pushing from TUI must ack
+// each push. The historical per-guard string `security.bypass.gitExfil`
+// remains valid as an explicit grant for operators who knowingly want to
+// re-open the auto-bypass (see SKILL.md must-not-do guidance).
+export const GUARD_GIT_EXFIL_SEVERITY: SecuritySeverity = 'high'
 export const GUARD_GIT_REMOTE_TAINTED = 'gitRemoteTainted'
+// Classified `high` (audience-leak axis): same path as gitExfil, second
+// step. A push after a mid-session `git remote set-url` to an
+// attacker-controlled URL is exactly the breach pattern that motivated
+// the entire security plugin per PR #134. The recorder-vs-checker split
+// (see comment on recordGitRemoteTaintIfAny below) is still load-bearing:
+// the recorder fires for anyone who can run the underlying command (ack
+// or the per-guard `bypassGitExfil` grant), so even if an operator
+// explicitly grants `bypassGitExfil` to a role, the second-step taint
+// check still fires on the eventual push.
+export const GUARD_GIT_REMOTE_TAINTED_SEVERITY: SecuritySeverity = 'high'
 
 // Anchors we reuse: a `git` token must be at start-of-line or follow a shell
 // separator. This blocks `git push` while letting `cgit-something` through

package/src/bundled-plugins/security/policies/outbound-secret-scan.ts

@@ -1,6 +1,18 @@
+import type { SecuritySeverity } from '../permissions'
 import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
 
 export const GUARD_OUTBOUND_SECRET = 'outboundSecret'
+// Classified `high` (audience-leak axis): bypass posts credential-shaped
+// text to a chat channel whose readership is a third-party audience
+// outside the operator's control loop. Channel readers, push-notification
+// previews, search indexes, and other bots in the channel all see the
+// secret before the operator can intervene. Owner-in-public-channel is
+// the canonical motivating case: even owner asking the agent to "post the
+// deploy status" should not be able to silently include a stack-trace
+// `Bearer ghp_...` line. The whole point of the high tier is that
+// audience-leak guards require per-call ack from every role, including
+// owner — see AGENTS.md `## Permissions` rules of thumb.
+export const GUARD_OUTBOUND_SECRET_SEVERITY: SecuritySeverity = 'high'
 
 const SIGNATURE_PATTERNS: ReadonlyArray<{ kind: string; pattern: RegExp }> = [
   { kind: 'aws_access_key_id', pattern: /\b(?:AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ABIA|ACCA)[A-Z0-9]{16}\b/ },

package/src/bundled-plugins/security/policies/prompt-injection.ts

@@ -463,10 +463,30 @@ export function detectPromptInjection(prompt: string): InjectionMatch[] {
 
 const DEFENSE_MARKER = '[security/prompt-injection]'
 
+// Subagent prompts are constructed by trusted bundled code, not from raw
+// user input. The backup-diagnose subagent in particular embeds raw git
+// stderr (which legitimately contains literal "git push --help" hint
+// strings on fast-forward rejection or missing-upstream failures) — those
+// hits would otherwise trigger the git_exfil category and inject a "do
+// NOT run git push" rule that contradicts the subagent's own
+// system-prompt instructions to retry with an ack. Under the audience-
+// leak policy the runtime tool.before is the universal backstop for
+// `git push` regardless of role (no role auto-bypasses), so the prompt-
+// side git_exfil category is strictly redundant for subagent origins.
+// Other categories (system_prompt_dump, secret_demand,
+// fake_privileged_skill) still fire for subagents because their threats
+// (e.g. memory-logger ingesting an attacker's transcript) are real.
+function filterForOrigin(matches: InjectionMatch[], origin: SessionPromptEvent['origin']): InjectionMatch[] {
+  if (origin?.kind !== 'subagent') return matches
+  return matches.filter((m) => m.category !== 'git_exfil')
+}
+
 export function applyPromptInjectionDefense(event: SessionPromptEvent): InjectionMatch[] {
-  const matches = detectPromptInjection(event.prompt)
-  if (matches.length === 0) return matches
-  if (event.prompt.includes(DEFENSE_MARKER)) return matches
+  const allMatches = detectPromptInjection(event.prompt)
+  if (allMatches.length === 0) return allMatches
+  if (event.prompt.includes(DEFENSE_MARKER)) return allMatches
+  const matches = filterForOrigin(allMatches, event.origin)
+  if (matches.length === 0) return allMatches
 
   const categories = Array.from(new Set(matches.map((m) => m.category))).join(', ')
   const note = [

package/src/bundled-plugins/security/policies/secret-exfil-bash.ts

@@ -1,6 +1,13 @@
+import type { SecuritySeverity } from '../permissions'
 import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
 
 export const GUARD_SECRET_EXFIL_BASH = 'secretExfilBash'
+// Classified `medium` (silent-attack axis): bypass dumps the whole
+// environment (every API key, every token) into the agent's tool-result
+// buffer. No direct channel side effect — operator only sees on session
+// review — but the secrets are now in model context and one channel_send
+// away from a third-party audience. Silent at the moment of leak.
+export const GUARD_SECRET_EXFIL_BASH_SEVERITY: SecuritySeverity = 'medium'
 
 const DANGEROUS_COMMAND_PATTERNS: ReadonlyArray<{ pattern: RegExp; label: string }> = [
   { pattern: /(^|[\s;|&(`$])(env|printenv)([\s;|&)`]|$)/, label: 'env / printenv (full environment dump)' },

package/src/bundled-plugins/security/policies/secret-exfil-read.ts

@@ -1,8 +1,14 @@
 import path from 'node:path'
 
+import type { SecuritySeverity } from '../permissions'
 import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
 
 export const GUARD_SECRET_EXFIL_READ = 'secretExfilRead'
+// Classified `medium` (silent-attack axis): bypass returns `.env` /
+// credential-file contents into model context. Same shape as
+// secretExfilBash — silent at the moment of read, becomes catastrophic on
+// the next channel-side tool call that quotes it.
+export const GUARD_SECRET_EXFIL_READ_SEVERITY: SecuritySeverity = 'medium'
 
 const SENSITIVE_BASENAMES = new Set([
   '.env',

package/src/bundled-plugins/security/policies/session-search-secrets.ts

@@ -1,6 +1,15 @@
+import type { SecuritySeverity } from '../permissions'
 import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
 
 export const GUARD_SESSION_SEARCH_SECRETS = 'sessionSearchSecrets'
+// Classified `medium` (silent-attack axis): bypass returns secret-shaped
+// session-search hits into the agent's tool-result buffer. The operator
+// doesn't see the raw hits — the agent summarizes them — so the leak is
+// silent from the operator's perspective even though it's a read tool.
+// The hits then live in model context as a precondition for a later
+// channel_send leak; outboundSecret would catch the actual send, but
+// silent-recon-then-summarize is its own attack shape.
+export const GUARD_SESSION_SEARCH_SECRETS_SEVERITY: SecuritySeverity = 'medium'
 
 const SESSION_SEARCH_TOOLS: ReadonlySet<string> = new Set([
   'session_search',

package/src/bundled-plugins/security/policies/ssrf.ts

@@ -1,6 +1,12 @@
+import type { SecuritySeverity } from '../permissions'
 import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
 
 export const GUARD_SSRF = 'ssrf'
+// Classified `medium` (silent-attack axis): bypass lets `curl
+// http://169.254.169.254/...` return cloud-metadata IAM credentials into
+// model context. Silent — no channel side effect at the moment of fetch.
+// Catastrophic on follow-up because the model now has live cloud creds.
+export const GUARD_SSRF_SEVERITY: SecuritySeverity = 'medium'
 
 const ALWAYS_BLOCKED_HOSTS = new Set([
   'localhost',

package/src/bundled-plugins/security/policies/system-prompt-leak.ts

@@ -1,6 +1,13 @@
+import type { SecuritySeverity } from '../permissions'
 import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
 
 export const GUARD_SYSTEM_PROMPT_LEAK = 'systemPromptLeak'
+// Classified `high` (audience-leak axis): bypass posts TypeClaw runtime
+// fingerprints / system-prompt fragments to a chat. Same shape as
+// outboundSecret — third-party audience, no operator intervention before
+// the leak lands. Disclosure also enables recon for later targeted
+// prompt-injection attacks against this agent.
+export const GUARD_SYSTEM_PROMPT_LEAK_SEVERITY: SecuritySeverity = 'high'
 
 const FINGERPRINT_PATTERNS: ReadonlyArray<{ label: string; pattern: RegExp }> = [
   { label: 'TypeClaw runtime preamble', pattern: /You are a general-purpose AI agent running inside TypeClaw\./ },

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

@@ -175,7 +175,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         managedHooks = registration.repos.flatMap((r) =>
           r.action === 'created' || r.action === 'updated' ? [{ repo: r.repo, hookId: r.hookId }] : [],
         )
-        logRegistrationOutcome(logger, registration)
+        logRegistrationOutcome(logger, registration, options.secrets.auth.type)
       }
     },
     async stop(): Promise<void> {
@@ -264,14 +264,98 @@ function detectLegacyProviderHostSuffix(url: string): string | undefined {
   return undefined
 }
 
-function logRegistrationOutcome(logger: GithubAdapterLogger, result: WebhookRegistrationResult): void {
+function logRegistrationOutcome(
+  logger: GithubAdapterLogger,
+  result: WebhookRegistrationResult,
+  authType: 'pat' | 'app',
+): void {
+  const permissionFailures: Array<{ repo: string; status: number }> = []
   for (const r of result.repos) {
     if (r.action === 'created') logger.info(`[github] registered webhook ${r.hookId} on ${r.repo}`)
     else if (r.action === 'updated') {
       const tail = r.stalePruned > 0 ? ` (pruned ${r.stalePruned} stale)` : ''
       logger.info(`[github] updated webhook ${r.hookId} on ${r.repo}${tail}`)
-    } else logger.warn(`[github] webhook register failed for ${r.repo}: ${r.error}`)
+    } else {
+      logger.warn(`[github] webhook register failed for ${r.repo}: ${r.error}`)
+      const status = parseListHooksPermissionStatus(r.error)
+      if (status !== null) permissionFailures.push({ repo: r.repo, status })
+    }
+  }
+  // One guidance block per start() (not per repo) so a 10-repo permission
+  // failure doesn't paste the same paragraph 10 times. The names below MUST
+  // match the current github.com UI labels — see comment in
+  // buildPermissionGuidance.
+  if (permissionFailures.length > 0) {
+    logger.warn(buildPermissionGuidance(authType, permissionFailures))
+  }
+}
+
+// Parses webhook-register errors of the shape `list hooks failed: <status> <body>`.
+// Returns the status code when it matches the two shapes GitHub emits for
+// missing access on the list-hooks endpoint:
+//   - 404 Not Found: the token cannot see the repo at all (private repo
+//     gated behind missing repository access — GitHub returns 404 instead of
+//     403 to avoid leaking the existence of private repos).
+//   - 403 Forbidden: the token sees the repo but lacks webhook-management
+//     permission, OR is blocked by an org SSO/SAML authorization gate.
+// Returns null for any other error (network, malformed slug, create-hook
+// failures, etc.) so the guidance only fires on the actual symptom.
+export function parseListHooksPermissionStatus(error: string): number | null {
+  const match = error.match(/^list hooks failed: (404|403)\b/)
+  if (match === null) return null
+  return Number(match[1])
+}
+
+// The labels below intentionally mirror github.com's current UI verbatim so a
+// user can grep their settings page for the exact string. If GitHub renames
+// any of these in a future redesign, update both here and the
+// `permissionGuidance` tests in lifecycle.test.ts.
+//
+//   Fine-grained PAT:
+//     Settings → Developer settings → Personal access tokens → Fine-grained tokens
+//     "Resource owner", "Repository access", "Repository permissions" → "Webhooks" → "Read and write", "Metadata" → "Read-only"
+//   GitHub App:
+//     Settings → Developer settings → GitHub Apps → <app> → Permissions & events
+//     "Repository permissions" → "Webhooks" → "Read and write"
+//     Install/configure on the org: <app settings> → Install App / Configure → "Repository access"
+//   Classic PAT (legacy, still supported by GitHub but we don't surface it in
+//     channel-add prompts):
+//     Settings → Developer settings → Personal access tokens (classic)
+//     Scope: "admin:repo_hook" (or full "repo" for private repositories)
+export function buildPermissionGuidance(
+  authType: 'pat' | 'app',
+  failures: ReadonlyArray<{ repo: string; status: number }>,
+): string {
+  const repoList = failures.map((f) => `${f.repo} (${f.status})`).join(', ')
+  const lines: string[] = [
+    `[github] webhook setup needs more access for: ${repoList}.`,
+    '  - 404 from GitHub means the token cannot see the repo (GitHub hides private repos behind 404 instead of 403).',
+    '  - 403 means the token sees the repo but lacks webhook permission, or is blocked by org SAML/SSO.',
+    '',
+  ]
+  if (authType === 'pat') {
+    lines.push(
+      '  Fix (fine-grained personal access token):',
+      '    1. Open https://github.com/settings/personal-access-tokens and edit the token TypeClaw is using.',
+      '    2. Under "Resource owner", select the org that owns the failing repos (e.g. the org in the slug above).',
+      '    3. Under "Repository access", choose "Only select repositories" and add every failing repo (or pick "All repositories").',
+      '    4. Under "Repository permissions", set "Webhooks" to "Read and write" and "Metadata" to "Read-only".',
+      '    5. Save. If the org enforces SAML SSO, click "Configure SSO" next to the token and authorize the org.',
+      '',
+      '  Or (classic personal access token): grant the "admin:repo_hook" scope (or "repo" for private repos),',
+      '  and on a SAML-protected org click "Authorize" next to the token.',
+    )
+  } else {
+    lines.push(
+      '  Fix (GitHub App):',
+      '    1. Open https://github.com/settings/apps and edit the app TypeClaw is using.',
+      '    2. Under "Permissions & events" → "Repository permissions", set "Webhooks" to "Read and write". Save.',
+      '    3. From the app page, click "Install App" (or "Configure" if already installed) and select the org that owns the failing repos.',
+      '    4. Under "Repository access", choose "Only select repositories" and add every failing repo (or pick "All repositories").',
+      '    5. If the app permissions changed in step 2, install owners must accept the updated permissions from the install page before the new access takes effect.',
+    )
   }
+  return lines.join('\n')
 }
 
 function logDeregistrationOutcome(

package/src/channels/router.ts

@@ -78,6 +78,24 @@ export const MAX_TYPING_HEARTBEAT_MS = 2 * 60 * 1000
 export const SESSION_IDLE_MS = 30 * 60 * 1000
 export const SESSION_GC_INTERVAL_MS = 60 * 1000
 
+// Hard cap on tool-initiated outbound sends per (chat:thread) per turn.
+// The original loop-incident emitted ~50 sends in one turn; even
+// legitimate split replies rarely cross 8. 10 leaves headroom for
+// genuine multi-part answers while definitively stopping runaway loops.
+// Enforced inside router.send for `source: 'tool'` callers; system
+// recovery paths (`source: 'system'`) bypass.
+export const MAX_CHANNEL_SENDS_PER_TURN = 10
+// Rolling window for outbound send-rate telemetry. 5s matches Discord's
+// rate-limit shape (5 msg / 5 s / channel) and comfortably covers Slack's
+// 1 msg/s sustained. The window is observational; exceeding the burst
+// threshold below escalates the per-send log to a warning.
+export const SEND_RATE_WINDOW_MS = 5_000
+// Above this in-window count, the per-send log line escalates to a
+// `send_rate_warning` so a burst stands out in the log stream. Every
+// send still emits a structured log line regardless of rate — this
+// constant only controls when the warning marker appears.
+export const SEND_RATE_WARN_THRESHOLD = 3
+
 /**
  * Maximum age of the last engaged inbound before the next inbound triggers a fresh session.
  * Set to the LLM provider's KV-cache TTL (5 min) so the new session's system prompt is
@@ -244,6 +262,26 @@ type LiveSession = {
   // router.send so the hint reflects the position of the about-to-happen send
   // (n-th in a row), nudging the model to yield without forcing it to.
   consecutiveSends: Map<string, number>
+  // Per-(chat:thread) text of the last reserved bot send. Set
+  // SYNCHRONOUSLY inside router.send before the outbound callback awaits,
+  // so two concurrent `router.send` calls for the same target cannot both
+  // pass the duplicate guard. Cleared on every new prompt batch (same
+  // lifecycle as `consecutiveSends`). The scope is "last 1 send within
+  // this turn" so legitimate multi-part replies (different bodies) and
+  // across-turn callbacks ("yes, I'm here" twice) are not blocked. Empty
+  // strings are normalized to undefined before storage so attachments-only
+  // sends never poison the tracker. The fuzzy-match upgrade is intentionally
+  // deferred — exact-match has zero false-positive risk by construction.
+  lastSentText: Map<string, string>
+  // Per-(chat:thread) ring of send timestamps (epoch ms) within the rolling
+  // SEND_RATE_WINDOW_MS window. Append-on-send, prune-on-read. Lifecycle is
+  // wall-clock (NOT cleared on new prompt batches) because rate is a
+  // property of the channel over time, not the agent's turn structure — a
+  // burst that straddles two adjacent turns is still a burst from the chat
+  // platform's POV. Telemetry-only today; the rate is logged when count
+  // crosses SEND_RATE_LOG_THRESHOLD so production data can inform a
+  // future hard cap without picking a threshold out of thin air.
+  sendTimestamps: Map<string, number[]>
   successfulChannelSends: number
   // Loop-guard state. See PEER_BOT_TURNS_WINDOW_MS / MAX_* constants
   // above. Updated in route() on every engaged peer-bot inbound, reset on
@@ -264,15 +302,35 @@ type ChannelCommandContext = {
   event: InboundMessage
 }
 
+export type SendSource = 'tool' | 'system'
+
+export type SendOptions = {
+  source?: SendSource
+}
+
+export const DUPLICATE_SEND_ERROR =
+  'Duplicate not sent. Do not call channel_send/channel_reply again this turn. ' +
+  'End with NO_REPLY unless you have genuinely new, non-redundant information.'
+
+export const TURN_CAP_ERROR =
+  `Send-cap reached for this turn (${MAX_CHANNEL_SENDS_PER_TURN} messages already sent to this conversation). ` +
+  'End your turn now. The user can prompt you again for more output.'
+
 export type ChannelRouter = {
   route: (event: InboundMessage) => Promise<void>
-  send: (msg: OutboundMessage) => Promise<SendResult>
+  send: (msg: OutboundMessage, opts?: SendOptions) => Promise<SendResult>
   getConsecutiveSendCount: (target: {
     adapter: ChannelKey['adapter']
     workspace: string
     chat: string
     thread?: string | null
   }) => number
+  getSendRate: (target: {
+    adapter: ChannelKey['adapter']
+    workspace: string
+    chat: string
+    thread?: string | null
+  }) => { count: number; windowMs: number }
   registerOutbound: (adapter: ChannelKey['adapter'], cb: OutboundCallback) => void
   unregisterOutbound: (adapter: ChannelKey['adapter'], cb: OutboundCallback) => void
   registerTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
@@ -719,6 +777,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         lastTurnAuthorIds: new Set(),
         consecutiveAborts: 0,
         consecutiveSends: new Map(),
+        lastSentText: new Map(),
+        sendTimestamps: new Map(),
         successfulChannelSends: 0,
         recentEngagedPeerBotTurns: [],
         consecutiveEngagedPeerBotTurns: 0,
@@ -1011,7 +1071,10 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
         live.currentTurnAuthorId = batch.length > 0 ? batch[batch.length - 1]!.authorId : null
         live.currentTurnAuthorIds = new Set(batch.map((m) => m.authorId))
-        if (batch.length > 0) live.consecutiveSends.clear()
+        if (batch.length > 0) {
+          live.consecutiveSends.clear()
+          live.lastSentText.clear()
+        }
 
         // Update the live origin holder so this turn's tool.before events
         // carry the current actor's id. The DefaultResourceLoader still
@@ -1036,6 +1099,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         } catch (err) {
           logger.error(`[channels] ${live.keyId}: prompt threw: ${describe(err)}`)
           live.consecutiveSends.clear()
+          live.lastSentText.clear()
         } finally {
           await fireSessionTurnEnd(live)
         }
@@ -1108,13 +1172,16 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(
           `[channels] ${channelKeyId(key)}: claim ${outcome.kind} author=${event.authorId} id=${event.externalMessageId}`,
         )
-        await send({
-          adapter: event.adapter,
-          workspace: event.workspace,
-          chat: event.chat,
-          thread: event.thread,
-          text: outcome.reply,
-        })
+        await send(
+          {
+            adapter: event.adapter,
+            workspace: event.workspace,
+            chat: event.chat,
+            thread: event.thread,
+            text: outcome.reply,
+          },
+          { source: 'system' },
+        )
         return
       }
     }
@@ -1421,10 +1488,52 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     return lastError
   }
 
-  const send = async (msg: OutboundMessage): Promise<SendResult> => {
+  const send = async (msg: OutboundMessage, opts?: SendOptions): Promise<SendResult> => {
+    const source: SendSource = opts?.source ?? 'tool'
     const callbacks = outboundCallbacks.get(msg.adapter)
     if (!callbacks || callbacks.size === 0) {
-      return { ok: false, error: `no adapter registered for "${msg.adapter}"` }
+      return { ok: false, error: `no adapter registered for "${msg.adapter}"`, code: 'no-adapter' }
+    }
+
+    const keyId = channelKeyId({
+      adapter: msg.adapter,
+      workspace: msg.workspace,
+      chat: msg.chat,
+      thread: msg.thread ?? null,
+    })
+    const live = liveSessions.get(keyId)
+    const sendKey = consecutiveSendKey(msg.chat, msg.thread)
+    const text = normalizeSendText(msg.text)
+
+    // Central enforcement. Tool-initiated sends are subject to two policies:
+    // a per-turn count cap (kills runaway loops regardless of content) and
+    // an exact-duplicate guard (kills the byte-identical-spam sub-mode).
+    // Both checks AND the state mutations they consult happen synchronously
+    // before any `await`, so two concurrent `router.send` calls for the same
+    // target (the parallel-tool-execution race) cannot both pass: the
+    // second observer sees the first one's increment / lastSentText write.
+    // System sources (validateChannelTurn recovery, role-claim reply) bypass
+    // — those are one-shot paths the policy doesn't apply to.
+    let priorLastSentText: string | undefined
+    let reserved = false
+    if (live && source === 'tool') {
+      const currentCount = live.consecutiveSends.get(sendKey) ?? 0
+      if (currentCount >= MAX_CHANNEL_SENDS_PER_TURN) {
+        return { ok: false, error: TURN_CAP_ERROR, code: 'turn-cap' }
+      }
+      if (text !== undefined && live.lastSentText.get(sendKey) === text) {
+        return { ok: false, error: DUPLICATE_SEND_ERROR, code: 'duplicate' }
+      }
+      // Reserve the slot before awaiting. If the callback rejects we roll
+      // back below; if it succeeds we keep the increment. The slot reserve
+      // is what makes parallel tool calls safe. We also snapshot the prior
+      // lastSentText so a transient delivery failure can be retried with
+      // the same text — the dup-guard exists to stop runaway loops, not to
+      // strand the model on a flaky adapter.
+      priorLastSentText = live.lastSentText.get(sendKey)
+      live.consecutiveSends.set(sendKey, currentCount + 1)
+      if (text !== undefined) live.lastSentText.set(sendKey, text)
+      reserved = true
     }
 
     // Snapshot the callbacks before iterating so a callback that mutates the
@@ -1443,16 +1552,20 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
 
     if (!delivered) {
-      return { ok: false, error: lastError ?? 'no callback accepted the outbound' }
+      // Roll back the slot reservation so a failed send doesn't burn cap
+      // budget or poison the dup-guard. Restoring lastSentText to its
+      // prior value (which may be undefined) lets a legitimate retry of
+      // the same text succeed — the dup-guard is for loops, not flake.
+      if (live && reserved) {
+        const after = (live.consecutiveSends.get(sendKey) ?? 1) - 1
+        if (after <= 0) live.consecutiveSends.delete(sendKey)
+        else live.consecutiveSends.set(sendKey, after)
+        if (priorLastSentText === undefined) live.lastSentText.delete(sendKey)
+        else live.lastSentText.set(sendKey, priorLastSentText)
+      }
+      return { ok: false, error: lastError ?? 'no callback accepted the outbound', code: 'callback-rejected' }
     }
 
-    const keyId = channelKeyId({
-      adapter: msg.adapter,
-      workspace: msg.workspace,
-      chat: msg.chat,
-      thread: msg.thread ?? null,
-    })
-    const live = liveSessions.get(keyId)
     if (live) {
       live.successfulChannelSends++
       // Don't stop the heartbeat here: the agent may still be mid-turn and
@@ -1477,8 +1590,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           grantStickyForReplyTargets(stickyLedger, keyId, targetIds, adapterConfig.engagement, now())
         }
       }
-      const sendKey = consecutiveSendKey(msg.chat, msg.thread)
-      live.consecutiveSends.set(sendKey, (live.consecutiveSends.get(sendKey) ?? 0) + 1)
+      const turnCount = live.consecutiveSends.get(sendKey) ?? 0
+      const rateCount = recordSendTimestamp(live, sendKey, now())
+      const level = rateCount >= SEND_RATE_WARN_THRESHOLD ? 'warn' : 'info'
+      const warn = rateCount >= SEND_RATE_WARN_THRESHOLD ? ' send_rate_warning' : ''
+      const textLen = text !== undefined ? text.length : 0
+      const fields = `source=${source} turn=${turnCount} rate=${rateCount}/${SEND_RATE_WINDOW_MS}ms text_len=${textLen}`
+      logger[level](`[channels] ${live.keyId} send ${fields}${warn}`)
     }
 
     return { ok: true }
@@ -1498,13 +1616,16 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     logger.warn(
       `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool text_len=${assistantText.length}`,
     )
-    const result = await send({
-      adapter: live.key.adapter,
-      workspace: live.key.workspace,
-      chat: live.key.chat,
-      thread: live.key.thread,
-      text: assistantText,
-    })
+    const result = await send(
+      {
+        adapter: live.key.adapter,
+        workspace: live.key.workspace,
+        chat: live.key.chat,
+        thread: live.key.thread,
+        text: assistantText,
+      },
+      { source: 'system' },
+    )
     if (!result.ok) {
       logger.warn(`[channels] ${live.keyId}: recovery send failed: ${result.error}`)
     }
@@ -1527,6 +1648,30 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     return live.consecutiveSends.get(consecutiveSendKey(target.chat, target.thread)) ?? 0
   }
 
+  const getSendRate = (target: {
+    adapter: ChannelKey['adapter']
+    workspace: string
+    chat: string
+    thread?: string | null
+  }): { count: number; windowMs: number } => {
+    const keyId = channelKeyId({
+      adapter: target.adapter,
+      workspace: target.workspace,
+      chat: target.chat,
+      thread: target.thread ?? null,
+    })
+    const live = liveSessions.get(keyId)
+    if (!live) return { count: 0, windowMs: SEND_RATE_WINDOW_MS }
+    const sendKey = consecutiveSendKey(target.chat, target.thread)
+    const buf = live.sendTimestamps.get(sendKey)
+    if (!buf || buf.length === 0) return { count: 0, windowMs: SEND_RATE_WINDOW_MS }
+    const cutoff = now() - SEND_RATE_WINDOW_MS
+    let i = 0
+    while (i < buf.length && buf[i]! <= cutoff) i++
+    if (i > 0) buf.splice(0, i)
+    return { count: buf.length, windowMs: SEND_RATE_WINDOW_MS }
+  }
+
   const tearDownLive = async (live: LiveSession): Promise<void> => {
     live.destroyed = true
     if (live.debounceTimer) clearTimeout(live.debounceTimer)
@@ -1585,6 +1730,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     route,
     send,
     getConsecutiveSendCount,
+    getSendRate,
     registerOutbound,
     unregisterOutbound,
     registerTyping,
@@ -1759,6 +1905,26 @@ function consecutiveSendKey(chat: string, thread: string | null | undefined): st
   return `${chat}:${thread ?? ''}`
 }
 
+function normalizeSendText(text: string | undefined): string | undefined {
+  if (text === undefined) return undefined
+  if (text === '') return undefined
+  return text
+}
+
+function recordSendTimestamp(live: LiveSession, sendKey: string, ts: number): number {
+  const buf = live.sendTimestamps.get(sendKey)
+  const cutoff = ts - SEND_RATE_WINDOW_MS
+  if (!buf) {
+    live.sendTimestamps.set(sendKey, [ts])
+    return 1
+  }
+  let i = 0
+  while (i < buf.length && buf[i]! <= cutoff) i++
+  if (i > 0) buf.splice(0, i)
+  buf.push(ts)
+  return buf.length
+}
+
 function dmMembership(fetchedAt: number): MembershipCount {
   return { humans: 1, bots: 1, fetchedAt, truncated: false }
 }

package/src/channels/types.ts

@@ -84,7 +84,9 @@ export type OutboundMessage = {
   attachments?: OutboundAttachment[]
 }
 
-export type SendResult = { ok: true } | { ok: false; error: string }
+export type SendErrorCode = 'duplicate' | 'turn-cap' | 'no-adapter' | 'callback-rejected'
+
+export type SendResult = { ok: true } | { ok: false; error: string; code?: SendErrorCode }
 
 export type OutboundCallback = (msg: OutboundMessage) => Promise<SendResult>