@pcircle/memesh 4.8.3 → 4.9.0

package/docs/platforms/agent-messaging.md

@@ -77,30 +77,58 @@ Linux. Windows remains supported for core MeMesh memory, durable message
 storage, and MCP tools, but host-native wakeup fails closed before creating
 credentials, configuration, IPC listeners, or managed child processes.
 
-Create one reusable owner-private config for each local path and principal.
-The stable principal is the logical recipient. Managed processes generate a
-fresh exact session identity; the ordinary Codex path instead uses the Codex
-thread identity supplied at SessionStart. No thread ID is copied by hand.
-Ordinary sessions outside the explicit `codex-session` workspace opt-in remain
-`presence-only/inbound-unavailable`.
+The default local endpoint is versioned with the wire protocol
+(`agent-router-v2.sock`). This lets a current router start beside an incompatible
+legacy daemon after an upgrade instead of killing it or taking over its live
+socket. Existing generated configs that name the former default are normalized
+in memory; an explicit custom socket remains exact and reports
+`router_version_mismatch` when it exposes the known legacy response shape.
+
+Create one reusable owner-private config for each managed local host and
+principal. The stable principal is the logical recipient. Managed processes
+generate a fresh exact session identity. Ordinary Codex plugin sessions instead
+register automatically from the Codex thread identity supplied at SessionStart,
+using a distinct thread-scoped principal; no thread ID is copied by hand.
 
 ```bash
-memesh agent setup codex-session --project my-project --principal codex-reviewer --workspace "$PWD"
 memesh agent setup codex --project my-project --principal codex-reviewer --workspace "$PWD"
 memesh agent setup claude --project my-project --principal claude-reviewer
 ```
 
 Optional declarations can be persisted with `--model <id>` and
 `--work-summary <text>` (each is capped at 200 characters); no defaults are guessed.
+For ordinary Codex only, `memesh agent setup codex-session ...` is an optional
+workspace-specific stable-principal override, not an activation prerequisite.
+When pairing Claude Channel with an automatically registered Codex session,
+use the complete `project` field returned by `memesh briefing --json` in the
+Claude setup command. A repository basename is not equivalent to the automatic
+collision-resistant project identity, and different project strings cannot
+discover or natively route to each other.
 
 ### Ordinary active Codex CLI session
 
-`codex-session` is the opt-in path for an ordinary local Codex session and
-requires the MeMesh Codex plugin to be installed and enabled so Codex loads
-the packaged SessionStart hook. Run
-the setup command from the exact workspace that Codex will use; it stores the
-configured real workspace and stable principal in the owner-private
-`codex-session.json` config. Restart Codex in that workspace after setup.
+An ordinary local Codex session requires the MeMesh Codex plugin to be installed
+and enabled so Codex loads the packaged SessionStart hook. Each startup or
+resumed thread then registers automatically under the current project with a
+thread-scoped principal. Use `message discover` to obtain the exact live session
+ID. No manual `agent setup` is required.
+
+The automatic project is a readable repo label plus a 32-hex identity suffix.
+For a network Git remote, the suffix covers a password-free locator; otherwise
+it covers the native real path. Standard GitHub HTTPS and SSH spellings
+converge. Generic SSH locators keep the login and whether the repository path is
+absolute or relative to that login's home, preventing distinct accounts or
+paths from sharing one scope. This keeps the same repo together across
+subdirectories, symlinks, remote-backed clones, and linked worktrees without
+letting two unrelated repos named `shared` discover or receive each other's
+messages. `memesh briefing` in that workspace reports the exact project value.
+
+If one workspace needs a stable named principal across different threads, run
+`memesh agent setup codex-session --project my-project --principal codex-reviewer
+--workspace "$PWD"` there and restart Codex. The owner-private config overrides
+project and principal only when its exact real workspace matches. Another
+workspace still uses automatic identity; a malformed or insecure override fails
+closed rather than silently downgrading.
 
 This guide's supported documented path is ordinary Codex CLI `SessionStart`.
 Codex Desktop or an unattached task is not user-visible native-delivery
@@ -108,23 +136,28 @@ evidence unless that exact live session registers with the router and the
 result is directly verified. This is a scope boundary for evidence, not a
 claim that Codex Desktop is universally unsupported.
 
