feat(adapter-claude-local): session-exhaustion backoff helpers (AIP-5933)

[yaverabbas]

Summary

Permanent upstream source fix for AIP-5916 session-exhaustion backoff guard.

Changes to src/server/parse.ts

• Add nextDailyResetUtc(now, resetHourUtc=22) — fallback reset time when session exhaustion gives no explicit clock in the error text
• Export isClaudeSessionExhaustionError as alias for isClaudeProviderQuotaError
• Extend extractClaudeRetryNotBefore to accept opts.sessionExhaustionFallbackResetHourUtc; falls back to nextDailyResetUtc when a provider-quota error has no reset clock

Changes to src/server/execute.ts

• Make toAdapterResult async
• Pass sessionExhaustionFallbackResetHourUtc: 22 on provider-quota paths
• Emit structured [paperclip] log when retry is scheduled for session exhaustion

Tracked in AIP-5933. Supersedes the in-place dist patch from AIP-5916.

[commitperclip]

Hey @yaverabbas! Before this PR can be reviewed, a few things need attention:

Missing or incomplete:

• Missing section: ## Thinking Path
• Missing section: ## What Changed
• Missing section: ## Verification
• Missing section: ## Risks
• Missing section: ## Model Used
• No linked issue or inline issue description found — either tag an existing issue with Fixes #NNN / Closes #NNN / Refs #NNN, or describe the underlying issue inline in the PR body following one of our issue templates (https://github.com/paperclipai/paperclip/tree/master/.github/ISSUE_TEMPLATE). See CONTRIBUTING.md → "Link Issues or Describe Them In-PR".
• Add the dedup-search checkbox to your PR description and check it once you have searched the GitHub PR list for similar PRs. See the PR template at .github/PULL_REQUEST_TEMPLATE.md and CONTRIBUTING.md → "Before You Start: Search First".
• You have changes to pnpm-lock.yaml — pr.yml will hard-fail this PR with a confusing message about lockfile edits. To fix: run pnpm install locally, exclude the lockfile from your commit, push again. The lockfile is regenerated automatically by the refresh bot on a schedule.

Informational:

• 📦 New dependencies added: @paperclipai/adapter-deflector. Review may take longer and new dependencies are less likely to be accepted — please check if existing deps cover this need.

Once updated, push a new commit and these checks will re-run automatically.

— commitperclip

[greptile-apps]

Greptile Summary

This PR ships two independent changes: session-exhaustion backoff helpers for the claude-local adapter (a nextDailyResetUtc fallback, a isClaudeSessionExhaustionError alias, and structured logging when a retry is scheduled), and a brand-new deflector_local adapter — a deterministic, non-LLM pre-check that auto-resolves issues matching a SQLite pattern KB.

• parse.ts adds nextDailyResetUtc and wires it into extractClaudeRetryNotBefore as a fallback when no explicit reset clock appears in the error text; execute.ts passes sessionExhaustionFallbackResetHourUtc: 22 on provider-quota paths and emits a [paperclip] log line when a retry is scheduled.
• The new deflector package includes a KB-backed pattern matcher, an audit logger, a CLI seed tool, a Docker smoke-test workflow, and full adapter plumbing (UI registry, server registry, display registry).
• The PR description omits the required PR template sections (thinking path, verification, risks, model used, checklist) and references internal ticket IDs (AIP-5933, AIP-5916) that are not accessible to public reviewers — both are CONTRIBUTING.md violations.

Confidence Score: 5/5

• The backoff logic is additive and conservative; the deflector adapter is clearly scoped to high-confidence, operator-configured patterns only.
• The claude-local changes are purely additive: a new date-math helper and an informational log line. The three previously-flagged issues (fallback applied to non-session quota types, log rejection aborting the quota result, missing re-export from the entry point) are real concerns but were raised in prior review threads and are not new findings here. The deflector adapter is self-contained with proper DB cleanup and conservative matching. The sync audit I/O is a quality concern but does not affect correctness in normal operation.
• No files require special attention beyond the open threads on packages/adapters/claude-local/src/server/parse.ts and packages/adapters/claude-local/src/server/execute.ts.

Important Files Changed

Filename	Overview
packages/adapters/claude-local/src/server/parse.ts	Adds nextDailyResetUtc, isClaudeSessionExhaustionError alias, CLAUDE_SESSION_EXHAUSTION_RE alias, and extends extractClaudeRetryNotBefore with a fallback reset hour. The fallback fires on any isClaudeProviderQuotaError hit (which includes weekly, 5-hour, and generic cap errors, not just session/daily ones), and neither new alias is re-exported from the package's server/index.ts entry point.
packages/adapters/claude-local/src/server/execute.ts	toAdapterResult is made async to allow awaiting the new informational onLog call when a provider-quota backoff is scheduled. If the caller-provided onLog rejects, the awaited log call propagates the rejection and aborts the function before returning the structured provider_quota result with retryNotBefore, so recovery receives a thrown error instead of the backoff schedule.
packages/adapters/deflector/src/server/execute.ts	New deflector adapter execute function. Logic is clear and conservative (only auto-resolves on high-confidence KB match + terminal origin). Synchronous appendAudit calls block the event loop on each invocation; DB is properly closed in a finally block.
packages/adapters/deflector/src/server/audit.ts	Audit logger using synchronous appendFileSync/mkdirSync, which blocks the event loop on every call. Should use async equivalents to avoid stalling concurrent adapter runs.
packages/adapters/deflector/src/server/match.ts	Pattern matching logic is straightforward and conservative: only high-confidence patterns fire, malformed regexes are caught and skipped, and origin-terminal checks guard against premature resolution.
.github/workflows/deflector-docker-smoke.yml	New smoke-test workflow that builds the deflector Docker image and validates Node.js + better-sqlite3 resolve correctly inside it. Well scoped with paths filter and timeout-minutes: 60.

_{Reviews (4): Last reviewed commit: "Merge pull request #2 from yaverabbas/fe..." | Re-trigger Greptile}

[greptile-apps]

Alias Missing From Package Entry Point

The package's server/index.ts uses an explicit named export list and does not re-export this new alias. A consumer importing isClaudeSessionExhaustionError from @paperclipai/adapter-claude-local/server therefore gets a TypeScript export error, despite the alias being declared as exported here.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/adapters/claude-local/src/server/parse.ts
Line: 529

Comment:
**Alias Missing From Package Entry Point**

The package's `server/index.ts` uses an explicit named export list and does not re-export this new alias. A consumer importing `isClaudeSessionExhaustionError` from `@paperclipai/adapter-claude-local/server` therefore gets a TypeScript export error, despite the alias being declared as exported here.

How can I resolve this? If you propose a fix, please make it concise.