Defer managed skill setup prompts until Orca restart

[brennanb2025]

TL;DR

This PR records managed-skill needs when Orca workflows use orca-linear, orchestration, computer-use, or orca-cli, then asks after the next Orca restart if setup still needs attention. Workflow entry no longer opens the install/update modal immediately.

On startup, Orca flushes the recorded requests through the managed-skill coordinator. If the skill is already ready, the request is cleared and nothing is shown. If the skill still needs setup and prompts are enabled, Orca shows the contextual install/update modal. If the experimental background update setting is enabled and the install is a verified safe global Orca-managed install, Orca can update during that restart-time flush instead of showing the modal.

The automatic path remains intentionally narrow and off by default: tracked global Orca-managed installs only, after the user explicitly enables the experimental setting. Orca does not auto-install missing skills, does not run broad skills update, and does not mutate project, remote/WSL, ambiguous, symlinked, bundled/plugin, or untracked/custom installs.

When Orca Updates vs Prompts

1. A workflow records a restart prompt request instead of checking/showing immediately:
   • Linear worktree from task -> orca-linear
   • Orca Orchestration runtime calls -> orchestration
   • Computer Use runtime calls -> computer-use
   • Agent browser/mobile-emulator runtime calls -> orca-cli
2. The request is deduped and persisted in settings so it survives app restart.
3. On the next Orca launch, the modal host calls skills:flushRestartPrompts once after settings hydrate, as long as Show agent skill setup prompts was enabled at startup.
4. Flush re-runs the existing coordinator. If the result is ready or updated, Orca clears that persisted request and shows nothing.
5. If the install is missing, Orca never auto-installs. The restart-time flush emits an actionable fallback with the global install command, and the modal is shown when setup prompts are enabled.
6. If Orca finds exactly one safe global managed install with trusted Orca lock metadata and the experimental background-update setting is off, the restart-time flush emits the update fallback with npx --yes skills update <skill> --global --yes and shows the modal.
7. If that same safe global managed install is found and the experimental setting is on, Orca runs npx --yes skills update <skill> --global --yes from the home directory, with shell: false, a 120s timeout, abort support, and post-update verification. Success emits an updated event and clears the pending request; no modal is shown. If update fails, times out, or post-update verification fails, Orca falls back to the manual update modal.
8. If Orca detects project, remote, WSL, repair-required, ambiguous, symlinked, bundled/plugin, malformed lockfile, unmanaged lockfile, or other unsafe states, it emits an actionable fallback instead of mutating anything. Remote/serve runtime interactions can still record the nudge, but they are marked remote so Orca only asks the user to update there after restart.
9. cooldown, target-required, and unsupported-skill are intentionally not emitted as modal events. Not now snoozes the current uiKey for the session; Don't show again disables the prompt setting and leaves workflows unblocked.

What Changed

• Added a restart-deferred prompt queue for managed-skill workflow nudges:
  • workflow/runtime triggers call deferManagedReadyPrompt,
  • requests are normalized, deduped, capped, and persisted,
  • startup flush calls the existing coordinator once for the recorded requests,
  • resolved requests are cleared, actionable fallbacks stay persisted for future restarts.
• Kept the existing managed-skill coordinator path for verified background updates:
  • discovers the active runtime/install,
  • requires a single global managed candidate,
  • reads the managed skills lock metadata,
  • runs npx --yes skills update <skill> --global --yes from a neutral cwd,
  • verifies the post-update install/lock before returning updated.
