@epoch-ai/cli 2.2.4 → 2.2.5

package/script/publish.ts

@@ -1,184 +0,0 @@
-#!/usr/bin/env bun
-import { $ } from "bun"
-import pkg from "../package.json"
-import { Script } from "@epoch-ai/script"
-import { fileURLToPath } from "url"
-
-const dir = fileURLToPath(new URL("..", import.meta.url))
-process.chdir(dir)
-
-const binaries: Record<string, string> = {}
-for (const filepath of new Bun.Glob("**/package.json").scanSync({ cwd: "./dist" })) {
-  if (filepath.includes("node_modules")) continue
-  const pkg = await Bun.file(`./dist/${filepath}`).json()
-  if (pkg.name === "@epoch-ai/cli") continue
-  binaries[pkg.name] = pkg.version
-}
-console.log("binaries", binaries)
-const version = Object.values(binaries)[0]
-
-await $`mkdir -p ./dist/${pkg.name}`
-await $`cp -r ./bin ./dist/${pkg.name}/bin`
-await $`cp ./script/postinstall.mjs ./dist/${pkg.name}/postinstall.mjs`
-await Bun.file(`./dist/${pkg.name}/LICENSE`).write(await Bun.file("../../LICENSE").text())
-
-await Bun.file(`./dist/${pkg.name}/package.json`).write(
-  JSON.stringify(
-    {
-      name: pkg.name,
-      bin: {
-        epochcli: `./bin/epochcli`,
-      },
-      scripts: {
-        postinstall: "node ./postinstall.mjs",
-      },
-      version: version,
-      license: pkg.license,
-      optionalDependencies: binaries,
-    },
-    null,
-    2,
-  ),
-)
-
-const tasks = Object.entries(binaries).map(async ([name]) => {
-  const pkgDir = `./dist/${name}`
-  if (process.platform !== "win32") {
-    await $`chmod -R 755 .`.cwd(pkgDir)
-  }
-  await $`bun pm pack`.cwd(pkgDir)
-  await $`npm publish *.tgz --access public --tag latest`.cwd(pkgDir).nothrow()
-})
-await Promise.all(tasks)
-await $`cd ./dist/${pkg.name} && bun pm pack && npm publish *.tgz --access public --tag latest`.nothrow()
-
-// const image = "ghcr.io/benjamesmurray/epoch-cli"
-// const platforms = "linux/amd64,linux/arm64"
-// const tags = [`${image}:${version}`, `${image}:${Script.channel}`]
-// const tagFlags = tags.flatMap((t) => ["-t", t])
-// await $`docker buildx build --platform ${platforms} ${tagFlags} --push .`
-
-// registries
-if (!Script.preview) {
-  // Calculate SHA values
-  const arm64Sha = await $`sha256sum ./dist/@epoch-ai/cli-linux-arm64.tar.gz | cut -d' ' -f1`.text().then((x) => x.trim())
-  const x64Sha = await $`sha256sum ./dist/@epoch-ai/cli-linux-x64.tar.gz | cut -d' ' -f1`.text().then((x) => x.trim())
-  const macX64Sha = await $`sha256sum ./dist/@epoch-ai/cli-darwin-x64.zip | cut -d' ' -f1`.text().then((x) => x.trim())
-  const macArm64Sha = await $`sha256sum ./dist/@epoch-ai/cli-darwin-arm64.zip | cut -d' ' -f1`.text().then((x) => x.trim())
-
-  const [pkgver, _subver = ""] = Script.version.split(/(-.*)/, 2)
-
-  // arch
-  const binaryPkgbuild = [
-    "# Maintainer: dax",
-    "# Maintainer: adam",
-    "",
-    "pkgname='@epoch-ai/cli-bin'",
-    `pkgver=${pkgver}`,
-    `_subver=${_subver}`,
-    "options=('!debug' '!strip')",
-    "pkgrel=1",
-    "pkgdesc='The AI coding agent built for the terminal.'",
-    "url='https://github.com/benjamesmurray/epoch-cli'",
-    "arch=('aarch64' 'x86_64')",
-    "license=('MIT')",
-    "provides=('epochcli')",
-    "conflicts=('epochcli')",
-    "depends=('ripgrep')",
-    "",
-    `source_aarch64=("\${pkgname}_\${pkgver}_aarch64.tar.gz::https://github.com/benjamesmurray/epoch-cli/releases/download/v\${pkgver}\${_subver}/@epoch-ai/cli-linux-arm64.tar.gz")`,
-    `sha256sums_aarch64=('${arm64Sha}')`,
-
-    `source_x86_64=("\${pkgname}_\${pkgver}_x86_64.tar.gz::https://github.com/benjamesmurray/epoch-cli/releases/download/v\${pkgver}\${_subver}/@epoch-ai/cli-linux-x64.tar.gz")`,
-    `sha256sums_x86_64=('${x64Sha}')`,
-    "",
-    "package() {",
-    '  install -Dm755 ./epochcli "${pkgdir}/usr/bin/epochcli"',
-    "}",
-    "",
-  ].join("\n")
-
-  for (const [pkg, pkgbuild] of [["@epoch-ai/cli-bin", binaryPkgbuild]]) {
-    for (let i = 0; i < 30; i++) {
-      try {
-        await $`rm -rf ./dist/aur-${pkg}`
-        await $`git clone ssh://aur@aur.archlinux.org/${pkg}.git ./dist/aur-${pkg}`
-        await $`cd ./dist/aur-${pkg} && git checkout master`
-        await Bun.file(`./dist/aur-${pkg}/PKGBUILD`).write(pkgbuild)
-        await $`cd ./dist/aur-${pkg} && makepkg --printsrcinfo > .SRCINFO`
-        await $`cd ./dist/aur-${pkg} && git add PKGBUILD .SRCINFO`
-        await $`cd ./dist/aur-${pkg} && git commit -m "Update to v${Script.version}"`
-        await $`cd ./dist/aur-${pkg} && git push`
-        break
-      } catch (e) {
-        continue
-      }
-    }
-  }
-
-  // Homebrew formula
-  const homebrewFormula = [
-    "# typed: false",
-    "# frozen_string_literal: true",
-    "",
-    "# This file was generated by GoReleaser. DO NOT EDIT.",
-    "class Epoch < Formula",
-    `  desc "The AI coding agent built for the terminal."`,
-    `  homepage "https://github.com/benjamesmurray/epoch-cli"`,
-    `  version "${Script.version.split("-")[0]}"`,
-    "",
-    `  depends_on "ripgrep"`,
-    "",
-    "  on_macos do",
-    "    if Hardware::CPU.intel?",
-    `      url "https://github.com/benjamesmurray/epoch-cli/releases/download/v${Script.version}/@epoch-ai/cli-darwin-x64.zip"`,
-    `      sha256 "${macX64Sha}"`,
-    "",
-    "      def install",
-    '        bin.install "epochcli"',
-    "      end",
-    "    end",
-    "    if Hardware::CPU.arm?",
-    `      url "https://github.com/benjamesmurray/epoch-cli/releases/download/v${Script.version}/@epoch-ai/cli-darwin-arm64.zip"`,
-    `      sha256 "${macArm64Sha}"`,
-    "",
-    "      def install",
-    '        bin.install "epochcli"',
-    "      end",
-    "    end",
-    "  end",
-    "",
-    "  on_linux do",
-    "    if Hardware::CPU.intel? and Hardware::CPU.is_64_bit?",
-    `      url "https://github.com/benjamesmurray/epoch-cli/releases/download/v${Script.version}/@epoch-ai/cli-linux-x64.tar.gz"`,
-    `      sha256 "${x64Sha}"`,
-    "      def install",
-    '        bin.install "epochcli"',
-    "      end",
-    "    end",
-    "    if Hardware::CPU.arm? and Hardware::CPU.is_64_bit?",
-    `      url "https://github.com/benjamesmurray/epoch-cli/releases/download/v${Script.version}/@epoch-ai/cli-linux-arm64.tar.gz"`,
-    `      sha256 "${arm64Sha}"`,
-    "      def install",
-    '        bin.install "epochcli"',
-    "      end",
-    "    end",
-    "  end",
-    "end",
-    "",
-    "",
-  ].join("\n")
-
-  const token = process.env.GITHUB_TOKEN
-  if (!token) {
-    console.error("GITHUB_TOKEN is required to update homebrew tap")
-    process.exit(1)
-  }
-  const tap = `https://x-access-token:${token}@github.com/anomalyco/homebrew-tap.git`
-  await $`rm -rf ./dist/homebrew-tap`
-  await $`git clone ${tap} ./dist/homebrew-tap`
-  await Bun.file("./dist/homebrew-tap/epochcli.rb").write(homebrewFormula)
-  await $`cd ./dist/homebrew-tap && git add epochcli.rb`
-  await $`cd ./dist/homebrew-tap && git commit -m "Update to v${Script.version}"`
-  await $`cd ./dist/homebrew-tap && git push`
-}

