Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
113 commits
Select commit Hold shift + click to select a range
e15cdf6
Introduce Plexus module discovery and lifecycle event vocabulary
Yehonal Nov 16, 2026
4a5c3a1
Expose configured Plexus module discovery
Yehonal Nov 16, 2026
a9d5ca5
Add atomic Plexus module batches and lifecycle receipts
Yehonal Nov 16, 2026
12b7661
Update module description failure assertion
Yehonal Nov 16, 2026
8a13fe1
Support multiple namespaces per Plexus module
Yehonal Nov 16, 2026
23bbb0d
Support bounded larger module graph requests
Yehonal Nov 16, 2026
cee31a8
Mark module conformance input as synthetic
Yehonal Nov 16, 2026
d3eae1c
Reject stale module snapshots without blocking graph writers
Yehonal Nov 16, 2026
0c1633e
Expose lifecycle evidence to trusted local modules
Yehonal Nov 16, 2026
69679ed
Guard Plexus mechanism files against private policy
Yehonal Nov 16, 2026
250a932
Model channel handover and pending delivery transitions
Yehonal Nov 16, 2026
0d58705
Persist channel queue transitions in graph journal
Yehonal Nov 16, 2026
17c0893
Add checked Plexus architecture diagram
Yehonal Nov 16, 2026
711d9ea
Persist ordered channel delivery reservations
Yehonal Nov 16, 2026
62c5965
Route waker notifications through durable channels
Yehonal Nov 16, 2026
35c6239
Guard channel cutover with fresh native evidence
Yehonal Nov 16, 2026
203dc88
Test lost channel reservation responses
Yehonal Nov 16, 2026
7ab7836
Keep channel cutover closed until state is verified
Yehonal Nov 16, 2026
585a3af
Prepare private handover state proof verification
Yehonal Nov 16, 2026
0b2cd85
Bind handover state proof to native session reply
Yehonal Nov 16, 2026
32c2ce7
Require private graph state for channel queues
Yehonal Nov 16, 2026
9b3f979
Accept prefixed channel identifiers
Yehonal Nov 16, 2026
b362a69
Pass channel payloads to adapters through stdin
Yehonal Nov 16, 2026
dec1b15
Queue channel messages through the local app server
Yehonal Nov 16, 2026
0bf7d88
Ignore untracked Python bytecode in privacy scan
Yehonal Nov 16, 2026
784862a
Pass state attestation requests over stdin
Yehonal Nov 16, 2026
6a6a7da
Define restart state data contract
Yehonal Nov 16, 2026
142eea3
Show restart state in Plexus diagram
Yehonal Nov 16, 2026
3afe172
Validate bounded restart YAML against state proof
Yehonal Nov 16, 2026
98f64d7
Prepare verified successor notice formatting
Yehonal Nov 16, 2026
b701620
Inspect correlated Codex final notice snapshots
Yehonal Nov 16, 2026
417ddd5
Represent observed session wake events
Yehonal Nov 16, 2026
cacc627
Handle exited process during inbox test cleanup
Yehonal Nov 16, 2026
2e659ba
Record verifiable Codex compaction evidence
Yehonal Nov 16, 2026
f3d987e
Allow lease cleanup time on busy runners
Yehonal Nov 16, 2026
aeb34e3
Guard channel reservation by recipient
Yehonal Nov 16, 2026
36e3ac2
Honor native default compaction item view
Yehonal Nov 16, 2026
1896ef1
Guard channel reservation by generation
Yehonal Nov 16, 2026
f62d195
Reserve channel state preparation before transport
Yehonal Nov 16, 2026
a6a87c2
Allow lease renewal observation under load
Yehonal Nov 16, 2026
3208994
Test interrupted handover preparation replay
Yehonal Nov 16, 2026
85d7be6
Add guarded trigger reconciliation engine
Yehonal Nov 16, 2026
017be51
Persist trigger transaction reservations
Yehonal Nov 16, 2026
99d2958
Recover uncertain trigger transactions explicitly
Yehonal Nov 16, 2026
2019d36
Bind cloud account scope to CLI profile
Yehonal Nov 16, 2026
9e2a72e
Record native queued wake evidence
Yehonal Nov 16, 2026
e33286f
Require correlated native wake readback
Yehonal Nov 16, 2026
e724013
Test wake readback identity mismatches
Yehonal Nov 16, 2026
d05585f
Expose correlated native queue identity
Yehonal Nov 16, 2026
3fc091a
Preserve bound queue identity in channel journal
Yehonal Nov 16, 2026
d2cb10a
Reserve wake identity before channel handover
Yehonal Nov 16, 2026
f73b9f7
Reserve channel before native wake start
Yehonal Nov 16, 2026
97f5ac0
Settle wake reservation after verified evidence
Yehonal Nov 16, 2026
8ca169e
Prevent duplicate wake reservations across channels
Yehonal Nov 16, 2026
43c0df9
Define role-scoped restart preparation
Yehonal Nov 16, 2026
9432666
Prepare wake reconciliation draft
Yehonal Nov 16, 2026
35338cb
Verify correlated wake recovery from native readback
Yehonal Nov 16, 2026
aa67d06
Rehearse role handover faults in memory
Yehonal Nov 16, 2026
1b138e8
Probe allowlisted role MCP servers
Yehonal Nov 16, 2026
737cac2
Cancel temporary MCP probes on deadline
Yehonal Nov 16, 2026
2918444
Wait for MCP probe termination
Yehonal Nov 16, 2026
8c9f17d
Bind cloud queue sends to account profile
Yehonal Nov 16, 2026
025e532
Route scoped cloud channel queues
Yehonal Nov 16, 2026
b4a2657
Fail closed if MCP probe termination is unconfirmed
Yehonal Nov 16, 2026
595dbd1
Reject invalid MCP probe authority
Yehonal Nov 16, 2026
d37af0c
Record failed trigger preflight without retaining reservation
Yehonal Nov 16, 2026
64677e9
Observe final notice in local Claude transcripts
Yehonal Nov 16, 2026
f2a6aba
Add local native final notice adapter
Yehonal Nov 16, 2026
1f41606
Reserve final notices before local delivery
Yehonal Nov 16, 2026
71a2036
Record local final notice observation in graph
Yehonal Nov 16, 2026
3051907
Prepare bounded Codex MCP connection sampling
Yehonal Nov 16, 2026
7f7059f
Require explicit isolated MCP sample connector
Yehonal Nov 16, 2026
39e50da
Observe Codex MCP startup notifications passively
Yehonal Nov 16, 2026
d078e6f
Prepare explicit role MCP exclusions for Codex
Yehonal Nov 16, 2026
c723f55
Assess observed Codex role start against policy
Yehonal Nov 16, 2026
d59aaf3
Add fail-closed namespace execution gate
Yehonal Nov 16, 2026
ba29806
Prepare owned isolated PID namespace lease
Yehonal Nov 16, 2026
565ebff
Test supervisor death around namespace release
Yehonal Nov 16, 2026
e143de0
Record uncertain trigger readback outcomes
Yehonal Nov 16, 2026
439dc45
Separate channel switch from predecessor notice
Yehonal Nov 16, 2026
e267497
Bind wake readback to channel backlog
Yehonal Nov 16, 2026
ed286b1
Test notice reservation after channel draining
Yehonal Nov 16, 2026
f7ca30f
Observe local Claude delivery in transcript
Yehonal Nov 16, 2026
04d7022
Correlate native Claude inbox observations
Yehonal Nov 16, 2026
79fc605
Recover uncertain wake during channel draining
Yehonal Nov 16, 2026
6c4d6cf
Revalidate restart state before handover
Yehonal Nov 16, 2026
2af8d30
Bind restart revalidation to channel state
Yehonal Nov 16, 2026
d03039c
Cover an automatically drained wake queue
Yehonal Nov 16, 2026
514482d
Reconcile automatically started wake by readback
Yehonal Nov 16, 2026
e514cc1
Disable unproven automatic wake observations
Yehonal Nov 16, 2026
0c54ca4
Reject ambiguous wake recovery evidence
Yehonal Nov 16, 2026
0ada6a3
Contain role MCP probes in a PID namespace
Yehonal Nov 16, 2026
49a3520
Require an explicit permit before MCP probe execution
Yehonal Nov 16, 2026
6452c31
Check namespace cleanup without host PID assumptions
Yehonal Nov 16, 2026
9374094
Make offline probe fixture independent of startup timing
Yehonal Nov 16, 2026
e2edc3d
Observe legacy Codex approval requests
Yehonal Nov 17, 2026
4d67759
Add opt-in isolated Codex rollback exercise
Yehonal Nov 17, 2026
d12aa23
Connect isolated role assessment to owned rollback
Yehonal Nov 17, 2026
b51754a
Persist isolated rollback intent before stopping
Yehonal Nov 17, 2026
b11e306
test: qualify isolated Claude mailbox delivery
Yehonal Nov 17, 2026
e21835e
Report inbox hook budget expiry
Yehonal Nov 17, 2026
8f4850d
Keep inbox hook timeout diagnostics opt in
Yehonal Nov 17, 2026
3d113ae
Observe Claude channel backlog before dispatch
Yehonal Nov 17, 2026
fb1afce
Recover Claude delivery from transcript evidence
Yehonal Nov 17, 2026
33813e6
Qualify Claude recovery against native transcript
Yehonal Nov 17, 2026
cb53d77
Recheck Claude transcript before delivery settlement
Yehonal Nov 17, 2026
de47932
Make Claude delivery snapshots recheckable
Yehonal Nov 17, 2026
b1b3a0c
Gate explicit Codex backlog wake evidence
Yehonal Nov 17, 2026
9cd04ec
Check Codex wake readiness before reservation
Yehonal Nov 17, 2026
1f18b13
Confirm delayed Codex wake readback
Yehonal Nov 17, 2026
4b422c1
Fence delayed trigger moves during recovery
Yehonal Nov 17, 2026
1695379
Fence stale trigger journal writers on recovery
Yehonal Nov 17, 2026
907f06e
Exercise trigger takeover across processes
Yehonal Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/verify.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ jobs:
node-version: "22"
cache: npm
- name: Install isolation test dependencies
run: sudo apt-get update && sudo apt-get install -y bubblewrap tmux
run: sudo apt-get update && sudo apt-get install -y bubblewrap tmux python3-yaml
- name: Verify isolation support
run: bwrap --unshare-all --die-with-parent --ro-bind / / /bin/true
- name: Install
Expand Down
34 changes: 34 additions & 0 deletions docs/design/plexus-architecture.mmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
flowchart LR
Client["Client or waker"] -- "channel mode" --> Channel["Stable channel"]
Channel --> Queue["Channel queue"]
Channel --> Session["Current session"]
Queue --> Journal["Graph event journal"]
Session --> Journal
Wake["Codex queued wake evidence"] --> Journal
Wake -. "planned waker integration" .-> Queue
Compaction["Codex compaction evidence"] --> Journal
Module["Registered module"] --> Contract["Versioned JSON contract"]
Contract --> Journal
Queue -- "bound receipt" --> Session
CloudAccount["Cloud account binding"] -. "planned routing" .-> Queue
Yaml["Bounded YAML decoder"] --> Restart
Restart["Restart state contract"] --> StatePrep["Reserved state preparation"]
Restart --> RoleProfile["Role-scoped launch plan"]
RoleProfile -. "synthetic rehearsal" .-> Rehearsal["In-memory handover rehearsal"]
RoleProfile -. "isolated assessment" .-> IsolatedRollback["Owned isolated rollback"]
IsolatedRollback -. "live handover blocked" .-> Handover
RoleProfile -. "planned runtime launch" .-> Handover
StatePrep --> Journal
StatePrep --> Revalidate["Restart state revalidation"]
Revalidate -. "planned lifecycle exclusion" .-> Handover
TriggerTxn["Trigger transaction engine"] --> TriggerJournal["Private trigger journal"]
TriggerRecovery["Explicit uncertain recovery"] --> TriggerJournal
TriggerTxn -. "planned scheduler adapters" .-> Handover
Notice["Successor notice formatter"] -. "planned publication" .-> Handover
Observation["Codex notice snapshot"] -. "planned finality check" .-> Handover
Handover["Handover"] -. "planned verified cutover" .-> Channel
Channel -. "pure switch model" .-> Drain["Observe queued deliveries"]
Drain -. "then reserve" .-> Notice
AutoWake["Auto-wake observation disabled"] -. "consumption unproven" .-> Wake
Wake -. "bound native proof" .-> Drain
ClaudeReadback["Local Claude transcript observer"] -. "observed inbox record" .-> Drain
325 changes: 325 additions & 0 deletions docs/design/plexus-channels.md

