@agfpd/iapeer 0.4.115 → 0.4.116

package/docs/15-fleet-api.md

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

package/docs/20-opencode.md

@@ -37,7 +37,15 @@ as a silent no-op.
 - Existing slot `provision-peer --personality <p> --runtime opencode --cwd <cwd>`.
 - Canonical child ABI: `PEER_PERSONALITY`, `PEER_RUNTIME=opencode`,
   `PEER_IDENTITY=opencode-<p>`; `IAPEER_IDENTITY` is an alias set by the core.
-- Private directory: `<IAPEER_ROOT>/peers/<p>/opencode/` (default root `~/.iapeer`).
+- Private directory: `<IAPEER_ROOT>/state/opencode/<p>/` (default root `~/.iapeer`).
+  It lives under the core's `state/`, never in the agent's working tree (the default
+  peer cwd is `<root>/peers/<p>`). Moved there from `<root>/peers/<p>/opencode/` on
+  2026-10-17, before any release (no producer ever wrote the old path; it is not
+  read or migrated).
+  Every consumer gets it from the core and never computes it: provider and
+  capability commands as `{privateDir}` / `IAPEER_PRIVATE_DIR` (docs/21); observers
+  the core does not launch (console, collectors, sweeps) from the fleet snapshot
+  `runtimes[].private_dir` (docs/15) or `iapeer private-dir <p> [--runtime opencode]`.
   Memory owns `iapeer-memory.json` and `iapeer-memory-plugin.mjs` there. The core
   reads the JSON fragment on each launch and merges its `mcp` and `plugin` fields
   into runtime overrides. Missing means no memory surfaces; malformed/present
@@ -58,7 +66,7 @@ a synthetic fixture as proof of the producer; the core ships a native source har
 The core is the **single producer**. Consumers read only these files, never the
 native OpenCode SQLite DB or a second SDK client:
 
-- `<IAPEER_ROOT>/peers/<p>/opencode/events.jsonl` — append-only journal, one JSON
+- `<IAPEER_ROOT>/state/opencode/<p>/events.jsonl` — append-only journal, one JSON
   object per line:
   `{schema:1, seq, time:<epoch ms>, identity:"opencode-<p>", launchID,
   sessionID:<native ses_…|null>, type, properties, nativeID:<event.id|null>}`.
@@ -76,11 +84,15 @@ native OpenCode SQLite DB or a second SDK client:
     with a new `launchID`, including resume, so the main session is recoverable from
     the journal alone. A launch that fails before readiness writes `runtime.error`
     `{error}` under its `launchID` instead.
-  - Consumers: web-runtime, telegram-runtime, statusline-injector and iapeer-memory's
-    weekly collector (it relies on the path, `time`, unchanged `type`/`properties` and
-    no rotation). Changing any of these requires notifying all four.
+  - Consumers: web-runtime, telegram-runtime and iapeer-memory's weekly collector (it
+    relies on the path, `time`, unchanged `type`/`properties` and no rotation).
+    statusline-injector reads in-process (its own plugin hook, which also receives the
+    context window), so the journal is optional for it. Any ABI change is announced
+    to all four.
+  - Per-peer plugin fragments merged into the launch config are the memory provider's
+    plus those of every registered capability (docs/21). No plugin list is hardcoded.
   - Native bootstrap snapshots can repeat part ids, so consumers must **upsert parts by id**.
-- `<IAPEER_ROOT>/peers/<p>/opencode/state.json`, written atomically:
+- `<IAPEER_ROOT>/state/opencode/<p>/state.json`, written atomically:
   `{schema:1, identity, cwd, sessionID, launchID, startedAt, lastEventSeq,
   lastActivityMs, status:"starting|idle|busy|approval|error|stopped", error?}`.
   - `lastEventSeq` is a fence: every journal line with `seq ≤ lastEventSeq` is
@@ -217,6 +229,91 @@ Native findings that bind the adapter:
   `dispose` does not run on a signal, so `runtime.stopped` for a signal death is the
   supervisor's job.
 
