💡 Change Scope

• Small Change: Fast feedback, localized UI/logic, low-risk.
• Large Change: New feature, cross-boundary logic, runtime-risk (persistence, IPC, lifecycle, recovery).

📝 What Does This PR Do?

This PR fixes two related startup/runtime bug classes that were both caused by split ownership across local shell/runtime boundaries:

1. It replaces one-off agent CLI PATH fixes with a centralized main-side executable resolution pipeline, durable per-provider overrides, and a shared resolution path for availability checks, model listing, hydrate/resume, and launch.
2. It also incorporates the workspace approval recovery fix from #174 by auto-registering persisted workspace roots during startup and gating local/remote guarded IPC paths until that bootstrap is finished.

The result is that GUI-launched environments no longer rely on ad-hoc executable discovery, and restored workspaces no longer lose terminal/agent/file-operation access just because approved-workspaces.json is missing or stale.

🏗️ Large Change Spec (Required if "Large Change" is checked)

1. Context & Business Logic

Two recurring problem classes were surfacing in adjacent startup paths:

• Finder/Dock/launcher startup often gives Electron a different runtime environment from the user's interactive shell. The old agent implementation split executable discovery across multiple call sites (PATH hydrate, availability checks, model probes, real launch), so the same provider could appear available in one path and unavailable in another.
• Restored workspaces come from persistence, but approved workspace roots were still treated like an independently maintained runtime list. If the approval file was cleared or stale, terminal/agent/guarded IPC paths failed after restart even though the workspace itself still existed in durable app state.

This PR makes both paths owner-based again: persisted settings own executable overrides, the main-side resolver owns local executable resolution, persisted workspace state remains the durable truth for workspace roots, and runtime approval stores bootstrap from that durable state instead of drifting away from it.

2. State Ownership & Invariants

Owner model:

• Durable provider override paths are owned by Settings via agentExecutablePathOverrideByProvider.
• Runtime executable resolution is owned by the main-side resolver/locator path.
• Shell environment capture is best-effort runtime observation, not durable truth.
• Persisted workspace paths remain the durable source for restored workspace roots.
• Runtime approved-root stores are bootstrap projections derived from persistence and explicit user approvals.

Invariants:

• Local provider availability, model listing, hydrate/resume, and direct launch must share the same executable resolution path.
• If a valid user override exists, it wins over shell PATH, process PATH, and fallback directories.
• Local absolute overrides must not be forwarded to remote worker launches.
• Startup approval hydration must finish before guarded local IPC or remote agent forwarding relies on approved roots for restored workspaces.
• Persisted workspace roots must be re-approved on startup without requiring the user to re-select the workspace.

3. Verification Plan & Regression Layer

Lowest meaningful regression layers:

• Unit: ShellEnvironmentService, ExecutableLocator, AgentExecutableResolver, persisted workspace approval gate, settings state, settings UI/search updates.
• Contract/integration: IPC payload validation, provider listing/model listing, local workspace approval bootstrap, remote agent startup gating, hydration/session catalog/session launch wiring.
• E2E: attempted through pnpm pre-commit; the full suite still has unrelated flaky failures, so failing specs were rerun directly to classify them.

Verification run:

• pnpm check
• targeted pnpm test -- --run ... coverage for resolver/locator/shell-env/settings/startup-approval paths
• targeted approval regressions passed:
  • tests/unit/contexts/persistedWorkspaceApproval.spec.ts
  • tests/contract/ipc/registerIpcHandlers.spec.ts
  • tests/contract/ipc/registerRemoteAgentIpcHandlers.spec.ts
  • tests/contract/ipc/ipcApprovedWorkspaceGuard.spec.ts
  • tests/contract/ipc/ipcApprovedWorkspaceGuard.agent.windows.spec.ts
• pnpm pre-commit earlier on this branch still showed unrelated flaky E2E failures in different specs on different runs, not a deterministic regression tied to this PR's change surface

✅ Delivery & Compliance Checklist

• My code passes the ultimate gatekeeper: pnpm pre-commit is completely green.
• I have signed the CLA if required (see CLA.md).
• I have included new tests to lock down the behavior (or explicitly stated why it's untestable).
• I have strictly adhered to the DEVELOPMENT.md architectural boundaries.
• I have attached a screenshot or screen recording (if this touches the UI).
• I have updated the documentation accordingly (if adding a feature or changing a contract).

📸 Screenshots / Visual Evidence

No screenshot attached in this CLI-created PR yet. The user-visible changes are the new Settings executable override section and the restored-workspace startup fix, which is primarily behavior-level rather than a new visual surface.