Fix workspace-scoped Codex skill discovery

[Quicksaver]

PR ID: 3059
PR URL: #3059
PR TITLE: Fix workspace-scoped Codex skill discovery

Summary

Fix Codex repo-local skill discovery by resolving skills for the active project or worktree cwd instead of relying on the provider-wide status snapshot.

The implementation adds a workspace-scoped provider-skills RPC and a shared web/mobile resolution policy so composer suggestions and rendered skill chips refresh for the correct workspace without leaking stale skills across workspace, environment, or provider changes.

What Changed

• Add server.listProviderSkills contracts, WebSocket and local API handlers, and environment-query wiring keyed by environment, provider instance, and cwd.
• Add ProviderSkillsLister to return snapshot skills for non-Codex or disabled Codex providers and run Codex skills/list in the validated workspace cwd for enabled Codex providers.
• Prepare the configured Codex home and forward configured launch arguments before each probe, and return bounded structured errors for provider lookup, settings, cwd, home-preparation, timeout, and app-server failures while projecting both Error instances and plain objects through one bounded diagnostic path.
• Coalesce requests by provider and normalized workspace root with a short TTL cache for successful lookups only, keep failed probes immediately retryable, bound cache capacity and concurrent probes, and terminate short-lived Codex app-server processes when requests finish or time out.
• Run Codex provider status probes with the configured server cwd instead of the backend process cwd.
• Share workspace-skill target preparation, query-state resolution, snapshot retention, fallback selection, and error formatting across web and mobile adapters: preserve settled skills during a same-workspace refresh, clear them while switching targets or after a failed refresh, and fall back to provider snapshot skills after empty or failed lookups while keeping errors visible, without refreshing workspace probes when only client-side fallback skills change.
• Align mobile workspace-skill lookup with environment connectivity and lazy activation: disconnected clients retain only verified same-workspace skills or provider fallback with a reconnect error, inactive same-workspace lookups preserve their verified snapshot, and pending workspace switches clear snapshots from other targets.
• Keep mobile thread-detail lookup lazy: empty thread opens do not start workspace RPCs, while the composer $ menu, complete draft skill tokens, and sent user skill references activate the shared lookup for composer and feed metadata.
• Load composer workspace skills only when needed for the $ menu or existing complete $skill references, and load timeline skills only when a sent user prompt contains a complete skill reference, including one at the end of the message; web and mobile new-worktree drafts deliberately use snapshot fallback until their cwd exists and never probe the base checkout for repo-local skills.
• Reuse workspace-scoped skills for web and mobile composer suggestions, inline editor chips, pending answers, and submitted user-message skill chips, with shared token-boundary handling across web and mobile rendering.
• Add focused coverage for RPC handling, workspace validation, Codex app-server cwd and lifecycle behavior, timeout and request coalescing, query-key isolation, stale-state prevention, lazy skill references, fallback/error rendering, search ranking, and timeline chips.

Why

Fixes #3040.

Codex discovers repo-local skills relative to the cwd supplied to skills/list, but a provider status snapshot is global to the provider instance. A workspace-scoped query is therefore required to show the correct skills for each project and worktree, especially while switching between workspaces or refreshing under failure.

Validation

