@agfpd/iapeer 0.4.109 → 0.4.111

package/src/runtime/deploy.ts

@@ -22,6 +22,7 @@ import { type Runtime } from '../core/constants.ts'
 import { IapError } from '../core/errors.ts'
 import { createPeer, type CreatePeerResult } from '../create/index.ts'
 import { readRuntimeManifest, writeRuntimeManifest, type RuntimeManifest, type RuntimePeerDecl } from './index.ts'
+import { verifyRuntimeSignatures, type RuntimeSignatureVerifier } from './signature.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Built-in runtime → npm package registry (§6): onboard AUTO-resolves
@@ -52,6 +53,7 @@ export interface DeployRuntimeOptions {
   bootstrap?: boolean
   env?: NodeJS.ProcessEnv
   warn?: (message: string) => void
+  verifySignatures?: RuntimeSignatureVerifier
 }
 
 export interface DeployedPeer {
@@ -90,6 +92,8 @@ export async function deployRuntime(opts: DeployRuntimeOptions): Promise<DeployR
     )
   }
   const declared = opts.peers ?? manifest.peers ?? []
+  const verifySignatures = opts.verifySignatures ?? verifyRuntimeSignatures
+  verifySignatures(opts.runtime, env, { ...manifest, peers: declared })
   const peers: DeployedPeer[] = []
   for (const decl of declared) {
     const result = await createPeer({
@@ -164,6 +168,8 @@ export interface InstallRuntimePackageOptions {
   env?: NodeJS.ProcessEnv
   /** Injected npx runner (tests / sandbox proof). */
   runNpx?: NpxRunner
+  /** Verify-only activation gate; injected in hermetic orchestration tests. */
+  verifySignatures?: RuntimeSignatureVerifier
 }
 
 /**
@@ -183,6 +189,11 @@ export function installRuntimePackage(opts: InstallRuntimePackageOptions): Insta
   const existing = readRuntimeManifest(opts.runtime, { env })
   const pkg = resolveRuntimePackage(opts.runtime, opts.package ?? existing?.package)
   if (existing && !opts.force) {
+    try {
+      (opts.verifySignatures ?? verifyRuntimeSignatures)(opts.runtime, env)
+    } catch (e) {
+      return { runtime: opts.runtime, package: pkg, state: 'failed', detail: e instanceof Error ? e.message : String(e) }
+    }
     return { runtime: opts.runtime, package: pkg, state: 'skipped' }
   }
   if (!pkg) {
@@ -194,6 +205,13 @@ export function installRuntimePackage(opts: InstallRuntimePackageOptions): Insta
   if (!r.ok) {
     return { runtime: opts.runtime, package: pkg, state: 'failed', detail: r.detail }
   }
+  // Verification is not version-gated and precedes manifest stamping/provision.
+  // Never repair an installed launcher here: the package owns staged repair.
+  try {
+    (opts.verifySignatures ?? verifyRuntimeSignatures)(opts.runtime, env)
+  } catch (e) {
+    return { runtime: opts.runtime, package: pkg, state: 'failed', detail: e instanceof Error ? e.message : String(e) }
+  }
   // В52 — stamp the delivering package into the fresh manifest (best-effort: a
   // missing manifest is the package's own contract breach, surfaced elsewhere).
   try {
@@ -212,6 +230,7 @@ export interface OnboardRuntimeOptions extends DeployRuntimeOptions {
   npx?: boolean
   /** Injected npx runner (tests / sandbox proof). */
   runNpx?: NpxRunner
+  verifySignatures?: RuntimeSignatureVerifier
 }
 
 export interface OnboardRuntimeResult {
@@ -235,6 +254,7 @@ export async function onboardRuntime(opts: OnboardRuntimeOptions): Promise<Onboa
     force: opts.npx,
     env,
     runNpx: opts.runNpx,
+    verifySignatures: opts.verifySignatures,
   })
   if (install.state === 'failed') {
     throw new IapError(`npx install of runtime "${opts.runtime}" package ${install.package} failed: ${install.detail ?? ''}`)
@@ -250,6 +270,7 @@ export async function onboardRuntime(opts: OnboardRuntimeOptions): Promise<Onboa
     bootstrap: opts.bootstrap,
     env,
     warn: opts.warn,
+    verifySignatures: opts.verifySignatures,
   })
   return { install, deploy }
 }