• Added/update guarded fallback states with actionable modal behavior for unsafe or failed update paths.
• Added a normal default-on Settings > Agents toggle, Show agent skill setup prompts, which controls whether restart-time managed-skill install/update prompts appear.
• Changed Don’t show again in the modal to disable that prompt setting, show a toast explaining where to re-enable it, and offer an Open Settings action back to Settings > Agents. If the settings write does not stick, Orca keeps the modal open and shows a failure toast instead of claiming prompts are off.
• Moved the background update setting to Experimental as an opt-in toggle; eligible stale global installs show the restart-time update modal unless the experimental setting is explicitly enabled.
• Wired deferred feature triggers for Linear, Orchestration, Computer Use, and Browser/mobile-emulator Orca CLI workflows.
• Added web/serve parity for managed-skill fallback/update events through skills.managedEvents, including retry coverage for re-pair, stream close/error/end, and transient pending subscribe failures.
• Updated modal copy and locale entries so CLI-triggered copy says the skill is needed, without claiming the skill or an agent was definitely the initiator.

Modal Copy

With workspace:

• Linear: A worktree was started from a Linear task in <workspace>. <Install/Update> the Linear agent skill to enable agents to read and update Linear issues.
• Orchestration: Orca Orchestration was used in <workspace>. <Install/Update> the orchestration skill to enable agents to coordinate reliably.
• Computer Use: Computer Use was used in <workspace>. <Install/Update> the Computer Use skill to enable agents to control apps reliably.
• Orca CLI: The Orca CLI skill is needed in <workspace>. <Install/Update> the CLI skill to enable this workflow to continue reliably.

Without workspace:

• Linear: A worktree was started from a Linear task. <Install/Update> the Linear agent skill to enable agents to read and update Linear issues.
• Orchestration: Orca Orchestration was used. <Install/Update> the orchestration skill to enable agents to coordinate reliably.
• Computer Use: Computer Use was used. <Install/Update> the Computer Use skill to enable agents to control apps reliably.
• Orca CLI: The Orca CLI skill is needed. <Install/Update> the CLI skill to enable this workflow to continue reliably.

Safety Model

Auto-update is allowed only during restart-time flush, only when the experimental setting is explicitly enabled, and only when Orca can prove it is updating the same tracked global install the user already has. It requires a supported managed skill name, host runtime, a single non-symlinked global install, managed lock metadata, no recent failure cooldown, and successful post-update verification.

Unsafe cases fall back instead of mutating: missing installs, project installs, ambiguous installs, bundled/plugin installs, symlinked globals, malformed/missing/unmanaged lockfile entries, remote/WSL/repair-required runtimes, unsupported skills, update failures, and update timeouts.

Design / Review / Perf

• Design approach: workflow and runtime surfaces record durable restart prompt requests; the central main-process coordinator still owns discovery, eligibility, optional experimental update execution, post-update verification, in-flight dedupe, success cache, cooldowns, and fallback construction.
• Design-review outcome: the design was adjusted so workflow entry does not interrupt users with setup prompts; modal/update decisions happen after restart from recorded context.
• Implementation deviations: project-scope auto-update remains intentionally unsupported; web/serve clients receive events through a streaming runtime RPC bridge rather than Electron IPC. Web clients no-op the deferred prompt API because they cannot inspect or mutate trusted host installs.
• Perf audit result: hot paths record a deduped settings entry instead of running discovery/subprocess work. Restart-time checks still use pre-discovery keys, in-flight dedupe, disabled-path fast fallback caching, session/app-version success caching for enabled auto-update, failure cooldowns, and bounded web retry timers.

Validation

Latest local validation for the restart-deferred prompt change:

• Focused Vitest: src/main/ipc/skills.test.ts, src/main/ipc/runtime-environments.test.ts, src/main/persistence.test.ts, src/renderer/src/components/skills/ManagedAgentSkillSetupDialogHost.test.ts, src/renderer/src/store/slices/worktrees.test.ts (5 files, 569 tests passed)
• Focused Vitest: src/renderer/src/web/web-preload-api.test.ts (1 file, 59 tests passed)
• pnpm run typecheck:node
• pnpm run typecheck:cli
• git diff --check

Latest manual Electron validation with $brennan-test-changes:

