orynacode-ai 1.16.2

package/specs/effect/error-boundaries-plan.md

@@ -0,0 +1,235 @@
+# Error Boundaries Plan
+
+Plan for removing `NamedError` as connective tissue while keeping public
+wire contracts stable.
+
+## Desired Shape
+
+```text
+Domain/service error
+  Schema.TaggedErrorClass
+  - catchable with catchTag / catchTags
+  - appears in service method error type
+  - no HTTP status
+  - no toObject()
+
+HTTP public error
+  Schema.ErrorClass / TaggedErrorClass with httpApiStatus
+  - endpoint-declared public contract
+  - owns legacy { name, data } only when that is the SDK wire shape
+
+CLI/user rendering
+  FormatError and small format helpers
+  - converts domain errors to text
+  - preserves useful structured fields
+
+Session/model-visible error
+  first-class session/message error schema or helper
+  - owns { name, data } event/message shape
+  - not a service error class
+```
+
+The important rule: a service error should not also be the HTTP body, CLI
+formatter, and session event body. Each seam adapts the error into the
+shape it owns.
+
+## Concrete Example: Provider Model Not Found
+
+Before:
+
+```ts
+export const ModelNotFoundError = NamedError.create("ProviderModelNotFoundError", {
+  providerID: ProviderID,
+  modelID: ModelID,
+  suggestions: Schema.optional(Schema.Array(Schema.String)),
+})
+```
+
+Problems:
+
+- Throwing it inside `Effect.fn` made it behave like a defect unless a
+  compatibility bridge caught it.
+- HTTP middleware knew that this one domain error should be a `400`.
+- Callers read `.data.*`, which couples them to the legacy `{ name, data }`
+  wire shape.
+
+After:
+
+```ts
+export class ModelNotFoundError extends Schema.TaggedErrorClass<ModelNotFoundError>()("ProviderModelNotFoundError", {
+  providerID: ProviderID,
+  modelID: ModelID,
+  suggestions: Schema.optional(Schema.Array(Schema.String)),
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+export interface Interface {
+  readonly getModel: (providerID: ProviderID, modelID: ModelID) => Effect.Effect<Model, ModelNotFoundError>
+}
+```
+
+Boundary adapters:
+
+```text
+CLI
+└─ FormatError sees _tag ProviderModelNotFoundError -> nice text
+
+Session prompt
+└─ catch ModelNotFoundError -> publish Session.Event.Error as message/session wire shape
+
+HTTP route
+└─ catch ModelNotFoundError -> declared BadRequest public API error when the endpoint needs it
+
+HTTP middleware
+└─ no Provider.ModelNotFoundError knowledge
+```
+
+## Refining Known Promise Failures
+
+Use `EffectPromise.refineRejection(...)` when a Promise boundary can reject
+with many unknown values, but only one or two rejection classes are expected
+domain failures. Unknown rejections stay defects; the helper maps only known
+rejection shapes to typed errors.
+
+```ts
+const language =
+  yield *
+  EffectPromise.refineRejection(
+    async () => loadFromProvider(),
+    (cause) => (cause instanceof NoSuchModelError ? new ModelNotFoundError({ providerID, modelID, cause }) : undefined),
+  )
+```
+
+Use this when the Promise can genuinely reject and most rejection values are
+still defects for the current module. Use `Effect.tryPromise({ try, catch })`
+when every rejection should become the same expected error type. Use
+`Effect.promise(...)` only when rejection means a defect and you do not need
+to refine known rejection classes.
+
+## Helper Modules We Probably Want
+
+Add helpers only when repeated call sites prove the seam is real.
+
+### HTTP API Errors
+
+Likely location: `src/server/routes/instance/httpapi/errors.ts`.
+
+Purpose:
+
+- construct public HTTP error bodies
+- preserve legacy `{ name, data }` where needed
+- attach `httpApiStatus`
+
+Good helpers:
+
+```ts
+notFound(message)
+badRequest(message)
+unknown()
+```
+
+Avoid:
+
+```ts
+mapAnyDomainError(error)
+```
+
+That recreates the giant middleware mapper problem.
+
+### Session / Message Error Wire Helpers
+
+Likely location: near `src/session/message-error.ts` or a new narrow
+module such as `src/session/event-error.ts`.
+
+Purpose:
+
+- construct the `{ name, data }` shape used by `Session.Event.Error` and
+  assistant message errors
+- replace `new NamedError.Unknown(...).toObject()` call sites
+- keep model-visible error bodies separate from service/domain errors
+
+Good helpers:
+
+```ts
+unknown(message)
+agentNotFound(agent, available)
+commandNotFound(command, available)
+modelNotFound(error: Provider.ModelNotFoundError)
+```
+
+### CLI Formatters
+
+Likely location: `src/cli/error.ts` until repetition demands domain-local
+format helpers.
+
+Purpose:
+
+- produce human-readable terminal messages from typed errors
+- support old `{ name, data }` shapes only while compatibility is needed
+
+## Migration Queue
+
+### Remove Domain Knowledge From HTTP Middleware
+
+- [x] Storage not found no longer maps through defect fallback.
+- [x] Worktree expected errors moved to typed errors.
+- [x] Provider auth expected errors moved to typed errors.
+- [x] Provider model not found no longer needs an HTTP middleware status
+      special case.
+- [ ] Convert `Session.BusyError` and map it at route boundaries.
+- [ ] Delete the broad `NamedError` middleware branch once no route relies
+      on defect-wrapped legacy domain errors.
+- [ ] Keep one final unknown-defect fallback that logs `Cause.pretty(cause)`
+      and returns a safe `500` body.
+
+### Remaining `NamedError.create(...)` Service Errors
+
+These should become `Schema.TaggedErrorClass` when touched:
+
+- [ ] `src/provider/provider.ts` — `ProviderInitError`.
+- [ ] `src/storage/db.ts` — database `NotFoundError`.
+- [ ] `src/mcp/index.ts` — `MCPFailed`.
+- [ ] `src/skill/index.ts` — `SkillInvalidError`,
+      `SkillNameMismatchError`.
+- [ ] `src/lsp/client.ts` — `LSPInitializeError`.
+- [ ] `src/ide/index.ts` — install errors.
+- [ ] `src/config/error.ts`, `src/config/config.ts`,
+      `src/config/markdown.ts` — config errors. These already render well
+      in the CLI, so migrate carefully and preserve diagnostics.
+
+### Session / Message Wire Errors
+
+These are not ordinary service errors. They mostly build `{ name, data }`
+objects for model-visible/session-visible output.
+
+- [ ] Add a first-class session/message error wire helper.
+- [ ] Replace `new NamedError.Unknown(...).toObject()` in
+      `src/session/prompt.ts`.
+- [ ] Replace `new NamedError.Unknown(...).toObject()` in config/skill/plugin
+      session event publishing.
+- [ ] Move `src/session/message-error.ts` and `src/session/message-v2.ts`
+      away from `NamedError.create(...)` once the wire helper exists.
+- [ ] Update retry/message tests to assert the wire schema/helper output,
+      not `NamedError` instances.
+
+### CLI Rendering
+
+- [x] Tagged config errors render with useful diagnostics.
+- [x] Provider model not found renders from both old `{ name, data }` and
+      new `_tag` shapes.
+- [ ] Add typed render cases as more `NamedError.create(...)` domains move
+      to `Schema.TaggedErrorClass`.
+- [ ] Eventually remove old-shape compatibility branches when no callers can
+      produce them.
+
+## PR Checklist
+
+For each migrated error:
+
+- [ ] Domain error is `Schema.TaggedErrorClass`.
+- [ ] Service method exposes the typed error in its error channel.
+- [ ] No service error has `toObject()` just for compatibility.
+- [ ] CLI, HTTP, and session/message adapters each own their output shape.
+- [ ] HTTP middleware gets smaller or stays unchanged.
+- [ ] Focused tests cover the domain error and any public rendering/wire
+      shape touched by the PR.