package/script/schema.ts

@@ -1,63 +0,0 @@
-#!/usr/bin/env bun
-
-import { z } from "zod"
-import { Config } from "../src/config/config"
-import { TuiConfig } from "../src/config/tui"
-
-function generate(schema: z.ZodType) {
-  const result = z.toJSONSchema(schema, {
-    io: "input", // Generate input shape (treats optional().default() as not required)
-    /**
-     * We'll use the `default` values of the field as the only value in `examples`.
-     * This will ensure no docs are needed to be read, as the configuration is
-     * self-documenting.
-     *
-     * See https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.9.5
-     */
-    override(ctx) {
-      const schema = ctx.jsonSchema
-
-      // Preserve strictness: set additionalProperties: false for objects
-      if (
-        schema &&
-        typeof schema === "object" &&
-        schema.type === "object" &&
-        schema.additionalProperties === undefined
-      ) {
-        schema.additionalProperties = false
-      }
-
-      // Add examples and default descriptions for string fields with defaults
-      if (schema && typeof schema === "object" && "type" in schema && schema.type === "string" && schema?.default) {
-        if (!schema.examples) {
-          schema.examples = [schema.default]
-        }
-
-        schema.description = [schema.description || "", `default: \`${schema.default}\``]
-          .filter(Boolean)
-          .join("\n\n")
-          .trim()
-      }
-    },
-  }) as Record<string, unknown> & {
-    allowComments?: boolean
-    allowTrailingCommas?: boolean
-  }
-
-  // used for json lsps since config supports jsonc
-  result.allowComments = true
-  result.allowTrailingCommas = true
-
-  return result
-}
-
-const configFile = process.argv[2]
-const tuiFile = process.argv[3]
-
-console.log(configFile)
-await Bun.write(configFile, JSON.stringify(generate(Config.Info), null, 2))
-
-if (tuiFile) {
-  console.log(tuiFile)
-  await Bun.write(tuiFile, JSON.stringify(generate(TuiConfig.Info), null, 2))
-}