• pnpm exec vp test --maxWorkers=1 apps/server/src/provider/ProviderSkillsLister.test.ts apps/server/src/provider/Layers/CodexProvider.test.ts packages/client-runtime/src/state/providerWorkspaceSkills.test.ts packages/client-runtime/src/state/runtime.test.ts apps/web/src/lib/providerWorkspaceSkillsState.test.ts apps/web/src/composer-editor-mentions.test.ts apps/web/src/components/chat/ComposerCommandMenu.test.tsx apps/web/src/components/chat/MessagesTimeline.test.tsx apps/mobile/src/features/threads/new-task-provider-skills.test.ts apps/mobile/src/features/threads/thread-composer-skill-items.test.ts (10 files, 92 tests passed)
• pnpm exec vp test --maxWorkers=1 apps/server/src/server.test.ts -t "server.listProviderSkills" (5 tests passed)
• pnpm exec vp test run --passWithNoTests apps/mobile/src/lib/nativeMarkdownText.test.ts packages/shared/src/skillInlineTokens.test.ts (native and shared inline-token coverage passed as part of the focused 4-file run)
• pnpm exec vp check apps/server/src/provider/Layers/CodexProvider.ts apps/server/src/provider/Layers/CodexProvider.test.ts apps/server/src/provider/ProviderSkillsLister.ts apps/server/scripts/codex-skills-mock-app-server.ts packages/client-runtime/src/state/providerWorkspaceSkills.ts packages/client-runtime/src/state/providerWorkspaceSkills.test.ts apps/web/src/lib/providerWorkspaceSkillsState.ts apps/web/src/lib/providerWorkspaceSkillsState.test.ts apps/mobile/src/state/providerWorkspaceSkillsState.ts (9 files passed formatting and lint/type-aware checks)
• pnpm exec vp check (0 errors; 9 existing React warnings)
• pnpm exec vp run typecheck (15 tasks passed)
• pnpm exec vp run lint:mobile (passed; SwiftLint, ktlint, and detekt were unavailable)
• Playwright smoke against web 5735 and server 13775: paired the isolated app, added the codex-skills worktree, and verified that typing $ opened the skill picker with repo-scoped entries such as iOS Debugger Agent alongside system skills.
• pnpm exec vp test run --passWithNoTests --project unit src/components/ChatView.logic.test.ts src/components/chat/ComposerCommandMenu.test.tsx src/lib/providerWorkspaceSkillsState.test.ts from apps/web (3 files, 47 tests passed after the future-worktree review fix)
• pnpm exec vp check src/components/ChatView.logic.ts src/components/ChatView.logic.test.ts src/components/ChatView.tsx src/components/chat/ChatComposer.tsx from apps/web (4 files passed formatting and lint/type-aware checks)
• Playwright follow-up against web 5735 and server 13775: with $ open, a future-worktree draft sent 0 server.listProviderSkills frames; switching the same draft to the current checkout sent 1 request with the assigned worktree cwd.
• pnpm exec vp test run --passWithNoTests src/state/providerWorkspaceSkills.test.ts from packages/client-runtime, the two focused mobile provider-skill tests, and the focused web workspace-skill state test (4 files, 42 tests passed after the mobile connection/state review fixes).
• pnpm exec vp check apps/mobile/src/state/providerWorkspaceSkillsState.ts apps/mobile/src/features/threads/new-task-flow-provider.tsx apps/mobile/src/features/threads/ThreadDetailScreen.tsx packages/client-runtime/src/state/providerWorkspaceSkills.ts packages/client-runtime/src/state/providerWorkspaceSkills.test.ts (5 files passed formatting and lint/type-aware checks).
• Integrated follow-up used isolated state on assigned web 5735 and server 13775; both browser automation profiles were locked by other sessions, and the available simulator lacked the required com.t3tools.t3code.dev client, so no new runtime assertion was recorded. All owned processes were stopped and isolated state was cleaned up.
• pnpm exec vp test run --passWithNoTests src/provider/ProviderSkillsLister.test.ts from apps/server (1 file, 5 tests passed after making failed cache entries immediately retryable).
• pnpm exec vp check src/provider/ProviderSkillsLister.ts src/provider/ProviderSkillsLister.test.ts from apps/server (2 files passed formatting and lint/type-aware checks).
• pnpm exec vp test run --passWithNoTests src/features/threads/thread-provider-skills.test.ts src/features/threads/new-task-provider-skills.test.ts src/features/threads/thread-composer-skill-items.test.ts from apps/mobile (3 files, 11 tests passed after making mobile thread-detail workspace-skill lookup lazy).
• pnpm exec vp check apps/mobile/src/features/threads/ThreadDetailScreen.tsx apps/mobile/src/features/threads/ThreadComposer.tsx apps/mobile/src/features/threads/thread-provider-skills.ts apps/mobile/src/features/threads/thread-provider-skills.test.ts BRANCH_DETAILS.md (5 files passed formatting; all 4 TypeScript files passed lint/type-aware checks).
• Integrated iOS verification used an installed com.t3tools.t3code.dev client and isolated backend state on assigned server port 13775, but Metro failed before application code loaded because @expo/cli@56.1.16 injected expo/virtual/env, which is absent from the installed expo@56.0.12 package. Both standard and client-env-disabled launches reproduced the same dependency mismatch; all owned processes and the simulator were stopped, and the disposable state was moved to Trash.
• pnpm exec vp test run --passWithNoTests src/provider/ProviderSkillsLister.test.ts src/diagnostics/ErrorCause.test.ts src/workspace/WorkspacePaths.test.ts from apps/server (3 files, 16 tests passed after normalizing provider-skill cache keys and removing the dead sanitizer branch).
• Focused client-runtime, web, and mobile provider-skill suites passed 48 tests across 5 files after centralizing the shared query policy.
• pnpm exec vp check BRANCH_DETAILS.md apps/mobile/src/state/providerWorkspaceSkillsState.ts apps/server/src/diagnostics/ErrorCause.ts apps/server/src/diagnostics/ErrorCause.test.ts apps/server/src/provider/ProviderSkillsLister.ts apps/server/src/provider/ProviderSkillsLister.test.ts apps/server/src/workspace/WorkspacePaths.ts apps/web/src/lib/providerWorkspaceSkillsState.ts packages/client-runtime/src/state/providerWorkspaceSkills.ts packages/client-runtime/src/state/providerWorkspaceSkills.test.ts (all 10 files passed formatting; all 9 TypeScript files passed lint/type-aware checks).
• Integrated browser follow-up used isolated state on assigned web 5735 and server 13775. Playwright's shared profile was locked before navigation, so the controlled browser fallback paired the app, added the codex-skills checkout, refreshed an initially timed-out Codex provider, selected Codex, and verified that $ displayed all 4 repo-local skills alongside personal and system skills. Both development processes were stopped and the disposable state was removed.