Large diffs are not rendered by default.

146 changes: 146 additions & 0 deletions docs/design/plexus-modules.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
# Plexus external modules

Status: design in progress. This document does not authorize a live rollout.

Plexus provides a generic extension boundary. Module commands, configuration and
private data belong to the operator; Plexus does not embed the policy of a module.
An external module must be invoked without a shell and must identify itself with
`describe`. A module keeps its own durable event cursor and may only write
attributes and events in its registered namespace. The registry is private and
must be explicitly configured; absence of configuration enables no modules.

## Lifecycle evidence

The lifecycle vocabulary is `session.started`, `session.woken`, `session.idle`,
`session.compacted`, `session.stopped`, and `session.handover`. A producer may
record one of these only when it has evidence for that transition. Discovery,
quietness, a queued message, or an expired lease alone are not proof that a
process stopped, compacted or handed over. Event ids must be stable on retry.

`session.woken` means that a wake-caused turn was actually observed for the
named session, with source evidence that binds the wake to that turn. Starting
a process, scheduling or accepting a message, or a generic unrelated turn is
not proof of a wake. Use a stable observation id across retries and deduplicate
the feed by `eventId`. A missing wake event is not evidence of zero wakes;
consumers must establish source and time-window coverage separately. This
contract does not itself install or enable a wake-event producer.

