saeeol 1.4.2 → 1.4.3

package/specs/effect/instance-context.md

@@ -1,309 +0,0 @@
-# Instance context migration
-
-Practical plan for retiring the promise-backed / ALS-backed `Instance` helper in `src/project/instance.ts` and moving instance selection fully into Effect-provided scope.
-
-## Goal
-
-End state:
-
-- request, CLI, TUI, and tool entrypoints shift into an instance through Effect, not `Instance.provide(...)`
-- Effect code reads the current instance from `InstanceRef` or its eventual replacement, not from ALS-backed sync getters
-- per-directory boot, caching, and disposal are scoped Effect resources, not a module-level `Map<string, Promise<InstanceContext>>`
-- ALS remains only as a temporary bridge for native callback APIs that fire outside the Effect fiber tree
-
-## Current split
-
-Today `src/project/instance.ts` still owns two separate concerns:
-
-- ambient current-instance context through `LocalContext` / `AsyncLocalStorage`
-- per-directory boot and deduplication through `cache: Map<string, Promise<InstanceContext>>`
-
-At the same time, the Effect side already exists:
-
-- `src/effect/instance-ref.ts` provides `InstanceRef` and `WorkspaceRef`
-- `src/effect/run-service.ts` already attaches those refs when a runtime starts inside an active instance ALS context
-- `src/effect/instance-state.ts` already prefers `InstanceRef` and only falls back to ALS when needed
-
-That means the migration is not "invent instance context in Effect". The migration is "stop relying on the legacy helper as the primary source of truth".
-
-## End state shape
-
-Near-term target shape:
-
-```ts
-InstanceScope.with({ directory, workspaceID }, effect)
-```
-
-Responsibilities of `InstanceScope.with(...)`:
-
-- resolve `directory`, `project`, and `worktree`
-- acquire or reuse the scoped per-directory instance environment
-- provide `InstanceRef` and `WorkspaceRef`
-- run the caller's Effect inside that environment
-
-Code inside the boundary should then do one of these:
-
-```ts
-const ctx = yield * InstanceState.context
-const dir = yield * InstanceState.directory
-```
-
-Long-term, once `InstanceState` itself is replaced by keyed layers / `LayerMap`, those reads can move to an `InstanceContext` service without changing the outer migration order.
-
-## Migration phases
-
-### Phase 1: stop expanding the legacy surface
-
-Rules for all new code:
-
-- do not add new `Instance.directory`, `Instance.worktree`, `Instance.project`, or `Instance.current` reads inside Effect code
-- do not add new `Instance.provide(...)` boundaries unless there is no Effect-native seam yet
-- use `InstanceState.context`, `InstanceState.directory`, or an explicit `ctx` parameter inside Effect code
-
-Success condition:
-
-- the file inventory below only shrinks from here
-
-### Phase 2: remove direct sync getter reads from Effect services
-
-Convert Effect services first, before replacing the top-level boundary. These modules already run inside Effect and mostly need `yield* InstanceState.context` or a yielded `ctx` instead of ambient sync access.
-
-Primary batch, highest payoff:
-
-- `src/file/index.ts`
-- `src/lsp/server.ts`
-- `src/worktree/index.ts`
-- `src/file/watcher.ts`
-- `src/format/formatter.ts`
-- `src/session/index.ts`
-- `src/project/vcs.ts`
-
-Mechanical replacement rule:
-
-- `Instance.directory` -> `ctx.directory` or `yield* InstanceState.directory`
-- `Instance.worktree` -> `ctx.worktree`
-- `Instance.project` -> `ctx.project`
-
-Do not thread strings manually through every public method if the service already has access to Effect context.
-
-### Phase 3: convert entry boundaries to provide instance refs directly
-
-After the service bodies stop assuming ALS, move the top-level boundaries to shift into Effect explicitly.
-
-Main boundaries:
-
-- HTTP server middleware and experimental `HttpApi` entrypoints
-- CLI commands
-- TUI worker / attach / thread entrypoints
-- tool execution entrypoints
-
-These boundaries should become Effect-native wrappers that:
-
-- decode directory / workspace inputs
-- resolve the instance context once
-- provide `InstanceRef` and `WorkspaceRef`
-- run the requested Effect
-
-At that point `Instance.provide(...)` becomes a legacy adapter instead of the normal code path.
-
-### Phase 4: replace promise boot cache with scoped instance runtime
-
-Once boundaries and services both rely on Effect context, replace the module-level promise cache in `src/project/instance.ts`.
-
-Target replacement:
-
-- keyed scoped runtime or keyed layer acquisition for each directory
-- reuse via `ScopedCache`, `LayerMap`, or another keyed Effect resource manager
-- cleanup performed by scope finalizers instead of `disposeAll()` iterating a Promise map
-
-This phase should absorb the current responsibilities of:
-
-- `cache` in `src/project/instance.ts`
-- `boot(...)`
-- most of `disposeInstance(...)`
-- manual `reload(...)` / `disposeAll()` fan-out logic
-
-### Phase 5: shrink ALS to callback bridges only
-
-Keep ALS only where a library invokes callbacks outside the Effect fiber tree and we still need to call code that reads instance context synchronously.
-
-Known bridge cases today:
-
-- `src/file/watcher.ts`
-- `src/session/llm.ts`
-- some LSP and plugin callback paths
-
-If those libraries become fully wrapped in Effect services, the remaining `Instance.bind(...)` uses can disappear too.
-
-### Phase 6: delete the legacy sync API
-
-Only after earlier phases land:
-
-- remove broad use of `Instance.current`, `Instance.directory`, `Instance.worktree`, `Instance.project`
-- reduce `src/project/instance.ts` to a thin compatibility shim or delete it entirely
-- remove the ALS fallback from `InstanceState.context`
-
-## Inventory of direct legacy usage
-
-Direct legacy usage means any source file that still calls one of:
-
-- `Instance.current`
-- `Instance.directory`
-- `Instance.worktree`
-- `Instance.project`
-- `Instance.provide(...)`
-- `Instance.bind(...)`
-- `Instance.restore(...)`
-- `Instance.reload(...)`
-- `Instance.dispose()` / `Instance.disposeAll()`
-
-Current total: `56` files in `packages/saeeol/src`.
-
-### Core bridge and plumbing
-
-These files define or adapt the current bridge. They should change last, after callers have moved.
-
-- `src/project/instance.ts`
-- `src/effect/run-service.ts`
-- `src/effect/instance-state.ts`
-- `src/project/bootstrap.ts`
-- `src/config/config.ts`
-
-Migration rule:
-
-- keep these as compatibility glue until the outer boundaries and inner services stop depending on ALS
-
-### HTTP and server boundaries
-
-These are the current request-entry seams that still create or consume instance context through the legacy helper.
-
-- `src/server/routes/instance/middleware.ts`
-- `src/server/routes/instance/index.ts`
-- `src/server/routes/instance/project.ts`
-- `src/server/routes/control/workspace.ts`
-- `src/server/routes/instance/file.ts`
-- `src/server/routes/instance/experimental.ts`
-- `src/server/routes/global.ts`
-
-Migration rule:
-
-- move these to explicit Effect entrypoints that provide `InstanceRef` / `WorkspaceRef`
-- do not move these first; first reduce the number of downstream handlers and services that still expect ambient ALS
-
-### CLI and TUI boundaries
-
-These commands still enter an instance through `Instance.provide(...)` or read sync getters directly.
-
-- `src/cli/bootstrap.ts`
-- `src/cli/cmd/agent.ts`
-- `src/cli/cmd/debug/agent.ts`
-- `src/cli/cmd/debug/ripgrep.ts`
-- `src/cli/cmd/github.ts`
-- `src/cli/cmd/import.ts`
-- `src/cli/cmd/mcp.ts`
-- `src/cli/cmd/models.ts`
-- `src/cli/cmd/plug.ts`
-- `src/cli/cmd/pr.ts`
-- `src/cli/cmd/providers.ts`
-- `src/cli/cmd/stats.ts`
-- `src/cli/cmd/tui/attach.ts`
-- `src/cli/cmd/tui/plugin/runtime.ts`
-- `src/cli/cmd/tui/thread.ts`
-- `src/cli/cmd/tui/worker.ts`
-
-Migration rule:
-
-- converge these on one shared `withInstance(...)` Effect entry helper instead of open-coded `Instance.provide(...)`
-- after that helper is proven, inline the legacy implementation behind an Effect-native scope provider
-
-### Tool boundary code
-
-These tools mostly use direct getters for path resolution and repo-relative display logic.
-
-- `src/tool/apply_patch.ts`
-- `src/tool/bash.ts`
-- `src/tool/edit.ts`
-- `src/tool/lsp.ts`
-- `src/tool/plan.ts`
-- `src/tool/read.ts`
-- `src/tool/write.ts`
-
-Migration rule:
-
-- expose the current instance as an explicit Effect dependency for tool execution
-- keep path logic local; avoid introducing another global singleton for tool state
-
-### Effect services still reading ambient instance state
-
-These modules are already the best near-term migration targets because they are in Effect code but still read sync getters from the legacy helper.
-
-- `src/agent/agent.ts`
-- `src/cli/cmd/tui/config/tui-migrate.ts`
-- `src/file/index.ts`
-- `src/file/watcher.ts`
-- `src/format/formatter.ts`
-- `src/lsp/client.ts`
-- `src/lsp/index.ts`
-- `src/lsp/server.ts`
-- `src/mcp/index.ts`
-- `src/project/vcs.ts`
-- `src/provider/provider.ts`
-- `src/pty/index.ts`
-- `src/session/session.ts`
-- `src/session/instruction.ts`
-- `src/session/llm.ts`
-- `src/session/system.ts`
-- `src/sync/index.ts`
-- `src/worktree/index.ts`
-
-Migration rule:
-
-- replace direct getter reads with `yield* InstanceState.context` or a yielded `ctx`
-- isolate `Instance.bind(...)` callers and convert only the truly callback-driven edges to bridge mode
-
-### Highest-churn hotspots
-
-Current highest direct-usage counts by file:
-
-- `src/file/index.ts` - `18`
-- `src/lsp/server.ts` - `14`
-- `src/worktree/index.ts` - `12`
-- `src/file/watcher.ts` - `9`
-- `src/cli/cmd/mcp.ts` - `8`
-- `src/format/formatter.ts` - `8`
-- `src/tool/apply_patch.ts` - `8`
-- `src/cli/cmd/github.ts` - `7`
-
-These files should drive the first measurable burn-down.
-
-## Recommended implementation order
-
-1. Migrate direct getter reads inside Effect services, starting with `file`, `lsp`, `worktree`, `format`, and `session`.
-2. Add one shared Effect-native boundary helper for CLI / tool / HTTP entrypoints so we stop open-coding `Instance.provide(...)`.
-3. Move experimental `HttpApi` entrypoints to that helper so the new server stack proves the pattern.
-4. Convert remaining CLI and tool boundaries.
-5. Replace the promise cache with a keyed scoped runtime or keyed layer map.
-6. Delete ALS fallback paths once only callback bridges still depend on them.
-
-## Definition of done
-
-This migration is done when all of the following are true:
-
-- new requests and commands enter an instance by providing Effect context, not ALS
-- Effect services no longer read `Instance.directory`, `Instance.worktree`, `Instance.project`, or `Instance.current`
-- `Instance.provide(...)` is gone from normal request / CLI / tool execution
-- per-directory boot and disposal are handled by scoped Effect resources
-- `Instance.bind(...)` is either gone or confined to a tiny set of native callback adapters
-
-## Tracker and worktree
-
-Active tracker items:
-
-- `lh7l73` - overall `HttpApi` migration
-- `yobwlk` - remove direct `Instance.*` reads inside Effect services
-- `7irl1e` - replace `InstanceState` / legacy instance caching with keyed Effect layers
-
-Dedicated worktree for this transition:
-
-- path: `/Users/kit/code/open-source/saeeol-worktrees/instance-effect-shift`
-- branch: `kit/instance-effect-shift`