-On `SessionStart` for `startup` or `resume`, the asynchronous companion checks
-the Codex thread identity, hook session identity, and configured workspace
-realpath before it connects to the router. A missing identity, a different
-workspace, compact lifecycle input, or a failed/disconnected connection does
-not register a host and does not wake anything.
+On `SessionStart` for `startup` or `resume`, a short hook validates the Codex
+thread identity and cwd, then launches an owner-private detached companion.
+Detachment is required because Codex reaps an async hook child when the CLI
+process exits, while `codex queue` accepts the thread only after its active
+writer is gone. `SessionEnd` leaves a bounded 45-second idle queue window;
+resume replaces the prior exact generation through its private control socket,
+and expiry removes the registration. A missing or malformed identity, invalid
+cwd, insecure explicit override, or failed connection does not register a host.
 
 For a registered session, MeMesh invokes `codex queue` with one untrusted full
 envelope capped at 16,384 bytes (16 KiB), including routing metadata and payload.
 The separate durable JSON-encoded payload limit is 65,536 bytes (64 KiB). The exact-session sender returns
 `native_delivery.status: "native_accepted"` only after the queue accepts it;
 Codex does not need a second `message fetch` to inspect that native message.
+For ordinary CLI, a message accepted in the idle window becomes model-visible
+when that same thread resumes; it does not wake a stopped terminal or Desktop UI.
 The persisted `host_accept` is neither agent readback nor an `ack` or workflow
 disposition. Codex exposes message text only through its `--message` process
 argument, so same-user process inspection may observe it while the short-lived
 queue command runs; do not put secrets in native messages.
 
-If the configured Codex session is stopped, missing, disconnected, or no
+If the target Codex session is stopped, missing, disconnected, or no
 longer matches its configured workspace, MeMesh does not start or replace it.
 An exact-session send reports `recipient_unavailable`; durable scoped recovery
 and receipt history remain available to fetch, cursor recovery, `poll`, or
@@ -203,6 +236,194 @@ for active Codex-session delivery.
 - `intake`, `ack`, `disposition`, and `activation` are explicit, separate, idempotent receipt facts. Inbox/MCP ACK is valid without a host-native acceptance; host-native ACK remains bound to its `host_accept`. `receipts` returns one ordered projection and identifies each underlying fact source. For example, `manual_resume_required` does not imply ACK, acceptance, rejection, cancellation, or completion.
 - The transport, rather than model-provided payload data, records sender-host provenance.
 