package/src/runtime/signature.ts

@@ -0,0 +1,35 @@
+// Secondary, verify-only gate. The package must verify its staged inode BEFORE
+// publishing it; the foundation refuses provisioning/restart of invalid code.
+import { ensureExecutableSignature, type ExecutableSignatureOptions } from '../install/signature.ts'
+import { resolveExecutable } from '../launch/launchd.ts'
+import { type Runtime } from '../core/constants.ts'
+import { readRuntimeManifest, type RuntimeManifest } from './index.ts'
+
+export type RuntimeSignatureVerifier = (runtime: Runtime, env: NodeJS.ProcessEnv, manifest?: RuntimeManifest) => void
+
+export function verifyRuntimeSignatures(
+  runtime: Runtime,
+  env: NodeJS.ProcessEnv,
+  suppliedManifest?: RuntimeManifest,
+  opts: Pick<ExecutableSignatureOptions, 'run' | 'platform'> = {},
+): void {
+  if ((opts.platform ?? process.platform) !== 'darwin') return
+  if (!opts.run && (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1')) return
+  const manifest = suppliedManifest ?? readRuntimeManifest(runtime, { env })
+  const names = new Set<string>()
+  const declared = manifest?.peers ?? []
+  // The same default launcher the core's provisioning/launch scheme uses. A
+  // fully explicit declared-set needs only its explicitly declared launchers.
+  if (!declared.length || declared.some(p => !p.runtimeBin)) names.add(`${runtime}-runtime`)
+  for (const peer of declared) if (peer.runtimeBin) names.add(peer.runtimeBin)
+  const hook = manifest?.selfConfig
+  if (hook) names.add(typeof hook === 'string' ? hook : hook.command)
+  const checked = new Set<string>()
+  for (const name of names) {
+    const path = resolveExecutable(name, env)
+    if (!path) throw new Error(`runtime "${runtime}" launcher not executable or not found: ${name}`)
+    if (checked.has(path)) continue
+    checked.add(path)
+    ensureExecutableSignature(path, { ...opts, env, repair: false })
+  }
+}

package/src/runtime/update.ts

@@ -10,8 +10,8 @@
 //   version with a new blurb/self-doc leaves stale descriptions) → restart the
 //   runtime's infra peers via the REGULAR stop/start verbs.
 //
-// The core's own `iapeer update` deliberately does NOT touch runtimes (foundation-
-// only — the standing contract; the symmetry is conscious).
+// The CLI's bare `iapeer update` invokes this runtime updater in its cascade;
+// --foundation-only and a foundation version pin omit the runtime leg.
 //
 // Version-gate honesty: the installed version comes from the manifest's `version`
 // stamp (the owners' self-install obligation, telegram 10.06). A manifest WITHOUT
@@ -24,6 +24,7 @@ import { isRuntime, type Runtime } from '../core/constants.ts'
 import { readPeersIndex } from '../registry/index.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
 import { readRuntimeManifest } from './index.ts'
+import { verifyRuntimeSignatures, type RuntimeSignatureVerifier } from './signature.ts'
 import {
   deployRuntime,
   installRuntimePackage,
@@ -71,6 +72,7 @@ export interface UpdateRuntimeOptions {
   force?: boolean
   env?: NodeJS.ProcessEnv
   runNpx?: NpxRunner
+  verifySignatures?: RuntimeSignatureVerifier
   npmVersion?: NpmVersionFn
   /** Injectable restart (tests). Default: the regular stop→start verbs, strictly
    *  sequential per peer. */
@@ -124,12 +126,17 @@ export async function updateRuntime(opts: UpdateRuntimeOptions): Promise<UpdateR
   }
   const installed = manifest.version
   if (installed && installed === latest && !opts.force) {
+    try {
+      (opts.verifySignatures ?? verifyRuntimeSignatures)(runtime, env)
+    } catch (e) {
+      return { runtime, package: pkg, state: 'install-failed', from: installed, to: latest, peers: [], restarted: [], detail: e instanceof Error ? e.message : String(e) }
+    }
     return { runtime, package: pkg, state: 'already-latest', from: installed, to: latest, peers: [], restarted: [] }
   }
 
   // Re-install, PINNED to the version the gate resolved (В51 — an unpinned npx can
   // serve a stale cached/propagating build while we report "updated → latest").
-  const install = installRuntimePackage({ runtime, package: manifest.package, version: latest, force: true, env, runNpx: opts.runNpx })
+  const install = installRuntimePackage({ runtime, package: manifest.package, version: latest, force: true, env, runNpx: opts.runNpx, verifySignatures: opts.verifySignatures })
   if (install.state !== 'ran') {
     return { runtime, package: pkg, state: 'install-failed', from: installed, to: latest, peers: [], restarted: [], detail: install.detail ?? install.state }
   }
@@ -157,7 +164,7 @@ export async function updateRuntime(opts: UpdateRuntimeOptions): Promise<UpdateR
   // peers — the deploy is an empty pass, by design.
   let peers: DeployedPeer[]
   try {
-    const d = await deployRuntime({ runtime, env, warn: opts.warn })
+    const d = await deployRuntime({ runtime, env, warn: opts.warn, verifySignatures: opts.verifySignatures })
     peers = d.peers
   } catch (e) {
     return { runtime, package: pkg, state: 'deploy-failed', from: installed, to: latest, peers: [], restarted: [], detail: e instanceof Error ? e.message : String(e) }

package/src/supervisor/daemon.ts

@@ -26,13 +26,14 @@ import {
   stripQueries,
 } from './protocol.ts'
 import { formatEventLine } from '../storage/rotatelog.ts'
-import { attachedPath, geometryPath, pidPath, servePath, sockPath, writeGeometry, writePidFile } from './paths.ts'
+import { attachedPath, geometryPath, pidPath, pidStartToken, servePath, sockPath, writeGeometry, writePidFile } from './paths.ts'
 import { newStabilityGate, nagSignature, nextBootAction, nextNagAction, signatureStable, type BootPredicates, type NagPredicate } from './boot.ts'
 import { modelToPlainText } from './render.ts'
 import { codexAdapter } from '../launch/adapters/codex.ts'
 import { claudeAdapter } from '../launch/adapters/claude.ts'
 import { approvalModeOf, readPeerProfile, type ApprovalMode } from '../identity/index.ts'
 import { routeCircuitBreaker } from './approvalRoute.ts'
+import { killPtyDescendants } from './processTree.ts'
 
 /** Resolve a runtime launcher from the host AT CALL TIME — env override (IAPEER_<RT>_BIN, the same
  *  knob the rest of the foundation uses) → PATH lookup — never a baked machine-specific path. Returns
@@ -110,6 +111,7 @@ const SIGWINCH_REDRAW_WAIT_MS = 300
 
 // Bun-native PTY (Bun ≥1.3.5) is not yet in @types/bun — type the slice we use.
 interface PtyChild {
+  pid: number
   terminal: { write(d: Uint8Array | string): void; resize(cols: number, rows: number): void }
   kill(sig?: number | string): void
 }
@@ -385,6 +387,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
       },
     },
   } as unknown as Parameters<typeof Bun.spawn>[1]) as unknown as PtyChild
+  const childToken = pidStartToken(child.pid)
   xterm.onData(resp => child.terminal.write(resp)) // @xterm auto-answers DA1/DSR → back to child
 
   /** Catch up a (re)attaching client to the current screen + history ONCE by sending a SNAPSHOT of the
@@ -602,6 +605,14 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
       } catch {
         /* */
       }
+    try {
+      // self-fresh/stop/reap owns the PTY's descendants, not just its TUI root. Snapshot BEFORE
+      // killing the runtime; exclude detached/shared daemons even if they are descendants.
+      const cleaned = killPtyDescendants(child.pid, childToken)
+      if (cleaned.killed || cleaned.skipped) appendExitEvent({ ev: 'session-tree', identity: session, ...cleaned })
+    } catch (e) {
+      appendExitEvent({ ev: 'session-tree', identity: session, error: (e as Error).message })
+    }
     try {
       child.kill('SIGKILL')
     } catch {

package/src/supervisor/fixtures/owned-stdio.ts

@@ -0,0 +1,57 @@
+// Deterministic stdio process tree: peer -> launcher -> MCP server.
+// No accounts, external services, or installed runtime binaries are used.
+import { spawn } from 'node:child_process'
+import { appendFileSync, writeFileSync } from 'node:fs'
+import { createInterface } from 'node:readline'
+
+const [mode, dir, cli] = process.argv.slice(2)
+const self = import.meta.path
+const record = (event: string, extra = {}) => appendFileSync(`${dir}/events.jsonl`, JSON.stringify({ event, pid: process.pid, ppid: process.ppid, ...extra }) + '\n')
+record(mode)
+
+if (mode === 'server') {
+  // Keep-alive handles after EOF model a server that cannot shut down by EOF alone.
+  // The supervisor's hard session teardown must reclaim it, not rely on compliance.
+  setInterval(() => {}, 1000)
+  process.on('SIGHUP', () => record('server-hup-ignored'))
+  process.on('SIGTERM', () => record('server-term-ignored'))
+  const input = createInterface({ input: process.stdin })
+  input.on('close', () => record('server-eof'))
+  input.on('line', line => {
+    const req = JSON.parse(line)
+    record(req.method)
+    if (req.id === undefined) return
+    const result = req.method === 'initialize'
+      ? { protocolVersion: req.params.protocolVersion, capabilities: { tools: {} }, serverInfo: { name: 'owned-stdio', version: '1' } }
+      : req.method === 'tools/list'
+        ? { tools: [{ name: 'ping', description: 'Return the serving process ID', inputSchema: { type: 'object', properties: {} } }] }
+        : { content: [{ type: 'text', text: `pong:${process.pid}` }] }
+    process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: req.id, result }) + '\n')
+  })
+} else if (mode === 'wrapper') {
+  const server = spawn(process.execPath, [self, 'server', dir], { stdio: 'inherit' })
+  process.on('SIGTERM', () => record('wrapper-term-ignored'))
+  process.on('SIGHUP', () => record('wrapper-hup-ignored'))
+  server.on('exit', () => process.exit(0))
+} else if (mode === 'peer') {
+  const sentinel = spawn('sleep', ['60'], { detached: true, stdio: 'ignore' })
+  sentinel.unref()
+  record('detached-sentinel', { pid: sentinel.pid })
+  const wrapper = spawn(process.execPath, [self, 'wrapper', dir], { stdio: ['pipe', 'pipe', 'inherit'] })
+  const input = createInterface({ input: wrapper.stdout })
+  const send = (id: number, method: string, params: unknown = {}) => wrapper.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n')
+  input.on('line', line => {
+    const response = JSON.parse(line)
+    if (response.id === 1) send(2, 'tools/list')
+    if (response.id === 2) send(3, 'tools/call', { name: 'ping', arguments: {} })
+    if (response.id === 3) {
+      writeFileSync(`${dir}/ready.json`, JSON.stringify({ peer: process.pid, wrapper: wrapper.pid, result: response.result }))
+      console.log('› ready')
+    }
+  })
+  send(1, 'initialize', { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'test-peer', version: '1' } })
+  // This is an actual child self-call to the source CLI, not killSession in disguise.
+  createInterface({ input: process.stdin }).on('line', line => {
+    if (line.replace(/\x1b\[20[01]~/g, '').trim() === 'fresh') spawn(process.execPath, [cli, 'self-fresh'], { stdio: 'inherit', env: process.env })
+  })
+}

package/src/supervisor/processTree.ts

@@ -0,0 +1,71 @@
+import { spawnSync } from 'node:child_process'
+
+export interface ProcessRecord { pid: number; ppid: number; tty: string; token: string }
+
+/** No argv/env in this snapshot: ancestry + controlling PTY, not names or groups, own cleanup. */
+export function parseProcessTable(table: string): ProcessRecord[] {
+  return table.split('\n').flatMap(line => {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/.exec(line)
+    if (!m || Number(m[1]) <= 0) return []
+    return [{ pid: Number(m[1]), ppid: Number(m[2]), tty: m[3], token: m[4] }]
+  })
+}
+
+function processTable(pid?: number): ProcessRecord[] {
+  const args = pid === undefined ? ['-axo', 'pid=,ppid=,tty=,lstart='] : ['-o', 'pid=,ppid=,tty=,lstart=', '-p', String(pid)]
+  const r = spawnSync('/bin/ps', args, { encoding: 'utf8', env: { ...process.env, LC_ALL: 'C' } })
+  if (r.error || r.status !== 0) throw new Error('could not read process ancestry for session teardown')
+  return parseProcessTable(r.stdout)
+}
+
+/** Capture BEFORE killing the runtime: afterwards stdio launchers may already have PPID 1.
+ * The controlling PTY is the ownership boundary: separate process groups (Codex stdio MCP) remain
+ * inside it, whereas setsid/detached services (possibly shared with other clients) leave it. Prune
+ * those entire branches. Never signal a whole group: only proven PTY descendants whose start token
+ * still matches are ours. This preserves the existing HARD session teardown semantics; it is not
+ * a replacement for an MCP client's graceful EOF protocol.
+ * Already-reparented children and children racing the snapshot are outside this ancestry snapshot. */
+export function killPtyDescendants(root: number, rootToken: string | null, deps: {
+  table?: () => ProcessRecord[]
+  identity?: (pid: number) => Pick<ProcessRecord, 'token' | 'tty'> | null
+  signal?: (pid: number) => void
+} = {}): { killed: number; skipped: number } {
+  if (!Number.isInteger(root) || root <= 1 || root === process.pid) throw new Error('invalid hosted runtime pid')
+  const rows = (deps.table ?? processTable)()
+  // The root may already have died (terminal.exit), even before this snapshot. Do not
+  // adopt an unrelated tree on PID reuse; a missing root needs no ancestry cleanup.
+  const currentRoot = rows.find(r => r.pid === root)
+  if (!currentRoot) return { killed: 0, skipped: 0 }
+  if (!rootToken || currentRoot.token !== rootToken) return { killed: 0, skipped: 1 }
+  if (['', '-', '??', '?'].includes(currentRoot.tty)) return { killed: 0, skipped: 1 }
+  const children = new Map<number, ProcessRecord[]>()
+  for (const row of rows) {
+    if (!children.has(row.ppid)) children.set(row.ppid, [])
+    children.get(row.ppid)!.push(row)
+  }
+  const seen = new Set([root, process.pid])
+  const owned: ProcessRecord[] = []
+  const visit = (parent: number) => {
+    for (const row of children.get(parent) ?? []) {
+      if (seen.has(row.pid)) continue
+      if (row.tty !== currentRoot.tty) continue // detached daemon and everything it owns are not this PTY's
+      seen.add(row.pid)
+      visit(row.pid)
+      owned.push(row) // leaves first, while ancestry is still available
+    }
+  }
+  visit(root)
+  let killed = 0, skipped = 0
+  for (const row of owned) {
+    // Unlike killing the root by its Bun subprocess handle, a descendant is a ps-derived PID.
+    // An unreadable token is NOT permission to signal it; fail closed on reuse / uncertainty.
+    let current: Pick<ProcessRecord, 'token' | 'tty'> | null
+    try { current = (deps.identity ?? (pid => processTable(pid)[0] ?? null))(row.pid) } catch { current = null }
+    if (current?.token !== row.token || current.tty !== row.tty) { skipped++; continue }
+    try {
+      (deps.signal ?? (pid => process.kill(pid, 'SIGKILL')))(row.pid)
+      killed++
+    } catch { /* exited between verification and signal */ }
+  }
+  return { killed, skipped }
+}

package/src/transport/attachments.ts

@@ -0,0 +1,163 @@
+// IAP attachment ownership — copy-on-send into recipient-owned foundation state.
+//
+// A caller-supplied attachment path is a SOURCE, never the delivered object. Before
+// routeSend builds an envelope, each regular file is copied byte-for-byte into:
+//
+//   <IAPEER_ROOT>/state/iapeer/attachments/<recipient>/<sha256>/<basename>
+//
+// and only that durable path enters the envelope. The content hash makes repeat
+// sends idempotent without coupling the copy to an ephemeral message/queue entry;
+// a recipient can forward its copy and the next route creates a separate copy in
+// the next recipient's inbox. Completed copies are STATE (not cache): no age GC.
+// The recipient's explicit peer removal purges its complete inbox.
+
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fstatSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  renameSync,
+  rmSync,
+  writeSync,
+} from 'node:fs'
+import { createHash, randomUUID } from 'node:crypto'
+import { basename, join } from 'node:path'
+import { STATE_DIR, isValidName } from '../core/constants.ts'
+import { IapError, err, ok, type Result } from '../core/errors.ts'
+import { resolveGlobalRoot } from '../storage/index.ts'
+
+const DIR_MODE = 0o700
+const FILE_MODE = 0o600
+const COPY_BUFFER_BYTES = 1024 * 1024
+
+export const ATTACHMENT_SPOOL_DIR = 'attachments'
+
+export interface SpooledAttachments {
+  paths: string[]
+  sha256: string[]
+}
+
+export interface AttachmentPurgeResult {
+  path: string
+  removed: boolean
+}
+
+export function attachmentSpoolRoot(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveGlobalRoot(env), STATE_DIR, 'iapeer', ATTACHMENT_SPOOL_DIR)
+}
+
+export function attachmentInboxDir(
+  recipient: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  if (!isValidName(recipient)) {
+    throw new IapError(`invalid attachment recipient "${recipient}"`)
+  }
+  return join(attachmentSpoolRoot(env), recipient)
+}
+
+/**
+ * Copy one source through an fsynced staging file while calculating its SHA-256.
+ * The staging file lives in the recipient inbox (same filesystem as the final
+ * path), so the final rename is atomic. A partial copy is never exposed in an IAP
+ * envelope and is cleaned on every failure visible to this process.
+ */
+function copyOne(
+  source: string,
+  recipient: string,
+  env: NodeJS.ProcessEnv,
+): { path: string; sha256: string } {
+  const inbox = attachmentInboxDir(recipient, env)
+  mkdirSync(inbox, { recursive: true, mode: DIR_MODE })
+  const tmp = join(inbox, `.incoming-${process.pid}-${randomUUID()}`)
+  let sourceFd: number | undefined
+  let targetFd: number | undefined
+  try {
+    sourceFd = openSync(source, 'r')
+    const sourceStat = fstatSync(sourceFd)
+    if (!sourceStat.isFile()) throw new Error('source is not a regular file')
+
+    targetFd = openSync(tmp, 'wx', FILE_MODE)
+    const hash = createHash('sha256')
+    const buffer = Buffer.allocUnsafe(COPY_BUFFER_BYTES)
+    while (true) {
+      const read = readSync(sourceFd, buffer, 0, buffer.length, null)
+      if (read === 0) break
+      hash.update(buffer.subarray(0, read))
+      let written = 0
+      while (written < read) {
+        const n = writeSync(targetFd, buffer, written, read - written)
+        if (n <= 0) {
+          throw new Error(`write made no progress (${written}/${read} bytes in current chunk)`)
+        }
+        written += n
+      }
+    }
+    fsyncSync(targetFd)
+    closeSync(targetFd)
+    targetFd = undefined
+    closeSync(sourceFd)
+    sourceFd = undefined
+
+    const sha256 = hash.digest('hex')
+    const hashDir = join(inbox, sha256)
+    mkdirSync(hashDir, { recursive: true, mode: DIR_MODE })
+    const path = join(hashDir, basename(source))
+    // Atomic publish. Replacing an existing same-hash+basename object is safe and
+    // repairs a manually damaged copy; concurrent publishers carry identical bytes.
+    renameSync(tmp, path)
+    chmodSync(path, FILE_MODE)
+    return { path, sha256 }
+  } finally {
+    if (targetFd !== undefined) {
+      try { closeSync(targetFd) } catch { /* already closed */ }
+    }
+    if (sourceFd !== undefined) {
+      try { closeSync(sourceFd) } catch { /* already closed */ }
+    }
+    try { rmSync(tmp, { force: true }) } catch { /* renamed or best-effort cleanup */ }
+  }
+}
+
+/**
+ * Materialize every attachment in the target peer's inbox. All validation and
+ * copying completes before the caller receives paths for envelope construction;
+ * any failure aborts the send loudly. Copies already completed before a later
+ * item fails stay as harmless recipient state and are content-address deduplicated
+ * on retry (removing them here could delete a copy referenced by an earlier send).
+ */
+export function spoolAttachments(
+  sources: readonly string[],
+  recipient: string,
+  env: NodeJS.ProcessEnv = process.env,
+): Result<SpooledAttachments> {
+  const paths: string[] = []
+  const sha256: string[] = []
+  for (let i = 0; i < sources.length; i++) {
+    const source = sources[i]!
+    try {
+      const copied = copyOne(source, recipient, env)
+      paths.push(copied.path)
+      sha256.push(copied.sha256)
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e)
+      return err(`attachment ${i + 1} "${source}" could not be copied for "${recipient}": ${reason}; message NOT delivered`)
+    }
+  }
+  return ok({ paths, sha256 })
+}
+
+/** Recipient-lifetime cleanup: called by `iapeer remove <peer>`. */
+export function purgeAttachmentInbox(
+  recipient: string,
+  env: NodeJS.ProcessEnv = process.env,
+): AttachmentPurgeResult {
+  const path = attachmentInboxDir(recipient, env)
+  const removed = existsSync(path)
+  rmSync(path, { recursive: true, force: true })
+  return { path, removed }
+}