+## Adapter under the pty supervisor — 2026-10-17
+
+`src/launch/adapters/opencode.ts` implements the structural adapter hooks
+(`RuntimeAdapter.prepareLaunch / structuralReady / deliver / control`,
+`deliveryConfirm: 'structural'`). Nothing reads the screen:
+- `prepareLaunch` writes the plugin, re-composes `OPENCODE_CONFIG_CONTENT` from
+  the freshly composed doctrine on every launch (resume included) and sets the
+  plugin env with a new `launchID`;
+- readiness is the `runtime.ready` line of **that** `launchID` written after the
+  prepare-time journal offset, plus a control ping answering the same `launchID`;
+- the first and every warm message go through `deliver`, whose ack means the
+  message is persisted natively; there is no composer hold and no pty paste;
+- `interrupt` is native abort; other control commands fail loud;
+- resume reads `state.json` `sessionID`; idle accounting reads
+  `state.lastActivityMs` (busy/approval count as activity now);
+- the supervisor records `runtime.stopped` + `status:stopped` on child exit and on
+  teardown (idempotent with a graceful dispose). Teardown SIGKILLs the child.
+
+`scripts/opencode-supervised-harness.ts` drives the real `launch()` with the
+native TUI hosted by the supervisor (isolated HOME/root, synthetic provider).
+Run of 2026-10-17 on native 1.19.3: 16/16 — cold READY in 3.5 s with the
+first message delivered; doctrine and native `AGENTS.md` on the wire; transport
+warm delivery idle and busy (busy acked in 6 ms, processed after the slow turn);
+interrupt; unsupported control refused; the TUI renders the core session;
+teardown → `runtime.stopped`; contiguous `seq`; resume on the same session with
+`resumed=true`, the new doctrine replacing the old, history kept.
+
+`scripts/opencode-wake-harness.ts` goes through the fleet lifecycle with a
+registered peer (`initPeer --runtime opencode`). Run of 2026-10-17: 9/9 — cold
+wake by a message (READY in 2.6 s, task delivered as the first message); the
+composed doctrine (identity YAML + local `IAPEER.md`) is the system prompt; a
+wake on a live session is idempotent; the supervise tick idle-reaps from the
+plugin state; the next message on the same topic resumes the same native session
+with the re-composed doctrine and earlier history. A topicless message after an
+idle-reap wakes fresh — core executor policy, identical for every runtime.
+
+`initPeer --runtime opencode` (create/add-runtime) first satisfies the native
+plugin-dependency no-op in every OpenCode config dir (`src/opencode/deps.ts`:
+`node_modules` present and `@opencode-ai/plugin` in the lock root, pinned to
+`opencode --version`). A failure aborts before the runtime is registered. Real
+npm, isolated HOME: installed in 11 s, the repeat is `present` with no network.
+
+`scripts/opencode-mcp-harness.ts` runs a sandboxed daemon in-process with two
+registered opencode peers. Run of 2026-10-17: 10/10. The core MCP is imported
+(`iapeer_send_to_peer` offered next to native `bash`); the model's native `bash`
+call runs; its `send_to_peer` call reaches the daemon with OpenCode's identity
+header, wakes the receiver on miss and delivers through the structural path. The
+receiver sees `<iap from="ocsend" runtime="opencode" …>`, the tool result is
+`ok` with `delivered_to.runtime: opencode`, the sender's journal has completed
+tool parts, and `delivery.log` records the send.
+
+Gated approval (OC10). Native 1.19.3 declares but never calls the
+`permission.ask` plugin hook, so the bridge rides the `permission.asked` event.
+Under `approval_mode: gated` the launch omits `--auto`, sets agent-level ask
+rules (`bash`, `edit`, `webfetch`, `external_directory`, `doom_loop` — reads,
+search and the core MCP stay allowed, as on gated claude; agent-level so an
+operator `permission: {"*":"allow"}` cannot undo them), and the plugin POSTs
+each native ask to `/fleet/v1/approvals` (`runtime: opencode`, `tool` = native
+permission, summary = permission + patterns), then answers natively
+(`once`/`reject`). Every failure direction rejects. A human who answers the
+native TUI prompt first wins: `permission.replied` aborts the broker request and
+the card is withdrawn from every face. `approval-mode` reports a launch-time
+surface only (nothing persistent). `scripts/opencode-gated-harness.ts`, run of
+2026-10-17: 13/13 — allow runs the command, deny does not and the model sees the
+rejection, broker timeout default-denies and clears the card, a TUI answer
+withdraws the card with exactly one native reply, `approvals.log` audits each.
+
+Observation (not closed): on startup the native TUI may detect its install method
+by probing package managers (`npm/yarn/pnpm/bun list -g`, `brew list`) unless
+the binary lives in `~/.opencode/bin` or `~/.local/bin`. With a fresh HOME a
+`brew` probe auto-updates over the network. The adapter sets
+`OPENCODE_DISABLE_AUTOUPDATE=1`. **Install OpenCode only with the official
+installer** (binary in `~/.opencode/bin`): that location skips the probes.
+
+Still not proved here: a live daemon on the host,
+approval routing, memory slot, two simultaneous runtimes of one personality.
+Since the commit after this proof, `opencode` is a supported local agent runtime:
+listed in `host.agent_runtimes` (docs/15), accepted by `add-runtime`/`create
+--runtime opencode`, gated to artificial peers, refreshed by `refresh`, and
+included in the memory provider's provision/unprovision runs and in capability
+applicability (docs/21). `create` does NOT auto-add it as a secondary runtime
+(an endpoint without a provider/model configuration would be dead) — it is an
+explicit opt-in. The binary resolves from `IAPEER_OPENCODE_BIN`, else
+`~/.opencode/bin/opencode`, else `opencode` on PATH.
+
 ## Delivery gate
 
 Source changes and isolated native artifacts are allowed. npm publication and host

