@agfpd/iapeer 0.4.120 → 0.4.121

package/docs/20-opencode.md

@@ -175,6 +175,14 @@ process was SIGKILLed before any answer, and the fresh next session never saw it
   (lifecycle.log) and `ev=inflight-redelivered|inflight-undelivered`
   (delivery.log).
 - A false «not processed» costs a visible duplicate, never a silent loss.
+- Unknown is not failed. When a live receiver's acceptance record does not appear
+  within the confirm window (a busy claude records a queued message late), the
+  send returns `ok` with `unconfirmed: true` instead of «NOT delivered» — the
+  sender must not resend. The ledger keeps the entry marked unconfirmed: once any
+  record carrying the envelope appears (including a claude `queue-operation`) it
+  is an ordinary pending entry; if none appears within 120 s the paste was
+  swallowed, and the ledger redelivers it. Each message is redelivered at most
+  once; a second miss becomes an explicit notice to the sender.
 
 The real death cause is recorded too: the supervisor waits for the reap, so a
 SIGKILL is logged as `dead_signal=SIGKILL`, never as a clean exit 0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.120",
+  "version": "0.4.121",
   "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/cli/index.ts

@@ -900,6 +900,117 @@ export async function compactPeer(
 // ephemeral zombie records a retired spawn leaves behind.
 // ─────────────────────────────────────────────────────────────────────────────
 
+// ─────────────────────────────────────────────────────────────────────────────
+// remove-runtime — the symmetric undo of add-runtime (one endpoint, not the peer)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface RemoveRuntimeOutcome {
+  personality: string
+  runtime: string
+  action: 'removed' | 'absent' | 'refused-default' | 'refused-last' | 'refused-live' | 'refused-infra'
+  reason?: string
+  /** What was undone, one line per surface. */
+  steps?: string[]
+}
+
+/**
+ * Detach ONE runtime from a peer (OC14-2 — the pilot rollback of `add-runtime --all`). Undoes what
+ * add-runtime did for that endpoint, in this order: refuse unsafe cases (the default runtime, the last
+ * runtime, a live session unless --force, an infra channel — its plist teardown is `remove`'s job);
+ * unprovision the memory slot and every capability for THIS runtime (occasion=remove); runtime cleanup
+ * (opencode: its core private dir; codex: cwd trust); park the cwd discovery markers (`.claude`/`.codex`
+ * and `.iapeer/runtimes/<rt>`) as `<name>.removed-<ts>` so re-provision does not rediscover the
+ * runtime — data is kept, nothing is deleted from the peer folder; drop it from the local profile
+ * (source of truth) and re-project the registry; purge the endpoint's lifecycle state.
+ */
+export async function removeRuntimeCli(
+  runtime: string,
+  opts: CliEnvOptions & { peer: string; force?: boolean },
+): Promise<RemoveRuntimeOutcome> {
+  const env = opts.env ?? process.env
+  const personality = opts.peer
+  const peer = findPeer(readPeersIndex({ env }), personality)
+  if (!peer) throw new Error(`peer "${personality}" is not registered`)
+  if (!peer.runtimes.includes(runtime)) return { personality, runtime, action: 'absent', reason: `"${personality}" does not declare ${runtime}` }
+  if (isInfraRuntime(runtime)) {
+    return { personality, runtime, action: 'refused-infra', reason: `"${runtime}" is an always-on channel (launchd plist) — not supported by remove-runtime yet` }
+  }
+  if (peer.runtimes.length === 1) {
+    return { personality, runtime, action: 'refused-last', reason: `${runtime} is the only runtime of "${personality}" — use \`iapeer remove ${personality}\`` }
+  }
+  if (peer.runtime === runtime) {
+    return {
+      personality,
+      runtime,
+      action: 'refused-default',
+      reason: `${runtime} is the default runtime of "${personality}" — switch it first: iapeer default-runtime <other> --peer ${personality}`,
+    }
+  }
+  const cfg = loadLifecycleConfig(env)
+  const identity = buildProcessAddress(runtime as Runtime, personality)
+  const steps: string[] = []
+  if (isPeerLive(runtime, personality, cfg.sockDir, env)) {
+    if (!opts.force) {
+      return { personality, runtime, action: 'refused-live', reason: `${identity} is LIVE — stop it first (iapeer stop ${personality} ${runtime}) or pass --force` }
+    }
+    const { killPtyHost } = await import('../launch/ptyHost.ts')
+    killPtyHost(identity, env)
+    steps.push('live session stopped (--force)')
+  }
+  // Slots for THIS endpoint (provider + capabilities), while the peer's state is still consistent.
+  try {
+    const slot = readMemoryProvider(env)
+    if (slot?.unprovision) {
+      const { runProvisionCommand } = await import('../enable/provisionCommand.ts')
+      const o = runProvisionCommand({ block: slot.unprovision, cwd: peer.cwd, runtime, personality, occasion: 'remove', env })
+      steps.push(`memory unprovision: ${o.state}${o.state !== 'ok' && o.detail ? ` (${o.detail})` : ''}`)
+    }
+  } catch (e) {
+    steps.push(`memory unprovision: failed (${e instanceof Error ? e.message : String(e)})`)
+  }
+  try {
+    const { runCapabilityLifecycle } = await import('../capability/index.ts')
+    for (const run of runCapabilityLifecycle({ kind: 'unprovision', personality, cwd: peer.cwd, runtimes: [runtime], occasion: 'remove', env })) {
+      steps.push(`capability ${run.capability} unprovision: ${run.outcome.state}`)
+    }
+  } catch (e) {
+    steps.push(`capabilities: failed (${e instanceof Error ? e.message : String(e)})`)
+  }
+  if (runtime === 'opencode') {
+    const { opencodePaths } = await import('../opencode/config.ts')
+    const dir = opencodePaths(personality, { env }).dir
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true, force: true })
+      steps.push(`opencode private dir removed: ${dir}`)
+    }
+  }
+  if (runtime === 'codex') {
+    try {
+      const { removeCodexCwdTrust } = await import('../launch/nativeMemory.ts')
+      steps.push(`codex cwd trust: ${removeCodexCwdTrust(peer.cwd, env).state}`)
+    } catch (e) {
+      steps.push(`codex cwd trust: failed (${e instanceof Error ? e.message : String(e)})`)
+    }
+  }
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..*$/, '')
+  for (const marker of [join(peer.cwd, `.${runtime}`), join(peer.cwd, '.iapeer', 'runtimes', runtime)]) {
+    if (!existsSync(marker)) continue
+    const parked = `${marker}.removed-${stamp}`
+    renameSync(marker, parked)
+    steps.push(`marker parked (data kept): ${parked}`)
+  }
+  const profile = readPeerProfile(peer.cwd)
+  if (profile) {
+    writePeerProfileAtomic(peer.cwd, { ...profile, runtimes: profile.runtimes.filter(r => r !== runtime) })
+    steps.push('local profile: runtime removed')
+  }
+  const { reindexFromLocals } = await import('../identity/profileStandard.ts')
+  await reindexFromLocals({ env })
+  const purged = purgeIdentityState(cfg, identity)
+  if (purged.length) steps.push(`lifecycle state purged: ${purged.join(', ')}`)
+  return { personality, runtime, action: 'removed', steps }
+}
+
 export interface RemoveOutcome {
   personality: string
   action: 'removed' | 'absent' | 'refused-live' | 'refused-foreign-launchd'
@@ -1605,6 +1716,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: 'remove-runtime <runtime> --peer <p> [--force]', desc: 'detach ONE agentic runtime from a peer (the undo of add-runtime): unprovision memory + capabilities for it, runtime cleanup (opencode private dir, codex trust), park its cwd markers as *.removed-<ts> (data kept), drop it from the profile + registry, purge its lifecycle state. Refuses the default runtime, the last runtime, a live session (unless --force) and infra channels' },
   { 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' },
@@ -2310,6 +2422,15 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         out(`${endpointPrivateDir(candidates[0]!, name, { env })}\n`)
         return 0
       }
