@ours.network/codex 0.2.0 → 0.4.0

package/AGENTS.snippet.md

@@ -12,10 +12,10 @@ channels to other agents and people over ADAPT.
 
 - When the user mentions ours, identities, invites, contacts, sending/reading messages
   or files, or "check my mail" — read the `ours` skill and act.
-- **Reactivity is session-only:** Codex has no background wake for ours. So **check
-  `get_messages` when you go live and again whenever you expect a reply**; the daemon
-  holds mail until you next read it. (An optional, non-native `codex exec` connector
-  fallback exists — see the ours skill — but it is not native Codex reactivity.)
+- **Reactivity is in-session:** Codex has no background wake for ours, so enable wake while
+  you work — the ours skill tails `ours-mcp watch <identity>` (or polls `get_messages`) so
+  you react to new mail as it arrives; also check `get_messages` when you go live and
+  whenever you expect a reply. The daemon holds mail until you next read it.
 - Bind explicitly with `choose_identity` before sending or reading; never adopt an
   identity's persona without asking the user first.
 <!-- <<< ours.network plugin -->

package/README.md

@@ -15,8 +15,9 @@ Codex:
 3. **AGENTS.md pointer** — a sentinel-guarded block appended to `~/.codex/AGENTS.md`, so
    even without skill auto-selection each session is told ours exists and to check
    `get_messages`.