+## Repeatable owner-run live checks
+
+Everything above is checked by the test suite against stubs and fakes. That
+proves the plumbing and nothing about a live model: a queue admission or a
+`host_accept` is a statement about a frame, not about cognition. Two checks
+close that gap by requiring evidence that could only have come out of a running
+model.
+
+```bash
+MEMESH_CODEX_QA_HOME="$(mktemp -d /private/tmp/memesh-codex-qa.XXXXXX)"
+CODEX_HOME="$MEMESH_CODEX_QA_HOME" codex login
+TMPDIR=/private/tmp npm run qa:live-journey -- --host codex --codex-home "$MEMESH_CODEX_QA_HOME" --out .qa/codex-report.json
+TMPDIR=/private/tmp npm run qa:live-journey -- --host claude --out .qa/claude-report.json
+```
+
+`.qa/` is where `npm run release:finish` looks for release receipts. Codex and
+Claude are separate delivery claims, so **both** must PASS within 24 hours
+against the exact clean commit being released, with current `dist/`, ordered
+lifecycle steps, lease renewal, model-visible evidence, and the stopped-session
+failure path. The installed Codex receipt also requires actual plugin
+SessionStart loading and a resume that supersedes the prior generation.
+One host can never satisfy the other host's gate. The commands above produce
+`.qa/codex-report.json` and `.qa/claude-report.json`, respectively. The directory
+is gitignored; reports are owner-machine evidence, never shipped.
+
+`TMPDIR` is not decoration on macOS. The router's Unix socket lives beside the
+database inside the temporary directory, and `AF_UNIX` caps a socket path at
+104 bytes; the platform default `os.tmpdir()` spends about half of that before
+the check adds anything. The script measures its own socket path and refuses
+with this hint rather than starting a router that cannot bind.
+
+`scripts/qa/live-journey.mjs` is owner-run and refuses to start when `CI` is
+set, because neither check can run unattended: one needs the owner's Codex
+login, the other needs a person at an interactive Claude session. Its argument
+parsing, its refusals, and every **pure** assertion it makes are unit-tested in
+`tests/qa/live-journey.test.ts`, which does run in CI against recorded
+fixtures; the orchestration around them is exercised only by a live run.
+
+Everything MeMesh writes goes into a fresh `mktemp` MEMESH_DIR that is deleted
+on exit (`--keep` retains it), against this repository's own `dist/`. The check
+refuses to start if that directory would resolve inside `$HOME/.memesh` — the
+comparison is made on **real** paths, before anything is created, so a
+symlinked `TMPDIR` cannot get past it — or if `dist/` has not been built. It
+reads no authentication file. Where that isolation stops is listed under
+limitations below, and the report records whether the working tree was dirty
+and whether `dist/` predates the newest file under `src/`.
+
+Shutdown order is part of the design rather than an afterthought. A connected
+host that sees the router socket disappear starts a **detached** packaged
+router inheriting its own environment — including this check's `MEMESH_DIR` —
+and the router recreates its data directory on start. The check therefore stops
+the companion, waits for live sessions to disconnect, stops the router, and
+only then removes the directory; if a session is still connected when the wait
+expires it keeps the directory rather than racing that spawn. The same sequence
+runs on failures and on `SIGINT`/`SIGTERM`.
+
+**`--host codex`** installs the candidate plugin into the caller-prepared
+authenticated `--codex-home`, verifies its cache, and creates a real Codex CLI
+thread. The installed plugin's SessionStart hook registers the thread; the
+runner never starts its companion. The check verifies lease renewal,
+exact-session delivery, resume-generation supersession, renewed lease, and a
+reply quoting the envelope's sentinel, `message_id`, and `delivery_id`.
+
+The proof rejects other command/tool activity except the narrowly allowed
+installed-skill read and failed work-package prepare probe; neither may contain
+proof identifiers. After SessionEnd retirement, the next send must return
+`recipient_unavailable` while the durable payload remains fetchable.
+Its v3 report requires registration from `codex_plugin_session_start` with
+`plugin_loader_verified: true`, including a renewed lease after resume supersedes
+the startup generation. `release:finish` requires separate current-candidate
+v3 receipts for both Codex and Claude; an old harness-injected v2 report does not
+prove automatic installed-plugin registration and is rejected.
+
+**`--host claude`** starts the router, runs `memesh agent setup claude`, writes
+a temporary MCP config, and prints the exact interactive launch command — which
+includes `--setting-sources ""` to request no user, project, or local settings
+source. That option did not suppress all `[User]` hooks in a live Claude Code
+2.1.263 check, so it is not treated as plugin isolation. The operator runs
+the command, checks `/mcp` and `/hooks` for any installed MeMesh plugin hook or
+extra MeMesh MCP server, and types the exact isolation confirmation token in the
+runner terminal. Other non-MeMesh hooks are outside this check. The token records
+operator attestation, not programmatic inspection. The runner then prints one
+trusted owner prompt: the operator submits it in Claude and confirms only after
+Claude replies `READY_FOR_UNTRUSTED_INTAKE`. That second attestation must also
+precede nonce generation. Only then does the runner wait for
+`lease_expires_at_ms` to advance, send one inert exact-session payload containing
+only its purpose and nonce, and wait for an
+`intake` receipt on that message whose actor is that session — the model must
+call `intake` exactly once under the prior trusted instruction, using the
+documented `intake-<message_id>` idempotency key and only the six fields the
+strict intake schema accepts (`action`, `project`, `recipient`, `message_id`,
+`intake_state`, `idempotency_key`). This is what makes the proof
+model-visible rather than transport-visible without treating the untrusted
+payload as instructions. The operator is then asked to exit the session, and
+the same fail-closed assertion runs. A reminder entered only after delivery is
+diagnostic and cannot satisfy this release receipt.
+
+Print mode (`claude -p`) is **not supported** and is deliberately not
+exercised. A print-mode session does not surface `memesh-channel` notifications
+to the model even when the channel host reports the frame accepted, so it can
+never produce the receipt this check requires.
+
+Each run writes a JSON report: the repository revision, every `message_id` and
+`delivery_id`, the `native_delivery` receipts, the model-visible evidence, and
+a `limitations` list. The exit code is 0 only when every required step passed.
+The limitations these checks always declare:
+
+- The Codex journey installs the candidate plugin into a caller-created
+  disposable authenticated `CODEX_HOME`, verifies the installed cache bytes,
+  and exercises that plugin's SessionStart and SessionEnd hooks through a real
+  Codex thread. It does not mutate the owner's normal Codex configuration. The
+  bounded `--codex-session-auto-registration` mode remains a narrower
+  account-free packaged router → native queue check and is not a substitute for
+  this installed-plugin journey.
+- The interactive Claude session is **outside** this check's isolation.
+  `--setting-sources ""` is accepted by the CLI (an invalid source name is
+  rejected, an empty list is not), but it is not verified to exclude
+  plugin-provided hooks or MCP servers. A MeMesh plugin hook running in that
+  session inherits no `MEMESH_DIR` and would write the owner's real
+  `~/.memesh`. Before nonce generation or send, the runner requires the exact
+  confirmation token after the operator checks `/mcp` and `/hooks`. This is a
+  recorded human attestation, not a machine inspection; inability to identify
+  whether an entry comes from MeMesh means the operator must stop the run.
+- `--host codex` creates one throwaway thread in the owner's Codex rollout
+  store and queues one message into it. That is session state, not
+  configuration; nothing outside the temporary directory is otherwise written.
+- Before delivery, the Claude operator submits one exact trusted intake prompt
+  and attests that its READY reply was observed. The runner cannot inspect that
+  UI exchange. After delivery the operator is told to type nothing, but the
+  runner cannot observe whether that instruction was followed. The intake
+  receipt proves the model called `intake` in that session after native
+  notification; it does not prove the operator followed either instruction.
+- The Claude intake receipt is matched on its `actor`, which `intake` sets from
+  the caller's `recipient`. The model must intake under its own session id; an
+  intake recorded against the principal id would not match, and the check would
+  report no model-visible proof.
+- `recipient_unavailable` is a shared failure surface — the same string is
+  returned when the *sender* cannot reach the router. The fail-closed step
+  therefore also records that `message discover` still answered and that
+  `message fetch` still returned the payload. That pairing, not the string, is
+  what attributes the failure to the stopped recipient.
+
+## Scope identifiers
+
+`project` and `recipient` together key one inbox, and `actor` is derived from
+`recipient`, so how those three are spelled is part of the contract rather than
+a formatting detail. Two spellings of one name are two inboxes: the recipient
+that fetches under one never sees what was sent under the other, and a
+`briefing` unread count is computed per spelling.
+
+Every message action canonicalises them to Unicode NFC and trims surrounding
+whitespace, on reads as well as writes, so a decomposed spelling reaches the
+rows a composed one wrote.
+
+A value spelled as an **absolute filesystem path is refused** — a POSIX path
+(`/root`), a Windows drive path (`C:\work`), or a UNC path (`\\host\share`).
+Project identity is derived from the working directory and can never take that
+shape, so such a value is not an identity MeMesh produced; the error names the
+field and a valid value. Callers that previously passed a home directory or a
+checkout path where the agent's or project's NAME belonged must pass the name.
+Nothing else is rewritten: identifiers are compared exactly, case included, and
+an identifier that merely contains a separator (`team/reviewer`) is accepted.
+MeMesh does not treat any prefix as a namespace, so `claude-code:reviewer` and
+`reviewer` are two different recipients.
+
+The same rule covers every surface that reads or writes that key, not only the
+`message` tool: `briefing` counts unfetched deliveries for one exact
+(`project`, `recipient`), and `memesh agent setup --project/--principal` writes
+the identity a host will register under. A path-shaped value is refused there
+too, at the moment the config is written, rather than surfacing later as an
+error about some other agent's send.
+
+`sender` is not covered by any of this. It is provenance rather than routing —
+it keys no inbox, and it keys the send idempotency record — so it is stored
+exactly as given, and the transport-bound provenance remains the field to trust.
+
+Rows written before this rule are preserved byte-for-byte. MeMesh reports
+path-shaped historical scope through its read-only memory invariant rather than
+guessing that `/root`, `/tmp/root`, and `root` name one recipient. Such rows may
+remain unreachable through the stricter public API until the owner supplies an
+explicit mapping. For a confirmed project mapping, rename both its entity tags
+and message scopes with the deliberate owner-run operation:
+
+```bash
+memesh kg rename-project --from <old> --to <new>          # dry run
+memesh kg rename-project --from <old> --to <new> --apply  # backs up first
+```
+
 ## Identity and lifecycle
 
 A **principal** is the stable logical recipient. A **session** is one live host connection for that principal. A **generation** changes when that session is replaced. An exact-session target never reroutes. A principal target can deliver only to an eligible active session after its activation checkpoint; it does not replay historical inbox contents into a first session.