Proof

• No external proof artifacts; validation is covered by the automated checks above.

---

Note

Medium Risk
Adds a new WebSocket RPC path that spawns timed Codex app-server probes per workspace and changes client skill state across web/mobile; mistakes could leak wrong-repo skills or amplify probe load, but scope is provider discovery rather than auth or persistence.

Overview
Fixes Codex repo-local skill discovery by listing skills for the active workspace cwd instead of the global provider status snapshot.

Server: New server.listProviderSkills RPC and ProviderSkillsLister run Codex skills/list against a validated, normalized workspace root (with bounded coalescing, concurrency limits, success-only TTL cache, 15s probe timeout, and process teardown). Non-Codex or disabled Codex instances still return snapshot skills. Failures surface structured ServerProviderSkillsListError payloads with sanitized diagnostics. Codex status probes now take an explicit cwd (server config) rather than process.cwd().

Clients: Shared provider-workspace-skills policy in client-runtime keys queries by environment, provider instance, and cwd; preserves same-workspace results during refresh; clears stale skills on workspace switches or failed refreshes; falls back to provider snapshot skills when offline, empty, or errored. Web and mobile composers load workspace skills lazily (active $ menu or complete $skill tokens); timelines decorate sent user prompts the same way. Future worktree drafts skip cwd probes until a directory exists.

Shared: @t3tools/shared/skillInlineTokens centralizes $skill boundary parsing for composer, timeline, and native markdown rendering.

^{Reviewed by Cursor Bugbot for commit cfe3942. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Fix workspace-scoped Codex skill discovery in the chat composer

• Adds a serverListProviderSkills WebSocket RPC endpoint that spawns the Codex app-server for a given cwd, queries its skills/list, and returns parsed results; requires AuthOrchestrationReadScope.
• Introduces useProviderWorkspaceSkills hooks (web and mobile) that fetch workspace-scoped skills lazily — only when the connection is live and the prompt or timeline contains a complete $skill reference — falling back to provider snapshot skills otherwise.
• Adds prepareProviderWorkspaceSkillsTarget and resolveProviderWorkspaceSkillsQuery utilities in client-runtime to normalize cache keys, gate querying on connection availability, and merge pending/error/fallback state into a single UI-ready object.
• Surfaces loading and error states from workspace skill queries in ComposerCommandMenu (web) and ComposerCommandPopover (mobile), including a new errorText banner that suppresses the empty-state hint.
• Extracts inline $skill token parsing into a shared parseInlineSkillTokens utility in @t3tools/shared, replacing local regexes in the web composer, mobile markdown renderer, and SkillInlineText.
• Risk: checkCodexProviderStatus now uses the server-configured cwd instead of process.cwd(), which changes probe behavior for any deployment where those differ.

^{Macroscope summarized cfe3942.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b6855377-25db-4603-b31a-4eb557ceae65

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces substantial new capability: a new WebSocket RPC endpoint, server-side bounded request caching, and cross-platform client state management for workspace-scoped skill discovery. Despite the 'Fix' title, the scope includes new API surfaces, new caching infrastructure, and runtime behavior changes across web, mobile, and server - warranting human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9388e7f. Configure here.}