@agfpd/iapeer 0.4.115 → 0.4.117

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

@@ -4,16 +4,18 @@ 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 { 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'
-export const OPENCODE_EXTENSION_FRAGMENTS = ['iapeer-memory', 'statusline-injector'] as const
+/** 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 = join(options.rootDir ?? resolveGlobalRoot(options.env), 'peers', personality, 'opencode')
+  const dir = opencodePrivateDir(personality, options)
   return {
     dir,
     plugin: join(dir, 'iapeer-plugin.mjs'),
@@ -65,15 +67,26 @@ export interface ComposeOpencodeConfigInput {
   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'))
-  for (const stem of OPENCODE_EXTENSION_FRAGMENTS) {
+  // 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))
   }
@@ -83,7 +96,13 @@ export function composeOpencodeConfig(input: ComposeOpencodeConfigInput, options
     autoupdate: false,
     share: 'disabled',
     default_agent: OPENCODE_AGENT,
-    agent: { [OPENCODE_AGENT]: { mode: 'primary', prompt: input.doctrine } },
+    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],
   })

package/src/opencode/control.ts

@@ -8,6 +8,7 @@ export type OpencodeControlRequest =
   | { op: 'deliver'; text: string }
   | { op: 'interrupt' }
   | { op: 'select' }
+  | { op: 'compact' }
 
 export interface OpencodeControlResponse {
   ok: boolean

package/src/opencode/deps.ts

@@ -0,0 +1,110 @@
+// Keep npm OFF the OpenCode wake path (docs/20 §Native findings). Before loading any external
+// plugin, native OpenCode (1.19.3 core/src/npm.ts Npm.install) reifies `@opencode-ai/plugin` in
+// EVERY config directory it scans, unless that directory already has `node_modules` AND the name
+// is in the root of its `package-lock.json` (the version is not re-checked once locked). A cold
+// directory therefore costs one npm https round-trip at startup — observed 60 s and >4 min stalls.
+// The core satisfies that exact no-op condition at runtime-attach time (an operator verb), so a
+// wake never waits on the network.
+//
+// Directories (native ConfigPaths.directories): the global config dir ($OPENCODE_CONFIG_DIR, else
+// $XDG_CONFIG_HOME/opencode, else ~/.config/opencode), every existing `.opencode` from the peer cwd
+// upwards, and ~/.opencode (where the official installer puts the binary). Non-writable dirs are
+// skipped natively and here.
+import { execFileSync } from 'node:child_process'
+import { accessSync, constants, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+export const OPENCODE_PLUGIN_PACKAGE = '@opencode-ai/plugin'
+
+export function opencodeConfigDirs(cwd: string, env: NodeJS.ProcessEnv = process.env): string[] {
+  const home = env.HOME?.trim() || homedir()
+  const globalDir = env.OPENCODE_CONFIG_DIR?.trim() || join(env.XDG_CONFIG_HOME?.trim() || join(home, '.config'), 'opencode')
+  const dirs = [globalDir]
+  let dir = resolve(cwd)
+  while (true) {
+    const candidate = join(dir, '.opencode')
+    if (existsSync(candidate)) dirs.push(candidate)
+    const parent = dirname(dir)
+    if (parent === dir || dir === home) break
+    dir = parent
+  }
+  const homeDir = join(home, '.opencode')
+  if (existsSync(homeDir)) dirs.push(homeDir)
+  return [...new Set(dirs)]
+}
+
+/** The exact native no-op condition for one directory. */
+export function pluginDependencySatisfied(dir: string): boolean {
+  if (!existsSync(join(dir, 'node_modules'))) return false
+  try {
+    const lock = JSON.parse(readFileSync(join(dir, 'package-lock.json'), 'utf8')) as { packages?: Record<string, Record<string, Record<string, string>>> }
+    const root = lock.packages?.[''] ?? {}
+    return [root.dependencies, root.devDependencies, root.peerDependencies, root.optionalDependencies].some(d => d && OPENCODE_PLUGIN_PACKAGE in d)
+  } catch {
+    return false
+  }
+}
+
+function writable(dir: string): boolean {
+  try {
+    accessSync(dir, constants.W_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export interface DependencyOutcome {
+  dir: string
+  state: 'present' | 'installed' | 'skipped-readonly' | 'failed'
+  detail?: string
+}
+
+export interface EnsureDepsDeps {
+  /** Native binary version (the plugin package is pinned to it, as native does). */
+  version: () => string
+  /** Run `npm install` in `dir` (throws on failure). */
+  npmInstall: (dir: string, spec: string) => void
+}
+
+export function defaultEnsureDepsDeps(bin: string, env: NodeJS.ProcessEnv): EnsureDepsDeps {
+  return {
+    version: () => execFileSync(bin, ['--version'], { encoding: 'utf8', timeout: 20000, env }).trim(),
+    npmInstall: (dir, spec) =>
+      void execFileSync('npm', ['install', '--no-audit', '--no-fund', '--save', spec], { cwd: dir, env, stdio: 'pipe', timeout: 300000 }),
+  }
+}
+
+/** Satisfy the native no-op condition in every config dir. Never throws; the caller decides. */
+export function ensureOpencodePluginDependency(cwd: string, env: NodeJS.ProcessEnv, deps: EnsureDepsDeps): DependencyOutcome[] {
+  // Fail-closed sandbox guard (the IAPEER_TEST_SANDBOX contract): these dirs resolve from HOME, which
+  // the IAPEER_ROOT isolation does not cover — a test that forgot to isolate HOME would write into the
+  // operator's real OpenCode config (it happened once, 17.10).
+  if ((env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') && resolve(env.HOME?.trim() || homedir()) === resolve(homedir())) {
+    throw new Error('IAPEER_TEST_SANDBOX: refusing to preinstall into the real HOME — inject an isolated HOME')
+  }
+  const dirs = opencodeConfigDirs(cwd, env)
+  mkdirSync(dirs[0]!, { recursive: true }) // the global config dir always exists natively
+  let version: string | undefined
+  const out: DependencyOutcome[] = []
+  for (const dir of dirs) {
+    if (pluginDependencySatisfied(dir)) {
+      out.push({ dir, state: 'present' })
+      continue
+    }
+    if (!writable(dir)) {
+      out.push({ dir, state: 'skipped-readonly' })
+      continue
+    }
+    try {
+      version ??= deps.version()
+      if (!/^\d+\.\d+\.\d+/.test(version)) throw new Error(`unexpected opencode --version output: ${JSON.stringify(version)}`)
+      deps.npmInstall(dir, `${OPENCODE_PLUGIN_PACKAGE}@${version}`)
+      out.push(pluginDependencySatisfied(dir) ? { dir, state: 'installed' } : { dir, state: 'failed', detail: 'npm finished but the lock does not record the package' })
+    } catch (e) {
+      out.push({ dir, state: 'failed', detail: e instanceof Error ? e.message.split('\n')[0] : String(e) })
+    }
+  }
+  return out
+}

package/src/opencode/iapeer-plugin.mjs

@@ -145,6 +145,15 @@ async function server(input) {
     await client.tui.publish({ body: { type: 'tui.session.select', properties: { sessionID: state.sessionID } } }).catch(() => {})
   }
 
+  // Model of the last assistant turn — compaction runs on it. Seeded from history on resume.
+  let lastModel = null
+  let compactedAfter = 0
+  function noteModel(info) {
+    if (info && info.role === 'assistant' && typeof info.providerID === 'string' && typeof info.modelID === 'string') {
+      lastModel = { providerID: info.providerID, modelID: info.modelID }
+    }
+  }
+
   // ── message acknowledgements: resolved by the native persist event ──────────
   const waiters = new Map()
   function awaitPersisted(messageID) {
@@ -187,6 +196,19 @@ async function server(input) {
         const res = await client.session.abort({ path: { id: state.sessionID } })
         return res.error ? { ok: false, error: JSON.stringify(res.error) } : { ok: true }
       }
+      case 'compact': {
+        // Native compaction (POST /session/:id/summarize) runs the summary turn to completion before
+        // it returns; the ack additionally requires the native `session.compacted` record for THIS
+        // session after the request (a silent no-op is never reported as success).
+        if (!state.sessionID) return { ok: false, error: 'no session' }
+        if (!lastModel) return { ok: false, error: 'nothing to compact (no assistant turn in this session yet)' }
+        const before = seq
+        const res = await client.session.summarize({ path: { id: state.sessionID }, body: { providerID: lastModel.providerID, modelID: lastModel.modelID } })
+        if (res.error) return { ok: false, error: 'summarize: ' + JSON.stringify(res.error) }
+        for (let i = 0; i < 50 && compactedAfter <= before; i++) await new Promise(r => setTimeout(r, 100))
+        if (compactedAfter <= before) return { ok: false, error: 'summarize returned but no session.compacted was recorded' }
+        return { ok: true, sessionID: state.sessionID, lastEventSeq: compactedAfter }
+      }
       case 'select':
         await selectInTui()
         return { ok: true, sessionID: state.sessionID }
@@ -195,6 +217,54 @@ async function server(input) {
     }
   }
 
+  // ── human approval (gated, docs/17 + docs/20 OC10) ───────────────────────────
+  // Native 1.19.3 never calls the `permission.ask` plugin hook, so the bridge rides the
+  // `permission.asked` event: a blocking broker request per native permission, answered back
+  // through the native reply route. Every failure direction is reject (fail-safe). A human who
+  // answers the native TUI prompt first wins: `permission.replied` aborts the broker request,
+  // the daemon sees the transport close and clears the card from every face.
+  const gated = env.IAPEER_APPROVAL_MODE === 'gated'
+  const fleetUrl = env.IAPEER_FLEET_URL
+  const approvals = new Map()
+  const clip = (s, n) => (s.length > n ? s.slice(0, n) + '…' : s)
+  function approvalCard(p) {
+    const patterns = Array.isArray(p.patterns) ? p.patterns.map(String) : []
+    const meta = p.metadata && typeof p.metadata === 'object' ? p.metadata : {}
+    const head = patterns.join('\n') || String(p.permission)
+    const extra = Object.keys(meta).length ? '\n\n' + clip(JSON.stringify(meta, null, 2), 6000) : ''
+    return { tool: String(p.permission), content: clip(head, 2000) + extra, summary: clip(`${p.permission}: ${patterns.join(' ') || '?'}`, 200) }
+  }
+  async function replyNative(p, response) {
+    await client
+      .postSessionIdPermissionsPermissionId({ path: { id: p.sessionID, permissionID: p.id }, body: { response } })
+      .catch(() => {}) // already answered (human in the TUI) → native NotFound; nothing to do
+  }
+  async function brokerApproval(p) {
+    const controller = new AbortController()
+    approvals.set(p.id, controller)
+    let response = 'reject'
+    try {
+      if (!fleetUrl) throw new Error('no IAPEER_FLEET_URL')
+      const headers = { 'content-type': 'application/json' }
+      if (env.IAPEER_BEARER_TOKEN) headers.authorization = 'Bearer ' + env.IAPEER_BEARER_TOKEN
+      const card = approvalCard(p)
+      const res = await fetch(fleetUrl + '/fleet/v1/approvals', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ personality: env.PEER_PERSONALITY, runtime: 'opencode', kind: 'tool', ...card }),
+        signal: controller.signal,
+      })
+      if (!res.ok) throw new Error('broker ' + res.status)
+      const d = await res.json()
+      if (d && d.decision === 'allow') response = 'once'
+    } catch (e) {
+      if (controller.signal.aborted) return // the human answered natively; never double-reply
+    } finally {
+      approvals.delete(p.id)
+    }
+    await replyNative(p, response)
+  }
+
   // ── control socket ──────────────────────────────────────────────────────────
   rmSync(paths.socket, { force: true })
   const control = createServer(conn => {
@@ -235,6 +305,10 @@ async function server(input) {
       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 (resumed) {
+        const hist = await client.session.messages({ path: { id: sessionID } }).catch(() => null)
+        for (const m of (hist && hist.data) || []) noteModel(m && m.info)
+      }
       if (state.status === 'starting') state.status = 'idle'
       journal('runtime.ready', { session: got.data, resumed }, null, sessionID)
     } catch (e) {
@@ -255,6 +329,9 @@ async function server(input) {
       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 (type === 'message.updated' && p && sessionID === state.sessionID) noteModel(p.info)
+      if (gated && type === 'permission.asked' && p && typeof p.id === 'string' && !approvals.has(p.id)) void brokerApproval(p)
+      if (type === 'permission.replied' && p && approvals.has(p.requestID)) approvals.get(p.requestID).abort()
       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
@@ -268,9 +345,11 @@ async function server(input) {
         }
       }
       journal(type, p, event.id ?? null, sessionID)
+      if (type === 'session.compacted' && sessionID === state.sessionID) compactedAfter = seq
       writeState()
     },
     dispose: async () => {
+      for (const c of approvals.values()) c.abort()
       state.status = 'stopped'
       journal('runtime.stopped', { reason: 'dispose' }, null, state.sessionID)
       writeState()