An experimental, explicitly invoked Codex adapter can bind an exact queued
submission and waker correlation to the turn returned by `thread/queue/start`.
It requires a full native thread readback with the same turn, start time,
message client id and input; incomplete or mismatched readback is unknown.
It first reserves the queue identity durably in a private evidence directory;
an ambiguous response leaves that identity reserved and requires manual
reconciliation rather than an automatic retry. Evidence records the session,
queue id, correlation, turn id and native start time, without message content;
its content-addressed reference can be checked locally with `--verify`.
Publishing a retained proof is idempotent. The operator must use one protected
evidence root and trust the local socket and waker's correlation: the file is
not an attestation against a local writer. `--apply` actually starts a queued
turn. Nothing schedules or enables this adapter, and its native behavior has
only been exercised with a synthetic server, not verified against a live runtime.
It is not connected to the waker or Limen and does not prove historical coverage.
For the native Codex stdin queue path, the transport receipt exposes the native
queue id alongside its session and correlation. The channel waker persists this
id in the same accepted queue item and generation when supplied. This proves
queue acceptance only; the waker does not yet invoke the wake-evidence adapter.
An ambiguous send remains inflight and cannot be automatically retried.
The channel journal can reserve an accepted wake by exact session, generation,
correlation and native queue id. An outstanding reservation blocks handover
and survives replay; it has no expiry. The graph refuses another channel's
reservation for that same session and queue id, and refuses already recorded
wakes. The experimental wake adapter acquires
the reservation before starting a turn and settles it only after the evidence
and lifecycle receipt are verified. Re-publishing the same proof with its
channel can recover a crash after the proof was written. An explicit recovery
may instead read the native thread, find a unique correlated user message that
matches the protected channel item, and verify the durable intent before
recording a distinct recovery proof. It never starts or resumes a thread.
Missing, partial, duplicate or mismatched observations remain unresolved;
there is no automatic retry. This path is not ready for operational use.

