typeclaw 0.37.4 → 0.37.6

package/src/bundled-plugins/github-cli-auth/index.ts

@@ -7,7 +7,7 @@ import { createApproveIdempotencyGuard } from './approve-idempotency'
 import { createGithubEffectiveApprovalResolver, createGithubHeadShaResolver } from './effective-approval'
 import { analyzeGhCommand, effectiveGhTokensForAuthenticatedUserEndpoint } from './gh-command'
 import { ensureGitAskPassHelper } from './git-askpass'
-import { analyzeGitCommand, defaultGitResolvers } from './git-command'
+import { analyzeGitCommand, defaultGitResolvers, resolveGhDefaultRepoFromCwd } from './git-command'
 import { checkGraphqlAuthNudge } from './graphql-auth-nudge'
 import { commitReviewIfSucceeded, noteReviewCommand } from './review-recorder'
 import { classifyGhToken, shouldMintAppToken } from './token-class'
@@ -72,6 +72,35 @@ export default definePlugin({
 
     type HookResult = void | { block: true; reason: string }
 
+    // A TRUSTED repo to fill in for a repo-less `gh` command, resolved from
+    // sources the command author cannot forge: (1) a GitHub channel session's
+    // own repo (origin.workspace comes from the signed webhook payload), then
+    // (2) the working tree's `origin` remote. NOT from any `-R`/path in the
+    // command (that is the attacker-controllable input the parser already
+    // handles). The slug is still gated by the repos[] allowlist at mint time.
+    const resolveTrustedFallbackRepo = async (origin: SessionOrigin | undefined): Promise<string | undefined> => {
+      if (origin?.kind === 'channel' && origin.adapter === 'github' && origin.workspace !== '') {
+        return origin.workspace
+      }
+      const fromCwd = await resolveGhDefaultRepoFromCwd(ctx.agentDir, defaultGitResolvers)
+      return fromCwd ?? undefined
+    }
+
+    // When a repo-less `gh` is blocked but a trusted repo IS available, show the
+    // exact single-bare rewrite so the agent recovers in one step instead of
+    // guessing. Composition blocks get a split-the-script instruction. The
+    // returned text is appended to the block reason (synchronous, always seen).
+    const buildGhBlockGuidance = (code: string, fallbackRepo: string | undefined): string => {
+      const slug = fallbackRepo ?? 'owner/repo'
+      if (code === 'composition') {
+        return (
+          ` Run each gh as its own single bare command, e.g. \`gh label edit <name> -R ${slug} --name ...\` —` +
+          ' not inside a function, `if`/`then`, `&&`, `;`, or `$(...)`.'
+        )
+      }
+      return ` For example: \`gh <cmd> -R ${slug}\` as a single bare command.`
+    }
+
     // 'fall-through' means "not a repo-targeting gh command" so the caller can
     // try the git path on the same command (e.g. `git ... # gh` substrings).
     const handleGhCommand = async (params: {
@@ -91,7 +120,26 @@ export default definePlugin({
       }
       if (review.dump !== null) return review.dump
 
-      const decision = analyzeGhCommand(command)
+      // Analyze first WITHOUT the fallback: an explicit `-R`/path repo must win,
+      // and we only pay for fallback resolution (a git subprocess) when the
+      // command is otherwise repo-less. A trusted fallback is then applied ONLY to
+      // a `missing-repo` block (never to composition/non-literal/multi-owner/api),
+      // and re-analysis re-runs the SAME composition gate, so a compound command
+      // still blocks. `fallbackRepoUsed` marks an inject that came from the
+      // fallback so we also set GH_REPO (gh needs the repo, not just the token).
+      let decision = analyzeGhCommand(command)
+      let fallbackRepo: string | undefined
+      let fallbackRepoUsed = false
+      if (decision.kind === 'block' && decision.code === 'missing-repo') {
+        fallbackRepo = await resolveTrustedFallbackRepo(event.origin)
+        if (fallbackRepo !== undefined) {
+          const withFallback = analyzeGhCommand(command, fallbackRepo)
+          if (withFallback.kind === 'inject') {
+            decision = withFallback
+            fallbackRepoUsed = true
+          }
+        }
+      }
 
       // `/user` classifies as pass-through (no repo to mint for), so this block
       // must run BEFORE the pass-through return. Resolve the EFFECTIVE token per
@@ -140,7 +188,10 @@ export default definePlugin({
         // NOT apply — a PAT needs no per-repo mint — so we never surface it here.
         if (runsUnsandboxed(event.origin)) {
           if (decision.kind === 'inject') {
-            event.args[TYPECLAW_INTERNAL_BASH_ENV] = { GH_TOKEN: process.env.GH_TOKEN as string }
+            event.args[TYPECLAW_INTERNAL_BASH_ENV] = {
+              GH_TOKEN: process.env.GH_TOKEN as string,
+              ...(fallbackRepoUsed && fallbackRepo !== undefined ? { GH_REPO: fallbackRepo } : {}),
+            }
           }
           return
         }
@@ -148,14 +199,18 @@ export default definePlugin({
         // available (a PAT must NOT suppress it, or the original silent-failure
         // bug returns); otherwise block with guidance rather than failing mute.
         if (!shouldMintAppToken(undefined, hasAppTokenResolver())) {
-          if (decision.kind === 'block') return { block: true, reason: decision.reason }
+          if (decision.kind === 'block') {
+            return { block: true, reason: decision.reason + buildGhBlockGuidance(decision.code, fallbackRepo) }
+          }
           warnSandboxedPatWithheldOnce()
           return { block: true, reason: sandboxedPatWithheldReason }
         }
         mintForSandboxedPat = true
       }
 
-      if (decision.kind === 'block') return { block: true, reason: decision.reason }
+      if (decision.kind === 'block') {
+        return { block: true, reason: decision.reason + buildGhBlockGuidance(decision.code, fallbackRepo) }
+      }
 
       // No App auth (no App-class GH_TOKEN and no live minter): leave whatever
       // is seeded so `gh` fails honestly rather than us guessing a token. The
@@ -166,8 +221,14 @@ export default definePlugin({
       if (result.kind === 'unavailable') return { block: true, reason: result.reason }
       // Inject via the internal env overlay (delivered to the spawn / bwrap
       // --setenv by the bash wrapper) so the token never enters the command
-      // string, where it could leak through logs or later hooks.
-      event.args[TYPECLAW_INTERNAL_BASH_ENV] = { GH_TOKEN: result.token }
+      // string, where it could leak through logs or later hooks. When the repo
+      // came from a trusted fallback (not an explicit -R), also set GH_REPO so
+      // `gh` actually targets it — a token alone leaves the repo unresolved.
+      // GH_REPO is non-secret; the token still scopes reach to that repo.
+      event.args[TYPECLAW_INTERNAL_BASH_ENV] = {
+        GH_TOKEN: result.token,
+        ...(fallbackRepoUsed ? { GH_REPO: decision.repoSlug } : {}),
+      }
       return
     }
 

package/src/bundled-plugins/memory/index.ts

@@ -155,12 +155,17 @@ const VECTOR_TURN_TOP_K = 10
 // without loading the ~279 MB model, or `hybridSearch` to fake retrieval while
 // testing hook orchestration — without leaking state across other tests in the
 // same worker. Production uses the real `embed` and `hybridSearch`.
-type MemoryPluginDeps = {
+export type MemoryPluginDeps = {
   hybridSearch: typeof hybridSearch
   queryEmbedFn: EmbedFn
+  openAppendVectorStore: (agentDir: string) => VectorStore
 }
 
-const defaultDeps: MemoryPluginDeps = { hybridSearch, queryEmbedFn: embed }
+const defaultDeps: MemoryPluginDeps = {
+  hybridSearch,
+  queryEmbedFn: embed,
+  openAppendVectorStore: (agentDir) => VectorStore.open(join(agentDir, 'memory', '.vectors', 'index.db')),
+}
 
 // Builds the per-turn user-prompt memory block for a vector agent. Non-channel
 // turns always use top-K hybrid search, regardless of total shard size. Repeated
@@ -231,7 +236,7 @@ async function renderVectorTurnMemory(
   }
 }
 
-function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
+export function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
   return definePlugin({
     configSchema: memoryConfigSchema,
     plugin: async (ctx) => {
@@ -401,9 +406,7 @@ function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
       }
 
       // Open a long-lived VectorStore for append-time indexing when vector is enabled.
-      const appendVectorStore = ctx.config.vector.enabled
-        ? VectorStore.open(join(ctx.agentDir, 'memory', '.vectors', 'index.db'))
-        : undefined
+      const appendVectorStore = ctx.config.vector.enabled ? deps.openAppendVectorStore(ctx.agentDir) : undefined
 
       return {
         subagents: {

package/src/bundled-plugins/memory/load-memory.ts

@@ -6,6 +6,7 @@ import type { SessionOrigin } from '@/agent/session-origin'
 import { buildInjectionPlan, DEFAULT_INJECTION_BUDGET_BYTES, type InjectionPlan } from './injection-plan'
 import { loadAllShards, type TopicShard } from './load-shards'
 import { topicsDir } from './paths'
+import { slugIsHeadingEcho } from './slug'
 import type { DedupedRetrievedItem } from './turn-dedup'
 
 const MAX_FILE_BYTES = 12 * 1024
@@ -130,7 +131,7 @@ export function renderRetrievedMemorySection(
       lines.push(`## ${item.heading}`)
       lines.push(item.excerpt.trimEnd(), '')
     } else if (item.source === 'topic' || item.source === 'reference') {
-      lines.push(`- ${item.heading} \`${item.key}\``)
+      lines.push(topicIndexEntry(item.heading, item.key))
     } else {
       lines.push(`- ${item.heading} _(recent observation)_`)
     }
@@ -150,11 +151,24 @@ export function renderTopicIndexMemorySection(
   if (options.origin?.kind === 'channel') lines.push(...CHANNEL_MEMORY_BOUNDARY, '')
   lines.push(topicIndexDirective(options), '')
   for (const shard of shards) {
-    lines.push(`- ${shard.frontmatter.heading} \`${shard.slug}\``)
+    lines.push(topicIndexEntry(shard.frontmatter.heading, shard.slug))
   }
   return lines.join('\n').trimEnd()
 }
 
+// A topic-index line names a topic so the model can decide whether to open it
+// (the slug is the `memory_search({ topic })` key). When the slug is just a kebab
+// echo of the heading the heading adds no signal, so render the slug alone; keep
+// both when they diverge (e.g. `gh-api-labels-array-syntax` vs "GitHub API label
+// management in the agent environment") or when the heading has no ASCII form
+// (e.g. CJK), where `slugIsHeadingEcho` returns false and the readable name stays.
+function topicIndexEntry(heading: string, slug: string): string {
+  if (slugIsHeadingEcho(heading, slug)) {
+    return `- \`${slug}\``
+  }
+  return `- ${heading} \`${slug}\``
+}
+
 function topicIndexDirective(options: Pick<LoadMemoryOptions, 'origin'>): string {
   if (options.origin?.kind === 'channel') {
     return 'Memory shown as headings only in channels. Call `memory_search({ topic: "<slug>" })` with a slug below to read a full body.'

package/src/bundled-plugins/memory/slug.ts

@@ -20,6 +20,25 @@ export function headingToSlug(heading: string, existingSlugs: Set<string>): stri
   return slug
 }
 
+// True only when `slug` is a clean kebab echo of `heading` (the readable form
+// adds nothing the slug doesn't). `headingToSlug` maps every non-ASCII letter,
+// ideograph, or symbol to `-` (or to an `untitled-<hash>` when nothing survives),
+// so a heading like `한글 memo` slugifies to `memo` and an all-CJK/emoji heading to
+// the fallback — collapsing either would drop the only human-readable name. Guard
+// by requiring the diacritic-folded heading to consist solely of ASCII
+// alphanumerics and separators/punctuation; any surviving CJK/emoji/symbol means
+// normalization discarded content, so it is never an echo. (Diacritics are
+// transliterated, not dropped — `café` → `cafe` stays a legitimate echo.)
+const ECHO_SAFE_HEADING = /^[A-Za-z0-9\s\p{P}]*$/u
+
+export function slugIsHeadingEcho(heading: string, slug: string): boolean {
+  const folded = heading.normalize('NFD').replace(/[\u0300-\u036f]/g, '')
+  if (!ECHO_SAFE_HEADING.test(folded)) {
+    return false
+  }
+  return headingToSlug(heading, new Set<string>()) === slug
+}
+
 function normalizeHeading(heading: string): string {
   let normalized = heading.normalize('NFD').replace(/[\u0300-\u036f]/g, '')
 

package/src/bundled-plugins/security/policies/private-surface-read.ts

@@ -178,7 +178,10 @@ function matchHidden(
   }
   for (const dir of deniedDirs) {
     const realDir = realpathRealIntendedPath(dir)
-    if (resolved === realDir || resolved.startsWith(`${realDir}/`)) return dir
+    // realpathRealIntendedPath joins with the platform separator, so the
+    // under-dir test must use path.sep too — a hardcoded "/" never matches the
+    // "\"-joined paths a win32 test runner produces.
+    if (resolved === realDir || resolved.startsWith(`${realDir}${path.sep}`)) return dir
   }
   return undefined
 }

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

@@ -61,56 +61,81 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     }
 
     const delivery = req.headers.get('x-github-delivery') ?? ''
-    if (delivery !== '' && options.dedup.has(delivery)) {
-      options.logger.info(`[github] duplicate delivery ignored id=${delivery}`)
-      return ok()
-    }
-
     const event = req.headers.get('x-github-event') ?? ''
     const payload = parseJson(body)
     if (payload === null) return ok()
-    const action = readString(payload, 'action')
-    if (!isGithubEventAllowed(options.allowlist(), event, action)) return ok()
-
-    const selfId = options.selfId()
-    const selfLogin = options.selfLogin()
-    const author = readAuthor(event, payload)
-    if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
-      maybeScheduleDecoyReviewerDrop({ event, action, payload, selfLogin, options })
-      options.logger.info(
-        `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
-      )
-      return ok()
-    }
+    // The HTTP request is only transport; event handling is the shared core.
+    await processVerifiedGithubDelivery(options, { event, delivery, payload })
+    return ok()
+  }
+}
 
-    // A push to an open PR (`synchronize`) is not a message to react to — it is
-    // a trigger to re-evaluate the bot's own outstanding review obligations on
-    // this PR: unresolved review threads it authored AND a sticky
-    // CHANGES_REQUESTED block (which leaves no threads when filed as a top-level
-    // verdict — the black hole this path closes). Both need an API round-trip,
-    // so it runs OFF the ACK path (like the decoy-reviewer drop) and only wakes a
-    // session when an obligation is outstanding. Returning here also keeps
-    // synchronize out of the generic awareness-only fallthrough below.
-    if (event === 'pull_request' && action === 'synchronize') {
-      if (delivery !== '') options.dedup.add(delivery)
-      scheduleReviewFollowup({ payload, selfLogin, options })
-      return ok()
+// Post-verification core shared by the live HTTP handler AND the missed-delivery
+// recovery sweep (recover-failed-deliveries.ts), which pulls lost payloads from
+// GitHub's authenticated deliveries API and re-injects them with no HTTP request
+// or signature. Routing both through this one function is the load-bearing
+// invariant: recovery must never become a second, divergent event pipeline.
+// `delivery` is the `X-GitHub-Delivery` GUID (stable across redeliveries, equal
+// to a delivery's `guid`) used as the dedup key, so a recovered event and its
+// later/duplicate live delivery collapse to one route. HMAC is the caller's job:
+// the live handler verifies the body; the sweep trusts the authenticated API.
+export async function processVerifiedGithubDelivery(
+  options: GithubWebhookHandlerOptions,
+  input: { event: string; delivery: string; payload: Record<string, unknown> },
+): Promise<void> {
+  const { event, delivery, payload } = input
+  if (delivery !== '') {
+    if (options.dedup.has(delivery)) {
+      options.logger.info(`[github] duplicate delivery ignored id=${delivery}`)
+      return
     }
+    // Reserve the delivery id synchronously, BEFORE the awaits below, so a live
+    // webhook and the recovery sweep can never both clear the dedup gate for the
+    // same event and route it twice. JS is single-threaded: nothing else runs
+    // between this has-check and add, so the reservation is atomic. The awaits
+    // and classify that follow are all throw-safe, so reserving early cannot
+    // strand a routable event.
+    options.dedup.add(delivery)
+  }
 
-    const teamIsBotMember = await resolveTeamMembership(event, payload, options)
-    const reviewCommentParent = await resolveReviewCommentParent(event, payload, selfId, selfLogin, options)
-    const classified = classifyGithubInbound(event, payload, selfLogin, {
-      teamIsBotMember,
-      authType: options.authType?.() ?? 'pat',
-      reviewOn: options.reviewOn?.() ?? 'review_requested',
-      ...(reviewCommentParent !== null ? { reviewCommentParent } : {}),
-    })
-    if (classified === null) return ok()
-
-    if (delivery !== '') options.dedup.add(delivery)
-    options.route(withApprovalPolicy(classified, options.allowApprove?.() ?? true))
-    return ok()
+  const action = readString(payload, 'action')
+  if (!isGithubEventAllowed(options.allowlist(), event, action)) return
+
+  const selfId = options.selfId()
+  const selfLogin = options.selfLogin()
+  const author = readAuthor(event, payload)
+  if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
+    maybeScheduleDecoyReviewerDrop({ event, action, payload, selfLogin, options })
+    options.logger.info(
+      `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
+    )
+    return
   }
+
+  // A push to an open PR (`synchronize`) is not a message to react to — it is
+  // a trigger to re-evaluate the bot's own outstanding review obligations on
+  // this PR: unresolved review threads it authored AND a sticky
+  // CHANGES_REQUESTED block (which leaves no threads when filed as a top-level
+  // verdict — the black hole this path closes). Both need an API round-trip,
+  // so it runs OFF the ACK path (like the decoy-reviewer drop) and only wakes a
+  // session when an obligation is outstanding. Returning here also keeps
+  // synchronize out of the generic awareness-only fallthrough below.
+  if (event === 'pull_request' && action === 'synchronize') {
+    scheduleReviewFollowup({ payload, selfLogin, options })
+    return
+  }
+
+  const teamIsBotMember = await resolveTeamMembership(event, payload, options)
+  const reviewCommentParent = await resolveReviewCommentParent(event, payload, selfId, selfLogin, options)
+  const classified = classifyGithubInbound(event, payload, selfLogin, {
+    teamIsBotMember,
+    authType: options.authType?.() ?? 'pat',
+    reviewOn: options.reviewOn?.() ?? 'review_requested',
+    ...(reviewCommentParent !== null ? { reviewCommentParent } : {}),
+  })
+  if (classified === null) return
+
+  options.route(withApprovalPolicy(classified, options.allowApprove?.() ?? true))
 }
 
 export const PR_APPROVAL_DISABLED_NOTE =

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

@@ -11,7 +11,7 @@ import { createDeliveryDedup } from './dedup'
 import { findPermissionGaps } from './event-permissions'
 import { createGithubFetchAttachmentCallback } from './fetch-attachment'
 import { createGithubHistoryCallback } from './history'
-import { createGithubWebhookHandler } from './inbound'
+import { createGithubWebhookHandler, processVerifiedGithubDelivery, type GithubWebhookHandlerOptions } from './inbound'
 import { applyManagedPath, buildManagedPath, resolveAgentId } from './managed-path'
 import { createGithubMembershipResolver } from './membership'
 import { createGithubOutboundCallback } from './outbound'
@@ -22,6 +22,7 @@ import {
 } from './permission-guidance'
 import { createGithubReactionCallback, createGithubRemoveReactionCallback } from './reactions'
 import { reconcileOpenPrs } from './reconcile-open-prs'
+import { createRecoveredGuidLog, recoverFailedGithubDeliveries } from './recover-failed-deliveries'
 import { createGithubReviewStateResolver } from './review-state'
 import { createGithubReviewThreadResolver } from './review-thread-resolver'
 import { createTeamMembershipChecker } from './team-membership'
@@ -67,6 +68,10 @@ 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 }
+  // How often to sweep each managed hook's GitHub delivery log for events whose
+  // inbound delivery failed (and that GitHub never redelivered), re-injecting
+  // them through the live event path. Zero disables the sweep. Default: 5 min.
+  deliveryRecoveryIntervalMs?: number
   // 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
@@ -89,6 +94,12 @@ const consoleLogger: GithubAdapterLogger = {
 
 const DEFAULT_WEBHOOK_REGISTRATION_DELAY_MS = 2_000
 const DEFAULT_TOKEN_REFRESH_INTERVAL_MS = 30 * 60 * 1000
+const DEFAULT_DELIVERY_RECOVERY_INTERVAL_MS = 5 * 60 * 1000
+// GitHub retains the delivery log for 3 days; sweep a little under that so a
+// failed delivery is always still listable on the next interval.
+const DELIVERY_RECOVERY_LOOKBACK_MS = 70 * 60 * 60 * 1000
+// Bounds an LLM-session storm if a bad tunnel window drops a large burst.
+const MAX_RECOVERED_PER_SWEEP = 50
 
 export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapter {
   const logger = options.logger ?? consoleLogger
@@ -105,8 +116,15 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
   let started = false
   let managedHooks: ReadonlyArray<{ repo: string; hookId: number }> = []
   let tokenRefreshTimer: { clear: () => void } | null = null
+  let deliveryRecoveryTimer: { clear: () => void } | null = null
   let unregisterTokenBridge: (() => void) | null = null
   const workspaceByChat = new Map<string, string>()
+  const setIntervalFn =
+    options.setInterval ??
+    ((handler: () => void, ms: number) => {
+      const timer = setInterval(handler, ms)
+      return { clear: () => clearInterval(timer) }
+    })
 
   const rememberWorkspace = (workspace: string, chat: string): void => {
     workspaceByChat.set(chat, workspace)
@@ -174,7 +192,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         logger.error(`[github] route failed: ${err instanceof Error ? err.message : String(err)}`)
       })
   }
-  const handler = createGithubWebhookHandler({
+  const handlerOptions: GithubWebhookHandlerOptions = {
     webhookSecret,
     dedup,
     allowlist: () => options.configRef().eventAllowlist,
@@ -188,7 +206,8 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     fetchImpl,
     logger,
     route: routeInbound,
-  })
+  }
+  const handler = createGithubWebhookHandler(handlerOptions)
 
   return {
     async start(): Promise<void> {
@@ -251,12 +270,6 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
               )
             })
           }
-          const setIntervalFn =
-            options.setInterval ??
-            ((handler: () => void, ms: number) => {
-              const timer = setInterval(handler, ms)
-              return { clear: () => clearInterval(timer) }
-            })
           tokenRefreshTimer = setIntervalFn(refresh, tokenRefreshIntervalMs)
         }
       } else {
@@ -355,10 +368,45 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
           logger.warn(`[github] reconcile pass failed: ${err instanceof Error ? err.message : String(err)}`)
         })
       }
+      // Periodically recover inbound deliveries that failed at the tunnel and
+      // were never redelivered (the cloudflare-quick 502 loss). Registered only
+      // when we manage hooks to query, and driven by the same injectable timer
+      // as the token refresh. The first sweep fires after one interval — NOT
+      // inside start() — so start() stays free of surprise API traffic; the
+      // reconcile pass above already covers the review-needed case immediately.
+      const deliveryRecoveryIntervalMs = options.deliveryRecoveryIntervalMs ?? DEFAULT_DELIVERY_RECOVERY_INTERVAL_MS
+      if (managedHooks.length > 0 && deliveryRecoveryIntervalMs > 0) {
+        // Created once and captured by `sweep`, so recovery idempotency persists
+        // across ticks even when the shared live dedup evicts the guid.
+        const recoveredLog = createRecoveredGuidLog(DELIVERY_RECOVERY_LOOKBACK_MS)
+        const sweep = () => {
+          recoverFailedGithubDeliveries({
+            hooks: managedHooks,
+            token: (repoSlug: string) => auth.token({ repoSlug }),
+            process: (input) => processVerifiedGithubDelivery(handlerOptions, input),
+            alreadySeen: (guid: string) => dedup.has(guid),
+            recoveredLog,
+            lookbackMs: DELIVERY_RECOVERY_LOOKBACK_MS,
+            maxPerSweep: MAX_RECOVERED_PER_SWEEP,
+            logger,
+            fetchImpl,
+          }).catch((err: unknown) => {
+            logger.warn(`[github] delivery recovery sweep failed: ${err instanceof Error ? err.message : String(err)}`)
+          })
+        }
+        deliveryRecoveryTimer = setIntervalFn(sweep, deliveryRecoveryIntervalMs)
+      }
     },
     async stop(): Promise<void> {
       if (!started) return
       started = false
+      // Stop the recovery sweep first: its async work outlives the synchronous
+      // unregister calls below, and a tick landing mid-teardown would query a
+      // hook we're about to deregister and could route during shutdown.
+      if (deliveryRecoveryTimer !== null) {
+        deliveryRecoveryTimer.clear()
+        deliveryRecoveryTimer = null
+      }
       options.router.unregisterOutbound('github', outbound)
       options.router.unregisterReaction('github', reaction)
       options.router.unregisterRemoveReaction('github', removeReaction)