package/specs/effect/loose-ends.md

@@ -1,34 +0,0 @@
-# Effect loose ends
-
-Small follow-ups that do not fit neatly into the main facade, route, tool, or schema migration checklists.
-
-## Config / TUI
-
-- [ ] `cli/cmd/tui/config/tui.ts` - finish the internal Effect migration.
-      Keep the current precedence and migration semantics intact while converting the remaining internal async helpers (`loadState`, `mergeFile`, `loadFile`, `load`) to `Effect.gen(...)` / `Effect.fn(...)`.
-- [ ] `cli/cmd/tui/config/tui.ts` callers - once the internal service is stable, migrate plain async callers to use `TuiConfig.Service` directly where that actually simplifies the code.
-      Likely first callers: `cli/cmd/tui/attach.ts`, `cli/cmd/tui/thread.ts`, `cli/cmd/tui/plugin/runtime.ts`.
-- [x] `env/index.ts` - already uses `InstanceState.make(...)`.
-
-## ConfigPaths
-
-- [ ] `config/paths.ts` - split pure helpers from effectful helpers.
-      Keep `fileInDirectory(...)` as a plain function.
-- [ ] `config/paths.ts` - add a `ConfigPaths.Service` for the effectful operations so callers do not inherit `AppFileSystem.Service` directly.
-      Initial service surface should cover:
-  - `projectFiles(...)`
-  - `directories(...)`
-  - `readFile(...)`
-  - `parseText(...)`
-- [ ] `config/config.ts` - switch internal config loading from `Effect.promise(() => ConfigPaths.*(...))` to `yield* paths.*(...)` once the service exists.
-- [ ] `cli/cmd/tui/config/tui.ts` - switch TUI config loading from async `ConfigPaths.*` wrappers to the `ConfigPaths.Service` once that service exists.
-- [ ] `cli/cmd/tui/config/tui-migrate.ts` - decide whether to leave this as a plain async module using wrapper functions or effectify it fully after `ConfigPaths.Service` lands.
-
-## Instance cleanup
-
-- [ ] `project/instance.ts` - keep shrinking the legacy ALS / Promise cache after the remaining `Instance.*` callers move over.
-
-## Notes
-
-- Prefer small, semantics-preserving config migrations. Config precedence, legacy key migration, and plugin origin tracking are easy to break accidentally.
-- When changing config loading internals, rerun the config and TUI suites first before broad package sweeps.

