@agfpd/iapeer 0.4.89 → 0.4.91

package/docs/10-messaging.md

@@ -85,3 +85,7 @@ A peer with the wake policy `wake_policy: "ephemeral"` in its profile works diff
 - **`iapeer self-done`** — a self-call by a worker that has nothing to send: it frees the queue for the next task without waking anyone. The doctrine is "nothing to send — `self-done` instead of an empty reply".
 
 This model keeps a stream of one-off tasks orderly: one worker per task, with no accumulation of parallel sessions and no empty wakes of the recipient.
+
+## Replying to a human: the origin guard
+
+An agent's reply to a human must land in the channel the human wrote from. The router enforces this mechanically: while the human's latest message to that agent is unanswered, a send targeting a *different* channel is held for a one-command confirmation (`iapeer confirm-send <id>`) instead of being delivered. Same-channel replies and initiative pass with no friction. The full contract — the armed-pair model, TTLs, `confirm-send` — is [18 — Origin guard](18-origin-guard.md).

package/docs/12-cli-reference.md

@@ -59,6 +59,7 @@ The full list of `iapeer <command>`. General rules: `--help` / `-h` anywhere in
 | Command | What it does |
 |---|---|
 | `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.
 

package/docs/17-approval.md

@@ -1,6 +1,6 @@
 # 17 — Human approval
 
-A peer can run in one of two **approval modes**. In `yolo` (the default — every peer today) the agent acts autonomously: the runtime is launched with its bypass flag and nothing asks a human before a tool runs. In `gated` the peer is launched **without** bypass, and every blocking approval the runtime would raise is routed to a **human** through the daemon's approval broker — a Telegram button, a tray click, or `iapeer approve` on the CLI. The human's `allow`/`deny` (with a reason) flows back into the runtime and the tool proceeds or is refused.
+A peer can run in one of two **approval modes**. In `yolo` (the default — every peer today) the agent acts autonomously: the runtime is launched with its bypass flag and nothing asks a human before a tool runs. In `gated` the peer is launched **without** bypass, and every blocking approval the runtime would raise is routed to a **human** through the daemon's approval broker — a Telegram button, a tray click, `iapeer approve` on the CLI, or the web console's approvals panel. The human's `allow`/`deny` (with a reason) flows back into the runtime and the tool proceeds or is refused.
 
 This is a **normative contract**. The approval broker is the daemon's, the fleet endpoints and `ev` kinds below are the surface that operator faces (CLI, tray, the Telegram runtime) are written against — not the daemon source. The interception facts (which runtime event fires, in which shape) are pinned to **Claude Code 2.1.201** and **codex-cli 0.142.5**, taken from the live binaries + current runtime docs.
 
@@ -103,7 +103,7 @@ An unknown tool falls back to a pretty-printed `tool_input`, so nothing is opaqu
 
 ## The broker (single source of truth)
 
-The approval queue lives **in the daemon** (the always-on process). Every channel that asks (the runtime hook, the supervisor breaker) and every channel that answers (CLI, tray, the Telegram runtime) is an interface to this one queue: a decision from any face resolves the request everywhere. In-memory + ephemeral — pending requests do **not** survive a daemon restart (the blocking hook connection breaks → the hook fails safe to deny); the durable `approvals.log` is the audit trace, not a recovery store.
+The approval queue lives **in the daemon** (the always-on process). Every channel that asks (the runtime hook, the supervisor breaker) and every channel that answers (CLI, tray, the Telegram runtime, the web console) is an interface to this one queue: a decision from any face resolves the request everywhere. In-memory + ephemeral — pending requests do **not** survive a daemon restart (the blocking hook connection breaks → the hook fails safe to deny); the durable `approvals.log` is the audit trace, not a recovery store.
 
 Flow: the gated peer's hook (or the supervisor breaker) blocks on `POST /fleet/v1/approvals` → the broker enqueues, emits `approval-request` (to `approvals.log` → SSE), and holds the connection → a face answers via `POST /fleet/v1/approvals/<id>/(approve|deny)` → the promise resolves, the daemon writes the runtime hook JSON back, the tool proceeds or is blocked with the reason.
 
@@ -118,7 +118,7 @@ The approval surface is served on both daemon listeners under `/fleet/v1`, same
 **Events** (compact logfmt line → SSE JSON; the full content is *not* in the event — read the queue for it):
 
 - `approval-request` — `id, personality, runtime, kind, tool, summary, created, expires, approvers`.
-- `approval-resolved` — `id, personality, runtime, decision (allow|deny), reason, by (approver), via (cli|tray|telegram|timeout|disconnect), latencyMs`.
+- `approval-resolved` — `id, personality, runtime, decision (allow|deny), reason, by (approver), via (cli|tray|telegram|web|timeout|disconnect), latencyMs`. `via` is the surface the decision came from, **self-declared by the answering face** in its `POST` body (free-form-tolerant, like `kind`; `timeout`/`disconnect` are broker-internal). A face that did not self-identify gets the field **omitted** — the audit line never guesses a surface.
 
 **Endpoints:**
 
@@ -126,12 +126,14 @@ The approval surface is served on both daemon listeners under `/fleet/v1`, same
 |---|---|
 | `GET /fleet/v1/approvals` | list pending requests (full items) |
 | `GET /fleet/v1/approvals/<id>` | one pending request, full `content` (the multi-line diff / plan / command) |
-| `POST /fleet/v1/approvals/<id>/approve` | `{approver?}` → allow |
-| `POST /fleet/v1/approvals/<id>/deny` | `{reason?, approver?}` → deny (reason to the model) |
+| `POST /fleet/v1/approvals/<id>/approve` | `{approver?, via?}` → allow |
+| `POST /fleet/v1/approvals/<id>/deny` | `{reason?, approver?, via?}` → deny (reason to the model) |
 | `POST /fleet/v1/approvals` | the **blocking long-poll** the asking hook/breaker holds: `{personality, runtime, kind, tool, content, summary?}` → `{id, decision, reason?}` |
 
 `kind` is the taxonomy tag (`tool` | `plan` | `question` | `circuit-breaker`; free-form-tolerant). So the SSE/badge stays light while the full content is available in every channel through the two `GET`s.
 
+`via` on approve/deny is the answering face's **self-identification of its surface** for the audit trail: the CLI sends `cli`, the tray `tray`, the Telegram runtime `telegram`, the web console `web`. A face MUST send it (the log omits `via` otherwise); the broker passes it through verbatim into `approvals.log`.
+
 ## CLI
 
 - `iapeer approvals [--json]` — the pending queue: personality · runtime · kind · **the verbatim command/content** · age · id.

package/docs/18-origin-guard.md

@@ -0,0 +1,66 @@
+# 18 — Origin guard
+
+[Русский](ru/18-origin-guard.md) · **English**
+
+When a human writes to an agent from one channel (say, the web console) and the agent replies into another (say, Telegram), the reply lands where the human is not looking. Until now this error class was held back only by agent doctrine («reply where the message came from») — memory, not mechanics. The **origin guard** enforces it at the router: an agent's *reply* to a human must target the channel the human last wrote from, or it is **held** for an explicit one-command confirmation instead of being delivered.
+
+This is a **normative contract** for the guard's behavior, state, and CLI surface.
+
+## What counts as a reply
+
+The guard keeps one entry per **(human, agent)** pair — humans are peers with `intelligence: natural`:
+
+- an ok **human → agent** delivery stamps the pair: the human's channel (`rt` = the sender's runtime) and the instant (`inboundTs`);
+- an ok **agent → human** delivery stamps `answeredTs`.
+
+The pair is **armed** when the latest inbound is *unanswered* (`inboundTs > answeredTs`) and younger than the arm TTL (48 h by default). An agent's send to the human **while armed is presumed a reply** and must target the origin channel. Once answered — or once the TTL cuts a stale thread — any further send is *initiative* and passes with no friction.
+
+Why not a plain time window: a long task is exactly the high-value catch (asked from web, the agent finishes two hours later — the reply must still land in web), while a long window would false-hold initiative after an already-answered question. Unansweredness is the semantically precise discriminator; the TTL only bounds staleness (a thread closed outside the router — in an attached terminal, by voice — is invisible to the guard and must not arm it forever).
+
+## The hold
+
+On an armed mismatch — the **intended** channel (`runtime` argument, or the human's default runtime when omitted) differs from the armed origin — the send is **not delivered**. It is persisted verbatim as a *pending held send* and the sender gets an instructive error:
+
+```text
+origin-guard: "arthur" last wrote to you from "web" (2026-07-15T12:58:03+03:00) and that
+message is not yet answered — this send targets "telegram". Message NOT delivered; held
+verbatim as og-1a2b3c4d (expires in 15 min).
+- cross-channel is intentional → deliver as addressed: iapeer confirm-send og-1a2b3c4d
+- reply to the origin channel instead: iapeer confirm-send og-1a2b3c4d --runtime web
+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).
+
+```bash
+iapeer confirm-send og-1a2b3c4d                 # deliver as addressed (intentional cross-channel)
+iapeer confirm-send og-1a2b3c4d --runtime web   # deliver the same message to the origin channel
+```
+
+`confirm-send` re-sends under the **original sender identity**. A peer session (carrying `PEER_IDENTITY`) may confirm only its own held sends; a bare operator shell may confirm any (same-uid trust domain). The claim is atomic — of two concurrent confirms exactly one wins. A failed delivery puts the hold back (retry until TTL); an expired hold answers «re-send the message instead».
+
+## Where it runs
+
+The guard and both stamps live in `routeSend` — the one routing point **both** entry paths share: the daemon's `send_to_peer` tool *and* the in-process CLI `iapeer send` (which is how the channel bridges deliver human inbound). A daemon-only guard would never see the inbound half and never arm. The bypass used by `confirm-send` is a routing dependency wired by the entry points — it is **not reachable from agent-supplied tool arguments**, so an agent cannot forge it.
+
+State is on disk (it must survive daemon restarts and short-lived CLI processes), under the state root:
+
+```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
+```
+
+## Scope and non-interference
+
+The guard touches exactly one traffic class: **agent → human** sends while armed. Everything else is untouched by construction: agent→agent, human→agent, service (`absent`) senders and targets, same-channel replies (armed origin = intended channel), initiative (disarmed), and every flow with the guard disabled. Input typed directly into an attached terminal never passes the router, so it neither arms nor disarms the pair — the arm TTL bounds the resulting staleness. Hard delivery policies (e.g. the telegram sender-face policy) still apply at delivery time, including on the confirm path.
+
+Delivery outcomes stay observable in `delivery.log`: a hold is an `ok=false` line whose `err` carries the origin-guard note (grep `origin-guard`); a confirmed delivery carries `og=<id>`, correlating it with its earlier refusal.
+
+## Knobs
+
+| Env | Default | Meaning |
+|---|---|---|
+| `IAPEER_ORIGIN_GUARD` | on | `0` disables the guard and the stamps host-wide |
+| `IAPEER_ORIGIN_GUARD_ARM_TTL_MS` | 48 h | how long an unanswered inbound keeps the pair armed |
+| `IAPEER_ORIGIN_GUARD_PENDING_TTL_MS` | 15 min | how long a held send stays confirmable |