package/docs/21-capabilities.md

@@ -0,0 +1,83 @@
+# 21 — Capability-plugin lifecycle
+
+A **capability plugin** adds per-peer surfaces to a peer's agent runtime: hooks, a
+private config fragment, an MCP entry (examples: statusline-injector, totp-presence).
+Like the memory slot, the **core owns when and for whom** these surfaces are provisioned
+and the **plugin owns what** they are. The core shells into two declared commands and
+knows nothing about surface forms.
+
+## Declaration
+
+`<IAPEER_ROOT>/capabilities/<name>.json` (default root `~/.iapeer`). The plugin never
+writes this file directly. Its installer runs `iapeer capability register <file>`, which
+validates the declaration and stores it.
+
+```json
+{
+  "schema": 1,
+  "capability": "statusline-injector",
+  "package": "@agfpd/statusline-injector",
+  "version": "1.2.3",
+  "runtimes": ["claude", "codex", "opencode"],
+  "provision":   { "command": "/abs/path/bin", "args": ["provision-peer",   "--personality", "{personality}", "--runtime", "{runtime}", "--cwd", "{cwd}", "--occasion", "{occasion}"] },
+  "unprovision": { "command": "/abs/path/bin", "args": ["unprovision-peer", "--personality", "{personality}", "--runtime", "{runtime}", "--cwd", "{cwd}", "--occasion", "{occasion}"] }
+}
+```
+
+Validation rules. A violation refuses `register`; an invalid file found on disk is
+reported loudly and never skipped silently.
+- `schema` is `1`. `capability` is a valid name and equals the file stem.
+- `runtimes` is a non-empty list of the agent runtimes the plugin supports.
+- `command` is an **absolute** path, because launchd's minimal PATH resolves nothing.
+- `args` is an argv tail. `{personality}`, `{runtime}`, `{cwd}` and `{occasion}` are
+  substituted per argument, and **no shell** is involved.
+- `{privateDir}` is the core-owned private directory of the endpoint (OpenCode:
+  `<root>/state/opencode/<p>/`). It is also exported as `IAPEER_PRIVATE_DIR` to the
+  command for every runtime that has one. Plugins take the directory from the core
+  and never compute the layout themselves. `{privateDir}` on a runtime without one
+  is refused (`failed`) before spawn. A command that spans runtimes reads the env
+  variable instead.
+- Both commands must carry `{personality}`. Several personalities can share one cwd,
+  and a command that cannot tell them apart would touch another peer's surfaces.
+
+## Joints (core-owned)
+
+An **endpoint** is one `(peer, runtime)` pair where the runtime is:
+- declared by the peer;
+- hostable as an agent by this core (`host.agent_runtimes`, docs/15);
+- listed in the declaration's `runtimes`.
+
+Channel runtimes (telegram, web, …) are never endpoints.
+
+| Joint | Command | `{occasion}` |
+|---|---|---|
+| Peer birth: `create`, `init`, `add-runtime`, and `default-runtime` convergence onto an unwired runtime | provision for each endpoint | `birth` |
+| `iapeer capability register` / `sync <name>` (sync is the repair) | provision for every endpoint of every registered peer | `sweep-on` |
+| `iapeer remove <peer>` | unprovision for each endpoint, before state purge | `remove` |
+| `iapeer capability unregister <name>` | unprovision for every endpoint, then the declaration is deleted | `off-all` |
+
+Timeout per call: 120 s. Every call is logged to `lifecycle.log` as
+`ev=capability-provision capability=<name> identity=<runtime>-<peer> occasion=… state=…`.
+Failure handling:
+- At birth and remove, a failure is a loud warning and the flow continues. A plugin
+  hiccup never kills a birth or blocks a removal.
+- For the sweep verbs, failures are listed per endpoint and the exit code is 1.
+
+## Plugin obligations
+
+- **Idempotent** by construction. The core may repeat `birth`/`sweep-on` for an
+  already-provisioned endpoint, for example on add-runtime repair or `sync`.
+- Surfaces are scoped by **personality and runtime**, not by cwd alone. For opencode
+  they live in the peer's private directory `<root>/state/opencode/<p>/`, and the core
+  merges `<name>.json` fragments from there (docs/20).
+- Exit 0 only when the surfaces are in place. stderr is the failure detail the operator
+  sees.
+- On `remove` / `off-all`, remove only this plugin's surfaces for that endpoint.
+- Hold your own lock against concurrent invocations.
+
+## Install / uninstall of the plugin package
+
+- Install: install the package, then `iapeer capability register <decl.json>`. This
+  provisions every existing peer.
+- Update: re-register with the new version. Registration is idempotent and re-sweeps.
+- Uninstall: `iapeer capability unregister <name>`, then remove the package.