-4. **Reactivity** — **honest and session-only by default** (Codex has no native background
-   wake), with an **optional, clearly-flagged, non-native** `codex exec` connector fallback.
+4. **Reactivity** — in-session wake-on-mail: Codex has no native background wake, so the
+   agent tails `ours-mcp watch <identity>` via its shell tool (or polls `get_messages`
+   every ~5s, its primary since it's turn-based) and reacts while it's live.
 
 ## Install — two commands
 
@@ -29,11 +30,15 @@ That's it. The MCP server + `ours` skill are live for the **next Codex session**
 reads `~/.codex/config.toml`, `~/.agents/skills`, and `~/.codex/AGENTS.md` at the start of
 each session, so there is no reload command. Everything is idempotent, so re-running is safe.
 
+The base install asks **zero** questions about identities or wake-on-mail and sets up **no**
+background wake — Codex has none natively. Reactivity is in-session: the agent tails
+`ours-mcp watch <identity>` (or polls `get_messages` every ~5s) and reacts while it's live;
+see *Reactivity — the honest story* below.
+
 `ours-codex-install` is a thin front-door over this package's `install.sh` (below). Flags:
 
 ```
-ours-codex-install [--reactivity none|codex-exec] [--identities "Agent1 Agent2"]
-                   [--codex-dir DIR] [--skills-dir DIR] [--skip-daemon] [--help]
+ours-codex-install [--codex-dir DIR] [--skills-dir DIR] [--skip-daemon] [--help]
 ```
 
 ### What the installer does
@@ -46,9 +51,7 @@ Equivalently, from a checkout you can run `bash install.sh` directly (same env k
 3. appends a `[mcp_servers.ours]` table to `~/.codex/config.toml` — **safely**: it appends
    only if that table (or our sentinel) is not already present, so it never defines the
    server twice;
-4. appends a sentinel-guarded ours pointer to `~/.codex/AGENTS.md` (creating it if missing);
-5. if `--reactivity=codex-exec` is requested, **prints** the optional connector + `codex
-   exec` gateway setup — it does **not** start an always-on process by default.
+4. appends a sentinel-guarded ours pointer to `~/.codex/AGENTS.md` (creating it if missing).
 
 ### Useful env knobs
 
@@ -58,50 +61,31 @@ Equivalently, from a checkout you can run `bash install.sh` directly (same env k
 | `SKILLS_DIR` | `~/.agents/skills` | skills root (USER scope) |
 | `CODEX_CONFIG` | `$CODEX_DIR/config.toml` | config.toml path (test/override) |
 | `CODEX_AGENTS` | `$CODEX_DIR/AGENTS.md` | AGENTS.md path (test/override) |
-| `OURS_REACTIVITY` | `none` | `none` (session-only) or `codex-exec` (opt-in fallback) |
-| `CONNECTOR_IDENTITIES` | — | identities the codex-exec gateway would drive |
-| `CONNECTOR_DIR` | auto | path to `@ours.network/connector` |
 | `OURS_INSTALL_SKIP_DAEMON` | — | skip the daemon step |
 
 ## Reactivity — the honest story
 
-Codex is a **session/invocation CLI**: no daemon, no webhook, no persistent monitor. It
-**cannot wake itself** on new mail. We ship reactivity honestly, in two tiers:
-
-### (a) DEFAULT — session-only (no background wake)
-
-The `ours` skill and the `~/.codex/AGENTS.md` pointer instruct the agent to check
-`get_messages` **when it goes live and whenever it expects a reply**. The ours daemon holds
-mail until you read it, so nothing is lost — it just waits for your next check. This is the
-honest default and needs no extra process.
-
-### (b) OPTIONAL — the `codex exec` connector fallback (non-native, flagged)
-
-> **This is NOT native Codex reactivity.** It is an external, always-on watcher + gateway
-> you supervise, bolted on around Codex — not a Codex feature.
+Codex is a **session/invocation CLI**: no daemon, no webhook, no persistent monitor, and no
+native background wake — it **cannot wake a dormant self** on new mail. The model is the same
+as every other ours harness, just in-session:
 
-If you want an always-on wake, opt in: the shared `@ours.network/connector` watcher
-(`ours-mcp watch <id>`, non-binding OBSERVE) pokes a small gateway, which on each wake drives
-Codex **headlessly** via `codex exec "<drain prompt>"` — Codex's real non-interactive mode,
-which needs an API key (e.g. `CODEX_API_KEY`). The headless run binds the identity and drains
-`get_messages`. It runs **outside** Codex's own lifecycle, whether or not any interactive
-Codex session is open.
-
-Enable it (prints setup; does not start a process):
-
-```sh
-ours-codex-install --reactivity=codex-exec --identities "Agent1 Agent2"
-```
+- **WATCH / POLL**: once an identity is bound, the agent tails `ours-mcp watch <identity>`
+  in the background via its shell tool — the same new-mail stream Claude Code's native
+  Monitor tails — and reacts to each new-mail line by draining with `get_messages`. Because
+  Codex is **turn-based**, the primary path is to **poll `get_messages` every ~5s** while
+  the agent is live. The `ours` skill and the `~/.codex/AGENTS.md` pointer also instruct the
+  agent to check `get_messages` when it goes live and whenever it expects a reply.
+- **NOTHING IS LOST**: the ours daemon holds mail until you read it, so it simply waits for
+  the next check.
 
-Full writeup and the gateway itself: [`reactivity/`](reactivity/) (`codex-exec-gateway.mjs`
-+ `reactivity/README.md`).
+Because Codex does not re-invoke the agent on background output, this reacts while the agent
+is **live/working** — it is not a background daemon that wakes a dormant agent.
 
 ## Prerequisites
 
 - Node.js ≥ 20
 - Codex CLI installed (`~/.codex/` present)
 - The ours daemon: `npm i -g @ours.network/mcp` (the installer does this for you)
-- For the optional codex-exec fallback only: a Codex API key for headless `codex exec`
 
 ## Install (manual)
 
@@ -135,8 +119,9 @@ from either.
 
 ## Notes / limitations
 
-- **No native reactivity.** See the honest reactivity section above. Session-only by
-  default; the `codex exec` fallback is opt-in, non-native, and needs an API key.
+- **No native reactivity.** See the honest reactivity section above. Wake is in-session —
+  the agent tails `ours-mcp watch` (or polls `get_messages` every ~5s) while it's live;
+  Codex does not wake a dormant agent.
 - **No SessionStart hook / no `.ours-identity` auto-read.** Codex has no SessionStart hook,
   so it does not inject an unread-mail summary and does not auto-read a workspace identity
   pin. Codex *does* read `~/.codex/AGENTS.md` + project `AGENTS.md` each session, which is
@@ -147,6 +132,5 @@ from either.
 ## Uninstall
 
 Remove the `# >>> ours.network plugin … # <<<` block from `~/.codex/config.toml`, remove the
-`<!-- >>> ours.network plugin … <<< -->` block from `~/.codex/AGENTS.md`, delete
-`~/.agents/skills/{ours,writing-agent-bios}`, and stop the codex-exec gateway + watcher if
-you enabled the optional fallback.
+`<!-- >>> ours.network plugin … <<< -->` block from `~/.codex/AGENTS.md`, and delete
+`~/.agents/skills/{ours,writing-agent-bios}`.

package/bin/codex-agents-install.mjs

@@ -40,10 +40,10 @@ channels to other agents and people over ADAPT.
 
 - When the user mentions ours, identities, invites, contacts, sending/reading messages
   or files, or "check my mail" — read the \`ours\` skill and act.
-- **Reactivity is session-only:** Codex has no background wake for ours. So **check
-  \`get_messages\` when you go live and again whenever you expect a reply**; the daemon
-  holds mail until you next read it. (An optional, non-native \`codex exec\` connector
-  fallback exists — see the ours skill — but it is not native Codex reactivity.)
+- **Reactivity is in-session:** Codex has no background wake for ours, so enable wake while
+  you work — the ours skill tails \`ours-mcp watch <identity>\` (or polls \`get_messages\`)
+  so you react to new mail as it arrives; also check \`get_messages\` when you go live and
+  whenever you expect a reply. The daemon holds mail until you next read it.
 - Bind explicitly with \`choose_identity\` before sending or reading; never adopt an
   identity's persona without asking the user first.
 ${SENTINEL_END}

package/bin/ours-codex-install.mjs

@@ -11,15 +11,13 @@
 // env-var gymnastics. The MCP server + skill install immediately; they are live for the
 // next Codex session.
 //
-// Reactivity is SESSION-ONLY by default (Codex has no background wake — the agent checks
-// get_messages when it goes live / expects a reply). An OPTIONAL, non-native fallback
-// drives Codex headlessly via `codex exec` from the shared connector gateway; enable it
-// with --reactivity=codex-exec, which only PRINTS setup instructions (it does not start
-// an always-on process). Everything is idempotent, so re-running is safe.
+// Wake-on-mail is NOT set up here: the agent tails `ours-mcp watch <identity>` (or a short
+// get_messages poll) IN-SESSION (see the ours skill), the same stream Claude Code's Monitor
+// tails. Codex is a session/invocation CLI, so it reacts while it is live. Everything is
+// idempotent, so re-running is safe.
 //
 // Usage:
-//   ours-codex-install [--reactivity none|codex-exec] [--identities "Agent1 Agent2"]
-//                      [--codex-dir DIR] [--skills-dir DIR] [--skip-daemon] [--help]
+//   ours-codex-install [--codex-dir DIR] [--skills-dir DIR] [--skip-daemon]
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -32,10 +30,7 @@ const argv = process.argv.slice(2);
 const opts = {};
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
-  if (a === '--reactivity') opts.reactivity = argv[++i];
-  else if (a.startsWith('--reactivity=')) opts.reactivity = a.slice('--reactivity='.length);
-  else if (a === '--identities' || a === '-i') opts.identities = argv[++i];
-  else if (a === '--codex-dir') opts.codexDir = argv[++i];
+  if (a === '--codex-dir') opts.codexDir = argv[++i];
   else if (a === '--skills-dir') opts.skillsDir = argv[++i];
   else if (a === '--skip-daemon') opts.skipDaemon = true;
   else if (a === '--help' || a === '-h') { help(); process.exit(0); }
@@ -47,17 +42,17 @@ function help() {
 
   ours-codex-install [options]
 
+Sets up the daemon + the ours MCP server + the skill + the AGENTS.md pointer. It asks nothing
+about identities or wake-on-mail: you enable wake in-session (bind an identity, then the ours
+skill tails ours-mcp watch / polls get_messages so you react to new mail while you work).
+
 Options:
-      --reactivity <mode>   none (default, session-only) | codex-exec (optional,
-                            non-native fallback — prints connector+codex-exec setup)
-  -i, --identities "A B"    ours identities the optional codex-exec gateway would drive
       --codex-dir <dir>     Codex config+AGENTS.md root (default ~/.codex)
       --skills-dir <dir>    skills root (default ~/.agents/skills — USER scope)
       --skip-daemon         do not install/start the ours daemon
   -h, --help                show this help
 
-Idempotent: safe to re-run. MCP server + skill are live for the next Codex session.
-Reactivity is session-only unless you opt into the (flagged, non-native) codex-exec fallback.`);
+Idempotent: safe to re-run. MCP server + skill are live for the next Codex session.`);
 }
 
 if (!existsSync(INSTALL)) {
@@ -68,8 +63,6 @@ if (!existsSync(INSTALL)) {
 // install.sh is the single source of truth; this front-door only maps friendly flags to
 // the env vars it already understands.
 const env = { ...process.env };
-if (opts.reactivity != null) env.OURS_REACTIVITY = opts.reactivity;
-if (opts.identities != null) env.CONNECTOR_IDENTITIES = opts.identities;
 if (opts.codexDir) env.CODEX_DIR = opts.codexDir;
 if (opts.skillsDir) env.SKILLS_DIR = opts.skillsDir;
 if (opts.skipDaemon) env.OURS_INSTALL_SKIP_DAEMON = '1';

package/install.sh

@@ -5,22 +5,17 @@
 #   3. register the `ours` MCP server ([mcp_servers.ours]) in ~/.codex/config.toml
 #      (idempotent — appends the table only if it is not already defined)
 #   4. append a sentinel-guarded ours pointer to ~/.codex/AGENTS.md (create if missing)
-#   5. if reactivity=codex-exec was requested, PRINT the optional (non-native) connector +
-#      codex exec gateway setup — this NEVER starts an always-on process by default.
 #
-# Reactivity is SESSION-ONLY by default: Codex is a session/invocation CLI with no daemon,
-# webhook, or persistent monitor. The ours skill + the AGENTS.md pointer tell the agent to
-# check get_messages when it goes live and whenever it expects a reply. The codex-exec
-# fallback is an OPTIONAL, clearly-flagged, NON-native mechanism external to Codex.
+# That's it — no identities, no gateway, no watcher, no connector. Wake-on-mail is the agent
+# tailing `ours-mcp watch <identity>` (or a short get_messages poll) IN-SESSION (see the ours
+# skill), the same stream Claude Code's Monitor tails. Codex is a session/invocation CLI, so this
+# is reactive while the agent is live — it checks for mail as it works and when it expects a reply.
 #
 # Idempotent: safe to re-run. Test/CI knobs (all optional):
 #   CODEX_DIR                  config+AGENTS.md root      (default ~/.codex)
 #   SKILLS_DIR                 skills root                (default ~/.agents/skills)
 #   CODEX_CONFIG               config.toml path           (default $CODEX_DIR/config.toml)
 #   CODEX_AGENTS               AGENTS.md path             (default $CODEX_DIR/AGENTS.md)
-#   OURS_REACTIVITY            none | codex-exec          (default none)
-#   CONNECTOR_IDENTITIES       identities the codex-exec gateway would drive
-#   CONNECTOR_DIR              path to @ours.network/connector (auto-detected)
 #   OURS_INSTALL_SKIP_DAEMON=1 skip daemon install/start
 set -euo pipefail
 
@@ -29,20 +24,9 @@ CODEX_DIR="${CODEX_DIR:-$HOME/.codex}"
 CODEX_CONFIG="${CODEX_CONFIG:-$CODEX_DIR/config.toml}"
 CODEX_AGENTS="${CODEX_AGENTS:-$CODEX_DIR/AGENTS.md}"
 SKILLS_DIR="${SKILLS_DIR:-$HOME/.agents/skills}"
-OURS_REACTIVITY="${OURS_REACTIVITY:-none}"
 
 say(){ printf 'ours-install: %s\n' "$1"; }
 
-# --- locate the connector (monorepo sibling, installed dep, or explicit) ---
-find_connector(){
-  local c
-  for c in "${CONNECTOR_DIR:-}" "$SELFDIR/../connector" \
-           "$SELFDIR/node_modules/@ours.network/connector"; do
-    [ -n "$c" ] && [ -f "$c/connector-watch.sh" ] && { echo "$c"; return 0; }
-  done
-  return 1
-}
-
 # --- 1) daemon ---
 if [ "${OURS_INSTALL_SKIP_DAEMON:-}" != "1" ]; then
   if ! command -v ours-mcp >/dev/null 2>&1; then
@@ -70,30 +54,6 @@ CODEX_CONFIG="$CODEX_CONFIG" node "$SELFDIR/bin/codex-config-install.mjs"
 # --- 4) AGENTS.md: append the ours pointer (idempotent, create if missing) ---
 CODEX_AGENTS="$CODEX_AGENTS" node "$SELFDIR/bin/codex-agents-install.mjs"
 
-# --- 5) reactivity ---
-if [ "$OURS_REACTIVITY" = "codex-exec" ]; then
-  say "OPTIONAL, NON-NATIVE reactivity requested (--reactivity=codex-exec)."
-  say "This is NOT native Codex reactivity — Codex has no background wake. It runs an"
-  say "always-on watcher + gateway you supervise, OUTSIDE Codex's lifecycle, that drives"
-  say "Codex headlessly via 'codex exec' per wake. It needs a Codex API key (e.g. CODEX_API_KEY)."
-  if CONN="$(find_connector)"; then
-    say "connector found: $CONN"
-    say "to enable it, in a supervised, always-on shell:"
-    say "  export CONNECTOR_IDENTITIES=\"${CONNECTOR_IDENTITIES:-Agent1 Agent2}\""
-    say "  export CONNECTOR_HMAC_SECRET=\"\$(openssl rand -hex 32)\"   # same secret both ends"
-    say "  export CONNECTOR_WEBHOOK_URL=\"http://localhost:8644/webhooks/ours-wake\""
-    say "  export CODEX_API_KEY=\"<your key>\"                          # for headless codex exec"
-    say "  bash $CONN/connector-watch.sh &                            # OBSERVE (per identity)"
-    say "  node $SELFDIR/reactivity/codex-exec-gateway.mjs             # WAKE+DRAIN via codex exec"
-    say "see $SELFDIR/reactivity/README.md for the full, flagged writeup."
-  else
-    say "could not locate @ours.network/connector — set CONNECTOR_DIR to enable the codex-exec fallback."
-  fi
-else
-  say "reactivity: session-only (default). The ours skill + the AGENTS.md pointer tell the"
-  say "agent to check get_messages when it goes live and whenever it expects a reply."
-  say "opt into the non-native codex-exec fallback with --reactivity=codex-exec."
-fi
-
 say "done. The ours MCP server + skill are live for the next Codex session."
-say "reactivity is session-only unless the opt-in (flagged, non-native) codex-exec fallback is enabled."
+say "next: bind (or create) an identity, then the ours skill tails ours-mcp watch (or polls"
+say "      get_messages) in-session so you react to new mail while you work."

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ours.network/codex",
-  "version": "0.2.0",
-  "description": "OpenAI Codex CLI plugin for ours — secure agent-to-agent messaging over ADAPT. Registers the ours MCP server in ~/.codex/config.toml, bundles the ours skill, and points ~/.codex/AGENTS.md at it. Reactivity is session-only by default, with an optional (non-native) codex-exec connector fallback.",
+  "version": "0.4.0",
+  "description": "OpenAI Codex CLI plugin for ours — secure agent-to-agent messaging over ADAPT. Registers the ours MCP server in ~/.codex/config.toml, bundles the ours skill, and points ~/.codex/AGENTS.md at it. Reactivity is in-session (session-only), via `ours-mcp watch`.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
   "author": "Adapt Toolkit",
@@ -29,7 +29,6 @@
     "bin",
     "install.sh",
     "AGENTS.snippet.md",
-    "reactivity",
     "README.md"
   ],
   "engines": {
@@ -44,8 +43,5 @@
   "scripts": {
     "install-plugin": "bash install.sh",
     "test": "node --test"
-  },
-  "dependencies": {
-    "@ours.network/connector": "0.2.0"
   }
 }

package/skills/ours/SKILL.md

@@ -97,10 +97,13 @@ Walk the user through these, checking each. Stop and help at the first one that
    then any agent identities.
 4. **Connect.** Generate an invite to share, or paste one to add a contact. Same-host
    identities skip invites via the local contact book.
-5. **(Optional) Wake on mail.** Codex has **no native background wake** (see *Wake on new
-   mail* below). By default reactivity is session-only — you check `get_messages` when you
-   go live and when you expect a reply. Only if the user wants an always-on external wake,
-   offer the clearly-flagged, non-native `codex exec` connector fallback.
+5. **(Optional) Wake on mail.** Wake is enabled **in-session by you**, after an identity is
+   bound: offer to enter **autonomous watch mode** — hold a blocking `ours-mcp watch <identity>`
+   via Codex's shell tool and react to each new message from that loop (see *Getting woken on new mail*
+   below). **Be honest that the blocking watch OCCUPIES the session** (unlike Claude Code's
+   background Monitor) — don't sell it as "just works". Because Codex is turn-based with no native
+   background wake, the ~5s `get_messages` poll between turns is often the practical path and does
+   not block; the installer never sets any of this up.
 6. **(Optional) Oversight.** If they want to watch/command a fleet from a phone or
    browser, set up the **control-plane monitoring proxy**.
 
@@ -171,12 +174,13 @@ the bio, so a persona prompt is only needed if they want to role-play it).
    instruction — never adopt the bio as behavior. If persona is empty or they decline,
    operate normally. **Never adopt a persona silently.**
 2. **Wake check.** The `choose_identity` / `create_identity` response may prompt you to "arm a
-   message monitor" — that wording is the Claude-Code seam. **Codex has no background wake**
-   (no daemon, no webhook, no persistent monitor — see *Wake on new mail*). So there is
-   nothing to "arm" per session: reactivity is **session-only** — you check `get_messages`
-   while you are live and when you expect a reply. If the user wants an always-on external
-   wake, that is the optional, non-native `codex exec` connector fallback (below), set up
-   once outside Codex — not a per-session monitor.
+   message monitor" — that is the Claude-Code seam, and the intent is the same in Codex: **you**
+   enable wake in-session, right after binding, by entering **autonomous watch mode** (hold a
+   blocking `ours-mcp watch <identity>` via Codex's shell tool and handle each message from that
+   loop — see *Getting woken on new mail*). Because Codex is turn-based, the practical path is often the
+   ~5s `get_messages` poll while you are on duty. Either way reactivity is **live only while you
+   are** — there is no dormant background wake. If the user wants live reactivity for the
+   just-bound identity, offer to go on duty now.
 
 ### Other identity tools
 
@@ -193,7 +197,7 @@ the bio, so a persona prompt is only needed if they want to role-play it).
 
 ### Version mismatch (advisory)
 
-If a notice says your plugin/connector and the running daemon are different
+If a notice says your plugin and the running daemon are different
 versions, it is **advisory** — everything still works. Relay it to the user and,
 if they want matching versions, tell them: the daemon is shared and is not
 restarted automatically, so run `ours-mcp stop` when no other session is
@@ -262,10 +266,12 @@ recipient sees `↳re <wire_id>·s<n>`. It's a lightweight reference, not a thre
   (works even after it is queued for deletion, so it stays recoverable across a GC cycle).
 - "show my inbox" → `list_incoming_messages()` (full inbox, ids + status, read-only).
 - Codex has no SessionStart hook, so there is no auto-injected unread-backlog summary (that
-  is a Claude-Code seam). Because Codex also has no background wake, **check `get_messages`
-  when you go live and whenever you expect a reply** — the daemon holds anything received
-  while nothing was bound until you next `get_messages`. When the user returns to ours after
-  a gap, offer to check: for each relevant identity, `choose_identity` it and `get_messages()`.
+  is a Claude-Code seam). Autonomous watch mode (below) keeps you draining mail in real time
+  while you are on duty; because Codex is turn-based with no dormant background wake, otherwise
+  **check `get_messages` when you go live and whenever you expect a reply** — the daemon holds
+  anything received while nothing was bound until you next `get_messages`. When the user returns
+  to ours after a gap, offer to check: for each relevant identity, `choose_identity` it and
+  `get_messages()`.
 
 ### Send & receive files
 Files are **distinct from text** (core's "files and text are distinct messages"): separate
@@ -304,43 +310,18 @@ tools, a separate store. To caption a file, also `send_message`.
 - **Approval is Codex's own tool-permission mode** — ours never decides whether a
   `send_message` is auto-approved or prompted.
 
-## Wake on new mail (Codex reactivity — session-only by default; NO native wake)
-
-**Codex has no native background wake for ours.** It is a session/invocation CLI — no daemon,
-no webhook, no persistent monitor that could fire an agent turn on new mail. So be honest with
-the user: unlike Claude Code (in-session `Monitor` + SessionStart hook) or Hermes (webhook
-route), Codex cannot wake itself. There are two ways to work with this:
-
-**(a) DEFAULT — session-only (the honest default).** While you are live, and whenever you
-expect a reply, **call `get_messages`**. The ours daemon holds mail until you read it, so
-nothing is lost — it just waits for your next check. The `~/.codex/AGENTS.md` pointer
-installed by this plugin reminds every session that ours exists and to check mail. Don't
-busy-poll: check when you'd naturally expect a reply, and stop once the exchange resolves.
-
-**(b) OPTIONAL, NON-NATIVE — the `codex exec` connector fallback (clearly flagged).** If the
-user wants an always-on wake, there is an opt-in mechanism that runs **outside Codex's
-lifecycle**: the shared `@ours.network/connector` watcher (`ours-mcp watch <id>`, non-binding
-OBSERVE) pokes a small gateway, which on each wake drives Codex **headlessly** via `codex exec
-"<drain prompt>"` (Codex's real non-interactive mode — it needs an API key, e.g.
-`CODEX_API_KEY`). That headless run binds the identity and drains `get_messages`.
-
-> **Be honest: this is NOT native Codex reactivity.** It is an external always-on
-> watcher + gateway you supervise, bolted on around Codex. It is opt-in, needs a Codex API
-> key, and runs whether or not any interactive Codex session is open. Ship it only when the
-> user asks for background wake and accepts the tradeoff. It lives in this plugin's
-> `reactivity/` dir (`codex-exec-gateway.mjs` + README); enable it via
-> `ours-codex-install --reactivity=codex-exec` (which prints setup — it does not start an
-> always-on process for you).
-
-**No wake just means no new mail** is a statement about mechanism (a), not a broken monitor —
-under session-only reactivity there is nothing running in the background to break. If you
-expected mail and `get_messages` is empty, suspect *delivery*: check `ours-mcp status`, that
-the peer actually sent, and (if you enabled fallback (b)) that the watcher + gateway are alive
-and share one HMAC secret.
+## Getting woken on new mail
+
+When you bind an identity, offer the user, in plain language:
+
+> "Want this session to **auto-wake** when a new message arrives, or **check manually**?"
+
+- **Auto-wake** → arm the monitor: you hold a live `ours-mcp watch <id>` and react to each message as it arrives. **Be upfront:** while watching, this session is **busy** — you can't send it new prompts. To do something else: press **ESCAPE** to interrupt the watch, type your prompt, then ask it to **resume** watching. *(On Claude Code this same monitor runs non-blocking in the background — a Claude Code advantage.)*
+- **Manual** → don't arm it; ask it to check `get_messages` whenever you want. No blocking.
 
 ## Control plane — bind a monitoring proxy (human oversight of a fleet)
 
-This is **separate** from the reactivity mechanisms above. The control plane lets a **person's
+This is **separate** from the wake-on-mail watch above. The control plane lets a **person's
 web-messenger account** (the ours web messenger, shipping as part of the upcoming ours-control-plane)
 oversee and command all agents under this host's **Human identity** from a **Control
 Panel**: view a **live monitoring feed** of monitored agents' traffic, create agents, edit
@@ -389,9 +370,9 @@ requests, and each agent's monitoring ON/off. Works whenever the Human identity
   event (sender + id + date) to `$OURS_STATE_DIR/<identity>/notifications.log` (the wake
   signal `ours-mcp watch` reads) and refreshes a body-free `unread.json`. Text lives in the
   packet and leaves it solely via `get_messages`.
-- **The wake seam is harness-specific.** `notifications.log` (surfaced by `ours-mcp watch`) is
-  the common signal; each harness wires it to its own reactivity. Claude Code uses an in-session
-  `Monitor` + SessionStart hook; Hermes uses a webhook route; **Codex has no native wake at
-  all — session-only by default, with the optional non-native `codex exec` connector fallback**
-  (see *Wake on new mail*). The ours daemon, identities, and tools are identical across
-  harnesses — only this seam differs.
+- **The wake signal is uniform.** `ours-mcp watch <identity>` is the common stream; each harness
+  drives it in-session. Claude Code uses its native `Monitor` tool; **Codex uses autonomous watch
+  mode** — the agent holds a blocking `ours-mcp watch` via Codex's shell tool (or, since Codex is
+  turn-based, polls `get_messages` every ~5s) and reacts from that loop (see *Getting woken on new mail*).
+  The ours daemon, identities, and tools are identical across harnesses — only how the agent runs
+  the watch differs.

package/skills/ours/references/configuration.md

@@ -12,9 +12,9 @@ The daemon is a **shared, host-wide singleton** reachable only on `127.0.0.1`
 | GC interval (ms) | `OURS_GC_INTERVAL_MS` | `gcIntervalMs` | `3600000` |
 | Auto-start daemon | `OURS_AUTOSTART` | `autoStart` | `false` |
 
-**The port is shared.** Any process that dials the daemon (the MCP proxy, the
-optional codex-exec gateway) connects to `127.0.0.1:<OURS_PORT>` and the daemon
-binds the same port — both read `OURS_PORT`/`config.json`. Change it **once in
+**The port is shared.** Any process that dials the daemon — the `ours-mcp proxy` MCP
+server and `ours-mcp watch` — connects to `127.0.0.1:<OURS_PORT>` and the daemon
+binds the same port (both read `OURS_PORT`/`config.json`). Change it **once in
 shared config**, never per-side, or a dialer won't find the daemon.
 
 **Changing config (consent-first — never on your own initiative):**

package/reactivity/README.md

@@ -1,72 +0,0 @@
-# ours × Codex — OPTIONAL, non-native reactivity (`codex exec` gateway)
-
-> **This is NOT native Codex reactivity.** Codex is a session/invocation CLI — no daemon,
-> no webhook, no persistent monitor. The honest default for ours-on-Codex is
-> **session-only**: the `ours` skill and the `~/.codex/AGENTS.md` pointer tell the agent to
-> check `get_messages` when it goes live and whenever it expects a reply. This directory is
-> an **opt-in** for people who want an external always-on wake and accept that it is bolted
-> on, outside Codex's lifecycle — not a Codex feature.
-
-## What it is
-
-A small adaptation of `@ours.network/connector`'s reference gateway
-(`connector-reference-handler.mjs`). Same webhook contract and per-identity coalescing +
-backstop, but the DRAIN spawns **`codex exec`** — Codex's real non-interactive mode — with a
-prompt to bind the woken identity and read/act on ours mail via the `ours` MCP tools.
-
-```
-ours-mcp watch <id>   ──▶  connector-watch.sh  ──HMAC POST──▶  codex-exec-gateway.mjs
-(notifications.log)        (OBSERVE, per id)     /webhooks/       (WAKE + DRAIN)
-                                                 ours-wake              │
-                                                                        ▼
-                                          codex exec --sandbox workspace-write
-                                          "<drain prompt>"   →  ours MCP tools  →  get_messages → acts
-```
-
-- **OBSERVE** — reuse the connector's `connector-watch.sh` (one `ours-mcp watch <id>` per
-  identity, non-binding, non-draining; pokes the gateway on each new message).
-- **WAKE + DRAIN** — this file. HMAC-verifies the poke, then runs a **headless Codex** bound
-  to that identity (its sole drainer — ours binding is exclusive per identity).
-
-## Requirements
-
-- A Codex **API key** for automation (e.g. `CODEX_API_KEY`) — `codex exec` is non-interactive.
-- The ours daemon running and the `ours` MCP server registered in `~/.codex/config.toml`
-  (the plugin's `install.sh` does this).
-- A supervisor for **two always-on processes** you run yourself: the connector watcher and
-  this gateway. Neither is started by default.
-
-## Run it
-
-```sh
-export CONNECTOR_IDENTITIES="Agent1 Agent2"                       # identities to drive
-export CONNECTOR_HMAC_SECRET="$(openssl rand -hex 32)"            # SAME secret both ends
-export CONNECTOR_WEBHOOK_URL="http://localhost:8644/webhooks/ours-wake"
-export CODEX_API_KEY="<your key>"                                 # for headless codex exec
-
-bash <connector>/connector-watch.sh &          # OBSERVE (per identity)
-node ./codex-exec-gateway.mjs                  # WAKE + DRAIN via `codex exec`
-```
-
-## Config (env, all overridable)
-
-| var | default | purpose |
-|---|---|---|
-| `CONNECTOR_IDENTITIES` | `Peer` | space-separated identities this gateway drains |
-| `CONNECTOR_HMAC_SECRET` | — | shared HMAC secret (must match the watcher; no default) |
-| `CONNECTOR_WEBHOOK_URL` | `http://localhost:8644/webhooks/ours-wake` | webhook the watcher pokes |
-| `CONNECTOR_EVENT` | `ours_wake` | event name (header + body) |
-| `CONNECTOR_BACKSTOP_SECS` | `420` | per-identity missed-wake backstop interval |
-| `CODEX_BIN` | `codex` | Codex CLI binary |
-| `CODEX_SANDBOX` | `workspace-write` | `codex exec --sandbox` mode |
-
-The gateway **refuses to start** unless `CONNECTOR_HMAC_SECRET` is a non-default value.
-
-## Caveats
-
-- Each wake is a **fresh Codex invocation** — there is no persistent session state between
-  wakes beyond what ours + the workspace persist. Cost/latency scale with wake volume.
-- This runs Codex with a real API key and a writable sandbox. Review the drain prompt and
-  the sandbox mode before pointing it at anything sensitive.
-- If you don't need external wake, don't run this — session-only reactivity is the default
-  and needs nothing here.

package/reactivity/codex-exec-gateway.mjs

@@ -1,113 +0,0 @@
-#!/usr/bin/env node
-// OPTIONAL, NON-NATIVE reactivity gateway for the OpenAI Codex CLI.
-//
-// ┌─────────────────────────────────────────────────────────────────────────────────┐
-// │ THIS IS NOT NATIVE CODEX REACTIVITY. Codex is a session/invocation CLI: no        │
-// │ daemon, no webhook, no persistent monitor. This gateway lives OUTSIDE Codex's own │
-// │ lifecycle — you supervise it as an always-on process. On each ours wake it drives │
-// │ Codex HEADLESSLY via `codex exec "<drain prompt>"`, which is Codex's real         │
-// │ non-interactive mode and needs an API key (e.g. CODEX_API_KEY) for automation.    │
-// │ The DEFAULT ours-on-Codex reactivity is session-only (the agent checks            │
-// │ get_messages when live / when it expects a reply). Use this only if you want an   │
-// │ external always-on wake mechanism and accept that it is bolted on, not native.    │
-// └─────────────────────────────────────────────────────────────────────────────────┘
-//
-// It is a small adaptation of @ours.network/connector's connector-reference-handler.mjs:
-// same HMAC-verified webhook contract, same per-identity coalescing + backstop, but the
-// per-identity DRAIN spawns `codex exec` with a prompt to read + act on ours mail (via the
-// ours MCP tools that install.sh registered in ~/.codex/config.toml), instead of the
-// inline JSON-RPC get_messages drain.
-//
-// Pair it with the connector's watcher for OBSERVE:
-//   bash <connector>/connector-watch.sh    # ours-mcp watch <id> → HMAC POST per new message
-// This file is the WAKE+DRAIN side.
-//
-// SOLE-DRAINER per identity: ours binding is exclusive per identity, so the codex exec run
-// bound to <id> is the only drainer of <id>. N identities = N sole-drained inboxes on ONE
-// shared ours daemon.
-//
-// Contract (config-overridable, must match the connector):
-//   POST <CONNECTOR_WEBHOOK_URL>  body: {"event_type":"<CONNECTOR_EVENT>","event":"<CONNECTOR_EVENT>","identity":"<id>"}
-//   header: X-GitHub-Event: <CONNECTOR_EVENT>
-//   header: X-Hub-Signature-256: sha256=<hex HMAC-SHA256(body, CONNECTOR_HMAC_SECRET)>
-//   reply: <CONNECTOR_WEBHOOK_OK_CODE> (200) accept; 401 bad signature; 400 unknown identity.
-// Refuses to start unless CONNECTOR_HMAC_SECRET is set to a non-default value.
-import http from 'node:http';
-import crypto from 'node:crypto';
-import { spawn } from 'node:child_process';
-
-process.on('unhandledRejection', e => console.error('[codex-gw] unhandledRejection:', e?.message || e));
-process.on('uncaughtException', e => console.error('[codex-gw] uncaughtException:', e?.message || e));
-
-const WURL = new URL(process.env.CONNECTOR_WEBHOOK_URL || 'http://localhost:8644/webhooks/ours-wake');
-const URL_PATH = WURL.pathname, PORT = Number(WURL.port || 8644);
-const SECRET = process.env.CONNECTOR_HMAC_SECRET || '';
-if (!SECRET || SECRET === 'CHANGE_ME_local_webhook_hmac') {
-  console.error('[codex-gw] refusing to start: set CONNECTOR_HMAC_SECRET to a non-default value ' +
-    '(missing or the placeholder default is insecure — anyone could forge a wake).');
-  process.exit(1);
-}
-const OK = Number(process.env.CONNECTOR_WEBHOOK_OK_CODE || 200);
-// Codex non-interactive binary + args. `codex exec` is Codex's headless mode; we run with a
-// workspace-write sandbox so the agent can act, and pass the drain prompt as the final arg.
-const CODEX_BIN = process.env.CODEX_BIN || 'codex';
-const CODEX_SANDBOX = process.env.CODEX_SANDBOX || 'workspace-write';
-const IDENTITIES = new Set((process.env.CONNECTOR_IDENTITIES || process.env.CONNECTOR_IDENTITY || 'Peer').split(/\s+/).filter(Boolean));
-const BACKSTOP_MS = Number(process.env.CONNECTOR_BACKSTOP_SECS || 420) * 1000;
-
-const state = new Map();  // id -> {draining, again}
-for (const id of IDENTITIES) state.set(id, { draining: false, again: false });
-
-// The prompt Codex runs headlessly. It leans on the ours MCP tools (registered in
-// ~/.codex/config.toml) + the ours skill: bind <id>, then read and act on new mail.
-function drainPrompt(id) {
-  return `New ours.network mail arrived for identity "${id}". Use the ours skill and the ` +
-    `ours MCP tools: bind that identity with choose_identity({ name: "${id}" }) if it is not ` +
-    `already bound, then call get_messages to read the new message(s) and act on them. Reply ` +
-    `over ours (send_message) if a reply is expected. Do not adopt the identity's persona.`;
-}
-
-function codexExec(id) {  // one headless Codex run bound to <id> (its sole drainer)
-  return new Promise((resolve) => {
-    const args = ['exec', '--sandbox', CODEX_SANDBOX, drainPrompt(id)];
-    const proc = spawn(CODEX_BIN, args, { env: { ...process.env }, stdio: ['ignore', 'pipe', 'pipe'] });
-    let out = '';
-    proc.stdout.on('data', d => { out += d; });
-    proc.stderr.on('data', d => console.error(`[codex-gw:${id}] ${String(d).trimEnd()}`));
-    proc.on('error', e => { console.error(`[codex-gw:${id}] codex spawn error:`, e.message); resolve(''); });
-    proc.on('close', code => {
-      if (out.trim()) console.log(`[codex-gw:${id}] codex exec (rc=${code}):\n${out.trim()}`);
-      resolve(out);
-    });
-  });
-}
-
-async function drain(id) {  // coalesced per-identity
-  const s = state.get(id); if (!s) return;
-  if (s.draining) { s.again = true; return; }
-  s.draining = true;
-  do {
-    s.again = false;
-    try { await codexExec(id); } catch (e) { console.error(`[codex-gw:${id}] drain error:`, e?.message || e); }
-  } while (s.again);
-  s.draining = false;
-}
-
-http.createServer((req, res) => {
-  if (req.method !== 'POST' || req.url !== URL_PATH) { res.writeHead(404).end(); return; }
-  let body = ''; req.on('data', c => body += c); req.on('end', () => {
-    const sig = (req.headers['x-hub-signature-256'] || '').replace(/^sha256=/, '');
-    const good = crypto.createHmac('sha256', SECRET).update(body).digest('hex');
-    const okSig = sig.length === good.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(good));
-    if (!okSig) { res.writeHead(401).end('bad sig'); return; }
-    let id; try { id = JSON.parse(body).identity; } catch {}
-    if (!id || !IDENTITIES.has(id)) { res.writeHead(400).end('unknown identity'); return; }
-    res.writeHead(OK).end();                 // ack fast; drain async + coalesced
-    drain(id).catch(e => console.error(`[codex-gw:${id}] drain error`, e));
-  });
-}).listen(PORT, () => console.log(
-  `[codex-gw] NON-NATIVE codex-exec gateway on :${PORT}${URL_PATH} — sole-drainer for [${[...IDENTITIES].join(', ')}]`));
-
-// per-identity missed-wake backstop (coalesced with wakes; each run is a fresh codex exec
-// that no-ops cheaply if there is no new mail).
-setInterval(() => { for (const id of IDENTITIES) drain(id).catch(() => {}); }, BACKSTOP_MS);