package/src/transport/index.ts

@@ -71,6 +71,17 @@ import {
 } from './originGuard.ts'
 import { keysToBytes } from '../supervisor/protocol.ts' // pure send-keys-vocab→pty-byte translation (boot-driver slice a), @xterm-free
 import { paneLogComposerOccupied } from '../launch/readyGateModel.ts' // spawn-flip Ф0b-3 slice 3c: hosted busy-composer detector (slice 2). @xterm dynamic-loaded inside it → warm path stays @xterm-free with the flip off
+import { spoolAttachments } from './attachments.ts'
+
+export {
+  ATTACHMENT_SPOOL_DIR,
+  attachmentInboxDir,
+  attachmentSpoolRoot,
+  purgeAttachmentInbox,
+  spoolAttachments,
+  type AttachmentPurgeResult,
+  type SpooledAttachments,
+} from './attachments.ts'
 
 export interface OnlinePeer {
   personality: string
@@ -1502,8 +1513,11 @@ async function routeSendInner(
   // Origin-guard (docs/18) — an agent's PRESUMED REPLY to a human (the human's latest
   // inbound to this agent is unanswered) must target the channel the human wrote from.
   // Checked FIRST, before any resolve/wake side-effect and before the telegram policy:
-  // a mismatch is HELD (persisted verbatim + instructive error), not delivered — the
-  // agent then confirms cross-channel or redirects to the origin, zero regeneration.
+  // a mismatch is HELD, not delivered — the agent then confirms cross-channel or
+  // redirects to the origin, zero regeneration. Attachment PATHS are the deliberate
+  // exception to "verbatim": sources are copied into the intended recipient's durable
+  // inbox before the hold is persisted, so deleting a /tmp source cannot break a later
+  // confirm-send. Message/topic/runtime remain verbatim.
   // Intended runtime = the explicit override or the human's default; exact for the
   // natural-peer class (implicit routing is strictly default_runtime-anchored).
   // Initiative (answered / no inbound / ARM_TTL-stale) passes untouched.
@@ -1516,9 +1530,11 @@ async function routeSendInner(
     const armed = armedOrigin(caller.personality, peer.personality, { env })
     const intendedRt = runtime ?? peer.runtime
     if (armed && armed.rt !== intendedRt) {
+      const spooled = spoolAttachments(attachmentsResult.value, peer.personality, env)
+      if (!spooled.ok) return spooled
       const held = holdSend(
         caller.address,
-        { personality, runtime, message, topic, attachments: attachmentsResult.value },
+        { personality, runtime, message, topic, attachments: spooled.value.paths },
         armed,
         intendedRt,
         { env },
@@ -1533,6 +1549,14 @@ async function routeSendInner(
   const intendedGuard = telegramSenderGuard(caller, runtime ?? peer.runtime, personality)
   if (!intendedGuard.ok) return intendedGuard
 
+  // Attachment ownership boundary: caller paths are SOURCES only. Materialize
+  // recipient-owned, content-addressed copies BEFORE building any live/wake/queue
+  // envelope. Every path below (including ephemeral/composer queues and bridge
+  // runtimes) therefore has the same durability semantics. Copy failure is a
+  // synchronous NOT-delivered error; no route side effect has happened yet.
+  const spooled = spoolAttachments(attachmentsResult.value, peer.personality, env)
+  if (!spooled.ok) return spooled
+
   // Stamped ONCE at router acceptance: the same instant travels as the envelope's
   // `ts` attribute (recipient side) AND is returned as the result's `ts` (sender
   // side) — the two correspond literally, which is what makes async-desync
@@ -1547,7 +1571,7 @@ async function routeSendInner(
     fromIntelligence: caller.intelligence,
     sentAt,
     topic,
-    attachments: attachmentsResult.value,
+    attachments: spooled.value.paths,
     message,
   })
 

package/src/update/index.ts

@@ -36,7 +36,8 @@ import { join } from 'path'
 import { isInfraRuntime } from '../core/constants.ts'
 import { IapError } from '../core/errors.ts'
 import { IAPEER_VERSION } from '../core/version.ts'
-import { stampBinaryHealthy } from '../install/index.ts'
+import { iapeerBinPath, stampBinaryHealthy } from '../install/index.ts'
+import { ensureExecutableSignature } from '../install/signature.ts'
 import { readPeersIndex } from '../registry/index.ts'
 import {
   cycleDaemon,
@@ -71,6 +72,9 @@ export interface UpdateDeps {
   /** Pull + rebuild the binary for `version` (default: npm pack → extract → source install).
    *  Returns true on success. */
   runInstall?: (version: string, env: NodeJS.ProcessEnv) => boolean
+  /** Verify-only installed-binary gate, including same-version stale-daemon heal.
+   *  Never repair a live binary. The package installer owns staged repair. */
+  verifyInstalledSignature?: (env: NodeJS.ProcessEnv) => void
   /** Restart the daemon onto the new binary (default: cycleDaemon — bootout+bootstrap, the LWCR-safe cycle). */
   restartDaemon?: (env: NodeJS.ProcessEnv) => DaemonRestartResult
   /** Re-register loaded foundation-owned infra launchd jobs whose plists run the
@@ -345,7 +349,20 @@ export async function updateIapeer(deps: UpdateDeps = {}): Promise<UpdateResult>
         : `could not resolve the latest ${IAPEER_PACKAGE} version from npm (offline / registry error)`,
     }
   }
+  const verifyInstalled = (): string | undefined => {
+    try {
+      if (deps.verifyInstalledSignature) deps.verifyInstalledSignature(env)
+      else ensureExecutableSignature(iapeerBinPath(env), { env, repair: false })
+      return undefined
+    } catch (e) {
+      return `installed foundation signature is invalid; no restart attempted: ${e instanceof Error ? e.message : String(e)}`
+    }
+  }
   if (desired === from && !deps.force) {
+    // Same-version heal is an activation path too: a valid running inode/version
+    // does not prove the current on-disk binary is safe to restart.
+    const signatureFailure = verifyInstalled()
+    if (signatureFailure) return { status: 'failed', from, latest: desired, reason: signatureFailure }
     // В53 — the binary is at the target, but is the LIVE daemon running it? A prior
     // update that swapped the binary and then died before/inside cycleDaemon leaves
     // the fleet on the old core FOREVER while every retry says "already-latest".
@@ -384,6 +401,9 @@ export async function updateIapeer(deps: UpdateDeps = {}): Promise<UpdateResult>
     }
   }
 
+  const signatureFailure = verifyInstalled()
+  if (signatureFailure) return { status: 'failed', from, latest: desired, reason: signatureFailure }
+
   const d = (deps.restartDaemon ?? cycleDaemon)(env)
   const settled = await settleDaemon(d, env, deps)
   return {