package/docs/README.md

@@ -81,6 +81,8 @@ The sections are layered: from "install and use" to "understand the architecture
 - [17 — Human approval](17-approval.md) — per-peer gated/yolo mode: routing a runtime's blocking approvals to a human through the daemon broker (hook interception, the broker, Fleet API + CLI)
 - [18 — Origin guard](18-origin-guard.md) — an agent's reply to a human must target the channel the human wrote from: the armed-pair model, the hold, `confirm-send`
 - [19 — Notices](19-notices.md) — telling the owner a peer went mute: detecting the structural API error that leaves a session alive, green and speechless, and routing it to the owner's surfaces one-way (not an approval)
+- [20 — OpenCode agent runtime](20-opencode.md) — acceptance contract, memory and observability ABI, core plugin, native harness
+- [21 — Capability-plugin lifecycle](21-capabilities.md) — declaration and core-owned provision/unprovision joints for per-peer plugin surfaces
 
 ## Status
 

package/package.json

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

package/src/approval/install.ts

@@ -203,6 +203,14 @@ export function setApprovalMode(cwd: string, mode: ApprovalMode, env: NodeJS.Pro
           ? `codex: native modal + supervisor proxy, no broker hook${removed ? ' (cleared prior hook)' : ''}`
           : `codex: ${removed ? 'hooks.json + trust removed' : 'trust cleared (no hooks.json)'}`,
       )
+    } else if (rt === 'opencode') {
+      // No persistent surface: argv (--auto), the agent's ask rules and the plugin's broker bridge are
+      // all composed at launch from this profile field (docs/20 OC10).
+      surfaces.push(
+        mode === 'gated'
+          ? 'opencode: launch-time ask rules + plugin broker bridge (no persistent surface)'
+          : 'opencode: launch-time --auto (no persistent surface)',
+      )
     }
   }
   return { mode, surfaces }

package/src/capability/cli.ts