• Launched the exact PR worktree and verified window.api.app.getIdentity() returned devBranch: brennanb2025/skill-update-detection and devRepoRoot: /Users/thebr/orca/workspaces/orca/skill-update-detection.
• Used isolated HOME and ORCA_DEV_USER_DATA_PATH, with demo-project as the workflow context; no real Orca repo, issue, PR, or user skill install was modified.
• Persisted a deferred orchestration restart prompt request and captured a full-page screenshot showing no modal before restart: /tmp/orca-managed-skill-private-before.png (1512x886).
• Restarted Orca and captured a full-page screenshot showing the contextual update modal for demo-project: /tmp/orca-managed-skill-private-update-modal.png (1512x887).
• Clicked the real Update control and captured a full-page screenshot showing the embedded terminal with npx --yes skills update orchestration --global --yes waiting for Enter: /tmp/orca-managed-skill-private-terminal.png (1512x887).
• Inspected the Electron console log for the manual pass; no app errors were present. The remaining lines were React dev tooling chatter and an xterm timing warning while the terminal was open.
• Stopped only the Electron process launched for this validation.

Validation attempted but blocked by existing toolchain/environment issues:

• pnpm run typecheck:web is blocked by unrelated missing Testing Library module/type errors in MobileNetworkInterfaceSection.test.tsx and TerminalSshReconnectOverlay.test.tsx.
• Changed-file oxlint is blocked by the merged mobile/.oxlintrc.json unsupported unicorn rule: no-array-fill-with-reference-type.

Earlier local validation after resolving and pushing the merge with origin/main:

• Renderer/settings/worktree focused Vitest: src/renderer/src/components/settings/ExperimentalPane.test.tsx, src/renderer/src/components/settings/OrchestrationPane.test.tsx, src/renderer/src/store/slices/worktrees.test.ts, src/renderer/src/components/emulator-pane/use-emulator-pane-session.test.ts (4 files, 210 tests passed)
• Main IPC/shared focused Vitest: src/main/ipc/register-core-handlers.test.ts, src/main/ipc/runtime-environments.test.ts, src/shared/agent-feature-install-commands.test.ts (3 files, 37 tests passed)
• git diff --check

Additional review validation already captured before this latest change:

• Focused Vitest and typechecks for the original coordinator/modal/settings work.
• Earlier broad Vitest run from review expanded to the full suite and passed: 2026 files, 20463 tests, 23 skipped.
• Post-push stabilization after commit f6568ccf4: PR checks passed at that time (verify, native smoke on Ubuntu, native smoke on Windows; platform matrix entries skipped as expected).

Residual Risk

• No manual Windows/WSL/SSH smoke was run in this final pass; coverage is automated tests plus code review. WSL/remote paths intentionally fall back and do not mutate.
• The auto-update trust model relies on managed lock metadata and discovery safety checks; in-place user edits to a formerly managed global skill without changing lock metadata are treated as part of that managed install.
• Already-running agents may continue using old skill context until future skill reads/invocations.
• Existing local profiles on this unmerged branch that already persisted managedAgentSkillBackgroundUpdatesEnabled: true remain opted in; production users have not received that default-on build.

---

[stage-review]

Ready to review this PR? Stage has broken it down into 15 individual chapters for you:

	Title
1	Define managed skill types and shared constants
2	Implement managed skill discovery and safety logic
3	Implement the managed skill update coordinator
4	Wire managed skill nudges through the RPC layer
5	Implement restart-deferred prompt persistence
6	Expose managed skill IPC handlers
7	Integrate nudges into runtime and environment IPC
8	Expose managed skill APIs to the renderer
9	Implement renderer-side skill discovery caching
10	Implement the managed skill setup dialog
11	Add managed skill settings to the UI
12	Nudge Linear skill setup during worktree creation
13	Update web UI and emulator for managed skills
14	Update UI components and translations
15	Add design documentation