For a specific known Codex compaction, `codex-compaction-evidence.mjs` performs
an on-demand read of the configured local app server. It requires the exact
thread, turn and `contextCompaction` item, a full turn view and a recorded item
completion timestamp. It writes a private, content-addressed evidence record
before idempotently recording `session.compacted` in an explicitly selected
graph; the command never defaults to the live graph. A local
consumer can resolve it with `--verify <reference> --session <session>
--evidence-root <directory>`, which checks the private file, digest and session.
This relies on an operator-controlled root and local app-server socket; the
record is not a cryptographic attestation against an untrusted local writer.
The feed's `at`
is the recording time; the evidence's `completedAtMs` is the native item time.
An absent item, partial view, unavailable timestamp, failed read or graph error
is unknown, never zero. This tool does not discover items, establish complete
history coverage, observe Claude, schedule collection or authenticate an
untrusted local socket. The operator must protect the socket and evidence root.
Older graph readers must understand the new lifecycle event before use.

Events use the graph's existing ordered, append-only store. Their consumers must
detect the retention watermark and report an expired cursor rather than silently
skip events. Graph projection, checkpoints, snapshots and compaction must remain
replayable with these events; deployments must account for older readers that
reject unknown event types before any producer is enabled.
The local unscoped change feed includes the opaque evidence reference so a
trusted registered module can inspect it. Scoped feeds omit that reference;
visibility of a session does not grant access to its evidence source. A
reference is not itself proof that its target has been verified.