@@ -276,7 +497,7 @@ reply, or a stopped-session wake-up.
 
 | Participant | Current path | Status today | Notes |
 |---|---|---|---|
-| Ordinary Codex CLI | `codex-session` owner-private opt-in | bounded full-message native delivery while active | Exact workspace, principal, and SessionStart identity must match; oversized envelopes return `native_message_too_large`, while stopped or disconnected sessions return `recipient_unavailable` |
+| Ordinary Codex CLI | automatic plugin SessionStart registration; optional `codex-session` identity override | bounded full-message native delivery while active | Exact thread identity is discoverable; oversized envelopes return `native_message_too_large`, while stopped or disconnected sessions return `recipient_unavailable` |
 | MeMesh-managed Codex app-server | `memesh-host-codex` | separate managed path | It creates its own Codex thread; it does not attach to an ordinary session |
 | Claude channel | `memesh-host-claude` | separate channel path | Requires the documented Channel opt-in; no stopped-session resume |
 | Other local MCP clients | MCP, HTTP, or CLI message operations | durable messaging only | Use `poll`/`watch` and scoped fetch where their own host loop supports it; this guide makes no native-wakeup claim |

package/hooks/hooks.json

@@ -39,8 +39,19 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/dist/host-runtime/codex-session.js",
-            "async": true,
-            "timeout": 31536000
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/dist/host-runtime/codex-session.js",
+            "timeout": 10
           }
         ]
       }
