opencode-lookout 0.0.0-stage → 0.1.2

package/dist/tui.js

@@ -0,0 +1,534 @@
+// Generated by npm run build; do not edit.
+import { memo as _$memo } from "@opentui/solid";
+import { effect as _$effect } from "@opentui/solid";
+import { createTextNode as _$createTextNode } from "@opentui/solid";
+import { createComponent as _$createComponent } from "@opentui/solid";
+import { insertNode as _$insertNode } from "@opentui/solid";
+import { insert as _$insert } from "@opentui/solid";
+import { setProp as _$setProp } from "@opentui/solid";
+import { createElement as _$createElement } from "@opentui/solid";
+import { Plugin } from "@opencode/plugin/tui";
+import { createRoot, createSignal, createEffect, untrack, For, Show, ErrorBoundary } from "solid-js";
+import { Lookout } from "../src/rpc.ts";
+import { ID } from "../src/config.mjs";
+import { BROWSE_KINDS, displayRows, statusTone, filterRows, text } from "../src/catalog.mjs";
+const titles = {
+  agent: "Agents",
+  skill: "Skills",
+  plugin: "Plugins",
+  command: "Commands",
+  provider: "Providers",
+  model: "Models"
+};
+
+/** Additive sidebar UI. All inventory and mutations use the selected server location. */
+export default Plugin.define({
+  id: ID,
+  setup(ctx) {
+    const rpc = ctx.client.rpc(Lookout);
+    const abort = new AbortController();
+    let stopped = false,
+      revision = 0,
+      timer;
+    let stopRoot = () => {};
+    const [preferences, savePreferences] = ctx.storage.store("sidebar", {
+      initial: {
+        collapsed: false,
+        expanded: ["agent", "skill", "plugin"],
+        pins: []
+      }
+    });
+    const [snapshot, setSnapshot] = createSignal({
+      rows: [],
+      errors: [],
+      location: "",
+      refreshedAt: ""
+    });
+    const [loading, setLoading] = createSignal(false);
+    const [unavailable, setUnavailable] = createSignal(false);
+    const rows = () => displayRows(snapshot().rows);
+    const currentLocation = () => {
+      const route = ctx.ui.router.current();
+      return (route.type === "session" ? ctx.data.session.get(route.sessionID)?.location : undefined) ?? ctx.location ?? ctx.data.location.default();
+    };
+    const notify = (message, variant = "info") => {
+      if (!stopped) ctx.ui.toast.show({
+        title: "Lookout",
+        message,
+        variant
+      });
+    };
+
+    /** Ignore responses for old locations and stop all pending requests on unload. */
+    async function refresh() {
+      const location = currentLocation(),
+        request = ++revision;
+      setLoading(true);
+      if (snapshot().location !== location.directory) setSnapshot({
+        rows: [],
+        errors: [],
+        location: location.directory ?? "",
+        refreshedAt: ""
+      });
+      try {
+        const result = await rpc.snapshot({}, {
+          location,
+          signal: abort.signal
+        });
+        if (!stopped && request === revision) {
+          setSnapshot(result);
+          setUnavailable(false);
+        }
+      } catch {
+        if (!stopped && request === revision) {
+          setUnavailable(true);
+          setSnapshot(previous => ({
+            ...previous,
+            errors: ["Server extension unavailable. Last results may be stale. Run the external status command."]
+          }));
+        }
+      } finally {
+        if (!stopped && request === revision) setLoading(false);
+      }
+    }
+    async function pin(row) {
+      const key = `${row.kind}:${row.id}`;
+      await savePreferences(draft => {
+        draft.pins = draft.pins.includes(key) ? draft.pins.filter(p => p !== key) : [...draft.pins, key].slice(-30);
+      });
+    }
+
+    /** Preview and confirmation are separate requests; neither silently grants access. */
+    async function toggle(row) {
+      if (!row.manageable || unavailable() || snapshot().errors.length) return;
+      const location = currentLocation();
+      try {
+        const preview = await rpc.preview({
+          kind: row.kind,
+          id: row.id,
+          enabled: row.owned
+        }, {
+          location,
+          signal: abort.signal
+        });
+        const accepted = await ctx.ui.dialog.confirm({
+          title: row.owned ? "Enable resource?" : "Disable resource?",
+          message: preview.summary,
+          label: {
+            confirm: "Apply globally",
+            cancel: "Cancel"
+          }
+        });
+        if (!accepted || stopped) return;
+        if (currentLocation().directory !== location.directory) {
+          notify("Location changed. Preview again.", "error");
+          return;
+        }
+        await rpc.apply({
+          token: preview.token
+        }, {
+          location,
+          signal: abort.signal
+        });
+        notify("Configuration saved. Refresh to check the effective state.", "success");
+      } catch (error) {
+        // A reload can interrupt the reply after a successful write. Never retry blindly.
+        notify(`Change was not confirmed: ${text(error instanceof Error ? error.message : "request failed", 180)}. Refresh before retrying.`, "error");
+      } finally {
+        if (!stopped) await refresh();
+      }
+    }
+    async function detail(row) {
+      // Let the previous dialog finish key dispatch and restore focus first.
+      await new Promise(resolve => setTimeout(resolve, 0));
+      if (stopped) return;
+      const choice = await ctx.ui.dialog.select({
+        title: `${titles[row.kind]} · ${text(row.id)}`,
+        options: [{
+          title: "Show details",
+          value: "details",
+          description: `${row.status} · ${row.source}`
+        }, {
+          title: preferences.pins.includes(`${row.kind}:${row.id}`) ? "Unpin from sidebar" : "Pin to sidebar",
+          value: "pin"
+        }, {
+          title: row.owned ? "Enable (remove our restriction)" : "Disable globally",
+          value: "toggle",
+          description: row.reason,
+          disabled: !row.manageable || unavailable() || snapshot().errors.length > 0
+        }]
+      });
+      if (choice === "pin") await pin(row);
+      if (choice === "toggle") await toggle(row);
+      if (choice === "details") await new Promise(resolve => setTimeout(resolve, 0));
+      if (choice === "details" && !stopped) {
+        const lines = [`ID: ${text(row.id)}`, `Status: ${row.status}`, `Source: ${row.source}`, row.description, ...row.details, "", row.reason].filter(Boolean);
+        // A close callback gives the read-only inspector an explicit lifecycle.
+        await new Promise(resolve => {
+          ctx.ui.dialog.set({
+            size: "large"
+          });
+          ctx.ui.dialog.show(() => (() => {
+            var _el$ = _$createElement("box"),
+              _el$2 = _$createElement("text"),
+              _el$3 = _$createElement("b"),
+              _el$4 = _$createElement("text");
+            _$insertNode(_el$, _el$2);
+            _$insertNode(_el$, _el$4);
+            _$setProp(_el$, "flexDirection", "column");
+            _$setProp(_el$, "padding", 2);
+            _$setProp(_el$, "gap", 1);
+            _$insertNode(_el$2, _el$3);
+            _$insert(_el$3, () => text(row.label));
+            _$insert(_el$, _$createComponent(For, {
+              each: lines,
+              children: line => (() => {
+                var _el$6 = _$createElement("text");
+                _$insert(_el$6, line);
+                _$effect(_$p => _$setProp(_el$6, "fg", ctx.theme.text.base, _$p));
+                return _el$6;
+              })()
+            }), _el$4);
+            _$insertNode(_el$4, _$createTextNode(`Escape to return`));
+            _$effect(_p$ => {
+              var _v$ = ctx.theme.text.base,
+                _v$2 = ctx.theme.text.muted;
+              _v$ !== _p$.e && (_p$.e = _$setProp(_el$2, "fg", _v$, _p$.e));
+              _v$2 !== _p$.t && (_p$.t = _$setProp(_el$4, "fg", _v$2, _p$.t));
+              return _p$;
+            }, {
+              e: undefined,
+              t: undefined
+            });
+            return _el$;
+          })(), resolve);
+        });
+      }
+    }
+
+    /** Native searchable dialogs keep selection, keyboard focus, and styling consistent. */
+    async function browse(initialKind = "all") {
+      let kind = BROWSE_KINDS.includes(initialKind) ? initialKind : "all",
+        state = "all";
+      await refresh();
+      while (!stopped) {
+        await new Promise(resolve => setTimeout(resolve, 0));
+        if (stopped) break;
+        let action = "";
+        const filteredRows = filterRows(rows(), {
+          kind,
+          state
+        });
+        const selected = await ctx.ui.dialog.select({
+          title: `Lookout · ${kind === "all" ? "All" : titles[kind]} · ${state}${snapshot().errors.length ? " · stale" : ""}`,
+          placeholder: "Search IDs, names, descriptions, models…",
+          options: filteredRows.map(row => ({
+            title: text(row.label),
+            value: row,
+            description: `${row.id} · ${row.status}`,
+            category: titles[row.kind]
+          })),
+          search: (query, options) => {
+            const matches = new Set(filterRows(filteredRows, {
+              query
+            }).map(r => `${r.kind}:${r.id}`));
+            return options.filter(o => matches.has(`${o.value.kind}:${o.value.id}`));
+          },
+          actions: [{
+            bind: "ctrl+f",
+            title: "Category",
+            selection: "none",
+            onTrigger: () => {
+              action = "category";
+              ctx.ui.dialog.clear();
+            }
+          }, {
+            bind: "ctrl+s",
+            title: "State",
+            selection: "none",
+            onTrigger: () => {
+              action = "state";
+              ctx.ui.dialog.clear();
+            }
+          }, {
+            bind: "ctrl+r",
+            title: "Refresh",
+            selection: "none",
+            onTrigger: () => {
+              action = "refresh";
+              ctx.ui.dialog.clear();
+            }
+          }]
+        });
+        if (selected) {
+          await detail(selected);
+          return;
+        } else if (action === "category") kind = (await ctx.ui.dialog.select({
+          title: "Category",
+          options: ["all", ...BROWSE_KINDS].map(value => ({
+            title: titles[value] ?? "All categories",
+            value
+          }))
+        })) ?? kind;else if (action === "state") state = (await ctx.ui.dialog.select({
+          title: "Filter by state",
+          options: [{
+            value: "all",
+            title: "All"
+          }, {
+            value: "managed",
+            title: "Controllable here"
+          }, {
+            value: "disabled",
+            title: "Disabled / restricted by Lookout"
+          }, {
+            value: "local",
+            title: "Local sources"
+          }, {
+            value: "errors",
+            title: "Failed / unknown / stale"
+          }]
+        })) ?? state;else if (action === "refresh") await refresh();else break;
+      }
+    }
+
+    // Event-driven refresh, coalesced to avoid a burst of RPCs during config reload.
+    const stopEvents = ctx.data.listen(({
+      details
+    }) => {
+      if (!["config.updated", "agent.updated", "skill.updated", "plugin.updated", "command.updated", "provider.updated", "model.updated", "mcp.status.changed"].includes(details.type)) return;
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        if (!stopped) void refresh();
+      }, 250);
+    });
+    createRoot(dispose => {
+      stopRoot = dispose;
+      createEffect(() => {
+        // Read the reactive directory even when refresh itself is untracked.
+        void currentLocation().directory;
+        untrack(() => void refresh());
+      });
+    });
+    ctx.keymap.layer(() => ({
+      mode: "global",
+      commands: [{
+        id: "lookout.open",
+        title: "Open Lookout",
+        group: "Lookout",
+        palette: true,
+        slash: {
+          name: "lookout",
+          arguments: true
+        },
+        run: input => browse(input?.trim() || "all")
+      }, {
+        id: "lookout.refresh",
+        title: "Refresh Lookout",
+        group: "Lookout",
+        palette: true,
+        run: refresh
+      }, {
+        id: "lookout.help",
+        title: "Lookout troubleshooting",
+        group: "Lookout",
+        palette: true,
+        run: async () => {
+          await ctx.ui.dialog.alert({
+            title: "Troubleshooting",
+            message: "From your Lookout checkout, outside OpenCode, run:\nnode bin/lookout.mjs status\nUse unload to disable the extension, or load to enable it.\nUnload preserves resource restrictions. See the README for restore and safe mode."
+          });
+        }
+      }]
+    }));
+    function Sidebar() {
+      const dot = row => {
+        const tone = statusTone(row, unavailable() || snapshot().errors.length > 0);
+        return tone === "muted" ? ctx.theme.text.muted : ctx.theme.text.feedback[tone].base;
+      };
+      const selectedAgent = () => {
+        const route = ctx.ui.router.current();
+        return route.type === "session" ? ctx.data.session.get(route.sessionID)?.agent : undefined;
+      };
+      const visible = kind => {
+        const categoryRows = rows().filter(row => row.kind === kind);
+        const pinned = categoryRows.filter(row => preferences.pins.includes(`${kind}:${row.id}`));
+        return (pinned.length ? pinned : filterRows(categoryRows).filter(row => (kind !== "plugin" || row.source !== "builtin") && row.status !== "hidden").sort((a, b) => Number(b.kind === "agent" && b.id === selectedAgent()) - Number(a.kind === "agent" && a.id === selectedAgent()))).slice(0, 3);
+      };
+      return (() => {
+        var _el$7 = _$createElement("box"),
+          _el$8 = _$createElement("text"),
+          _el$9 = _$createElement("b"),
+          _el$0 = _$createTextNode(` Lookout`);
+        _$insertNode(_el$7, _el$8);
+        _$setProp(_el$7, "flexDirection", "column");
+        _$setProp(_el$7, "marginTop", 1);
+        _$insertNode(_el$8, _el$9);
+        _$setProp(_el$8, "onMouseDown", () => void savePreferences(d => {
+          d.collapsed = !d.collapsed;
+        }));
+        _$insertNode(_el$9, _el$0);
+        _$insert(_el$9, () => preferences.collapsed ? "▶" : "▼", _el$0);
+        _$insert(_el$7, _$createComponent(Show, {
+          get when() {
+            return !preferences.collapsed;
+          },
+          get children() {
+            return [_$createComponent(Show, {
+              get when() {
+                return loading();
+              },
+              get children() {
+                var _el$1 = _$createElement("text");
+                _$insertNode(_el$1, _$createTextNode(`Refreshing…`));
+                _$effect(_$p => _$setProp(_el$1, "fg", ctx.theme.text.muted, _$p));
+                return _el$1;
+              }
+            }), _$createComponent(Show, {
+              get when() {
+                return snapshot().errors.length;
+              },
+              get children() {
+                var _el$11 = _$createElement("text");
+                _$insertNode(_el$11, _$createTextNode(`Stale / unavailable — refresh`));
+                _$effect(_$p => _$setProp(_el$11, "fg", ctx.theme.text.muted, _$p));
+                return _el$11;
+              }
+            }), _$createComponent(For, {
+              each: BROWSE_KINDS,
+              children: kind => (() => {
+                var _el$15 = _$createElement("box"),
+                  _el$16 = _$createElement("text"),
+                  _el$17 = _$createTextNode(` `),
+                  _el$18 = _$createElement("b"),
+                  _el$19 = _$createTextNode(` `),
+                  _el$20 = _$createElement("span");
+                _$insertNode(_el$15, _el$16);
+                _$setProp(_el$15, "flexDirection", "column");
+                _$insertNode(_el$16, _el$17);
+                _$insertNode(_el$16, _el$18);
+                _$insertNode(_el$16, _el$19);
+                _$insertNode(_el$16, _el$20);
+                _$setProp(_el$16, "onMouseDown", () => void savePreferences(d => {
+                  d.expanded = d.expanded.includes(kind) ? d.expanded.filter(k => k !== kind) : [...d.expanded, kind];
+                }));
+                _$insert(_el$16, () => preferences.expanded.includes(kind) ? "▼" : "▶", _el$17);
+                _$insert(_el$18, () => titles[kind]);
+                _$insert(_el$20, () => rows().filter(r => r.kind === kind).length);
+                _$insert(_el$15, _$createComponent(Show, {
+                  get when() {
+                    return preferences.expanded.includes(kind);
+                  },
+                  get children() {
+                    return [_$createComponent(For, {
+                      get each() {
+                        return visible(kind);
+                      },
+                      children: row => (() => {
+                        var _el$24 = _$createElement("box"),
+                          _el$25 = _$createElement("text"),
+                          _el$26 = _$createTextNode(`  `),
+                          _el$27 = _$createElement("span"),
+                          _el$29 = _$createTextNode(` `);
+                        _$insertNode(_el$24, _el$25);
+                        _$setProp(_el$24, "flexDirection", "column");
+                        _$insertNode(_el$25, _el$26);
+                        _$insertNode(_el$25, _el$27);
+                        _$insertNode(_el$25, _el$29);
+                        _$setProp(_el$25, "onMouseDown", () => void detail(row));
+                        _$insertNode(_el$27, _$createTextNode(`•`));
+                        _$insert(_el$25, () => row.kind === "agent" && row.id === selectedAgent() ? "› " : "", null);
+                        _$insert(_el$25, () => text(row.label, 28), null);
+                        _$insert(_el$24, _$createComponent(Show, {
+                          get when() {
+                            return row.kind === "plugin";
+                          },
+                          get children() {
+                            var _el$30 = _$createElement("text"),
+                              _el$31 = _$createTextNode(`    `);
+                            _$insertNode(_el$30, _el$31);
+                            _$setProp(_el$30, "wrapMode", "none");
+                            _$setProp(_el$30, "truncate", true);
+                            _$setProp(_el$30, "onMouseDown", () => void detail(row));
+                            _$insert(_el$30, () => row.description || "missing description", null);
+                            _$effect(_$p => _$setProp(_el$30, "fg", ctx.theme.text.muted, _$p));
+                            return _el$30;
+                          }
+                        }), null);
+                        _$effect(_p$ => {
+                          var _v$5 = ctx.theme.text.base,
+                            _v$6 = {
+                              fg: dot(row)
+                            };
+                          _v$5 !== _p$.e && (_p$.e = _$setProp(_el$25, "fg", _v$5, _p$.e));
+                          _v$6 !== _p$.t && (_p$.t = _$setProp(_el$27, "style", _v$6, _p$.t));
+                          return _p$;
+                        }, {
+                          e: undefined,
+                          t: undefined
+                        });
+                        return _el$24;
+                      })()
+                    }), (() => {
+                      var _el$21 = _$createElement("text"),
+                        _el$22 = _$createTextNode(` Search / manage…`);
+                      _$insertNode(_el$21, _el$22);
+                      _$setProp(_el$21, "onMouseDown", () => void browse(kind));
+                      _$effect(_$p => _$setProp(_el$21, "fg", ctx.theme.text.muted, _$p));
+                      return _el$21;
+                    })()];
+                  }
+                }), null);
+                _$effect(_p$ => {
+                  var _v$3 = ctx.theme.text.base,
+                    _v$4 = {
+                      fg: ctx.theme.text.muted
+                    };
+                  _v$3 !== _p$.e && (_p$.e = _$setProp(_el$16, "fg", _v$3, _p$.e));
+                  _v$4 !== _p$.t && (_p$.t = _$setProp(_el$20, "style", _v$4, _p$.t));
+                  return _p$;
+                }, {
+                  e: undefined,
+                  t: undefined
+                });
+                return _el$15;
+              })()
+            }), (() => {
+              var _el$13 = _$createElement("text");
+              _$insertNode(_el$13, _$createTextNode(`/lookout`));
+              _$setProp(_el$13, "onMouseDown", () => void browse());
+              _$effect(_$p => _$setProp(_el$13, "fg", ctx.theme.text.muted, _$p));
+              return _el$13;
+            })()];
+          }
+        }), null);
+        _$effect(_$p => _$setProp(_el$8, "fg", ctx.theme.text.base, _$p));
+        return _el$7;
+      })();
+    }
+    const stopSlot = ctx.ui.slot({
+      append: "sidebar.content",
+      render: () => _$createComponent(ErrorBoundary, {
+        get fallback() {
+          return (() => {
+            var _el$32 = _$createElement("text");
+            _$insertNode(_el$32, _$createTextNode(`Lookout unavailable; use unload.`));
+            _$effect(_$p => _$setProp(_el$32, "fg", ctx.theme.text.muted, _$p));
+            return _el$32;
+          })();
+        },
+        get children() {
+          return _$createComponent(Sidebar, {});
+        }
+      })
+    });
+    return () => {
+      stopped = true;
+      ++revision;
+      abort.abort();
+      clearTimeout(timer);
+      stopEvents();
+      stopRoot();
+      stopSlot();
+    };
+  }
+});

