@agfpd/iapeer 0.4.108 → 0.4.110

package/CHANGELOG.md

@@ -10,6 +10,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **IAP attachments now transfer ownership instead of forwarding fragile source paths.**
+  Every `send_to_peer`, `iapeer send`, and Fleet API send copies regular-file sources
+  into the target peer's durable, content-addressed foundation inbox before an
+  envelope can be accepted. The recipient can read or forward the copy after the
+  sender deletes `/tmp` or otherwise removes the source. Copies live for the
+  recipient peer's lifetime and `iapeer remove` purges its inbox.
+
 ## [0.4.25] - 2026-06-22
 
 ### Fixed

package/docs/06-storage.md

@@ -26,6 +26,7 @@ The same plugin can store data at both levels: shared in `~/.iapeer/`, peer-boun
 │       └── .iapeer/           (peer-level layout — see below)
 ├── state/
 │   ├── iapeer/                daemon state (router.sock, router.json …)
+│   │   └── attachments/       recipient-owned IAP attachment copies
 │   └── <plugin>/              a plugin's mutable state
 ├── logs/
 │   ├── iapeer/                daemon logs: lifecycle.log, delivery.log, exits.log
@@ -53,7 +54,7 @@ The same plugin can store data at both levels: shared in `~/.iapeer/`, peer-boun
 A few nodes worth highlighting:
 
 - **`peers-profiles.json`** — the registry. Written only through a single writer under the file lock `peers-profiles.lock`; direct editing is forbidden at the core level.
-- **`state/iapeer/`** — where the daemon lives: its local socket `router.sock` and config `router.json`.
+- **`state/iapeer/`** — where the daemon lives: its local socket `router.sock`, config `router.json`, and `attachments/<recipient>/<sha256>/<basename>` inboxes. Attachment inboxes are durable recipient state (not cache); peer removal cleans that recipient's inbox.
 - **`logs/<name>/`** — an infrastructure peer's logs are placed by peer name at the shared level (not in the peer's folder), because it's the output of a launchd service.
 - **`runtimes/<runtime>/`** — dual ownership: the root belongs to the runtime itself (Telegram keeps bot tokens and poll state here), while the `plugins/<plugin>/` subfolder is the plugins' space, holding their config under this runtime.
 - **`docs/<package>/`** — on-host reference docs, one folder per ecosystem package (see below).

package/docs/10-messaging.md

@@ -23,6 +23,18 @@ iapeer send assistant --message "..." --topic "release" --from claude-reviewer
 
 The `--from` flag sets the sender (`<runtime>-<name>`); by default it's the identity of the current folder's peer. `--attachment` is repeatable. `--message-file`, with the body from a file or stdin, is handy for long, multi-line messages.
 
+## Attachment ownership
+
+An attachment argument is a **source path**, not the delivered path. `routeSend` opens every source as a regular file and copies its bytes into the target peer's foundation-owned inbox before it builds the envelope:
+
+```text
+~/.iapeer/state/iapeer/attachments/<recipient>/<sha256>/<basename>
+```
+
+The envelope contains these absolute inbox paths. Therefore an `ok`/`delivered`/`queued` result also means that every attachment already has a readable recipient copy; the sender may immediately delete or rename its source. A missing, unreadable, or non-regular source fails the send before delivery. Re-sending an inbox file to a third peer makes another copy in that third peer's inbox.
+
+The copy is recipient-owned state, not cache: it is not age-GCed and lives for the recipient peer's lifetime. `iapeer remove <recipient>` removes the complete inbox. Removing the sender, cleaning `/tmp`, restarting the daemon, draining an ephemeral queue, and bridge history rotation do not remove it.
+
 ## The delivery path
 
 The daemon finds the recipient in the registry and selects its endpoint first. With no explicit `runtime`, the endpoint is always the recipient's `default_runtime`; liveness of other declared runtimes does not change that choice. An explicit `runtime` selects that exact surface. The daemon then looks at the selected endpoint's state:

package/docs/12-cli-reference.md

