openfork 1.17.14 → 1.17.15

package/specs/effect/loose-ends.md

@@ -0,0 +1,30 @@
+# 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 `FSUtil.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.
+
+## 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

@@ -0,0 +1,62 @@
+# Effect Migration Patterns
+
+This is the compact reference for moving code toward the current Effect
+shape. The high-level roadmap is [`todo.md`](./todo.md); examples and
+rules are in [`guide.md`](./guide.md).
+
+## Default Shape
+
+- Service methods return `Effect`.
+- Service methods are named with `Effect.fn("Domain.method")`.
+- Expected failures are typed errors on the error channel.
+- Dependencies are yielded once at layer construction and closed over by
+  methods.
+- `defaultLayer` wires production dependencies; tests can use open layers
+  when replacing dependencies.
+
+## Instance State
+
+Use `InstanceState` for per-directory state, subscriptions, scoped
+background work, and per-instance cleanup.
+
+Do not add ad hoc `started` flags on top of `InstanceState`; the scoped
+cache handles run-once and concurrent deduplication.
+
+## Runtime Boundaries
+
+Prefer `AppRuntime` for crossing from non-Effect code into the shared app
+layer.
+
+`makeRuntime(...)` exists for intentional service-local boundaries and
+legacy facades. Do not add new service-local runtimes unless the service is
+genuinely outside `AppLayer`.
+
+## Platform Edges
+
+- Use `FSUtil.Service` instead of raw filesystem APIs in
+  effectified services.
+- Use `AppProcess.Service` instead of raw process wrappers.
+- Use `HttpClient.HttpClient` instead of raw `fetch` in Effect code.
+- Use `Effect.cached` for shared in-flight work.
+- Use `Effect.callback` for callback APIs.
+
+## Tests During Migration
+
+When migrating code, migrate touched tests toward
+[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md):
+
+- `testEffect(...)`
+- `it.effect`, `it.live`, or `it.instance`
+- explicit layers for behavior changes
+- deterministic waits instead of sleeps
+- no mutable env/global flags after layers are built
+
+## Migration Checklist
+
+- [ ] The code has a single Effect body instead of Promise wrappers around
+      service calls.
+- [ ] Expected failures are typed errors, not thrown exceptions or defects.
+- [ ] Layer requirements are explicit.
+- [ ] Tests use Effect-aware fixtures and focused layers.
+- [ ] Public behavior and wire shapes are preserved unless intentionally
+      changed.

package/specs/effect/routes.md

@@ -0,0 +1,61 @@
+# HTTP Route Patterns
+
+Current guidance for `packages/openfork/src/server/routes/instance/httpapi`.
+
+## Handler Shape
+
+Use `HttpApiBuilder.group(...)` for normal JSON and streaming HTTP API
+endpoints. Yield stable services once while building the handler layer,
+then close over those services in endpoint implementations.
+
+```ts
+export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session", (handlers) =>
+  Effect.gen(function* () {
+    const session = yield* Session.Service
+
+    return handlers.handle("list", () => session.list())
+  }),
+)
+```
+
+Use raw `HttpRouter` only for routes that do not fit the request/response
+HttpApi model, such as WebSocket upgrades or catch-all fallback routes.
+
+Do not rebuild stable layers inside request handlers. Provide stable
+services at the route/layer boundary and use request-level provisioning
+only for request-derived context.
+
+## Error Boundaries
+
+Expected service errors should be mapped at the handler boundary to
+endpoint-declared public HTTP errors. Keep one-off mappings inline. Extract
+small helpers when the same mapping repeats.
+
+Generic middleware should not become a domain-error mapper. It should
+handle cross-cutting concerns and final unknown-defect fallback.
+
+Public JSON errors should be explicit schema contracts declared on each
+endpoint or group. Built-in `HttpApiError.*` is fine only when its generated
+body is intentionally the public wire shape.
+
+Preserve existing `{ name, data }` error bodies until a deliberate breaking
+API change.
+
+## OpenAPI Compatibility
+
+`public.ts` still owns SDK/OpenAPI compatibility transforms. Shrink those
+transforms by tightening source schemas one workaround at a time.
+
+When an OpenAPI-visible source schema changes:
+
+- verify the generated SDK diff is intentional
+- preserve legacy compatibility unless the PR explicitly changes it
+- prefer source-schema fixes over new post-processing rules
+
+## Checklist For Route PRs
+
+- [ ] Stable services are yielded at handler-layer construction.
+- [ ] Expected domain errors are translated at the route boundary.
+- [ ] Endpoint/group error schemas describe the public body and status.
+- [ ] Middleware does not gain new domain-specific name checks.
+- [ ] Raw routes are used only when HttpApi is the wrong abstraction.

