@agfpd/iapeer 0.4.115 → 0.4.116

package/src/cli/index.ts

@@ -154,7 +154,7 @@ export function listPeers(opts: CliEnvOptions = {}): PeerListing[] {
     let bestMt = -1
     for (const rt of peer.runtimes) {
       try {
-        const mt = getAdapter(rt).newestActivityMtime(peer.cwd)
+        const mt = getAdapter(rt).newestActivityMtime(peer.cwd, { personality: peer.personality, env })
         if (mt !== null && mt > bestMt) {
           bestMt = mt
           lastActive = rt
@@ -367,7 +367,7 @@ export interface RefreshOutcome {
 
 /** Runtimes that consume the layered system prompt (doctrine/fragments) — the only ones a soft-reload
  *  affects. Routers (notifier/telegram) and absent runtimes carry no doctrine. */
-const AGENTIC_RUNTIMES: ReadonlySet<string> = new Set(['claude', 'codex'])
+const AGENTIC_RUNTIMES: ReadonlySet<string> = new Set(['claude', 'codex', 'opencode'])
 
 /**
  * refresh <peer> [runtime] (or --all): arm a LAZY soft-reload. Each agentic (claude/codex) runtime of the
@@ -813,6 +813,9 @@ export async function compactPeer(
   const control = opts.controlFn ?? routeControl
   const compactDone = opts.compactDoneFn ?? waitForCompactDone
   const waitDone = (rt: Runtime, baseline: ReturnType<typeof compactDoneBaseline>, woke: boolean): CompactPeerOutcome | null => {
+    // A structural runtime's control already returned only after the native compaction was recorded
+    // (docs/20) — there is no transcript marker to wait for.
+    if (getAdapter(rt).deliveryConfirm === 'structural') return null
     const done = compactDone(
       {
         personality,
@@ -928,6 +931,8 @@ export interface RemoveOutcome {
   /** Recipient-owned IAP attachment inbox cleanup. Completed attachment copies
    *  are state for the peer lifetime, so explicit peer removal owns their purge. */
   attachmentInbox?: string
+  /** OpenCode private state dir (<root>/state/opencode/<p>) removed with the peer. */
+  opencodeState?: string
 }
 
 /**
@@ -1018,7 +1023,7 @@ export async function removePeerCli(
     const slot = readMemoryProvider(env)
     if (slot?.unprovision) {
       const { runProvisionCommand } = await import('../enable/provisionCommand.ts')
-      const agentic = peer.runtimes.filter((r): r is 'claude' | 'codex' => r === 'claude' || r === 'codex')
+      const agentic = peer.runtimes.filter(r => r === 'claude' || r === 'codex' || r === 'opencode')
       for (const rt of agentic) {
         const o = runProvisionCommand({
           block: slot.unprovision,
@@ -1041,11 +1046,26 @@ export async function removePeerCli(
           },
           { env },
         )
-        unprovisionOutcomes.push(`${rt}:${o.state}${o.state !== 'ok' && o.detail ? ` (${o.detail})` : ''}`)
+        unprovisionOutcomes.push(`memory/${rt}:${o.state}${o.state !== 'ok' && o.detail ? ` (${o.detail})` : ''}`)
       }
     }
   } catch (e) {
-    unprovisionOutcomes.push(`failed: ${e instanceof Error ? e.message : String(e)}`)
+    unprovisionOutcomes.push(`memory failed: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  // Capability-plugin unprovision (docs/21) — same joint, same best-effort contract.
+  try {
+    const { runCapabilityLifecycle } = await import('../capability/index.ts')
+    for (const run of runCapabilityLifecycle({ kind: 'unprovision', personality, cwd: peer.cwd, runtimes: peer.runtimes, occasion: 'remove', env })) {
+      const o = run.outcome
+      appendLifecycleEvent(
+        pluginLogsDir('iapeer', { env }),
+        { ev: 'capability-provision', capability: run.capability, identity: `${run.runtime}-${personality}`, occasion: 'remove', state: o.state, exit: o.exitCode ?? undefined, ms: o.durationMs, detail: o.detail },
+        { env },
+      )
+      unprovisionOutcomes.push(`${run.capability}/${run.runtime}:${o.state}${o.state !== 'ok' && o.detail ? ` (${o.detail})` : ''}`)
+    }
+  } catch (e) {
+    unprovisionOutcomes.push(`capabilities failed: ${e instanceof Error ? e.message : String(e)}`)
   }
   // Codex pre-trust cleanup (reap-side counterpart of the birth-time
   // preTrustCodexCwd): a removed codex peer must
@@ -1086,12 +1106,27 @@ export async function removePeerCli(
   } catch (e) {
     attachmentInbox = `FAILED: ${e instanceof Error ? e.message : String(e)}`
   }
+  // OpenCode private state (journal, state, plugin, control socket, provider fragments) lives under
+  // <root>/state/opencode/<p>, outside the cwd — it must not outlive the peer and ambush a namesake.
+  // After unprovision above, so the memory/capability owners removed their own files first.
+  let opencodeState: string | undefined
+  try {
+    const { opencodePaths } = await import('../opencode/config.ts')
+    const dir = opencodePaths(personality, { env }).dir
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true, force: true })
+      opencodeState = `removed ${dir}`
+    }
+  } catch (e) {
+    opencodeState = `FAILED: ${e instanceof Error ? e.message : String(e)}`
+  }
   return {
     personality,
     action: 'removed',
     cwd: peer.cwd,
     purgedState,
     ...(attachmentInbox ? { attachmentInbox } : {}),
+    ...(opencodeState ? { opencodeState } : {}),
     ...(plistTeardown ? { plistTeardown } : {}),
     ...(unprovisionOutcomes.length ? { unprovision: unprovisionOutcomes } : {}),
     ...(trustCleaned ? { codexTrust: trustCleaned } : {}),
@@ -1554,6 +1589,7 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
   { sig: 'compact <peer> [runtime]', desc: 'compact the peer\'s dialogue (/compact); resumes clean-asleep first' },
   { sig: 'self-fresh', desc: '(agent self-call) mark /new eager-fresh + self-kill — the daemon relaunches fresh' },
   { sig: 'self-done', desc: '(agent self-call, ephemeral) silent finish: arm own quiet-reap, wake no one' },
+  { sig: 'capability <list | register <decl.json> | sync <name> | unregister <name>>', desc: 'capability-plugin lifecycle: per-peer provision/unprovision on every agent endpoint (docs/21)' },
   { sig: 'native-memory <off|on> (--peer <p> | --all)', desc: "gate/restore runtimes' native memory (canonized lever; контракт «Слот памяти»)" },
   { sig: 'trust-hooks <hooks.json> [--check]', desc: 'pre-seed codex hooks trust for a file-form hooks.json (no modal); --check = drift report' },
   {
@@ -1564,6 +1600,7 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
     sig: 'tray install|uninstall|render [--stream]|cmd <c> <peer>|approve <id>|deny <id> [reason]|status',
     desc: 'the macOS menu-bar fleet dashboard (SwiftBar plugin) — first external Fleet API client; renders the approval queue (badge + Allow/Deny), install activates it (installs SwiftBar when absent). See docs/16.',
   },
+  { sig: 'private-dir <peer> [--runtime r]', desc: 'print the core-owned private directory of a peer endpoint (docs/20: opencode journal/state/fragments). The ONLY way a process not launched by the core gets the path — never derive the layout. Without --runtime: the single declared runtime that has one. Exit 1 when none' },
   { sig: 'approval-mode <peer> [gated|yolo]', desc: 'read/flip a peer\'s human-approval mode (docs/17): yolo=current bypass; gated=blocking runtime approvals routed to a human. Persists + brings runtime surfaces to the mode; applies on next fresh session' },
   { sig: 'approvals [--json]', desc: 'list pending human-approval requests (verbatim action content); the host answer channel to the daemon broker' },
   { sig: 'approve <id>', desc: 'approve a pending request — the decision clears it in every channel' },
@@ -1839,6 +1876,11 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         if (tcc) out(tcc)
         return daemonFailed || r.marketplaces.some(m => m.state === 'failed') || infraFailed ? 1 : 0
       }
+      case 'capability': {
+        // Capability-plugin lifecycle (docs/21): register / sync / unregister / list.
+        const { capabilityCli } = await import('../capability/cli.ts')
+        return capabilityCli(positionals, env, out, errOut)
+      }
       case 'native-memory': {
         // The canonized runtime-memory lever (контракт «Слот памяти» §Native-память):
         // off = explicit disable merged into the peer's runtime config files; on =
@@ -2237,6 +2279,32 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         for (const o of outcomes) out(`${o.personality}: ${o.action}${o.detail ? ` — ${o.detail}` : ''}\n`)
         return outcomes.some(o => o.action === 'failed') ? 1 : 0
       }
+      case 'private-dir': {
+        const name = positionals[0]
+        if (!name) return argErr(errOut, 'private-dir needs a peer — usage: iapeer private-dir <peer> [--runtime r]')
+        const peer = findPeer(readPeersIndex({ env }), name)
+        if (!peer) {
+          errOut(`peer "${name}" is not registered\n`)
+          return 1
+        }
+        const { endpointPrivateDir } = await import('../storage/index.ts')
+        const wanted = typeof flags.runtime === 'string' ? flags.runtime : undefined
+        if (wanted && !peer.runtimes.includes(wanted)) {
+          errOut(`peer "${name}" does not declare runtime "${wanted}" (declared: ${peer.runtimes.join(', ')})\n`)
+          return 1
+        }
+        const candidates = (wanted ? [wanted] : peer.runtimes).filter(rt => endpointPrivateDir(rt, name, { env }))
+        if (candidates.length !== 1) {
+          errOut(
+            candidates.length === 0
+              ? `no private directory for "${name}"${wanted ? ` (${wanted})` : ''} — only opencode endpoints have one\n`
+              : `"${name}" has several endpoints with a private directory (${candidates.join(', ')}) — pass --runtime\n`,
+          )
+          return 1
+        }
+        out(`${endpointPrivateDir(candidates[0]!, name, { env })}\n`)
+        return 0
+      }
       case 'default-runtime': {
         // The PRIMARY flip (routing/wake default) — the fleet-switch moment itself.
         const rt = positionals[0]
@@ -2313,7 +2381,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           }
           // v1.2: the provider unwound its surfaces (occasion=remove) — say how it went.
           if (o.unprovision?.length) {
-            out(`memory unprovision: ${o.unprovision.join(', ')}\n`)
+            out(`unprovision: ${o.unprovision.join(', ')}\n`)
           }
           // Codex pre-trust cleanup — the cwd's trust entry must die with the peer.
           if (o.codexTrust) {
@@ -2328,6 +2396,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           if (o.purgedState?.length) {
             out(`lifecycle state purged: ${o.purgedState.join(', ')}\n`)
           }
+          if (o.opencodeState) out(`opencode state: ${o.opencodeState}\n`)
           if (o.attachmentInbox) {
             out(`attachment inbox: ${o.attachmentInbox}\n`)
           }

package/src/core/constants.ts

@@ -11,7 +11,7 @@ export const RUNTIME_RE_SOURCE = '^[a-z][a-z0-9]{0,31}$'
 
 export type Runtime = string
 export type TmuxRuntime = Runtime
-export const SUPPORTED_LOCAL_RUNTIMES = ['claude', 'codex'] as const
+export const SUPPORTED_LOCAL_RUNTIMES = ['claude', 'codex', 'opencode'] as const
 export type SupportedLocalRuntime = (typeof SUPPORTED_LOCAL_RUNTIMES)[number]
 
 export const PEERS_SCHEMA_VERSION = 2

package/src/daemon/fleet.ts

@@ -37,6 +37,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 { endpointPrivateDir } from '../storage/index.ts'
 import { IAPEER_VERSION } from '../core/version.ts'
 import {
   ephemeralQueueDepth,
@@ -85,6 +86,9 @@ export interface FleetRuntimeStatus {
    *  `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
+  /** Core-owned private directory of this endpoint (docs/20: opencode journal/state). Absent when the
+   *  runtime has none. Observers read it from here; they never derive the layout. */
+  private_dir?: string
   /** 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
@@ -236,6 +240,10 @@ export function buildFleetSnapshot(
    *  never emitted, which is exactly its "no claim" semantics. */
   activityOf?: (personality: string, runtime: string) => TurnActivity | undefined,
 ): FleetSnapshot {
+  const privateDirOf = (runtime: string, personality: string): { private_dir?: string } => {
+    const d = endpointPrivateDir(runtime, personality, { env })
+    return d ? { private_dir: d } : {}
+  }
   const peers: FleetPeer[] = ops.listPeers({ env }).map(r => {
     const runtimes: FleetRuntimeStatus[] = r.runtimes.map(s => {
       const attached =
@@ -247,6 +255,7 @@ export function buildFleetSnapshot(
         runtime: s.runtime,
         status: s.status,
         agent: isSupportedLocalRuntime(s.runtime),
+        ...(privateDirOf(s.runtime, r.personality)),
         ...(attached ? { attached: true } : {}),
         ...(activity ? { activity } : {}),
       }

package/src/enable/provisionCommand.ts

@@ -18,6 +18,7 @@
 
 import { spawnSync } from 'child_process'
 import { accessSync, constants as FS } from 'fs'
+import { endpointPrivateDir } from '../storage/index.ts'
 import type { MemoryProviderProvision } from '../status/index.ts'
 
 /** The agreed occasion vocabulary (финален). */
@@ -48,8 +49,9 @@ export interface ProvisionCommandOutcome {
   argv: string[]
 }
 
-function substitute(arg: string, s: ProvisionCommandSpec): string {
+function substitute(arg: string, s: ProvisionCommandSpec, privateDir: string | undefined): string {
   return arg
+    .replaceAll('{privateDir}', privateDir ?? '{privateDir}')
     .replaceAll('{cwd}', s.cwd)
     .replaceAll('{runtime}', s.runtime)
     .replaceAll('{personality}', s.personality)
@@ -70,9 +72,16 @@ function tail(text: string, max = 400): string | undefined {
  * must not kill a birth or a remove).
  */
 export function runProvisionCommand(spec: ProvisionCommandSpec): ProvisionCommandOutcome {
-  const env = spec.env ?? process.env
-  const argv = [spec.block.command, ...spec.block.args.map(a => substitute(a, spec))]
+  const baseEnv = spec.env ?? process.env
+  const privateDir = endpointPrivateDir(spec.runtime, spec.personality, { env: baseEnv })
+  const argv = [spec.block.command, ...spec.block.args.map(a => substitute(a, spec, privateDir))]
   const started = Date.now()
+  // {privateDir} for a runtime that has none is a declaration error — refuse loudly rather than run
+  // the command with a guessed or empty path.
+  if (!privateDir && spec.block.args.some(a => a.includes('{privateDir}'))) {
+    return { state: 'failed', exitCode: null, detail: `{privateDir} is undefined for runtime "${spec.runtime}"`, durationMs: 0, argv }
+  }
+  const env: NodeJS.ProcessEnv = privateDir ? { ...baseEnv, IAPEER_PRIVATE_DIR: privateDir } : baseEnv
   try {
     accessSync(spec.block.command, FS.X_OK)
   } catch {

package/src/identity/index.ts

@@ -215,7 +215,7 @@ export function discoverPeerRuntimes(cwd: string, currentRuntime: Runtime): Runt
 
 /** Agentic runtimes only an ARTIFICIAL peer can drive. A natural (human) or absent
  *  (no mind) peer has nobody to sit in a claude/codex session under its identity. */
-const AGENTIC_GATED_RUNTIMES: ReadonlySet<string> = new Set(['claude', 'codex'])
+const AGENTIC_GATED_RUNTIMES: ReadonlySet<string> = new Set(['claude', 'codex', 'opencode'])
 
 /**
  * DISCOVERY GATE (хвост-2, boris 15.07): drop agentic runtimes a NON-artificial peer

package/src/init/index.ts

@@ -32,41 +32,19 @@ import { provisionPeer, type ProvisionResult } from '../provision/index.ts'
 import { claudeSettingsPath } from '../launch/nativeMemory.ts'
 import { bootstrapFailed, launchctlBootstrap, resolveAlwaysOnTarget, type BootstrapResult } from '../launch/launchd.ts'
 import { runtimeSelfConfig, type SelfConfigResult } from '../runtime/index.ts'
+import { defaultEnsureDepsDeps, ensureOpencodePluginDependency, type EnsureDepsDeps } from '../opencode/deps.ts'
 import type { Intelligence } from '../core/constants.ts'
 
 /** The MCP-server name the peer's `.mcp.json` uses for the foundation daemon. */
 export const IAPEER_MCP_SERVER_NAME = 'iapeer'
 
-/** Fallback HTTP-MCP daemon port when no router.json is published yet (the daemon
- *  binds this stable loopback port by default; init before daemon-start uses it). */
-export const DEFAULT_DAEMON_MCP_PORT = 8765
+// Daemon URL resolution lives in storage (shared with the launch adapters without an
+// init↔launch import cycle); re-exported here for existing callers.
+import { DEFAULT_DAEMON_MCP_PORT, resolveDaemonMcpUrl } from '../storage/index.ts'
+export { DEFAULT_DAEMON_MCP_PORT, resolveDaemonMcpUrl }
 
 const IAPEER_DOCTRINE_FILE = 'IAPEER.md'
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Daemon URL resolution (router.json published by the daemon, else the default)
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Resolve the daemon HTTP-MCP URL to write into a peer's `.mcp.json`. Primary: the
- * `tcp` field of the daemon's discovery file `~/.iapeer/state/iapeer/router.json`
- * (published live by the daemon). Fallback: the well-known default loopback URL —
- * so `iapeer init` works even before the daemon is started (the daemon binds the
- * same stable port; IAPEER_PORT overrides it at the daemon, not here).
- */
-export function resolveDaemonMcpUrl(options: StorageOptions = {}): string {
-  const routerJson = join(pluginStateDir('iapeer', options), 'router.json')
-  try {
-    const parsed = JSON.parse(readFileSync(routerJson, 'utf8')) as { tcp?: unknown }
-    if (typeof parsed.tcp === 'string' && parsed.tcp) return parsed.tcp
-  } catch {
-    /* no router.json (daemon not started) → the well-known default below */
-  }
-  const env = options.env ?? process.env
-  const port = env.IAPEER_PORT?.trim() || String(DEFAULT_DAEMON_MCP_PORT)
-  return `http://127.0.0.1:${port}/mcp`
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // claude `.mcp.json` wiring (project-scope; auto-enables on cold-start)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -394,18 +372,33 @@ export function ensureGlobalDoctrineTemplate(env: NodeJS.ProcessEnv = process.en
  */
 export function isRuntimeInstalled(runtime: Runtime, env: NodeJS.ProcessEnv = process.env): boolean {
   if (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') return true
-  const override = runtime === 'claude' ? env.IAPEER_CLAUDE_BIN : runtime === 'codex' ? env.IAPEER_CODEX_BIN : undefined
+  const override =
+    runtime === 'claude' ? env.IAPEER_CLAUDE_BIN
+    : runtime === 'codex' ? env.IAPEER_CODEX_BIN
+    : runtime === 'opencode' ? env.IAPEER_OPENCODE_BIN
+    : undefined
   if (override?.trim()) return true
   const home = env.HOME?.trim() || homedir()
   if (runtime === 'claude' && existsSync(join(home, '.local', 'bin', 'claude'))) return true
   if (Bun.which(runtime)) return true
   if (runtime === 'claude' && existsSync(join(home, '.claude'))) return true
   if (runtime === 'codex' && existsSync(join(home, '.codex'))) return true
+  // OpenCode's official installer puts the binary in ~/.opencode/bin (not on a launchd PATH).
+  if (runtime === 'opencode' && existsSync(join(home, '.opencode', 'bin', 'opencode'))) return true
   return false
 }
 
 const AGENTIC_RUNTIMES: Runtime[] = ['claude', 'codex']
 
+/** The OpenCode binary the core launches: IAPEER_OPENCODE_BIN, else the official installer's
+ *  ~/.opencode/bin/opencode, else `opencode` on PATH (mirrors loadLifecycleConfig). */
+export function resolveOpencodeBin(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.IAPEER_OPENCODE_BIN?.trim()
+  if (override) return override
+  const installed = join(env.HOME?.trim() || homedir(), '.opencode', 'bin', 'opencode')
+  return existsSync(installed) ? installed : 'opencode'
+}
+
 /**
  * Resolve a peer's primary AGENTIC runtime — install-aware:
  *   1. explicit (`--runtime`) → use it, but VALIDATE it is installed (clear error instead
@@ -469,6 +462,9 @@ export interface InitPeerOptions {
   bootstrap?: boolean
   env?: NodeJS.ProcessEnv
   warn?: (message: string) => void
+  /** OpenCode plugin-dependency preinstall seam (tests). Absent → the real binary + npm; skipped
+   *  entirely under IAPEER_TEST_SANDBOX unless injected. */
+  opencodeDeps?: EnsureDepsDeps
 }
 
 export interface InitPeerResult extends ProvisionResult {
@@ -505,6 +501,22 @@ export async function initPeer(opts: InitPeerOptions): Promise<InitPeerResult> {
   // decide the primary (resolvePrimaryRuntime), so the primary always matches the
   // config that gets written (no `.codex`-only-but-primary-claude mismatch).
   const runtime = resolvePrimaryRuntime(opts.cwd, opts.runtime, rt => isRuntimeInstalled(rt, env))
+  // OpenCode: satisfy the native plugin-dependency no-op BEFORE the runtime is registered, so a wake
+  // never waits on npm (docs/20). Fail-closed: a failure leaves the peer without the opencode runtime.
+  if (runtime === 'opencode') {
+    const sandboxed = env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1'
+    if (opts.opencodeDeps || !sandboxed) {
+      const deps = opts.opencodeDeps ?? defaultEnsureDepsDeps(resolveOpencodeBin(env), env)
+      const outcomes = ensureOpencodePluginDependency(opts.cwd, env, deps)
+      const failed = outcomes.filter(o => o.state === 'failed')
+      if (failed.length > 0) {
+        throw new IapError(
+          `opencode plugin dependency preinstall failed — ${failed.map(f => `${f.dir}: ${f.detail ?? 'failed'}`).join('; ')}. ` +
+            `Without it OpenCode runs npm on every cold start. Fix npm access and re-run.`,
+        )
+      }
+    }
+  }
   const provisioned = await provisionPeer({
     cwd: opts.cwd,
     runtime,

package/src/launch/adapters/opencode.ts

@@ -0,0 +1,192 @@
+// opencode RuntimeAdapter — the "HOW to launch / observe ONE OpenCode session" half of the
+// launch contract (docs/20-opencode.md). Unlike claude/codex, NOTHING here reads the screen:
+// readiness, delivery and control go through the core-owned in-process plugin
+// (src/opencode/iapeer-plugin.mjs) — its runtime.ready journal line, its control socket and its
+// per-message persistence ack. The native TUI is still hosted by the pty supervisor (the human
+// attach surface), but the core never pastes into it.
+//
+// Per-launch preparation (prepareLaunch):
+//   • write the plugin source into <root>/state/opencode/<p>/ (re-written every launch — the
+//     installed copy is never trusted to be current);
+//   • compose OPENCODE_CONFIG_CONTENT: the operator's opencode.json + inline env config, the memory
+//     and capability fragments, then the core-required fields (agent.iapeer.prompt = the freshly
+//     composed doctrine, the iapeer MCP, the plugin) — doctrine is re-read on EVERY process launch,
+//     including resume;
+//   • the plugin ABI env: IAPEER_OPENCODE_DIR / _LAUNCH_ID / _SESSION (resume only).
+//
+// State is personality-scoped (not cwd-scoped: two personalities may share a cwd), so the
+// observation methods take the optional ObserveContext; without it they answer null/not-ok.
+
+import { randomBytes } from 'node:crypto'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { composeOpencodeConfig, OPENCODE_AGENT, OPENCODE_PLUGIN_SOURCE, opencodePaths, writeOpencodePlugin } from '../../opencode/config.ts'
+import { opencodeControl } from '../../opencode/control.ts'
+import { fileMtimeMs, readJournalFrom, readOpencodeState } from '../../opencode/journal.ts'
+import { resolveDaemonMcpUrl } from '../../storage/index.ts'
+import { resolveFleetBase } from '../../approval/brokerClient.ts'
+import type {
+  ApprovalMode,
+  ControlCommand,
+  ControlPlan,
+  LaunchAdapterConfig,
+  LaunchSpec,
+  ObserveContext,
+  PreparedLaunch,
+  RuntimeAdapter,
+} from '../types.ts'
+
+/** Compaction is a model turn; bound it like a long turn, not like a socket round-trip. */
+export const OPENCODE_COMPACT_TIMEOUT_MS = 600_000
+
+/** Journal byte offset at prepare time, per launchID — structuralReady scans only THIS launch's lines. */
+const readyOffsets = new Map<string, number>()
+
+function newLaunchID(): string {
+  return `lch_${Date.now().toString(36)}${randomBytes(6).toString('hex')}`
+}
+
+function paths(personality: string, env?: NodeJS.ProcessEnv) {
+  return opencodePaths(personality, { env })
+}
+
+function controlSocket(personality: string, env?: NodeJS.ProcessEnv): string {
+  return `${paths(personality, env).dir}/control.sock`
+}
+
+export const opencodeAdapter: RuntimeAdapter = {
+  runtime: 'opencode',
+  kind: 'tui',
+  usesDoctrine: true,
+  // No pty submit surface: the core never pastes into the OpenCode TUI.
+  deliveryMarkers: { promptGlyphs: [] },
+  deliveryConfirm: 'structural',
+
+  buildArgv(spec: LaunchSpec, cfg: LaunchAdapterConfig): string[] {
+    const argv = [cfg.opencodeBin ?? 'opencode']
+    if (spec.resume && spec.resumeRef) argv.push('--session', spec.resumeRef)
+    argv.push('--agent', OPENCODE_AGENT)
+    // yolo (default) = the fleet's bypass posture; gated launches without it so native
+    // permission requests reach the approval path (docs/17, OC10).
+    if ((spec.approvalMode ?? 'yolo') === 'yolo') argv.push('--auto')
+    if (spec.extraArgs?.length) argv.push(...spec.extraArgs)
+    return argv
+  },
+
+  prepareLaunch(spec, baseEnv, cfg): PreparedLaunch {
+    const env = cfg.env ?? process.env
+    if (!spec.systemPromptFile || !existsSync(spec.systemPromptFile)) {
+      throw new Error(`opencode: composed system prompt missing (${spec.systemPromptFile ?? 'none'})`)
+    }
+    const doctrine = readFileSync(spec.systemPromptFile, 'utf8')
+    const p = paths(spec.personality, env)
+    writeOpencodePlugin(spec.personality, OPENCODE_PLUGIN_SOURCE, { env })
+    const config = composeOpencodeConfig(
+      {
+        personality: spec.personality,
+        doctrine,
+        daemonUrl: resolveDaemonMcpUrl({ env }),
+        inline: baseEnv.OPENCODE_CONFIG_CONTENT,
+        approvalMode: spec.approvalMode ?? 'yolo',
+      },
+      { env },
+    )
+    const launchID = newLaunchID()
+    readyOffsets.set(launchID, existsSync(p.events) ? statSync(p.events).size : 0)
+    const out: Record<string, string> = {
+      OPENCODE_CONFIG_CONTENT: JSON.stringify(config),
+      IAPEER_OPENCODE_DIR: p.dir,
+      IAPEER_OPENCODE_LAUNCH_ID: launchID,
+      IAPEER_IDENTITY: spec.identity,
+      // A fleet peer never self-updates (config autoupdate:false says the same; the flag also covers
+      // native paths that read only the env). Updates are an operator action.
+      OPENCODE_DISABLE_AUTOUPDATE: '1',
+      // docs/17: the plugin bridges native permission asks to the daemon broker only when gated.
+      IAPEER_APPROVAL_MODE: spec.approvalMode ?? 'yolo',
+      IAPEER_FLEET_URL: resolveFleetBase(env),
+    }
+    if (spec.resume && spec.resumeRef) out.IAPEER_OPENCODE_SESSION = spec.resumeRef
+    return { env: out, readyToken: launchID }
+  },
+
+  async structuralReady(spec, launchID, deadlineMs, alive, env) {
+    const p = paths(spec.personality, env)
+    let offset = readyOffsets.get(launchID) ?? 0
+    try {
+      while (Date.now() < deadlineMs) {
+        const { lines, end } = readJournalFrom(p.events, offset)
+        offset = end
+        for (const l of lines) {
+          if (l.launchID !== launchID) continue
+          if (l.type === 'runtime.ready') {
+            // The control socket is up before readiness is journaled; one ping proves it serves.
+            const ping = await opencodeControl(controlSocket(spec.personality, env), { op: 'ping' }, 5000)
+            if (!ping.ok) return { ok: false, reason: `runtime.ready seen but control ping failed: ${ping.error}` }
+            if (ping.launchID !== launchID) return { ok: false, reason: `control socket answers launch ${ping.launchID}, expected ${launchID}` }
+            return { ok: true }
+          }
+          if (l.type === 'runtime.error') {
+            const e = (l.properties as { error?: unknown } | null)?.error
+            return { ok: false, reason: `runtime.error: ${typeof e === 'string' ? e : JSON.stringify(e)}` }
+          }
+        }
+        if (!alive()) return { ok: false, reason: 'process exited before runtime.ready' }
+        await new Promise(r => setTimeout(r, 500))
+      }
+      return { ok: false, reason: 'no runtime.ready before the boot deadline (plugin not loaded?)' }
+    } finally {
+      readyOffsets.delete(launchID)
+    }
+  },
+
+  async deliver(target, text, env) {
+    const r = await opencodeControl(controlSocket(target.personality, env), { op: 'deliver', text })
+    return r.ok ? { ok: true, messageID: r.messageID } : { ok: false, error: r.error ?? 'deliver failed' }
+  },
+
+  async control(target, command, env) {
+    if (command.name === 'interrupt') {
+      const r = await opencodeControl(controlSocket(target.personality, env), { op: 'interrupt' })
+      return r.ok ? { ok: true } : { ok: false, error: r.error ?? 'interrupt failed' }
+    }
+    if (command.name === 'compact') {
+      // Blocks until the native summary turn completed and session.compacted is recorded.
+      const r = await opencodeControl(controlSocket(target.personality, env), { op: 'compact' }, OPENCODE_COMPACT_TIMEOUT_MS)
+      return r.ok ? { ok: true } : { ok: false, error: r.error ?? 'compact failed' }
+    }
+    return { ok: false, error: `opencode does not support control command "${command.name}"` }
+  },
+
+  // ── Screen predicates: deliberately inert (structural runtime). ──────────────
+  bootDialogKeys(): string[] | null {
+    return null
+  },
+  isInputReady(_pane: string, _mode?: ApprovalMode): boolean {
+    return false
+  },
+
+  newestActivityMtime(_cwd: string, ctx?: ObserveContext): number | null {
+    return ctx ? fileMtimeMs(paths(ctx.personality, ctx.env).events) : null
+  },
+
+  /** Busy/idle come from the plugin's state, not from a file mtime: lastActivityMs advances only on
+   *  journaled native events. A busy/approval status counts as activity NOW (a long tool call). */
+  lastTurnMtime(_cwd: string, ctx?: ObserveContext): number | null {
+    if (!ctx) return null
+    const s = readOpencodeState(paths(ctx.personality, ctx.env).state)
+    if (!s) return null
+    if (s.status === 'busy' || s.status === 'approval') return Date.now()
+    return s.lastActivityMs
+  },
+
+  resolveResume(_cwd: string, ctx?: ObserveContext): { ok: boolean; ref?: string; reason?: string } {
+    if (!ctx) return { ok: false, reason: 'opencode resume needs the personality (no observation context)' }
+    const s = readOpencodeState(paths(ctx.personality, ctx.env).state)
+    if (!s?.sessionID) return { ok: false, reason: `no recorded OpenCode session for "${ctx.personality}"` }
+    return { ok: true, ref: s.sessionID }
+  },
+
+  // Control goes through `control` above; there is no pty key plan.
+  executeControl(_command: ControlCommand): ControlPlan | null {
+    return null
+  },
+}

package/src/launch/index.ts

@@ -25,6 +25,7 @@ import { telegramAdapter } from './adapters/telegram.ts'
 import { notifierAdapter } from './adapters/notifier.ts'
 import { voicetalkAdapter } from './adapters/voicetalk.ts'
 import { webAdapter } from './adapters/web.ts'
+import { opencodeAdapter } from './adapters/opencode.ts'
 import type {
   LaunchConfig,
   LaunchFn,
@@ -97,6 +98,7 @@ export function getAdapter(runtime: Runtime): RuntimeAdapter {
   if (runtime === 'notifier') return notifierAdapter
   if (runtime === 'voicetalk') return voicetalkAdapter
   if (runtime === 'web') return webAdapter
+  if (runtime === 'opencode') return opencodeAdapter
   throw new Error(`no launch adapter for runtime "${runtime}"`)
 }
 
@@ -189,6 +191,19 @@ export const launch: LaunchFn = async (
   // loads here, default-on — and the router branch never reaches it).
   if (adapter.kind === 'tui' || adapter.kind === 'router') {
     const invocation = buildLaunchInvocation(spec, adapter, cfg)
+    // Structural runtimes (opencode) prepare launch artifacts + extra env BEFORE spawn. The identity
+    // ABI stays authoritative: prepared env never overrides PEER_PERSONALITY/RUNTIME/IDENTITY.
+    let readyToken: string | undefined
+    if (adapter.prepareLaunch) {
+      try {
+        const prepared = adapter.prepareLaunch(spec, invocation.env, cfg)
+        const { PEER_PERSONALITY, PEER_RUNTIME, PEER_IDENTITY } = invocation.env
+        invocation.env = { ...invocation.env, ...prepared.env, PEER_PERSONALITY, PEER_RUNTIME, PEER_IDENTITY }
+        readyToken = prepared.readyToken
+      } catch (e) {
+        return fail(identity, `launch preparation failed: ${e instanceof Error ? e.message : String(e)}`)
+      }
+    }
     mkdirSync(cfg.logDir, { recursive: true, mode: 0o700 }) // the supervisor writes the pane-log here
     const paneLogPath = `${cfg.logDir}/${identity}.log`
     // SESSION-START BOUNDARY (premature-ready fix): the pane-log is a SHARED append-only file across a
@@ -219,6 +234,18 @@ export const launch: LaunchFn = async (
         if (hostSessionAlive(identity, env)) return ready(identity)
         return fail(identity, 'hosted router session not alive immediately after bringup')
       }
+      // STRUCTURAL runtime (opencode): readiness = the runtime's own ready record for THIS launch, and
+      // the first message goes through the adapter's deliver, whose ack means THIS message is persisted
+      // natively (a durable native queue) — so there is no pane gate and no activity ready-gate.
+      if (adapter.structuralReady && readyToken) {
+        const r = await adapter.structuralReady(spec, readyToken, Date.now() + cfg.bootDeadlineSecs * 1000, () => hostSessionAlive(identity, env), env)
+        if (!r.ok) return fail(identity, `never-became-ready (structural: ${r.reason ?? 'unknown'})`)
+        if (firstMessage.trim().length === 0) return ready(identity)
+        if (!adapter.deliver) return fail(identity, 'structural runtime has no deliver hook')
+        const d = await adapter.deliver({ personality: spec.personality, identity }, firstMessage, env)
+        if (!d.ok) return fail(identity, `structural deliver failed: ${d.error}`)
+        return ready(identity)
+      }
       // BOOT: the supervisor's boot-driver dismisses startup dialogs internally; wait for the input
       // surface via the pane-log model, then deliver over the socket + ready-gate on a model turn —
       // the SAME shape as the tmux boot/deliver/ready-gate below, with host equivalents.
@@ -234,7 +261,7 @@ export const launch: LaunchFn = async (
       // alone push mtime past the baseline, so the gate below fires on the boot write — NOT on the
       // model PROCESSING firstMessage — returning ready/taskDelivered while the message is unseen
       // (silent loss). Snapped here — post-boot, pre-deliver — only the model's own turn advances it.
-      const baselineMtime = adapter.newestActivityMtime(cwd) ?? 0
+      const baselineMtime = adapter.newestActivityMtime(cwd, { personality: spec.personality, env }) ?? 0
       // INSTRUMENTATION (premature-ready diagnosis): record the session-start boundary and how much THIS
       // session had written into the shared pane-log by the time the ready-gate fired. On a recurrence,
       // paneLogBytes ≈ paneLogStartByte (ready seen though the new session wrote ~nothing) localizes a
@@ -255,7 +282,7 @@ export const launch: LaunchFn = async (
       while (Date.now() < readyDeadline) {
         await sleep(2000)
         if (!hostSessionAlive(identity, env)) return fail(identity, 'hosted session vanished during ready-gate')
-        if ((adapter.newestActivityMtime(cwd) ?? 0) > baselineMtime) return ready(identity)
+        if ((adapter.newestActivityMtime(cwd, { personality: spec.personality, env }) ?? 0) > baselineMtime) return ready(identity)
       }
       return fail(identity, 'model-did-not-process-task (hosted: no activity advance after delivery)')
     }