@brutalsystems/tincan-opencode 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# Tin Can — opencode Plugin
+
+## What it does
+
+This plugin makes live opencode sessions addressable as peers in Tin Can's messaging network. When installed, any active opencode session automatically advertises itself to the registry at `~/.tincan/peers/opencode/`, where Tin Can can discover and send messages to it. Without this plugin, there are no opencode peers — a session running in the TUI is invisible to peer messaging, even if Tin Can is installed.
+
+The plugin receives inbound messages delivered to a Unix socket and injects them into the active session as prompts for the agent to act on.
+
+## Requirements
+
+- **opencode** 1.18.31 (verified; other versions untested)
+- **Tin Can** 0.4.0 or later
+
+## Install
+
+The loader globs one level deep, so the installation is two copies:
+
+```bash
+mkdir -p ~/.config/opencode/plugin
+cp plugins/opencode/tincan.ts ~/.config/opencode/plugin/
+cp -r plugins/opencode/tincan-lib ~/.config/opencode/plugin/
+```
+
+### Why two copies?
+
+The opencode loader globs `{plugin,plugins}/*.{ts,js}` — one level deep only. `tincan.ts` must sit directly in `~/.config/opencode/plugin/`, or the plugin will not load at all.
+
+The `tincan-lib/` directory contains unit-testable helpers and is never globbed by the loader, which is exactly what we want. It is namespace-separated (not called `lib/`) because `~/.config/opencode/plugin/` is shared with every other opencode plugin, and we need the name to be unambiguous.
+
+Note: `~/.config/opencode/plugins/` (plural) is equally valid — both spellings work.
+
+## Verify the installation
+
+1. Start opencode normally:
+   ```bash
+   opencode
+   ```
+
+2. Within the TUI, send a message (type a message and press Enter — any input to the agent is fine).
+
+3. Check the registry in another terminal:
+   ```bash
+   ls -la ~/.tincan/peers/opencode/
+   ```
+
+   You should see:
+   - Session files named like `ses_*.json`
+   - An instance socket named like `inst-*.sock` (mode `0600`)
+
+   You will **not** see an `inst-*.caller.json` yet, and its absence is not a
+   failure. That file is written the first time the session invokes one of
+   Tin Can's MCP tools (`peers`, `send_peer`, `message_log`), which the steps
+   above do not do. It appears once you use one — and only if Tin Can is also
+   registered as an MCP server, which is a separate install.
+
+4. Examine a session file:
+   ```bash
+   cat ~/.tincan/peers/opencode/ses_*.json
+   ```
+
+   It should contain the session ID, slug, title, directory, state, and socket path.
+
+## Uninstall
+
+Remove the plugin files:
+
+```bash
+rm ~/.config/opencode/plugin/tincan.ts
+rm -rf ~/.config/opencode/plugin/tincan-lib
+```
+
+Clean up the registry (this step is optional but recommended):
+
+```bash
+rm -rf ~/.tincan/peers/opencode
+rm -f ~/.tincan/opencode-plugin.log ~/.tincan/opencode-plugin.log.1
+```
+
+## Troubleshooting
+
+The plugin log is the only diagnostic surface. Output does not reach opencode's own log file; check this file instead:
+
+```bash
+tail -f ~/.tincan/opencode-plugin.log
+```
+
+Or with a custom `TINCAN_HOME`:
+
+```bash
+tail -f "$TINCAN_HOME/opencode-plugin.log"
+```
+
+### Troubleshooting table
+
+| Symptom | Cause | Action |
+|---------|-------|--------|
+| **No registry files appear at all** | The plugin is not loading, or initialization failed. | Check the plugin log for `event=selfcheck.failed`. This usually means opencode's private `client._client` field moved due to a version change. Only opencode 1.18.31 is verified. See SPEC.md §3. |
+| **No file appears after `opencode --continue`** | Expected, not a bug. A resumed session is invisible until it next does something. | Send one message to the session (type input or wait for agent activity). The registry file will appear then. See SPEC.md §5. |
+| **`event=bind.failed` mentioning socket path too long** | `TINCAN_HOME` directory nesting is too deep. macOS caps AF_UNIX socket paths near 103 bytes. | Shorten `TINCAN_HOME` or the path to it. For example, move `~/.tincan` to a shallower location. |
+| **Messages accepted but nothing happens; `event=transport-broken detail=html response`** | The `/api/` prefix was lost in the request path. The opencode server falls back to its web UI and returns 200 with HTML instead of JSON, making an invalid request look like success. | Verify you are running opencode 1.18.31. Check the plugin source to ensure `POST /api/session/{sessionID}/prompt` is the exact path. |
+| **`event=rejected status=409`** | The same `message_id` was re-sent with different content. opencode treats this as a mismatched re-submit. | This is not a retryable failure. Check the Tin Can side to ensure message IDs are not being duplicated. |
+| **`event=dropped detail="missing envelope"`** | The `text` on the wire did not carry Tin Can's `<peer_message …>` envelope. | The envelope is the only thing marking an injected prompt as a peer's words rather than the operator's, so the plugin requires it. A hand-rolled sender must include it; from Tin Can itself this means a bug on the sending side. See SPEC.md §7. |
+| **`event=dropped detail=unknown session`** | A message arrived for a session ID this plugin never heard announced. | Expected right after `opencode --continue` if messages arrive before the session is active. Send the message again; the session will be registered on its next activity. |
+| **Stale peers listed in Tin Can, or socket files remain after a crash** | An instance was killed with `kill -9` or crashed without cleanup. Its registry files and socket remain. | Start a fresh opencode instance. On startup, the plugin sweeps orphaned sockets and removes any files for dead processes (identified by attempting a connection and seeing it refused). This is automatic. |
+
+## Known limits
+
+1. **Replay detection is per-process.** After an opencode restart, a re-sent `message_id` is logged as a fresh delivery even though opencode still de-duplicates it server-side. The plugin's log wording is approximate; the actual behaviour (no duplicate injection) is guaranteed.
+
+2. **The plugin log keeps one generation.** It rotates to `opencode-plugin.log.1` once it passes 4 MB, and the previous `.1` is overwritten. Nothing older is kept, so pipe it somewhere else if you need a longer history.
+
+3. **A resumed session is invisible until active.** When you run `opencode --continue`, the session does not appear in the registry until it next receives an event (a message, a user action, or agent activity). This was chosen over guessing from a session list, which would advertise closed sessions and silently lose messages. See SPEC.md §5 for details.
+
+## What it deliberately does not do
+
+### No outbound send path
+
+This plugin only *receives* messages. For opencode to *send* messages to a peer, Tin Can must be registered as an MCP server in opencode's configuration and accessed as a tool. The plugin and the MCP server are separate installations and work in tandem.
+
+**Both are needed for two-way messaging.** Installing only the plugin gives you a peer that can listen but not speak. Installing only Tin Can as an MCP server gives you a peer that can speak but not listen. No error is raised either way — you just get one-way silence.
+
+### No rate limiting
+
+Rate limiting is Tin Can's responsibility, not the plugin's. The plugin injects every message it receives immediately. If a flood arrives, Tin Can is at fault.
+
+The socket does cap concurrent connections (64) and drops one left idle for 30 seconds, but neither counts or delays messages: they bound the file descriptors and buffers a leaking sender can pin inside the opencode process, which is a different problem from too many messages.
+
+### No message logging
+
+The plugin logs sender, session, delivery mode, and message ID for diagnostics, but it does not log message bodies. The user's work is recorded in Tin Can's own logs; duplicating it here would clutter the plugin log.
+
+### No `/tui/append-prompt` integration
+
+Putting text in the human's compose box (the `/tui/append-prompt` endpoint) would interrupt a person rather than an agent. This is a different product decision that belongs in a later conversation about operator notification and workflow, not in the peer-messaging path.
+
+See SPEC.md §11 for more details on out-of-scope features.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@brutalsystems/tincan-opencode",
+  "version": "0.6.0",
+  "description": "opencode plugin for Tin Can — the receive half, so an opencode session can be messaged by a live Claude Code, Codex or opencode peer.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tincan",
+    "agents",
+    "agent-messaging"
+  ],
+  "license": "MIT",
+  "author": "Mike Williams",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrutalSystems/tincan.git",
+    "directory": "plugins/opencode"
+  },
+  "homepage": "https://github.com/BrutalSystems/tincan#readme",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./tincan.ts"
+  },
+  "files": [
+    "tincan.ts",
+    "tincan-lib",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/tincan-lib/caller.ts

@@ -0,0 +1,49 @@
+import { join } from 'node:path';
+import { isoStamp, writeJsonAtomic, type RecordContext } from './registry.js';
+
+/**
+ * Which session is currently talking to Tin Can's MCP server.
+ *
+ * opencode exports no OPENCODE_SESSION_ID into tool subprocesses, and pid
+ * ancestry only identifies the instance. The `tool.execute.before` hook does
+ * carry the calling sessionID, so the plugin records it here for Tin Can to
+ * read when it needs to exclude itself from its own peer list.
+ */
+export interface CallerRecord {
+  instance_id: string;
+  session_id: string;
+  pid: number;
+  tool: string;
+  at: string;
+}
+
+/** Distinct from a session record, which is always `ses_*.json`. */
+export function callerFile(dir: string, instanceID: string): string {
+  return join(dir, `${instanceID}.caller.json`);
+}
+
+/**
+ * opencode names an MCP tool `<server key>_<tool name>`, and the server key is
+ * whatever the user put in their opencode config — `tincan`, `tc`, anything.
+ * So match the tool-name suffix, never a prefix. A leading `_` is required, so
+ * a built-in called `peers` does not match.
+ */
+const TINCAN_TOOLS = ['peers', 'send_peer', 'message_log'];
+
+export function isTincanTool(toolID: string): boolean {
+  return TINCAN_TOOLS.some((name) => toolID.endsWith(`_${name}`));
+}
+
+export function composeCaller(sessionID: string, toolID: string, ctx: RecordContext): CallerRecord {
+  return {
+    instance_id: ctx.instance_id,
+    session_id: sessionID,
+    pid: ctx.pid,
+    tool: toolID,
+    at: isoStamp(ctx.now()),
+  };
+}
+
+export async function writeCaller(dir: string, rec: CallerRecord): Promise<void> {
+  await writeJsonAtomic(callerFile(dir, rec.instance_id), rec);
+}

package/tincan-lib/delivery.ts

@@ -0,0 +1,98 @@
+import type { DeliveryOutcome, InboundMessage, Transport, TransportResponse } from './types.js';
+
+/**
+ * The v1 route, deliberately, and deliberately NOT under /api.
+ *
+ * There are two prompt APIs and they are different engines. The /api one
+ * (`HttpApi.make("server")` in packages/protocol, self-described as an
+ * "Experimental HttpApi surface for selected instance routes") admits the
+ * message durably and asks a run coordinator to drain it. On a TUI-hosted
+ * session that drain fails to resolve the session's model and dies before the
+ * agent runs — 20 observed failures across two unrelated providers, zero
+ * successes — while telling nobody: the POST has already answered 200 and no
+ * error is written into the session.
+ *
+ * This one goes through SessionPrompt.Service instead and simply runs.
+ * Verified on stock opencode 1.18.31 in a TUI-hosted session: three sends,
+ * three turns, three answers. It is also what the reference integration
+ * (Intelligent-Internet/opencode-a2a) posts to.
+ *
+ * Do not "fix" this back to /api/. The old comment here warned that a missing
+ * prefix returns SPA HTML — true of the /api surface's own paths, and the
+ * reason `interpret` still guards for HTML, but this is a different route on
+ * a different API, not that one with a prefix dropped.
+ */
+export function promptUrl(sessionID: string): string {
+  return `/session/${sessionID}/prompt_async`;
+}
+
+export interface TextPart {
+  type: 'text';
+  text: string;
+}
+
+/**
+ * PromptPayload is PromptInput minus sessionID (opencode
+ * packages/opencode/src/server/routes/instance/httpapi/groups/session.ts:70).
+ * `parts` is the only required field; a text part needs only `type` and
+ * `text`. Everything else — model, agent, system, variant, noReply — is
+ * optional and deliberately left unset: Tin Can delivers a message, it does
+ * not reconfigure the peer's session.
+ *
+ * Note what is absent: `delivery`. v1 has no steer/queue, so `urgent` cannot
+ * be expressed on this leg and `runtimeSupportsUrgent` reports false for
+ * opencode accordingly. Sending a `delivery` key here would 400.
+ */
+export interface PromptBody {
+  parts: TextPart[];
+  messageID: string;
+}
+
+export function promptBody(msg: InboundMessage): PromptBody {
+  return {
+    // Verbatim. The <peer_message> envelope is the only provenance marking on
+    // this path and must never be trimmed or reformatted. SPEC §7.
+    parts: [{ type: 'text', text: msg.text }],
+    // Our id, so message_log lines and opencode's own records agree.
+    messageID: msg.message_id,
+  };
+}
+
+export function interpret(res: TransportResponse, alreadySent: boolean): DeliveryOutcome {
+  const status = res.response?.status ?? 0;
+  const data: unknown = res.data;
+
+  if (typeof data === 'string' && data.trimStart().toLowerCase().startsWith('<!doctype')) {
+    return { kind: 'transport-broken', detail: 'html response — wrong route prefix?' };
+  }
+
+  if (status >= 400) {
+    const err = (typeof res.error === 'object' && res.error !== null ? res.error : {}) as Record<string, unknown>;
+    return {
+      kind: 'rejected',
+      status,
+      tag: typeof err._tag === 'string' ? err._tag : 'unknown',
+      detail: typeof err.message === 'string' ? err.message : '',
+    };
+  }
+
+  // prompt_async answers 204 with an empty body. Anything else in the 2xx
+  // range means we reached something that is not prompt_async — most likely
+  // the old /api route, which answered 200 — and reading that as success is
+  // how a half-applied upgrade would go unnoticed.
+  if (status === 204) return { kind: 'delivered', replay: alreadySent };
+  return { kind: 'transport-broken', detail: `expected 204 from prompt_async, got ${status}` };
+}
+
+export async function deliver(transport: Transport, msg: InboundMessage, alreadySent: Set<string>): Promise<DeliveryOutcome> {
+  const replay = alreadySent.has(msg.message_id);
+  let res: TransportResponse;
+  try {
+    res = await transport.post({ url: promptUrl(msg.to_session), body: promptBody(msg) });
+  } catch (e) {
+    return { kind: 'transport-broken', detail: String(e) };
+  }
+  const outcome = interpret(res, replay);
+  if (outcome.kind === 'delivered') alreadySent.add(msg.message_id);
+  return outcome;
+}

package/tincan-lib/events.ts

@@ -0,0 +1,63 @@
+import type { SessionInfo, SessionState } from './types.js';
+
+export type EventEffect =
+  | { kind: 'upsert'; info: SessionInfo }
+  | { kind: 'state'; sessionID: string; state: SessionState }
+  | { kind: 'remove'; sessionID: string }
+  | { kind: 'ignore' };
+
+const IGNORE: EventEffect = { kind: 'ignore' };
+
+function readInfo(v: unknown): SessionInfo | null {
+  if (typeof v !== 'object' || v === null) return null;
+  const o = v as Record<string, unknown>;
+  if (
+    typeof o.id !== 'string' ||
+    typeof o.slug !== 'string' ||
+    typeof o.title !== 'string' ||
+    typeof o.directory !== 'string' ||
+    typeof o.version !== 'string'
+  ) {
+    return null;
+  }
+  return { id: o.id, slug: o.slug, title: o.title, directory: o.directory, version: o.version };
+}
+
+export function effectOf(event: unknown): EventEffect {
+  if (typeof event !== 'object' || event === null) return IGNORE;
+  const e = event as Record<string, unknown>;
+  const props = (typeof e.properties === 'object' && e.properties !== null ? e.properties : {}) as Record<string, unknown>;
+
+  switch (e.type) {
+    case 'session.created':
+    case 'session.updated': {
+      const info = readInfo(props.info);
+      return info ? { kind: 'upsert', info } : IGNORE;
+    }
+    case 'session.deleted': {
+      // Read leniently: a delete needs nothing but the id. Demanding the full
+      // create/update shape here means a payload missing (say) `version`
+      // returns `ignore`, so the record is never removed — and Tin Can then
+      // sees a peer whose socket is alive, so its liveness prune never fires
+      // and every message to it is dropped as `unknown session`. A peer that
+      // looks healthy and swallows input is worse than a stale one.
+      const id = (props.info as { id?: unknown } | undefined)?.id;
+      return typeof id === 'string' ? { kind: 'remove', sessionID: id } : IGNORE;
+    }
+    case 'session.idle': {
+      const id = props.sessionID;
+      return typeof id === 'string' ? { kind: 'state', sessionID: id, state: 'idle' } : IGNORE;
+    }
+    case 'session.status': {
+      const id = props.sessionID;
+      if (typeof id !== 'string') return IGNORE;
+      const status = props.status as { type?: unknown } | undefined;
+      // Only 'idle' is idle. 'busy', 'retry' and anything opencode adds later
+      // are all "the agent is not free". SPEC §5.
+      const state: SessionState = status?.type === 'idle' ? 'idle' : 'busy';
+      return { kind: 'state', sessionID: id, state };
+    }
+    default:
+      return IGNORE;
+  }
+}

package/tincan-lib/log.ts

@@ -0,0 +1,74 @@
+/**
+ * Logging with a hard whitelist. SPEC §8.2: the plugin must never write
+ * message bodies into opencode's logs. Enforced here rather than remembered
+ * at every call site.
+ */
+
+export interface LogFields {
+  event: string;
+  session?: string;
+  from?: string;
+  delivery?: string;
+  message_id?: string;
+  status?: number;
+  detail?: string;
+}
+
+export type Logger = (fields: LogFields) => void;
+
+const ORDER = ['event', 'session', 'from', 'delivery', 'message_id', 'status', 'detail'] as const;
+
+/**
+ * Wrap a callback so its own failure can never reach the host. SPEC §8.1.
+ *
+ * The one place this pattern lives: every host- or caller-supplied callback
+ * in the plugin is wrapped exactly once, where it is captured, and is then
+ * called bare everywhere else. Three separate hand-rolled versions of this
+ * used to sit in log.ts, plugin.ts and server.ts, with call sites that
+ * disagreed about which of them applied.
+ */
+export function swallow<A extends unknown[]>(fn: (...args: A) => void): (...args: A) => void {
+  return (...args: A) => {
+    try {
+      fn(...args);
+    } catch {
+      // Deliberate. A logging or error-reporting failure is not worth a
+      // wedged opencode session.
+    }
+  };
+}
+
+/**
+ * Values are quoted when they contain a space, an `=` or a quote.
+ *
+ * `message_from` is peer-controlled and lands in `from=`. Unquoted, a sender
+ * calling itself `x delivery=steer session=ses_victim` forges fields in a
+ * line an operator reads during an incident.
+ */
+function renderValue(value: unknown): string {
+  let rendered = String(value)
+    // One event is always one line. U+2028 and U+2029 are line
+    // terminators too — to a log viewer, to a terminal, and to JS itself.
+    .replace(/\s*[\r\n\u2028\u2029]+\s*/g, ' ');
+  if (rendered.length > 120) {
+    rendered = rendered.slice(0, 120) + '…';
+  }
+  if (/[\s="]/.test(rendered)) {
+    rendered = `"${rendered.replace(/"/g, '\\"')}"`;
+  }
+  return rendered;
+}
+
+export function formatLog(fields: LogFields): string {
+  const parts: string[] = [];
+  for (const key of ORDER) {
+    const value = (fields as unknown as Record<string, unknown>)[key];
+    if (value === undefined || value === null) continue;
+    parts.push(`${key}=${renderValue(value)}`);
+  }
+  return `[tincan] ${parts.join(' ')}`;
+}
+
+export function makeLogger(sink: (line: string) => void): Logger {
+  return swallow((fields: LogFields) => sink(formatLog(fields)));
+}

package/tincan-lib/paths.ts

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+
+/**
+ * macOS caps sun_path at 104 bytes including the NUL terminator; 102 bytes
+ * binds and 106 fails on the verified machine. Guard at 103. SPEC §4.
+ */
+export const MAX_UNIX_PATH = 103;
+
+function tincanHome(env: Record<string, string | undefined>, home: string): string {
+  return env.TINCAN_HOME && env.TINCAN_HOME.length > 0 ? env.TINCAN_HOME : join(home, '.tincan');
+}
+
+export function peersDir(env: Record<string, string | undefined>, home: string): string {
+  return join(tincanHome(env, home), 'peers', 'opencode');
+}
+
+/**
+ * Deliberately BESIDE `peers/`, not inside `peers/opencode/`: that directory
+ * is scanned by Tin Can and swept by `sweepOrphans`, and a log file dropped
+ * in it would confuse both.
+ */
+export function pluginLogPath(env: Record<string, string | undefined>, home: string): string {
+  return join(tincanHome(env, home), 'opencode-plugin.log');
+}
+
+export function sessionFile(dir: string, sessionID: string): string {
+  return join(dir, `${sessionID}.json`);
+}
+
+export function socketPath(dir: string, instanceID: string): string {
+  return join(dir, `${instanceID}.sock`);
+}
+
+export function socketPathTooLong(path: string): boolean {
+  return Buffer.byteLength(path, 'utf8') >= MAX_UNIX_PATH;
+}
+
+export function newInstanceId(randomHex: () => string): string {
+  return `inst-${randomHex()}`;
+}

package/tincan-lib/plugin.ts

@@ -0,0 +1,239 @@
+import { composeCaller, isTincanTool, writeCaller } from './caller.js';
+import { deliver } from './delivery.js';
+import { effectOf } from './events.js';
+import { makeLogger, swallow, type Logger } from './log.js';
+import { socketPath } from './paths.js';
+import {
+  composeRecord, isoStamp, removeAllForInstance, removeRecord,
+  sameIgnoringTimestamp, sweepOrphans, writeRecord, type RecordContext,
+} from './registry.js';
+import { listenLines, probeSocket, type ServerHandle } from './server.js';
+import { PLUGIN_VERSION, type RegistryRecord, type SessionInfo, type SessionState, type Transport } from './types.js';
+import { parseLine } from './wire.js';
+
+export interface LineHandlerDeps {
+  transport: Transport;
+  /** Sessions this process heard announced. Anything else is not addressable. */
+  known: Map<string, RegistryRecord>;
+  sent: Set<string>;
+  log: Logger;
+}
+
+export function makeLineHandler(deps: LineHandlerDeps): (line: string) => Promise<void> {
+  // Wrapped once, here, because deps.log is caller-supplied; called bare
+  // everywhere below. SPEC §8.1.
+  const log = swallow(deps.log);
+  return async (line: string): Promise<void> => {
+    try {
+      const parsed = parseLine(line);
+      if (!parsed.ok) {
+        log({ event: 'dropped', detail: parsed.reason });
+        return;
+      }
+      const msg = parsed.message;
+      if (!deps.known.has(msg.to_session)) {
+        log({
+          event: 'dropped',
+          session: msg.to_session,
+          from: msg.message_from,
+          message_id: msg.message_id,
+          detail: 'unknown session',
+        });
+        return;
+      }
+      const outcome = await deliver(deps.transport, msg, deps.sent);
+      log({
+        event: outcome.kind === 'delivered' ? (outcome.replay ? 'replay' : 'delivered') : outcome.kind,
+        session: msg.to_session,
+        from: msg.message_from,
+        delivery: msg.delivery,
+        message_id: msg.message_id,
+        status: outcome.kind === 'rejected' ? outcome.status : undefined,
+        detail:
+          outcome.kind === 'rejected' ? outcome.tag
+          : outcome.kind === 'transport-broken' ? outcome.detail
+          : undefined,
+      });
+    } catch (e) {
+      // Nothing here may reach the host. SPEC §8.1.
+      log({ event: 'handler.failed', detail: String(e) });
+    }
+  };
+}
+
+export interface PluginDeps {
+  dir: string;
+  instanceId: string;
+  pid: number;
+  transport: Transport;
+  now: () => Date;
+  sink: (line: string) => void;
+}
+
+export interface PluginHooks {
+  event: (input: { event: unknown }) => Promise<void>;
+  'tool.execute.before': (input: unknown) => Promise<void>;
+  dispose: () => Promise<void>;
+}
+
+async function selfCheck(transport: Transport, log: Logger): Promise<boolean> {
+  try {
+    const res = await transport.get({ url: '/api/session' });
+    if (typeof res.data === 'string') {
+      log({ event: 'selfcheck.failed', detail: 'html response' });
+      return false;
+    }
+    if ((res.response?.status ?? 0) !== 200) {
+      log({ event: 'selfcheck.failed', status: res.response?.status });
+      return false;
+    }
+    return true;
+  } catch (e) {
+    log({ event: 'selfcheck.failed', detail: String(e) });
+    return false;
+  }
+}
+
+export async function startPlugin(deps: PluginDeps): Promise<PluginHooks> {
+  const log = makeLogger(deps.sink);
+  const known = new Map<string, RegistryRecord>();
+  const sent = new Set<string>();
+  let server: ServerHandle | null = null;
+
+  const sock = socketPath(deps.dir, deps.instanceId);
+  const ctx: RecordContext = {
+    socket: sock,
+    instance_id: deps.instanceId,
+    pid: deps.pid,
+    plugin_version: PLUGIN_VERSION,
+    now: deps.now,
+  };
+
+  const handleLine = makeLineHandler({ transport: deps.transport, known, sent, log });
+
+  if (await selfCheck(deps.transport, log)) {
+    try {
+      const swept = await sweepOrphans(deps.dir, deps.instanceId, probeSocket);
+      if (swept.length > 0) log({ event: 'swept', detail: swept.join(',') });
+      server = await listenLines({
+        path: sock,
+        onLine: (line) => { void handleLine(line); },
+        onError: (e) => log({ event: 'socket.error', detail: String(e) }),
+      });
+      log({ event: 'bound', detail: sock });
+    } catch (e) {
+      log({ event: 'bind.failed', detail: String(e) });
+      server = null;
+    }
+  }
+
+  /**
+   * Every mutation of `known` and of the registry directory runs through this
+   * one chain. opencode dispatches events without awaiting the previous one,
+   * and unserialised `set`-then-write against `delete`-then-unlink interleaves
+   * into a deleted session whose file survives with a live-looking state —
+   * which `known` no longer holds, so nothing ever rewrites or removes it
+   * again. `then(fn, fn)` rather than `then(fn)`: a rejected link must not
+   * stall the chain behind it.
+   */
+  let queue: Promise<unknown> = Promise.resolve();
+  const serial = <T>(fn: () => Promise<T>): Promise<T> => {
+    const next = queue.then(fn, fn);
+    queue = next;
+    return next;
+  };
+
+  /** Write only when something other than the timestamp changed: session.updated
+   *  fires repeatedly while the model rewrites the title. SPEC §5.
+   *
+   *  `known` is updated only AFTER the write lands. Updating it first makes a
+   *  failed write poison the dedup cache: the next identical event compares
+   *  equal against memory and is skipped, leaving disk permanently stale. */
+  const applyRecord = async (candidate: RegistryRecord): Promise<void> => {
+    const prev = known.get(candidate.session_id);
+    if (prev && sameIgnoringTimestamp(prev, candidate)) return;
+    await writeRecord(deps.dir, candidate);
+    known.set(candidate.session_id, candidate);
+  };
+
+  const applyInfo = (info: SessionInfo): Promise<void> => serial(async () => {
+    const state = known.get(info.id)?.state ?? 'idle';
+    await applyRecord(composeRecord(info, state, ctx));
+  });
+
+  const applyState = (sessionID: string, state: SessionState): Promise<void> => serial(async () => {
+    const base = known.get(sessionID);
+    if (!base) return; // Never announced, so not addressable. SPEC §5.
+    await applyRecord({ ...base, state, updated_at: isoStamp(ctx.now()) });
+  });
+
+  const applyRemove = (sessionID: string): Promise<void> => serial(async () => {
+    known.delete(sessionID);
+    await removeRecord(deps.dir, sessionID);
+  });
+
+  return {
+    event: async (input: { event: unknown }): Promise<void> => {
+      if (!server) return; // Advertising without a delivery path would be a lie.
+      try {
+        // opencode's real contract wraps the payload as { event }. Tolerate a
+        // bare event too: getting this normalisation wrong produces silent
+        // inertness (effectOf sees no `type` and returns 'ignore' forever),
+        // the worst failure mode there is, and a future opencode change
+        // narrowing or widening the wrapper must not silently switch the
+        // plugin off again.
+        const event = (input as { event?: unknown } | null)?.event ?? input;
+        const effect = effectOf(event);
+        switch (effect.kind) {
+          case 'upsert':
+            await applyInfo(effect.info);
+            return;
+          case 'state':
+            await applyState(effect.sessionID, effect.state);
+            return;
+          case 'remove':
+            await applyRemove(effect.sessionID);
+            return;
+          default:
+            return;
+        }
+      } catch (e) {
+        log({ event: 'event.failed', detail: String(e) });
+      }
+    },
+
+    'tool.execute.before': async (input: unknown): Promise<void> => {
+      if (!server) return; // No delivery path, so no session worth excluding.
+      try {
+        const i = (typeof input === 'object' && input !== null ? input : {}) as Record<string, unknown>;
+        if (typeof i.tool !== 'string' || typeof i.sessionID !== 'string') return;
+        if (!isTincanTool(i.tool)) return;
+        await writeCaller(deps.dir, composeCaller(i.sessionID, i.tool, ctx));
+      } catch (e) {
+        log({ event: 'caller.failed', detail: String(e) });
+      }
+    },
+
+    dispose: async (): Promise<void> => {
+      // Order matters. Stop accepting work BEFORE removing anything: a
+      // closed ServerHandle is still a truthy object, and the event hook's
+      // only gate is `if (!server) return`, so a fire-and-forget onLine
+      // dispatch racing dispose could otherwise resurrect a registry file
+      // pointing at a socket that no longer exists — exactly the
+      // undeliverable-entry state the self-check exists to prevent. Removing
+      // first left the same window open for an event already in flight.
+      // Idempotent: a second dispose() finds server already null.
+      const handle = server;
+      server = null;
+      known.clear();
+      try {
+        if (handle) await handle.close();
+        // Through the chain, so any write already queued lands before the
+        // sweep rather than after it.
+        await serial(() => removeAllForInstance(deps.dir, deps.instanceId));
+      } catch (e) {
+        log({ event: 'dispose.failed', detail: String(e) });
+      }
+    },
+  };
+}

package/tincan-lib/registry.ts

@@ -0,0 +1,161 @@
+import { randomBytes } from 'node:crypto';
+import { chmod, mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { sessionFile, socketPath } from './paths.js';
+import type { RegistryRecord, SessionInfo, SessionState } from './types.js';
+
+export interface RecordContext {
+  socket: string;
+  instance_id: string;
+  pid: number;
+  plugin_version: string;
+  now: () => Date;
+}
+
+/** ISO 8601 to whole seconds, as SPEC §4's example shows. */
+export function isoStamp(d: Date): string {
+  return `${d.toISOString().slice(0, 19)}Z`;
+}
+
+export function composeRecord(info: SessionInfo, state: SessionState, ctx: RecordContext): RegistryRecord {
+  return {
+    session_id: info.id,
+    slug: info.slug,
+    title: info.title,
+    directory: info.directory,
+    state,
+    socket: ctx.socket,
+    instance_id: ctx.instance_id,
+    pid: ctx.pid,
+    plugin_version: ctx.plugin_version,
+    opencode_version: info.version,
+    updated_at: isoStamp(ctx.now()),
+  };
+}
+
+export function sameIgnoringTimestamp(a: RegistryRecord, b: RegistryRecord): boolean {
+  const { updated_at: _a, ...restA } = a;
+  const { updated_at: _b, ...restB } = b;
+  return JSON.stringify(restA) === JSON.stringify(restB);
+}
+
+/**
+ * Atomic: temp file in the same directory, then rename. SPEC §4.
+ *
+ * The temp suffix includes both the pid (disambiguates between processes)
+ * and a random token (disambiguates between two concurrent writes to the
+ * same path inside one process — the pid alone collides there).
+ */
+export async function writeJsonAtomic(finalPath: string, value: unknown): Promise<void> {
+  const dir = dirname(finalPath);
+  // mkdir's `mode` is ignored when the directory already exists — and Tin Can
+  // itself may have created ~/.tincan/peers at 0755. chmod unconditionally, or
+  // the 0700 parent that closes the bind-to-chmod race in SPEC §8.3 is a
+  // fiction.
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await chmod(dir, 0o700);
+  const tmp = `${finalPath}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  await rename(tmp, finalPath);
+}
+
+export async function writeRecord(dir: string, rec: RegistryRecord): Promise<void> {
+  await writeJsonAtomic(sessionFile(dir, rec.session_id), rec);
+}
+
+export async function removeRecord(dir: string, sessionID: string): Promise<void> {
+  try {
+    await unlink(sessionFile(dir, sessionID));
+  } catch {
+    // Already gone is the desired end state.
+  }
+}
+
+export async function removeAllForInstance(dir: string, instanceID: string): Promise<void> {
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    try {
+      const rec = JSON.parse(await readFile(join(dir, name), 'utf8')) as RegistryRecord;
+      if (rec.instance_id === instanceID) await unlink(join(dir, name));
+    } catch {
+      // Unreadable or unparseable: not ours to delete.
+    }
+  }
+}
+
+/**
+ * Delete the socket and registry files of every instance whose socket refuses
+ * a connection. The instance id is fresh on every load, so without this a
+ * `kill -9` leaves files nobody will ever reclaim. SPEC §6.
+ *
+ * Sockets are enumerated directly rather than read off records: because the
+ * plugin advertises nothing at load (SPEC §5), a crashed instance that never
+ * saw a session event leaves a socket with no record pointing at it, and that
+ * is the common case, not an edge case.
+ */
+export async function sweepOrphans(
+  dir: string,
+  selfInstance: string,
+  probe: (socketPath: string) => Promise<boolean>,
+): Promise<string[]> {
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const instances = new Map<string, { files: string[]; socket: string }>();
+  const entryFor = (id: string) => {
+    let entry = instances.get(id);
+    if (!entry) {
+      entry = { files: [], socket: socketPath(dir, id) };
+      instances.set(id, entry);
+    }
+    return entry;
+  };
+
+  for (const name of names) {
+    if (name.endsWith('.sock')) {
+      // Only OUR sockets. This directory is plugin-owned today, but the
+      // moment another Tin Can component drops a socket beside ours,
+      // treating every *.sock as an abandoned instance would delete it on
+      // the next opencode start.
+      if (!name.startsWith('inst-')) continue;
+      const id = name.slice(0, -'.sock'.length);
+      if (id !== selfInstance) entryFor(id);
+      continue;
+    }
+    if (!name.endsWith('.json')) continue;
+    try {
+      const rec = JSON.parse(await readFile(join(dir, name), 'utf8')) as RegistryRecord;
+      if (typeof rec.instance_id !== 'string' || rec.instance_id === selfInstance) continue;
+      entryFor(rec.instance_id).files.push(join(dir, name));
+    } catch {
+      // Unreadable or unparseable: not ours to delete.
+    }
+  }
+
+  const swept: string[] = [];
+  for (const [instance, entry] of instances) {
+    let alive = false;
+    try {
+      alive = await probe(entry.socket);
+    } catch {
+      alive = false;
+    }
+    if (alive) continue;
+    for (const file of entry.files) {
+      try { await unlink(file); } catch { /* already gone */ }
+    }
+    try { await unlink(entry.socket); } catch { /* already gone */ }
+    swept.push(instance);
+  }
+  return swept;
+}

package/tincan-lib/server.ts

@@ -0,0 +1,173 @@
+import { chmod, mkdir, unlink } from 'node:fs/promises';
+import { createServer, connect, type Server, type Socket } from 'node:net';
+import { dirname } from 'node:path';
+import { swallow } from './log.js';
+import { socketPathTooLong } from './paths.js';
+import { MAX_LINE_BYTES } from './wire.js';
+
+/**
+ * Resource hygiene on our own listener, not rate limiting — SPEC §8.6 puts
+ * throttling in Tin Can, and nothing here counts or delays messages. What
+ * these bound is file descriptors and buffers held inside the opencode
+ * process: a leaking sender that connects and never closes would otherwise
+ * accumulate sockets, each able to hold MAX_LINE_BYTES of unterminated
+ * buffer, until fd exhaustion wedges the host — which SPEC §8.1 calls a
+ * worse outcome than a missed message.
+ */
+export const MAX_CONNECTIONS = 64;
+export const IDLE_TIMEOUT_MS = 30_000;
+
+export interface ListenOptions {
+  path: string;
+  onLine: (line: string) => void;
+  onError: (err: unknown) => void;
+  /** Overridable so tests need not wait out the real one. */
+  idleTimeoutMs?: number;
+}
+
+export interface ServerHandle {
+  close(): Promise<void>;
+}
+
+/**
+ * `onError` is already wrapped with `swallow`, so it is safe to call bare.
+ * `onLine` is not: its failure has somewhere useful to go, so it is called
+ * inside a try that reports to `onError` rather than being swallowed.
+ */
+interface Handlers {
+  onLine: (line: string) => void;
+  onError: (err: unknown) => void;
+}
+
+function frame(socket: Socket, handlers: Handlers): void {
+  socket.setEncoding('utf8');
+  let buf = '';
+  let overflowed = false;
+
+  const emit = (line: string) => {
+    if (line.length === 0) return;
+    try {
+      handlers.onLine(line);
+    } catch (e) {
+      // A handler failure must never reach the host. SPEC §8.1.
+      handlers.onError(e);
+    }
+  };
+
+  socket.on('data', (chunk: string) => {
+    buf += chunk;
+    let i: number;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, i);
+      buf = buf.slice(i + 1);
+      if (overflowed) { overflowed = false; continue; }
+      if (Buffer.byteLength(line, 'utf8') >= MAX_LINE_BYTES) {
+        handlers.onError(new Error('oversize line dropped'));
+        continue;
+      }
+      emit(line);
+    }
+    if (Buffer.byteLength(buf, 'utf8') >= MAX_LINE_BYTES) {
+      handlers.onError(new Error('oversize line dropped'));
+      buf = '';
+      overflowed = true;
+    }
+  });
+
+  socket.on('end', () => {
+    if (!overflowed && buf.length > 0) emit(buf);
+    buf = '';
+  });
+  socket.on('error', (e) => handlers.onError(e));
+}
+
+export async function listenLines(opts: ListenOptions): Promise<ServerHandle> {
+  if (socketPathTooLong(opts.path)) {
+    throw new Error(`socket path too long (${Buffer.byteLength(opts.path)} bytes): ${opts.path}`);
+  }
+  const dir = dirname(opts.path);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  // mkdir's `mode` is ignored when the directory already exists, and this
+  // parent is shared across every instance and every restart — so without
+  // an unconditional chmod, the 0700 protection SPEC §8.3 calls load-bearing
+  // only ever applies on a machine's first run. Matches registry.ts's
+  // writeRecord.
+  await chmod(dir, 0o700);
+  try {
+    await unlink(opts.path);
+  } catch {
+    // Nothing there is the common case.
+  }
+
+  const sockets = new Set<Socket>();
+  const idleMs = opts.idleTimeoutMs ?? IDLE_TIMEOUT_MS;
+  // Wrapped exactly once, here, and called bare from then on. A caller's
+  // onError can itself throw (a broken logging sink, say) and that must
+  // never propagate out of a synchronous EventEmitter callback — SPEC §8.1
+  // is absolute, and this module is its strictest instance.
+  const handlers: Handlers = { onLine: opts.onLine, onError: swallow(opts.onError) };
+  const server: Server = createServer((socket) => {
+    sockets.add(socket);
+    socket.on('close', () => sockets.delete(socket));
+    // A sender writes one line and closes. Anything still idle after this
+    // is a leak, not a peer.
+    socket.setTimeout(idleMs, () => socket.destroy());
+    frame(socket, handlers);
+  });
+  server.maxConnections = MAX_CONNECTIONS;
+  server.on('error', (e) => handlers.onError(e));
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(opts.path, () => resolve());
+  });
+
+  const closeServer = () => new Promise<void>((resolve) => server.close(() => resolve()));
+
+  try {
+    // Neither node:net nor Bun.listen honours 0600 on creation. SPEC §4.
+    await chmod(opts.path, 0o600);
+  } catch (e) {
+    // Rethrowing from here would leave a listening server on a 0755 socket
+    // that no ServerHandle exists to close.
+    await closeServer();
+    try { await unlink(opts.path); } catch { /* already gone */ }
+    throw e;
+  }
+
+  let closed = false;
+  return {
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      // server.close() only stops new connections and waits for existing
+      // ones to end on their own — it never terminates them. A single idle
+      // peer would otherwise wedge this forever, and SPEC §8.1 names
+      // wedging the user's session as worse than a missed message.
+      for (const socket of sockets) socket.destroy();
+      await closeServer();
+      try {
+        await unlink(opts.path);
+      } catch {
+        // Already gone.
+      }
+    },
+  };
+}
+
+/** The liveness test the whole staleness model rests on. SPEC §6. */
+export function probeSocket(path: string, timeoutMs = 250): Promise<boolean> {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (alive: boolean) => {
+      if (done) return;
+      done = true;
+      try { c.destroy(); } catch { /* already gone */ }
+      resolve(alive);
+    };
+    const c = connect(path);
+    c.setTimeout(timeoutMs, () => finish(false));
+    c.on('connect', () => finish(true));
+    c.on('error', () => finish(false));
+  });
+}

package/tincan-lib/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Hand-written types for the slice of opencode 1.18.31 this plugin touches.
+ *
+ * Deliberately NOT imported from @opencode-ai/plugin: its published types
+ * disagree with the 1.18.31 runtime in both directions — they declare a
+ * `client.v2` that does not exist, and omit the `slug` that does.
+ * See SPEC.md §2.
+ */
+
+/** Tracks the Tin Can package version: every registry record reports it,
+ *  and a number matching no release tells an operator nothing. */
+export const PLUGIN_VERSION = '0.6.0';
+export const OPENCODE_TESTED_VERSION = '1.18.31';
+
+/** Server-enforced: sessionID must match ^ses, message id must match ^msg_. */
+export const SESSION_ID_RE = /^ses/;
+export const MESSAGE_ID_RE = /^msg_/;
+
+/** No 'unreachable': the plugin cannot observe its own absence. Tin Can infers
+ *  that from a refused socket and caches it in its own view. SPEC §4. */
+export type SessionState = 'idle' | 'busy';
+export type Delivery = 'queue' | 'steer';
+
+/** The subset of opencode's Session we rely on. `slug` and `version` are
+ *  present at runtime on event payloads even though the SDK type omits them. */
+export interface SessionInfo {
+  id: string;
+  slug: string;
+  title: string;
+  directory: string;
+  version: string;
+}
+
+export interface RegistryRecord {
+  session_id: string;
+  slug: string;
+  title: string;
+  directory: string;
+  state: SessionState;
+  socket: string;
+  instance_id: string;
+  pid: number;
+  plugin_version: string;
+  opencode_version: string;
+  updated_at: string;
+}
+
+export interface InboundMessage {
+  to_session: string;
+  message_from: string;
+  text: string;
+  delivery: Delivery;
+  message_id: string;
+}
+
+/** The hey-api client reachable at `input.client._client`. See SPEC.md §3. */
+export interface TransportResponse {
+  data?: unknown;
+  error?: unknown;
+  response?: { status?: number };
+}
+export interface Transport {
+  get(args: { url: string }): Promise<TransportResponse>;
+  post(args: { url: string; body?: unknown }): Promise<TransportResponse>;
+}
+
+export type DeliveryOutcome =
+  | { kind: 'delivered'; replay: boolean }
+  | { kind: 'rejected'; status: number; tag: string; detail: string }
+  | { kind: 'transport-broken'; detail: string };

package/tincan-lib/wire.ts

@@ -0,0 +1,73 @@
+import { MESSAGE_ID_RE, SESSION_ID_RE, type Delivery, type InboundMessage } from './types.js';
+
+/** One line, one message. Anything larger is a sender bug or an attack. */
+export const MAX_LINE_BYTES = 256 * 1024;
+
+/** Session and message IDs must be bounded to prevent body leakage via overlong ids. */
+export const MAX_ID_BYTES = 128;
+
+/**
+ * The opening token of Tin Can's provenance envelope.
+ *
+ * Only the token, never the whole tag: `src/envelope.ts` emits
+ * `<peer_message from="…" runtime="…" id="…">` and those attributes are free
+ * to change. What must not change is that the envelope is there at all —
+ * SPEC §7 makes it the load-bearing safety control on this path, and without
+ * this check a Tin Can regression that stopped enveloping would inject text
+ * indistinguishable from the operator's own with nothing noticing.
+ */
+export const ENVELOPE_TOKEN = '<peer_message';
+
+export type ParseResult =
+  | { ok: true; message: InboundMessage }
+  | { ok: false; reason: string };
+
+function str(v: unknown): v is string {
+  return typeof v === 'string' && v.length > 0;
+}
+
+export function parseLine(line: string): ParseResult {
+  if (Buffer.byteLength(line, 'utf8') >= MAX_LINE_BYTES) return { ok: false, reason: 'oversize' };
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(line);
+  } catch {
+    return { ok: false, reason: 'malformed json' };
+  }
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return { ok: false, reason: 'not an object' };
+  }
+  const o = raw as Record<string, unknown>;
+
+  if (!str(o.to_session)) return { ok: false, reason: 'missing to_session' };
+  if (!str(o.message_from)) return { ok: false, reason: 'missing message_from' };
+  if (!str(o.text)) return { ok: false, reason: 'missing text' };
+  if (!str(o.delivery)) return { ok: false, reason: 'missing delivery' };
+  if (!str(o.message_id)) return { ok: false, reason: 'missing message_id' };
+
+  // Presence only. The plugin never inspects, trims or conditions the
+  // envelope's contents — that stays Tin Can's. SPEC §7.
+  if (!o.text.includes(ENVELOPE_TOKEN)) return { ok: false, reason: 'missing envelope' };
+
+  if (!SESSION_ID_RE.test(o.to_session)) return { ok: false, reason: 'bad to_session' };
+  if (Buffer.byteLength(o.to_session, 'utf8') > MAX_ID_BYTES) return { ok: false, reason: 'bad to_session' };
+  if (!MESSAGE_ID_RE.test(o.message_id)) return { ok: false, reason: 'bad message_id' };
+  if (Buffer.byteLength(o.message_id, 'utf8') > MAX_ID_BYTES) return { ok: false, reason: 'bad message_id' };
+  // message_from is peer-controlled and reaches the operator's log. Bound it
+  // like the ids, or it is the one wire field a sender can use to push an
+  // arbitrary amount of its own text into a log line.
+  if (Buffer.byteLength(o.message_from, 'utf8') > MAX_ID_BYTES) return { ok: false, reason: 'bad message_from' };
+  if (o.delivery !== 'queue' && o.delivery !== 'steer') return { ok: false, reason: 'bad delivery' };
+
+  return {
+    ok: true,
+    message: {
+      to_session: o.to_session,
+      message_from: o.message_from,
+      text: o.text,
+      delivery: o.delivery as Delivery,
+      message_id: o.message_id,
+    },
+  };
+}

package/tincan.ts

@@ -0,0 +1,88 @@
+/**
+ * Tin Can — opencode plugin.
+ *
+ * WARNING: opencode's loader invokes EVERY exported function in this file as a
+ * plugin, and does not descend into subdirectories. Export exactly one thing,
+ * and never a `default`. All logic lives in ./tincan-lib/. See SPEC.md §2.
+ */
+import { randomBytes } from 'node:crypto';
+import { appendFileSync, chmodSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname } from 'node:path';
+import { newInstanceId, peersDir, pluginLogPath } from './tincan-lib/paths.js';
+import { startPlugin } from './tincan-lib/plugin.js';
+import type { Transport } from './tincan-lib/types.js';
+
+/** Rotates to `<log>.1` past this. Small enough to stay cheap to read, big
+ *  enough to hold a long session's diagnostics. */
+const MAX_LOG_BYTES = 4 * 1024 * 1024;
+
+export const TinCan = async (input: { client: { _client?: unknown } }) => {
+  // console.error would land in the TUI's own terminal — the same one
+  // opencode is drawing its interface on — and nowhere else: it never
+  // reaches opencode's own log file. Appending to our own log file is the
+  // only way an operator can read event=selfcheck.failed / bind.failed /
+  // transport-broken after the session ends. makeLogger already guards the
+  // call into this sink, but the sink itself must not throw either — a
+  // logging failure (e.g. an unwritable disk) must never reach the host.
+  const logPath = pluginLogPath(process.env, homedir());
+  // Every other artefact here is owner-only (peers dir 0700, socket 0600,
+  // records 0600). This log holds no message bodies, but it does hold
+  // session ids, peer names, message ids and delivery modes — a record of
+  // who is messaging whom — so it gets the same treatment. `mode` on
+  // appendFileSync only takes effect when the file is created, so a chmod
+  // follows the first write to any given file — a pre-existing 0644 log
+  // gets tightened too, not just a freshly created one.
+  //
+  // This runs on the TUI's worker thread, so it is kept to ONE syscall per
+  // line in the steady state: the mkdir, the chmod and the size check happen
+  // on the first write only, and the size is tracked in memory after that.
+  let logBytes = -1;   // -1 until the directory is ensured and the size read
+  let tightened = false; // chmod applied to the file currently at logPath
+  const sink = (line: string) => {
+    try {
+      const data = `${line}\n`;
+      if (logBytes < 0) {
+        mkdirSync(dirname(logPath), { recursive: true });
+        try { logBytes = statSync(logPath).size; } catch { logBytes = 0; }
+      }
+      if (logBytes >= MAX_LOG_BYTES) {
+        // One generation back, then overwritten. Two bounded files beat one
+        // unbounded one, and a rotation that fails must not cost us the
+        // line — logBytes is reset either way so we do not retry per line.
+        try {
+          renameSync(logPath, `${logPath}.1`);
+          chmodSync(`${logPath}.1`, 0o600);
+          tightened = false;
+        } catch { /* keep appending */ }
+        logBytes = 0;
+      }
+      appendFileSync(logPath, data, { mode: 0o600 });
+      logBytes += Buffer.byteLength(data);
+      if (!tightened) {
+        chmodSync(logPath, 0o600);
+        tightened = true;
+      }
+    } catch {
+      // Nothing here may reach the host. SPEC §8.1.
+    }
+  };
+  // The only private-field dependency in the plugin. SPEC §3 explains why it
+  // is unavoidable; the self-check inside startPlugin turns a future breakage
+  // into "no opencode peers" rather than a crash.
+  const transport = input.client?._client;
+
+  if (!transport || typeof (transport as { post?: unknown }).post !== 'function') {
+    sink('[tincan] event=selfcheck.failed detail=no transport on client._client');
+    return {};
+  }
+
+  return startPlugin({
+    dir: peersDir(process.env, homedir()),
+    instanceId: newInstanceId(() => randomBytes(3).toString('hex')),
+    pid: process.pid,
+    transport: transport as Transport,
+    now: () => new Date(),
+    sink,
+  });
+};