package/docs/README.md

@@ -79,6 +79,7 @@ The sections are layered: from "install and use" to "understand the architecture
 - [15 — Fleet API](15-fleet-api.md) — the daemon's HTTP surface for operator clients (dashboards, tray apps, scripts): snapshot, event stream, commands
 - [16 — Tray](16-tray.md) — the macOS menu-bar fleet dashboard (SwiftBar plugin), the first external Fleet API client
 - [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`
 
 ## Status
 

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

@@ -67,3 +67,7 @@ iapeer compact assistant       # сжать диалог
 - **`iapeer self-done`** — самовызов воркера, которому нечего отправить: освобождает очередь под следующую задачу, не разбудив никого. Доктрина «нечего отправлять — `self-done` вместо пустого ответа».
 
 Эта модель держит поток одноразовых задач упорядоченным: один воркер на задачу, без накопления параллельных сессий, без пустых пробуждений адресата.
+
+## Ответ человеку: origin guard
+
+Ответ агента человеку обязан лечь в канал, из которого человек писал. Роутер закрепляет это механически: пока последнее сообщение человека этому агенту не отвечено, отправка в *другой* канал удерживается до подтверждения одной командой (`iapeer confirm-send <id>`) — вместо доставки. Ответы в тот же канал и инициатива проходят без трения. Полный контракт — модель взведённой пары, TTL, `confirm-send` — в [18 — Origin guard](18-origin-guard.md).

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

@@ -59,6 +59,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` по умолчанию — идентичность пира текущей папки.
 

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

@@ -0,0 +1,66 @@
+# 18 — Origin guard (страж канала-источника)
+
+**Русский** · [English](../18-origin-guard.md)
+
+Когда человек пишет агенту из одного канала (скажем, из web-консоли), а агент отвечает в другой (скажем, в Telegram), ответ уходит туда, куда человек не смотрит. До сих пор этот класс ошибок держался только на доктрине агента («отвечай туда, откуда пришло») — на памяти, не на механике. **Origin guard** закрепляет правило на роутере: *ответ* агента человеку обязан целиться в канал, из которого человек писал в последний раз, иначе он **удерживается** до явного подтверждения одной командой — вместо доставки.
+
+Это **нормативный контракт** поведения стража, его состояния и CLI-поверхности.
+
+## Что считается ответом
+
+Страж ведёт одну запись на пару **(человек, агент)** — люди суть пиры с `intelligence: natural`:
+
+- успешная доставка **человек → агент** штампует пару: канал человека (`rt` = рантайм отправителя) и момент (`inboundTs`);
+- успешная доставка **агент → человек** штампует `answeredTs`.
+
+Пара **взведена**, когда последнее входящее *не отвечено* (`inboundTs > answeredTs`) и моложе TTL взвода (по умолчанию 48 ч). Отправка агента человеку **при взведённой паре презюмируется ответом** и обязана целиться в канал-источник. После ответа — либо после того как TTL отсёк залежалую нить — любая следующая отправка есть *инициатива* и проходит без трения.
+
+Почему не простое окно времени: долгая задача — ровно тот ценный класс, который нужно ловить (спросили из web, агент закончил через два часа — ответ всё равно должен лечь в web), а длинное окно ложно удерживало бы инициативу после уже отвеченного вопроса. Неотвеченность — семантически точный дискриминатор; TTL лишь ограничивает залежалость (нить, закрытая мимо роутера — в приаттаченном терминале, голосом — стражу не видна и не должна держать пару взведённой вечно).
+
+## Удержание
+
+При взведённом несовпадении — **намеченный** канал (аргумент `runtime`, а при его отсутствии дефолтный рантайм человека) отличается от взведённого источника — отправка **не доставляется**. Она сохраняется дословно как *удержанная* (pending), а отправитель получает инструктивную ошибку:
+
+```text
+origin-guard: "arthur" last wrote to you from "web" (2026-07-15T12:58:03+03:00) and that
+message is not yet answered — this send targets "telegram". Message NOT delivered; held
+verbatim as og-1a2b3c4d (expires in 15 min).
+- cross-channel is intentional → deliver as addressed: iapeer confirm-send og-1a2b3c4d
+- reply to the origin channel instead: iapeer confirm-send og-1a2b3c4d --runtime web
+Do not re-send the message text — confirm-send delivers the held message.
+```
+
+Оба выхода стоят одну shell-команду и **ноль регенерации сообщения**: удержанная отправка несёт полный исходный ввод (текст, топик, вложения).
+
+```bash
+iapeer confirm-send og-1a2b3c4d                 # доставить как адресовано (кросс-канал намеренный)
+iapeer confirm-send og-1a2b3c4d --runtime web   # доставить то же сообщение в канал-источник
+```
+
+`confirm-send` отправляет от **исходной идентичности отправителя**. Сессия пира (несущая `PEER_IDENTITY`) может подтверждать только свои удержанные отправки; голый операторский шелл — любые (домен доверия same-uid). Захват атомарен — из двух конкурентных подтверждений побеждает ровно одно. Провал доставки возвращает удержание на место (повтор до TTL); истёкшее отвечает «отправь сообщение заново».
+
+## Где это работает
+
+Страж и оба штампа живут в `routeSend` — единственной точке маршрутизации, общей для **обоих** путей входа: инструмента `send_to_peer` демона *и* внутрипроцессного CLI `iapeer send` (которым мосты каналов доставляют входящие от человека). Страж только на стороне демона никогда не видел бы входящую половину и никогда бы не взводился. Обход (bypass), которым пользуется `confirm-send`, — зависимость маршрутизации, которую прошивают точки входа; он **недостижим из tool-аргументов агента**, подделать его агент не может.
+
+Состояние — на диске (обязано переживать рестарты демона и короткоживущие CLI-процессы), под корнем состояния:
+
+```text
+~/.iapeer/state/iapeer/origin/
+  state.json          # (агент → человек → {rt, inboundTs, answeredTs}) — last-wins, атомарные записи
+  pending/<id>.json   # удержанные отправки, дословно; ленивый GC после TTL
+```
+
+## Границы и невмешательство
+
+Страж касается ровно одного класса трафика: отправки **агент → человек** при взведённой паре. Всё прочее не затронуто по построению: агент→агент, человек→агент, сервисные (`absent`) отправители и цели, ответы в тот же канал (источник = намеченный канал), инициатива (пара разряжена) и любые потоки при выключенном страже. Ввод, набранный прямо в приаттаченном терминале, роутер не проходит — он не взводит и не разряжает пару; итоговую залежалость ограничивает TTL взвода. Жёсткие политики доставки (например, telegram-политика лица отправителя) продолжают действовать в момент доставки, включая путь подтверждения.
+
+Исходы доставки наблюдаемы в `delivery.log`: удержание — строка `ok=false`, чей `err` несёт ноут стража (grep `origin-guard`); подтверждённая доставка несёт `og=<id>`, связывающий её с прежним отказом.
+
+## Ручки
+
+| Env | По умолчанию | Смысл |
+|---|---|---|
+| `IAPEER_ORIGIN_GUARD` | вкл | `0` выключает стража и штампы на всём хосте |
+| `IAPEER_ORIGIN_GUARD_ARM_TTL_MS` | 48 ч | сколько неотвеченное входящее держит пару взведённой |
+| `IAPEER_ORIGIN_GUARD_PENDING_TTL_MS` | 15 мин | сколько удержанная отправка остаётся подтверждаемой |

package/docs/ru/README.md

@@ -79,6 +79,7 @@ iapeer send assistant --message "привет, ты на связи?"
 - [15 — Fleet API](15-fleet-api.md) — HTTP-поверхность демона для операторских клиентов (дашборды, tray-приложения, скрипты): снапшот, поток событий, команды
 - [16 — Трей](16-tray.md) — дашборд флота в меню-баре macOS (плагин SwiftBar), первый внешний клиент Fleet API
 - [17 — Подтверждение человеком](17-approval.md) — режим gated/yolo на пира: маршрутизация блокирующих подтверждений рантайма человеку через брокер демона (перехват хуком, брокер, Fleet API + CLI)
+- [18 — Origin guard](18-origin-guard.md) — ответ агента человеку обязан целиться в канал, из которого человек писал: модель взведённой пары, удержание, `confirm-send`
 
 ## Статус
 

package/package.json

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

@@ -1079,6 +1079,12 @@ export interface SendOptions extends CliEnvOptions {
   message: string
   topic?: string
   attachments?: string[]
+  /** Origin-guard bypass (docs/18) — set ONLY by `iapeer confirm-send` (the held-send
+   *  delivery). Wired into RouteDeps, never derivable from agent-supplied tool args. */
+  originGuardBypass?: boolean
+  /** Held-send id (confirm-send) — stamped into delivery.log as `og=` so a confirmed
+   *  delivery is correlatable with its earlier origin-hold refusal. */
+  og?: string
 }
 
 const cliWake: WakeFn = req =>
@@ -1112,7 +1118,12 @@ export async function sendMessage(
     // noteLiveTopic — CLI-path parity (same seam the daemon wires): a live delivery
     // through the CLI fallback must update the target's .topic marker too, or a
     // daemon-restart-window send re-opens the stale-marker false-fresh.
-    { wake: cliWake, ephemeral: makeEphemeralRouteDeps(cfg, env, () => {}), noteLiveTopic: makeNoteLiveTopic(cfg, env) },
+    {
+      wake: cliWake,
+      ephemeral: makeEphemeralRouteDeps(cfg, env, () => {}),
+      noteLiveTopic: makeNoteLiveTopic(cfg, env),
+      originGuardBypass: opts.originGuardBypass,
+    },
   )
   // delivery.log sink — CLI-path parity (observability gap: enqueues routed
   // through the CLI left to=<peer> at ZERO while real wakes happened; the daemon
@@ -1135,6 +1146,7 @@ export async function sendMessage(
     len: opts.message.length,
     att: opts.attachments?.length || undefined,
     topic: opts.topic,
+    og: opts.og, // held-send id (confirm-send) — correlates with the origin-hold refusal
     err: result.ok ? undefined : result.error.message,
   })
   if (!result.ok) throw new Error(result.error.message)
