agmsgd: one resident daemon for delivery, sync and control — RFC open for comment

[fujibee]

agmsg's automatic delivery currently costs one background process per receiving session, plus one per team that syncs with other machines, plus a small stack per Codex session. We want to replace all of them with a single resident daemon — and because that changes monitor mode substantially, we are publishing the design before implementing it rather than after.

The design: docs/design/agmsgd-rfc.md (日本語版)

It is an RFC, not a decision — settled decisions land as ADRs as usual. Nothing here is built yet, which is the point: the shape can still change cheaply. It assumes the terminal driver released in 1.3.0 — specifically the identity it put at the terminal layer, where a pane knows which agent occupies it, the same way under tmux and under herdr. That is what a delivery daemon needs, because delivery means resolving an addressee to a place. (peek, poke and arrange are conveniences on the same naming; the daemon is not one of their callers.)

What it proposes

• Messages stop getting lost. Nothing is marked read until an agent actually fetches it. Today a broken or leftover watcher can consume messages nobody ever saw.
• Notifications stop eating context. Instead of pushing full message text into a session, the agent gets one line — sender and subject — and decides for itself when to spend context on the rest. Search grows alongside it, so choosing not to fetch now stays cheap later.
• You never declare your role again. A session resolves its identity at startup from what it already knows, and holding it is exclusive. Forgetting stops being dangerous: today a session that never claimed a role receives everything addressed to anyone in the project and marks it read; afterwards it receives nothing and harms no one.
• Groups without a group feature. A message can address a tag, with each recipient's read state tracked separately. Tag membership is the subscription — a tag exists once someone subscribes and is gone when the last one leaves, so there is no registry to curate. Addressing a tag nobody subscribes to is an error rather than a delivery to no one.
• Codex without the launch wrapper. Real-time delivery no longer requires starting Codex through a wrapper, which is where most Codex-related bugs we have shipped came from.
• One process instead of a fleet. On one busy machine we counted roughly fifteen agmsg background processes. They become one supervised daemon.
• A control channel no model interprets. Commands like despawn executed by the daemon, mechanically, with an explicit authorization model required before anything beyond it ships.

Where your experience would change the design

The RFC ends with six questions. The ones most likely to depend on how you run agmsg:

1. Auto-selected delivery mode — the daemon picks how to deliver by looking at your environment. Is there a setup where that guess would be wrong for you?
2. "Noticed" is not "read" — do you have scripts or habits that assume a displayed message is already marked read?
3. One identity per (team, name) — does anyone deliberately run the same agent name on two different tools, needing them kept separate?
4. Search — what do you actually need to find, and by what? Would Gmail-style operators (from:, after:, subject:) cover it?
5. Control commands — what would you require before enabling remote peek/poke on one of your machines: per-team opt-in, sender allowlists, an audit log?
6. The daemonless fallback — we plan to keep agmsg usable without the daemon. Would you actually run that way, or should we simplify and require it?

A one-line answer is genuinely useful — "yes, I do X" tells us more about whether a default is safe than silence does. Disagreement about the whole direction is welcome too; that is far easier to act on now than after it ships.

[pennywise1026-eng]

Field answers to the six open questions, from one deployment: a team of 5–6 seats over two machines (a headless Linux box running four resident Codex workers under systemd + a Claude Code leader in herdr panes; a Windows box with Codex Desktop as a second leader). agmsg v1.3.0, running with a local patch set we just filed as #1294–#1299.

1. Auto-selected delivery mode. Pane detection alone would guess wrong for us. On the same host we have three kinds of seats at once: herdr panes (pane-addressable), pane-less Codex Desktop, and resident Codex workers that are idle most of the time and only wake on a message — no hook fires for them until something is delivered. Please include idle residents as notification targets, and expose which route was chosen and why (one line) so a wrong guess is diagnosable rather than silent.

