0.3.3: validate recipient is live before send/reply

Agents were sending postcards to 3-word addresses from long-ended
peer sessions. Since addresses are per-session and don't persist
across restarts, those sends silently landed in orphan inboxes
that cleanup would later garbage-collect — making it look like the
message went through when no peer ever read it.

`send` and `reply` now check the recipient against the live
directory and error out with a message pointing the agent at
`oat-postcard directory` to see who's actually reachable. `--force`
added to both verbs for the rare case you want to drop a postcard
into an orphan inbox intentionally.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jwesleye

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Asynchronous 1-to-1 postcard messaging between AI agent sessions via a Git-backed ledger",
-    "version": "0.3.2"
+    "version": "0.3.3"
   },
   "plugins": [
     {
       "name": "postcard",
       "source": "./",
       "description": "Postcard protocol for cross-session AI agent messaging. Ships a CLI, slash commands, a model-invoked skill, a Clerk subagent for inbox triage, and SessionStart / Stop / UserPromptSubmit hooks.",
-      "version": "0.3.2",
+      "version": "0.3.3",
       "license": "MIT",
       "repository": "https://github.com/Open-Agent-Tools/Postcard",
       "keywords": ["messaging", "agents", "ledger", "git", "async", "multi-agent"]

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "postcard",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Asynchronous 1-to-1 postcard messaging between AI agent sessions via a Git-backed ledger.",
   "author": {
     "name": "Open Agent Tools"

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to oat-postcard. Dates are UTC.
 
+## [0.3.3] - 2026-04-22
+
+### Changed
+- `send` and `reply` now validate the recipient against the live
+  directory and error out by default if the address is not active.
+  Previously sends to dead addresses silently wrote to an orphan
+  inbox that `cleanup` would later garbage-collect — making it look
+  like the message went through when in fact no peer ever read it.
+  Since 3-word addresses are per-session and don't persist across
+  restarts, a dead-address send is almost always a bug.
+- Error format: `error: address 'foo-bar-baz' is not in the live
+  directory. Run 'oat-postcard directory' to see active peers;
+  --force to send anyway.` (Or the equivalent "parent sender no
+  longer in the live directory" variant for `reply`.)
+- `--force` flag added to both `send` and `reply` to bypass the check
+  when you intentionally want to drop a postcard into an orphan
+  inbox (testing, debugging).
+- New helper `directory.is_active(address) -> bool`.
+
 ## [0.3.2] - 2026-04-22
 
 ### Changed

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oat-postcard"
-version = "0.3.2"
+version = "0.3.3"
 description = "Asynchronous 1-to-1 postcard messaging between AI agent sessions via a Git-backed ledger."
 readme = "README.md"
 license = { text = "MIT" }

src/oat_postcard/__init__.py

@@ -1 +1 @@
-__version__ = "0.3.2"
+__version__ = "0.3.3"

src/oat_postcard/cli.py

@@ -45,21 +45,38 @@ def _reply_title(parent_title: str) -> str:
 
 
 def _cmd_send(args: argparse.Namespace) -> int:
-    from . import ledger, session
+    from . import directory, ledger, session
 
+    if not args.force and not directory.is_active(args.address):
+        print(
+            f"error: address {args.address!r} is not in the live directory. "
+            "Run 'oat-postcard directory' to see active peers; --force to "
+            "send anyway.",
+            file=sys.stderr,
+        )
+        return 1
     sender = session.resolve_or_init()
     pc = ledger.send(sender, args.address, args.title, args.body)
     print(f"sent {pc.id[:8]} to {args.address}")
     return 0
 
 
 def _cmd_reply(args: argparse.Namespace) -> int:
-    from . import ledger, session
+    from . import directory, ledger, session
 
     parent = ledger.get_postcard(args.parent_id)
     if parent is None:
         print(f"error: no postcard matching {args.parent_id!r}", file=sys.stderr)
         return 1
+    if not args.force and not directory.is_active(parent.sender):
+        print(
+            f"error: parent sender {parent.sender!r} is no longer in the live "
+            "directory (their session has ended). Addresses are per-session "
+            "and don't persist across restarts. Use --force to reply into "
+            "the orphan inbox anyway.",
+            file=sys.stderr,
+        )
+        return 1
     sender = session.resolve_or_init()
     title = _reply_title(parent.title)
     pc = ledger.send(sender, parent.sender, title, args.body, reply_to=parent.id)
@@ -315,6 +332,11 @@ def build_parser() -> argparse.ArgumentParser:
     p_send.add_argument("address")
     p_send.add_argument("title")
     p_send.add_argument("body")
+    p_send.add_argument(
+        "--force",
+        action="store_true",
+        help="send even if the recipient is not in the live directory",
+    )
     p_send.set_defaults(func=_cmd_send)
 
     p_reply = sub.add_parser(
@@ -323,6 +345,11 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_reply.add_argument("parent_id", help="parent postcard id (full or 8-char prefix)")
     p_reply.add_argument("body")
+    p_reply.add_argument(
+        "--force",
+        action="store_true",
+        help="reply even if the parent sender is no longer active",
+    )
     p_reply.set_defaults(func=_cmd_reply)
 
     p_inbox = sub.add_parser(

src/oat_postcard/directory.py

@@ -73,6 +73,10 @@ def resolve(address: str) -> Entry | None:
     return Entry(**data)
 
 
+def is_active(address: str) -> bool:
+    return any(e.address == address for e in list_active())
+
+
 def list_active(prune: bool = True) -> list[Entry]:
     paths.ensure_root()
     entries: list[Entry] = []

tests/test_cli.py

@@ -1,8 +1,19 @@
+import os
 from datetime import datetime, timezone
+from pathlib import Path
 
 import pytest
 
-from oat_postcard import cli, ledger, session
+from oat_postcard import cli, directory, ledger, session
+
+
+def _register_live_peer(address: str) -> None:
+    directory.register(
+        address=address,
+        session_id=f"test-{address}",
+        pid=os.getpid(),
+        cwd=Path.cwd(),
+    )
 
 
 def test_parse_time_window_accepts_shorthand():
@@ -37,6 +48,7 @@ def test_reply_title_truncates_to_max():
 
 def test_reply_cmd_sends_with_reply_to(tmp_root, session_env, capsys):
     me = session.init_session()
+    _register_live_peer("peer")
     parent = ledger.send("peer", me, "parent title", "parent body")
 
     rc = cli.main(["reply", parent.id[:8], "acknowledged"])
@@ -115,6 +127,7 @@ def test_log_rejects_bad_time_spec(tmp_root, session_env, capsys):
 
 def test_send_oversized_body_returns_clean_error(tmp_root, session_env, capsys):
     session.init_session()
+    _register_live_peer("peer")
     big = "x" * (ledger.BODY_MAX + 1)
     rc = cli.main(["send", "peer", "short title", big])
     assert rc == 1
@@ -125,8 +138,52 @@ def test_send_oversized_body_returns_clean_error(tmp_root, session_env, capsys):
 
 def test_send_oversized_title_returns_clean_error(tmp_root, session_env, capsys):
     session.init_session()
+    _register_live_peer("peer")
     rc = cli.main(["send", "peer", "x" * (ledger.TITLE_MAX + 1), "body"])
     assert rc == 1
     err = capsys.readouterr().err
     assert "title exceeds" in err
     assert "Traceback" not in err
+
+
+def test_send_rejects_dead_address(tmp_root, session_env, capsys):
+    session.init_session()
+    rc = cli.main(["send", "ghost-dead-address", "t", "b"])
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert "not in the live directory" in err
+    assert "'ghost-dead-address'" in err
+    assert "--force" in err
+    # No postcard should have been written
+    assert ledger.log() == []
+
+
+def test_send_force_bypasses_dead_address_check(tmp_root, session_env, capsys):
+    session.init_session()
+    rc = cli.main(["send", "--force", "ghost-dead-address", "t", "b"])
+    assert rc == 0
+    assert "sent" in capsys.readouterr().out
+    cards = ledger.log()
+    assert len(cards) == 1 and cards[0].recipient == "ghost-dead-address"
+
+
+def test_reply_rejects_dead_parent_sender(tmp_root, session_env, capsys):
+    me = session.init_session()
+    # Parent came from a peer who is no longer in the directory
+    parent = ledger.send("ghost-peer", me, "parent", "body")
+    rc = cli.main(["reply", parent.id[:8], "acknowledged"])
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert "no longer in the live directory" in err
+    assert "'ghost-peer'" in err
+    assert "--force" in err
+
+
+def test_reply_force_bypasses_dead_parent_sender_check(tmp_root, session_env, capsys):
+    me = session.init_session()
+    parent = ledger.send("ghost-peer", me, "parent", "body")
+    rc = cli.main(["reply", "--force", parent.id[:8], "acknowledged"])
+    assert rc == 0
+    cards = ledger.log()
+    reply = next(c for c in cards if c.reply_to == parent.id)
+    assert reply.recipient == "ghost-peer"