@agfpd/iapeer 0.4.114 → 0.4.115

package/docs/15-fleet-api.md

@@ -38,7 +38,8 @@ The full fleet state. The peer rows are produced by the **same in-process functi
     "uptimeSecs": 32400,
     "memory": { "provider": "iapeer-memory", "version": "1.2.3", "heartbeatAgeSecs": 12 },
     "voice":  { "provider": "voice-connect", "version": "0.3.1", "heartbeatAgeSecs": null },
-    "fda": true
+    "fda": true,
+    "agent_runtimes": ["claude", "codex"]
   },
   "peers": [
     {
@@ -48,8 +49,8 @@ The full fleet state. The peer rows are produced by the **same in-process functi
       "default_runtime": "claude",
       "cwd": "/Users/me/.iapeer/peers/boris",
       "runtimes": [
-        { "runtime": "claude", "status": "live", "attached": true, "activity": "working" },
-        { "runtime": "codex",  "status": "asleep" }
+        { "runtime": "claude", "status": "live", "agent": true, "attached": true, "activity": "working" },
+        { "runtime": "codex",  "status": "asleep", "agent": true }
       ],
       "last_active_runtime": "claude",
       "last_active_ms": 1751731100000,
@@ -77,6 +78,8 @@ The full fleet state. The peer rows are produced by the **same in-process functi
 Field notes:
 
 - `runtimes[].status` — `live` (session up) · `asleep` (wakeable on demand) · `stopped` (operator stop flag; the daemon won't wake it). Same glyph semantics as the CLI: `●` / `○` / `✕`.
+- `runtimes[].agent` — **agent-endpoint discovery**: `true` iff this declared runtime is an agent runtime the running core can host (listed in `host.agent_runtimes`). A channel that offers a personality's agent endpoints (a Telegram menu, a web picker) offers exactly its `agent: true` runtimes — never a consumer-side runtime list, never a `which`/PATH probe. A declared runtime the core cannot host (a newer peer profile on an older core) is `false` and is not offered. A channel runtime (`telegram`, `web`, …) is always `false`. Additive: a pre-discovery daemon omits it — clients MUST then fall back to treating no runtime as discoverable rather than guessing. Which endpoint a send reaches is a separate rule: an omitted runtime is always `default_runtime` (config-anchored, never «the live one»); a control action for the same dialogue must name the same runtime its send used.
+- `host.agent_runtimes` — the agent runtimes this core build can host, in preference order. It grows when an agent adapter ships (e.g. `opencode`, docs/20).
 - `runtimes[].attached` — present (`true`) only when a **human operator** is attached to that live hosted session.
 - `runtimes[].activity` — **turn activity**: is this runtime *in a turn* right now. See «Activity» below. Additive; absent on a pre-activity daemon, on every non-`live` runtime, and whenever the daemon has no evidence — clients MUST treat absence as **no claim**, never as `idle`.
 - `attached` — any runtime attached (peer-level convenience).

package/docs/20-opencode.md

@@ -0,0 +1,226 @@
+# 20 — OpenCode agent runtime
+
+**Implementation in progress; not a released capability.** This is the acceptance
+contract, not a claim that the matrix below has passed. Existing Claude/Codex
+behaviour and the signing-phase activation restrictions remain unchanged.
+
+## Ownership and mechanism
+
+OpenCode is an **agent adapter**, not an infrastructure router. Its native process
+and TUI belong to the existing pty supervisor; wake, locks, crash guard, idle-reap,
+resume/fresh choice, identity, routing and operator commands stay foundation-owned.
+It does not acquire a launchd KeepAlive plist or bypass H4.
+
+Provider and model configuration belongs to OpenCode configuration/launch.env.
+NVIDIA is one provider, not a dependency of the adapter. Credentials are environment
+references or native credential storage, never embedded in generated artifacts.
+
+The native `agent.iapeer.prompt` replaces the provider's built-in base prompt.
+The native environment, tools and project-instruction channels remain enabled, as
+they do for Claude/Codex. A user-message prefix is not a system-prompt replacement.
+The file is re-composed on every process launch, including resume; live processes
+keep their launch snapshot. Foreign config/plugins are preserved, not overwritten.
+OpenCode's inline config **merges** other sources; managed config/MDM can override
+it. Effective-config checks must refuse a conflicting required setting rather
+than claim success, erase foreign settings, or circumvent an administrative gate.
+
+Structural delivery/readiness/control use the native plugin SDK, not a guessed
+screen glyph or a successful process spawn. The core-owned plugin must be present
+and healthy before incoming delivery. The native TUI remains the attach surface.
+An acknowledgement means the **specific message** is persisted/accepted, not merely
+that bytes reached a socket. Message IDs, session IDs, tool events and errors must
+remain available to history/observability clients. No mandatory command may succeed
+as a silent no-op.
+
+## Memory-provider ABI (agreed with iapeer-memory)
+
+- Existing slot `provision-peer --personality <p> --runtime opencode --cwd <cwd>`.
+- Canonical child ABI: `PEER_PERSONALITY`, `PEER_RUNTIME=opencode`,
+  `PEER_IDENTITY=opencode-<p>`; `IAPEER_IDENTITY` is an alias set by the core.
+- Private directory: `<IAPEER_ROOT>/peers/<p>/opencode/` (default root `~/.iapeer`).
+  Memory owns `iapeer-memory.json` and `iapeer-memory-plugin.mjs` there. The core
+  reads the JSON fragment on each launch and merges its `mcp` and `plugin` fields
+  into runtime overrides. Missing means no memory surfaces; malformed/present
+  means an explicit failure. Other keys are rejected, not given core authority.
+- MCP fragment uses `type: remote`, `oauth: false`, and
+  `headers: {"X-IAPeer-Identity": "{env:PEER_IDENTITY}"}`. Memory owns its MCP and
+  write-attribution hooks; foundation owns IAP, doctrine and approvals.
+- Guide/index remain ordinary global/local `.iapeer/fragments` input to the
+  foundation composer. They are not duplicated in a separate OpenCode memory.
+- Unprovision receives `--personality` as well as `--cwd` and `--runtime` so removal
+  cannot target another personality sharing a working directory.
+
+## Observability ABI (agreed with web-runtime, telegram-runtime, statusline-injector)
+
+**Contract under implementation — no live producer yet.** Consumers must not treat
+a synthetic fixture as proof of the producer; the core ships a native source harness.
+
+The core is the **single producer**. Consumers read only these files, never the
+native OpenCode SQLite DB or a second SDK client:
+
+- `<IAPEER_ROOT>/peers/<p>/opencode/events.jsonl` — append-only journal, one JSON
+  object per line:
+  `{schema:1, seq, time:<epoch ms>, identity:"opencode-<p>", launchID,
+  sessionID:<native ses_…|null>, type, properties, nativeID:<event.id|null>}`.
+  - `seq` is monotonic across process restarts and resumes. The journal is never
+    rotated or renamed on fresh. Consumers dedup by `seq`.
+  - Native events are passed through **unchanged** (`type` + `properties`):
+    `message.updated` (info: tokens, cost, modelID, providerID, time.completed),
+    `message.part.updated` (the full part with id, tool args/output),
+    `message.part.delta`, `session.status`, `session.error`, `session.created`,
+    `session.compacted`, `permission.asked`/`permission.replied`.
+  - Core events: `runtime.ready` `{session:<native session info>, resumed:boolean}`;
+    `runtime.stopped` `{reason, exitCode?:number, signal?:string}`. A resume emits
+    `runtime.ready` with the existing session; it never fabricates `session.created`.
+    **Every process launch that reaches readiness writes exactly one `runtime.ready`**
+    with a new `launchID`, including resume, so the main session is recoverable from
+    the journal alone. A launch that fails before readiness writes `runtime.error`
+    `{error}` under its `launchID` instead.
+  - Consumers: web-runtime, telegram-runtime, statusline-injector and iapeer-memory's
+    weekly collector (it relies on the path, `time`, unchanged `type`/`properties` and
+    no rotation). Changing any of these requires notifying all four.
+  - Native bootstrap snapshots can repeat part ids, so consumers must **upsert parts by id**.
+- `<IAPEER_ROOT>/peers/<p>/opencode/state.json`, written atomically:
+  `{schema:1, identity, cwd, sessionID, launchID, startedAt, lastEventSeq,
+  lastActivityMs, status:"starting|idle|busy|approval|error|stopped", error?}`.
+  - `lastEventSeq` is a fence: every journal line with `seq ≤ lastEventSeq` is
+    durable on disk before the state write.
+  - Busy/idle comes from `status`, not from the pane-log mtime.
+  - An abrupt process death (SIGKILL) is recorded by the core supervisor; the
+    in-process plugin alone cannot promise `stopped`. A stale `busy` after a death
+    is resolved from supervisor liveness.
+- Session identity: exactly one native session per personality. Fresh starts a new
+  ID; resume keeps the same one.
+- Turn completion: correlate assistant `info.time.completed` with terminal tool
+  parts. `session.status` idle is a native observation only: it does not guarantee
+  that no event is still in flight. The live ordering is still to be verified.
+- Control (`interrupt`/`new`/`compact`) and approvals use the existing Fleet API and
+  approval faces. There is no new face API.
+- Endpoint selection: send and control from one channel dialogue anchor on the
+  same endpoint. A send without a runtime resolves to the profile's
+  `default_runtime`. `delivery.delivered_to.runtime` is authoritative for activity.
+  The live runtime is not a selector when two endpoints are live.
+
+Open core contracts this ABI depends on:
+
+- **Agent-endpoint discovery** — the declared profile runtimes plus the agent
+  adapters the core supports, for channel menus. Not `Bun.which` and not a
+  consumer-side hardcode.
+- **Capability-plugin lifecycle** — a stable declaration through which a
+  registered capability plugin (e.g. statusline-injector) gets
+  provision/unprovision per peer and runtime, like the memory slot. Until it
+  exists, a manual install is not reported as final.
+
+## Acceptance matrix
+
+`OPEN` includes implementation and/or missing live proof. Unit tests, config-file
+existence and isolated SDK probes alone do not close an end-to-end row. Row IDs are
+stable interfaces for the independent acceptance harness.
+
+| ID | Mandatory invariant and normal triggers | Owner / evidence required | State |
+|---|---|---|---|
+| OC01 | create/init/add-runtime; discovery intelligence gate; no default-runtime migration | core; cold peer and shared-cwd contrast | OPEN |
+| OC02 | explicit/default endpoint, simultaneous runtimes, exact per-request identity | core; real MCP headers and routing contrast | OPEN |
+| OC03 | cold/warm inbound, busy queue, attachments, response, no loss/duplicate | core; native records, IAP history, 3/3 full cycles | OPEN |
+| OC04 | process launch, MCP import, actual readiness, missing/invalid config/plugin failure | core; native process and effective-config contrast | OPEN |
+| OC05 | attach/detach, human input coexistence, full native history | core + channel clients; actual PTY and history replay | OPEN |
+| OC06 | stop/start, idle-reap/resume, refresh/new/self-fresh/self-done | core; each original trigger and same/fresh session IDs | OPEN |
+| OC07 | abrupt death, crash-loop guard, restart/recovery, durable queued work | core; actual death and recovery, not synthetic mid-pipeline events | OPEN |
+| OC08 | base system swap, native instructions, fresh doctrine on resumed history | core; wire capture before/after full process restart | MECHANISM VERIFIED; adapter proof OPEN |
+| OC09 | memory MCP, shared personality, guide/index, native write/edit/patch authorship, removal | memory provider + core slot; isolated vault and actual tool writes | OPEN |
+| OC10 | gated/yolo, native risky action → broker allow/deny/timeout/cancel; direct attach race | core + approval faces; real risky triggers, no production cards | OPEN |
+| OC11 | interrupt and compact, completion/failure detection; unsupported runtime-specific commands fail loud | core; native turn interruption/compaction records | OPEN |
+| OC12 | native skills and MCP extensions; foreign configuration preserved | core + capability owners; actual tool/skill calls | OPEN |
+| OC13 | state, busy/idle/tool work, errors/notices, usage where available, full owner-channel history | core event contract + web/telegram/statusline owners | OPEN |
+| OC14 | install/update/remove/rollback; signature/exec failure preserves previous state | core + provider installers; exact installed published artifact | OPEN |
+| OC15 | provider-independent config and NVIDIA synthetic cloud trial | core + linus; native model/tool behaviour, no fleet secrets/memory | OPEN |
+| OC16 | Claude/Codex and H4/path-isolation regressions | core + PM; hermetic suite and coordinated native regression | OPEN |
+
+Codex thread goals and third-party Claude/Codex marketplace plugins are not
+cross-runtime guarantees. Their availability is reported explicitly. Native
+OpenCode skills, core MCP and the mandatory memory/approval surfaces are required;
+calling those optional would not satisfy this contract. Unavailable provider
+metrics are null/unknown, never fabricated zeroes.
+
+## Verified mechanism baseline — 2026-10-17
+
+Native npm `opencode-darwin-arm64@1.19.3`, executable SHA-256
+`6d3e6458fce4b649edf974c19959d5dbfe1e7f255a503dcfc01215b24ad3ea5b`.
+The official source tag `v1.19.3` resolves to
+`e3c4eb242585dcd77be1a867391b7c25fd47ce52`; this is a source reference, not
+cryptographic provenance of the npm binary (npm metadata has no gitHead).
+
+The native server was started against a local synthetic OpenAI-compatible provider,
+fresh HOME/XDG directories and a synthetic working directory. The first wire system
+starts with doctrine ONE; after full process stop/start, the same session's next
+system starts with doctrine TWO and contains no ONE. Both user turns survive;
+native AGENTS.md remains in both system messages. This establishes swap/resume
+semantics, not fleet delivery or the acceptance cycles. Production and NVIDIA were
+not contacted. The original probe retained the two requests and native events;
+the reproducible packaged proof is part of the implementation deliverable.
+
+Official references (checked against native 1.19.3, not assumed from latest docs):
+[CLI](https://opencode.ai/docs/cli/),
+[agents](https://opencode.ai/docs/agents/),
+[plugins](https://opencode.ai/docs/plugins/),
+[MCP](https://opencode.ai/docs/mcp-servers/),
+[config precedence](https://opencode.ai/docs/config/#precedence-order),
+[NVIDIA](https://opencode.ai/docs/providers/#nvidia),
+[native prompt selection](https://github.com/anomalyco/opencode/blob/v1.19.3/packages/opencode/src/session/llm/request.ts),
+[native permission lifecycle](https://github.com/anomalyco/opencode/blob/v1.19.3/packages/opencode/src/permission/index.ts).
+
+## Core plugin and native harness — 2026-10-17
+
+`src/opencode/iapeer-plugin.mjs` is the core-owned plugin. It is embedded in the
+binary as text and written to `<dir>/iapeer-plugin.mjs` before every launch. Its
+launch environment is `IAPEER_OPENCODE_DIR`, `PEER_IDENTITY`,
+`IAPEER_OPENCODE_LAUNCH_ID` and, for resume, `IAPEER_OPENCODE_SESSION`. It produces
+the observability ABI above and serves `<dir>/control.sock`
+(`src/opencode/control.ts`). The socket takes one JSON line per connection:
+- `ping` returns the identity, session and status;
+- `deliver {text}` acknowledges `{messageID}` only after the native
+  `message.updated` for that exact core-chosen ID is observed;
+- `interrupt` runs the native abort;
+- `select` publishes `tui.session.select`.
+
+Readiness runs after plugin init returns, because calling the in-process client
+during plugin loading would wait on the instance being built.
+
+`scripts/opencode-native-harness.ts` runs the real binary (`opencode serve`) with a
+synthetic provider and an isolated HOME and root. Run of 2026-10-17 on native 1.19.3:
+16/16 checks passed.
+- Readiness and ping.
+- Idle delivery acknowledged after persistence; doctrine on the wire.
+- A delivery during a running slow turn was acknowledged in 8 ms and processed after
+  that turn. The native queue is durable.
+- Interrupt.
+- Contiguous `seq` and the state fence.
+- Full process restart with `--session`: same session, `resumed=true`, `seq`
+  continues, the new doctrine replaces the old one, native `AGENTS.md` and earlier
+  history are kept.
+
+This proves the producer and plugin mechanics under `serve`. It does not prove the
+TUI-under-supervisor adapter, matrix rows or acceptance cycles.
+
+Native findings that bind the adapter:
+- **Cold config dir means npm on the critical path.** Before loading any external
+  plugin, OpenCode runs `npm install @opencode-ai/plugin@<version>` in each config
+  dir that lacks it (`Config.waitForDependencies`). On 17.10 this took about 60 s
+  on one run and hung for over 4 min on others: a single npm https connection
+  stalled. The adapter must install and verify this dependency at
+  `install-runtime`/update time, not on the wake path. The harness uses
+  `--seed-config` for offline determinism.
+- **`serve` builds the directory instance lazily** (on the first request); the TUI
+  does it at startup.
+- **A SIGTERM during startup can leave the process running.** It killed the npm
+  child, then initialization continued. Stop must escalate TERM → KILL. The plugin's
+  `dispose` does not run on a signal, so `runtime.stopped` for a signal death is the
+  supervisor's job.
+
+## Delivery gate
+
+Source changes and isolated native artifacts are allowed. npm publication and host
+activation are separate coordinated stages. Neither this document nor the runtime
+task authorizes production START, neighbouring service restarts, auth/MFA changes,
+or a signing-gate bypass. Final acceptance uses the exact installed published
+bytes and a PM-owned activation window with recovery instructions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.114",
+  "version": "0.4.115",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/daemon/fleet.ts

@@ -35,6 +35,7 @@
 
 import type { IncomingMessage, ServerResponse } from 'http'
 import { closeSync, openSync, readSync, statSync } from 'fs'
+import { isSupportedLocalRuntime, SUPPORTED_LOCAL_RUNTIMES } from '../core/constants.ts'
 import { buildProcessAddress } from '../core/socket.ts'
 import { IAPEER_VERSION } from '../core/version.ts'
 import {
@@ -79,6 +80,11 @@ export const FLEET_API_VERSION = 1
 export interface FleetRuntimeStatus {
   runtime: string
   status: 'live' | 'asleep' | 'stopped'
+  /** AGENT-ENDPOINT discovery (docs/15 §Agent endpoints): true iff this declared runtime is an
+   *  agent runtime THIS core can host (`host.agent_runtimes`). A channel offers exactly the
+   *  `agent:true` runtimes of a personality — never a consumer-side hardcode or `Bun.which`.
+   *  A declared runtime the running core cannot host (newer peer, older core) is `false`. */
+  agent: boolean
   /** Present (true) iff a HUMAN operator is attached to this live hosted session. */
   attached?: boolean
   /** Whether this runtime is IN A TURN right now — a SEPARATE concept from `status`, which
@@ -125,6 +131,8 @@ export interface FleetHost {
   memory: { provider: string; version: string; heartbeatAgeSecs: number | null } | null
   voice: { provider: string; version: string; heartbeatAgeSecs: number | null } | null
   fda: boolean | null
+  /** The agent runtimes this core build can host (its agent adapters), in preference order. */
+  agent_runtimes: string[]
 }
 
 /** A pending human-approval request as the snapshot exposes it (docs/17). The SAME items
@@ -238,6 +246,7 @@ export function buildFleetSnapshot(
       return {
         runtime: s.runtime,
         status: s.status,
+        agent: isSupportedLocalRuntime(s.runtime),
         ...(attached ? { attached: true } : {}),
         ...(activity ? { activity } : {}),
       }
@@ -289,6 +298,7 @@ export function buildFleetSnapshot(
         ? { provider: voice.provider, version: voice.version, heartbeatAgeSecs: heartbeatAgeSecs(voice, nowMs) }
         : null,
       fda: probeFullDiskAccess(env),
+      agent_runtimes: [...SUPPORTED_LOCAL_RUNTIMES],
     },
     peers,
     // ADDITIVE + omitted when empty (absence ⇒ empty queue, docs/15). broker.list() is a

package/src/opencode/config.ts

@@ -0,0 +1,102 @@
+// Private, personality-scoped OpenCode configuration. This module is preparatory:
+// declaring a runtime as supported is gated on the complete adapter, not this file.
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { isValidName } from '../core/constants.ts'
+import { resolveGlobalRoot, writeFileAtomic, type StorageOptions } from '../storage/index.ts'
+import pluginSource from './iapeer-plugin.mjs' with { type: 'text' }
+
+export const OPENCODE_AGENT = 'iapeer'
+export const OPENCODE_EXTENSION_FRAGMENTS = ['iapeer-memory', 'statusline-injector'] as const
+type JsonObject = Record<string, unknown>
+
+export function opencodePaths(personality: string, options: StorageOptions = {}) {
+  if (!isValidName(personality)) throw new Error(`invalid OpenCode personality: ${personality}`)
+  const dir = join(options.rootDir ?? resolveGlobalRoot(options.env), 'peers', personality, 'opencode')
+  return {
+    dir,
+    plugin: join(dir, 'iapeer-plugin.mjs'),
+    state: join(dir, 'state.json'),
+    events: join(dir, 'events.jsonl'),
+    config: join(dir, 'opencode.json'), // optional operator-owned provider/model config
+  }
+}
+
+function object(value: unknown, source: string): JsonObject {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${source}: expected a JSON object`)
+  return value as JsonObject
+}
+
+/** OpenCode-like object merge; plugin arrays are additive, with stable dedup. */
+export function mergeOpencodeConfig(base: JsonObject, extra: JsonObject): JsonObject {
+  const out = { ...base }
+  for (const [key, value] of Object.entries(extra)) {
+    if (key === 'plugin' && Array.isArray(value)) {
+      const all = [...(Array.isArray(out[key]) ? out[key] as unknown[] : []), ...value]
+      out[key] = all.filter((v, i) => all.findIndex(x => JSON.stringify(x) === JSON.stringify(v)) === i)
+    } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+      const prior = out[key]
+      out[key] = mergeOpencodeConfig(prior && typeof prior === 'object' && !Array.isArray(prior) ? prior as JsonObject : {}, value as JsonObject)
+    } else out[key] = value
+  }
+  return out
+}
+
+export function readOpencodeExtension(path: string): JsonObject {
+  const fragment = object(JSON.parse(readFileSync(path, 'utf8')), path)
+  for (const key of Object.keys(fragment)) {
+    if (key !== 'mcp' && key !== 'plugin') throw new Error(`${path}: unsupported extension field ${key}`)
+  }
+  if (fragment.mcp !== undefined) {
+    const mcp = object(fragment.mcp, `${path}: mcp`)
+    if ('iapeer' in mcp) throw new Error(`${path}: extension cannot replace core IAP MCP`)
+    for (const [name, config] of Object.entries(mcp)) object(config, `${path}: mcp.${name}`)
+  }
+  if (fragment.plugin !== undefined && (!Array.isArray(fragment.plugin) || fragment.plugin.some(p => typeof p !== 'string' || !p.startsWith('file:///')))) {
+    throw new Error(`${path}: plugins must be absolute file URLs`)
+  }
+  return fragment
+}
+
+export interface ComposeOpencodeConfigInput {
+  personality: string
+  doctrine: string
+  daemonUrl: string
+  /** Existing OPENCODE_CONFIG_CONTENT. It is merged, never discarded. */
+  inline?: string
+}
+
+/** No writes and no env resolution except through injected StorageOptions. */
+export function composeOpencodeConfig(input: ComposeOpencodeConfigInput, options: StorageOptions = {}): JsonObject {
+  if (!input.doctrine.trim()) throw new Error('OpenCode requires a non-empty composed system prompt')
+  const paths = opencodePaths(input.personality, options)
+  let result: JsonObject = existsSync(paths.config) ? object(JSON.parse(readFileSync(paths.config, 'utf8')), paths.config) : {}
+  if (input.inline !== undefined) result = mergeOpencodeConfig(result, object(JSON.parse(input.inline), 'OPENCODE_CONFIG_CONTENT'))
+  for (const stem of OPENCODE_EXTENSION_FRAGMENTS) {
+    const path = join(paths.dir, `${stem}.json`)
+    if (existsSync(path)) result = mergeOpencodeConfig(result, readOpencodeExtension(path))
+  }
+  // Last writer for required fields; foreign MCP servers, agents, plugins and
+  // provider settings survive. Effective managed overrides still need a live gate.
+  return mergeOpencodeConfig(result, {
+    autoupdate: false,
+    share: 'disabled',
+    default_agent: OPENCODE_AGENT,
+    agent: { [OPENCODE_AGENT]: { mode: 'primary', prompt: input.doctrine } },
+    mcp: { iapeer: { type: 'remote', url: input.daemonUrl, enabled: true, oauth: false, headers: { 'X-IAPeer-Identity': '{env:PEER_IDENTITY}' } } },
+    plugin: [pathToFileURL(paths.plugin).href],
+  })
+}
+
+/** Installer/launcher must pass only trusted core source. Provider secrets stay in
+ * native env/config, never interpolated into this executable source artifact. */
+export function writeOpencodePlugin(personality: string, source: string, options: StorageOptions = {}): string {
+  const paths = opencodePaths(personality, options)
+  mkdirSync(paths.dir, { recursive: true, mode: 0o700 })
+  writeFileAtomic(paths.plugin, source, 0o600)
+  return paths.plugin
+}
+
+/** The core-owned plugin source shipped with this package (embedded in the compiled binary). */
+export const OPENCODE_PLUGIN_SOURCE: string = pluginSource

package/src/opencode/control.ts

@@ -0,0 +1,55 @@
+// Core side of the OpenCode control socket served by the core-owned plugin
+// (src/opencode/iapeer-plugin.mjs). One newline-terminated JSON request per
+// connection, one JSON response line back. Used for readiness, delivery, interrupt.
+import { connect } from 'node:net'
+
+export type OpencodeControlRequest =
+  | { op: 'ping' }
+  | { op: 'deliver'; text: string }
+  | { op: 'interrupt' }
+  | { op: 'select' }
+
+export interface OpencodeControlResponse {
+  ok: boolean
+  error?: string
+  identity?: string
+  launchID?: string
+  sessionID?: string | null
+  messageID?: string
+  status?: string
+  lastEventSeq?: number
+}
+
+export function opencodeControl(
+  socketPath: string,
+  request: OpencodeControlRequest,
+  timeoutMs = 20000,
+): Promise<OpencodeControlResponse> {
+  return new Promise(resolve => {
+    let buf = ''
+    let settled = false
+    const done = (r: OpencodeControlResponse) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      sock.destroy()
+      resolve(r)
+    }
+    const sock = connect(socketPath)
+    const timer = setTimeout(() => done({ ok: false, error: `control ${request.op}: no response within ${timeoutMs}ms` }), timeoutMs)
+    sock.setEncoding('utf8')
+    sock.on('connect', () => sock.write(JSON.stringify(request) + '\n'))
+    sock.on('data', chunk => {
+      buf += chunk
+      const nl = buf.indexOf('\n')
+      if (nl < 0) return
+      try {
+        done(JSON.parse(buf.slice(0, nl)) as OpencodeControlResponse)
+      } catch {
+        done({ ok: false, error: `control ${request.op}: malformed response` })
+      }
+    })
+    sock.on('error', e => done({ ok: false, error: `control ${request.op}: ${e.message}` }))
+    sock.on('close', () => done({ ok: false, error: `control ${request.op}: connection closed without a response` }))
+  })
+}

package/src/opencode/iapeer-plugin.d.mts

@@ -0,0 +1,4 @@
+// The plugin is shipped as SOURCE TEXT (imported with `{ type: 'text' }`) and written
+// into the peer's private OpenCode directory before each launch.
+declare const source: string
+export default source

package/src/opencode/iapeer-plugin.mjs

@@ -0,0 +1,283 @@
+// iapeer core plugin for OpenCode — the core writes this file before every launch
+// (src/opencode/iapeer-plugin.mjs in @agfpd/iapeer). Do not edit the installed copy.
+//
+// Responsibilities (docs/20-opencode.md):
+//   • the single PRODUCER of the observability ABI: events.jsonl (append-only,
+//     seq monotonic across restarts) + state.json (atomic; lastEventSeq is a fence);
+//   • the structural control surface: a unix socket the core uses for readiness,
+//     message delivery (acknowledged only once THIS message is persisted natively),
+//     interrupt and TUI session selection.
+// Plain ESM, no dependencies: it runs inside OpenCode's own server worker.
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { createServer } from 'node:net'
+import { join } from 'node:path'
+
+const SCHEMA = 1
+const DELIVER_ACK_MS = 15000
+// Native events forwarded into the journal unchanged (type + properties).
+const JOURNALED = new Set([
+  'message.updated',
+  'message.removed',
+  'message.part.updated',
+  'message.part.removed',
+  'message.part.delta',
+  'session.status',
+  'session.idle',
+  'session.error',
+  'session.created',
+  'session.updated',
+  'session.compacted',
+  'permission.asked',
+  'permission.replied',
+])
+
+// Same layout as OpenCode's own ascending identifiers, so a core-chosen messageID
+// sorts correctly in the native history.
+const ID_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+let idLast = 0
+let idCounter = 0
+function ascendingId(prefix) {
+  const now = Date.now()
+  if (now !== idLast) {
+    idLast = now
+    idCounter = 0
+  }
+  idCounter++
+  const value = BigInt(now) * 0x1000n + BigInt(idCounter)
+  let time = ''
+  for (let i = 0; i < 6; i++) time += Number((value >> BigInt(40 - 8 * i)) & 0xffn).toString(16).padStart(2, '0')
+  const bytes = crypto.getRandomValues(new Uint8Array(14))
+  return prefix + '_' + time + Array.from(bytes, b => ID_CHARS[b % 62]).join('')
+}
+
+function sessionOf(type, p) {
+  if (!p || typeof p !== 'object') return null
+  if (typeof p.sessionID === 'string') return p.sessionID
+  if (p.info && typeof p.info.sessionID === 'string') return p.info.sessionID
+  if (p.part && typeof p.part.sessionID === 'string') return p.part.sessionID
+  if (type.startsWith('session.') && p.info && typeof p.info.id === 'string') return p.info.id
+  return null
+}
+
+/** Last `seq` in an existing journal: read only the tail (the journal never shrinks). */
+function lastSeq(path) {
+  if (!existsSync(path)) return 0
+  const fd = openSync(path, 'r')
+  try {
+    const size = fstatSync(fd).size
+    let span = 4096
+    while (true) {
+      const start = Math.max(0, size - span)
+      const buf = Buffer.alloc(size - start)
+      readSync(fd, buf, 0, buf.length, start)
+      const lines = buf.toString('utf8').split('\n').filter(Boolean)
+      // the first line may be cut unless we read from 0
+      for (let i = lines.length - 1; i >= (start === 0 ? 0 : 1); i--) {
+        try {
+          const seq = JSON.parse(lines[i]).seq
+          if (Number.isInteger(seq)) return seq
+        } catch {}
+      }
+      if (start === 0) return 0
+      span *= 4
+    }
+  } finally {
+    closeSync(fd)
+  }
+}
+
+async function server(input) {
+  const env = process.env
+  const dir = env.IAPEER_OPENCODE_DIR
+  const identity = env.PEER_IDENTITY
+  // Not launched by iapeer (or by an incompatible core): stay inert rather than guess.
+  if (!dir || !identity) return {}
+  const client = input.client
+  const launchID = env.IAPEER_OPENCODE_LAUNCH_ID || ascendingId('lch')
+  const paths = {
+    events: join(dir, 'events.jsonl'),
+    state: join(dir, 'state.json'),
+    socket: join(dir, 'control.sock'),
+  }
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+
+  let seq = lastSeq(paths.events)
+  const state = {
+    schema: SCHEMA,
+    identity,
+    cwd: input.directory,
+    sessionID: env.IAPEER_OPENCODE_SESSION || null,
+    launchID,
+    startedAt: Date.now(),
+    lastEventSeq: seq,
+    lastActivityMs: Date.now(),
+    status: 'starting',
+  }
+  function writeState() {
+    const tmp = paths.state + '.' + process.pid + '.tmp'
+    writeFileSync(tmp, JSON.stringify(state) + '\n', { mode: 0o600 })
+    renameSync(tmp, paths.state)
+  }
+  function journal(type, properties, nativeID, sessionID) {
+    seq++
+    const line = { schema: SCHEMA, seq, time: Date.now(), identity, launchID, sessionID: sessionID ?? null, type, properties, nativeID: nativeID ?? null }
+    appendFileSync(paths.events, JSON.stringify(line) + '\n', { mode: 0o600 })
+    state.lastEventSeq = seq // fence: the line above is on disk before the state write below
+    state.lastActivityMs = line.time
+  }
+
+  // ── session: exactly one per identity ──────────────────────────────────────
+  let ensuring
+  async function ensureSession() {
+    if (state.sessionID) return state.sessionID
+    ensuring ??= (async () => {
+      const res = await client.session.create({ body: { title: identity } })
+      if (!res.data || typeof res.data.id !== 'string') throw new Error('session.create failed: ' + JSON.stringify(res.error ?? null))
+      state.sessionID = res.data.id
+      return state.sessionID
+    })().finally(() => {
+      ensuring = undefined
+    })
+    return ensuring
+  }
+  async function selectInTui() {
+    if (!state.sessionID) return
+    await client.tui.publish({ body: { type: 'tui.session.select', properties: { sessionID: state.sessionID } } }).catch(() => {})
+  }
+
+  // ── message acknowledgements: resolved by the native persist event ──────────
+  const waiters = new Map()
+  function awaitPersisted(messageID) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        waiters.delete(messageID)
+        reject(new Error('message ' + messageID + ' not persisted within ' + DELIVER_ACK_MS + 'ms'))
+      }, DELIVER_ACK_MS)
+      waiters.set(messageID, () => {
+        clearTimeout(timer)
+        waiters.delete(messageID)
+        resolve()
+      })
+    })
+  }
+
+  async function handle(req) {
+    switch (req && req.op) {
+      case 'ping':
+        return { ok: true, identity, launchID, sessionID: state.sessionID, status: state.status, lastEventSeq: state.lastEventSeq }
+      case 'deliver': {
+        if (typeof req.text !== 'string' || !req.text) return { ok: false, error: 'deliver: empty text' }
+        const sessionID = await ensureSession()
+        const messageID = ascendingId('msg')
+        const persisted = awaitPersisted(messageID)
+        const res = await client.session.promptAsync({
+          path: { id: sessionID },
+          body: { messageID, agent: 'iapeer', parts: [{ type: 'text', text: req.text }] },
+        })
+        if (res.error) {
+          waiters.delete(messageID)
+          persisted.catch(() => {})
+          return { ok: false, error: 'prompt_async: ' + JSON.stringify(res.error) }
+        }
+        await persisted
+        return { ok: true, sessionID, messageID }
+      }
+      case 'interrupt': {
+        if (!state.sessionID) return { ok: false, error: 'no session' }
+        const res = await client.session.abort({ path: { id: state.sessionID } })
+        return res.error ? { ok: false, error: JSON.stringify(res.error) } : { ok: true }
+      }
+      case 'select':
+        await selectInTui()
+        return { ok: true, sessionID: state.sessionID }
+      default:
+        return { ok: false, error: 'unknown op ' + JSON.stringify(req && req.op) }
+    }
+  }
+
+  // ── control socket ──────────────────────────────────────────────────────────
+  rmSync(paths.socket, { force: true })
+  const control = createServer(conn => {
+    let buf = ''
+    conn.setEncoding('utf8')
+    conn.on('data', chunk => {
+      buf += chunk
+      const nl = buf.indexOf('\n')
+      if (nl < 0) return
+      const line = buf.slice(0, nl)
+      buf = ''
+      let req
+      try {
+        req = JSON.parse(line)
+      } catch {
+        conn.end(JSON.stringify({ ok: false, error: 'bad request' }) + '\n')
+        return
+      }
+      handle(req).then(
+        r => conn.end(JSON.stringify(r) + '\n'),
+        e => conn.end(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }) + '\n'),
+      )
+    })
+    conn.on('error', () => {})
+  })
+  await new Promise((resolve, reject) => {
+    control.once('error', reject)
+    control.listen(paths.socket, () => resolve())
+  })
+
+  // Readiness runs AFTER init returns: calling the in-process client while OpenCode is
+  // still loading this plugin would wait on the very instance state being built.
+  // The socket is up and the session is known (fresh: created now) → runtime.ready —
+  // the core's readiness signal, never a screen glyph.
+  setTimeout(async () => {
+    const resumed = Boolean(state.sessionID)
+    try {
+      const sessionID = await ensureSession()
+      const got = await client.session.get({ path: { id: sessionID } })
+      if (!got.data) throw new Error('session ' + sessionID + ' not found: ' + JSON.stringify(got.error ?? null))
+      if (state.status === 'starting') state.status = 'idle'
+      journal('runtime.ready', { session: got.data, resumed }, null, sessionID)
+    } catch (e) {
+      state.status = 'error'
+      state.error = e instanceof Error ? e.message : String(e)
+      journal('runtime.error', { error: state.error }, null, state.sessionID)
+    }
+    writeState()
+    // The TUI may not be subscribed yet; the core re-selects on demand via op:select.
+    setTimeout(() => void selectInTui(), 500)
+  }, 0)
+  writeState()
+
+  return {
+    event: async ({ event }) => {
+      const type = event && event.type
+      if (!JOURNALED.has(type)) return
+      const p = event.properties
+      const sessionID = sessionOf(type, p)
+      if (type === 'message.updated' && p && p.info && waiters.has(p.info.id)) waiters.get(p.info.id)()
+      if (sessionID && sessionID === state.sessionID) {
+        if (type === 'session.status' && p.status) {
+          state.status = p.status.type === 'busy' || p.status.type === 'retry' ? 'busy' : p.status.type === 'idle' ? 'idle' : state.status
+          delete state.error
+        } else if (type === 'session.idle') state.status = 'idle'
+        else if (type === 'permission.asked') state.status = 'approval'
+        else if (type === 'permission.replied' && state.status === 'approval') state.status = 'busy'
+        else if (type === 'session.error') {
+          state.status = 'error'
+          state.error = JSON.stringify(p.error ?? null)
+        }
+      }
+      journal(type, p, event.id ?? null, sessionID)
+      writeState()
+    },
+    dispose: async () => {
+      state.status = 'stopped'
+      journal('runtime.stopped', { reason: 'dispose' }, null, state.sessionID)
+      writeState()
+      await new Promise(resolve => control.close(() => resolve()))
+      rmSync(paths.socket, { force: true })
+    },
+  }
+}
+
+export default { id: 'iapeer', server }