Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/desktop/src/main/ai/built-in-tools.ts`:
- Around line 37-41: The execute handler for this built-in tool currently casts
args.query and args.limit without validation; add runtime checks in the execute
function to validate that args.query is a non-empty string and args.limit (if
provided) is a positive integer before calling deps.searchNotes, returning a
structured error response (e.g., { ok: false, error: '...' }) when validation
fails; use the same symbols (execute, args.query, args.limit, deps.searchNotes)
so the fix is localized to this function and avoid relying solely on the JSON
schema.

In `@apps/desktop/src/main/ai/ipc-ai.ts`:
- Around line 96-105: The IPC handlers (ipcMain.handle('ai:cancel', etc.) mutate
shared state in activeHandles without verifying the caller; store the
originating sender id (use _event.sender.id / webContents.id) when creating each
entry in activeHandles and, in all handlers that inspect or modify entries
(including the cancel path using requestId and handle.abort), first lookup the
entry and compare its stored ownerId to _event.sender.id, rejecting the call if
they differ; update the activeHandles entry structure to include ownerId,
enforce the ownership check in all related handlers (the cancel handler and the
others flagged around lines 165–190), and only then perform abort(), delete(),
or resolve operations.
- Around line 107-130: The current ai:validate handler calls service.chat and
immediately aborts the returned handle so executeChat never runs and invalid
providers/keys/baseUrls still return ok: true; update the ai:validate
implementation (ipcMain.handle for 'ai:validate') to perform a real validation:
either call the provider's validation method (e.g., provider.validate(...) or
provider.listModels(...)) obtained from the registry/service, or if using
service.chat keep the handle but consume handle.events until you receive the
first non-'start' event (or an error) before deciding success, then
abort/cleanup the stream and return the appropriate {ok:false, error:...} on
failure instead of returning true prematurely; ensure errors thrown by
executeChat or provider calls are caught and converted to a message.

In `@apps/desktop/src/main/ai/setup.ts`:
- Line 13: The code currently force-casts net.fetch to FetchFn when registering
AnthropicProvider (registry.register(new AnthropicProvider(net.fetch as unknown
as FetchFn))), which hides a type mismatch; replace the cast with an explicit
adapter or runtime-validated wrapper that maps Electron's net.fetch shape to the
package's FetchFn contract (e.g., implement an adaptNetFetchToFetchFn function
and pass adaptNetFetchToFetchFn(net.fetch) into new AnthropicProvider), and add
a small runtime assertion/test that the adapted function conforms to FetchFn
behavior before registering to ensure the contract is explicit and safe.

In `@apps/desktop/src/main/index.ts`:
- Around line 2354-2360: The createNote handler currently returns a silent empty
id on failure; change createNote (the exported async function that calls
createNoteOperation with noteRepo) to propagate the failure as an error result
instead of returning { id: '' } — e.g., when createNoteOperation returns
result.ok === false, return an object matching the tool executor contract (like
{ ok: false, error: result.error || 'createNote failed' }) so callers (and the
built-in-tools.ts executor) can handle the failure rather than receiving a bogus
empty id.
- Around line 2350-2352: The listNotebooks implementation returns noteCount: 0
for every notebook; update listNotebooks to populate the real note counts by
using the repository method that returns metadata (e.g., nbRepo.getWithMetadata
or an equivalent), or by calling nbRepo.getWithMetadata(nb.id) per notebook (in
parallel) and mapping metadata.noteCount into the returned object instead of
hardcoding 0; alternatively, if the repository cannot provide counts, document
that noteCount is unsupported rather than returning 0.

In `@apps/desktop/src/renderer/components/ai/AiPanel.tsx`:
- Around line 171-175: The error case in the stream handler (the `case 'error'`
block) is tearing down UI state for transient retryable errors emitted by
`withRetry()`; update the `case 'error'` handler so it only calls setError,
setLoading(false) and clears activeRequestRef.current when the error is a
final/non-retryable failure (mirror the same guard used in the initial-command
listener before `onCommandExecuted()` / `commandCleanup()`), otherwise ignore
transient/backoff errors so later retried `text`/`done` events from the same
request are processed; locate the `case 'error'` block and add the
retryable/final error check (using the same predicate or property the
initial-command listener uses) before performing teardown.
- Around line 277-346: The command-specific onEvent handler races with the
shared listener because it compares the incoming requestId to
activeRequestRef.current which the shared listener may clear first; capture the
command's request id when you create the handler (e.g. const commandRequestId =
activeRequestRef.current) and use that captured commandRequestId inside the
closure instead of activeRequestRef.current so the
replaceSelection/insertAtCursor logic and onCommandExecuted() always run for
this command's events; update the conditional (if (requestId !==
commandRequestId) return;) and keep the rest of the handler (accumulatedText,
switch cases, commandCleanup()) the same.
- Around line 228-240: The handler for the 'tool_complete' event unconditionally
sets status: 'complete', which masks rejected/failed results; update the
setToolCalls callback (inside the 'tool_complete' case) to inspect e.result.ok
and any existing status (keep 'rejected' if already set) and set status to
'complete' only when e.result.ok is true, otherwise set a failure status (e.g.,
'failed' or preserve 'rejected') and attach e.result; reference the existing
variables setToolCalls, event (cast to e), e.call.id, existing, and e.result
when implementing the change.

In `@apps/desktop/src/renderer/components/ai/ToolCallBlock.tsx`:
- Around line 72-81: The Run/Cancel buttons in ToolCallBlock (rendered when
status === 'pending_confirmation') can be double-clicked because status updates
are asynchronous; wrap onConfirm and onReject with a local loading boolean
(e.g., isActioning) in the ToolCallBlock component, set isActioning = true
immediately in the click handlers before invoking the passed callbacks, and
disable both buttons when isActioning is true (or while status !==
'pending_confirmation'); also ensure isActioning is cleared if the parent status
prop changes or after the callback's promise resolves/rejects so the UI stays in
sync.
- Around line 47-70: The header currently uses a non-interactive div with
onClick (the element rendering className "ai-tool-call-header" that toggles
expanded via setExpanded and reads expanded) so keyboard users can't activate
it; replace the div with an actual interactive element (preferably a <button>)
or at minimum add role="button", tabIndex={0} and an onKeyDown handler that
calls setExpanded on Enter/Space, and ensure aria-expanded={expanded} and an
accessible label are present; also update CSS to reset button default styles so
the visual remains the same for the element that replaces the div.

In `@apps/desktop/src/renderer/stores/settings/schema.ts`:
- Around line 64-67: SettingsSchemaV2 currently ends up requiring the new
AiSettings.provider field, collapsing v2/v3 boundaries; fix by creating a
v2-specific AI settings type (e.g., AiSettingsV2) that omits or excludes the
provider field (or explicitly defines the older shape) and use that type inside
SettingsSchemaV2 instead of AiSettings so migrations/validation keep the real
persisted v2 shape separate from the new v3 AiSettings; update any references
that build SettingsSchemaV2 to use AiSettingsV2 (or an Omit<AiSettings,
'provider'> type) and keep AiSettings as the v3 shape with provider.

In `@apps/desktop/src/renderer/stores/settings/settingsStore.ts`:
- Around line 96-107: The code assigns settings = mutable before running the v3
migration, so the migration changes to mutable (adding ai.provider and bumping
version) are never returned; fix by ensuring the post-migration state is
returned — either move the settings = mutable as SettingsSchema assignment to
after the migration block or reassign settings = mutable as SettingsSchema right
before the return; reference the variables/members named settings, mutable,
SettingsSchema and the v3 migration block that sets version: 3 and ai: {
provider: 'anthropic', ...mutable.ai } so the returned object includes the
migrated values.

In `@apps/desktop/src/renderer/styles/ai-panel.css`:
- Line 305: The CSS rule uses the deprecated value "word-break: break-word";
replace that declaration with a non-deprecated alternative by either using
"overflow-wrap: break-word;" for natural wrapping or "word-break: break-all;"
for aggressive breaking—update the rule that currently contains "word-break:
break-word;" to one of these alternatives (or include both: "overflow-wrap:
break-word;" and a fallback "word-break: break-all;") so the selector no longer
relies on the deprecated value.

In `@apps/web/app/`(marketing)/auth/verify/AuthVerifyContent.tsx:
- Around line 42-43: Replace hardcoded hex color classes in AuthVerifyContent
(e.g., the h1 with className "text-2xl font-bold text-[`#f4f4f5`] mb-3" and the p
with "text-[`#a1a1aa`] mb-6", plus other occurrences noted around lines 63-65,
82-83, 94-102) with Tailwind theme tokens or named color classes such as
text-zinc-50 and text-zinc-400, or better yet use semantic theme tokens you’ve
defined (e.g., text-foreground, text-muted) from your
Tailwind/@readied/product-config; also normalize border opacity notation to
border-white/6 where applicable. Ensure you update the className strings on the
relevant JSX elements in AuthVerifyContent.tsx (h1, p, and any other elements
flagged) to use the token names instead of hex values.