package/script/seed-e2e.ts

@@ -1,60 +0,0 @@
-const dir = process.env.EPOCHCLI_E2E_PROJECT_DIR ?? process.cwd()
-const title = process.env.EPOCHCLI_E2E_SESSION_TITLE ?? "E2E Session"
-const text = process.env.EPOCHCLI_E2E_MESSAGE ?? "Seeded for UI e2e"
-const model = process.env.EPOCHCLI_E2E_MODEL ?? "epochcli/gpt-5-nano"
-const parts = model.split("/")
-const providerID = parts[0] ?? "epochcli"
-const modelID = parts[1] ?? "gpt-5-nano"
-const now = Date.now()
-
-const seed = async () => {
-  const { Instance } = await import("../src/project/instance")
-  const { InstanceBootstrap } = await import("../src/project/bootstrap")
-  const { Config } = await import("../src/config/config")
-  const { Session } = await import("../src/session")
-  const { MessageID, PartID } = await import("../src/session/schema")
-  const { Project } = await import("../src/project/project")
-  const { ModelID, ProviderID } = await import("../src/provider/schema")
-  const { ToolRegistry } = await import("../src/tool/registry")
-
-  try {
-    await Instance.provide({
-      directory: dir,
-      init: InstanceBootstrap,
-      fn: async () => {
-        await Config.waitForDependencies()
-        await ToolRegistry.ids()
-
-        const session = await Session.create({ title })
-        const messageID = MessageID.ascending()
-        const partID = PartID.ascending()
-        const message = {
-          id: messageID,
-          sessionID: session.id,
-          role: "user" as const,
-          time: { created: now },
-          agent: "build",
-          model: {
-            providerID: ProviderID.make(providerID),
-            modelID: ModelID.make(modelID),
-          },
-        }
-        const part = {
-          id: partID,
-          sessionID: session.id,
-          messageID,
-          type: "text" as const,
-          text,
-          time: { start: now },
-        }
-        await Session.updateMessage(message)
-        await Session.updatePart(part)
-        await Project.update({ projectID: Instance.project.id, name: "E2E Project" })
-      },
-    })
-  } finally {
-    await Instance.disposeAll().catch(() => {})
-  }
-}
-
-await seed()

package/script/upgrade-opentui.ts