package/specs/effect/schema.md

@@ -0,0 +1,88 @@
+# Schema Migration
+
+Use Effect Schema as the source of truth for domain models, DTOs, IDs,
+inputs, outputs, and typed errors.
+
+This is guidance, not an inventory. Do not use this file to track which
+schema modules are complete; verify current state with `git grep` before
+starting a migration.
+
+## Preferred Shapes
+
+Use `Schema.Class` for exported data objects with a clear domain identity:
+
+```ts
+export class Info extends Schema.Class<Info>("Foo.Info")({
+  id: FooID,
+  name: Schema.String,
+  enabled: Schema.Boolean,
+}) {}
+```
+
+Use `Schema.Struct` for local shapes and simple nested objects:
+
+```ts
+const Payload = Schema.Struct({
+  id: FooID,
+  value: Schema.String,
+})
+```
+
+Use `Schema.TaggedErrorClass` for expected domain errors:
+
+```ts
+export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("FooNotFoundError", {
+  id: FooID,
+}) {}
+```
+
+Use branded schema-backed IDs for single-value domain identifiers.
+
+## Boundary Rule
+
+Effect Schema should own the type. Boundaries should consume Effect Schema
+directly or use narrow boundary-specific helpers. Avoid reintroducing a
+generic Effect Schema -> Zod bridge.
+
+Current intentional boundaries:
+
+- Public plugin tools still expose Zod through `tool.schema = z`.
+- Tool parameters use tool-specific JSON Schema helpers.
+- Public config and TUI schema generation goes through the schema script.
+- AI SDK object generation uses Standard Schema / JSON Schema helpers.
+
+When Zod must stay temporarily, leave a short note explaining the boundary
+or compatibility reason.
+
+## Refinements
+
+Reuse named refinements instead of re-spelling constraints:
+
+```ts
+const PositiveInt = Schema.Number.check(Schema.isInt()).check(Schema.isGreaterThan(0))
+const NonNegativeInt = Schema.Number.check(Schema.isInt()).check(Schema.isGreaterThanOrEqualTo(0))
+```
+
+Prefer domain-named leaf schemas when the name improves callers or error
+messages. Avoid adding brands purely for novelty.
+
+## Migration Order
+
+For a domain that still has mixed schemas:
+
+1. Shared leaf models and branded IDs.
+2. Exported `Info`, `Input`, `Output`, and event payload types.
+3. Expected domain errors.
+4. Service-local internal models.
+5. HTTP/tool/AI boundary validators.
+
+Keep public wire shapes stable unless the PR is explicitly a breaking API
+change.
+
+## Checklist For A PR
+
+- [ ] There is one schema source of truth for each migrated type.
+- [ ] Remaining Zod is an intentional boundary choice.
+- [ ] Public JSON/OpenAPI output is unchanged or intentionally updated.
+- [ ] Derived helpers are narrow and boundary-specific.
+- [ ] Tests assert behavior, not duplicated schema implementation details.

package/specs/effect/server-package.md

