Distillation

Date: Sep 8, 2026

• 🔴 [requested-review] (03:07) User requested a read-only final correctness review of the exact current repository diff under /home/byk/Code/opencode-v2-pilot and every line of the isolated plugin /home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty.ts; requested current file:line evidence, classification as PASS/CONCERN/MUST-FIX, and an ending of exactly MERGE or DO-NOT-MERGE.
• 🔴 (03:07) User stated prior blockers were addressed through canonical ctx.permission.assert, fixed environment, canonical/revalidated cwd, per-owner/global limits, close-based completion, awaited TERM-to-KILL cleanup, stream error handling, bounded writes, linear paged reads, and bounded grep.
• 🔴 (03:07) User directed the review to check API type design, adapter scope/error semantics, permission-decline behavior, process-lifecycle races, output completeness, resource bounds, and regressions.
• 🔴 (03:07) User directed that no files be edited and no services be started during the review.
• 🟡 (03:08) Repository status showed changed files including packages/core/src/plugin/host.ts, packages/core/test/plugin.test.ts, packages/core/test/plugin/host.ts, and packages/plugin/src/promise/adapter.ts, plus untracked packages/cli/dist-v2-pilot-final/; additional status/diff content was elided.
• 🟡 (03:08) Diff evidence included a test named retains Promise plugin groups for later registrations and ignores a disabled group's attempts, using plugin ID promise-plugin; its deferred ctx.command.transform adds command late, throws Error("late Promise failure"), expects plugin state status: "failed" with an error containing command.transform, and verifies command late remains undefined across repeated registration attempts.
• 🟡 (03:08) Diff evidence included permission test identifier messageID: "msg_plugin_permission" and an invocation using Session.ID.make("ses_plugin"), prompt { text: "" }, and delivery "steer".
• 🟡 (03:08) Repository instruction files discovered: /home/byk/Code/opencode-v2-pilot/services/www/src/docs/AGENTS.md, /home/byk/Code/opencode-v2-pilot/services/www/AGENTS.md, /home/byk/Code/opencode-v2-pilot/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/desktop/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/ui/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/core/src/tool/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/stats/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/tui/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/session-ui/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/schema/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/plugin/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/ai/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/codemode/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/cli/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/app/AGENTS.md, /home/byk/Code/opencode-v2-pilot/packages/app/e2e/performance/AGENTS.md, and /home/byk/Code/opencode-v2-pilot/packages/app/e2e/AGENTS.md.
• 🔴 (03:08) User’s repository convention requires running bun run generate from packages/client after changing the public Protocol or Server HttpApi; generated client files must not be edited directly.
• 🔴 (03:08) User’s repository dependency rule is: runtime dependencies flow from Schema to Core and Protocol, then from Core and Protocol to Server; Client runtime code may depend on Schema and Protocol but never Core or Server; sdk composes Client, Core, and Server.
• 🔴 (03:08) User’s implementation-scope convention places current changes in packages/core, packages/cli, packages/server, packages/protocol, packages/schema, and related generated client surfaces when required.
• 🔴 (03:08) User stated the repository does not use Changesets; do not add .changeset files and use the existing release workflow.
• 🔴 (03:08) User stated the default repository branch is v2; new branches/worktrees default to v2 or origin/v2 if local v2 is unavailable, pull requests default to target v2, and diffs should use v2 or origin/v2 because local main may not exist.
• 🔴 (03:08) User’s branch-name convention is at most three hyphen-separated words, with no slashes or type prefixes such as feat/ or fix/; examples are session-recovery, fix-scroll-state, and regenerate-sdk.
• 🔴 (03:08) User’s commit and PR-title convention is type(scope): summary; valid types are feat, fix, docs, chore, refactor, and test, with optional scopes such as core, opencode, tui, app, desktop, sdk, or plugin.
• 🔴 (03:08) User requires imports never be aliased: do not use forms such as import { foo as bar } from "..." or resolve as pathResolve.
• 🔴 (03:08) User requires never using type-position import("...") references, including forms such as Schema.declare<import("@opencode/plugin/effect/plugin").Plugin["effect"]>; only a genuine name collision with no alternative permits an aliased type import such as import type { Plugin as PluginDefinition } from "...", and even then it is strongly disfavored.
• 🔴 (03:08) User requires never using star imports, including import * as Foo from "..." and import type * as Foo from "...".
• 🔴 (03:08) User’s namespace-import convention is to import a module’s exported namespace by name, e.g. import { Project } from "@opencode/core/project", then use Project.ID.
• 🔴 (03:08) User prefers dynamic imports for heavy modules needed only in selected code paths, especially startup-sensitive entrypoints; bindings should be destructured near the top of the narrowest relevant scope, branch-specific imports should remain within their branch, and inline chains such as await import("./module").then((mod) => mod.value()) or (await import("./module")).value() should be avoided.
• 🔴 (03:08) User requires bun typecheck always be run from package directories such as packages/core, never tsc directly.
• 🔴 (03:08) User stated tests cannot run from the repository root because of the do-not-run-tests-from-root guard; tests must run from package directories such as packages/core.
• 🔴 (03:08) User prefers tests of actual implementation with mocks avoided as much as possible; globalThis.* should not be used unless it is the only option, and implementation logic must not be duplicated into tests.
• 🔴 (03:08) User’s general code-style rules include: keep code in one function unless composable/reusable; validate unknown values once at the owning boundary; do not defensively revalidate schema-, constructor-, or internal-type-guaranteed values; avoid speculative complexity without first explaining the concrete failure mode, likelihood, and complexity cost and obtaining user buy-in; avoid try/catch and any; prefer Bun APIs, inference, functional array methods, const, early returns, and dot notation over unnecessary destructuring; avoid else; and inline single-use values to reduce variable count.
• 🔴 (03:08) User’s Effect convention requires binding services to named variables before invoking methods and prohibits nested service yields such as yield* (yield* Foo.Service).bar().
• 🔴 (03:08) User’s helper conventions are to keep the main function on the happy path, place genuinely useful supporting helpers nearby and often below the main export, avoid extracting simple single-use expressions, keep synchronous parsing/validation/option construction synchronous, use Schema.UnknownFromJsonString and Schema.decodeUnknownOption rather than manual JSON.parse wrapped in Effect.try for untrusted JSON strings, and comment only on non-obvious constraints or surprising behavior.
• 🔴 (03:08) User’s Drizzle schema convention requires snake_case field names so SQL column names do not need string redefinitions.
• 🔴 (03:08) User stated the plugin package has two versions, Effect and Promise.
• 🔴 (03:08) User requires every Effect-version plugin domain to extend the corresponding Effect API client interface from @opencode/client/effect/api, prohibits redefining functions already present on that interface, and permits plugin domains to add only functions meaningful in plugin context.