@@ -61,7 +61,7 @@ The full list of `iapeer <command>`. General rules: `--help` / `-h` anywhere in
 | `send <target> (--message <text> \| --message-file <f\|->) [--from <id>] [--runtime <r>] [--attachment <path>]… [--topic <t>]` | Manual IAP send over the same path as `send_to_peer`. |
 | `confirm-send <id> [--runtime <rt>]` | Deliver a held send ([origin guard](18-origin-guard.md)): as addressed, or `--runtime` redirects it to the origin channel. No re-send of the message text. |
 
-`--message-file -` reads the body from stdin. `--attachment` is repeatable. `--from` defaults to the current folder's peer identity.
+`--message-file -` reads the body from stdin. `--attachment` is repeatable and names an absolute source file; the router copies it into recipient-owned state before accepting the send. `--from` defaults to the current folder's peer identity.
 
 ## Launch and runtimes
 

package/docs/13-architecture-and-contract.md

@@ -13,6 +13,7 @@ The system's behavior rests on these:
 - **A single registry writer.** `peers-profiles.json` is written only through one writer under a file lock. Direct writing of the file is forbidden at the core level — this rules out races.
 - **Liveness is defined by a peer's live session.** A peer is alive if and only if it has a live session under the supervisor. This isn't a separate state flag that can desync, but an observable fact.
 - **`delivered` ⟺ landed in a live session.** Delivery success means the message was accepted by a live session (the daemon waited for confirmation). If it didn't confirm — the daemon treats the session as dead rather than lying about success.
+- **Attachments are copied before routing.** Caller paths are only sources. Before an envelope can be accepted as delivered or queued, `routeSend` copies every attachment into the target peer's foundation-owned inbox and puts those copy paths into the envelope. A later delete, rename, or cleanup of the caller's source cannot break the received attachment. The copies live for the lifetime of the recipient peer and `iapeer remove <peer>` removes that inbox.
 - **The source of truth is the local profile.** The registry is a reprojectable projection of the peer profiles. On a divergence, the profile wins.
 - **The binary is installed on the host.** The daemon runs from the installed `~/.local/bin/iapeer`, not from a source working tree. An update is replacing the binary and restarting the daemon onto it.
 

package/docs/15-fleet-api.md

@@ -203,10 +203,10 @@ What the headline states look like on the stream: a peer **waking** is `ev=wake`
 `POST /fleet/v1/send` — deliver a message through the same routing path as the `send_to_peer` tool (wake-on-miss, queueing, delivery log — identical semantics):
 
 ```json
-{ "personality": "boris", "message": "…", "runtime": "claude", "topic": "…", "from": "nova" }
+{ "personality": "boris", "message": "…", "runtime": "claude", "topic": "…", "attachments": ["/tmp/report.pdf"], "from": "nova" }
 ```
 
-`from` is optional: a full `<runtime>-<personality>`, or a bare personality (its default runtime). Default: the **single natural-intelligence peer** of the registry — a GUI-originated message is the human's. With zero or several natural peers the request is refused (`400`) with an instruction to pass `from`.
+`from` is optional: a full `<runtime>-<personality>`, or a bare personality (its default runtime). Default: the **single natural-intelligence peer** of the registry — a GUI-originated message is the human's. With zero or several natural peers the request is refused (`400`) with an instruction to pass `from`. `attachments`, when present, is the same array of absolute source paths as the MCP tool; the shared `routeSend` path copies them into the recipient inbox before acceptance.
 
 Not part of the *command* API, deliberately: **attach** (a terminal handoff — a client opens the system terminal with `iapeer attach <peer>`), registry/host **admin verbs** (`create`/`remove`/`update`/`uninstall` — will be added when a client actually needs them). The **human-approval broker** now lives under `/fleet/v1/approvals*` (`GET` the queue / one item, `POST /<id>/(approve|deny)`) with the `approval-request` / `approval-resolved` SSE `ev` kinds and the `approvals` snapshot field above — the full contract is **docs/17-approval**. The **notice board** lives under `/fleet/v1/notices*` (`GET` the board / one item — **read-only**: a notice is one-way and has nothing to resolve) with the `notice-raised` SSE `ev` kind and the `notices` snapshot field above — the full contract is **docs/19-notices**.
 

package/docs/18-origin-guard.md