In `@apps/web/app/`(marketing)/pricing/page.tsx:
- Around line 112-132: The current annual NumberTicker uses decimalPlaces={0},
which will silently round if the yearly price ever includes cents; update the
annual block to compute decimalPlaces dynamically (e.g., decimalPlaces =
annualAmountCents % 100 === 0 ? 0 : 2) and pass that value to the NumberTicker
for annualPrice (or, if you don't have annualAmountCents, derive it from
annualPrice by converting to cents with safe rounding and then checking cents %
100), ensuring the NumberTicker usage (component name NumberTicker and prop
decimalPlaces) reflects the computed value rather than a hardcoded 0.

In `@apps/web/components/Footer.tsx`:
- Around line 137-150: The social link rendering is duplicated: the map over
socialLinks in Footer (the block rendering icon-only links) repeats the same
href/label/target/rel/aria pattern already used earlier; extract a small
reusable SocialLink component (e.g., SocialLink({ social, iconOnly?: boolean }))
and replace both maps to call it with iconOnly=true for the icon-row and
iconOnly=false for the labeled row, preserving className variants and props
(href, target, rel, aria-label, and rendering social.icon and optionally
social.label).

In `@CLAUDE.md`:
- Around line 265-268: The fenced code block containing "Renderer (AiPanel) →
IPC → Main (ipc-ai.ts) → AIService → ProviderRegistry → Provider → SSE stream ←
batched LLMEvents (text/error/done) ←" is missing a language identifier; update
that opening ``` to include a language (for example ```text) so the code block
conforms to MD040 and renders correctly.