2. Noticed is not read. Yes, and we already operate that way: a seat treats read/ACK as "the transport worked", never as "the work was accepted"; acceptance is checked against the artifact. One caveat: we have not audited every monitor/script we own for an implicit "displayed ⇒ read" assumption, so "zero migration impact" is not something we can confirm — a short migration note listing what changes for read_at would help.

3. One identity per (team, name). Yes. We found no case where same-name-on-different-tools is intentionally kept separate. The condition that matters is on reconnect: ownership must not fall back to the older session record (#1299).

4. Search. by sender, recipient, team, date, words — plus exact mid match and following the reply correlation (re:) chain; that is what we actually use when reconstructing a decision. Depth: at least month-spanning (we routinely cite messages 4–5 weeks old). Search must not touch read_at; only a body fetch of selected ids marks them read (#1297). Gmail-style from: / after: / subject: would cover all our cases.

5. Remote peek/poke. Before enabling on one of our machines: per-team opt-in, permission split by operation and by sender (peek = view right, poke = input right, granted separately), an allow/deny audit log, and re-resolution + expiry of the target session at execution time (a stale placement must fail closed, not poke whoever now sits in that pane).

6. Daemonless fallback. For normal resident operation we need the daemon. What we would still want daemonless is recovery: when the daemon is down or misbehaving, the same send / inbox / history must keep working for diagnosis and manual drain. We have not run daemonless for a sustained period, so no data on that. If Desktop send becomes daemon-only, please state that exception explicitly in the compatibility table.

One addition not covered above: please state in the API/CLI docs what a receipt guarantees — persisted, notified, fetched — and that it says nothing about business-level acknowledgement/completion/acceptance. We do not want agmsg to implement task state; we want the boundary written down so agents stop inferring "done" from "read".

Happy to test a pre-release of the daemon on the Windows seat first — it is the one where the current bridge is weakest for us.

[fujibee]

Thank you for taking the time to answer all six questions from a running deployment. We are reading through it, and through the issues you filed.

On testing a pre-release on your Windows seat: that would be welcome. We will post here when there is something to try.

[fujibee]

One more note on the Windows seat: codex-app support is on the roadmap, though we cannot say yet whether it lands in the first release.

[fujibee]

A short follow-up: several of your points line up with what we are building, and hearing them from a running deployment helped. In particular: (1) a seat's owner never reverts to an older session after a reconnect, (2) only messages that were actually shown become read, and history does not change that, (3) send, inbox and history keep working even without the daemon. Thanks again.

[joelmitz]

Thanks for publishing this before implementing it — the shape questions are the
ones I can actually answer from measurements rather than from opinion.

Context for what follows: I run agmsg daily on a single Linux host that is the
system of record for my work, with occasional sessions on other machines that
join the same team. Installed version is v1.3.0-141-g62c389a. Everything
below is something I re-ran today rather than remembered.

I am answering 1, 2, 3, 5 and 6. I am not answering 4 (search), because I
have no data on what I actually search for — we read at turn boundaries and
almost never search back, so anything I said about operators would be a guess.

---

1. Auto-selected delivery mode — yes, there is a setup where the guess goes wrong

There is a third layout layer, and it is neither tmux nor herdr nor "no pane
manager".

The RFC's premise is that "a pane knows which agent occupies it, the same way
under tmux and under herdr". That is true of tmux and herdr. It is not true of
my primary environment. My primary pane manager is orca; herdr is my
secondary. scripts/drivers/terminals/ ships exactly three drivers — herdr,
plain, tmux — and there is no driver for the one I spend most of my day in.

So this is what where.sh reports from the session I am writing this in:

resolved=true placement=none reason=no_addressable_pane terminal=plain \
  capabilities=spawn despawn peek poke

terminal=plain, placement=none. Per scripts/drivers/terminals/plain/README.md,
a bare plain:- placement narrows peek and poke to unsupported at the
instance level, before either verb is attempted — even though the manifest
ceiling lists them, which is what you see echoed in capabilities= above.

The reason this matters for the daemon specifically is that the failure is not
"no pane manager". There is a pane manager; agmsg simply cannot address it.
Step 1 of your channel selection ("session runs under a pane manager the daemon
can control?") and step 2 ("no pane manager? fall back to the tool's own
channel") both describe environments I do not have. The correct outcome for me
is step 2's channel — but it must be reached because the placement did not
resolve, not because no pane manager was detected. If detection asks "is there
a terminal emulator / a tty / a pane manager?" it will answer yes here and pick
a channel that cannot deliver.

Concretely, the request:

• Key the daemon's choice off the terminal driver's resolved placement, not
  off the presence of a pane manager. placement=none → tool-native channel,
  regardless of what else is running on the machine.
• This is not an unusual machine. On this one host, the same roster shows
  sessions at reach=can:peek,poke,arrange under herdr and this session at
  placement=none at the same moment. Whatever the daemon decides has to be
  per-registration, not per-host and not per-project.
• Make the chosen channel visible. Today's wrong guess would be silent. I
  would like the daemon's status output to say, per registration, which channel
  was selected and on what evidence — so that "delivery mode auto-detected" is
  falsifiable rather than trusted.
• Precedent from your own code, which I think is exactly the right instinct:
  peek.sh on a bare plain:- claude-code target already falls back to reading
  the session transcript off disk, and prefixes the output with an
  AGMSG-NATIVE-RECORD: marker so a caller can never mistake a transcript for a
  screen. A substitute channel, labelled as a substitute. The daemon's mode
  selection deserves the same explicitness.

I am not asking for an orca driver in this RFC — that is a separate piece of
work, and I am the one who would have to write it. I am asking that the daemon's
detection not assume the world is two-valued.

---

2. "Noticed" is not "read" — no habit to break here, and the split fixes a real conflation

No: nothing I run treats "the watcher displayed it" as "read". We fetch
explicitly. So the change is safe from my side.

More usefully, here is what my team store looks like as of 2026-09-18: over
5,000 messages across ~46 days (first message 2026-08-03, last 2026-09-18), of
which several hundred are unread by read_at IS NULL.

I am giving round numbers on purpose, and especially for the unread count,
because that count moves. It moved by several hundred on the day I wrote this,
without anyone reading anything: a session restarted and marked its backlog read
in one pass. That volatility is part of my answer rather than an excuse for
imprecision — a number that swings that far on a process restart is a number
whose meaning is underdefined, which is exactly the problem this question is
about.

What is stable is the distribution, and it is almost perfectly binary:

• identities that actually run on this host — nearly everything is read.
  Unread, when it is not zero, is a handful of very recent messages.
• names registered for other machines — nearly everything is unread. Whole
  mailboxes sit at or near 100% unread, from their first message to their last.

The schema explains why. The messages table on my install has read_at and
nothing else — there is no notified/noticed column at all. So read_at IS NULL
is doing double duty: it means "was delivered to someone who did not read it"
and "was never delivered to anyone, because that name has no live session on
this machine". The only thing separating those two populations in the split
above is my own knowledge of which names are remote. Nothing in the store says
it — and no amount of precision in the counts would change that, which is why
the exact figures are not the point.

That is precisely what your receipts table makes readable, so: yes, please.
The per-recipient noticed_at / read_at split is a thing I have been
reconstructing by hand. The one thing I would ask is that the status/inbox
surface distinguishes never noticed from noticed, not read in its default
output, because those are different problems — the first is a delivery bug, the
second is a human.

One caveat on the other side, in case it affects how much you trust
"displayed": watch directives already degrade silently in the claude-code driver
today (#1270), so "the watcher showed it" is not a reliable signal in the
current code either.

---

3. One identity per (team, name) — No, but (team, name) is not unique in my roster today

Short answer to the question as asked: no, I do not deliberately run the same
name on two different tools, and collapsing the tool out of the key costs me
nothing. Where I need separation I already put it in the name. My roster
resolves to shapes like:

claude, claude-<host>, claude-<host>-herdr, claude-<other-host>, ...
codex,  codex-<host>,  codex-<host>-herdr,  codex-desktop, ...

23 registration rows, of which 6 are claude-code names and 6 are codex names.
I have folded (tool, host, terminal) into the name string by hand. So the
(team, name) constraint is, if anything, looser than what I already enforce
on myself, and "bob is bob whichever tool it runs on" is a promise I would not
use. (I would happily drop the naming convention if identities gained real
host/terminal attributes — but that is a wish, not an objection.)

Three measurements that complicate the migration, though:

(a) (team, name) does not uniquely identify a registration in my store right
now. team.sh prints 23 member rows and then reports 22 member(s) —
because one name appears twice. The two rows have the same name and the same
tool type; they differ only by working directory (a repository root, and a
subdirectory of it). One of the two carries
delivery=off (unrecognized: no settings file found ... this project may not be registered). So the duplicate is not "same agent on two tools" — the tool axis
is not what separates them, and dropping the tool from the key does not resolve
it. Whatever the migration does with (team, name, tool) → (team, name) has
to decide which of my two rows wins, and the naive answer may pick the one whose
project has no settings file. Please state the collapse rule explicitly in the
migration notes, and make it report collisions rather than silently keeping one.

(b) Identity binding already drifts, and today it is caught only because the
roster prints a checkable field. One of my entries currently reports
identity=mismatch, with the terminal's session title not matching the expected
<team>-<name> form. That is a direct counter-example to "you never declare
your role again / a session resolves its identity at startup" — resolution at
startup is exactly when a wrong binding gets established quietly. So: please keep
an equivalent of that identity=verified/unverified/mismatch field in the
daemon's status, and make a mismatch refuse delivery rather than guess. A
daemon that resolves identity automatically needs a louder verification story
than one where a human typed actas, not a quieter one.

(c) Most of the roster is, by design, not deliverable here — and that is
normal. Counting reach values across those 23 rows:

reach=cannot  19
reach=can      3
reach=unknown  1

(Counted with grep -oE 'reach=[a-z]+' | sort | uniq -c; grep -c 'reach=can'
over-counts, because it also matches cannot — worth knowing if you script
against this output.) 11 of the rows are registrations belonging to other
machines. If the daemon's status presents unreachable registrations as failures,
a normal multi-machine team will look like a fleet of broken things. Please
distinguish "not here" from "here and broken".

---

5. Control commands — per-team opt-in and an audit log are both necessary and both miss one requirement

I already run a written policy for injecting text into a pane on another host,
adopted before this RFC existed. It has two rules:

1. Every send to a pane on another host needs a human approval at that moment.
   Not a standing per-team opt-in — per send.
2. The injected text must name its sender in the first line.

Rule 2 exists because a pane write has no from field. An agmsg message
carries a sender; text typed into a pane does not. The recipient reading its own
screen cannot tell who asked. I know this rule is load-bearing because my agent
broke it five times in a single day and the recipient had no way to tell.

Mapping that onto the three options you list:

• per-team opt-in — necessary, not sufficient. Too coarse for a host where a
  human is sitting in front of the screen.
• sender allowlists — right shape, wrong side. They decide whether the write
  happens; they say nothing about what the recipient can see.
• audit log — after the fact. It tells the operator, later. The
  recipient needs to know now, at the moment the line appears on its screen.

So the requirement I would add, which is none of the three: the daemon should
stamp the authenticated sender identity into the injected text itself, not
only into the log. The daemon is the one component that actually knows who
issued the command; a convention that asks the sending agent to name itself is
something an agent can forget, and mine did. If the daemon does this
mechanically, my hand-written rule 2 becomes unnecessary and becomes
trustworthy for the first time.

And please keep per-send approval expressible, alongside per-team opt-in.
"This team may remote-poke this machine" is the right unit for a headless box
and the wrong unit for the one I am looking at.

---

6. Daemonless fallback — keep it, but do not spend much on it

I deliberately run one host as the system of record. Running the same work on
more than one machine concurrently causes conflicts, so single-host assumptions
and absolute paths are a specification in my setup, not debt. On that host I
would run agmsgd and register it with systemd without hesitating. Requiring the
daemon there costs me nothing.

Where the fallback earns its keep is the other machines: 11 of my 23 roster
rows are registrations for hosts that participate occasionally. Node 22+ is a per
machine install, and those machines mostly need to send and read, not to receive
push delivery.

So my answer is: keep the fallback, but scope it to send / inbox / history /
search on bash + sqlite, exactly as your compatibility table already draws it.
"No automatic delivery without the daemon" is a perfectly acceptable line. Do not
invest in making delivery work daemonless — I would not use that, and neither, I
suspect, would anyone who has enough machines to care.

---

One separate note: the RFC's premise is not reachable from the docs

This is a documentation gap rather than a design comment, but it affects who can
usefully review this RFC.

The RFC rests on the terminal identity shipped in 1.3.0. A reader who goes
looking for that layer in the repository does not find it:

• ARCHITECTURE.md still describes "The 3-axis driver model" (storage /
  agent / delivery) and contains zero occurrences of the word "terminal" —
  while scripts/drivers/ now holds four axis directories (partition,
  storage, terminals, types).
• docs/spec/driver-interface.md is 408 lines and contains zero occurrences of
  "terminal", so there is no written contract for what a terminal driver must
  implement.
• docs/adr/ has 0001–0004 plus ref/ 0005–0007, none of which covers the
  terminal axis.

The only prose that describes the layer is the three per-driver READMEs under
scripts/drivers/terminals/. Those are good — plain's README is where I learned
the plain:- instance-level narrowing I cited in question 1 — but they are
written for their driver, not for the model, so the shared contract has to be
inferred from three examples.

Would a documentation PR be welcome? I would be glad to write one: add the
terminal axis to ARCHITECTURE.md's model, and a terminal section to
driver-interface.md describing the operations, the capability manifest and the
instance-level narrowing, drawn entirely from the shipped code and the existing
READMEs — descriptive only, no design changes proposed. I am asking before
writing it rather than opening a PR, because the axis naming and where this
belongs (ARCHITECTURE + spec, or an ADR) are yours to set, and I would rather
not guess and then argue about it in review.

[fujibee]

Thank you for taking the time to write this up, and for re-running the measurements rather than going from memory. We are reading through it.

On the documentation PR: thanks for asking first — we would rather not take a comprehensive documentation PR here. If you raise a specific point, we will look at it and respond to that point.

[fujibee]

A short follow-up: your notes shaped a few things. In particular: (1) the delivery route is chosen per registration, from whether that registration's pane was resolved, not from whether a pane manager is present. We are fixing the RFC's wording on this. (2) when the identity does not match, delivery is refused rather than guessed. (3) "notified" and "read" are kept apart. Thanks again.

[sanie0421]

Field data from a larger-than-usual single-host deployment, in case the process-count argument in "Why now" is useful to have a number attached to.

Setup. One macOS host (Apple silicon), agmsg 1.3.1, 20 teams registered locally. Every team is one Claude Code seat + one Codex seat, each in its own tmux pane, all on monitor delivery. No remote sync (zero sync engines running). Codex seats are started by our own launcher script rather than the shipped wrapper. Everything below was measured today, not remembered.

The process herd, counted

The RFC says "roughly 15 agmsg background processes on a busy machine". Counting only processes whose command line is under the agmsg install dir or our own agmsg launchers:

ps -eo pid,lstart,command | grep -E "/\.agents/skills/agmsg/|/scripts/agmsg-" | grep -v grep

• 74 resident processes
• 42 of them started before the currently installed version (1.3.1, installed this morning)
• oldest: 41 days (9 room launchers + 1 codex-bridge.js, all from the same minute)
• breakdown: watch-once.sh 19, codex-bridge.js 19, our room launcher 15, watch.sh 12, codex-bridge-launcher.sh 7, other 2

So the herd scales with teams, and the interesting part is not the size — it is the age.

Shipping a fix does not retire the processes it fixed

codex-bridge.js per --project: 8 on one project, 2 on another, 1 each elsewhere.

• 5 of the 8 started 12 days ago with --pair <five different roles> on the same project — i.e. the pre-1.3.1 dispatcher that started every role in the project (codex: one app-server per seat, never shared (#1254) #1273, fix(codex): dispatch only a seat's recorded role #1285). We are on 1.3.1. The fixed code is installed and the buggy processes are still running, pointing at an --app-server URL that is also the stale-endpoint case (fix(codex-bridge): ignore stale request app-server URL #1293, fix(codex-bridge): ignore stale request app-server URL #1305).
• 2 more are the same seat (--team X --name Y, identical) started 40 seconds apart.

This is the same shape as the two sync engines you found while writing the note (#1103), on the bridge axis instead. It is an argument for two properties of the daemon beyond "fewer processes":

1. Refusing a duplicate registration is worth more than restarting cleanly. Nothing here errored. The duplicate and the 41-day-old process are indistinguishable from a healthy one without reading lstart.
2. install --update needs a defined answer for "processes started by the previous version". install --update: replace a running sync engine on the new code (#963) #1288 does this for sync engines; whatever agmsgd does at upgrade time is the moment that decides whether age can accumulate again.

Q2 — "displayed ⇒ read" habits: we have one, and it is written down as a rule

We do not have scripts assuming it, but we have a procedure that exists only because of it: our rooms are explicitly told never to run inbox to look at another seat's messages, use history instead, because displaying consumes. That rule is in our handbook, and new sessions get it at start.

Under receipts that rule stops being necessary — which is a real simplification, not just a semantic change. If the migration note lists "what stops being true" as well as "what changes", that line is the kind of thing that can be deleted with confidence.

Q1 — auto-selection should be right for us, with one caveat

All 20 teams are tmux panes, so pane-addressable detection should pick correctly for both seat types. The caveat is ownership rather than detection: our Codex seats are not started by the shipped wrapper, so anything that infers the route from "how the process was launched" rather than from "where it is now" would guess wrong for us. Resolving placement per delivery (as the RFC says) is what makes this safe — worth keeping explicit.

Seconding the request that the chosen route and the reason be reported in one line. Today a wrong guess is silent, and silence and "no traffic" look identical.

Q6 — we would take the daemon; the fallback is not load-bearing for us

Given 74 processes and 42 of them outliving the installed version, supervision is the feature. We would not run the daemon-less shape by choice. Keeping bash+sqlite send/receive for hosts that cannot run Node still seems right, but we would not ask you to hold back the daemon-required design on our account.

Not answering 4 (search) — we have no measurement of what we actually look for, so any operator list would be invented.

[fujibee]

Thank you for counting this on a real host. 74 resident processes, 42 of them older than the installed version, is a number we did not have, and it says more than our estimate did. We are reading through it.

[NNK-github]

Field notes from a Windows deployment, in case a third OS is useful for the shape questions. Facts below were measured on our host; where I am inferring, I say so. Issue numbers refer to the ones already on the tracker.

Setup. One Windows 11 host. Pane manager is herdr 0.9.0. agmsg is v1.3.0 plus a small local patch set (Windows process handling only); scripts run under Git Bash (MSYS). Teams are typically one Claude Code seat plus one Codex CLI seat, started and torn down by our own launcher, which calls the official scripts. Codex seats are started through herdr's agent start --kind codex -- --remote ws://… against an app-server our launcher owns, because on Windows herdr starts agents through PowerShell and never sees the bash-side wrapper or PATH shim (the same PowerShell-pane boundary we reported in #578). The Claude Code app and the Codex app also run on the same host, unmanaged.

Overall direction: yes. "Registration carries a pid, the daemon checks liveness, delivery is a typed line into the pane, despawn is executed mechanically" matches what our launcher ended up building around agmsg from the outside. Four things from our measurements that I would want the daemon to get right from day one, then the six questions.

A. Process identity on Windows: a bare pid is not a liveness token; record which namespace minted it, or use (native pid, start time)

The one delivery outage we hit on 1.3.0 was #458 / #415 in a new shape: the Codex bridge launcher writes $! (an MSYS job pid) into the pidfile, the liveness check reads it back with tasklist (native namespace), the number happened to collide with a long-lived native process (a desktop app helper), and the bridge concluded "already running" and exited every time it was started. Zero bridges armed, no natural recovery. scripts/lib/instance-id.sh:145-147 already states the rule ("for anything $! or $$ produced … use _agmsg_pid_alive_local") — it is the split you introduced after our #567 report, and it holds for the app-server probe; the bridge launcher's own pidfile path (codex-bridge-launcher.sh, the $! write and the _agmsg_pid_alive read) does not follow it, and 1.3.1 has the same two lines. We patched locally (the launcher polls until the $! job resolves to the native node.exe pid and writes that, or writes nothing) and re-verified on Codex CLI 0.155.1 today: pidfile == native pid, bridge armed, delivery round trip OK.

Why this matters for agmsgd: "each registration carries a process id, the daemon checks the process is alive before delivering, and dead entries are collected" is exactly the mechanism that failed. This is an inference, not a measurement of agmsgd: if the registration is written by a bash hook under MSYS and the liveness check runs in the Node daemon, the same mismatch reappears. Two concrete asks: (1) a registration should carry a liveness token that is unambiguous across namespaces — on Windows that is the native pid plus StartTime.Ticks, which codex-bridge.js / codex-bridge-launcher.sh already use for the lease since #978 (we verified that form on this host in that thread); (2) when the daemon cannot decide (no token, wrong namespace), treat the registration as unverified and let the message wait, rather than delivering into a pane that may belong to someone else or collecting a live seat. Related, smaller, will file separately: scripts/team-list.sh writes MSYS-spelled paths into a TSV that native python3 then cannot open (FileNotFoundError for every team).

B. A registration needs a binding generation, not just a pane id

herdr reuses pane ids, and pane move --new-workspace changes a pane's id while the seat keeps running; we measured both. (a) A placement record left behind by a closed team pointed at a pane id that a new team's Claude seat was given next, and the #1114 guard correctly refused to name the new seat — right behaviour, but any registration keyed on pane id alone will eventually point at the wrong occupant. (b) After a move, the recorded pane was gone while the seat was alive under a new id. role-session.sh:176-182 already says a reader must compare named_ref with the pane it is in now. The RFC's "re-check where a session runs at delivery time" covers (b). For (a) I would ask for two distinct generations: the terminal's (herdr exposes a terminal_id per pane and a server start time; a pane id under a different server generation is a different pane) and the binding's own (a registration instance id, so that "same pane id, same server, different occupant" is still detectable). "Pane id exists but either generation differs" should read as not this seat.

C. Typing into the pane: define "accepted", and expect composer states

We drive seats by typing into panes today, so this is the part I can speak to most concretely. Measured on Claude Code's composer under herdr: the prompt glyph differs between states (❯ idle vs › while a submission is pending), the composer can hold several lines, and a stalled submission leaves /agmsg actas <name> or /exit sitting unsent — a subsequent typed line then appends to it or is swallowed. ctrl+a is not select-all there (it moves to line start); ctrl+e followed by backspaces is what reliably clears. A daemon that types a notification into that composer will meet the same states. The RFC's "if the typing fails … nothing is recorded" is the right principle; the ask is to define "succeeded" as the pane read back shows the line was consumed and the composer is empty (not "the send-text call returned"), and to record noticed only then. Otherwise noticed gets recorded for a line that is sitting unsent.

D. Claude Code's own channel is bounded; say who re-arms it

Measured on Claude Code 2.1.27x: a Monitor watch expires at 5 minutes by default and at most 30 minutes with an explicit timeout; persistent is ignored (#1270, the directive fixed in #1287, re-arm made opt-in in #1315 with rearm.sh). While it is expired the session is not woken; the message waits in the store, which is fine for the store, but the session stays deaf until something re-arms it. For seats under a pane manager the daemon's pane write sidesteps this — good. For the "no pane manager, fall back to the tool's channel" branch, please state in the design that the channel is bounded and who re-arms it; otherwise a pane-less Claude session silently goes deaf after 30 minutes.

The six questions

1. Auto-selected mode. One case where the guess is wrong from the agent's point of view: a Codex seat started via herdr agent start … --remote runs its hooks in the app-server's context, so from inside the seat where.sh reports placement=none terminal=plain, HERDR_PANE_ID is empty, and herdr's agent_session for that pane is also empty — while from the outside herdr lists the pane and the occupant process within seconds. So please decide the route from the daemon's view of the registration and the terminal driver (pane known → write into it), not from what the agent's own environment claims, and expose the chosen route and the reason in status, as the first commenter also asked. On Windows also expect pane process-info not to show MSYS children (the foreground process is bash.exe), so occupancy should come from the terminal's agent list plus agmsg's own placement record, never from process ancestry.
2. Noticed is not read. No such habit on our side: our launcher's residue and teardown checks look at registrations, role-sessions, placements and pidfiles, never at read marks. The one thing we would need is a read-only way for an outside tool to ask "anything noticed-but-unread for this recipient?" before it archives a seat.
3. One identity per (team, name). Yes, please; we never run the same name on two tools on purpose. What we do rely on is the opposite guarantee, and it is about the binding (the registration instance that ties a session to an identity), not the name: after a fresh (new thread, same name) the old session must not keep the binding, and a not-yet-read ctrl:despawn addressed while the old binding held must not be delivered to the new one (codex monitor: after despawn + spawn --fresh, the launcher binds the previous seat's thread before actas, and rows sent in that window are consumed into a thread no TUI shows #1266 shape). If control messages are executed by the daemon this mostly disappears, but their receipts should be keyed to the binding.
4. Search. Modest: team:, from:, to:, after:/before:, words, plus exact message id and the reply chain. A month back is plenty for us.
5. Control commands. Before enabling anything beyond same-machine same-team despawn: per-team opt-in on the receiving machine, a sender allowlist and an audit log, as listed — plus two things from running teardown ourselves. (a) The result must say whether the target actually ended (pane gone, process gone, registration removed), distinct from "command accepted". Today a graceful despawn for a seat without a watcher always times out and the only path to completion is --force, so we require a human-declared actor for it. (b) A despawn that could not confirm the stop must not archive, reset or reuse that seat's records. Our own launcher once did exactly that — a teardown that failed to obtain the team's generation archived and reset the records of seats it had not stopped, orphaning them — and we had to add the fail-closed rule ourselves; despawn.sh already keeps the record on an unconfirmed force. If the daemon owns despawn, please keep that invariant inside it.
6. Daemonless fallback. We would run the daemon (Node is already on the host for our launcher). We would not miss the daemonless path. What we would need instead is a status that answers "is the daemon running, which version, which registrations does it hold" — today the equivalent question means reading pidfiles and ps across two pid namespaces.

Happy to re-run any of the above on the Windows host against a branch.

[fujibee]

Thank you for the notes from a Windows host, and for marking what you measured apart from what you inferred. We are reading through them.