oacp-cli 0.2.2__tar.gz → 0.2.3__tar.gz

{oacp_cli-0.2.2 → oacp_cli-0.2.3}/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.3] - 2026-04-26
+
+### Changed
+
+- `oacp watch` defaults are now notification-friendly: existing inbox messages are no longer replayed on the first scan for a target, and `message_archived` events are suppressed by default. Pass `--since=epoch` to restore replay and `--show-archived` to re-enable archive events. Reduces noise for `Monitor` and `oacp watch` consumers.
+
+### Added
+
+- `oacp watch --since=<spec>` — controls the first-run baseline cutoff. Accepts `now` (default), `epoch`, relative durations (`30s`, `5m`, `2h`, `7d`), or ISO 8601 timestamps. Only applies on first run for a target (no state file yet).
+- `oacp watch --show-archived` — opt-in flag to emit `message_archived` events. Useful for observer agents tracking another agent's inbox; disabled by default because the watching agent's own deletes are self-loops.
+
 ## [0.2.2] - 2026-04-17
 
 ### Added
@@ -110,6 +121,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Checkout step in github-release workflow job (#19)
 - Pre-release audit fixes: SHA-pinned actions, dangling doc refs (#15, #16)
 
+[0.2.3]: https://github.com/kiloloop/oacp/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/kiloloop/oacp/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/kiloloop/oacp/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/kiloloop/oacp/compare/v0.1.9...v0.2.0

{oacp_cli-0.2.2 → oacp_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oacp-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: Open Agent Coordination Protocol CLI for file-based multi-agent workflows
 Project-URL: Homepage, https://github.com/kiloloop/oacp
 Project-URL: Repository, https://github.com/kiloloop/oacp
@@ -165,7 +165,7 @@ uv tool install .
 
 **`oacp send`**: `--in-reply-to`, `--expires`, `--body-file`, `--channel`, `--dry-run`, `--json`, `--quiet`
 
-**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`
+**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`, `--since` (default `now`), `--show-archived`
 
 **`oacp doctor`**: `--fix` (auto-fix safe issues), `--json`, `-o/--output`
 

{oacp_cli-0.2.2 → oacp_cli-0.2.3}/README.md

@@ -139,7 +139,7 @@ uv tool install .
 
 **`oacp send`**: `--in-reply-to`, `--expires`, `--body-file`, `--channel`, `--dry-run`, `--json`, `--quiet`
 
-**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`
+**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`, `--since` (default `now`), `--show-archived`
 
 **`oacp doctor`**: `--fix` (auto-fix safe issues), `--json`, `-o/--output`
 

{oacp_cli-0.2.2 → oacp_cli-0.2.3}/docs/guides/runtime_capability_matrix.md

@@ -1,10 +1,12 @@
 # Cross-Runtime Parity Matrix
 
-**Date**: 2026-04-17
+**Date**: 2026-04-24
 
 This is a capability comparison across 3 agent runtimes (Claude Code, Codex, Gemini), compiled from each runtime's self-report and current runtime changelogs. Use this as a reference when deciding which agent to assign for a given task.
 
-Codex was last checked against the official Codex changelog entries for app update `26.415` (2026-04-16) and `Codex CLI 0.121.0` (2026-04-15).
+Claude was last checked against Claude Code `v2.1.118`.
+
+Codex was last checked against app update `26.415`, CLI `0.123.0`, and OpenAI's GPT-5.5 launch note from 2026-04-23.
 
 ---
 
@@ -15,31 +17,32 @@ Codex was last checked against the official Codex changelog entries for app upda
 | Spawn background tasks | Yes — Task tool + Bash `run_in_background`                                 | Yes — shell background processes                                                               | Yes — `run_command` async mode                                        |
 | Spawn subagents        | Yes — typed agents (Explore, Plan, general-purpose, code-reviewer, etc.)   | Yes — native `spawn_agent` lifecycle with `default`, `explorer`, and `worker` agents          | Partial — `browser_subagent` only                                     |
 | Parallel agent teams   | Yes — TeamCreate, task lists, SendMessage, broadcast                       | Partial — parallel spawned agents are supported, but there is no team/task-list primitive      | No — parallel tool calls but no independent agent instances           |
-| MCP tools              | Yes — extensible via MCP servers                                           | Yes — MCP/plugin support depends on configured servers and marketplaces                        | Yes — MCP server support                                              |
+| MCP tools              | Yes — extensible via MCP servers                                           | Yes — MCP/plugin support with `/mcp verbose` diagnostics; configuration-dependent             | Yes — MCP server support                                              |
 | Web search             | Yes — native WebSearch tool                                                | Yes — web search/fetch tools                                                                   | Yes — native `search_web` tool                                        |
 | Browser interaction    | Partial — WebFetch (read-only, HTML→markdown)                              | Partial — web tools plus early in-app browser for local/public pages without sign-in           | Yes — full browser control (click, type, navigate, screenshot, video) |
-| File system access     | Sandboxed — configurable read/write allowlists                             | Policy-dependent per session                                                                   | Full — unrestricted                                                   |
+| File system access     | Sandboxed — configurable read/write allowlists                             | Policy-dependent per session; sandbox profiles can include deny-read rules                     | Full — unrestricted                                                   |
 | Git operations         | Yes — via Bash (may need sandbox configuration)                            | Yes — native                                                                                   | Yes — via shell                                                       |
 | GitHub CLI (gh)        | Yes — via Bash (may need sandbox configuration)                            | Yes — authenticated                                                                            | Yes — native                                                          |
 | Session memory         | Strong — auto-loaded MEMORY.md + optional MCP memory                       | Partial — app memories where available plus OACP file memory; app memories are not protocol SSOT | Partial — Knowledge Items (not directly writable), conversation logs  |
-| Interactive mode       | Yes — CLI chat with permissions, plan mode                                 | Yes — desktop app                                                                              | Yes — chat with task UI, artifacts                                    |
-| Context window         | ~1M with Opus 4.7 (auto-compaction extends indefinitely)                   | Not directly exposed; practically finite                                                       | ~1M tokens                                                            |
-| Cost model             | Token-based, visible in statusline                                         | Not surfaced in runtime                                                                        | Token-based                                                           |
-| Sandbox restrictions   | Yes — configurable allowlists                                              | Session-dependent                                                                              | None — full system access                                             |
+| Interactive mode       | Yes — CLI chat with permissions, plan mode                                 | Yes — desktop app and CLI/TUI, including Plan Mode and side conversations                      | Yes — chat with task UI, artifacts                                    |
+| Context window         | ~1M with Opus 4.7 (auto-compaction extends indefinitely)                   | Model-dependent; GPT-5.5 in Codex is documented at 400K, with no auto-compaction guarantee      | ~1M tokens                                                            |
+| Cost model             | Token-based, visible in statusline                                         | Not surfaced per session; GPT-5.5 Fast mode trades 2.5x cost for 1.5x token generation speed   | Token-based                                                           |
+| Sandbox restrictions   | Yes — configurable allowlists                                              | Session-dependent; supports deny-read policies, isolated `codex exec`, and remote sandbox requirements | None — full system access                                             |
 
 ---
 
-## 2. Unique Capabilities (Only One Runtime Has)
+## 2. Distinctive Capabilities
 
 | Capability                       | Runtime       | Details                                                                      |
 | -------------------------------- | ------------- | ---------------------------------------------------------------------------- |
 | Typed subagent orchestration     | Claude        | Multiple agent types with scoped tools and model selection                   |
 | Team coordination primitive      | Claude        | TeamCreate + task lists + assignment + broadcast + shutdown                  |
-| Plan mode                        | Claude        | Structured explore → plan → approve → implement workflow                     |
+| Plan mode                        | Claude, Codex | Claude has structured explore → plan → approve → implement; Codex CLI can move from planning into fresh-context implementation |
 | Auto-compaction                  | Claude        | Context auto-compresses, enabling unlimited session length                   |
 | Cross-session semantic search    | Claude        | MCP-based searchable memory (optional)                                       |
 | Browser automation (full)        | Gemini        | Click, type, navigate, screenshot, WebP video recording                      |
-| Image generation                 | Gemini        | Native `generate_image` tool                                                 |
+| GPT-5.5 model availability       | Codex         | Available in Codex for Plus, Pro, Business, Enterprise, Edu, and Go plans with a 400K context window |
+| Image generation                 | Codex, Gemini | Codex CLI image generation is enabled by default; Gemini has native `generate_image` |
 | URL content reading (no browser) | Gemini        | `read_url_content` fetches HTML→markdown or PDF directly                     |
 | Code outline navigation          | Gemini        | `view_file_outline`, `view_code_item` for structured exploration             |
 | PTY / terminal stdin             | Codex, Gemini | Codex: native PTY; Gemini: `send_command_input` (Claude lacks stdin support) |
@@ -68,9 +71,9 @@ Scope: skills shipped in [`kiloloop/oacp-skills`](https://github.com/kiloloop/oa
 
 | Dimension       | Claude                                                                 | Codex                                                                   | Gemini                                                               |
 | --------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| Best at         | Orchestration, multi-agent teams, persistent memory, plan-then-execute | Terminal-native execution, fast iterative patching, app-assisted PR/artifact review, protocol discipline | Web research, browser automation, visual verification, large context |
-| Ideal task type | Team coordination, complex multi-file refactors, long-running sessions | Shell-heavy workflows, targeted file edits, deterministic scripts, PR follow-up, artifact review | External research, UI testing, document review, MCP integrations     |
-| Cost profile    | Flexible (haiku subagents for cheap tasks, opus for complex)           | Not directly visible                                                    | Token-based, web search has additional costs                         |
+| Best at         | Orchestration, multi-agent teams, persistent memory, plan-then-execute | Terminal-native execution, GPT-5.5 agentic coding, fast iterative patching, plan-to-implementation handoff, app-assisted PR/artifact review, protocol discipline | Web research, browser automation, visual verification, large context |
+| Ideal task type | Team coordination, complex multi-file refactors, long-running sessions | Shell-heavy workflows, long-horizon coding, targeted file edits, deterministic scripts, PR follow-up, artifact review, CLI planning passes | External research, UI testing, document review, MCP integrations     |
+| Cost profile    | Flexible (haiku subagents for cheap tasks, opus for complex)           | Per-session cost not visible; GPT-5.5 is described as more token-efficient than GPT-5.4 for Codex tasks | Token-based, web search has additional costs                         |
 
 ---
 
@@ -80,11 +83,11 @@ Scope: skills shipped in [`kiloloop/oacp-skills`](https://github.com/kiloloop/oa
 | ----------------------------- | ----------------------------- | -------------------------------------------------------------- | ---------------------- |
 | No subagents                  | —                             | Yes                                                            | Partial (browser only) |
 | No browser automation         | Yes (read-only)               | Partial (in-app browser is not full automation and excludes sign-in flows) | —                      |
-| No image generation           | Yes                           | Yes                                                            | —                      |
+| No image generation           | Yes                           | —                                                              | —                      |
 | No persistent writable memory | —                             | Partial (app memories are not a replacement for OACP durable memory) | Yes                    |
 | Sandbox friction              | Yes (configurable)            | Session-dependent                                              | —                      |
 | No team primitive             | —                             | Yes                                                            | Yes                    |
-| Context limits                | Auto-compaction mitigates     | Yes (no compaction)                                            | Large but finite       |
+| Context limits                | Auto-compaction mitigates     | Model-dependent; GPT-5.5 in Codex is 400K, but there is no documented auto-compaction behavior | Large but finite       |
 | No terminal stdin             | Yes                           | —                                                              | —                      |
 | Cost not surfaced             | —                             | Yes                                                            | —                      |
 
@@ -110,6 +113,7 @@ These are the highest-impact gaps where one runtime's limitation blocks effectiv
 | Dimension                    | Claude                           | Codex                                      | Gemini                                        |
 | ---------------------------- | -------------------------------- | ------------------------------------------ | --------------------------------------------- |
 | Max parallel tool calls      | ~10+                             | Yes (parallel independent calls)           | ~10 (practical)                               |
+| Side conversations           | No                               | Yes (`/side` in CLI/TUI)                   | No                                            |
 | Hooks system                 | Yes (pre/post tool call hooks)   | No                                         | No                                            |
 | Automation scheduling        | Yes (`CronCreate`, `ScheduleWakeup`, `/loop`, `/schedule` skills) | Yes (desktop app thread automations wake a thread on a schedule, with user request) | No                                            |
 | Notebook editing             | Yes (NotebookEdit tool)          | No                                         | No                                            |
@@ -117,6 +121,8 @@ These are the highest-impact gaps where one runtime's limitation blocks effectiv
 | Image reading (multimodal)   | Yes                              | Yes (desktop app local image/view support) | Yes                                           |
 | Artifact system              | No                               | Yes (sidebar preview for generated files) | Yes (task.md, implementation plans)           |
 | Video recording              | No                               | No                                         | Yes (WebP via browser)                        |
+| Image generation             | No                               | Yes (enabled by default in CLI)            | Yes                                           |
+| MCP diagnostics              | Partial                          | Yes (`/mcp verbose`)                       | Partial                                       |
 | Multi-file editing primitive | Edit tool (one file at a time)   | `apply_patch` (one file)                   | `multi_replace_file_content` (non-contiguous) |
 | Workflow file format         | SKILL.md with YAML frontmatter   | SKILL.md with YAML frontmatter             | Markdown with YAML frontmatter                |
 | Policy visibility at runtime | Partial (sandbox config visible) | Yes (session policy in system context)     | Yes (`SafeToAutoRun` flags)                   |
@@ -124,4 +130,10 @@ These are the highest-impact gaps where one runtime's limitation blocks effectiv
 
 ---
 
+## 8. Source Notes
+
+- GPT-5.5 Codex availability, 400K context, Fast mode, token-efficiency, and API timing come from OpenAI's 2026-04-23 release note: <https://openai.com/index/introducing-gpt-5-5/>.
+
+---
+
 *Each runtime should update only its own column. Discrepancies should be resolved by the runtime owner.*

{oacp_cli-0.2.2 → oacp_cli-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oacp-cli"
-version = "0.2.2"
+version = "0.2.3"
 description = "Open Agent Coordination Protocol CLI for file-based multi-agent workflows"
 readme = "README.md"
 license = "Apache-2.0"

{oacp_cli-0.2.2 → oacp_cli-0.2.3}/scripts/oacp_watch.py

@@ -18,7 +18,9 @@ from __future__ import annotations
 import argparse
 import json
 import sys
+import time
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional, Sequence
 
@@ -30,6 +32,37 @@ except ImportError:  # pragma: no cover
 
 STATE_VERSION = 1
 
+_DURATION_UNITS = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+
+
+def _parse_since(spec: str, *, now: float) -> float:
+    """Parse a --since spec to an epoch timestamp.
+
+    Accepts: 'now', 'epoch', duration like '30s' / '5m' / '2h' / '7d',
+    or an ISO 8601 timestamp (trailing 'Z' allowed; naive timestamps treated as UTC).
+    """
+    if spec == "now":
+        return now
+    if spec == "epoch":
+        return 0.0
+    if (
+        len(spec) >= 2
+        and spec[-1] in _DURATION_UNITS
+        and spec[:-1].isdigit()
+    ):
+        return now - int(spec[:-1]) * _DURATION_UNITS[spec[-1]]
+    try:
+        normalized = spec[:-1] + "+00:00" if spec.endswith("Z") else spec
+        dt = datetime.fromisoformat(normalized)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(
+            f"--since: cannot parse {spec!r} "
+            "(use 'now', 'epoch', a duration like '30s'/'5m'/'2h'/'7d', or an ISO 8601 timestamp)"
+        ) from exc
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.timestamp()
+
 
 @dataclass(frozen=True)
 class WatchTarget:
@@ -222,9 +255,10 @@ def _resolve_targets(
     return targets, errors
 
 
-def _load_state(state_file: Path) -> Dict[str, Any]:
+def _load_state(state_file: Path) -> tuple[Dict[str, Any], bool]:
+    """Return (state, existed). `existed` is False for first-run targets."""
     if not state_file.is_file():
-        return {"version": STATE_VERSION, "messages": {}}
+        return {"version": STATE_VERSION, "messages": {}}, False
     data = json.loads(state_file.read_text(encoding="utf-8"))
     if not isinstance(data, dict):
         raise ValueError("state file root must be a JSON object")
@@ -237,7 +271,10 @@ def _load_state(state_file: Path) -> Dict[str, Any]:
             normalized[str(file_name)] = {
                 key: str(value) for key, value in metadata.items()
             }
-    return {"version": int(data.get("version", STATE_VERSION)), "messages": normalized}
+    return (
+        {"version": int(data.get("version", STATE_VERSION)), "messages": normalized},
+        True,
+    )
 
 
 def _write_state(state_file: Path, payload: Dict[str, Any]) -> None:
@@ -252,9 +289,10 @@ def _write_state(state_file: Path, payload: Dict[str, Any]) -> None:
 
 def _scan_target(
     target: WatchTarget,
-) -> tuple[Dict[str, Dict[str, str]], List[Dict[str, Any]]]:
+) -> tuple[Dict[str, Dict[str, str]], Dict[str, float], List[Dict[str, Any]]]:
     errors: List[Dict[str, Any]] = []
     current_messages: Dict[str, Dict[str, str]] = {}
+    mtimes: Dict[str, float] = {}
     for path in sorted(
         candidate
         for candidate in target.inbox_dir.iterdir()
@@ -262,6 +300,7 @@ def _scan_target(
     ):
         try:
             metadata = _message_metadata(target.project, target.agent, path)
+            mtime = path.stat().st_mtime
         except Exception as exc:
             errors.append(
                 _error_event(
@@ -280,13 +319,16 @@ def _scan_target(
             "subject": metadata["subject"],
             "priority": metadata["priority"],
         }
-    return current_messages, errors
+        mtimes[path.name] = mtime
+    return current_messages, mtimes, errors
 
 
 def _build_delta_events(
     target: WatchTarget,
     previous_messages: Dict[str, Dict[str, str]],
     current_messages: Dict[str, Dict[str, str]],
+    *,
+    show_archived: bool,
 ) -> List[Dict[str, Any]]:
     events: List[Dict[str, Any]] = []
     for file_name in sorted(current_messages.keys() - previous_messages.keys()):
@@ -297,14 +339,15 @@ def _build_delta_events(
         }
         event.update(current_messages[file_name])
         events.append(event)
-    for file_name in sorted(previous_messages.keys() - current_messages.keys()):
-        event = {
-            "event": "message_archived",
-            "project": target.project,
-            "agent": target.agent,
-        }
-        event.update(previous_messages[file_name])
-        events.append(event)
+    if show_archived:
+        for file_name in sorted(previous_messages.keys() - current_messages.keys()):
+            event = {
+                "event": "message_archived",
+                "project": target.project,
+                "agent": target.agent,
+            }
+            event.update(previous_messages[file_name])
+            events.append(event)
     return events
 
 
@@ -330,8 +373,31 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
     parser.add_argument("--agent", required=True, help="Agent inbox name to watch")
     parser.add_argument("--oacp-dir", default=None, help="Override OACP home directory")
     parser.add_argument("--json", action="store_true", dest="json_output", help="Emit JSON Lines")
+    parser.add_argument(
+        "--since",
+        default="now",
+        help=(
+            "Cutoff for first-run baseline: 'now' (default) suppresses replay of "
+            "existing inbox messages; 'epoch' replays everything; '30s'/'5m'/'2h'/'7d' "
+            "for relative windows; ISO 8601 ('2026-04-26T00:00:00Z') for absolute. "
+            "Only applies on first run for a target (no state file yet)."
+        ),
+    )
+    parser.add_argument(
+        "--show-archived",
+        action="store_true",
+        help=(
+            "Emit 'message_archived' events when messages disappear from the inbox. "
+            "Off by default — when the watching agent is also the inbox owner, "
+            "these events are self-loops (the agent already knows it deleted them)."
+        ),
+    )
 
     args = parser.parse_args(list(argv) if argv is not None else None)
+    try:
+        since_epoch = _parse_since(args.since, now=time.time())
+    except argparse.ArgumentTypeError as exc:
+        parser.error(str(exc))
     oacp_root = _resolve_oacp_home(args.oacp_dir)
 
     targets, target_errors = _resolve_targets(
@@ -352,7 +418,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
 
     for target in targets:
         try:
-            previous_state = _load_state(target.state_file)
+            previous_state, state_existed = _load_state(target.state_file)
         except Exception as exc:
             had_errors = True
             _emit_error(
@@ -365,13 +431,26 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 json_output=args.json_output,
             )
             continue
-        current_messages, scan_errors = _scan_target(target)
+        current_messages, mtimes, scan_errors = _scan_target(target)
         if scan_errors:
             had_errors = True
             for event in scan_errors:
                 _emit_error(event, json_output=args.json_output)
         previous_messages = previous_state["messages"]
-        target_events = _build_delta_events(target, previous_messages, current_messages)
+        if not state_existed:
+            # First run for this target: seed baseline with messages whose mtime <= since.
+            # NEW_MESSAGE events fire only for files newer than the cutoff.
+            previous_messages = {
+                file_name: current_messages[file_name]
+                for file_name in current_messages
+                if mtimes.get(file_name, 0.0) <= since_epoch
+            }
+        target_events = _build_delta_events(
+            target,
+            previous_messages,
+            current_messages,
+            show_archived=args.show_archived,
+        )
         payload = {
             "version": STATE_VERSION,
             "project": target.project,

{oacp_cli-0.2.2 → oacp_cli-0.2.3}/tests/test_oacp_watch.py

@@ -6,8 +6,10 @@ from __future__ import annotations
 
 import io
 import json
+import os
 import sys
 import tempfile
+import time
 import unittest
 from pathlib import Path
 
@@ -64,7 +66,7 @@ class TestOacpWatch(unittest.TestCase):
             sys.stderr = old_stderr
         return code, stdout, stderr
 
-    def test_first_run_emits_existing_messages(self) -> None:
+    def test_default_first_run_suppresses_existing_messages(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             root = Path(tmpdir)
             _write_message(
@@ -82,6 +84,36 @@ class TestOacpWatch(unittest.TestCase):
             )
         self.assertEqual(code, 0)
         self.assertEqual(stderr, "")
+        self.assertEqual(stdout, "")
+
+    def test_first_run_with_since_epoch_emits_existing_messages(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            _write_message(
+                root,
+                "demo",
+                "codex",
+                "20260411050000_iris_task_request_abcd.yaml",
+                sender="iris",
+                msg_type="task_request",
+                priority="P2",
+                subject="First",
+            )
+            code, stdout, stderr = self._run(
+                [
+                    "--agent",
+                    "codex",
+                    "--project",
+                    "demo",
+                    "--oacp-dir",
+                    tmpdir,
+                    "--since",
+                    "epoch",
+                    "--json",
+                ]
+            )
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
         events = [json.loads(line) for line in stdout.splitlines() if line.strip()]
         self.assertEqual(len(events), 1)
         self.assertEqual(events[0]["event"], "new_message")
@@ -147,7 +179,7 @@ class TestOacpWatch(unittest.TestCase):
         self.assertEqual(events[0]["subject"], "Second")
         self.assertEqual(events[0]["priority"], "P1")
 
-    def test_removed_message_emits_message_archived(self) -> None:
+    def test_removed_message_emits_message_archived_when_show_archived(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             root = Path(tmpdir)
             msg_path = _write_message(
@@ -160,10 +192,32 @@ class TestOacpWatch(unittest.TestCase):
                 priority="P2",
                 subject="First",
             )
-            self._run(["--agent", "codex", "--project", "demo", "--oacp-dir", tmpdir, "--json"])
+            self._run(
+                [
+                    "--agent",
+                    "codex",
+                    "--project",
+                    "demo",
+                    "--oacp-dir",
+                    tmpdir,
+                    "--since",
+                    "epoch",
+                    "--show-archived",
+                    "--json",
+                ]
+            )
             msg_path.unlink()
             code, stdout, stderr = self._run(
-                ["--agent", "codex", "--project", "demo", "--oacp-dir", tmpdir, "--json"]
+                [
+                    "--agent",
+                    "codex",
+                    "--project",
+                    "demo",
+                    "--oacp-dir",
+                    tmpdir,
+                    "--show-archived",
+                    "--json",
+                ]
             )
         self.assertEqual(code, 0)
         self.assertEqual(stderr, "")
@@ -172,6 +226,41 @@ class TestOacpWatch(unittest.TestCase):
         self.assertEqual(events[0]["event"], "message_archived")
         self.assertEqual(events[0]["subject"], "First")
 
+    def test_removed_message_suppressed_by_default(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            msg_path = _write_message(
+                root,
+                "demo",
+                "codex",
+                "20260411050000_iris_task_request_abcd.yaml",
+                sender="iris",
+                msg_type="task_request",
+                priority="P2",
+                subject="First",
+            )
+            # Seed baseline so the message is tracked in state.
+            self._run(
+                [
+                    "--agent",
+                    "codex",
+                    "--project",
+                    "demo",
+                    "--oacp-dir",
+                    tmpdir,
+                    "--since",
+                    "epoch",
+                    "--json",
+                ]
+            )
+            msg_path.unlink()
+            code, stdout, stderr = self._run(
+                ["--agent", "codex", "--project", "demo", "--oacp-dir", tmpdir, "--json"]
+            )
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        self.assertEqual(stdout, "")
+
     def test_repeatable_project_keeps_argument_order(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             root = Path(tmpdir)
@@ -205,6 +294,8 @@ class TestOacpWatch(unittest.TestCase):
                     "alpha",
                     "--oacp-dir",
                     tmpdir,
+                    "--since",
+                    "epoch",
                     "--json",
                 ]
             )
@@ -237,7 +328,16 @@ class TestOacpWatch(unittest.TestCase):
                 subject="Alpha",
             )
             code, stdout, stderr = self._run(
-                ["--agent", "codex", "--all-projects", "--oacp-dir", tmpdir, "--json"]
+                [
+                    "--agent",
+                    "codex",
+                    "--all-projects",
+                    "--oacp-dir",
+                    tmpdir,
+                    "--since",
+                    "epoch",
+                    "--json",
+                ]
             )
         self.assertEqual(code, 0)
         self.assertEqual(stderr, "")
@@ -277,7 +377,17 @@ class TestOacpWatch(unittest.TestCase):
             (inbox_dir / "broken.yaml").write_text("subject: [unterminated\n", encoding="utf-8")
 
             first_code, first_stdout, first_stderr = self._run(
-                ["--agent", "codex", "--project", "demo", "--oacp-dir", tmpdir, "--json"]
+                [
+                    "--agent",
+                    "codex",
+                    "--project",
+                    "demo",
+                    "--oacp-dir",
+                    tmpdir,
+                    "--since",
+                    "epoch",
+                    "--json",
+                ]
             )
             second_code, second_stdout, second_stderr = self._run(
                 ["--agent", "codex", "--project", "demo", "--oacp-dir", tmpdir, "--json"]
@@ -330,6 +440,8 @@ class TestOacpWatch(unittest.TestCase):
                     "missing",
                     "--oacp-dir",
                     tmpdir,
+                    "--since",
+                    "epoch",
                     "--json",
                 ]
             )
@@ -341,5 +453,104 @@ class TestOacpWatch(unittest.TestCase):
         self.assertEqual(events[1]["project"], "valid")
 
 
+    def test_since_relative_duration_only_emits_new_files(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            old_path = _write_message(
+                root,
+                "demo",
+                "codex",
+                "20260411050000_iris_task_request_old.yaml",
+                sender="iris",
+                msg_type="task_request",
+                priority="P2",
+                subject="Old",
+            )
+            # Backdate the old message to 1 hour ago.
+            old_time = time.time() - 3600
+            os.utime(old_path, (old_time, old_time))
+
+            _write_message(
+                root,
+                "demo",
+                "codex",
+                "20260411060000_iris_task_request_new.yaml",
+                sender="iris",
+                msg_type="task_request",
+                priority="P1",
+                subject="New",
+            )
+
+            code, stdout, stderr = self._run(
+                [
+                    "--agent",
+                    "codex",
+                    "--project",
+                    "demo",
+                    "--oacp-dir",
+                    tmpdir,
+                    "--since",
+                    "5m",
+                    "--json",
+                ]
+            )
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        events = [json.loads(line) for line in stdout.splitlines() if line.strip()]
+        self.assertEqual(len(events), 1)
+        self.assertEqual(events[0]["event"], "new_message")
+        self.assertEqual(events[0]["subject"], "New")
+
+    def test_since_iso_timestamp_with_z_suffix(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            _write_message(
+                root,
+                "demo",
+                "codex",
+                "20260411050000_iris_task_request_abcd.yaml",
+                sender="iris",
+                msg_type="task_request",
+                priority="P2",
+                subject="First",
+            )
+            code, stdout, stderr = self._run(
+                [
+                    "--agent",
+                    "codex",
+                    "--project",
+                    "demo",
+                    "--oacp-dir",
+                    tmpdir,
+                    "--since",
+                    "1970-01-01T00:00:00Z",
+                    "--json",
+                ]
+            )
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        events = [json.loads(line) for line in stdout.splitlines() if line.strip()]
+        self.assertEqual(len(events), 1)
+        self.assertEqual(events[0]["subject"], "First")
+
+    def test_since_invalid_spec_exits_with_usage_error(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            with self.assertRaises(SystemExit) as ctx:
+                self._run(
+                    [
+                        "--agent",
+                        "codex",
+                        "--project",
+                        "demo",
+                        "--oacp-dir",
+                        tmpdir,
+                        "--since",
+                        "not-a-valid-spec",
+                        "--json",
+                    ]
+                )
+        self.assertEqual(ctx.exception.code, 2)
+
+
 if __name__ == "__main__":
     unittest.main()