In `@docs/superpowers/specs/2026-03-14-ai-core-provider-abstraction-design.md`:
- Around line 44-112: The fenced code blocks in the spec are missing language
identifiers which breaks syntax highlighting; update each fenced block by adding
an appropriate language tag (use text for ASCII diagrams and the specific
language where applicable). For example, add ```text to the block that begins
with "Renderer" and likewise tag the blocks containing "AIService",
"ContextBuilder", "ProviderRegistry", and "LLMProvider" (or replace with a more
specific language tag if the block contains real code rather than an ASCII
diagram). Ensure every triple-backtick fence in the file has a language
specifier.

In `@docs/superpowers/specs/2026-03-18-ai-tool-use-design.md`:
- Around line 185-199: The public API doc for chatWithTools currently declares
it returning ChatHandle but must return the richer ToolChatHandle because
tool-enabled chats stream both ToolLoopEvent and LLMEvent; update the signature
for chatWithTools(request: ToolChatRequest): ToolChatHandle (and any related
docs) so the return type reflects ToolLoopEvent support and reference
ToolChatRequest, chatWithTools, ToolChatHandle, ToolLoopEvent and LLMEvent when
making the change.

In `@package.json`:
- Around line 59-64: The pnpm.overrides entry is forcing `@types/react` and
`@types/react-dom` to React 18 versions which conflicts with apps/web's
react@^19.0.0; update the overrides so they do not globally pin React 18 types —
either remove the global pnpm.overrides for "@types/react" and
"@types/react-dom" and instead add package-scoped overrides for packages that
still need React 18, or change the override to the matching React 19 type
versions; look for the pnpm.overrides block (symbols: "pnpm", "overrides",
"@types/react", "@types/react-dom") and adjust to either remove the global pins
or replace them with per-package overrides targeting the specific packages or
update to React 19 `@types` versions to match apps/web's react@^19.0.0.

In `@packages/ai-core/src/ai-command-types.test.ts`:
- Around line 1-232: This file duplicates the same test suite for
resolveTemplate, validateAiCommandDefinition, validateAiCommandPreset, and
serializePreset/parsePreset that exists elsewhere; remove this duplicate test
file (or consolidate by deleting its contents) so the tests only exist in one
location, ensuring only one set of describe blocks referencing resolveTemplate,
validateAiCommandDefinition, validateAiCommandPreset, serializePreset, and
parsePreset remains in the repo.

In `@packages/ai-core/src/ai-service.ts`:
- Around line 100-170: The request lifecycle in executeChatWithTools currently
does provider lookup, model discovery, context building, and emits the initial
'start' event outside the try/finally so activeRequests.delete and the final
'done' yield can be skipped if any of those steps throws or the iterator is
closed; refactor executeChatWithTools (and the other generator at lines 173-247)
to move provider = this.registry.get(...), model discovery (models.find...),
context construction (buildContext), creation/emission of the initial 'start'
event, and the runToolLoop logic into a single outer try/catch/finally block so
that activeRequests.delete(requestId) and the final 'done' yield always run,
preserve the inner catch behavior that yields a provider_error on non-abort
errors, and keep runToolLoop/toolLoop handling the same inside the try.

In `@packages/ai-core/src/context-builder.ts`:
- Around line 14-20: The ContextSources.interface declares toolResults but
buildContext does not use it; add a brief clarifying comment above the
toolResults property in the ContextSources interface stating it is reserved for
future tool loop support and currently unused by buildContext (or remove the
property if you prefer to keep the interface minimal) so future readers know
this is intentional; reference the ContextSources interface and the buildContext
function in the comment to make the intent explicit.
- Around line 93-95: buildContext computes available as budget.maxContextTokens
- budget.maxResponseTokens but doesn't guard against negative values; update the
start of buildContext to clamp available to a non‑negative value (e.g. available
= Math.max(0, budget.maxContextTokens - budget.maxResponseTokens)) and, if
appropriate for your flow, handle the zero case early (return an empty/zeroed
ContextBuildResult or skip token allocation) so downstream logic using available
won't misbehave; reference: buildContext, ContextBudget, available.

In `@packages/ai-core/src/providers/anthropic.ts`:
- Around line 191-198: When JSON.parse(block.jsonBuf || '{}') fails we currently
swallow the error and return an empty args object; change the catch to capture
the parse error and surface it in the yielded tool call so downstream handlers
can detect malformed JSON. Specifically, in the try/catch around JSON.parse
(reference block.jsonBuf and the args variable) keep the fallback args = {} but
store the caught error message (e.g., parseError or rawJson) and include that in
the yielded object for type:'tool_call' (the same place you call yield { type:
'tool_call', id: block.id, name: block.name, args }) before calling
toolBlocks.delete(index). Ensure the parse error info is non-throwing and
concise so existing consumers can opt-in to logging or error handling.
- Around line 36-46: The classifyHttpStatus function currently maps any 400 to
context_overflow which is too broad; update the logic so classifyHttpStatus (or
the Anthropic response handler that calls it) examines the response body/error
payload for specific Anthropic validation messages (e.g., schema errors,
invalid_params, or explicit "context length" indicators) and only return {code:
'context_overflow', retryable: false} when the body clearly indicates
token/context limits; otherwise map known validation errors to distinct codes
(e.g., 'invalid_request' or 'validation_error') or default to provider_error,
and ensure this check is implemented where the response body is available (the
error handling path that invokes classifyHttpStatus).

In `@packages/ai-core/src/providers/sse-parser.ts`:
- Around line 15-23: The SSE parsing assumes '\n\n' framing and drops
EOF-terminated frames; update the logic around reader.read/decoder.decode and
buffer handling to normalize CRLF to LF (e.g., replace '\r\n' with '\n' on
incoming chunks) before splitting, split on '\n\n' to get complete events, and
when reader.read() returns done=true flush/process any remaining buffer content
as a final event (don't just break). Also add a regression test that sends
frames terminated with '\r\n\r\n' and a frame that ends at EOF (CRLF+EOF) to
ensure both are yielded.

In `@packages/ai-core/src/retry.ts`:
- Around line 33-37: The auth error check uses msg.includes('invalid.*key')
which treats the pattern as a literal string and misses messages like "invalid
api key"; in the function where msg is defined (variable msg) replace the
literal include with a regex test (e.g., /invalid.*key/i.test(msg)) or check for
both 'invalid' and 'key' substrings case-insensitively so that messages such as
"invalid api key" correctly return 'auth_failed' from the classification logic.
- Around line 57-75: The retry loop currently restarts fn() even after yielding
payload events which causes duplicate outputs; add a flag (e.g., emittedPayload)
that is set when yielding any payload event (such as event.type === 'text' or
'tool_call' or any non-control event), and only allow the retry logic inside the
for-await when emittedPayload is false; specifically, in the block handling
event.type === 'error' and retryable codes, check emittedPayload and if true
treat the error as non-retryable (yield { ...event, retryable: false } and
return) instead of breaking to retry; update the loop around fn(), and
references to attempt, opts.maxRetries, opts.retryableCodes and fn() accordingly
so retries only happen before any payload escapes the wrapper.

In `@packages/ai-core/src/tool-registry.ts`:
- Around line 20-27: The unregister callback is not instance-safe because it
always deletes by tool.name; change register (in register(tool:
ToolRegistration)) to store a registration token alongside the tool in the
this.tools map (e.g., map value becomes an object {tool, token}) and capture
that token in the returned disposer closure; when the disposer runs, only delete
this.tools.get(tool.name) if its stored token equals the captured token so a
later re-registration with the same name isn't removed by an earlier disposer.

In `@packages/ai-core/tests/ai-service.test.ts`:
- Around line 124-135: The test currently only checks that handles returned from
service.chat have requestId values but doesn't assert that cancelAll() actually
aborts them; update the test using the handles (from AIServiceImpl.chat) to
consume their event streams or returned promises and assert that the
terminal/done event includes cancelled: true (e.g., subscribe or await
handle.events or handle.result and verify an event object with done: {
cancelled: true } for both handles after calling service.cancelAll()), keeping
existing setup with ProviderRegistry and createMockProvider.

In `@packages/ai-core/tests/providers/anthropic.test.ts`:
- Around line 102-112: The test for 401 currently inspects properties of
errorEvent without asserting it exists, so add an existence assertion before
property checks: after collecting events with collectEvents(provider) and
locating errorEvent (const errorEvent = events.find(...)), add
expect(errorEvent).toBeDefined() (or equivalent) to ensure the test fails if no
error event was emitted, then keep the existing checks on errorEvent.code and
errorEvent.retryable for AnthropicProvider handling of a 401.

In `@packages/ai-core/tests/retry.test.ts`:
- Around line 79-88: The mock async iterator in the test never signals
completion because its second next() return uses done: false for the `{ type:
'done', durationMs: 50 }` event; update the iterator returned by the test (the
next() closure that closes over `yielded`) to return `done: true` for the
`'done'` event so the iterator terminates correctly (i.e., adjust the second
return of the `next()` method from `{ done: false, value: { type: 'done', ... }
}` to `{ done: true, value: { type: 'done', ... } }`).

In `@packages/ai-core/tests/tool-loop.test.ts`:
- Around line 3-7: Remove the unused type import and alias: delete ToolCall from
the import list in the top of the test (keep ToolLoopOptions and ToolLoopEvent)
and remove the unused type alias ChatFn (the "type ChatFn = ..." declaration);
this cleans up unused symbols while leaving LLMEvent, ChatOptions, LLMProvider,
and ProviderConfig intact.

---

Outside diff comments:
In `@apps/desktop/src/renderer/pages/settings/sections/AiSection.tsx`:
- Around line 50-53: The hardcoded modelOptions array in AiSection is showing
Claude models regardless of ai.provider; replace this with provider-aware logic:
either call window.readied.ai.listModels(ai.provider) inside the AiSection
component (e.g., on provider change) to populate modelOptions dynamically, or
filter a master models list by ai.provider before setting modelOptions; also
update any UI label text that says "Claude model" to a provider-agnostic string
and apply the same fix where modelOptions is duplicated (the other modelOptions
usage referenced in the file). Ensure you reference and update the modelOptions
variable, the ai.provider state, and the call site using
window.readied.ai.listModels so the dropdown reflects the selected provider.