@@ -1277,6 +1289,10 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
     sig: 'send <target> (--message <text> | --message-file <f|->) [--from <id>] [--attachment <p>]… [--topic <t>]',
     desc: 'manual IAP send (fallback)',
   },
+  {
+    sig: 'confirm-send <id> [--runtime <rt>]',
+    desc: 'deliver a held send (origin-guard, docs/18): as addressed, or --runtime redirects it to the origin channel — no re-send of the message text',
+  },
   { sig: '<runtime>', desc: "launch the cwd's peer FRESH; on a TTY drop into it (like attach), else detached" },
   { sig: 'connect telegram <peer> [--token <t>]', desc: 'attach a telegram bot to a peer (bot add → interface → router restart; asks only the token). Alias: `iapeer enable telegram <peer>`' },
   { sig: 'enable <plugin> [peer] [--no-setup]', desc: 'install + enable an agfpd capability for a peer' },
@@ -2136,6 +2152,54 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         )
         return 0
       }
+      case 'confirm-send': {
+        // Origin-guard (docs/18): deliver a HELD send — as addressed (intentional
+        // cross-channel), or redirected to the origin channel via --runtime. The held
+        // message is re-sent VERBATIM under the ORIGINAL sender identity; the bypass
+        // flag lives in RouteDeps (not tool args), so this verb is the only gate.
+        const id = positionals[0]
+        if (!id) return argErr(errOut, 'confirm-send needs an id — usage: iapeer confirm-send <id> [--runtime <rt>]')
+        const rtOverride = typeof flags.runtime === 'string' ? flags.runtime : undefined
+        const { claimHeldSend, restoreHeldSend, discardHeldSend } = await import('../transport/originGuard.ts')
+        const claimed = claimHeldSend(id, { env })
+        if (!claimed.ok) {
+          errOut(`${claimed.error.message}\n`)
+          return 1
+        }
+        const held = claimed.value
+        // The confirmer must BE the holder: a peer session carries PEER_IDENTITY, and a
+        // held send may only be confirmed by the peer that produced it. Absent identity
+        // (a bare operator shell) is trusted — same-uid operator, same trust domain.
+        const confirmer = env.PEER_IDENTITY?.trim()
+        if (confirmer && confirmer !== held.caller) {
+          restoreHeldSend(id, { env })
+          errOut(`confirm-send: held send ${id} belongs to ${held.caller}, not ${confirmer} — refused\n`)
+          return 1
+        }
+        try {
+          const r = await sendMessage({
+            target: held.personality,
+            from: held.caller,
+            message: held.message,
+            runtime: rtOverride ?? held.runtime,
+            topic: held.topic,
+            attachments: held.attachments,
+            env,
+            originGuardBypass: true,
+            og: held.id,
+          })
+          discardHeldSend(id, { env })
+          out(`delivered held send ${id} to ${r.delivered_to.personality} (${r.delivered_to.runtime})\n`)
+          return 0
+        } catch (e) {
+          restoreHeldSend(id, { env })
+          errOut(
+            `confirm-send: delivery failed — ${e instanceof Error ? e.message : String(e)}; ` +
+              `the held send remains until its TTL — retry: iapeer confirm-send ${id}\n`,
+          )
+          return 1
+        }
+      }
       case 'version':
       case '--version':
       case '-v': {

package/src/daemon/approvals.ts

@@ -1,6 +1,6 @@
 // Approval broker — the in-daemon queue that is the SINGLE SOURCE OF TRUTH for
 // human-approval requests (docs/17). Every channel (the runtime hook that ASKS, and
-// the CLI / tray / telegram faces that ANSWER) is an interface to THIS one queue: a
+// the CLI / tray / telegram / web-console faces that ANSWER) is an interface to THIS one queue: a
 // decision from any face resolves the request everywhere (the owner's invariant).
 //
 // Flow: a gated peer's PreToolUse hook blocks and POSTs /fleet/v1/approvals → the fleet
@@ -56,7 +56,9 @@ export interface ApprovalDecision {
 export interface ResolveMeta {
   /** The approver who answered (a nature-peer personality). */
   by?: string
-  /** The channel that answered: cli | tray | telegram | timeout | disconnect. */
+  /** The surface that answered: cli | tray | telegram | web | timeout | disconnect.
+   *  Self-declared by the answering face (free-form-tolerant); absent when the face
+   *  did not self-identify — the audit line then omits `via` rather than guessing. */
   via?: string
 }
 

package/src/daemon/fleet.ts

@@ -636,7 +636,10 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
           /* empty/invalid body is fine — approve/deny carry only optional fields */
         }
         const by = typeof body.approver === 'string' ? body.approver : undefined
-        const via = typeof body.via === 'string' ? body.via : 'cli'
+        // The answering face self-identifies its surface in `via` (cli | tray | telegram | web | …;
+        // free-form-tolerant like `kind`). NO default — an audit line must never claim a surface the
+        // caller did not state; a face that sent nothing is logged with the field omitted.
+        const via = typeof body.via === 'string' ? body.via : undefined
         const ok =
           action === 'approve'
             ? broker.resolve(id, { decision: 'allow', reason: typeof body.reason === 'string' ? body.reason : undefined }, { by, via })

package/src/transport/index.ts

@@ -57,6 +57,17 @@ import {
   listHostedPeers,
 } from '../launch/ptyHost.ts'
 import { sendControlToHost, type DeliverResult } from '../supervisor/deliver.ts'
+// Origin-guard (docs/18) — reply-channel mechanic for agent→human sends. Lives in
+// transport because routeSend is the ONLY choke point both directions share (human
+// inbound arrives via the CLI entry path, past the daemon — see originGuard.ts header).
+import {
+  armedOrigin,
+  buildHoldNote,
+  holdSend,
+  noteHumanAnswered,
+  noteHumanInbound,
+  originGuardEnabled,
+} 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
 
@@ -971,6 +982,11 @@ export interface RouteDeps {
   isLaunchdManaged?: (personality: string) => boolean
   /** Injectable async sleep for the launchd-revive retry poll (tests). Default: setTimeout. */
   sleep?: (ms: number) => Promise<void>
+  /** Origin-guard bypass — set ONLY by `iapeer confirm-send` (the held-send delivery).
+   *  DELIBERATELY a RouteDeps field, not a SendToPeerInput field: tool arguments are
+   *  agent-supplied, so an input flag would let any agent forge the bypass; deps are
+   *  wired by the entry points (daemon/CLI), out of the agent's reach. */
+  originGuardBypass?: boolean
 }
 
 /** Best-effort noteLiveTopic invocation — only on a non-empty topic, never throws. */
@@ -1295,6 +1311,36 @@ export async function routeSend(
   caller: ResolvedCaller,
   input: SendToPeerInput,
   deps: RouteDeps = {},
+): Promise<Result<RouteResult>> {
+  const result = await routeSendInner(caller, input, deps)
+  // Origin-guard stamps — AFTER an ok outcome only (a failed send answered nothing and
+  // carried no inbound). Best-effort: a stamp failure must never fail a delivered
+  // message. Covers EVERY ok path (live / queued / wake / launchd-revive) in one place.
+  if (result.ok) stampOriginOnDelivered(caller, input.personality, deps.env ?? process.env)
+  return result
+}
+
+/** Post-ok origin stamps: human→agent ⇒ inbound (arms the pair with the human's origin
+ *  channel); agent→human ⇒ answered (disarms). Any other pair — no-op. */
+function stampOriginOnDelivered(caller: ResolvedCaller, targetPersonality: string, env: NodeJS.ProcessEnv): void {
+  try {
+    if (!originGuardEnabled(env)) return
+    const peer = findPeer(readPeersIndex({ env }), targetPersonality)
+    if (!peer) return
+    if (caller.intelligence === 'natural' && peer.intelligence === 'artificial') {
+      noteHumanInbound(peer.personality, caller.personality, caller.runtime, { env })
+    } else if (caller.intelligence === 'artificial' && peer.intelligence === 'natural') {
+      noteHumanAnswered(caller.personality, peer.personality, { env })
+    }
+  } catch {
+    /* stamps are observability for the guard — never fail a delivered message */
+  }
+}
+
+async function routeSendInner(
+  caller: ResolvedCaller,
+  input: SendToPeerInput,
+  deps: RouteDeps = {},
 ): Promise<Result<RouteResult>> {
   const { personality, runtime, message } = input
   const topic = truncateTopic(input.topic)
@@ -1324,6 +1370,35 @@ export async function routeSend(
     return err(`peer "${personality}" is not in the iapeer peers index; message NOT delivered`)
   }
 
+  // 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.
+  // Intended runtime = the explicit override or the human's default; exact for the
+  // natural-peer class (their channels are always-on launchd routers, so the
+  // only-live-session fallback cannot silently diverge outside a seconds-wide crash
+  // window). Initiative (answered / no inbound / ARM_TTL-stale) passes untouched.
+  if (
+    !deps.originGuardBypass &&
+    originGuardEnabled(env) &&
+    caller.intelligence === 'artificial' &&
+    peer.intelligence === 'natural'
+  ) {
+    const armed = armedOrigin(caller.personality, peer.personality, { env })
+    const intendedRt = runtime ?? peer.runtime
+    if (armed && armed.rt !== intendedRt) {
+      const held = holdSend(
+        caller.address,
+        { personality, runtime, message, topic, attachments: attachmentsResult.value },
+        armed,
+        intendedRt,
+        { env },
+      )
+      return err(buildHoldNote(held, { env }))
+    }
+  }
+
   // Telegram sender policy — INTENDED channel (explicit override, or the target's
   // default). Checked BEFORE any wake side-effect: a wake delivers the envelope as
   // the boot first-message, past the resolved-target guards further down.

package/src/transport/originGuard.ts

@@ -0,0 +1,300 @@
+// Origin-guard (docs/18) — the daemon-layer mechanic against the "agent answered the
+// human in the wrong channel" error class. Doctrine (origin-routing: reply where the
+// human wrote from) lives in every agent's memory — unreliable by construction; this
+// module enforces it MECHANICALLY at the delivery choke point, routeSend (§3 of the
+// host rules: fix errors at the right layer).
+//
+// WHY transport, not the daemon: live forensics of delivery.log showed that ALL
+// human-inbound traffic (telegram-arthur / web-arthur) arrives via `iapeer send`
+// (path=cli — the bridges run the CLI verb, an IN-PROCESS routeSend that never touches
+// the daemon's callTool), and codex agents send through the CLI shim too. routeSend is
+// the ONLY point both directions and both entry paths (daemon MCP + CLI) share — a
+// daemon-side guard would be blind to the inbound half and never arm.
+//
+// Model (per (human, agent) pair, humans = intelligence:natural):
+//   • inbound stamp   — an ok human→agent delivery records {rt, inboundTs}.
+//   • answered stamp  — an ok agent→human delivery records answeredTs.
+//   • armed           — inboundTs > answeredTs (the latest inbound is UNANSWERED) and
+//                       younger than ARM_TTL. Discriminates reply-vs-initiative
+//                       semantically: an outbound while armed is presumed a REPLY (must
+//                       match the origin channel); once answered (or TTL-stale), any
+//                       further outbound is INITIATIVE — no friction. A pure time
+//                       window would either miss the long-task class (asked from web,
+//                       answered 2h later into telegram) or false-hold initiative.
+//   • hold            — an armed mismatch (intended runtime ≠ origin runtime) is NOT
+//                       delivered: the send is persisted verbatim as a pending file and
+//                       the sender gets an instructive error. `iapeer confirm-send <id>`
+//                       delivers it as addressed; `--runtime <origin>` redirects it to
+//                       the origin channel — zero message regeneration either way.
+//
+// State is on DISK (not daemon memory) because the CLI entry path is a short-lived
+// process, and stamps must survive daemon restarts. Writes are atomic
+// (storage.writeFileAtomic); concurrent read-modify-write is LAST-WINS by design — the
+// guard is soft, stamp frequency is human-paced, and a lost stamp degrades to at most
+// one extra confirm (owner-approved v1 fork; add locking only if it bites live).
+//
+// Paths resolve from the injected env (the readPeersIndex({env}) pattern) so the
+// IAPEER_ROOT sandbox isolates tests — never from a re-resolved process.env.
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync } from 'fs'
+import { join } from 'path'
+import { randomBytes } from 'crypto'
+import { err, ok, type Result } from '../core/errors.ts'
+import { pluginStateDir, writeFileAtomic } from '../storage/index.ts'
+import { formatSentAt } from '../codec/index.ts'
+
+/** Kill-switch: IAPEER_ORIGIN_GUARD=0 disables the guard AND the stamps host-wide. */
+export function originGuardEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.IAPEER_ORIGIN_GUARD !== '0'
+}
+
+const DEFAULT_ARM_TTL_MS = 48 * 60 * 60 * 1000 // 48 h — covers a realistic reply latency, cuts staleness
+const DEFAULT_PENDING_TTL_MS = 15 * 60 * 1000 // 15 min — the agent confirms within its current turn
+
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = parseInt(raw ?? '', 10)
+  return Number.isFinite(n) && n > 0 ? n : dflt
+}
+
+export function armTtlMs(env: NodeJS.ProcessEnv = process.env): number {
+  return envPosInt(env.IAPEER_ORIGIN_GUARD_ARM_TTL_MS, DEFAULT_ARM_TTL_MS)
+}
+
+export function pendingTtlMs(env: NodeJS.ProcessEnv = process.env): number {
+  return envPosInt(env.IAPEER_ORIGIN_GUARD_PENDING_TTL_MS, DEFAULT_PENDING_TTL_MS)
+}
+
+export interface OriginGuardOptions {
+  env?: NodeJS.ProcessEnv
+  /** Injectable clock (tests). Default Date.now. */
+  nowMs?: number
+}
+
+// ── Origin state (last inbound / answered, per agent→human pair) ─────────────────
+
+export interface OriginEntry {
+  /** The runtime the human's latest message arrived FROM (its origin channel). */
+  rt: string
+  /** When that inbound was delivered ok (epoch ms). */
+  inboundTs: number
+  /** When the agent last answered this human ok (epoch ms). Absent = never. */
+  answeredTs?: number
+}
+
+/** agent personality → human personality → entry. */
+type OriginState = Record<string, Record<string, OriginEntry>>
+
+function originDir(env: NodeJS.ProcessEnv): string {
+  return join(pluginStateDir('iapeer', { env }), 'origin')
+}
+
+function statePath(env: NodeJS.ProcessEnv): string {
+  return join(originDir(env), 'state.json')
+}
+
+function pendingDir(env: NodeJS.ProcessEnv): string {
+  return join(originDir(env), 'pending')
+}
+
+function readState(env: NodeJS.ProcessEnv): OriginState {
+  try {
+    const parsed = JSON.parse(readFileSync(statePath(env), 'utf8')) as unknown
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed as OriginState
+  } catch {
+    /* missing / corrupt → empty (the guard fails open: no state, no holds) */
+  }
+  return {}
+}
+
+function writeState(env: NodeJS.ProcessEnv, state: OriginState): void {
+  mkdirSync(originDir(env), { recursive: true })
+  writeFileAtomic(statePath(env), `${JSON.stringify(state)}\n`)
+}
+
+/** Record an ok human→agent delivery: the human's origin channel + instant. */
+export function noteHumanInbound(agent: string, human: string, rt: string, opts: OriginGuardOptions = {}): void {
+  const env = opts.env ?? process.env
+  const now = opts.nowMs ?? Date.now()
+  const state = readState(env)
+  const perAgent = (state[agent] ??= {})
+  const prev = perAgent[human]
+  // Keep answeredTs — a NEWER inbound re-arms regardless, since inboundTs > answeredTs.
+  perAgent[human] = { rt, inboundTs: now, ...(prev?.answeredTs !== undefined ? { answeredTs: prev.answeredTs } : {}) }
+  writeState(env, state)
+}
+
+/** Record an ok agent→human delivery: the pair is answered (disarms the guard). */
+export function noteHumanAnswered(agent: string, human: string, opts: OriginGuardOptions = {}): void {
+  const env = opts.env ?? process.env
+  const now = opts.nowMs ?? Date.now()
+  const state = readState(env)
+  const entry = state[agent]?.[human]
+  if (!entry) return // nothing to disarm — never wrote to us via the router
+  entry.answeredTs = now
+  writeState(env, state)
+}
+
+/** The ARMED origin for (agent, human), or null: the latest inbound is unanswered AND
+ *  younger than ARM_TTL. Null = initiative / already answered / stale — no friction. */
+export function armedOrigin(agent: string, human: string, opts: OriginGuardOptions = {}): OriginEntry | null {
+  const env = opts.env ?? process.env
+  const now = opts.nowMs ?? Date.now()
+  const entry = readState(env)[agent]?.[human]
+  if (!entry) return null
+  if (entry.answeredTs !== undefined && entry.answeredTs >= entry.inboundTs) return null
+  if (now - entry.inboundTs > armTtlMs(env)) return null
+  return entry
+}
+
+// ── Pending (held) sends ─────────────────────────────────────────────────────────
+
+export interface HeldSend {
+  id: string
+  /** The sender's address (`<runtime>-<personality>`) — the identity confirm-send re-sends AS. */
+  caller: string
+  personality: string
+  runtime?: string
+  message: string
+  topic?: string
+  attachments?: string[]
+  /** The armed origin channel the human last wrote from (unanswered). */
+  originRt: string
+  /** When that unanswered inbound arrived (epoch ms) — shown in the hold note. */
+  originTs: number
+  /** The channel this send would have landed in (input.runtime ?? the human's default). */
+  intendedRt: string
+  createdMs: number
+}
+
+function pendingPath(env: NodeJS.ProcessEnv, id: string): string {
+  return join(pendingDir(env), `${id}.json`)
+}
+
+function claimedPath(env: NodeJS.ProcessEnv, id: string): string {
+  return join(pendingDir(env), `${id}.json.claimed`)
+}
+
+/** Lazy GC — unlink pending files older than the pending TTL (by mtime). Called on
+ *  every hold/claim touch; cheap (one readdir of a near-empty dir), no timers. */
+export function sweepExpiredPendings(opts: OriginGuardOptions = {}): void {
+  const env = opts.env ?? process.env
+  const now = opts.nowMs ?? Date.now()
+  const ttl = pendingTtlMs(env)
+  let entries: string[]
+  try {
+    entries = readdirSync(pendingDir(env))
+  } catch {
+    return
+  }
+  for (const name of entries) {
+    if (!name.endsWith('.json') && !name.endsWith('.json.claimed')) continue
+    const path = join(pendingDir(env), name)
+    try {
+      if (now - statSync(path).mtimeMs > ttl) unlinkSync(path)
+    } catch {
+      /* raced away / unreadable — best-effort */
+    }
+  }
+}
+
+/** Persist a held send verbatim and return its record. */
+export function holdSend(
+  callerAddress: string,
+  input: { personality: string; runtime?: string; message: string; topic?: string; attachments?: string[] },
+  origin: OriginEntry,
+  intendedRt: string,
+  opts: OriginGuardOptions = {},
+): HeldSend {
+  const env = opts.env ?? process.env
+  const now = opts.nowMs ?? Date.now()
+  sweepExpiredPendings(opts)
+  const id = `og-${randomBytes(4).toString('hex')}`
+  const held: HeldSend = {
+    id,
+    caller: callerAddress,
+    personality: input.personality,
+    ...(input.runtime !== undefined ? { runtime: input.runtime } : {}),
+    message: input.message,
+    ...(input.topic !== undefined ? { topic: input.topic } : {}),
+    ...(input.attachments?.length ? { attachments: [...input.attachments] } : {}),
+    originRt: origin.rt,
+    originTs: origin.inboundTs,
+    intendedRt,
+    createdMs: now,
+  }
+  mkdirSync(pendingDir(env), { recursive: true })
+  writeFileAtomic(pendingPath(env, id), `${JSON.stringify(held, null, 2)}\n`)
+  return held
+}
+
+/** The instructive error the sender receives INSTEAD of a delivery. Self-sufficient:
+ *  it names the mismatch, both zero-regeneration exits, and the TTL. */
+export function buildHoldNote(held: HeldSend, opts: OriginGuardOptions = {}): string {
+  const env = opts.env ?? process.env
+  const ttlMin = Math.round(pendingTtlMs(env) / 60_000)
+  return (
+    `origin-guard: "${held.personality}" last wrote to you from "${held.originRt}" ` +
+    `(${formatSentAt(new Date(held.originTs))}) and that message is not yet answered — ` +
+    `this send targets "${held.intendedRt}". Message NOT delivered; held verbatim as ${held.id} (expires in ${ttlMin} min).\n` +
+    `- cross-channel is intentional → deliver as addressed: iapeer confirm-send ${held.id}\n` +
+    `- reply to the origin channel instead: iapeer confirm-send ${held.id} --runtime ${held.originRt}\n` +
+    `Do not re-send the message text — confirm-send delivers the held message.`
+  )
+}
+
+/** Claim a pending send for delivery — atomic rename (<id>.json → <id>.json.claimed),
+ *  so a concurrent second confirm loses cleanly (ENOENT → "no pending"). TTL-checked. */
+export function claimHeldSend(id: string, opts: OriginGuardOptions = {}): Result<HeldSend> {
+  const env = opts.env ?? process.env
+  const now = opts.nowMs ?? Date.now()
+  sweepExpiredPendings(opts)
+  const src = pendingPath(env, id)
+  const dst = claimedPath(env, id)
+  let raw: string
+  try {
+    renameSync(src, dst) // atomic claim — exactly one confirmer wins
+    raw = readFileSync(dst, 'utf8')
+  } catch {
+    return err(`no pending held send "${id}" (expired, already confirmed, or unknown) — re-send the message instead`)
+  }
+  let held: HeldSend
+  try {
+    held = JSON.parse(raw) as HeldSend
+  } catch {
+    try {
+      unlinkSync(dst)
+    } catch {
+      /* best-effort */
+    }
+    return err(`held send "${id}" is unreadable (corrupt pending file) — re-send the message instead`)
+  }
+  if (now - held.createdMs > pendingTtlMs(env)) {
+    try {
+      unlinkSync(dst)
+    } catch {
+      /* best-effort */
+    }
+    return err(`held send "${id}" expired (${Math.round(pendingTtlMs(env) / 60_000)} min TTL) — re-send the message instead`)
+  }
+  return ok(held)
+}
+
+/** Delivery failed — put the claimed pending back so confirm-send can be retried until TTL. */
+export function restoreHeldSend(id: string, opts: OriginGuardOptions = {}): void {
+  const env = opts.env ?? process.env
+  try {
+    renameSync(claimedPath(env, id), pendingPath(env, id))
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Delivery succeeded — drop the claimed pending. */
+export function discardHeldSend(id: string, opts: OriginGuardOptions = {}): void {
+  const env = opts.env ?? process.env
+  try {
+    unlinkSync(claimedPath(env, id))
+  } catch {
+    /* best-effort */
+  }
+}