package/specs/effect/migration.md

@@ -1,299 +0,0 @@
-# Effect patterns
-
-Practical reference for new and migrated Effect code in `packages/saeeol`.
-
-## Choose scope
-
-Use `InstanceState` (from `src/effect/instance-state.ts`) for services that need per-directory state, per-instance cleanup, or project-bound background work. InstanceState uses a `ScopedCache` keyed by directory, so each open project gets its own copy of the state that is automatically cleaned up on disposal.
-
-Use `makeRuntime` (from `src/effect/run-service.ts`) to create a per-service `ManagedRuntime` that lazily initializes and shares layers via a global `memoMap`. Returns `{ runPromise, runFork, runCallback }`.
-
-- Global services (no per-directory state): Account, Auth, AppFileSystem, Installation, Truncate, Worktree
-- Instance-scoped (per-directory state via InstanceState): Agent, Bus, Command, Config, File, FileWatcher, Format, LSP, MCP, Permission, Plugin, ProviderAuth, Pty, Question, SessionStatus, Skill, Snapshot, ToolRegistry, Vcs
-
-Rule of thumb: if two open directories should not share one copy of the service, it needs `InstanceState`.
-
-## Instance context transition
-
-See `instance-context.md` for the phased plan to remove the legacy ALS / promise-backed `Instance` helper and move request / CLI / tool boundaries onto Effect-provided instance scope.
-
-## Service shape
-
-Every service follows the same pattern: one module, flat top-level exports, traced Effect methods, and a self-reexport at the bottom when the file is the public module.
-
-```ts
-export interface Interface {
-  readonly get: (id: FooID) => Effect.Effect<FooInfo, FooError>
-}
-
-export class Service extends Context.Service<Service, Interface>()("@saeeol/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 Service.of({ get })
-  }),
-)
-
-export const defaultLayer = layer.pipe(Layer.provide(FooDep.layer))
-
-export * as Foo from "."
-```
-
-Rules:
-
-- Keep the service surface in one module; prefer flat top-level exports over `export namespace Foo { ... }`
-- Use `Effect.fn("Foo.method")` for Effect methods
-- Use a self-reexport (`export * as Foo from "."` or `"./foo"`) for the public namespace projection
-- Avoid service-local `makeRuntime(...)` facades unless a file is still intentionally in the older migration phase
-- No `Layer.fresh` for normal per-directory isolation; use `InstanceState`
-
-## Schema → Zod interop
-
-When a service uses Effect Schema internally but needs Zod schemas for the HTTP layer, derive Zod from Schema using the `zod()` helper from `@/util/effect-zod`:
-
-```ts
-import { zod } from "@/util/effect-zod"
-
-export const ZodInfo = zod(Info) // derives z.ZodType from Schema.Union
-```
-
-See `Auth.ZodInfo` for the canonical example.
-
-## InstanceState init patterns
-
-The `InstanceState.make` init callback receives a `Scope`, so you can use `Effect.acquireRelease`, `Effect.addFinalizer`, and `Effect.forkScoped` inside it. Resources acquired this way are automatically cleaned up when the instance is disposed or invalidated by `ScopedCache`. This makes it the right place for:
-
-- **Subscriptions**: Yield `Bus.Service` at the layer level, then use `Stream` + `forkScoped` inside the init closure. The fiber is automatically interrupted when the instance scope closes:
-
-```ts
-const bus = yield * Bus.Service
-
-const cache =
-  yield *
-  InstanceState.make<State>(
-    Effect.fn("Foo.state")(function* (ctx) {
-      // ... load state ...
-
-      yield* bus.subscribeAll().pipe(
-        Stream.runForEach((event) =>
-          Effect.sync(() => {
-            /* handle */
-          }),
-        ),
-        Effect.forkScoped,
-      )
-
-      return {
-        /* state */
-      }
-    }),
-  )
-```
-
-- **Resource cleanup**: Use `Effect.acquireRelease` or `Effect.addFinalizer` for resources that need teardown (native watchers, process handles, etc.):
-
-```ts
-yield *
-  Effect.acquireRelease(
-    Effect.sync(() => nativeAddon.watch(dir)),
-    (watcher) => Effect.sync(() => watcher.close()),
-  )
-```
-
-- **Background fibers**: Use `Effect.forkScoped` — the fiber is interrupted on disposal.
-- **Side effects at init**: Config notification, event wiring, etc. all belong in the init closure. Callers just do `InstanceState.get(cache)` to trigger everything, and `ScopedCache` deduplicates automatically.
-
-The key insight: don't split init into a separate method with a `started` flag. Put everything in the `InstanceState.make` closure and let `ScopedCache` handle the run-once semantics.
-
-## Effect.cached for deduplication
-
-Use `Effect.cached` when multiple concurrent callers should share a single in-flight computation. It memoizes the result and deduplicates concurrent fibers — second caller joins the first caller's fiber instead of starting a new one.
-
-```ts
-// Inside the layer — yield* to initialize the memo
-let cached = yield * Effect.cached(loadExpensive())
-
-const get = Effect.fn("Foo.get")(function* () {
-  return yield* cached // concurrent callers share the same fiber
-})
-
-// To invalidate: swap in a fresh memo
-const invalidate = Effect.fn("Foo.invalidate")(function* () {
-  cached = yield* Effect.cached(loadExpensive())
-})
-```
-
-Prefer `Effect.cached` over these patterns:
-
-- Storing a `Fiber.Fiber | undefined` with manual check-and-fork (e.g. `file/index.ts` `ensure`)
-- Storing a `Promise<void>` task for deduplication (e.g. `skill/index.ts` `ensure`)
-- `let cached: X | undefined` with check-and-load (races when two callers see `undefined` before either resolves)
-
-`Effect.cached` handles the run-once + concurrent-join semantics automatically. For invalidatable caches, reassign with `yield* Effect.cached(...)` — the old memo is discarded.
-
-## Scheduled Tasks
-
-For loops or periodic work, use `Effect.repeat` or `Effect.schedule` with `Effect.forkScoped` in the layer definition.
-
-## Preferred Effect services
-
-In effectified services, prefer yielding existing Effect services over dropping down to ad hoc platform APIs.
-
-Prefer these first:
-
-- `FileSystem.FileSystem` instead of raw `fs/promises` for effectful file I/O
-- `ChildProcessSpawner.ChildProcessSpawner` with `ChildProcess.make(...)` instead of custom process wrappers
-- `HttpClient.HttpClient` instead of raw `fetch`
-- `Path.Path` instead of mixing path helpers into service code when you already need a path service
-- `Config` for effect-native configuration reads
-- `Clock` / `DateTime` for time reads inside effects
-
-## Child processes
-
-For child process work in services, yield `ChildProcessSpawner.ChildProcessSpawner` in the layer and use `ChildProcess.make(...)`.
-
-Keep shelling-out code inside the service, not in callers.
-
-## Shared leaf models
-
-Shared schema or model files can stay outside the service namespace when lower layers also depend on them.
-
-That is fine for leaf files like `schema.ts`. Keep the service surface in the owning namespace.
-
-## Migration checklist
-
-Service-shape migrated (single namespace, traced methods, `InstanceState` where needed).
-
-This checklist is only about the service shape migration. Many of these services still keep `makeRuntime(...)` plus async facade exports; that facade-removal phase is tracked separately in `facades.md`.
-
-- [x] `Account` — `account/index.ts`
-- [x] `Agent` — `agent/agent.ts`
-- [x] `AppFileSystem` — `filesystem/index.ts`
-- [x] `Auth` — `auth/index.ts` (uses `zod()` helper for Schema→Zod interop)
-- [x] `Bus` — `bus/index.ts`
-- [x] `Command` — `command/index.ts`
-- [x] `Config` — `config/config.ts`
-- [x] `Discovery` — `skill/discovery.ts` (dependency-only layer, no standalone runtime)
-- [x] `File` — `file/index.ts`
-- [x] `FileWatcher` — `file/watcher.ts`
-- [x] `Format` — `format/index.ts`
-- [x] `Installation` — `installation/index.ts`
-- [x] `LSP` — `lsp/index.ts`
-- [x] `MCP` — `mcp/index.ts`
-- [x] `McpAuth` — `mcp/auth.ts`
-- [x] `Permission` — `permission/index.ts`
-- [x] `Plugin` — `plugin/index.ts`
-- [x] `Project` — `project/project.ts`
-- [x] `ProviderAuth` — `provider/auth.ts`
-- [x] `Pty` — `pty/index.ts`
-- [x] `Question` — `question/index.ts`
-- [x] `SessionStatus` — `session/status.ts`
-- [x] `Skill` — `skill/index.ts`
-- [x] `Snapshot` — `snapshot/index.ts`
-- [x] `ToolRegistry` — `tool/registry.ts`
-- [x] `Truncate` — `tool/truncate.ts`
-- [x] `Vcs` — `project/vcs.ts`
-- [x] `Worktree` — `worktree/index.ts`
-
-- [x] `Session` — `session/index.ts`
-- [x] `SessionProcessor` — `session/processor.ts`
-- [x] `SessionPrompt` — `session/prompt.ts`
-- [x] `SessionCompaction` — `session/compaction.ts`
-- [x] `SessionSummary` — `session/summary.ts`
-- [x] `SessionRevert` — `session/revert.ts`
-- [x] `Instruction` — `session/instruction.ts`
-- [x] `SystemPrompt` — `session/system.ts`
-- [x] `Provider` — `provider/provider.ts`
-- [x] `Storage` — `storage/storage.ts`
-- [x] `ShareNext` — `share/share-next.ts`
-- [x] `SessionTodo` — `session/todo.ts`
-
-Still open at the service-shape level:
-
-- [ ] `SyncEvent` — `sync/index.ts` (deferred pending sync with James)
-- [ ] `Workspace` — `control-plane/workspace.ts` (deferred pending sync with James)
-
-## Tool migration
-
-Tool-specific migration guidance and checklist live in `tools.md`.
-
-## Effect service adoption in already-migrated code
-
-Some already-effectified areas still use raw `Filesystem.*` or `Process.spawn` in their implementation or helper modules. These are low-hanging fruit — the layers already exist, they just need the dependency swap.
-
-### `Filesystem.*` → `AppFileSystem.Service` (yield in layer)
-
-- [x] `config/config.ts` — `installDependencies()` now uses `AppFileSystem`
-- [x] `provider/provider.ts` — recent model state now reads via `AppFileSystem.Service`
-
-### `Process.spawn` → `ChildProcessSpawner` (yield in layer)
-
-- [x] `format/formatter.ts` — direct `Process.spawn()` checks removed (`air`, `uv`)
-- [ ] `lsp/server.ts` — multiple `Process.spawn()` installs/download helpers
-
-## Filesystem consolidation
-
-`util/filesystem.ts` is still used widely across `src/`, and raw `fs` / `fs/promises` imports still exist in multiple tooling and infrastructure files. As services and tools are effectified, they should switch from `Filesystem.*` to yielding `AppFileSystem.Service` where possible — this should happen naturally during each migration, not as a separate sweep.
-
-Tool-specific filesystem cleanup notes live in `tools.md`.
-
-## Primitives & utilities
-
-- [ ] `util/lock.ts` — reader-writer lock → Effect Semaphore/Permit
-- [ ] `util/flock.ts` — file-based distributed lock with heartbeat → Effect.repeat + addFinalizer
-- [ ] `util/process.ts` — child process spawn wrapper → return Effect instead of Promise
-- [ ] `util/lazy.ts` — replace uses in Effect code with Effect.cached; keep for sync-only code
-
-## Destroying the facades
-
-This phase is no longer broadly open. There are 5 `makeRuntime(...)` call sites under `src/`, and only a small subset are still ordinary facade-removal targets. The live checklist now lives in `facades.md`.
-
-These facades exist because cyclic imports used to force each service to build its own independent runtime. Now that the layer DAG is acyclic and `AppRuntime` (`src/effect/app-runtime.ts`) composes everything into one `ManagedRuntime`, we're removing them.
-
-### Process
-
-For each service, the migration is roughly:
-
-1. **Find callers.** `grep -n "Namespace\.(methodA|methodB|...)"` across `src/` and `test/`. Skip the service file itself.
-2. **Migrate production callers.** For each effectful caller that does `Effect.tryPromise(() => Namespace.method(...))`:
-   - Add the service to the caller's layer R type (`Layer.Layer<Self, never, ... | Namespace.Service>`)
-   - Yield it at the top of the layer: `const ns = yield* Namespace.Service`
-   - Replace `Effect.tryPromise(() => Namespace.method(...))` with `yield* ns.method(...)` (or `ns.method(...).pipe(Effect.orElseSucceed(...))` for the common fallback case)
-   - Add `Layer.provide(Namespace.defaultLayer)` to the caller's own `defaultLayer` chain
-3. **Fix tests that used the caller's raw `.layer`.** Any test that composes `Caller.layer` (not `defaultLayer`) needs to also provide the newly-required service tag. The fastest fix is usually switching to `Caller.defaultLayer` since it now pulls in the new dependency.
-4. **Migrate test callers of the facade.** Tests calling `Namespace.method(...)` directly get converted to full effectful style using `testEffect(Namespace.defaultLayer)` + `it.live` / `it.effect` + `yield* svc.method(...)`. Don't wrap the test body in `Effect.promise(async () => {...})` — do the whole thing in `Effect.gen` and use `AppFileSystem.Service` / `tmpdirScoped` / `Effect.addFinalizer` for what used to be raw `fs` / `Bun.write` / `try/finally`.
-5. **Delete the facades.** Once `grep` shows zero callers, remove the `export async function` block AND the `makeRuntime(...)` line from the service namespace. Also remove the now-unused `import { makeRuntime }`.
-
-### Pitfalls
-
-- **Layer caching inside tests.** `testEffect(layer)` constructs the Storage (or whatever) service once and memoizes it. If a test then tries `inner.pipe(Effect.provide(customStorage))` to swap in a differently-configured Storage, the outer cached one wins and the inner provision is a no-op. Fix: wrap the overriding layer in `Layer.fresh(...)`, which forces a new instance to be built instead of hitting the memoMap cache. This lets a single `testEffect(...)` serve both simple and per-test-customized cases.
-- **`Effect.tryPromise` → `yield*` drops the Promise layer.** The old code was `Effect.tryPromise(() => Storage.read(...))` — a `tryPromise` wrapper because the facade returned a Promise. The new code is `yield* storage.read(...)` directly — the service method already returns an Effect, so no wrapper is needed. Don't reach for `Effect.promise` or `Effect.tryPromise` during migration; if you're using them on a service method call, you're doing it wrong.
-- **Raw `.layer` test callers break silently in the type checker.** When you add a new R requirement to a service's `.layer`, any test that composes it raw (not `defaultLayer`) becomes under-specified. `tsgo` will flag this — the error looks like `Type 'Storage.Service' is not assignable to type '... | Service | TestConsole'`. Usually the fix is to switch that composition to `defaultLayer`, or add `Layer.provide(NewDep.defaultLayer)` to the custom composition.
-- **Tests that do async setup with `fs`, `Bun.write`, `tmpdir`.** Convert these to `AppFileSystem.Service` calls inside `Effect.gen`, and use `tmpdirScoped()` instead of `tmpdir()` so cleanup happens via the scope finalizer. For file operations on the actual filesystem (not via a service), a small helper like `const writeJson = Effect.fnUntraced(function* (file, value) { const fs = yield* AppFileSystem.Service; yield* fs.makeDirectory(path.dirname(file), { recursive: true }); yield* fs.writeFileString(file, JSON.stringify(value, null, 2)) })` keeps the migration tests clean.
-
-### Migration log
-
-- `SessionStatus` — migrated 2026-04-11. Replaced the last route and retry-policy callers with `AppRuntime.runPromise(SessionStatus.Service.use(...))` and removed the `makeRuntime(...)` facade.
-- `ShareNext` — migrated 2026-04-11. Swapped remaining async callers to `AppRuntime.runPromise(ShareNext.Service.use(...))`, removed the `makeRuntime(...)` facade, and kept instance bootstrap on the shared app runtime.
-- `SessionTodo` — migrated 2026-04-10. Already matched the target service shape in `session/todo.ts`: single namespace, traced Effect methods, and no `makeRuntime(...)` facade remained; checklist updated to reflect the completed migration.
-- `Storage` — migrated 2026-04-10. One production caller (`Session.diff`) and all storage.test.ts tests converted to effectful style. Facades and `makeRuntime` removed.
-- `SessionRunState` — migrated 2026-04-11. Single caller in `server/routes/instance/session.ts` converted; facade removed.
-- `Account` — migrated 2026-04-11. Callers in `server/routes/instance/experimental.ts` and `cli/cmd/account.ts` converted; facade removed.
-- `Instruction` — migrated 2026-04-11. Test-only callers converted; facade removed.
-- `FileWatcher` — migrated 2026-04-11. Callers in `project/bootstrap.ts` and test converted; facade removed.
-- `Question` — migrated 2026-04-11. Callers in `server/routes/instance/question.ts` and test converted; facade removed.
-- `Truncate` — migrated 2026-04-11. Caller in `tool/tool.ts` and test converted; facade removed.
-
-## Route handler effectification
-
-Route-handler migration guidance and checklist live in `routes.md`.