@agfpd/iapeer 0.4.114 → 0.4.116

package/src/capability/index.ts

@@ -0,0 +1,160 @@
+// Capability-plugin lifecycle (docs/21-capabilities.md).
+//
+// A capability plugin (statusline-injector, totp-presence, …) puts per-peer
+// surfaces into a peer's runtime: hooks, a private config fragment, an MCP entry.
+// Like the memory slot (ADR-009 inversion), the CORE owns WHEN and FOR WHOM —
+// every agent endpoint of every peer, at birth, at a new runtime, at removal, and
+// on registration — and the PLUGIN owns WHAT: it declares two commands and the
+// core shells into them. The core knows nothing about surface forms.
+//
+// Declaration: <IAPEER_ROOT>/capabilities/<name>.json, written ONLY through
+// `iapeer capability register` (validated), removed through `unregister`.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs'
+import { isAbsolute, join } from 'node:path'
+import { isSupportedLocalRuntime, isValidName } from '../core/constants.ts'
+import { resolveGlobalRoot, writeFileAtomic, type StorageOptions } from '../storage/index.ts'
+import { runProvisionCommand, type ProvisionCommandOutcome, type ProvisionOccasion } from '../enable/provisionCommand.ts'
+
+export const CAPABILITY_SCHEMA = 1
+
+export interface CapabilityCommand {
+  /** Absolute path to the plugin's executable (launchd's minimal PATH resolves nothing). */
+  command: string
+  /** Argv tail; {cwd} {runtime} {personality} {occasion} are substituted per argument, no shell. */
+  args: string[]
+}
+
+export interface CapabilityDeclaration {
+  schema: 1
+  /** The capability name = the declaration file stem. */
+  capability: string
+  package?: string
+  version?: string
+  /** Agent runtimes the plugin provisions for. Endpoints of other runtimes are skipped. */
+  runtimes: string[]
+  provision: CapabilityCommand
+  unprovision: CapabilityCommand
+}
+
+export function capabilitiesDir(options: StorageOptions = {}): string {
+  return join(options.rootDir ?? resolveGlobalRoot(options.env), 'capabilities')
+}
+
+function command(value: unknown, where: string): CapabilityCommand {
+  const v = value as Partial<CapabilityCommand> | null
+  if (!v || typeof v !== 'object') throw new Error(`${where}: expected {command, args}`)
+  if (typeof v.command !== 'string' || !isAbsolute(v.command)) throw new Error(`${where}.command must be an absolute path`)
+  if (!Array.isArray(v.args) || v.args.some(a => typeof a !== 'string')) throw new Error(`${where}.args must be an array of strings`)
+  if (!v.args.some(a => a.includes('{personality}'))) {
+    // Several personalities can share one cwd: a command that cannot tell them apart
+    // would provision or tear down the wrong peer's surfaces.
+    throw new Error(`${where}.args must carry {personality}`)
+  }
+  return { command: v.command, args: [...v.args] }
+}
+
+/** Validate an untrusted declaration. Throws with the first violation. */
+export function parseCapabilityDeclaration(raw: unknown): CapabilityDeclaration {
+  const d = raw as Record<string, unknown> | null
+  if (!d || typeof d !== 'object' || Array.isArray(d)) throw new Error('declaration must be a JSON object')
+  if (d.schema !== CAPABILITY_SCHEMA) throw new Error(`unsupported schema ${JSON.stringify(d.schema)} (expected ${CAPABILITY_SCHEMA})`)
+  if (!isValidName(d.capability)) throw new Error(`invalid capability name ${JSON.stringify(d.capability)}`)
+  if (!Array.isArray(d.runtimes) || d.runtimes.length === 0 || d.runtimes.some(r => typeof r !== 'string')) {
+    throw new Error('runtimes must be a non-empty array of runtime names')
+  }
+  for (const k of ['package', 'version'] as const) {
+    if (d[k] !== undefined && typeof d[k] !== 'string') throw new Error(`${k} must be a string`)
+  }
+  return {
+    schema: CAPABILITY_SCHEMA,
+    capability: d.capability as string,
+    ...(d.package ? { package: d.package as string } : {}),
+    ...(d.version ? { version: d.version as string } : {}),
+    runtimes: [...new Set(d.runtimes as string[])],
+    provision: command(d.provision, 'provision'),
+    unprovision: command(d.unprovision, 'unprovision'),
+  }
+}
+
+export interface CapabilityListing {
+  declarations: CapabilityDeclaration[]
+  /** Files that exist but do not validate — reported, never silently skipped. */
+  invalid: { file: string; error: string }[]
+}
+
+export function listCapabilities(options: StorageOptions = {}): CapabilityListing {
+  const dir = capabilitiesDir(options)
+  const out: CapabilityListing = { declarations: [], invalid: [] }
+  if (!existsSync(dir)) return out
+  for (const f of readdirSync(dir).filter(f => f.endsWith('.json')).sort()) {
+    try {
+      const decl = parseCapabilityDeclaration(JSON.parse(readFileSync(join(dir, f), 'utf8')))
+      if (`${decl.capability}.json` !== f) throw new Error(`file name must be ${decl.capability}.json`)
+      out.declarations.push(decl)
+    } catch (e) {
+      out.invalid.push({ file: join(dir, f), error: e instanceof Error ? e.message : String(e) })
+    }
+  }
+  return out
+}
+
+export function writeCapabilityDeclaration(decl: CapabilityDeclaration, options: StorageOptions = {}): string {
+  const dir = capabilitiesDir(options)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const path = join(dir, `${decl.capability}.json`)
+  writeFileAtomic(path, JSON.stringify(decl, null, 2) + '\n', 0o600)
+  return path
+}
+
+export function removeCapabilityDeclaration(name: string, options: StorageOptions = {}): boolean {
+  if (!isValidName(name)) throw new Error(`invalid capability name ${JSON.stringify(name)}`)
+  const path = join(capabilitiesDir(options), `${name}.json`)
+  if (!existsSync(path)) return false
+  rmSync(path)
+  return true
+}
+
+/** The (runtime) endpoints of a peer a capability applies to: declared by the peer,
+ *  hostable as an agent by this core, and listed by the capability. */
+export function capabilityEndpoints(decl: CapabilityDeclaration, peerRuntimes: readonly string[]): string[] {
+  return peerRuntimes.filter(r => isSupportedLocalRuntime(r) && decl.runtimes.includes(r))
+}
+
+export interface CapabilityRun {
+  capability: string
+  runtime: string
+  outcome: ProvisionCommandOutcome
+}
+
+/**
+ * Run one lifecycle command of every applicable capability for ONE peer. Never
+ * throws; callers decide how loud a failure is (birth/remove: warn and continue).
+ * `only` narrows to one capability (register/unregister sweeps).
+ */
+export function runCapabilityLifecycle(args: {
+  kind: 'provision' | 'unprovision'
+  personality: string
+  cwd: string
+  runtimes: readonly string[]
+  occasion: ProvisionOccasion
+  env?: NodeJS.ProcessEnv
+  only?: CapabilityDeclaration
+  rootDir?: string
+}): CapabilityRun[] {
+  const decls = args.only ? [args.only] : listCapabilities({ env: args.env, rootDir: args.rootDir }).declarations
+  const runs: CapabilityRun[] = []
+  for (const decl of decls) {
+    for (const runtime of capabilityEndpoints(decl, args.runtimes)) {
+      const outcome = runProvisionCommand({
+        block: args.kind === 'provision' ? decl.provision : decl.unprovision,
+        cwd: args.cwd,
+        runtime,
+        personality: args.personality,
+        occasion: args.occasion,
+        env: args.env,
+      })
+      runs.push({ capability: decl.capability, runtime, outcome })
+    }
+  }
+  return runs
+}

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