## Isolation requirements

Namespacing must be enforced by the graph writer, not trusted to an executable.
A module must not change session identity, ownership, another module's state, or
core graph facts. Configuration is an authority boundary: arbitrary commands are
not accepted from events, graph attributes, user text or remote clients. Invocation
must be bounded by a timeout and an output limit; diagnostics must not leak
private inputs. A crash, invalid response or partial write must not advance the
module's cursor. Retry semantics must not duplicate committed changes.

Module conformance tests must cover protocol identity, namespace enforcement,
independent cursors, retries, malformed responses, timeout, and retention gaps.
The example module and all fixtures use synthetic data only.

## Proposed process protocol

The host invokes a configured argument vector followed by an operation; no shell
expansion is involved. Requests and responses are single JSON objects on stdin
and stdout. Every response identifies protocol `agent-mesh.plexus-module.v1`.
`describe` receives `{}` and returns the module name, its exact namespaces and
supported operations. The registry must reject duplicate names or namespaces.
The registry is an operator-owned allowlist, not a marketplace or code sandbox.

The initial read-only discovery surface is `mesh-graph module list` and
`mesh-graph module describe --name <name>`. It reads the operator-owned
`$XDG_CONFIG_HOME/agent-mesh/modules.json` (or `--config <path>`). The registry
has `schemaVersion: 1` and a `modules` array containing `name`, `command` as an
argument array, optional `namespaces` (default: the module name), and optional
`timeoutMs`. One command may own several namespaces. A missing file
registers no modules; malformed files and duplicate names fail closed. Describe
does not update a cursor or write graph state. stderr is not returned to callers.
Process requests are capped at 32 MiB; responses and configuration at 1 MiB.
Oversized requests fail without advancing the cursor rather than silently
truncating the graph. These limits are not a substitute for future pagination.