_{Chapters generated by Stage for commit 62b28a2 on Jul 2, 2026 5:37am UTC.}

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR implements an end-to-end "Agent Skill Auto-Update" system for Orca-managed agent skills. It introduces shared managed-skill types and a non-interactive --yes flag on install/update commands. A new main-process ManagedSkillUpdateCoordinator handles lockfile hash verification, in-flight deduplication, cooldown tracking, and subprocess-based skill updates with abort/timeout handling. Runtime RPC dispatch is extended to detect feature interactions (orchestration, computer-use, emulator, browser methods) and trigger best-effort managed-skill nudges, including a new streaming skills.managedEvents RPC method. Emulator UI-owned calls now pass suppressFeatureInteraction: true to prevent spurious nudges. IPC wiring propagates the store to handler registrars; a new skills:ensureManagedReady handler and sendManagedSkillFallback/sendManagedSkillUpdated broadcasters connect the coordinator to renderer windows. The renderer gains a cached skill-discovery module with deduplication, a FIFO fallback queue dialog host (ManagedAgentSkillSetupDialogHost) with dismiss/snooze/recheck behavior, and a settings toggle for background updates. Worktree creation triggers a Linear managed-skill nudge. Localization is added in five locales.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 1.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title matches the core change: deferring managed skill prompts until the next Orca restart.
Description check	✅ Passed	The PR description is detailed and covers the main change, testing, review, security, and notes, with screenshot evidence included despite nonstandard headings.

---

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.}

[coderabbitai]

Actionable comments posted: 7

🧹 Nitpick comments (2)

src/renderer/src/web/web-preload-api.ts (1)

2290-2324: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a short why-comment for the web-only fallback.

This intentionally never installs/updates skills from the web preload. Add a one-line rationale so future changes do not treat the fallback as missing implementation. As per coding guidelines, “When writing or modifying code driven by a design doc or non-obvious constraint, add a comment explaining why the code behaves the way it does.”