+      case 'remove-runtime': {
+        const rt = positionals[0]
+        const peerName = typeof flags.peer === 'string' ? flags.peer : undefined
+        if (!rt || !peerName) return argErr(errOut, 'remove-runtime needs a runtime and a peer — usage: iapeer remove-runtime <runtime> --peer <p> [--force]')
+        const o = await removeRuntimeCli(rt, { peer: peerName, force: flags.force === true, env })
+        out(`${o.personality}: ${o.runtime} ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
+        for (const step of o.steps ?? []) out(`  ${step}\n`)
+        return o.action === 'removed' || o.action === 'absent' ? 0 : 1
+      }
       case 'default-runtime': {
         // The PRIMARY flip (routing/wake default) — the fleet-switch moment itself.
         const rt = positionals[0]

package/src/daemon/main.ts

@@ -56,6 +56,7 @@ import type { ResolvedCaller } from '../identity/index.ts'
 import { findPeer, readPeersIndex } from '../registry/index.ts'
 import {
   createComposerDeliveryQueue,
+  deliveryLanded,
   deliveryProcessed,
   routeSend,
   type InflightNote,
@@ -265,8 +266,10 @@ export function makeNoteInflight(cfg: LifecycleConfig): (note: InflightNote) =>
 }
 
 /** The redelivery prefix — the model sees it is a re-send, not a duplicate of something it answered. */
+const REDELIVERY_PREFIX = '[redelivered by iapeer:'
 export function redeliveryMessage(e: InflightEntry): string {
-  return `[redelivered by iapeer: the receiving session ended before answering this message; originally sent ${e.sentAt}]\n${e.message}`
+  const why = e.unconfirmed ? 'it never reached the receiving session' : 'the receiving session ended before answering this message'
+  return `${REDELIVERY_PREFIX} ${why}; originally sent ${e.sentAt}]\n${e.message}`
 }
 
 /** Body of the explicit non-delivery notice to the original sender. */
@@ -289,7 +292,7 @@ export async function processInflight(
   cfg: LifecycleConfig,
   env: NodeJS.ProcessEnv,
   routeDeps: RouteDeps,
-  seam: { send?: typeof routeSend; processed?: (e: InflightEntry) => boolean } = {},
+  seam: { send?: typeof routeSend; processed?: (e: InflightEntry) => boolean; landed?: (e: InflightEntry) => boolean } = {},
 ): Promise<void> {
   const processed = seam.processed ?? ((e: InflightEntry) => deliveryProcessed(e, env))
   const send = seam.send ?? routeSend
@@ -297,6 +300,7 @@ export async function processInflight(
     const n = sweepInflight(cfg.stateDir, identity, {
       sessionToken: id => (hostSessionAlive(id, env) ? hostSessionToken(id, env) : null),
       processed,
+      landed: seam.landed ?? ((e: InflightEntry) => deliveryLanded(e, env)),
     })
     if (n > 0) appendLifecycleEvent(cfg.eventLogDir, { ev: 'inflight-orphaned', identity, count: n }, { env })
   }
@@ -305,6 +309,9 @@ export async function processInflight(
       const index = readPeersIndex({ env })
       let reason: string
       try {
+        // ONE redelivery per message: an already-redelivered message that orphans again goes to the
+        // sender as an explicit notice instead of looping.
+        if (e.message.startsWith(REDELIVERY_PREFIX)) throw new Error('already redelivered once and still not processed')
         const caller = resolveCallerIdentity({ personality: e.caller.personality, runtime: e.caller.runtime }, index)
         const r = await send(
           caller,

package/src/lifecycle/inflight.ts

@@ -32,8 +32,14 @@ export interface InflightEntry {
   attachments?: string[]
   /** The presented envelope (what the model sees) — the processed-check needle source. */
   rendered: string
+  /** The live confirm window ran out at delivery: whether it LANDED is still unknown. */
+  unconfirmed?: true
 }
 
+/** How long an unconfirmed delivery may stay unlanded in a live session before the ledger treats the
+ *  paste as swallowed and redelivers it (once). Generous: a busy receiver records a queued message late. */
+export const UNLANDED_AFTER_MS = 120_000
+
 const inflightPath = (stateDir: string, identity: string) => join(stateDir, `${identity}.inflight.jsonl`)
 const orphansPath = (stateDir: string, identity: string) => join(stateDir, `${identity}.orphans.jsonl`)
 
@@ -84,6 +90,9 @@ export interface InflightSweepDeps {
   sessionToken: (identity: string) => string | null
   /** Did the receiving session answer this entry? */
   processed: (entry: InflightEntry) => boolean
+  /** Did the entry land in the session at all? Only consulted for `unconfirmed` entries. */
+  landed?: (entry: InflightEntry) => boolean
+  now?: number
 }
 
 /**
@@ -105,8 +114,23 @@ export function sweepInflight(stateDir: string, identity: string, deps: Inflight
       done = false
     }
     if (done) continue
-    if (current !== null && current === e.sessionToken) keep.push(e)
-    else orphaned.push(e)
+    if (current !== null && current === e.sessionToken) {
+      // Unknown landing (confirm window ran out): once seen in the session it is a normal pending entry;
+      // still unseen after UNLANDED_AFTER_MS → the paste was swallowed → orphan (redeliver once).
+      if (e.unconfirmed && deps.landed) {
+        let landed = false
+        try {
+          landed = deps.landed(e)
+        } catch {
+          landed = false
+        }
+        if (landed) keep.push({ ...e, unconfirmed: undefined })
+        else if ((deps.now ?? Date.now()) - e.ts > UNLANDED_AFTER_MS) orphaned.push(e)
+        else keep.push(e)
+        continue
+      }
+      keep.push(e)
+    } else orphaned.push(e)
   }
   writeJsonl(inflightPath(stateDir, identity), keep)
   if (orphaned.length) for (const o of orphaned) appendFileSync(orphansPath(stateDir, identity), JSON.stringify(o) + '\n', { mode: 0o600 })

package/src/transport/index.ts

@@ -294,6 +294,13 @@ export interface WarmDeliverSeam {
    *  the real `resubmitHosted` (a bare CR over the control channel). Tests inject a spy to assert the
    *  retry fires only while unconfirmed — and never once the record is in. */
   resubmit?: (identity: string) => Promise<void>
+  /** UNKNOWN ≠ FAILED (incident 18.10: a busy receiver's transcript record landed after the grace,
+   *  the sender got «NOT delivered», believed it and sent a duplicate). When set, a confirm grace that
+   *  runs out on a LIVE session is reported as UNCONFIRMED — `onUnconfirmed()` fires and the delivery
+   *  returns ok — and the inflight ledger, not the sender, owns any retry (docs/20 §Durable inbound).
+   *  Unset (default): the strict legacy false-FAIL. */
+  allowUnconfirmed?: boolean
+  onUnconfirmed?: () => void
 }
 
 /**
@@ -445,6 +452,10 @@ async function deliverViaHost(
     }
     await sleep(LIVENESS_POLL_MS)
   }
+  if (seam.allowUnconfirmed) {
+    seam.onUnconfirmed?.()
+    return ok(undefined)
+  }
   return err(
     `hosted peer "${target.personality}" (${target.runtime}) is listed live but did not accept the message ` +
       `(no transcript record carrying the message within ${graceMs}ms) — live but unresponsive to this delivery (not dead); message NOT delivered`,
@@ -892,6 +903,36 @@ export function deliveryProcessed(probe: ProcessedProbe, env: NodeJS.ProcessEnv
   return false
 }
 
+/**
+ * Did the envelope LAND in the receiving session at all (any record carrying it, including claude's
+ * queue-operation for a busy session)? Weaker than deliveryProcessed — it separates «queued / being
+ * worked on» from «the paste was swallowed and nothing will ever see it». Structural runtimes (opencode)
+ * always landed: their delivery ack is a native persistence ack.
+ */
+export function deliveryLanded(probe: ProcessedProbe, env: NodeJS.ProcessEnv = process.env): boolean {
+  if (getAdapter(probe.runtime).deliveryConfirm === 'structural') return true
+  const needles = confirmNeedles(probe.rendered)
+  if (!needles.length || needles.every(n => !n)) return false
+  for (const path of compactCandidateFiles(probe.runtime, probe.cwd, env)) {
+    let st
+    try {
+      st = statSync(path)
+    } catch {
+      continue
+    }
+    if (st.mtimeMs < probe.ts - 5000) continue
+    for (const line of readFileTailFrom(path, Math.max(0, st.size - PROCESSED_TAIL_BYTES)).split(/\r?\n/)) {
+      if (!line.trim()) continue
+      try {
+        if (jsonStringValuesContainAll(JSON.parse(line), needles)) return true
+      } catch {
+        /* skip */
+      }
+    }
+  }
+  return false
+}
+
 /** One confirmed delivery to an AGENT endpoint, as transport reports it to the inflight ledger. */
 export interface InflightNote {
   sentAt: string
@@ -905,6 +946,8 @@ export interface InflightNote {
   topic?: string
   attachments?: string[]
   rendered: string
+  /** The live confirm window ran out (see WarmDeliverSeam.allowUnconfirmed). */
+  unconfirmed?: true
 }
 
 function compactDoneTimeoutMs(env: NodeJS.ProcessEnv | undefined): number {
@@ -1144,6 +1187,10 @@ export interface RouteResult {
   queuedBy?: 'ephemeral' | 'composer'
   /** Queue depth right after the enqueue (observability; only with queued). */
   queueDepth?: number
+  /** The bytes reached the live session but its acceptance record did not appear within the confirm
+   *  window (e.g. a busy receiver). NOT a failure: do not resend — the core's inflight ledger checks
+   *  it landed and redelivers once (or tells you) if it did not. */
+  unconfirmed?: true
 }
 
 // WakeFn — the lifecycle wake primitive, INJECTED (transport never imports
@@ -1293,7 +1340,7 @@ function noteTopic(deps: RouteDeps, identity: string, topic: string | undefined)
   }
 }
 
-type InflightInfo = { sentAt: string; caller: ResolvedCaller; message: string; topic?: string; attachments?: string[]; envelope: string }
+type InflightInfo = { sentAt: string; caller: ResolvedCaller; message: string; topic?: string; attachments?: string[]; envelope: string; unconfirmed?: boolean }
 
 /** Best-effort inflight record (OC07) — only for agent (tui) endpoints. */
 function noteInflight(
@@ -1318,6 +1365,7 @@ function noteInflight(
       ...(info.topic ? { topic: info.topic } : {}),
       ...(info.attachments?.length ? { attachments: info.attachments } : {}),
       rendered: renderEnvelopeForAgent(info.envelope),
+      ...(info.unconfirmed ? { unconfirmed: true as const } : {}),
     })
   } catch {
     /* a post-delivery hook must never fail the delivery */
@@ -1790,16 +1838,26 @@ async function routeSendInner(
     // peer.cwd enables the Ф-B transcript-mtime liveness probe (busy-session case).
     // deliverWarm is HOST-AWARE (spawn-flip Ф0b-2): a supervisor-hosted target delivers over its
     // socket, any other target keeps the tmux path. Flag-off → byte-identical to deliverViaTmux.
-    const delivered = await deliverWarm(target.value, envelope, peer.cwd, {}, env)
+    // Unknown ≠ failed: a confirm window that runs out on a LIVE session is reported unconfirmed and the
+    // inflight ledger owns the retry — only when that ledger is wired (deps.noteInflight), else strict.
+    let unconfirmed = false
+    const delivered = await deliverWarm(
+      target.value,
+      envelope,
+      peer.cwd,
+      deps.noteInflight ? { allowUnconfirmed: true, onUnconfirmed: () => (unconfirmed = true) } : {},
+      env,
+    )
     if (!delivered.ok) return delivered
     noteTopic(deps, target.value.address, topic)
     noteDelivered(deps, target.value.address) // В7 — floor the idle proxy so this delivery isn't reaped away
-    noteInflight(deps, target.value, peer.cwd, inflightInfo, env)
+    noteInflight(deps, target.value, peer.cwd, { ...inflightInfo, unconfirmed }, env)
     return ok({
       ok: true,
       delivered_to: { personality: target.value.personality, runtime: target.value.runtime },
       woke: false,
       ts: sentAt,
+      ...(unconfirmed ? { unconfirmed: true as const } : {}),
     })
   }