@@ -1,64 +0,0 @@
-#!/usr/bin/env bun
-
-import path from "node:path"
-
-const raw = process.argv[2]
-if (!raw) {
-  console.error("Usage: bun run script/upgrade-opentui.ts <version>")
-  process.exit(1)
-}
-
-const ver = raw.replace(/^v/, "")
-const root = path.resolve(import.meta.dir, "../../..")
-const skip = new Set([".git", ".epochcli", ".turbo", "dist", "node_modules"])
-const keys = ["@opentui/core", "@opentui/solid"] as const
-
-const files = (await Array.fromAsync(new Bun.Glob("**/package.json").scan({ cwd: root }))).filter(
-  (file) => !file.split("/").some((part) => skip.has(part)),
-)
-
-const set = (cur: string) => {
-  if (cur.startsWith(">=")) return `>=${ver}`
-  if (cur.startsWith("^")) return `^${ver}`
-  if (cur.startsWith("~")) return `~${ver}`
-  return ver
-}
-
-const edit = (obj: unknown) => {
-  if (!obj || typeof obj !== "object") return false
-  const map = obj as Record<string, unknown>
-  return keys
-    .map((key) => {
-      const cur = map[key]
-      if (typeof cur !== "string") return false
-      const next = set(cur)
-      if (next === cur) return false
-      map[key] = next
-      return true
-    })
-    .some(Boolean)
-}
-
-const out = (
-  await Promise.all(
-    files.map(async (rel) => {
-      const file = path.join(root, rel)
-      const txt = await Bun.file(file).text()
-      const json = JSON.parse(txt)
-      const hit = [json.dependencies, json.devDependencies, json.peerDependencies].map(edit).some(Boolean)
-      if (!hit) return null
-      await Bun.write(file, `${JSON.stringify(json, null, 2)}\n`)
-      return rel
-    }),
-  )
-).filter((item): item is string => item !== null)
-
-if (out.length === 0) {
-  console.log("No opentui deps found")
-  process.exit(0)
-}
-
-console.log(`Updated opentui to ${ver} in:`)
-for (const file of out) {
-  console.log(`- ${file}`)
-}

package/specs/effect-migration.md

