openfork 1.17.14 → 1.17.16

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/openfork.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 `openfork.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/openfork`.
+
+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 openfork 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.

package/specs/effect/guide.md

@@ -0,0 +1,247 @@
+# Effect Guide
+
+How we write Effect code in `packages/openfork`. The companion roadmap is
+[`todo.md`](./todo.md).
+
+This guide describes the preferred shape for new work and migrations. If a
+legacy file differs, migrate it only when it is already in scope.
+
+## Service Shape
+
+Use one module per service: flat top-level exports, traced Effect methods,
+explicit layers, and a self-reexport at the bottom.
+
+```ts
+export interface Interface {
+  readonly get: (id: FooID) => Effect.Effect<FooInfo, FooError>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@openfork/Foo") {}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const state = yield* InstanceState.make<State>(Effect.fn("Foo.state")(() => Effect.succeed({})))
+
+    const get = Effect.fn("Foo.get")(function* (id: FooID) {
+      const s = yield* InstanceState.get(state)
+      return yield* loadFoo(s, id)
+    })
+
+    return Service.of({ get })
+  }),
+)
+
+export const defaultLayer = layer.pipe(Layer.provide(FooDep.defaultLayer))
+
+export * as Foo from "./foo"
+```
+
+Rules:
+
+- Do not use `export namespace Foo { ... }`.
+- Use `Effect.fn("Foo.method")` for public service methods.
+- Use `Effect.fnUntraced` for small internal helpers that do not need a
+  span.
+- Keep helpers as non-exported top-level declarations in the same file.
+- Self-reexport with `export * as Foo from "."` for `index.ts`, otherwise
+  `export * as Foo from "./foo"`.
+- In `src/config`, keep the existing top-of-file self-export pattern.
+
+## Runtime Boundaries
+
+Most code should run through [`AppRuntime`](../../src/effect/app-runtime.ts).
+It hosts `AppLayer`, shares the global `memoMap`, and restores the current
+instance/workspace refs when crossing from non-Effect code.
+
+Use `AppRuntime.runPromise(effect)` at app boundaries such as CLI commands,
+HTTP handlers, or plain async adapters.
+
+`makeRuntime(...)` still exists for a few intentional service-local
+boundaries and migration leftovers. Do not add a new service-local runtime
+unless the service truly cannot live in `AppLayer`.
+
+## Runtime Flags
+
+Read openfork runtime flags through
+[`RuntimeFlags.Service`](../../src/effect/runtime-flags.ts), not through
+mutable `Flag` or late `process.env` reads.
+
+Tests should vary behavior with explicit layer variants:
+
+```ts
+const it = testEffect(MyService.defaultLayer.pipe(Layer.provide(RuntimeFlags.layer({ experimentalReferences: true }))))
+```
+
+Do not mutate `process.env` or `Flag` after services/layers are built.
+
+## Per-Instance State
+
+Use [`InstanceState`](../../src/effect/instance-state.ts) when two open
+directories should not share one copy of a service's state. It is backed by
+a `ScopedCache`, keyed by directory, and disposed automatically when an
+instance is unloaded.
+
+Put subscriptions, finalizers, and scoped background work inside the
+`InstanceState.make(...)` initializer:
+
+```ts
+const cache =
+  yield *
+  InstanceState.make<State>(
+    Effect.fn("Foo.state")(function* () {
+      const bus = yield* Bus.Service
+
+      yield* bus.subscribeAll().pipe(
+        Stream.runForEach((event) => handleEvent(event)),
+        Effect.forkScoped,
+      )
+
+      yield* Effect.acquireRelease(openResource, closeResource)
+
+      return yield* loadInitialState()
+    }),
+  )
+```
+
+Do not add separate `started` flags on top of `InstanceState`. Let
+`ScopedCache` handle run-once and deduplication.
+
+To make `init()` non-blocking, fork at the caller/bootstrap boundary. Do
+not fork inside `InstanceState.make(...)` just to return early with
+partially initialized state.
+
+## Errors
+
+Expected domain failures belong on the Effect error channel. Defects are
+for bugs, impossible states, and final unknown-boundary fallbacks.
+
+```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 new expected domain errors.
+- Export a domain-level `Error` union from service modules.
+- In `Effect.gen` / `Effect.fn`, prefer `yield* new MyError(...)` for
+  direct expected failures.
+- Use `Schema.Defect` for unknown cause fields.
+- Use `Effect.try(...)`, `Effect.tryPromise(...)`, `Effect.mapError`,
+  `Effect.catchTag`, and `Effect.catchTags` to translate external
+  failures into domain errors.
+- Do not use `Effect.die(...)` for user, IO, validation, missing-resource,
+  auth, provider, or busy-state failures.
+
+## HTTP Error Boundaries
+
+Service modules stay HTTP-agnostic. They should not import HTTP status
+codes, `HttpApiError`, `HttpServerResponse`, or route-specific error
+schemas.
+
+HTTP handlers translate service errors into endpoint-declared public error
+schemas. Keep mappings inline when they are one-off; extract tiny shared
+helpers only when the same translation repeats.
+
+Do not turn generic middleware into a registry of domain errors. Middleware
+should handle cross-cutting concerns and the final unknown-defect fallback.
+
+Preserve legacy public wire shapes, such as `{ name, data }`, until a
+deliberate breaking API change.
+
+## Schemas
+
+Use Effect Schema as the source of truth.
+
+- Use `Schema.Class` for exported data objects with a clear identity.
+- Use `Schema.Struct` for local shapes and simple nested objects.
+- Use `Schema.brand` for single-value IDs.
+- Reuse named refinements instead of re-spelling constraints.
+- Prefer narrow boundary helpers over generic Schema-to-Zod bridges.
+
+Intentional boundaries:
+
+- Public plugin tools still expose Zod through `tool.schema = z`.
+- Tool parameter JSON Schema is generated through tool-specific helpers.
+- Public config and TUI schemas are generated through the schema script.
+
+## Preferred Services
+
+In effectified code, yield existing services instead of dropping to ad hoc
+platform APIs.
+
+- Use `FSUtil.Service` instead of raw `fs/promises` for app file IO.
+- Use `AppProcess.Service` instead of direct `ChildProcessSpawner.spawn` or
+  legacy process helpers.
+- Use `HttpClient.HttpClient` instead of raw `fetch` inside Effect code.
+- Use `Path.Path`, `Config`, `Clock`, and `DateTime` when already inside
+  Effect.
+- Use `Effect.callback` for callback-based APIs.
+- Use `Effect.void` instead of `Effect.succeed(undefined)`.
+- Use `Effect.cached` when concurrent callers should share one in-flight
+  computation.
+
+For background loops, use `Effect.repeat` or `Effect.schedule` with
+`Effect.forkScoped` in the owning layer/state scope.
+
+## Promise And ALS Bridges
+
+[`EffectBridge`](../../src/effect/bridge.ts) is the sanctioned helper for
+Promise/callback interop that needs to preserve instance/workspace context.
+It preserves explicit `InstanceRef` / `WorkspaceRef` context for effects run
+through the bridge. Plain JS callbacks that need instance data should receive
+that data explicitly.
+
+## Testing
+
+Detailed test migration rules live in
+[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md).
+
+Core pattern:
+
+```ts
+const it = testEffect(Layer.mergeAll(MyService.defaultLayer))
+
+describe("my service", () => {
+  it.instance("does the thing", () =>
+    Effect.gen(function* () {
+      const svc = yield* MyService.Service
+      expect(yield* svc.run()).toEqual("ok")
+    }),
+  )
+})
+```
+
+Rules:
+
+- Use `it.effect(...)` for TestClock/TestConsole tests.
+- Use `it.live(...)` for real timers, filesystem mtimes, child processes,
+  git, locks, or other live integration behavior.
+- Use `it.instance(...)` for service tests that need a scoped instance.
+- Prefer Effect-aware fixtures from `test/fixture/fixture.ts`.
+- Avoid sleeps; wait for real events or deterministic state transitions.
+- Avoid mutable `process.env`, `Flag`, or module-global changes after
+  layers are built.
+- Use `Layer.mock` for partial service stubs.
+- Avoid custom `ManagedRuntime`, `attach(...)`, or ad hoc `run(...)` test
+  wrappers.
+
+## Verification
+
+From `packages/openfork`:
+
+```bash
+bun run typecheck
+bun run test -- path/to/test.ts
+```
+
+Do not run tests from the repo root; the repo has a guard for that.

package/specs/effect/instance-context.md

@@ -0,0 +1,13 @@
+# Instance Context
+
+Instance selection is now Effect-provided context.
+
+Use these APIs:
+
+- `InstanceRef` for the current project context.
+- `WorkspaceRef` for the current workspace id.
+- `InstanceState.context` / `InstanceState.directory` inside Effect services that require an instance.
+- `InstanceStore` at entry boundaries that need to load, reload, or dispose project contexts.
+- `EffectBridge` for native, plugin, or plain JavaScript callback boundaries that need to re-enter Effect with captured refs.
+
+Do not add new ambient instance globals. Promise and callback boundaries should either stay in Effect, use `EffectBridge`, or pass the required context explicitly.