@@ -0,0 +1,106 @@
+// `iapeer capability <list|register|unregister|sync>` — the operator/installer surface
+// of the capability-plugin lifecycle (docs/21-capabilities.md).
+import { readFileSync } from 'node:fs'
+import { readPeersIndex } from '../registry/index.ts'
+import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
+import { pluginLogsDir } from '../storage/index.ts'
+import type { ProvisionOccasion } from '../enable/provisionCommand.ts'
+import {
+  capabilityEndpoints,
+  listCapabilities,
+  parseCapabilityDeclaration,
+  removeCapabilityDeclaration,
+  runCapabilityLifecycle,
+  writeCapabilityDeclaration,
+  type CapabilityDeclaration,
+} from './index.ts'
+
+export interface CapabilitySweepLine {
+  personality: string
+  runtime: string
+  state: string
+  detail?: string
+}
+
+/** Run one command of ONE capability across every registered peer's applicable endpoints. */
+export async function sweepCapability(
+  decl: CapabilityDeclaration,
+  kind: 'provision' | 'unprovision',
+  occasion: ProvisionOccasion,
+  env: NodeJS.ProcessEnv,
+): Promise<CapabilitySweepLine[]> {
+  const lines: CapabilitySweepLine[] = []
+  for (const p of readPeersIndex({ env }).peers) {
+    if (capabilityEndpoints(decl, p.runtimes).length === 0) continue
+    for (const run of runCapabilityLifecycle({ kind, personality: p.personality, cwd: p.cwd, runtimes: p.runtimes, occasion, env, only: decl })) {
+      const o = run.outcome
+      appendLifecycleEvent(
+        pluginLogsDir('iapeer', { env }),
+        { ev: 'capability-provision', capability: decl.capability, identity: `${run.runtime}-${p.personality}`, occasion, state: o.state, exit: o.exitCode ?? undefined, ms: o.durationMs, detail: o.detail },
+        { env },
+      )
+      lines.push({ personality: p.personality, runtime: run.runtime, state: o.state, ...(o.state !== 'ok' && o.detail ? { detail: o.detail } : {}) })
+    }
+  }
+  return lines
+}
+
+function find(name: string, env: NodeJS.ProcessEnv): CapabilityDeclaration {
+  const decl = listCapabilities({ env }).declarations.find(d => d.capability === name)
+  if (!decl) throw new Error(`capability "${name}" is not registered`)
+  return decl
+}
+
+/** Returns the process exit code. */
+export async function capabilityCli(
+  positionals: string[],
+  env: NodeJS.ProcessEnv,
+  out: (s: string) => void,
+  errOut: (s: string) => void,
+): Promise<number> {
+  const [sub, arg] = positionals
+  const report = (lines: CapabilitySweepLine[]): number => {
+    for (const l of lines) out(`${l.personality} (${l.runtime}): ${l.state}${l.detail ? ` — ${l.detail}` : ''}\n`)
+    if (lines.length === 0) out('no applicable peer endpoints\n')
+    return lines.some(l => l.state !== 'ok') ? 1 : 0
+  }
+  try {
+    switch (sub) {
+      case 'list': {
+        const { declarations, invalid } = listCapabilities({ env })
+        for (const d of declarations) out(`${d.capability}${d.version ? `@${d.version}` : ''}  runtimes=[${d.runtimes.join(', ')}]  ${d.provision.command}\n`)
+        for (const b of invalid) out(`INVALID ${b.file}: ${b.error}\n`)
+        if (declarations.length + invalid.length === 0) out('no capabilities registered\n')
+        return invalid.length ? 1 : 0
+      }
+      case 'register': {
+        if (!arg) throw new Error('usage: iapeer capability register <declaration.json>')
+        const decl = parseCapabilityDeclaration(JSON.parse(readFileSync(arg, 'utf8')))
+        const path = writeCapabilityDeclaration(decl, { env })
+        out(`registered ${decl.capability} → ${path}\n`)
+        // Existing peers get the surfaces now; new peers get them at birth.
+        return report(await sweepCapability(decl, 'provision', 'sweep-on', env))
+      }
+      case 'sync': {
+        if (!arg) throw new Error('usage: iapeer capability sync <name>')
+        return report(await sweepCapability(find(arg, env), 'provision', 'sweep-on', env))
+      }
+      case 'unregister': {
+        if (!arg) throw new Error('usage: iapeer capability unregister <name>')
+        const decl = find(arg, env)
+        const code = report(await sweepCapability(decl, 'unprovision', 'off-all', env))
+        // The declaration goes even if a peer failed to unwind: a lingering declaration
+        // would re-provision surfaces on the next birth. The failures are reported above.
+        removeCapabilityDeclaration(decl.capability, { env })
+        out(`unregistered ${decl.capability}\n`)
+        return code
+      }
+      default:
+        errOut('usage: iapeer capability <list | register <declaration.json> | sync <name> | unregister <name>>\n')
+        return 2
+    }
+  } catch (e) {
+    errOut(`capability ${sub ?? ''}: ${e instanceof Error ? e.message : String(e)}\n`)
+    return 1
+  }
+}

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
+}