@@ -35,7 +35,9 @@
 
 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,
@@ -79,6 +81,14 @@ export const FLEET_API_VERSION = 1
 export interface FleetRuntimeStatus {
   runtime: string
   status: 'live' | 'asleep' | 'stopped'
+  /** AGENT-ENDPOINT discovery (docs/15 §Agent endpoints): true iff this declared runtime is an
+   *  agent runtime THIS core can host (`host.agent_runtimes`). A channel offers exactly the
+   *  `agent:true` runtimes of a personality — never a consumer-side hardcode or `Bun.which`.
+   *  A declared runtime the running core cannot host (newer peer, older core) is `false`. */
+  agent: boolean
+  /** 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
@@ -125,6 +135,8 @@ export interface FleetHost {
   memory: { provider: string; version: string; heartbeatAgeSecs: number | null } | null
   voice: { provider: string; version: string; heartbeatAgeSecs: number | null } | null
   fda: boolean | null
+  /** The agent runtimes this core build can host (its agent adapters), in preference order. */
+  agent_runtimes: string[]
 }
 
 /** A pending human-approval request as the snapshot exposes it (docs/17). The SAME items
@@ -228,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 =
@@ -238,6 +254,8 @@ export function buildFleetSnapshot(
       return {
         runtime: s.runtime,
         status: s.status,
+        agent: isSupportedLocalRuntime(s.runtime),
+        ...(privateDirOf(s.runtime, r.personality)),
         ...(attached ? { attached: true } : {}),
         ...(activity ? { activity } : {}),
       }
@@ -289,6 +307,7 @@ export function buildFleetSnapshot(
         ? { provider: voice.provider, version: voice.version, heartbeatAgeSecs: heartbeatAgeSecs(voice, nowMs) }
         : null,
       fda: probeFullDiskAccess(env),
+      agent_runtimes: [...SUPPORTED_LOCAL_RUNTIMES],
     },
     peers,
     // ADDITIVE + omitted when empty (absence ⇒ empty queue, docs/15). broker.list() is a

package/src/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,