@@ -1,310 +0,0 @@
-# Effect patterns
-
-Practical reference for new and migrated Effect code in `packages/epochcli`.
-
-## 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, FileTime, 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`.
-
-## Service shape
-
-Every service follows the same pattern — a single namespace with the service definition, layer, `runPromise`, and async facade functions:
-
-```ts
-export namespace Foo {
-  export interface Interface {
-    readonly get: (id: FooID) => Effect.Effect<FooInfo, FooError>
-  }
-
-  export class Service extends ServiceMap.Service<Service, Interface>()("@epochcli/Foo") {}
-
-  export const layer = Layer.effect(
-    Service,
-    Effect.gen(function* () {
-      // For instance-scoped services:
-      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 })
-    }),
-  )
-
-  // Optional: wire dependencies
-  export const defaultLayer = layer.pipe(Layer.provide(FooDep.layer))
-
-  // Per-service runtime (inside the namespace)
-  const { runPromise } = makeRuntime(Service, defaultLayer)
-
-  // Async facade functions
-  export async function get(id: FooID) {
-    return runPromise((svc) => svc.get(id))
-  }
-}
-```
-
-Rules:
-
-- Keep everything in one namespace, one file — no separate `service.ts` / `index.ts` split
-- `runPromise` goes inside the namespace (not exported unless tests need it)
-- Facade functions are plain `async function` — no `fn()` wrappers
-- Use `Effect.fn("Namespace.method")` for all Effect functions (for tracing)
-- No `Layer.fresh` — InstanceState handles per-directory isolation
-
-## 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
-
-Fully migrated (single namespace, InstanceState where needed, flattened facade):
-
-- [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] `FileTime` — `file/time.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] `Provider` — `provider/provider.ts`
-- [x] `Storage` — `storage/storage.ts`
-
-Still open:
-
-- [ ] `SessionTodo` — `session/todo.ts`
-- [ ] `ShareNext` — `share/share-next.ts`
-- [ ] `SyncEvent` — `sync/index.ts`
-- [ ] `Workspace` — `control-plane/workspace.ts`
-
-## Tool interface → Effect
-
-Once individual tools are effectified, change `Tool.Info` (`tool/tool.ts`) so `init` and `execute` return `Effect` instead of `Promise`. This lets tool implementations compose natively with the Effect pipeline rather than being wrapped in `Effect.promise()` at the call site. Requires:
-
-1. Migrate each tool to return Effects
-2. Update `Tool.define()` factory to work with Effects
-3. Update `SessionPrompt` to `yield*` tool results instead of `await`ing
-
-### Tool migration details
-
-Until the tool interface itself returns `Effect`, use this transitional pattern for migrated tools:
-
-- `Tool.defineEffect(...)` should `yield*` the services the tool depends on and close over them in the returned tool definition.
-- Keep the bridge at the Promise boundary only. Prefer a single `Effect.runPromise(...)` in the temporary `async execute(...)` implementation, and move the inner logic into `Effect.fn(...)` helpers instead of scattering `runPromise` islands through the tool body.
-- If a tool starts requiring new services, wire them into `ToolRegistry.defaultLayer` so production callers resolve the same dependencies as tests.
-
-Tool tests should use the existing Effect helpers in `packages/epochcli/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* Effect.promise(() => 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 migrated tool tests aligned with the production service graph today, and makes the eventual `Tool.Info` → `Effect` cleanup mostly mechanical later.
-
-Individual tools, ordered by value:
-
-- [ ] `apply_patch.ts` — HIGH: multi-step orchestration, error accumulation, Bus events
-- [ ] `bash.ts` — HIGH: shell orchestration, quoting, timeout handling, output capture
-- [x] `read.ts` — HIGH: streaming I/O, readline, binary detection → FileSystem + Stream
-- [ ] `edit.ts` — HIGH: multi-step diff/format/publish pipeline, FileWatcher lock
-- [ ] `grep.ts` — MEDIUM: spawns ripgrep → ChildProcessSpawner, timeout handling
-- [ ] `write.ts` — MEDIUM: permission checks, diagnostics polling, Bus events
-- [ ] `codesearch.ts` — MEDIUM: HTTP + SSE + manual timeout → HttpClient + Effect.timeout
-- [ ] `webfetch.ts` — MEDIUM: fetch with UA retry, size limits → HttpClient
-- [ ] `websearch.ts` — MEDIUM: MCP over HTTP → HttpClient
-- [ ] `batch.ts` — MEDIUM: parallel execution, per-call error recovery → Effect.all
-- [ ] `task.ts` — MEDIUM: task state management
-- [ ] `ls.ts` — MEDIUM: bounded directory listing over ripgrep-backed traversal
-- [ ] `multiedit.ts` — MEDIUM: sequential edit orchestration over `edit.ts`
-- [ ] `glob.ts` — LOW: simple async generator
-- [ ] `lsp.ts` — LOW: dispatch switch over LSP operations
-- [ ] `question.ts` — LOW: prompt wrapper
-- [ ] `skill.ts` — LOW: skill tool adapter
-- [ ] `todo.ts` — LOW: todo persistence wrapper
-- [ ] `invalid.ts` — LOW: invalid-tool fallback
-- [ ] `plan.ts` — LOW: plan file operations
-
-## 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)
-
-- [ ] `file/index.ts` — 1 remaining `Filesystem.readText()` call in untracked diff handling
-- [ ] `config/config.ts` — 5 remaining `Filesystem.*` calls in `installDependencies()`
-- [ ] `provider/provider.ts` — 1 remaining `Filesystem.readJson()` call for recent model state
-
-### `Process.spawn` → `ChildProcessSpawner` (yield in layer)
-
-- [ ] `format/formatter.ts` — 2 remaining `Process.spawn()` checks (`air`, `uv`)
-- [ ] `lsp/server.ts` — multiple `Process.spawn()` installs/download helpers
-
-## Filesystem consolidation
-
-`util/filesystem.ts` (raw fs wrapper) is currently imported by **34 files**. The effectified `AppFileSystem` service (`filesystem/index.ts`) is currently imported by **15 files**. As services and tools are effectified, they should switch from `Filesystem.*` to yielding `AppFileSystem.Service` — this happens naturally during each migration, not as a separate effort.
-
-Similarly, **21 files** still import raw `fs` or `fs/promises` directly. These should migrate to `AppFileSystem` or `Filesystem.*` as they're touched.
-
-Current raw fs users that will convert during tool migration:
-
-- `tool/read.ts` — fs.createReadStream, readline
-- `tool/apply_patch.ts` — fs/promises
-- `file/ripgrep.ts` — fs/promises
-- `patch/index.ts` — fs, fs/promises
-
-## 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