`module run --name <name>` observes the graph and a page from the module's
cursor without holding the writer lock during feed replay. If the graph moves
during observation or before commit, the run fails without advancing its cursor.
The host invokes `process` outside the lock, validates its response and commits
the bounded batch and cursor as one graph event under the lock. An intervening
run for the same module causes a cursor conflict. The request contains `schema`, `graph`, `cursor`, and `events`; the
response contains `schema`, `name`, `batchId`, `attributes`, and `events`.
Attributes identify a session and a namespaced key; they are projected under
that namespace on its node. Events identify a session, a namespaced type, and JSON data.
The cursor is host-owned, not selected by a module. An initial run starts at the
current head; an expired cursor fails closed and requires reconciliation. A
no-change run does not append a new batch solely to observe its own events.

`module apply` is an operator-level interface for an already computed batch;
the configured name determines its permitted namespaces. Both paths check the cursor and
the last batch id while holding the graph lock. An identical retry of the last
batch returns a duplicate receipt, while a reused id with different content or
an older cursor fails. No exactly-once guarantee is claimed for arbitrary
external effects made by an executable. `module conformance` checks a synthetic
description and process response with `mode: "conformance"` and synthetic graph
data; a module must not contact live sources in that mode. This command is not a sandbox or a proof of side-effect
isolation. Configuration and OS access remain under the operator's control.
35 changes: 35 additions & 0 deletions docs/design/plexus-restart-state.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Restart state contract

A state file may carry a `RIAVVIO` YAML block. Its versioned content records
the session being replaced, its stable channel, harness, working directory,
skills, triggers and goal. Trigger configuration is opaque to Plexus and is
interpreted only by the responsible adapter. The block may contain private
paths and prompts and belongs in a private state file, not in the public repo.

```yaml
schema: agent-mesh.restart.v1
session: codex:example
channel: '#example'
harness: codex
working_directory: /workspace
skills: [example-skill]
triggers:
- id: trigger-1
kind: timer
config:
prompt: Perform the next check.
goal:
objective: Finish the task.
status: active
```

`skills` and `triggers` are arrays, including when empty; `goal` is either an
object or null. Trigger `(kind, id)` pairs are unique. A trusted adapter must
bind the block to the correlated old session and channel, and independently
reconcile every trigger with its source before using it. The `restart-yaml.py`
decoder requires PyYAML and rejects duplicate keys, aliases, anchors, explicit
tags, oversized input and non-JSON values. It accepts either a standalone YAML
file or a single `## RIAVVIO` section immediately followed by a fenced `yaml`
block. `validateRestartState` checks the decoded object; neither component is
a scheduler or authorization to recreate anything. Handover remains disabled
until trigger reconciliation and final-notice verification are implemented.
2 changes: 1 addition & 1 deletion docs/design/plexus.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ In practice few nodes carry refs: nothing feeds them automatically, so linking i
storage. `agent` is also unvalidated, so test harnesses can leave nodes with arbitrary agent names.

Ledgers have no shared store. A file-based ledger and a database-backed work-item store are both
reachable only through opaque refs such as `management:MGT-0239`, which is the right boundary.
reachable only through opaque refs such as `ledger:item-1`, which is the right boundary.

## 2. Data model

Expand Down
2 changes: 1 addition & 1 deletion packages/tmux-bridge/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ node $BIN/mesh-graph.mjs show --json
The graph command atomically writes only `<state>/graph.json`; launch provenance is
the separate append-only stream described above. Neither path calls context or work-item
systems. Nodes may carry explicit opaque `--refs source:record,...` values, such as
`management:MGT-0239` or `amf:record-id`. The graph validates their shape but never resolves or
`ledger:item-1` or `amf:record-id`. The graph validates their shape but never resolves or
infers them. A work-orchestration or recall consumer may read `graph.json` and compose its own
projection. Keep `summary` to one compact line; session context belongs behind a ref.

Expand Down
Loading