@@ -30,7 +30,7 @@ verbatim as og-1a2b3c4d (expires in 15 min).
 Do not re-send the message text — confirm-send delivers the held message.
 ```
 
-Both exits cost one shell command and **zero message regeneration**: the held send carries the full original input (message, topic, attachments).
+Both exits cost one shell command and **zero message regeneration**: the held send carries the original message/topic/runtime and recipient-owned copies of every attachment. Copying happens before the hold is persisted, so deleting a caller's temporary sources during the 15-minute decision window cannot break `confirm-send`.
 
 ```bash
 iapeer confirm-send og-1a2b3c4d                 # deliver as addressed (intentional cross-channel)
@@ -48,7 +48,7 @@ State is on disk (it must survive daemon restarts and short-lived CLI processes)
 ```text
 ~/.iapeer/state/iapeer/origin/
   state.json          # (agent → human → {rt, inboundTs, answeredTs}) — last-wins, atomic writes
-  pending/<id>.json   # held sends, verbatim; lazily GC'd past the pending TTL
+  pending/<id>.json   # held sends; attachment fields already name recipient-inbox copies
 ```
 
 ## Scope and non-interference

package/docs/ru/06-/321/205/321/200/320/260/320/275/320/265/320/275/320/270/320/265.md

@@ -26,6 +26,7 @@
 │       └── .iapeer/           (раскладка уровня пира — см. ниже)
 ├── state/
 │   ├── iapeer/                состояние демона (router.sock, router.json …)
+│   │   └── attachments/       копии IAP-вложений, принадлежащие получателям
 │   └── <плагин>/              изменяемое состояние плагина
 ├── logs/
 │   ├── iapeer/                журналы демона: lifecycle.log, delivery.log, exits.log
@@ -53,7 +54,7 @@
 Несколько узлов стоит выделить:
 
 - **`peers-profiles.json`** — реестр. Пишется только через единственного писателя под файловой блокировкой `peers-profiles.lock`; прямое редактирование запрещено на уровне ядра.
-- **`state/iapeer/`** — здесь живёт демон: его локальный сокет `router.sock` и конфигурация `router.json`.
+- **`state/iapeer/`** — здесь живёт демон: его локальный сокет `router.sock`, конфигурация `router.json` и inbox-каталоги `attachments/<получатель>/<sha256>/<имя-файла>`. Inbox — долгоживущее состояние получателя, а не кэш; удаление пира очищает его inbox.
 - **`logs/<имя>/`** — журналы инфраструктурных пиров кладутся по имени пира на общем уровне (а не в папке пира), потому что это вывод службы под launchd.
 - **`runtimes/<рантайм>/`** — двойное владение: корень принадлежит самому рантайму (Telegram держит здесь токены ботов, состояние опроса), а подпапка `plugins/<плагин>/` — это пространство плагинов, где лежит их конфиг под этим рантаймом.
 - **`docs/<пакет>/`** — справочные доки на хосте, по одной папке на каждый пакет экосистемы (см. ниже).

package/docs/ru/10-/320/276/320/261/320/274/320/265/320/275-/321/201/320/276/320/276/320/261/321/211/320/265/320/275/320/270/321/217/320/274/320/270.md

@@ -23,6 +23,18 @@ iapeer send assistant --message "..." --topic "релиз" --from claude-reviewe
 
 Флаг `--from` задаёт отправителя (`<рантайм>-<имя>`); по умолчанию — идентичность пира текущей папки. `--attachment` повторяемый. `--message-file` с телом из файла или stdin удобен для длинных и многострочных сообщений.
 
