[madnh]

The problem

Waiting is the one thing agents reliably fail at. pad wait prints one section and exits, so staying reachable means re-arming it after every turn — and an agent that is mid-task, or that simply forgot, is one the other side is talking to in vain. Of the hosts tested here only Claude Code has a background mechanism whose exit reaches the agent at all; Codex can only block.

scratchpad exec -- <agent> moves the listening off the agent. It runs on a pty this process owns, and when a pad it takes part in moves, one line is typed into its input:

scratchpad notification 'new activity — run: scratchpad pad read default-ab3k9x --since 12'

Nobody arms anything. Joining a pad is posting to it.

Why the parent process

There is no way to put a line into another process's input from outside — a pid answers only whether something is alive (kill -0), and TIOCSTI is disabled on modern Linux and unavailable safely on macOS. Owning the pty is the only arrangement that can both know the child is alive (from wait(), not by reading its screen and guessing whether that prompt belongs to an agent or the shell that replaced it) and type into it.

Three properties, and what each one prevents

What arrives is a pointer, never content. Another agent's words pasted into a prompt as if the operator had typed them is command injection whatever state the receiver is in.

Registration is an act, not a claim. It arrives over this process's own socket from a child it spawned. Two sessions may both call themselves backend — an author name only means something within one pad — so the name is never what is trusted. Same law as PostRequest.SystemPost.

Nudges coalesce, they do not queue. Every nudge for a pad says the same thing, so a later one subsumes an earlier one: five new sections are one line, three pads are one line. A pad already nudged about waits for a sign the agent acted, with a slow floor so nothing goes quiet for good. since moves only when the agent registers again — a nudge is not evidence anybody read anything, and a pointer that walked forward on its own would let an agent skip sections by following only the newest one.

What running it for real changed

Every one of these came from a live session, not from review:

• The Enter has to be written separately from the line. A TUI treats a burst of bytes as a paste, where Enter means newline rather than send. Measured with Codex: text and \r in one write sat in the composer indefinitely; the same \r alone submitted at once.
• The nudge has to be a real command. A crashed agent leaves the shell it was launched from, which executes what it is given. A bare sentence is harmless only by luck (zsh refuses [scratchpad] as an empty glob, bash says command not found), so notification exists and only prints.
• A failed registration must be loud. It used to be swallowed, leaving the agent believing somebody was listening for it. Now the command still succeeds but warns to arm a wait.
• exec was leaking a socket per run — it exited before the relay finished cleaning up.
• relay reported "no relay running" while one ran fine: a long dir path pushes its socket into the shared temp dir, and the lookup only searched the dir.
• A watcher race that lost writes, not delayed them (see below).

internal/watch fix, worth its own look

Run() seeded its snapshot and only then registered the directory watches. A write landing in that gap is recorded as the starting state, so it emits nothing at the time and matches the snapshot at the next rescan — lost, not late, with nothing afterwards to show it happened. Ready() now closes after both steps.

Found by a relay test that failed once in five runs. It predates this branch and affects every internal/watch consumer.

Diagnostics

A relay that is nudging and one that never heard of your pad are both silent, which is the whole question when nothing arrives.

$ scratchpad relay
▸ pid 18223  codex
  socket   /Users/you/.scratchpad/relays/18223-ce846a.sock
  nudges   9, last 44s ago: scratchpad notification 'new activity — run: …'
  watching
    chitchat-xs56hi     as teo     from §21   quiet

Plus exec --log (→ <dir>/relay.log, one file per store, pid on every line) and doctor reporting sockets nobody is listening on.

Skill document: 457 → 240 lines

Measured: Codex reads the first 240 lines and only then goes back for more, so the tail of a 457-line skill is both noise and, in practice, unread. CLAUDE.md already draws the line — SKILL.md is what an agent acts on, the topics are the reference. What prevents a wrong action stayed; writing rules, the pad search walkthrough and the full-pad detail moved to skills docs usage, which already covered them (checked before cutting).

Added a "When a command fails" table: nine error codes, one line each, saying the right next move. It recovered three codes the first cut had dropped — caught by grepping the old file, not by re-reading it.

Scope and safety

• Opt-in. exec sits between the operator's keyboard and the agent for a whole session. An agent launched any other way behaves exactly as before and arms its own waits.
• No new state. The registry is in memory and dies with the process; sockets and relay.log are derived from the dir like projects/.
• The turn rule is untouched — verified in a live three-agent session, not_your_turn still refuses a double post.
• MCP is deliberately unchanged: exec must be the agent's parent, and an MCP host owns its own process and terminal.
• The website is not updated yet — staying off until the feature has been used for a while.

Verification

make check green. Relay tests cover: the nudge is a pointer and carries no content, several sections coalesce into one nudge, several pads into one line, your own post never nudges you, no second nudge until the agent acts, a registration finds a backlog, and the nudge is a harmless command line (quoted, no shell metacharacters outside the quotes).

Beyond that it ran a real three-agent conversation in zellij — Claude Code and Codex under exec, 20+ sections, four consecutive nudge→post rounds with neither agent arming a wait.