Merge pull request #10662 from Kilo-Org/effect-facade-ratchet-pr-10661

ci(cli): prevent new shared Effect promise facades

.github/workflows/check-opencode-annotations.yml

@@ -38,6 +38,9 @@ jobs:
           fi
 
       # kilocode_change start
+      - name: Check Effect Promise facade allowlist
+        run: bun run script/check-opencode-promise-facades.ts
+
       - name: Check workflow allowlist
         run: bun run script/check-workflows.ts
       # kilocode_change end

AGENTS.md

@@ -21,6 +21,7 @@ Kilo CLI is an open source AI coding agent that generates code from natural lang
 - **Source links**: After adding or changing URLs in `packages/kilo-vscode/`, `packages/kilo-vscode/webview-ui/`, or `packages/opencode/src/`, run `bun run script/extract-source-links.ts` from the repo root and commit the updated `packages/kilo-docs/source-links.md`. CI runs this check — the build fails if the file is stale.
 - **kilocode_change check**: `bun run check-kilocode-change` from `packages/kilo-vscode/`. CI runs this — `kilocode_change` is a marker for upstream merge conflicts and must not appear in `packages/kilo-vscode/` or `packages/kilo-ui/` (these are entirely Kilo Code additions). Remove the markers before pushing.
 - **opencode annotation check**: `bun run script/check-opencode-annotations.ts` from repo root. CI runs this on PRs touching `packages/opencode/` — every Kilo-specific change in shared opencode files must be annotated with `kilocode_change` markers. Exempt paths (no markers needed): `packages/opencode/src/kilocode/`, `packages/opencode/test/kilocode/`, and any path containing `kilocode` in the name.
+- **Effect facade ratchet**: Do not add runtime-backed Promise facades to shared `packages/opencode/src` Effect services; use service dependencies, `AppRuntime`, or Kilo-owned boundaries. Run `bun run script/check-opencode-promise-facades.ts` when touching service adapters.
 - **workflow allowlist**: `bun run script/check-workflows.ts` from repo root. CI runs this as part of the annotations workflow — any `.yml` / `.yaml` file added to or removed from `.github/workflows/` must be reflected in the hardcoded list in `script/check-workflows.ts`. Prevents upstream-merged workflows from silently starting to run in our CI.
 - **Backend/SDK programmatic testing**: see [TESTING.md](./TESTING.md) for spawning the local main-branch backend (`bun dev serve`) and driving it via `curl` — use this instead of `kilo serve` (prod binary) when testing backend fixes.
 

script/check-opencode-promise-facades.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env bun
+// kilocode_change - new file
+
+/**
+ * Prevents new service-local runtimes in shared Effect modules while the
+ * remaining Kilo Promise facades are migrated away.
+ *
+ * Existing sites are allowed only when classified below. Remove transitional
+ * entries after their migration lands so later reintroductions fail CI.
+ */
+
+import path from "node:path"
+
+const ROOT = path.resolve(import.meta.dir, "..")
+const DIR = path.join(ROOT, "packages", "opencode", "src")
+const PATTERN = /makeRuntime\s*\(\s*Service\s*,/g
+
+const allow: Record<string, string> = {
+  "bus/index.ts": "core bus callback and synchronous runtime boundary",
+  "cli/cmd/tui/config/tui.ts": "separately tracked TUI config facade",
+  "installation/index.ts": "existing installation facade outside #10655",
+  "permission/index.ts": "transitional facade removed by #10620",
+  "project/project.ts": "transitional facade removed by #10620",
+  "project/vcs.ts": "transitional facade removed by #10620",
+  "provider/provider.ts": "transitional facade tracked by #10655",
+  "question/index.ts": "transitional facade deferred for upstream reconciliation in #10655",
+  "session/compaction.ts": "existing compaction facade outside #10655",
+  "session/prompt.ts": "transitional facade tracked by #10655",
+  "session/session.ts": "transitional facade tracked by #10655",
+  "session/summary.ts": "transitional facade removed by #10620",
+  "snapshot/index.ts": "transitional facade tracked by #10660",
+  "storage/storage.ts": "transitional facade tracked by #10659",
+  "sync/index.ts": "sync event runtime boundary",
+  "tool/registry.ts": "transitional facade removed by #10620",
+}
+
+const owned = (file: string) => file.startsWith("kilocode/") || file.startsWith("kilo-sessions/")
+const hits: Array<{ file: string; line: number }> = []
+const glob = new Bun.Glob("**/*.ts")
+
+for (const file of glob.scanSync({ cwd: DIR, onlyFiles: true })) {
+  if (owned(file)) continue
+  const text = await Bun.file(path.join(DIR, file)).text()
+  for (const match of text.matchAll(PATTERN)) {
+    const line = text.slice(0, match.index ?? 0).split("\n").length
+    hits.push({ file, line })
+  }
+}
+
+const invalid = hits.filter((hit) => !allow[hit.file])
+const drift = Object.entries(allow).flatMap(([file, reason]) => {
+  const count = hits.filter((hit) => hit.file === file).length
+  if (count === 1) return []
+  return [`  packages/opencode/src/${file}: expected 1 classified site, found ${count} (${reason})`]
+})
+
+if (invalid.length > 0 || drift.length > 0) {
+  if (invalid.length > 0) {
+    console.error("Found unclassified service-local Effect runtimes in shared opencode modules:")
+    for (const hit of invalid) console.error(`  packages/opencode/src/${hit.file}:${hit.line}`)
+    console.error("")
+  }
+  if (drift.length > 0) {
+    console.error("Classified service-local runtime exceptions no longer match the current source:")
+    for (const item of drift) console.error(item)
+    console.error("")
+  }
+  console.error("Do not add Promise facades to shared Effect services.")
+  console.error("Yield the service directly, or bridge at an existing AppRuntime or Kilo-owned boundary.")
+  console.error("Remove migrated exceptions, or classify intentional runtime changes with an explicit reason.")
+  process.exit(1)
+}
+
+console.log(`check-opencode-promise-facades: ${hits.length} classified runtime site(s), no facade drift found.`)