Distillation

Date: September 9, 2026

• 🔴 (09:54) User established that OpenCode owns a full-screen TUI, so startup banners and other plugin output must NEVER use raw stderr writes; route them through log (file + sink, with stderr only when not silenced), making them visible via lore logs.
• 🔴 (09:54) User established that OpenCode request headers must emit x-lore-git-remote only from the git remote paired with the current project path, never from a different project’s earlier plugin call.
• 🔴 (09:54) In /home/byk/Code/opencode-lore/packages/opencode/src/index.ts, LORE_UPSTREAM_EXTRA_HEADERS is parsed line-by-line using the first : separator; blank or malformed lines are skipped, names/values are trimmed, and shouldForwardUpstreamExtraHeader(name) prevents clobbering gateway-managed headers.
• 🔴 (09:54) The OpenCode fetch interceptor is installed once per process when Lore is active. getHeaders() adds gatewayAccessHeadersForRemote(gatewayBase), x-lore-project from currentProject.path, and the path-paired x-lore-git-remote; startup logs include routing through ${gatewayBase} and dashboard: ${gatewayBase}/ui.
• 🔴 (09:54) OpenCode plugin initialization failures are logged with the full stack or message via log.error("init failed: ...") before rethrowing, because the host plugin loader may catch and swallow the exception; the error remains available through the file/Sentry sink and lore logs.
• 🔴 (09:54) /home/byk/Code/opencode-lore/packages/opencode/src/index.ts must export only LorePlugin and its same-reference default export. Helpers belong in ./internal.ts; OpenCode’s legacy loader invokes every function export as a plugin and rejects non-function exports. The invariant is guarded by the "plugin entry module export shape" test in test/index.test.ts.
• 🔴 (09:55) User preference: always use const.
• 🔴 [enforced-workflow] (09:55) User directive: “Always always always commit your work.” Then create a PR if applicable; do not merge merely because the user asked to fix an issue.
• 🔴 (09:55) User preference: always prefer recall over assuming information is unavailable, especially for prior decisions, preferences, paths, and approaches; consume a synchronous recall result and continue within the same turn rather than ending on the recall invocation.
• 🔴 (09:55) User expects evidence-first, read-only investigation before code changes or conclusions: verify the active checkout/worktree, loaded configuration, dependency links, schemas, artifacts, binaries, processes, services, callers, caches, lifecycle, concurrency, failure, and cleanup paths; distinguish facts, hypotheses, and gaps; cite exact paths, lines, symbols, predicates, revisions, timestamps, and correlated telemetry; do not mutate state without authorization.
• 🔴 (09:55) User expects complete pre-commit validation: bundle the gateway, run the full Vitest suite or relevant subset, run oxfmt format checks, and run oxlint; surface exact failure/warning counts, diagnose hangs or failures rather than merely retrying, inspect diffs, and report commit hashes. Bundle debug-ID injection and absent SENTRY_AUTH_TOKEN are expected conditions.
• 🔴 [requested-tests] (09:55) User expects deterministic failing-first regression tests for bug fixes and exact lifecycle/accounting paths, focused tests for success, failure, races, aborts, restarts, teardown, compatibility, and degraded modes, plus repeated async/streaming tests to detect flakes.
• 🔴 (09:55) In /home/byk/Code/opencode-lore/packages/gateway/src/cli/start.ts, internalProbeFetch(url, init) uses nodeHttpFetch for loopback URLs to bypass WHATWG’s browser forbidden-port list, while non-loopback URLs retain normal fetch transport semantics.
• 🔴 (09:55) probeGatewayIdentityDetailed(baseURL, token, timeoutMs = 1500) calls /_lore/control with authorization: Bearer ${token} and accepts only an OK JSON response with status === "ok", service === "lore", and a positive safe-integer numeric pid; outcomes are "authenticated", "rejected", "timeout", or "unavailable".
• 🔴 (09:55) probeGatewayIdentity(baseURL, token, timeoutMs = 1500) is a compatibility wrapper returning the authenticated { pid } identity or null.
• 🔴 (09:55) probeGatewayProcessStatus(record, timeoutMs = 1500) probes all record.hosts concurrently and returns "authenticated" if any authenticated identity has pid === record.pid; otherwise precedence is "timeout" over "rejected" over "unavailable".
• 🔴 (09:55) probeGatewayStatus(baseURL, timeoutMs = 1500) probes /health and preserves four public-health states: an OK response is "healthy", a non-OK response or non-refusal transport failure is "error", abort is "timeout", and recursively verified ECONNREFUSED—including an AggregateError whose nonempty errors are all refusals—is "not-running".
• 🔴 (09:55) probeGateway(baseURL, timeoutMs = 1500) is the non-destructive boolean compatibility wrapper and returns true only when probeGatewayStatus() returns "healthy".
• 🔴 (09:55) probeUrlFor(host, port) maps bind-all hosts 0.0.0.0 → 127.0.0.1 and :: → ::1, then brackets IPv6 using bracketHost, producing valid URLs such as http://[::1]:3207.
• 🔴 (09:55) probeGatewayProcessHost(record, timeoutMs = 1500) authenticates every bound host concurrently and returns the first original record.hosts[index] whose identity PID matches record.pid, or null; probeGatewayProcess() returns whether such a host exists.
• 🔴 (09:55) requestGatewayShutdown(record, timeoutMs = 1500) sends graceful shutdown requests to the token-authenticated /_lore/control endpoint across the record’s hosts using internalProbeFetch.
• 🔴 (09:56) OpenCode Promise-v2 plugins implement { readonly id: string; readonly setup: (context: PluginContext) => Promise<void> | void }; define(plugin) returns the plugin unchanged, and PluginDomain exposes asynchronous add(plugin) and remove(id).
• 🔴 (09:56) OpenCode Promise-v2 PluginContext contains options, agent, aisdk, catalog, command, integration, plugin, reference, and skill; agent, catalog, command, integration, reference, and skill include Reload.
• 🔴 (09:56) OpenCode’s external plugin loader in /home/byk/Code/opencode/packages/core/src/config/plugin/external.ts discovers sorted {plugin,plugins}/*.{ts,js} files, dynamically imports each entrypoint, validates it with PluginModule, reads only .default, converts Promise plugins through PluginPromise.fromPromise(value) unless the value already has "effect", and registers them with ctx.plugin.add({ id, effect }); individual load failures are suppressed with Effect.ignoreCause.
• 🔴 (09:57) /home/byk/Code/opencode/packages/core/src/plugin/promise.ts adapts Promise plugins to the Effect-only host with fromPromise(plugin), preserving the plugin scope for registration disposal and captured fiber context for boot-time batching.
• 🔴 (09:57) In fromPromise(plugin), hook registration runs with Effect.runPromiseWith(context)(Scope.provide(scope)(effect)) and returns a Promise Registration whose dispose() executes the host registration’s Effect in the captured context.
• 🔴 (09:57) The Promise-plugin adapter wraps transform callbacks with Effect.promise(() => Promise.resolve(callback(draft))); it adapts agent, aisdk.sdk, aisdk.language, catalog, command, integration, reference, and skill, including each applicable reload() method.
• 🔴 (09:57) Promise-v2 child plugin registration recursively calls fromPromise(input) before host.plugin.add(child); removal maps to host.plugin.remove(id). The plugin’s asynchronous setup(context2) is awaited inside the Effect.
• 🔴 (09:57) /home/byk/Code/opencode-lore/packages/gateway/src/index.ts publicly exports loadConfig, DEFAULT_PORTS, DEFAULT_PORT, GatewayConfig, startServer, handleRequest, resetPipelineState, readPortFile, readGatewayProcessFile, startGateway, probeGateway, probeGatewayProcess, probeGatewayProcessHost, probeUrlFor, GatewayHandle, and StartOptions.
• 🔴 (09:57) The gateway package exports both Stricli-driven runCli from ./cli/cli and legacy _cli from ./cli/main; runCli handles migrated commands and falls back to _cli during the migration window.
• 🔴 (09:57) Gateway direct-execution detection compares process.argv[1] with __filename in CJS or fileURLToPath(import.meta.url) in ESM, returning false on error. When directly executed, it dynamically imports commandStart and runs commandStart({ quiet: true }), defaulting to start rather than run because embedded execution has no TTY and should not auto-launch an agent.
• 🔴 (09:57) /home/byk/Code/opencode-lore/packages/gateway/script/bundle.ts uses packages/gateway/src/index.ts as an entry point and generates dist/index.d.cts; /home/byk/Code/opencode-lore/packages/gateway/script/build.ts generates index.bun.js containing export * from "../src/index.ts";.