@@ -0,0 +1,58 @@
+# Server Package Extraction
+
+Practical reference for a future `packages/server` split after the openfork
+server moved to the Effect HttpApi backend.
+
+## Current State
+
+- The server still lives in `packages/openfork`.
+- The runtime and app layer are centralized in `src/effect/app-runtime.ts` and
+  `src/effect/run-service.ts`.
+- The route tree lives under `src/server/routes/instance/httpapi` and is hosted
+  from `src/server/server.ts`.
+- OpenAPI generation is based on the HttpApi contract plus compatibility
+  translation in `src/server/routes/instance/httpapi/public.ts`.
+- There is no standalone `packages/server` workspace yet.
+
+## Future State
+
+Target package layout:
+
+- `packages/core` - shared domain services and schemas
+- `packages/server` - HTTP contracts, handlers, OpenAPI generation, and an
+  embeddable server API
+- `packages/cli` - TUI and CLI entrypoints
+- `packages/sdk` - generated from the server OpenAPI spec
+- `packages/plugin` - plugin authoring surface
+
+## Extraction Rule
+
+Do not create a package cycle.
+
+Until enough shared service code lives outside `packages/openfork`, a future
+`packages/server` should either:
+
+- own pure HttpApi contracts only, or
+- accept host-provided services/layers/callbacks from `packages/openfork`
+
+It should not import `packages/openfork` services while `packages/openfork`
+imports it to host routes.
+
+## Suggested PR Sequence
+
+1. Keep shrinking OpenAPI compatibility shims in `httpapi/public.ts`.
+2. Move stable domain schemas into shared packages only when they no longer
+   depend on openfork-local runtime modules.
+3. Extract pure HttpApi contract modules into `packages/server` once the contract
+   can compile without importing `packages/openfork` implementation details.
+4. Extract handler factories after their service dependencies can be supplied by
+   a host layer instead of imported directly.
+5. Move server hosting last, after package ownership is clear.
+
+## Non-Goals
+
+- Do not revive the old dual-backend migration shape.
+- Do not split server hosting before service dependencies have a clean package
+  boundary.
+- Do not switch SDK generation to a new package until generated output is known
+  to remain compatible.

package/specs/effect/todo.md