@@ -55,6 +66,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "ExitPlanMode|AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/decision-nudge.js",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "Stop": [

package/llms-install.md

@@ -68,7 +68,7 @@ MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY=1 memesh doctor
 ```
 
 This probe does not exercise a real host session and never wakes a stopped
-session. The ordinary Codex path below is the documented native local wakeup
+session. The ordinary Codex path below is the documented bounded native queue
 path; `poll`/`watch` and cursor recovery remain available for compatibility and
 diagnosis.
 
@@ -104,8 +104,13 @@ umask 077
 memesh-router
 ```
 
-If you start it yourself, it creates `agent-router.sock` and `agent-router.token` beside the active
-MeMesh database (normally `~/.memesh/`) with owner-private permissions. Check
+If you start it yourself, it creates the current protocol endpoint
+`agent-router-v2.sock` and the shared `agent-router.token` beside the active
+MeMesh database (normally `~/.memesh/`) with owner-private permissions. After
+an upgrade, an older router may remain on its legacy socket until its old
+sessions exit or the machine restarts. Current clients do not attach to it,
+and MeMesh does not kill or unlink a live process without durable ownership
+proof. Check
 the installed adapter imports and the live socket as distinct facts:
 
 ```bash
@@ -117,10 +122,20 @@ The router probe does not register a host, send content, or wake a stopped
 session. Generate reusable `0600` configs; session identities are not copied
 from an active ordinary session.
 
-For an ordinary active local Codex session, first install and enable the MeMesh
-Codex plugin (Option A), which supplies the packaged SessionStart hook. Then
-run this from the exact workspace you want to configure and restart Codex in
-that same workspace:
+For an ordinary active local Codex session, install and enable the MeMesh
+Codex plugin (Option A), which supplies the packaged SessionStart hook. On the
+next startup or resume, that thread registers automatically under the current
+project with a thread-scoped principal. First read the exact automatic project
+value, then copy its `project` field into the discover command:
+
+```bash
+memesh briefing --json
+memesh message discover --project '<project from briefing>'
+```
+
+No manual host setup is required. If one exact workspace needs a stable named
+principal across different Codex threads, create this optional override and
+restart Codex in that workspace:
 
 ```bash
 memesh agent setup codex-session --project my-project --principal codex-recipient --workspace "$PWD"
@@ -128,22 +143,34 @@ memesh agent setup codex-session --project my-project --principal codex-recipien
 
 This stores the configured workspace realpath and principal in
 `~/.memesh/hosts/codex-session.json`. On `SessionStart` (`startup` or
-`resume`), an asynchronous companion registers only when its Codex thread ID,
-hook session ID, and workspace realpath match that config. The authenticated
-router sends the active exact session one bounded full message through native
-`codex queue`; no second `message fetch` is required for that live delivery.
+`resume`), a short hook validates the Codex thread ID and cwd, then launches an
+owner-private detached companion. SessionEnd leaves a bounded 45-second idle
+queue window; resume replaces the prior generation, and expiry removes it. A
+matching valid override supplies its project and principal; another workspace
+keeps automatic thread-scoped registration. A malformed or insecure override
+fails closed. The authenticated router sends the exact registered thread one
+bounded full message through native `codex queue`; no second `message fetch`
+is required. A message accepted during the idle window becomes model-visible
+when the same thread resumes; a stopped UI is not awakened.
 
 `host_accept` records only that the local Codex queue accepted that message. It
 does not prove an agent read the payload, acknowledged it, or accepted the
 work. Codex exposes message text through its `--message` process argument, so
 same-user process inspection may observe it while the queue command runs; do