♻️ Proposed refactor

     ensureManagedReady: (request: ManagedAgentSkillEnsureRequest) => {
+      // Why: web preload cannot perform trusted host updates, so managed skills are remote-only fallbacks.
       const uiKey = ['remote', '', request.skillName, request.context].join(':')

Source: Coding guidelines

src/main/skills/managed-skill-discovery-candidate.ts (1)

8-12: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider documenting the dual-check rationale.

The function checks both skill.name and basename(skill.directoryPath). While this defensive approach makes sense (skills might be identified by either their metadata name or folder name), a brief comment explaining when each case applies would improve maintainability.

📝 Example comment

 export function isDiscoveredManagedSkill(
   skill: DiscoveredSkill,
   skillName: ManagedAgentSkillName
 ): boolean {
+  // Check both metadata name and directory basename because skills can be
+  // identified by either (e.g., when skill.json is missing or skill.name differs from folder).
   const expected = normalizeSkillName(skillName)

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 65f49013-e491-401d-bffb-71684ca210cf

📥 Commits

Reviewing files that changed from the base of the PR and between 185175a and c7d1479.

📒 Files selected for processing (62)

• docs/reference/agent-skill-auto-update-plan.md
• src/main/index.ts
• src/main/ipc/register-core-handlers.test.ts
• src/main/ipc/register-core-handlers.ts
• src/main/ipc/runtime-environments.test.ts
• src/main/ipc/runtime-environments.ts
• src/main/ipc/runtime-managed-skill-nudge.ts
• src/main/ipc/runtime.ts
• src/main/ipc/skills.test.ts
• src/main/ipc/skills.ts
• src/main/runtime/rpc/dispatcher-feature-interactions.test.ts
• src/main/runtime/rpc/dispatcher.ts
• src/main/runtime/rpc/managed-skill-nudge.ts
• src/main/runtime/rpc/runtime-feature-interaction-id.ts
• src/main/runtime/runtime-rpc.ts
• src/main/skills/discovery.ts
• src/main/skills/managed-skill-discovery-candidate.ts
• src/main/skills/managed-skill-discovery-selection.ts
• src/main/skills/managed-skill-ensure-result.ts
• src/main/skills/managed-skill-fallback-message.ts
• src/main/skills/managed-skill-global-candidate.ts
• src/main/skills/managed-skill-lockfile.ts
• src/main/skills/managed-skill-target.ts
• src/main/skills/managed-skill-update-cache-key.ts
• src/main/skills/managed-skill-update-contract.ts
• src/main/skills/managed-skill-updates.test.ts
• src/main/skills/managed-skill-updates.ts
• src/preload/api-types.ts
• src/preload/index.ts
• src/renderer/src/App.tsx
• src/renderer/src/components/onboarding/onboarding-feature-setup.test.ts
• src/renderer/src/components/settings/AgentSkillSetupPanel.test.tsx
• src/renderer/src/components/settings/AgentsPane.test.tsx
• src/renderer/src/components/settings/AgentsPane.tsx
• src/renderer/src/components/settings/BrowserUseSkillStep.test.tsx
• src/renderer/src/components/settings/CliSection.test.tsx
• src/renderer/src/components/settings/OrchestrationPane.test.tsx
• src/renderer/src/components/settings/agent-skill-installed-command-callers.test.ts
• src/renderer/src/components/settings/agents-search.ts
• src/renderer/src/components/settings/managed-agent-skill-background-updates-copy.ts
• src/renderer/src/components/sidebar/LinearAgentSkillSetupPrompt.test.tsx
• src/renderer/src/components/skills/ManagedAgentSkillSetupDialogHost.test.ts
• src/renderer/src/components/skills/ManagedAgentSkillSetupDialogHost.tsx
• src/renderer/src/components/skills/managed-agent-skill-dialog-copy.ts
• src/renderer/src/components/skills/managed-agent-skill-dialog-state.ts
• src/renderer/src/hooks/installed-agent-skill-discovery.ts
• src/renderer/src/hooks/useInstalledAgentSkills.test.ts
• src/renderer/src/hooks/useInstalledAgentSkills.ts
• src/renderer/src/i18n/locales/en.json
• src/renderer/src/i18n/locales/es.json
• src/renderer/src/i18n/locales/ja.json
• src/renderer/src/i18n/locales/ko.json
• src/renderer/src/i18n/locales/zh.json
• src/renderer/src/store/slices/worktrees.test.ts
• src/renderer/src/store/slices/worktrees.ts
• src/renderer/src/web/web-preload-api.test.ts
• src/renderer/src/web/web-preload-api.ts
• src/shared/agent-feature-install-commands.test.ts
• src/shared/agent-feature-install-commands.ts
• src/shared/constants.ts
• src/shared/skills.ts
• src/shared/types.ts

[brennanb2025]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 6

🧹 Nitpick comments (1)

src/main/skills/managed-skill-update-cache-key.ts (1)

17-24: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Document why the success cache key ignores request context/target.

This key intentionally collapses multiple workspaces onto the same verified global lock hash, but that reads like an accidental cache-collision bug without a short rationale comment.

As per coding guidelines, "When writing or modifying code driven by a design doc or non-obvious constraint, add a comment explaining why the code behaves the way it does."

Source: Coding guidelines

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 050a703f-e776-44cb-b985-b4c262471508

📥 Commits

Reviewing files that changed from the base of the PR and between 204b3e0 and 5ab31df.

📒 Files selected for processing (45)

• docs/reference/agent-skill-auto-update-plan.md
• src/main/index.ts
• src/main/ipc/runtime-environments.test.ts
• src/main/ipc/runtime-managed-skill-nudge.ts
• src/main/ipc/skills.test.ts
• src/main/ipc/skills.ts
• src/main/runtime/rpc/dispatcher-feature-interactions.test.ts
• src/main/runtime/rpc/managed-skill-nudge.ts
• src/main/runtime/rpc/methods/skills.test.ts
• src/main/runtime/rpc/methods/skills.ts
• src/main/runtime/rpc/runtime-feature-interaction-id.ts
• src/main/skills/managed-skill-ensure-result.ts
• src/main/skills/managed-skill-events.ts
• src/main/skills/managed-skill-fallback-message.ts
• src/main/skills/managed-skill-global-candidate.ts
• src/main/skills/managed-skill-post-update-verification.ts
• src/main/skills/managed-skill-test-fixtures.ts
• src/main/skills/managed-skill-update-cache-key.ts
• src/main/skills/managed-skill-update-contract.ts
• src/main/skills/managed-skill-update-coordinator-registry.ts
• src/main/skills/managed-skill-update-runner.test.ts
• src/main/skills/managed-skill-update-runner.ts
• src/main/skills/managed-skill-updates-safety.test.ts
• src/main/skills/managed-skill-updates.test.ts
• src/main/skills/managed-skill-updates.ts
• src/preload/api-types.ts
• src/preload/index.ts
• src/renderer/src/App.tsx
• src/renderer/src/components/emulator-pane/use-emulator-pane-controls.ts
• src/renderer/src/components/emulator-pane/use-emulator-pane-session.ts
• src/renderer/src/components/emulator-pane/use-emulator-pane-shutdown.ts
• src/renderer/src/components/settings/AgentSkillSetupPanel.test.tsx
• src/renderer/src/components/settings/AgentSkillSetupPanel.tsx
• src/renderer/src/components/settings/MobileEmulatorSettingsPane.tsx
• src/renderer/src/components/skills/ManagedAgentSkillSetupDialogHost.test.ts
• src/renderer/src/components/skills/ManagedAgentSkillSetupDialogHost.tsx
• src/renderer/src/components/skills/managed-agent-skill-dialog-copy.ts
• src/renderer/src/components/task-page-github-work-item-status.ts
• src/renderer/src/hooks/installed-agent-skill-discovery.ts
• src/renderer/src/hooks/useInstalledAgentSkills.test.ts
• src/renderer/src/i18n/locales/en.json
• src/renderer/src/i18n/locales/es.json
• src/renderer/src/i18n/locales/ja.json
• src/renderer/src/i18n/locales/ko.json
• src/renderer/src/i18n/locales/zh.json

💤 Files with no reviewable changes (12)

• src/renderer/src/components/settings/MobileEmulatorSettingsPane.tsx
• src/renderer/src/hooks/useInstalledAgentSkills.test.ts
• src/renderer/src/components/skills/managed-agent-skill-dialog-copy.ts
• src/renderer/src/components/skills/ManagedAgentSkillSetupDialogHost.test.ts
• src/renderer/src/hooks/installed-agent-skill-discovery.ts
• src/renderer/src/components/task-page-github-work-item-status.ts
• src/renderer/src/components/skills/ManagedAgentSkillSetupDialogHost.tsx
• src/renderer/src/i18n/locales/ko.json
• src/renderer/src/i18n/locales/es.json
• src/renderer/src/i18n/locales/en.json
• src/renderer/src/i18n/locales/zh.json
• src/renderer/src/i18n/locales/ja.json

✅ Files skipped from review due to trivial changes (1)

• docs/reference/agent-skill-auto-update-plan.md

🚧 Files skipped from review as they are similar to previous changes (11)

• src/main/ipc/runtime-managed-skill-nudge.ts
• src/main/runtime/rpc/managed-skill-nudge.ts
• src/renderer/src/components/settings/AgentSkillSetupPanel.test.tsx
• src/main/runtime/rpc/runtime-feature-interaction-id.ts
• src/main/skills/managed-skill-fallback-message.ts
• src/renderer/src/App.tsx
• src/preload/api-types.ts
• src/preload/index.ts
• src/main/skills/managed-skill-global-candidate.ts
• src/main/ipc/skills.ts
• src/main/index.ts