@@ -0,0 +1,241 @@
+# Effect TODO
+
+Short roadmap for Effect cleanup in `packages/openfork`.
+
+Current patterns and examples live in [`guide.md`](./guide.md). Error
+boundary migration details live in
+[`error-boundaries-plan.md`](./error-boundaries-plan.md). Test migration rules live in
+[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md).
+Older deep-dive notes in this directory may still be useful, but treat
+this roadmap and the guide as the current entry points.
+
+This is a planning map, not a verified inventory. Before starting a task,
+re-run a targeted `git grep` from current `dev` and update this file if
+the inventory changed.
+
+## Priorities
+
+```text
+P0  ERR + RENDER + HTTP
+    Make expected failures typed, render them well, and stop relying on
+    generic HTTP error guesswork.
+
+P1  TEST
+    Convert touched tests to the ideal Effect test patterns from the guide.
+
+P2  RF
+    Move mutable runtime flags into typed runtime/config services.
+
+P3  GLOBAL
+    Make global paths explicit and remove import-time side effects.
+
+P4  INST + BRIDGE
+    Remove ambient Instance coupling while keeping Promise/callback interop.
+
+P5  PROC + FS
+    Replace raw process/filesystem edges with typed Effect services.
+
+P6  OA
+    Shrink OpenAPI compatibility shims as source schemas improve.
+```
+
+## Work Paths
+
+- `ERR` Typed errors — replace legacy `NamedError.create(...)` and
+  `Effect.die(...)` for expected service failures with
+  `Schema.TaggedErrorClass` errors on the Effect error channel.
+  Shrinks: [`NamedError`](../../../core/src/util/error.ts) usage.
+- `RENDER` User-visible error rendering — preserve structured typed-error
+  details at CLI, HTTP, and tool boundaries.
+  Shrinks: opaque `Error: Name` rendering.
+- `HTTP` HTTP route cleanup — make route errors explicit instead of
+  relying on generic middleware to guess status/body from error names.
+  Shrinks: [`middleware/error.ts`](../../src/server/routes/instance/httpapi/middleware/error.ts)
+  and route-level compatibility shims.
+- `TEST` Effect test migration — use `testEffect`, `it.live`, and
+  `it.instance` with explicit layers.
+  Shrinks: Promise-style tests, sleeps, mutable global test flags.
+- `RF` RuntimeFlags / Flag deletion — move mutable
+  [`Flag`](../../../core/src/flag/flag.ts) reads into typed runtime/config
+  services.
+  Shrinks: [`flag.ts`](../../../core/src/flag/flag.ts),
+  [`test/fixture/flag.ts`](../../test/fixture/flag.ts).
+- `GLOBAL` Global paths / import side effects — make global path state
+  explicit and testable instead of mutable module state.
+  Shrinks: [`global.ts`](../../../core/src/global.ts) import-time side
+  effects, mutable `Global.Path` overrides, and its `Flag` dependency.
+- `INST` Instance context — keep project context explicit through Effect refs
+  and bridge boundaries.
+- `BRIDGE` Promise/callback interop — keep bridge helpers, but reduce
+  legacy ALS coupling.
+  Shrinks: ad hoc Promise/callback re-entry code.
+- `PROC` AppProcess migration — prefer `AppProcess.Service` over raw
+  process wrappers.
+  Shrinks: direct spawn callsites and legacy process helpers.
+- `FS` FSUtil migration — prefer `FSUtil.Service` over raw
+  filesystem APIs.
+  Shrinks: direct `fs` / `Bun.file` service callsites where inappropriate.
+- `RT` Runtime/facade cleanup — remove service-local `makeRuntime`
+  facades when not intentional.
+  Shrinks: async facade exports around services and
+  [`run-service.ts`](../../src/effect/run-service.ts) usage.
+- `OA` OpenAPI compatibility — tighten source schemas instead of
+  post-processing generated OpenAPI.
+  Shrinks: schema workaround blocks in
+  [`public.ts`](../../src/server/routes/instance/httpapi/public.ts).
+
+## P0: Errors, Rendering, And HTTP
+
+This should be the next big cleanup theme. The codebase is moving toward
+typed Effect failures, but the user-facing boundaries still leak old
+shapes and sometimes collapse rich errors into opaque strings.
+
+### Problems
+
+- Some expected service failures still use `NamedError.create(...)` or
+  collapse to `Effect.die(...)`. The storage/worktree/provider-auth
+  conversions are done; an inventory sweep is needed for the rest.
+- HTTP error middleware still guesses status codes from error names —
+  some entries (e.g. storage `NotFound`, provider auth) can now be
+  removed, but the middleware overall has not shrunk.
+- Route handlers and route groups do not consistently declare the public
+  error body they intend to expose.
+- Repeated route error translations do not yet have a clear home: some
+  should stay inline, some deserve tiny shared mapper helpers.
+
+### Target Shape
+
+- Services define expected failures with `Schema.TaggedErrorClass`.
+- Services export an `Error` union and include it in method return types.
+- Expected failures stay on the Effect error channel.
+- `Effect.die(...)` is reserved for defects: bugs, impossible states,
+  violated invariants, or final unknown-boundary fallbacks.
+- Inside `Effect.gen` / `Effect.fn`, use `yield* new MyError(...)` for
+  direct expected failures.
+- Domain services do not import HTTP status codes, `HttpApiError`, or
+  route-specific error schemas.
+- HTTP route groups make their public error contracts obvious.
+- Handlers map service errors to declared HTTP errors at the boundary.
+- Shared mapper helpers are only for repeated translations, not a giant
+  central registry of every domain error.
+- Generic HTTP middleware should shrink; it should not accumulate more
+  name-based domain knowledge.
+
+### Recently completed
+
+- [x] `RENDER-1` CLI tagged config error rendering (#27256, tests #27257).
+- [x] `ERR-1` [`storage/storage.ts`](../../src/storage/storage.ts) typed
+      `NotFoundError` (#27265) and removal of the server defect fallback
+      (#27287).
+- [x] `ERR-2` [`worktree/index.ts`](../../src/worktree/index.ts) typed
+      errors (#27296).
+- [x] `ERR-3` [`provider/auth.ts`](../../src/provider/auth.ts) typed
+      validation/oauth errors (#27301).
+- [x] `HTTP-1` Unknown-500 details no longer leaked (#27251); follow-up
+      to stop exposing named defects (#27471).
+- [x] Session message reads typed and made effectful (#27269, #27275,
+      #27280, #27291).
+- [x] Session HTTP error contracts tightened (#27308); busy-session
+      mapping centralized (#27375, #27473).
+- [x] Provider init (#27484) and LSP init (#27494) errors typed.
+
+### First PR Candidates
+
+- [ ] `HTTP-2` Audit one route group for explicit error contracts and
+      decide which mappings stay inline vs. shared helper.
+- [ ] `ERR-4` Sweep remaining `NamedError.create(...)` and
+      `Effect.die(...)` callsites for expected failures — re-run `git
+grep` to build a current inventory.
+- [ ] `RENDER-2` Audit CLI and TUI surfaces for any remaining opaque
+      `Error: Name` rendering of typed errors.
+
+## P1: Tests
+
+When touching tests, migrate them toward the ideal patterns in
+[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md):
+
+- Use `testEffect(...)` with explicit layers.
+- Prefer `it.instance(...)` for service tests that need an instance.
+- Prefer `it.live(...)` for real timers, filesystem mtimes, child
+  processes, git, locks, or other live integration behavior.
+- Avoid sleeps; wait on real events or deterministic state transitions.
+- Do not mutate `process.env` or mutable globals after layers are built.
+- Use explicit layer variants, such as `RuntimeFlags.layer(...)`, for
+  behavior changes.
+
+## P2: RuntimeFlags / Flag Deletion
+
+Recently completed:
+
+- [x] Plugin/pure-mode flags moved to RuntimeFlags.
+- [x] Tool visibility flags moved to RuntimeFlags.
+- [x] Built-in websearch provider selection uses the same runtime flags as
+      tool visibility.
+- [x] Removed global default-plugin disabling from test preload.
+- [x] `RF-1` Reference reads routed through runtime flags (#27318).
+- [x] `RF-2` Plan-mode prompt read routed through runtime flags (#27320).
+- [x] `RF-3` Event-system reads routed through runtime flags (#27323).
+- [x] `RF-4` Workspaces reads routed through runtime flags for session
+      (#27335), sync (#27336), and control-plane (#27337).
+- [x] LLM client (#27368) and installation client (#27369) routed
+      through runtime flags.
+- [x] TUI plugin runtime flags simplified (#27506).
+- [x] Background-subagents flag moved to RuntimeFlags, then removed
+      (`refactor(task): use runtime flag for background subagents`,
+      `refactor(flags): remove background subagents flag`).
+
+Remaining cleanup:
+
+- [ ] Sweep lingering `Flag.*` reads — many CLI/TUI/config/observability
+      callsites still import [`flag.ts`](../../../core/src/flag/flag.ts).
+      Decide per-callsite whether to route through RuntimeFlags, accept
+      as legitimate env/config boundary, or migrate to typed `Config`.
+- [ ] Delete [`test/fixture/flag.ts`](../../test/fixture/flag.ts) once
+      tests no longer mutate `Flag`.
+- [ ] Delete [`flag.ts`](../../../core/src/flag/flag.ts) once no packages
+      import it.
+
+## P3: Global Paths
+
+[`global.ts`](../../../core/src/global.ts) is real connective tissue, not
+just cosmetic ugliness. It currently mixes path calculation, import-time
+directory creation, `Flock` setup, mutable exported `Path` state, and a
+`Flag` dependency.
+
+Problems to reduce:
+
+- Importing the module creates directories.
+- Tests override `Global.Path` by mutating exported module state.
+- Most callers use `Global.Path` directly instead of the Effect service.
+- `Global.make()` still reads mutable `Flag.OPENCODE_CONFIG_DIR`.
+
+Next PR candidates:
+
+- [ ] Replace mutable `Global.Path` test overrides with explicit test
+      layers or scoped helpers.
+- [ ] Move directory creation and `Flock` setup behind an explicit init
+      boundary where possible.
+- [ ] Remove the `Flag` dependency from global path resolution.
+
+## P4: Instance And Bridge
+
+Instance context migration is complete for the legacy sync shim. Promise and callback interop continues through [`effect/bridge.ts`](../../src/effect/bridge.ts).
+
+Current rules:
+
+- Effect services read instance data from `InstanceRef`, `WorkspaceRef`, `InstanceState`, or explicit arguments.
+- Plain JavaScript callback boundaries use `EffectBridge` or explicit context arguments.
+- Runtime entrypoints must provide refs explicitly when they are instance-scoped.
+
+## Lower Priority Tracks
+
+- `PROC` / `FS` — continue AppProcess and FSUtil migrations as
+  focused PRs when touching relevant files.
+- `RT` — remove service-local runtime facades only when they are not an
+  intentional boundary.
+- `OA` — shrink [`public.ts`](../../src/server/routes/instance/httpapi/public.ts)
+  by tightening source schemas one workaround at a time.
+- `fetch` → `HttpClient` — migrate raw fetch callsites when the caller is
+  already effectful or being effectified.
+- `Tools` — remaining tool cleanup is narrow: `webfetch` HTML extraction
+  and `shell` raw stream/promise edges.

package/specs/effect/tools.md

@@ -0,0 +1,88 @@
+# Tool migration
+
+Practical reference for the current tool-migration state in `packages/openfork`.
+
+## Status
+
+`Tool.Def.execute` and `Tool.Info.init` already return `Effect` on this branch, and the built-in tool surface is now largely on the target shape.
+
+The current exported tools in `src/tool` all use `Tool.define(...)` with Effect-based initialization, and nearly all of them already build their tool body with `Effect.gen(...)` and `Effect.fn(...)`.
+
+So the remaining work is no longer "convert tools to Effect at all". The remaining work is mostly:
+
+1. remove Promise and raw platform bridges inside individual tool bodies
+2. swap tool internals to Effect-native services like `FSUtil`, `HttpClient`, and `ChildProcessSpawner`
+3. keep tests and callers aligned with `yield* info.init()` and real service graphs
+
+## Current shape
+
+`Tool.define(...)` is already the Effect-native helper here.
+
+- `init` is an `Effect`
+- `info.init()` returns an `Effect`
+- `execute(...)` returns an `Effect`
+
+That means a tool does not need a separate `Tool.defineEffect(...)` helper to count as migrated. A tool is effectively migrated when its init and execute path stay Effect-native, even if some internals still bridge to Promise-based or raw APIs.
+
+## Tests
+
+Tool tests should use the existing Effect helpers in `packages/openfork/test/lib/effect.ts`:
+
+- Use `testEffect(...)` / `it.live(...)` instead of creating fake local wrappers around effectful tools.
+- Yield the real tool export, then initialize it: `const info = yield* ReadTool`, `const tool = yield* info.init()`.
+- Run tests inside a real instance with `provideTmpdirInstance(...)` or `provideInstance(tmpdirScoped(...))` so instance-scoped services resolve exactly as they do in production.
+
+This keeps tool tests aligned with the production service graph and makes follow-up cleanup mostly mechanical.
+
+## Exported tools
+
+These exported tool definitions currently use `Tool.define(...)` in `src/tool`:
+
+- [x] `apply_patch.ts`
+- [x] `bash.ts`
+- [x] `edit.ts`
+- [x] `glob.ts`
+- [x] `grep.ts`
+- [x] `invalid.ts`
+- [x] `lsp.ts`
+- [x] `plan.ts`
+- [x] `question.ts`
+- [x] `read.ts`
+- [x] `skill.ts`
+- [x] `task.ts`
+- [x] `todo.ts`
+- [x] `webfetch.ts`
+- [x] `websearch.ts`
+- [x] `write.ts`
+
+Notes:
+
+- There is no current `ls.ts` tool file on this branch.
+- `truncate.ts` is an Effect service used by tools, not a tool definition itself.
+- `mcp-exa.ts`, `external-directory.ts`, and `schema.ts` are support modules, not standalone tool definitions.
+
+## Follow-up cleanup
+
+Most exported tools are already on the intended Effect-native shape. The remaining cleanup is narrower than the old checklist implied.
+
+Current spot cleanups worth tracking:
+
+- [x] `read.ts` — streams through `FSUtil.Service.stream` with `Stream.splitLines`; the legacy Node stream / `readline` helper is gone
+- [ ] `bash.ts` — already uses Effect child-process primitives; only keep tracking shell-specific platform bridges and parser/loading details as they come up
+- [ ] `webfetch.ts` — already uses `HttpClient`; remaining work is limited to smaller boundary helpers like HTML text extraction
+- [ ] `file/ripgrep.ts` — adjacent to tool migration; still has raw fs/process usage that affects `grep.ts` and file-search routes
+- [x] `patch/index.ts` — apply path now returns `Effect` over `FSUtil.Service`; the parser and chunk replacer stay pure
+
+Notable items that are already effectively on the target path and do not need separate migration bullets right now:
+
+- `apply_patch.ts`
+- `grep.ts`
+- `write.ts`
+- `websearch.ts`
+- `edit.ts`
+
+## Filesystem notes
+
+Current raw fs users that still appear relevant here:
+
+- `file/ripgrep.ts` — `fs/promises`