-not send secrets through the native path. If the session is stopped, missing, disconnected, or in another
-workspace, MeMesh neither starts nor replaces it; the durable inbox remains
+not send secrets through the native path. If the session is stopped, missing,
+or disconnected, MeMesh neither starts nor replaces it; the durable inbox remains
 available to scoped fetch, cursor recovery, `poll`, and `memesh message watch`
-for audit and diagnosis.
+for audit and diagnosis. Failed exact-session native delivery is not replayed
+automatically after a later registration; the sender must retry deliberately.
 
 The following are separate managed-host paths:
 
+When pairing Claude Channel with an automatically registered Codex session,
+copy the complete `project` value from `memesh briefing --json` into the Claude
+setup command. Do not substitute the repository basename: automatic project
+identities include a collision-resistant suffix, and different project strings
+cannot discover or natively route to each other.
+
 ```bash
 memesh agent setup codex --project my-project --principal codex-recipient --workspace "$PWD"
 memesh-host-codex --config "$HOME/.memesh/hosts/codex.json"
@@ -192,13 +219,17 @@ memesh doctor
 
 ## 3. Codex CLI
 
-Prerequisite: section 2 — `memesh-mcp` must resolve on PATH.
+Install from the Codex plugin marketplace for zero-config MCP tools and the
+SessionStart/SessionEnd companion lifecycle:
 
 ```
-codex mcp add memesh -- memesh-mcp
+codex plugin marketplace add PCIRCLE-AI/memesh
+codex plugin add memesh@pcircle-memesh
 ```
 
-Writes `[mcp_servers.memesh]` into `~/.codex/config.toml`.
+The plugin manifest starts its bundled `dist/mcp/server.js` directly from the
+plugin cache. It does not need a global `memesh-mcp` command or a manual
+`codex mcp add` entry.
 
 **Verify**:
 
@@ -208,33 +239,34 @@ codex mcp list
 
 Expected: `memesh` is listed as enabled.
 
-### Optional: Codex plugin marketplace
+### Manual npm-global alternative
 
-Current Codex CLI versions can install the repository's plugin marketplace
-directly. For a fresh install:
+If you installed section 2 instead of the Codex plugin, register the global
+stdio command manually:
 
 ```
-codex plugin marketplace add PCIRCLE-AI/memesh
-codex plugin add memesh@pcircle-memesh
+codex mcp add memesh -- memesh-mcp
 ```
 
-If the configured marketplace snapshot is stale, refresh it and reinstall the
-plugin:
+This writes `[mcp_servers.memesh]` into `~/.codex/config.toml`.
+
+### Refresh a stale plugin cache
+
+If the configured marketplace snapshot is stale, refresh it and re-stage the
+plugin. `codex plugin add` replaces the installed cache atomically, so do not
+remove the working plugin first:
 
 ```
 codex plugin marketplace upgrade pcircle-memesh