package/docs/ARCHITECTURE.md

@@ -0,0 +1,124 @@
+# Architecture
+
+## npm artifact boundary
+
+The package ships the server/RPC TypeScript exports, runtime modules, recovery
+CLI, public docs and a generated `dist/tui.js`. Babel's pinned Solid universal
+transform targets `@opentui/solid`; the generated TUI imports the original RPC and
+shared runtime modules. `build:check` rejects stale generated code. No install or
+pack lifecycle scripts execute. The SDK, OpenTUI and Solid are host-provided
+optional peers; only `jsonc-parser` is installed for offline recovery.
+
+The supported npm install uses a dedicated stable prefix and the same marked
+directory load entry as a checkout. Harness files stay in the repository while
+integration loads a production-installed tarball from a separate dependency
+tree. Direct registry entries and ephemeral npm-exec caches are not claimed by
+the path-owned recovery CLI.
+
+## Release tooling boundary
+
+`scripts/release-policy.mjs` contains pure report, freshness, and compatibility
+validation. `security.mjs` owns scanner execution, pinned rule acquisition, and
+full-history/working-tree scans. `compatibility.mjs` owns version discovery,
+artifact-bound Docker builds, terminal tests, and fixture cleanup.
+`release-check.mjs` requires a clean source revision and fresh matching receipts,
+reruns quality checks, and writes a local assessment. None of these scripts
+publishes packages or changes user configuration. CI runs the same entry points.
+CodeQL runs only on GitHub; `check-codeql.mjs` validates its generated SARIF using
+the same pure scanner policy. Its two checks remain separately required.
+
+## Boundaries
+
+`src/tui.tsx` contributes to `sidebar.content` and uses native select and confirmation
+dialogs plus a read-only inspector in the host dialog container. It uses semantic
+theme colors, not hardcoded Carbonfox colors
+or private host renderables. The UI requests a location-scoped inventory through
+`src/rpc.ts`. It never writes configuration or executes a shell command.
+
+The display allowlist excludes MCP from sidebar headings, category selection,
+search, and saved pins; OpenCode provides that interface natively. The server's
+seven-category RPC contract and owned MCP restrictions remain unchanged for
+compatibility and offline recovery. Status dots use the same semantic feedback
+tokens as the native MCP sidebar, with muted text for inactive entries.
+
+`src/server.ts` reads the public V2 catalogs. Each category can fail independently;
+the UI keeps stale data and disables controls rather than infer an empty catalog.
+Inventory normalization in `src/catalog.mjs` copies only display fields. It does
+not serialize prompts, skill bodies, MCP commands, provider headers, or credentials.
+
+`src/plugin-description.mjs` enriches plugin rows from their exact local source.
+Directories use their own `package.json` description; single files use only a
+leading JSDoc `@description` tag. Reads are bounded to 64 KiB for manifests and a
+16 KiB source prefix. Only the sanitized description (at most 400 UTF-16 code
+units) reaches the UI. Metadata failures return `missing description` without
+failing the catalog. There is no code evaluation, ancestor search, registry
+request, or plugin-ID lookup table. Refresh rereads metadata rather than retaining
+an outdated description cache. This tag is a Lookout convention, not an OpenCode
+SDK field.
+
+`src/controller.mjs` validates disable requests against a fresh inventory before
+preview and apply. Enable requests require an owned restriction, even when the
+resource has disappeared from the catalog. A random, single-use token binds the request to a file fingerprint for
+60 seconds. A new preview invalidates the previous preview in that instance.
+`src/config.mjs` owns exact-ID entries in marked array regions. Enabling removes
+an owned entry; it never creates an overriding allow rule.
+
+`bin/lookout.mjs` is the independent recovery path. It requires only Node.js
+and the package's installed JSONC parser, not a working OpenCode process.
+
+## Configuration ownership
+
+OpenCode does not discover an arbitrary `lookout.jsonc`, so controls use
+the existing global configuration. The controller writes only `policies` and
+`plugins` arrays. JSONC syntax-tree validation rejects duplicate keys, damaged
+ownership markers, and unexpected entry shapes. If an array already exists,
+removing its managed block restores the original bytes. If the controller creates
+an array, restoring its entries leaves an empty array.
+
+Plugin load/unload uses a separate `lookout:lifecycle` marker. Unload replaces the
+package path with `-opencode-lookout`. It does not remove resource-denial
+blocks. The source directory is outside `plugins/`, so removing the load entry
+actually stops discovery. Do not copy a second instance into `plugins/`.
+
+Writes use an exclusive lock, a same-directory temporary file, flush, fingerprint
+recheck, and atomic rename. The controller rejects symlinked or hard-linked files.
+Reads open with no-follow/nonblocking flags, validate the descriptor, and consume
+at most 1 MiB plus one overflow-detection byte. Descriptor metadata is rechecked
+after reading; path metadata from before open never determines safety or mode.
+A lock serializes Lookout writers. An unrelated editor does not participate
+in that lock: a small race remains between the final check and rename. Avoid
+editing global config while confirming a change.
+
+## Lifecycle and scope
+
+Server cleanup removes its RPC registration and clears outstanding previews.
+TUI cleanup aborts requests, cancels its refresh timer, removes its event listener,
+disposes its Solid root, and unregisters the sidebar contribution. OpenCode owns
+the lifecycle of the registered keymap layer. Requests for an old location cannot
+replace the current inventory.
+
+UI preferences are stored through OpenCode's terminal-local plugin storage.
+They survive reloads and contain only collapsed sections and pinned IDs. Resource
+restrictions live in the server's global config, not terminal storage. For remote
+servers, controls affect the remote user's configuration; local unload changes
+only the local installation. Run recovery commands on the relevant server host.
+
+## Language and API conventions
+
+- TypeScript defines the OpenCode integration and public UI data contracts.
+- JavaScript modules use JSDoc to document exported behavior and security-sensitive
+  boundaries. Tests exercise these pure modules without OpenCode or a terminal.
+- Comments explain ownership, failure handling, and constraints. They do not
+  narrate assignments or duplicate type declarations.
+- V2 SDK dependencies are pinned to the target OpenCode release. Do not substitute
+  the old `@opencode-ai/plugin` package or invent compatibility aliases.
+- Changes must pass `make check`; changes to configuration semantics also need an
+  isolated live server test before deployment to the personal environment.
+
+## API references
+
+- [TUI plugin API](https://opencode.ai/v2/docs/build/plugins/cli/)
+- [Server plugin API](https://opencode.ai/v2/docs/build/plugins/server/)
+- [RPC API](https://opencode.ai/v2/docs/build/plugins/rpc/)
+- [Plugin loading and control](https://opencode.ai/v2/docs/plugins/)
+- [Policy precedence](https://opencode.ai/v2/docs/policies/)