engineering-conventions

Wrap every awaited operation on the plugin-init path in withTimeout and degrade non-fatally on timeout. The OpenCode plugin host silently drops a plugin whose entry never resolves, so unbounded awaits cause the 'no agents in TUI' failure from issue #704.

Every bunSpawn call must pass cwd, stdin: 'ignore', a timeout in milliseconds, bounded stdio, and call proc.kill() in a finally block. An outer withTimeout alone lets the awaiter proceed but does not abort the child process.

The src/lang/index.ts barrel re-exports from ./runtime, which statically imports web-tree-sitter and loads heavy WASM at module-eval time. Import from src/lang/profiles instead, or use dynamic import() with the --external web-tree-sitter build flag.

mock.module leaks across files in Bun's shared test-runner process. Prefer _test_exports for pure function testing, then _internals dependency-injection seams for within-module mocking, and use mock.module only when unavoidable with restoration in afterEach.

Unversioned bunx biome resolves to whatever the registry returns at run time, which may differ from the pinned version in package.json. Invoke the pinned version explicitly, e.g. bunx @biomejs/biome@<version> ci ., to match the CI gate.

The test_runner tool is for targeted validation with explicit files lists; MAX_SAFE_TEST_FILES is 50 and broader scopes can stall or kill OpenCode. For full repo validation, run the shell commands in contributing.md or TESTING.md directly.