@agfpd/iapeer 0.4.114 → 0.4.116

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)')
     }

package/src/launch/types.ts

@@ -143,6 +143,8 @@ export interface LaunchAdapterConfig {
   voicetalkBin?: string
   /** web-runtime launch binary (router runtime, infra/always-on — the owner's browser fleet-console). */
   webBin?: string
+  /** OpenCode native TUI binary (agent runtime, docs/20). Absent → `opencode` on PATH. */
+  opencodeBin?: string
 }
 
 export interface LaunchSpec {
@@ -283,8 +285,11 @@ export interface RuntimeAdapter {
    *     transcript grace here only ever FALSE-FAILs a message that WILL be processed,
    *     wrongly escalating to a fallback peer. A genuinely dead session still fails
    *     at the socket-ack (no socket / stalled flush) → really-dead still escalates.
+   *   - 'structural' (opencode): the runtime has NO pty submit surface at all — delivery goes through
+   *     the adapter's own `deliver` hook (a native control channel) whose acknowledgement already means
+   *     THIS message was persisted natively. deliverViaHost calls `deliver` instead of the pty paste.
    */
-  deliveryConfirm?: 'transcript' | 'socket-ack'
+  deliveryConfirm?: 'transcript' | 'socket-ack' | 'structural'
 
   /**
    * If set, launch REFUSES unless the peer's intelligence is IN this set (fail-loud —
@@ -381,13 +386,13 @@ export interface RuntimeAdapter {
   /** Newest activity-proxy FILE mtime — used by the READY-GATE (it waits for ANY transcript write past
    *  baseline = "the model produced its first turn"). NOT for idle accounting: a live session re-saves
    *  this file without a new entry, so it is falsely fresh at idle. null for a router (no proxy). */
-  newestActivityMtime(cwd: string): number | null
+  newestActivityMtime(cwd: string, ctx?: ObserveContext): number | null
 
   /** Content-timestamp (epoch ms) of the LAST meaningful transcript ENTRY — the reliable IDLE-accounting
    *  signal. Unlike newestActivityMtime (file mtime, re-touched at idle) and the pane-log mtime (a
    *  statusline re-render ticks it at idle), the entry stream only advances on real turn activity.
    *  superviseTick uses THIS for idle/quiet age. null for a router (no transcript). */
-  lastTurnMtime(cwd: string): number | null
+  lastTurnMtime(cwd: string, ctx?: ObserveContext): number | null
 
   /** В58 — newest FILE mtime among the session's CHILD workflow/subagent transcripts (a running workflow
    *  writes them continuously). A peer that launched a long workflow (>1h) makes NO turns of its own, so
@@ -398,7 +403,7 @@ export interface RuntimeAdapter {
 
   /** Resume preflight — validate a resume request fail-loud (never silent fresh).
    *  Returns the resolved ref (claude uuid) or ok:false with a reason. */
-  resolveResume(cwd: string): { ok: boolean; ref?: string; reason?: string }
+  resolveResume(cwd: string, ctx?: ObserveContext): { ok: boolean; ref?: string; reason?: string }
 
   /**
    * Map an abstract in-session control command to this runtime's mechanism (a tmux
@@ -411,6 +416,39 @@ export interface RuntimeAdapter {
    * interrupt / drive a possibly-stuck session, exactly when normal delivery wouldn't.
    */
   executeControl(command: ControlCommand): ControlPlan | null
+
+  // ── Structural runtime hooks (docs/20 — OpenCode). All optional; a pty-glyph runtime (claude/codex)
+  // omits every one and launch/transport stay byte-identical for it. ─────────────────────────────────
+
+  /** Pre-spawn preparation (writes runtime-owned launch artifacts, e.g. the core plugin) → extra child
+   *  env merged into the composed invocation BEFORE the identity ABI. `baseEnv` is the composed child env
+   *  (base + launch.env) so an operator inline config is merged, not discarded. `readyToken` identifies
+   *  THIS process launch for structuralReady (e.g. a launchID). Throws → launch FAILS loud. */
+  prepareLaunch?(spec: LaunchSpec, baseEnv: NodeJS.ProcessEnv, cfg: LaunchAdapterConfig & { env?: NodeJS.ProcessEnv }): PreparedLaunch
+
+  /** Structural readiness replacing the pane-glyph gate: resolves when the runtime itself reported
+   *  readiness for `readyToken` (fail on deadline / reported error / `alive()` false). */
+  structuralReady?(spec: LaunchSpec, readyToken: string, deadlineMs: number, alive: () => boolean, env: NodeJS.ProcessEnv): Promise<{ ok: boolean; reason?: string }>
+
+  /** Structural delivery (deliveryConfirm 'structural'): resolves ok only when THIS message is accepted
+   *  and persisted by the runtime. */
+  deliver?(target: { personality: string; identity: string }, text: string, env: NodeJS.ProcessEnv): Promise<{ ok: boolean; error?: string; messageID?: string }>
+
+  /** Structural in-session control (interrupt, …). A runtime that declares it is controlled through
+   *  THIS, not executeControl's pty key plan. Unsupported command → ok:false with an explicit reason. */
+  control?(target: { personality: string; identity: string }, command: ControlCommand, env: NodeJS.ProcessEnv): Promise<{ ok: boolean; error?: string }>
+}
+
+/** Optional per-peer observation context for adapters whose state is personality-scoped (opencode keeps
+ *  it under <root>/state/opencode/<p>, not per-cwd). cwd-keyed runtimes ignore it. */
+export interface ObserveContext {
+  personality: string
+  env?: NodeJS.ProcessEnv
+}
+
+export interface PreparedLaunch {
+  env: Record<string, string>
+  readyToken?: string
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/lifecycle/index.ts

@@ -60,6 +60,8 @@ import { appendLifecycleEvent, superviseLogVerbose } from './eventlog.ts'
 export interface LifecycleConfig {
   claudeBin: string
   codexBin: string
+  /** OpenCode native binary (docs/20). Optional so hand-built test configs stay valid. */
+  opencodeBin?: string
   sockDir: string
   stateDir: string // ~/.iapeer/state/lifecycle
   logDir: string // ~/.iapeer/logs/lifecycle
@@ -109,6 +111,8 @@ export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): Lifec
   return {
     claudeBin: env.IAPEER_CLAUDE_BIN ?? join(home, '.local', 'bin', 'claude'),
     codexBin: env.IAPEER_CODEX_BIN ?? 'codex',
+    // The official installer's location is not on launchd's PATH; prefer it over a bare name.
+    opencodeBin: env.IAPEER_OPENCODE_BIN ?? (existsSync(join(home, '.opencode', 'bin', 'opencode')) ? join(home, '.opencode', 'bin', 'opencode') : 'opencode'),
     sockDir: resolveSockDir(env),
     stateDir: join(root, STATE_DIR, 'lifecycle'),
     logDir: join(root, LOGS_DIR, 'lifecycle'),
@@ -1103,7 +1107,7 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     // by the death cause (.idle-reaped marker) + peer-type/topic. An EXPLICIT resume
     // that finds nothing to resume fails loud. incomingTopic (args.topic) is the
     // executor discriminator.
-    const mode = resolveWakeMode(cfg, identity, cwd, args.resume, c => adapter.resolveResume(c), args.topic)
+    const mode = resolveWakeMode(cfg, identity, cwd, args.resume, c => adapter.resolveResume(c, { personality: args.personality, env }), args.topic)
     // The bring-up decision is the durable trace — log it BEFORE launch (the decision
     // stands regardless of whether the subsequent launch succeeds). resolveWakeMode has
     // already consumed any .idle-reaped marker, so `cause` is now its only record.
@@ -1158,6 +1162,7 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     const launchCfg: LaunchConfig = {
       claudeBin: cfg.claudeBin,
       codexBin: cfg.codexBin,
+      ...(cfg.opencodeBin ? { opencodeBin: cfg.opencodeBin } : {}),
       sockDir: cfg.sockDir,
       bootDeadlineSecs: cfg.bootDeadlineSecs,
       readyGateSecs: cfg.readyGateSecs,
@@ -1295,7 +1300,7 @@ export interface SuperviseDeps {
    *  transcript entry). This is the RELIABLE idle signal — NOT the transcript FILE mtime (re-saved at
    *  idle) and NOT the pane-log mtime (a statusline re-render ticks it at idle); both falsely keep an
    *  idle session young. Tests inject a controlled value to exercise the idle/quiet age hermetically. */
-  lastTurnMtime?: (runtime: string, cwd: string) => number | null
+  lastTurnMtime?: (runtime: string, cwd: string, personality?: string) => number | null
   /** В58 — child workflow/subagent activity seam (default: the adapter's childActivityMtime). Folded into
    *  the idle proxy so a peer driving a long workflow (no turns of its own) is not reaped mid-work. */
   childActivityMtime?: (runtime: string, cwd: string) => number | null
@@ -1312,7 +1317,7 @@ interface SuperviseCtx {
   cfg: LifecycleConfig
   env: NodeJS.ProcessEnv
   nowMs: number
-  lastTurnMt: (runtime: string, cwd: string) => number | null
+  lastTurnMt: (runtime: string, cwd: string, personality?: string) => number | null
   childActivityMt: (runtime: string, cwd: string) => number | null
   isAlive: (sock: string, identity: string) => boolean
   kill: (sock: string, identity: string) => void
@@ -1425,7 +1430,7 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
   // governs (an old wokeAt = woken-long-ago = idle → reaped; a recent wokeAt = just-woken → protected).
   const ephemeral = isEphemeralPeer(s.cwd)
   let lt = 0
-  try { lt = lastTurnMt(s.runtime, s.cwd) ?? 0 } catch { /* unreadable → wokeAt floor */ }
+  try { lt = lastTurnMt(s.runtime, s.cwd, s.personality) ?? 0 } catch { /* unreadable → wokeAt floor */ }
   // В58 — fold in CHILD workflow/subagent activity. A peer driving a long (>1h) workflow makes NO turns
   // of its own, so lt is stale; without this the busy-with-workflow session is idle-reaped mid-work (live
   // incident: iapeer-memory cut mid-audit). A running workflow writes its subagent transcripts
@@ -1507,7 +1512,9 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
 export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): SuperviseOutcome[] {
   const env = deps.env ?? process.env
   const nowMs = deps.nowMs ?? Date.now()
-  const lastTurnMt = deps.lastTurnMtime ?? ((rt: string, c: string) => getAdapter(rt as Runtime).lastTurnMtime(c))
+  const lastTurnMt =
+    deps.lastTurnMtime ??
+    ((rt: string, c: string, p?: string) => getAdapter(rt as Runtime).lastTurnMtime(c, p ? { personality: p, env } : undefined))
   const childActivityMt =
     deps.childActivityMtime ?? ((rt: string, c: string) => getAdapter(rt as Runtime).childActivityMtime?.(c) ?? null)
   // Default seams bind the injected env so a sandboxed tick never reads/kills the real fleet.
@@ -1799,7 +1806,7 @@ export function lastActiveRuntime(peer: PeerRecord, cfg: LifecycleConfig): Runti
   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 })
       if (mt !== null && mt > bestMt) {
         bestMt = mt
         best = rt

package/src/opencode/config.ts

@@ -0,0 +1,121 @@
+// 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 { opencodePrivateDir, writeFileAtomic, type StorageOptions } from '../storage/index.ts'
+import pluginSource from './iapeer-plugin.mjs' with { type: 'text' }
+import { listCapabilities } from '../capability/index.ts'
+
+export const OPENCODE_AGENT = 'iapeer'
+/** The memory provider's private fragment stem (docs/20 §Memory-provider ABI). */
+export const OPENCODE_MEMORY_FRAGMENT = 'iapeer-memory'
+type JsonObject = Record<string, unknown>
+
+export function opencodePaths(personality: string, options: StorageOptions = {}) {
+  if (!isValidName(personality)) throw new Error(`invalid OpenCode personality: ${personality}`)
+  const dir = opencodePrivateDir(personality, options)
+  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
+  /** docs/17. gated → the iapeer agent ASKS before exec/mutation/web (bash, edit, webfetch), and the
+   *  plugin bridges each native ask to the human broker. yolo (default) adds nothing (`--auto`). */
+  approvalMode?: 'yolo' | 'gated'
+}
+
+/** Gated ask rules — the claude/codex «ask before acting» set mapped onto OpenCode permissions.
+ *  Agent-level, so an operator's top-level `permission: {"*":"allow"}` cannot silently undo it. Reads,
+ *  search and the core MCP stay allowed (as on gated claude). */
+export const OPENCODE_GATED_PERMISSION = { bash: 'ask', edit: 'ask', webfetch: 'ask', external_directory: 'ask', doom_loop: 'ask' } as const
+
+/** 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'))
+  // Fragment owners: the memory provider + every REGISTERED capability (docs/21) — never a
+  // hardcoded plugin list. An unregistered plugin's leftover fragment is not merged.
+  const stems = [OPENCODE_MEMORY_FRAGMENT, ...listCapabilities(options).declarations.map(d => d.capability)]
+  for (const stem of stems) {
+    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,
+        ...(input.approvalMode === 'gated' ? { permission: { ...OPENCODE_GATED_PERMISSION } } : {}),
+      },
+    },
+    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,56 @@
+// 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' }
+  | { op: 'compact' }
+
+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` }))
+  })
+}