+## Владение вложениями
+
+Аргумент вложения — **путь источника**, а не доставленный путь. До сборки конверта `routeSend` открывает каждый источник как обычный файл и копирует его байты в foundation-owned inbox целевого пира:
+
+```text
+~/.iapeer/state/iapeer/attachments/<получатель>/<sha256>/<имя-файла>
+```
+
+В конверт попадают абсолютные пути этих копий. Поэтому исход `ok`/`delivered`/`queued` одновременно значит, что каждое вложение уже имеет читаемую копию получателя; отправитель может сразу удалить или переименовать исходник. Отсутствующий, нечитаемый или необычный файл валит отправку до доставки. Пересылка inbox-файла третьему пиру создаёт отдельную копию в inbox третьего пира.
+
+Копия — состояние получателя, а не кэш: по возрасту не удаляется и живёт столько же, сколько пир-получатель. `iapeer remove <получатель>` удаляет весь inbox. Удаление отправителя, очистка `/tmp`, рестарт демона, дренаж ephemeral-очереди и ротация истории моста её не удаляют.
+
 ## Путь доставки
 
 Демон находит получателя в реестре и сначала выбирает поверхность доставки. Без явного `runtime` это всегда `default_runtime` адресата; живость других объявленных рантаймов выбор не меняет. Явный `runtime` выбирает ровно указанную поверхность. Затем демон смотрит на состояние выбранной поверхности:

package/docs/ru/12-cli-reference.md

@@ -61,7 +61,7 @@
 | `send <цель> (--message <текст> \| --message-file <f\|->) [--from <id>] [--runtime <r>] [--attachment <путь>]… [--topic <t>]` | Ручная отправка IAP по тому же пути, что `send_to_peer`. |
 | `confirm-send <id> [--runtime <rt>]` | Доставить удержанную отправку ([origin guard](18-origin-guard.md)): как адресована, либо `--runtime` перенаправляет её в канал-источник. Без повторной отправки текста. |
 
-`--message-file -` читает тело из stdin. `--attachment` повторяемый. `--from` по умолчанию — идентичность пира текущей папки.
+`--message-file -` читает тело из stdin. `--attachment` повторяемый и задаёт абсолютный путь файла-источника; до принятия отправки роутер копирует его в состояние получателя. `--from` по умолчанию — идентичность пира текущей папки.
 
 ## Запуск и рантаймы
 

package/docs/ru/13-/320/260/321/200/321/205/320/270/321/202/320/265/320/272/321/202/321/203/321/200/320/260-/320/270-/320/272/320/276/320/275/321/202/321/200/320/260/320/272/321/202.md

@@ -13,6 +13,7 @@
 - **Единственный писатель реестра.** `peers-profiles.json` пишется только через одного писателя под файловой блокировкой. Прямая запись файла запрещена на уровне ядра — это исключает гонки.
 - **Живость определяется live-сессией пира.** Пир жив тогда и только тогда, когда у него есть живая сессия под супервизором. Это не отдельный флаг в состоянии, который можно рассинхронизировать, а наблюдаемый факт.
 - **`доставлено` ⟺ легло в живую сессию.** Успех доставки означает, что сообщение принято живой сессией (демон дождался подтверждения). Не подтвердила — демон считает сессию мёртвой, а не лжёт об успехе.
+- **Вложения копируются до маршрутизации.** Пути вызывающего — только источники. Прежде чем конверт может быть принят как delivered или queued, `routeSend` копирует каждое вложение в принадлежащий foundation inbox целевого пира и вкладывает в конверт уже пути копий. Последующие удаление, переименование или очистка исходника не ломают полученное вложение. Копии живут столько же, сколько пир-получатель; `iapeer remove <пир>` удаляет его inbox.
 - **Источник истины — локальный профиль.** Реестр — пересобираемая проекция профилей пиров. При расхождении прав профиль.
 - **Бинарь установлен на хост.** Демон работает с установленного `~/.local/bin/iapeer`, а не из рабочего дерева исходников. Обновление — это замена бинаря и перезапуск демона на него.
 

package/docs/ru/15-fleet-api.md

@@ -133,10 +133,10 @@ GET /fleet/v1/events?replay=50
 `POST /fleet/v1/send` — доставить сообщение тем же маршрутом, что инструмент `send_to_peer` (wake-on-miss, очереди, delivery-лог — семантика идентична):
 
 ```json
-{ "personality": "boris", "message": "…", "runtime": "claude", "topic": "…", "from": "nova" }
+{ "personality": "boris", "message": "…", "runtime": "claude", "topic": "…", "attachments": ["/tmp/report.pdf"], "from": "nova" }
 ```
 