package/specs/effect/errors.md

@@ -0,0 +1,207 @@
+# Typed Error Migration
+
+This note expands the `ERR`, `RENDER`, and `HTTP` tracks from
+[`todo.md`](./todo.md). It is the current reference for expected failures,
+typed service errors, and HTTP error boundaries.
+
+For the migration architecture and queue, see
+[`error-boundaries-plan.md`](./error-boundaries-plan.md).
+
+## Goal
+
+- Expected service failures live on the Effect error channel.
+- Service interfaces expose those failures in their return types.
+- Domain errors are authored with `Schema.TaggedErrorClass`.
+- `Effect.die(...)` is reserved for defects: bugs, impossible states,
+  violated invariants, and final unknown-boundary fallbacks.
+- HTTP status codes and public wire bodies are handled at HTTP route
+  boundaries, not inside service modules.
+- User-facing boundaries render useful structured error details instead of
+  opaque `Error: SomeName` strings.
+
+## Service Error Shape
+
+```ts
+export class SessionBusyError extends Schema.TaggedErrorClass<SessionBusyError>()("SessionBusyError", {
+  sessionID: SessionID,
+  message: Schema.String,
+}) {}
+
+export type Error = Storage.Error | SessionBusyError
+
+export interface Interface {
+  readonly get: (id: SessionID) => Effect.Effect<Info, Error>
+}
+```
+
+Rules:
+
+- Use `Schema.TaggedErrorClass` for expected domain failures.
+- Export a domain-level `Error` union from each service module.
+- Put expected errors in service method signatures.
+- Use `yield* new DomainError(...)` for direct early failures in
+  `Effect.gen` / `Effect.fn`.
+- Use `Schema.Defect` for unknown cause fields when preserving the cause is
+  useful for logs or callers.
+- Use `Effect.try(...)`, `Effect.tryPromise(...)`, `Effect.mapError`,
+  `Effect.catchTag`, and `Effect.catchTags` to translate external
+  failures into domain errors.
+- Do not use `throw`, `Effect.die(...)`, or `catchDefect` for expected
+  user, IO, validation, missing-resource, auth, provider, worktree, or
+  busy-state failures.
+
+## HTTP Boundary Shape
+
+Service modules stay transport-agnostic. They should not import HTTP
+status codes, `HttpApiError`, `HttpServerResponse`, or route-specific
+error schemas.
+
+HTTP handlers translate service errors into public endpoint errors:
+
+```ts
+const get = Effect.fn("SessionHttpApi.get")(function* (ctx: { params: { sessionID: SessionID } }) {
+  return yield* session
+    .get(ctx.params.sessionID)
+    .pipe(Effect.catchTag("StorageNotFoundError", () => notFound("Session not found")))
+})
+```
+
+Endpoint definitions declare which public errors can be emitted. Public
+HTTP error schemas carry their response status with `httpApiStatus` or the
+equivalent HttpApi schema annotation.
+
+Effect's own HttpApi examples follow this pattern:
+
+```ts
+export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
+  "Unauthorized",
+  { message: Schema.String },
+  { httpApiStatus: 401 },
+) {}
+
+export class Authorization extends HttpApiMiddleware.Service<
+  Authorization,
+  {
+    provides: CurrentUser
+  }
+>()("app/Authorization", {
+  security: { bearer: HttpApiSecurity.bearer },
+  error: Unauthorized,
+}) {}
+```
+
+Endpoint-level errors use the same idea:
+
+```ts
+export class ConfigApiError extends Schema.ErrorClass<ConfigApiError>("ConfigApiError")(
+  {
+    name: Schema.Union(Schema.Literal("ConfigInvalidError"), Schema.Literal("ConfigJsonError")),
+    data: Schema.Struct({ message: Schema.optional(Schema.String), path: Schema.String }),
+  },
+  { httpApiStatus: 400 },
+) {}
+
+HttpApiEndpoint.get("get", "/config", {
+  success: Config.Info,
+  error: ConfigApiError,
+})
+```
+
+The service error and HTTP error may be the same class only when the wire
+shape is intentionally public. Use separate HTTP error schemas when the
+service error contains internals, low-level causes, retry hints, or data
+that should not be exposed to API clients.
+
+Do not map every domain error into one universal HTTP error class. Prefer a
+small public error vocabulary by route group: shared shapes like
+`ApiNotFoundError`, route-specific shapes like `ConfigApiError`, and built-in
+empty `HttpApiError.*` only when an empty/no-content body is the intended SDK
+contract.
+
+## Mapping Guidance
+
+- Keep one-off translations inline in the handler.
+- Extract tiny shared helpers when the same translation repeats across a
+  route group.
+- Do not create one giant `unknown -> status` mapper.
+- Do not grow generic HTTP middleware into a registry of domain errors.
+- Preserve existing public `{ name, data }` bodies until a deliberate
+  breaking API change.
+- Use built-in `HttpApiError.*` only when its generated body and SDK
+  surface are intentionally the public contract.
+- Prefer `Schema.ErrorClass` for public HTTP error bodies whose wire shape is
+  not the same as the internal domain error shape.
+- Prefer `Schema.TaggedErrorClass` for service/domain errors and middleware
+  errors that are naturally tagged by `_tag`.
+- If preserving a legacy `{ name, data }` body, model that shape explicitly in
+  the public API error schema instead of relying on `NamedError.toObject()` in
+  generic middleware.
+
+## User-Facing Rendering
+
+HTTP serialization and user rendering are separate boundaries. The server
+should send structured public errors; CLI and TUI code should format those
+structures through one shared formatter.
+
+For SDK calls using `{ throwOnError: true }`, the generated client may wrap the
+decoded response body in an `Error`. The original body should remain available
+under `error.cause.body`; `FormatError` is the right place to unwrap and render
+that body. TUI aggregation helpers should call `FormatError` first, then fall
+back to generic `Error.message` / string rendering.
+
+When several parallel startup requests fail from the same underlying issue,
+group identical rendered messages and list the affected request names once.
+For example:
+
+```text
+Configuration is invalid at /path/to/opencode.json
+↳ Expected object, got "not-object" provider.bad.options
+Affected startup requests: config.providers, provider.list, app.agents, config.get
+```
+
+## Middleware Guidance
+
+HTTP middleware should be cross-cutting: auth, context, schema decode
+formatting, routing, and final unknown-defect fallback.
+
+The current compatibility middleware still knows about some legacy domain
+errors. As route groups declare expected errors and handlers map them, that
+middleware should shrink. It should not gain new name checks.
+
+Unknown `500` responses should log full details server-side with
+`Cause.pretty(cause)` and return a safe public body.
+
+The config startup regression in #27056 is the failure mode this rule is meant
+to avoid: a user-authored invalid `opencode.json` crossed the HttpApi boundary
+as a defect, so middleware replaced a useful `ConfigInvalidError` with a safe
+generic `UnknownError`. The compatibility fix is to preserve config parse and
+validation errors as client-visible `400`s. The target architecture is better:
+config loading should fail on the typed error channel, config HTTP handlers
+should map those errors to declared `ConfigApiError` responses, and the generic
+middleware should never see them.
+
+## Migration Order
+
+Prefer small vertical slices:
+
+1. Fix rendering at one user-visible boundary.
+2. Convert one service domain to `Schema.TaggedErrorClass` errors.
+3. Map those errors at the affected HTTP handlers.
+4. Remove the corresponding name-based middleware branch if possible.
+5. Add or update focused tests for both service error tags and HTTP wire
+   bodies.
+
+Good early domains are storage not-found, worktree errors, and provider
+auth validation errors because they currently drive HTTP behavior.
+
+Config parse and validation errors are also a good early slice because they
+are startup-blocking and must be rendered clearly in both CLI and TUI flows.
+
+## Checklist For A PR
+
+- [ ] Expected failures are typed errors, not defects.
+- [ ] Service method signatures expose the expected error union.
+- [ ] HTTP handlers translate domain errors at the boundary.
+- [ ] Public HTTP error bodies preserve existing wire contracts.
+- [ ] Generic middleware gets smaller or stays unchanged.
+- [ ] Focused tests cover the service error and any public HTTP response.