-codex plugin remove memesh
 codex plugin add memesh@pcircle-memesh
 ```
 
-These commands are separate from the MCP registration above; keep the MCP
-path when a host needs `memesh-mcp` directly.
-
 | Failure | Remedy |
 |---|---|
 | `command not found: codex` | Codex CLI itself is not installed — out of scope here; install it first, then re-run the add. |
-| `memesh` absent from the list | The add did not persist. Re-run `codex mcp add memesh -- memesh-mcp` and re-check. |
-| Listed, but tool calls fail | Run `command -v memesh-mcp`. Empty output means section 2 is incomplete or PATH is wrong — fix per section 2's table. |
+| Plugin-installed `memesh` is absent | Refresh and reinstall the plugin using the commands above, then restart Codex. |
+| Manually registered `memesh` is absent | Re-run `codex mcp add memesh -- memesh-mcp` and re-check. |
+| Manual registration is listed, but tool calls fail | Run `command -v memesh-mcp`. Empty output means section 2 is incomplete or PATH is wrong — fix per section 2's table. |
 
 ## 4. Cursor
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pcircle/memesh",
-  "version": "4.8.3",
-  "description": "MeMesh \u2014 agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
+  "version": "4.9.0",
+  "description": "MeMesh — agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -17,7 +17,6 @@
   "files": [
     "dist/",
     "dashboard/dist/",
-    ".mcp.json",
     "hooks/hooks.json",
     "scripts/hooks/",
     "scripts/upgrade-plugin.sh",
@@ -31,13 +30,11 @@
     "AGENTS.md"
   ],
   "scripts": {
-    "build": "node scripts/check-schema-drift.mjs && tsc && node scripts/generate-hook-core.mjs && node scripts/copy-cli-assets.mjs && node scripts/set-executable-bits.mjs && node scripts/generate-skills-manifest.mjs && npm run build:dashboard && node scripts/smoke-test.mjs",
+    "build": "node scripts/check-schema-drift.mjs && tsc && node scripts/build-mcp-bundle.mjs && node scripts/generate-hook-core.mjs && node scripts/copy-cli-assets.mjs && node scripts/set-executable-bits.mjs && node scripts/generate-skills-manifest.mjs && npm run build:dashboard && node scripts/smoke-test.mjs",
     "build:dashboard": "node scripts/build-dashboard.mjs",
     "test": "vitest",
     "test:e2e-dashboard": "node scripts/dashboard-e2e-smoke.mjs",
     "test:issue-224": "vitest run tests/dashboard/issue-224-data-refresh.test.tsx --maxWorkers=1",
-    "test:issue-225": "vitest run tests/dashboard/issue-225-language-persistence.test.tsx --maxWorkers=1",
-    "test:issue-226": "vitest run tests/dashboard/SettingsTab-primary-llm.test.tsx tests/transports/http.test.ts --maxWorkers=1",
     "test:issue-227": "vitest run tests/dashboard/ProjectRoadmap.test.tsx --maxWorkers=1",
     "test:issue-228": "vitest run tests/dashboard/FeedbackWidget.test.tsx --maxWorkers=1",
     "test:issue-229": "vitest run tests/dashboard/OnboardingBanner.test.tsx tests/dashboard-i18n.test.ts --maxWorkers=1",
@@ -51,14 +48,20 @@
     "check:surface-parity": "node scripts/check-readme-tool-parity.mjs && node scripts/check-codemap-parity.mjs",
     "audit:prod": "node scripts/check-consumer-audit.mjs",
     "audit:memory": "node scripts/audit/memory-invariants.mjs",
-    "verify:release": "npm run lint && npm run typecheck && node scripts/check-version-coherence.mjs && node scripts/check-generated-mirror.mjs && node scripts/check-agent-message-sync.mjs && npm run check:surface-parity && node scripts/check-doc-claims.mjs && node scripts/audit/verification-audit.mjs && npm run audit:prod",
+    "check:entry-points-start": "node scripts/check-entry-points-start.mjs",
+    "verify:release": "npm run lint && npm run typecheck && node scripts/check-version-coherence.mjs && node scripts/check-generated-mirror.mjs && node scripts/check-agent-message-sync.mjs && npm run check:surface-parity && node scripts/check-doc-claims.mjs && node scripts/audit/verification-audit.mjs && npm run audit:prod && npm run check:entry-points-start",
     "release:finish": "node scripts/finish-release.mjs",
-    "prepublishOnly": "npm run build && npm run verify:release && npm run test:isolated && npm run test:packaged && npm run test:packaged:upgrade",
+    "verify:artifact": "npm run verify:release && npm run test:isolated && npm run test:packaged && npm run test:packaged:upgrade",
+    "prepublishOnly": "npm run build && npm run verify:artifact",
     "typecheck": "tsc -p tsconfig.check.json && tsc -p tsconfig.check-dashboard.json",
     "lint": "eslint src/ scripts/ tests/ dashboard/src/ --max-warnings 0",
     "lint:fix": "eslint src/ scripts/ tests/ dashboard/src/ --fix",
     "start": "node dist/mcp/server.js",
     "bench:longmemeval": "node benchmarks/longmemeval/run.mjs --mode A --dataset /tmp/longmemeval_s.json",
+    "qa:live-journey": "node scripts/qa/live-journey.mjs",
+    "qa:pre-release": "node scripts/qa/pre-release.mjs",
+    "qa:ui-review": "node scripts/qa/ui-review.mjs",
+    "qa:post-release": "node scripts/qa/post-release.mjs",
     "test:isolated": "node scripts/run-tests-isolated.mjs",
     "test:coverage": "node scripts/run-tests-isolated.mjs --coverage"
   },
@@ -89,7 +92,6 @@
     "commander": "^14.0.3",
     "express": "^5.2.1",
     "express-rate-limit": "8.5.1",
-    "sqlite-vec": "^0.1.9",
     "ws": "^8.21.3",
     "zod": "4.4.3"
   },
@@ -117,6 +119,7 @@
     "@types/node": "25.6.2",
     "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "4.1.5",
+    "esbuild": "0.28.1",
     "eslint": "^10.3.0",
     "happy-dom": "^20.9.0",
     "playwright": "^1.59.1",

package/scripts/hooks/_generated/agent-message-inbox.js

@@ -28,11 +28,30 @@ export function unreadDeliveryCount(db, project, recipient) {
         return 0;
     }
 }
-export function unreadInboxLines(count, project, recipient) {
-    if (count <= 0 || !recipient)
+export function recipientEverSeen(db, project, recipient) {
+    try {
+        const row = db.prepare(`SELECT (
+         EXISTS(SELECT 1 FROM agent_principals WHERE project = ? AND principal_id = ?)
+         OR EXISTS(SELECT 1 FROM agent_message_deliveries WHERE project = ? AND recipient = ?)
+         OR EXISTS(SELECT 1 FROM agent_session_instances WHERE project = ? AND session_instance_id = ?)
+       ) AS seen`).get(project, recipient, project, recipient, project, recipient);
+        return row?.seen === undefined ? undefined : Boolean(row.seen);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function unreadInboxLines(count, project, recipient, everSeen) {
+    if (!recipient)
         return [];
-    const noun = count === 1 ? 'message' : 'messages';
     const displayProject = JSON.stringify(project);
     const displayRecipient = JSON.stringify(recipient);
-    return [`${count} ${noun} waiting for ${displayRecipient} in project ${displayProject} — poll the message tool with project ${displayProject} and recipient ${displayRecipient}, then fetch each message_id; fetching does not acknowledge.`];
+    if (count > 0) {
+        const noun = count === 1 ? 'message' : 'messages';
+        return [`${count} ${noun} waiting for ${displayRecipient} in project ${displayProject} — poll the message tool with project ${displayProject} and recipient ${displayRecipient}, then fetch each message_id; fetching does not acknowledge.`];
+    }
+    if (everSeen === false) {
+        return [`No messages waiting for ${displayRecipient} in project ${displayProject} — and this recipient id has never been seen in this project (check for a typo).`];
+    }
+    return [];
 }