-`from` опционален: полный `<runtime>-<personality>` или голая personality (её default-рантайм). По умолчанию — **единственный natural-intelligence пир** реестра: сообщение из GUI принадлежит человеку. При нуле или нескольких natural-пирах запрос отклоняется (`400`) с указанием передать `from`.
+`from` опционален: полный `<runtime>-<personality>` или голая personality (её default-рантайм). По умолчанию — **единственный natural-intelligence пир** реестра: сообщение из GUI принадлежит человеку. При нуле или нескольких natural-пирах запрос отклоняется (`400`) с указанием передать `from`. `attachments`, если передан, — тот же массив абсолютных путей источников, что и у MCP-инструмента; общий путь `routeSend` копирует их в inbox получателя до принятия.
 
 Не входит в *командный* API, намеренно: **attach** (передача терминала — клиент открывает системный терминал с `iapeer attach <peer>`), реестровые/хостовые **admin-verb'ы** (`create`/`remove`/`update`/`uninstall` — добавятся, когда появится клиент с реальной потребностью). **Брокер human-approval** теперь живёт под `/fleet/v1/approvals*` (`GET` очередь / один item, `POST /<id>/(approve|deny)`) с видами SSE `approval-request` / `approval-resolved` и полем `approvals` в снапшоте выше — полный контракт в **docs/17-approval**.
 

package/docs/ru/18-origin-guard.md

@@ -30,7 +30,7 @@ verbatim as og-1a2b3c4d (expires in 15 min).
 Do not re-send the message text — confirm-send delivers the held message.
 ```
 
-Оба выхода стоят одну shell-команду и **ноль регенерации сообщения**: удержанная отправка несёт полный исходный ввод (текст, топик, вложения).
+Оба выхода стоят одну shell-команду и **ноль регенерации сообщения**: удержанная отправка несёт исходные текст/топик/рантайм и принадлежащие получателю копии каждого вложения. Копирование идёт до сохранения hold, поэтому удаление временных исходников в 15-минутном окне решения не ломает `confirm-send`.
 
 ```bash
 iapeer confirm-send og-1a2b3c4d                 # доставить как адресовано (кросс-канал намеренный)
@@ -48,7 +48,7 @@ iapeer confirm-send og-1a2b3c4d --runtime web   # доставить то же
 ```text
 ~/.iapeer/state/iapeer/origin/
   state.json          # (агент → человек → {rt, inboundTs, answeredTs}) — last-wins, атомарные записи
-  pending/<id>.json   # удержанные отправки, дословно; ленивый GC после TTL
+  pending/<id>.json   # удержанные отправки; вложения уже указывают на копии inbox
 ```
 
 ## Границы и невмешательство

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.108",
+  "version": "0.4.110",
   "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