package/specs/effect/facades.md

@@ -0,0 +1,218 @@
+# Facade removal checklist
+
+Concrete inventory of the remaining `makeRuntime(...)`-backed facades in `packages/opencode`.
+
+Current status on this branch:
+
+- `src/` has 5 `makeRuntime(...)` call sites total.
+- 2 are intentionally excluded from this checklist: `src/bus/index.ts` and `src/effect/cross-spawn-spawner.ts`.
+- That leaves 2 live runtime-backed service facades still worth tracking here: `src/npm/index.ts` and `src/cli/cmd/tui/config/tui.ts`.
+
+Recent progress:
+
+- Wave 1 is merged: `Pty`, `Skill`, `Vcs`, `ToolRegistry`, `Auth`.
+- Wave 2 is merged: `Config`, `Provider`, `File`, `LSP`, `MCP`.
+
+## Priority hotspots
+
+- `src/cli/cmd/tui/config/tui.ts` still exports `makeRuntime(...)` plus async facade helpers for `get()` and `waitForDependencies()`.
+- `src/npm/index.ts` still exports `makeRuntime(...)` plus async facade helpers for `install()`, `add()`, `outdated()`, and `which()`.
+
+## Completed Batches
+
+Low-risk batch, all merged:
+
+1. `src/pty/index.ts`
+2. `src/skill/index.ts`
+3. `src/project/vcs.ts`
+4. `src/tool/registry.ts`
+5. `src/auth/index.ts`
+
+Caller-heavy batch, all merged:
+
+1. `src/config/config.ts`
+2. `src/provider/provider.ts`
+3. `../core/src/filesystem.ts`
+4. `src/lsp/index.ts`
+5. `src/mcp/index.ts`
+
+Shared pattern:
+
+- one service file still exports `makeRuntime(...)` + async facades
+- one or two route or CLI entrypoints call those facades directly
+- tests call the facade directly and need to switch to `yield* svc.method(...)`
+- once callers are gone, delete `makeRuntime(...)`, remove async facade exports, and drop the `makeRuntime` import
+
+## Done means
+
+For each service in the low-risk batch, the work is complete only when all of these are true:
+
+1. all production callers stop using `Namespace.method(...)` facade calls
+2. all direct test callers stop using the facade and instead yield the service from context
+3. the service file no longer has `makeRuntime(...)`
+4. the service file no longer exports runtime-backed facade helpers
+5. `grep` for the migrated facade methods only finds the service implementation itself or unrelated names
+
+## Caller templates
+
+### Route handlers
+
+Use one `AppRuntime.runPromise(Effect.gen(...))` body and yield the service inside it.
+
+```ts
+const value = await AppRuntime.runPromise(
+  Effect.gen(function* () {
+    const pty = yield* Pty.Service
+    return yield* pty.list()
+  }),
+)
+```
+
+If two service calls are independent, keep them in the same effect body and use `Effect.all(...)`.
+
+### Plain async CLI or script entrypoints
+
+If the caller is not itself an Effect service yet, still prefer one contiguous `AppRuntime.runPromise(Effect.gen(...))` block for the whole unit of work.
+
+```ts
+const skills = await AppRuntime.runPromise(
+  Effect.gen(function* () {
+    const auth = yield* Auth.Service
+    const skill = yield* Skill.Service
+    yield* auth.set(key, info)
+    return yield* skill.all()
+  }),
+)
+```
+
+Only fall back to `AppRuntime.runPromise(Service.use(...))` for truly isolated one-off calls or awkward callback boundaries. Do not stack multiple tiny `runPromise(...)` calls in the same contiguous workflow.
+
+This is the right intermediate state. Do not block facade removal on effectifying the whole CLI file.
+
+### Bootstrap or fire-and-forget startup code
+
+If the old facade call existed only to kick off initialization, call the service through the existing runtime for that file.
+
+```ts
+void BootstrapRuntime.runPromise(Vcs.Service.use((svc) => svc.init()))
+```
+
+Do not reintroduce a dedicated runtime in the service just for bootstrap.
+
+### Tests
+
+Convert facade tests to full effect style.
+
+```ts
+it.effect("does the thing", () =>
+  Effect.gen(function* () {
+    const svc = yield* Pty.Service
+    const info = yield* svc.create({ command: "cat", title: "a" })
+    yield* svc.remove(info.id)
+  }).pipe(Effect.provide(Pty.defaultLayer)),
+)
+```
+
+If the repo test already uses `testEffect(...)`, prefer `testEffect(Service.defaultLayer)` and `yield* Service.Service` inside the test body.
+
+Do not route tests through `AppRuntime` unless the test is explicitly exercising the app runtime. For facade removal, tests should usually provide the specific service layer they need.
+
+If the test uses `provideTmpdirInstance(...)`, remember that fixture needs a live `ChildProcessSpawner` layer. For services whose `defaultLayer` does not already provide that infra, prefer the repo-standard cross-spawn layer:
+
+```ts
+const infra = CrossSpawnSpawner.defaultLayer
+
+const it = testEffect(Layer.mergeAll(MyService.defaultLayer, infra))
+```
+
+Without that extra layer, tests fail at runtime with `Service not found: effect/process/ChildProcessSpawner`.
+
+## Questions already answered
+
+### Do we need to effectify the whole caller first?
+
+No.
+
+- route files: compose the handler with `AppRuntime.runPromise(Effect.gen(...))`
+- CLI and scripts: use `AppRuntime.runPromise(Service.use(...))`
+- bootstrap: use the existing bootstrap runtime
+
+Facade removal does not require a bigger refactor than that.
+
+### Should tests keep calling the namespace from async test bodies?
+
+No. Convert them now.
+
+The end state is `yield* svc.method(...)`, not `await Namespace.method(...)` inside `async` tests.
+
+### Should we keep `runPromise` exported for convenience?
+
+No. For this batch the goal is to delete the service-local runtime entirely.
+
+### What if a route has websocket callbacks or nested async handlers?
+
+Keep the route shape, but replace each facade call with `AppRuntime.runPromise(Service.use(...))` or wrap the surrounding async section in one `Effect.gen(...)` when practical. Do not keep the service facade just because the route has callback-shaped code.
+
+### Should we use one `runPromise` per service call?
+
+No.
+
+Default to one contiguous `AppRuntime.runPromise(Effect.gen(...))` block per handler, command, or workflow. Yield every service you need inside that block.
+
+Multiple tiny `runPromise(...)` calls are only acceptable when the caller structure forces it, such as websocket lifecycle callbacks, external callback APIs, or genuinely unrelated one-off operations.
+
+### Should we wrap a single service expression in `Effect.gen(...)`?
+
+Usually no.
+
+Prefer the direct form when there is only one expression:
+
+```ts
+await Effect.runPromise(FileSystem.Service.use((svc) => svc.read({ path })))
+```
+
+Use `Effect.gen(...)` when the workflow actually needs multiple yielded values or branching.
+
+## Learnings
+
+These were the recurring mistakes and useful corrections from the first two batches:
+
+1. Tests should usually provide the specific service layer, not `AppRuntime`.
+2. If a test uses `provideTmpdirInstance(...)` and needs child processes, prefer `CrossSpawnSpawner.defaultLayer`.
+3. Location-scoped services may need both the service layer and the right location fixture. `FileSystem` tests, for example, provide `Location.Service` plus `FileSystem.locationLayer`.
+4. Do not wrap a single `Service.use(...)` call in `Effect.gen(...)` just to return it. Use the direct form.
+5. For CLI readability, extract file-local preload helpers when the handler starts doing config load + service load + batched effect fanout inline.
+6. When rebasing a facade branch after nearby merges, prefer the already-cleaned service/test version over older inline facade-era code.
+
+## Remaining work
+
+Most of the original facade-removal backlog is already done. The practical remaining work is narrower now:
+
+1. remove the `Npm` runtime-backed facade from `src/npm/index.ts`
+2. remove the `TuiConfig` runtime-backed facade from `src/cli/cmd/tui/config/tui.ts`
+
+## Checklist
+
+- [ ] `src/npm/index.ts` (`Npm`) - still exports runtime-backed async facade helpers on top of `Npm.Service`
+- [ ] `src/cli/cmd/tui/config/tui.ts` (`TuiConfig`) - still exports runtime-backed async facade helpers on top of `TuiConfig.Service`
+- [x] `src/session/session.ts` / `src/session/prompt.ts` / `src/session/revert.ts` / `src/session/summary.ts` - service-local facades removed
+- [x] `src/agent/agent.ts` (`Agent`) - service-local facades removed
+- [x] `src/permission/index.ts` (`Permission`) - service-local facades removed
+- [x] `src/worktree/index.ts` (`Worktree`) - service-local facades removed
+- [x] `src/plugin/index.ts` (`Plugin`) - service-local facades removed
+- [x] `src/snapshot/index.ts` (`Snapshot`) - service-local facades removed
+- [x] `../core/src/filesystem.ts` (`FileSystem`) - legacy opencode service removed
+- [x] `src/lsp/index.ts` (`LSP`) - facades removed and merged
+- [x] `src/mcp/index.ts` (`MCP`) - facades removed and merged
+- [x] `src/config/config.ts` (`Config`) - facades removed and merged
+- [x] `src/provider/provider.ts` (`Provider`) - facades removed and merged
+- [x] `src/pty/index.ts` (`Pty`) - facades removed and merged
+- [x] `src/skill/index.ts` (`Skill`) - facades removed and merged
+- [x] `src/project/vcs.ts` (`Vcs`) - facades removed and merged
+- [x] `src/tool/registry.ts` (`ToolRegistry`) - facades removed and merged
+- [x] `src/auth/index.ts` (`Auth`) - facades removed and merged
+
+## Excluded `makeRuntime(...)` sites
+
+- `src/bus/index.ts` - core bus plumbing, not a normal facade-removal target.
+- `src/effect/cross-spawn-spawner.ts` - runtime helper for `ChildProcessSpawner`, not a service namespace facade.