@@ -26,7 +26,15 @@ import { cascadeTail, recycleFoundationOwnedInfraJobs, updateIapeer, waitForDaem
 import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/socket.ts'
 import { ensureGlobalIapScaffold } from '../storage/index.ts'
 import { findPeer, readPeersIndex, removePeer, type PeerRecord } from '../registry/index.ts'
-import { compactDoneBaseline, isPeerLive, routeControl, routeSend, waitForCompactDone, type WakeFn } from '../transport/index.ts'
+import {
+  compactDoneBaseline,
+  isPeerLive,
+  purgeAttachmentInbox,
+  routeControl,
+  routeSend,
+  waitForCompactDone,
+  type WakeFn,
+} from '../transport/index.ts'
 import {
   attachPeer,
   clearIdleReaped,
@@ -888,6 +896,9 @@ export interface RemoveOutcome {
    *  personality inherits the dead namesake's parking (defect: stale .stopped →
    *  `mode=refused cause=stopped` on a freshly-created peer). */
   purgedState?: string[]
+  /** Recipient-owned IAP attachment inbox cleanup. Completed attachment copies
+   *  are state for the peer lifetime, so explicit peer removal owns their purge. */
+  attachmentInbox?: string
 }
 
 /**
@@ -1039,11 +1050,19 @@ export async function removePeerCli(
   // remove never half-purges a still-registered peer.
   const cfg = loadLifecycleConfig(env)
   const purgedState = peer.runtimes.flatMap(rt => purgeIdentityState(cfg, buildProcessAddress(rt, personality)))
+  let attachmentInbox: string | undefined
+  try {
+    const purged = purgeAttachmentInbox(personality, env)
+    if (purged.removed) attachmentInbox = `removed ${purged.path}`
+  } catch (e) {
+    attachmentInbox = `FAILED: ${e instanceof Error ? e.message : String(e)}`
+  }
   return {
     personality,
     action: 'removed',
     cwd: peer.cwd,
     purgedState,
+    ...(attachmentInbox ? { attachmentInbox } : {}),
     ...(plistTeardown ? { plistTeardown } : {}),
     ...(unprovisionOutcomes.length ? { unprovision: unprovisionOutcomes } : {}),
     ...(trustCleaned ? { codexTrust: trustCleaned } : {}),
@@ -2280,6 +2299,9 @@ 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.attachmentInbox) {
+            out(`attachment inbox: ${o.attachmentInbox}\n`)
+          }
           // Deliberate: the registry reap never deletes user data — but SAY so, or
           // the default-location peers leave silent orphan folders.
           if (o.cwd && existsSync(o.cwd)) {

package/src/daemon/fleet.ts

@@ -658,7 +658,13 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
           return sendJson(res, 400, { error: e instanceof Error ? e.message : String(e) })
         }
         if (typeof body.personality !== 'string' || !body.personality || typeof body.message !== 'string' || !body.message) {
-          return sendJson(res, 400, { error: 'send needs {personality, message} (+ optional runtime/topic/from)' })
+          return sendJson(res, 400, { error: 'send needs {personality, message} (+ optional runtime/topic/attachments/from)' })
+        }
+        if (
+          body.attachments !== undefined &&
+          (!Array.isArray(body.attachments) || !body.attachments.every(item => typeof item === 'string'))
+        ) {
+          return sendJson(res, 400, { error: 'send attachments must be an array of absolute local source-file paths' })
         }
         let caller: ResolvedCaller
         try {
@@ -676,6 +682,7 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
             runtime: typeof body.runtime === 'string' ? body.runtime : undefined,
             message: body.message,
             topic: typeof body.topic === 'string' ? body.topic : undefined,
+            attachments: Array.isArray(body.attachments) ? body.attachments : undefined,
           },
           ctx.deps,
         )

package/src/daemon/index.ts

@@ -163,7 +163,7 @@ export function listTools(): unknown[] {
           topic: { type: 'string', description: 'Optional short topic for threading related peer messages.', maxLength: MAX_TOPIC_LEN },
           attachments: {
             type: 'array',
-            description: 'Optional absolute local file paths. IAP delivers them as a separate <attachments> field, not as part of message text.',
+            description: 'Optional absolute local source-file paths. Before accepting the send, IAP copies each regular file into durable recipient-owned state and puts the copy paths in the separate <attachments> field; the sources may be deleted immediately after success.',
             maxItems: MAX_ATTACHMENTS,
             items: { type: 'string' },
           },

package/src/supervisor/client.ts

@@ -3,7 +3,7 @@
 // port-deps live here + in protocol.ts: #1 TERM_RESET on EVERY exit path (incl. SIGHUP window-close,
 // via writeSync which works inside a signal handler), and #2 backpressure is the daemon's side.
 import { writeSync } from 'node:fs'
-import { FRAME_DATA, FRAME_RESIZE, TERM_RESET, frame, makeFramer, sizePayload } from './protocol.ts'
+import { FRAME_DATA, FRAME_RESIZE, TERM_ATTACH_RESET, TERM_RESET, frame, makeFramer, sizePayload } from './protocol.ts'
 import { ownershipVerdict, pidStartToken, readPidFile, sockPath } from './paths.ts'
 
 const DETACH = 0x1d // Ctrl-]
@@ -81,6 +81,17 @@ export async function runSupervisorClient(runDir: string, session: string): Prom
   // Ready the terminal BEFORE connecting, so the repaint snapshot renders the instant it arrives.
   if (process.stdin.isTTY) process.stdin.setRawMode(true)
   process.stdin.resume()
+  // The daemon owns the emulated session/model; THIS client owns the physical operator viewport.
+  // Normalize that viewport before connecting so its one-time snapshot cannot be appended below a
+  // shell prompt or a prior attach's differently-wrapped frame. HOME+ED0 is intentional: unlike
+  // ED2/ED3 it does not trigger Apple Terminal's clear-to-scrollback trap (protocol.ts).
+  if (process.stdout.isTTY) {
+    try {
+      writeSync(1, TERM_ATTACH_RESET)
+    } catch {
+      /* a failed cosmetic reset must not block attach */
+    }
+  }
 
   const curSize = (): Buffer => sizePayload(process.stdout.columns || 80, process.stdout.rows || 24)
   const sock = await Bun.connect({
@@ -142,9 +153,9 @@ export async function runSupervisorClient(runDir: string, session: string): Prom
     })
   }
   process.on('exit', () => restore()) // last-resort sync net
-  // NO pre-repaint attach banner: any stdout (even stderr — same tty device) printed before the daemon's
-  // snapshot lands pollutes the fresh terminal's scrollback, defeating native-history reconstruction. The
-  // detach key (Ctrl-]) is documented in CLI help / the attach verb, not emitted as a scrollback line.
+  // NO pre-repaint attach banner: after TERM_ATTACH_RESET, the daemon snapshot must be the first CONTENT
+  // painted into the normalized viewport. The detach key (Ctrl-]) is documented in CLI help / the attach
+  // verb, not emitted as a scrollback line.
   // STAY ATTACHED. The client lives on its handles (raw stdin + the socket); EVERY terminal path
   // (detach Ctrl-], session-end close(), SIGHUP/SIGTERM, socket error) calls process.exit ITSELF.
   // This promise INTENTIONALLY never resolves: returning here would resolve runSupervisorClient the

package/src/supervisor/daemon.ts

@@ -399,8 +399,9 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
    *  Scrollback rows are spinner-stripped; the viewport stays verbatim. The child's SIGWINCH redraw (from
    *  applyGeometry) then settles the live viewport at the client's width. Backpressure-safe
    *  (BackpressureWriter) — a large snapshot MUST NOT drop past the socket buffer (port-dep #2). Called
-   *  EXACTLY ONCE per client (its first FRAME_RESIZE). NO clears (\x1b[2J/3J): a fresh window needs none,
-   *  and Apple Terminal scrolls 2J into scrollback + ignores 3J. */
+   *  EXACTLY ONCE per client (its first FRAME_RESIZE). The daemon/model sends NO clears
+   *  (\x1b[2J/3J): Apple Terminal scrolls 2J into scrollback + ignores 3J. The attach client owns its
+   *  physical viewport and normalizes it once with HOME+ED0 before connecting. */
   // Await until the model has parsed ALL writes AND none arrived during the wait (stable). Awaiting a single
   // write promise is not enough: while the client is gated (initializing, live-forward skipped) new child
   // bytes still land in the model and bump writeSeq — loop until the sequence holds steady so the snapshot

package/src/supervisor/protocol.ts

@@ -164,6 +164,18 @@ export function keysToBytes(keys: string[], enc: KeyEncoding = {}): Buffer {
   return Buffer.from(out, 'utf8')
 }
 
+// ── client terminal normalization ────────────────────────────────────────────────
+// A (re)attach can start in an already-used Terminal.app normal buffer: the shell prompt and a prior
+// attach's differently-wrapped frame still occupy the physical viewport. The daemon's serialized model
+// deliberately carries NO clear (it is shared protocol data, while the stale viewport belongs to each
+// client), so the client must home + erase the CURRENT display before the one-time snapshot arrives.
+//
+// Use ED0 from HOME, NOT ED2/ED3. Apple Terminal implements neither of the latter as the primitive we
+// need: ED2 pushes the old display into native scrollback and ED3 is ignored, so repeated attaches stack
+// broken-width dumps in history. HOME+ED0 clears the viewport in place; the daemon still sends exactly
+// one model snapshot and later SIGWINCH resizes remain raw/live (no repeated dump).
+export const TERM_ATTACH_RESET = '\x1b[H\x1b[J'
+
 // ── port-dep #1: terminal reset on every client exit path ───────────────────────
 // The child sets a STACK of app-modes on the live terminal (alt-screen, bracketed-paste,
 // focus-events, theme-update, ALL mouse tracking, kitty-keyboard, scroll-region, hidden cursor).

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,
   })