From e15cdf6601840a9aa113c08b3dd4c1f67a94f7e5 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:51:42 +0000 Subject: [PATCH 001/113] Introduce Plexus module discovery and lifecycle event vocabulary --- docs/design/plexus-modules.md | 54 +++++++++++++++++++ packages/tmux-bridge/bin/plexus-modules.mjs | 49 +++++++++++++++++ packages/tmux-bridge/bin/plexus.mjs | 14 ++++- .../examples/plexus-example-module.mjs | 13 +++++ .../test/plexus-lifecycle.test.mjs | 22 ++++++++ .../tmux-bridge/test/plexus-modules.test.mjs | 27 ++++++++++ skills/agent-tmux/bin/plexus.mjs | 14 ++++- 7 files changed, 191 insertions(+), 2 deletions(-) create mode 100644 docs/design/plexus-modules.md create mode 100644 packages/tmux-bridge/bin/plexus-modules.mjs create mode 100644 packages/tmux-bridge/examples/plexus-example-module.mjs create mode 100644 packages/tmux-bridge/test/plexus-lifecycle.test.mjs create mode 100644 packages/tmux-bridge/test/plexus-modules.test.mjs diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md new file mode 100644 index 00000000..01a019b1 --- /dev/null +++ b/docs/design/plexus-modules.md @@ -0,0 +1,54 @@ +# 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.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. + +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. + +## 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 namespace and +supported operations. The registry must reject duplicate names or namespaces. +The registry is an operator-owned allowlist, not a marketplace or code sandbox. + +Before a module can make graph changes, the writer must accept a bounded batch +under the graph lock, verify its namespace and cursor precondition, and record +the batch and its next cursor atomically. Retrying an identical batch must return +its original receipt; reusing an id for different contents must fail. Module +events and attributes must survive graph replay, checkpointing and compaction. +These writer and transaction semantics are required work, not yet implemented. diff --git a/packages/tmux-bridge/bin/plexus-modules.mjs b/packages/tmux-bridge/bin/plexus-modules.mjs new file mode 100644 index 00000000..9c0cb77d --- /dev/null +++ b/packages/tmux-bridge/bin/plexus-modules.mjs @@ -0,0 +1,49 @@ +import { readFile } from "node:fs/promises"; +import { spawn } from "node:child_process"; + +export const MODULE_PROTOCOL = "agent-mesh.plexus-module.v1"; +const NAME = /^[a-z][a-z0-9-]{0,63}$/; +const MAX_BYTES = 1024 * 1024; + +// This is an operator allowlist, not a sandbox for untrusted programs. +export async function readModuleRegistry(path) { + let text; + try { text = await readFile(path, "utf8"); } + catch (error) { if (error.code === "ENOENT") return []; throw error; } + if (Buffer.byteLength(text) > MAX_BYTES) throw new Error("module registry is too large"); + const config = JSON.parse(text); + if (!config || config.schemaVersion !== 1 || !Array.isArray(config.modules)) throw new Error("invalid module registry"); + const names = new Set(); + return config.modules.map((entry) => { + if (!entry || !NAME.test(entry.name) || names.has(entry.name)) throw new Error("invalid or duplicate module name"); + if (!Array.isArray(entry.command) || !entry.command.length || entry.command.some(v => typeof v !== "string" || !v || v.includes("\0"))) throw new Error("invalid module command"); + const timeoutMs = entry.timeoutMs ?? 10000; + if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) throw new Error("invalid module timeout"); + names.add(entry.name); + return { name: entry.name, command: [...entry.command], timeoutMs }; + }); +} + +export async function describeModule(entry) { + const result = await new Promise((resolve, reject) => { + const child = spawn(entry.command[0], [...entry.command.slice(1), "describe"], { stdio: ["pipe", "pipe", "ignore"], shell: false }); + let output = [], bytes = 0, finished = false; + const finish = (error, value) => { if (finished) return; finished = true; clearTimeout(timer); error ? reject(error) : resolve(value); }; + const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new Error("module timed out")); }, entry.timeoutMs); + child.on("error", () => finish(new Error("module failed"))); + child.stdout.on("data", chunk => { + bytes += chunk.length; + if (bytes > MAX_BYTES) { child.kill("SIGKILL"); finish(new Error("module response too large")); } + else output.push(chunk); + }); + child.stdin.on("error", () => {}); + child.on("close", code => { + if (code !== 0) return finish(new Error("module failed")); + try { finish(null, JSON.parse(Buffer.concat(output).toString("utf8"))); } + catch { finish(new Error("invalid module response")); } + }); + child.stdin.end("{}\n"); + }); + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || result.namespace !== entry.name || !Array.isArray(result.operations) || !result.operations.includes("describe")) throw new Error("invalid module description"); + return result; +} diff --git a/packages/tmux-bridge/bin/plexus.mjs b/packages/tmux-bridge/bin/plexus.mjs index 4706a3df..87b8ce7c 100644 --- a/packages/tmux-bridge/bin/plexus.mjs +++ b/packages/tmux-bridge/bin/plexus.mjs @@ -18,7 +18,8 @@ export const LINK_SOURCES = /^(bridge-launch|hook|ledger-write|reconciler|operat export const ROLE_WEIGHTS = { owns: 1, "works-on": 1, coordinates: 0.8, reviews: 0.7, discusses: 0.6, observes: 0.3, mentioned: 0.2 }; export const HALF_LIFE_DAYS = 7; export const TOUCH_COALESCE_MS = 10 * 60 * 1000; -export const PLEXUS_EVENTS = new Set(["role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated"]); +export const LIFECYCLE_EVENTS = new Set(["session.started", "session.idle", "session.compacted", "session.stopped", "session.handover"]); +export const PLEXUS_EVENTS = new Set(["role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated", ...LIFECYCLE_EVENTS]); const HARNESSES = new Set(["codex", "claude"]); const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i; const SESSION_ID = /^(codex|claude):[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/; @@ -84,6 +85,15 @@ export function applyPlexusEvent(state, item) { const effects = []; const openLinks = () => [...state.links.values()].filter((link) => link.until === null); switch (item.type) { + case "session.started": + case "session.idle": + case "session.compacted": + case "session.stopped": + case "session.handover": + parseGraphSessionId(item.session); + if (typeof item.evidence !== "string" || !item.evidence || item.evidence.length > 512 || /[\r\n\x00]/.test(item.evidence)) throw new Error("lifecycle event requires an evidence reference"); + effects.push({ kind: item.type, session: item.session }); + break; case "role.changed": if (!state.roleClaims) state.roleClaims = new Map(); if (item.previous) state.roleClaims.set(item.previous.id, item.previous); @@ -886,6 +896,8 @@ function feedFor(state, seen, item) { if (from && to) out.push({ type: effect.kind, edgeId: effect.edge.id, kind: effect.edge.type, from, to, subject: effect.edge.id }); } else if (effect.kind === "session.renewed") { out.push({ type: "session.renewed", from: effect.from, to: effect.to, subject: effect.to }); + } else if (LIFECYCLE_EVENTS.has(effect.kind)) { + out.push({ type: effect.kind, session: effect.session, subject: effect.session }); } } return out; diff --git a/packages/tmux-bridge/examples/plexus-example-module.mjs b/packages/tmux-bridge/examples/plexus-example-module.mjs new file mode 100644 index 00000000..4bd67c82 --- /dev/null +++ b/packages/tmux-bridge/examples/plexus-example-module.mjs @@ -0,0 +1,13 @@ +#!/usr/bin/env node +// Synthetic protocol example; it has no access to real graph state. +if (process.argv[2] !== "describe") { + process.stderr.write("unsupported operation\n"); + process.exitCode = 1; +} else { + process.stdout.write(JSON.stringify({ + schema: "agent-mesh.plexus-module.v1", + name: "example", + namespace: "example", + operations: ["describe"], + }) + "\n"); +} diff --git a/packages/tmux-bridge/test/plexus-lifecycle.test.mjs b/packages/tmux-bridge/test/plexus-lifecycle.test.mjs new file mode 100644 index 00000000..79cd08a4 --- /dev/null +++ b/packages/tmux-bridge/test/plexus-lifecycle.test.mjs @@ -0,0 +1,22 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { applyPlexusEvent, LIFECYCLE_EVENTS, PLEXUS_EVENTS } from "../bin/plexus.mjs"; + +const session = "codex:11111111-1111-4111-8111-111111111111"; +const state = () => ({ nodes: new Map(), links: new Map(), edges: new Map(), renewals: [] }); + +test("lifecycle evidence is replayable without mutating session ownership", () => { + for (const type of LIFECYCLE_EVENTS) { + const graph = state(); + assert.ok(PLEXUS_EVENTS.has(type)); + assert.deepEqual(applyPlexusEvent(graph, { type, session, evidence: "source:example" }), [{ kind: type, session }]); + assert.equal(graph.nodes.size, 0); + assert.equal(graph.links.size, 0); + } +}); + +test("lifecycle events reject missing evidence and malformed identities", () => { + assert.throws(() => applyPlexusEvent(state(), { type: "session.idle", session }), /evidence/); + assert.throws(() => applyPlexusEvent(state(), { type: "session.started", session: "codex:bad", evidence: "source:example" }), /session/); + assert.throws(() => applyPlexusEvent(state(), { type: "session.stopped", session, evidence: "one\ntwo" }), /evidence/); +}); diff --git a/packages/tmux-bridge/test/plexus-modules.test.mjs b/packages/tmux-bridge/test/plexus-modules.test.mjs new file mode 100644 index 00000000..54293782 --- /dev/null +++ b/packages/tmux-bridge/test/plexus-modules.test.mjs @@ -0,0 +1,27 @@ +import assert from "node:assert/strict"; +import { mkdtemp, writeFile, rm } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import test from "node:test"; +import { readModuleRegistry, describeModule } from "../bin/plexus-modules.mjs"; + +test("registry is private configuration and duplicate names fail closed", async () => { + const dir = await mkdtemp(join(tmpdir(), "plexus-modules-")); + try { + const file = join(dir, "config.json"); + assert.deepEqual(await readModuleRegistry(file), []); + const entry = { name: "example", command: [process.execPath, "fixture.mjs"] }; + await writeFile(file, JSON.stringify({ schemaVersion: 1, modules: [entry, entry] })); + await assert.rejects(readModuleRegistry(file), /duplicate/); + await writeFile(file, "{"); + await assert.rejects(readModuleRegistry(file)); + } finally { await rm(dir, { recursive: true, force: true }); } +}); + +test("describe verifies identity and enforces timeouts", async () => { + const good = "process.stdout.write(JSON.stringify({schema:'agent-mesh.plexus-module.v1',name:'example',namespace:'example',operations:['describe']}))"; + const entry = { name: "example", command: [process.execPath, "-e", good], timeoutMs: 1000 }; + assert.equal((await describeModule(entry)).namespace, "example"); + await assert.rejects(describeModule({ ...entry, name: "other" }), /description/); + await assert.rejects(describeModule({ ...entry, command: [process.execPath, "-e", "setTimeout(()=>{}, 10000)"], timeoutMs: 20 }), /timed out/); +}); diff --git a/skills/agent-tmux/bin/plexus.mjs b/skills/agent-tmux/bin/plexus.mjs index 4706a3df..87b8ce7c 100644 --- a/skills/agent-tmux/bin/plexus.mjs +++ b/skills/agent-tmux/bin/plexus.mjs @@ -18,7 +18,8 @@ export const LINK_SOURCES = /^(bridge-launch|hook|ledger-write|reconciler|operat export const ROLE_WEIGHTS = { owns: 1, "works-on": 1, coordinates: 0.8, reviews: 0.7, discusses: 0.6, observes: 0.3, mentioned: 0.2 }; export const HALF_LIFE_DAYS = 7; export const TOUCH_COALESCE_MS = 10 * 60 * 1000; -export const PLEXUS_EVENTS = new Set(["role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated"]); +export const LIFECYCLE_EVENTS = new Set(["session.started", "session.idle", "session.compacted", "session.stopped", "session.handover"]); +export const PLEXUS_EVENTS = new Set(["role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated", ...LIFECYCLE_EVENTS]); const HARNESSES = new Set(["codex", "claude"]); const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i; const SESSION_ID = /^(codex|claude):[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/; @@ -84,6 +85,15 @@ export function applyPlexusEvent(state, item) { const effects = []; const openLinks = () => [...state.links.values()].filter((link) => link.until === null); switch (item.type) { + case "session.started": + case "session.idle": + case "session.compacted": + case "session.stopped": + case "session.handover": + parseGraphSessionId(item.session); + if (typeof item.evidence !== "string" || !item.evidence || item.evidence.length > 512 || /[\r\n\x00]/.test(item.evidence)) throw new Error("lifecycle event requires an evidence reference"); + effects.push({ kind: item.type, session: item.session }); + break; case "role.changed": if (!state.roleClaims) state.roleClaims = new Map(); if (item.previous) state.roleClaims.set(item.previous.id, item.previous); @@ -886,6 +896,8 @@ function feedFor(state, seen, item) { if (from && to) out.push({ type: effect.kind, edgeId: effect.edge.id, kind: effect.edge.type, from, to, subject: effect.edge.id }); } else if (effect.kind === "session.renewed") { out.push({ type: "session.renewed", from: effect.from, to: effect.to, subject: effect.to }); + } else if (LIFECYCLE_EVENTS.has(effect.kind)) { + out.push({ type: effect.kind, session: effect.session, subject: effect.session }); } } return out; From 4a5c3a171bc7f167cb210867e11c0284aee3c24a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:55:53 +0000 Subject: [PATCH 002/113] Expose configured Plexus module discovery --- docs/design/plexus-modules.md | 8 +++ packages/tmux-bridge/bin/mesh-graph.mjs | 15 +++++- packages/tmux-bridge/bin/plexus-modules.mjs | 4 +- .../tmux-bridge/test/plexus-modules.test.mjs | 19 +++++++ skills/agent-tmux/bin/mesh-graph.mjs | 15 +++++- skills/agent-tmux/bin/plexus-modules.mjs | 49 +++++++++++++++++++ 6 files changed, 106 insertions(+), 4 deletions(-) create mode 100644 skills/agent-tmux/bin/plexus-modules.mjs diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index 01a019b1..54465f93 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -46,6 +46,14 @@ and stdout. Every response identifies protocol `agent-mesh.plexus-module.v1`. 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 `. It reads the operator-owned +`$XDG_CONFIG_HOME/agent-mesh/modules.json` (or `--config `). The registry +has `schemaVersion: 1` and a `modules` array containing `name`, `command` as an +argument array, and optional `timeoutMs`. Namespace equals name. 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. + Before a module can make graph changes, the writer must accept a bounded batch under the graph lock, verify its namespace and cursor precondition, and record the batch and its next cursor atomically. Retrying an identical batch must return diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 034563c1..93b4a459 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -34,6 +34,7 @@ import * as plexus from "./plexus.mjs"; import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from "./session-catalog.mjs"; import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; +import { readModuleRegistry, describeModule } from "./plexus-modules.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -93,6 +94,7 @@ const { values, positionals } = parseArgs({ evidence: { type: "string" }, input: { type: "string" }, config: { type: "string" }, + name: { type: "string" }, sort: { type: "string" }, filter: { type: "string", multiple: true }, format: { type: "string" }, @@ -119,7 +121,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { module: ["list", "describe"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -131,6 +133,17 @@ const stateDir = resolve(values.state || GRAPH_DIR); try { switch (command) { + case "module": { + const configPath = values.config || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "agent-mesh", "modules.json"); + const entries = await readModuleRegistry(configPath); + if (subcommand === "list") printResult({ modules: entries.map(entry => ({ name: entry.name })) }, { json: true }); + else if (subcommand === "describe") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + printResult(await describeModule(entry), { json: true }); + } else throw new Error("unknown module operation"); + break; + } case "links": { if (subcommand !== "verify") throw new Error("unknown links operation"); const verify = graph => { diff --git a/packages/tmux-bridge/bin/plexus-modules.mjs b/packages/tmux-bridge/bin/plexus-modules.mjs index 9c0cb77d..7f0f9262 100644 --- a/packages/tmux-bridge/bin/plexus-modules.mjs +++ b/packages/tmux-bridge/bin/plexus-modules.mjs @@ -15,7 +15,7 @@ export async function readModuleRegistry(path) { if (!config || config.schemaVersion !== 1 || !Array.isArray(config.modules)) throw new Error("invalid module registry"); const names = new Set(); return config.modules.map((entry) => { - if (!entry || !NAME.test(entry.name) || names.has(entry.name)) throw new Error("invalid or duplicate module name"); + if (!entry || typeof entry.name !== "string" || !NAME.test(entry.name) || names.has(entry.name)) throw new Error("invalid or duplicate module name"); if (!Array.isArray(entry.command) || !entry.command.length || entry.command.some(v => typeof v !== "string" || !v || v.includes("\0"))) throw new Error("invalid module command"); const timeoutMs = entry.timeoutMs ?? 10000; if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) throw new Error("invalid module timeout"); @@ -44,6 +44,6 @@ export async function describeModule(entry) { }); child.stdin.end("{}\n"); }); - if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || result.namespace !== entry.name || !Array.isArray(result.operations) || !result.operations.includes("describe")) throw new Error("invalid module description"); + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || result.namespace !== entry.name || !Array.isArray(result.operations) || !result.operations.includes("describe") || result.operations.some(op => typeof op !== "string")) throw new Error("invalid module description"); return result; } diff --git a/packages/tmux-bridge/test/plexus-modules.test.mjs b/packages/tmux-bridge/test/plexus-modules.test.mjs index 54293782..3e88acd8 100644 --- a/packages/tmux-bridge/test/plexus-modules.test.mjs +++ b/packages/tmux-bridge/test/plexus-modules.test.mjs @@ -3,6 +3,9 @@ import { mkdtemp, writeFile, rm } from "node:fs/promises"; import { join } from "node:path"; import { tmpdir } from "node:os"; import test from "node:test"; +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { fileURLToPath } from "node:url"; import { readModuleRegistry, describeModule } from "../bin/plexus-modules.mjs"; test("registry is private configuration and duplicate names fail closed", async () => { @@ -18,6 +21,22 @@ test("registry is private configuration and duplicate names fail closed", async } finally { await rm(dir, { recursive: true, force: true }); } }); +test("graph discovers and describes only registered modules", async () => { + const dir = await mkdtemp(join(tmpdir(), "plexus-modules-cli-")); + try { + const config = join(dir, "config.json"); + const fixture = fileURLToPath(new URL("../examples/plexus-example-module.mjs", import.meta.url)); + const graph = fileURLToPath(new URL("../bin/mesh-graph.mjs", import.meta.url)); + await writeFile(config, JSON.stringify({ schemaVersion: 1, modules: [{ name: "example", command: [process.execPath, fixture] }] })); + const exec = promisify(execFile); + const list = await exec(process.execPath, [graph, "module", "list", "--config", config]); + assert.deepEqual(JSON.parse(list.stdout), { modules: [{ name: "example" }] }); + const describe = await exec(process.execPath, [graph, "module", "describe", "--config", config, "--name", "example"]); + assert.equal(JSON.parse(describe.stdout).namespace, "example"); + await assert.rejects(exec(process.execPath, [graph, "module", "describe", "--config", config, "--name", "unknown"])); + } finally { await rm(dir, { recursive: true, force: true }); } +}); + test("describe verifies identity and enforces timeouts", async () => { const good = "process.stdout.write(JSON.stringify({schema:'agent-mesh.plexus-module.v1',name:'example',namespace:'example',operations:['describe']}))"; const entry = { name: "example", command: [process.execPath, "-e", good], timeoutMs: 1000 }; diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 034563c1..93b4a459 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -34,6 +34,7 @@ import * as plexus from "./plexus.mjs"; import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from "./session-catalog.mjs"; import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; +import { readModuleRegistry, describeModule } from "./plexus-modules.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -93,6 +94,7 @@ const { values, positionals } = parseArgs({ evidence: { type: "string" }, input: { type: "string" }, config: { type: "string" }, + name: { type: "string" }, sort: { type: "string" }, filter: { type: "string", multiple: true }, format: { type: "string" }, @@ -119,7 +121,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { module: ["list", "describe"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -131,6 +133,17 @@ const stateDir = resolve(values.state || GRAPH_DIR); try { switch (command) { + case "module": { + const configPath = values.config || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "agent-mesh", "modules.json"); + const entries = await readModuleRegistry(configPath); + if (subcommand === "list") printResult({ modules: entries.map(entry => ({ name: entry.name })) }, { json: true }); + else if (subcommand === "describe") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + printResult(await describeModule(entry), { json: true }); + } else throw new Error("unknown module operation"); + break; + } case "links": { if (subcommand !== "verify") throw new Error("unknown links operation"); const verify = graph => { diff --git a/skills/agent-tmux/bin/plexus-modules.mjs b/skills/agent-tmux/bin/plexus-modules.mjs new file mode 100644 index 00000000..7f0f9262 --- /dev/null +++ b/skills/agent-tmux/bin/plexus-modules.mjs @@ -0,0 +1,49 @@ +import { readFile } from "node:fs/promises"; +import { spawn } from "node:child_process"; + +export const MODULE_PROTOCOL = "agent-mesh.plexus-module.v1"; +const NAME = /^[a-z][a-z0-9-]{0,63}$/; +const MAX_BYTES = 1024 * 1024; + +// This is an operator allowlist, not a sandbox for untrusted programs. +export async function readModuleRegistry(path) { + let text; + try { text = await readFile(path, "utf8"); } + catch (error) { if (error.code === "ENOENT") return []; throw error; } + if (Buffer.byteLength(text) > MAX_BYTES) throw new Error("module registry is too large"); + const config = JSON.parse(text); + if (!config || config.schemaVersion !== 1 || !Array.isArray(config.modules)) throw new Error("invalid module registry"); + const names = new Set(); + return config.modules.map((entry) => { + if (!entry || typeof entry.name !== "string" || !NAME.test(entry.name) || names.has(entry.name)) throw new Error("invalid or duplicate module name"); + if (!Array.isArray(entry.command) || !entry.command.length || entry.command.some(v => typeof v !== "string" || !v || v.includes("\0"))) throw new Error("invalid module command"); + const timeoutMs = entry.timeoutMs ?? 10000; + if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) throw new Error("invalid module timeout"); + names.add(entry.name); + return { name: entry.name, command: [...entry.command], timeoutMs }; + }); +} + +export async function describeModule(entry) { + const result = await new Promise((resolve, reject) => { + const child = spawn(entry.command[0], [...entry.command.slice(1), "describe"], { stdio: ["pipe", "pipe", "ignore"], shell: false }); + let output = [], bytes = 0, finished = false; + const finish = (error, value) => { if (finished) return; finished = true; clearTimeout(timer); error ? reject(error) : resolve(value); }; + const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new Error("module timed out")); }, entry.timeoutMs); + child.on("error", () => finish(new Error("module failed"))); + child.stdout.on("data", chunk => { + bytes += chunk.length; + if (bytes > MAX_BYTES) { child.kill("SIGKILL"); finish(new Error("module response too large")); } + else output.push(chunk); + }); + child.stdin.on("error", () => {}); + child.on("close", code => { + if (code !== 0) return finish(new Error("module failed")); + try { finish(null, JSON.parse(Buffer.concat(output).toString("utf8"))); } + catch { finish(new Error("invalid module response")); } + }); + child.stdin.end("{}\n"); + }); + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || result.namespace !== entry.name || !Array.isArray(result.operations) || !result.operations.includes("describe") || result.operations.some(op => typeof op !== "string")) throw new Error("invalid module description"); + return result; +} From a9d5ca5f6dd6b612e09d93909eb728399ff5c0f7 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:04:15 +0000 Subject: [PATCH 003/113] Add atomic Plexus module batches and lifecycle receipts --- docs/design/plexus-modules.md | 26 ++++-- packages/tmux-bridge/bin/mesh-graph.mjs | 92 ++++++++++++++++++- packages/tmux-bridge/bin/module-batches.mjs | 46 ++++++++++ packages/tmux-bridge/bin/plexus-modules.mjs | 15 ++- packages/tmux-bridge/bin/plexus.mjs | 18 +++- .../examples/plexus-example-module.mjs | 13 ++- .../test/plexus-lifecycle.test.mjs | 3 +- .../test/plexus-module-batch.test.mjs | 85 +++++++++++++++++ skills/agent-tmux/bin/mesh-graph.mjs | 92 ++++++++++++++++++- skills/agent-tmux/bin/module-batches.mjs | 46 ++++++++++ skills/agent-tmux/bin/plexus-modules.mjs | 15 ++- skills/agent-tmux/bin/plexus.mjs | 18 +++- 12 files changed, 441 insertions(+), 28 deletions(-) create mode 100644 packages/tmux-bridge/bin/module-batches.mjs create mode 100644 packages/tmux-bridge/test/plexus-module-batch.test.mjs create mode 100644 skills/agent-tmux/bin/module-batches.mjs diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index 54465f93..841306ee 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -54,9 +54,23 @@ argument array, and optional `timeoutMs`. Namespace equals name. 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. -Before a module can make graph changes, the writer must accept a bounded batch -under the graph lock, verify its namespace and cursor precondition, and record -the batch and its next cursor atomically. Retrying an identical batch must return -its original receipt; reusing an id for different contents must fail. Module -events and attributes must survive graph replay, checkpointing and compaction. -These writer and transaction semantics are required work, not yet implemented. +`module run --name ` captures the graph and a page from the module's +cursor under the graph lock, then invokes `process` outside the lock. The host +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 key; they are projected under that module's +name 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 namespace. 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; it is not a sandbox or a proof of side-effect +isolation. Configuration and OS access remain under the operator's control. diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 93b4a459..59a9f6f3 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -34,7 +34,8 @@ import * as plexus from "./plexus.mjs"; import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from "./session-catalog.mjs"; import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; -import { readModuleRegistry, describeModule } from "./plexus-modules.mjs"; +import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; +import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -121,7 +122,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { module: ["list", "describe"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -133,6 +134,31 @@ const stateDir = resolve(values.state || GRAPH_DIR); try { switch (command) { + case "lifecycle": { + if (subcommand !== "record") throw new Error("unknown lifecycle operation"); + if (!plexus.LIFECYCLE_EVENTS.has(values.type)) throw new Error("invalid lifecycle type"); + const session = requiredSingleLine(values.session, "--session"); + const evidence = requiredSingleLine(values.evidence, "--evidence"); + if (!OPAQUE_REF.test(evidence)) throw new Error("--evidence must be an opaque evidence reference"); + const sourceId = requiredSingleLine(values.id, "--id"); + if (!/^[A-Za-z0-9._:-]{1,128}$/.test(sourceId)) throw new Error("invalid lifecycle observation id"); + const to = values.to; + if (values.type === "session.handover" ? typeof to !== "string" || to === session : to !== undefined) throw new Error("handover alone requires a distinct --to session"); + const digest = createHash("sha256").update(JSON.stringify({ type: values.type, session, evidence, to: to ?? null })).digest("hex"); + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + const result = mutate(stateDir, graph => { + if (!graph.migrated || graph.unnumbered) throw new Error("lifecycle events require a migrated graph"); + if (graph.nodes.filter(node => plexus.sessionIdOf(node) === session).length !== 1 || (to && graph.nodes.filter(node => plexus.sessionIdOf(node) === to).length !== 1)) throw new Error("unknown or ambiguous session"); + const prior = (graph.lifecycleReceipts || []).find(item => item.id === receiptId); + if (prior) { + if (prior.digest !== digest) throw new Error("observation id reused with different contents"); + return { graph, result: { observation: sourceId, duplicate: true } }; + } + return { graph, event: event(values.type, { session, evidence, ...(to ? { to } : {}), receiptId, digest }), result: { observation: sourceId, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } case "module": { const configPath = values.config || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "agent-mesh", "modules.json"); const entries = await readModuleRegistry(configPath); @@ -141,6 +167,57 @@ try { const entry = entries.find(item => item.name === values.name); if (!entry) throw new Error("module is not registered"); printResult(await describeModule(entry), { json: true }); + } else if (subcommand === "conformance") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + const desc = await describeModule(entry); + if (!desc.operations.includes("process")) throw new Error("module does not support process"); + const graph = { nodes: [{ id: "synthetic-node", agent: "codex", runtimeUuid: "22222222-2222-4222-8222-222222222222" }], moduleStates: [] }; + const result = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph, cursor: null, events: [] }); + if (Object.keys(result).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); + validateModuleBatch(entry.name, { id: result.batchId, cursor: null, nextCursor: "synthetic-cursor", attributes: result.attributes, events: result.events }, graph, plexus.sessionIdOf); + printResult({ module: entry.name, conformance: "pass", scope: "synthetic protocol response only" }, { json: true }); + } else if (subcommand === "run") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + const description = await describeModule(entry); + if (!description.operations.includes("process")) throw new Error("module does not support process"); + ensureStateDir(stateDir); + const snapshot = withLock(stateDir, () => { + const graph = loadGraph(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("module runs require a migrated graph"); + const cursor = graph.moduleStates?.find(item => item.name === entry.name)?.cursor ?? null; + const query = cursor === null ? { initial: "head" } : { sinceCursor: cursor }; + const feed = runQuery(stateDir, "changes", { input: JSON.stringify(query) }); + if (feed.reset) throw new Error("module cursor expired; reconciliation required"); + return { graph, cursor, feed }; + }); + const events = snapshot.feed.events.filter(item => !item.type.startsWith(`${entry.name}.`)); + const output = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph: snapshot.graph, cursor: snapshot.cursor, events }); + if (Object.keys(output).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); + if (snapshot.cursor !== null && events.length === 0 && Array.isArray(output.attributes) && output.attributes.length === 0 && Array.isArray(output.events) && output.events.length === 0) { + printResult({ module: entry.name, unchanged: true }, { json: true }); + break; + } + const batch = { id: output.batchId, cursor: snapshot.cursor, nextCursor: snapshot.feed.cursor, attributes: output.attributes, events: output.events }; + const result = mutate(stateDir, graph => { + const checked = validateModuleBatch(entry.name, batch, graph, plexus.sessionIdOf); + if (checked.duplicate) return { graph, result: { module: entry.name, batchId: batch.id, duplicate: true } }; + return { graph, event: event("module.batch", { module: entry.name, batch, digest: checked.digest }), result: { module: entry.name, batchId: batch.id, duplicate: false } }; + }); + printResult(result, { json: true }); + } else if (subcommand === "apply") { + if (!entries.some(item => item.name === values.name)) throw new Error("module is not registered"); + const raw = values.input === "-" ? readFileSync(0, "utf8") : values.input; + if (typeof raw !== "string" || Buffer.byteLength(raw) > 1024 * 1024) throw new Error("invalid module input"); + const batch = JSON.parse(raw); + const result = mutate(stateDir, graph => { + if (!graph.migrated || graph.unnumbered) throw new Error("module batches require a migrated graph"); + const checked = validateModuleBatch(values.name, batch, graph, plexus.sessionIdOf); + if (checked.duplicate) return { graph, result: { module: values.name, batchId: batch.id, duplicate: true } }; + return { graph, event: event("module.batch", { module: values.name, batch, digest: checked.digest }), result: { module: values.name, batchId: batch.id, duplicate: false } }; + }); + printResult(result, { json: true }); } else throw new Error("unknown module operation"); break; } @@ -1121,7 +1198,7 @@ function readCheckpoint(statePath) { if (checkpoint.schema !== GRAPH_SCHEMA || checkpoint.graph?.schema !== GRAPH_SCHEMA || !Array.isArray(checkpoint.graph.nodes) || !Array.isArray(checkpoint.graph.edges) || // Older binaries rewrite the checkpoint without Plexus state; replaying from the file is the only safe answer. - !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || + !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Array.isArray(checkpoint.graph.moduleStates) || !Array.isArray(checkpoint.graph.lifecycleReceipts) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || !cursor || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || !Number.isSafeInteger(cursor.dev) || !Number.isSafeInteger(cursor.ino)) { return null; @@ -1210,7 +1287,7 @@ function* readEventRecords(statePath, offset = 0) { function deriveGraph(events, base = null) { const nodes = new Map((base?.nodes || []).map((node) => [node.id, node])); const edges = new Map((base?.edges || []).map((edge) => [edge.id, edge])); - const state = { nodes, roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; + const state = { nodes, moduleStates: new Map((base?.moduleStates || []).map(item => [item.name, item])), lifecycleReceipts: new Map((base?.lifecycleReceipts || []).map(item => [item.id, item])), roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; const baseSeq = base?.lastSeq || 0; let lastSeq = baseSeq; let unnumbered = base?.unnumbered === true; @@ -1222,8 +1299,13 @@ function deriveGraph(events, base = null) { lastSeq = Math.max(lastSeq, item.seq); } else if (state.migrated) unnumbered = true; generatedAt = item.at || generatedAt; + if (item.type === "module.batch") { + applyModuleBatch(state, item, plexus.sessionIdOf); + continue; + } if (plexus.PLEXUS_EVENTS.has(item.type)) { plexus.applyPlexusEvent(state, item); + if (plexus.LIFECYCLE_EVENTS.has(item.type) && item.receiptId) state.lifecycleReceipts.set(item.receiptId, { id: item.receiptId, digest: item.digest }); continue; } if (item.type === "node.upserted") { @@ -1253,6 +1335,8 @@ function deriveGraph(events, base = null) { edges: [...edges.values()].sort((left, right) => left.id.localeCompare(right.id)), links, renewals: state.renewals, + moduleStates: [...state.moduleStates.values()], + lifecycleReceipts: [...state.lifecycleReceipts.values()], roleClaims: [...state.roleClaims.values()], migrated: state.migrated, lastSeq, diff --git a/packages/tmux-bridge/bin/module-batches.mjs b/packages/tmux-bridge/bin/module-batches.mjs new file mode 100644 index 00000000..e6f2685f --- /dev/null +++ b/packages/tmux-bridge/bin/module-batches.mjs @@ -0,0 +1,46 @@ +import { createHash } from "node:crypto"; + +const NAME = /^[a-z][a-z0-9-]{0,63}$/; +const KEY = /^[a-z][a-z0-9_-]{0,63}$/; + +// A batch is one event, so graph changes and its checkpoint commit together. +export function validateModuleBatch(name, batch, graph, sessionIdOf) { + if (typeof name !== "string" || !NAME.test(name)) throw new Error("invalid module name"); + if (!batch || typeof batch !== "object" || Array.isArray(batch) || Object.keys(batch).some(k => !["id", "cursor", "nextCursor", "attributes", "events"].includes(k))) throw new Error("invalid module batch"); + if (typeof batch.id !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(batch.id)) throw new Error("invalid batch id"); + for (const c of [batch.cursor, batch.nextCursor]) if (!(c === null || (typeof c === "string" && c.length <= 4096))) throw new Error("invalid module cursor"); + if (batch.nextCursor === null) throw new Error("next cursor is required"); + if (!Array.isArray(batch.attributes) || batch.attributes.length > 200 || !Array.isArray(batch.events) || batch.events.length > 200) throw new Error("invalid batch contents"); + if (Buffer.byteLength(JSON.stringify(batch)) > 1024 * 1024) throw new Error("module batch too large"); + const seen = new Set(); + for (const attr of batch.attributes) { + if (!attr || Object.keys(attr).some(k => !["session", "key", "value"].includes(k)) || typeof attr.session !== "string" || typeof attr.key !== "string" || !KEY.test(attr.key) || !Object.hasOwn(attr, "value")) throw new Error("invalid module attribute"); + if (graph.nodes.filter(node => sessionIdOf(node) === attr.session).length !== 1) throw new Error("unknown or ambiguous session"); + const identity = `${attr.session}\0${attr.key}`; + if (seen.has(identity)) throw new Error("duplicate module attribute"); + seen.add(identity); + } + for (const ev of batch.events) { + if (!ev || Object.keys(ev).some(k => !["type", "session", "data"].includes(k)) || typeof ev.type !== "string" || !ev.type.startsWith(`${name}.`) || !KEY.test(ev.type.slice(name.length + 1)) || typeof ev.session !== "string" || graph.nodes.filter(node => sessionIdOf(node) === ev.session).length !== 1 || !Object.hasOwn(ev, "data")) throw new Error("invalid namespaced event"); + } + const digest = createHash("sha256").update(JSON.stringify(batch)).digest("hex"); + const previous = (graph.moduleStates || []).find(item => item.name === name); + if (previous?.batchId === batch.id) { + if (previous.digest !== digest) throw new Error("batch id reused with different contents"); + return { duplicate: true, digest }; + } + if ((previous?.cursor ?? null) !== batch.cursor) throw new Error("module cursor conflict"); + return { duplicate: false, digest }; +} + +export function applyModuleBatch(state, event, sessionIdOf) { + if (!state.moduleStates) state.moduleStates = new Map(); + for (const attr of event.batch.attributes) { + const node = [...state.nodes.values()].find(item => sessionIdOf(item) === attr.session); + if (!node) throw new Error("module batch names unknown session"); + const modules = { ...(node.moduleAttributes || {}) }; + modules[event.module] = { ...(Object.hasOwn(modules, event.module) ? modules[event.module] : {}), [attr.key]: attr.value }; + state.nodes.set(node.id, { ...node, moduleAttributes: modules }); + } + state.moduleStates.set(event.module, { name: event.module, cursor: event.batch.nextCursor, batchId: event.batch.id, digest: event.digest }); +} diff --git a/packages/tmux-bridge/bin/plexus-modules.mjs b/packages/tmux-bridge/bin/plexus-modules.mjs index 7f0f9262..52b9a477 100644 --- a/packages/tmux-bridge/bin/plexus-modules.mjs +++ b/packages/tmux-bridge/bin/plexus-modules.mjs @@ -24,9 +24,12 @@ export async function readModuleRegistry(path) { }); } -export async function describeModule(entry) { +export async function invokeModule(entry, operation, request) { + if (!["describe", "process"].includes(operation)) throw new Error("invalid module operation"); + const input = JSON.stringify(request); + if (Buffer.byteLength(input) > MAX_BYTES) throw new Error("module request too large"); const result = await new Promise((resolve, reject) => { - const child = spawn(entry.command[0], [...entry.command.slice(1), "describe"], { stdio: ["pipe", "pipe", "ignore"], shell: false }); + const child = spawn(entry.command[0], [...entry.command.slice(1), operation], { stdio: ["pipe", "pipe", "ignore"], shell: false }); let output = [], bytes = 0, finished = false; const finish = (error, value) => { if (finished) return; finished = true; clearTimeout(timer); error ? reject(error) : resolve(value); }; const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new Error("module timed out")); }, entry.timeoutMs); @@ -42,8 +45,14 @@ export async function describeModule(entry) { try { finish(null, JSON.parse(Buffer.concat(output).toString("utf8"))); } catch { finish(new Error("invalid module response")); } }); - child.stdin.end("{}\n"); + child.stdin.end(`${input}\n`); }); + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name) throw new Error("invalid module response"); + return result; +} + +export async function describeModule(entry) { + const result = await invokeModule(entry, "describe", {}); if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || result.namespace !== entry.name || !Array.isArray(result.operations) || !result.operations.includes("describe") || result.operations.some(op => typeof op !== "string")) throw new Error("invalid module description"); return result; } diff --git a/packages/tmux-bridge/bin/plexus.mjs b/packages/tmux-bridge/bin/plexus.mjs index 87b8ce7c..79f5d6e4 100644 --- a/packages/tmux-bridge/bin/plexus.mjs +++ b/packages/tmux-bridge/bin/plexus.mjs @@ -7,6 +7,7 @@ import { createHmac, randomUUID } from "node:crypto"; import { posix } from "node:path"; import { createHash } from "node:crypto"; +import { applyModuleBatch } from "./module-batches.mjs"; import { LEDGER_VIEW_SCHEMA, LEDGER_VIEW_SORT, buildLedgerViewRows, ledgerViewProfileRevision, ledgerViewValue, validateLedgerViewProfile @@ -92,7 +93,11 @@ export function applyPlexusEvent(state, item) { case "session.handover": parseGraphSessionId(item.session); if (typeof item.evidence !== "string" || !item.evidence || item.evidence.length > 512 || /[\r\n\x00]/.test(item.evidence)) throw new Error("lifecycle event requires an evidence reference"); - effects.push({ kind: item.type, session: item.session }); + if (item.type === "session.handover") { + parseGraphSessionId(item.to); + if (item.to === item.session) throw new Error("handover target must differ"); + } else if (item.to !== undefined) throw new Error("unexpected lifecycle target"); + effects.push({ kind: item.type, session: item.session, ...(item.to ? { to: item.to } : {}) }); break; case "role.changed": if (!state.roleClaims) state.roleClaims = new Map(); @@ -787,6 +792,7 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { nodes: new Map((snapshotGraph?.nodes || []).map((node) => [node.id, node])), links: new Map((snapshotGraph?.links || []).map((link) => [link.id, link])), edges: new Map((snapshotGraph?.edges || []).map((edge) => [edge.id, edge])), + moduleStates: new Map((snapshotGraph?.moduleStates || []).map(item => [item.name, item])), renewals: [...(snapshotGraph?.renewals || [])], migrated: snapshotGraph?.migrated === true, }; const seen = new Set([...state.nodes.values()].map(sessionIdOf).filter(Boolean)); @@ -818,6 +824,10 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { } function applyReplay(state, item, emitted) { + if (item.type === "module.batch") { + if (!emitted) applyModuleBatch(state, item, sessionIdOf); + return; + } if (item.type === "node.upserted") { state.nodes.set(item.node.id, item.node); return; @@ -836,6 +846,10 @@ function applyReplay(state, item, emitted) { function feedFor(state, seen, item) { const out = []; + if (item.type === "module.batch") { + applyModuleBatch(state, item, sessionIdOf); + return item.batch.events.map((entry, index) => ({ type: entry.type, session: entry.session, data: entry.data, subject: `${item.id}:${index}` })); + } if (item.type === "node.upserted") { const id = sessionIdOf(item.node); const previous = state.nodes.get(item.node.id); @@ -897,7 +911,7 @@ function feedFor(state, seen, item) { } else if (effect.kind === "session.renewed") { out.push({ type: "session.renewed", from: effect.from, to: effect.to, subject: effect.to }); } else if (LIFECYCLE_EVENTS.has(effect.kind)) { - out.push({ type: effect.kind, session: effect.session, subject: effect.session }); + out.push({ type: effect.kind, session: effect.session, ...(effect.to ? { to: effect.to } : {}), subject: effect.session }); } } return out; diff --git a/packages/tmux-bridge/examples/plexus-example-module.mjs b/packages/tmux-bridge/examples/plexus-example-module.mjs index 4bd67c82..8952dee4 100644 --- a/packages/tmux-bridge/examples/plexus-example-module.mjs +++ b/packages/tmux-bridge/examples/plexus-example-module.mjs @@ -1,6 +1,13 @@ #!/usr/bin/env node -// Synthetic protocol example; it has no access to real graph state. -if (process.argv[2] !== "describe") { +// Synthetic protocol example; it never writes attributes or events. +import { createHash } from "node:crypto"; +import { readFileSync } from "node:fs"; + +if (process.argv[2] === "process") { + const input = JSON.parse(readFileSync(0, "utf8")); + const batchId = createHash("sha256").update(JSON.stringify(input.cursor)).digest("hex"); + process.stdout.write(JSON.stringify({ schema: "agent-mesh.plexus-module.v1", name: "example", batchId, attributes: [], events: [] }) + "\n"); +} else if (process.argv[2] !== "describe") { process.stderr.write("unsupported operation\n"); process.exitCode = 1; } else { @@ -8,6 +15,6 @@ if (process.argv[2] !== "describe") { schema: "agent-mesh.plexus-module.v1", name: "example", namespace: "example", - operations: ["describe"], + operations: ["describe", "process"], }) + "\n"); } diff --git a/packages/tmux-bridge/test/plexus-lifecycle.test.mjs b/packages/tmux-bridge/test/plexus-lifecycle.test.mjs index 79cd08a4..b19faf7b 100644 --- a/packages/tmux-bridge/test/plexus-lifecycle.test.mjs +++ b/packages/tmux-bridge/test/plexus-lifecycle.test.mjs @@ -9,7 +9,8 @@ test("lifecycle evidence is replayable without mutating session ownership", () = for (const type of LIFECYCLE_EVENTS) { const graph = state(); assert.ok(PLEXUS_EVENTS.has(type)); - assert.deepEqual(applyPlexusEvent(graph, { type, session, evidence: "source:example" }), [{ kind: type, session }]); + const extra = type === "session.handover" ? { to: "claude:33333333-3333-4333-8333-333333333333" } : {}; + assert.deepEqual(applyPlexusEvent(graph, { type, session, evidence: "source:example", ...extra }), [{ kind: type, session, ...extra }]); assert.equal(graph.nodes.size, 0); assert.equal(graph.links.size, 0); } diff --git a/packages/tmux-bridge/test/plexus-module-batch.test.mjs b/packages/tmux-bridge/test/plexus-module-batch.test.mjs new file mode 100644 index 00000000..2525971a --- /dev/null +++ b/packages/tmux-bridge/test/plexus-module-batch.test.mjs @@ -0,0 +1,85 @@ +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { promisify } from "node:util"; +import test from "node:test"; + +const exec = promisify(execFile); +const graph = fileURLToPath(new URL("../bin/mesh-graph.mjs", import.meta.url)); +const uuid = "22222222-2222-4222-8222-222222222222"; +const session = `codex:${uuid}`; + +test("module batches atomically update their own state and survive replay and compaction", async (t) => { + const dir = await mkdtemp(join(tmpdir(), "plexus-batch-")); + t.after(() => rm(dir, { recursive: true, force: true })); + const state = join(dir, "state"), config = join(dir, "modules.json"); + await writeFile(config, JSON.stringify({ schemaVersion: 1, modules: [{ name: "example", command: ["example"] }, { name: "other", command: ["example"] }] })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, "--state", state, ...args])).stdout); + await call("add", "--agent", "codex", "--tmux-target", "test", "--cwd", "/synthetic", "--runtime-uuid", uuid, "--json"); + await call("migrate", "--apply", "--json"); + const start = await call("query", "changes", "--input", JSON.stringify({ initial: "head" })); + const batch = { id: "a1", cursor: null, nextCursor: "one", attributes: [{ session, key: "count", value: 1 }], events: [{ type: "example.changed", session, data: { count: 1 } }] }; + const apply = (name, input) => call("module", "apply", "--config", config, "--name", name, "--input", JSON.stringify(input)); + assert.equal((await apply("example", batch)).duplicate, false); + assert.equal((await apply("example", batch)).duplicate, true); + await assert.rejects(apply("example", { ...batch, attributes: [] }), /batch id reused/); + await assert.rejects(apply("other", batch), /namespaced/); + await assert.rejects(apply("example", { ...batch, id: "a2" }), /cursor conflict/); + const feed = await call("query", "changes", "--input", JSON.stringify({ sinceCursor: start.cursor })); + assert.equal(feed.events.filter(item => item.type === "example.changed").length, 1); + await rm(join(state, "checkpoint.json")); + let projection = await call("show", "--json"); + assert.equal(projection.nodes[0].moduleAttributes.example.count, 1); + assert.equal(projection.moduleStates[0].cursor, "one"); + await call("compact", "--all-history", "--apply", "--json"); + await rm(join(state, "checkpoint.json"), { force: true }); + projection = await call("show", "--json"); + assert.equal(projection.nodes[0].moduleAttributes.example.count, 1); + assert.equal(projection.moduleStates[0].cursor, "one"); + assert.equal((await apply("example", batch)).duplicate, true); + const racing = await Promise.allSettled([ + apply("example", { id: "race-a", cursor: "one", nextCursor: "two-a", attributes: [], events: [] }), + apply("example", { id: "race-b", cursor: "one", nextCursor: "two-b", attributes: [], events: [] }), + ]); + assert.equal(racing.filter(item => item.status === "fulfilled").length, 1); + assert.equal(racing.filter(item => item.status === "rejected").length, 1); +}); + +test("a registered module can initialize once and an idle run does not create events", async (t) => { + const dir = await mkdtemp(join(tmpdir(), "plexus-run-")); + t.after(() => rm(dir, { recursive: true, force: true })); + const state = join(dir, "state"), config = join(dir, "modules.json"); + const fixture = fileURLToPath(new URL("../examples/plexus-example-module.mjs", import.meta.url)); + await writeFile(config, JSON.stringify({ schemaVersion: 1, modules: [{ name: "example", command: [process.execPath, fixture] }] })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, "--state", state, ...args])).stdout); + await call("add", "--agent", "codex", "--tmux-target", "test", "--cwd", "/synthetic", "--runtime-uuid", uuid, "--json"); + await call("migrate", "--apply", "--json"); + assert.equal((await call("module", "conformance", "--config", config, "--name", "example")).conformance, "pass"); + assert.equal((await call("module", "run", "--config", config, "--name", "example")).duplicate, false); + const before = await call("show", "--json"); + assert.equal((await call("module", "run", "--config", config, "--name", "example")).unchanged, true); + const after = await call("show", "--json"); + assert.equal(after.lastSeq, before.lastSeq); +}); + +test("lifecycle observations are idempotent across replay and compaction", async (t) => { + const dir = await mkdtemp(join(tmpdir(), "plexus-life-")); + t.after(() => rm(dir, { recursive: true, force: true })); + const state = join(dir, "state"); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, "--state", state, ...args])).stdout); + await call("add", "--agent", "codex", "--tmux-target", "test", "--cwd", "/synthetic", "--runtime-uuid", uuid, "--json"); + await call("migrate", "--apply", "--json"); + const head = await call("query", "changes", "--input", JSON.stringify({ initial: "head" })); + const args = ["lifecycle", "record", "--session", session, "--type", "session.idle", "--id", "source-observation-1", "--evidence", "observation:sample"]; + assert.equal((await call(...args)).duplicate, false); + assert.equal((await call(...args)).duplicate, true); + await assert.rejects(call(...args.slice(0, -1), "observation:different"), /different contents/); + const feed = await call("query", "changes", "--input", JSON.stringify({ sinceCursor: head.cursor })); + assert.equal(feed.events.filter(item => item.type === "session.idle").length, 1); + await call("compact", "--all-history", "--apply", "--json"); + await rm(join(state, "checkpoint.json"), { force: true }); + assert.equal((await call(...args)).duplicate, true); +}); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 93b4a459..59a9f6f3 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -34,7 +34,8 @@ import * as plexus from "./plexus.mjs"; import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from "./session-catalog.mjs"; import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; -import { readModuleRegistry, describeModule } from "./plexus-modules.mjs"; +import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; +import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -121,7 +122,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { module: ["list", "describe"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -133,6 +134,31 @@ const stateDir = resolve(values.state || GRAPH_DIR); try { switch (command) { + case "lifecycle": { + if (subcommand !== "record") throw new Error("unknown lifecycle operation"); + if (!plexus.LIFECYCLE_EVENTS.has(values.type)) throw new Error("invalid lifecycle type"); + const session = requiredSingleLine(values.session, "--session"); + const evidence = requiredSingleLine(values.evidence, "--evidence"); + if (!OPAQUE_REF.test(evidence)) throw new Error("--evidence must be an opaque evidence reference"); + const sourceId = requiredSingleLine(values.id, "--id"); + if (!/^[A-Za-z0-9._:-]{1,128}$/.test(sourceId)) throw new Error("invalid lifecycle observation id"); + const to = values.to; + if (values.type === "session.handover" ? typeof to !== "string" || to === session : to !== undefined) throw new Error("handover alone requires a distinct --to session"); + const digest = createHash("sha256").update(JSON.stringify({ type: values.type, session, evidence, to: to ?? null })).digest("hex"); + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + const result = mutate(stateDir, graph => { + if (!graph.migrated || graph.unnumbered) throw new Error("lifecycle events require a migrated graph"); + if (graph.nodes.filter(node => plexus.sessionIdOf(node) === session).length !== 1 || (to && graph.nodes.filter(node => plexus.sessionIdOf(node) === to).length !== 1)) throw new Error("unknown or ambiguous session"); + const prior = (graph.lifecycleReceipts || []).find(item => item.id === receiptId); + if (prior) { + if (prior.digest !== digest) throw new Error("observation id reused with different contents"); + return { graph, result: { observation: sourceId, duplicate: true } }; + } + return { graph, event: event(values.type, { session, evidence, ...(to ? { to } : {}), receiptId, digest }), result: { observation: sourceId, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } case "module": { const configPath = values.config || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "agent-mesh", "modules.json"); const entries = await readModuleRegistry(configPath); @@ -141,6 +167,57 @@ try { const entry = entries.find(item => item.name === values.name); if (!entry) throw new Error("module is not registered"); printResult(await describeModule(entry), { json: true }); + } else if (subcommand === "conformance") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + const desc = await describeModule(entry); + if (!desc.operations.includes("process")) throw new Error("module does not support process"); + const graph = { nodes: [{ id: "synthetic-node", agent: "codex", runtimeUuid: "22222222-2222-4222-8222-222222222222" }], moduleStates: [] }; + const result = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph, cursor: null, events: [] }); + if (Object.keys(result).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); + validateModuleBatch(entry.name, { id: result.batchId, cursor: null, nextCursor: "synthetic-cursor", attributes: result.attributes, events: result.events }, graph, plexus.sessionIdOf); + printResult({ module: entry.name, conformance: "pass", scope: "synthetic protocol response only" }, { json: true }); + } else if (subcommand === "run") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + const description = await describeModule(entry); + if (!description.operations.includes("process")) throw new Error("module does not support process"); + ensureStateDir(stateDir); + const snapshot = withLock(stateDir, () => { + const graph = loadGraph(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("module runs require a migrated graph"); + const cursor = graph.moduleStates?.find(item => item.name === entry.name)?.cursor ?? null; + const query = cursor === null ? { initial: "head" } : { sinceCursor: cursor }; + const feed = runQuery(stateDir, "changes", { input: JSON.stringify(query) }); + if (feed.reset) throw new Error("module cursor expired; reconciliation required"); + return { graph, cursor, feed }; + }); + const events = snapshot.feed.events.filter(item => !item.type.startsWith(`${entry.name}.`)); + const output = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph: snapshot.graph, cursor: snapshot.cursor, events }); + if (Object.keys(output).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); + if (snapshot.cursor !== null && events.length === 0 && Array.isArray(output.attributes) && output.attributes.length === 0 && Array.isArray(output.events) && output.events.length === 0) { + printResult({ module: entry.name, unchanged: true }, { json: true }); + break; + } + const batch = { id: output.batchId, cursor: snapshot.cursor, nextCursor: snapshot.feed.cursor, attributes: output.attributes, events: output.events }; + const result = mutate(stateDir, graph => { + const checked = validateModuleBatch(entry.name, batch, graph, plexus.sessionIdOf); + if (checked.duplicate) return { graph, result: { module: entry.name, batchId: batch.id, duplicate: true } }; + return { graph, event: event("module.batch", { module: entry.name, batch, digest: checked.digest }), result: { module: entry.name, batchId: batch.id, duplicate: false } }; + }); + printResult(result, { json: true }); + } else if (subcommand === "apply") { + if (!entries.some(item => item.name === values.name)) throw new Error("module is not registered"); + const raw = values.input === "-" ? readFileSync(0, "utf8") : values.input; + if (typeof raw !== "string" || Buffer.byteLength(raw) > 1024 * 1024) throw new Error("invalid module input"); + const batch = JSON.parse(raw); + const result = mutate(stateDir, graph => { + if (!graph.migrated || graph.unnumbered) throw new Error("module batches require a migrated graph"); + const checked = validateModuleBatch(values.name, batch, graph, plexus.sessionIdOf); + if (checked.duplicate) return { graph, result: { module: values.name, batchId: batch.id, duplicate: true } }; + return { graph, event: event("module.batch", { module: values.name, batch, digest: checked.digest }), result: { module: values.name, batchId: batch.id, duplicate: false } }; + }); + printResult(result, { json: true }); } else throw new Error("unknown module operation"); break; } @@ -1121,7 +1198,7 @@ function readCheckpoint(statePath) { if (checkpoint.schema !== GRAPH_SCHEMA || checkpoint.graph?.schema !== GRAPH_SCHEMA || !Array.isArray(checkpoint.graph.nodes) || !Array.isArray(checkpoint.graph.edges) || // Older binaries rewrite the checkpoint without Plexus state; replaying from the file is the only safe answer. - !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || + !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Array.isArray(checkpoint.graph.moduleStates) || !Array.isArray(checkpoint.graph.lifecycleReceipts) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || !cursor || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || !Number.isSafeInteger(cursor.dev) || !Number.isSafeInteger(cursor.ino)) { return null; @@ -1210,7 +1287,7 @@ function* readEventRecords(statePath, offset = 0) { function deriveGraph(events, base = null) { const nodes = new Map((base?.nodes || []).map((node) => [node.id, node])); const edges = new Map((base?.edges || []).map((edge) => [edge.id, edge])); - const state = { nodes, roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; + const state = { nodes, moduleStates: new Map((base?.moduleStates || []).map(item => [item.name, item])), lifecycleReceipts: new Map((base?.lifecycleReceipts || []).map(item => [item.id, item])), roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; const baseSeq = base?.lastSeq || 0; let lastSeq = baseSeq; let unnumbered = base?.unnumbered === true; @@ -1222,8 +1299,13 @@ function deriveGraph(events, base = null) { lastSeq = Math.max(lastSeq, item.seq); } else if (state.migrated) unnumbered = true; generatedAt = item.at || generatedAt; + if (item.type === "module.batch") { + applyModuleBatch(state, item, plexus.sessionIdOf); + continue; + } if (plexus.PLEXUS_EVENTS.has(item.type)) { plexus.applyPlexusEvent(state, item); + if (plexus.LIFECYCLE_EVENTS.has(item.type) && item.receiptId) state.lifecycleReceipts.set(item.receiptId, { id: item.receiptId, digest: item.digest }); continue; } if (item.type === "node.upserted") { @@ -1253,6 +1335,8 @@ function deriveGraph(events, base = null) { edges: [...edges.values()].sort((left, right) => left.id.localeCompare(right.id)), links, renewals: state.renewals, + moduleStates: [...state.moduleStates.values()], + lifecycleReceipts: [...state.lifecycleReceipts.values()], roleClaims: [...state.roleClaims.values()], migrated: state.migrated, lastSeq, diff --git a/skills/agent-tmux/bin/module-batches.mjs b/skills/agent-tmux/bin/module-batches.mjs new file mode 100644 index 00000000..e6f2685f --- /dev/null +++ b/skills/agent-tmux/bin/module-batches.mjs @@ -0,0 +1,46 @@ +import { createHash } from "node:crypto"; + +const NAME = /^[a-z][a-z0-9-]{0,63}$/; +const KEY = /^[a-z][a-z0-9_-]{0,63}$/; + +// A batch is one event, so graph changes and its checkpoint commit together. +export function validateModuleBatch(name, batch, graph, sessionIdOf) { + if (typeof name !== "string" || !NAME.test(name)) throw new Error("invalid module name"); + if (!batch || typeof batch !== "object" || Array.isArray(batch) || Object.keys(batch).some(k => !["id", "cursor", "nextCursor", "attributes", "events"].includes(k))) throw new Error("invalid module batch"); + if (typeof batch.id !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(batch.id)) throw new Error("invalid batch id"); + for (const c of [batch.cursor, batch.nextCursor]) if (!(c === null || (typeof c === "string" && c.length <= 4096))) throw new Error("invalid module cursor"); + if (batch.nextCursor === null) throw new Error("next cursor is required"); + if (!Array.isArray(batch.attributes) || batch.attributes.length > 200 || !Array.isArray(batch.events) || batch.events.length > 200) throw new Error("invalid batch contents"); + if (Buffer.byteLength(JSON.stringify(batch)) > 1024 * 1024) throw new Error("module batch too large"); + const seen = new Set(); + for (const attr of batch.attributes) { + if (!attr || Object.keys(attr).some(k => !["session", "key", "value"].includes(k)) || typeof attr.session !== "string" || typeof attr.key !== "string" || !KEY.test(attr.key) || !Object.hasOwn(attr, "value")) throw new Error("invalid module attribute"); + if (graph.nodes.filter(node => sessionIdOf(node) === attr.session).length !== 1) throw new Error("unknown or ambiguous session"); + const identity = `${attr.session}\0${attr.key}`; + if (seen.has(identity)) throw new Error("duplicate module attribute"); + seen.add(identity); + } + for (const ev of batch.events) { + if (!ev || Object.keys(ev).some(k => !["type", "session", "data"].includes(k)) || typeof ev.type !== "string" || !ev.type.startsWith(`${name}.`) || !KEY.test(ev.type.slice(name.length + 1)) || typeof ev.session !== "string" || graph.nodes.filter(node => sessionIdOf(node) === ev.session).length !== 1 || !Object.hasOwn(ev, "data")) throw new Error("invalid namespaced event"); + } + const digest = createHash("sha256").update(JSON.stringify(batch)).digest("hex"); + const previous = (graph.moduleStates || []).find(item => item.name === name); + if (previous?.batchId === batch.id) { + if (previous.digest !== digest) throw new Error("batch id reused with different contents"); + return { duplicate: true, digest }; + } + if ((previous?.cursor ?? null) !== batch.cursor) throw new Error("module cursor conflict"); + return { duplicate: false, digest }; +} + +export function applyModuleBatch(state, event, sessionIdOf) { + if (!state.moduleStates) state.moduleStates = new Map(); + for (const attr of event.batch.attributes) { + const node = [...state.nodes.values()].find(item => sessionIdOf(item) === attr.session); + if (!node) throw new Error("module batch names unknown session"); + const modules = { ...(node.moduleAttributes || {}) }; + modules[event.module] = { ...(Object.hasOwn(modules, event.module) ? modules[event.module] : {}), [attr.key]: attr.value }; + state.nodes.set(node.id, { ...node, moduleAttributes: modules }); + } + state.moduleStates.set(event.module, { name: event.module, cursor: event.batch.nextCursor, batchId: event.batch.id, digest: event.digest }); +} diff --git a/skills/agent-tmux/bin/plexus-modules.mjs b/skills/agent-tmux/bin/plexus-modules.mjs index 7f0f9262..52b9a477 100644 --- a/skills/agent-tmux/bin/plexus-modules.mjs +++ b/skills/agent-tmux/bin/plexus-modules.mjs @@ -24,9 +24,12 @@ export async function readModuleRegistry(path) { }); } -export async function describeModule(entry) { +export async function invokeModule(entry, operation, request) { + if (!["describe", "process"].includes(operation)) throw new Error("invalid module operation"); + const input = JSON.stringify(request); + if (Buffer.byteLength(input) > MAX_BYTES) throw new Error("module request too large"); const result = await new Promise((resolve, reject) => { - const child = spawn(entry.command[0], [...entry.command.slice(1), "describe"], { stdio: ["pipe", "pipe", "ignore"], shell: false }); + const child = spawn(entry.command[0], [...entry.command.slice(1), operation], { stdio: ["pipe", "pipe", "ignore"], shell: false }); let output = [], bytes = 0, finished = false; const finish = (error, value) => { if (finished) return; finished = true; clearTimeout(timer); error ? reject(error) : resolve(value); }; const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new Error("module timed out")); }, entry.timeoutMs); @@ -42,8 +45,14 @@ export async function describeModule(entry) { try { finish(null, JSON.parse(Buffer.concat(output).toString("utf8"))); } catch { finish(new Error("invalid module response")); } }); - child.stdin.end("{}\n"); + child.stdin.end(`${input}\n`); }); + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name) throw new Error("invalid module response"); + return result; +} + +export async function describeModule(entry) { + const result = await invokeModule(entry, "describe", {}); if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || result.namespace !== entry.name || !Array.isArray(result.operations) || !result.operations.includes("describe") || result.operations.some(op => typeof op !== "string")) throw new Error("invalid module description"); return result; } diff --git a/skills/agent-tmux/bin/plexus.mjs b/skills/agent-tmux/bin/plexus.mjs index 87b8ce7c..79f5d6e4 100644 --- a/skills/agent-tmux/bin/plexus.mjs +++ b/skills/agent-tmux/bin/plexus.mjs @@ -7,6 +7,7 @@ import { createHmac, randomUUID } from "node:crypto"; import { posix } from "node:path"; import { createHash } from "node:crypto"; +import { applyModuleBatch } from "./module-batches.mjs"; import { LEDGER_VIEW_SCHEMA, LEDGER_VIEW_SORT, buildLedgerViewRows, ledgerViewProfileRevision, ledgerViewValue, validateLedgerViewProfile @@ -92,7 +93,11 @@ export function applyPlexusEvent(state, item) { case "session.handover": parseGraphSessionId(item.session); if (typeof item.evidence !== "string" || !item.evidence || item.evidence.length > 512 || /[\r\n\x00]/.test(item.evidence)) throw new Error("lifecycle event requires an evidence reference"); - effects.push({ kind: item.type, session: item.session }); + if (item.type === "session.handover") { + parseGraphSessionId(item.to); + if (item.to === item.session) throw new Error("handover target must differ"); + } else if (item.to !== undefined) throw new Error("unexpected lifecycle target"); + effects.push({ kind: item.type, session: item.session, ...(item.to ? { to: item.to } : {}) }); break; case "role.changed": if (!state.roleClaims) state.roleClaims = new Map(); @@ -787,6 +792,7 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { nodes: new Map((snapshotGraph?.nodes || []).map((node) => [node.id, node])), links: new Map((snapshotGraph?.links || []).map((link) => [link.id, link])), edges: new Map((snapshotGraph?.edges || []).map((edge) => [edge.id, edge])), + moduleStates: new Map((snapshotGraph?.moduleStates || []).map(item => [item.name, item])), renewals: [...(snapshotGraph?.renewals || [])], migrated: snapshotGraph?.migrated === true, }; const seen = new Set([...state.nodes.values()].map(sessionIdOf).filter(Boolean)); @@ -818,6 +824,10 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { } function applyReplay(state, item, emitted) { + if (item.type === "module.batch") { + if (!emitted) applyModuleBatch(state, item, sessionIdOf); + return; + } if (item.type === "node.upserted") { state.nodes.set(item.node.id, item.node); return; @@ -836,6 +846,10 @@ function applyReplay(state, item, emitted) { function feedFor(state, seen, item) { const out = []; + if (item.type === "module.batch") { + applyModuleBatch(state, item, sessionIdOf); + return item.batch.events.map((entry, index) => ({ type: entry.type, session: entry.session, data: entry.data, subject: `${item.id}:${index}` })); + } if (item.type === "node.upserted") { const id = sessionIdOf(item.node); const previous = state.nodes.get(item.node.id); @@ -897,7 +911,7 @@ function feedFor(state, seen, item) { } else if (effect.kind === "session.renewed") { out.push({ type: "session.renewed", from: effect.from, to: effect.to, subject: effect.to }); } else if (LIFECYCLE_EVENTS.has(effect.kind)) { - out.push({ type: effect.kind, session: effect.session, subject: effect.session }); + out.push({ type: effect.kind, session: effect.session, ...(effect.to ? { to: effect.to } : {}), subject: effect.session }); } } return out; From 12b76619760f09db21e9e4f72151e5801d39ce6a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:05:46 +0000 Subject: [PATCH 004/113] Update module description failure assertion --- packages/tmux-bridge/test/plexus-modules.test.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/tmux-bridge/test/plexus-modules.test.mjs b/packages/tmux-bridge/test/plexus-modules.test.mjs index 3e88acd8..39c92507 100644 --- a/packages/tmux-bridge/test/plexus-modules.test.mjs +++ b/packages/tmux-bridge/test/plexus-modules.test.mjs @@ -41,6 +41,6 @@ test("describe verifies identity and enforces timeouts", async () => { const good = "process.stdout.write(JSON.stringify({schema:'agent-mesh.plexus-module.v1',name:'example',namespace:'example',operations:['describe']}))"; const entry = { name: "example", command: [process.execPath, "-e", good], timeoutMs: 1000 }; assert.equal((await describeModule(entry)).namespace, "example"); - await assert.rejects(describeModule({ ...entry, name: "other" }), /description/); + await assert.rejects(describeModule({ ...entry, name: "other" }), /invalid module response/); await assert.rejects(describeModule({ ...entry, command: [process.execPath, "-e", "setTimeout(()=>{}, 10000)"], timeoutMs: 20 }), /timed out/); }); From 8a13fe1da211b12821b340fbffc6470a92298dd1 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:12:28 +0000 Subject: [PATCH 005/113] Support multiple namespaces per Plexus module --- docs/design/plexus-modules.md | 11 ++++++----- packages/tmux-bridge/bin/mesh-graph.mjs | 11 ++++++----- packages/tmux-bridge/bin/module-batches.mjs | 9 +++++---- packages/tmux-bridge/bin/plexus-modules.mjs | 10 +++++++--- .../tmux-bridge/examples/plexus-example-module.mjs | 2 +- .../tmux-bridge/test/plexus-module-batch.test.mjs | 6 ++++-- packages/tmux-bridge/test/plexus-modules.test.mjs | 8 +++++--- skills/agent-tmux/bin/mesh-graph.mjs | 11 ++++++----- skills/agent-tmux/bin/module-batches.mjs | 9 +++++---- skills/agent-tmux/bin/plexus-modules.mjs | 10 +++++++--- 10 files changed, 52 insertions(+), 35 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index 841306ee..e1e92c2e 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -42,7 +42,7 @@ The example module and all fixtures use synthetic data only. 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 namespace and +`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. @@ -50,7 +50,8 @@ The initial read-only discovery surface is `mesh-graph module list` and `mesh-graph module describe --name `. It reads the operator-owned `$XDG_CONFIG_HOME/agent-mesh/modules.json` (or `--config `). The registry has `schemaVersion: 1` and a `modules` array containing `name`, `command` as an -argument array, and optional `timeoutMs`. Namespace equals name. A missing file +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. @@ -60,14 +61,14 @@ 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 key; they are projected under that module's -name on its node. Events identify a session, a namespaced type, and JSON data. +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 namespace. Both paths check the cursor and +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 diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 59a9f6f3..3645b3fe 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -175,7 +175,7 @@ try { const graph = { nodes: [{ id: "synthetic-node", agent: "codex", runtimeUuid: "22222222-2222-4222-8222-222222222222" }], moduleStates: [] }; const result = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph, cursor: null, events: [] }); if (Object.keys(result).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); - validateModuleBatch(entry.name, { id: result.batchId, cursor: null, nextCursor: "synthetic-cursor", attributes: result.attributes, events: result.events }, graph, plexus.sessionIdOf); + validateModuleBatch(entry.name, entry.namespaces, { id: result.batchId, cursor: null, nextCursor: "synthetic-cursor", attributes: result.attributes, events: result.events }, graph, plexus.sessionIdOf); printResult({ module: entry.name, conformance: "pass", scope: "synthetic protocol response only" }, { json: true }); } else if (subcommand === "run") { const entry = entries.find(item => item.name === values.name); @@ -192,7 +192,7 @@ try { if (feed.reset) throw new Error("module cursor expired; reconciliation required"); return { graph, cursor, feed }; }); - const events = snapshot.feed.events.filter(item => !item.type.startsWith(`${entry.name}.`)); + const events = snapshot.feed.events.filter(item => !entry.namespaces.some(namespace => item.type.startsWith(`${namespace}.`))); const output = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph: snapshot.graph, cursor: snapshot.cursor, events }); if (Object.keys(output).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); if (snapshot.cursor !== null && events.length === 0 && Array.isArray(output.attributes) && output.attributes.length === 0 && Array.isArray(output.events) && output.events.length === 0) { @@ -201,19 +201,20 @@ try { } const batch = { id: output.batchId, cursor: snapshot.cursor, nextCursor: snapshot.feed.cursor, attributes: output.attributes, events: output.events }; const result = mutate(stateDir, graph => { - const checked = validateModuleBatch(entry.name, batch, graph, plexus.sessionIdOf); + const checked = validateModuleBatch(entry.name, entry.namespaces, batch, graph, plexus.sessionIdOf); if (checked.duplicate) return { graph, result: { module: entry.name, batchId: batch.id, duplicate: true } }; return { graph, event: event("module.batch", { module: entry.name, batch, digest: checked.digest }), result: { module: entry.name, batchId: batch.id, duplicate: false } }; }); printResult(result, { json: true }); } else if (subcommand === "apply") { - if (!entries.some(item => item.name === values.name)) throw new Error("module is not registered"); + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); const raw = values.input === "-" ? readFileSync(0, "utf8") : values.input; if (typeof raw !== "string" || Buffer.byteLength(raw) > 1024 * 1024) throw new Error("invalid module input"); const batch = JSON.parse(raw); const result = mutate(stateDir, graph => { if (!graph.migrated || graph.unnumbered) throw new Error("module batches require a migrated graph"); - const checked = validateModuleBatch(values.name, batch, graph, plexus.sessionIdOf); + const checked = validateModuleBatch(entry.name, entry.namespaces, batch, graph, plexus.sessionIdOf); if (checked.duplicate) return { graph, result: { module: values.name, batchId: batch.id, duplicate: true } }; return { graph, event: event("module.batch", { module: values.name, batch, digest: checked.digest }), result: { module: values.name, batchId: batch.id, duplicate: false } }; }); diff --git a/packages/tmux-bridge/bin/module-batches.mjs b/packages/tmux-bridge/bin/module-batches.mjs index e6f2685f..6c0e0c50 100644 --- a/packages/tmux-bridge/bin/module-batches.mjs +++ b/packages/tmux-bridge/bin/module-batches.mjs @@ -4,7 +4,7 @@ const NAME = /^[a-z][a-z0-9-]{0,63}$/; const KEY = /^[a-z][a-z0-9_-]{0,63}$/; // A batch is one event, so graph changes and its checkpoint commit together. -export function validateModuleBatch(name, batch, graph, sessionIdOf) { +export function validateModuleBatch(name, namespaces, batch, graph, sessionIdOf) { if (typeof name !== "string" || !NAME.test(name)) throw new Error("invalid module name"); if (!batch || typeof batch !== "object" || Array.isArray(batch) || Object.keys(batch).some(k => !["id", "cursor", "nextCursor", "attributes", "events"].includes(k))) throw new Error("invalid module batch"); if (typeof batch.id !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(batch.id)) throw new Error("invalid batch id"); @@ -14,14 +14,14 @@ export function validateModuleBatch(name, batch, graph, sessionIdOf) { if (Buffer.byteLength(JSON.stringify(batch)) > 1024 * 1024) throw new Error("module batch too large"); const seen = new Set(); for (const attr of batch.attributes) { - if (!attr || Object.keys(attr).some(k => !["session", "key", "value"].includes(k)) || typeof attr.session !== "string" || typeof attr.key !== "string" || !KEY.test(attr.key) || !Object.hasOwn(attr, "value")) throw new Error("invalid module attribute"); + if (!attr || Object.keys(attr).some(k => !["session", "key", "value"].includes(k)) || typeof attr.session !== "string" || typeof attr.key !== "string" || attr.key.split(".").length !== 2 || !namespaces.includes(attr.key.split(".")[0]) || !KEY.test(attr.key.split(".")[1]) || !Object.hasOwn(attr, "value")) throw new Error("invalid namespaced module attribute"); if (graph.nodes.filter(node => sessionIdOf(node) === attr.session).length !== 1) throw new Error("unknown or ambiguous session"); const identity = `${attr.session}\0${attr.key}`; if (seen.has(identity)) throw new Error("duplicate module attribute"); seen.add(identity); } for (const ev of batch.events) { - if (!ev || Object.keys(ev).some(k => !["type", "session", "data"].includes(k)) || typeof ev.type !== "string" || !ev.type.startsWith(`${name}.`) || !KEY.test(ev.type.slice(name.length + 1)) || typeof ev.session !== "string" || graph.nodes.filter(node => sessionIdOf(node) === ev.session).length !== 1 || !Object.hasOwn(ev, "data")) throw new Error("invalid namespaced event"); + if (!ev || Object.keys(ev).some(k => !["type", "session", "data"].includes(k)) || typeof ev.type !== "string" || ev.type.split(".").length !== 2 || !namespaces.includes(ev.type.split(".")[0]) || !KEY.test(ev.type.split(".")[1]) || typeof ev.session !== "string" || graph.nodes.filter(node => sessionIdOf(node) === ev.session).length !== 1 || !Object.hasOwn(ev, "data")) throw new Error("invalid namespaced event"); } const digest = createHash("sha256").update(JSON.stringify(batch)).digest("hex"); const previous = (graph.moduleStates || []).find(item => item.name === name); @@ -39,7 +39,8 @@ export function applyModuleBatch(state, event, sessionIdOf) { const node = [...state.nodes.values()].find(item => sessionIdOf(item) === attr.session); if (!node) throw new Error("module batch names unknown session"); const modules = { ...(node.moduleAttributes || {}) }; - modules[event.module] = { ...(Object.hasOwn(modules, event.module) ? modules[event.module] : {}), [attr.key]: attr.value }; + const [namespace, key] = attr.key.split("."); + modules[namespace] = { ...(Object.hasOwn(modules, namespace) ? modules[namespace] : {}), [key]: attr.value }; state.nodes.set(node.id, { ...node, moduleAttributes: modules }); } state.moduleStates.set(event.module, { name: event.module, cursor: event.batch.nextCursor, batchId: event.batch.id, digest: event.digest }); diff --git a/packages/tmux-bridge/bin/plexus-modules.mjs b/packages/tmux-bridge/bin/plexus-modules.mjs index 52b9a477..eaa917e0 100644 --- a/packages/tmux-bridge/bin/plexus-modules.mjs +++ b/packages/tmux-bridge/bin/plexus-modules.mjs @@ -13,14 +13,17 @@ export async function readModuleRegistry(path) { if (Buffer.byteLength(text) > MAX_BYTES) throw new Error("module registry is too large"); const config = JSON.parse(text); if (!config || config.schemaVersion !== 1 || !Array.isArray(config.modules)) throw new Error("invalid module registry"); - const names = new Set(); + const names = new Set(), namespaces = new Set(); return config.modules.map((entry) => { if (!entry || typeof entry.name !== "string" || !NAME.test(entry.name) || names.has(entry.name)) throw new Error("invalid or duplicate module name"); + const owned = entry.namespaces ?? [entry.name]; + if (!Array.isArray(owned) || !owned.length || owned.length > 32 || owned.some(ns => typeof ns !== "string" || !NAME.test(ns) || namespaces.has(ns)) || new Set(owned).size !== owned.length) throw new Error("invalid or duplicate module namespace"); if (!Array.isArray(entry.command) || !entry.command.length || entry.command.some(v => typeof v !== "string" || !v || v.includes("\0"))) throw new Error("invalid module command"); const timeoutMs = entry.timeoutMs ?? 10000; if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) throw new Error("invalid module timeout"); names.add(entry.name); - return { name: entry.name, command: [...entry.command], timeoutMs }; + for (const namespace of owned) namespaces.add(namespace); + return { name: entry.name, namespaces: [...owned], command: [...entry.command], timeoutMs }; }); } @@ -53,6 +56,7 @@ export async function invokeModule(entry, operation, request) { export async function describeModule(entry) { const result = await invokeModule(entry, "describe", {}); - if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || result.namespace !== entry.name || !Array.isArray(result.operations) || !result.operations.includes("describe") || result.operations.some(op => typeof op !== "string")) throw new Error("invalid module description"); + const owned = entry.namespaces ?? [entry.name]; + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || !Array.isArray(result.namespaces) || result.namespaces.length !== owned.length || owned.some(ns => !result.namespaces.includes(ns)) || new Set(result.namespaces).size !== owned.length || !Array.isArray(result.operations) || !result.operations.includes("describe") || result.operations.some(op => typeof op !== "string")) throw new Error("invalid module description"); return result; } diff --git a/packages/tmux-bridge/examples/plexus-example-module.mjs b/packages/tmux-bridge/examples/plexus-example-module.mjs index 8952dee4..76de23df 100644 --- a/packages/tmux-bridge/examples/plexus-example-module.mjs +++ b/packages/tmux-bridge/examples/plexus-example-module.mjs @@ -14,7 +14,7 @@ if (process.argv[2] === "process") { process.stdout.write(JSON.stringify({ schema: "agent-mesh.plexus-module.v1", name: "example", - namespace: "example", + namespaces: ["example"], operations: ["describe", "process"], }) + "\n"); } diff --git a/packages/tmux-bridge/test/plexus-module-batch.test.mjs b/packages/tmux-bridge/test/plexus-module-batch.test.mjs index 2525971a..a77f94a7 100644 --- a/packages/tmux-bridge/test/plexus-module-batch.test.mjs +++ b/packages/tmux-bridge/test/plexus-module-batch.test.mjs @@ -16,12 +16,12 @@ test("module batches atomically update their own state and survive replay and co const dir = await mkdtemp(join(tmpdir(), "plexus-batch-")); t.after(() => rm(dir, { recursive: true, force: true })); const state = join(dir, "state"), config = join(dir, "modules.json"); - await writeFile(config, JSON.stringify({ schemaVersion: 1, modules: [{ name: "example", command: ["example"] }, { name: "other", command: ["example"] }] })); + await writeFile(config, JSON.stringify({ schemaVersion: 1, modules: [{ name: "example", namespaces: ["example", "sleep", "cost"], command: ["example"] }, { name: "other", command: ["example"] }] })); const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, "--state", state, ...args])).stdout); await call("add", "--agent", "codex", "--tmux-target", "test", "--cwd", "/synthetic", "--runtime-uuid", uuid, "--json"); await call("migrate", "--apply", "--json"); const start = await call("query", "changes", "--input", JSON.stringify({ initial: "head" })); - const batch = { id: "a1", cursor: null, nextCursor: "one", attributes: [{ session, key: "count", value: 1 }], events: [{ type: "example.changed", session, data: { count: 1 } }] }; + const batch = { id: "a1", cursor: null, nextCursor: "one", attributes: [{ session, key: "example.count", value: 1 }, { session, key: "sleep.count", value: 2 }, { session, key: "cost.count", value: 3 }], events: [{ type: "example.changed", session, data: { count: 1 } }] }; const apply = (name, input) => call("module", "apply", "--config", config, "--name", name, "--input", JSON.stringify(input)); assert.equal((await apply("example", batch)).duplicate, false); assert.equal((await apply("example", batch)).duplicate, true); @@ -33,6 +33,8 @@ test("module batches atomically update their own state and survive replay and co await rm(join(state, "checkpoint.json")); let projection = await call("show", "--json"); assert.equal(projection.nodes[0].moduleAttributes.example.count, 1); + assert.equal(projection.nodes[0].moduleAttributes.sleep.count, 2); + assert.equal(projection.nodes[0].moduleAttributes.cost.count, 3); assert.equal(projection.moduleStates[0].cursor, "one"); await call("compact", "--all-history", "--apply", "--json"); await rm(join(state, "checkpoint.json"), { force: true }); diff --git a/packages/tmux-bridge/test/plexus-modules.test.mjs b/packages/tmux-bridge/test/plexus-modules.test.mjs index 39c92507..11ac9aa4 100644 --- a/packages/tmux-bridge/test/plexus-modules.test.mjs +++ b/packages/tmux-bridge/test/plexus-modules.test.mjs @@ -16,6 +16,8 @@ test("registry is private configuration and duplicate names fail closed", async const entry = { name: "example", command: [process.execPath, "fixture.mjs"] }; await writeFile(file, JSON.stringify({ schemaVersion: 1, modules: [entry, entry] })); await assert.rejects(readModuleRegistry(file), /duplicate/); + await writeFile(file, JSON.stringify({ schemaVersion: 1, modules: [{ ...entry, namespaces: ["shared"] }, { ...entry, name: "other", namespaces: ["shared"] }] })); + await assert.rejects(readModuleRegistry(file), /namespace/); await writeFile(file, "{"); await assert.rejects(readModuleRegistry(file)); } finally { await rm(dir, { recursive: true, force: true }); } @@ -32,15 +34,15 @@ test("graph discovers and describes only registered modules", async () => { const list = await exec(process.execPath, [graph, "module", "list", "--config", config]); assert.deepEqual(JSON.parse(list.stdout), { modules: [{ name: "example" }] }); const describe = await exec(process.execPath, [graph, "module", "describe", "--config", config, "--name", "example"]); - assert.equal(JSON.parse(describe.stdout).namespace, "example"); + assert.deepEqual(JSON.parse(describe.stdout).namespaces, ["example"]); await assert.rejects(exec(process.execPath, [graph, "module", "describe", "--config", config, "--name", "unknown"])); } finally { await rm(dir, { recursive: true, force: true }); } }); test("describe verifies identity and enforces timeouts", async () => { - const good = "process.stdout.write(JSON.stringify({schema:'agent-mesh.plexus-module.v1',name:'example',namespace:'example',operations:['describe']}))"; + const good = "process.stdout.write(JSON.stringify({schema:'agent-mesh.plexus-module.v1',name:'example',namespaces:['example'],operations:['describe']}))"; const entry = { name: "example", command: [process.execPath, "-e", good], timeoutMs: 1000 }; - assert.equal((await describeModule(entry)).namespace, "example"); + assert.deepEqual((await describeModule(entry)).namespaces, ["example"]); await assert.rejects(describeModule({ ...entry, name: "other" }), /invalid module response/); await assert.rejects(describeModule({ ...entry, command: [process.execPath, "-e", "setTimeout(()=>{}, 10000)"], timeoutMs: 20 }), /timed out/); }); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 59a9f6f3..3645b3fe 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -175,7 +175,7 @@ try { const graph = { nodes: [{ id: "synthetic-node", agent: "codex", runtimeUuid: "22222222-2222-4222-8222-222222222222" }], moduleStates: [] }; const result = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph, cursor: null, events: [] }); if (Object.keys(result).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); - validateModuleBatch(entry.name, { id: result.batchId, cursor: null, nextCursor: "synthetic-cursor", attributes: result.attributes, events: result.events }, graph, plexus.sessionIdOf); + validateModuleBatch(entry.name, entry.namespaces, { id: result.batchId, cursor: null, nextCursor: "synthetic-cursor", attributes: result.attributes, events: result.events }, graph, plexus.sessionIdOf); printResult({ module: entry.name, conformance: "pass", scope: "synthetic protocol response only" }, { json: true }); } else if (subcommand === "run") { const entry = entries.find(item => item.name === values.name); @@ -192,7 +192,7 @@ try { if (feed.reset) throw new Error("module cursor expired; reconciliation required"); return { graph, cursor, feed }; }); - const events = snapshot.feed.events.filter(item => !item.type.startsWith(`${entry.name}.`)); + const events = snapshot.feed.events.filter(item => !entry.namespaces.some(namespace => item.type.startsWith(`${namespace}.`))); const output = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph: snapshot.graph, cursor: snapshot.cursor, events }); if (Object.keys(output).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); if (snapshot.cursor !== null && events.length === 0 && Array.isArray(output.attributes) && output.attributes.length === 0 && Array.isArray(output.events) && output.events.length === 0) { @@ -201,19 +201,20 @@ try { } const batch = { id: output.batchId, cursor: snapshot.cursor, nextCursor: snapshot.feed.cursor, attributes: output.attributes, events: output.events }; const result = mutate(stateDir, graph => { - const checked = validateModuleBatch(entry.name, batch, graph, plexus.sessionIdOf); + const checked = validateModuleBatch(entry.name, entry.namespaces, batch, graph, plexus.sessionIdOf); if (checked.duplicate) return { graph, result: { module: entry.name, batchId: batch.id, duplicate: true } }; return { graph, event: event("module.batch", { module: entry.name, batch, digest: checked.digest }), result: { module: entry.name, batchId: batch.id, duplicate: false } }; }); printResult(result, { json: true }); } else if (subcommand === "apply") { - if (!entries.some(item => item.name === values.name)) throw new Error("module is not registered"); + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); const raw = values.input === "-" ? readFileSync(0, "utf8") : values.input; if (typeof raw !== "string" || Buffer.byteLength(raw) > 1024 * 1024) throw new Error("invalid module input"); const batch = JSON.parse(raw); const result = mutate(stateDir, graph => { if (!graph.migrated || graph.unnumbered) throw new Error("module batches require a migrated graph"); - const checked = validateModuleBatch(values.name, batch, graph, plexus.sessionIdOf); + const checked = validateModuleBatch(entry.name, entry.namespaces, batch, graph, plexus.sessionIdOf); if (checked.duplicate) return { graph, result: { module: values.name, batchId: batch.id, duplicate: true } }; return { graph, event: event("module.batch", { module: values.name, batch, digest: checked.digest }), result: { module: values.name, batchId: batch.id, duplicate: false } }; }); diff --git a/skills/agent-tmux/bin/module-batches.mjs b/skills/agent-tmux/bin/module-batches.mjs index e6f2685f..6c0e0c50 100644 --- a/skills/agent-tmux/bin/module-batches.mjs +++ b/skills/agent-tmux/bin/module-batches.mjs @@ -4,7 +4,7 @@ const NAME = /^[a-z][a-z0-9-]{0,63}$/; const KEY = /^[a-z][a-z0-9_-]{0,63}$/; // A batch is one event, so graph changes and its checkpoint commit together. -export function validateModuleBatch(name, batch, graph, sessionIdOf) { +export function validateModuleBatch(name, namespaces, batch, graph, sessionIdOf) { if (typeof name !== "string" || !NAME.test(name)) throw new Error("invalid module name"); if (!batch || typeof batch !== "object" || Array.isArray(batch) || Object.keys(batch).some(k => !["id", "cursor", "nextCursor", "attributes", "events"].includes(k))) throw new Error("invalid module batch"); if (typeof batch.id !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(batch.id)) throw new Error("invalid batch id"); @@ -14,14 +14,14 @@ export function validateModuleBatch(name, batch, graph, sessionIdOf) { if (Buffer.byteLength(JSON.stringify(batch)) > 1024 * 1024) throw new Error("module batch too large"); const seen = new Set(); for (const attr of batch.attributes) { - if (!attr || Object.keys(attr).some(k => !["session", "key", "value"].includes(k)) || typeof attr.session !== "string" || typeof attr.key !== "string" || !KEY.test(attr.key) || !Object.hasOwn(attr, "value")) throw new Error("invalid module attribute"); + if (!attr || Object.keys(attr).some(k => !["session", "key", "value"].includes(k)) || typeof attr.session !== "string" || typeof attr.key !== "string" || attr.key.split(".").length !== 2 || !namespaces.includes(attr.key.split(".")[0]) || !KEY.test(attr.key.split(".")[1]) || !Object.hasOwn(attr, "value")) throw new Error("invalid namespaced module attribute"); if (graph.nodes.filter(node => sessionIdOf(node) === attr.session).length !== 1) throw new Error("unknown or ambiguous session"); const identity = `${attr.session}\0${attr.key}`; if (seen.has(identity)) throw new Error("duplicate module attribute"); seen.add(identity); } for (const ev of batch.events) { - if (!ev || Object.keys(ev).some(k => !["type", "session", "data"].includes(k)) || typeof ev.type !== "string" || !ev.type.startsWith(`${name}.`) || !KEY.test(ev.type.slice(name.length + 1)) || typeof ev.session !== "string" || graph.nodes.filter(node => sessionIdOf(node) === ev.session).length !== 1 || !Object.hasOwn(ev, "data")) throw new Error("invalid namespaced event"); + if (!ev || Object.keys(ev).some(k => !["type", "session", "data"].includes(k)) || typeof ev.type !== "string" || ev.type.split(".").length !== 2 || !namespaces.includes(ev.type.split(".")[0]) || !KEY.test(ev.type.split(".")[1]) || typeof ev.session !== "string" || graph.nodes.filter(node => sessionIdOf(node) === ev.session).length !== 1 || !Object.hasOwn(ev, "data")) throw new Error("invalid namespaced event"); } const digest = createHash("sha256").update(JSON.stringify(batch)).digest("hex"); const previous = (graph.moduleStates || []).find(item => item.name === name); @@ -39,7 +39,8 @@ export function applyModuleBatch(state, event, sessionIdOf) { const node = [...state.nodes.values()].find(item => sessionIdOf(item) === attr.session); if (!node) throw new Error("module batch names unknown session"); const modules = { ...(node.moduleAttributes || {}) }; - modules[event.module] = { ...(Object.hasOwn(modules, event.module) ? modules[event.module] : {}), [attr.key]: attr.value }; + const [namespace, key] = attr.key.split("."); + modules[namespace] = { ...(Object.hasOwn(modules, namespace) ? modules[namespace] : {}), [key]: attr.value }; state.nodes.set(node.id, { ...node, moduleAttributes: modules }); } state.moduleStates.set(event.module, { name: event.module, cursor: event.batch.nextCursor, batchId: event.batch.id, digest: event.digest }); diff --git a/skills/agent-tmux/bin/plexus-modules.mjs b/skills/agent-tmux/bin/plexus-modules.mjs index 52b9a477..eaa917e0 100644 --- a/skills/agent-tmux/bin/plexus-modules.mjs +++ b/skills/agent-tmux/bin/plexus-modules.mjs @@ -13,14 +13,17 @@ export async function readModuleRegistry(path) { if (Buffer.byteLength(text) > MAX_BYTES) throw new Error("module registry is too large"); const config = JSON.parse(text); if (!config || config.schemaVersion !== 1 || !Array.isArray(config.modules)) throw new Error("invalid module registry"); - const names = new Set(); + const names = new Set(), namespaces = new Set(); return config.modules.map((entry) => { if (!entry || typeof entry.name !== "string" || !NAME.test(entry.name) || names.has(entry.name)) throw new Error("invalid or duplicate module name"); + const owned = entry.namespaces ?? [entry.name]; + if (!Array.isArray(owned) || !owned.length || owned.length > 32 || owned.some(ns => typeof ns !== "string" || !NAME.test(ns) || namespaces.has(ns)) || new Set(owned).size !== owned.length) throw new Error("invalid or duplicate module namespace"); if (!Array.isArray(entry.command) || !entry.command.length || entry.command.some(v => typeof v !== "string" || !v || v.includes("\0"))) throw new Error("invalid module command"); const timeoutMs = entry.timeoutMs ?? 10000; if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) throw new Error("invalid module timeout"); names.add(entry.name); - return { name: entry.name, command: [...entry.command], timeoutMs }; + for (const namespace of owned) namespaces.add(namespace); + return { name: entry.name, namespaces: [...owned], command: [...entry.command], timeoutMs }; }); } @@ -53,6 +56,7 @@ export async function invokeModule(entry, operation, request) { export async function describeModule(entry) { const result = await invokeModule(entry, "describe", {}); - if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || result.namespace !== entry.name || !Array.isArray(result.operations) || !result.operations.includes("describe") || result.operations.some(op => typeof op !== "string")) throw new Error("invalid module description"); + const owned = entry.namespaces ?? [entry.name]; + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || !Array.isArray(result.namespaces) || result.namespaces.length !== owned.length || owned.some(ns => !result.namespaces.includes(ns)) || new Set(result.namespaces).size !== owned.length || !Array.isArray(result.operations) || !result.operations.includes("describe") || result.operations.some(op => typeof op !== "string")) throw new Error("invalid module description"); return result; } From 23bbb0d649de13452dbee43afdef9e41d03cdb88 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:15:36 +0000 Subject: [PATCH 006/113] Support bounded larger module graph requests --- docs/design/plexus-modules.md | 3 +++ packages/tmux-bridge/bin/plexus-modules.mjs | 5 ++++- packages/tmux-bridge/test/plexus-modules.test.mjs | 10 +++++++++- skills/agent-tmux/bin/plexus-modules.mjs | 5 ++++- 4 files changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index e1e92c2e..e924df83 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -54,6 +54,9 @@ 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 ` captures the graph and a page from the module's cursor under the graph lock, then invokes `process` outside the lock. The host diff --git a/packages/tmux-bridge/bin/plexus-modules.mjs b/packages/tmux-bridge/bin/plexus-modules.mjs index eaa917e0..389d5be1 100644 --- a/packages/tmux-bridge/bin/plexus-modules.mjs +++ b/packages/tmux-bridge/bin/plexus-modules.mjs @@ -4,6 +4,9 @@ import { spawn } from "node:child_process"; export const MODULE_PROTOCOL = "agent-mesh.plexus-module.v1"; const NAME = /^[a-z][a-z0-9-]{0,63}$/; const MAX_BYTES = 1024 * 1024; +// Graph snapshots can be substantially larger than module responses. This is a +// hard bound, not permission to truncate a graph silently. +const MAX_REQUEST_BYTES = 32 * 1024 * 1024; // This is an operator allowlist, not a sandbox for untrusted programs. export async function readModuleRegistry(path) { @@ -30,7 +33,7 @@ export async function readModuleRegistry(path) { export async function invokeModule(entry, operation, request) { if (!["describe", "process"].includes(operation)) throw new Error("invalid module operation"); const input = JSON.stringify(request); - if (Buffer.byteLength(input) > MAX_BYTES) throw new Error("module request too large"); + if (Buffer.byteLength(input) > MAX_REQUEST_BYTES) throw new Error("module request too large"); const result = await new Promise((resolve, reject) => { const child = spawn(entry.command[0], [...entry.command.slice(1), operation], { stdio: ["pipe", "pipe", "ignore"], shell: false }); let output = [], bytes = 0, finished = false; diff --git a/packages/tmux-bridge/test/plexus-modules.test.mjs b/packages/tmux-bridge/test/plexus-modules.test.mjs index 11ac9aa4..c6812dda 100644 --- a/packages/tmux-bridge/test/plexus-modules.test.mjs +++ b/packages/tmux-bridge/test/plexus-modules.test.mjs @@ -6,7 +6,7 @@ import test from "node:test"; import { execFile } from "node:child_process"; import { promisify } from "node:util"; import { fileURLToPath } from "node:url"; -import { readModuleRegistry, describeModule } from "../bin/plexus-modules.mjs"; +import { readModuleRegistry, describeModule, invokeModule } from "../bin/plexus-modules.mjs"; test("registry is private configuration and duplicate names fail closed", async () => { const dir = await mkdtemp(join(tmpdir(), "plexus-modules-")); @@ -46,3 +46,11 @@ test("describe verifies identity and enforces timeouts", async () => { await assert.rejects(describeModule({ ...entry, name: "other" }), /invalid module response/); await assert.rejects(describeModule({ ...entry, command: [process.execPath, "-e", "setTimeout(()=>{}, 10000)"], timeoutMs: 20 }), /timed out/); }); + +test("large graph requests are bounded independently from module responses", async () => { + const fixture = fileURLToPath(new URL("../examples/plexus-example-module.mjs", import.meta.url)); + const entry = { name: "example", command: [process.execPath, fixture], timeoutMs: 5000 }; + const response = await invokeModule(entry, "process", { cursor: null, graph: { synthetic: "x".repeat(2 * 1024 * 1024) } }); + assert.deepEqual(response.attributes, []); + await assert.rejects(invokeModule(entry, "process", { graph: "x".repeat(33 * 1024 * 1024) }), /too large/); +}); diff --git a/skills/agent-tmux/bin/plexus-modules.mjs b/skills/agent-tmux/bin/plexus-modules.mjs index eaa917e0..389d5be1 100644 --- a/skills/agent-tmux/bin/plexus-modules.mjs +++ b/skills/agent-tmux/bin/plexus-modules.mjs @@ -4,6 +4,9 @@ import { spawn } from "node:child_process"; export const MODULE_PROTOCOL = "agent-mesh.plexus-module.v1"; const NAME = /^[a-z][a-z0-9-]{0,63}$/; const MAX_BYTES = 1024 * 1024; +// Graph snapshots can be substantially larger than module responses. This is a +// hard bound, not permission to truncate a graph silently. +const MAX_REQUEST_BYTES = 32 * 1024 * 1024; // This is an operator allowlist, not a sandbox for untrusted programs. export async function readModuleRegistry(path) { @@ -30,7 +33,7 @@ export async function readModuleRegistry(path) { export async function invokeModule(entry, operation, request) { if (!["describe", "process"].includes(operation)) throw new Error("invalid module operation"); const input = JSON.stringify(request); - if (Buffer.byteLength(input) > MAX_BYTES) throw new Error("module request too large"); + if (Buffer.byteLength(input) > MAX_REQUEST_BYTES) throw new Error("module request too large"); const result = await new Promise((resolve, reject) => { const child = spawn(entry.command[0], [...entry.command.slice(1), operation], { stdio: ["pipe", "pipe", "ignore"], shell: false }); let output = [], bytes = 0, finished = false; From cee31a8ed575f1dea81b8bbc0b6cf47d652bae7a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:22:44 +0000 Subject: [PATCH 007/113] Mark module conformance input as synthetic --- docs/design/plexus-modules.md | 3 ++- packages/tmux-bridge/bin/mesh-graph.mjs | 2 +- skills/agent-tmux/bin/mesh-graph.mjs | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index e924df83..ed487207 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -76,5 +76,6 @@ 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; it is not a sandbox or a proof of side-effect +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. diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 3645b3fe..22ce149b 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -173,7 +173,7 @@ try { const desc = await describeModule(entry); if (!desc.operations.includes("process")) throw new Error("module does not support process"); const graph = { nodes: [{ id: "synthetic-node", agent: "codex", runtimeUuid: "22222222-2222-4222-8222-222222222222" }], moduleStates: [] }; - const result = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph, cursor: null, events: [] }); + const result = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", mode: "conformance", graph, cursor: null, events: [] }); if (Object.keys(result).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); validateModuleBatch(entry.name, entry.namespaces, { id: result.batchId, cursor: null, nextCursor: "synthetic-cursor", attributes: result.attributes, events: result.events }, graph, plexus.sessionIdOf); printResult({ module: entry.name, conformance: "pass", scope: "synthetic protocol response only" }, { json: true }); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 3645b3fe..22ce149b 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -173,7 +173,7 @@ try { const desc = await describeModule(entry); if (!desc.operations.includes("process")) throw new Error("module does not support process"); const graph = { nodes: [{ id: "synthetic-node", agent: "codex", runtimeUuid: "22222222-2222-4222-8222-222222222222" }], moduleStates: [] }; - const result = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph, cursor: null, events: [] }); + const result = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", mode: "conformance", graph, cursor: null, events: [] }); if (Object.keys(result).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); validateModuleBatch(entry.name, entry.namespaces, { id: result.batchId, cursor: null, nextCursor: "synthetic-cursor", attributes: result.attributes, events: result.events }, graph, plexus.sessionIdOf); printResult({ module: entry.name, conformance: "pass", scope: "synthetic protocol response only" }, { json: true }); From d3eae1c6a054af3a20a0214158293c11c8a75759 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:35:20 +0000 Subject: [PATCH 008/113] Reject stale module snapshots without blocking graph writers --- docs/design/plexus-modules.md | 11 +++++----- packages/tmux-bridge/bin/mesh-graph.mjs | 22 ++++++++++--------- .../test/plexus-module-batch.test.mjs | 18 +++++++++++++++ skills/agent-tmux/bin/mesh-graph.mjs | 22 ++++++++++--------- 4 files changed, 48 insertions(+), 25 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index ed487207..d80ea04f 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -58,11 +58,12 @@ 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 ` captures the graph and a page from the module's -cursor under the graph lock, then invokes `process` outside the lock. The host -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 +`module run --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. diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 22ce149b..8ef7f4c6 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -182,16 +182,17 @@ try { if (!entry) throw new Error("module is not registered"); const description = await describeModule(entry); if (!description.operations.includes("process")) throw new Error("module does not support process"); - ensureStateDir(stateDir); - const snapshot = withLock(stateDir, () => { - const graph = loadGraph(stateDir); - if (!graph.migrated || graph.unnumbered) throw new Error("module runs require a migrated graph"); - const cursor = graph.moduleStates?.find(item => item.name === entry.name)?.cursor ?? null; - const query = cursor === null ? { initial: "head" } : { sinceCursor: cursor }; - const feed = runQuery(stateDir, "changes", { input: JSON.stringify(query) }); - if (feed.reset) throw new Error("module cursor expired; reconciliation required"); - return { graph, cursor, feed }; - }); + // Feed replay can be large. Never hold the shared writer lock while + // scanning it; reject if the graph moved during observation instead. + const graph = loadGraph(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("module runs require a migrated graph"); + const cursor = graph.moduleStates?.find(item => item.name === entry.name)?.cursor ?? null; + const query = cursor === null ? { initial: "head" } : { sinceCursor: cursor }; + const feed = runQuery(stateDir, "changes", { input: JSON.stringify(query) }); + if (feed.reset) throw new Error("module cursor expired; reconciliation required"); + const observed = loadGraph(stateDir); + if (observed.lastSeq !== graph.lastSeq || plexus.decodeCursor(feed.cursor, "changes").seq > graph.lastSeq) throw new Error("graph changed during module observation"); + const snapshot = { graph, cursor, feed }; const events = snapshot.feed.events.filter(item => !entry.namespaces.some(namespace => item.type.startsWith(`${namespace}.`))); const output = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph: snapshot.graph, cursor: snapshot.cursor, events }); if (Object.keys(output).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); @@ -201,6 +202,7 @@ try { } const batch = { id: output.batchId, cursor: snapshot.cursor, nextCursor: snapshot.feed.cursor, attributes: output.attributes, events: output.events }; const result = mutate(stateDir, graph => { + if (graph.lastSeq !== snapshot.graph.lastSeq) throw new Error("graph changed during module processing"); const checked = validateModuleBatch(entry.name, entry.namespaces, batch, graph, plexus.sessionIdOf); if (checked.duplicate) return { graph, result: { module: entry.name, batchId: batch.id, duplicate: true } }; return { graph, event: event("module.batch", { module: entry.name, batch, digest: checked.digest }), result: { module: entry.name, batchId: batch.id, duplicate: false } }; diff --git a/packages/tmux-bridge/test/plexus-module-batch.test.mjs b/packages/tmux-bridge/test/plexus-module-batch.test.mjs index a77f94a7..4c5c7e9f 100644 --- a/packages/tmux-bridge/test/plexus-module-batch.test.mjs +++ b/packages/tmux-bridge/test/plexus-module-batch.test.mjs @@ -85,3 +85,21 @@ test("lifecycle observations are idempotent across replay and compaction", async await rm(join(state, "checkpoint.json"), { force: true }); assert.equal((await call(...args)).duplicate, true); }); + +test("a concurrent graph change rejects a stale module result without advancing its cursor", async (t) => { + const dir = await mkdtemp(join(tmpdir(), "plexus-race-")); + t.after(() => rm(dir, { recursive: true, force: true })); + const state = join(dir, "state"), config = join(dir, "modules.json"), fixture = join(dir, "fixture.mjs"); + const script = `import { spawnSync } from 'node:child_process'; +if (process.argv[2] === 'describe') console.log(JSON.stringify({schema:'agent-mesh.plexus-module.v1',name:'example',namespaces:['example'],operations:['describe','process']})); +else { const p=spawnSync(process.execPath,[${JSON.stringify(graph)},'--state',${JSON.stringify(state)},'add','--agent','codex','--tmux-target','concurrent','--cwd','/synthetic','--runtime-uuid','33333333-3333-4333-8333-333333333333','--json']); if(p.status!==0) process.exit(1); console.log(JSON.stringify({schema:'agent-mesh.plexus-module.v1',name:'example',batchId:'race',attributes:[],events:[]})); }`; + await writeFile(fixture, script); + await writeFile(config, JSON.stringify({ schemaVersion: 1, modules: [{ name: "example", command: [process.execPath, fixture] }] })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, "--state", state, ...args])).stdout); + await call("add", "--agent", "codex", "--tmux-target", "test", "--cwd", "/synthetic", "--runtime-uuid", uuid, "--json"); + await call("migrate", "--apply", "--json"); + await assert.rejects(call("module", "run", "--config", config, "--name", "example"), /graph changed during module processing/); + const after = await call("show", "--json"); + assert.equal(after.nodes.length, 2); + assert.deepEqual(after.moduleStates, []); +}); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 22ce149b..8ef7f4c6 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -182,16 +182,17 @@ try { if (!entry) throw new Error("module is not registered"); const description = await describeModule(entry); if (!description.operations.includes("process")) throw new Error("module does not support process"); - ensureStateDir(stateDir); - const snapshot = withLock(stateDir, () => { - const graph = loadGraph(stateDir); - if (!graph.migrated || graph.unnumbered) throw new Error("module runs require a migrated graph"); - const cursor = graph.moduleStates?.find(item => item.name === entry.name)?.cursor ?? null; - const query = cursor === null ? { initial: "head" } : { sinceCursor: cursor }; - const feed = runQuery(stateDir, "changes", { input: JSON.stringify(query) }); - if (feed.reset) throw new Error("module cursor expired; reconciliation required"); - return { graph, cursor, feed }; - }); + // Feed replay can be large. Never hold the shared writer lock while + // scanning it; reject if the graph moved during observation instead. + const graph = loadGraph(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("module runs require a migrated graph"); + const cursor = graph.moduleStates?.find(item => item.name === entry.name)?.cursor ?? null; + const query = cursor === null ? { initial: "head" } : { sinceCursor: cursor }; + const feed = runQuery(stateDir, "changes", { input: JSON.stringify(query) }); + if (feed.reset) throw new Error("module cursor expired; reconciliation required"); + const observed = loadGraph(stateDir); + if (observed.lastSeq !== graph.lastSeq || plexus.decodeCursor(feed.cursor, "changes").seq > graph.lastSeq) throw new Error("graph changed during module observation"); + const snapshot = { graph, cursor, feed }; const events = snapshot.feed.events.filter(item => !entry.namespaces.some(namespace => item.type.startsWith(`${namespace}.`))); const output = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph: snapshot.graph, cursor: snapshot.cursor, events }); if (Object.keys(output).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); @@ -201,6 +202,7 @@ try { } const batch = { id: output.batchId, cursor: snapshot.cursor, nextCursor: snapshot.feed.cursor, attributes: output.attributes, events: output.events }; const result = mutate(stateDir, graph => { + if (graph.lastSeq !== snapshot.graph.lastSeq) throw new Error("graph changed during module processing"); const checked = validateModuleBatch(entry.name, entry.namespaces, batch, graph, plexus.sessionIdOf); if (checked.duplicate) return { graph, result: { module: entry.name, batchId: batch.id, duplicate: true } }; return { graph, event: event("module.batch", { module: entry.name, batch, digest: checked.digest }), result: { module: entry.name, batchId: batch.id, duplicate: false } }; From 0c1633e5149beb227c25eb07f48f001ee968f0e4 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:43:54 +0000 Subject: [PATCH 009/113] Expose lifecycle evidence to trusted local modules --- docs/design/plexus-modules.md | 4 ++++ packages/tmux-bridge/bin/plexus.mjs | 8 ++++---- .../tmux-bridge/test/plexus-lifecycle.test.mjs | 2 +- packages/tmux-bridge/test/plexus.test.mjs | 14 ++++++++++++++ skills/agent-tmux/bin/plexus.mjs | 8 ++++---- 5 files changed, 27 insertions(+), 9 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index d80ea04f..4c839b37 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -22,6 +22,10 @@ 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 diff --git a/packages/tmux-bridge/bin/plexus.mjs b/packages/tmux-bridge/bin/plexus.mjs index 79f5d6e4..828fe09b 100644 --- a/packages/tmux-bridge/bin/plexus.mjs +++ b/packages/tmux-bridge/bin/plexus.mjs @@ -97,7 +97,7 @@ export function applyPlexusEvent(state, item) { parseGraphSessionId(item.to); if (item.to === item.session) throw new Error("handover target must differ"); } else if (item.to !== undefined) throw new Error("unexpected lifecycle target"); - effects.push({ kind: item.type, session: item.session, ...(item.to ? { to: item.to } : {}) }); + effects.push({ kind: item.type, session: item.session, evidence: item.evidence, ...(item.to ? { to: item.to } : {}) }); break; case "role.changed": if (!state.roleClaims) state.roleClaims = new Map(); @@ -806,7 +806,7 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { continue; } if (output.length >= limit) break; - const emitted = feedFor(state, seen, item); + const emitted = feedFor(state, seen, item, scope); applyReplay(state, item, emitted); scanned = item.seq; if (!emitted.length) continue; @@ -844,7 +844,7 @@ function applyReplay(state, item, emitted) { if (PLEXUS_EVENTS.has(item.type) && !emitted) applyPlexusEvent(state, item); } -function feedFor(state, seen, item) { +function feedFor(state, seen, item, scope) { const out = []; if (item.type === "module.batch") { applyModuleBatch(state, item, sessionIdOf); @@ -911,7 +911,7 @@ function feedFor(state, seen, item) { } else if (effect.kind === "session.renewed") { out.push({ type: "session.renewed", from: effect.from, to: effect.to, subject: effect.to }); } else if (LIFECYCLE_EVENTS.has(effect.kind)) { - out.push({ type: effect.kind, session: effect.session, ...(effect.to ? { to: effect.to } : {}), subject: effect.session }); + out.push({ type: effect.kind, session: effect.session, ...(scope === null ? { evidence: effect.evidence } : {}), ...(effect.to ? { to: effect.to } : {}), subject: effect.session }); } } return out; diff --git a/packages/tmux-bridge/test/plexus-lifecycle.test.mjs b/packages/tmux-bridge/test/plexus-lifecycle.test.mjs index b19faf7b..f99f1c95 100644 --- a/packages/tmux-bridge/test/plexus-lifecycle.test.mjs +++ b/packages/tmux-bridge/test/plexus-lifecycle.test.mjs @@ -10,7 +10,7 @@ test("lifecycle evidence is replayable without mutating session ownership", () = const graph = state(); assert.ok(PLEXUS_EVENTS.has(type)); const extra = type === "session.handover" ? { to: "claude:33333333-3333-4333-8333-333333333333" } : {}; - assert.deepEqual(applyPlexusEvent(graph, { type, session, evidence: "source:example", ...extra }), [{ kind: type, session, ...extra }]); + assert.deepEqual(applyPlexusEvent(graph, { type, session, evidence: "source:example", ...extra }), [{ kind: type, session, evidence: "source:example", ...extra }]); assert.equal(graph.nodes.size, 0); assert.equal(graph.links.size, 0); } diff --git a/packages/tmux-bridge/test/plexus.test.mjs b/packages/tmux-bridge/test/plexus.test.mjs index 68b2fa4d..27560c58 100644 --- a/packages/tmux-bridge/test/plexus.test.mjs +++ b/packages/tmux-bridge/test/plexus.test.mjs @@ -47,6 +47,20 @@ const scopeA = { handleKey: "space-a-handle-key-0123456789", }; +test("lifecycle feed exposes evidence locally but not to scoped consumers", async (t) => { + const state = await mkdtemp(join(tmpdir(), "plexus-life-scope-")); + t.after(() => rm(state, { recursive: true, force: true })); + await seed(state); + await ok(state, ["migrate", "--apply"]); + const start = (await query(state, "changes", { initial: "head" })).cursor; + await ok(state, ["lifecycle", "record", "--session", `codex:${CODEX}`, "--type", "session.idle", "--id", "scope-example", "--evidence", "private:example"]); + const local = await query(state, "changes", { sinceCursor: start }); + const scoped = await query(state, "changes", { sinceCursor: start, scope: scopeA }); + assert.equal(local.events[0].evidence, "private:example"); + assert.equal(scoped.events[0].type, "session.idle"); + assert.ok(!("evidence" in scoped.events[0])); +}); + test("cloud registration has exact account-qualified identity and survives graph replay", async (t) => { const state = await mkdtemp(join(tmpdir(), "plexus-cloud-")); t.after(() => rm(state, { recursive: true, force: true })); diff --git a/skills/agent-tmux/bin/plexus.mjs b/skills/agent-tmux/bin/plexus.mjs index 79f5d6e4..828fe09b 100644 --- a/skills/agent-tmux/bin/plexus.mjs +++ b/skills/agent-tmux/bin/plexus.mjs @@ -97,7 +97,7 @@ export function applyPlexusEvent(state, item) { parseGraphSessionId(item.to); if (item.to === item.session) throw new Error("handover target must differ"); } else if (item.to !== undefined) throw new Error("unexpected lifecycle target"); - effects.push({ kind: item.type, session: item.session, ...(item.to ? { to: item.to } : {}) }); + effects.push({ kind: item.type, session: item.session, evidence: item.evidence, ...(item.to ? { to: item.to } : {}) }); break; case "role.changed": if (!state.roleClaims) state.roleClaims = new Map(); @@ -806,7 +806,7 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { continue; } if (output.length >= limit) break; - const emitted = feedFor(state, seen, item); + const emitted = feedFor(state, seen, item, scope); applyReplay(state, item, emitted); scanned = item.seq; if (!emitted.length) continue; @@ -844,7 +844,7 @@ function applyReplay(state, item, emitted) { if (PLEXUS_EVENTS.has(item.type) && !emitted) applyPlexusEvent(state, item); } -function feedFor(state, seen, item) { +function feedFor(state, seen, item, scope) { const out = []; if (item.type === "module.batch") { applyModuleBatch(state, item, sessionIdOf); @@ -911,7 +911,7 @@ function feedFor(state, seen, item) { } else if (effect.kind === "session.renewed") { out.push({ type: "session.renewed", from: effect.from, to: effect.to, subject: effect.to }); } else if (LIFECYCLE_EVENTS.has(effect.kind)) { - out.push({ type: effect.kind, session: effect.session, ...(effect.to ? { to: effect.to } : {}), subject: effect.session }); + out.push({ type: effect.kind, session: effect.session, ...(scope === null ? { evidence: effect.evidence } : {}), ...(effect.to ? { to: effect.to } : {}), subject: effect.session }); } } return out; From 69679ed992831425e13d29334454735559dcac4d Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:43:36 +0000 Subject: [PATCH 010/113] Guard Plexus mechanism files against private policy --- docs/design/plexus.md | 2 +- packages/tmux-bridge/README.md | 2 +- packages/tmux-bridge/test/mesh-graph.test.mjs | 6 +++--- packages/tmux-bridge/test/plexus-privacy.test.mjs | 9 +++++++++ scripts/mesh-readiness.mjs | 2 ++ scripts/plexus-privacy.mjs | 14 ++++++++++++++ 6 files changed, 30 insertions(+), 5 deletions(-) create mode 100644 packages/tmux-bridge/test/plexus-privacy.test.mjs create mode 100644 scripts/plexus-privacy.mjs diff --git a/docs/design/plexus.md b/docs/design/plexus.md index 8a3984b8..199f010d 100644 --- a/docs/design/plexus.md +++ b/docs/design/plexus.md @@ -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 diff --git a/packages/tmux-bridge/README.md b/packages/tmux-bridge/README.md index 6b50f303..f6c9655c 100644 --- a/packages/tmux-bridge/README.md +++ b/packages/tmux-bridge/README.md @@ -182,7 +182,7 @@ node $BIN/mesh-graph.mjs show --json The graph command atomically writes only `/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. diff --git a/packages/tmux-bridge/test/mesh-graph.test.mjs b/packages/tmux-bridge/test/mesh-graph.test.mjs index 491e0e75..93e478f3 100644 --- a/packages/tmux-bridge/test/mesh-graph.test.mjs +++ b/packages/tmux-bridge/test/mesh-graph.test.mjs @@ -28,13 +28,13 @@ test("mesh-graph derives an inspectable graph from append-only events", async () const first = await run(state, [ "add", "--agent", "codex", "--tmux-target", "mesh-codex-main", "--cwd", "/workspace/mesh", "--role-profile", "developer", "--title", "Graph work", "--summary", "initial implementation", - "--refs", "management:MGT-0239,amf:record-id", "--json", + "--refs", "ledger:item-1,amf:record-id", "--json", ]); assert.equal(first.code, 0, first.stderr); const firstNode = JSON.parse(first.stdout).node; assert.match(firstNode.id, /^node-[0-9a-f-]{36}$/); assert.equal(firstNode.runtimeUuid, null); - assert.deepEqual(firstNode.refs, ["management:MGT-0239", "amf:record-id"]); + assert.deepEqual(firstNode.refs, ["ledger:item-1", "amf:record-id"]); const reconciled = await run(state, [ "add", "--tmux-target", "mesh-codex-main", "--runtime-uuid", "11111111-1111-4111-8111-111111111111", "--json", @@ -67,7 +67,7 @@ test("mesh-graph derives an inspectable graph from append-only events", async () assert.equal(graph.nodes.length, 2); assert.equal(graph.edges.length, 1); assert.equal(graph.nodes.find((node) => node.id === firstNode.id).runtimeUuid, "11111111-1111-4111-8111-111111111111"); - assert.deepEqual(graph.nodes.find((node) => node.id === firstNode.id).refs, ["management:MGT-0239", "amf:record-id"]); + assert.deepEqual(graph.nodes.find((node) => node.id === firstNode.id).refs, ["ledger:item-1", "amf:record-id"]); assert.equal(graph.nodes.find((node) => node.id === secondNode.id).status, "closed"); const projection = JSON.parse(await readFile(join(state, "graph.json"), "utf8")); diff --git a/packages/tmux-bridge/test/plexus-privacy.test.mjs b/packages/tmux-bridge/test/plexus-privacy.test.mjs new file mode 100644 index 00000000..adfc1507 --- /dev/null +++ b/packages/tmux-bridge/test/plexus-privacy.test.mjs @@ -0,0 +1,9 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { containsPrivatePlexusPolicy, isPlexusMechanismFile } from '../../../scripts/plexus-privacy.mjs'; + +test('Plexus public mechanism paths and private references are classified', () => { + for (const path of ['docs/design/plexus.md', 'docs/design/plexus-modules.md', 'packages/tmux-bridge/README.md', 'packages/tmux-bridge/bin/plexus.mjs', 'packages/tmux-bridge/bin/mesh-graph.mjs', 'packages/tmux-bridge/bin/plexus-modules.mjs', 'packages/tmux-bridge/examples/plexus-example-module.mjs', 'packages/tmux-bridge/test/plexus-privacy.test.mjs', 'skills/agent-tmux/bin/agent-waker.py']) assert.equal(isPlexusMechanismFile(path), true, path); + for (const value of ['gale' + 'haut', 'management:' + 'MGT-123', '/home/' + 'administrator/private']) assert.equal(containsPrivatePlexusPolicy(value), true); + assert.equal(containsPrivatePlexusPolicy('A configurable policy uses a synthetic session.'), false); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index 654f1d9e..ae6c51e8 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -3,6 +3,7 @@ import { readFileSync, readdirSync, statSync } from "node:fs"; import path from "node:path"; import { fileURLToPath } from "node:url"; import { parseMeshV1Envelope, planMeshV1Dispatch } from "../packages/core/src/policy.js"; +import { containsPrivatePlexusPolicy, isPlexusMechanismFile } from "./plexus-privacy.mjs"; const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); const checks = []; @@ -70,6 +71,7 @@ check("turn gate fails closed", () => { const plan = planMeshV1Dispatch({ localP check("seen loop guard fails closed", () => { const plan = planMeshV1Dispatch({ localParticipant: "alpha" }, { text: "cc-mesh: alpha\ncc-mesh-from: beta\ncc-mesh-id: ready-6\ncc-mesh-turn: alpha\ncc-mesh-final: true\ncc-mesh-seen: beta,alpha\n\nhello" }); assert(plan.reason === "mesh_v1_loop_guard_seen", `expected loop guard got ${plan.reason}`); }); check("privacy snowflake rule ignores repeated placeholders", () => { assert(!snowflakeIdPattern.test("111111111111111111"), "repeated-digit placeholder must not be flagged"); assert(!snowflakeIdPattern.test("222222222222222222"), "repeated-digit placeholder must not be flagged"); assert(snowflakeIdPattern.test("123456789" + "012345678"), "mixed-digit snowflake-shaped ID must be flagged"); }); check("public-tree privacy sanity", () => { const deny = [snowflakeIdPattern, new RegExp("/home/operator/env/workspace/iter" + "modus/"), /(api[_-]?key|secret|password|token)\s*[:=]\s*["'][^"']{6,}["']/i]; const privateIdentifiers = ["ti" + "rrenia", "od" + "ino", "iter" + "modus"]; const skipDirs = new Set([".git", "node_modules", "dist"]); const skipPaths = new Set([".syncwheel/ledger"]); const hits = []; function walk(dir) { if (skipPaths.has(path.relative(root, dir))) return; for (const entry of readdirSync(dir)) { if (skipDirs.has(entry)) continue; const full = path.join(dir, entry); const stat = statSync(full); if (stat.isDirectory()) walk(full); else if (stat.isFile()) { const text = readFileSync(full, "utf8"); for (const pattern of deny) if (pattern.test(text)) hits.push(path.relative(root, full)); if (privateIdentifiers.some((identifier) => text.toLowerCase().includes(identifier))) hits.push(path.relative(root, full)); } } } walk(root); assert(hits.length === 0, `privacy scan hits: ${[...new Set(hits)].join(", ")}`); }); +check("Plexus mechanism privacy", () => { const hits = []; const skip = new Set([".git", "node_modules", "dist", "var"]); function walk(dir) { for (const entry of readdirSync(dir)) { if (skip.has(entry)) continue; const full = path.join(dir, entry), stat = statSync(full); if (stat.isDirectory()) walk(full); else if (stat.isFile()) { const relative = path.relative(root, full); if (isPlexusMechanismFile(relative) && containsPrivatePlexusPolicy(readFileSync(full, "utf8"))) hits.push(relative); } } } walk(root); assert(hits.length === 0, `Plexus privacy scan hits: ${hits.join(", ")}`); }); check("agent-tmux skill bundle sync", () => { const drifted = agentTmuxBundleFiles.filter((relativePath) => { try { return !readFileSync(path.join(root, "packages/tmux-bridge", relativePath)).equals(readFileSync(path.join(root, "skills/agent-tmux", relativePath))); } catch { return true; } }); assert(drifted.length === 0, `agent-tmux skill bundle drift: ${drifted.join(", ")}`); }); for (const result of checks) console.log(`${result.ok ? "PASS" : "FAIL"} ${result.name}${result.ok ? "" : `: ${result.error}`}`); if (checks.some((result) => !result.ok)) process.exit(1); diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs new file mode 100644 index 00000000..6d15c7cb --- /dev/null +++ b/scripts/plexus-privacy.mjs @@ -0,0 +1,14 @@ +// Public mechanism files must not embed private deployment policy or identifiers. +const privatePatterns = [ + new RegExp('gale' + 'haut', 'i'), + new RegExp('management:' + 'MGT-[0-9]+', 'i'), + new RegExp('/home/' + 'administrator(?:/|\\b)', 'i'), +]; + +export function isPlexusMechanismFile(relativePath) { + return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|module-batches|mesh-(?:graph|channel)|agent-waker|session-(?:sleep|handover)|(?:sleep|handover)-))/.test(relativePath); +} + +export function containsPrivatePlexusPolicy(text) { + return privatePatterns.some((pattern) => pattern.test(text)); +} From 250a93249545dea830c97d87554f3124b7325bcf Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:28:21 +0000 Subject: [PATCH 011/113] Model channel handover and pending delivery transitions --- docs/design/plexus-channels.md | 12 +++++ packages/tmux-bridge/bin/channel-state.mjs | 54 +++++++++++++++++++ .../tmux-bridge/test/channel-state.test.mjs | 22 ++++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-privacy.mjs | 2 +- skills/agent-tmux/bin/channel-state.mjs | 54 +++++++++++++++++++ 6 files changed, 144 insertions(+), 1 deletion(-) create mode 100644 docs/design/plexus-channels.md create mode 100644 packages/tmux-bridge/bin/channel-state.mjs create mode 100644 packages/tmux-bridge/test/channel-state.test.mjs create mode 100644 skills/agent-tmux/bin/channel-state.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md new file mode 100644 index 00000000..af27aad2 --- /dev/null +++ b/docs/design/plexus-channels.md @@ -0,0 +1,12 @@ +# Channel transition prototype + +`channel-state.mjs` defines pure JSON transitions for a stable channel, its +current session and a queue. An in-flight message is bound to a session and +generation. A handover stops new dispatch and cannot finish while a delivery is +unresolved. Only a matching acceptance receipt resolves an in-flight message. + +This is not yet a channel service: it has no durable transactional store, +concurrent-writer arbitration, transport, authorization, waker integration, +recovery procedure or session verification. The caller must not treat the +`verified` argument as evidence by itself. It must establish all of these +properties before connecting the transitions to live sessions. diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs new file mode 100644 index 00000000..9e6de7e7 --- /dev/null +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -0,0 +1,54 @@ +/** Pure channel transitions. A host must persist each transition atomically. */ +const identifier = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); +const copy = (state) => structuredClone(state); + +export function createChannel(id, session) { + if (!identifier(id) || !identifier(session)) throw new Error('invalid channel or session'); + return { schema: 'agent-mesh.channel.v1', id, session, generation: 1, phase: 'active', queue: [] }; +} + +export function enqueue(state, id, payload) { + if (!identifier(id) || typeof payload !== 'string' || !payload || Buffer.byteLength(payload) > 65536) throw new Error('invalid message'); + const prior = state.queue.find((item) => item.id === id); + if (prior) { + if (prior.payload !== payload) throw new Error('message id conflict'); + return copy(state); + } + const next = copy(state); + next.queue.push({ id, payload, state: 'pending' }); + return next; +} + +export function beginDelivery(state, id) { + if (state.phase !== 'active') throw new Error('handover in progress'); + const next = copy(state), item = next.queue.find((row) => row.id === id); + if (!item || item.state !== 'pending') throw new Error('message not pending'); + item.state = 'inflight'; + item.session = state.session; + item.generation = state.generation; + return next; +} + +export function acknowledge(state, id, receipt) { + const next = copy(state), item = next.queue.find((row) => row.id === id); + if (!item || item.state !== 'inflight' || !receipt || receipt.status !== 'accepted' || receipt.messageId !== id || receipt.session !== item.session || receipt.generation !== item.generation) throw new Error('unverified delivery receipt'); + item.state = 'accepted'; + return next; +} + +export function beginHandover(state) { + if (state.phase !== 'active') throw new Error('handover already in progress'); + const next = copy(state); + next.phase = 'handover'; + return next; +} + +export function finishHandover(state, session, verified) { + if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); + if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + const next = copy(state); + next.session = session; + next.generation += 1; + next.phase = 'active'; + return next; +} diff --git a/packages/tmux-bridge/test/channel-state.test.mjs b/packages/tmux-bridge/test/channel-state.test.mjs new file mode 100644 index 00000000..141cbf62 --- /dev/null +++ b/packages/tmux-bridge/test/channel-state.test.mjs @@ -0,0 +1,22 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, finishHandover } from '../bin/channel-state.mjs'; + +test('handover queues work and never reroutes an uncertain delivery', () => { + let channel = createChannel('example', 'session:one'); + channel = enqueue(channel, 'message-1', 'hello'); + channel = beginDelivery(channel, 'message-1'); + channel = beginHandover(channel); + channel = enqueue(channel, 'message-2', 'queued'); + assert.throws(() => beginDelivery(channel, 'message-2'), /handover/); + assert.throws(() => finishHandover(channel, 'session:two', true), /inflight/); + assert.throws(() => acknowledge(channel, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'session:two', generation: 1 }), /receipt/); + channel = acknowledge(channel, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'session:one', generation: 1 }); + assert.throws(() => finishHandover(channel, 'session:two', false), /successor/); + channel = finishHandover(channel, 'session:two', true); + channel = beginDelivery(channel, 'message-2'); + assert.equal(channel.queue[1].session, 'session:two'); + assert.equal(channel.queue[1].generation, 2); + assert.deepEqual(enqueue(channel, 'message-2', 'queued'), channel); + assert.throws(() => enqueue(channel, 'message-2', 'different'), /conflict/); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index ae6c51e8..b8d4fabf 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -38,6 +38,7 @@ const agentTmuxBundleFiles = [ "bin/mesh-capacity-dispatch.mjs", "bin/mesh-graph.mjs", "bin/plexus.mjs", + "bin/channel-state.mjs", "bin/ledger-view.mjs", "bin/session-catalog.mjs", "bin/session-links.mjs", diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs index 6d15c7cb..68675fbc 100644 --- a/scripts/plexus-privacy.mjs +++ b/scripts/plexus-privacy.mjs @@ -6,7 +6,7 @@ const privatePatterns = [ ]; export function isPlexusMechanismFile(relativePath) { - return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|module-batches|mesh-(?:graph|channel)|agent-waker|session-(?:sleep|handover)|(?:sleep|handover)-))/.test(relativePath); + return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|module-batches|mesh-(?:graph|channel)|agent-waker|session-(?:sleep|handover)|(?:sleep|handover)-))/.test(relativePath); } export function containsPrivatePlexusPolicy(text) { diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs new file mode 100644 index 00000000..9e6de7e7 --- /dev/null +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -0,0 +1,54 @@ +/** Pure channel transitions. A host must persist each transition atomically. */ +const identifier = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); +const copy = (state) => structuredClone(state); + +export function createChannel(id, session) { + if (!identifier(id) || !identifier(session)) throw new Error('invalid channel or session'); + return { schema: 'agent-mesh.channel.v1', id, session, generation: 1, phase: 'active', queue: [] }; +} + +export function enqueue(state, id, payload) { + if (!identifier(id) || typeof payload !== 'string' || !payload || Buffer.byteLength(payload) > 65536) throw new Error('invalid message'); + const prior = state.queue.find((item) => item.id === id); + if (prior) { + if (prior.payload !== payload) throw new Error('message id conflict'); + return copy(state); + } + const next = copy(state); + next.queue.push({ id, payload, state: 'pending' }); + return next; +} + +export function beginDelivery(state, id) { + if (state.phase !== 'active') throw new Error('handover in progress'); + const next = copy(state), item = next.queue.find((row) => row.id === id); + if (!item || item.state !== 'pending') throw new Error('message not pending'); + item.state = 'inflight'; + item.session = state.session; + item.generation = state.generation; + return next; +} + +export function acknowledge(state, id, receipt) { + const next = copy(state), item = next.queue.find((row) => row.id === id); + if (!item || item.state !== 'inflight' || !receipt || receipt.status !== 'accepted' || receipt.messageId !== id || receipt.session !== item.session || receipt.generation !== item.generation) throw new Error('unverified delivery receipt'); + item.state = 'accepted'; + return next; +} + +export function beginHandover(state) { + if (state.phase !== 'active') throw new Error('handover already in progress'); + const next = copy(state); + next.phase = 'handover'; + return next; +} + +export function finishHandover(state, session, verified) { + if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); + if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + const next = copy(state); + next.session = session; + next.generation += 1; + next.phase = 'active'; + return next; +} From 0d5870582362ff2de18afab2ed3aa9b5efad8ca7 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:32:03 +0000 Subject: [PATCH 012/113] Persist channel queue transitions in graph journal --- docs/design/plexus-channels.md | 11 ++++-- packages/tmux-bridge/bin/mesh-graph.mjs | 37 +++++++++++++++++-- packages/tmux-bridge/bin/plexus.mjs | 7 +++- .../test/plexus-channel-store.test.mjs | 32 ++++++++++++++++ skills/agent-tmux/bin/mesh-graph.mjs | 37 +++++++++++++++++-- skills/agent-tmux/bin/plexus.mjs | 7 +++- 6 files changed, 120 insertions(+), 11 deletions(-) create mode 100644 packages/tmux-bridge/test/plexus-channel-store.test.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index af27aad2..66d315e4 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -5,8 +5,13 @@ current session and a queue. An in-flight message is bound to a session and generation. A handover stops new dispatch and cannot finish while a delivery is unresolved. Only a matching acceptance receipt resolves an in-flight message. -This is not yet a channel service: it has no durable transactional store, -concurrent-writer arbitration, transport, authorization, waker integration, -recovery procedure or session verification. The caller must not treat the +The graph command now persists channel creation, enqueue and handover start as +events under the graph writer lock. Queued messages survive replay and +compaction. The graph and event log contain message bodies and must remain +private; this is not a scoped remote API. + +This is not yet a complete channel service: delivery and handover completion +are not exposed by the graph command. It has no transport, authorization, +waker integration, recovery procedure or session verification. The caller must not treat the `verified` argument as evidence by itself. It must establish all of these properties before connecting the transitions to live sessions. diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 8ef7f4c6..520df394 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -36,6 +36,7 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; +import { createChannel, enqueue, beginHandover } from "./channel-state.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -122,7 +123,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -134,6 +135,35 @@ const stateDir = resolve(values.state || GRAPH_DIR); try { switch (command) { + case "channel": { + const name = requiredSingleLine(values.name, "--name"); + if (subcommand === "get") { + const channel = (loadGraph(stateDir).channels || []).find((item) => item.id === name); + if (!channel) throw new Error("unknown channel"); + printResult({ channel }, { json: true }); + break; + } + const result = mutate(stateDir, graph => { + if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); + const current = (graph.channels || []).find((item) => item.id === name); + let next; + if (subcommand === "create") { + if (current) throw new Error("channel already exists"); + const session = requiredSingleLine(values.session, "--session"); + if (graph.nodes.filter(node => plexus.sessionIdOf(node) === session).length !== 1) throw new Error("unknown or ambiguous session"); + next = createChannel(name, session); + } else { + if (!current) throw new Error("unknown channel"); + if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), values.input); + else if (subcommand === "begin-handover") next = beginHandover(current); + else throw new Error("unknown channel operation"); + } + if (current && JSON.stringify(current) === JSON.stringify(next)) return { graph, result: { channel: next, duplicate: true } }; + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } case "lifecycle": { if (subcommand !== "record") throw new Error("unknown lifecycle operation"); if (!plexus.LIFECYCLE_EVENTS.has(values.type)) throw new Error("invalid lifecycle type"); @@ -1201,7 +1231,7 @@ function readCheckpoint(statePath) { if (checkpoint.schema !== GRAPH_SCHEMA || checkpoint.graph?.schema !== GRAPH_SCHEMA || !Array.isArray(checkpoint.graph.nodes) || !Array.isArray(checkpoint.graph.edges) || // Older binaries rewrite the checkpoint without Plexus state; replaying from the file is the only safe answer. - !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Array.isArray(checkpoint.graph.moduleStates) || !Array.isArray(checkpoint.graph.lifecycleReceipts) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || + !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Array.isArray(checkpoint.graph.moduleStates) || !Array.isArray(checkpoint.graph.lifecycleReceipts) || !Array.isArray(checkpoint.graph.channels) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || !cursor || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || !Number.isSafeInteger(cursor.dev) || !Number.isSafeInteger(cursor.ino)) { return null; @@ -1290,7 +1320,7 @@ function* readEventRecords(statePath, offset = 0) { function deriveGraph(events, base = null) { const nodes = new Map((base?.nodes || []).map((node) => [node.id, node])); const edges = new Map((base?.edges || []).map((edge) => [edge.id, edge])); - const state = { nodes, moduleStates: new Map((base?.moduleStates || []).map(item => [item.name, item])), lifecycleReceipts: new Map((base?.lifecycleReceipts || []).map(item => [item.id, item])), roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; + const state = { nodes, channels: new Map((base?.channels || []).map(item => [item.id, item])), moduleStates: new Map((base?.moduleStates || []).map(item => [item.name, item])), lifecycleReceipts: new Map((base?.lifecycleReceipts || []).map(item => [item.id, item])), roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; const baseSeq = base?.lastSeq || 0; let lastSeq = baseSeq; let unnumbered = base?.unnumbered === true; @@ -1337,6 +1367,7 @@ function deriveGraph(events, base = null) { nodes: state.migrated ? plexus.projectNodeRefs(sortedNodes, links) : sortedNodes, edges: [...edges.values()].sort((left, right) => left.id.localeCompare(right.id)), links, + channels: [...state.channels.values()], renewals: state.renewals, moduleStates: [...state.moduleStates.values()], lifecycleReceipts: [...state.lifecycleReceipts.values()], diff --git a/packages/tmux-bridge/bin/plexus.mjs b/packages/tmux-bridge/bin/plexus.mjs index 828fe09b..8d2872b1 100644 --- a/packages/tmux-bridge/bin/plexus.mjs +++ b/packages/tmux-bridge/bin/plexus.mjs @@ -20,7 +20,7 @@ export const ROLE_WEIGHTS = { owns: 1, "works-on": 1, coordinates: 0.8, reviews: export const HALF_LIFE_DAYS = 7; export const TOUCH_COALESCE_MS = 10 * 60 * 1000; export const LIFECYCLE_EVENTS = new Set(["session.started", "session.idle", "session.compacted", "session.stopped", "session.handover"]); -export const PLEXUS_EVENTS = new Set(["role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated", ...LIFECYCLE_EVENTS]); +export const PLEXUS_EVENTS = new Set(["channel.updated", "role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated", ...LIFECYCLE_EVENTS]); const HARNESSES = new Set(["codex", "claude"]); const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i; const SESSION_ID = /^(codex|claude):[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/; @@ -86,6 +86,11 @@ export function applyPlexusEvent(state, item) { const effects = []; const openLinks = () => [...state.links.values()].filter((link) => link.until === null); switch (item.type) { + case "channel.updated": + if (!item.channel || item.channel.schema !== "agent-mesh.channel.v1" || typeof item.channel.id !== "string" || !Array.isArray(item.channel.queue)) throw new Error("invalid channel event"); + if (!state.channels) state.channels = new Map(); + state.channels.set(item.channel.id, item.channel); + break; case "session.started": case "session.idle": case "session.compacted": diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs new file mode 100644 index 00000000..14ff256f --- /dev/null +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -0,0 +1,32 @@ +import assert from 'node:assert/strict'; +import { execFile } from 'node:child_process'; +import { mkdtemp, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { promisify } from 'node:util'; +import test from 'node:test'; +const exec = promisify(execFile); +const bin = fileURLToPath(new URL('../bin/mesh-graph.mjs', import.meta.url)); + +test('channel and queued messages survive concurrent writers, replay and compaction', async (t) => { + const state = await mkdtemp(join(tmpdir(), 'channel-store-')); + t.after(() => rm(state, { recursive: true, force: true })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args])).stdout); + const uuid = '22222222-2222-4222-8222-222222222222'; + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${uuid}`); + await call('channel', 'begin-handover', '--name', 'example'); + await Promise.all(['one', 'two'].map(id => call('channel', 'enqueue', '--name', 'example', '--id', id, '--input', id))); + assert.equal((await call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'one')).duplicate, true); + await assert.rejects(call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'changed'), /conflict/); + await rm(join(state, 'checkpoint.json')); + let channel = (await call('channel', 'get', '--name', 'example')).channel; + assert.equal(channel.phase, 'handover'); + assert.deepEqual(channel.queue.map(row => row.id).sort(), ['one', 'two']); + await call('compact', '--all-history', '--apply', '--json'); + await rm(join(state, 'checkpoint.json'), { force: true }); + channel = (await call('channel', 'get', '--name', 'example')).channel; + assert.deepEqual(channel.queue.map(row => row.id).sort(), ['one', 'two']); +}); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 8ef7f4c6..520df394 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -36,6 +36,7 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; +import { createChannel, enqueue, beginHandover } from "./channel-state.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -122,7 +123,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -134,6 +135,35 @@ const stateDir = resolve(values.state || GRAPH_DIR); try { switch (command) { + case "channel": { + const name = requiredSingleLine(values.name, "--name"); + if (subcommand === "get") { + const channel = (loadGraph(stateDir).channels || []).find((item) => item.id === name); + if (!channel) throw new Error("unknown channel"); + printResult({ channel }, { json: true }); + break; + } + const result = mutate(stateDir, graph => { + if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); + const current = (graph.channels || []).find((item) => item.id === name); + let next; + if (subcommand === "create") { + if (current) throw new Error("channel already exists"); + const session = requiredSingleLine(values.session, "--session"); + if (graph.nodes.filter(node => plexus.sessionIdOf(node) === session).length !== 1) throw new Error("unknown or ambiguous session"); + next = createChannel(name, session); + } else { + if (!current) throw new Error("unknown channel"); + if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), values.input); + else if (subcommand === "begin-handover") next = beginHandover(current); + else throw new Error("unknown channel operation"); + } + if (current && JSON.stringify(current) === JSON.stringify(next)) return { graph, result: { channel: next, duplicate: true } }; + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } case "lifecycle": { if (subcommand !== "record") throw new Error("unknown lifecycle operation"); if (!plexus.LIFECYCLE_EVENTS.has(values.type)) throw new Error("invalid lifecycle type"); @@ -1201,7 +1231,7 @@ function readCheckpoint(statePath) { if (checkpoint.schema !== GRAPH_SCHEMA || checkpoint.graph?.schema !== GRAPH_SCHEMA || !Array.isArray(checkpoint.graph.nodes) || !Array.isArray(checkpoint.graph.edges) || // Older binaries rewrite the checkpoint without Plexus state; replaying from the file is the only safe answer. - !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Array.isArray(checkpoint.graph.moduleStates) || !Array.isArray(checkpoint.graph.lifecycleReceipts) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || + !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Array.isArray(checkpoint.graph.moduleStates) || !Array.isArray(checkpoint.graph.lifecycleReceipts) || !Array.isArray(checkpoint.graph.channels) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || !cursor || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || !Number.isSafeInteger(cursor.dev) || !Number.isSafeInteger(cursor.ino)) { return null; @@ -1290,7 +1320,7 @@ function* readEventRecords(statePath, offset = 0) { function deriveGraph(events, base = null) { const nodes = new Map((base?.nodes || []).map((node) => [node.id, node])); const edges = new Map((base?.edges || []).map((edge) => [edge.id, edge])); - const state = { nodes, moduleStates: new Map((base?.moduleStates || []).map(item => [item.name, item])), lifecycleReceipts: new Map((base?.lifecycleReceipts || []).map(item => [item.id, item])), roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; + const state = { nodes, channels: new Map((base?.channels || []).map(item => [item.id, item])), moduleStates: new Map((base?.moduleStates || []).map(item => [item.name, item])), lifecycleReceipts: new Map((base?.lifecycleReceipts || []).map(item => [item.id, item])), roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; const baseSeq = base?.lastSeq || 0; let lastSeq = baseSeq; let unnumbered = base?.unnumbered === true; @@ -1337,6 +1367,7 @@ function deriveGraph(events, base = null) { nodes: state.migrated ? plexus.projectNodeRefs(sortedNodes, links) : sortedNodes, edges: [...edges.values()].sort((left, right) => left.id.localeCompare(right.id)), links, + channels: [...state.channels.values()], renewals: state.renewals, moduleStates: [...state.moduleStates.values()], lifecycleReceipts: [...state.lifecycleReceipts.values()], diff --git a/skills/agent-tmux/bin/plexus.mjs b/skills/agent-tmux/bin/plexus.mjs index 828fe09b..8d2872b1 100644 --- a/skills/agent-tmux/bin/plexus.mjs +++ b/skills/agent-tmux/bin/plexus.mjs @@ -20,7 +20,7 @@ export const ROLE_WEIGHTS = { owns: 1, "works-on": 1, coordinates: 0.8, reviews: export const HALF_LIFE_DAYS = 7; export const TOUCH_COALESCE_MS = 10 * 60 * 1000; export const LIFECYCLE_EVENTS = new Set(["session.started", "session.idle", "session.compacted", "session.stopped", "session.handover"]); -export const PLEXUS_EVENTS = new Set(["role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated", ...LIFECYCLE_EVENTS]); +export const PLEXUS_EVENTS = new Set(["channel.updated", "role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated", ...LIFECYCLE_EVENTS]); const HARNESSES = new Set(["codex", "claude"]); const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i; const SESSION_ID = /^(codex|claude):[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/; @@ -86,6 +86,11 @@ export function applyPlexusEvent(state, item) { const effects = []; const openLinks = () => [...state.links.values()].filter((link) => link.until === null); switch (item.type) { + case "channel.updated": + if (!item.channel || item.channel.schema !== "agent-mesh.channel.v1" || typeof item.channel.id !== "string" || !Array.isArray(item.channel.queue)) throw new Error("invalid channel event"); + if (!state.channels) state.channels = new Map(); + state.channels.set(item.channel.id, item.channel); + break; case "session.started": case "session.idle": case "session.compacted": From 17c0893ef8aa9a3f4afbf8f4780a94f7da02212d Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:34:12 +0000 Subject: [PATCH 013/113] Add checked Plexus architecture diagram --- docs/design/plexus-architecture.mmd | 10 ++++++++++ docs/design/plexus-channels.md | 4 ++++ scripts/mesh-readiness.mjs | 2 ++ scripts/plexus-diagram.mjs | 12 ++++++++++++ 4 files changed, 28 insertions(+) create mode 100644 docs/design/plexus-architecture.mmd create mode 100644 scripts/plexus-diagram.mjs diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd new file mode 100644 index 00000000..0f34efa5 --- /dev/null +++ b/docs/design/plexus-architecture.mmd @@ -0,0 +1,10 @@ +flowchart LR + Client["Client or waker"] -. "planned routing" .-> Channel["Stable channel"] + Channel --> Queue["Channel queue"] + Channel --> Session["Current session"] + Queue --> Journal["Graph event journal"] + Session --> Journal + Module["Registered module"] --> Contract["Versioned JSON contract"] + Contract --> Journal + Queue -. "planned delivery" .-> Session + Handover["Handover"] -. "planned verified cutover" .-> Channel diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 66d315e4..defac461 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -1,5 +1,9 @@ # Channel transition prototype +The public [architecture diagram](plexus-architecture.mmd) distinguishes +implemented components from planned links. Keep its source in +`scripts/plexus-diagram.mjs` synchronized; the readiness check compares them. + `channel-state.mjs` defines pure JSON transitions for a stable channel, its current session and a queue. An in-flight message is bound to a session and generation. A handover stops new dispatch and cannot finish while a delivery is diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index b8d4fabf..22352588 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -4,6 +4,7 @@ import path from "node:path"; import { fileURLToPath } from "node:url"; import { parseMeshV1Envelope, planMeshV1Dispatch } from "../packages/core/src/policy.js"; import { containsPrivatePlexusPolicy, isPlexusMechanismFile } from "./plexus-privacy.mjs"; +import { plexusDiagram } from "./plexus-diagram.mjs"; const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); const checks = []; @@ -63,6 +64,7 @@ const agentTmuxBundleFiles = [ const snowflakeIdPattern = /\b(?!([0-9])\1{16,19}\b)\d{17,20}\b/; function check(name, fn) { try { fn(); checks.push({ name, ok: true }); } catch (error) { checks.push({ name, ok: false, error: error.message }); } } function assert(condition, message) { if (!condition) throw new Error(message); } +check("Plexus architecture diagram sync", () => { assert(readFileSync(path.join(root, "docs/design/plexus-architecture.mmd"), "utf8") === plexusDiagram, "Plexus architecture diagram differs from its source"); }); check("parse Mesh v1 headers", () => { const envelope = parseMeshV1Envelope("cc-mesh: alpha\ncc-mesh-from: beta\ncc-mesh-id: ready-1\ncc-mesh-turn: alpha\ncc-mesh-final: false\nhop-limit: 2\n\nhello"); assert(envelope.valid, `expected valid envelope: ${envelope.errors.join(",")}`); assert(envelope.final === false, "expected partial final flag"); assert(envelope.hopLimit === 2, "expected hop limit parse"); }); check("parse compact ccm:v1 headers", () => { const envelope = parseMeshV1Envelope("<@123>\nccm:v1 id=ready-compact from=beta turn=alpha final=1 seen=beta hop=2\n\nhello"); assert(envelope.valid, `expected valid compact envelope: ${envelope.errors.join(",")}`); assert(envelope.format === "ccm:v1", "expected compact format marker"); assert(envelope.final === true, "expected compact final flag"); assert(envelope.to[0] === "alpha", "expected compact turn to become recipient"); assert(envelope.body === "hello", "expected compact body parse"); }); check("partial buffers only", () => { const plan = planMeshV1Dispatch({ localParticipant: "alpha" }, { messageId: "ready-m1", text: "cc-mesh: alpha\ncc-mesh-from: beta\ncc-mesh-id: ready-2\ncc-mesh-turn: alpha\ncc-mesh-final: false\n\npart" }); assert(plan.nextAction === "buffer_only", `expected buffer_only got ${plan.nextAction}`); assert(!plan.dispatchText, "partial must not dispatch text"); }); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs new file mode 100644 index 00000000..be3ad81d --- /dev/null +++ b/scripts/plexus-diagram.mjs @@ -0,0 +1,12 @@ +// Update this diagram together with the public architecture when it changes. +export const plexusDiagram = `flowchart LR + Client["Client or waker"] -. "planned routing" .-> Channel["Stable channel"] + Channel --> Queue["Channel queue"] + Channel --> Session["Current session"] + Queue --> Journal["Graph event journal"] + Session --> Journal + Module["Registered module"] --> Contract["Versioned JSON contract"] + Contract --> Journal + Queue -. "planned delivery" .-> Session + Handover["Handover"] -. "planned verified cutover" .-> Channel +`; From 711d9ea871a07c7dd91c1e3f848292992cc39245 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:36:36 +0000 Subject: [PATCH 014/113] Persist ordered channel delivery reservations --- docs/design/plexus-channels.md | 9 +++++++-- packages/tmux-bridge/bin/channel-state.mjs | 2 ++ packages/tmux-bridge/bin/mesh-graph.mjs | 6 ++++-- .../tmux-bridge/test/channel-state.test.mjs | 5 ++++- .../test/plexus-channel-store.test.mjs | 17 +++++++++++++++++ skills/agent-tmux/bin/channel-state.mjs | 2 ++ skills/agent-tmux/bin/mesh-graph.mjs | 6 ++++-- 7 files changed, 40 insertions(+), 7 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index defac461..e67f2835 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -14,8 +14,13 @@ events under the graph writer lock. Queued messages survive replay and compaction. The graph and event log contain message bodies and must remain private; this is not a scoped remote API. -This is not yet a complete channel service: delivery and handover completion -are not exposed by the graph command. It has no transport, authorization, +The graph command can also reserve a pending message and record a matching +acceptance receipt. Reservation is durable before transport; a crash or +uncertain outcome leaves the item in flight and blocks handover. A local +caller is responsible for verifying transport receipts before recording them. + +This is not yet a complete channel service: handover completion is not exposed +by the graph command. It has no transport, authorization, waker integration, recovery procedure or session verification. The caller must not treat the `verified` argument as evidence by itself. It must establish all of these properties before connecting the transitions to live sessions. diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 9e6de7e7..21eba0c2 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -21,6 +21,8 @@ export function enqueue(state, id, payload) { export function beginDelivery(state, id) { if (state.phase !== 'active') throw new Error('handover in progress'); + if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + if (state.queue.find((item) => item.state === 'pending')?.id !== id) throw new Error('message is not first pending'); const next = copy(state), item = next.queue.find((row) => row.id === id); if (!item || item.state !== 'pending') throw new Error('message not pending'); item.state = 'inflight'; diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 520df394..9f39ea77 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -36,7 +36,7 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge } from "./channel-state.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -123,7 +123,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -155,6 +155,8 @@ try { } else { if (!current) throw new Error("unknown channel"); if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), values.input); + else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id")); + else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(values.input, "--input"))); else if (subcommand === "begin-handover") next = beginHandover(current); else throw new Error("unknown channel operation"); } diff --git a/packages/tmux-bridge/test/channel-state.test.mjs b/packages/tmux-bridge/test/channel-state.test.mjs index 141cbf62..e8a79840 100644 --- a/packages/tmux-bridge/test/channel-state.test.mjs +++ b/packages/tmux-bridge/test/channel-state.test.mjs @@ -5,7 +5,10 @@ import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, fini test('handover queues work and never reroutes an uncertain delivery', () => { let channel = createChannel('example', 'session:one'); channel = enqueue(channel, 'message-1', 'hello'); + channel = enqueue(channel, 'message-0', 'second'); + assert.throws(() => beginDelivery(channel, 'message-0'), /first pending/); channel = beginDelivery(channel, 'message-1'); + assert.throws(() => beginDelivery(channel, 'message-0'), /inflight/); channel = beginHandover(channel); channel = enqueue(channel, 'message-2', 'queued'); assert.throws(() => beginDelivery(channel, 'message-2'), /handover/); @@ -14,7 +17,7 @@ test('handover queues work and never reroutes an uncertain delivery', () => { channel = acknowledge(channel, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'session:one', generation: 1 }); assert.throws(() => finishHandover(channel, 'session:two', false), /successor/); channel = finishHandover(channel, 'session:two', true); - channel = beginDelivery(channel, 'message-2'); + channel = beginDelivery(channel, 'message-0'); assert.equal(channel.queue[1].session, 'session:two'); assert.equal(channel.queue[1].generation, 2); assert.deepEqual(enqueue(channel, 'message-2', 'queued'), channel); diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index 14ff256f..16541b85 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -30,3 +30,20 @@ test('channel and queued messages survive concurrent writers, replay and compact channel = (await call('channel', 'get', '--name', 'example')).channel; assert.deepEqual(channel.queue.map(row => row.id).sort(), ['one', 'two']); }); + +test('delivery reservation and matching receipt survive graph replay', async (t) => { + const state = await mkdtemp(join(tmpdir(), 'channel-delivery-')); + t.after(() => rm(state, { recursive: true, force: true })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args])).stdout); + const uuid = '22222222-2222-4222-8222-222222222222', session = `codex:${uuid}`; + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', session); + await call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'payload'); + await call('channel', 'begin-delivery', '--name', 'example', '--id', 'one'); + await rm(join(state, 'checkpoint.json')); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'inflight'); + await assert.rejects(call('channel', 'acknowledge', '--name', 'example', '--id', 'one', '--input', JSON.stringify({ status: 'accepted', messageId: 'one', session: 'codex:wrong', generation: 1 })), /receipt/); + await call('channel', 'acknowledge', '--name', 'example', '--id', 'one', '--input', JSON.stringify({ status: 'accepted', messageId: 'one', session, generation: 1 })); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'accepted'); +}); diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 9e6de7e7..21eba0c2 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -21,6 +21,8 @@ export function enqueue(state, id, payload) { export function beginDelivery(state, id) { if (state.phase !== 'active') throw new Error('handover in progress'); + if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + if (state.queue.find((item) => item.state === 'pending')?.id !== id) throw new Error('message is not first pending'); const next = copy(state), item = next.queue.find((row) => row.id === id); if (!item || item.state !== 'pending') throw new Error('message not pending'); item.state = 'inflight'; diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 520df394..9f39ea77 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -36,7 +36,7 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge } from "./channel-state.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -123,7 +123,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -155,6 +155,8 @@ try { } else { if (!current) throw new Error("unknown channel"); if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), values.input); + else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id")); + else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(values.input, "--input"))); else if (subcommand === "begin-handover") next = beginHandover(current); else throw new Error("unknown channel operation"); } From 62c5965b6d651f891698af90845192551f0c7be3 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:41:20 +0000 Subject: [PATCH 015/113] Route waker notifications through durable channels --- docs/design/plexus-architecture.mmd | 4 +- packages/tmux-bridge/bin/agent-waker.py | 97 ++++++++++++++++++- packages/tmux-bridge/docs/agent-waker.md | 8 ++ .../scripts/test-isolation-regression.sh | 1 + .../test/agent-waker-channel.test.py | 92 ++++++++++++++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-diagram.mjs | 4 +- skills/agent-tmux/bin/agent-waker.py | 97 ++++++++++++++++++- 8 files changed, 296 insertions(+), 8 deletions(-) create mode 100644 packages/tmux-bridge/test/agent-waker-channel.test.py diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 0f34efa5..6fc96e2c 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -1,10 +1,10 @@ flowchart LR - Client["Client or waker"] -. "planned routing" .-> Channel["Stable channel"] + Client["Client or waker"] -- "channel mode" --> Channel["Stable channel"] Channel --> Queue["Channel queue"] Channel --> Session["Current session"] Queue --> Journal["Graph event journal"] Session --> Journal Module["Registered module"] --> Contract["Versioned JSON contract"] Contract --> Journal - Queue -. "planned delivery" .-> Session + Queue -- "bound receipt" --> Session Handover["Handover"] -. "planned verified cutover" .-> Channel diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index 612af5cd..1234390b 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -158,7 +158,95 @@ def record(job: str, outcome: str, session: str, note: str) -> None: capture_output=True) +def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dict[str, Any]: + command = ['node', str(BIN / 'mesh-graph.mjs')] + if args.graph_state: + command += ['--state', args.graph_state] + command += ['channel', operation, '--name', args.channel, *options] + result = subprocess.run(command, text=True, capture_output=True, timeout=30, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or not isinstance(value.get('channel'), dict): + raise ValueError('invalid channel response') + return value['channel'] + + +def run_channel(args: argparse.Namespace) -> int: + path = Path(args.state) if args.state else state_dir() / f'{args.job}.json' + with locked(path) as acquired: + if not acquired: + print(json.dumps({'job': args.job, 'outcome': 'noop', 'reason': 'previous run still active'})) + return 0 + state, state_errors = load_state(path) + if state_errors: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unreadable waker state'})) + return 3 + new, errors = run_producer(args.producer, args.producer_timeout) + errors = state_errors + errors + known = {entry['key'] for entry in state['pending']} + for item in new: + key = item_key(item) + if key not in known: + known.add(key) + state['pending'].append({'key': key, 'item': item}) + signature = error_signature(errors) + wake_errors = errors if signature and signature != state.get('errorSignature') else [] + if not errors: + state['errorSignature'] = None + flight = state.get('inFlight') + recipient = {'channel': args.channel} + if flight and flight.get('recipient') != recipient: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'in-flight recipient changed'})) + return 3 + if not flight and (state['pending'] or wake_errors): + flight = {'correlationId': f'waker-{uuid.uuid4()}', 'recipient': recipient, + 'message': compose(args.job, state['pending'], wake_errors), + 'itemKeys': [entry['key'] for entry in state['pending'][:MAX_LISTED]], 'errorSignature': signature} + state['inFlight'] = flight + save_state(path, state) + try: + if flight: + channel_call(args, 'enqueue', '--id', flight['correlationId'], '--input', flight['message']) + accepted = set(flight['itemKeys']) + state['pending'] = [entry for entry in state['pending'] if entry['key'] not in accepted] + state['lastDelivery'] = {'correlationId': flight['correlationId'], 'at': time.time(), + 'itemKeys': flight['itemKeys'], 'status': 'channel-queued'} + if flight['errorSignature']: + state['errorSignature'] = flight['errorSignature'] + state.pop('inFlight', None) + save_state(path, state) + channel = channel_call(args, 'get') + if channel.get('phase') != 'active': + print(json.dumps({'job': args.job, 'outcome': 'queued', 'reason': 'handover'})) + return 0 + if any(item.get('state') == 'inflight' for item in channel['queue']): + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unresolved delivery'})) + return 3 + pending = next((item for item in channel['queue'] if item.get('state') == 'pending'), None) + if not pending: + print(json.dumps({'job': args.job, 'outcome': 'noop'})) + return 0 + channel = channel_call(args, 'begin-delivery', '--id', pending['id']) + item = next(item for item in channel['queue'] if item['id'] == pending['id']) + agent, sep, session = item['session'].partition(':') + if not sep or agent not in ('codex', 'claude'): + raise ValueError('unsupported channel recipient') + code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, + True, resume=args.resume and agent == 'codex') + if code != 0: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'delivery unconfirmed'})) + return 3 + receipt = {'status': 'accepted', 'messageId': item['id'], 'session': item['session'], 'generation': item['generation']} + channel_call(args, 'acknowledge', '--id', item['id'], '--input', json.dumps(receipt, separators=(',', ':'))) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'correlationId': item['id']})) + return 0 + except (OSError, subprocess.SubprocessError, ValueError, KeyError, TypeError, StopIteration): + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'channel unavailable or delivery unresolved'})) + return 3 + + def run(args: argparse.Namespace) -> int: + if getattr(args, 'channel', None): + return run_channel(args) path = Path(args.state) if args.state else state_dir() / f"{args.job}.json" with locked(path) as acquired: if not acquired: @@ -225,7 +313,10 @@ def main(argv: list[str] | None = None) -> int: runner = sub.add_parser("run", help="run the producer once and deliver anything new") runner.add_argument("--job", required=True) runner.add_argument("--agent", default="claude", choices=("claude", "codex")) - runner.add_argument("--session", required=True, help="owning session UUID") + recipient = runner.add_mutually_exclusive_group(required=True) + recipient.add_argument("--session", help="owning session UUID") + recipient.add_argument("--channel", help="stable channel identifier") + runner.add_argument("--graph-state", help="override graph state for isolated tests") runner.add_argument("--managed-inbox-root", help="required for Claude sessions") runner.add_argument("--delivery-only", action="store_true", help="acknowledge the native queue, without waiting for a result") runner.add_argument("--resume", action="store_true", help="opt in to native Codex resume when idle") @@ -233,7 +324,9 @@ def main(argv: list[str] | None = None) -> int: runner.add_argument("--producer-timeout", type=int, default=280) runner.add_argument("producer", nargs=argparse.REMAINDER, help="-- command that prints the JSON report") args = parser.parse_args(argv) - if args.resume and args.agent != "codex": + if args.channel and not args.delivery_only: + parser.error("--channel requires --delivery-only") + if args.resume and not args.channel and args.agent != "codex": parser.error("--resume requires --agent codex") if args.producer[:1] == ["--"]: args.producer = args.producer[1:] diff --git a/packages/tmux-bridge/docs/agent-waker.md b/packages/tmux-bridge/docs/agent-waker.md index 86564efd..69796d8a 100644 --- a/packages/tmux-bridge/docs/agent-waker.md +++ b/packages/tmux-bridge/docs/agent-waker.md @@ -30,6 +30,14 @@ For an idle Codex owner, explicit `--agent codex --resume` forwards native `--resume` through the existing transport and communications gate. It is opt-in; Claude resume is rejected. A queue receipt still does not prove an actor response. +In channel mode, `--channel --delivery-only` persists the notification +in the graph queue before acknowledging the producer. A handover keeps it +queued. The first pending message is reserved before invoking the native +transport; an unconfirmed delivery stays in flight and requires reconciliation. +The native bound queue receipt is checked before the graph records acceptance. +Channel delivery does not establish that the receiving actor read the message. +The channel mode and handover are not yet enabled in existing timers. + Delivery-only acknowledgement requires native JSON `status: queued`, matching agent/session/correlation and no `held: true`. Except for the bound delivered duplicate described below, held, refused, malformed or missing receipts retain pending items diff --git a/packages/tmux-bridge/scripts/test-isolation-regression.sh b/packages/tmux-bridge/scripts/test-isolation-regression.sh index 7dd27af5..543f8022 100644 --- a/packages/tmux-bridge/scripts/test-isolation-regression.sh +++ b/packages/tmux-bridge/scripts/test-isolation-regression.sh @@ -62,6 +62,7 @@ python3 test/mesh-groups.test.py python3 test/session-inbox.test.py python3 test/run-receipt.test.py python3 test/agent-waker.test.py +python3 test/agent-waker-channel.test.py python3 test/session-controller.test.py python3 test/owner-notify.test.py scripts/socket-isolation-test.sh diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py new file mode 100644 index 00000000..1d87fc1e --- /dev/null +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -0,0 +1,92 @@ +import contextlib +import importlib.util +import io +import json +from pathlib import Path +import subprocess +import tempfile +from types import SimpleNamespace +import unittest +from unittest.mock import patch + +root = Path(__file__).resolve().parents[1] +spec = importlib.util.spec_from_file_location('channel_waker', root / 'bin' / 'agent-waker.py') +waker = importlib.util.module_from_spec(spec) +spec.loader.exec_module(waker) +uuid = '22222222-2222-4222-8222-222222222222' + + +class ChannelWakerTest(unittest.TestCase): + def test_lost_enqueue_response_retries_same_message_without_duplication(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'graph' + def call(*args): + return json.loads(subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], check=True, capture_output=True, text=True).stdout) + call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') + call('channel', 'begin-handover', '--name', 'example') + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + original = waker.channel_call + def lost_response(args, operation, *options): + result = original(args, operation, *options) + if operation == 'enqueue': + raise subprocess.TimeoutExpired('fixture', 1) + return result + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'channel_call', side_effect=lost_response), contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + with patch.object(waker, 'run_producer', return_value=([], [])), contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 0) + self.assertEqual(len(call('channel', 'get', '--name', 'example')['channel']['queue']), 1) + self.assertEqual(json.loads(Path(args.state).read_text())['pending'], []) + + def test_unreadable_state_stops_before_producer_advances(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'waker.json' + state.write_text('{broken') + args = SimpleNamespace(state=str(state), graph_state=str(Path(directory) / 'graph'), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + with patch.object(waker, 'run_producer') as producer, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + producer.assert_not_called() + self.assertEqual(state.read_text(), '{broken') + + def test_enqueue_during_handover_and_uncertain_delivery_blocks_retry(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'graph' + def call(*args): + return json.loads(subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], check=True, capture_output=True, text=True).stdout) + call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') + call('channel', 'begin-handover', '--name', 'example') + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 0) + deliver.assert_not_called() + channel = call('channel', 'get', '--name', 'example')['channel'] + self.assertEqual(channel['phase'], 'handover') + self.assertEqual(channel['queue'][0]['state'], 'pending') + self.assertEqual(json.loads(Path(args.state).read_text())['pending'], []) + + def test_accepted_delivery_is_bound_and_uncertainty_is_not_retried(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'graph' + def call(*args): + return json.loads(subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], check=True, capture_output=True, text=True).stdout) + call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'deliver', return_value=0) as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 0) + self.assertEqual(deliver.call_args.args[0:2], ('codex', uuid)) + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'accepted') + with patch.object(waker, 'run_producer', return_value=([{'event': 'two'}], [])), patch.object(waker, 'deliver', return_value=78) as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + self.assertEqual(waker.run(args), 3) + self.assertEqual(deliver.call_count, 1) + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][1]['state'], 'inflight') + + +if __name__ == '__main__': + unittest.main() diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index 22352588..90c8c323 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -21,6 +21,7 @@ const agentTmuxBundleFiles = [ "bin/agent-read.sh", "bin/agent-follow.py", "bin/agent-watch.py", + "bin/agent-waker.py", "bin/agent-send.sh", "bin/agent-spawn.sh", "bin/agent-session.sh", diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index be3ad81d..c7e783fb 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -1,12 +1,12 @@ // Update this diagram together with the public architecture when it changes. export const plexusDiagram = `flowchart LR - Client["Client or waker"] -. "planned routing" .-> Channel["Stable channel"] + Client["Client or waker"] -- "channel mode" --> Channel["Stable channel"] Channel --> Queue["Channel queue"] Channel --> Session["Current session"] Queue --> Journal["Graph event journal"] Session --> Journal Module["Registered module"] --> Contract["Versioned JSON contract"] Contract --> Journal - Queue -. "planned delivery" .-> Session + Queue -- "bound receipt" --> Session Handover["Handover"] -. "planned verified cutover" .-> Channel `; diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index 612af5cd..1234390b 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -158,7 +158,95 @@ def record(job: str, outcome: str, session: str, note: str) -> None: capture_output=True) +def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dict[str, Any]: + command = ['node', str(BIN / 'mesh-graph.mjs')] + if args.graph_state: + command += ['--state', args.graph_state] + command += ['channel', operation, '--name', args.channel, *options] + result = subprocess.run(command, text=True, capture_output=True, timeout=30, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or not isinstance(value.get('channel'), dict): + raise ValueError('invalid channel response') + return value['channel'] + + +def run_channel(args: argparse.Namespace) -> int: + path = Path(args.state) if args.state else state_dir() / f'{args.job}.json' + with locked(path) as acquired: + if not acquired: + print(json.dumps({'job': args.job, 'outcome': 'noop', 'reason': 'previous run still active'})) + return 0 + state, state_errors = load_state(path) + if state_errors: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unreadable waker state'})) + return 3 + new, errors = run_producer(args.producer, args.producer_timeout) + errors = state_errors + errors + known = {entry['key'] for entry in state['pending']} + for item in new: + key = item_key(item) + if key not in known: + known.add(key) + state['pending'].append({'key': key, 'item': item}) + signature = error_signature(errors) + wake_errors = errors if signature and signature != state.get('errorSignature') else [] + if not errors: + state['errorSignature'] = None + flight = state.get('inFlight') + recipient = {'channel': args.channel} + if flight and flight.get('recipient') != recipient: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'in-flight recipient changed'})) + return 3 + if not flight and (state['pending'] or wake_errors): + flight = {'correlationId': f'waker-{uuid.uuid4()}', 'recipient': recipient, + 'message': compose(args.job, state['pending'], wake_errors), + 'itemKeys': [entry['key'] for entry in state['pending'][:MAX_LISTED]], 'errorSignature': signature} + state['inFlight'] = flight + save_state(path, state) + try: + if flight: + channel_call(args, 'enqueue', '--id', flight['correlationId'], '--input', flight['message']) + accepted = set(flight['itemKeys']) + state['pending'] = [entry for entry in state['pending'] if entry['key'] not in accepted] + state['lastDelivery'] = {'correlationId': flight['correlationId'], 'at': time.time(), + 'itemKeys': flight['itemKeys'], 'status': 'channel-queued'} + if flight['errorSignature']: + state['errorSignature'] = flight['errorSignature'] + state.pop('inFlight', None) + save_state(path, state) + channel = channel_call(args, 'get') + if channel.get('phase') != 'active': + print(json.dumps({'job': args.job, 'outcome': 'queued', 'reason': 'handover'})) + return 0 + if any(item.get('state') == 'inflight' for item in channel['queue']): + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unresolved delivery'})) + return 3 + pending = next((item for item in channel['queue'] if item.get('state') == 'pending'), None) + if not pending: + print(json.dumps({'job': args.job, 'outcome': 'noop'})) + return 0 + channel = channel_call(args, 'begin-delivery', '--id', pending['id']) + item = next(item for item in channel['queue'] if item['id'] == pending['id']) + agent, sep, session = item['session'].partition(':') + if not sep or agent not in ('codex', 'claude'): + raise ValueError('unsupported channel recipient') + code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, + True, resume=args.resume and agent == 'codex') + if code != 0: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'delivery unconfirmed'})) + return 3 + receipt = {'status': 'accepted', 'messageId': item['id'], 'session': item['session'], 'generation': item['generation']} + channel_call(args, 'acknowledge', '--id', item['id'], '--input', json.dumps(receipt, separators=(',', ':'))) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'correlationId': item['id']})) + return 0 + except (OSError, subprocess.SubprocessError, ValueError, KeyError, TypeError, StopIteration): + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'channel unavailable or delivery unresolved'})) + return 3 + + def run(args: argparse.Namespace) -> int: + if getattr(args, 'channel', None): + return run_channel(args) path = Path(args.state) if args.state else state_dir() / f"{args.job}.json" with locked(path) as acquired: if not acquired: @@ -225,7 +313,10 @@ def main(argv: list[str] | None = None) -> int: runner = sub.add_parser("run", help="run the producer once and deliver anything new") runner.add_argument("--job", required=True) runner.add_argument("--agent", default="claude", choices=("claude", "codex")) - runner.add_argument("--session", required=True, help="owning session UUID") + recipient = runner.add_mutually_exclusive_group(required=True) + recipient.add_argument("--session", help="owning session UUID") + recipient.add_argument("--channel", help="stable channel identifier") + runner.add_argument("--graph-state", help="override graph state for isolated tests") runner.add_argument("--managed-inbox-root", help="required for Claude sessions") runner.add_argument("--delivery-only", action="store_true", help="acknowledge the native queue, without waiting for a result") runner.add_argument("--resume", action="store_true", help="opt in to native Codex resume when idle") @@ -233,7 +324,9 @@ def main(argv: list[str] | None = None) -> int: runner.add_argument("--producer-timeout", type=int, default=280) runner.add_argument("producer", nargs=argparse.REMAINDER, help="-- command that prints the JSON report") args = parser.parse_args(argv) - if args.resume and args.agent != "codex": + if args.channel and not args.delivery_only: + parser.error("--channel requires --delivery-only") + if args.resume and not args.channel and args.agent != "codex": parser.error("--resume requires --agent codex") if args.producer[:1] == ["--"]: args.producer = args.producer[1:] From 35c62393b1930cb5bb1f2327e28564c1216e6a4d Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:46:04 +0000 Subject: [PATCH 016/113] Guard channel cutover with fresh native evidence --- docs/design/plexus-channels.md | 16 +++++++--- packages/tmux-bridge/bin/mesh-graph.mjs | 24 ++++++++++++-- packages/tmux-bridge/bin/plexus.mjs | 5 +++ .../test/plexus-channel-store.test.mjs | 32 ++++++++++++++++++- skills/agent-tmux/bin/mesh-graph.mjs | 24 ++++++++++++-- skills/agent-tmux/bin/plexus.mjs | 5 +++ 6 files changed, 94 insertions(+), 12 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index e67f2835..bd6be8ac 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -19,8 +19,14 @@ acceptance receipt. Reservation is durable before transport; a crash or uncertain outcome leaves the item in flight and blocks handover. A local caller is responsible for verifying transport receipts before recording them. -This is not yet a complete channel service: handover completion is not exposed -by the graph command. It has no transport, authorization, -waker integration, recovery procedure or session verification. The caller must not treat the -`verified` argument as evidence by itself. It must establish all of these -properties before connecting the transitions to live sessions. +Handover completion currently supports only a Codex successor with a fresh +unarchived native-thread observation and exactly one detected writer. It +atomically changes the channel and emits `session.handover`, with a native +thread link in the channel receipt. Missing or ambiguous evidence fails closed; +Claude and cloud successors are not yet supported by this operation. + +This is not yet a complete handover workflow: it does not write state for the +old session, publish or verify the old session's final notice, archive anything, +or reconcile uncertain transport outcomes. It must not be used for a live +handover until those steps and their failure recovery are implemented and +verified. The local graph is a trusted operator interface, not a remote API. diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 9f39ea77..9f74c470 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -36,7 +36,7 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, finishHandover } from "./channel-state.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -123,7 +123,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -157,7 +157,25 @@ try { if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), values.input); else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id")); else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(values.input, "--input"))); - else if (subcommand === "begin-handover") next = beginHandover(current); + else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; + else if (subcommand === "finish-handover") { + const target = requiredSingleLine(values.to, "--to"); + if (current.phase === "active" && current.session === target && current.handoverReceipt?.successor === target) return { graph, result: { channel: current, duplicate: true } }; + const matches = graph.nodes.filter(node => plexus.sessionIdOf(node) === target); + const node = matches[0], proof = node?.sessionLink; + const started = Date.parse(current.handoverStartedAt), checked = Date.parse(proof?.checkedAt); + if (matches.length !== 1 || node.status === "closed" || node.surface?.archived === true || proof?.status !== "ok" || proof.resolvedSession !== target || proof.lastKnown === true || !Number.isFinite(started) || !Number.isFinite(checked) || checked < started || checked > Date.now()) throw new Error("successor requires fresh verified link"); + // Current native link discovery can prove an unarchived Codex thread. + // Claude link observations explicitly leave remote reachability unverified. + if (!/^codex:[0-9a-f-]{36}$/.test(target) || proof.source !== "codex-threads" || proof.link !== target) throw new Error("successor native verification unavailable"); + const writer = probeWriter({ harness: "codex", nativeId: target.slice(6) }); + if (writer?.agent !== "codex" || writer.sessionId !== target.slice(6) || !Array.isArray(writer.writers) || writer.writers.length !== 1 || !Number.isSafeInteger(writer.writers[0]?.pid) || writer.writers[0].pid <= 0 || writer.writers[0].kind !== "codex") throw new Error("successor requires one verified writer"); + const link = `codex://threads/${target.slice(6)}`; + next = finishHandover(current, target, true); + next.handoverReceipt = { previous: current.session, successor: target, link, checkedAt: proof.checkedAt, writer: writer.writers[0] }; + delete next.handoverStartedAt; + return { graph, event: event("session.handover", { session: current.session, to: target, evidence: `channel:${name}`, channel: next }), result: { channel: next, duplicate: false } }; + } else throw new Error("unknown channel operation"); } if (current && JSON.stringify(current) === JSON.stringify(next)) return { graph, result: { channel: next, duplicate: true } }; diff --git a/packages/tmux-bridge/bin/plexus.mjs b/packages/tmux-bridge/bin/plexus.mjs index 8d2872b1..4d9ef0d2 100644 --- a/packages/tmux-bridge/bin/plexus.mjs +++ b/packages/tmux-bridge/bin/plexus.mjs @@ -101,6 +101,11 @@ export function applyPlexusEvent(state, item) { if (item.type === "session.handover") { parseGraphSessionId(item.to); if (item.to === item.session) throw new Error("handover target must differ"); + if (item.channel !== undefined) { + if (!item.channel || item.channel.schema !== "agent-mesh.channel.v1" || item.channel.session !== item.to) throw new Error("invalid handover channel"); + if (!state.channels) state.channels = new Map(); + state.channels.set(item.channel.id, item.channel); + } } else if (item.to !== undefined) throw new Error("unexpected lifecycle target"); effects.push({ kind: item.type, session: item.session, evidence: item.evidence, ...(item.to ? { to: item.to } : {}) }); break; diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index 16541b85..5c23a8be 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { execFile } from 'node:child_process'; -import { mkdtemp, rm } from 'node:fs/promises'; +import { appendFile, mkdtemp, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -31,6 +31,36 @@ test('channel and queued messages survive concurrent writers, replay and compact assert.deepEqual(channel.queue.map(row => row.id).sort(), ['one', 'two']); }); +test('cutover requires fresh successor verification and is replayed with its lifecycle event', async (t) => { + const state = await mkdtemp(join(tmpdir(), 'channel-cutover-')); + t.after(() => rm(state, { recursive: true, force: true })); + const writer = join(state, 'writer-fixture.mjs'); + await writeFile(writer, `console.log(JSON.stringify({agent:'codex',sessionId:'33333333-3333-4333-8333-333333333333',writers:[]}))`); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args], {env: {...process.env, MESH_PLEXUS_WRITER_STATUS: writer}})).stdout); + const one = '22222222-2222-4222-8222-222222222222', two = '33333333-3333-4333-8333-333333333333'; + for (const uuid of [one, two]) await call('add', '--agent', 'codex', '--tmux-target', `test-${uuid}`, '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${one}`); + await call('channel', 'begin-handover', '--name', 'example'); + const target = `codex:${two}`; + await assert.rejects(call('channel', 'finish-handover', '--name', 'example', '--to', target), /fresh verified link/); + const graph = await call('show', '--json'); + const node = graph.nodes.find(row => row.runtimeUuid === two); + const checkedAt = new Date().toISOString(); + node.sessionLink = { status: 'ok', resolvedSession: target, link: target, source: 'codex-threads', checkedAt, lastKnown: false }; + const fixture = { schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-proof', type: 'node.upserted', at: checkedAt, node, seq: graph.lastSeq + 1, host: 'local' }; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify(fixture)}\n`); + await assert.rejects(call('channel', 'finish-handover', '--name', 'example', '--to', target), /one verified writer/); + await writeFile(writer, `console.log(JSON.stringify({agent:'codex',sessionId:'33333333-3333-4333-8333-333333333333',writers:[{pid:123,kind:'codex'}]}))`); + const result = await call('channel', 'finish-handover', '--name', 'example', '--to', target); + assert.equal(result.channel.session, target); + assert.equal(result.channel.handoverReceipt.link, `codex://threads/${two}`); + assert.equal((await call('channel', 'finish-handover', '--name', 'example', '--to', target)).duplicate, true); + await rm(join(state, 'checkpoint.json')); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.session, target); + assert.ok((await call('query', 'changes', '--input', '{}')).events.some(item => item.type === 'session.handover' && item.to === target)); +}); + test('delivery reservation and matching receipt survive graph replay', async (t) => { const state = await mkdtemp(join(tmpdir(), 'channel-delivery-')); t.after(() => rm(state, { recursive: true, force: true })); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 9f39ea77..9f74c470 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -36,7 +36,7 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, finishHandover } from "./channel-state.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -123,7 +123,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -157,7 +157,25 @@ try { if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), values.input); else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id")); else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(values.input, "--input"))); - else if (subcommand === "begin-handover") next = beginHandover(current); + else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; + else if (subcommand === "finish-handover") { + const target = requiredSingleLine(values.to, "--to"); + if (current.phase === "active" && current.session === target && current.handoverReceipt?.successor === target) return { graph, result: { channel: current, duplicate: true } }; + const matches = graph.nodes.filter(node => plexus.sessionIdOf(node) === target); + const node = matches[0], proof = node?.sessionLink; + const started = Date.parse(current.handoverStartedAt), checked = Date.parse(proof?.checkedAt); + if (matches.length !== 1 || node.status === "closed" || node.surface?.archived === true || proof?.status !== "ok" || proof.resolvedSession !== target || proof.lastKnown === true || !Number.isFinite(started) || !Number.isFinite(checked) || checked < started || checked > Date.now()) throw new Error("successor requires fresh verified link"); + // Current native link discovery can prove an unarchived Codex thread. + // Claude link observations explicitly leave remote reachability unverified. + if (!/^codex:[0-9a-f-]{36}$/.test(target) || proof.source !== "codex-threads" || proof.link !== target) throw new Error("successor native verification unavailable"); + const writer = probeWriter({ harness: "codex", nativeId: target.slice(6) }); + if (writer?.agent !== "codex" || writer.sessionId !== target.slice(6) || !Array.isArray(writer.writers) || writer.writers.length !== 1 || !Number.isSafeInteger(writer.writers[0]?.pid) || writer.writers[0].pid <= 0 || writer.writers[0].kind !== "codex") throw new Error("successor requires one verified writer"); + const link = `codex://threads/${target.slice(6)}`; + next = finishHandover(current, target, true); + next.handoverReceipt = { previous: current.session, successor: target, link, checkedAt: proof.checkedAt, writer: writer.writers[0] }; + delete next.handoverStartedAt; + return { graph, event: event("session.handover", { session: current.session, to: target, evidence: `channel:${name}`, channel: next }), result: { channel: next, duplicate: false } }; + } else throw new Error("unknown channel operation"); } if (current && JSON.stringify(current) === JSON.stringify(next)) return { graph, result: { channel: next, duplicate: true } }; diff --git a/skills/agent-tmux/bin/plexus.mjs b/skills/agent-tmux/bin/plexus.mjs index 8d2872b1..4d9ef0d2 100644 --- a/skills/agent-tmux/bin/plexus.mjs +++ b/skills/agent-tmux/bin/plexus.mjs @@ -101,6 +101,11 @@ export function applyPlexusEvent(state, item) { if (item.type === "session.handover") { parseGraphSessionId(item.to); if (item.to === item.session) throw new Error("handover target must differ"); + if (item.channel !== undefined) { + if (!item.channel || item.channel.schema !== "agent-mesh.channel.v1" || item.channel.session !== item.to) throw new Error("invalid handover channel"); + if (!state.channels) state.channels = new Map(); + state.channels.set(item.channel.id, item.channel); + } } else if (item.to !== undefined) throw new Error("unexpected lifecycle target"); effects.push({ kind: item.type, session: item.session, evidence: item.evidence, ...(item.to ? { to: item.to } : {}) }); break; From 203dc88064a685b30e35b0f8b9ae9e9a8d46b93b Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:48:27 +0000 Subject: [PATCH 017/113] Test lost channel reservation responses --- .../test/agent-waker-channel.test.py | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index 1d87fc1e..874cc415 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -17,6 +17,29 @@ class ChannelWakerTest(unittest.TestCase): + def test_lost_reservation_response_does_not_send_or_retry(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'graph' + def call(*args): + return json.loads(subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], check=True, capture_output=True, text=True).stdout) + call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + original = waker.channel_call + def lost_response(args, operation, *options): + result = original(args, operation, *options) + if operation == 'begin-delivery': + raise subprocess.TimeoutExpired('fixture', 1) + return result + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'channel_call', side_effect=lost_response), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + deliver.assert_not_called() + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + deliver.assert_not_called() + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'inflight') + def test_lost_enqueue_response_retries_same_message_without_duplication(self): with tempfile.TemporaryDirectory() as directory: state = Path(directory) / 'graph' From 7ab783694cfed5ac8b226c1e0682ce531fe26876 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:50:56 +0000 Subject: [PATCH 018/113] Keep channel cutover closed until state is verified --- docs/design/plexus-channels.md | 10 +++++----- packages/tmux-bridge/bin/mesh-graph.mjs | 10 ++++------ .../tmux-bridge/test/plexus-channel-store.test.mjs | 11 ++++------- skills/agent-tmux/bin/mesh-graph.mjs | 10 ++++------ 4 files changed, 17 insertions(+), 24 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index bd6be8ac..47e4ed96 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -19,11 +19,11 @@ acceptance receipt. Reservation is durable before transport; a crash or uncertain outcome leaves the item in flight and blocks handover. A local caller is responsible for verifying transport receipts before recording them. -Handover completion currently supports only a Codex successor with a fresh -unarchived native-thread observation and exactly one detected writer. It -atomically changes the channel and emits `session.handover`, with a native -thread link in the channel receipt. Missing or ambiguous evidence fails closed; -Claude and cloud successors are not yet supported by this operation. +Handover completion is disabled until an adapter can verify that the old +session wrote its state. A path or caller assertion is not sufficient proof. +The prepared Codex path additionally requires a fresh unarchived native-thread +observation and exactly one detected writer. Claude and cloud successors are +not yet supported by this operation. This is not yet a complete handover workflow: it does not write state for the old session, publish or verify the old session's final notice, archive anything, diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 9f74c470..d5cc6a8d 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -36,7 +36,7 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, finishHandover } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge } from "./channel-state.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -170,11 +170,9 @@ try { if (!/^codex:[0-9a-f-]{36}$/.test(target) || proof.source !== "codex-threads" || proof.link !== target) throw new Error("successor native verification unavailable"); const writer = probeWriter({ harness: "codex", nativeId: target.slice(6) }); if (writer?.agent !== "codex" || writer.sessionId !== target.slice(6) || !Array.isArray(writer.writers) || writer.writers.length !== 1 || !Number.isSafeInteger(writer.writers[0]?.pid) || writer.writers[0].pid <= 0 || writer.writers[0].kind !== "codex") throw new Error("successor requires one verified writer"); - const link = `codex://threads/${target.slice(6)}`; - next = finishHandover(current, target, true); - next.handoverReceipt = { previous: current.session, successor: target, link, checkedAt: proof.checkedAt, writer: writer.writers[0] }; - delete next.handoverStartedAt; - return { graph, event: event("session.handover", { session: current.session, to: target, evidence: `channel:${name}`, channel: next }), result: { channel: next, duplicate: false } }; + // A caller assertion or a file path is not proof that the old + // session wrote its state; no verified adapter exists yet. + throw new Error("old-session state verification unavailable; cutover disabled"); } else throw new Error("unknown channel operation"); } diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index 5c23a8be..956e188f 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -31,7 +31,7 @@ test('channel and queued messages survive concurrent writers, replay and compact assert.deepEqual(channel.queue.map(row => row.id).sort(), ['one', 'two']); }); -test('cutover requires fresh successor verification and is replayed with its lifecycle event', async (t) => { +test('cutover fails closed until old-session state authorship is verified', async (t) => { const state = await mkdtemp(join(tmpdir(), 'channel-cutover-')); t.after(() => rm(state, { recursive: true, force: true })); const writer = join(state, 'writer-fixture.mjs'); @@ -52,13 +52,10 @@ test('cutover requires fresh successor verification and is replayed with its lif await appendFile(join(state, 'events.jsonl'), `${JSON.stringify(fixture)}\n`); await assert.rejects(call('channel', 'finish-handover', '--name', 'example', '--to', target), /one verified writer/); await writeFile(writer, `console.log(JSON.stringify({agent:'codex',sessionId:'33333333-3333-4333-8333-333333333333',writers:[{pid:123,kind:'codex'}]}))`); - const result = await call('channel', 'finish-handover', '--name', 'example', '--to', target); - assert.equal(result.channel.session, target); - assert.equal(result.channel.handoverReceipt.link, `codex://threads/${two}`); - assert.equal((await call('channel', 'finish-handover', '--name', 'example', '--to', target)).duplicate, true); + await assert.rejects(call('channel', 'finish-handover', '--name', 'example', '--to', target), /old-session state verification unavailable/); await rm(join(state, 'checkpoint.json')); - assert.equal((await call('channel', 'get', '--name', 'example')).channel.session, target); - assert.ok((await call('query', 'changes', '--input', '{}')).events.some(item => item.type === 'session.handover' && item.to === target)); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.session, `codex:${one}`); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.phase, 'handover'); }); test('delivery reservation and matching receipt survive graph replay', async (t) => { diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 9f74c470..d5cc6a8d 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -36,7 +36,7 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, finishHandover } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge } from "./channel-state.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -170,11 +170,9 @@ try { if (!/^codex:[0-9a-f-]{36}$/.test(target) || proof.source !== "codex-threads" || proof.link !== target) throw new Error("successor native verification unavailable"); const writer = probeWriter({ harness: "codex", nativeId: target.slice(6) }); if (writer?.agent !== "codex" || writer.sessionId !== target.slice(6) || !Array.isArray(writer.writers) || writer.writers.length !== 1 || !Number.isSafeInteger(writer.writers[0]?.pid) || writer.writers[0].pid <= 0 || writer.writers[0].kind !== "codex") throw new Error("successor requires one verified writer"); - const link = `codex://threads/${target.slice(6)}`; - next = finishHandover(current, target, true); - next.handoverReceipt = { previous: current.session, successor: target, link, checkedAt: proof.checkedAt, writer: writer.writers[0] }; - delete next.handoverStartedAt; - return { graph, event: event("session.handover", { session: current.session, to: target, evidence: `channel:${name}`, channel: next }), result: { channel: next, duplicate: false } }; + // A caller assertion or a file path is not proof that the old + // session wrote its state; no verified adapter exists yet. + throw new Error("old-session state verification unavailable; cutover disabled"); } else throw new Error("unknown channel operation"); } From 585a3af94bde09169ea0ec663f57128296c93a35 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:54:27 +0000 Subject: [PATCH 019/113] Prepare private handover state proof verification --- docs/design/plexus-channels.md | 6 ++++ .../tmux-bridge/bin/handover-state-proof.mjs | 28 +++++++++++++++++++ .../test/handover-state-proof.test.mjs | 25 +++++++++++++++++ scripts/mesh-readiness.mjs | 1 + .../agent-tmux/bin/handover-state-proof.mjs | 28 +++++++++++++++++++ 5 files changed, 88 insertions(+) create mode 100644 packages/tmux-bridge/bin/handover-state-proof.mjs create mode 100644 packages/tmux-bridge/test/handover-state-proof.test.mjs create mode 100644 skills/agent-tmux/bin/handover-state-proof.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 47e4ed96..a2dcd236 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -21,6 +21,12 @@ caller is responsible for verifying transport receipts before recording them. Handover completion is disabled until an adapter can verify that the old session wrote its state. A path or caller assertion is not sufficient proof. +`handover-state-proof.mjs` prepares the file-verification part: it binds a +correlated actor response to a session, nonce, filename and SHA-256, and checks +the private file without following a final symlink. It does not authenticate the +response, parse the state format, or invoke a session; a future adapter must +obtain that response from the correlated native transport and verify its own +state-format contract before enabling cutover. The prepared Codex path additionally requires a fresh unarchived native-thread observation and exactly one detected writer. Claude and cloud successors are not yet supported by this operation. diff --git a/packages/tmux-bridge/bin/handover-state-proof.mjs b/packages/tmux-bridge/bin/handover-state-proof.mjs new file mode 100644 index 00000000..823bdf09 --- /dev/null +++ b/packages/tmux-bridge/bin/handover-state-proof.mjs @@ -0,0 +1,28 @@ +/** Verify an actor's correlated response against a private state file. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join } from 'node:path'; + +// The caller must obtain response from the native correlated-result transport, +// bound to session and nonce. This function cannot authenticate arbitrary text. +export async function verifyStateResponse({ session, nonce, response, root, filename }) { + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce) || !isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); + const rootInfo = await lstat(root); + if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); + if (typeof response !== 'string' || Buffer.byteLength(response) > 8192) throw new Error('invalid state response'); + let attestation; + try { attestation = JSON.parse(response); } catch { throw new Error('invalid state response'); } + if (!attestation || attestation.schema !== 'agent-mesh.handover-state.v1' || attestation.session !== session || attestation.nonce !== nonce || attestation.filename !== filename || !/^[0-9a-f]{64}$/.test(attestation.sha256)) throw new Error('state response binding mismatch'); + const file = await open(join(root, filename), constants.O_RDONLY | constants.O_NOFOLLOW); + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 1024 * 1024) throw new Error('invalid state file'); + const bytes = await file.readFile(); + const after = await file.stat(); + if (before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('state file changed during verification'); + const digest = createHash('sha256').update(bytes).digest('hex'); + if (digest !== attestation.sha256) throw new Error('state file digest mismatch'); + return { schema: attestation.schema, session, nonce, filename, sha256: digest, bytes: bytes.length }; + } finally { await file.close(); } +} diff --git a/packages/tmux-bridge/test/handover-state-proof.test.mjs b/packages/tmux-bridge/test/handover-state-proof.test.mjs new file mode 100644 index 00000000..7dd205b3 --- /dev/null +++ b/packages/tmux-bridge/test/handover-state-proof.test.mjs @@ -0,0 +1,25 @@ +import assert from 'node:assert/strict'; +import { createHash } from 'node:crypto'; +import { chmod, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import test from 'node:test'; +import { verifyStateResponse } from '../bin/handover-state-proof.mjs'; + +test('state proof binds correlated response to private file bytes', async (t) => { + const root = await mkdtemp(join(tmpdir(), 'state-proof-')); + t.after(() => rm(root, { recursive: true, force: true })); + const session = 'codex:22222222-2222-4222-8222-222222222222', filename = 'state.yaml', nonce = 'attempt-1'; + const content = 'version: 1\nnext: example\n'; + await writeFile(join(root, filename), content, { mode: 0o600 }); + const response = { schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }; + const verify = (overrides = {}) => verifyStateResponse({ session, nonce, filename, root, response: JSON.stringify(response), ...overrides }); + assert.equal((await verify()).bytes, Buffer.byteLength(content)); + await assert.rejects(verify({ nonce: 'other' }), /binding/); + await writeFile(join(root, filename), 'changed', { mode: 0o600 }); + await assert.rejects(verify(), /digest/); + await chmod(join(root, filename), 0o644); + await assert.rejects(verify(), /invalid state file/); + await symlink(filename, join(root, 'alias.yaml')); + await assert.rejects(verify({ filename: 'alias.yaml', response: JSON.stringify({ ...response, filename: 'alias.yaml' }) })); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index 90c8c323..41303ec8 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -41,6 +41,7 @@ const agentTmuxBundleFiles = [ "bin/mesh-graph.mjs", "bin/plexus.mjs", "bin/channel-state.mjs", + "bin/handover-state-proof.mjs", "bin/ledger-view.mjs", "bin/session-catalog.mjs", "bin/session-links.mjs", diff --git a/skills/agent-tmux/bin/handover-state-proof.mjs b/skills/agent-tmux/bin/handover-state-proof.mjs new file mode 100644 index 00000000..823bdf09 --- /dev/null +++ b/skills/agent-tmux/bin/handover-state-proof.mjs @@ -0,0 +1,28 @@ +/** Verify an actor's correlated response against a private state file. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join } from 'node:path'; + +// The caller must obtain response from the native correlated-result transport, +// bound to session and nonce. This function cannot authenticate arbitrary text. +export async function verifyStateResponse({ session, nonce, response, root, filename }) { + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce) || !isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); + const rootInfo = await lstat(root); + if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); + if (typeof response !== 'string' || Buffer.byteLength(response) > 8192) throw new Error('invalid state response'); + let attestation; + try { attestation = JSON.parse(response); } catch { throw new Error('invalid state response'); } + if (!attestation || attestation.schema !== 'agent-mesh.handover-state.v1' || attestation.session !== session || attestation.nonce !== nonce || attestation.filename !== filename || !/^[0-9a-f]{64}$/.test(attestation.sha256)) throw new Error('state response binding mismatch'); + const file = await open(join(root, filename), constants.O_RDONLY | constants.O_NOFOLLOW); + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 1024 * 1024) throw new Error('invalid state file'); + const bytes = await file.readFile(); + const after = await file.stat(); + if (before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('state file changed during verification'); + const digest = createHash('sha256').update(bytes).digest('hex'); + if (digest !== attestation.sha256) throw new Error('state file digest mismatch'); + return { schema: attestation.schema, session, nonce, filename, sha256: digest, bytes: bytes.length }; + } finally { await file.close(); } +} From 0b2cd85d094103c3f4ec77dde458f8b8c0a21da0 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:57:11 +0000 Subject: [PATCH 020/113] Bind handover state proof to native session reply --- docs/design/plexus-channels.md | 8 +++--- .../tmux-bridge/bin/handover-state-proof.mjs | 26 ++++++++++++++++++- .../test/handover-state-proof.test.mjs | 21 ++++++++++++++- .../agent-tmux/bin/handover-state-proof.mjs | 26 ++++++++++++++++++- 4 files changed, 74 insertions(+), 7 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index a2dcd236..2fdc068e 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -23,10 +23,10 @@ Handover completion is disabled until an adapter can verify that the old session wrote its state. A path or caller assertion is not sufficient proof. `handover-state-proof.mjs` prepares the file-verification part: it binds a correlated actor response to a session, nonce, filename and SHA-256, and checks -the private file without following a final symlink. It does not authenticate the -response, parse the state format, or invoke a session; a future adapter must -obtain that response from the correlated native transport and verify its own -state-format contract before enabling cutover. +the private file without following a final symlink. `requestStateProof` obtains +the response through the existing native correlated-result transport; Codex +resume remains disabled. The verifier does not parse the state format or make a +graph cutover. A caller must verify its state-format contract before proceeding. The prepared Codex path additionally requires a fresh unarchived native-thread observation and exactly one detected writer. Claude and cloud successors are not yet supported by this operation. diff --git a/packages/tmux-bridge/bin/handover-state-proof.mjs b/packages/tmux-bridge/bin/handover-state-proof.mjs index 823bdf09..eca3f268 100644 --- a/packages/tmux-bridge/bin/handover-state-proof.mjs +++ b/packages/tmux-bridge/bin/handover-state-proof.mjs @@ -2,7 +2,31 @@ import { constants } from 'node:fs'; import { lstat, open, realpath } from 'node:fs/promises'; import { createHash } from 'node:crypto'; -import { isAbsolute, join } from 'node:path'; +import { randomUUID } from 'node:crypto'; +import { execFile } from 'node:child_process'; +import { promisify } from 'node:util'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); +const exec = promisify(execFile); + +/** Obtain a correlated native-session result, then bind it to file bytes. */ +export async function requestStateProof({ session, root, filename, managedInboxRoot }, runNative = exec) { + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !isAbsolute(root) || /[\r\n\x00]/.test(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); + const rootInfo = await lstat(root); + if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); + const [agent, nativeId] = session.split(':'); + if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); + const nonce = `handover-${randomUUID()}`; + const message = `Write your handover state in the configured format to ${join(root, filename)} with private permissions. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; + const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message', message]; + if (agent === 'codex') argv.push('--no-resume'); + if (agent === 'claude') argv.push('--managed-inbox-root', managedInboxRoot); + const result = await runNative(process.execPath, argv, { timeout: 125000, maxBuffer: 8192 }); + if (!result || typeof result.stdout !== 'string') throw new Error('native result unavailable'); + return verifyStateResponse({ session, nonce, response: result.stdout, root, filename }); +} // The caller must obtain response from the native correlated-result transport, // bound to session and nonce. This function cannot authenticate arbitrary text. diff --git a/packages/tmux-bridge/test/handover-state-proof.test.mjs b/packages/tmux-bridge/test/handover-state-proof.test.mjs index 7dd205b3..ac3fcf6d 100644 --- a/packages/tmux-bridge/test/handover-state-proof.test.mjs +++ b/packages/tmux-bridge/test/handover-state-proof.test.mjs @@ -4,7 +4,7 @@ import { chmod, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import test from 'node:test'; -import { verifyStateResponse } from '../bin/handover-state-proof.mjs'; +import { requestStateProof, verifyStateResponse } from '../bin/handover-state-proof.mjs'; test('state proof binds correlated response to private file bytes', async (t) => { const root = await mkdtemp(join(tmpdir(), 'state-proof-')); @@ -23,3 +23,22 @@ test('state proof binds correlated response to private file bytes', async (t) => await symlink(filename, join(root, 'alias.yaml')); await assert.rejects(verify({ filename: 'alias.yaml', response: JSON.stringify({ ...response, filename: 'alias.yaml' }) })); }); + +test('native request binds response to its own correlation without resuming', async (t) => { + const root = await mkdtemp(join(tmpdir(), 'state-native-')); + t.after(() => rm(root, { recursive: true, force: true })); + const session = 'codex:22222222-2222-4222-8222-222222222222', filename = 'state.yaml'; + const fake = async (binary, argv) => { + assert.equal(binary, process.execPath); + assert.ok(argv.includes('--no-resume')); + const nonce = argv[argv.indexOf('--correlation-id') + 1]; + const content = 'version: 1\n'; + await writeFile(join(root, filename), content, { mode: 0o600 }); + return { stdout: JSON.stringify({ schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }) }; + }; + const proof = await requestStateProof({ session, root, filename }, fake); + assert.equal(proof.session, session); + assert.ok(proof.nonce.startsWith('handover-')); + await assert.rejects(requestStateProof({ session, root, filename }, async () => ({ stdout: JSON.stringify({ status: 'held' }) })), /binding/); + await assert.rejects(requestStateProof({ session, root, filename }, async () => { throw new Error('timeout'); }), /timeout/); +}); diff --git a/skills/agent-tmux/bin/handover-state-proof.mjs b/skills/agent-tmux/bin/handover-state-proof.mjs index 823bdf09..eca3f268 100644 --- a/skills/agent-tmux/bin/handover-state-proof.mjs +++ b/skills/agent-tmux/bin/handover-state-proof.mjs @@ -2,7 +2,31 @@ import { constants } from 'node:fs'; import { lstat, open, realpath } from 'node:fs/promises'; import { createHash } from 'node:crypto'; -import { isAbsolute, join } from 'node:path'; +import { randomUUID } from 'node:crypto'; +import { execFile } from 'node:child_process'; +import { promisify } from 'node:util'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); +const exec = promisify(execFile); + +/** Obtain a correlated native-session result, then bind it to file bytes. */ +export async function requestStateProof({ session, root, filename, managedInboxRoot }, runNative = exec) { + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !isAbsolute(root) || /[\r\n\x00]/.test(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); + const rootInfo = await lstat(root); + if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); + const [agent, nativeId] = session.split(':'); + if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); + const nonce = `handover-${randomUUID()}`; + const message = `Write your handover state in the configured format to ${join(root, filename)} with private permissions. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; + const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message', message]; + if (agent === 'codex') argv.push('--no-resume'); + if (agent === 'claude') argv.push('--managed-inbox-root', managedInboxRoot); + const result = await runNative(process.execPath, argv, { timeout: 125000, maxBuffer: 8192 }); + if (!result || typeof result.stdout !== 'string') throw new Error('native result unavailable'); + return verifyStateResponse({ session, nonce, response: result.stdout, root, filename }); +} // The caller must obtain response from the native correlated-result transport, // bound to session and nonce. This function cannot authenticate arbitrary text. From 32c2ce7554a3ec005173c57a22c3531e26035aad Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:02:48 +0000 Subject: [PATCH 021/113] Require private graph state for channel queues --- docs/design/plexus-channels.md | 3 +++ packages/tmux-bridge/bin/mesh-graph.mjs | 13 +++++++++++++ .../test/plexus-channel-store.test.mjs | 17 ++++++++++++++++- skills/agent-tmux/bin/mesh-graph.mjs | 13 +++++++++++++ 4 files changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 2fdc068e..694b5f1d 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -13,6 +13,9 @@ The graph command now persists channel creation, enqueue and handover start as events under the graph writer lock. Queued messages survive replay and compaction. The graph and event log contain message bodies and must remain private; this is not a scoped remote API. +Channel operations reject a non-private or non-canonical graph directory and +reject existing graph, checkpoint, snapshot or event files with unsafe owner, +permissions, links or file type. They do not silently repair existing state. The graph command can also reserve a pending message and record a matching acceptance receipt. Reservation is durable before transport; a crash or diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index d5cc6a8d..4905aa94 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -18,6 +18,7 @@ import { readFileSync, readSync, readlinkSync, + realpathSync, renameSync, rmSync, statSync, @@ -137,6 +138,7 @@ try { switch (command) { case "channel": { const name = requiredSingleLine(values.name, "--name"); + assertPrivateChannelState(stateDir); if (subcommand === "get") { const channel = (loadGraph(stateDir).channels || []).find((item) => item.id === name); if (!channel) throw new Error("unknown channel"); @@ -144,6 +146,7 @@ try { break; } const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); const current = (graph.channels || []).find((item) => item.id === name); let next; @@ -1481,6 +1484,16 @@ function ensureStateDir(statePath) { mkdirSync(statePath, { recursive: true, mode: 0o700 }); } +function assertPrivateChannelState(statePath) { + const root = lstatSync(statePath); + if (!root.isDirectory() || root.isSymbolicLink() || root.uid !== process.getuid() || (root.mode & 0o077) !== 0 || realpathSync(statePath) !== resolve(statePath)) throw new Error("channel graph directory must be private and canonical"); + for (const name of ["events.jsonl", "graph.json", "checkpoint.json", "snapshot.json"]) { + const file = join(statePath, name); + const info = lstatSync(file, { throwIfNoEntry: false }); + if (info && (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0)) throw new Error(`channel graph file must be private: ${name}`); + } +} + function acquireLock(statePath) { const lock = join(statePath, "graph.lock"); const deadline = Date.now() + 5_000; diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index 956e188f..2fb73ec8 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { execFile } from 'node:child_process'; -import { appendFile, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { appendFile, chmod, mkdtemp, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -9,6 +9,21 @@ import test from 'node:test'; const exec = promisify(execFile); const bin = fileURLToPath(new URL('../bin/mesh-graph.mjs', import.meta.url)); +test('channel operations reject a graph with non-private persisted files', async (t) => { + const state = await mkdtemp(join(tmpdir(), 'channel-permissions-')); + t.after(() => rm(state, { recursive: true, force: true })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args])).stdout); + const uuid = '22222222-2222-4222-8222-222222222222'; + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${uuid}`); + await chmod(join(state, 'events.jsonl'), 0o644); + await assert.rejects(call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'private'), /must be private/); + await assert.rejects(call('channel', 'get', '--name', 'example'), /must be private/); + await chmod(join(state, 'events.jsonl'), 0o600); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue.length, 0); +}); + test('channel and queued messages survive concurrent writers, replay and compaction', async (t) => { const state = await mkdtemp(join(tmpdir(), 'channel-store-')); t.after(() => rm(state, { recursive: true, force: true })); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index d5cc6a8d..4905aa94 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -18,6 +18,7 @@ import { readFileSync, readSync, readlinkSync, + realpathSync, renameSync, rmSync, statSync, @@ -137,6 +138,7 @@ try { switch (command) { case "channel": { const name = requiredSingleLine(values.name, "--name"); + assertPrivateChannelState(stateDir); if (subcommand === "get") { const channel = (loadGraph(stateDir).channels || []).find((item) => item.id === name); if (!channel) throw new Error("unknown channel"); @@ -144,6 +146,7 @@ try { break; } const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); const current = (graph.channels || []).find((item) => item.id === name); let next; @@ -1481,6 +1484,16 @@ function ensureStateDir(statePath) { mkdirSync(statePath, { recursive: true, mode: 0o700 }); } +function assertPrivateChannelState(statePath) { + const root = lstatSync(statePath); + if (!root.isDirectory() || root.isSymbolicLink() || root.uid !== process.getuid() || (root.mode & 0o077) !== 0 || realpathSync(statePath) !== resolve(statePath)) throw new Error("channel graph directory must be private and canonical"); + for (const name of ["events.jsonl", "graph.json", "checkpoint.json", "snapshot.json"]) { + const file = join(statePath, name); + const info = lstatSync(file, { throwIfNoEntry: false }); + if (info && (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0)) throw new Error(`channel graph file must be private: ${name}`); + } +} + function acquireLock(statePath) { const lock = join(statePath, "graph.lock"); const deadline = Date.now() + 5_000; From 9b3f97920d42a41492fc0706ea3c09a9513106d9 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:05:29 +0000 Subject: [PATCH 022/113] Accept prefixed channel identifiers --- docs/design/plexus-channels.md | 1 + packages/tmux-bridge/bin/channel-state.mjs | 3 ++- .../tmux-bridge/test/agent-waker-channel.test.py | 8 ++++---- packages/tmux-bridge/test/channel-state.test.mjs | 2 ++ .../tmux-bridge/test/plexus-channel-store.test.mjs | 14 +++++++------- skills/agent-tmux/bin/channel-state.mjs | 3 ++- 6 files changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 694b5f1d..0375fe68 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -8,6 +8,7 @@ implemented components from planned links. Keep its source in current session and a queue. An in-flight message is bound to a session and generation. A handover stops new dispatch and cannot finish while a delivery is unresolved. Only a matching acceptance receipt resolves an in-flight message. +Channel identifiers may start with `#`; the prefix is part of the identifier. The graph command now persists channel creation, enqueue and handover start as events under the graph writer lock. Queued messages survive replay and diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 21eba0c2..7d2216a8 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -1,9 +1,10 @@ /** Pure channel transitions. A host must persist each transition atomically. */ const identifier = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); +const channelIdentifier = (value) => typeof value === 'string' && /^#?[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); const copy = (state) => structuredClone(state); export function createChannel(id, session) { - if (!identifier(id) || !identifier(session)) throw new Error('invalid channel or session'); + if (!channelIdentifier(id) || !identifier(session)) throw new Error('invalid channel or session'); return { schema: 'agent-mesh.channel.v1', id, session, generation: 1, phase: 'active', queue: [] }; } diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index 874cc415..88612cb9 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -80,13 +80,13 @@ def call(*args): return json.loads(subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], check=True, capture_output=True, text=True).stdout) call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') call('migrate', '--apply', '--json') - call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') - call('channel', 'begin-handover', '--name', 'example') - args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + call('channel', 'create', '--name', '#example', '--session', f'codex:{uuid}') + call('channel', 'begin-handover', '--name', '#example') + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='#example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): self.assertEqual(waker.run(args), 0) deliver.assert_not_called() - channel = call('channel', 'get', '--name', 'example')['channel'] + channel = call('channel', 'get', '--name', '#example')['channel'] self.assertEqual(channel['phase'], 'handover') self.assertEqual(channel['queue'][0]['state'], 'pending') self.assertEqual(json.loads(Path(args.state).read_text())['pending'], []) diff --git a/packages/tmux-bridge/test/channel-state.test.mjs b/packages/tmux-bridge/test/channel-state.test.mjs index e8a79840..c2b4b070 100644 --- a/packages/tmux-bridge/test/channel-state.test.mjs +++ b/packages/tmux-bridge/test/channel-state.test.mjs @@ -3,6 +3,8 @@ import test from 'node:test'; import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, finishHandover } from '../bin/channel-state.mjs'; test('handover queues work and never reroutes an uncertain delivery', () => { + assert.equal(createChannel('#example', 'session:one').id, '#example'); + assert.throws(() => createChannel('#', 'session:one'), /invalid/); let channel = createChannel('example', 'session:one'); channel = enqueue(channel, 'message-1', 'hello'); channel = enqueue(channel, 'message-0', 'second'); diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index 2fb73ec8..0dcc2a2c 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -31,18 +31,18 @@ test('channel and queued messages survive concurrent writers, replay and compact const uuid = '22222222-2222-4222-8222-222222222222'; await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); await call('migrate', '--apply', '--json'); - await call('channel', 'create', '--name', 'example', '--session', `codex:${uuid}`); - await call('channel', 'begin-handover', '--name', 'example'); - await Promise.all(['one', 'two'].map(id => call('channel', 'enqueue', '--name', 'example', '--id', id, '--input', id))); - assert.equal((await call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'one')).duplicate, true); - await assert.rejects(call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'changed'), /conflict/); + await call('channel', 'create', '--name', '#example', '--session', `codex:${uuid}`); + await call('channel', 'begin-handover', '--name', '#example'); + await Promise.all(['one', 'two'].map(id => call('channel', 'enqueue', '--name', '#example', '--id', id, '--input', id))); + assert.equal((await call('channel', 'enqueue', '--name', '#example', '--id', 'one', '--input', 'one')).duplicate, true); + await assert.rejects(call('channel', 'enqueue', '--name', '#example', '--id', 'one', '--input', 'changed'), /conflict/); await rm(join(state, 'checkpoint.json')); - let channel = (await call('channel', 'get', '--name', 'example')).channel; + let channel = (await call('channel', 'get', '--name', '#example')).channel; assert.equal(channel.phase, 'handover'); assert.deepEqual(channel.queue.map(row => row.id).sort(), ['one', 'two']); await call('compact', '--all-history', '--apply', '--json'); await rm(join(state, 'checkpoint.json'), { force: true }); - channel = (await call('channel', 'get', '--name', 'example')).channel; + channel = (await call('channel', 'get', '--name', '#example')).channel; assert.deepEqual(channel.queue.map(row => row.id).sort(), ['one', 'two']); }); diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 21eba0c2..7d2216a8 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -1,9 +1,10 @@ /** Pure channel transitions. A host must persist each transition atomically. */ const identifier = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); +const channelIdentifier = (value) => typeof value === 'string' && /^#?[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); const copy = (state) => structuredClone(state); export function createChannel(id, session) { - if (!identifier(id) || !identifier(session)) throw new Error('invalid channel or session'); + if (!channelIdentifier(id) || !identifier(session)) throw new Error('invalid channel or session'); return { schema: 'agent-mesh.channel.v1', id, session, generation: 1, phase: 'active', queue: [] }; } From b362a69f8835d061212598cc3152e46cd925fca7 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:09:30 +0000 Subject: [PATCH 023/113] Pass channel payloads to adapters through stdin --- .../tmux-bridge/bin/agent-native-call.mjs | 21 +++++++++++++++++-- packages/tmux-bridge/bin/agent-waker.py | 19 +++++++++++------ packages/tmux-bridge/bin/mesh-graph.mjs | 19 +++++++++++++++-- packages/tmux-bridge/docs/agent-waker.md | 4 ++++ .../test/agent-waker-channel.test.py | 9 ++++++++ .../tmux-bridge/test/native-stdin.test.mjs | 16 ++++++++++++++ skills/agent-tmux/bin/agent-native-call.mjs | 21 +++++++++++++++++-- skills/agent-tmux/bin/agent-waker.py | 19 +++++++++++------ skills/agent-tmux/bin/mesh-graph.mjs | 19 +++++++++++++++-- 9 files changed, 127 insertions(+), 20 deletions(-) create mode 100644 packages/tmux-bridge/test/native-stdin.test.mjs diff --git a/packages/tmux-bridge/bin/agent-native-call.mjs b/packages/tmux-bridge/bin/agent-native-call.mjs index 558bb24f..cd784f76 100755 --- a/packages/tmux-bridge/bin/agent-native-call.mjs +++ b/packages/tmux-bridge/bin/agent-native-call.mjs @@ -4,6 +4,7 @@ import { commsLease } from "./comms-client.mjs"; import { createHash } from "node:crypto"; import { execFile } from "node:child_process"; +import { readSync } from "node:fs"; import { access, open, readdir, stat } from "node:fs/promises"; import { homedir } from "node:os"; import { join, resolve } from "node:path"; @@ -30,6 +31,7 @@ const { values } = parseArgs({ goal: { type: "string" }, "goal-resume": { type: "string", default: "blocked" }, message: { type: "string" }, + "message-stdin": { type: "boolean", default: false }, "managed-inbox-root": { type: "string" }, help: { type: "boolean", short: "h", default: false } }, @@ -37,14 +39,15 @@ const { values } = parseArgs({ }); if (values.help) { - console.log("Usage: agent-native-call.mjs --agent codex|claude --session --correlation-id --message [--timeout ] [--resume (Codex only)] [--cloud --delivery-only (Claude cloud only)] [--steer-or-queue (Codex only)] [--goal TEXT (Codex, local Claude)] [--goal-resume blocked|any|off (Codex only)] [--delivery-only]"); + console.log("Usage: agent-native-call.mjs --agent codex|claude --session --correlation-id (--message | --message-stdin) [--timeout ] [--resume (Codex only)] [--cloud --delivery-only (Claude cloud only)] [--steer-or-queue (Codex only)] [--goal TEXT (Codex, local Claude)] [--goal-resume blocked|any|off (Codex only)] [--delivery-only]"); process.exit(0); } const agent = required(values.agent, "--agent"); const sessionId = required(values.session, "--session"); const correlationId = required(values["correlation-id"], "--correlation-id"); -const message = required(values.message, "--message"); +if (values["message-stdin"] && values.message !== undefined) fail("--message and --message-stdin are mutually exclusive", 2); +const message = values["message-stdin"] ? required(readMessageStdin(), "--message-stdin") : required(values.message, "--message"); const timeoutSeconds = Number(values.timeout); if (agent !== "codex" && agent !== "claude") fail(`native active-session calls are not implemented for agent ${agent}`, 2); if (values.resume && values["no-resume"]) fail("--resume and --no-resume are mutually exclusive", 2); @@ -272,6 +275,20 @@ function finish(bodies, begin, end) { process.exit(0); } +function readMessageStdin() { + const max = 65536, chunks = []; + let total = 0; + for (;;) { + const chunk = Buffer.allocUnsafe(Math.min(4096, max + 1 - total)); + const count = readSync(0, chunk, 0, chunk.length, null); + if (!count) break; + total += count; + if (total > max) fail("stdin message too large", 2); + chunks.push(chunk.subarray(0, count)); + } + return Buffer.concat(chunks).toString("utf8"); +} + function messageText(record, role) { const payload = record?.payload; if (record?.type === "event_msg") { diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index 1234390b..9ed4599f 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -116,9 +116,10 @@ def compose(job: str, pending: list[dict[str, Any]], errors: list[Any]) -> str: return "\n".join(lines) -def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False) -> int: +def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False) -> int: command = ["node", str(BIN / "agent-native-call.mjs"), "--agent", agent, "--session", session, - "--correlation-id", correlation, "--timeout", "5", "--message", message] + "--correlation-id", correlation, "--timeout", "5"] + command += ["--message-stdin"] if message_stdin else ["--message", message] if resume: if agent != "codex": raise ValueError("waker resume is supported only for Codex") @@ -127,7 +128,7 @@ def deliver(agent: str, session: str, correlation: str, message: str, inbox_root command += ["--delivery-only"] if inbox_root: command += ["--managed-inbox-root", inbox_root] - result = subprocess.run(command, text=True, capture_output=True) + result = subprocess.run(command, text=True, capture_output=True, **({"input": message} if message_stdin else {})) try: receipt = json.loads(result.stdout) except (ValueError, TypeError): @@ -162,8 +163,14 @@ def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dic command = ['node', str(BIN / 'mesh-graph.mjs')] if args.graph_state: command += ['--state', args.graph_state] - command += ['channel', operation, '--name', args.channel, *options] - result = subprocess.run(command, text=True, capture_output=True, timeout=30, check=True) + arguments = list(options) + payload = None + if '--input' in arguments: + index = arguments.index('--input') + 1 + payload = arguments[index] + arguments[index] = '-' + command += ['channel', operation, '--name', args.channel, *arguments] + result = subprocess.run(command, input=payload, text=True, capture_output=True, timeout=30, check=True) value = json.loads(result.stdout) if not isinstance(value, dict) or not isinstance(value.get('channel'), dict): raise ValueError('invalid channel response') @@ -231,7 +238,7 @@ def run_channel(args: argparse.Namespace) -> int: if not sep or agent not in ('codex', 'claude'): raise ValueError('unsupported channel recipient') code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, - True, resume=args.resume and agent == 'codex') + True, resume=args.resume and agent == 'codex', message_stdin=True) if code != 0: print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'delivery unconfirmed'})) return 3 diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 4905aa94..e21b1d3b 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -138,6 +138,7 @@ try { switch (command) { case "channel": { const name = requiredSingleLine(values.name, "--name"); + const channelInput = values.input === "-" ? readBoundedChannelInput() : values.input; assertPrivateChannelState(stateDir); if (subcommand === "get") { const channel = (loadGraph(stateDir).channels || []).find((item) => item.id === name); @@ -157,9 +158,9 @@ try { next = createChannel(name, session); } else { if (!current) throw new Error("unknown channel"); - if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), values.input); + if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), channelInput); else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id")); - else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(values.input, "--input"))); + else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "finish-handover") { const target = requiredSingleLine(values.to, "--to"); @@ -1484,6 +1485,20 @@ function ensureStateDir(statePath) { mkdirSync(statePath, { recursive: true, mode: 0o700 }); } +function readBoundedChannelInput() { + const max = 65536, chunks = []; + let total = 0; + while (true) { + const chunk = Buffer.allocUnsafe(Math.min(4096, max + 1 - total)); + const count = readSync(0, chunk, 0, chunk.length, null); + if (!count) break; + total += count; + if (total > max) throw new Error("channel input too large"); + chunks.push(chunk.subarray(0, count)); + } + return Buffer.concat(chunks).toString("utf8"); +} + function assertPrivateChannelState(statePath) { const root = lstatSync(statePath); if (!root.isDirectory() || root.isSymbolicLink() || root.uid !== process.getuid() || (root.mode & 0o077) !== 0 || realpathSync(statePath) !== resolve(statePath)) throw new Error("channel graph directory must be private and canonical"); diff --git a/packages/tmux-bridge/docs/agent-waker.md b/packages/tmux-bridge/docs/agent-waker.md index 69796d8a..eafe22a4 100644 --- a/packages/tmux-bridge/docs/agent-waker.md +++ b/packages/tmux-bridge/docs/agent-waker.md @@ -36,6 +36,10 @@ queued. The first pending message is reserved before invoking the native transport; an unconfirmed delivery stays in flight and requires reconciliation. The native bound queue receipt is checked before the graph records acceptance. Channel delivery does not establish that the receiving actor read the message. +Channel payloads reach the graph and native transport adapter on standard input. +The existing Codex queue transport still passes its message as a downstream +CLI argument; do not treat this change as eliminating every process-argument +exposure. The channel mode and handover are not yet enabled in existing timers. Delivery-only acknowledgement requires native JSON `status: queued`, matching diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index 88612cb9..8360538f 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -17,6 +17,15 @@ class ChannelWakerTest(unittest.TestCase): + def test_native_adapter_receives_message_on_stdin(self): + from unittest.mock import Mock + receipt = {'status': 'queued', 'agent': 'codex', 'sessionId': uuid, 'correlationId': 'message-1'} + with patch.object(waker.subprocess, 'run', return_value=Mock(returncode=0, stdout=json.dumps(receipt))) as run: + self.assertEqual(waker.deliver('codex', uuid, 'message-1', 'private fixture', None, True, message_stdin=True), 0) + self.assertNotIn('private fixture', run.call_args.args[0]) + self.assertIn('--message-stdin', run.call_args.args[0]) + self.assertEqual(run.call_args.kwargs['input'], 'private fixture') + def test_lost_reservation_response_does_not_send_or_retry(self): with tempfile.TemporaryDirectory() as directory: state = Path(directory) / 'graph' diff --git a/packages/tmux-bridge/test/native-stdin.test.mjs b/packages/tmux-bridge/test/native-stdin.test.mjs new file mode 100644 index 00000000..b71e2f09 --- /dev/null +++ b/packages/tmux-bridge/test/native-stdin.test.mjs @@ -0,0 +1,16 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; +import test from 'node:test'; +const bin = fileURLToPath(new URL('../bin/agent-native-call.mjs', import.meta.url)); + +test('native transport parses bounded stdin before rejecting unsupported agent', () => { + const args = [bin, '--agent', 'fixture', '--session', 'fixture', '--correlation-id', 'fixture', '--message-stdin']; + const valid = spawnSync(process.execPath, args, { input: 'private fixture', encoding: 'utf8' }); + assert.notEqual(valid.status, 0); + assert.match(valid.stderr, /not implemented/); + assert.ok(!valid.stderr.includes('private fixture')); + const oversized = spawnSync(process.execPath, args, { input: 'x'.repeat(65537), encoding: 'utf8' }); + assert.notEqual(oversized.status, 0); + assert.match(oversized.stderr, /stdin message too large/); +}); diff --git a/skills/agent-tmux/bin/agent-native-call.mjs b/skills/agent-tmux/bin/agent-native-call.mjs index 558bb24f..cd784f76 100755 --- a/skills/agent-tmux/bin/agent-native-call.mjs +++ b/skills/agent-tmux/bin/agent-native-call.mjs @@ -4,6 +4,7 @@ import { commsLease } from "./comms-client.mjs"; import { createHash } from "node:crypto"; import { execFile } from "node:child_process"; +import { readSync } from "node:fs"; import { access, open, readdir, stat } from "node:fs/promises"; import { homedir } from "node:os"; import { join, resolve } from "node:path"; @@ -30,6 +31,7 @@ const { values } = parseArgs({ goal: { type: "string" }, "goal-resume": { type: "string", default: "blocked" }, message: { type: "string" }, + "message-stdin": { type: "boolean", default: false }, "managed-inbox-root": { type: "string" }, help: { type: "boolean", short: "h", default: false } }, @@ -37,14 +39,15 @@ const { values } = parseArgs({ }); if (values.help) { - console.log("Usage: agent-native-call.mjs --agent codex|claude --session --correlation-id --message [--timeout ] [--resume (Codex only)] [--cloud --delivery-only (Claude cloud only)] [--steer-or-queue (Codex only)] [--goal TEXT (Codex, local Claude)] [--goal-resume blocked|any|off (Codex only)] [--delivery-only]"); + console.log("Usage: agent-native-call.mjs --agent codex|claude --session --correlation-id (--message | --message-stdin) [--timeout ] [--resume (Codex only)] [--cloud --delivery-only (Claude cloud only)] [--steer-or-queue (Codex only)] [--goal TEXT (Codex, local Claude)] [--goal-resume blocked|any|off (Codex only)] [--delivery-only]"); process.exit(0); } const agent = required(values.agent, "--agent"); const sessionId = required(values.session, "--session"); const correlationId = required(values["correlation-id"], "--correlation-id"); -const message = required(values.message, "--message"); +if (values["message-stdin"] && values.message !== undefined) fail("--message and --message-stdin are mutually exclusive", 2); +const message = values["message-stdin"] ? required(readMessageStdin(), "--message-stdin") : required(values.message, "--message"); const timeoutSeconds = Number(values.timeout); if (agent !== "codex" && agent !== "claude") fail(`native active-session calls are not implemented for agent ${agent}`, 2); if (values.resume && values["no-resume"]) fail("--resume and --no-resume are mutually exclusive", 2); @@ -272,6 +275,20 @@ function finish(bodies, begin, end) { process.exit(0); } +function readMessageStdin() { + const max = 65536, chunks = []; + let total = 0; + for (;;) { + const chunk = Buffer.allocUnsafe(Math.min(4096, max + 1 - total)); + const count = readSync(0, chunk, 0, chunk.length, null); + if (!count) break; + total += count; + if (total > max) fail("stdin message too large", 2); + chunks.push(chunk.subarray(0, count)); + } + return Buffer.concat(chunks).toString("utf8"); +} + function messageText(record, role) { const payload = record?.payload; if (record?.type === "event_msg") { diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index 1234390b..9ed4599f 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -116,9 +116,10 @@ def compose(job: str, pending: list[dict[str, Any]], errors: list[Any]) -> str: return "\n".join(lines) -def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False) -> int: +def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False) -> int: command = ["node", str(BIN / "agent-native-call.mjs"), "--agent", agent, "--session", session, - "--correlation-id", correlation, "--timeout", "5", "--message", message] + "--correlation-id", correlation, "--timeout", "5"] + command += ["--message-stdin"] if message_stdin else ["--message", message] if resume: if agent != "codex": raise ValueError("waker resume is supported only for Codex") @@ -127,7 +128,7 @@ def deliver(agent: str, session: str, correlation: str, message: str, inbox_root command += ["--delivery-only"] if inbox_root: command += ["--managed-inbox-root", inbox_root] - result = subprocess.run(command, text=True, capture_output=True) + result = subprocess.run(command, text=True, capture_output=True, **({"input": message} if message_stdin else {})) try: receipt = json.loads(result.stdout) except (ValueError, TypeError): @@ -162,8 +163,14 @@ def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dic command = ['node', str(BIN / 'mesh-graph.mjs')] if args.graph_state: command += ['--state', args.graph_state] - command += ['channel', operation, '--name', args.channel, *options] - result = subprocess.run(command, text=True, capture_output=True, timeout=30, check=True) + arguments = list(options) + payload = None + if '--input' in arguments: + index = arguments.index('--input') + 1 + payload = arguments[index] + arguments[index] = '-' + command += ['channel', operation, '--name', args.channel, *arguments] + result = subprocess.run(command, input=payload, text=True, capture_output=True, timeout=30, check=True) value = json.loads(result.stdout) if not isinstance(value, dict) or not isinstance(value.get('channel'), dict): raise ValueError('invalid channel response') @@ -231,7 +238,7 @@ def run_channel(args: argparse.Namespace) -> int: if not sep or agent not in ('codex', 'claude'): raise ValueError('unsupported channel recipient') code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, - True, resume=args.resume and agent == 'codex') + True, resume=args.resume and agent == 'codex', message_stdin=True) if code != 0: print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'delivery unconfirmed'})) return 3 diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 4905aa94..e21b1d3b 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -138,6 +138,7 @@ try { switch (command) { case "channel": { const name = requiredSingleLine(values.name, "--name"); + const channelInput = values.input === "-" ? readBoundedChannelInput() : values.input; assertPrivateChannelState(stateDir); if (subcommand === "get") { const channel = (loadGraph(stateDir).channels || []).find((item) => item.id === name); @@ -157,9 +158,9 @@ try { next = createChannel(name, session); } else { if (!current) throw new Error("unknown channel"); - if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), values.input); + if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), channelInput); else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id")); - else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(values.input, "--input"))); + else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "finish-handover") { const target = requiredSingleLine(values.to, "--to"); @@ -1484,6 +1485,20 @@ function ensureStateDir(statePath) { mkdirSync(statePath, { recursive: true, mode: 0o700 }); } +function readBoundedChannelInput() { + const max = 65536, chunks = []; + let total = 0; + while (true) { + const chunk = Buffer.allocUnsafe(Math.min(4096, max + 1 - total)); + const count = readSync(0, chunk, 0, chunk.length, null); + if (!count) break; + total += count; + if (total > max) throw new Error("channel input too large"); + chunks.push(chunk.subarray(0, count)); + } + return Buffer.concat(chunks).toString("utf8"); +} + function assertPrivateChannelState(statePath) { const root = lstatSync(statePath); if (!root.isDirectory() || root.isSymbolicLink() || root.uid !== process.getuid() || (root.mode & 0o077) !== 0 || realpathSync(statePath) !== resolve(statePath)) throw new Error("channel graph directory must be private and canonical"); From dec1b153bf448d71e550ebe5e8c58b782e564693 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:17:50 +0000 Subject: [PATCH 024/113] Queue channel messages through the local app server --- .../tmux-bridge/bin/agent-native-call.mjs | 35 +++++++++++---- packages/tmux-bridge/bin/agent-waker.py | 2 + packages/tmux-bridge/docs/agent-waker.md | 6 +-- .../test/agent-waker-channel.test.py | 1 + .../test/native-private-queue.test.mjs | 44 +++++++++++++++++++ skills/agent-tmux/bin/agent-native-call.mjs | 35 +++++++++++---- skills/agent-tmux/bin/agent-waker.py | 2 + 7 files changed, 106 insertions(+), 19 deletions(-) create mode 100644 packages/tmux-bridge/test/native-private-queue.test.mjs diff --git a/packages/tmux-bridge/bin/agent-native-call.mjs b/packages/tmux-bridge/bin/agent-native-call.mjs index cd784f76..d851b03c 100755 --- a/packages/tmux-bridge/bin/agent-native-call.mjs +++ b/packages/tmux-bridge/bin/agent-native-call.mjs @@ -13,6 +13,7 @@ import { parseArgs } from "node:util"; import { inspectClaudeSessionOwnership } from "./claude-session-ownership.mjs"; import { goalCommand, liveClaudeSessions, typeClaudeGoal } from "./claude-goal.mjs"; import { GOAL_RESUME_MODES, reconcileCodexGoal } from "./codex-goal.mjs"; +import { withCodexAppServer } from "./codex-app-server.mjs"; let activeComms; let enqueueStarted = false; @@ -153,16 +154,34 @@ if (agent === "codex") { } if (deliveryMethod !== "steer") { enqueueStarted = true; - const queued = await run(process.env.CODEX_BIN || "codex", [ - "queue", "--thread", sessionId, "--message", protocolMessage, ...(resume ? ["--resume"] : []) - ], (timeoutSeconds + 15) * 1000); - if (queued.code !== 0) { - if (codexSessionIsNotDirectlyWritable(queued)) { - fail("Codex spawned sub-agent sessions are readable but do not accept direct queued turns.", 79); + if (values["message-stdin"] && !values["steer-or-queue"]) { + try { + await withCodexAppServer({ clientName: "agent-mesh-channel-queue", timeout: (timeoutSeconds + 15) * 1000, + timeoutMessage: "queue outcome unknown; inspect before retrying" }, async (request) => { + const input = [{ type: "text", text: protocolMessage, text_elements: [] }]; + const response = await request("thread/queue/add", { threadId: sessionId, clientUserMessageId: correlationId, input }); + const entry = response?.queuedSubmission; + if (typeof entry?.id !== "string" || !entry.id || entry.clientUserMessageId !== correlationId || JSON.stringify(entry.input) !== JSON.stringify(input)) throw new Error("queue receipt mismatch"); + if (resume) { + try { await request("thread/resume", { threadId: sessionId }); } + catch { resumeDiagnostic = true; } + } + }); + } catch { + fail("Codex queue outcome uncertain; inspect before retrying", 70); } - fail(safeError("Codex native queue failed", queued), 1); + } else { + const queued = await run(process.env.CODEX_BIN || "codex", [ + "queue", "--thread", sessionId, "--message", protocolMessage, ...(resume ? ["--resume"] : []) + ], (timeoutSeconds + 15) * 1000); + if (queued.code !== 0) { + if (codexSessionIsNotDirectlyWritable(queued)) { + fail("Codex spawned sub-agent sessions are readable but do not accept direct queued turns.", 79); + } + fail(safeError("Codex native queue failed", queued), 1); + } + resumeDiagnostic = Boolean(resume && queued.stderr?.trim()); } - resumeDiagnostic = Boolean(resume && queued.stderr?.trim()); deliveryMethod = "queue"; } } else { diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index 9ed4599f..9fc5bbd3 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -124,6 +124,8 @@ def deliver(agent: str, session: str, correlation: str, message: str, inbox_root if agent != "codex": raise ValueError("waker resume is supported only for Codex") command += ["--resume"] + elif message_stdin and agent == "codex": + command += ["--no-resume"] if delivery_only: command += ["--delivery-only"] if inbox_root: diff --git a/packages/tmux-bridge/docs/agent-waker.md b/packages/tmux-bridge/docs/agent-waker.md index eafe22a4..d7a6887e 100644 --- a/packages/tmux-bridge/docs/agent-waker.md +++ b/packages/tmux-bridge/docs/agent-waker.md @@ -37,9 +37,9 @@ transport; an unconfirmed delivery stays in flight and requires reconciliation. The native bound queue receipt is checked before the graph records acceptance. Channel delivery does not establish that the receiving actor read the message. Channel payloads reach the graph and native transport adapter on standard input. -The existing Codex queue transport still passes its message as a downstream -CLI argument; do not treat this change as eliminating every process-argument -exposure. +The Codex channel path queues via the local app-server protocol, without a +downstream message argument. An uncertain queue outcome is not retried +automatically. Queue acceptance still does not prove the actor read the message. The channel mode and handover are not yet enabled in existing timers. Delivery-only acknowledgement requires native JSON `status: queued`, matching diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index 8360538f..e6495484 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -24,6 +24,7 @@ def test_native_adapter_receives_message_on_stdin(self): self.assertEqual(waker.deliver('codex', uuid, 'message-1', 'private fixture', None, True, message_stdin=True), 0) self.assertNotIn('private fixture', run.call_args.args[0]) self.assertIn('--message-stdin', run.call_args.args[0]) + self.assertIn('--no-resume', run.call_args.args[0]) self.assertEqual(run.call_args.kwargs['input'], 'private fixture') def test_lost_reservation_response_does_not_send_or_retry(self): diff --git a/packages/tmux-bridge/test/native-private-queue.test.mjs b/packages/tmux-bridge/test/native-private-queue.test.mjs new file mode 100644 index 00000000..ead33b6f --- /dev/null +++ b/packages/tmux-bridge/test/native-private-queue.test.mjs @@ -0,0 +1,44 @@ +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import test from 'node:test'; +import { createAppServer } from './fixtures/fake-app-server.mjs'; +const bin = fileURLToPath(new URL('../bin/agent-native-call.mjs', import.meta.url)); +const session = '33333333-3333-4333-8333-333333333333'; + +for (const badReceipt of [false, true]) { + test(`private native queue ${badReceipt ? 'rejects mismatched' : 'accepts bound'} receipt`, async (t) => { + const root = await mkdtemp(join(tmpdir(), 'private-native-')); + t.after(() => rm(root, { recursive: true, force: true })); + const sessions = join(root, 'sessions'); await mkdir(sessions); + await writeFile(join(sessions, `rollout-${session}.jsonl`), JSON.stringify({ type: 'session_meta', payload: { id: session } }) + '\n'); + const seen = []; + const server = createAppServer((message, peer) => { + if (!message.id) return; + if (message.method === 'thread/queue/add') { + seen.push(message); + peer.send({ id: message.id, result: { queuedSubmission: { id: 'queue-1', clientUserMessageId: badReceipt ? 'wrong' : message.params.clientUserMessageId, input: message.params.input } } }); + } else peer.send({ id: message.id, result: {} }); + }); + const socket = join(root, 'server.sock'); + await new Promise(resolve => server.listen(socket, resolve)); + t.after(() => new Promise(resolve => server.close(resolve))); + const env = { ...process.env, CODEX_SESSION_ROOT: sessions, CODEX_REMOTE_SOCK: socket, CODEX_NO_REMOTE: '', CODEX_BIN: '/not-a-real-cli', MESH_COMMS_STATE: join(root, 'comms'), AGENT_FALLBACK_STATE: join(root, 'fallback') }; + delete env.MESH_COMMS_REPLAY_FD; + const child = spawn(process.execPath, [bin, '--agent', 'codex', '--session', session, '--correlation-id', 'fixture-1', '--message-stdin', '--no-resume', '--delivery-only', '--timeout', '3'], { env, stdio: ['pipe', 'pipe', 'pipe'] }); + let stdout = '', stderr = ''; + child.stdout.on('data', data => stdout += data); child.stderr.on('data', data => stderr += data); + child.stdin.end('private fixture'); + const code = await new Promise(resolve => child.on('close', resolve)); + assert.equal(seen.length, 1); + assert.equal(seen[0].params.threadId, session); + assert.equal(seen[0].params.input[0].text, 'private fixture'); + assert.equal(seen[0].params.clientUserMessageId, 'fixture-1'); + assert.ok(!stderr.includes('private fixture')); + if (badReceipt) { assert.notEqual(code, 0); assert.match(stderr, /uncertain/); } + else { assert.equal(code, 0, stderr); assert.equal(JSON.parse(stdout).status, 'queued'); } + }); +} diff --git a/skills/agent-tmux/bin/agent-native-call.mjs b/skills/agent-tmux/bin/agent-native-call.mjs index cd784f76..d851b03c 100755 --- a/skills/agent-tmux/bin/agent-native-call.mjs +++ b/skills/agent-tmux/bin/agent-native-call.mjs @@ -13,6 +13,7 @@ import { parseArgs } from "node:util"; import { inspectClaudeSessionOwnership } from "./claude-session-ownership.mjs"; import { goalCommand, liveClaudeSessions, typeClaudeGoal } from "./claude-goal.mjs"; import { GOAL_RESUME_MODES, reconcileCodexGoal } from "./codex-goal.mjs"; +import { withCodexAppServer } from "./codex-app-server.mjs"; let activeComms; let enqueueStarted = false; @@ -153,16 +154,34 @@ if (agent === "codex") { } if (deliveryMethod !== "steer") { enqueueStarted = true; - const queued = await run(process.env.CODEX_BIN || "codex", [ - "queue", "--thread", sessionId, "--message", protocolMessage, ...(resume ? ["--resume"] : []) - ], (timeoutSeconds + 15) * 1000); - if (queued.code !== 0) { - if (codexSessionIsNotDirectlyWritable(queued)) { - fail("Codex spawned sub-agent sessions are readable but do not accept direct queued turns.", 79); + if (values["message-stdin"] && !values["steer-or-queue"]) { + try { + await withCodexAppServer({ clientName: "agent-mesh-channel-queue", timeout: (timeoutSeconds + 15) * 1000, + timeoutMessage: "queue outcome unknown; inspect before retrying" }, async (request) => { + const input = [{ type: "text", text: protocolMessage, text_elements: [] }]; + const response = await request("thread/queue/add", { threadId: sessionId, clientUserMessageId: correlationId, input }); + const entry = response?.queuedSubmission; + if (typeof entry?.id !== "string" || !entry.id || entry.clientUserMessageId !== correlationId || JSON.stringify(entry.input) !== JSON.stringify(input)) throw new Error("queue receipt mismatch"); + if (resume) { + try { await request("thread/resume", { threadId: sessionId }); } + catch { resumeDiagnostic = true; } + } + }); + } catch { + fail("Codex queue outcome uncertain; inspect before retrying", 70); } - fail(safeError("Codex native queue failed", queued), 1); + } else { + const queued = await run(process.env.CODEX_BIN || "codex", [ + "queue", "--thread", sessionId, "--message", protocolMessage, ...(resume ? ["--resume"] : []) + ], (timeoutSeconds + 15) * 1000); + if (queued.code !== 0) { + if (codexSessionIsNotDirectlyWritable(queued)) { + fail("Codex spawned sub-agent sessions are readable but do not accept direct queued turns.", 79); + } + fail(safeError("Codex native queue failed", queued), 1); + } + resumeDiagnostic = Boolean(resume && queued.stderr?.trim()); } - resumeDiagnostic = Boolean(resume && queued.stderr?.trim()); deliveryMethod = "queue"; } } else { diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index 9ed4599f..9fc5bbd3 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -124,6 +124,8 @@ def deliver(agent: str, session: str, correlation: str, message: str, inbox_root if agent != "codex": raise ValueError("waker resume is supported only for Codex") command += ["--resume"] + elif message_stdin and agent == "codex": + command += ["--no-resume"] if delivery_only: command += ["--delivery-only"] if inbox_root: From 0bf7d88e6cde6911532cb1a2caafa8b51109d4f4 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:28:36 +0000 Subject: [PATCH 025/113] Ignore untracked Python bytecode in privacy scan --- packages/tmux-bridge/test/plexus-privacy.test.mjs | 13 ++++++++++++- scripts/mesh-readiness.mjs | 7 +++++-- scripts/plexus-privacy.mjs | 6 ++++++ 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/packages/tmux-bridge/test/plexus-privacy.test.mjs b/packages/tmux-bridge/test/plexus-privacy.test.mjs index adfc1507..3f562185 100644 --- a/packages/tmux-bridge/test/plexus-privacy.test.mjs +++ b/packages/tmux-bridge/test/plexus-privacy.test.mjs @@ -1,6 +1,17 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { containsPrivatePlexusPolicy, isPlexusMechanismFile } from '../../../scripts/plexus-privacy.mjs'; +import { containsPrivatePlexusPolicy, isGeneratedPythonBytecode, isPlexusMechanismFile } from '../../../scripts/plexus-privacy.mjs'; + +test('only interpreter bytecode in cache directories is excluded from text scanning', () => { + const tracked = new Set(['pkg/__pycache__/tracked.cpython-312.pyc']); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/example.cpython-312.pyc', tracked), true); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/example.cpython-312.opt-1.pyc', tracked), true); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/tracked.cpython-312.pyc', tracked), false); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/example.cpython-312.pyc', null), false); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/example.py', tracked), false); + assert.equal(isGeneratedPythonBytecode('pkg/example.cpython-312.pyc', tracked), false); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/other.pyc', tracked), false); +}); test('Plexus public mechanism paths and private references are classified', () => { for (const path of ['docs/design/plexus.md', 'docs/design/plexus-modules.md', 'packages/tmux-bridge/README.md', 'packages/tmux-bridge/bin/plexus.mjs', 'packages/tmux-bridge/bin/mesh-graph.mjs', 'packages/tmux-bridge/bin/plexus-modules.mjs', 'packages/tmux-bridge/examples/plexus-example-module.mjs', 'packages/tmux-bridge/test/plexus-privacy.test.mjs', 'skills/agent-tmux/bin/agent-waker.py']) assert.equal(isPlexusMechanismFile(path), true, path); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index 41303ec8..943aa5e5 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -2,11 +2,14 @@ import { readFileSync, readdirSync, statSync } from "node:fs"; import path from "node:path"; import { fileURLToPath } from "node:url"; +import { execFileSync } from "node:child_process"; import { parseMeshV1Envelope, planMeshV1Dispatch } from "../packages/core/src/policy.js"; -import { containsPrivatePlexusPolicy, isPlexusMechanismFile } from "./plexus-privacy.mjs"; +import { containsPrivatePlexusPolicy, isGeneratedPythonBytecode, isPlexusMechanismFile } from "./plexus-privacy.mjs"; import { plexusDiagram } from "./plexus-diagram.mjs"; const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +let trackedFiles = null; +try { trackedFiles = new Set(execFileSync("git", ["ls-files", "-z"], { cwd: root, encoding: "utf8" }).split("\0")); } catch { /* Without Git, scan every file. */ } const checks = []; const agentTmuxBundleFiles = [ "bin/agent-mesh", @@ -75,7 +78,7 @@ check("duplicate final suppressed", () => { const final = planMeshV1Dispatch({ l check("turn gate fails closed", () => { const plan = planMeshV1Dispatch({ localParticipant: "alpha" }, { text: "cc-mesh: alpha\ncc-mesh-from: beta\ncc-mesh-id: ready-5\ncc-mesh-turn: gamma\ncc-mesh-final: true\n\nhello" }); assert(plan.reason === "mesh_v1_not_local_turn", `expected turn gate got ${plan.reason}`); }); check("seen loop guard fails closed", () => { const plan = planMeshV1Dispatch({ localParticipant: "alpha" }, { text: "cc-mesh: alpha\ncc-mesh-from: beta\ncc-mesh-id: ready-6\ncc-mesh-turn: alpha\ncc-mesh-final: true\ncc-mesh-seen: beta,alpha\n\nhello" }); assert(plan.reason === "mesh_v1_loop_guard_seen", `expected loop guard got ${plan.reason}`); }); check("privacy snowflake rule ignores repeated placeholders", () => { assert(!snowflakeIdPattern.test("111111111111111111"), "repeated-digit placeholder must not be flagged"); assert(!snowflakeIdPattern.test("222222222222222222"), "repeated-digit placeholder must not be flagged"); assert(snowflakeIdPattern.test("123456789" + "012345678"), "mixed-digit snowflake-shaped ID must be flagged"); }); -check("public-tree privacy sanity", () => { const deny = [snowflakeIdPattern, new RegExp("/home/operator/env/workspace/iter" + "modus/"), /(api[_-]?key|secret|password|token)\s*[:=]\s*["'][^"']{6,}["']/i]; const privateIdentifiers = ["ti" + "rrenia", "od" + "ino", "iter" + "modus"]; const skipDirs = new Set([".git", "node_modules", "dist"]); const skipPaths = new Set([".syncwheel/ledger"]); const hits = []; function walk(dir) { if (skipPaths.has(path.relative(root, dir))) return; for (const entry of readdirSync(dir)) { if (skipDirs.has(entry)) continue; const full = path.join(dir, entry); const stat = statSync(full); if (stat.isDirectory()) walk(full); else if (stat.isFile()) { const text = readFileSync(full, "utf8"); for (const pattern of deny) if (pattern.test(text)) hits.push(path.relative(root, full)); if (privateIdentifiers.some((identifier) => text.toLowerCase().includes(identifier))) hits.push(path.relative(root, full)); } } } walk(root); assert(hits.length === 0, `privacy scan hits: ${[...new Set(hits)].join(", ")}`); }); +check("public-tree privacy sanity", () => { const deny = [snowflakeIdPattern, new RegExp("/home/operator/env/workspace/iter" + "modus/"), /(api[_-]?key|secret|password|token)\s*[:=]\s*["'][^"']{6,}["']/i]; const privateIdentifiers = ["ti" + "rrenia", "od" + "ino", "iter" + "modus"]; const skipDirs = new Set([".git", "node_modules", "dist"]); const skipPaths = new Set([".syncwheel/ledger"]); const hits = []; function walk(dir) { if (skipPaths.has(path.relative(root, dir))) return; for (const entry of readdirSync(dir)) { if (skipDirs.has(entry)) continue; const full = path.join(dir, entry); const stat = statSync(full); if (stat.isDirectory()) walk(full); else if (stat.isFile() && !isGeneratedPythonBytecode(path.relative(root, full), trackedFiles)) { const text = readFileSync(full, "utf8"); for (const pattern of deny) if (pattern.test(text)) hits.push(path.relative(root, full)); if (privateIdentifiers.some((identifier) => text.toLowerCase().includes(identifier))) hits.push(path.relative(root, full)); } } } walk(root); assert(hits.length === 0, `privacy scan hits: ${[...new Set(hits)].join(", ")}`); }); check("Plexus mechanism privacy", () => { const hits = []; const skip = new Set([".git", "node_modules", "dist", "var"]); function walk(dir) { for (const entry of readdirSync(dir)) { if (skip.has(entry)) continue; const full = path.join(dir, entry), stat = statSync(full); if (stat.isDirectory()) walk(full); else if (stat.isFile()) { const relative = path.relative(root, full); if (isPlexusMechanismFile(relative) && containsPrivatePlexusPolicy(readFileSync(full, "utf8"))) hits.push(relative); } } } walk(root); assert(hits.length === 0, `Plexus privacy scan hits: ${hits.join(", ")}`); }); check("agent-tmux skill bundle sync", () => { const drifted = agentTmuxBundleFiles.filter((relativePath) => { try { return !readFileSync(path.join(root, "packages/tmux-bridge", relativePath)).equals(readFileSync(path.join(root, "skills/agent-tmux", relativePath))); } catch { return true; } }); assert(drifted.length === 0, `agent-tmux skill bundle drift: ${drifted.join(", ")}`); }); for (const result of checks) console.log(`${result.ok ? "PASS" : "FAIL"} ${result.name}${result.ok ? "" : `: ${result.error}`}`); diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs index 68675fbc..02bda86b 100644 --- a/scripts/plexus-privacy.mjs +++ b/scripts/plexus-privacy.mjs @@ -12,3 +12,9 @@ export function isPlexusMechanismFile(relativePath) { export function containsPrivatePlexusPolicy(text) { return privatePatterns.some((pattern) => pattern.test(text)); } + +// Python writes interpreter-specific binary caches while the test suite runs. +// Keep scanning any source files placed in such directories. +export function isGeneratedPythonBytecode(relativePath, trackedFiles) { + return trackedFiles instanceof Set && !trackedFiles.has(relativePath) && /(?:^|\/)__pycache__\/[^/]+\.cpython-\d+(?:\.opt-\d+)?\.pyc$/.test(relativePath); +} From 784862a1588865e72655f4a768dcdb7faedb84b2 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:38:56 +0000 Subject: [PATCH 026/113] Pass state attestation requests over stdin --- packages/tmux-bridge/bin/handover-state-proof.mjs | 14 ++++++++++---- .../tmux-bridge/test/handover-state-proof.test.mjs | 5 ++++- skills/agent-tmux/bin/handover-state-proof.mjs | 14 ++++++++++---- 3 files changed, 24 insertions(+), 9 deletions(-) diff --git a/packages/tmux-bridge/bin/handover-state-proof.mjs b/packages/tmux-bridge/bin/handover-state-proof.mjs index eca3f268..419a8779 100644 --- a/packages/tmux-bridge/bin/handover-state-proof.mjs +++ b/packages/tmux-bridge/bin/handover-state-proof.mjs @@ -4,12 +4,18 @@ import { lstat, open, realpath } from 'node:fs/promises'; import { createHash } from 'node:crypto'; import { randomUUID } from 'node:crypto'; import { execFile } from 'node:child_process'; -import { promisify } from 'node:util'; import { dirname, isAbsolute, join } from 'node:path'; import { fileURLToPath } from 'node:url'; const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); -const exec = promisify(execFile); +const exec = (command, args, { input, ...options }) => new Promise((resolve, reject) => { + const child = execFile(command, args, options, (error, stdout) => { + if (error) reject(new Error('native state request failed')); + else resolve({ stdout }); + }); + child.stdin.on('error', () => {}); + child.stdin.end(input); +}); /** Obtain a correlated native-session result, then bind it to file bytes. */ export async function requestStateProof({ session, root, filename, managedInboxRoot }, runNative = exec) { @@ -20,10 +26,10 @@ export async function requestStateProof({ session, root, filename, managedInboxR if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); const nonce = `handover-${randomUUID()}`; const message = `Write your handover state in the configured format to ${join(root, filename)} with private permissions. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; - const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message', message]; + const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message-stdin']; if (agent === 'codex') argv.push('--no-resume'); if (agent === 'claude') argv.push('--managed-inbox-root', managedInboxRoot); - const result = await runNative(process.execPath, argv, { timeout: 125000, maxBuffer: 8192 }); + const result = await runNative(process.execPath, argv, { input: message, timeout: 125000, maxBuffer: 8192 }); if (!result || typeof result.stdout !== 'string') throw new Error('native result unavailable'); return verifyStateResponse({ session, nonce, response: result.stdout, root, filename }); } diff --git a/packages/tmux-bridge/test/handover-state-proof.test.mjs b/packages/tmux-bridge/test/handover-state-proof.test.mjs index ac3fcf6d..86ac1380 100644 --- a/packages/tmux-bridge/test/handover-state-proof.test.mjs +++ b/packages/tmux-bridge/test/handover-state-proof.test.mjs @@ -28,9 +28,12 @@ test('native request binds response to its own correlation without resuming', as const root = await mkdtemp(join(tmpdir(), 'state-native-')); t.after(() => rm(root, { recursive: true, force: true })); const session = 'codex:22222222-2222-4222-8222-222222222222', filename = 'state.yaml'; - const fake = async (binary, argv) => { + const fake = async (binary, argv, options) => { assert.equal(binary, process.execPath); assert.ok(argv.includes('--no-resume')); + assert.ok(argv.includes('--message-stdin')); + assert.ok(!argv.some(value => value.includes(root))); + assert.ok(options.input.includes(join(root, filename))); const nonce = argv[argv.indexOf('--correlation-id') + 1]; const content = 'version: 1\n'; await writeFile(join(root, filename), content, { mode: 0o600 }); diff --git a/skills/agent-tmux/bin/handover-state-proof.mjs b/skills/agent-tmux/bin/handover-state-proof.mjs index eca3f268..419a8779 100644 --- a/skills/agent-tmux/bin/handover-state-proof.mjs +++ b/skills/agent-tmux/bin/handover-state-proof.mjs @@ -4,12 +4,18 @@ import { lstat, open, realpath } from 'node:fs/promises'; import { createHash } from 'node:crypto'; import { randomUUID } from 'node:crypto'; import { execFile } from 'node:child_process'; -import { promisify } from 'node:util'; import { dirname, isAbsolute, join } from 'node:path'; import { fileURLToPath } from 'node:url'; const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); -const exec = promisify(execFile); +const exec = (command, args, { input, ...options }) => new Promise((resolve, reject) => { + const child = execFile(command, args, options, (error, stdout) => { + if (error) reject(new Error('native state request failed')); + else resolve({ stdout }); + }); + child.stdin.on('error', () => {}); + child.stdin.end(input); +}); /** Obtain a correlated native-session result, then bind it to file bytes. */ export async function requestStateProof({ session, root, filename, managedInboxRoot }, runNative = exec) { @@ -20,10 +26,10 @@ export async function requestStateProof({ session, root, filename, managedInboxR if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); const nonce = `handover-${randomUUID()}`; const message = `Write your handover state in the configured format to ${join(root, filename)} with private permissions. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; - const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message', message]; + const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message-stdin']; if (agent === 'codex') argv.push('--no-resume'); if (agent === 'claude') argv.push('--managed-inbox-root', managedInboxRoot); - const result = await runNative(process.execPath, argv, { timeout: 125000, maxBuffer: 8192 }); + const result = await runNative(process.execPath, argv, { input: message, timeout: 125000, maxBuffer: 8192 }); if (!result || typeof result.stdout !== 'string') throw new Error('native result unavailable'); return verifyStateResponse({ session, nonce, response: result.stdout, root, filename }); } From 6a6a7dabb5ed4b48db53f0727740607e8978f594 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:49:27 +0000 Subject: [PATCH 027/113] Define restart state data contract --- docs/design/plexus-restart-state.md | 33 +++++++++++++++++++ packages/tmux-bridge/bin/restart-state.mjs | 23 +++++++++++++ .../tmux-bridge/test/plexus-privacy.test.mjs | 3 ++ .../tmux-bridge/test/restart-state.test.mjs | 18 ++++++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-privacy.mjs | 2 +- skills/agent-tmux/bin/restart-state.mjs | 23 +++++++++++++ 7 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 docs/design/plexus-restart-state.md create mode 100644 packages/tmux-bridge/bin/restart-state.mjs create mode 100644 packages/tmux-bridge/test/restart-state.test.mjs create mode 100644 skills/agent-tmux/bin/restart-state.mjs diff --git a/docs/design/plexus-restart-state.md b/docs/design/plexus-restart-state.md new file mode 100644 index 00000000..dc0a7781 --- /dev/null +++ b/docs/design/plexus-restart-state.md @@ -0,0 +1,33 @@ +# 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 +parse YAML with duplicate keys and unsafe tags rejected, bind the block to the +correlated old session and channel, and independently reconcile every trigger +with its source before using it. `validateRestartState` checks the decoded +object only: it is not a YAML parser, proof of authorship, scheduler or +authorization to recreate anything. Handover remains disabled until those +separate checks and final-notice verification are implemented. diff --git a/packages/tmux-bridge/bin/restart-state.mjs b/packages/tmux-bridge/bin/restart-state.mjs new file mode 100644 index 00000000..d01ab53d --- /dev/null +++ b/packages/tmux-bridge/bin/restart-state.mjs @@ -0,0 +1,23 @@ +/** Validate a parsed restart block; never execute its instructions. */ +const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; +const nonempty = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 8192 && !value.includes('\0'); + +export function validateRestartState(block, { session, channel } = {}) { + if (!isObject(block) || block.schema !== 'agent-mesh.restart.v1') throw new Error('invalid restart schema'); + for (const field of ['session', 'channel', 'harness', 'working_directory']) { + if (!nonempty(block[field])) throw new Error(`invalid restart ${field}`); + } + if (session !== undefined && block.session !== session) throw new Error('restart session mismatch'); + if (channel !== undefined && block.channel !== channel) throw new Error('restart channel mismatch'); + if (!Array.isArray(block.skills) || block.skills.length > 256 || !block.skills.every(nonempty)) throw new Error('invalid restart skills'); + if (!Array.isArray(block.triggers) || block.triggers.length > 256) throw new Error('invalid restart triggers'); + const ids = new Set(); + for (const trigger of block.triggers) { + if (!isObject(trigger) || !nonempty(trigger.id) || !nonempty(trigger.kind) || !isObject(trigger.config)) throw new Error('invalid restart trigger'); + const key = JSON.stringify([trigger.kind, trigger.id]); + if (ids.has(key)) throw new Error('duplicate restart trigger'); + ids.add(key); + } + if (block.goal !== null && (!isObject(block.goal) || !nonempty(block.goal.objective) || !nonempty(block.goal.status))) throw new Error('invalid restart goal'); + return true; +} diff --git a/packages/tmux-bridge/test/plexus-privacy.test.mjs b/packages/tmux-bridge/test/plexus-privacy.test.mjs index 3f562185..0e976814 100644 --- a/packages/tmux-bridge/test/plexus-privacy.test.mjs +++ b/packages/tmux-bridge/test/plexus-privacy.test.mjs @@ -14,6 +14,9 @@ test('only interpreter bytecode in cache directories is excluded from text scann }); test('Plexus public mechanism paths and private references are classified', () => { + assert.equal(isPlexusMechanismFile('packages/tmux-bridge/bin/restart-state.mjs'), true); + assert.equal(isPlexusMechanismFile('packages/tmux-bridge/test/restart-state.test.mjs'), true); + assert.equal(isPlexusMechanismFile('skills/agent-tmux/bin/restart-state.mjs'), true); for (const path of ['docs/design/plexus.md', 'docs/design/plexus-modules.md', 'packages/tmux-bridge/README.md', 'packages/tmux-bridge/bin/plexus.mjs', 'packages/tmux-bridge/bin/mesh-graph.mjs', 'packages/tmux-bridge/bin/plexus-modules.mjs', 'packages/tmux-bridge/examples/plexus-example-module.mjs', 'packages/tmux-bridge/test/plexus-privacy.test.mjs', 'skills/agent-tmux/bin/agent-waker.py']) assert.equal(isPlexusMechanismFile(path), true, path); for (const value of ['gale' + 'haut', 'management:' + 'MGT-123', '/home/' + 'administrator/private']) assert.equal(containsPrivatePlexusPolicy(value), true); assert.equal(containsPrivatePlexusPolicy('A configurable policy uses a synthetic session.'), false); diff --git a/packages/tmux-bridge/test/restart-state.test.mjs b/packages/tmux-bridge/test/restart-state.test.mjs new file mode 100644 index 00000000..055d48de --- /dev/null +++ b/packages/tmux-bridge/test/restart-state.test.mjs @@ -0,0 +1,18 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { validateRestartState } from '../bin/restart-state.mjs'; + +const sample = () => ({ 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' } }); +test('restart block is bound to its original session and stable channel', () => { + assert.equal(validateRestartState(sample(), { session: 'codex:example', channel: '#example' }), true); + assert.throws(() => validateRestartState(sample(), { session: 'codex:other' }), /session mismatch/); + assert.throws(() => validateRestartState(sample(), { channel: '#other' }), /channel mismatch/); +}); +test('restart block rejects incomplete or ambiguous configuration', () => { + for (const [key, value] of [['schema', 'other'], ['harness', ''], ['working_directory', null], ['skills', [null]], ['triggers', [{ id: 'x', kind: 'timer' }]], ['goal', {}]]) { + assert.throws(() => validateRestartState({ ...sample(), [key]: value }), undefined, key); + } + const item = { id: 'x', kind: 'timer', config: {} }; + assert.throws(() => validateRestartState({ ...sample(), triggers: [item, item] }), /duplicate/); + assert.equal(validateRestartState({ ...sample(), triggers: [], skills: [], goal: null }), true); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index 943aa5e5..db0ce18c 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -45,6 +45,7 @@ const agentTmuxBundleFiles = [ "bin/plexus.mjs", "bin/channel-state.mjs", "bin/handover-state-proof.mjs", + "bin/restart-state.mjs", "bin/ledger-view.mjs", "bin/session-catalog.mjs", "bin/session-links.mjs", diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs index 02bda86b..fe304ea9 100644 --- a/scripts/plexus-privacy.mjs +++ b/scripts/plexus-privacy.mjs @@ -6,7 +6,7 @@ const privatePatterns = [ ]; export function isPlexusMechanismFile(relativePath) { - return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|module-batches|mesh-(?:graph|channel)|agent-waker|session-(?:sleep|handover)|(?:sleep|handover)-))/.test(relativePath); + return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|module-batches|mesh-(?:graph|channel)|agent-waker|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); } export function containsPrivatePlexusPolicy(text) { diff --git a/skills/agent-tmux/bin/restart-state.mjs b/skills/agent-tmux/bin/restart-state.mjs new file mode 100644 index 00000000..d01ab53d --- /dev/null +++ b/skills/agent-tmux/bin/restart-state.mjs @@ -0,0 +1,23 @@ +/** Validate a parsed restart block; never execute its instructions. */ +const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; +const nonempty = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 8192 && !value.includes('\0'); + +export function validateRestartState(block, { session, channel } = {}) { + if (!isObject(block) || block.schema !== 'agent-mesh.restart.v1') throw new Error('invalid restart schema'); + for (const field of ['session', 'channel', 'harness', 'working_directory']) { + if (!nonempty(block[field])) throw new Error(`invalid restart ${field}`); + } + if (session !== undefined && block.session !== session) throw new Error('restart session mismatch'); + if (channel !== undefined && block.channel !== channel) throw new Error('restart channel mismatch'); + if (!Array.isArray(block.skills) || block.skills.length > 256 || !block.skills.every(nonempty)) throw new Error('invalid restart skills'); + if (!Array.isArray(block.triggers) || block.triggers.length > 256) throw new Error('invalid restart triggers'); + const ids = new Set(); + for (const trigger of block.triggers) { + if (!isObject(trigger) || !nonempty(trigger.id) || !nonempty(trigger.kind) || !isObject(trigger.config)) throw new Error('invalid restart trigger'); + const key = JSON.stringify([trigger.kind, trigger.id]); + if (ids.has(key)) throw new Error('duplicate restart trigger'); + ids.add(key); + } + if (block.goal !== null && (!isObject(block.goal) || !nonempty(block.goal.objective) || !nonempty(block.goal.status))) throw new Error('invalid restart goal'); + return true; +} From 142eea3c704adf4ae0f23a636db30cf97d3c82b2 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:49:52 +0000 Subject: [PATCH 028/113] Show restart state in Plexus diagram --- docs/design/plexus-architecture.mmd | 1 + scripts/plexus-diagram.mjs | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 6fc96e2c..5eeda185 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -7,4 +7,5 @@ flowchart LR Module["Registered module"] --> Contract["Versioned JSON contract"] Contract --> Journal Queue -- "bound receipt" --> Session + Restart["Restart state contract"] -. "planned validation" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index c7e783fb..8e19a656 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -8,5 +8,6 @@ export const plexusDiagram = `flowchart LR Module["Registered module"] --> Contract["Versioned JSON contract"] Contract --> Journal Queue -- "bound receipt" --> Session + Restart["Restart state contract"] -. "planned validation" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel `; From 3afe1725c4b8bf084fdc60445fcb02de85e47173 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:00:14 +0000 Subject: [PATCH 029/113] Validate bounded restart YAML against state proof --- .github/workflows/verify.yml | 2 +- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-channels.md | 4 +- docs/design/plexus-restart-state.md | 14 ++-- .../tmux-bridge/bin/handover-state-proof.mjs | 19 ++++-- packages/tmux-bridge/bin/restart-yaml.py | 67 +++++++++++++++++++ .../test/handover-state-proof.test.mjs | 19 ++++-- .../tmux-bridge/test/restart-yaml.test.mjs | 21 ++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-diagram.mjs | 1 + .../agent-tmux/bin/handover-state-proof.mjs | 19 ++++-- skills/agent-tmux/bin/restart-yaml.py | 67 +++++++++++++++++++ 12 files changed, 209 insertions(+), 26 deletions(-) create mode 100644 packages/tmux-bridge/bin/restart-yaml.py create mode 100644 packages/tmux-bridge/test/restart-yaml.test.mjs create mode 100644 skills/agent-tmux/bin/restart-yaml.py diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index 95070fda..33561404 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -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 diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 5eeda185..bfe03323 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -7,5 +7,6 @@ flowchart LR Module["Registered module"] --> Contract["Versioned JSON contract"] Contract --> Journal Queue -- "bound receipt" --> Session + Yaml["Bounded YAML decoder"] --> Restart Restart["Restart state contract"] -. "planned validation" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 0375fe68..57831777 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -29,8 +29,8 @@ session wrote its state. A path or caller assertion is not sufficient proof. correlated actor response to a session, nonce, filename and SHA-256, and checks the private file without following a final symlink. `requestStateProof` obtains the response through the existing native correlated-result transport; Codex -resume remains disabled. The verifier does not parse the state format or make a -graph cutover. A caller must verify its state-format contract before proceeding. +resume remains disabled. The verifier decodes and validates the restart block, +but does not reconcile its triggers or make a graph cutover. The prepared Codex path additionally requires a fresh unarchived native-thread observation and exactly one detected writer. Claude and cloud successors are not yet supported by this operation. diff --git a/docs/design/plexus-restart-state.md b/docs/design/plexus-restart-state.md index dc0a7781..6cc83504 100644 --- a/docs/design/plexus-restart-state.md +++ b/docs/design/plexus-restart-state.md @@ -25,9 +25,11 @@ goal: `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 -parse YAML with duplicate keys and unsafe tags rejected, bind the block to the -correlated old session and channel, and independently reconcile every trigger -with its source before using it. `validateRestartState` checks the decoded -object only: it is not a YAML parser, proof of authorship, scheduler or -authorization to recreate anything. Handover remains disabled until those -separate checks and final-notice verification are implemented. +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. diff --git a/packages/tmux-bridge/bin/handover-state-proof.mjs b/packages/tmux-bridge/bin/handover-state-proof.mjs index 419a8779..12fdf581 100644 --- a/packages/tmux-bridge/bin/handover-state-proof.mjs +++ b/packages/tmux-bridge/bin/handover-state-proof.mjs @@ -3,11 +3,13 @@ import { constants } from 'node:fs'; import { lstat, open, realpath } from 'node:fs/promises'; import { createHash } from 'node:crypto'; import { randomUUID } from 'node:crypto'; -import { execFile } from 'node:child_process'; +import { execFile, spawnSync } from 'node:child_process'; import { dirname, isAbsolute, join } from 'node:path'; import { fileURLToPath } from 'node:url'; +import { validateRestartState } from './restart-state.mjs'; const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); +const yamlBin = join(dirname(fileURLToPath(import.meta.url)), 'restart-yaml.py'); const exec = (command, args, { input, ...options }) => new Promise((resolve, reject) => { const child = execFile(command, args, options, (error, stdout) => { if (error) reject(new Error('native state request failed')); @@ -18,25 +20,26 @@ const exec = (command, args, { input, ...options }) => new Promise((resolve, rej }); /** Obtain a correlated native-session result, then bind it to file bytes. */ -export async function requestStateProof({ session, root, filename, managedInboxRoot }, runNative = exec) { +export async function requestStateProof({ session, channel, root, filename, managedInboxRoot }, runNative = exec) { if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !isAbsolute(root) || /[\r\n\x00]/.test(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); const rootInfo = await lstat(root); if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); const [agent, nativeId] = session.split(':'); if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); const nonce = `handover-${randomUUID()}`; - const message = `Write your handover state in the configured format to ${join(root, filename)} with private permissions. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; + if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); + const message = `Write your handover state with a RIAVVIO YAML block using agent-mesh.restart.v1 to ${join(root, filename)} with private permissions. Bind the block to session ${session} and channel ${channel}, and include harness, working_directory, skills, triggers and goal. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message-stdin']; if (agent === 'codex') argv.push('--no-resume'); if (agent === 'claude') argv.push('--managed-inbox-root', managedInboxRoot); const result = await runNative(process.execPath, argv, { input: message, timeout: 125000, maxBuffer: 8192 }); if (!result || typeof result.stdout !== 'string') throw new Error('native result unavailable'); - return verifyStateResponse({ session, nonce, response: result.stdout, root, filename }); + return verifyStateResponse({ session, channel, nonce, response: result.stdout, root, filename }); } // The caller must obtain response from the native correlated-result transport, // bound to session and nonce. This function cannot authenticate arbitrary text. -export async function verifyStateResponse({ session, nonce, response, root, filename }) { +export async function verifyStateResponse({ session, channel, nonce, response, root, filename }) { if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce) || !isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); const rootInfo = await lstat(root); if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); @@ -53,6 +56,12 @@ export async function verifyStateResponse({ session, nonce, response, root, file if (before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('state file changed during verification'); const digest = createHash('sha256').update(bytes).digest('hex'); if (digest !== attestation.sha256) throw new Error('state file digest mismatch'); + if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); + const decoded = spawnSync(process.env.PYTHON || 'python3', ['-I', yamlBin], { input: bytes, encoding: 'utf8', timeout: 10000, maxBuffer: 2 * 1024 * 1024 }); + if (decoded.error || decoded.status !== 0) throw new Error('restart YAML unavailable or invalid'); + let restart; + try { restart = JSON.parse(decoded.stdout); } catch { throw new Error('invalid restart YAML result'); } + validateRestartState(restart, { session, channel }); return { schema: attestation.schema, session, nonce, filename, sha256: digest, bytes: bytes.length }; } finally { await file.close(); } } diff --git a/packages/tmux-bridge/bin/restart-yaml.py b/packages/tmux-bridge/bin/restart-yaml.py new file mode 100644 index 00000000..46144e51 --- /dev/null +++ b/packages/tmux-bridge/bin/restart-yaml.py @@ -0,0 +1,67 @@ +#!/usr/bin/env python3 +"""Decode a bounded restart block; do not emit state contents on errors.""" +import json +import math +import re +import sys + +try: + import yaml +except ImportError: + print('restart YAML parser unavailable: PyYAML is required', file=sys.stderr) + sys.exit(2) + + +class UniqueLoader(yaml.SafeLoader): + def construct_mapping(self, node, deep=False): + result = {} + for key_node, value_node in node.value: + key = self.construct_object(key_node, deep=deep) + if not isinstance(key, str) or key in result: + raise ValueError('non-string or duplicate key') + result[key] = self.construct_object(value_node, deep=deep) + return result + + +def json_value(value, depth=0, count=None): + count = count if count is not None else [0] + count[0] += 1 + if depth > 32 or count[0] > 20000: + raise ValueError('restart structure too large') + if value is None or isinstance(value, (bool, str, int)): + return value + if isinstance(value, float) and math.isfinite(value): + return value + if isinstance(value, list): + return [json_value(item, depth + 1, count) for item in value] + if isinstance(value, dict): + return {key: json_value(item, depth + 1, count) for key, item in value.items()} + raise ValueError('restart value is not JSON-compatible') + + +def decode(data): + text = data.decode('utf-8').replace('\r\n', '\n') + headings = list(re.finditer(r'^## RIAVVIO[ \t]*$', text, re.MULTILINE)) + if headings: + if len(headings) != 1: + raise ValueError('ambiguous restart section') + rest = text[headings[0].end():] + match = re.match(r'\n[ \t\n]*```ya?ml[ \t]*\n(.*?)^```[ \t]*$', rest, re.MULTILINE | re.DOTALL | re.IGNORECASE) + if not match: + raise ValueError('missing restart YAML block') + text = match.group(1) + for token in yaml.scan(text, Loader=UniqueLoader): + if isinstance(token, (yaml.tokens.AliasToken, yaml.tokens.AnchorToken, yaml.tokens.TagToken)): + raise ValueError('aliases, anchors and explicit tags are not allowed') + return json_value(yaml.load(text, Loader=UniqueLoader)) + + +try: + raw = sys.stdin.buffer.read(1024 * 1024 + 1) + if not raw or len(raw) > 1024 * 1024: + raise ValueError('invalid state size') + result = decode(raw) + print(json.dumps(result, ensure_ascii=True, allow_nan=False, separators=(',', ':'))) +except (ValueError, TypeError, UnicodeError, yaml.YAMLError, RecursionError): + print('invalid restart YAML', file=sys.stderr) + sys.exit(1) diff --git a/packages/tmux-bridge/test/handover-state-proof.test.mjs b/packages/tmux-bridge/test/handover-state-proof.test.mjs index 86ac1380..de077d49 100644 --- a/packages/tmux-bridge/test/handover-state-proof.test.mjs +++ b/packages/tmux-bridge/test/handover-state-proof.test.mjs @@ -9,13 +9,18 @@ import { requestStateProof, verifyStateResponse } from '../bin/handover-state-pr test('state proof binds correlated response to private file bytes', async (t) => { const root = await mkdtemp(join(tmpdir(), 'state-proof-')); t.after(() => rm(root, { recursive: true, force: true })); - const session = 'codex:22222222-2222-4222-8222-222222222222', filename = 'state.yaml', nonce = 'attempt-1'; - const content = 'version: 1\nnext: example\n'; + const session = 'codex:22222222-2222-4222-8222-222222222222', channel = '#example', filename = 'state.yaml', nonce = 'attempt-1'; + const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\n`; await writeFile(join(root, filename), content, { mode: 0o600 }); const response = { schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }; - const verify = (overrides = {}) => verifyStateResponse({ session, nonce, filename, root, response: JSON.stringify(response), ...overrides }); + const verify = (overrides = {}) => verifyStateResponse({ session, channel, nonce, filename, root, response: JSON.stringify(response), ...overrides }); assert.equal((await verify()).bytes, Buffer.byteLength(content)); + await assert.rejects(verify({ channel: '#other' }), /channel mismatch/); await assert.rejects(verify({ nonce: 'other' }), /binding/); + const malformed = content + 'harness: other\n'; + await writeFile(join(root, filename), malformed, { mode: 0o600 }); + const malformedResponse = JSON.stringify({ ...response, sha256: createHash('sha256').update(malformed).digest('hex') }); + await assert.rejects(verify({ response: malformedResponse }), /restart YAML/); await writeFile(join(root, filename), 'changed', { mode: 0o600 }); await assert.rejects(verify(), /digest/); await chmod(join(root, filename), 0o644); @@ -35,13 +40,13 @@ test('native request binds response to its own correlation without resuming', as assert.ok(!argv.some(value => value.includes(root))); assert.ok(options.input.includes(join(root, filename))); const nonce = argv[argv.indexOf('--correlation-id') + 1]; - const content = 'version: 1\n'; + const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\n`; await writeFile(join(root, filename), content, { mode: 0o600 }); return { stdout: JSON.stringify({ schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }) }; }; - const proof = await requestStateProof({ session, root, filename }, fake); + const proof = await requestStateProof({ session, channel: '#example', root, filename }, fake); assert.equal(proof.session, session); assert.ok(proof.nonce.startsWith('handover-')); - await assert.rejects(requestStateProof({ session, root, filename }, async () => ({ stdout: JSON.stringify({ status: 'held' }) })), /binding/); - await assert.rejects(requestStateProof({ session, root, filename }, async () => { throw new Error('timeout'); }), /timeout/); + await assert.rejects(requestStateProof({ session, channel: '#example', root, filename }, async () => ({ stdout: JSON.stringify({ status: 'held' }) })), /binding/); + await assert.rejects(requestStateProof({ session, channel: '#example', root, filename }, async () => { throw new Error('timeout'); }), /timeout/); }); diff --git a/packages/tmux-bridge/test/restart-yaml.test.mjs b/packages/tmux-bridge/test/restart-yaml.test.mjs new file mode 100644 index 00000000..49633dae --- /dev/null +++ b/packages/tmux-bridge/test/restart-yaml.test.mjs @@ -0,0 +1,21 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; +import test from 'node:test'; + +const parser = fileURLToPath(new URL('../bin/restart-yaml.py', import.meta.url)); +const parse = text => spawnSync('python3', ['-I', parser], { input: text, encoding: 'utf8' }); +test('restart YAML accepts a single fenced block and standalone documents', () => { + assert.deepEqual(JSON.parse(parse('schema: example\nskills: [one, two]\n').stdout), { schema: 'example', skills: ['one', 'two'] }); + const result = parse('# State\n\n## RIAVVIO\n\n```yaml\nschema: example\n```\n\n## Notes\nhello\n'); + assert.equal(result.status, 0, result.stderr); + assert.deepEqual(JSON.parse(result.stdout), { schema: 'example' }); +}); +test('restart YAML rejects ambiguous or unsafe inputs without exposing contents', () => { + for (const input of ['key: first\nkey: second\n', 'key: &anchor first\nother: *anchor\n', 'key: !!str value\n', 'a: 1\n---\na: 2\n', '## RIAVVIO\nnot a block\n', '## RIAVVIO\n```yaml\na: 1\n```\n## RIAVVIO\n```yaml\na: 2\n```\n', 'secret: fixture\n'.repeat(80000)]) { + const result = parse(input); + assert.notEqual(result.status, 0); + assert.equal(result.stdout, ''); + assert.ok(!result.stderr.includes('fixture')); + } +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index db0ce18c..2b76fdf3 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -46,6 +46,7 @@ const agentTmuxBundleFiles = [ "bin/channel-state.mjs", "bin/handover-state-proof.mjs", "bin/restart-state.mjs", + "bin/restart-yaml.py", "bin/ledger-view.mjs", "bin/session-catalog.mjs", "bin/session-links.mjs", diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 8e19a656..7e7c7150 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -8,6 +8,7 @@ export const plexusDiagram = `flowchart LR Module["Registered module"] --> Contract["Versioned JSON contract"] Contract --> Journal Queue -- "bound receipt" --> Session + Yaml["Bounded YAML decoder"] --> Restart Restart["Restart state contract"] -. "planned validation" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel `; diff --git a/skills/agent-tmux/bin/handover-state-proof.mjs b/skills/agent-tmux/bin/handover-state-proof.mjs index 419a8779..12fdf581 100644 --- a/skills/agent-tmux/bin/handover-state-proof.mjs +++ b/skills/agent-tmux/bin/handover-state-proof.mjs @@ -3,11 +3,13 @@ import { constants } from 'node:fs'; import { lstat, open, realpath } from 'node:fs/promises'; import { createHash } from 'node:crypto'; import { randomUUID } from 'node:crypto'; -import { execFile } from 'node:child_process'; +import { execFile, spawnSync } from 'node:child_process'; import { dirname, isAbsolute, join } from 'node:path'; import { fileURLToPath } from 'node:url'; +import { validateRestartState } from './restart-state.mjs'; const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); +const yamlBin = join(dirname(fileURLToPath(import.meta.url)), 'restart-yaml.py'); const exec = (command, args, { input, ...options }) => new Promise((resolve, reject) => { const child = execFile(command, args, options, (error, stdout) => { if (error) reject(new Error('native state request failed')); @@ -18,25 +20,26 @@ const exec = (command, args, { input, ...options }) => new Promise((resolve, rej }); /** Obtain a correlated native-session result, then bind it to file bytes. */ -export async function requestStateProof({ session, root, filename, managedInboxRoot }, runNative = exec) { +export async function requestStateProof({ session, channel, root, filename, managedInboxRoot }, runNative = exec) { if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !isAbsolute(root) || /[\r\n\x00]/.test(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); const rootInfo = await lstat(root); if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); const [agent, nativeId] = session.split(':'); if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); const nonce = `handover-${randomUUID()}`; - const message = `Write your handover state in the configured format to ${join(root, filename)} with private permissions. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; + if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); + const message = `Write your handover state with a RIAVVIO YAML block using agent-mesh.restart.v1 to ${join(root, filename)} with private permissions. Bind the block to session ${session} and channel ${channel}, and include harness, working_directory, skills, triggers and goal. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message-stdin']; if (agent === 'codex') argv.push('--no-resume'); if (agent === 'claude') argv.push('--managed-inbox-root', managedInboxRoot); const result = await runNative(process.execPath, argv, { input: message, timeout: 125000, maxBuffer: 8192 }); if (!result || typeof result.stdout !== 'string') throw new Error('native result unavailable'); - return verifyStateResponse({ session, nonce, response: result.stdout, root, filename }); + return verifyStateResponse({ session, channel, nonce, response: result.stdout, root, filename }); } // The caller must obtain response from the native correlated-result transport, // bound to session and nonce. This function cannot authenticate arbitrary text. -export async function verifyStateResponse({ session, nonce, response, root, filename }) { +export async function verifyStateResponse({ session, channel, nonce, response, root, filename }) { if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce) || !isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); const rootInfo = await lstat(root); if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); @@ -53,6 +56,12 @@ export async function verifyStateResponse({ session, nonce, response, root, file if (before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('state file changed during verification'); const digest = createHash('sha256').update(bytes).digest('hex'); if (digest !== attestation.sha256) throw new Error('state file digest mismatch'); + if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); + const decoded = spawnSync(process.env.PYTHON || 'python3', ['-I', yamlBin], { input: bytes, encoding: 'utf8', timeout: 10000, maxBuffer: 2 * 1024 * 1024 }); + if (decoded.error || decoded.status !== 0) throw new Error('restart YAML unavailable or invalid'); + let restart; + try { restart = JSON.parse(decoded.stdout); } catch { throw new Error('invalid restart YAML result'); } + validateRestartState(restart, { session, channel }); return { schema: attestation.schema, session, nonce, filename, sha256: digest, bytes: bytes.length }; } finally { await file.close(); } } diff --git a/skills/agent-tmux/bin/restart-yaml.py b/skills/agent-tmux/bin/restart-yaml.py new file mode 100644 index 00000000..46144e51 --- /dev/null +++ b/skills/agent-tmux/bin/restart-yaml.py @@ -0,0 +1,67 @@ +#!/usr/bin/env python3 +"""Decode a bounded restart block; do not emit state contents on errors.""" +import json +import math +import re +import sys + +try: + import yaml +except ImportError: + print('restart YAML parser unavailable: PyYAML is required', file=sys.stderr) + sys.exit(2) + + +class UniqueLoader(yaml.SafeLoader): + def construct_mapping(self, node, deep=False): + result = {} + for key_node, value_node in node.value: + key = self.construct_object(key_node, deep=deep) + if not isinstance(key, str) or key in result: + raise ValueError('non-string or duplicate key') + result[key] = self.construct_object(value_node, deep=deep) + return result + + +def json_value(value, depth=0, count=None): + count = count if count is not None else [0] + count[0] += 1 + if depth > 32 or count[0] > 20000: + raise ValueError('restart structure too large') + if value is None or isinstance(value, (bool, str, int)): + return value + if isinstance(value, float) and math.isfinite(value): + return value + if isinstance(value, list): + return [json_value(item, depth + 1, count) for item in value] + if isinstance(value, dict): + return {key: json_value(item, depth + 1, count) for key, item in value.items()} + raise ValueError('restart value is not JSON-compatible') + + +def decode(data): + text = data.decode('utf-8').replace('\r\n', '\n') + headings = list(re.finditer(r'^## RIAVVIO[ \t]*$', text, re.MULTILINE)) + if headings: + if len(headings) != 1: + raise ValueError('ambiguous restart section') + rest = text[headings[0].end():] + match = re.match(r'\n[ \t\n]*```ya?ml[ \t]*\n(.*?)^```[ \t]*$', rest, re.MULTILINE | re.DOTALL | re.IGNORECASE) + if not match: + raise ValueError('missing restart YAML block') + text = match.group(1) + for token in yaml.scan(text, Loader=UniqueLoader): + if isinstance(token, (yaml.tokens.AliasToken, yaml.tokens.AnchorToken, yaml.tokens.TagToken)): + raise ValueError('aliases, anchors and explicit tags are not allowed') + return json_value(yaml.load(text, Loader=UniqueLoader)) + + +try: + raw = sys.stdin.buffer.read(1024 * 1024 + 1) + if not raw or len(raw) > 1024 * 1024: + raise ValueError('invalid state size') + result = decode(raw) + print(json.dumps(result, ensure_ascii=True, allow_nan=False, separators=(',', ':'))) +except (ValueError, TypeError, UnicodeError, yaml.YAMLError, RecursionError): + print('invalid restart YAML', file=sys.stderr) + sys.exit(1) From 98f64d7133d2a865146e9cf5a5f1045ef7ceff67 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:10:14 +0000 Subject: [PATCH 030/113] Prepare verified successor notice formatting --- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-channels.md | 7 ++++ packages/tmux-bridge/bin/handover-notice.mjs | 32 +++++++++++++++++++ .../tmux-bridge/test/handover-notice.test.mjs | 23 +++++++++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-diagram.mjs | 1 + skills/agent-tmux/bin/handover-notice.mjs | 32 +++++++++++++++++++ 7 files changed, 97 insertions(+) create mode 100644 packages/tmux-bridge/bin/handover-notice.mjs create mode 100644 packages/tmux-bridge/test/handover-notice.test.mjs create mode 100644 skills/agent-tmux/bin/handover-notice.mjs diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index bfe03323..e084ceb5 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -9,4 +9,5 @@ flowchart LR Queue -- "bound receipt" --> Session Yaml["Bounded YAML decoder"] --> Restart Restart["Restart state contract"] -. "planned validation" .-> Handover + Notice["Successor notice formatter"] -. "planned publication" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 57831777..0b5a8fbf 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -40,3 +40,10 @@ old session, publish or verify the old session's final notice, archive anything, or reconcile uncertain transport outcomes. It must not be used for a live handover until those steps and their failure recovery are implemented and verified. The local graph is a trusted operator interface, not a remote API. + +`handover-notice.mjs` builds a notice from already resolved identifiers. It +supports same-project cloud anchors, cross-project cloud URLs and Codex thread +URLs. Its transcript comparison is only a predicate: an authenticated adapter +must independently supply a complete observation and prove the successor's +identity. Formatting or matching caller-supplied data alone is not evidence of +publication, finality or authorization to archive. diff --git a/packages/tmux-bridge/bin/handover-notice.mjs b/packages/tmux-bridge/bin/handover-notice.mjs new file mode 100644 index 00000000..8ab384c4 --- /dev/null +++ b/packages/tmux-bridge/bin/handover-notice.mjs @@ -0,0 +1,32 @@ +/** Build a successor link from resolved identifiers, never from a guessed URL. */ +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const projectId = /^[A-Za-z0-9_-]{1,256}$/; +const threadId = /^cmsg_[A-Za-z0-9_-]{1,250}$/; + +export function successorLink(target) { + if (!target || typeof target !== 'object') throw new Error('invalid successor'); + if (target.kind === 'codex' && typeof target.id === 'string' && uuid.test(target.id)) return `codex://threads/${target.id}`; + if (target.kind === 'cloud' && typeof target.sourceProject === 'string' && projectId.test(target.sourceProject) && + typeof target.targetProject === 'string' && projectId.test(target.targetProject) && + typeof target.thread === 'string' && threadId.test(target.thread)) { + return target.sourceProject === target.targetProject ? `#${target.thread}` : + `https://claude.ai/code/project/${target.targetProject}?thread=${target.thread}`; + } + throw new Error('invalid successor link identifiers'); +} + +export function formatFinalNotice({ target, label, prefix }) { + if (typeof label !== 'string' || !label.trim() || label.length > 300 || /[\r\n\x00-\x1f\x7f]/.test(label) || + typeof prefix !== 'string' || !prefix.trim() || prefix.length > 500 || /[\r\n\x00-\x1f\x7f]/.test(prefix)) throw new Error('invalid notice text'); + const escaped = label.replace(/[\\\[\]]/g, '\\$&'); + return `${prefix} [${escaped}](${successorLink(target)})`; +} + +/** Compare a trusted, complete transcript observation; this does not obtain one. */ +export function matchesFinalNotice(observation, { session, message }) { + if (!observation || observation.complete !== true || observation.session !== session || + typeof session !== 'string' || !session || typeof message !== 'string' || !message || + !Array.isArray(observation.messages) || !observation.messages.length) return false; + const last = observation.messages.at(-1); + return Boolean(last && last.role === 'assistant' && last.text === message); +} diff --git a/packages/tmux-bridge/test/handover-notice.test.mjs b/packages/tmux-bridge/test/handover-notice.test.mjs new file mode 100644 index 00000000..6578b046 --- /dev/null +++ b/packages/tmux-bridge/test/handover-notice.test.mjs @@ -0,0 +1,23 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { successorLink, formatFinalNotice, matchesFinalNotice } from '../bin/handover-notice.mjs'; + +test('successor links preserve same-project anchors, cross-project links and Codex threads', () => { + assert.equal(successorLink({ kind: 'cloud', sourceProject: 'chan_a', targetProject: 'chan_a', thread: 'cmsg_abc' }), '#cmsg_abc'); + assert.equal(successorLink({ kind: 'cloud', sourceProject: 'chan_a', targetProject: 'chan_b', thread: 'cmsg_abc' }), 'https://claude.ai/code/project/chan_b?thread=cmsg_abc'); + assert.equal(successorLink({ kind: 'codex', id: '22222222-2222-4222-8222-222222222222' }), 'codex://threads/22222222-2222-4222-8222-222222222222'); + for (const target of [{ kind: 'codex', id: 'short' }, { kind: 'cloud', sourceProject: 'a', targetProject: 'b?evil', thread: 'cmsg_abc' }, { kind: 'cloud', sourceProject: 'a', targetProject: 'a', thread: 'wrong' }]) assert.throws(() => successorLink(target)); +}); +test('notice text escapes labels and rejects injected lines', () => { + const target = { kind: 'cloud', sourceProject: 'a', targetProject: 'a', thread: 'cmsg_abc' }; + assert.equal(formatFinalNotice({ target, label: 'Next [session]', prefix: 'Continue:' }), 'Continue: [Next \\[session\\]](#cmsg_abc)'); + assert.throws(() => formatFinalNotice({ target, label: 'next\nextra', prefix: 'Continue:' })); +}); +test('a notice must be the observed final assistant message in the original session', () => { + const expected = { session: 'codex:old', message: 'Continue here.' }; + const observation = { complete: true, session: expected.session, messages: [{ role: 'assistant', text: expected.message }] }; + assert.equal(matchesFinalNotice(observation, expected), true); + assert.equal(matchesFinalNotice({ ...observation, complete: false }, expected), false); + assert.equal(matchesFinalNotice({ ...observation, session: 'codex:other' }, expected), false); + assert.equal(matchesFinalNotice({ ...observation, messages: [...observation.messages, { role: 'user', text: 'later' }] }, expected), false); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index 2b76fdf3..aa01a31d 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -45,6 +45,7 @@ const agentTmuxBundleFiles = [ "bin/plexus.mjs", "bin/channel-state.mjs", "bin/handover-state-proof.mjs", + "bin/handover-notice.mjs", "bin/restart-state.mjs", "bin/restart-yaml.py", "bin/ledger-view.mjs", diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 7e7c7150..7713e2b3 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -10,5 +10,6 @@ export const plexusDiagram = `flowchart LR Queue -- "bound receipt" --> Session Yaml["Bounded YAML decoder"] --> Restart Restart["Restart state contract"] -. "planned validation" .-> Handover + Notice["Successor notice formatter"] -. "planned publication" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel `; diff --git a/skills/agent-tmux/bin/handover-notice.mjs b/skills/agent-tmux/bin/handover-notice.mjs new file mode 100644 index 00000000..8ab384c4 --- /dev/null +++ b/skills/agent-tmux/bin/handover-notice.mjs @@ -0,0 +1,32 @@ +/** Build a successor link from resolved identifiers, never from a guessed URL. */ +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const projectId = /^[A-Za-z0-9_-]{1,256}$/; +const threadId = /^cmsg_[A-Za-z0-9_-]{1,250}$/; + +export function successorLink(target) { + if (!target || typeof target !== 'object') throw new Error('invalid successor'); + if (target.kind === 'codex' && typeof target.id === 'string' && uuid.test(target.id)) return `codex://threads/${target.id}`; + if (target.kind === 'cloud' && typeof target.sourceProject === 'string' && projectId.test(target.sourceProject) && + typeof target.targetProject === 'string' && projectId.test(target.targetProject) && + typeof target.thread === 'string' && threadId.test(target.thread)) { + return target.sourceProject === target.targetProject ? `#${target.thread}` : + `https://claude.ai/code/project/${target.targetProject}?thread=${target.thread}`; + } + throw new Error('invalid successor link identifiers'); +} + +export function formatFinalNotice({ target, label, prefix }) { + if (typeof label !== 'string' || !label.trim() || label.length > 300 || /[\r\n\x00-\x1f\x7f]/.test(label) || + typeof prefix !== 'string' || !prefix.trim() || prefix.length > 500 || /[\r\n\x00-\x1f\x7f]/.test(prefix)) throw new Error('invalid notice text'); + const escaped = label.replace(/[\\\[\]]/g, '\\$&'); + return `${prefix} [${escaped}](${successorLink(target)})`; +} + +/** Compare a trusted, complete transcript observation; this does not obtain one. */ +export function matchesFinalNotice(observation, { session, message }) { + if (!observation || observation.complete !== true || observation.session !== session || + typeof session !== 'string' || !session || typeof message !== 'string' || !message || + !Array.isArray(observation.messages) || !observation.messages.length) return false; + const last = observation.messages.at(-1); + return Boolean(last && last.role === 'assistant' && last.text === message); +} From b701620884cbab16409a92fea7c9388393e76108 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:21:43 +0000 Subject: [PATCH 031/113] Inspect correlated Codex final notice snapshots --- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-channels.md | 9 +++ .../bin/handover-codex-observation.mjs | 75 +++++++++++++++++++ .../test/handover-codex-observation.test.mjs | 57 ++++++++++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-diagram.mjs | 1 + .../bin/handover-codex-observation.mjs | 75 +++++++++++++++++++ 7 files changed, 219 insertions(+) create mode 100644 packages/tmux-bridge/bin/handover-codex-observation.mjs create mode 100644 packages/tmux-bridge/test/handover-codex-observation.test.mjs create mode 100644 skills/agent-tmux/bin/handover-codex-observation.mjs diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index e084ceb5..c2129ac1 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -10,4 +10,5 @@ flowchart LR Yaml["Bounded YAML decoder"] --> Restart Restart["Restart state contract"] -. "planned validation" .-> Handover Notice["Successor notice formatter"] -. "planned publication" .-> Handover + Observation["Codex notice snapshot"] -. "planned finality check" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 0b5a8fbf..7665c14e 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -47,3 +47,12 @@ URLs. Its transcript comparison is only a predicate: an authenticated adapter must independently supply a complete observation and prove the successor's identity. Formatting or matching caller-supplied data alone is not evidence of publication, finality or authorization to archive. + +`handover-codex-observation.mjs` can inspect a bounded local Codex transcript +snapshot for a correlated request followed by the exact final notice and a +matching completed turn. It fails closed for ambiguous files, malformed or +partial records, and identity mismatches. It returns hashes, never transcript +contents. This observation is local evidence at the instant read, not proof +that no later turn can arrive; safe finality still requires exclusive lifecycle +control and an authenticated source. Claude and cloud transcripts are not +supported by this observer. diff --git a/packages/tmux-bridge/bin/handover-codex-observation.mjs b/packages/tmux-bridge/bin/handover-codex-observation.mjs new file mode 100644 index 00000000..00712de5 --- /dev/null +++ b/packages/tmux-bridge/bin/handover-codex-observation.mjs @@ -0,0 +1,75 @@ +/** Read-only final-notice evidence from a local Codex transcript snapshot. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const MAX_TRANSCRIPT = 128 * 1024 * 1024; + +function textOf(record, role) { + const payload = record?.payload; + if (record?.type === 'event_msg' && payload?.type === (role === 'user' ? 'user_message' : 'agent_message')) return typeof payload.message === 'string' ? payload.message : null; + if (record?.type !== 'response_item' || payload?.type !== 'message' || payload.role !== role || !Array.isArray(payload.content)) return null; + const type = role === 'user' ? 'input_text' : 'output_text'; + const parts = payload.content.filter(item => item?.type === type && typeof item.text === 'string').map(item => item.text); + return parts.length ? parts.join('\n') : null; +} + +/** An observation proves only the snapshot read; a later turn may still arrive. */ +export async function observeCodexFinalNotice({ root, id, nonce, message }) { + if (!isAbsolute(root) || typeof id !== 'string' || !UUID.test(id) || typeof nonce !== 'string' || !nonce.startsWith('handover-') || !UUID.test(nonce.slice('handover-'.length)) || + typeof message !== 'string' || !message || Buffer.byteLength(message) > 8192) throw new Error('invalid notice observation request'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const candidates = entries.filter(entry => entry.isFile() && entry.name.toLowerCase().endsWith(`${id.toLowerCase()}.jsonl`)) + .map(entry => join(entry.parentPath, entry.name)); + if (candidates.length !== 1) throw new Error('transcript identity unavailable or ambiguous'); + const path = candidates[0]; + if (await realpath(path) !== path) throw new Error('non-canonical transcript'); + const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await handle.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > MAX_TRANSCRIPT) throw new Error('invalid transcript file'); + bytes = await handle.readFile(); + const after = await handle.stat(); + const current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + } finally { await handle.close(); } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let meta = false, anchored = false, lastAssistant = null, completed = false; + for (const line of text.split('\n')) { + if (!line) continue; + let record; + try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + if (record.type === 'session_meta') { + if (meta || record?.payload?.id !== id) throw new Error('transcript session mismatch'); + meta = true; + continue; + } + if (!meta) throw new Error('transcript session metadata missing'); + const user = textOf(record, 'user'); + if (user !== null) { + const newAnchor = user.includes(`[HANDOVER:${nonce}]`); + // Native transcripts can repeat the same user message in two formats. + if (!(anchored && newAnchor && lastAssistant === null && !completed)) { anchored = newAnchor; lastAssistant = null; completed = false; } + continue; + } + if (record.type === 'event_msg' && record?.payload?.type === 'task_started' && completed) { anchored = false; completed = false; lastAssistant = null; } + if (anchored && record.type === 'response_item' && ['function_call', 'custom_tool_call'].includes(record?.payload?.type)) { lastAssistant = null; completed = false; } + const assistant = textOf(record, 'assistant'); + if (assistant !== null && anchored) { if (completed) completed = false; lastAssistant = assistant; } + if (record.type === 'event_msg' && record?.payload?.type === 'task_complete' && anchored) { + completed = lastAssistant === message && record.payload.last_agent_message === message; + } + } + if (!meta || !anchored || !completed) throw new Error('final notice not proven in transcript snapshot'); + return { schema: 'agent-mesh.final-notice-observation.v1', session: `codex:${id}`, nonce, + messageSha256: createHash('sha256').update(message).digest('hex'), transcriptSha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length }; +} diff --git a/packages/tmux-bridge/test/handover-codex-observation.test.mjs b/packages/tmux-bridge/test/handover-codex-observation.test.mjs new file mode 100644 index 00000000..1ce7bdc0 --- /dev/null +++ b/packages/tmux-bridge/test/handover-codex-observation.test.mjs @@ -0,0 +1,57 @@ +import assert from 'node:assert/strict'; +import { appendFile, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import test from 'node:test'; +import { observeCodexFinalNotice } from '../bin/handover-codex-observation.mjs'; + +const id = '22222222-2222-4222-8222-222222222222', nonce = 'handover-44444444-4444-4444-8444-444444444444', message = 'Continue: [next](codex://threads/33333333-3333-4333-8333-333333333333)'; +const line = value => JSON.stringify(value) + '\n'; +const meta = () => line({ type: 'session_meta', payload: { id } }); +const input = () => line({ type: 'event_msg', payload: { type: 'user_message', message: `[HANDOVER:${nonce}] Write the final notice.` } }); +const output = () => line({ type: 'response_item', payload: { type: 'message', role: 'assistant', phase: 'final_answer', content: [{ type: 'output_text', text: message }] } }); +const complete = () => line({ type: 'event_msg', payload: { type: 'task_complete', last_agent_message: message } }); + +async function fixture(t) { + const root = await mkdtemp(join(tmpdir(), 'notice-observation-')); + t.after(() => rm(root, { recursive: true, force: true })); + const path = join(root, `rollout-${id}.jsonl`); + await writeFile(path, meta() + input() + output() + complete(), { mode: 0o600 }); + return { root, path, run: () => observeCodexFinalNotice({ root, id, nonce, message }) }; +} +test('a correlated final Codex notice is observed without returning transcript text', async t => { + const f = await fixture(t), result = await f.run(); + assert.equal(result.session, `codex:${id}`); + assert.match(result.messageSha256, /^[a-f0-9]{64}$/); + assert.ok(!JSON.stringify(result).includes(message)); +}); +test('a later user turn or malformed trailing record rejects the observation', async t => { + const f = await fixture(t); + await appendFile(f.path, line({ type: 'event_msg', payload: { type: 'user_message', message: 'later' } })); + await assert.rejects(f.run(), /not proven/); + await writeFile(f.path, meta() + input() + output() + complete() + '{bad}\n'); + await assert.rejects(f.run(), /invalid transcript record/); + await writeFile(f.path, meta() + input() + output() + complete() + '{partial'); + await assert.rejects(f.run(), /partial transcript/); +}); +test('identity, exact completion, and an unambiguous native transcript are required', async t => { + const f = await fixture(t); + await writeFile(f.path, line({ type: 'session_meta', payload: { id: 'other' } }) + input() + output() + complete()); + await assert.rejects(f.run(), /session mismatch/); + await writeFile(f.path, meta() + input() + output() + line({ type: 'event_msg', payload: { type: 'task_complete', last_agent_message: 'different' } })); + await assert.rejects(f.run(), /not proven/); + await writeFile(f.path, meta() + input() + output() + line({ type: 'response_item', payload: { type: 'function_call' } }) + complete()); + await assert.rejects(f.run(), /not proven/); + await writeFile(f.path, meta() + input() + output() + complete() + line({ type: 'event_msg', payload: { type: 'task_started' } })); + await assert.rejects(f.run(), /not proven/); + await writeFile(f.path, meta() + input() + output() + complete()); + await writeFile(join(f.root, `duplicate-${id}.jsonl`), meta() + input() + output() + complete()); + await assert.rejects(f.run(), /ambiguous/); +}); +test('a symlinked transcript is not accepted', async t => { + const f = await fixture(t), other = join(f.root, 'unrelated'); + await writeFile(other, meta() + input() + output() + complete()); + await rm(f.path); + await symlink(other, f.path); + await assert.rejects(f.run(), /unavailable or ambiguous/); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index aa01a31d..9566bc45 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -46,6 +46,7 @@ const agentTmuxBundleFiles = [ "bin/channel-state.mjs", "bin/handover-state-proof.mjs", "bin/handover-notice.mjs", + "bin/handover-codex-observation.mjs", "bin/restart-state.mjs", "bin/restart-yaml.py", "bin/ledger-view.mjs", diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 7713e2b3..79dbe0f7 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -11,5 +11,6 @@ export const plexusDiagram = `flowchart LR Yaml["Bounded YAML decoder"] --> Restart Restart["Restart state contract"] -. "planned validation" .-> Handover Notice["Successor notice formatter"] -. "planned publication" .-> Handover + Observation["Codex notice snapshot"] -. "planned finality check" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel `; diff --git a/skills/agent-tmux/bin/handover-codex-observation.mjs b/skills/agent-tmux/bin/handover-codex-observation.mjs new file mode 100644 index 00000000..00712de5 --- /dev/null +++ b/skills/agent-tmux/bin/handover-codex-observation.mjs @@ -0,0 +1,75 @@ +/** Read-only final-notice evidence from a local Codex transcript snapshot. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const MAX_TRANSCRIPT = 128 * 1024 * 1024; + +function textOf(record, role) { + const payload = record?.payload; + if (record?.type === 'event_msg' && payload?.type === (role === 'user' ? 'user_message' : 'agent_message')) return typeof payload.message === 'string' ? payload.message : null; + if (record?.type !== 'response_item' || payload?.type !== 'message' || payload.role !== role || !Array.isArray(payload.content)) return null; + const type = role === 'user' ? 'input_text' : 'output_text'; + const parts = payload.content.filter(item => item?.type === type && typeof item.text === 'string').map(item => item.text); + return parts.length ? parts.join('\n') : null; +} + +/** An observation proves only the snapshot read; a later turn may still arrive. */ +export async function observeCodexFinalNotice({ root, id, nonce, message }) { + if (!isAbsolute(root) || typeof id !== 'string' || !UUID.test(id) || typeof nonce !== 'string' || !nonce.startsWith('handover-') || !UUID.test(nonce.slice('handover-'.length)) || + typeof message !== 'string' || !message || Buffer.byteLength(message) > 8192) throw new Error('invalid notice observation request'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const candidates = entries.filter(entry => entry.isFile() && entry.name.toLowerCase().endsWith(`${id.toLowerCase()}.jsonl`)) + .map(entry => join(entry.parentPath, entry.name)); + if (candidates.length !== 1) throw new Error('transcript identity unavailable or ambiguous'); + const path = candidates[0]; + if (await realpath(path) !== path) throw new Error('non-canonical transcript'); + const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await handle.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > MAX_TRANSCRIPT) throw new Error('invalid transcript file'); + bytes = await handle.readFile(); + const after = await handle.stat(); + const current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + } finally { await handle.close(); } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let meta = false, anchored = false, lastAssistant = null, completed = false; + for (const line of text.split('\n')) { + if (!line) continue; + let record; + try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + if (record.type === 'session_meta') { + if (meta || record?.payload?.id !== id) throw new Error('transcript session mismatch'); + meta = true; + continue; + } + if (!meta) throw new Error('transcript session metadata missing'); + const user = textOf(record, 'user'); + if (user !== null) { + const newAnchor = user.includes(`[HANDOVER:${nonce}]`); + // Native transcripts can repeat the same user message in two formats. + if (!(anchored && newAnchor && lastAssistant === null && !completed)) { anchored = newAnchor; lastAssistant = null; completed = false; } + continue; + } + if (record.type === 'event_msg' && record?.payload?.type === 'task_started' && completed) { anchored = false; completed = false; lastAssistant = null; } + if (anchored && record.type === 'response_item' && ['function_call', 'custom_tool_call'].includes(record?.payload?.type)) { lastAssistant = null; completed = false; } + const assistant = textOf(record, 'assistant'); + if (assistant !== null && anchored) { if (completed) completed = false; lastAssistant = assistant; } + if (record.type === 'event_msg' && record?.payload?.type === 'task_complete' && anchored) { + completed = lastAssistant === message && record.payload.last_agent_message === message; + } + } + if (!meta || !anchored || !completed) throw new Error('final notice not proven in transcript snapshot'); + return { schema: 'agent-mesh.final-notice-observation.v1', session: `codex:${id}`, nonce, + messageSha256: createHash('sha256').update(message).digest('hex'), transcriptSha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length }; +} From 417ddd5fe6c94159f3050f8eb6a9ba598bca90df Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:31:20 +0000 Subject: [PATCH 032/113] Represent observed session wake events --- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-modules.md | 10 +++++++++- packages/tmux-bridge/bin/plexus.mjs | 3 ++- packages/tmux-bridge/test/plexus.test.mjs | 21 +++++++++++++++++++++ scripts/plexus-diagram.mjs | 1 + skills/agent-tmux/bin/plexus.mjs | 3 ++- 6 files changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index c2129ac1..d302be44 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -4,6 +4,7 @@ flowchart LR Channel --> Session["Current session"] Queue --> Journal["Graph event journal"] Session --> Journal + Wake["Wake observation"] -. "planned producer" .-> Journal Module["Registered module"] --> Contract["Versioned JSON contract"] Contract --> Journal Queue -- "bound receipt" --> Session diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index 4c839b37..0a171589 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -11,12 +11,20 @@ must be explicitly configured; absence of configuration enables no modules. ## Lifecycle evidence -The lifecycle vocabulary is `session.started`, `session.idle`, +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. + 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 diff --git a/packages/tmux-bridge/bin/plexus.mjs b/packages/tmux-bridge/bin/plexus.mjs index 4d9ef0d2..1ccf49b6 100644 --- a/packages/tmux-bridge/bin/plexus.mjs +++ b/packages/tmux-bridge/bin/plexus.mjs @@ -19,7 +19,7 @@ export const LINK_SOURCES = /^(bridge-launch|hook|ledger-write|reconciler|operat export const ROLE_WEIGHTS = { owns: 1, "works-on": 1, coordinates: 0.8, reviews: 0.7, discusses: 0.6, observes: 0.3, mentioned: 0.2 }; export const HALF_LIFE_DAYS = 7; export const TOUCH_COALESCE_MS = 10 * 60 * 1000; -export const LIFECYCLE_EVENTS = new Set(["session.started", "session.idle", "session.compacted", "session.stopped", "session.handover"]); +export const LIFECYCLE_EVENTS = new Set(["session.started", "session.woken", "session.idle", "session.compacted", "session.stopped", "session.handover"]); export const PLEXUS_EVENTS = new Set(["channel.updated", "role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated", ...LIFECYCLE_EVENTS]); const HARNESSES = new Set(["codex", "claude"]); const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i; @@ -92,6 +92,7 @@ export function applyPlexusEvent(state, item) { state.channels.set(item.channel.id, item.channel); break; case "session.started": + case "session.woken": case "session.idle": case "session.compacted": case "session.stopped": diff --git a/packages/tmux-bridge/test/plexus.test.mjs b/packages/tmux-bridge/test/plexus.test.mjs index 27560c58..5219def8 100644 --- a/packages/tmux-bridge/test/plexus.test.mjs +++ b/packages/tmux-bridge/test/plexus.test.mjs @@ -61,6 +61,27 @@ test("lifecycle feed exposes evidence locally but not to scoped consumers", asyn assert.ok(!("evidence" in scoped.events[0])); }); +test("observed wake events are session-bound and retries do not double count", async (t) => { + const state = await mkdtemp(join(tmpdir(), "plexus-wake-")); + t.after(() => rm(state, { recursive: true, force: true })); + await seed(state); + await ok(state, ["migrate", "--apply"]); + const cursor = (await query(state, "changes", { initial: "head" })).cursor; + const args = ["lifecycle", "record", "--session", `codex:${CODEX}`, "--type", "session.woken", "--id", "wake-example", "--evidence", "native:turn-example"]; + assert.equal((await ok(state, args)).duplicate, false); + assert.equal((await ok(state, args)).duplicate, true); + assert.notEqual((await run(state, [...args.slice(0, -1), "native:other"])).code, 0); + const feed = await query(state, "changes", { sinceCursor: cursor }); + const wake = feed.events.filter(event => event.type === "session.woken"); + assert.equal(wake.length, 1); + assert.equal(wake[0].session, `codex:${CODEX}`); + assert.equal(wake[0].evidence, "native:turn-example"); + assert.ok(wake[0].eventId && Number.isSafeInteger(wake[0].seq) && wake[0].at && wake[0].host); + const scoped = await query(state, "changes", { sinceCursor: cursor, scope: scopeA }); + assert.equal(scoped.events.filter(event => event.type === "session.woken").length, 1); + assert.ok(!('evidence' in scoped.events.find(event => event.type === "session.woken"))); +}); + test("cloud registration has exact account-qualified identity and survives graph replay", async (t) => { const state = await mkdtemp(join(tmpdir(), "plexus-cloud-")); t.after(() => rm(state, { recursive: true, force: true })); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 79dbe0f7..9fc40403 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -5,6 +5,7 @@ export const plexusDiagram = `flowchart LR Channel --> Session["Current session"] Queue --> Journal["Graph event journal"] Session --> Journal + Wake["Wake observation"] -. "planned producer" .-> Journal Module["Registered module"] --> Contract["Versioned JSON contract"] Contract --> Journal Queue -- "bound receipt" --> Session diff --git a/skills/agent-tmux/bin/plexus.mjs b/skills/agent-tmux/bin/plexus.mjs index 4d9ef0d2..1ccf49b6 100644 --- a/skills/agent-tmux/bin/plexus.mjs +++ b/skills/agent-tmux/bin/plexus.mjs @@ -19,7 +19,7 @@ export const LINK_SOURCES = /^(bridge-launch|hook|ledger-write|reconciler|operat export const ROLE_WEIGHTS = { owns: 1, "works-on": 1, coordinates: 0.8, reviews: 0.7, discusses: 0.6, observes: 0.3, mentioned: 0.2 }; export const HALF_LIFE_DAYS = 7; export const TOUCH_COALESCE_MS = 10 * 60 * 1000; -export const LIFECYCLE_EVENTS = new Set(["session.started", "session.idle", "session.compacted", "session.stopped", "session.handover"]); +export const LIFECYCLE_EVENTS = new Set(["session.started", "session.woken", "session.idle", "session.compacted", "session.stopped", "session.handover"]); export const PLEXUS_EVENTS = new Set(["channel.updated", "role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated", ...LIFECYCLE_EVENTS]); const HARNESSES = new Set(["codex", "claude"]); const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i; @@ -92,6 +92,7 @@ export function applyPlexusEvent(state, item) { state.channels.set(item.channel.id, item.channel); break; case "session.started": + case "session.woken": case "session.idle": case "session.compacted": case "session.stopped": From cacc6278d925a9af908c346a03fb7f8a0f5cc490 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:42:04 +0000 Subject: [PATCH 033/113] Handle exited process during inbox test cleanup --- packages/tmux-bridge/test/session-inbox.test.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/tmux-bridge/test/session-inbox.test.py b/packages/tmux-bridge/test/session-inbox.test.py index 3bec63f3..a689e11a 100644 --- a/packages/tmux-bridge/test/session-inbox.test.py +++ b/packages/tmux-bridge/test/session-inbox.test.py @@ -208,7 +208,7 @@ def test_detached_service_survives_hook_exit_and_delivers_only_real_batches(self while time.monotonic() Date: Mon, 16 Nov 2026 17:01:31 +0000 Subject: [PATCH 034/113] Record verifiable Codex compaction evidence --- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-modules.md | 18 ++++ .../bin/codex-compaction-evidence.mjs | 100 ++++++++++++++++++ .../test/codex-compaction-evidence.test.mjs | 77 ++++++++++++++ .../tmux-bridge/test/plexus-privacy.test.mjs | 3 + scripts/mesh-readiness.mjs | 1 + scripts/plexus-diagram.mjs | 1 + scripts/plexus-privacy.mjs | 2 +- .../bin/codex-compaction-evidence.mjs | 100 ++++++++++++++++++ 9 files changed, 302 insertions(+), 1 deletion(-) create mode 100644 packages/tmux-bridge/bin/codex-compaction-evidence.mjs create mode 100644 packages/tmux-bridge/test/codex-compaction-evidence.test.mjs create mode 100644 skills/agent-tmux/bin/codex-compaction-evidence.mjs diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index d302be44..2ec28154 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -5,6 +5,7 @@ flowchart LR Queue --> Journal["Graph event journal"] Session --> Journal Wake["Wake observation"] -. "planned producer" .-> Journal + Compaction["Codex compaction evidence"] --> Journal Module["Registered module"] --> Contract["Versioned JSON contract"] Contract --> Journal Queue -- "bound receipt" --> Session diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index 0a171589..27bb07b7 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -25,6 +25,24 @@ 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. +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 --session +--evidence-root `, 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 diff --git a/packages/tmux-bridge/bin/codex-compaction-evidence.mjs b/packages/tmux-bridge/bin/codex-compaction-evidence.mjs new file mode 100644 index 00000000..1d0ae997 --- /dev/null +++ b/packages/tmux-bridge/bin/codex-compaction-evidence.mjs @@ -0,0 +1,100 @@ +#!/usr/bin/env node +/** Observe one native compaction and commit an idempotent local evidence reference. */ +import { parseArgs } from 'node:util'; +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { spawnSync } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { withCodexAppServer } from './codex-app-server.mjs'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = text => createHash('sha256').update(text).digest('hex'); +const here = dirname(fileURLToPath(import.meta.url)); + +export function compactionFromThread(response, { thread, turn, item }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof turn !== 'string' || !TOKEN.test(turn) || typeof item !== 'string' || !TOKEN.test(item) || response?.thread?.id !== thread || !Array.isArray(response.thread.turns)) throw new Error('native thread identity unavailable'); + const turns = response.thread.turns.filter(value => value?.id === turn); + if (turns.length !== 1 || turns[0].itemsView !== 'full' || !Array.isArray(turns[0].items)) throw new Error('native turn unavailable or incomplete'); + const items = turns[0].items.filter(value => value?.id === item); + if (items.length !== 1 || items[0].type !== 'contextCompaction' || !Number.isSafeInteger(items[0].completedAtMs) || items[0].completedAtMs <= 0) throw new Error('completed compaction unavailable'); + return { schema: 'agent-mesh.codex-compaction-evidence.v1', source: 'codex-app-server.thread-read', session: `codex:${thread}`, turn, item, completedAtMs: items[0].completedAtMs }; +} + +async function privateRoot(root) { + if (!isAbsolute(root)) throw new Error('invalid evidence root'); + const info = await lstat(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('evidence root must be private and canonical'); +} + +async function persistEvidence(root, body) { + await privateRoot(root); + const digest = hash(body), path = join(root, `${digest}.json`); + let file; + try { + file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + await file.writeFile(body); + await file.sync(); + } catch (error) { + if (error.code !== 'EEXIST') throw error; + file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + const info = await file.stat(); + if (!info.isFile() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0 || info.size !== Buffer.byteLength(body) || await file.readFile('utf8') !== body) throw new Error('existing evidence mismatch'); + } finally { if (file) await file.close(); } + const directory = await open(root, constants.O_RDONLY); + try { await directory.sync(); } finally { await directory.close(); } + return `codex-compaction:${digest}`; +} + +/** Verify a record from the operator's trusted private evidence root. */ +export async function verifyCodexCompactionEvidence({ evidenceRoot, reference, session }) { + if (typeof reference !== 'string' || !/^codex-compaction:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid evidence request'); + await privateRoot(evidenceRoot); + const path = join(evidenceRoot, `${reference.slice('codex-compaction:'.length)}.json`); + const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let body; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid evidence file'); + body = await file.readFile('utf8'); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('evidence changed during verification'); + } finally { await file.close(); } + if (`codex-compaction:${hash(body)}` !== reference) throw new Error('evidence digest mismatch'); + let value; + try { value = JSON.parse(body); } catch { throw new Error('invalid evidence record'); } + if (!value || Object.keys(value).sort().join(',') !== 'completedAtMs,item,schema,session,source,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-compaction-evidence.v1' || value.source !== 'codex-app-server.thread-read' || value.session !== session || typeof value.turn !== 'string' || !TOKEN.test(value.turn) || typeof value.item !== 'string' || !TOKEN.test(value.item) || !Number.isSafeInteger(value.completedAtMs) || value.completedAtMs <= 0) throw new Error('evidence identity mismatch'); + return { schema: value.schema, session, turn: value.turn, item: value.item, completedAtMs: value.completedAtMs, evidence: reference }; +} + +export async function recordCodexCompaction({ thread, turn, item, evidenceRoot, graphState }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof turn !== 'string' || !TOKEN.test(turn) || typeof item !== 'string' || !TOKEN.test(item) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('invalid observation identity or graph state'); + await privateRoot(evidenceRoot); + const response = await withCodexAppServer({ clientName: 'agent-mesh-compaction-evidence', timeout: 30000, timeoutMessage: 'native observation timed out' }, request => request('thread/read', { threadId: thread, includeTurns: true })); + const evidence = compactionFromThread(response, { thread, turn, item }); + const reference = await persistEvidence(evidenceRoot, `${JSON.stringify(evidence)}\n`); + const observation = `codex-compaction-${hash(JSON.stringify([thread, turn, item]))}`; + const args = [join(here, 'mesh-graph.mjs'), '--state', graphState]; + args.push('lifecycle', 'record', '--type', 'session.compacted', '--session', evidence.session, '--id', observation, '--evidence', reference); + const result = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (result.error || result.status !== 0) throw new Error('graph recording failed; retain evidence and retry with the same identity'); + let receipt; + try { receipt = JSON.parse(result.stdout); } catch { throw new Error('graph receipt unavailable'); } + if (receipt?.observation !== observation || typeof receipt.duplicate !== 'boolean') throw new Error('graph receipt mismatch'); + return { schema: 'agent-mesh.compaction-record.v1', session: evidence.session, evidence: reference, duplicate: receipt.duplicate }; +} + +if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { + try { + const { values } = parseArgs({ options: { thread: { type: 'string' }, turn: { type: 'string' }, item: { type: 'string' }, verify: { type: 'string' }, session: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' } }, strict: true }); + if (values.verify !== undefined) { + if (values.thread || values.turn || values.item || values['graph-state']) throw new Error('invalid verify options'); + console.log(JSON.stringify(await verifyCodexCompactionEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }))); + } else { + if (values.session) throw new Error('invalid record options'); + console.log(JSON.stringify(await recordCodexCompaction({ thread: values.thread, turn: values.turn, item: values.item, evidenceRoot: values['evidence-root'], graphState: values['graph-state'] }))); + } + } catch { console.error('compaction observation or recording failed; inspect locally before retry'); process.exitCode = 1; } +} diff --git a/packages/tmux-bridge/test/codex-compaction-evidence.test.mjs b/packages/tmux-bridge/test/codex-compaction-evidence.test.mjs new file mode 100644 index 00000000..8788fd0e --- /dev/null +++ b/packages/tmux-bridge/test/codex-compaction-evidence.test.mjs @@ -0,0 +1,77 @@ +import assert from 'node:assert/strict'; +import { execFile } from 'node:child_process'; +import { chmod, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { promisify } from 'node:util'; +import test from 'node:test'; +import { compactionFromThread, verifyCodexCompactionEvidence } from '../bin/codex-compaction-evidence.mjs'; +import { createAppServer } from './fixtures/fake-app-server.mjs'; + +const exec = promisify(execFile), thread = '22222222-2222-4222-8222-222222222222', turn = 'turn-fixture', item = 'item-fixture'; +const bin = fileURLToPath(new URL('../bin/codex-compaction-evidence.mjs', import.meta.url)); +const graph = fileURLToPath(new URL('../bin/mesh-graph.mjs', import.meta.url)); +const response = () => ({ thread: { id: thread, turns: [{ id: turn, itemsView: 'full', items: [{ id: item, type: 'contextCompaction', completedAtMs: 123456789 }] }] } }); + +test('only an exact completed native compaction in a full turn is accepted', () => { + const identity = { thread, turn, item }; + assert.equal(compactionFromThread(response(), identity).completedAtMs, 123456789); + const missingTime = response(); missingTime.thread.turns[0].items[0].completedAtMs = null; + const summary = response(); summary.thread.turns[0].itemsView = 'summary'; + const wrongType = response(); wrongType.thread.turns[0].items[0].type = 'agentMessage'; + const duplicate = response(); duplicate.thread.turns.push(duplicate.thread.turns[0]); + const duplicateItem = response(); duplicateItem.thread.turns[0].items.push(duplicateItem.thread.turns[0].items[0]); + for (const value of [missingTime, summary, wrongType, duplicate, duplicateItem, { thread: { id: 'other', turns: [] } }]) assert.throws(() => compactionFromThread(value, identity)); +}); + +test('native read records private evidence before an idempotent graph event', async t => { + const root = await mkdtemp(join(tmpdir(), 'compaction-evidence-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = join(root, 'graph'), evidence = join(root, 'evidence'), socket = join(root, 'fake.sock'); + await mkdir(state, { mode: 0o700 }); await mkdir(evidence, { mode: 0o700 }); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, '--state', state, ...args])).stdout); + const requests = []; let completedAtMs = 123456789; + const server = createAppServer((request, peer) => { + if (!request.id) return; + if (request.method === 'thread/read') { requests.push(request); const data = response(); data.thread.turns[0].items[0].completedAtMs = completedAtMs; peer.send({ id: request.id, result: data }); } + else peer.send({ id: request.id, result: {} }); + }); + await new Promise(resolve => server.listen(socket, resolve)); + t.after(() => new Promise(resolve => server.close(resolve))); + const env = { ...process.env, CODEX_REMOTE_SOCK: socket, CODEX_NO_REMOTE: '' }; + const run = async () => JSON.parse((await exec(process.execPath, [bin, '--thread', thread, '--turn', turn, '--item', item, '--evidence-root', evidence, '--graph-state', state], { env })).stdout); + await assert.rejects(exec(process.execPath, [bin, '--thread', thread, '--turn', turn, '--item', item, '--evidence-root', evidence], { env })); + assert.equal(requests.length, 0, 'no native observation without an explicit graph'); + assert.deepEqual(await readdir(evidence), []); + await assert.rejects(run()); + assert.equal((await readdir(evidence)).length, 1, 'proof remains after graph rejection'); + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', thread, '--json'); + await call('migrate', '--apply', '--json'); + const cursor = (await call('query', 'changes', '--input', JSON.stringify({ initial: 'head' }))).cursor; + const first = await run(), second = await run(); + assert.equal(first.duplicate, false); assert.equal(second.duplicate, true); + assert.equal(first.evidence, second.evidence); + assert.deepEqual(requests.map(r => r.params), Array(3).fill({ threadId: thread, includeTurns: true })); + const files = await readdir(evidence); assert.equal(files.length, 1); + const saved = JSON.parse(await readFile(join(evidence, files[0]), 'utf8')); + assert.equal(saved.session, `codex:${thread}`); assert.equal(saved.completedAtMs, 123456789); + const verified = await verifyCodexCompactionEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }); + assert.equal(verified.completedAtMs, 123456789); + const cliVerified = JSON.parse((await exec(process.execPath, [bin, '--verify', first.evidence, '--session', `codex:${thread}`, '--evidence-root', evidence], { env })).stdout); + assert.equal(cliVerified.completedAtMs, 123456789); + assert.equal(requests.length, 3, 'verification does not contact the native app server'); + await assert.rejects(verifyCodexCompactionEvidence({ evidenceRoot: evidence, reference: first.evidence, session: 'codex:33333333-3333-4333-8333-333333333333' }), /identity/); + const feed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.deepEqual(feed.events.filter(e => e.type === 'session.compacted').map(e => e.evidence), [first.evidence]); + completedAtMs += 1; + await assert.rejects(run(), /compaction observation or recording failed/); + const afterConflict = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.equal(afterConflict.events.filter(e => e.type === 'session.compacted').length, 1); + const evidenceFile = join(evidence, files[0]); + await chmod(evidenceFile, 0o644); + await assert.rejects(verifyCodexCompactionEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }), /invalid evidence file/); + await chmod(evidenceFile, 0o600); + await writeFile(evidenceFile, JSON.stringify({ ...saved, completedAtMs: 123456780 }) + '\n'); + await assert.rejects(verifyCodexCompactionEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }), /digest/); +}); diff --git a/packages/tmux-bridge/test/plexus-privacy.test.mjs b/packages/tmux-bridge/test/plexus-privacy.test.mjs index 0e976814..552c9850 100644 --- a/packages/tmux-bridge/test/plexus-privacy.test.mjs +++ b/packages/tmux-bridge/test/plexus-privacy.test.mjs @@ -14,6 +14,9 @@ test('only interpreter bytecode in cache directories is excluded from text scann }); test('Plexus public mechanism paths and private references are classified', () => { + assert.equal(isPlexusMechanismFile('packages/tmux-bridge/bin/codex-compaction-evidence.mjs'), true); + assert.equal(isPlexusMechanismFile('packages/tmux-bridge/test/codex-compaction-evidence.test.mjs'), true); + assert.equal(isPlexusMechanismFile('skills/agent-tmux/bin/codex-compaction-evidence.mjs'), true); assert.equal(isPlexusMechanismFile('packages/tmux-bridge/bin/restart-state.mjs'), true); assert.equal(isPlexusMechanismFile('packages/tmux-bridge/test/restart-state.test.mjs'), true); assert.equal(isPlexusMechanismFile('skills/agent-tmux/bin/restart-state.mjs'), true); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index 9566bc45..2e9589b8 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -47,6 +47,7 @@ const agentTmuxBundleFiles = [ "bin/handover-state-proof.mjs", "bin/handover-notice.mjs", "bin/handover-codex-observation.mjs", + "bin/codex-compaction-evidence.mjs", "bin/restart-state.mjs", "bin/restart-yaml.py", "bin/ledger-view.mjs", diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 9fc40403..9e46fee6 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -6,6 +6,7 @@ export const plexusDiagram = `flowchart LR Queue --> Journal["Graph event journal"] Session --> Journal Wake["Wake observation"] -. "planned producer" .-> Journal + Compaction["Codex compaction evidence"] --> Journal Module["Registered module"] --> Contract["Versioned JSON contract"] Contract --> Journal Queue -- "bound receipt" --> Session diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs index fe304ea9..ddbc134f 100644 --- a/scripts/plexus-privacy.mjs +++ b/scripts/plexus-privacy.mjs @@ -6,7 +6,7 @@ const privatePatterns = [ ]; export function isPlexusMechanismFile(relativePath) { - return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|module-batches|mesh-(?:graph|channel)|agent-waker|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); + return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|codex-compaction-|module-batches|mesh-(?:graph|channel)|agent-waker|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); } export function containsPrivatePlexusPolicy(text) { diff --git a/skills/agent-tmux/bin/codex-compaction-evidence.mjs b/skills/agent-tmux/bin/codex-compaction-evidence.mjs new file mode 100644 index 00000000..1d0ae997 --- /dev/null +++ b/skills/agent-tmux/bin/codex-compaction-evidence.mjs @@ -0,0 +1,100 @@ +#!/usr/bin/env node +/** Observe one native compaction and commit an idempotent local evidence reference. */ +import { parseArgs } from 'node:util'; +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { spawnSync } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { withCodexAppServer } from './codex-app-server.mjs'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = text => createHash('sha256').update(text).digest('hex'); +const here = dirname(fileURLToPath(import.meta.url)); + +export function compactionFromThread(response, { thread, turn, item }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof turn !== 'string' || !TOKEN.test(turn) || typeof item !== 'string' || !TOKEN.test(item) || response?.thread?.id !== thread || !Array.isArray(response.thread.turns)) throw new Error('native thread identity unavailable'); + const turns = response.thread.turns.filter(value => value?.id === turn); + if (turns.length !== 1 || turns[0].itemsView !== 'full' || !Array.isArray(turns[0].items)) throw new Error('native turn unavailable or incomplete'); + const items = turns[0].items.filter(value => value?.id === item); + if (items.length !== 1 || items[0].type !== 'contextCompaction' || !Number.isSafeInteger(items[0].completedAtMs) || items[0].completedAtMs <= 0) throw new Error('completed compaction unavailable'); + return { schema: 'agent-mesh.codex-compaction-evidence.v1', source: 'codex-app-server.thread-read', session: `codex:${thread}`, turn, item, completedAtMs: items[0].completedAtMs }; +} + +async function privateRoot(root) { + if (!isAbsolute(root)) throw new Error('invalid evidence root'); + const info = await lstat(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('evidence root must be private and canonical'); +} + +async function persistEvidence(root, body) { + await privateRoot(root); + const digest = hash(body), path = join(root, `${digest}.json`); + let file; + try { + file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + await file.writeFile(body); + await file.sync(); + } catch (error) { + if (error.code !== 'EEXIST') throw error; + file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + const info = await file.stat(); + if (!info.isFile() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0 || info.size !== Buffer.byteLength(body) || await file.readFile('utf8') !== body) throw new Error('existing evidence mismatch'); + } finally { if (file) await file.close(); } + const directory = await open(root, constants.O_RDONLY); + try { await directory.sync(); } finally { await directory.close(); } + return `codex-compaction:${digest}`; +} + +/** Verify a record from the operator's trusted private evidence root. */ +export async function verifyCodexCompactionEvidence({ evidenceRoot, reference, session }) { + if (typeof reference !== 'string' || !/^codex-compaction:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid evidence request'); + await privateRoot(evidenceRoot); + const path = join(evidenceRoot, `${reference.slice('codex-compaction:'.length)}.json`); + const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let body; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid evidence file'); + body = await file.readFile('utf8'); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('evidence changed during verification'); + } finally { await file.close(); } + if (`codex-compaction:${hash(body)}` !== reference) throw new Error('evidence digest mismatch'); + let value; + try { value = JSON.parse(body); } catch { throw new Error('invalid evidence record'); } + if (!value || Object.keys(value).sort().join(',') !== 'completedAtMs,item,schema,session,source,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-compaction-evidence.v1' || value.source !== 'codex-app-server.thread-read' || value.session !== session || typeof value.turn !== 'string' || !TOKEN.test(value.turn) || typeof value.item !== 'string' || !TOKEN.test(value.item) || !Number.isSafeInteger(value.completedAtMs) || value.completedAtMs <= 0) throw new Error('evidence identity mismatch'); + return { schema: value.schema, session, turn: value.turn, item: value.item, completedAtMs: value.completedAtMs, evidence: reference }; +} + +export async function recordCodexCompaction({ thread, turn, item, evidenceRoot, graphState }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof turn !== 'string' || !TOKEN.test(turn) || typeof item !== 'string' || !TOKEN.test(item) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('invalid observation identity or graph state'); + await privateRoot(evidenceRoot); + const response = await withCodexAppServer({ clientName: 'agent-mesh-compaction-evidence', timeout: 30000, timeoutMessage: 'native observation timed out' }, request => request('thread/read', { threadId: thread, includeTurns: true })); + const evidence = compactionFromThread(response, { thread, turn, item }); + const reference = await persistEvidence(evidenceRoot, `${JSON.stringify(evidence)}\n`); + const observation = `codex-compaction-${hash(JSON.stringify([thread, turn, item]))}`; + const args = [join(here, 'mesh-graph.mjs'), '--state', graphState]; + args.push('lifecycle', 'record', '--type', 'session.compacted', '--session', evidence.session, '--id', observation, '--evidence', reference); + const result = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (result.error || result.status !== 0) throw new Error('graph recording failed; retain evidence and retry with the same identity'); + let receipt; + try { receipt = JSON.parse(result.stdout); } catch { throw new Error('graph receipt unavailable'); } + if (receipt?.observation !== observation || typeof receipt.duplicate !== 'boolean') throw new Error('graph receipt mismatch'); + return { schema: 'agent-mesh.compaction-record.v1', session: evidence.session, evidence: reference, duplicate: receipt.duplicate }; +} + +if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { + try { + const { values } = parseArgs({ options: { thread: { type: 'string' }, turn: { type: 'string' }, item: { type: 'string' }, verify: { type: 'string' }, session: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' } }, strict: true }); + if (values.verify !== undefined) { + if (values.thread || values.turn || values.item || values['graph-state']) throw new Error('invalid verify options'); + console.log(JSON.stringify(await verifyCodexCompactionEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }))); + } else { + if (values.session) throw new Error('invalid record options'); + console.log(JSON.stringify(await recordCodexCompaction({ thread: values.thread, turn: values.turn, item: values.item, evidenceRoot: values['evidence-root'], graphState: values['graph-state'] }))); + } + } catch { console.error('compaction observation or recording failed; inspect locally before retry'); process.exitCode = 1; } +} From f3d987e4d96cdb471906e67c6220e4ab3c4eef59 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:05:20 +0000 Subject: [PATCH 035/113] Allow lease cleanup time on busy runners --- packages/tmux-bridge/test/capacity-dispatch.test.mjs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/tmux-bridge/test/capacity-dispatch.test.mjs b/packages/tmux-bridge/test/capacity-dispatch.test.mjs index 781aa19f..da362414 100644 --- a/packages/tmux-bridge/test/capacity-dispatch.test.mjs +++ b/packages/tmux-bridge/test/capacity-dispatch.test.mjs @@ -316,7 +316,9 @@ test("agent-spawn uses a routed native rendering and closes its lease after the const opened = JSON.parse(await readFile(state, "utf8")); assert.deepEqual(opened.sessions[0].candidate, { key: "0123456789abcdef0123456789abcdef", model: "governed-model", effort: "high", capacityCostBase: null }); await waitFor(async () => (await readFile(`${state}.events.ndjson`, "utf8")).includes("lease_renewed")); - await waitFor(async () => JSON.parse(await readFile(state, "utf8")).sessions[0]?.status === "completed", 3_000); + // The fixture sleeps for two seconds; allow the observer to be scheduled + // on a loaded runner while still requiring the lease to complete. + await waitFor(async () => JSON.parse(await readFile(state, "utf8")).sessions[0]?.status === "completed", 15_000); assert.equal((await runCommand("tmux", ["-L", socket, "has-session", "-t", target], env)).code, 0, "the tmux shell remains after the agent process exits"); const events = await readFile(`${state}.events.ndjson`, "utf8"); assert.match(events, /session_active/); From aeb34e3edfc489412c337bd04de25b5851850392 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:19:57 +0000 Subject: [PATCH 036/113] Guard channel reservation by recipient --- packages/tmux-bridge/bin/agent-waker.py | 8 ++++++-- packages/tmux-bridge/bin/channel-state.mjs | 3 ++- packages/tmux-bridge/bin/mesh-graph.mjs | 2 +- .../tmux-bridge/test/agent-waker-channel.test.py | 12 ++++++++++++ .../tmux-bridge/test/plexus-channel-store.test.mjs | 4 +++- skills/agent-tmux/bin/agent-waker.py | 8 ++++++-- skills/agent-tmux/bin/channel-state.mjs | 3 ++- skills/agent-tmux/bin/mesh-graph.mjs | 2 +- 8 files changed, 33 insertions(+), 9 deletions(-) diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index 9fc5bbd3..44d71910 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -234,10 +234,14 @@ def run_channel(args: argparse.Namespace) -> int: if not pending: print(json.dumps({'job': args.job, 'outcome': 'noop'})) return 0 - channel = channel_call(args, 'begin-delivery', '--id', pending['id']) + target = channel['session'] + agent, sep, session = target.partition(':') + if not sep or agent not in ('codex', 'claude'): + raise ValueError('unsupported channel recipient') + channel = channel_call(args, 'begin-delivery', '--id', pending['id'], '--session', target) item = next(item for item in channel['queue'] if item['id'] == pending['id']) agent, sep, session = item['session'].partition(':') - if not sep or agent not in ('codex', 'claude'): + if not sep or agent not in ('codex', 'claude') or item['session'] != target: raise ValueError('unsupported channel recipient') code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, True, resume=args.resume and agent == 'codex', message_stdin=True) diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 7d2216a8..7fdb621a 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -20,8 +20,9 @@ export function enqueue(state, id, payload) { return next; } -export function beginDelivery(state, id) { +export function beginDelivery(state, id, expectedSession) { if (state.phase !== 'active') throw new Error('handover in progress'); + if (expectedSession !== undefined && state.session !== expectedSession) throw new Error('channel recipient changed'); if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); if (state.queue.find((item) => item.state === 'pending')?.id !== id) throw new Error('message is not first pending'); const next = copy(state), item = next.queue.find((row) => row.id === id); diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index e21b1d3b..d7f50b5e 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -159,7 +159,7 @@ try { } else { if (!current) throw new Error("unknown channel"); if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), channelInput); - else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id")); + else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id"), values.session === undefined ? undefined : requiredSingleLine(values.session, "--session")); else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "finish-handover") { diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index e6495484..80c00ae3 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -17,6 +17,18 @@ class ChannelWakerTest(unittest.TestCase): + def test_unsupported_recipient_does_not_reserve_delivery(self): + with tempfile.TemporaryDirectory() as directory: + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state='fixture', channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + queued = {'phase': 'active', 'session': 'claude-cloud:fixture:session_Test', 'generation': 1, 'queue': [{'id': 'one', 'state': 'pending', 'payload': 'fixture'}]} + reserved = {**queued, 'queue': [{**queued['queue'][0], 'state': 'inflight', 'session': queued['session'], 'generation': 1}]} + def call(args, operation, *options): + return reserved if operation == 'begin-delivery' else queued + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', side_effect=call) as channel_call, patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + deliver.assert_not_called() + self.assertNotIn('begin-delivery', [call.args[1] for call in channel_call.call_args_list]) + def test_native_adapter_receives_message_on_stdin(self): from unittest.mock import Mock receipt = {'status': 'queued', 'agent': 'codex', 'sessionId': uuid, 'correlationId': 'message-1'} diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index 0dcc2a2c..54b9ab8c 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -82,7 +82,9 @@ test('delivery reservation and matching receipt survive graph replay', async (t) await call('migrate', '--apply', '--json'); await call('channel', 'create', '--name', 'example', '--session', session); await call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'payload'); - await call('channel', 'begin-delivery', '--name', 'example', '--id', 'one'); + await assert.rejects(call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', 'codex:other'), /recipient changed/); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'pending'); + await call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', session); await rm(join(state, 'checkpoint.json')); assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'inflight'); await assert.rejects(call('channel', 'acknowledge', '--name', 'example', '--id', 'one', '--input', JSON.stringify({ status: 'accepted', messageId: 'one', session: 'codex:wrong', generation: 1 })), /receipt/); diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index 9fc5bbd3..44d71910 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -234,10 +234,14 @@ def run_channel(args: argparse.Namespace) -> int: if not pending: print(json.dumps({'job': args.job, 'outcome': 'noop'})) return 0 - channel = channel_call(args, 'begin-delivery', '--id', pending['id']) + target = channel['session'] + agent, sep, session = target.partition(':') + if not sep or agent not in ('codex', 'claude'): + raise ValueError('unsupported channel recipient') + channel = channel_call(args, 'begin-delivery', '--id', pending['id'], '--session', target) item = next(item for item in channel['queue'] if item['id'] == pending['id']) agent, sep, session = item['session'].partition(':') - if not sep or agent not in ('codex', 'claude'): + if not sep or agent not in ('codex', 'claude') or item['session'] != target: raise ValueError('unsupported channel recipient') code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, True, resume=args.resume and agent == 'codex', message_stdin=True) diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 7d2216a8..7fdb621a 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -20,8 +20,9 @@ export function enqueue(state, id, payload) { return next; } -export function beginDelivery(state, id) { +export function beginDelivery(state, id, expectedSession) { if (state.phase !== 'active') throw new Error('handover in progress'); + if (expectedSession !== undefined && state.session !== expectedSession) throw new Error('channel recipient changed'); if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); if (state.queue.find((item) => item.state === 'pending')?.id !== id) throw new Error('message is not first pending'); const next = copy(state), item = next.queue.find((row) => row.id === id); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index e21b1d3b..d7f50b5e 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -159,7 +159,7 @@ try { } else { if (!current) throw new Error("unknown channel"); if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), channelInput); - else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id")); + else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id"), values.session === undefined ? undefined : requiredSingleLine(values.session, "--session")); else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "finish-handover") { From 36e3ac2b8a26b7d7a3abc0560efb2163bd216d62 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:33:08 +0000 Subject: [PATCH 037/113] Honor native default compaction item view --- packages/tmux-bridge/bin/codex-compaction-evidence.mjs | 3 ++- .../tmux-bridge/test/codex-compaction-evidence.test.mjs | 8 ++++++-- skills/agent-tmux/bin/codex-compaction-evidence.mjs | 3 ++- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/packages/tmux-bridge/bin/codex-compaction-evidence.mjs b/packages/tmux-bridge/bin/codex-compaction-evidence.mjs index 1d0ae997..b5018086 100644 --- a/packages/tmux-bridge/bin/codex-compaction-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-compaction-evidence.mjs @@ -17,7 +17,8 @@ const here = dirname(fileURLToPath(import.meta.url)); export function compactionFromThread(response, { thread, turn, item }) { if (typeof thread !== 'string' || !UUID.test(thread) || typeof turn !== 'string' || !TOKEN.test(turn) || typeof item !== 'string' || !TOKEN.test(item) || response?.thread?.id !== thread || !Array.isArray(response.thread.turns)) throw new Error('native thread identity unavailable'); const turns = response.thread.turns.filter(value => value?.id === turn); - if (turns.length !== 1 || turns[0].itemsView !== 'full' || !Array.isArray(turns[0].items)) throw new Error('native turn unavailable or incomplete'); + // The native Turn schema defaults an omitted itemsView to "full". + if (turns.length !== 1 || (turns[0].itemsView !== undefined && turns[0].itemsView !== 'full') || !Array.isArray(turns[0].items) || !['completed', 'interrupted', 'failed', 'inProgress'].includes(turns[0].status)) throw new Error('native turn unavailable or incomplete'); const items = turns[0].items.filter(value => value?.id === item); if (items.length !== 1 || items[0].type !== 'contextCompaction' || !Number.isSafeInteger(items[0].completedAtMs) || items[0].completedAtMs <= 0) throw new Error('completed compaction unavailable'); return { schema: 'agent-mesh.codex-compaction-evidence.v1', source: 'codex-app-server.thread-read', session: `codex:${thread}`, turn, item, completedAtMs: items[0].completedAtMs }; diff --git a/packages/tmux-bridge/test/codex-compaction-evidence.test.mjs b/packages/tmux-bridge/test/codex-compaction-evidence.test.mjs index 8788fd0e..a451227d 100644 --- a/packages/tmux-bridge/test/codex-compaction-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-compaction-evidence.test.mjs @@ -12,17 +12,21 @@ import { createAppServer } from './fixtures/fake-app-server.mjs'; const exec = promisify(execFile), thread = '22222222-2222-4222-8222-222222222222', turn = 'turn-fixture', item = 'item-fixture'; const bin = fileURLToPath(new URL('../bin/codex-compaction-evidence.mjs', import.meta.url)); const graph = fileURLToPath(new URL('../bin/mesh-graph.mjs', import.meta.url)); -const response = () => ({ thread: { id: thread, turns: [{ id: turn, itemsView: 'full', items: [{ id: item, type: 'contextCompaction', completedAtMs: 123456789 }] }] } }); +const response = () => ({ thread: { id: thread, turns: [{ id: turn, status: 'completed', itemsView: 'full', items: [{ id: item, type: 'contextCompaction', completedAtMs: 123456789 }] }] } }); test('only an exact completed native compaction in a full turn is accepted', () => { const identity = { thread, turn, item }; assert.equal(compactionFromThread(response(), identity).completedAtMs, 123456789); + const implicitFull = response(); delete implicitFull.thread.turns[0].itemsView; + assert.equal(compactionFromThread(implicitFull, identity).completedAtMs, 123456789); const missingTime = response(); missingTime.thread.turns[0].items[0].completedAtMs = null; const summary = response(); summary.thread.turns[0].itemsView = 'summary'; + const invalidView = response(); invalidView.thread.turns[0].itemsView = null; + const missingStatus = response(); delete missingStatus.thread.turns[0].status; const wrongType = response(); wrongType.thread.turns[0].items[0].type = 'agentMessage'; const duplicate = response(); duplicate.thread.turns.push(duplicate.thread.turns[0]); const duplicateItem = response(); duplicateItem.thread.turns[0].items.push(duplicateItem.thread.turns[0].items[0]); - for (const value of [missingTime, summary, wrongType, duplicate, duplicateItem, { thread: { id: 'other', turns: [] } }]) assert.throws(() => compactionFromThread(value, identity)); + for (const value of [missingTime, summary, invalidView, missingStatus, wrongType, duplicate, duplicateItem, { thread: { id: 'other', turns: [] } }]) assert.throws(() => compactionFromThread(value, identity)); }); test('native read records private evidence before an idempotent graph event', async t => { diff --git a/skills/agent-tmux/bin/codex-compaction-evidence.mjs b/skills/agent-tmux/bin/codex-compaction-evidence.mjs index 1d0ae997..b5018086 100644 --- a/skills/agent-tmux/bin/codex-compaction-evidence.mjs +++ b/skills/agent-tmux/bin/codex-compaction-evidence.mjs @@ -17,7 +17,8 @@ const here = dirname(fileURLToPath(import.meta.url)); export function compactionFromThread(response, { thread, turn, item }) { if (typeof thread !== 'string' || !UUID.test(thread) || typeof turn !== 'string' || !TOKEN.test(turn) || typeof item !== 'string' || !TOKEN.test(item) || response?.thread?.id !== thread || !Array.isArray(response.thread.turns)) throw new Error('native thread identity unavailable'); const turns = response.thread.turns.filter(value => value?.id === turn); - if (turns.length !== 1 || turns[0].itemsView !== 'full' || !Array.isArray(turns[0].items)) throw new Error('native turn unavailable or incomplete'); + // The native Turn schema defaults an omitted itemsView to "full". + if (turns.length !== 1 || (turns[0].itemsView !== undefined && turns[0].itemsView !== 'full') || !Array.isArray(turns[0].items) || !['completed', 'interrupted', 'failed', 'inProgress'].includes(turns[0].status)) throw new Error('native turn unavailable or incomplete'); const items = turns[0].items.filter(value => value?.id === item); if (items.length !== 1 || items[0].type !== 'contextCompaction' || !Number.isSafeInteger(items[0].completedAtMs) || items[0].completedAtMs <= 0) throw new Error('completed compaction unavailable'); return { schema: 'agent-mesh.codex-compaction-evidence.v1', source: 'codex-app-server.thread-read', session: `codex:${thread}`, turn, item, completedAtMs: items[0].completedAtMs }; From 1896ef1f4ea6002f6ddef9a53cf5cdddf8edd010 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:47:13 +0000 Subject: [PATCH 038/113] Guard channel reservation by generation --- packages/tmux-bridge/bin/agent-waker.py | 7 +++++-- packages/tmux-bridge/bin/channel-state.mjs | 3 ++- packages/tmux-bridge/bin/mesh-graph.mjs | 6 +++++- packages/tmux-bridge/test/agent-waker-channel.test.py | 4 +++- packages/tmux-bridge/test/plexus-channel-store.test.mjs | 5 ++++- skills/agent-tmux/bin/agent-waker.py | 7 +++++-- skills/agent-tmux/bin/channel-state.mjs | 3 ++- skills/agent-tmux/bin/mesh-graph.mjs | 6 +++++- 8 files changed, 31 insertions(+), 10 deletions(-) diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index 44d71910..96d968f7 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -235,13 +235,16 @@ def run_channel(args: argparse.Namespace) -> int: print(json.dumps({'job': args.job, 'outcome': 'noop'})) return 0 target = channel['session'] + generation = channel['generation'] + if isinstance(generation, bool) or not isinstance(generation, int) or generation < 1: + raise ValueError('invalid channel generation') agent, sep, session = target.partition(':') if not sep or agent not in ('codex', 'claude'): raise ValueError('unsupported channel recipient') - channel = channel_call(args, 'begin-delivery', '--id', pending['id'], '--session', target) + channel = channel_call(args, 'begin-delivery', '--id', pending['id'], '--session', target, '--generation', str(generation)) item = next(item for item in channel['queue'] if item['id'] == pending['id']) agent, sep, session = item['session'].partition(':') - if not sep or agent not in ('codex', 'claude') or item['session'] != target: + if not sep or agent not in ('codex', 'claude') or item['session'] != target or item['generation'] != generation: raise ValueError('unsupported channel recipient') code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, True, resume=args.resume and agent == 'codex', message_stdin=True) diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 7fdb621a..856efecc 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -20,9 +20,10 @@ export function enqueue(state, id, payload) { return next; } -export function beginDelivery(state, id, expectedSession) { +export function beginDelivery(state, id, expectedSession, expectedGeneration) { if (state.phase !== 'active') throw new Error('handover in progress'); if (expectedSession !== undefined && state.session !== expectedSession) throw new Error('channel recipient changed'); + if (expectedGeneration !== undefined && (!Number.isSafeInteger(expectedGeneration) || expectedGeneration < 1 || state.generation !== expectedGeneration)) throw new Error('channel generation changed'); if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); if (state.queue.find((item) => item.state === 'pending')?.id !== id) throw new Error('message is not first pending'); const next = copy(state), item = next.queue.find((row) => row.id === id); diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index d7f50b5e..b8c3f773 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -65,6 +65,7 @@ const { values, positionals } = parseArgs({ options: { state: { type: "string" }, session: { type: "string" }, + generation: { type: "string" }, project: { type: "string" }, archive: { type: "string" }, ttl: { type: "string" }, @@ -159,7 +160,10 @@ try { } else { if (!current) throw new Error("unknown channel"); if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), channelInput); - else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id"), values.session === undefined ? undefined : requiredSingleLine(values.session, "--session")); + else if (subcommand === "begin-delivery") { + if (values.generation !== undefined && !/^[1-9][0-9]*$/.test(values.generation)) throw new Error("invalid channel generation"); + next = beginDelivery(current, requiredSingleLine(values.id, "--id"), values.session === undefined ? undefined : requiredSingleLine(values.session, "--session"), values.generation === undefined ? undefined : Number(values.generation)); + } else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "finish-handover") { diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index 80c00ae3..a2576b86 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -122,9 +122,11 @@ def call(*args): call('migrate', '--apply', '--json') call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) - with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'deliver', return_value=0) as deliver, contextlib.redirect_stdout(io.StringIO()): + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'channel_call', wraps=waker.channel_call) as channel_call, patch.object(waker, 'deliver', return_value=0) as deliver, contextlib.redirect_stdout(io.StringIO()): self.assertEqual(waker.run(args), 0) self.assertEqual(deliver.call_args.args[0:2], ('codex', uuid)) + reservation = next(call.args for call in channel_call.call_args_list if call.args[1] == 'begin-delivery') + self.assertEqual(reservation[-2:], ('--generation', '1')) self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'accepted') with patch.object(waker, 'run_producer', return_value=([{'event': 'two'}], [])), patch.object(waker, 'deliver', return_value=78) as deliver, contextlib.redirect_stdout(io.StringIO()): self.assertEqual(waker.run(args), 3) diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index 54b9ab8c..d2a815f0 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -83,8 +83,11 @@ test('delivery reservation and matching receipt survive graph replay', async (t) await call('channel', 'create', '--name', 'example', '--session', session); await call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'payload'); await assert.rejects(call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', 'codex:other'), /recipient changed/); + await assert.rejects(call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', session, '--generation', '2'), /generation changed/); + await assert.rejects(call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--generation', '1.0'), /invalid channel generation/); + await assert.rejects(call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--generation', '9007199254740992'), /generation changed/); assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'pending'); - await call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', session); + await call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', session, '--generation', '1'); await rm(join(state, 'checkpoint.json')); assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'inflight'); await assert.rejects(call('channel', 'acknowledge', '--name', 'example', '--id', 'one', '--input', JSON.stringify({ status: 'accepted', messageId: 'one', session: 'codex:wrong', generation: 1 })), /receipt/); diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index 44d71910..96d968f7 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -235,13 +235,16 @@ def run_channel(args: argparse.Namespace) -> int: print(json.dumps({'job': args.job, 'outcome': 'noop'})) return 0 target = channel['session'] + generation = channel['generation'] + if isinstance(generation, bool) or not isinstance(generation, int) or generation < 1: + raise ValueError('invalid channel generation') agent, sep, session = target.partition(':') if not sep or agent not in ('codex', 'claude'): raise ValueError('unsupported channel recipient') - channel = channel_call(args, 'begin-delivery', '--id', pending['id'], '--session', target) + channel = channel_call(args, 'begin-delivery', '--id', pending['id'], '--session', target, '--generation', str(generation)) item = next(item for item in channel['queue'] if item['id'] == pending['id']) agent, sep, session = item['session'].partition(':') - if not sep or agent not in ('codex', 'claude') or item['session'] != target: + if not sep or agent not in ('codex', 'claude') or item['session'] != target or item['generation'] != generation: raise ValueError('unsupported channel recipient') code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, True, resume=args.resume and agent == 'codex', message_stdin=True) diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 7fdb621a..856efecc 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -20,9 +20,10 @@ export function enqueue(state, id, payload) { return next; } -export function beginDelivery(state, id, expectedSession) { +export function beginDelivery(state, id, expectedSession, expectedGeneration) { if (state.phase !== 'active') throw new Error('handover in progress'); if (expectedSession !== undefined && state.session !== expectedSession) throw new Error('channel recipient changed'); + if (expectedGeneration !== undefined && (!Number.isSafeInteger(expectedGeneration) || expectedGeneration < 1 || state.generation !== expectedGeneration)) throw new Error('channel generation changed'); if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); if (state.queue.find((item) => item.state === 'pending')?.id !== id) throw new Error('message is not first pending'); const next = copy(state), item = next.queue.find((row) => row.id === id); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index d7f50b5e..b8c3f773 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -65,6 +65,7 @@ const { values, positionals } = parseArgs({ options: { state: { type: "string" }, session: { type: "string" }, + generation: { type: "string" }, project: { type: "string" }, archive: { type: "string" }, ttl: { type: "string" }, @@ -159,7 +160,10 @@ try { } else { if (!current) throw new Error("unknown channel"); if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), channelInput); - else if (subcommand === "begin-delivery") next = beginDelivery(current, requiredSingleLine(values.id, "--id"), values.session === undefined ? undefined : requiredSingleLine(values.session, "--session")); + else if (subcommand === "begin-delivery") { + if (values.generation !== undefined && !/^[1-9][0-9]*$/.test(values.generation)) throw new Error("invalid channel generation"); + next = beginDelivery(current, requiredSingleLine(values.id, "--id"), values.session === undefined ? undefined : requiredSingleLine(values.session, "--session"), values.generation === undefined ? undefined : Number(values.generation)); + } else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "finish-handover") { From f62d195cbf0735bff52ac689903094d79695edb3 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:57:46 +0000 Subject: [PATCH 039/113] Reserve channel state preparation before transport --- docs/design/plexus-architecture.mmd | 4 ++- docs/design/plexus-channels.md | 6 ++++ packages/tmux-bridge/bin/channel-state.mjs | 19 +++++++++++ .../tmux-bridge/bin/handover-state-proof.mjs | 14 ++++++-- packages/tmux-bridge/bin/mesh-graph.mjs | 34 +++++++++++++++++-- .../tmux-bridge/test/channel-state.test.mjs | 18 +++++++++- .../test/handover-state-proof.test.mjs | 21 +++++++++++- scripts/plexus-diagram.mjs | 4 ++- skills/agent-tmux/bin/channel-state.mjs | 19 +++++++++++ .../agent-tmux/bin/handover-state-proof.mjs | 14 ++++++-- skills/agent-tmux/bin/mesh-graph.mjs | 34 +++++++++++++++++-- 11 files changed, 173 insertions(+), 14 deletions(-) diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 2ec28154..80d30f88 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -10,7 +10,9 @@ flowchart LR Contract --> Journal Queue -- "bound receipt" --> Session Yaml["Bounded YAML decoder"] --> Restart - Restart["Restart state contract"] -. "planned validation" .-> Handover + Restart["Restart state contract"] --> StatePrep["Reserved state preparation"] + StatePrep --> Journal + StatePrep -. "planned proof revalidation" .-> Handover Notice["Successor notice formatter"] -. "planned publication" .-> Handover Observation["Codex notice snapshot"] -. "planned finality check" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 7665c14e..ae182d6a 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -31,6 +31,12 @@ the private file without following a final symlink. `requestStateProof` obtains the response through the existing native correlated-result transport; Codex resume remains disabled. The verifier decodes and validates the restart block, but does not reconcile its triggers or make a graph cutover. +`channel prepare-state` durably reserves a single correlated request before +contacting the current session, then records the validated state digest only if +the same handover, session and generation remain current. Messages may still be +queued while the request runs. A failure or lost response leaves the request +unresolved and prevents an automatic resend; recovery is not yet implemented. +The proof does not authorize cutover, archive, or final-message publication. The prepared Codex path additionally requires a fresh unarchived native-thread observation and exactly one detected writer. Claude and cloud successors are not yet supported by this operation. diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 856efecc..3f93ae6a 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -45,11 +45,30 @@ export function beginHandover(state) { if (state.phase !== 'active') throw new Error('handover already in progress'); const next = copy(state); next.phase = 'handover'; + delete next.statePreparation; + return next; +} + +// A reserved request is intentionally not retried automatically after a crash. +export function reserveStatePreparation(state, id) { + if (state.phase !== 'handover' || state.statePreparation || !identifier(id)) throw new Error('state preparation unavailable or unresolved'); + if (state.queue.some(item => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + const next = copy(state); + next.statePreparation = { id, session: state.session, generation: state.generation, status: 'requested' }; + return next; +} + +export function completeStatePreparation(state, proof) { + const pending = state.statePreparation; + if (state.phase !== 'handover' || !pending || pending.status !== 'requested' || pending.session !== state.session || pending.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.handover-state.v1' || proof.nonce !== pending.id || proof.session !== pending.session || !/^[0-9a-f]{64}$/.test(proof.sha256) || typeof proof.filename !== 'string' || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('state preparation changed or proof invalid'); + const next = copy(state); + next.statePreparation = { ...pending, status: 'verified', filename: proof.filename, sha256: proof.sha256, bytes: proof.bytes }; return next; } export function finishHandover(state, session, verified) { if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); + if (state.statePreparation && state.statePreparation.status !== 'verified') throw new Error('state preparation unresolved'); if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); const next = copy(state); next.session = session; diff --git a/packages/tmux-bridge/bin/handover-state-proof.mjs b/packages/tmux-bridge/bin/handover-state-proof.mjs index 12fdf581..0c4b17b1 100644 --- a/packages/tmux-bridge/bin/handover-state-proof.mjs +++ b/packages/tmux-bridge/bin/handover-state-proof.mjs @@ -19,14 +19,24 @@ const exec = (command, args, { input, ...options }) => new Promise((resolve, rej child.stdin.end(input); }); +// reserve and complete are atomic host mutations; a failed request deliberately +// leaves the reservation unresolved so a caller cannot silently resend it. +export async function prepareState({ reserve, request, complete }) { + const reservation = reserve(); + const pending = reservation?.statePreparation; + if (!pending || pending.status !== 'requested' || typeof pending.session !== 'string' || typeof pending.id !== 'string') throw new Error('state preparation reservation unavailable'); + const proof = await request(pending); + return complete(proof); +} + /** Obtain a correlated native-session result, then bind it to file bytes. */ -export async function requestStateProof({ session, channel, root, filename, managedInboxRoot }, runNative = exec) { +export async function requestStateProof({ session, channel, root, filename, managedInboxRoot, nonce = `handover-${randomUUID()}` }, runNative = exec) { if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !isAbsolute(root) || /[\r\n\x00]/.test(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); const rootInfo = await lstat(root); if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); const [agent, nativeId] = session.split(':'); if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); - const nonce = `handover-${randomUUID()}`; + if (typeof nonce !== 'string' || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce)) throw new Error('invalid request nonce'); if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); const message = `Write your handover state with a RIAVVIO YAML block using agent-mesh.restart.v1 to ${join(root, filename)} with private permissions. Bind the block to session ${session} and channel ${channel}, and include harness, working_directory, skills, triggers and goal. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message-stdin']; diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index b8c3f773..c7585cba 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -26,7 +26,7 @@ import { writeSync, } from "node:fs"; import { homedir } from "node:os"; -import { dirname, join, resolve } from "node:path"; +import { dirname, isAbsolute, join, resolve } from "node:path"; import { randomUUID, createHash } from "node:crypto"; import { spawn, spawnSync } from "node:child_process"; import { fileURLToPath } from "node:url"; @@ -37,7 +37,8 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; +import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -66,6 +67,9 @@ const { values, positionals } = parseArgs({ state: { type: "string" }, session: { type: "string" }, generation: { type: "string" }, + "state-root": { type: "string" }, + filename: { type: "string" }, + "managed-inbox-root": { type: "string" }, project: { type: "string" }, archive: { type: "string" }, ttl: { type: "string" }, @@ -125,7 +129,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -147,6 +151,30 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "prepare-state") { + const root = requiredSingleLine(values["state-root"], "--state-root"), filename = requiredSingleLine(values.filename, "--filename"); + if (!isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error("invalid state preparation path"); + const info = lstatSync(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || realpathSync(root) !== root) throw new Error("state root must be private and canonical"); + const nonce = `handover-${randomUUID()}`; + const result = await prepareState({ reserve: () => mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(current.session) || (current.session.startsWith("claude:") && (!values["managed-inbox-root"] || !isAbsolute(values["managed-inbox-root"])))) throw new Error("unsupported state preparation recipient"); + const next = reserveStatePreparation(current, nonce); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, statePreparation: next.statePreparation } }; + }), request: pending => requestStateProof({ session: pending.session, channel: name, root, filename, managedInboxRoot: values["managed-inbox-root"], nonce: pending.id }), complete: proof => mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + const next = completeStatePreparation(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, statePreparation: next.statePreparation } }; + }) }); + printResult(result, { json: true }); + break; + } const result = mutate(stateDir, graph => { assertPrivateChannelState(stateDir); if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); diff --git a/packages/tmux-bridge/test/channel-state.test.mjs b/packages/tmux-bridge/test/channel-state.test.mjs index c2b4b070..e7479e13 100644 --- a/packages/tmux-bridge/test/channel-state.test.mjs +++ b/packages/tmux-bridge/test/channel-state.test.mjs @@ -1,6 +1,22 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, finishHandover } from '../bin/channel-state.mjs'; +import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, finishHandover, reserveStatePreparation, completeStatePreparation } from '../bin/channel-state.mjs'; + +test('state preparation reserves once and binds proof to the channel generation', () => { + let channel = beginHandover(createChannel('example', 'codex:old')); + channel = reserveStatePreparation(channel, 'handover-1'); + assert.throws(() => reserveStatePreparation(channel, 'handover-2'), /unresolved/); + assert.throws(() => finishHandover(channel, 'codex:new', true), /unresolved/); + channel = enqueue(channel, 'queued', 'fixture'); + const proof = { schema: 'agent-mesh.handover-state.v1', session: 'codex:old', nonce: 'handover-1', filename: 'state.yaml', sha256: 'a'.repeat(64), bytes: 42 }; + assert.throws(() => completeStatePreparation(channel, { ...proof, nonce: 'other' }), /invalid/); + assert.throws(() => completeStatePreparation({ ...channel, generation: 2 }, proof), /changed/); + assert.throws(() => completeStatePreparation({ ...channel, session: 'codex:other' }, proof), /changed/); + channel = completeStatePreparation(channel, proof); + assert.equal(channel.statePreparation.status, 'verified'); + assert.equal(channel.queue[0].state, 'pending'); + assert.throws(() => completeStatePreparation(channel, proof), /invalid/); +}); test('handover queues work and never reroutes an uncertain delivery', () => { assert.equal(createChannel('#example', 'session:one').id, '#example'); diff --git a/packages/tmux-bridge/test/handover-state-proof.test.mjs b/packages/tmux-bridge/test/handover-state-proof.test.mjs index de077d49..7df3c063 100644 --- a/packages/tmux-bridge/test/handover-state-proof.test.mjs +++ b/packages/tmux-bridge/test/handover-state-proof.test.mjs @@ -4,7 +4,24 @@ import { chmod, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import test from 'node:test'; -import { requestStateProof, verifyStateResponse } from '../bin/handover-state-proof.mjs'; +import { prepareState, requestStateProof, verifyStateResponse } from '../bin/handover-state-proof.mjs'; +import { beginHandover, completeStatePreparation, createChannel, enqueue, reserveStatePreparation } from '../bin/channel-state.mjs'; + +test('preparation reserves before transport, retains a lost response, and binds concurrent queue changes', async () => { + let channel = beginHandover(createChannel('example', 'codex:old')); + const proof = { schema: 'agent-mesh.handover-state.v1', session: 'codex:old', nonce: 'handover-1', filename: 'state.yaml', sha256: 'a'.repeat(64), bytes: 42 }; + let sends = 0; + const reserve = () => { channel = reserveStatePreparation(channel, 'handover-1'); return { statePreparation: channel.statePreparation }; }; + const complete = value => { channel = completeStatePreparation(channel, value); return channel; }; + await assert.rejects(prepareState({ reserve, request: async () => { sends++; throw new Error('lost response'); }, complete }), /lost response/); + assert.equal(channel.statePreparation.status, 'requested'); + await assert.rejects(prepareState({ reserve, request: async () => { sends++; return proof; }, complete }), /unresolved/); + assert.equal(sends, 1); + channel = beginHandover(createChannel('example', 'codex:old')); + const result = await prepareState({ reserve, request: async pending => { assert.equal(pending.id, proof.nonce); channel = enqueue(channel, 'one', 'fixture'); return proof; }, complete }); + assert.equal(result.statePreparation.status, 'verified'); + assert.equal(result.queue[0].state, 'pending'); +}); test('state proof binds correlated response to private file bytes', async (t) => { const root = await mkdtemp(join(tmpdir(), 'state-proof-')); @@ -47,6 +64,8 @@ test('native request binds response to its own correlation without resuming', as const proof = await requestStateProof({ session, channel: '#example', root, filename }, fake); assert.equal(proof.session, session); assert.ok(proof.nonce.startsWith('handover-')); + assert.equal((await requestStateProof({ session, channel: '#example', root, filename, nonce: 'handover-fixed' }, fake)).nonce, 'handover-fixed'); + await assert.rejects(requestStateProof({ session, channel: '#example', root, filename, nonce: 'unsafe nonce' }, fake), /nonce/); await assert.rejects(requestStateProof({ session, channel: '#example', root, filename }, async () => ({ stdout: JSON.stringify({ status: 'held' }) })), /binding/); await assert.rejects(requestStateProof({ session, channel: '#example', root, filename }, async () => { throw new Error('timeout'); }), /timeout/); }); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 9e46fee6..7b8ffb39 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -11,7 +11,9 @@ export const plexusDiagram = `flowchart LR Contract --> Journal Queue -- "bound receipt" --> Session Yaml["Bounded YAML decoder"] --> Restart - Restart["Restart state contract"] -. "planned validation" .-> Handover + Restart["Restart state contract"] --> StatePrep["Reserved state preparation"] + StatePrep --> Journal + StatePrep -. "planned proof revalidation" .-> Handover Notice["Successor notice formatter"] -. "planned publication" .-> Handover Observation["Codex notice snapshot"] -. "planned finality check" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 856efecc..3f93ae6a 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -45,11 +45,30 @@ export function beginHandover(state) { if (state.phase !== 'active') throw new Error('handover already in progress'); const next = copy(state); next.phase = 'handover'; + delete next.statePreparation; + return next; +} + +// A reserved request is intentionally not retried automatically after a crash. +export function reserveStatePreparation(state, id) { + if (state.phase !== 'handover' || state.statePreparation || !identifier(id)) throw new Error('state preparation unavailable or unresolved'); + if (state.queue.some(item => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + const next = copy(state); + next.statePreparation = { id, session: state.session, generation: state.generation, status: 'requested' }; + return next; +} + +export function completeStatePreparation(state, proof) { + const pending = state.statePreparation; + if (state.phase !== 'handover' || !pending || pending.status !== 'requested' || pending.session !== state.session || pending.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.handover-state.v1' || proof.nonce !== pending.id || proof.session !== pending.session || !/^[0-9a-f]{64}$/.test(proof.sha256) || typeof proof.filename !== 'string' || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('state preparation changed or proof invalid'); + const next = copy(state); + next.statePreparation = { ...pending, status: 'verified', filename: proof.filename, sha256: proof.sha256, bytes: proof.bytes }; return next; } export function finishHandover(state, session, verified) { if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); + if (state.statePreparation && state.statePreparation.status !== 'verified') throw new Error('state preparation unresolved'); if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); const next = copy(state); next.session = session; diff --git a/skills/agent-tmux/bin/handover-state-proof.mjs b/skills/agent-tmux/bin/handover-state-proof.mjs index 12fdf581..0c4b17b1 100644 --- a/skills/agent-tmux/bin/handover-state-proof.mjs +++ b/skills/agent-tmux/bin/handover-state-proof.mjs @@ -19,14 +19,24 @@ const exec = (command, args, { input, ...options }) => new Promise((resolve, rej child.stdin.end(input); }); +// reserve and complete are atomic host mutations; a failed request deliberately +// leaves the reservation unresolved so a caller cannot silently resend it. +export async function prepareState({ reserve, request, complete }) { + const reservation = reserve(); + const pending = reservation?.statePreparation; + if (!pending || pending.status !== 'requested' || typeof pending.session !== 'string' || typeof pending.id !== 'string') throw new Error('state preparation reservation unavailable'); + const proof = await request(pending); + return complete(proof); +} + /** Obtain a correlated native-session result, then bind it to file bytes. */ -export async function requestStateProof({ session, channel, root, filename, managedInboxRoot }, runNative = exec) { +export async function requestStateProof({ session, channel, root, filename, managedInboxRoot, nonce = `handover-${randomUUID()}` }, runNative = exec) { if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !isAbsolute(root) || /[\r\n\x00]/.test(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); const rootInfo = await lstat(root); if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); const [agent, nativeId] = session.split(':'); if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); - const nonce = `handover-${randomUUID()}`; + if (typeof nonce !== 'string' || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce)) throw new Error('invalid request nonce'); if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); const message = `Write your handover state with a RIAVVIO YAML block using agent-mesh.restart.v1 to ${join(root, filename)} with private permissions. Bind the block to session ${session} and channel ${channel}, and include harness, working_directory, skills, triggers and goal. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message-stdin']; diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index b8c3f773..c7585cba 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -26,7 +26,7 @@ import { writeSync, } from "node:fs"; import { homedir } from "node:os"; -import { dirname, join, resolve } from "node:path"; +import { dirname, isAbsolute, join, resolve } from "node:path"; import { randomUUID, createHash } from "node:crypto"; import { spawn, spawnSync } from "node:child_process"; import { fileURLToPath } from "node:url"; @@ -37,7 +37,8 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; +import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -66,6 +67,9 @@ const { values, positionals } = parseArgs({ state: { type: "string" }, session: { type: "string" }, generation: { type: "string" }, + "state-root": { type: "string" }, + filename: { type: "string" }, + "managed-inbox-root": { type: "string" }, project: { type: "string" }, archive: { type: "string" }, ttl: { type: "string" }, @@ -125,7 +129,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -147,6 +151,30 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "prepare-state") { + const root = requiredSingleLine(values["state-root"], "--state-root"), filename = requiredSingleLine(values.filename, "--filename"); + if (!isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error("invalid state preparation path"); + const info = lstatSync(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || realpathSync(root) !== root) throw new Error("state root must be private and canonical"); + const nonce = `handover-${randomUUID()}`; + const result = await prepareState({ reserve: () => mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(current.session) || (current.session.startsWith("claude:") && (!values["managed-inbox-root"] || !isAbsolute(values["managed-inbox-root"])))) throw new Error("unsupported state preparation recipient"); + const next = reserveStatePreparation(current, nonce); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, statePreparation: next.statePreparation } }; + }), request: pending => requestStateProof({ session: pending.session, channel: name, root, filename, managedInboxRoot: values["managed-inbox-root"], nonce: pending.id }), complete: proof => mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + const next = completeStatePreparation(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, statePreparation: next.statePreparation } }; + }) }); + printResult(result, { json: true }); + break; + } const result = mutate(stateDir, graph => { assertPrivateChannelState(stateDir); if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); From a6a87c2401fd26efc9481dcebaf9b0d21e095595 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:03:08 +0000 Subject: [PATCH 040/113] Allow lease renewal observation under load --- packages/tmux-bridge/test/capacity-dispatch.test.mjs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/tmux-bridge/test/capacity-dispatch.test.mjs b/packages/tmux-bridge/test/capacity-dispatch.test.mjs index da362414..780670df 100644 --- a/packages/tmux-bridge/test/capacity-dispatch.test.mjs +++ b/packages/tmux-bridge/test/capacity-dispatch.test.mjs @@ -303,7 +303,7 @@ test("agent-spawn uses a routed native rendering and closes its lease after the await mkdir(bin); await mkdir(agents); await writeFile(limen, `#!/bin/sh\nif [ "$1" = route ]; then echo '{"decision":"route","provider":"codex","model":"governed-model","nativeModel":"native-model","effort":"high","decisionId":"route-1","configHash":"cfg","lease":{"expiresAt":999,"candidate":{"key":"0123456789abcdef0123456789abcdef","model":"governed-model","effort":"high","capacityCostBase":null}}}'; exit 0; fi\nif [ "$1" = renew ]; then echo '{"status":"renewed","expiresAt":999}'; exit 0; fi\nif [ "$1" = complete ]; then echo '{"status":"completed","candidate":{"key":"0123456789abcdef0123456789abcdef","model":"governed-model","effort":"high","capacityCostBase":null}}'; exit 0; fi\nexit 2\n`); await writeFile(join(agents, "codex.conf"), `AGENT_BIN="fake-codex"\nAGENT_ALIVE_PROCESS_PATTERN="^(fake-codex|sleep)$"\nAGENT_SUBMIT_KEY="Enter"\nAGENT_PROMPT_CHAR="FAKE>"\nAGENT_WORKING_PATTERN="WORKING"\nAGENT_IDLE_PATTERN="FAKE>"\nAGENT_RESUME_CMD="fake-codex"\nAGENT_HAS_CWD_PICKER="false"\nAGENT_PICKER_PATTERN=""\nAGENT_NEW_CMD="fake-codex"\nAGENT_SESSION_DIR="${dir}"\nAGENT_SESSION_CWD_EXTRACTOR='printf "?\\n"'\nAGENT_SUPPORTS_MODEL="true"\nAGENT_MODEL_ARGS=(--model "{VALUE}")\nAGENT_MODEL_PASSTHRU_PATTERNS=()\nAGENT_SUPPORTS_EFFORT="true"\nAGENT_EFFORT_ARGS=(--effort "{VALUE}")\nAGENT_EFFORT_PASSTHRU_PATTERNS=()\n`); - await writeFile(codex, `#!/bin/sh\nprintf '%s\\n' "$*" > '${launchArgs}'\nprintf 'FAKE>\\n'\nsleep 2\n`); + await writeFile(codex, `#!/bin/sh\nprintf '%s\\n' "$*" > '${launchArgs}'\nprintf 'FAKE>\\n'\nsleep 10\n`); await chmod(limen, 0o700); await chmod(codex, 0o700); const env = { ...process.env, PATH: `${bin}:${process.env.PATH}`, LIMEN_BIN: limen, MESH_CAPACITY_STATE: state, MESH_TMUX_SOCKET: socket, MESH_LEASE_RENEW_MS: "10", AGENT_MESH_AGENTS_DIR: agents }; try { @@ -315,10 +315,10 @@ test("agent-spawn uses a routed native rendering and closes its lease after the assert.match(await readFile(launchArgs, "utf8"), /--effort high/); const opened = JSON.parse(await readFile(state, "utf8")); assert.deepEqual(opened.sessions[0].candidate, { key: "0123456789abcdef0123456789abcdef", model: "governed-model", effort: "high", capacityCostBase: null }); - await waitFor(async () => (await readFile(`${state}.events.ndjson`, "utf8")).includes("lease_renewed")); - // The fixture sleeps for two seconds; allow the observer to be scheduled + await waitFor(async () => (await readFile(`${state}.events.ndjson`, "utf8")).includes("lease_renewed"), 8_000); + // The fixture sleeps for ten seconds; allow the observer to be scheduled // on a loaded runner while still requiring the lease to complete. - await waitFor(async () => JSON.parse(await readFile(state, "utf8")).sessions[0]?.status === "completed", 15_000); + await waitFor(async () => JSON.parse(await readFile(state, "utf8")).sessions[0]?.status === "completed", 20_000); assert.equal((await runCommand("tmux", ["-L", socket, "has-session", "-t", target], env)).code, 0, "the tmux shell remains after the agent process exits"); const events = await readFile(`${state}.events.ndjson`, "utf8"); assert.match(events, /session_active/); From 3208994c43afced49ec8f422bf4d1e8c750ee6d3 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:14:23 +0000 Subject: [PATCH 041/113] Test interrupted handover preparation replay --- .../test/plexus-channel-store.test.mjs | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index d2a815f0..47fee4ef 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { execFile } from 'node:child_process'; -import { appendFile, chmod, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { appendFile, chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -9,6 +9,32 @@ import test from 'node:test'; const exec = promisify(execFile); const bin = fileURLToPath(new URL('../bin/mesh-graph.mjs', import.meta.url)); +test('failed native state request stays reserved across replay and is never resent', async (t) => { + const root = await mkdtemp(join(tmpdir(), 'channel-prepare-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = join(root, 'graph'), files = join(root, 'files'), sessions = join(root, 'sessions'); + await mkdir(files, { mode: 0o700 }); await mkdir(sessions, { mode: 0o700 }); + const env = { ...process.env, XDG_STATE_HOME: join(root, 'xdg'), XDG_CONFIG_HOME: join(root, 'config'), CODEX_SESSION_ROOT: sessions, MESH_COMMS_STATE: join(root, 'comms'), MESH_GRAPH_STATE: state, AGENT_FALLBACK_STATE: join(root, 'fallback') }; + delete env.MESH_COMMS_REPLAY_FD; + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args], { env, timeout: 30000 })).stdout); + const uuid = '22222222-2222-4222-8222-222222222222'; + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${uuid}`); + await call('channel', 'begin-handover', '--name', 'example'); + await call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'fixture'); + const args = ['channel', 'prepare-state', '--name', 'example', '--state-root', files, '--filename', 'state.yaml']; + await assert.rejects(call(...args)); + await rm(join(state, 'checkpoint.json'), { force: true }); + const first = (await call('channel', 'get', '--name', 'example')).channel; + assert.equal(first.statePreparation.status, 'requested'); + assert.equal(first.queue[0].state, 'pending'); + await assert.rejects(call(...args), /unresolved/); + const second = (await call('channel', 'get', '--name', 'example')).channel; + assert.deepEqual(second.statePreparation, first.statePreparation); + assert.equal(second.queue[0].state, 'pending'); +}); + test('channel operations reject a graph with non-private persisted files', async (t) => { const state = await mkdtemp(join(tmpdir(), 'channel-permissions-')); t.after(() => rm(state, { recursive: true, force: true })); From 85d7be61dedb801b38df783d7e53e0a42755e716 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:27:18 +0000 Subject: [PATCH 042/113] Add guarded trigger reconciliation engine --- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-channels.md | 10 ++++ .../tmux-bridge/bin/trigger-transaction.mjs | 53 ++++++++++++++++++ .../test/trigger-transaction.test.mjs | 54 +++++++++++++++++++ scripts/plexus-diagram.mjs | 1 + skills/agent-tmux/bin/trigger-transaction.mjs | 53 ++++++++++++++++++ 6 files changed, 172 insertions(+) create mode 100644 packages/tmux-bridge/bin/trigger-transaction.mjs create mode 100644 packages/tmux-bridge/test/trigger-transaction.test.mjs create mode 100644 skills/agent-tmux/bin/trigger-transaction.mjs diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 80d30f88..9a2a254a 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -13,6 +13,7 @@ flowchart LR Restart["Restart state contract"] --> StatePrep["Reserved state preparation"] StatePrep --> Journal StatePrep -. "planned proof revalidation" .-> Handover + TriggerTxn["Trigger transaction engine"] -. "planned adapters and journal" .-> Handover Notice["Successor notice formatter"] -. "planned publication" .-> Handover Observation["Codex notice snapshot"] -. "planned finality check" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index ae182d6a..6494f7cb 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -37,6 +37,16 @@ the same handover, session and generation remain current. Messages may still be queued while the request runs. A failure or lost response leaves the request unresolved and prevents an automatic resend; recovery is not yet implemented. The proof does not authorize cutover, archive, or final-message publication. + +`trigger-transaction.mjs` supplies a generic transaction engine, not a live +scheduler adapter. Its injected journal must atomically reserve overlapping +trigger sets and durably record intent before each move. Its adapter must +compare the original target and version atomically and expose the operation ID +on readback. Definite refusal rolls back earlier verified moves using the same +compare-and-set contract; an ambiguous result stays unresolved and is not +retried. Dry-run reads and journals a plan without moving triggers. Concrete +timer and cloud adapters, durable journal implementation and recovery are not +yet provided; this engine is not authorization to change live triggers. The prepared Codex path additionally requires a fresh unarchived native-thread observation and exactly one detected writer. Claude and cloud successors are not yet supported by this operation. diff --git a/packages/tmux-bridge/bin/trigger-transaction.mjs b/packages/tmux-bridge/bin/trigger-transaction.mjs new file mode 100644 index 00000000..2b4df347 --- /dev/null +++ b/packages/tmux-bridge/bin/trigger-transaction.mjs @@ -0,0 +1,53 @@ +/** Reconcile session-bound triggers through an operator-provided CAS adapter. */ +const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); + +// begin must atomically reserve this ID and trigger set, rejecting unresolved +// overlapping transactions. Each write must be durable before it resolves. +// The adapter atomically compares target AND version and stores operationId. +export async function reconcileTriggers({ triggers, from, to, transactionId, adapter, journal, dryRun = true }) { + if (!Array.isArray(triggers) || triggers.length > 256 || !token(from) || !token(to) || from === to || !token(transactionId) || transactionId.length > 90 || typeof dryRun !== 'boolean' || typeof adapter?.read !== 'function' || typeof adapter?.move !== 'function' || typeof journal?.begin !== 'function' || typeof journal?.write !== 'function') throw new Error('invalid trigger transaction'); + const seen = new Set(); + for (const trigger of triggers) { + if (!token(trigger?.kind) || !token(trigger?.id) || seen.has(`${trigger.kind}\0${trigger.id}`)) throw new Error('invalid or duplicate trigger'); + seen.add(`${trigger.kind}\0${trigger.id}`); + } + const receipt = { schema: 'agent-mesh.trigger-transaction.v1', id: transactionId, from, to, dryRun, status: 'planning', triggers: [] }; + await journal.begin({ id: transactionId, triggers: structuredClone(triggers), dryRun }); + const save = () => journal.write(structuredClone(receipt)); + for (const trigger of triggers) { + const current = await adapter.read(trigger); + if (!current || current.target !== from || !token(current.version)) throw new Error('trigger source or version not verified'); + receipt.triggers.push({ kind: trigger.kind, id: trigger.id, before: current.version, status: 'planned' }); + } + receipt.status = dryRun ? 'dry-run' : 'applying'; + await save(); + if (dryRun) return receipt; + for (let i = 0; i < receipt.triggers.length; i++) { + const row = receipt.triggers[i], operationId = `${transactionId}:${i}`; + row.status = 'applying'; row.operationId = operationId; await save(); + let response; + try { response = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: from, expectedVersion: row.before, target: to, operationId }); } + catch { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + if (response?.status !== 'applied' || !token(response.version)) { + row.status = response?.status === 'not-applied' ? 'not-applied' : 'uncertain'; + receipt.status = row.status === 'uncertain' ? 'uncertain' : 'rolling-back'; await save(); + if (row.status === 'uncertain') return receipt; + for (let j = i - 1; j >= 0; j--) { + const prior = receipt.triggers[j], rollbackId = `${transactionId}:rollback:${j}`; + prior.status = 'rolling-back'; await save(); + let rollback; + try { rollback = await adapter.move({ kind: prior.kind, id: prior.id, expectedTarget: to, expectedVersion: prior.after, target: from, operationId: rollbackId }); } + catch { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + if (rollback?.status !== 'applied' || !token(rollback.version)) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + const observed = await adapter.read(prior); + if (observed?.target !== from || observed.version !== rollback.version || observed.lastOperationId !== rollbackId) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + prior.status = 'rolled-back'; prior.rollbackVersion = rollback.version; await save(); + } + receipt.status = 'rolled-back'; await save(); return receipt; + } + const observed = await adapter.read(row); + if (observed?.target !== to || observed.version !== response.version || observed.lastOperationId !== operationId) { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + row.after = response.version; row.status = 'verified'; await save(); + } + receipt.status = 'verified'; await save(); return receipt; +} diff --git a/packages/tmux-bridge/test/trigger-transaction.test.mjs b/packages/tmux-bridge/test/trigger-transaction.test.mjs new file mode 100644 index 00000000..92de450d --- /dev/null +++ b/packages/tmux-bridge/test/trigger-transaction.test.mjs @@ -0,0 +1,54 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { reconcileTriggers } from '../bin/trigger-transaction.mjs'; + +function fixture() { + const state = new Map(['one', 'two'].map(id => [id, { target: 'codex:old', version: 'v1' }])); + const records = []; let counter = 1, calls = 0, refuse = false, lose = false; + const adapter = { + read: async ({ id }) => structuredClone(state.get(id)), + move: async ({ id, expectedTarget, expectedVersion, target, operationId }) => { + calls++; + if (refuse && id === 'two') return { status: 'not-applied' }; + const old = state.get(id); + if (old.target !== expectedTarget || old.version !== expectedVersion) return { status: 'not-applied' }; + const next = { target, version: `v${++counter}`, lastOperationId: operationId }; + state.set(id, next); + if (lose && id === 'two') throw new Error('lost response'); + return { status: 'applied', version: next.version }; + } + }; + let reserved = false; + const journal = { begin: async () => { if (reserved) throw new Error('transaction already reserved'); reserved = true; }, write: async receipt => records.push(structuredClone(receipt)) }; + const run = (dryRun = false) => reconcileTriggers({ triggers: ['one', 'two'].map(id => ({ kind: 'timer', id })), from: 'codex:old', to: 'codex:new', transactionId: 'fixture', adapter, journal, dryRun }); + return { state, records, run, calls: () => calls, refuse: () => { refuse = true; }, lose: () => { lose = true; } }; +} + +test('dry run reads sources and records plan without moving triggers', async () => { + const f = fixture(), receipt = await f.run(true); + assert.equal(receipt.status, 'dry-run'); assert.equal(f.calls(), 0); + assert.equal(f.state.get('one').target, 'codex:old'); +}); + +test('each move is recorded before invocation and verified by operation identity', async () => { + const f = fixture(), receipt = await f.run(); + assert.equal(receipt.status, 'verified'); + assert.deepEqual(receipt.triggers.map(row => row.status), ['verified', 'verified']); + assert.ok(f.records.some(item => item.triggers[0].status === 'applying')); + assert.equal(f.state.get('two').target, 'codex:new'); +}); + +test('a definite refusal rolls back earlier verified moves', async () => { + const f = fixture(); f.refuse(); const receipt = await f.run(); + assert.equal(receipt.status, 'rolled-back'); + assert.equal(receipt.triggers[0].status, 'rolled-back'); + assert.equal(f.state.get('one').target, 'codex:old'); +}); + +test('a lost response is uncertain and is never retried or falsely rolled back', async () => { + const f = fixture(); f.lose(); const receipt = await f.run(); + assert.equal(receipt.status, 'uncertain'); assert.equal(f.calls(), 2); + await assert.rejects(f.run(), /already reserved/); + assert.equal(receipt.triggers[1].status, 'uncertain'); + assert.equal(f.state.get('one').target, 'codex:new'); +}); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 7b8ffb39..83cd585f 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -14,6 +14,7 @@ export const plexusDiagram = `flowchart LR Restart["Restart state contract"] --> StatePrep["Reserved state preparation"] StatePrep --> Journal StatePrep -. "planned proof revalidation" .-> Handover + TriggerTxn["Trigger transaction engine"] -. "planned adapters and journal" .-> Handover Notice["Successor notice formatter"] -. "planned publication" .-> Handover Observation["Codex notice snapshot"] -. "planned finality check" .-> Handover Handover["Handover"] -. "planned verified cutover" .-> Channel diff --git a/skills/agent-tmux/bin/trigger-transaction.mjs b/skills/agent-tmux/bin/trigger-transaction.mjs new file mode 100644 index 00000000..2b4df347 --- /dev/null +++ b/skills/agent-tmux/bin/trigger-transaction.mjs @@ -0,0 +1,53 @@ +/** Reconcile session-bound triggers through an operator-provided CAS adapter. */ +const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); + +// begin must atomically reserve this ID and trigger set, rejecting unresolved +// overlapping transactions. Each write must be durable before it resolves. +// The adapter atomically compares target AND version and stores operationId. +export async function reconcileTriggers({ triggers, from, to, transactionId, adapter, journal, dryRun = true }) { + if (!Array.isArray(triggers) || triggers.length > 256 || !token(from) || !token(to) || from === to || !token(transactionId) || transactionId.length > 90 || typeof dryRun !== 'boolean' || typeof adapter?.read !== 'function' || typeof adapter?.move !== 'function' || typeof journal?.begin !== 'function' || typeof journal?.write !== 'function') throw new Error('invalid trigger transaction'); + const seen = new Set(); + for (const trigger of triggers) { + if (!token(trigger?.kind) || !token(trigger?.id) || seen.has(`${trigger.kind}\0${trigger.id}`)) throw new Error('invalid or duplicate trigger'); + seen.add(`${trigger.kind}\0${trigger.id}`); + } + const receipt = { schema: 'agent-mesh.trigger-transaction.v1', id: transactionId, from, to, dryRun, status: 'planning', triggers: [] }; + await journal.begin({ id: transactionId, triggers: structuredClone(triggers), dryRun }); + const save = () => journal.write(structuredClone(receipt)); + for (const trigger of triggers) { + const current = await adapter.read(trigger); + if (!current || current.target !== from || !token(current.version)) throw new Error('trigger source or version not verified'); + receipt.triggers.push({ kind: trigger.kind, id: trigger.id, before: current.version, status: 'planned' }); + } + receipt.status = dryRun ? 'dry-run' : 'applying'; + await save(); + if (dryRun) return receipt; + for (let i = 0; i < receipt.triggers.length; i++) { + const row = receipt.triggers[i], operationId = `${transactionId}:${i}`; + row.status = 'applying'; row.operationId = operationId; await save(); + let response; + try { response = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: from, expectedVersion: row.before, target: to, operationId }); } + catch { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + if (response?.status !== 'applied' || !token(response.version)) { + row.status = response?.status === 'not-applied' ? 'not-applied' : 'uncertain'; + receipt.status = row.status === 'uncertain' ? 'uncertain' : 'rolling-back'; await save(); + if (row.status === 'uncertain') return receipt; + for (let j = i - 1; j >= 0; j--) { + const prior = receipt.triggers[j], rollbackId = `${transactionId}:rollback:${j}`; + prior.status = 'rolling-back'; await save(); + let rollback; + try { rollback = await adapter.move({ kind: prior.kind, id: prior.id, expectedTarget: to, expectedVersion: prior.after, target: from, operationId: rollbackId }); } + catch { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + if (rollback?.status !== 'applied' || !token(rollback.version)) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + const observed = await adapter.read(prior); + if (observed?.target !== from || observed.version !== rollback.version || observed.lastOperationId !== rollbackId) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + prior.status = 'rolled-back'; prior.rollbackVersion = rollback.version; await save(); + } + receipt.status = 'rolled-back'; await save(); return receipt; + } + const observed = await adapter.read(row); + if (observed?.target !== to || observed.version !== response.version || observed.lastOperationId !== operationId) { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + row.after = response.version; row.status = 'verified'; await save(); + } + receipt.status = 'verified'; await save(); return receipt; +} From 017be51e8f5934bb0fc2d3aa052ac40888d4ca9c Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:32:42 +0000 Subject: [PATCH 043/113] Persist trigger transaction reservations --- docs/design/plexus-architecture.mmd | 3 +- docs/design/plexus-channels.md | 12 ++- packages/tmux-bridge/bin/trigger-journal.mjs | 76 +++++++++++++++++++ .../tmux-bridge/test/trigger-journal.test.mjs | 60 +++++++++++++++ scripts/plexus-diagram.mjs | 3 +- skills/agent-tmux/bin/trigger-journal.mjs | 76 +++++++++++++++++++ 6 files changed, 226 insertions(+), 4 deletions(-) create mode 100644 packages/tmux-bridge/bin/trigger-journal.mjs create mode 100644 packages/tmux-bridge/test/trigger-journal.test.mjs create mode 100644 skills/agent-tmux/bin/trigger-journal.mjs diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 9a2a254a..5b3786e3 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -13,7 +13,8 @@ flowchart LR Restart["Restart state contract"] --> StatePrep["Reserved state preparation"] StatePrep --> Journal StatePrep -. "planned proof revalidation" .-> Handover - TriggerTxn["Trigger transaction engine"] -. "planned adapters and journal" .-> Handover + TriggerTxn["Trigger transaction engine"] --> TriggerJournal["Private trigger journal"] + 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 diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 6494f7cb..a419e376 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -45,8 +45,16 @@ compare the original target and version atomically and expose the operation ID on readback. Definite refusal rolls back earlier verified moves using the same compare-and-set contract; an ambiguous result stays unresolved and is not retried. Dry-run reads and journals a plan without moving triggers. Concrete -timer and cloud adapters, durable journal implementation and recovery are not -yet provided; this engine is not authorization to change live triggers. +timer and cloud adapters and automatic recovery are not yet provided; this +engine is not authorization to change live triggers. + +`trigger-journal.mjs` implements the local journal in an explicitly selected, +private canonical directory. It reserves overlapping trigger sets atomically, +persists snapshots using fsync and atomic replacement, and rejects reused +transaction IDs. Uncertain transactions keep their reservation after restart. +A leftover lock requires operator reconciliation; it is never removed as stale +automatically. The journal is a trusted local operator component and does not +itself prove a scheduler change or provide recovery of an uncertain move. The prepared Codex path additionally requires a fresh unarchived native-thread observation and exactly one detected writer. Claude and cloud successors are not yet supported by this operation. diff --git a/packages/tmux-bridge/bin/trigger-journal.mjs b/packages/tmux-bridge/bin/trigger-journal.mjs new file mode 100644 index 00000000..1a655c2f --- /dev/null +++ b/packages/tmux-bridge/bin/trigger-journal.mjs @@ -0,0 +1,76 @@ +/** Private crash-conservative journal for trigger transactions. */ +import { constants, closeSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'; +import { randomUUID } from 'node:crypto'; +import { isAbsolute, join } from 'node:path'; + +const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const terminal = new Set(['verified', 'rolled-back', 'dry-run']); +const statuses = new Set(['planning', 'applying', 'rolling-back', 'uncertain', ...terminal]); +const key = trigger => JSON.stringify([trigger.kind, trigger.id]); + +export function triggerJournal(root) { + if (typeof root !== 'string' || !isAbsolute(root)) throw new Error('invalid journal root'); + const checkRoot = () => { + const info = lstatSync(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || realpathSync(root) !== root) throw new Error('journal root must be private and canonical'); + }; + const file = join(root, 'trigger-transactions.json'), lock = join(root, '.trigger-transactions.lock'); + const syncRoot = () => { const fd = openSync(root, constants.O_RDONLY | constants.O_DIRECTORY); try { fsyncSync(fd); } finally { closeSync(fd); } }; + const load = () => { + let fd; + try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW); } + catch (error) { if (error.code === 'ENOENT') return { schema: 'agent-mesh.trigger-journal.v1', entries: [] }; throw error; } + try { + const info = fstatSync(fd); + if (!info.isFile() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0 || info.size > 8 * 1024 * 1024) throw new Error('invalid journal file'); + const data = JSON.parse(readFileSync(fd, 'utf8')); + if (data?.schema !== 'agent-mesh.trigger-journal.v1' || !Array.isArray(data.entries) || new Set(data.entries.map(entry => entry?.id)).size !== data.entries.length || data.entries.some(entry => !token(entry?.id) || typeof entry.dryRun !== 'boolean' || !Array.isArray(entry.triggers) || entry.triggers.some(t => !token(t?.kind) || !token(t?.id)) || new Set(entry.triggers.map(key)).size !== entry.triggers.length || !statuses.has(entry.status))) throw new Error('invalid journal content'); + return data; + } finally { closeSync(fd); } + }; + const save = data => { + const body = `${JSON.stringify(data)}\n`; + if (Buffer.byteLength(body) > 8 * 1024 * 1024) throw new Error('journal is too large'); + const temporary = join(root, `.trigger-journal-${randomUUID()}.tmp`); + const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + try { writeFileSync(fd, body); fsyncSync(fd); } finally { closeSync(fd); } + renameSync(temporary, file); syncRoot(); + }; + const transaction = operation => { + checkRoot(); + let fd; + try { fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); } + catch (error) { if (error.code === 'EEXIST') throw new Error('journal lock held or requires recovery'); throw error; } + try { fsyncSync(fd); syncRoot(); const data = load(); const result = operation(data); save(data); return result; } + finally { + const owned = fstatSync(fd); closeSync(fd); + const current = lstatSync(lock); + if (current.dev !== owned.dev || current.ino !== owned.ino) throw new Error('journal lock changed'); + unlinkSync(lock); syncRoot(); + } + }; + return { + async begin({ id, triggers, dryRun }) { + if (!token(id) || !Array.isArray(triggers) || typeof dryRun !== 'boolean' || triggers.some(t => !token(t?.kind) || !token(t?.id)) || new Set(triggers.map(key)).size !== triggers.length) throw new Error('invalid journal reservation'); + return transaction(data => { + if (data.entries.some(entry => entry.id === id)) throw new Error('transaction already reserved'); + const requested = new Set(triggers.map(key)); + if (data.entries.some(entry => !terminal.has(entry.status) && entry.triggers.some(trigger => requested.has(key(trigger))))) throw new Error('overlapping transaction unresolved'); + data.entries.push({ id, dryRun, status: 'planning', triggers: structuredClone(triggers), receipt: null }); + }); + }, + async write(receipt) { + return transaction(data => { + const entry = data.entries.find(item => item.id === receipt?.id); + if (!entry || terminal.has(entry.status) || receipt.schema !== 'agent-mesh.trigger-transaction.v1' || receipt.dryRun !== entry.dryRun || !statuses.has(receipt.status) || !Array.isArray(receipt.triggers) || JSON.stringify(receipt.triggers.map(key)) !== JSON.stringify(entry.triggers.map(key))) throw new Error('invalid journal update'); + entry.status = receipt.status; entry.receipt = structuredClone(receipt); + }); + }, + async get(id) { + checkRoot(); + if (!token(id)) throw new Error('invalid transaction id'); + const entry = load().entries.find(item => item.id === id); + return entry ? structuredClone(entry) : null; + } + }; +} diff --git a/packages/tmux-bridge/test/trigger-journal.test.mjs b/packages/tmux-bridge/test/trigger-journal.test.mjs new file mode 100644 index 00000000..4479dcfa --- /dev/null +++ b/packages/tmux-bridge/test/trigger-journal.test.mjs @@ -0,0 +1,60 @@ +import assert from 'node:assert/strict'; +import { execFile } from 'node:child_process'; +import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; +import test from 'node:test'; +import { promisify } from 'node:util'; +import { triggerJournal } from '../bin/trigger-journal.mjs'; +import { reconcileTriggers } from '../bin/trigger-transaction.mjs'; +const exec = promisify(execFile); + +test('concurrent processes cannot reserve the same trigger', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-journal-')); + t.after(() => rm(root, { recursive: true, force: true })); + const moduleUrl = new URL('../bin/trigger-journal.mjs', import.meta.url).href; + const script = `import { triggerJournal } from ${JSON.stringify(moduleUrl)}; await triggerJournal(process.argv[1]).begin({id: process.argv[2], triggers:[{kind:'timer',id:'one'}], dryRun:false});`; + const results = await Promise.allSettled(['first', 'second'].map(id => exec(process.execPath, ['--input-type=module', '-e', script, root, id]))); + assert.equal(results.filter(result => result.status === 'fulfilled').length, 1); + const rejected = results.find(result => result.status === 'rejected'); + assert.match(rejected.reason.stderr, /overlapping transaction unresolved|journal lock held/); +}); + +test('uncertain move remains reserved after journal re-open', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-journal-')); + t.after(() => rm(root, { recursive: true, force: true })); + const trigger = { kind: 'timer', id: 'one' }, journal = triggerJournal(root); + let calls = 0; + const adapter = { read: async () => ({ target: 'codex:old', version: 'v1' }), move: async () => { calls++; throw new Error('lost'); } }; + const receipt = await reconcileTriggers({ triggers: [trigger], from: 'codex:old', to: 'codex:new', transactionId: 'first', adapter, journal, dryRun: false }); + assert.equal(receipt.status, 'uncertain'); assert.equal(calls, 1); + const reopened = triggerJournal(root); + assert.equal((await reopened.get('first')).status, 'uncertain'); + await assert.rejects(reopened.begin({ id: 'second', triggers: [trigger], dryRun: false }), /overlapping/); + await assert.rejects(reopened.begin({ id: 'first', triggers: [trigger], dryRun: false }), /already reserved/); + assert.equal(calls, 1); +}); + +test('completed dry run releases scope, but not its transaction ID', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-journal-')); + t.after(() => rm(root, { recursive: true, force: true })); + const trigger = { kind: 'timer', id: 'one' }, journal = triggerJournal(root); + const adapter = { read: async () => ({ target: 'codex:old', version: 'v1' }), move: async () => { throw new Error('must not move'); } }; + const receipt = await reconcileTriggers({ triggers: [trigger], from: 'codex:old', to: 'codex:new', transactionId: 'dry', adapter, journal }); + assert.equal(receipt.status, 'dry-run'); + await journal.begin({ id: 'next', triggers: [trigger], dryRun: false }); + await assert.rejects(journal.begin({ id: 'dry', triggers: [trigger], dryRun: false }), /already reserved/); +}); + +test('journal refuses unsafe permissions, invalid state and abandoned locks', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-journal-')); + t.after(() => rm(root, { recursive: true, force: true })); + const journal = triggerJournal(root), reservation = { id: 'one', triggers: [], dryRun: true }; + await chmod(root, 0o755); + await assert.rejects(journal.begin(reservation), /private/); + await chmod(root, 0o700); + await writeFile(join(root, 'trigger-transactions.json'), '{broken', { mode: 0o600 }); + await assert.rejects(journal.begin(reservation)); + await writeFile(join(root, '.trigger-transactions.lock'), 'fixture', { mode: 0o600 }); + await assert.rejects(journal.begin(reservation), /lock held/); +}); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 83cd585f..17585ba4 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -14,7 +14,8 @@ export const plexusDiagram = `flowchart LR Restart["Restart state contract"] --> StatePrep["Reserved state preparation"] StatePrep --> Journal StatePrep -. "planned proof revalidation" .-> Handover - TriggerTxn["Trigger transaction engine"] -. "planned adapters and journal" .-> Handover + TriggerTxn["Trigger transaction engine"] --> TriggerJournal["Private trigger journal"] + 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 diff --git a/skills/agent-tmux/bin/trigger-journal.mjs b/skills/agent-tmux/bin/trigger-journal.mjs new file mode 100644 index 00000000..1a655c2f --- /dev/null +++ b/skills/agent-tmux/bin/trigger-journal.mjs @@ -0,0 +1,76 @@ +/** Private crash-conservative journal for trigger transactions. */ +import { constants, closeSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'; +import { randomUUID } from 'node:crypto'; +import { isAbsolute, join } from 'node:path'; + +const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const terminal = new Set(['verified', 'rolled-back', 'dry-run']); +const statuses = new Set(['planning', 'applying', 'rolling-back', 'uncertain', ...terminal]); +const key = trigger => JSON.stringify([trigger.kind, trigger.id]); + +export function triggerJournal(root) { + if (typeof root !== 'string' || !isAbsolute(root)) throw new Error('invalid journal root'); + const checkRoot = () => { + const info = lstatSync(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || realpathSync(root) !== root) throw new Error('journal root must be private and canonical'); + }; + const file = join(root, 'trigger-transactions.json'), lock = join(root, '.trigger-transactions.lock'); + const syncRoot = () => { const fd = openSync(root, constants.O_RDONLY | constants.O_DIRECTORY); try { fsyncSync(fd); } finally { closeSync(fd); } }; + const load = () => { + let fd; + try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW); } + catch (error) { if (error.code === 'ENOENT') return { schema: 'agent-mesh.trigger-journal.v1', entries: [] }; throw error; } + try { + const info = fstatSync(fd); + if (!info.isFile() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0 || info.size > 8 * 1024 * 1024) throw new Error('invalid journal file'); + const data = JSON.parse(readFileSync(fd, 'utf8')); + if (data?.schema !== 'agent-mesh.trigger-journal.v1' || !Array.isArray(data.entries) || new Set(data.entries.map(entry => entry?.id)).size !== data.entries.length || data.entries.some(entry => !token(entry?.id) || typeof entry.dryRun !== 'boolean' || !Array.isArray(entry.triggers) || entry.triggers.some(t => !token(t?.kind) || !token(t?.id)) || new Set(entry.triggers.map(key)).size !== entry.triggers.length || !statuses.has(entry.status))) throw new Error('invalid journal content'); + return data; + } finally { closeSync(fd); } + }; + const save = data => { + const body = `${JSON.stringify(data)}\n`; + if (Buffer.byteLength(body) > 8 * 1024 * 1024) throw new Error('journal is too large'); + const temporary = join(root, `.trigger-journal-${randomUUID()}.tmp`); + const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + try { writeFileSync(fd, body); fsyncSync(fd); } finally { closeSync(fd); } + renameSync(temporary, file); syncRoot(); + }; + const transaction = operation => { + checkRoot(); + let fd; + try { fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); } + catch (error) { if (error.code === 'EEXIST') throw new Error('journal lock held or requires recovery'); throw error; } + try { fsyncSync(fd); syncRoot(); const data = load(); const result = operation(data); save(data); return result; } + finally { + const owned = fstatSync(fd); closeSync(fd); + const current = lstatSync(lock); + if (current.dev !== owned.dev || current.ino !== owned.ino) throw new Error('journal lock changed'); + unlinkSync(lock); syncRoot(); + } + }; + return { + async begin({ id, triggers, dryRun }) { + if (!token(id) || !Array.isArray(triggers) || typeof dryRun !== 'boolean' || triggers.some(t => !token(t?.kind) || !token(t?.id)) || new Set(triggers.map(key)).size !== triggers.length) throw new Error('invalid journal reservation'); + return transaction(data => { + if (data.entries.some(entry => entry.id === id)) throw new Error('transaction already reserved'); + const requested = new Set(triggers.map(key)); + if (data.entries.some(entry => !terminal.has(entry.status) && entry.triggers.some(trigger => requested.has(key(trigger))))) throw new Error('overlapping transaction unresolved'); + data.entries.push({ id, dryRun, status: 'planning', triggers: structuredClone(triggers), receipt: null }); + }); + }, + async write(receipt) { + return transaction(data => { + const entry = data.entries.find(item => item.id === receipt?.id); + if (!entry || terminal.has(entry.status) || receipt.schema !== 'agent-mesh.trigger-transaction.v1' || receipt.dryRun !== entry.dryRun || !statuses.has(receipt.status) || !Array.isArray(receipt.triggers) || JSON.stringify(receipt.triggers.map(key)) !== JSON.stringify(entry.triggers.map(key))) throw new Error('invalid journal update'); + entry.status = receipt.status; entry.receipt = structuredClone(receipt); + }); + }, + async get(id) { + checkRoot(); + if (!token(id)) throw new Error('invalid transaction id'); + const entry = load().entries.find(item => item.id === id); + return entry ? structuredClone(entry) : null; + } + }; +} From 99d2958c8723018422e26248fadb7c188f9c66d2 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:41:56 +0000 Subject: [PATCH 044/113] Recover uncertain trigger transactions explicitly --- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-channels.md | 12 ++-- packages/tmux-bridge/bin/trigger-journal.mjs | 21 ++++++- .../tmux-bridge/bin/trigger-transaction.mjs | 38 +++++++++++++ .../tmux-bridge/test/trigger-journal.test.mjs | 56 ++++++++++++++++++- scripts/plexus-diagram.mjs | 1 + skills/agent-tmux/bin/trigger-journal.mjs | 21 ++++++- skills/agent-tmux/bin/trigger-transaction.mjs | 38 +++++++++++++ 8 files changed, 181 insertions(+), 7 deletions(-) diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 5b3786e3..66469ed3 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -14,6 +14,7 @@ flowchart LR StatePrep --> Journal StatePrep -. "planned proof revalidation" .-> 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 diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index a419e376..c11a60cc 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -41,11 +41,11 @@ The proof does not authorize cutover, archive, or final-message publication. `trigger-transaction.mjs` supplies a generic transaction engine, not a live scheduler adapter. Its injected journal must atomically reserve overlapping trigger sets and durably record intent before each move. Its adapter must -compare the original target and version atomically and expose the operation ID -on readback. Definite refusal rolls back earlier verified moves using the same +compare the original target and a never-reused state version atomically and +expose the operation ID on readback. Definite refusal rolls back earlier verified moves using the same compare-and-set contract; an ambiguous result stays unresolved and is not retried. Dry-run reads and journals a plan without moving triggers. Concrete -timer and cloud adapters and automatic recovery are not yet provided; this +timer and cloud adapters are not yet provided; this engine is not authorization to change live triggers. `trigger-journal.mjs` implements the local journal in an explicitly selected, @@ -54,7 +54,11 @@ persists snapshots using fsync and atomic replacement, and rejects reused transaction IDs. Uncertain transactions keep their reservation after restart. A leftover lock requires operator reconciliation; it is never removed as stale automatically. The journal is a trusted local operator component and does not -itself prove a scheduler change or provide recovery of an uncertain move. +itself prove a scheduler change. Explicit recovery of an `uncertain` receipt +first inspects every trigger and rolls back only versions linked to the original +operation; other changes remain unresolved. A recovery lock prevents concurrent +recovery. Abrupt process loss while an operation is still `applying` or +`rolling-back`, or an abandoned lock, requires separate operator reconciliation. The prepared Codex path additionally requires a fresh unarchived native-thread observation and exactly one detected writer. Claude and cloud successors are not yet supported by this operation. diff --git a/packages/tmux-bridge/bin/trigger-journal.mjs b/packages/tmux-bridge/bin/trigger-journal.mjs index 1a655c2f..5603d817 100644 --- a/packages/tmux-bridge/bin/trigger-journal.mjs +++ b/packages/tmux-bridge/bin/trigger-journal.mjs @@ -1,6 +1,6 @@ /** Private crash-conservative journal for trigger transactions. */ import { constants, closeSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'; -import { randomUUID } from 'node:crypto'; +import { createHash, randomUUID } from 'node:crypto'; import { isAbsolute, join } from 'node:path'; const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); @@ -71,6 +71,25 @@ export function triggerJournal(root) { if (!token(id)) throw new Error('invalid transaction id'); const entry = load().entries.find(item => item.id === id); return entry ? structuredClone(entry) : null; + }, + async withRecovery(id, callback) { + checkRoot(); + if (!token(id) || typeof callback !== 'function') throw new Error('invalid recovery request'); + const recoveryLock = join(root, `.trigger-recovery-${createHash('sha256').update(id).digest('hex')}.lock`); + let fd; + try { fd = openSync(recoveryLock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); } + catch (error) { if (error.code === 'EEXIST') throw new Error('recovery lock held or requires reconciliation'); throw error; } + try { + fsyncSync(fd); syncRoot(); + const journal = triggerJournal(root), entry = await journal.get(id); + if (!entry || entry.status !== 'uncertain' || !entry.receipt) throw new Error('transaction not recoverable'); + return await callback(entry.receipt, receipt => journal.write(receipt)); + } finally { + const owned = fstatSync(fd); closeSync(fd); + const current = lstatSync(recoveryLock); + if (current.dev !== owned.dev || current.ino !== owned.ino) throw new Error('recovery lock changed'); + unlinkSync(recoveryLock); syncRoot(); + } } }; } diff --git a/packages/tmux-bridge/bin/trigger-transaction.mjs b/packages/tmux-bridge/bin/trigger-transaction.mjs index 2b4df347..557b792a 100644 --- a/packages/tmux-bridge/bin/trigger-transaction.mjs +++ b/packages/tmux-bridge/bin/trigger-transaction.mjs @@ -51,3 +51,41 @@ export async function reconcileTriggers({ triggers, from, to, transactionId, ada } receipt.status = 'verified'; await save(); return receipt; } + +/** Explicitly roll back an uncertain transaction after inspecting all targets. */ +export async function recoverUncertainTriggers({ transactionId, adapter, journal }) { + if (!token(transactionId) || typeof adapter?.read !== 'function' || typeof adapter?.move !== 'function' || typeof journal?.withRecovery !== 'function') throw new Error('invalid trigger recovery'); + return journal.withRecovery(transactionId, async (receipt, save) => { + if (receipt.id !== transactionId || receipt.status !== 'uncertain' || receipt.dryRun !== false || !Array.isArray(receipt.triggers)) throw new Error('invalid uncertain receipt'); + const observations = []; + for (let i = 0; i < receipt.triggers.length; i++) { + const row = receipt.triggers[i], observed = await adapter.read(row); + if (!observed || !token(observed.version)) throw new Error('trigger observation unavailable'); + const forwardId = `${transactionId}:${i}`, rollbackId = `${transactionId}:rollback:${i}`; + if (observed.target === receipt.from && observed.version === row.before) observations.push({ kind: 'unchanged', observed }); + else if (observed.target === receipt.from && observed.lastOperationId === rollbackId && (!row.rollbackVersion || row.rollbackVersion === observed.version)) observations.push({ kind: 'rolled-back', observed }); + else if (observed.target === receipt.to && observed.lastOperationId === forwardId && (!row.after || row.after === observed.version)) observations.push({ kind: 'moved', observed }); + else throw new Error('trigger changed outside transaction'); + } + for (let i = receipt.triggers.length - 1; i >= 0; i--) { + const row = receipt.triggers[i], { kind, observed } = observations[i]; + if (kind !== 'moved') { + row.status = kind === 'unchanged' ? 'not-applied' : 'rolled-back'; + if (kind === 'rolled-back') row.rollbackVersion = observed.version; + continue; + } + const operationId = `${transactionId}:rollback:${i}`; + row.after = observed.version; row.status = 'rolling-back'; receipt.status = 'rolling-back'; await save(receipt); + let result, confirmed; + try { + result = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: receipt.to, expectedVersion: observed.version, target: receipt.from, operationId }); + if (result?.status === 'applied' && token(result.version)) confirmed = await adapter.read(row); + } catch { /* The outcome may have been applied. */ } + if (confirmed?.target !== receipt.from || confirmed.version !== result?.version || confirmed.lastOperationId !== operationId) { + row.status = 'uncertain'; receipt.status = 'uncertain'; await save(receipt); return receipt; + } + row.status = 'rolled-back'; row.rollbackVersion = result.version; await save(receipt); + } + receipt.status = 'rolled-back'; await save(receipt); return receipt; + }); +} diff --git a/packages/tmux-bridge/test/trigger-journal.test.mjs b/packages/tmux-bridge/test/trigger-journal.test.mjs index 4479dcfa..36b405cf 100644 --- a/packages/tmux-bridge/test/trigger-journal.test.mjs +++ b/packages/tmux-bridge/test/trigger-journal.test.mjs @@ -6,7 +6,7 @@ import { tmpdir } from 'node:os'; import test from 'node:test'; import { promisify } from 'node:util'; import { triggerJournal } from '../bin/trigger-journal.mjs'; -import { reconcileTriggers } from '../bin/trigger-transaction.mjs'; +import { reconcileTriggers, recoverUncertainTriggers } from '../bin/trigger-transaction.mjs'; const exec = promisify(execFile); test('concurrent processes cannot reserve the same trigger', async t => { @@ -35,6 +35,60 @@ test('uncertain move remains reserved after journal re-open', async t => { assert.equal(calls, 1); }); +test('explicit recovery rolls back only a proven move after a lost response', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-recovery-')); + t.after(() => rm(root, { recursive: true, force: true })); + let state = { target: 'codex:old', version: 'v1' }, lose = true, calls = 0; + const adapter = { read: async () => structuredClone(state), move: async args => { + calls++; + if (state.target !== args.expectedTarget || state.version !== args.expectedVersion) return { status: 'not-applied' }; + state = { target: args.target, version: `v${calls + 1}`, lastOperationId: args.operationId }; + if (lose) { lose = false; throw new Error('response lost'); } + return { status: 'applied', version: state.version }; + } }; + const journal = triggerJournal(root), triggers = [{ kind: 'timer', id: 'one' }]; + const first = await reconcileTriggers({ triggers, from: 'codex:old', to: 'codex:new', transactionId: 'tx', adapter, journal, dryRun: false }); + assert.equal(first.status, 'uncertain'); assert.equal(state.target, 'codex:new'); + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal: triggerJournal(root) }); + assert.equal(recovered.status, 'rolled-back'); assert.equal(state.target, 'codex:old'); assert.equal(calls, 2); + assert.equal((await triggerJournal(root).get('tx')).status, 'rolled-back'); +}); + +test('recovery refuses another writer before attempting any rollback', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-recovery-')); + t.after(() => rm(root, { recursive: true, force: true })); + let state = { target: 'codex:old', version: 'v1' }, calls = 0; + const adapter = { read: async () => structuredClone(state), move: async args => { calls++; state = { target: args.target, version: 'v2', lastOperationId: args.operationId }; throw new Error('lost'); } }; + const journal = triggerJournal(root); + await reconcileTriggers({ triggers: [{ kind: 'timer', id: 'one' }], from: 'codex:old', to: 'codex:new', transactionId: 'tx', adapter, journal, dryRun: false }); + state = { target: 'codex:new', version: 'v3', lastOperationId: 'other' }; + await assert.rejects(recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }), /outside transaction/); + assert.equal(calls, 1); assert.equal((await journal.get('tx')).status, 'uncertain'); +}); + +test('recovery restores two proven moves in reverse order', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-recovery-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = new Map(['one', 'two'].map(id => [id, { target: 'codex:old', version: 'v1' }])); + const operations = []; let counter = 1, lose = true; + const adapter = { read: async ({ id }) => structuredClone(state.get(id)), move: async args => { + const current = state.get(args.id); + if (current.target !== args.expectedTarget || current.version !== args.expectedVersion) return { status: 'not-applied' }; + operations.push(args.operationId); + const next = { target: args.target, version: `v${++counter}`, lastOperationId: args.operationId }; + state.set(args.id, next); + if (args.id === 'two' && lose) { lose = false; throw new Error('response lost'); } + return { status: 'applied', version: next.version }; + } }; + const journal = triggerJournal(root), triggers = ['one', 'two'].map(id => ({ kind: 'timer', id })); + const uncertain = await reconcileTriggers({ triggers, from: 'codex:old', to: 'codex:new', transactionId: 'tx', adapter, journal, dryRun: false }); + assert.equal(uncertain.status, 'uncertain'); + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); + assert.equal(recovered.status, 'rolled-back'); + assert.deepEqual(operations, ['tx:0', 'tx:1', 'tx:rollback:1', 'tx:rollback:0']); + assert.equal(state.get('one').target, 'codex:old'); assert.equal(state.get('two').target, 'codex:old'); +}); + test('completed dry run releases scope, but not its transaction ID', async t => { const root = await mkdtemp(join(tmpdir(), 'trigger-journal-')); t.after(() => rm(root, { recursive: true, force: true })); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 17585ba4..414487e8 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -15,6 +15,7 @@ export const plexusDiagram = `flowchart LR StatePrep --> Journal StatePrep -. "planned proof revalidation" .-> 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 diff --git a/skills/agent-tmux/bin/trigger-journal.mjs b/skills/agent-tmux/bin/trigger-journal.mjs index 1a655c2f..5603d817 100644 --- a/skills/agent-tmux/bin/trigger-journal.mjs +++ b/skills/agent-tmux/bin/trigger-journal.mjs @@ -1,6 +1,6 @@ /** Private crash-conservative journal for trigger transactions. */ import { constants, closeSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'; -import { randomUUID } from 'node:crypto'; +import { createHash, randomUUID } from 'node:crypto'; import { isAbsolute, join } from 'node:path'; const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); @@ -71,6 +71,25 @@ export function triggerJournal(root) { if (!token(id)) throw new Error('invalid transaction id'); const entry = load().entries.find(item => item.id === id); return entry ? structuredClone(entry) : null; + }, + async withRecovery(id, callback) { + checkRoot(); + if (!token(id) || typeof callback !== 'function') throw new Error('invalid recovery request'); + const recoveryLock = join(root, `.trigger-recovery-${createHash('sha256').update(id).digest('hex')}.lock`); + let fd; + try { fd = openSync(recoveryLock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); } + catch (error) { if (error.code === 'EEXIST') throw new Error('recovery lock held or requires reconciliation'); throw error; } + try { + fsyncSync(fd); syncRoot(); + const journal = triggerJournal(root), entry = await journal.get(id); + if (!entry || entry.status !== 'uncertain' || !entry.receipt) throw new Error('transaction not recoverable'); + return await callback(entry.receipt, receipt => journal.write(receipt)); + } finally { + const owned = fstatSync(fd); closeSync(fd); + const current = lstatSync(recoveryLock); + if (current.dev !== owned.dev || current.ino !== owned.ino) throw new Error('recovery lock changed'); + unlinkSync(recoveryLock); syncRoot(); + } } }; } diff --git a/skills/agent-tmux/bin/trigger-transaction.mjs b/skills/agent-tmux/bin/trigger-transaction.mjs index 2b4df347..557b792a 100644 --- a/skills/agent-tmux/bin/trigger-transaction.mjs +++ b/skills/agent-tmux/bin/trigger-transaction.mjs @@ -51,3 +51,41 @@ export async function reconcileTriggers({ triggers, from, to, transactionId, ada } receipt.status = 'verified'; await save(); return receipt; } + +/** Explicitly roll back an uncertain transaction after inspecting all targets. */ +export async function recoverUncertainTriggers({ transactionId, adapter, journal }) { + if (!token(transactionId) || typeof adapter?.read !== 'function' || typeof adapter?.move !== 'function' || typeof journal?.withRecovery !== 'function') throw new Error('invalid trigger recovery'); + return journal.withRecovery(transactionId, async (receipt, save) => { + if (receipt.id !== transactionId || receipt.status !== 'uncertain' || receipt.dryRun !== false || !Array.isArray(receipt.triggers)) throw new Error('invalid uncertain receipt'); + const observations = []; + for (let i = 0; i < receipt.triggers.length; i++) { + const row = receipt.triggers[i], observed = await adapter.read(row); + if (!observed || !token(observed.version)) throw new Error('trigger observation unavailable'); + const forwardId = `${transactionId}:${i}`, rollbackId = `${transactionId}:rollback:${i}`; + if (observed.target === receipt.from && observed.version === row.before) observations.push({ kind: 'unchanged', observed }); + else if (observed.target === receipt.from && observed.lastOperationId === rollbackId && (!row.rollbackVersion || row.rollbackVersion === observed.version)) observations.push({ kind: 'rolled-back', observed }); + else if (observed.target === receipt.to && observed.lastOperationId === forwardId && (!row.after || row.after === observed.version)) observations.push({ kind: 'moved', observed }); + else throw new Error('trigger changed outside transaction'); + } + for (let i = receipt.triggers.length - 1; i >= 0; i--) { + const row = receipt.triggers[i], { kind, observed } = observations[i]; + if (kind !== 'moved') { + row.status = kind === 'unchanged' ? 'not-applied' : 'rolled-back'; + if (kind === 'rolled-back') row.rollbackVersion = observed.version; + continue; + } + const operationId = `${transactionId}:rollback:${i}`; + row.after = observed.version; row.status = 'rolling-back'; receipt.status = 'rolling-back'; await save(receipt); + let result, confirmed; + try { + result = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: receipt.to, expectedVersion: observed.version, target: receipt.from, operationId }); + if (result?.status === 'applied' && token(result.version)) confirmed = await adapter.read(row); + } catch { /* The outcome may have been applied. */ } + if (confirmed?.target !== receipt.from || confirmed.version !== result?.version || confirmed.lastOperationId !== operationId) { + row.status = 'uncertain'; receipt.status = 'uncertain'; await save(receipt); return receipt; + } + row.status = 'rolled-back'; row.rollbackVersion = result.version; await save(receipt); + } + receipt.status = 'rolled-back'; await save(receipt); return receipt; + }); +} From 2019d36104bb86d648d69fc09f5682a5266c143e Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:48:58 +0000 Subject: [PATCH 045/113] Bind cloud account scope to CLI profile --- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-channels.md | 9 ++++ .../tmux-bridge/bin/cloud-account-binding.mjs | 41 ++++++++++++++++ .../test/cloud-account-binding.test.mjs | 48 +++++++++++++++++++ scripts/plexus-diagram.mjs | 1 + .../agent-tmux/bin/cloud-account-binding.mjs | 41 ++++++++++++++++ 6 files changed, 141 insertions(+) create mode 100644 packages/tmux-bridge/bin/cloud-account-binding.mjs create mode 100644 packages/tmux-bridge/test/cloud-account-binding.test.mjs create mode 100644 skills/agent-tmux/bin/cloud-account-binding.mjs diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 66469ed3..d7adacf3 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -9,6 +9,7 @@ flowchart LR 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"] StatePrep --> Journal diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index c11a60cc..b5a0d1e3 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -63,6 +63,15 @@ The prepared Codex path additionally requires a fresh unarchived native-thread observation and exactly one detected writer. Claude and cloud successors are not yet supported by this operation. +`cloud-account-binding.mjs` prepares an opt-in Claude CLI account check. A +private operator profile binds an account scope to a CLI configuration directory +and a digest of its reported account and organization; the helper checks the +same profile before and after an operation and treats changes as uncertain. +Profile configuration and digests are private. This check relies on a trusted +CLI and configuration directory, does not prevent a concurrent credential +switch, and is not provider readback or proof of delivery. It is not connected +to channel routing or enabled by default. + This is not yet a complete handover workflow: it does not write state for the old session, publish or verify the old session's final notice, archive anything, or reconcile uncertain transport outcomes. It must not be used for a live diff --git a/packages/tmux-bridge/bin/cloud-account-binding.mjs b/packages/tmux-bridge/bin/cloud-account-binding.mjs new file mode 100644 index 00000000..513a18ea --- /dev/null +++ b/packages/tmux-bridge/bin/cloud-account-binding.mjs @@ -0,0 +1,41 @@ +/** Bind an operator-selected Claude CLI profile to an account scope. */ +import { createHash } from 'node:crypto'; +import { execFile } from 'node:child_process'; +import { lstat, realpath } from 'node:fs/promises'; +import { isAbsolute } from 'node:path'; +import { promisify } from 'node:util'; + +const execute = promisify(execFile); +const SCOPE = /^[a-z][a-z0-9-]{0,63}$/; + +// Only a digest is returned. Raw identity and credentials are never returned +// or copied to a receipt; the operator must protect the configured profile. +export function claudeSubjectHash(status) { + if (!status || status.loggedIn !== true || status.apiProvider !== 'firstParty' || status.authMethod !== 'claude.ai' || status.storedClaudeAiLogin !== true || typeof status.email !== 'string' || !status.email.trim() || typeof status.orgId !== 'string' || !status.orgId.trim()) throw new Error('Claude account identity unavailable'); + return createHash('sha256').update(JSON.stringify([status.email.trim().toLowerCase(), status.orgId.trim()])).digest('hex'); +} + +export async function verifyClaudeAccount(profile, run = execute) { + if (!profile || typeof profile.scope !== 'string' || !SCOPE.test(profile.scope) || typeof profile.expectedSubjectHash !== 'string' || !/^[0-9a-f]{64}$/.test(profile.expectedSubjectHash) || typeof profile.configDir !== 'string' || !isAbsolute(profile.configDir) || typeof profile.command !== 'string' || !isAbsolute(profile.command)) throw new Error('invalid cloud account profile'); + const info = await lstat(profile.configDir); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(profile.configDir) !== profile.configDir) throw new Error('cloud profile must be private and canonical'); + let output; + try { output = await run(profile.command, ['auth', 'status', '--json'], { env: { ...process.env, CLAUDE_CONFIG_DIR: profile.configDir }, timeout: 10000, maxBuffer: 8192 }); } + catch { throw new Error('Claude account check unavailable'); } + let status; + try { status = JSON.parse(output.stdout); } catch { throw new Error('invalid Claude account response'); } + if (status.configDirectory !== profile.configDir || claudeSubjectHash(status) !== profile.expectedSubjectHash) throw new Error('Claude account scope mismatch'); + return { scope: profile.scope, subjectHash: profile.expectedSubjectHash }; +} + +// Check the same profile before and after an operation. A changed or unreadable +// profile after invocation leaves its result uncertain; callers must not resend. +export async function withClaudeAccount(profile, action, run = execute) { + const binding = await verifyClaudeAccount(profile, run); + let result; + try { result = await action({ scope: binding.scope, configDir: profile.configDir, command: profile.command }); } + catch { throw new Error('cloud operation outcome uncertain'); } + try { await verifyClaudeAccount(profile, run); } + catch { throw new Error('cloud operation outcome uncertain'); } + return result; +} diff --git a/packages/tmux-bridge/test/cloud-account-binding.test.mjs b/packages/tmux-bridge/test/cloud-account-binding.test.mjs new file mode 100644 index 00000000..82a407b3 --- /dev/null +++ b/packages/tmux-bridge/test/cloud-account-binding.test.mjs @@ -0,0 +1,48 @@ +import assert from 'node:assert/strict'; +import { chmod, mkdtemp, rm } from 'node:fs/promises'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; +import test from 'node:test'; +import { claudeSubjectHash, verifyClaudeAccount, withClaudeAccount } from '../bin/cloud-account-binding.mjs'; + +async function fixture(t) { + const root = await mkdtemp(join(tmpdir(), 'cloud-binding-')); + t.after(() => rm(root, { recursive: true, force: true })); + const status = { loggedIn: true, apiProvider: 'firstParty', authMethod: 'claude.ai', storedClaudeAiLogin: true, email: 'fixture@example.invalid', orgId: 'synthetic-org', configDirectory: root }; + const profile = { scope: 'fixture', configDir: root, command: '/synthetic/claude', expectedSubjectHash: claudeSubjectHash(status) }; + return { root, status, profile }; +} + +test('matching provider, profile and account produce only a bound digest', async t => { + const f = await fixture(t); + const run = async (command, args, options) => { + assert.equal(command, f.profile.command); assert.deepEqual(args, ['auth', 'status', '--json']); + assert.equal(options.env.CLAUDE_CONFIG_DIR, f.root); + return { stdout: JSON.stringify(f.status) }; + }; + const value = await verifyClaudeAccount(f.profile, run); + assert.deepEqual(value, { scope: 'fixture', subjectHash: f.profile.expectedSubjectHash }); + assert.ok(!JSON.stringify(value).includes(f.status.email)); + let invoked = false; + assert.equal(await withClaudeAccount(f.profile, async context => { invoked = true; assert.equal(context.configDir, f.root); return 'receipt'; }, run), 'receipt'); + assert.equal(invoked, true); +}); + +test('wrong account or profile fails before the action', async t => { + const f = await fixture(t); let invoked = false; + const run = async () => ({ stdout: JSON.stringify({ ...f.status, orgId: 'other' }) }); + await assert.rejects(withClaudeAccount(f.profile, async () => { invoked = true; }, run), /scope mismatch/); + assert.equal(invoked, false); + await assert.rejects(verifyClaudeAccount(f.profile, async () => ({ stdout: JSON.stringify({ ...f.status, configDirectory: '/other' }) })), /scope mismatch/); + await assert.rejects(verifyClaudeAccount(f.profile, async () => ({ stdout: JSON.stringify({ ...f.status, loggedIn: false }) })), /identity unavailable/); + await chmod(f.root, 0o755); + await assert.rejects(verifyClaudeAccount(f.profile, run), /private/); +}); + +test('account changes or transport errors after invocation stay uncertain', async t => { + const f = await fixture(t); let count = 0, actions = 0; + const run = async () => ({ stdout: JSON.stringify(++count === 1 ? f.status : { ...f.status, email: 'other@example.invalid' }) }); + await assert.rejects(withClaudeAccount(f.profile, async () => { actions++; return 'accepted'; }, run), /outcome uncertain/); + assert.equal(actions, 1); + await assert.rejects(withClaudeAccount(f.profile, async () => { throw new Error('transport'); }, async () => ({ stdout: JSON.stringify(f.status) })), /outcome uncertain/); +}); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 414487e8..c147772a 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -10,6 +10,7 @@ export const plexusDiagram = `flowchart LR 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"] StatePrep --> Journal diff --git a/skills/agent-tmux/bin/cloud-account-binding.mjs b/skills/agent-tmux/bin/cloud-account-binding.mjs new file mode 100644 index 00000000..513a18ea --- /dev/null +++ b/skills/agent-tmux/bin/cloud-account-binding.mjs @@ -0,0 +1,41 @@ +/** Bind an operator-selected Claude CLI profile to an account scope. */ +import { createHash } from 'node:crypto'; +import { execFile } from 'node:child_process'; +import { lstat, realpath } from 'node:fs/promises'; +import { isAbsolute } from 'node:path'; +import { promisify } from 'node:util'; + +const execute = promisify(execFile); +const SCOPE = /^[a-z][a-z0-9-]{0,63}$/; + +// Only a digest is returned. Raw identity and credentials are never returned +// or copied to a receipt; the operator must protect the configured profile. +export function claudeSubjectHash(status) { + if (!status || status.loggedIn !== true || status.apiProvider !== 'firstParty' || status.authMethod !== 'claude.ai' || status.storedClaudeAiLogin !== true || typeof status.email !== 'string' || !status.email.trim() || typeof status.orgId !== 'string' || !status.orgId.trim()) throw new Error('Claude account identity unavailable'); + return createHash('sha256').update(JSON.stringify([status.email.trim().toLowerCase(), status.orgId.trim()])).digest('hex'); +} + +export async function verifyClaudeAccount(profile, run = execute) { + if (!profile || typeof profile.scope !== 'string' || !SCOPE.test(profile.scope) || typeof profile.expectedSubjectHash !== 'string' || !/^[0-9a-f]{64}$/.test(profile.expectedSubjectHash) || typeof profile.configDir !== 'string' || !isAbsolute(profile.configDir) || typeof profile.command !== 'string' || !isAbsolute(profile.command)) throw new Error('invalid cloud account profile'); + const info = await lstat(profile.configDir); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(profile.configDir) !== profile.configDir) throw new Error('cloud profile must be private and canonical'); + let output; + try { output = await run(profile.command, ['auth', 'status', '--json'], { env: { ...process.env, CLAUDE_CONFIG_DIR: profile.configDir }, timeout: 10000, maxBuffer: 8192 }); } + catch { throw new Error('Claude account check unavailable'); } + let status; + try { status = JSON.parse(output.stdout); } catch { throw new Error('invalid Claude account response'); } + if (status.configDirectory !== profile.configDir || claudeSubjectHash(status) !== profile.expectedSubjectHash) throw new Error('Claude account scope mismatch'); + return { scope: profile.scope, subjectHash: profile.expectedSubjectHash }; +} + +// Check the same profile before and after an operation. A changed or unreadable +// profile after invocation leaves its result uncertain; callers must not resend. +export async function withClaudeAccount(profile, action, run = execute) { + const binding = await verifyClaudeAccount(profile, run); + let result; + try { result = await action({ scope: binding.scope, configDir: profile.configDir, command: profile.command }); } + catch { throw new Error('cloud operation outcome uncertain'); } + try { await verifyClaudeAccount(profile, run); } + catch { throw new Error('cloud operation outcome uncertain'); } + return result; +} From 9e2a72e1768ced9d8a6bd7d990f99773d50cf4c4 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:59:17 +0000 Subject: [PATCH 046/113] Record native queued wake evidence --- docs/design/plexus-architecture.mmd | 3 +- docs/design/plexus-modules.md | 14 +++ .../tmux-bridge/bin/codex-wake-evidence.mjs | 94 +++++++++++++++++++ .../test/codex-wake-evidence.test.mjs | 71 ++++++++++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-diagram.mjs | 3 +- skills/agent-tmux/bin/codex-wake-evidence.mjs | 94 +++++++++++++++++++ 7 files changed, 278 insertions(+), 2 deletions(-) create mode 100644 packages/tmux-bridge/bin/codex-wake-evidence.mjs create mode 100644 packages/tmux-bridge/test/codex-wake-evidence.test.mjs create mode 100644 skills/agent-tmux/bin/codex-wake-evidence.mjs diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index d7adacf3..20111842 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -4,7 +4,8 @@ flowchart LR Channel --> Session["Current session"] Queue --> Journal["Graph event journal"] Session --> Journal - Wake["Wake observation"] -. "planned producer" .-> 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 diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index 27bb07b7..db1cbaed 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -25,6 +25,20 @@ 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 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 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 diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs new file mode 100644 index 00000000..6d591dbd --- /dev/null +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -0,0 +1,94 @@ +#!/usr/bin/env node +/** Explicitly start one queued waker turn and record private native evidence. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { spawnSync } from 'node:child_process'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parseArgs } from 'node:util'; +import { withCodexAppServer } from './codex-app-server.mjs'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = value => createHash('sha256').update(value).digest('hex'); +const here = dirname(fileURLToPath(import.meta.url)); + +async function privateRoot(root) { + if (typeof root !== 'string' || !isAbsolute(root)) throw new Error('invalid evidence root'); + const info = await lstat(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('evidence root must be private and canonical'); +} + +async function createDurable(root, name, body) { + const fd = await open(join(root, name), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + try { await fd.writeFile(body); await fd.sync(); } finally { await fd.close(); } + const directory = await open(root, constants.O_RDONLY); + try { await directory.sync(); } finally { await directory.close(); } +} + +export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { + if (typeof reference !== 'string' || !/^codex-wake:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid wake verification request'); + await privateRoot(evidenceRoot); + const path = join(evidenceRoot, `wake-${reference.slice('codex-wake:'.length)}.json`), file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let body; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid wake evidence file'); + body = await file.readFile('utf8'); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('wake evidence changed'); + } finally { await file.close(); } + if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); + let value; + try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } + if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-wake-evidence.v1' || value.source !== 'codex-app-server.queue-start' || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + return { ...value, evidence: reference }; +} + +export async function publishCodexWake({ evidenceRoot, reference, session, graphState }) { + if (typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit graph state required'); + const proof = await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); + const observation = `codex-wake-${hash(JSON.stringify([session, proof.queueId]))}`; + const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'lifecycle', 'record', '--type', 'session.woken', '--session', session, '--id', observation, '--evidence', reference], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (result.error || result.status !== 0) throw new Error('graph recording failed; retain evidence for explicit publication'); + let receipt; try { receipt = JSON.parse(result.stdout); } catch { throw new Error('graph receipt unavailable'); } + if (receipt?.observation !== observation || typeof receipt.duplicate !== 'boolean') throw new Error('graph receipt mismatch'); + return { schema: 'agent-mesh.wake-record.v1', session, evidence: reference, duplicate: receipt.duplicate }; +} + +export async function startCodexWake({ thread, queueId, correlation, evidenceRoot, graphState, apply }) { + if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit wake identity, graph and apply required'); + await privateRoot(evidenceRoot); + await privateRoot(graphState); + thread = thread.toLowerCase(); + const session = `codex:${thread}`; + const result = await spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'show', '--json'], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); + let graph; try { graph = JSON.parse(result.stdout); } catch { throw new Error('graph unavailable'); } + const matches = Array.isArray(graph.nodes) ? graph.nodes.filter(node => node.agent === 'codex' && node.runtimeUuid === thread) : []; + if (result.error || result.status !== 0 || !graph.migrated || matches.length !== 1 || matches[0].status === 'closed' || matches[0].surface?.archived === true) throw new Error('wake session not registered or closed'); + const intent = hash(JSON.stringify([session, queueId])); + const evidence = await withCodexAppServer({ clientName: 'agent-mesh-wake-evidence', timeout: 30000, timeoutMessage: 'native wake outcome uncertain' }, async request => { + const listed = await request('thread/queue/list', { threadId: thread, limit: 100 }); + if (!Array.isArray(listed?.data) || listed.nextCursor != null || listed.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length !== 1) throw new Error('queued waker identity unavailable'); + await createDurable(evidenceRoot, `intent-${intent}.json`, `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`); + const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); + const turn = started?.turn; + if (!turn || typeof turn.id !== 'string' || !UUID.test(turn.id) || turn.status !== 'inProgress' || !Number.isSafeInteger(turn.startedAt) || turn.startedAt <= 0) throw new Error('native wake outcome uncertain'); + return { schema: 'agent-mesh.codex-wake-evidence.v1', source: 'codex-app-server.queue-start', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt }; + }); + const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; + await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); + return publishCodexWake({ evidenceRoot, reference, session, graphState }); +} + +if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { + try { + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + let result; + if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); + else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'] }); + else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + console.log(JSON.stringify(result)); + } catch { console.error('wake observation failed or outcome uncertain; inspect before retry'); process.exitCode = 1; } +} diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs new file mode 100644 index 00000000..3ad8f461 --- /dev/null +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -0,0 +1,71 @@ +import assert from 'node:assert/strict'; +import { execFile } from 'node:child_process'; +import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { promisify } from 'node:util'; +import test from 'node:test'; +import { verifyCodexWakeEvidence } from '../bin/codex-wake-evidence.mjs'; +import { createAppServer } from './fixtures/fake-app-server.mjs'; + +const exec = promisify(execFile); +const thread = '22222222-2222-4222-8222-222222222222'; +const turn = '33333333-3333-4333-8333-333333333333'; +const correlation = 'waker-44444444-4444-4444-8444-444444444444'; +const bin = fileURLToPath(new URL('../bin/codex-wake-evidence.mjs', import.meta.url)); +const graph = fileURLToPath(new URL('../bin/mesh-graph.mjs', import.meta.url)); + +test('queued wake needs explicit apply, a native start and durable correlated proof', async t => { + const root = await mkdtemp(join(tmpdir(), 'wake-evidence-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = join(root, 'graph'), evidence = join(root, 'evidence'), socket = join(root, 'fake.sock'); + await mkdir(state, { mode: 0o700 }); await mkdir(evidence, { mode: 0o700 }); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, '--state', state, ...args])).stdout); + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', thread, '--json'); + await call('migrate', '--apply', '--json'); + const cursor = (await call('query', 'changes', '--input', JSON.stringify({ initial: 'head' }))).cursor; + const requests = []; let mode = 'success'; + const server = createAppServer((request, peer) => { + if (!request.id) return; + requests.push(request); + if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: [{ id: 'queued-1', clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: 'fixture' }] }], nextCursor: null } }); + else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: 123456789, items: [] } } }); + else peer.send({ id: request.id, result: {} }); + }); + await new Promise(resolve => server.listen(socket, resolve)); + t.after(() => new Promise(resolve => server.close(resolve))); + const env = { ...process.env, CODEX_REMOTE_SOCK: socket, CODEX_NO_REMOTE: '' }; + const args = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--evidence-root', evidence, '--graph-state', state]; + await assert.rejects(exec(process.execPath, [bin, ...args], { env })); + assert.equal(requests.length, 0); + mode = 'wrong'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); + assert.deepEqual(await readdir(evidence), []); + mode = 'success'; + const first = JSON.parse((await exec(process.execPath, [bin, '--apply', ...args], { env })).stdout); + assert.equal(first.duplicate, false); + const verified = await verifyCodexWakeEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }); + assert.equal(verified.turn, turn); + assert.equal(verified.correlation, correlation); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 1); + await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 1); + const again = JSON.parse((await exec(process.execPath, [bin, '--publish', first.evidence, '--session', `codex:${thread}`, '--evidence-root', evidence, '--graph-state', state], { env })).stdout); + assert.equal(again.duplicate, true); + const feed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.deepEqual(feed.events.filter(e => e.type === 'session.woken').map(e => e.evidence), [first.evidence]); + const uncertainRoot = join(root, 'uncertain'); await mkdir(uncertainRoot, { mode: 0o700 }); + const uncertainArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--evidence-root', uncertainRoot, '--graph-state', state]; + mode = 'uncertain'; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...uncertainArgs], { env })); + assert.deepEqual((await readdir(uncertainRoot)).map(name => name.split('-')[0]), ['intent']); + const starts = requests.filter(r => r.method === 'thread/queue/start').length; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...uncertainArgs], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, starts); + const uncertainFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.equal(uncertainFeed.events.filter(e => e.type === 'session.woken').length, 1); + const file = join(evidence, `wake-${first.evidence.slice('codex-wake:'.length)}.json`); + const saved = JSON.parse(await readFile(file, 'utf8')); saved.startedAt++; + await writeFile(file, `${JSON.stringify(saved)}\n`); + await assert.rejects(verifyCodexWakeEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }), /digest/); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index 2e9589b8..a93839eb 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -48,6 +48,7 @@ const agentTmuxBundleFiles = [ "bin/handover-notice.mjs", "bin/handover-codex-observation.mjs", "bin/codex-compaction-evidence.mjs", + "bin/codex-wake-evidence.mjs", "bin/restart-state.mjs", "bin/restart-yaml.py", "bin/ledger-view.mjs", diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index c147772a..2042a79f 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -5,7 +5,8 @@ export const plexusDiagram = `flowchart LR Channel --> Session["Current session"] Queue --> Journal["Graph event journal"] Session --> Journal - Wake["Wake observation"] -. "planned producer" .-> 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 diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs new file mode 100644 index 00000000..6d591dbd --- /dev/null +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -0,0 +1,94 @@ +#!/usr/bin/env node +/** Explicitly start one queued waker turn and record private native evidence. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { spawnSync } from 'node:child_process'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parseArgs } from 'node:util'; +import { withCodexAppServer } from './codex-app-server.mjs'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = value => createHash('sha256').update(value).digest('hex'); +const here = dirname(fileURLToPath(import.meta.url)); + +async function privateRoot(root) { + if (typeof root !== 'string' || !isAbsolute(root)) throw new Error('invalid evidence root'); + const info = await lstat(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('evidence root must be private and canonical'); +} + +async function createDurable(root, name, body) { + const fd = await open(join(root, name), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + try { await fd.writeFile(body); await fd.sync(); } finally { await fd.close(); } + const directory = await open(root, constants.O_RDONLY); + try { await directory.sync(); } finally { await directory.close(); } +} + +export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { + if (typeof reference !== 'string' || !/^codex-wake:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid wake verification request'); + await privateRoot(evidenceRoot); + const path = join(evidenceRoot, `wake-${reference.slice('codex-wake:'.length)}.json`), file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let body; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid wake evidence file'); + body = await file.readFile('utf8'); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('wake evidence changed'); + } finally { await file.close(); } + if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); + let value; + try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } + if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-wake-evidence.v1' || value.source !== 'codex-app-server.queue-start' || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + return { ...value, evidence: reference }; +} + +export async function publishCodexWake({ evidenceRoot, reference, session, graphState }) { + if (typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit graph state required'); + const proof = await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); + const observation = `codex-wake-${hash(JSON.stringify([session, proof.queueId]))}`; + const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'lifecycle', 'record', '--type', 'session.woken', '--session', session, '--id', observation, '--evidence', reference], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (result.error || result.status !== 0) throw new Error('graph recording failed; retain evidence for explicit publication'); + let receipt; try { receipt = JSON.parse(result.stdout); } catch { throw new Error('graph receipt unavailable'); } + if (receipt?.observation !== observation || typeof receipt.duplicate !== 'boolean') throw new Error('graph receipt mismatch'); + return { schema: 'agent-mesh.wake-record.v1', session, evidence: reference, duplicate: receipt.duplicate }; +} + +export async function startCodexWake({ thread, queueId, correlation, evidenceRoot, graphState, apply }) { + if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit wake identity, graph and apply required'); + await privateRoot(evidenceRoot); + await privateRoot(graphState); + thread = thread.toLowerCase(); + const session = `codex:${thread}`; + const result = await spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'show', '--json'], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); + let graph; try { graph = JSON.parse(result.stdout); } catch { throw new Error('graph unavailable'); } + const matches = Array.isArray(graph.nodes) ? graph.nodes.filter(node => node.agent === 'codex' && node.runtimeUuid === thread) : []; + if (result.error || result.status !== 0 || !graph.migrated || matches.length !== 1 || matches[0].status === 'closed' || matches[0].surface?.archived === true) throw new Error('wake session not registered or closed'); + const intent = hash(JSON.stringify([session, queueId])); + const evidence = await withCodexAppServer({ clientName: 'agent-mesh-wake-evidence', timeout: 30000, timeoutMessage: 'native wake outcome uncertain' }, async request => { + const listed = await request('thread/queue/list', { threadId: thread, limit: 100 }); + if (!Array.isArray(listed?.data) || listed.nextCursor != null || listed.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length !== 1) throw new Error('queued waker identity unavailable'); + await createDurable(evidenceRoot, `intent-${intent}.json`, `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`); + const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); + const turn = started?.turn; + if (!turn || typeof turn.id !== 'string' || !UUID.test(turn.id) || turn.status !== 'inProgress' || !Number.isSafeInteger(turn.startedAt) || turn.startedAt <= 0) throw new Error('native wake outcome uncertain'); + return { schema: 'agent-mesh.codex-wake-evidence.v1', source: 'codex-app-server.queue-start', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt }; + }); + const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; + await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); + return publishCodexWake({ evidenceRoot, reference, session, graphState }); +} + +if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { + try { + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + let result; + if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); + else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'] }); + else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + console.log(JSON.stringify(result)); + } catch { console.error('wake observation failed or outcome uncertain; inspect before retry'); process.exitCode = 1; } +} From e33286f90f2d868968e0ba8aee97bb510636fb1c Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:04:16 +0000 Subject: [PATCH 047/113] Require correlated native wake readback --- docs/design/plexus-modules.md | 2 ++ packages/tmux-bridge/bin/codex-wake-evidence.mjs | 11 +++++++++-- .../tmux-bridge/test/codex-wake-evidence.test.mjs | 8 ++++++++ skills/agent-tmux/bin/codex-wake-evidence.mjs | 11 +++++++++-- 4 files changed, 28 insertions(+), 4 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index db1cbaed..ead4e307 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -27,6 +27,8 @@ 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, diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index 6d591dbd..0f16f166 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -42,7 +42,7 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); let value; try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } - if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-wake-evidence.v1' || value.source !== 'codex-app-server.queue-start' || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-wake-evidence.v2' || value.source !== 'codex-app-server.queue-start-readback' || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } @@ -75,7 +75,14 @@ export async function startCodexWake({ thread, queueId, correlation, evidenceRoo const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); const turn = started?.turn; if (!turn || typeof turn.id !== 'string' || !UUID.test(turn.id) || turn.status !== 'inProgress' || !Number.isSafeInteger(turn.startedAt) || turn.startedAt <= 0) throw new Error('native wake outcome uncertain'); - return { schema: 'agent-mesh.codex-wake-evidence.v1', source: 'codex-app-server.queue-start', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt }; + const readback = await request('thread/read', { threadId: thread, includeTurns: true }); + const observed = readback?.thread; + const turns = Array.isArray(observed?.turns) ? observed.turns.filter(item => item?.id === turn.id) : []; + const observedTurn = turns[0]; + const messages = Array.isArray(observedTurn?.items) ? observedTurn.items.filter(item => item?.type === 'userMessage' && item.clientId === correlation) : []; + const queued = listed.data.find(item => item?.id === queueId && item.clientUserMessageId === correlation); + if (observed?.id !== thread || turns.length !== 1 || (observedTurn.itemsView !== undefined && observedTurn.itemsView !== 'full') || observedTurn.startedAt !== turn.startedAt || messages.length !== 1 || !Array.isArray(messages[0].content) || JSON.stringify(messages[0].content) !== JSON.stringify(queued.input)) throw new Error('wake readback unavailable; outcome uncertain'); + return { schema: 'agent-mesh.codex-wake-evidence.v2', source: 'codex-app-server.queue-start-readback', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt }; }); const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 3ad8f461..42d59a5b 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -31,6 +31,7 @@ test('queued wake needs explicit apply, a native start and durable correlated pr requests.push(request); if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: [{ id: 'queued-1', clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: 'fixture' }] }], nextCursor: null } }); else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: 123456789, items: [] } } }); + else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: thread, turns: [{ id: turn, startedAt: 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', clientId: correlation, content: [{ type: 'text', text: 'fixture' }] }] }] } } }); else peer.send({ id: request.id, result: {} }); }); await new Promise(resolve => server.listen(socket, resolve)); @@ -64,6 +65,13 @@ test('queued wake needs explicit apply, a native start and durable correlated pr assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, starts); const uncertainFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); assert.equal(uncertainFeed.events.filter(e => e.type === 'session.woken').length, 1); + const partialRoot = join(root, 'partial'); await mkdir(partialRoot, { mode: 0o700 }); + const partialArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--evidence-root', partialRoot, '--graph-state', state]; + mode = 'partial'; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...partialArgs], { env })); + assert.deepEqual((await readdir(partialRoot)).map(name => name.split('-')[0]), ['intent']); + const partialFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.equal(partialFeed.events.filter(e => e.type === 'session.woken').length, 1); const file = join(evidence, `wake-${first.evidence.slice('codex-wake:'.length)}.json`); const saved = JSON.parse(await readFile(file, 'utf8')); saved.startedAt++; await writeFile(file, `${JSON.stringify(saved)}\n`); diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index 6d591dbd..0f16f166 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -42,7 +42,7 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); let value; try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } - if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-wake-evidence.v1' || value.source !== 'codex-app-server.queue-start' || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-wake-evidence.v2' || value.source !== 'codex-app-server.queue-start-readback' || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } @@ -75,7 +75,14 @@ export async function startCodexWake({ thread, queueId, correlation, evidenceRoo const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); const turn = started?.turn; if (!turn || typeof turn.id !== 'string' || !UUID.test(turn.id) || turn.status !== 'inProgress' || !Number.isSafeInteger(turn.startedAt) || turn.startedAt <= 0) throw new Error('native wake outcome uncertain'); - return { schema: 'agent-mesh.codex-wake-evidence.v1', source: 'codex-app-server.queue-start', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt }; + const readback = await request('thread/read', { threadId: thread, includeTurns: true }); + const observed = readback?.thread; + const turns = Array.isArray(observed?.turns) ? observed.turns.filter(item => item?.id === turn.id) : []; + const observedTurn = turns[0]; + const messages = Array.isArray(observedTurn?.items) ? observedTurn.items.filter(item => item?.type === 'userMessage' && item.clientId === correlation) : []; + const queued = listed.data.find(item => item?.id === queueId && item.clientUserMessageId === correlation); + if (observed?.id !== thread || turns.length !== 1 || (observedTurn.itemsView !== undefined && observedTurn.itemsView !== 'full') || observedTurn.startedAt !== turn.startedAt || messages.length !== 1 || !Array.isArray(messages[0].content) || JSON.stringify(messages[0].content) !== JSON.stringify(queued.input)) throw new Error('wake readback unavailable; outcome uncertain'); + return { schema: 'agent-mesh.codex-wake-evidence.v2', source: 'codex-app-server.queue-start-readback', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt }; }); const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); From e724013f2062e98f6c46f3616d76b75c8ebcf277 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:08:36 +0000 Subject: [PATCH 048/113] Test wake readback identity mismatches --- .../tmux-bridge/test/codex-wake-evidence.test.mjs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 42d59a5b..6a08ead4 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -31,7 +31,7 @@ test('queued wake needs explicit apply, a native start and durable correlated pr requests.push(request); if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: [{ id: 'queued-1', clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: 'fixture' }] }], nextCursor: null } }); else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: 123456789, items: [] } } }); - else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: thread, turns: [{ id: turn, startedAt: 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', clientId: correlation, content: [{ type: 'text', text: 'fixture' }] }] }] } } }); + else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, startedAt: mode === 'wrong-time' ? 123456788 : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture' }] }] }] } } }); else peer.send({ id: request.id, result: {} }); }); await new Promise(resolve => server.listen(socket, resolve)); @@ -72,6 +72,15 @@ test('queued wake needs explicit apply, a native start and durable correlated pr assert.deepEqual((await readdir(partialRoot)).map(name => name.split('-')[0]), ['intent']); const partialFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); assert.equal(partialFeed.events.filter(e => e.type === 'session.woken').length, 1); + for (const mismatch of ['wrong-thread', 'wrong-turn', 'wrong-time', 'wrong-client', 'wrong-input']) { + const mismatchRoot = join(root, mismatch); await mkdir(mismatchRoot, { mode: 0o700 }); + const mismatchArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--evidence-root', mismatchRoot, '--graph-state', state]; + mode = mismatch; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...mismatchArgs], { env })); + assert.deepEqual((await readdir(mismatchRoot)).map(name => name.split('-')[0]), ['intent']); + } + const mismatchFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.equal(mismatchFeed.events.filter(e => e.type === 'session.woken').length, 1); const file = join(evidence, `wake-${first.evidence.slice('codex-wake:'.length)}.json`); const saved = JSON.parse(await readFile(file, 'utf8')); saved.startedAt++; await writeFile(file, `${JSON.stringify(saved)}\n`); From d05585f89e285cec087e03af364ef2f0e69163ac Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:12:18 +0000 Subject: [PATCH 049/113] Expose correlated native queue identity --- docs/design/plexus-modules.md | 3 +++ packages/tmux-bridge/bin/agent-native-call.mjs | 5 ++++- .../tmux-bridge/test/native-private-queue.test.mjs | 10 +++++++++- skills/agent-tmux/bin/agent-native-call.mjs | 5 ++++- 4 files changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index ead4e307..a3ced56d 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -40,6 +40,9 @@ 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. This is queue acceptance only; +the waker does not yet persist the id or invoke the wake-evidence adapter. 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 diff --git a/packages/tmux-bridge/bin/agent-native-call.mjs b/packages/tmux-bridge/bin/agent-native-call.mjs index d851b03c..ef5e2ea2 100755 --- a/packages/tmux-bridge/bin/agent-native-call.mjs +++ b/packages/tmux-bridge/bin/agent-native-call.mjs @@ -128,6 +128,7 @@ let resumeDiagnostic = false; let transportAccepted = false; let deliveryMethod; let steeredTurnId; +let nativeQueueId; try { if (agent === "codex") { if (values["steer-or-queue"]) { @@ -161,7 +162,8 @@ if (agent === "codex") { const input = [{ type: "text", text: protocolMessage, text_elements: [] }]; const response = await request("thread/queue/add", { threadId: sessionId, clientUserMessageId: correlationId, input }); const entry = response?.queuedSubmission; - if (typeof entry?.id !== "string" || !entry.id || entry.clientUserMessageId !== correlationId || JSON.stringify(entry.input) !== JSON.stringify(input)) throw new Error("queue receipt mismatch"); + if (typeof entry?.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(entry.id) || entry.clientUserMessageId !== correlationId || JSON.stringify(entry.input) !== JSON.stringify(input)) throw new Error("queue receipt mismatch"); + nativeQueueId = entry.id; if (resume) { try { await request("thread/resume", { threadId: sessionId }); } catch { resumeDiagnostic = true; } @@ -207,6 +209,7 @@ const goal = goalOptions ? await applyGoal(agent, sessionId, goalOptions) : unde // Queue acknowledgement is transport proof, never proof that the turn ran. if (values["delivery-only"]) { console.log(JSON.stringify({ status: deliveryMethod === "steer" ? "steered" : "queued", agent, sessionId, correlationId, + ...(nativeQueueId ? { nativeQueueId } : {}), ...(values["steer-or-queue"] ? { deliveryMethod, ...(steeredTurnId ? { turnId: steeredTurnId } : {}) } : {}), ...(goal ? { goal } : {}), ...(resume && deliveryMethod === "queue" ? { resumeRequested: true, resumeVerified: false, resumeDiagnostic } : {}) })); diff --git a/packages/tmux-bridge/test/native-private-queue.test.mjs b/packages/tmux-bridge/test/native-private-queue.test.mjs index ead33b6f..273547c2 100644 --- a/packages/tmux-bridge/test/native-private-queue.test.mjs +++ b/packages/tmux-bridge/test/native-private-queue.test.mjs @@ -39,6 +39,14 @@ for (const badReceipt of [false, true]) { assert.equal(seen[0].params.clientUserMessageId, 'fixture-1'); assert.ok(!stderr.includes('private fixture')); if (badReceipt) { assert.notEqual(code, 0); assert.match(stderr, /uncertain/); } - else { assert.equal(code, 0, stderr); assert.equal(JSON.parse(stdout).status, 'queued'); } + else { + assert.equal(code, 0, stderr); + const receipt = JSON.parse(stdout); + assert.equal(receipt.status, 'queued'); + assert.equal(receipt.nativeQueueId, 'queue-1'); + assert.equal(receipt.sessionId, session); + assert.equal(receipt.correlationId, 'fixture-1'); + assert.ok(!stdout.includes('private fixture')); + } }); } diff --git a/skills/agent-tmux/bin/agent-native-call.mjs b/skills/agent-tmux/bin/agent-native-call.mjs index d851b03c..ef5e2ea2 100755 --- a/skills/agent-tmux/bin/agent-native-call.mjs +++ b/skills/agent-tmux/bin/agent-native-call.mjs @@ -128,6 +128,7 @@ let resumeDiagnostic = false; let transportAccepted = false; let deliveryMethod; let steeredTurnId; +let nativeQueueId; try { if (agent === "codex") { if (values["steer-or-queue"]) { @@ -161,7 +162,8 @@ if (agent === "codex") { const input = [{ type: "text", text: protocolMessage, text_elements: [] }]; const response = await request("thread/queue/add", { threadId: sessionId, clientUserMessageId: correlationId, input }); const entry = response?.queuedSubmission; - if (typeof entry?.id !== "string" || !entry.id || entry.clientUserMessageId !== correlationId || JSON.stringify(entry.input) !== JSON.stringify(input)) throw new Error("queue receipt mismatch"); + if (typeof entry?.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(entry.id) || entry.clientUserMessageId !== correlationId || JSON.stringify(entry.input) !== JSON.stringify(input)) throw new Error("queue receipt mismatch"); + nativeQueueId = entry.id; if (resume) { try { await request("thread/resume", { threadId: sessionId }); } catch { resumeDiagnostic = true; } @@ -207,6 +209,7 @@ const goal = goalOptions ? await applyGoal(agent, sessionId, goalOptions) : unde // Queue acknowledgement is transport proof, never proof that the turn ran. if (values["delivery-only"]) { console.log(JSON.stringify({ status: deliveryMethod === "steer" ? "steered" : "queued", agent, sessionId, correlationId, + ...(nativeQueueId ? { nativeQueueId } : {}), ...(values["steer-or-queue"] ? { deliveryMethod, ...(steeredTurnId ? { turnId: steeredTurnId } : {}) } : {}), ...(goal ? { goal } : {}), ...(resume && deliveryMethod === "queue" ? { resumeRequested: true, resumeVerified: false, resumeDiagnostic } : {}) })); From 3fc091aa73ba8e1a66011e40b4d8aaae84fa753f Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:17:24 +0000 Subject: [PATCH 050/113] Preserve bound queue identity in channel journal --- docs/design/plexus-modules.md | 6 ++++-- packages/tmux-bridge/bin/agent-waker.py | 13 +++++++++++-- packages/tmux-bridge/bin/channel-state.mjs | 4 ++++ .../test/agent-waker-channel.test.py | 17 +++++++++++++---- .../tmux-bridge/test/channel-state.test.mjs | 13 +++++++++++++ .../tmux-bridge/test/plexus-privacy.test.mjs | 1 + scripts/plexus-privacy.mjs | 2 +- skills/agent-tmux/bin/agent-waker.py | 13 +++++++++++-- skills/agent-tmux/bin/channel-state.mjs | 4 ++++ 9 files changed, 62 insertions(+), 11 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index a3ced56d..7ea80ac9 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -41,8 +41,10 @@ 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. This is queue acceptance only; -the waker does not yet persist the id or invoke the wake-evidence adapter. +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. 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 diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index 96d968f7..a66df950 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -11,6 +11,7 @@ import hashlib import json import os +import re from pathlib import Path import subprocess import sys @@ -116,7 +117,7 @@ def compose(job: str, pending: list[dict[str, Any]], errors: list[Any]) -> str: return "\n".join(lines) -def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False) -> int: +def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False, receipt_out: dict | None = None) -> int: command = ["node", str(BIN / "agent-native-call.mjs"), "--agent", agent, "--session", session, "--correlation-id", correlation, "--timeout", "5"] command += ["--message-stdin"] if message_stdin else ["--message", message] @@ -152,6 +153,12 @@ def deliver(agent: str, session: str, correlation: str, message: str, inbox_root return 78 if delivery_only and (not isinstance(receipt, dict) or receipt.get("status") != "queued"): return 78 + if delivery_only and receipt_out is not None and result.returncode == 0 and bound: + native_id = receipt.get('nativeQueueId') + if native_id is not None: + if agent != 'codex' or not isinstance(native_id, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', native_id): + return 78 + receipt_out['nativeQueueId'] = native_id return result.returncode @@ -246,12 +253,14 @@ def run_channel(args: argparse.Namespace) -> int: agent, sep, session = item['session'].partition(':') if not sep or agent not in ('codex', 'claude') or item['session'] != target or item['generation'] != generation: raise ValueError('unsupported channel recipient') + transport_receipt = {} code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, - True, resume=args.resume and agent == 'codex', message_stdin=True) + True, resume=args.resume and agent == 'codex', message_stdin=True, receipt_out=transport_receipt) if code != 0: print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'delivery unconfirmed'})) return 3 receipt = {'status': 'accepted', 'messageId': item['id'], 'session': item['session'], 'generation': item['generation']} + receipt.update(transport_receipt) channel_call(args, 'acknowledge', '--id', item['id'], '--input', json.dumps(receipt, separators=(',', ':'))) print(json.dumps({'job': args.job, 'outcome': 'acted', 'correlationId': item['id']})) return 0 diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 3f93ae6a..21d798c0 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -37,6 +37,10 @@ export function beginDelivery(state, id, expectedSession, expectedGeneration) { export function acknowledge(state, id, receipt) { const next = copy(state), item = next.queue.find((row) => row.id === id); if (!item || item.state !== 'inflight' || !receipt || receipt.status !== 'accepted' || receipt.messageId !== id || receipt.session !== item.session || receipt.generation !== item.generation) throw new Error('unverified delivery receipt'); + if (receipt.nativeQueueId !== undefined) { + if (!item.session.startsWith('codex:') || !identifier(receipt.nativeQueueId)) throw new Error('invalid native queue receipt'); + item.nativeQueueId = receipt.nativeQueueId; + } item.state = 'accepted'; return next; } diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index a2576b86..7d7223c2 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -31,9 +31,11 @@ def call(args, operation, *options): def test_native_adapter_receives_message_on_stdin(self): from unittest.mock import Mock - receipt = {'status': 'queued', 'agent': 'codex', 'sessionId': uuid, 'correlationId': 'message-1'} + receipt = {'status': 'queued', 'agent': 'codex', 'sessionId': uuid, 'correlationId': 'message-1', 'nativeQueueId': 'queue-1'} + output = {} with patch.object(waker.subprocess, 'run', return_value=Mock(returncode=0, stdout=json.dumps(receipt))) as run: - self.assertEqual(waker.deliver('codex', uuid, 'message-1', 'private fixture', None, True, message_stdin=True), 0) + self.assertEqual(waker.deliver('codex', uuid, 'message-1', 'private fixture', None, True, message_stdin=True, receipt_out=output), 0) + self.assertEqual(output, {'nativeQueueId': 'queue-1'}) self.assertNotIn('private fixture', run.call_args.args[0]) self.assertIn('--message-stdin', run.call_args.args[0]) self.assertIn('--no-resume', run.call_args.args[0]) @@ -122,12 +124,19 @@ def call(*args): call('migrate', '--apply', '--json') call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) - with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'channel_call', wraps=waker.channel_call) as channel_call, patch.object(waker, 'deliver', return_value=0) as deliver, contextlib.redirect_stdout(io.StringIO()): + def accepted(*args, **kwargs): + kwargs['receipt_out']['nativeQueueId'] = 'queue-1' + return 0 + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'channel_call', wraps=waker.channel_call) as channel_call, patch.object(waker, 'deliver', side_effect=accepted) as deliver, contextlib.redirect_stdout(io.StringIO()): self.assertEqual(waker.run(args), 0) self.assertEqual(deliver.call_args.args[0:2], ('codex', uuid)) reservation = next(call.args for call in channel_call.call_args_list if call.args[1] == 'begin-delivery') self.assertEqual(reservation[-2:], ('--generation', '1')) - self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'accepted') + item = call('channel', 'get', '--name', 'example')['channel']['queue'][0] + self.assertEqual(item['state'], 'accepted') + self.assertEqual(item['nativeQueueId'], 'queue-1') + self.assertEqual(item['session'], f'codex:{uuid}') + self.assertEqual(item['generation'], 1) with patch.object(waker, 'run_producer', return_value=([{'event': 'two'}], [])), patch.object(waker, 'deliver', return_value=78) as deliver, contextlib.redirect_stdout(io.StringIO()): self.assertEqual(waker.run(args), 3) self.assertEqual(waker.run(args), 3) diff --git a/packages/tmux-bridge/test/channel-state.test.mjs b/packages/tmux-bridge/test/channel-state.test.mjs index e7479e13..664610e6 100644 --- a/packages/tmux-bridge/test/channel-state.test.mjs +++ b/packages/tmux-bridge/test/channel-state.test.mjs @@ -2,6 +2,19 @@ import assert from 'node:assert/strict'; import test from 'node:test'; import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, finishHandover, reserveStatePreparation, completeStatePreparation } from '../bin/channel-state.mjs'; +test('native queue identity is scoped to its accepted Codex delivery', () => { + const session = 'codex:22222222-2222-4222-8222-222222222222'; + let channel = createChannel('example', session); + channel = beginDelivery(enqueue(channel, 'message-1', 'fixture'), 'message-1', session, 1); + const receipt = { status: 'accepted', messageId: 'message-1', session, generation: 1, nativeQueueId: 'queue-1' }; + assert.throws(() => acknowledge(channel, 'message-1', { ...receipt, nativeQueueId: '../unsafe' }), /queue receipt/); + assert.throws(() => acknowledge(channel, 'message-1', { ...receipt, generation: 2 }), /receipt/); + assert.equal(acknowledge(channel, 'message-1', receipt).queue[0].nativeQueueId, 'queue-1'); + let other = createChannel('other', 'claude:22222222-2222-4222-8222-222222222222'); + other = beginDelivery(enqueue(other, 'message-1', 'fixture'), 'message-1', other.session, 1); + assert.throws(() => acknowledge(other, 'message-1', { ...receipt, session: other.session }), /queue receipt/); +}); + test('state preparation reserves once and binds proof to the channel generation', () => { let channel = beginHandover(createChannel('example', 'codex:old')); channel = reserveStatePreparation(channel, 'handover-1'); diff --git a/packages/tmux-bridge/test/plexus-privacy.test.mjs b/packages/tmux-bridge/test/plexus-privacy.test.mjs index 552c9850..e6ad027a 100644 --- a/packages/tmux-bridge/test/plexus-privacy.test.mjs +++ b/packages/tmux-bridge/test/plexus-privacy.test.mjs @@ -17,6 +17,7 @@ test('Plexus public mechanism paths and private references are classified', () = assert.equal(isPlexusMechanismFile('packages/tmux-bridge/bin/codex-compaction-evidence.mjs'), true); assert.equal(isPlexusMechanismFile('packages/tmux-bridge/test/codex-compaction-evidence.test.mjs'), true); assert.equal(isPlexusMechanismFile('skills/agent-tmux/bin/codex-compaction-evidence.mjs'), true); + for (const path of ['packages/tmux-bridge/bin/codex-wake-evidence.mjs', 'packages/tmux-bridge/test/codex-wake-evidence.test.mjs', 'skills/agent-tmux/bin/codex-wake-evidence.mjs']) assert.equal(isPlexusMechanismFile(path), true, path); assert.equal(isPlexusMechanismFile('packages/tmux-bridge/bin/restart-state.mjs'), true); assert.equal(isPlexusMechanismFile('packages/tmux-bridge/test/restart-state.test.mjs'), true); assert.equal(isPlexusMechanismFile('skills/agent-tmux/bin/restart-state.mjs'), true); diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs index ddbc134f..95c26189 100644 --- a/scripts/plexus-privacy.mjs +++ b/scripts/plexus-privacy.mjs @@ -6,7 +6,7 @@ const privatePatterns = [ ]; export function isPlexusMechanismFile(relativePath) { - return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|codex-compaction-|module-batches|mesh-(?:graph|channel)|agent-waker|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); + return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|codex-(?:compaction|wake)-|module-batches|mesh-(?:graph|channel)|agent-waker|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); } export function containsPrivatePlexusPolicy(text) { diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index 96d968f7..a66df950 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -11,6 +11,7 @@ import hashlib import json import os +import re from pathlib import Path import subprocess import sys @@ -116,7 +117,7 @@ def compose(job: str, pending: list[dict[str, Any]], errors: list[Any]) -> str: return "\n".join(lines) -def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False) -> int: +def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False, receipt_out: dict | None = None) -> int: command = ["node", str(BIN / "agent-native-call.mjs"), "--agent", agent, "--session", session, "--correlation-id", correlation, "--timeout", "5"] command += ["--message-stdin"] if message_stdin else ["--message", message] @@ -152,6 +153,12 @@ def deliver(agent: str, session: str, correlation: str, message: str, inbox_root return 78 if delivery_only and (not isinstance(receipt, dict) or receipt.get("status") != "queued"): return 78 + if delivery_only and receipt_out is not None and result.returncode == 0 and bound: + native_id = receipt.get('nativeQueueId') + if native_id is not None: + if agent != 'codex' or not isinstance(native_id, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', native_id): + return 78 + receipt_out['nativeQueueId'] = native_id return result.returncode @@ -246,12 +253,14 @@ def run_channel(args: argparse.Namespace) -> int: agent, sep, session = item['session'].partition(':') if not sep or agent not in ('codex', 'claude') or item['session'] != target or item['generation'] != generation: raise ValueError('unsupported channel recipient') + transport_receipt = {} code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, - True, resume=args.resume and agent == 'codex', message_stdin=True) + True, resume=args.resume and agent == 'codex', message_stdin=True, receipt_out=transport_receipt) if code != 0: print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'delivery unconfirmed'})) return 3 receipt = {'status': 'accepted', 'messageId': item['id'], 'session': item['session'], 'generation': item['generation']} + receipt.update(transport_receipt) channel_call(args, 'acknowledge', '--id', item['id'], '--input', json.dumps(receipt, separators=(',', ':'))) print(json.dumps({'job': args.job, 'outcome': 'acted', 'correlationId': item['id']})) return 0 diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 3f93ae6a..21d798c0 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -37,6 +37,10 @@ export function beginDelivery(state, id, expectedSession, expectedGeneration) { export function acknowledge(state, id, receipt) { const next = copy(state), item = next.queue.find((row) => row.id === id); if (!item || item.state !== 'inflight' || !receipt || receipt.status !== 'accepted' || receipt.messageId !== id || receipt.session !== item.session || receipt.generation !== item.generation) throw new Error('unverified delivery receipt'); + if (receipt.nativeQueueId !== undefined) { + if (!item.session.startsWith('codex:') || !identifier(receipt.nativeQueueId)) throw new Error('invalid native queue receipt'); + item.nativeQueueId = receipt.nativeQueueId; + } item.state = 'accepted'; return next; } From d2cb10aee0bdbc53dae2a4f6200d1a1d659a1591 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:21:47 +0000 Subject: [PATCH 051/113] Reserve wake identity before channel handover --- docs/design/plexus-modules.md | 5 ++++ packages/tmux-bridge/bin/channel-state.mjs | 11 +++++++++ packages/tmux-bridge/bin/mesh-graph.mjs | 8 +++++-- .../test/agent-waker-channel.test.py | 23 +++++++++++++++++++ .../tmux-bridge/test/channel-state.test.mjs | 15 +++++++++++- skills/agent-tmux/bin/channel-state.mjs | 11 +++++++++ skills/agent-tmux/bin/mesh-graph.mjs | 8 +++++-- 7 files changed, 76 insertions(+), 5 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index 7ea80ac9..d38ccdc1 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -45,6 +45,11 @@ 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 experimental wake adapter does not +yet acquire or settle this reservation, and no recovery operation exists, so +the reservation interface 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 diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 21d798c0..7f323511 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -47,12 +47,23 @@ export function acknowledge(state, id, receipt) { export function beginHandover(state) { if (state.phase !== 'active') throw new Error('handover already in progress'); + if (state.wakeReservation) throw new Error('wake reservation unresolved'); const next = copy(state); next.phase = 'handover'; delete next.statePreparation; return next; } +// A reservation is durable and has no expiry: a crashed native call is unknown. +export function reserveWake(state, id, session, generation, nativeQueueId) { + if (state.phase !== 'active' || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); + const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); + if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); + const next = copy(state); + next.wakeReservation = { id, session, generation, nativeQueueId }; + return next; +} + // A reserved request is intentionally not retried automatically after a crash. export function reserveStatePreparation(state, id) { if (state.phase !== 'handover' || state.statePreparation || !identifier(id)) throw new Error('state preparation unavailable or unresolved'); diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index c7585cba..338bbbdb 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -37,7 +37,7 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; @@ -129,7 +129,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -193,6 +193,10 @@ try { next = beginDelivery(current, requiredSingleLine(values.id, "--id"), values.session === undefined ? undefined : requiredSingleLine(values.session, "--session"), values.generation === undefined ? undefined : Number(values.generation)); } else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); + else if (subcommand === "reserve-wake") { + if (!/^[1-9][0-9]*$/.test(values.generation || "")) throw new Error("invalid channel generation"); + next = reserveWake(current, requiredSingleLine(values.id, "--id"), requiredSingleLine(values.session, "--session"), Number(values.generation), requiredSingleLine(channelInput, "--input")); + } else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "finish-handover") { const target = requiredSingleLine(values.to, "--to"); diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index 7d7223c2..031e5be6 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -17,6 +17,29 @@ class ChannelWakerTest(unittest.TestCase): + def test_wake_reservation_survives_reload_and_blocks_handover(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'graph' + def call(*args): + return subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], capture_output=True, text=True) + def ok(*args): + result = call(*args) + self.assertEqual(result.returncode, 0, result.stderr) + return json.loads(result.stdout) + session = f'codex:{uuid}' + ok('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + ok('migrate', '--apply', '--json') + ok('channel', 'create', '--name', 'example', '--session', session) + ok('channel', 'enqueue', '--name', 'example', '--id', 'message-1', '--input', 'fixture') + ok('channel', 'begin-delivery', '--name', 'example', '--id', 'message-1', '--session', session, '--generation', '1') + receipt = {'status': 'accepted', 'messageId': 'message-1', 'session': session, 'generation': 1, 'nativeQueueId': 'queue-1'} + ok('channel', 'acknowledge', '--name', 'example', '--id', 'message-1', '--input', json.dumps(receipt)) + ok('channel', 'reserve-wake', '--name', 'example', '--id', 'message-1', '--session', session, '--generation', '1', '--input', 'queue-1') + observed = ok('channel', 'get', '--name', 'example')['channel'] + self.assertEqual(observed['wakeReservation']['nativeQueueId'], 'queue-1') + self.assertNotEqual(call('channel', 'begin-handover', '--name', 'example').returncode, 0) + self.assertEqual(ok('channel', 'get', '--name', 'example')['channel']['phase'], 'active') + def test_unsupported_recipient_does_not_reserve_delivery(self): with tempfile.TemporaryDirectory() as directory: args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state='fixture', channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) diff --git a/packages/tmux-bridge/test/channel-state.test.mjs b/packages/tmux-bridge/test/channel-state.test.mjs index 664610e6..f4fd4936 100644 --- a/packages/tmux-bridge/test/channel-state.test.mjs +++ b/packages/tmux-bridge/test/channel-state.test.mjs @@ -1,6 +1,19 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, finishHandover, reserveStatePreparation, completeStatePreparation } from '../bin/channel-state.mjs'; +import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, finishHandover, reserveWake, reserveStatePreparation, completeStatePreparation } from '../bin/channel-state.mjs'; + +test('a wake reservation prevents handover and requires exact accepted queue identity', () => { + const session = 'codex:22222222-2222-4222-8222-222222222222'; + let channel = createChannel('example', session); + channel = beginDelivery(enqueue(channel, 'message-1', 'fixture'), 'message-1', session, 1); + channel = acknowledge(channel, 'message-1', { status: 'accepted', messageId: 'message-1', session, generation: 1, nativeQueueId: 'queue-1' }); + assert.throws(() => reserveWake(channel, 'message-1', session, 2, 'queue-1'), /reservation/); + assert.throws(() => reserveWake(channel, 'message-1', session, 1, 'queue-2'), /identity/); + const reserved = reserveWake(channel, 'message-1', session, 1, 'queue-1'); + assert.throws(() => beginHandover(reserved), /wake reservation/); + assert.throws(() => reserveWake(reserved, 'message-1', session, 1, 'queue-1'), /reservation/); + assert.throws(() => reserveWake(beginHandover(channel), 'message-1', session, 1, 'queue-1'), /reservation/); +}); test('native queue identity is scoped to its accepted Codex delivery', () => { const session = 'codex:22222222-2222-4222-8222-222222222222'; diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 21d798c0..7f323511 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -47,12 +47,23 @@ export function acknowledge(state, id, receipt) { export function beginHandover(state) { if (state.phase !== 'active') throw new Error('handover already in progress'); + if (state.wakeReservation) throw new Error('wake reservation unresolved'); const next = copy(state); next.phase = 'handover'; delete next.statePreparation; return next; } +// A reservation is durable and has no expiry: a crashed native call is unknown. +export function reserveWake(state, id, session, generation, nativeQueueId) { + if (state.phase !== 'active' || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); + const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); + if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); + const next = copy(state); + next.wakeReservation = { id, session, generation, nativeQueueId }; + return next; +} + // A reserved request is intentionally not retried automatically after a crash. export function reserveStatePreparation(state, id) { if (state.phase !== 'handover' || state.statePreparation || !identifier(id)) throw new Error('state preparation unavailable or unresolved'); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index c7585cba..338bbbdb 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -37,7 +37,7 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; @@ -129,7 +129,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -193,6 +193,10 @@ try { next = beginDelivery(current, requiredSingleLine(values.id, "--id"), values.session === undefined ? undefined : requiredSingleLine(values.session, "--session"), values.generation === undefined ? undefined : Number(values.generation)); } else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); + else if (subcommand === "reserve-wake") { + if (!/^[1-9][0-9]*$/.test(values.generation || "")) throw new Error("invalid channel generation"); + next = reserveWake(current, requiredSingleLine(values.id, "--id"), requiredSingleLine(values.session, "--session"), Number(values.generation), requiredSingleLine(channelInput, "--input")); + } else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "finish-handover") { const target = requiredSingleLine(values.to, "--to"); From f73b9f779414487f5d53a8b14b92b8881129ea7a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:26:41 +0000 Subject: [PATCH 052/113] Reserve channel before native wake start --- docs/design/plexus-modules.md | 7 +++--- .../tmux-bridge/bin/codex-wake-evidence.mjs | 12 ++++++--- .../test/codex-wake-evidence.test.mjs | 25 ++++++++++++++++--- skills/agent-tmux/bin/codex-wake-evidence.mjs | 12 ++++++--- 4 files changed, 41 insertions(+), 15 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index d38ccdc1..cbbc0b5d 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -47,9 +47,10 @@ 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 experimental wake adapter does not -yet acquire or settle this reservation, and no recovery operation exists, so -the reservation interface is not ready for operational use. +and survives replay; it has no expiry. The experimental wake adapter acquires +the reservation before starting a turn, but cannot yet settle it even on +success, and no recovery operation exists. 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 diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index 0f16f166..1505f46a 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -57,8 +57,8 @@ export async function publishCodexWake({ evidenceRoot, reference, session, graph return { schema: 'agent-mesh.wake-record.v1', session, evidence: reference, duplicate: receipt.duplicate }; } -export async function startCodexWake({ thread, queueId, correlation, evidenceRoot, graphState, apply }) { - if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit wake identity, graph and apply required'); +export async function startCodexWake({ thread, queueId, correlation, channel, generation, evidenceRoot, graphState, apply }) { + if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || !Number.isSafeInteger(generation) || generation < 1 || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit wake identity, channel, generation, graph and apply required'); await privateRoot(evidenceRoot); await privateRoot(graphState); thread = thread.toLowerCase(); @@ -71,6 +71,10 @@ export async function startCodexWake({ thread, queueId, correlation, evidenceRoo const evidence = await withCodexAppServer({ clientName: 'agent-mesh-wake-evidence', timeout: 30000, timeoutMessage: 'native wake outcome uncertain' }, async request => { const listed = await request('thread/queue/list', { threadId: thread, limit: 100 }); if (!Array.isArray(listed?.data) || listed.nextCursor != null || listed.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length !== 1) throw new Error('queued waker identity unavailable'); + const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (reserved.error || reserved.status !== 0) throw new Error('wake reservation unavailable or uncertain'); + let reservation; try { reservation = JSON.parse(reserved.stdout)?.channel?.wakeReservation; } catch { throw new Error('wake reservation receipt unavailable'); } + if (!reservation || reservation.id !== correlation || reservation.session !== session || reservation.generation !== generation || reservation.nativeQueueId !== queueId) throw new Error('wake reservation receipt mismatch'); await createDurable(evidenceRoot, `intent-${intent}.json`, `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`); const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); const turn = started?.turn; @@ -91,11 +95,11 @@ export async function startCodexWake({ thread, queueId, correlation, evidenceRoo if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { try { - const { values } = parseArgs({ options: { apply: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); let result; if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'] }); - else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, channel: values.channel, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); console.log(JSON.stringify(result)); } catch { console.error('wake observation failed or outcome uncertain; inspect before retry'); process.exitCode = 1; } } diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 6a08ead4..2c6eecd5 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -24,6 +24,14 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, '--state', state, ...args])).stdout); await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', thread, '--json'); await call('migrate', '--apply', '--json'); + const session = `codex:${thread}`; + async function prepareChannel(name) { + await call('channel', 'create', '--name', name, '--session', session); + await call('channel', 'enqueue', '--name', name, '--id', correlation, '--input', 'fixture'); + await call('channel', 'begin-delivery', '--name', name, '--id', correlation, '--session', session, '--generation', '1'); + await call('channel', 'acknowledge', '--name', name, '--id', correlation, '--input', JSON.stringify({ status: 'accepted', messageId: correlation, session, generation: 1, nativeQueueId: 'queued-1' })); + } + await prepareChannel('success'); const cursor = (await call('query', 'changes', '--input', JSON.stringify({ initial: 'head' }))).cursor; const requests = []; let mode = 'success'; const server = createAppServer((request, peer) => { @@ -37,14 +45,20 @@ test('queued wake needs explicit apply, a native start and durable correlated pr await new Promise(resolve => server.listen(socket, resolve)); t.after(() => new Promise(resolve => server.close(resolve))); const env = { ...process.env, CODEX_REMOTE_SOCK: socket, CODEX_NO_REMOTE: '' }; - const args = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--evidence-root', evidence, '--graph-state', state]; + const args = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', 'success', '--generation', '1', '--evidence-root', evidence, '--graph-state', state]; await assert.rejects(exec(process.execPath, [bin, ...args], { env })); assert.equal(requests.length, 0); + await prepareChannel('handover'); + await call('channel', 'begin-handover', '--name', 'handover'); + await assert.rejects(exec(process.execPath, [bin, '--apply', '--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', 'handover', '--generation', '1', '--evidence-root', evidence, '--graph-state', state], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 0); mode = 'wrong'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); assert.deepEqual(await readdir(evidence), []); mode = 'success'; const first = JSON.parse((await exec(process.execPath, [bin, '--apply', ...args], { env })).stdout); assert.equal(first.duplicate, false); + assert.equal((await call('channel', 'get', '--name', 'success')).channel.wakeReservation.id, correlation); + await assert.rejects(call('channel', 'begin-handover', '--name', 'success')); const verified = await verifyCodexWakeEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }); assert.equal(verified.turn, turn); assert.equal(verified.correlation, correlation); @@ -56,7 +70,8 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const feed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); assert.deepEqual(feed.events.filter(e => e.type === 'session.woken').map(e => e.evidence), [first.evidence]); const uncertainRoot = join(root, 'uncertain'); await mkdir(uncertainRoot, { mode: 0o700 }); - const uncertainArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--evidence-root', uncertainRoot, '--graph-state', state]; + await prepareChannel('uncertain'); + const uncertainArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', 'uncertain', '--generation', '1', '--evidence-root', uncertainRoot, '--graph-state', state]; mode = 'uncertain'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...uncertainArgs], { env })); assert.deepEqual((await readdir(uncertainRoot)).map(name => name.split('-')[0]), ['intent']); @@ -66,7 +81,8 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const uncertainFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); assert.equal(uncertainFeed.events.filter(e => e.type === 'session.woken').length, 1); const partialRoot = join(root, 'partial'); await mkdir(partialRoot, { mode: 0o700 }); - const partialArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--evidence-root', partialRoot, '--graph-state', state]; + await prepareChannel('partial'); + const partialArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', 'partial', '--generation', '1', '--evidence-root', partialRoot, '--graph-state', state]; mode = 'partial'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...partialArgs], { env })); assert.deepEqual((await readdir(partialRoot)).map(name => name.split('-')[0]), ['intent']); @@ -74,7 +90,8 @@ test('queued wake needs explicit apply, a native start and durable correlated pr assert.equal(partialFeed.events.filter(e => e.type === 'session.woken').length, 1); for (const mismatch of ['wrong-thread', 'wrong-turn', 'wrong-time', 'wrong-client', 'wrong-input']) { const mismatchRoot = join(root, mismatch); await mkdir(mismatchRoot, { mode: 0o700 }); - const mismatchArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--evidence-root', mismatchRoot, '--graph-state', state]; + await prepareChannel(mismatch); + const mismatchArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', mismatch, '--generation', '1', '--evidence-root', mismatchRoot, '--graph-state', state]; mode = mismatch; await assert.rejects(exec(process.execPath, [bin, '--apply', ...mismatchArgs], { env })); assert.deepEqual((await readdir(mismatchRoot)).map(name => name.split('-')[0]), ['intent']); diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index 0f16f166..1505f46a 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -57,8 +57,8 @@ export async function publishCodexWake({ evidenceRoot, reference, session, graph return { schema: 'agent-mesh.wake-record.v1', session, evidence: reference, duplicate: receipt.duplicate }; } -export async function startCodexWake({ thread, queueId, correlation, evidenceRoot, graphState, apply }) { - if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit wake identity, graph and apply required'); +export async function startCodexWake({ thread, queueId, correlation, channel, generation, evidenceRoot, graphState, apply }) { + if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || !Number.isSafeInteger(generation) || generation < 1 || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit wake identity, channel, generation, graph and apply required'); await privateRoot(evidenceRoot); await privateRoot(graphState); thread = thread.toLowerCase(); @@ -71,6 +71,10 @@ export async function startCodexWake({ thread, queueId, correlation, evidenceRoo const evidence = await withCodexAppServer({ clientName: 'agent-mesh-wake-evidence', timeout: 30000, timeoutMessage: 'native wake outcome uncertain' }, async request => { const listed = await request('thread/queue/list', { threadId: thread, limit: 100 }); if (!Array.isArray(listed?.data) || listed.nextCursor != null || listed.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length !== 1) throw new Error('queued waker identity unavailable'); + const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (reserved.error || reserved.status !== 0) throw new Error('wake reservation unavailable or uncertain'); + let reservation; try { reservation = JSON.parse(reserved.stdout)?.channel?.wakeReservation; } catch { throw new Error('wake reservation receipt unavailable'); } + if (!reservation || reservation.id !== correlation || reservation.session !== session || reservation.generation !== generation || reservation.nativeQueueId !== queueId) throw new Error('wake reservation receipt mismatch'); await createDurable(evidenceRoot, `intent-${intent}.json`, `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`); const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); const turn = started?.turn; @@ -91,11 +95,11 @@ export async function startCodexWake({ thread, queueId, correlation, evidenceRoo if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { try { - const { values } = parseArgs({ options: { apply: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); let result; if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'] }); - else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, channel: values.channel, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); console.log(JSON.stringify(result)); } catch { console.error('wake observation failed or outcome uncertain; inspect before retry'); process.exitCode = 1; } } From 97f5ac0b9876251a51c63fde51c2b8b884ba93d7 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:31:18 +0000 Subject: [PATCH 053/113] Settle wake reservation after verified evidence --- docs/design/plexus-modules.md | 8 ++++--- packages/tmux-bridge/bin/channel-state.mjs | 12 +++++++++- .../tmux-bridge/bin/codex-wake-evidence.mjs | 15 ++++++++---- packages/tmux-bridge/bin/mesh-graph.mjs | 23 +++++++++++++++++-- .../test/codex-wake-evidence.test.mjs | 10 +++++--- skills/agent-tmux/bin/channel-state.mjs | 12 +++++++++- skills/agent-tmux/bin/codex-wake-evidence.mjs | 15 ++++++++---- skills/agent-tmux/bin/mesh-graph.mjs | 23 +++++++++++++++++-- 8 files changed, 98 insertions(+), 20 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index cbbc0b5d..604d5e6e 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -48,9 +48,11 @@ 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 experimental wake adapter acquires -the reservation before starting a turn, but cannot yet settle it even on -success, and no recovery operation exists. This path is not ready for -operational use. +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. A crash before that +point stays unresolved; there is no automatic retry or recovery for an +unproven native outcome. 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 diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 7f323511..05661ab6 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -57,13 +57,23 @@ export function beginHandover(state) { // A reservation is durable and has no expiry: a crashed native call is unknown. export function reserveWake(state, id, session, generation, nativeQueueId) { if (state.phase !== 'active' || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); - const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); + const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && !item.wakeEvidence && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); const next = copy(state); next.wakeReservation = { id, session, generation, nativeQueueId }; return next; } +export function settleWake(state, proof) { + const reservation = state.wakeReservation; + if (!reservation || state.phase !== 'active' || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); + if (!item) throw new Error('wake item unavailable'); + item.wakeEvidence = proof.evidence; + delete next.wakeReservation; + return next; +} + // A reserved request is intentionally not retried automatically after a crash. export function reserveStatePreparation(state, id) { if (state.phase !== 'handover' || state.statePreparation || !identifier(id)) throw new Error('state preparation unavailable or unresolved'); diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index 1505f46a..fa63bc03 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -46,7 +46,7 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session return { ...value, evidence: reference }; } -export async function publishCodexWake({ evidenceRoot, reference, session, graphState }) { +export async function publishCodexWake({ evidenceRoot, reference, session, graphState, channel }) { if (typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit graph state required'); const proof = await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); const observation = `codex-wake-${hash(JSON.stringify([session, proof.queueId]))}`; @@ -54,7 +54,14 @@ export async function publishCodexWake({ evidenceRoot, reference, session, graph if (result.error || result.status !== 0) throw new Error('graph recording failed; retain evidence for explicit publication'); let receipt; try { receipt = JSON.parse(result.stdout); } catch { throw new Error('graph receipt unavailable'); } if (receipt?.observation !== observation || typeof receipt.duplicate !== 'boolean') throw new Error('graph receipt mismatch'); - return { schema: 'agent-mesh.wake-record.v1', session, evidence: reference, duplicate: receipt.duplicate }; + if (channel !== undefined) { + const settled = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'settle-wake', '--name', channel, '--session', session, '--state-root', evidenceRoot, '--input', reference], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (settled.error || settled.status !== 0) throw new Error('wake settlement unavailable; retain evidence for recovery'); + let status; try { status = JSON.parse(settled.stdout); } catch { throw new Error('wake settlement receipt unavailable'); } + const item = status?.channel?.queue?.find(row => row.id === proof.correlation && row.session === session && row.nativeQueueId === proof.queueId); + if (item?.wakeEvidence !== reference) throw new Error('wake settlement receipt mismatch'); + } + return { schema: 'agent-mesh.wake-record.v1', session, evidence: reference, duplicate: receipt.duplicate, ...(channel !== undefined ? { settled: true } : {}) }; } export async function startCodexWake({ thread, queueId, correlation, channel, generation, evidenceRoot, graphState, apply }) { @@ -90,7 +97,7 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge }); const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); - return publishCodexWake({ evidenceRoot, reference, session, graphState }); + return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); } if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { @@ -98,7 +105,7 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { const { values } = parseArgs({ options: { apply: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); let result; if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); - else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'] }); + else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'], channel: values.channel }); else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, channel: values.channel, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); console.log(JSON.stringify(result)); } catch { console.error('wake observation failed or outcome uncertain; inspect before retry'); process.exitCode = 1; } diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 338bbbdb..428e15a1 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -37,7 +37,8 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; +import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; @@ -129,7 +130,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -151,6 +152,24 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "settle-wake") { + const session = requiredSingleLine(values.session, "--session"); + const evidence = requiredSingleLine(channelInput, "--input"); + const proof = await verifyCodexWakeEvidence({ evidenceRoot: requiredSingleLine(values["state-root"], "--state-root"), reference: evidence, session }); + const sourceId = `codex-wake-${createHash("sha256").update(JSON.stringify([session, proof.queueId])).digest("hex")}`; + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + const digest = createHash("sha256").update(JSON.stringify({ type: "session.woken", session, evidence, to: null })).digest("hex"); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current || !(graph.lifecycleReceipts || []).some(item => item.id === receiptId && item.digest === digest)) throw new Error("recorded wake proof unavailable"); + if (!current.wakeReservation && current.queue.some(item => item.id === proof.correlation && item.session === session && item.nativeQueueId === proof.queueId && item.wakeEvidence === evidence)) return { graph, result: { channel: current, duplicate: true } }; + const next = settleWake(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } if (subcommand === "prepare-state") { const root = requiredSingleLine(values["state-root"], "--state-root"), filename = requiredSingleLine(values.filename, "--filename"); if (!isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error("invalid state preparation path"); diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 2c6eecd5..2cd3f9d1 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -57,16 +57,19 @@ test('queued wake needs explicit apply, a native start and durable correlated pr mode = 'success'; const first = JSON.parse((await exec(process.execPath, [bin, '--apply', ...args], { env })).stdout); assert.equal(first.duplicate, false); - assert.equal((await call('channel', 'get', '--name', 'success')).channel.wakeReservation.id, correlation); - await assert.rejects(call('channel', 'begin-handover', '--name', 'success')); + const success = (await call('channel', 'get', '--name', 'success')).channel; + assert.equal(success.wakeReservation, undefined); + assert.equal(success.queue[0].wakeEvidence, first.evidence); + assert.equal(first.settled, true); const verified = await verifyCodexWakeEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }); assert.equal(verified.turn, turn); assert.equal(verified.correlation, correlation); assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 1); await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 1); - const again = JSON.parse((await exec(process.execPath, [bin, '--publish', first.evidence, '--session', `codex:${thread}`, '--evidence-root', evidence, '--graph-state', state], { env })).stdout); + const again = JSON.parse((await exec(process.execPath, [bin, '--publish', first.evidence, '--session', `codex:${thread}`, '--channel', 'success', '--evidence-root', evidence, '--graph-state', state], { env })).stdout); assert.equal(again.duplicate, true); + assert.equal(again.settled, true); const feed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); assert.deepEqual(feed.events.filter(e => e.type === 'session.woken').map(e => e.evidence), [first.evidence]); const uncertainRoot = join(root, 'uncertain'); await mkdir(uncertainRoot, { mode: 0o700 }); @@ -74,6 +77,7 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const uncertainArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', 'uncertain', '--generation', '1', '--evidence-root', uncertainRoot, '--graph-state', state]; mode = 'uncertain'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...uncertainArgs], { env })); + await assert.rejects(call('channel', 'begin-handover', '--name', 'uncertain')); assert.deepEqual((await readdir(uncertainRoot)).map(name => name.split('-')[0]), ['intent']); const starts = requests.filter(r => r.method === 'thread/queue/start').length; await assert.rejects(exec(process.execPath, [bin, '--apply', ...uncertainArgs], { env })); diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 7f323511..05661ab6 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -57,13 +57,23 @@ export function beginHandover(state) { // A reservation is durable and has no expiry: a crashed native call is unknown. export function reserveWake(state, id, session, generation, nativeQueueId) { if (state.phase !== 'active' || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); - const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); + const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && !item.wakeEvidence && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); const next = copy(state); next.wakeReservation = { id, session, generation, nativeQueueId }; return next; } +export function settleWake(state, proof) { + const reservation = state.wakeReservation; + if (!reservation || state.phase !== 'active' || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); + if (!item) throw new Error('wake item unavailable'); + item.wakeEvidence = proof.evidence; + delete next.wakeReservation; + return next; +} + // A reserved request is intentionally not retried automatically after a crash. export function reserveStatePreparation(state, id) { if (state.phase !== 'handover' || state.statePreparation || !identifier(id)) throw new Error('state preparation unavailable or unresolved'); diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index 1505f46a..fa63bc03 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -46,7 +46,7 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session return { ...value, evidence: reference }; } -export async function publishCodexWake({ evidenceRoot, reference, session, graphState }) { +export async function publishCodexWake({ evidenceRoot, reference, session, graphState, channel }) { if (typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit graph state required'); const proof = await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); const observation = `codex-wake-${hash(JSON.stringify([session, proof.queueId]))}`; @@ -54,7 +54,14 @@ export async function publishCodexWake({ evidenceRoot, reference, session, graph if (result.error || result.status !== 0) throw new Error('graph recording failed; retain evidence for explicit publication'); let receipt; try { receipt = JSON.parse(result.stdout); } catch { throw new Error('graph receipt unavailable'); } if (receipt?.observation !== observation || typeof receipt.duplicate !== 'boolean') throw new Error('graph receipt mismatch'); - return { schema: 'agent-mesh.wake-record.v1', session, evidence: reference, duplicate: receipt.duplicate }; + if (channel !== undefined) { + const settled = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'settle-wake', '--name', channel, '--session', session, '--state-root', evidenceRoot, '--input', reference], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (settled.error || settled.status !== 0) throw new Error('wake settlement unavailable; retain evidence for recovery'); + let status; try { status = JSON.parse(settled.stdout); } catch { throw new Error('wake settlement receipt unavailable'); } + const item = status?.channel?.queue?.find(row => row.id === proof.correlation && row.session === session && row.nativeQueueId === proof.queueId); + if (item?.wakeEvidence !== reference) throw new Error('wake settlement receipt mismatch'); + } + return { schema: 'agent-mesh.wake-record.v1', session, evidence: reference, duplicate: receipt.duplicate, ...(channel !== undefined ? { settled: true } : {}) }; } export async function startCodexWake({ thread, queueId, correlation, channel, generation, evidenceRoot, graphState, apply }) { @@ -90,7 +97,7 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge }); const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); - return publishCodexWake({ evidenceRoot, reference, session, graphState }); + return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); } if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { @@ -98,7 +105,7 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { const { values } = parseArgs({ options: { apply: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); let result; if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); - else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'] }); + else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'], channel: values.channel }); else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, channel: values.channel, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); console.log(JSON.stringify(result)); } catch { console.error('wake observation failed or outcome uncertain; inspect before retry'); process.exitCode = 1; } diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 338bbbdb..428e15a1 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -37,7 +37,8 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; +import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; @@ -129,7 +130,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -151,6 +152,24 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "settle-wake") { + const session = requiredSingleLine(values.session, "--session"); + const evidence = requiredSingleLine(channelInput, "--input"); + const proof = await verifyCodexWakeEvidence({ evidenceRoot: requiredSingleLine(values["state-root"], "--state-root"), reference: evidence, session }); + const sourceId = `codex-wake-${createHash("sha256").update(JSON.stringify([session, proof.queueId])).digest("hex")}`; + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + const digest = createHash("sha256").update(JSON.stringify({ type: "session.woken", session, evidence, to: null })).digest("hex"); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current || !(graph.lifecycleReceipts || []).some(item => item.id === receiptId && item.digest === digest)) throw new Error("recorded wake proof unavailable"); + if (!current.wakeReservation && current.queue.some(item => item.id === proof.correlation && item.session === session && item.nativeQueueId === proof.queueId && item.wakeEvidence === evidence)) return { graph, result: { channel: current, duplicate: true } }; + const next = settleWake(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } if (subcommand === "prepare-state") { const root = requiredSingleLine(values["state-root"], "--state-root"), filename = requiredSingleLine(values.filename, "--filename"); if (!isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error("invalid state preparation path"); From 8ca169e0d5879da25e5e8384c43a7d638b3d14f1 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:35:35 +0000 Subject: [PATCH 054/113] Prevent duplicate wake reservations across channels --- docs/design/plexus-modules.md | 4 +++- packages/tmux-bridge/bin/mesh-graph.mjs | 6 ++++- .../test/codex-wake-evidence.test.mjs | 24 +++++++++++-------- skills/agent-tmux/bin/mesh-graph.mjs | 6 ++++- 4 files changed, 27 insertions(+), 13 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index 604d5e6e..e70cc99c 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -47,7 +47,9 @@ 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 experimental wake adapter acquires +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. A crash before that diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 428e15a1..296d3e3d 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -214,7 +214,11 @@ try { else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); else if (subcommand === "reserve-wake") { if (!/^[1-9][0-9]*$/.test(values.generation || "")) throw new Error("invalid channel generation"); - next = reserveWake(current, requiredSingleLine(values.id, "--id"), requiredSingleLine(values.session, "--session"), Number(values.generation), requiredSingleLine(channelInput, "--input")); + const session = requiredSingleLine(values.session, "--session"), queueId = requiredSingleLine(channelInput, "--input"); + const sourceId = `codex-wake-${createHash("sha256").update(JSON.stringify([session, queueId])).digest("hex")}`; + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + if ((graph.lifecycleReceipts || []).some(item => item.id === receiptId) || (graph.channels || []).some(item => item.id !== name && item.wakeReservation?.session === session && item.wakeReservation?.nativeQueueId === queueId)) throw new Error("wake identity already reserved or recorded"); + next = reserveWake(current, requiredSingleLine(values.id, "--id"), session, Number(values.generation), queueId); } else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "finish-handover") { diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 2cd3f9d1..e795b8bc 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -25,19 +25,19 @@ test('queued wake needs explicit apply, a native start and durable correlated pr await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', thread, '--json'); await call('migrate', '--apply', '--json'); const session = `codex:${thread}`; - async function prepareChannel(name) { + async function prepareChannel(name, nativeId = 'queued-1') { await call('channel', 'create', '--name', name, '--session', session); await call('channel', 'enqueue', '--name', name, '--id', correlation, '--input', 'fixture'); await call('channel', 'begin-delivery', '--name', name, '--id', correlation, '--session', session, '--generation', '1'); - await call('channel', 'acknowledge', '--name', name, '--id', correlation, '--input', JSON.stringify({ status: 'accepted', messageId: correlation, session, generation: 1, nativeQueueId: 'queued-1' })); + await call('channel', 'acknowledge', '--name', name, '--id', correlation, '--input', JSON.stringify({ status: 'accepted', messageId: correlation, session, generation: 1, nativeQueueId: nativeId })); } await prepareChannel('success'); const cursor = (await call('query', 'changes', '--input', JSON.stringify({ initial: 'head' }))).cursor; - const requests = []; let mode = 'success'; + const requests = []; let mode = 'success', nativeId = 'queued-1'; const server = createAppServer((request, peer) => { if (!request.id) return; requests.push(request); - if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: [{ id: 'queued-1', clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: 'fixture' }] }], nextCursor: null } }); + if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: 'fixture' }] }], nextCursor: null } }); else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: 123456789, items: [] } } }); else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, startedAt: mode === 'wrong-time' ? 123456788 : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture' }] }] }] } } }); else peer.send({ id: request.id, result: {} }); @@ -70,14 +70,18 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const again = JSON.parse((await exec(process.execPath, [bin, '--publish', first.evidence, '--session', `codex:${thread}`, '--channel', 'success', '--evidence-root', evidence, '--graph-state', state], { env })).stdout); assert.equal(again.duplicate, true); assert.equal(again.settled, true); + await prepareChannel('duplicate'); + await assert.rejects(call('channel', 'reserve-wake', '--name', 'duplicate', '--id', correlation, '--session', session, '--generation', '1', '--input', 'queued-1')); const feed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); assert.deepEqual(feed.events.filter(e => e.type === 'session.woken').map(e => e.evidence), [first.evidence]); const uncertainRoot = join(root, 'uncertain'); await mkdir(uncertainRoot, { mode: 0o700 }); - await prepareChannel('uncertain'); - const uncertainArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', 'uncertain', '--generation', '1', '--evidence-root', uncertainRoot, '--graph-state', state]; + nativeId = 'queued-uncertain'; await prepareChannel('uncertain', nativeId); + const uncertainArgs = ['--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'uncertain', '--generation', '1', '--evidence-root', uncertainRoot, '--graph-state', state]; mode = 'uncertain'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...uncertainArgs], { env })); await assert.rejects(call('channel', 'begin-handover', '--name', 'uncertain')); + await prepareChannel('competing', nativeId); + await assert.rejects(call('channel', 'reserve-wake', '--name', 'competing', '--id', correlation, '--session', session, '--generation', '1', '--input', nativeId)); assert.deepEqual((await readdir(uncertainRoot)).map(name => name.split('-')[0]), ['intent']); const starts = requests.filter(r => r.method === 'thread/queue/start').length; await assert.rejects(exec(process.execPath, [bin, '--apply', ...uncertainArgs], { env })); @@ -85,8 +89,8 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const uncertainFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); assert.equal(uncertainFeed.events.filter(e => e.type === 'session.woken').length, 1); const partialRoot = join(root, 'partial'); await mkdir(partialRoot, { mode: 0o700 }); - await prepareChannel('partial'); - const partialArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', 'partial', '--generation', '1', '--evidence-root', partialRoot, '--graph-state', state]; + nativeId = 'queued-partial'; await prepareChannel('partial', nativeId); + const partialArgs = ['--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'partial', '--generation', '1', '--evidence-root', partialRoot, '--graph-state', state]; mode = 'partial'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...partialArgs], { env })); assert.deepEqual((await readdir(partialRoot)).map(name => name.split('-')[0]), ['intent']); @@ -94,8 +98,8 @@ test('queued wake needs explicit apply, a native start and durable correlated pr assert.equal(partialFeed.events.filter(e => e.type === 'session.woken').length, 1); for (const mismatch of ['wrong-thread', 'wrong-turn', 'wrong-time', 'wrong-client', 'wrong-input']) { const mismatchRoot = join(root, mismatch); await mkdir(mismatchRoot, { mode: 0o700 }); - await prepareChannel(mismatch); - const mismatchArgs = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', mismatch, '--generation', '1', '--evidence-root', mismatchRoot, '--graph-state', state]; + nativeId = `queued-${mismatch}`; await prepareChannel(mismatch, nativeId); + const mismatchArgs = ['--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', mismatch, '--generation', '1', '--evidence-root', mismatchRoot, '--graph-state', state]; mode = mismatch; await assert.rejects(exec(process.execPath, [bin, '--apply', ...mismatchArgs], { env })); assert.deepEqual((await readdir(mismatchRoot)).map(name => name.split('-')[0]), ['intent']); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 428e15a1..296d3e3d 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -214,7 +214,11 @@ try { else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); else if (subcommand === "reserve-wake") { if (!/^[1-9][0-9]*$/.test(values.generation || "")) throw new Error("invalid channel generation"); - next = reserveWake(current, requiredSingleLine(values.id, "--id"), requiredSingleLine(values.session, "--session"), Number(values.generation), requiredSingleLine(channelInput, "--input")); + const session = requiredSingleLine(values.session, "--session"), queueId = requiredSingleLine(channelInput, "--input"); + const sourceId = `codex-wake-${createHash("sha256").update(JSON.stringify([session, queueId])).digest("hex")}`; + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + if ((graph.lifecycleReceipts || []).some(item => item.id === receiptId) || (graph.channels || []).some(item => item.id !== name && item.wakeReservation?.session === session && item.wakeReservation?.nativeQueueId === queueId)) throw new Error("wake identity already reserved or recorded"); + next = reserveWake(current, requiredSingleLine(values.id, "--id"), session, Number(values.generation), queueId); } else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "finish-handover") { From 43c0df9d0f68e8d02bf81920c28d958c2b2d5778 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:48:49 +0000 Subject: [PATCH 055/113] Define role-scoped restart preparation --- docs/design/plexus-channels.md | 17 ++++++++++ .../tmux-bridge/bin/handover-state-proof.mjs | 4 +-- packages/tmux-bridge/bin/restart-state.mjs | 13 +++++++- .../tmux-bridge/bin/role-launch-profile.mjs | 30 +++++++++++++++++ .../test/handover-state-proof.test.mjs | 4 +-- .../test/role-launch-profile.test.mjs | 33 +++++++++++++++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-privacy.mjs | 2 +- .../agent-tmux/bin/handover-state-proof.mjs | 4 +-- skills/agent-tmux/bin/restart-state.mjs | 13 +++++++- skills/agent-tmux/bin/role-launch-profile.mjs | 30 +++++++++++++++++ 11 files changed, 142 insertions(+), 9 deletions(-) create mode 100644 packages/tmux-bridge/bin/role-launch-profile.mjs create mode 100644 packages/tmux-bridge/test/role-launch-profile.test.mjs create mode 100644 skills/agent-tmux/bin/role-launch-profile.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index b5a0d1e3..6514facb 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -93,3 +93,20 @@ contents. This observation is local evidence at the instant read, not proof that no later turn can arrive; safe finality still requires exclusive lifecycle control and an authenticated source. Claude and cloud transcripts are not supported by this observer. +# Role-scoped restart preparation + +The `agent-mesh.restart.v1` YAML handover block requires `role_profile` when +used as a state proof. Its schema `agent-mesh.role-profile.v1` contains `role` +and unique identifier arrays `permissions`, `mcp`, and `plugins`. These are +references, not commands or grants. A trusted private authority must resolve +them and reject out-of-scope or human-gated permissions. A missing profile +fails handover preparation; legacy readers may still parse old state. + +The isolated role-launch planner probes only the configured MCP names. An +unreachable MCP is omitted and listed in the receipt without blocking startup. +The launch assessor reports the observed MCP count and startup tokens, or null +when tokens are unavailable; an unexpected permission prompt or component +requires rollback. These are preparation primitives only: no provider startup, +permission enforcement, timeout cancellation, live rollback or token collector +is connected yet. The approved handover remains disabled until native evidence +and those adapters are present. diff --git a/packages/tmux-bridge/bin/handover-state-proof.mjs b/packages/tmux-bridge/bin/handover-state-proof.mjs index 0c4b17b1..f091917b 100644 --- a/packages/tmux-bridge/bin/handover-state-proof.mjs +++ b/packages/tmux-bridge/bin/handover-state-proof.mjs @@ -38,7 +38,7 @@ export async function requestStateProof({ session, channel, root, filename, mana if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); if (typeof nonce !== 'string' || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce)) throw new Error('invalid request nonce'); if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); - const message = `Write your handover state with a RIAVVIO YAML block using agent-mesh.restart.v1 to ${join(root, filename)} with private permissions. Bind the block to session ${session} and channel ${channel}, and include harness, working_directory, skills, triggers and goal. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; + const message = `Write your handover state with a RIAVVIO YAML block using agent-mesh.restart.v1 to ${join(root, filename)} with private permissions. Bind the block to session ${session} and channel ${channel}, and include harness, working_directory, skills, triggers, goal and role_profile with schema agent-mesh.role-profile.v1, role and exact identifier lists permissions, mcp, plugins. List only existing grants; do not grant anything. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message-stdin']; if (agent === 'codex') argv.push('--no-resume'); if (agent === 'claude') argv.push('--managed-inbox-root', managedInboxRoot); @@ -71,7 +71,7 @@ export async function verifyStateResponse({ session, channel, nonce, response, r if (decoded.error || decoded.status !== 0) throw new Error('restart YAML unavailable or invalid'); let restart; try { restart = JSON.parse(decoded.stdout); } catch { throw new Error('invalid restart YAML result'); } - validateRestartState(restart, { session, channel }); + validateRestartState(restart, { session, channel, requireRoleProfile: true }); return { schema: attestation.schema, session, nonce, filename, sha256: digest, bytes: bytes.length }; } finally { await file.close(); } } diff --git a/packages/tmux-bridge/bin/restart-state.mjs b/packages/tmux-bridge/bin/restart-state.mjs index d01ab53d..8cbb5800 100644 --- a/packages/tmux-bridge/bin/restart-state.mjs +++ b/packages/tmux-bridge/bin/restart-state.mjs @@ -1,14 +1,25 @@ /** Validate a parsed restart block; never execute its instructions. */ const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; const nonempty = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 8192 && !value.includes('\0'); +const profileId = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); -export function validateRestartState(block, { session, channel } = {}) { +export function validateRoleProfile(profile) { + if (!isObject(profile) || Object.keys(profile).sort().join(',') !== 'mcp,permissions,plugins,role,schema' || profile.schema !== 'agent-mesh.role-profile.v1' || !profileId(profile.role)) throw new Error('invalid role profile'); + for (const key of ['permissions', 'mcp', 'plugins']) { + const values = profile[key]; + if (!Array.isArray(values) || values.length > 256 || !values.every(profileId) || new Set(values).size !== values.length) throw new Error(`invalid role profile ${key}`); + } + return true; +} + +export function validateRestartState(block, { session, channel, requireRoleProfile = false } = {}) { if (!isObject(block) || block.schema !== 'agent-mesh.restart.v1') throw new Error('invalid restart schema'); for (const field of ['session', 'channel', 'harness', 'working_directory']) { if (!nonempty(block[field])) throw new Error(`invalid restart ${field}`); } if (session !== undefined && block.session !== session) throw new Error('restart session mismatch'); if (channel !== undefined && block.channel !== channel) throw new Error('restart channel mismatch'); + if (requireRoleProfile || block.role_profile !== undefined) validateRoleProfile(block.role_profile); if (!Array.isArray(block.skills) || block.skills.length > 256 || !block.skills.every(nonempty)) throw new Error('invalid restart skills'); if (!Array.isArray(block.triggers) || block.triggers.length > 256) throw new Error('invalid restart triggers'); const ids = new Set(); diff --git a/packages/tmux-bridge/bin/role-launch-profile.mjs b/packages/tmux-bridge/bin/role-launch-profile.mjs new file mode 100644 index 00000000..569260b6 --- /dev/null +++ b/packages/tmux-bridge/bin/role-launch-profile.mjs @@ -0,0 +1,30 @@ +/** Build a role-scoped launch plan without granting capabilities or starting services. */ +import { validateRoleProfile } from './restart-state.mjs'; + +const id = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const list = value => Array.isArray(value) && value.length <= 256 && value.every(id) && new Set(value).size === value.length; + +export async function planRoleLaunch({ profile, authority, probe, timeoutMs = 3000 }) { + validateRoleProfile(profile); + if (!authority || authority.role !== profile.role || !list(authority.permissions) || !list(authority.mcp) || !list(authority.plugins) || !list(authority.humanGatedPermissions) || typeof probe !== 'function' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new Error('invalid role authority'); + for (const field of ['permissions', 'mcp', 'plugins']) if (profile[field].some(value => !authority[field].includes(value))) throw new Error('role profile exceeds authority'); + if (profile.permissions.some(value => authority.humanGatedPermissions.includes(value))) throw new Error('human-gated permission cannot be pregranted'); + const available = [], unavailable = []; + for (const name of profile.mcp) { + let timer; + try { + const result = await Promise.race([Promise.resolve().then(() => probe(name)), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('unreachable')), timeoutMs); })]); + (result === true ? available : unavailable).push(name); + } catch { unavailable.push(name); } + finally { clearTimeout(timer); } + } + return { schema: 'agent-mesh.role-launch-plan.v1', role: profile.role, permissions: [...profile.permissions], plugins: [...profile.plugins], mcpToStart: available, mcpUnavailable: unavailable }; +} + +/** Assess observed startup; the caller owns rollback and native observation. */ +export function assessRoleLaunch({ plan, observed }) { + if (!plan || plan.schema !== 'agent-mesh.role-launch-plan.v1' || !list(plan.permissions) || !list(plan.plugins) || !list(plan.mcpToStart) || !list(plan.mcpUnavailable) || !observed || !list(observed.mcpStarted) || !list(observed.pluginsStarted) || typeof observed.permissionPrompt !== 'boolean' || !(observed.startupTokens === null || (Number.isSafeInteger(observed.startupTokens) && observed.startupTokens >= 0))) throw new Error('invalid launch observation'); + const unexpected = observed.mcpStarted.some(value => !plan.mcpToStart.includes(value)) || observed.pluginsStarted.some(value => !plan.plugins.includes(value)); + const failed = observed.permissionPrompt || unexpected; + return { schema: 'agent-mesh.role-launch-receipt.v1', status: failed ? 'rollback-required' : 'ready', reason: observed.permissionPrompt ? 'unexpected-permission' : unexpected ? 'unexpected-component' : null, mcpStarted: observed.mcpStarted.length, mcpUnavailable: [...new Set([...plan.mcpUnavailable, ...plan.mcpToStart.filter(value => !observed.mcpStarted.includes(value))])], startupTokens: observed.startupTokens }; +} diff --git a/packages/tmux-bridge/test/handover-state-proof.test.mjs b/packages/tmux-bridge/test/handover-state-proof.test.mjs index 7df3c063..ce5342fb 100644 --- a/packages/tmux-bridge/test/handover-state-proof.test.mjs +++ b/packages/tmux-bridge/test/handover-state-proof.test.mjs @@ -27,7 +27,7 @@ test('state proof binds correlated response to private file bytes', async (t) => const root = await mkdtemp(join(tmpdir(), 'state-proof-')); t.after(() => rm(root, { recursive: true, force: true })); const session = 'codex:22222222-2222-4222-8222-222222222222', channel = '#example', filename = 'state.yaml', nonce = 'attempt-1'; - const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\n`; + const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\nrole_profile:\n schema: agent-mesh.role-profile.v1\n role: operator\n permissions: []\n mcp: []\n plugins: []\n`; await writeFile(join(root, filename), content, { mode: 0o600 }); const response = { schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }; const verify = (overrides = {}) => verifyStateResponse({ session, channel, nonce, filename, root, response: JSON.stringify(response), ...overrides }); @@ -57,7 +57,7 @@ test('native request binds response to its own correlation without resuming', as assert.ok(!argv.some(value => value.includes(root))); assert.ok(options.input.includes(join(root, filename))); const nonce = argv[argv.indexOf('--correlation-id') + 1]; - const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\n`; + const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\nrole_profile:\n schema: agent-mesh.role-profile.v1\n role: operator\n permissions: []\n mcp: []\n plugins: []\n`; await writeFile(join(root, filename), content, { mode: 0o600 }); return { stdout: JSON.stringify({ schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }) }; }; diff --git a/packages/tmux-bridge/test/role-launch-profile.test.mjs b/packages/tmux-bridge/test/role-launch-profile.test.mjs new file mode 100644 index 00000000..6603581a --- /dev/null +++ b/packages/tmux-bridge/test/role-launch-profile.test.mjs @@ -0,0 +1,33 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { validateRestartState } from '../bin/restart-state.mjs'; +import { planRoleLaunch, assessRoleLaunch } from '../bin/role-launch-profile.mjs'; + +const profile = { schema: 'agent-mesh.role-profile.v1', role: 'operator', permissions: ['read'], mcp: ['alpha', 'beta'], plugins: ['example'] }; +const authority = { role: 'operator', permissions: ['read', 'publish'], humanGatedPermissions: ['publish'], mcp: ['alpha', 'beta'], plugins: ['example'] }; + +test('restart role profile is explicit, bounded and never creates grants', () => { + const state = { schema: 'agent-mesh.restart.v1', session: 'codex:example', channel: '#example', harness: 'codex', working_directory: '/workspace', skills: [], triggers: [], goal: null }; + assert.throws(() => validateRestartState(state, { requireRoleProfile: true }), /profile/); + assert.equal(validateRestartState({ ...state, role_profile: profile }, { requireRoleProfile: true }), true); + assert.throws(() => validateRestartState({ ...state, role_profile: { ...profile, permissions: ['read', 'read'] } }), /permissions/); + assert.throws(() => validateRestartState({ ...state, role_profile: { ...profile, mcp: ['*'] } }), /mcp/); +}); + +test('unreachable MCP is excluded while unexpected permission requires rollback', async () => { + const seen = []; + const plan = await planRoleLaunch({ profile, authority, probe: async name => { seen.push(name); if (name === 'beta') throw new Error('offline'); return true; }, timeoutMs: 50 }); + assert.deepEqual(seen, ['alpha', 'beta']); + assert.deepEqual(plan.mcpToStart, ['alpha']); + assert.deepEqual(plan.mcpUnavailable, ['beta']); + const observed = { mcpStarted: ['alpha'], pluginsStarted: ['example'], permissionPrompt: false, startupTokens: null }; + const receipt = assessRoleLaunch({ plan, observed }); + assert.equal(receipt.status, 'ready'); + assert.equal(receipt.mcpStarted, 1); + assert.deepEqual(receipt.mcpUnavailable, ['beta']); + assert.equal(receipt.startupTokens, null); + assert.equal(assessRoleLaunch({ plan, observed: { ...observed, permissionPrompt: true } }).status, 'rollback-required'); + assert.equal(assessRoleLaunch({ plan, observed: { ...observed, mcpStarted: ['alpha', 'other'] } }).status, 'rollback-required'); + await assert.rejects(planRoleLaunch({ profile: { ...profile, permissions: ['publish'] }, authority, probe: async () => true }), /human-gated/); + await assert.rejects(planRoleLaunch({ profile: { ...profile, mcp: ['other'] }, authority, probe: async () => true }), /exceeds/); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index a93839eb..a53a1007 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -50,6 +50,7 @@ const agentTmuxBundleFiles = [ "bin/codex-compaction-evidence.mjs", "bin/codex-wake-evidence.mjs", "bin/restart-state.mjs", + "bin/role-launch-profile.mjs", "bin/restart-yaml.py", "bin/ledger-view.mjs", "bin/session-catalog.mjs", diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs index 95c26189..12f79a6c 100644 --- a/scripts/plexus-privacy.mjs +++ b/scripts/plexus-privacy.mjs @@ -6,7 +6,7 @@ const privatePatterns = [ ]; export function isPlexusMechanismFile(relativePath) { - return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|codex-(?:compaction|wake)-|module-batches|mesh-(?:graph|channel)|agent-waker|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); + return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|codex-(?:compaction|wake)-|module-batches|mesh-(?:graph|channel)|agent-waker|role-launch-|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); } export function containsPrivatePlexusPolicy(text) { diff --git a/skills/agent-tmux/bin/handover-state-proof.mjs b/skills/agent-tmux/bin/handover-state-proof.mjs index 0c4b17b1..f091917b 100644 --- a/skills/agent-tmux/bin/handover-state-proof.mjs +++ b/skills/agent-tmux/bin/handover-state-proof.mjs @@ -38,7 +38,7 @@ export async function requestStateProof({ session, channel, root, filename, mana if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); if (typeof nonce !== 'string' || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce)) throw new Error('invalid request nonce'); if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); - const message = `Write your handover state with a RIAVVIO YAML block using agent-mesh.restart.v1 to ${join(root, filename)} with private permissions. Bind the block to session ${session} and channel ${channel}, and include harness, working_directory, skills, triggers and goal. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; + const message = `Write your handover state with a RIAVVIO YAML block using agent-mesh.restart.v1 to ${join(root, filename)} with private permissions. Bind the block to session ${session} and channel ${channel}, and include harness, working_directory, skills, triggers, goal and role_profile with schema agent-mesh.role-profile.v1, role and exact identifier lists permissions, mcp, plugins. List only existing grants; do not grant anything. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message-stdin']; if (agent === 'codex') argv.push('--no-resume'); if (agent === 'claude') argv.push('--managed-inbox-root', managedInboxRoot); @@ -71,7 +71,7 @@ export async function verifyStateResponse({ session, channel, nonce, response, r if (decoded.error || decoded.status !== 0) throw new Error('restart YAML unavailable or invalid'); let restart; try { restart = JSON.parse(decoded.stdout); } catch { throw new Error('invalid restart YAML result'); } - validateRestartState(restart, { session, channel }); + validateRestartState(restart, { session, channel, requireRoleProfile: true }); return { schema: attestation.schema, session, nonce, filename, sha256: digest, bytes: bytes.length }; } finally { await file.close(); } } diff --git a/skills/agent-tmux/bin/restart-state.mjs b/skills/agent-tmux/bin/restart-state.mjs index d01ab53d..8cbb5800 100644 --- a/skills/agent-tmux/bin/restart-state.mjs +++ b/skills/agent-tmux/bin/restart-state.mjs @@ -1,14 +1,25 @@ /** Validate a parsed restart block; never execute its instructions. */ const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; const nonempty = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 8192 && !value.includes('\0'); +const profileId = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); -export function validateRestartState(block, { session, channel } = {}) { +export function validateRoleProfile(profile) { + if (!isObject(profile) || Object.keys(profile).sort().join(',') !== 'mcp,permissions,plugins,role,schema' || profile.schema !== 'agent-mesh.role-profile.v1' || !profileId(profile.role)) throw new Error('invalid role profile'); + for (const key of ['permissions', 'mcp', 'plugins']) { + const values = profile[key]; + if (!Array.isArray(values) || values.length > 256 || !values.every(profileId) || new Set(values).size !== values.length) throw new Error(`invalid role profile ${key}`); + } + return true; +} + +export function validateRestartState(block, { session, channel, requireRoleProfile = false } = {}) { if (!isObject(block) || block.schema !== 'agent-mesh.restart.v1') throw new Error('invalid restart schema'); for (const field of ['session', 'channel', 'harness', 'working_directory']) { if (!nonempty(block[field])) throw new Error(`invalid restart ${field}`); } if (session !== undefined && block.session !== session) throw new Error('restart session mismatch'); if (channel !== undefined && block.channel !== channel) throw new Error('restart channel mismatch'); + if (requireRoleProfile || block.role_profile !== undefined) validateRoleProfile(block.role_profile); if (!Array.isArray(block.skills) || block.skills.length > 256 || !block.skills.every(nonempty)) throw new Error('invalid restart skills'); if (!Array.isArray(block.triggers) || block.triggers.length > 256) throw new Error('invalid restart triggers'); const ids = new Set(); diff --git a/skills/agent-tmux/bin/role-launch-profile.mjs b/skills/agent-tmux/bin/role-launch-profile.mjs new file mode 100644 index 00000000..569260b6 --- /dev/null +++ b/skills/agent-tmux/bin/role-launch-profile.mjs @@ -0,0 +1,30 @@ +/** Build a role-scoped launch plan without granting capabilities or starting services. */ +import { validateRoleProfile } from './restart-state.mjs'; + +const id = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const list = value => Array.isArray(value) && value.length <= 256 && value.every(id) && new Set(value).size === value.length; + +export async function planRoleLaunch({ profile, authority, probe, timeoutMs = 3000 }) { + validateRoleProfile(profile); + if (!authority || authority.role !== profile.role || !list(authority.permissions) || !list(authority.mcp) || !list(authority.plugins) || !list(authority.humanGatedPermissions) || typeof probe !== 'function' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new Error('invalid role authority'); + for (const field of ['permissions', 'mcp', 'plugins']) if (profile[field].some(value => !authority[field].includes(value))) throw new Error('role profile exceeds authority'); + if (profile.permissions.some(value => authority.humanGatedPermissions.includes(value))) throw new Error('human-gated permission cannot be pregranted'); + const available = [], unavailable = []; + for (const name of profile.mcp) { + let timer; + try { + const result = await Promise.race([Promise.resolve().then(() => probe(name)), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('unreachable')), timeoutMs); })]); + (result === true ? available : unavailable).push(name); + } catch { unavailable.push(name); } + finally { clearTimeout(timer); } + } + return { schema: 'agent-mesh.role-launch-plan.v1', role: profile.role, permissions: [...profile.permissions], plugins: [...profile.plugins], mcpToStart: available, mcpUnavailable: unavailable }; +} + +/** Assess observed startup; the caller owns rollback and native observation. */ +export function assessRoleLaunch({ plan, observed }) { + if (!plan || plan.schema !== 'agent-mesh.role-launch-plan.v1' || !list(plan.permissions) || !list(plan.plugins) || !list(plan.mcpToStart) || !list(plan.mcpUnavailable) || !observed || !list(observed.mcpStarted) || !list(observed.pluginsStarted) || typeof observed.permissionPrompt !== 'boolean' || !(observed.startupTokens === null || (Number.isSafeInteger(observed.startupTokens) && observed.startupTokens >= 0))) throw new Error('invalid launch observation'); + const unexpected = observed.mcpStarted.some(value => !plan.mcpToStart.includes(value)) || observed.pluginsStarted.some(value => !plan.plugins.includes(value)); + const failed = observed.permissionPrompt || unexpected; + return { schema: 'agent-mesh.role-launch-receipt.v1', status: failed ? 'rollback-required' : 'ready', reason: observed.permissionPrompt ? 'unexpected-permission' : unexpected ? 'unexpected-component' : null, mcpStarted: observed.mcpStarted.length, mcpUnavailable: [...new Set([...plan.mcpUnavailable, ...plan.mcpToStart.filter(value => !observed.mcpStarted.includes(value))])], startupTokens: observed.startupTokens }; +} From 94326660f1719fd71f6c09fe6de7f4e9b3b7cda0 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:50:11 +0000 Subject: [PATCH 056/113] Prepare wake reconciliation draft --- .../tmux-bridge/bin/codex-wake-evidence.mjs | 45 ++++++++++++++++++- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index fa63bc03..1454a0fa 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -27,6 +27,46 @@ async function createDurable(root, name, body) { try { await directory.sync(); } finally { await directory.close(); } } +async function readIntent(root, session, queueId, correlation) { + const path = join(root, `intent-${hash(JSON.stringify([session, queueId]))}.json`); + const fd = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + try { + const before = await fd.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid intent'); + const body = await fd.readFile('utf8'), after = await fd.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || body !== `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`) throw new Error('intent mismatch'); + } finally { await fd.close(); } +} + +// Reconcile only from a completed readback; never start or resume a thread. +export async function reconcileCodexWake({ channel, graphState, evidenceRoot, apply }) { + if (apply !== true || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit recovery scope required'); + await privateRoot(graphState); await privateRoot(evidenceRoot); + const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); + let state; try { state = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } + const reservation = state?.wakeReservation; + if (result.error || result.status !== 0 || state?.phase !== 'active' || !reservation || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); + const { session, id: correlation, nativeQueueId: queueId, generation } = reservation; + const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string'); + if (items.length !== 1) throw new Error('wake item unavailable'); + await readIntent(evidenceRoot, session, queueId, correlation); + const thread = session.slice(6); + const observed = await withCodexAppServer({ clientName: 'agent-mesh-wake-reconcile', timeout: 30000, timeoutMessage: 'native read unavailable' }, request => request('thread/read', { threadId: thread, includeTurns: true })); + if (observed?.thread?.id !== thread || !Array.isArray(observed.thread.turns)) throw new Error('native read unavailable'); + const matching = []; + for (const turn of observed.thread.turns) { + if (!Array.isArray(turn.items) || (turn.itemsView !== undefined && turn.itemsView !== 'full')) throw new Error('incomplete native read'); + for (const item of turn.items) if (item?.type === 'userMessage' && item.clientId === correlation) matching.push({ turn, item }); + } + const candidate = matching[0]; + if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('wake readback not uniquely verified'); + const evidence = { schema: 'agent-mesh.codex-wake-evidence.v2', source: 'codex-app-server.queue-start-readback', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt }; + const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; + try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } + catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } + return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); +} + export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { if (typeof reference !== 'string' || !/^codex-wake:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid wake verification request'); await privateRoot(evidenceRoot); @@ -102,9 +142,10 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { try { - const { values } = parseArgs({ options: { apply: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, reconcile: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); let result; - if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); + if (values.reconcile) result = await reconcileCodexWake({ channel: values.channel, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + else if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'], channel: values.channel }); else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, channel: values.channel, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); console.log(JSON.stringify(result)); From 35338cb3fcea44927dff8f566dc54196e04e645d Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:52:31 +0000 Subject: [PATCH 057/113] Verify correlated wake recovery from native readback --- docs/design/plexus-modules.md | 9 ++-- .../tmux-bridge/bin/codex-wake-evidence.mjs | 4 +- .../test/codex-wake-evidence.test.mjs | 21 +++++++-- skills/agent-tmux/bin/codex-wake-evidence.mjs | 47 +++++++++++++++++-- 4 files changed, 68 insertions(+), 13 deletions(-) diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md index e70cc99c..9e52a4a1 100644 --- a/docs/design/plexus-modules.md +++ b/docs/design/plexus-modules.md @@ -52,9 +52,12 @@ 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. A crash before that -point stays unresolved; there is no automatic retry or recovery for an -unproven native outcome. This path is not ready for operational use. +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 diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index 1454a0fa..39ceb3ae 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -60,7 +60,7 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap } const candidate = matching[0]; if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('wake readback not uniquely verified'); - const evidence = { schema: 'agent-mesh.codex-wake-evidence.v2', source: 'codex-app-server.queue-start-readback', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt }; + const evidence = { schema: 'agent-mesh.codex-wake-evidence.v3', source: 'codex-app-server.correlated-recovery', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt }; const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } @@ -82,7 +82,7 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); let value; try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } - if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-wake-evidence.v2' || value.source !== 'codex-app-server.queue-start-readback' || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || !((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index e795b8bc..0bc28aaa 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -37,9 +37,9 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const server = createAppServer((request, peer) => { if (!request.id) return; requests.push(request); - if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: 'fixture' }] }], nextCursor: null } }); + if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: 'fixture', text_elements: [] }] }], nextCursor: null } }); else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: 123456789, items: [] } } }); - else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, startedAt: mode === 'wrong-time' ? 123456788 : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture' }] }] }] } } }); + else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, status: 'completed', startedAt: mode === 'wrong-time' ? 123456788 : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture', text_elements: [] }] }] }] } } }); else peer.send({ id: request.id, result: {} }); }); await new Promise(resolve => server.listen(socket, resolve)); @@ -86,8 +86,19 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const starts = requests.filter(r => r.method === 'thread/queue/start').length; await assert.rejects(exec(process.execPath, [bin, '--apply', ...uncertainArgs], { env })); assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, starts); + const recoverArgs = ['--reconcile', '--channel', 'uncertain', '--evidence-root', uncertainRoot, '--graph-state', state]; + await assert.rejects(exec(process.execPath, [bin, ...recoverArgs], { env })); + mode = 'wrong-client'; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...recoverArgs], { env })); + assert.ok((await call('channel', 'get', '--name', 'uncertain')).channel.wakeReservation); + mode = 'success'; + const recovered = JSON.parse((await exec(process.execPath, [bin, '--apply', ...recoverArgs], { env })).stdout); + assert.equal(recovered.settled, true); + assert.equal((await verifyCodexWakeEvidence({ evidenceRoot: uncertainRoot, reference: recovered.evidence, session })).source, 'codex-app-server.correlated-recovery'); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, starts); + assert.equal((await call('channel', 'get', '--name', 'uncertain')).channel.wakeReservation, undefined); const uncertainFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); - assert.equal(uncertainFeed.events.filter(e => e.type === 'session.woken').length, 1); + assert.equal(uncertainFeed.events.filter(e => e.type === 'session.woken').length, 2); const partialRoot = join(root, 'partial'); await mkdir(partialRoot, { mode: 0o700 }); nativeId = 'queued-partial'; await prepareChannel('partial', nativeId); const partialArgs = ['--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'partial', '--generation', '1', '--evidence-root', partialRoot, '--graph-state', state]; @@ -95,7 +106,7 @@ test('queued wake needs explicit apply, a native start and durable correlated pr await assert.rejects(exec(process.execPath, [bin, '--apply', ...partialArgs], { env })); assert.deepEqual((await readdir(partialRoot)).map(name => name.split('-')[0]), ['intent']); const partialFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); - assert.equal(partialFeed.events.filter(e => e.type === 'session.woken').length, 1); + assert.equal(partialFeed.events.filter(e => e.type === 'session.woken').length, 2); for (const mismatch of ['wrong-thread', 'wrong-turn', 'wrong-time', 'wrong-client', 'wrong-input']) { const mismatchRoot = join(root, mismatch); await mkdir(mismatchRoot, { mode: 0o700 }); nativeId = `queued-${mismatch}`; await prepareChannel(mismatch, nativeId); @@ -105,7 +116,7 @@ test('queued wake needs explicit apply, a native start and durable correlated pr assert.deepEqual((await readdir(mismatchRoot)).map(name => name.split('-')[0]), ['intent']); } const mismatchFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); - assert.equal(mismatchFeed.events.filter(e => e.type === 'session.woken').length, 1); + assert.equal(mismatchFeed.events.filter(e => e.type === 'session.woken').length, 2); const file = join(evidence, `wake-${first.evidence.slice('codex-wake:'.length)}.json`); const saved = JSON.parse(await readFile(file, 'utf8')); saved.startedAt++; await writeFile(file, `${JSON.stringify(saved)}\n`); diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index fa63bc03..39ceb3ae 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -27,6 +27,46 @@ async function createDurable(root, name, body) { try { await directory.sync(); } finally { await directory.close(); } } +async function readIntent(root, session, queueId, correlation) { + const path = join(root, `intent-${hash(JSON.stringify([session, queueId]))}.json`); + const fd = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + try { + const before = await fd.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid intent'); + const body = await fd.readFile('utf8'), after = await fd.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || body !== `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`) throw new Error('intent mismatch'); + } finally { await fd.close(); } +} + +// Reconcile only from a completed readback; never start or resume a thread. +export async function reconcileCodexWake({ channel, graphState, evidenceRoot, apply }) { + if (apply !== true || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit recovery scope required'); + await privateRoot(graphState); await privateRoot(evidenceRoot); + const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); + let state; try { state = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } + const reservation = state?.wakeReservation; + if (result.error || result.status !== 0 || state?.phase !== 'active' || !reservation || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); + const { session, id: correlation, nativeQueueId: queueId, generation } = reservation; + const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string'); + if (items.length !== 1) throw new Error('wake item unavailable'); + await readIntent(evidenceRoot, session, queueId, correlation); + const thread = session.slice(6); + const observed = await withCodexAppServer({ clientName: 'agent-mesh-wake-reconcile', timeout: 30000, timeoutMessage: 'native read unavailable' }, request => request('thread/read', { threadId: thread, includeTurns: true })); + if (observed?.thread?.id !== thread || !Array.isArray(observed.thread.turns)) throw new Error('native read unavailable'); + const matching = []; + for (const turn of observed.thread.turns) { + if (!Array.isArray(turn.items) || (turn.itemsView !== undefined && turn.itemsView !== 'full')) throw new Error('incomplete native read'); + for (const item of turn.items) if (item?.type === 'userMessage' && item.clientId === correlation) matching.push({ turn, item }); + } + const candidate = matching[0]; + if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('wake readback not uniquely verified'); + const evidence = { schema: 'agent-mesh.codex-wake-evidence.v3', source: 'codex-app-server.correlated-recovery', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt }; + const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; + try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } + catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } + return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); +} + export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { if (typeof reference !== 'string' || !/^codex-wake:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid wake verification request'); await privateRoot(evidenceRoot); @@ -42,7 +82,7 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); let value; try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } - if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-wake-evidence.v2' || value.source !== 'codex-app-server.queue-start-readback' || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || !((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } @@ -102,9 +142,10 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { try { - const { values } = parseArgs({ options: { apply: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, reconcile: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); let result; - if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); + if (values.reconcile) result = await reconcileCodexWake({ channel: values.channel, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + else if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'], channel: values.channel }); else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, channel: values.channel, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); console.log(JSON.stringify(result)); From aa67d061297952a0a4ab822908c9bb5de06e1938 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:56:33 +0000 Subject: [PATCH 058/113] Rehearse role handover faults in memory --- docs/design/plexus-architecture.mmd | 3 +++ docs/design/plexus-channels.md | 5 ++++ packages/tmux-bridge/bin/handover-dry-run.mjs | 18 +++++++++++++ .../test/handover-dry-run.test.mjs | 26 +++++++++++++++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-diagram.mjs | 3 +++ skills/agent-tmux/bin/handover-dry-run.mjs | 18 +++++++++++++ 7 files changed, 74 insertions(+) create mode 100644 packages/tmux-bridge/bin/handover-dry-run.mjs create mode 100644 packages/tmux-bridge/test/handover-dry-run.test.mjs create mode 100644 skills/agent-tmux/bin/handover-dry-run.mjs diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 20111842..575aa838 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -13,6 +13,9 @@ flowchart LR 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 -. "planned runtime launch" .-> Handover StatePrep --> Journal StatePrep -. "planned proof revalidation" .-> Handover TriggerTxn["Trigger transaction engine"] --> TriggerJournal["Private trigger journal"] diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 6514facb..8b552127 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -110,3 +110,8 @@ requires rollback. These are preparation primitives only: no provider startup, permission enforcement, timeout cancellation, live rollback or token collector is connected yet. The approved handover remains disabled until native evidence and those adapters are present. + +`handover-dry-run.mjs` rehearses only in memory; it never contacts native +sessions, MCPs or timers. Its synthetic fault tests cover two roles, offline MCP, +permission prompt, interrupted start, quota exhaustion and a queued message. +It does not verify native delivery, rollback or the real pilot. diff --git a/packages/tmux-bridge/bin/handover-dry-run.mjs b/packages/tmux-bridge/bin/handover-dry-run.mjs new file mode 100644 index 00000000..f1a5b747 --- /dev/null +++ b/packages/tmux-bridge/bin/handover-dry-run.mjs @@ -0,0 +1,18 @@ +/** In-memory rehearsal only. No native session, service, timer or graph is changed. */ +import { beginHandover, createChannel, enqueue, finishHandover } from './channel-state.mjs'; +import { planRoleLaunch, assessRoleLaunch } from './role-launch-profile.mjs'; + +export async function rehearseHandover({ role, oldSession, newSession, profile, authority, offlineMcp = [], fault = 'none', messageDuringHandover = false }) { + if (typeof role !== 'string' || profile?.role !== role || !['none', 'interrupted', 'quota', 'permission'].includes(fault) || !Array.isArray(offlineMcp) || !offlineMcp.every(name => typeof name === 'string') || typeof messageDuringHandover !== 'boolean') throw new Error('invalid rehearsal'); + let channel = beginHandover(createChannel(`fixture-${role}`, oldSession)); + if (messageDuringHandover) channel = enqueue(channel, 'fixture-message', 'synthetic message'); + const plan = await planRoleLaunch({ profile, authority, probe: async name => !offlineMcp.includes(name) }); + const observed = { mcpStarted: [...plan.mcpToStart], pluginsStarted: [...plan.plugins], permissionPrompt: fault === 'permission', startupTokens: null }; + const launch = assessRoleLaunch({ plan, observed }); + if (fault === 'interrupted' || fault === 'quota' || launch.status !== 'ready') { + channel = { ...channel, phase: 'active' }; + return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'rolled-back', reason: fault === 'none' ? launch.reason : fault, channel, launch }; + } + channel = finishHandover(channel, newSession, true); + return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'switched', reason: null, channel, launch }; +} diff --git a/packages/tmux-bridge/test/handover-dry-run.test.mjs b/packages/tmux-bridge/test/handover-dry-run.test.mjs new file mode 100644 index 00000000..0b20cfb1 --- /dev/null +++ b/packages/tmux-bridge/test/handover-dry-run.test.mjs @@ -0,0 +1,26 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { rehearseHandover } from '../bin/handover-dry-run.mjs'; + +const role = name => ({ role: name, oldSession: `codex:${name}-old`, newSession: `codex:${name}-new`, profile: { schema: 'agent-mesh.role-profile.v1', role: name, permissions: ['read'], mcp: ['core', 'optional'], plugins: ['plugin'] }, authority: { role: name, permissions: ['read'], humanGatedPermissions: ['external'], mcp: ['core', 'optional'], plugins: ['plugin'] } }); + +test('two synthetic roles preserve messages and rollback on isolated faults', async () => { + for (const name of ['one', 'two']) { + const fixture = role(name); + const offline = await rehearseHandover({ ...fixture, offlineMcp: ['optional'], messageDuringHandover: true }); + assert.equal(offline.simulated, true); + assert.equal(offline.outcome, 'switched'); + assert.equal(offline.channel.session, fixture.newSession); + assert.equal(offline.channel.queue[0].state, 'pending'); + assert.equal(offline.launch.mcpStarted, 1); + assert.deepEqual(offline.launch.mcpUnavailable, ['optional']); + assert.equal(offline.launch.startupTokens, null); + for (const fault of ['permission', 'interrupted', 'quota']) { + const result = await rehearseHandover({ ...fixture, fault, messageDuringHandover: true }); + assert.equal(result.outcome, 'rolled-back'); + assert.equal(result.channel.session, fixture.oldSession); + assert.equal(result.channel.phase, 'active'); + assert.equal(result.channel.queue[0].state, 'pending'); + } + } +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index a53a1007..c44d3d46 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -46,6 +46,7 @@ const agentTmuxBundleFiles = [ "bin/channel-state.mjs", "bin/handover-state-proof.mjs", "bin/handover-notice.mjs", + "bin/handover-dry-run.mjs", "bin/handover-codex-observation.mjs", "bin/codex-compaction-evidence.mjs", "bin/codex-wake-evidence.mjs", diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 2042a79f..5ff41fd8 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -14,6 +14,9 @@ export const plexusDiagram = `flowchart LR 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 -. "planned runtime launch" .-> Handover StatePrep --> Journal StatePrep -. "planned proof revalidation" .-> Handover TriggerTxn["Trigger transaction engine"] --> TriggerJournal["Private trigger journal"] diff --git a/skills/agent-tmux/bin/handover-dry-run.mjs b/skills/agent-tmux/bin/handover-dry-run.mjs new file mode 100644 index 00000000..f1a5b747 --- /dev/null +++ b/skills/agent-tmux/bin/handover-dry-run.mjs @@ -0,0 +1,18 @@ +/** In-memory rehearsal only. No native session, service, timer or graph is changed. */ +import { beginHandover, createChannel, enqueue, finishHandover } from './channel-state.mjs'; +import { planRoleLaunch, assessRoleLaunch } from './role-launch-profile.mjs'; + +export async function rehearseHandover({ role, oldSession, newSession, profile, authority, offlineMcp = [], fault = 'none', messageDuringHandover = false }) { + if (typeof role !== 'string' || profile?.role !== role || !['none', 'interrupted', 'quota', 'permission'].includes(fault) || !Array.isArray(offlineMcp) || !offlineMcp.every(name => typeof name === 'string') || typeof messageDuringHandover !== 'boolean') throw new Error('invalid rehearsal'); + let channel = beginHandover(createChannel(`fixture-${role}`, oldSession)); + if (messageDuringHandover) channel = enqueue(channel, 'fixture-message', 'synthetic message'); + const plan = await planRoleLaunch({ profile, authority, probe: async name => !offlineMcp.includes(name) }); + const observed = { mcpStarted: [...plan.mcpToStart], pluginsStarted: [...plan.plugins], permissionPrompt: fault === 'permission', startupTokens: null }; + const launch = assessRoleLaunch({ plan, observed }); + if (fault === 'interrupted' || fault === 'quota' || launch.status !== 'ready') { + channel = { ...channel, phase: 'active' }; + return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'rolled-back', reason: fault === 'none' ? launch.reason : fault, channel, launch }; + } + channel = finishHandover(channel, newSession, true); + return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'switched', reason: null, channel, launch }; +} From 1b138e88d9e8c891dc397cc67a846e0eb63f4c7a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:01:25 +0000 Subject: [PATCH 059/113] Probe allowlisted role MCP servers --- docs/design/plexus-channels.md | 8 +++ packages/tmux-bridge/bin/role-mcp-probe.mjs | 56 +++++++++++++++++++ .../tmux-bridge/test/role-mcp-probe.test.mjs | 22 ++++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-privacy.mjs | 2 +- skills/agent-tmux/bin/role-mcp-probe.mjs | 56 +++++++++++++++++++ 6 files changed, 144 insertions(+), 1 deletion(-) create mode 100644 packages/tmux-bridge/bin/role-mcp-probe.mjs create mode 100644 packages/tmux-bridge/test/role-mcp-probe.test.mjs create mode 100644 skills/agent-tmux/bin/role-mcp-probe.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 8b552127..fcf52e71 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -115,3 +115,11 @@ and those adapters are present. sessions, MCPs or timers. Its synthetic fault tests cover two roles, offline MCP, permission prompt, interrupted start, quota exhaustion and a queued message. It does not verify native delivery, rollback or the real pilot. + +An optional stdio probe resolves MCP names exclusively through a trusted +operator-supplied allowlist and launches a short-lived isolated process without +a shell. It requires an MCP initialization response and ping, bounds output +and time, and terminates its process group. It currently supports protocol +`2024-11-05` only and has been tested with synthetic processes; successful +probing does not prove that an MCP started in the successor session. It is not +scheduled or wired to the live handover. diff --git a/packages/tmux-bridge/bin/role-mcp-probe.mjs b/packages/tmux-bridge/bin/role-mcp-probe.mjs new file mode 100644 index 00000000..93b0899c --- /dev/null +++ b/packages/tmux-bridge/bin/role-mcp-probe.mjs @@ -0,0 +1,56 @@ +/** Probe one operator-authorized stdio MCP in its own process group. */ +import { spawn } from 'node:child_process'; +import { isAbsolute } from 'node:path'; + +export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { + if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw new Error('invalid MCP allowlist'); + return name => { + if (typeof name !== 'string' || !Object.hasOwn(allowlist, name)) throw new Error('MCP is not allowlisted'); + const entry = allowlist[name]; + if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error('invalid MCP allowlist entry'); + return probeStdioMcp({ command: entry.command, env: entry.env, timeoutMs }); + }; +} + +// The profile contains identifiers only. Callers must resolve them using a +// trusted private allowlist; never construct this command from session text. +export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000 }) { + if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new Error('invalid MCP probe configuration'); + return new Promise(resolve => { + let child, timer, buffer = '', phase = 'initialize', finished = false; + const finish = result => { + if (finished) return; + finished = true; clearTimeout(timer); + if (child?.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } + resolve(result); + }; + try { child = spawn(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } + catch { finish(false); return; } + timer = setTimeout(() => finish(false), timeoutMs); + child.once('error', () => finish(false)); + child.once('close', () => finish(false)); + child.stdin.on('error', () => finish(false)); + child.stdout.setEncoding('utf8'); + const write = message => child.stdin.write(`${JSON.stringify(message)}\n`); + child.stdout.on('data', data => { + if (finished) return; + buffer += data; + if (Buffer.byteLength(buffer) > 1024 * 1024) return finish(false); + let index; + while (!finished && (index = buffer.indexOf('\n')) >= 0) { + const line = buffer.slice(0, index); buffer = buffer.slice(index + 1); + let reply; try { reply = JSON.parse(line); } catch { return finish(false); } + if (reply?.jsonrpc !== '2.0') return finish(false); + if (phase === 'initialize' && reply.id === 1) { + if (reply.error || !reply.result || reply.result.protocolVersion !== '2024-11-05' || !reply.result.capabilities || typeof reply.result.capabilities !== 'object' || Array.isArray(reply.result.capabilities) || typeof reply.result.serverInfo?.name !== 'string' || !reply.result.serverInfo.name || typeof reply.result.serverInfo.version !== 'string' || !reply.result.serverInfo.version) return finish(false); + phase = 'ping'; + write({ jsonrpc: '2.0', method: 'notifications/initialized' }); + write({ jsonrpc: '2.0', id: 2, method: 'ping', params: {} }); + } else if (phase === 'ping' && reply.id === 2) { + finish(!reply.error && !!reply.result && typeof reply.result === 'object' && !Array.isArray(reply.result)); + } else if (reply.id !== undefined) return finish(false); + } + }); + write({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'role-profile-probe', version: '1' } } }); + }); +} diff --git a/packages/tmux-bridge/test/role-mcp-probe.test.mjs b/packages/tmux-bridge/test/role-mcp-probe.test.mjs new file mode 100644 index 00000000..20a2e544 --- /dev/null +++ b/packages/tmux-bridge/test/role-mcp-probe.test.mjs @@ -0,0 +1,22 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { probeStdioMcp, roleProbeFromAllowlist } from '../bin/role-mcp-probe.mjs'; +import { planRoleLaunch } from '../bin/role-launch-profile.mjs'; + +const fixture = `let buffer = ''; process.stdin.setEncoding('utf8'); process.stdin.on('data', data => { buffer += data; let index; while ((index = buffer.indexOf('\\n')) >= 0) { const line = buffer.slice(0, index); buffer = buffer.slice(index + 1); const request = JSON.parse(line); if (request.method === 'initialize') console.log(JSON.stringify({jsonrpc:'2.0',id:1,result:{protocolVersion:'2024-11-05',capabilities:{},serverInfo:{name:'fixture',version:'1'}}})); if (request.method === 'ping') console.log(JSON.stringify({jsonrpc:'2.0',id:2,result:{}})); } });`; + +test('only an initialized and responsive MCP is accepted by role planning', async () => { + const good = { command: [process.execPath, '--input-type=module', '-e', fixture], timeoutMs: 2000 }; + const offline = { command: [process.execPath, '--input-type=module', '-e', 'setInterval(() => {}, 1000)'], timeoutMs: 150 }; + assert.equal(await probeStdioMcp(good), true); + assert.equal(await probeStdioMcp(offline), false); + const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['good', 'offline'], plugins: [] }; + const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['good', 'offline'], plugins: [] }; + const allowlist = { good, offline }; + const probe = roleProbeFromAllowlist(allowlist, 1000); + const plan = await planRoleLaunch({ profile, authority, probe, timeoutMs: 3000 }); + assert.deepEqual(plan.mcpToStart, ['good']); + assert.deepEqual(plan.mcpUnavailable, ['offline']); + assert.throws(() => probe('unlisted'), /allowlisted/); + await assert.rejects(probeStdioMcp({ command: ['relative-program'] }), /configuration/); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index c44d3d46..e1c9e44f 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -52,6 +52,7 @@ const agentTmuxBundleFiles = [ "bin/codex-wake-evidence.mjs", "bin/restart-state.mjs", "bin/role-launch-profile.mjs", + "bin/role-mcp-probe.mjs", "bin/restart-yaml.py", "bin/ledger-view.mjs", "bin/session-catalog.mjs", diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs index 12f79a6c..b374923b 100644 --- a/scripts/plexus-privacy.mjs +++ b/scripts/plexus-privacy.mjs @@ -6,7 +6,7 @@ const privatePatterns = [ ]; export function isPlexusMechanismFile(relativePath) { - return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|codex-(?:compaction|wake)-|module-batches|mesh-(?:graph|channel)|agent-waker|role-launch-|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); + return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|codex-(?:compaction|wake)-|module-batches|mesh-(?:graph|channel)|agent-waker|role-(?:launch|mcp)-|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); } export function containsPrivatePlexusPolicy(text) { diff --git a/skills/agent-tmux/bin/role-mcp-probe.mjs b/skills/agent-tmux/bin/role-mcp-probe.mjs new file mode 100644 index 00000000..93b0899c --- /dev/null +++ b/skills/agent-tmux/bin/role-mcp-probe.mjs @@ -0,0 +1,56 @@ +/** Probe one operator-authorized stdio MCP in its own process group. */ +import { spawn } from 'node:child_process'; +import { isAbsolute } from 'node:path'; + +export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { + if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw new Error('invalid MCP allowlist'); + return name => { + if (typeof name !== 'string' || !Object.hasOwn(allowlist, name)) throw new Error('MCP is not allowlisted'); + const entry = allowlist[name]; + if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error('invalid MCP allowlist entry'); + return probeStdioMcp({ command: entry.command, env: entry.env, timeoutMs }); + }; +} + +// The profile contains identifiers only. Callers must resolve them using a +// trusted private allowlist; never construct this command from session text. +export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000 }) { + if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new Error('invalid MCP probe configuration'); + return new Promise(resolve => { + let child, timer, buffer = '', phase = 'initialize', finished = false; + const finish = result => { + if (finished) return; + finished = true; clearTimeout(timer); + if (child?.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } + resolve(result); + }; + try { child = spawn(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } + catch { finish(false); return; } + timer = setTimeout(() => finish(false), timeoutMs); + child.once('error', () => finish(false)); + child.once('close', () => finish(false)); + child.stdin.on('error', () => finish(false)); + child.stdout.setEncoding('utf8'); + const write = message => child.stdin.write(`${JSON.stringify(message)}\n`); + child.stdout.on('data', data => { + if (finished) return; + buffer += data; + if (Buffer.byteLength(buffer) > 1024 * 1024) return finish(false); + let index; + while (!finished && (index = buffer.indexOf('\n')) >= 0) { + const line = buffer.slice(0, index); buffer = buffer.slice(index + 1); + let reply; try { reply = JSON.parse(line); } catch { return finish(false); } + if (reply?.jsonrpc !== '2.0') return finish(false); + if (phase === 'initialize' && reply.id === 1) { + if (reply.error || !reply.result || reply.result.protocolVersion !== '2024-11-05' || !reply.result.capabilities || typeof reply.result.capabilities !== 'object' || Array.isArray(reply.result.capabilities) || typeof reply.result.serverInfo?.name !== 'string' || !reply.result.serverInfo.name || typeof reply.result.serverInfo.version !== 'string' || !reply.result.serverInfo.version) return finish(false); + phase = 'ping'; + write({ jsonrpc: '2.0', method: 'notifications/initialized' }); + write({ jsonrpc: '2.0', id: 2, method: 'ping', params: {} }); + } else if (phase === 'ping' && reply.id === 2) { + finish(!reply.error && !!reply.result && typeof reply.result === 'object' && !Array.isArray(reply.result)); + } else if (reply.id !== undefined) return finish(false); + } + }); + write({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'role-profile-probe', version: '1' } } }); + }); +} From 737cac2d8b8cbd70c561178df3fb63169cd4c9ba Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:06:30 +0000 Subject: [PATCH 060/113] Cancel temporary MCP probes on deadline --- docs/design/plexus-channels.md | 4 ++- .../tmux-bridge/bin/role-launch-profile.mjs | 6 ++-- packages/tmux-bridge/bin/role-mcp-probe.mjs | 14 ++++++--- .../tmux-bridge/test/role-mcp-probe.test.mjs | 30 +++++++++++++++++++ skills/agent-tmux/bin/role-launch-profile.mjs | 6 ++-- skills/agent-tmux/bin/role-mcp-probe.mjs | 14 ++++++--- 6 files changed, 59 insertions(+), 15 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index fcf52e71..97386ce2 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -122,4 +122,6 @@ a shell. It requires an MCP initialization response and ping, bounds output and time, and terminates its process group. It currently supports protocol `2024-11-05` only and has been tested with synthetic processes; successful probing does not prove that an MCP started in the successor session. It is not -scheduled or wired to the live handover. +scheduled or wired to the live handover. Planner deadlines signal cancellation; +the supplied stdio probe terminates its process group on that signal. Other +probe implementations must honor cancellation themselves. diff --git a/packages/tmux-bridge/bin/role-launch-profile.mjs b/packages/tmux-bridge/bin/role-launch-profile.mjs index 569260b6..820979c6 100644 --- a/packages/tmux-bridge/bin/role-launch-profile.mjs +++ b/packages/tmux-bridge/bin/role-launch-profile.mjs @@ -11,12 +11,12 @@ export async function planRoleLaunch({ profile, authority, probe, timeoutMs = 30 if (profile.permissions.some(value => authority.humanGatedPermissions.includes(value))) throw new Error('human-gated permission cannot be pregranted'); const available = [], unavailable = []; for (const name of profile.mcp) { - let timer; + let timer; const controller = new AbortController(); try { - const result = await Promise.race([Promise.resolve().then(() => probe(name)), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('unreachable')), timeoutMs); })]); + const result = await Promise.race([Promise.resolve().then(() => probe(name, { signal: controller.signal })), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('unreachable')); }, timeoutMs); })]); (result === true ? available : unavailable).push(name); } catch { unavailable.push(name); } - finally { clearTimeout(timer); } + finally { clearTimeout(timer); controller.abort(); } } return { schema: 'agent-mesh.role-launch-plan.v1', role: profile.role, permissions: [...profile.permissions], plugins: [...profile.plugins], mcpToStart: available, mcpUnavailable: unavailable }; } diff --git a/packages/tmux-bridge/bin/role-mcp-probe.mjs b/packages/tmux-bridge/bin/role-mcp-probe.mjs index 93b0899c..f20da427 100644 --- a/packages/tmux-bridge/bin/role-mcp-probe.mjs +++ b/packages/tmux-bridge/bin/role-mcp-probe.mjs @@ -4,29 +4,35 @@ import { isAbsolute } from 'node:path'; export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw new Error('invalid MCP allowlist'); - return name => { + return (name, { signal } = {}) => { if (typeof name !== 'string' || !Object.hasOwn(allowlist, name)) throw new Error('MCP is not allowlisted'); const entry = allowlist[name]; if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error('invalid MCP allowlist entry'); - return probeStdioMcp({ command: entry.command, env: entry.env, timeoutMs }); + return probeStdioMcp({ command: entry.command, env: entry.env, timeoutMs, signal }); }; } // The profile contains identifiers only. Callers must resolve them using a // trusted private allowlist; never construct this command from session text. -export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000 }) { - if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new Error('invalid MCP probe configuration'); +export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal }) { + if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw new Error('invalid MCP probe configuration'); return new Promise(resolve => { let child, timer, buffer = '', phase = 'initialize', finished = false; + let onAbort; const finish = result => { if (finished) return; finished = true; clearTimeout(timer); + if (signal && onAbort) signal.removeEventListener('abort', onAbort); if (child?.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } resolve(result); }; + if (signal?.aborted) { finish(false); return; } try { child = spawn(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } catch { finish(false); return; } timer = setTimeout(() => finish(false), timeoutMs); + onAbort = () => finish(false); + signal?.addEventListener('abort', onAbort, { once: true }); + if (signal?.aborted) { finish(false); return; } child.once('error', () => finish(false)); child.once('close', () => finish(false)); child.stdin.on('error', () => finish(false)); diff --git a/packages/tmux-bridge/test/role-mcp-probe.test.mjs b/packages/tmux-bridge/test/role-mcp-probe.test.mjs index 20a2e544..284ea972 100644 --- a/packages/tmux-bridge/test/role-mcp-probe.test.mjs +++ b/packages/tmux-bridge/test/role-mcp-probe.test.mjs @@ -1,5 +1,8 @@ import assert from 'node:assert/strict'; import test from 'node:test'; +import { mkdtemp, access, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; import { probeStdioMcp, roleProbeFromAllowlist } from '../bin/role-mcp-probe.mjs'; import { planRoleLaunch } from '../bin/role-launch-profile.mjs'; @@ -20,3 +23,30 @@ test('only an initialized and responsive MCP is accepted by role planning', asyn assert.throws(() => probe('unlisted'), /allowlisted/); await assert.rejects(probeStdioMcp({ command: ['relative-program'] }), /configuration/); }); + +test('a cancelled probe terminates its temporary MCP process', async t => { + const root = await mkdtemp(join(tmpdir(), 'mcp-cancel-')); + t.after(() => rm(root, { recursive: true, force: true })); + const started = join(root, 'started'), late = join(root, 'late'); + const code = "import {writeFileSync} from 'node:fs'; writeFileSync(process.argv[1], 'ok'); setTimeout(() => writeFileSync(process.argv[2], 'late'), 500); setInterval(() => {}, 1000);"; + const controller = new AbortController(); + const probe = probeStdioMcp({ command: [process.execPath, '--input-type=module', '-e', code, started, late], timeoutMs: 2000, signal: controller.signal }); + let seen = false; + for (let i = 0; i < 100 && !seen; i++) { + try { await access(started); seen = true; } catch { await new Promise(resolve => setTimeout(resolve, 10)); } + } + assert.equal(seen, true, 'fixture process started'); + controller.abort(); + assert.equal(await probe, false); + await new Promise(resolve => setTimeout(resolve, 600)); + await assert.rejects(access(late)); +}); + +test('planner aborts its trusted probe when its deadline expires', async () => { + const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['slow'], plugins: [] }; + const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['slow'], plugins: [] }; + let aborted = false; + const plan = await planRoleLaunch({ profile, authority, timeoutMs: 20, probe: (_name, { signal }) => new Promise(resolve => signal.addEventListener('abort', () => { aborted = true; resolve(false); }, { once: true })) }); + assert.equal(aborted, true); + assert.deepEqual(plan.mcpUnavailable, ['slow']); +}); diff --git a/skills/agent-tmux/bin/role-launch-profile.mjs b/skills/agent-tmux/bin/role-launch-profile.mjs index 569260b6..820979c6 100644 --- a/skills/agent-tmux/bin/role-launch-profile.mjs +++ b/skills/agent-tmux/bin/role-launch-profile.mjs @@ -11,12 +11,12 @@ export async function planRoleLaunch({ profile, authority, probe, timeoutMs = 30 if (profile.permissions.some(value => authority.humanGatedPermissions.includes(value))) throw new Error('human-gated permission cannot be pregranted'); const available = [], unavailable = []; for (const name of profile.mcp) { - let timer; + let timer; const controller = new AbortController(); try { - const result = await Promise.race([Promise.resolve().then(() => probe(name)), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('unreachable')), timeoutMs); })]); + const result = await Promise.race([Promise.resolve().then(() => probe(name, { signal: controller.signal })), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('unreachable')); }, timeoutMs); })]); (result === true ? available : unavailable).push(name); } catch { unavailable.push(name); } - finally { clearTimeout(timer); } + finally { clearTimeout(timer); controller.abort(); } } return { schema: 'agent-mesh.role-launch-plan.v1', role: profile.role, permissions: [...profile.permissions], plugins: [...profile.plugins], mcpToStart: available, mcpUnavailable: unavailable }; } diff --git a/skills/agent-tmux/bin/role-mcp-probe.mjs b/skills/agent-tmux/bin/role-mcp-probe.mjs index 93b0899c..f20da427 100644 --- a/skills/agent-tmux/bin/role-mcp-probe.mjs +++ b/skills/agent-tmux/bin/role-mcp-probe.mjs @@ -4,29 +4,35 @@ import { isAbsolute } from 'node:path'; export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw new Error('invalid MCP allowlist'); - return name => { + return (name, { signal } = {}) => { if (typeof name !== 'string' || !Object.hasOwn(allowlist, name)) throw new Error('MCP is not allowlisted'); const entry = allowlist[name]; if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error('invalid MCP allowlist entry'); - return probeStdioMcp({ command: entry.command, env: entry.env, timeoutMs }); + return probeStdioMcp({ command: entry.command, env: entry.env, timeoutMs, signal }); }; } // The profile contains identifiers only. Callers must resolve them using a // trusted private allowlist; never construct this command from session text. -export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000 }) { - if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new Error('invalid MCP probe configuration'); +export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal }) { + if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw new Error('invalid MCP probe configuration'); return new Promise(resolve => { let child, timer, buffer = '', phase = 'initialize', finished = false; + let onAbort; const finish = result => { if (finished) return; finished = true; clearTimeout(timer); + if (signal && onAbort) signal.removeEventListener('abort', onAbort); if (child?.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } resolve(result); }; + if (signal?.aborted) { finish(false); return; } try { child = spawn(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } catch { finish(false); return; } timer = setTimeout(() => finish(false), timeoutMs); + onAbort = () => finish(false); + signal?.addEventListener('abort', onAbort, { once: true }); + if (signal?.aborted) { finish(false); return; } child.once('error', () => finish(false)); child.once('close', () => finish(false)); child.stdin.on('error', () => finish(false)); From 291844411d2c365741f9a98b89840573caa72f65 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:10:50 +0000 Subject: [PATCH 061/113] Wait for MCP probe termination --- docs/design/plexus-channels.md | 5 +++-- packages/tmux-bridge/bin/role-launch-profile.mjs | 14 ++++++++++---- packages/tmux-bridge/bin/role-mcp-probe.mjs | 10 ++++++---- packages/tmux-bridge/test/role-mcp-probe.test.mjs | 12 ++++++++++-- skills/agent-tmux/bin/role-launch-profile.mjs | 14 ++++++++++---- skills/agent-tmux/bin/role-mcp-probe.mjs | 10 ++++++---- 6 files changed, 45 insertions(+), 20 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 97386ce2..a566a7ee 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -123,5 +123,6 @@ and time, and terminates its process group. It currently supports protocol `2024-11-05` only and has been tested with synthetic processes; successful probing does not prove that an MCP started in the successor session. It is not scheduled or wired to the live handover. Planner deadlines signal cancellation; -the supplied stdio probe terminates its process group on that signal. Other -probe implementations must honor cancellation themselves. +the supplied stdio probe terminates its process group on that signal and waits +for the child close before reporting success. Other probe implementations must +honor cancellation themselves; an unconfirmed cancellation stops the plan. diff --git a/packages/tmux-bridge/bin/role-launch-profile.mjs b/packages/tmux-bridge/bin/role-launch-profile.mjs index 820979c6..30b5e1ac 100644 --- a/packages/tmux-bridge/bin/role-launch-profile.mjs +++ b/packages/tmux-bridge/bin/role-launch-profile.mjs @@ -11,12 +11,18 @@ export async function planRoleLaunch({ profile, authority, probe, timeoutMs = 30 if (profile.permissions.some(value => authority.humanGatedPermissions.includes(value))) throw new Error('human-gated permission cannot be pregranted'); const available = [], unavailable = []; for (const name of profile.mcp) { - let timer; const controller = new AbortController(); + let timer, cleanupTimer; const controller = new AbortController(), timedOut = Symbol('timeout'), cleanupTimedOut = Symbol('cleanup-timeout'); + const pending = Promise.resolve().then(() => probe(name, { signal: controller.signal })); try { - const result = await Promise.race([Promise.resolve().then(() => probe(name, { signal: controller.signal })), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('unreachable')); }, timeoutMs); })]); + const result = await Promise.race([pending, new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(timedOut); }, timeoutMs); })]); + if (result === timedOut) { + const cleanup = await Promise.race([pending.then(() => true, () => true), new Promise(resolve => { cleanupTimer = setTimeout(() => resolve(cleanupTimedOut), 1500); })]); + if (cleanup === cleanupTimedOut) throw new Error('probe cancellation unconfirmed'); + unavailable.push(name); continue; + } (result === true ? available : unavailable).push(name); - } catch { unavailable.push(name); } - finally { clearTimeout(timer); controller.abort(); } + } catch (error) { if (error?.message === 'probe cancellation unconfirmed') throw error; unavailable.push(name); } + finally { clearTimeout(timer); clearTimeout(cleanupTimer); controller.abort(); } } return { schema: 'agent-mesh.role-launch-plan.v1', role: profile.role, permissions: [...profile.permissions], plugins: [...profile.plugins], mcpToStart: available, mcpUnavailable: unavailable }; } diff --git a/packages/tmux-bridge/bin/role-mcp-probe.mjs b/packages/tmux-bridge/bin/role-mcp-probe.mjs index f20da427..4a6d29cb 100644 --- a/packages/tmux-bridge/bin/role-mcp-probe.mjs +++ b/packages/tmux-bridge/bin/role-mcp-probe.mjs @@ -17,14 +17,16 @@ export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal }) { if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw new Error('invalid MCP probe configuration'); return new Promise(resolve => { - let child, timer, buffer = '', phase = 'initialize', finished = false; + let child, timer, reapTimer, buffer = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false; let onAbort; + const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); resolve(result); } }; const finish = result => { if (finished) return; - finished = true; clearTimeout(timer); + finished = true; desired = result; clearTimeout(timer); if (signal && onAbort) signal.removeEventListener('abort', onAbort); if (child?.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } - resolve(result); + if (!child || closed) done(child ? desired : false); + else reapTimer = setTimeout(() => done(false), 1000); }; if (signal?.aborted) { finish(false); return; } try { child = spawn(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } @@ -34,7 +36,7 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa signal?.addEventListener('abort', onAbort, { once: true }); if (signal?.aborted) { finish(false); return; } child.once('error', () => finish(false)); - child.once('close', () => finish(false)); + child.once('close', () => { closed = true; if (!finished) finish(false); else done(desired); }); child.stdin.on('error', () => finish(false)); child.stdout.setEncoding('utf8'); const write = message => child.stdin.write(`${JSON.stringify(message)}\n`); diff --git a/packages/tmux-bridge/test/role-mcp-probe.test.mjs b/packages/tmux-bridge/test/role-mcp-probe.test.mjs index 284ea972..6d3c03e0 100644 --- a/packages/tmux-bridge/test/role-mcp-probe.test.mjs +++ b/packages/tmux-bridge/test/role-mcp-probe.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { mkdtemp, access, rm } from 'node:fs/promises'; +import { mkdtemp, access, readFile, rm } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { probeStdioMcp, roleProbeFromAllowlist } from '../bin/role-mcp-probe.mjs'; @@ -28,7 +28,7 @@ test('a cancelled probe terminates its temporary MCP process', async t => { const root = await mkdtemp(join(tmpdir(), 'mcp-cancel-')); t.after(() => rm(root, { recursive: true, force: true })); const started = join(root, 'started'), late = join(root, 'late'); - const code = "import {writeFileSync} from 'node:fs'; writeFileSync(process.argv[1], 'ok'); setTimeout(() => writeFileSync(process.argv[2], 'late'), 500); setInterval(() => {}, 1000);"; + const code = "import {writeFileSync} from 'node:fs'; writeFileSync(process.argv[1], String(process.pid)); setTimeout(() => writeFileSync(process.argv[2], 'late'), 500); setInterval(() => {}, 1000);"; const controller = new AbortController(); const probe = probeStdioMcp({ command: [process.execPath, '--input-type=module', '-e', code, started, late], timeoutMs: 2000, signal: controller.signal }); let seen = false; @@ -36,8 +36,10 @@ test('a cancelled probe terminates its temporary MCP process', async t => { try { await access(started); seen = true; } catch { await new Promise(resolve => setTimeout(resolve, 10)); } } assert.equal(seen, true, 'fixture process started'); + const pid = Number(await readFile(started, 'utf8')); controller.abort(); assert.equal(await probe, false); + assert.throws(() => process.kill(pid, 0), error => error.code === 'ESRCH'); await new Promise(resolve => setTimeout(resolve, 600)); await assert.rejects(access(late)); }); @@ -50,3 +52,9 @@ test('planner aborts its trusted probe when its deadline expires', async () => { assert.equal(aborted, true); assert.deepEqual(plan.mcpUnavailable, ['slow']); }); + +test('planner refuses to continue if cancellation is not acknowledged', async () => { + const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['slow'], plugins: [] }; + const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['slow'], plugins: [] }; + await assert.rejects(planRoleLaunch({ profile, authority, timeoutMs: 5, probe: () => new Promise(() => {}) }), /cancellation unconfirmed/); +}); diff --git a/skills/agent-tmux/bin/role-launch-profile.mjs b/skills/agent-tmux/bin/role-launch-profile.mjs index 820979c6..30b5e1ac 100644 --- a/skills/agent-tmux/bin/role-launch-profile.mjs +++ b/skills/agent-tmux/bin/role-launch-profile.mjs @@ -11,12 +11,18 @@ export async function planRoleLaunch({ profile, authority, probe, timeoutMs = 30 if (profile.permissions.some(value => authority.humanGatedPermissions.includes(value))) throw new Error('human-gated permission cannot be pregranted'); const available = [], unavailable = []; for (const name of profile.mcp) { - let timer; const controller = new AbortController(); + let timer, cleanupTimer; const controller = new AbortController(), timedOut = Symbol('timeout'), cleanupTimedOut = Symbol('cleanup-timeout'); + const pending = Promise.resolve().then(() => probe(name, { signal: controller.signal })); try { - const result = await Promise.race([Promise.resolve().then(() => probe(name, { signal: controller.signal })), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('unreachable')); }, timeoutMs); })]); + const result = await Promise.race([pending, new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(timedOut); }, timeoutMs); })]); + if (result === timedOut) { + const cleanup = await Promise.race([pending.then(() => true, () => true), new Promise(resolve => { cleanupTimer = setTimeout(() => resolve(cleanupTimedOut), 1500); })]); + if (cleanup === cleanupTimedOut) throw new Error('probe cancellation unconfirmed'); + unavailable.push(name); continue; + } (result === true ? available : unavailable).push(name); - } catch { unavailable.push(name); } - finally { clearTimeout(timer); controller.abort(); } + } catch (error) { if (error?.message === 'probe cancellation unconfirmed') throw error; unavailable.push(name); } + finally { clearTimeout(timer); clearTimeout(cleanupTimer); controller.abort(); } } return { schema: 'agent-mesh.role-launch-plan.v1', role: profile.role, permissions: [...profile.permissions], plugins: [...profile.plugins], mcpToStart: available, mcpUnavailable: unavailable }; } diff --git a/skills/agent-tmux/bin/role-mcp-probe.mjs b/skills/agent-tmux/bin/role-mcp-probe.mjs index f20da427..4a6d29cb 100644 --- a/skills/agent-tmux/bin/role-mcp-probe.mjs +++ b/skills/agent-tmux/bin/role-mcp-probe.mjs @@ -17,14 +17,16 @@ export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal }) { if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw new Error('invalid MCP probe configuration'); return new Promise(resolve => { - let child, timer, buffer = '', phase = 'initialize', finished = false; + let child, timer, reapTimer, buffer = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false; let onAbort; + const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); resolve(result); } }; const finish = result => { if (finished) return; - finished = true; clearTimeout(timer); + finished = true; desired = result; clearTimeout(timer); if (signal && onAbort) signal.removeEventListener('abort', onAbort); if (child?.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } - resolve(result); + if (!child || closed) done(child ? desired : false); + else reapTimer = setTimeout(() => done(false), 1000); }; if (signal?.aborted) { finish(false); return; } try { child = spawn(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } @@ -34,7 +36,7 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa signal?.addEventListener('abort', onAbort, { once: true }); if (signal?.aborted) { finish(false); return; } child.once('error', () => finish(false)); - child.once('close', () => finish(false)); + child.once('close', () => { closed = true; if (!finished) finish(false); else done(desired); }); child.stdin.on('error', () => finish(false)); child.stdout.setEncoding('utf8'); const write = message => child.stdin.write(`${JSON.stringify(message)}\n`); From 8c9f17d232ab0d3a3c43ab03d36a48f22f236bde Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:18:07 +0000 Subject: [PATCH 062/113] Bind cloud queue sends to account profile --- docs/design/plexus-channels.md | 7 +++ .../tmux-bridge/bin/agent-native-call.mjs | 26 +++++++-- .../tmux-bridge/bin/cloud-account-binding.mjs | 25 ++++++++- packages/tmux-bridge/bin/mesh-comms.py | 8 +++ .../test/cloud-account-binding.test.mjs | 19 ++++++- .../test/cloud-native-call.test.mjs | 55 ++++++++++++++++++- scripts/mesh-readiness.mjs | 2 + scripts/plexus-privacy.mjs | 2 +- skills/agent-tmux/bin/agent-native-call.mjs | 26 +++++++-- .../agent-tmux/bin/cloud-account-binding.mjs | 25 ++++++++- skills/agent-tmux/bin/mesh-comms.py | 8 +++ 11 files changed, 183 insertions(+), 20 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index a566a7ee..dbe20c7d 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -67,6 +67,13 @@ not yet supported by this operation. private operator profile binds an account scope to a CLI configuration directory and a digest of its reported account and organization; the helper checks the same profile before and after an operation and treats changes as uncertain. +The native cloud transport can opt into this binding with an explicitly scoped, +private `agent-mesh.cloud-account.v1` profile. The queued comms replay binds the +profile digest and scope, refusing a changed profile. Its provider acknowledgement +still proves queue acceptance only; it does not prove that the recipient read it. +The channel waker is not yet connected to this scoped transport. Account checks +cannot exclude a non-cooperating concurrent switch that is changed and restored +between the checks; the profile and account directory require operator control. Profile configuration and digests are private. This check relies on a trusted CLI and configuration directory, does not prevent a concurrent credential switch, and is not provider readback or proof of delivery. It is not connected diff --git a/packages/tmux-bridge/bin/agent-native-call.mjs b/packages/tmux-bridge/bin/agent-native-call.mjs index ef5e2ea2..1bcc339c 100755 --- a/packages/tmux-bridge/bin/agent-native-call.mjs +++ b/packages/tmux-bridge/bin/agent-native-call.mjs @@ -14,6 +14,7 @@ import { inspectClaudeSessionOwnership } from "./claude-session-ownership.mjs"; import { goalCommand, liveClaudeSessions, typeClaudeGoal } from "./claude-goal.mjs"; import { GOAL_RESUME_MODES, reconcileCodexGoal } from "./codex-goal.mjs"; import { withCodexAppServer } from "./codex-app-server.mjs"; +import { loadClaudeAccountProfile, withClaudeAccount } from "./cloud-account-binding.mjs"; let activeComms; let enqueueStarted = false; @@ -26,6 +27,9 @@ const { values } = parseArgs({ timeout: { type: "string", default: "120" }, "delivery-only": { type: "boolean", default: false }, cloud: { type: "boolean", default: false }, + "cloud-profile": { type: "string" }, + "cloud-scope": { type: "string" }, + "cloud-profile-digest": { type: "string" }, "steer-or-queue": { type: "boolean", default: false }, resume: { type: "boolean", default: false }, "no-resume": { type: "boolean", default: false }, @@ -68,6 +72,8 @@ const goalOptions = agent === "codex" ? { objective: values.goal?.trim(), resume if (values.cloud && (agent !== "claude" || !values["delivery-only"] || values.resume || values["managed-inbox-root"])) { fail("--cloud requires --agent claude --delivery-only, without --resume or --managed-inbox-root", 2); } +if ((!values.cloud && (values["cloud-profile"] || values["cloud-scope"] || values["cloud-profile-digest"])) || Boolean(values["cloud-profile"]) !== Boolean(values["cloud-scope"]) || (values["cloud-profile-digest"] && !values["cloud-profile"])) fail("cloud profile and scope must be supplied together for cloud transport", 2); +const cloudProfile = values["cloud-profile"] ? await loadClaudeAccountProfile(values["cloud-profile"], values["cloud-scope"], values["cloud-profile-digest"]) : undefined; if (values.cloud ? !/^(session|cse)_[A-Za-z0-9]{1,128}$/.test(sessionId) : !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(sessionId)) { fail(values.cloud ? "--session must be an exact session_ or cse_ cloud ID" : "--session must be a complete UUID", 2); @@ -87,6 +93,7 @@ const protocolMessage = values["delivery-only"] ? message : `${anchor} Use the r const comms = await commsLease({ kind: 'native', runtime: agent, destination: sessionId, correlation: correlationId, message: protocolMessage, inbox_root: values['managed-inbox-root'], resume, ...(values.cloud ? { cloud: true } : {}), + ...(cloudProfile ? { cloud_profile: values['cloud-profile'], cloud_scope: values['cloud-scope'], cloud_profile_digest: cloudProfile.digest } : {}), ...(values["steer-or-queue"] ? { steer_first: true } : {}), ...(goalOptions?.objective ? { goal: goalOptions.objective } : {}), ...(goalOptions?.resume && goalOptions.resume !== "blocked" ? { goal_resume: goalOptions.resume } : {}) }); @@ -100,10 +107,17 @@ if (comms.status !== 'send') { // Cloud follow-ups have a provider queue acknowledgement, but no local transcript. // All failures after invoking the provider retain the gate's unknown receipt. if (values.cloud) { - enqueueStarted = true; - const sent = await run(process.env.CLAUDE_BIN || "claude", [ - "-p", "--cloud", sessionId, "--output-format", "json" - ], timeoutSeconds * 1000, message); + let sent; + if (cloudProfile) { + sent = await withClaudeAccount(cloudProfile.profile, async binding => { + enqueueStarted = true; + return run(binding.command, ["-p", "--cloud", sessionId, "--output-format", "json"], timeoutSeconds * 1000, message, { ...process.env, CLAUDE_CONFIG_DIR: binding.configDir }); + }); + await loadClaudeAccountProfile(values["cloud-profile"], values["cloud-scope"], cloudProfile.digest); + } else { + enqueueStarted = true; + sent = await run(process.env.CLAUDE_BIN || "claude", ["-p", "--cloud", sessionId, "--output-format", "json"], timeoutSeconds * 1000, message); + } let receipt; try { receipt = JSON.parse(sent.stdout); } catch { /* Unproven acceptance. */ } if (sent.code !== 0 || receipt?.ok !== true || receipt.session_id !== sessionId) { @@ -393,9 +407,9 @@ async function consumeTranscript(path, start) { } } -function run(command, args, timeoutMs, input) { +function run(command, args, timeoutMs, input, env = process.env) { return new Promise((resolveRun) => { - const child = execFile(command, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => { + const child = execFile(command, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024, env }, (error, stdout, stderr) => { resolveRun({ code: error && typeof error.code === "number" ? error.code : error ? 1 : 0, stdout: typeof stdout === "string" ? stdout : "", diff --git a/packages/tmux-bridge/bin/cloud-account-binding.mjs b/packages/tmux-bridge/bin/cloud-account-binding.mjs index 513a18ea..8391a3f1 100644 --- a/packages/tmux-bridge/bin/cloud-account-binding.mjs +++ b/packages/tmux-bridge/bin/cloud-account-binding.mjs @@ -1,13 +1,34 @@ /** Bind an operator-selected Claude CLI profile to an account scope. */ import { createHash } from 'node:crypto'; import { execFile } from 'node:child_process'; -import { lstat, realpath } from 'node:fs/promises'; -import { isAbsolute } from 'node:path'; +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { dirname, isAbsolute } from 'node:path'; import { promisify } from 'node:util'; const execute = promisify(execFile); const SCOPE = /^[a-z][a-z0-9-]{0,63}$/; +export async function loadClaudeAccountProfile(path, scope, expectedDigest) { + if (typeof path !== 'string' || !isAbsolute(path) || !SCOPE.test(scope || '') || (expectedDigest !== undefined && !/^[0-9a-f]{64}$/.test(expectedDigest))) throw new Error('invalid cloud profile reference'); + const parent = dirname(path), dir = await lstat(parent); + if (!dir.isDirectory() || dir.isSymbolicLink() || dir.uid !== process.getuid() || (dir.mode & 0o077) !== 0 || await realpath(parent) !== parent) throw new Error('cloud profile directory not private'); + const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 8192) throw new Error('invalid cloud profile file'); + bytes = await file.readFile(); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('cloud profile changed'); + } finally { await file.close(); } + const digest = createHash('sha256').update(bytes).digest('hex'); + if (expectedDigest !== undefined && digest !== expectedDigest) throw new Error('cloud profile changed'); + let profile; try { profile = JSON.parse(bytes.toString('utf8')); } catch { throw new Error('invalid cloud profile'); } + if (!profile || Object.keys(profile).sort().join(',') !== 'command,configDir,expectedSubjectHash,schema,scope' || profile.schema !== 'agent-mesh.cloud-account.v1' || profile.scope !== scope) throw new Error('cloud profile scope mismatch'); + return { profile, digest }; +} + // Only a digest is returned. Raw identity and credentials are never returned // or copied to a receipt; the operator must protect the configured profile. export function claudeSubjectHash(status) { diff --git a/packages/tmux-bridge/bin/mesh-comms.py b/packages/tmux-bridge/bin/mesh-comms.py index b5af653d..fc3e3485 100755 --- a/packages/tmux-bridge/bin/mesh-comms.py +++ b/packages/tmux-bridge/bin/mesh-comms.py @@ -107,6 +107,10 @@ def validate(spec): not re.fullmatch(r'(session|cse)_[A-Za-z0-9]{1,128}', spec['destination']) or spec.get('resume') or spec.get('inbox_root')): raise ValueError('invalid Claude cloud destination') + profile_keys = ('cloud_profile', 'cloud_scope', 'cloud_profile_digest') + if any(key in spec for key in profile_keys): + if not spec.get('cloud') or not all(isinstance(spec.get(key), str) for key in profile_keys) or not Path(spec['cloud_profile']).is_absolute() or not re.fullmatch(r'[a-z][a-z0-9-]{0,63}', spec['cloud_scope']) or not re.fullmatch(r'[0-9a-f]{64}', spec['cloud_profile_digest']): + raise ValueError('invalid cloud account profile') if 'steer_first' in spec and (spec['steer_first'] is not True or spec['kind'] != 'native' or spec['runtime'] != 'codex' or spec.get('cloud')): raise ValueError('invalid steer-or-queue destination') claude_goal = spec['runtime'] == 'claude' and not spec.get('cloud') and 'goal_resume' not in spec @@ -244,6 +248,8 @@ def observe_inbox(spec, ident, confirmed): def identity(spec): destination = [spec['kind'], spec['runtime'], spec['destination'], spec.get('socket'), spec.get('correlation') or encode(spec)] + if spec.get('cloud_profile'): + destination.append(spec['cloud_scope']) return hashlib.sha256(encode(destination).encode()).hexdigest() @@ -253,6 +259,8 @@ def command(spec): '--correlation-id', spec['correlation'], '--message', spec['message'], '--delivery-only'] if spec.get('cloud'): args += ['--cloud'] + if spec.get('cloud_profile'): + args += ['--cloud-profile', spec['cloud_profile'], '--cloud-scope', spec['cloud_scope'], '--cloud-profile-digest', spec['cloud_profile_digest']] if spec.get('steer_first'): args += ['--steer-or-queue'] if spec.get('inbox_root'): diff --git a/packages/tmux-bridge/test/cloud-account-binding.test.mjs b/packages/tmux-bridge/test/cloud-account-binding.test.mjs index 82a407b3..61d5f4ec 100644 --- a/packages/tmux-bridge/test/cloud-account-binding.test.mjs +++ b/packages/tmux-bridge/test/cloud-account-binding.test.mjs @@ -1,9 +1,9 @@ import assert from 'node:assert/strict'; -import { chmod, mkdtemp, rm } from 'node:fs/promises'; +import { chmod, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'; import { join } from 'node:path'; import { tmpdir } from 'node:os'; import test from 'node:test'; -import { claudeSubjectHash, verifyClaudeAccount, withClaudeAccount } from '../bin/cloud-account-binding.mjs'; +import { claudeSubjectHash, loadClaudeAccountProfile, verifyClaudeAccount, withClaudeAccount } from '../bin/cloud-account-binding.mjs'; async function fixture(t) { const root = await mkdtemp(join(tmpdir(), 'cloud-binding-')); @@ -28,6 +28,21 @@ test('matching provider, profile and account produce only a bound digest', async assert.equal(invoked, true); }); +test('profile file is private, scoped and digest-bound across replay', async t => { + const f = await fixture(t), path = join(f.root, 'profile.json'); + await writeFile(path, JSON.stringify({ schema: 'agent-mesh.cloud-account.v1', ...f.profile }), { mode: 0o600 }); + const loaded = await loadClaudeAccountProfile(path, 'fixture'); + assert.equal((await loadClaudeAccountProfile(path, 'fixture', loaded.digest)).digest, loaded.digest); + await assert.rejects(loadClaudeAccountProfile(path, 'other'), /scope/); + await chmod(path, 0o644); + await assert.rejects(loadClaudeAccountProfile(path, 'fixture'), /file/); + await chmod(path, 0o600); + await writeFile(path, '{}'); + await assert.rejects(loadClaudeAccountProfile(path, 'fixture', loaded.digest), /changed/); + await symlink(path, join(f.root, 'link.json')); + await assert.rejects(loadClaudeAccountProfile(join(f.root, 'link.json'), 'fixture')); +}); + test('wrong account or profile fails before the action', async t => { const f = await fixture(t); let invoked = false; const run = async () => ({ stdout: JSON.stringify({ ...f.status, orgId: 'other' }) }); diff --git a/packages/tmux-bridge/test/cloud-native-call.test.mjs b/packages/tmux-bridge/test/cloud-native-call.test.mjs index e3b33fd1..461d6034 100644 --- a/packages/tmux-bridge/test/cloud-native-call.test.mjs +++ b/packages/tmux-bridge/test/cloud-native-call.test.mjs @@ -6,6 +6,7 @@ import { dirname, join } from 'node:path'; import { fileURLToPath } from 'node:url'; import { promisify } from 'node:util'; import test from 'node:test'; +import { claudeSubjectHash } from '../bin/cloud-account-binding.mjs'; const exec = promisify(execFile); const bin = join(dirname(dirname(fileURLToPath(import.meta.url))), 'bin'); @@ -16,8 +17,15 @@ async function fixture(t, mode = 'success') { t.after(() => rm(root, { recursive: true, force: true })); const provider = join(root, 'fake-claude.mjs'); const calls = join(root, 'calls.jsonl'); + const profilePath = join(root, 'profile.json'); await writeFile(provider, `#!/usr/bin/env node -import { appendFile } from 'node:fs/promises'; +import { appendFile, readFile, writeFile } from 'node:fs/promises'; +if (process.argv[2] === 'auth') { + let count = 0; try { count = Number(await readFile(process.env.CLOUD_TEST_AUTH_COUNT, 'utf8')); } catch {} + await writeFile(process.env.CLOUD_TEST_AUTH_COUNT, String(++count)); + console.log(JSON.stringify({loggedIn:true,apiProvider:'firstParty',authMethod:'claude.ai',storedClaudeAiLogin:true,email:process.env.CLOUD_TEST_MODE === 'wrong-account' || (process.env.CLOUD_TEST_MODE === 'account-changed' && count > 1) ? 'other@example.invalid' : 'fixture@example.invalid',orgId:'fixture-org',configDirectory:process.env.CLAUDE_CONFIG_DIR})); + process.exit(0); +} let message = ''; for await (const chunk of process.stdin) message += chunk; await appendFile(process.env.CLOUD_TEST_CALLS, JSON.stringify({ args: process.argv.slice(2), message }) + '\\n'); const mode = process.env.CLOUD_TEST_MODE; @@ -28,7 +36,10 @@ else console.log(JSON.stringify({ ok: mode !== 'refused', session_id: mode === ' if (mode === 'nonzero') process.exitCode = 1; `); await chmod(provider, 0o755); + const status = { loggedIn: true, apiProvider: 'firstParty', authMethod: 'claude.ai', storedClaudeAiLogin: true, email: 'fixture@example.invalid', orgId: 'fixture-org' }; + await writeFile(profilePath, JSON.stringify({ schema: 'agent-mesh.cloud-account.v1', scope: 'fixture', configDir: root, command: provider, expectedSubjectHash: claudeSubjectHash(status) }), { mode: 0o600 }); const env = { ...process.env, CLAUDE_BIN: provider, CLOUD_TEST_CALLS: calls, CLOUD_TEST_MODE: mode, + CLOUD_TEST_AUTH_COUNT: join(root, 'auth-count'), MESH_COMMS_STATE: join(root, 'comms'), AGENT_FALLBACK_STATE: join(root, 'fallback') }; // A host replay capability must never enter an isolated test invocation. delete env.MESH_COMMS_REPLAY_FD; @@ -43,9 +54,51 @@ if (mode === 'nonzero') process.exitCode = 1; gate: (action) => command('python3', [join(bin, 'mesh-comms.py'), action, '--scope', 'claude', '--reason', 'synthetic test', '--by', 'test']), status: () => command('python3', [join(bin, 'mesh-comms.py'), 'status']), calls: async () => { try { return (await readFile(calls, 'utf8')).trim().split('\n').filter(Boolean).map(JSON.parse); } catch (error) { if (error.code === 'ENOENT') return []; throw error; } }, + profileArgs: ['--cloud-profile', profilePath, '--cloud-scope', 'fixture'], + profilePath, }; } +test('scoped cloud transport checks the selected account before and after enqueue', async t => { + const f = await fixture(t); + const result = await f.invoke(f.profileArgs); + assert.equal(result.code, 0, result.stderr); + assert.equal(JSON.parse(result.stdout).readBack, false); + assert.equal((await f.calls()).length, 1); +}); + +test('wrong account refuses before sending; account change after send remains unknown', async t => { + const wrong = await fixture(t, 'wrong-account'); + assert.notEqual((await wrong.invoke(wrong.profileArgs)).code, 0); + assert.equal((await wrong.calls()).length, 0); + const changed = await fixture(t, 'account-changed'); + assert.notEqual((await changed.invoke(changed.profileArgs)).code, 0); + assert.equal((await changed.calls()).length, 1); + assert.notEqual((await changed.invoke(changed.profileArgs)).code, 0); + assert.equal((await changed.calls()).length, 1); + assert.equal(JSON.parse((await changed.status()).stdout).counts.unknown, 1); +}); + +test('queued scoped replay preserves profile and refuses a changed profile', async t => { + const f = await fixture(t); + assert.equal((await f.gate('queue')).code, 0); + assert.equal(JSON.parse((await f.invoke(f.profileArgs)).stdout).held, true); + await writeFile(f.profilePath, '{}', { mode: 0o600 }); + await f.gate('on'); + assert.equal((await f.calls()).length, 0); + assert.equal(JSON.parse((await f.status()).stdout).counts.unknown, 1); +}); + +test('queued scoped replay uses the same private account profile', async t => { + const f = await fixture(t); + assert.equal((await f.gate('queue')).code, 0); + assert.equal(JSON.parse((await f.invoke(f.profileArgs)).stdout).held, true); + const flushed = await f.gate('on'); + assert.equal(flushed.code, 0, flushed.stderr); + assert.equal(JSON.parse(flushed.stdout).counts.delivered, 1); + assert.equal((await f.calls()).length, 1); +}); + test('cloud delivery verifies exact provider JSON and needs no local transcript', async t => { const f = await fixture(t); const result = await f.invoke(); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index e1c9e44f..a496e239 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -29,6 +29,8 @@ const agentTmuxBundleFiles = [ "bin/agent-spawn.sh", "bin/agent-session.sh", "bin/agent-native-call.mjs", + "bin/cloud-account-binding.mjs", + "bin/codex-app-server.mjs", "bin/codex-goal.mjs", "bin/agent-goal.mjs", "bin/claude-goal.mjs", diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs index b374923b..0747fda6 100644 --- a/scripts/plexus-privacy.mjs +++ b/scripts/plexus-privacy.mjs @@ -6,7 +6,7 @@ const privatePatterns = [ ]; export function isPlexusMechanismFile(relativePath) { - return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|codex-(?:compaction|wake)-|module-batches|mesh-(?:graph|channel)|agent-waker|role-(?:launch|mcp)-|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); + return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|cloud-(?:account|native)-|codex-(?:compaction|wake)-|module-batches|mesh-(?:graph|channel)|agent-waker|role-(?:launch|mcp)-|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); } export function containsPrivatePlexusPolicy(text) { diff --git a/skills/agent-tmux/bin/agent-native-call.mjs b/skills/agent-tmux/bin/agent-native-call.mjs index ef5e2ea2..1bcc339c 100755 --- a/skills/agent-tmux/bin/agent-native-call.mjs +++ b/skills/agent-tmux/bin/agent-native-call.mjs @@ -14,6 +14,7 @@ import { inspectClaudeSessionOwnership } from "./claude-session-ownership.mjs"; import { goalCommand, liveClaudeSessions, typeClaudeGoal } from "./claude-goal.mjs"; import { GOAL_RESUME_MODES, reconcileCodexGoal } from "./codex-goal.mjs"; import { withCodexAppServer } from "./codex-app-server.mjs"; +import { loadClaudeAccountProfile, withClaudeAccount } from "./cloud-account-binding.mjs"; let activeComms; let enqueueStarted = false; @@ -26,6 +27,9 @@ const { values } = parseArgs({ timeout: { type: "string", default: "120" }, "delivery-only": { type: "boolean", default: false }, cloud: { type: "boolean", default: false }, + "cloud-profile": { type: "string" }, + "cloud-scope": { type: "string" }, + "cloud-profile-digest": { type: "string" }, "steer-or-queue": { type: "boolean", default: false }, resume: { type: "boolean", default: false }, "no-resume": { type: "boolean", default: false }, @@ -68,6 +72,8 @@ const goalOptions = agent === "codex" ? { objective: values.goal?.trim(), resume if (values.cloud && (agent !== "claude" || !values["delivery-only"] || values.resume || values["managed-inbox-root"])) { fail("--cloud requires --agent claude --delivery-only, without --resume or --managed-inbox-root", 2); } +if ((!values.cloud && (values["cloud-profile"] || values["cloud-scope"] || values["cloud-profile-digest"])) || Boolean(values["cloud-profile"]) !== Boolean(values["cloud-scope"]) || (values["cloud-profile-digest"] && !values["cloud-profile"])) fail("cloud profile and scope must be supplied together for cloud transport", 2); +const cloudProfile = values["cloud-profile"] ? await loadClaudeAccountProfile(values["cloud-profile"], values["cloud-scope"], values["cloud-profile-digest"]) : undefined; if (values.cloud ? !/^(session|cse)_[A-Za-z0-9]{1,128}$/.test(sessionId) : !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(sessionId)) { fail(values.cloud ? "--session must be an exact session_ or cse_ cloud ID" : "--session must be a complete UUID", 2); @@ -87,6 +93,7 @@ const protocolMessage = values["delivery-only"] ? message : `${anchor} Use the r const comms = await commsLease({ kind: 'native', runtime: agent, destination: sessionId, correlation: correlationId, message: protocolMessage, inbox_root: values['managed-inbox-root'], resume, ...(values.cloud ? { cloud: true } : {}), + ...(cloudProfile ? { cloud_profile: values['cloud-profile'], cloud_scope: values['cloud-scope'], cloud_profile_digest: cloudProfile.digest } : {}), ...(values["steer-or-queue"] ? { steer_first: true } : {}), ...(goalOptions?.objective ? { goal: goalOptions.objective } : {}), ...(goalOptions?.resume && goalOptions.resume !== "blocked" ? { goal_resume: goalOptions.resume } : {}) }); @@ -100,10 +107,17 @@ if (comms.status !== 'send') { // Cloud follow-ups have a provider queue acknowledgement, but no local transcript. // All failures after invoking the provider retain the gate's unknown receipt. if (values.cloud) { - enqueueStarted = true; - const sent = await run(process.env.CLAUDE_BIN || "claude", [ - "-p", "--cloud", sessionId, "--output-format", "json" - ], timeoutSeconds * 1000, message); + let sent; + if (cloudProfile) { + sent = await withClaudeAccount(cloudProfile.profile, async binding => { + enqueueStarted = true; + return run(binding.command, ["-p", "--cloud", sessionId, "--output-format", "json"], timeoutSeconds * 1000, message, { ...process.env, CLAUDE_CONFIG_DIR: binding.configDir }); + }); + await loadClaudeAccountProfile(values["cloud-profile"], values["cloud-scope"], cloudProfile.digest); + } else { + enqueueStarted = true; + sent = await run(process.env.CLAUDE_BIN || "claude", ["-p", "--cloud", sessionId, "--output-format", "json"], timeoutSeconds * 1000, message); + } let receipt; try { receipt = JSON.parse(sent.stdout); } catch { /* Unproven acceptance. */ } if (sent.code !== 0 || receipt?.ok !== true || receipt.session_id !== sessionId) { @@ -393,9 +407,9 @@ async function consumeTranscript(path, start) { } } -function run(command, args, timeoutMs, input) { +function run(command, args, timeoutMs, input, env = process.env) { return new Promise((resolveRun) => { - const child = execFile(command, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => { + const child = execFile(command, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024, env }, (error, stdout, stderr) => { resolveRun({ code: error && typeof error.code === "number" ? error.code : error ? 1 : 0, stdout: typeof stdout === "string" ? stdout : "", diff --git a/skills/agent-tmux/bin/cloud-account-binding.mjs b/skills/agent-tmux/bin/cloud-account-binding.mjs index 513a18ea..8391a3f1 100644 --- a/skills/agent-tmux/bin/cloud-account-binding.mjs +++ b/skills/agent-tmux/bin/cloud-account-binding.mjs @@ -1,13 +1,34 @@ /** Bind an operator-selected Claude CLI profile to an account scope. */ import { createHash } from 'node:crypto'; import { execFile } from 'node:child_process'; -import { lstat, realpath } from 'node:fs/promises'; -import { isAbsolute } from 'node:path'; +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { dirname, isAbsolute } from 'node:path'; import { promisify } from 'node:util'; const execute = promisify(execFile); const SCOPE = /^[a-z][a-z0-9-]{0,63}$/; +export async function loadClaudeAccountProfile(path, scope, expectedDigest) { + if (typeof path !== 'string' || !isAbsolute(path) || !SCOPE.test(scope || '') || (expectedDigest !== undefined && !/^[0-9a-f]{64}$/.test(expectedDigest))) throw new Error('invalid cloud profile reference'); + const parent = dirname(path), dir = await lstat(parent); + if (!dir.isDirectory() || dir.isSymbolicLink() || dir.uid !== process.getuid() || (dir.mode & 0o077) !== 0 || await realpath(parent) !== parent) throw new Error('cloud profile directory not private'); + const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 8192) throw new Error('invalid cloud profile file'); + bytes = await file.readFile(); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('cloud profile changed'); + } finally { await file.close(); } + const digest = createHash('sha256').update(bytes).digest('hex'); + if (expectedDigest !== undefined && digest !== expectedDigest) throw new Error('cloud profile changed'); + let profile; try { profile = JSON.parse(bytes.toString('utf8')); } catch { throw new Error('invalid cloud profile'); } + if (!profile || Object.keys(profile).sort().join(',') !== 'command,configDir,expectedSubjectHash,schema,scope' || profile.schema !== 'agent-mesh.cloud-account.v1' || profile.scope !== scope) throw new Error('cloud profile scope mismatch'); + return { profile, digest }; +} + // Only a digest is returned. Raw identity and credentials are never returned // or copied to a receipt; the operator must protect the configured profile. export function claudeSubjectHash(status) { diff --git a/skills/agent-tmux/bin/mesh-comms.py b/skills/agent-tmux/bin/mesh-comms.py index b5af653d..fc3e3485 100755 --- a/skills/agent-tmux/bin/mesh-comms.py +++ b/skills/agent-tmux/bin/mesh-comms.py @@ -107,6 +107,10 @@ def validate(spec): not re.fullmatch(r'(session|cse)_[A-Za-z0-9]{1,128}', spec['destination']) or spec.get('resume') or spec.get('inbox_root')): raise ValueError('invalid Claude cloud destination') + profile_keys = ('cloud_profile', 'cloud_scope', 'cloud_profile_digest') + if any(key in spec for key in profile_keys): + if not spec.get('cloud') or not all(isinstance(spec.get(key), str) for key in profile_keys) or not Path(spec['cloud_profile']).is_absolute() or not re.fullmatch(r'[a-z][a-z0-9-]{0,63}', spec['cloud_scope']) or not re.fullmatch(r'[0-9a-f]{64}', spec['cloud_profile_digest']): + raise ValueError('invalid cloud account profile') if 'steer_first' in spec and (spec['steer_first'] is not True or spec['kind'] != 'native' or spec['runtime'] != 'codex' or spec.get('cloud')): raise ValueError('invalid steer-or-queue destination') claude_goal = spec['runtime'] == 'claude' and not spec.get('cloud') and 'goal_resume' not in spec @@ -244,6 +248,8 @@ def observe_inbox(spec, ident, confirmed): def identity(spec): destination = [spec['kind'], spec['runtime'], spec['destination'], spec.get('socket'), spec.get('correlation') or encode(spec)] + if spec.get('cloud_profile'): + destination.append(spec['cloud_scope']) return hashlib.sha256(encode(destination).encode()).hexdigest() @@ -253,6 +259,8 @@ def command(spec): '--correlation-id', spec['correlation'], '--message', spec['message'], '--delivery-only'] if spec.get('cloud'): args += ['--cloud'] + if spec.get('cloud_profile'): + args += ['--cloud-profile', spec['cloud_profile'], '--cloud-scope', spec['cloud_scope'], '--cloud-profile-digest', spec['cloud_profile_digest']] if spec.get('steer_first'): args += ['--steer-or-queue'] if spec.get('inbox_root'): From 025e5328c81157aa1c0b150e8d19425bd1d212c7 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:24:08 +0000 Subject: [PATCH 063/113] Route scoped cloud channel queues --- docs/design/plexus-channels.md | 9 ++-- packages/tmux-bridge/bin/agent-waker.py | 50 ++++++++++++++++--- .../test/agent-waker-channel.test.py | 38 ++++++++++++++ skills/agent-tmux/bin/agent-waker.py | 50 ++++++++++++++++--- 4 files changed, 128 insertions(+), 19 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index dbe20c7d..47dc27a9 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -71,13 +71,16 @@ The native cloud transport can opt into this binding with an explicitly scoped, private `agent-mesh.cloud-account.v1` profile. The queued comms replay binds the profile digest and scope, refusing a changed profile. Its provider acknowledgement still proves queue acceptance only; it does not prove that the recipient read it. -The channel waker is not yet connected to this scoped transport. Account checks +The channel waker can opt in with a private profile directory; it routes a scoped +cloud session once and keeps the message in flight until independently verified. +There is no cloud readback reconciliation yet, so this route is not operational +for handover and deliberately blocks subsequent delivery. Account checks cannot exclude a non-cooperating concurrent switch that is changed and restored between the checks; the profile and account directory require operator control. Profile configuration and digests are private. This check relies on a trusted CLI and configuration directory, does not prevent a concurrent credential -switch, and is not provider readback or proof of delivery. It is not connected -to channel routing or enabled by default. +switch, and is not provider readback or proof of delivery. The route is disabled +by default. This is not yet a complete handover workflow: it does not write state for the old session, publish or verify the old session's final notice, archive anything, diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index a66df950..d5869764 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -12,6 +12,7 @@ import json import os import re +import stat from pathlib import Path import subprocess import sys @@ -117,10 +118,14 @@ def compose(job: str, pending: list[dict[str, Any]], errors: list[Any]) -> str: return "\n".join(lines) -def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False, receipt_out: dict | None = None) -> int: +def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False, receipt_out: dict | None = None, cloud_profile: str | None = None, cloud_scope: str | None = None) -> int: command = ["node", str(BIN / "agent-native-call.mjs"), "--agent", agent, "--session", session, "--correlation-id", correlation, "--timeout", "5"] command += ["--message-stdin"] if message_stdin else ["--message", message] + if cloud_profile or cloud_scope: + if not (cloud_profile and cloud_scope and agent == "claude" and delivery_only and message_stdin and not resume and not inbox_root): + raise ValueError("invalid cloud delivery options") + command += ["--cloud", "--cloud-profile", cloud_profile, "--cloud-scope", cloud_scope] if resume: if agent != "codex": raise ValueError("waker resume is supported only for Codex") @@ -138,6 +143,8 @@ def deliver(agent: str, session: str, correlation: str, message: str, inbox_root receipt = None bound = (isinstance(receipt, dict) and receipt.get("agent") == agent and receipt.get("sessionId") == session and receipt.get("correlationId") == correlation) + if cloud_profile and isinstance(receipt, dict) and receipt.get("status") == "queued" and (receipt.get("transport") != "claude-cloud" or receipt.get("readBack") is not False): + return 78 if delivery_only and isinstance(receipt, dict) and receipt.get("status") == "queued" and not bound: return 78 # A comms hold can exit zero: process success is not native queue acceptance. @@ -186,6 +193,24 @@ def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dic return value['channel'] +def cloud_target(target: str, root: str | None) -> tuple[str, str, str]: + match = re.fullmatch(r'claude-cloud:([a-z][a-z0-9-]{0,63}):((?:session|cse)_[A-Za-z0-9]{1,128})', target) + if not match or not root: + raise ValueError('unsupported cloud recipient') + directory = Path(root) + if not directory.is_absolute() or directory.resolve() != directory: + raise ValueError('invalid cloud profile root') + info = directory.lstat() + if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('insecure cloud profile root') + scope, session = match.groups() + profile = directory / f'{scope}.json' + info = profile.lstat() + if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('insecure cloud profile') + return session, str(profile), scope + + def run_channel(args: argparse.Namespace) -> int: path = Path(args.state) if args.state else state_dir() / f'{args.job}.json' with locked(path) as acquired: @@ -245,20 +270,28 @@ def run_channel(args: argparse.Namespace) -> int: generation = channel['generation'] if isinstance(generation, bool) or not isinstance(generation, int) or generation < 1: raise ValueError('invalid channel generation') - agent, sep, session = target.partition(':') - if not sep or agent not in ('codex', 'claude'): - raise ValueError('unsupported channel recipient') + cloud_profile = cloud_scope = None + if target.startswith('claude-cloud:'): + session, cloud_profile, cloud_scope = cloud_target(target, getattr(args, 'cloud_profile_root', None)) + agent = 'claude' + else: + agent, sep, session = target.partition(':') + if not sep or agent not in ('codex', 'claude'): + raise ValueError('unsupported channel recipient') channel = channel_call(args, 'begin-delivery', '--id', pending['id'], '--session', target, '--generation', str(generation)) item = next(item for item in channel['queue'] if item['id'] == pending['id']) - agent, sep, session = item['session'].partition(':') - if not sep or agent not in ('codex', 'claude') or item['session'] != target or item['generation'] != generation: + if item['session'] != target or item['generation'] != generation: raise ValueError('unsupported channel recipient') transport_receipt = {} - code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, - True, resume=args.resume and agent == 'codex', message_stdin=True, receipt_out=transport_receipt) + options = {'cloud_profile': cloud_profile, 'cloud_scope': cloud_scope} if cloud_profile else {} + code = deliver(agent, session, item['id'], item['payload'], None if cloud_profile else args.managed_inbox_root, + True, resume=args.resume and agent == 'codex', message_stdin=True, receipt_out=transport_receipt, **options) if code != 0: print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'delivery unconfirmed'})) return 3 + if cloud_profile: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'cloud queued; receipt unverified'})) + return 3 receipt = {'status': 'accepted', 'messageId': item['id'], 'session': item['session'], 'generation': item['generation']} receipt.update(transport_receipt) channel_call(args, 'acknowledge', '--id', item['id'], '--input', json.dumps(receipt, separators=(',', ':'))) @@ -342,6 +375,7 @@ def main(argv: list[str] | None = None) -> int: recipient.add_argument("--session", help="owning session UUID") recipient.add_argument("--channel", help="stable channel identifier") runner.add_argument("--graph-state", help="override graph state for isolated tests") + runner.add_argument("--cloud-profile-root", help="private directory for scoped cloud account profiles") runner.add_argument("--managed-inbox-root", help="required for Claude sessions") runner.add_argument("--delivery-only", action="store_true", help="acknowledge the native queue, without waiting for a result") runner.add_argument("--resume", action="store_true", help="opt in to native Codex resume when idle") diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index 031e5be6..7c36fb23 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -64,6 +64,44 @@ def test_native_adapter_receives_message_on_stdin(self): self.assertIn('--no-resume', run.call_args.args[0]) self.assertEqual(run.call_args.kwargs['input'], 'private fixture') + def test_cloud_queue_stays_inflight_and_is_not_resent(self): + with tempfile.TemporaryDirectory() as directory: + rootdir = Path(directory) + profiles = rootdir / 'profiles' + profiles.mkdir(mode=0o700) + profile = profiles / 'fixture.json' + profile.write_text('{}') + profile.chmod(0o600) + state = rootdir / 'graph' + def call(*args): + result = subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], capture_output=True, text=True) + self.assertEqual(result.returncode, 0, result.stderr) + return json.loads(result.stdout) + target = 'claude-cloud:fixture:session_Test' + call('cloud', 'register', '--session', target, '--evidence', 'test:fixture') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', target) + args = SimpleNamespace(state=str(rootdir / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False, cloud_profile_root=str(profiles)) + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'deliver', return_value=0) as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + self.assertEqual(waker.run(args), 3) + self.assertEqual(deliver.call_count, 1) + self.assertEqual(deliver.call_args.kwargs['cloud_scope'], 'fixture') + self.assertEqual(deliver.call_args.kwargs['cloud_profile'], str(profile)) + item = call('channel', 'get', '--name', 'example')['channel']['queue'][0] + self.assertEqual(item['state'], 'inflight') + + def test_cloud_adapter_requires_bound_queue_receipt(self): + from unittest.mock import Mock + receipt = {'status': 'queued', 'agent': 'claude', 'sessionId': 'session_Test', 'correlationId': 'message-1', 'transport': 'claude-cloud', 'readBack': False} + with patch.object(waker.subprocess, 'run', return_value=Mock(returncode=0, stdout=json.dumps(receipt))) as run: + self.assertEqual(waker.deliver('claude', 'session_Test', 'message-1', 'fixture', None, True, message_stdin=True, cloud_profile='/fixture/profile.json', cloud_scope='fixture'), 0) + self.assertIn('--cloud', run.call_args.args[0]) + self.assertEqual(run.call_args.kwargs['input'], 'fixture') + receipt['readBack'] = True + with patch.object(waker.subprocess, 'run', return_value=Mock(returncode=0, stdout=json.dumps(receipt))): + self.assertEqual(waker.deliver('claude', 'session_Test', 'message-1', 'fixture', None, True, message_stdin=True, cloud_profile='/fixture/profile.json', cloud_scope='fixture'), 78) + def test_lost_reservation_response_does_not_send_or_retry(self): with tempfile.TemporaryDirectory() as directory: state = Path(directory) / 'graph' diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index a66df950..d5869764 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -12,6 +12,7 @@ import json import os import re +import stat from pathlib import Path import subprocess import sys @@ -117,10 +118,14 @@ def compose(job: str, pending: list[dict[str, Any]], errors: list[Any]) -> str: return "\n".join(lines) -def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False, receipt_out: dict | None = None) -> int: +def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False, receipt_out: dict | None = None, cloud_profile: str | None = None, cloud_scope: str | None = None) -> int: command = ["node", str(BIN / "agent-native-call.mjs"), "--agent", agent, "--session", session, "--correlation-id", correlation, "--timeout", "5"] command += ["--message-stdin"] if message_stdin else ["--message", message] + if cloud_profile or cloud_scope: + if not (cloud_profile and cloud_scope and agent == "claude" and delivery_only and message_stdin and not resume and not inbox_root): + raise ValueError("invalid cloud delivery options") + command += ["--cloud", "--cloud-profile", cloud_profile, "--cloud-scope", cloud_scope] if resume: if agent != "codex": raise ValueError("waker resume is supported only for Codex") @@ -138,6 +143,8 @@ def deliver(agent: str, session: str, correlation: str, message: str, inbox_root receipt = None bound = (isinstance(receipt, dict) and receipt.get("agent") == agent and receipt.get("sessionId") == session and receipt.get("correlationId") == correlation) + if cloud_profile and isinstance(receipt, dict) and receipt.get("status") == "queued" and (receipt.get("transport") != "claude-cloud" or receipt.get("readBack") is not False): + return 78 if delivery_only and isinstance(receipt, dict) and receipt.get("status") == "queued" and not bound: return 78 # A comms hold can exit zero: process success is not native queue acceptance. @@ -186,6 +193,24 @@ def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dic return value['channel'] +def cloud_target(target: str, root: str | None) -> tuple[str, str, str]: + match = re.fullmatch(r'claude-cloud:([a-z][a-z0-9-]{0,63}):((?:session|cse)_[A-Za-z0-9]{1,128})', target) + if not match or not root: + raise ValueError('unsupported cloud recipient') + directory = Path(root) + if not directory.is_absolute() or directory.resolve() != directory: + raise ValueError('invalid cloud profile root') + info = directory.lstat() + if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('insecure cloud profile root') + scope, session = match.groups() + profile = directory / f'{scope}.json' + info = profile.lstat() + if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('insecure cloud profile') + return session, str(profile), scope + + def run_channel(args: argparse.Namespace) -> int: path = Path(args.state) if args.state else state_dir() / f'{args.job}.json' with locked(path) as acquired: @@ -245,20 +270,28 @@ def run_channel(args: argparse.Namespace) -> int: generation = channel['generation'] if isinstance(generation, bool) or not isinstance(generation, int) or generation < 1: raise ValueError('invalid channel generation') - agent, sep, session = target.partition(':') - if not sep or agent not in ('codex', 'claude'): - raise ValueError('unsupported channel recipient') + cloud_profile = cloud_scope = None + if target.startswith('claude-cloud:'): + session, cloud_profile, cloud_scope = cloud_target(target, getattr(args, 'cloud_profile_root', None)) + agent = 'claude' + else: + agent, sep, session = target.partition(':') + if not sep or agent not in ('codex', 'claude'): + raise ValueError('unsupported channel recipient') channel = channel_call(args, 'begin-delivery', '--id', pending['id'], '--session', target, '--generation', str(generation)) item = next(item for item in channel['queue'] if item['id'] == pending['id']) - agent, sep, session = item['session'].partition(':') - if not sep or agent not in ('codex', 'claude') or item['session'] != target or item['generation'] != generation: + if item['session'] != target or item['generation'] != generation: raise ValueError('unsupported channel recipient') transport_receipt = {} - code = deliver(agent, session, item['id'], item['payload'], args.managed_inbox_root, - True, resume=args.resume and agent == 'codex', message_stdin=True, receipt_out=transport_receipt) + options = {'cloud_profile': cloud_profile, 'cloud_scope': cloud_scope} if cloud_profile else {} + code = deliver(agent, session, item['id'], item['payload'], None if cloud_profile else args.managed_inbox_root, + True, resume=args.resume and agent == 'codex', message_stdin=True, receipt_out=transport_receipt, **options) if code != 0: print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'delivery unconfirmed'})) return 3 + if cloud_profile: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'cloud queued; receipt unverified'})) + return 3 receipt = {'status': 'accepted', 'messageId': item['id'], 'session': item['session'], 'generation': item['generation']} receipt.update(transport_receipt) channel_call(args, 'acknowledge', '--id', item['id'], '--input', json.dumps(receipt, separators=(',', ':'))) @@ -342,6 +375,7 @@ def main(argv: list[str] | None = None) -> int: recipient.add_argument("--session", help="owning session UUID") recipient.add_argument("--channel", help="stable channel identifier") runner.add_argument("--graph-state", help="override graph state for isolated tests") + runner.add_argument("--cloud-profile-root", help="private directory for scoped cloud account profiles") runner.add_argument("--managed-inbox-root", help="required for Claude sessions") runner.add_argument("--delivery-only", action="store_true", help="acknowledge the native queue, without waiting for a result") runner.add_argument("--resume", action="store_true", help="opt in to native Codex resume when idle") From b4a26570bdf4438a022414e5eb2897cf5f69f96d Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:28:08 +0000 Subject: [PATCH 064/113] Fail closed if MCP probe termination is unconfirmed --- docs/design/plexus-channels.md | 6 +++--- packages/tmux-bridge/bin/role-mcp-probe.mjs | 8 ++++---- packages/tmux-bridge/test/role-mcp-probe.test.mjs | 11 +++++++++++ skills/agent-tmux/bin/role-mcp-probe.mjs | 8 ++++---- 4 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 47dc27a9..a9eb6f5f 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -117,8 +117,7 @@ unreachable MCP is omitted and listed in the receipt without blocking startup. The launch assessor reports the observed MCP count and startup tokens, or null when tokens are unavailable; an unexpected permission prompt or component requires rollback. These are preparation primitives only: no provider startup, -permission enforcement, timeout cancellation, live rollback or token collector -is connected yet. The approved handover remains disabled until native evidence +permission enforcement, live rollback or token collector is connected yet. The approved handover remains disabled until native evidence and those adapters are present. `handover-dry-run.mjs` rehearses only in memory; it never contacts native @@ -134,5 +133,6 @@ and time, and terminates its process group. It currently supports protocol probing does not prove that an MCP started in the successor session. It is not scheduled or wired to the live handover. Planner deadlines signal cancellation; the supplied stdio probe terminates its process group on that signal and waits -for the child close before reporting success. Other probe implementations must +for the child close before reporting any result; failure to observe closure stops +the plan. Other probe implementations must honor cancellation themselves; an unconfirmed cancellation stops the plan. diff --git a/packages/tmux-bridge/bin/role-mcp-probe.mjs b/packages/tmux-bridge/bin/role-mcp-probe.mjs index 4a6d29cb..01faad6b 100644 --- a/packages/tmux-bridge/bin/role-mcp-probe.mjs +++ b/packages/tmux-bridge/bin/role-mcp-probe.mjs @@ -14,9 +14,9 @@ export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { // The profile contains identifiers only. Callers must resolve them using a // trusted private allowlist; never construct this command from session text. -export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal }) { +export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal, spawnProcess = spawn }) { if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw new Error('invalid MCP probe configuration'); - return new Promise(resolve => { + return new Promise((resolve, reject) => { let child, timer, reapTimer, buffer = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false; let onAbort; const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); resolve(result); } }; @@ -26,10 +26,10 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa if (signal && onAbort) signal.removeEventListener('abort', onAbort); if (child?.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } if (!child || closed) done(child ? desired : false); - else reapTimer = setTimeout(() => done(false), 1000); + else reapTimer = setTimeout(() => { if (!resolved) { resolved = true; reject(new Error('probe cancellation unconfirmed')); } }, 1000); }; if (signal?.aborted) { finish(false); return; } - try { child = spawn(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } + try { child = spawnProcess(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } catch { finish(false); return; } timer = setTimeout(() => finish(false), timeoutMs); onAbort = () => finish(false); diff --git a/packages/tmux-bridge/test/role-mcp-probe.test.mjs b/packages/tmux-bridge/test/role-mcp-probe.test.mjs index 6d3c03e0..f9ff7af2 100644 --- a/packages/tmux-bridge/test/role-mcp-probe.test.mjs +++ b/packages/tmux-bridge/test/role-mcp-probe.test.mjs @@ -58,3 +58,14 @@ test('planner refuses to continue if cancellation is not acknowledged', async () const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['slow'], plugins: [] }; await assert.rejects(planRoleLaunch({ profile, authority, timeoutMs: 5, probe: () => new Promise(() => {}) }), /cancellation unconfirmed/); }); + +test('unobserved process closure fails planning instead of treating MCP as offline', async () => { + const { EventEmitter } = await import('node:events'); + const child = new EventEmitter(); + child.stdin = new EventEmitter(); child.stdin.write = () => true; + child.stdout = new EventEmitter(); child.stdout.setEncoding = () => {}; + const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['stuck'], plugins: [] }; + const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['stuck'], plugins: [] }; + const probe = (_name, { signal }) => probeStdioMcp({ command: [process.execPath], timeoutMs: 5, signal, spawnProcess: () => child }); + await assert.rejects(planRoleLaunch({ profile, authority, probe, timeoutMs: 1400 }), /probe cancellation unconfirmed/); +}); diff --git a/skills/agent-tmux/bin/role-mcp-probe.mjs b/skills/agent-tmux/bin/role-mcp-probe.mjs index 4a6d29cb..01faad6b 100644 --- a/skills/agent-tmux/bin/role-mcp-probe.mjs +++ b/skills/agent-tmux/bin/role-mcp-probe.mjs @@ -14,9 +14,9 @@ export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { // The profile contains identifiers only. Callers must resolve them using a // trusted private allowlist; never construct this command from session text. -export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal }) { +export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal, spawnProcess = spawn }) { if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw new Error('invalid MCP probe configuration'); - return new Promise(resolve => { + return new Promise((resolve, reject) => { let child, timer, reapTimer, buffer = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false; let onAbort; const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); resolve(result); } }; @@ -26,10 +26,10 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa if (signal && onAbort) signal.removeEventListener('abort', onAbort); if (child?.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } if (!child || closed) done(child ? desired : false); - else reapTimer = setTimeout(() => done(false), 1000); + else reapTimer = setTimeout(() => { if (!resolved) { resolved = true; reject(new Error('probe cancellation unconfirmed')); } }, 1000); }; if (signal?.aborted) { finish(false); return; } - try { child = spawn(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } + try { child = spawnProcess(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } catch { finish(false); return; } timer = setTimeout(() => finish(false), timeoutMs); onAbort = () => finish(false); From 595dbd1c88062d9787917ff61e8f7fcd105c230a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:32:24 +0000 Subject: [PATCH 065/113] Reject invalid MCP probe authority --- docs/design/plexus-channels.md | 3 ++- packages/tmux-bridge/bin/role-launch-profile.mjs | 2 +- packages/tmux-bridge/bin/role-mcp-probe.mjs | 10 ++++++---- packages/tmux-bridge/test/role-mcp-probe.test.mjs | 7 +++++++ skills/agent-tmux/bin/role-launch-profile.mjs | 2 +- skills/agent-tmux/bin/role-mcp-probe.mjs | 10 ++++++---- 6 files changed, 23 insertions(+), 11 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index a9eb6f5f..a0962798 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -134,5 +134,6 @@ probing does not prove that an MCP started in the successor session. It is not scheduled or wired to the live handover. Planner deadlines signal cancellation; the supplied stdio probe terminates its process group on that signal and waits for the child close before reporting any result; failure to observe closure stops -the plan. Other probe implementations must +the plan. Missing or invalid private probe configuration stops planning rather than +being classified as an unreachable MCP. Other probe implementations must honor cancellation themselves; an unconfirmed cancellation stops the plan. diff --git a/packages/tmux-bridge/bin/role-launch-profile.mjs b/packages/tmux-bridge/bin/role-launch-profile.mjs index 30b5e1ac..33abcad6 100644 --- a/packages/tmux-bridge/bin/role-launch-profile.mjs +++ b/packages/tmux-bridge/bin/role-launch-profile.mjs @@ -21,7 +21,7 @@ export async function planRoleLaunch({ profile, authority, probe, timeoutMs = 30 unavailable.push(name); continue; } (result === true ? available : unavailable).push(name); - } catch (error) { if (error?.message === 'probe cancellation unconfirmed') throw error; unavailable.push(name); } + } catch (error) { if (error?.message === 'probe cancellation unconfirmed' || error?.code === 'MCP_PROBE_CONFIGURATION') throw error; unavailable.push(name); } finally { clearTimeout(timer); clearTimeout(cleanupTimer); controller.abort(); } } return { schema: 'agent-mesh.role-launch-plan.v1', role: profile.role, permissions: [...profile.permissions], plugins: [...profile.plugins], mcpToStart: available, mcpUnavailable: unavailable }; diff --git a/packages/tmux-bridge/bin/role-mcp-probe.mjs b/packages/tmux-bridge/bin/role-mcp-probe.mjs index 01faad6b..6ef7b435 100644 --- a/packages/tmux-bridge/bin/role-mcp-probe.mjs +++ b/packages/tmux-bridge/bin/role-mcp-probe.mjs @@ -2,12 +2,14 @@ import { spawn } from 'node:child_process'; import { isAbsolute } from 'node:path'; +const configurationError = message => Object.assign(new Error(message), { code: 'MCP_PROBE_CONFIGURATION' }); + export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { - if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw new Error('invalid MCP allowlist'); + if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw configurationError('invalid MCP allowlist'); return (name, { signal } = {}) => { - if (typeof name !== 'string' || !Object.hasOwn(allowlist, name)) throw new Error('MCP is not allowlisted'); + if (typeof name !== 'string' || !Object.hasOwn(allowlist, name)) throw configurationError('MCP is not allowlisted'); const entry = allowlist[name]; - if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error('invalid MCP allowlist entry'); + if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw configurationError('invalid MCP allowlist entry'); return probeStdioMcp({ command: entry.command, env: entry.env, timeoutMs, signal }); }; } @@ -15,7 +17,7 @@ export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { // The profile contains identifiers only. Callers must resolve them using a // trusted private allowlist; never construct this command from session text. export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal, spawnProcess = spawn }) { - if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw new Error('invalid MCP probe configuration'); + if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw configurationError('invalid MCP probe configuration'); return new Promise((resolve, reject) => { let child, timer, reapTimer, buffer = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false; let onAbort; diff --git a/packages/tmux-bridge/test/role-mcp-probe.test.mjs b/packages/tmux-bridge/test/role-mcp-probe.test.mjs index f9ff7af2..144bb25d 100644 --- a/packages/tmux-bridge/test/role-mcp-probe.test.mjs +++ b/packages/tmux-bridge/test/role-mcp-probe.test.mjs @@ -69,3 +69,10 @@ test('unobserved process closure fails planning instead of treating MCP as offli const probe = (_name, { signal }) => probeStdioMcp({ command: [process.execPath], timeoutMs: 5, signal, spawnProcess: () => child }); await assert.rejects(planRoleLaunch({ profile, authority, probe, timeoutMs: 1400 }), /probe cancellation unconfirmed/); }); + +test('missing or invalid private MCP configuration stops planning', async () => { + const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['wanted'], plugins: [] }; + const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['wanted'], plugins: [] }; + await assert.rejects(planRoleLaunch({ profile, authority, probe: roleProbeFromAllowlist({}) }), /not allowlisted/); + await assert.rejects(planRoleLaunch({ profile, authority, probe: roleProbeFromAllowlist({ wanted: { command: ['relative-program'] } }) }), /invalid MCP probe configuration/); +}); diff --git a/skills/agent-tmux/bin/role-launch-profile.mjs b/skills/agent-tmux/bin/role-launch-profile.mjs index 30b5e1ac..33abcad6 100644 --- a/skills/agent-tmux/bin/role-launch-profile.mjs +++ b/skills/agent-tmux/bin/role-launch-profile.mjs @@ -21,7 +21,7 @@ export async function planRoleLaunch({ profile, authority, probe, timeoutMs = 30 unavailable.push(name); continue; } (result === true ? available : unavailable).push(name); - } catch (error) { if (error?.message === 'probe cancellation unconfirmed') throw error; unavailable.push(name); } + } catch (error) { if (error?.message === 'probe cancellation unconfirmed' || error?.code === 'MCP_PROBE_CONFIGURATION') throw error; unavailable.push(name); } finally { clearTimeout(timer); clearTimeout(cleanupTimer); controller.abort(); } } return { schema: 'agent-mesh.role-launch-plan.v1', role: profile.role, permissions: [...profile.permissions], plugins: [...profile.plugins], mcpToStart: available, mcpUnavailable: unavailable }; diff --git a/skills/agent-tmux/bin/role-mcp-probe.mjs b/skills/agent-tmux/bin/role-mcp-probe.mjs index 01faad6b..6ef7b435 100644 --- a/skills/agent-tmux/bin/role-mcp-probe.mjs +++ b/skills/agent-tmux/bin/role-mcp-probe.mjs @@ -2,12 +2,14 @@ import { spawn } from 'node:child_process'; import { isAbsolute } from 'node:path'; +const configurationError = message => Object.assign(new Error(message), { code: 'MCP_PROBE_CONFIGURATION' }); + export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { - if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw new Error('invalid MCP allowlist'); + if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw configurationError('invalid MCP allowlist'); return (name, { signal } = {}) => { - if (typeof name !== 'string' || !Object.hasOwn(allowlist, name)) throw new Error('MCP is not allowlisted'); + if (typeof name !== 'string' || !Object.hasOwn(allowlist, name)) throw configurationError('MCP is not allowlisted'); const entry = allowlist[name]; - if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error('invalid MCP allowlist entry'); + if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw configurationError('invalid MCP allowlist entry'); return probeStdioMcp({ command: entry.command, env: entry.env, timeoutMs, signal }); }; } @@ -15,7 +17,7 @@ export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { // The profile contains identifiers only. Callers must resolve them using a // trusted private allowlist; never construct this command from session text. export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal, spawnProcess = spawn }) { - if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw new Error('invalid MCP probe configuration'); + if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw configurationError('invalid MCP probe configuration'); return new Promise((resolve, reject) => { let child, timer, reapTimer, buffer = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false; let onAbort; From d37af0cd198fb9b857cd417d7b44b787ecc61790 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:36:07 +0000 Subject: [PATCH 066/113] Record failed trigger preflight without retaining reservation --- docs/design/plexus-channels.md | 4 +++- packages/tmux-bridge/bin/trigger-journal.mjs | 2 +- .../tmux-bridge/bin/trigger-transaction.mjs | 18 +++++++++++++----- .../tmux-bridge/test/trigger-journal.test.mjs | 17 +++++++++++++++++ skills/agent-tmux/bin/trigger-journal.mjs | 2 +- skills/agent-tmux/bin/trigger-transaction.mjs | 18 +++++++++++++----- 6 files changed, 48 insertions(+), 13 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index a0962798..fec9c1f6 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -44,7 +44,9 @@ trigger sets and durably record intent before each move. Its adapter must compare the original target and a never-reused state version atomically and expose the operation ID on readback. Definite refusal rolls back earlier verified moves using the same compare-and-set contract; an ambiguous result stays unresolved and is not -retried. Dry-run reads and journals a plan without moving triggers. Concrete +retried. A failed preflight read records a terminal not-applied receipt before +releasing its reservation; no trigger move has been attempted. Dry-run reads +and journals a plan without moving triggers. Concrete timer and cloud adapters are not yet provided; this engine is not authorization to change live triggers. diff --git a/packages/tmux-bridge/bin/trigger-journal.mjs b/packages/tmux-bridge/bin/trigger-journal.mjs index 5603d817..fa92734e 100644 --- a/packages/tmux-bridge/bin/trigger-journal.mjs +++ b/packages/tmux-bridge/bin/trigger-journal.mjs @@ -4,7 +4,7 @@ import { createHash, randomUUID } from 'node:crypto'; import { isAbsolute, join } from 'node:path'; const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); -const terminal = new Set(['verified', 'rolled-back', 'dry-run']); +const terminal = new Set(['verified', 'rolled-back', 'dry-run', 'not-applied']); const statuses = new Set(['planning', 'applying', 'rolling-back', 'uncertain', ...terminal]); const key = trigger => JSON.stringify([trigger.kind, trigger.id]); diff --git a/packages/tmux-bridge/bin/trigger-transaction.mjs b/packages/tmux-bridge/bin/trigger-transaction.mjs index 557b792a..1b586d77 100644 --- a/packages/tmux-bridge/bin/trigger-transaction.mjs +++ b/packages/tmux-bridge/bin/trigger-transaction.mjs @@ -11,13 +11,21 @@ export async function reconcileTriggers({ triggers, from, to, transactionId, ada if (!token(trigger?.kind) || !token(trigger?.id) || seen.has(`${trigger.kind}\0${trigger.id}`)) throw new Error('invalid or duplicate trigger'); seen.add(`${trigger.kind}\0${trigger.id}`); } - const receipt = { schema: 'agent-mesh.trigger-transaction.v1', id: transactionId, from, to, dryRun, status: 'planning', triggers: [] }; + const receipt = { schema: 'agent-mesh.trigger-transaction.v1', id: transactionId, from, to, dryRun, status: 'planning', triggers: triggers.map(({ kind, id }) => ({ kind, id, status: 'pending' })) }; await journal.begin({ id: transactionId, triggers: structuredClone(triggers), dryRun }); const save = () => journal.write(structuredClone(receipt)); - for (const trigger of triggers) { - const current = await adapter.read(trigger); - if (!current || current.target !== from || !token(current.version)) throw new Error('trigger source or version not verified'); - receipt.triggers.push({ kind: trigger.kind, id: trigger.id, before: current.version, status: 'planned' }); + for (let i = 0; i < triggers.length; i++) { + let current; + try { current = await adapter.read(triggers[i]); } catch { /* No mutation has been attempted. */ } + if (!current || current.target !== from || !token(current.version)) { + receipt.triggers[i].status = 'unverified'; + receipt.status = 'not-applied'; + receipt.reason = 'trigger source or version not verified'; + await save(); + return receipt; + } + receipt.triggers[i].before = current.version; + receipt.triggers[i].status = 'planned'; } receipt.status = dryRun ? 'dry-run' : 'applying'; await save(); diff --git a/packages/tmux-bridge/test/trigger-journal.test.mjs b/packages/tmux-bridge/test/trigger-journal.test.mjs index 36b405cf..aeae672a 100644 --- a/packages/tmux-bridge/test/trigger-journal.test.mjs +++ b/packages/tmux-bridge/test/trigger-journal.test.mjs @@ -112,3 +112,20 @@ test('journal refuses unsafe permissions, invalid state and abandoned locks', as await writeFile(join(root, '.trigger-transactions.lock'), 'fixture', { mode: 0o600 }); await assert.rejects(journal.begin(reservation), /lock held/); }); + +test('preflight read failure is durably not-applied and releases the reservation', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-preflight-')); + t.after(() => rm(root, { recursive: true, force: true })); + const triggers = [{ kind: 'timer', id: 'one' }, { kind: 'timer', id: 'two' }]; + let moves = 0; + const adapter = { read: async ({ id }) => { if (id === 'two') throw new Error('offline'); return { target: 'codex:old', version: 'v1' }; }, move: async () => { moves++; } }; + const journal = triggerJournal(root); + const receipt = await reconcileTriggers({ triggers, from: 'codex:old', to: 'codex:new', transactionId: 'first', adapter, journal, dryRun: false }); + assert.equal(receipt.status, 'not-applied'); + assert.equal(receipt.triggers[1].status, 'unverified'); + assert.equal(moves, 0); + const stored = await triggerJournal(root).get('first'); + assert.equal(stored.status, 'not-applied'); + assert.equal(stored.receipt.reason, 'trigger source or version not verified'); + await triggerJournal(root).begin({ id: 'second', triggers, dryRun: true }); +}); diff --git a/skills/agent-tmux/bin/trigger-journal.mjs b/skills/agent-tmux/bin/trigger-journal.mjs index 5603d817..fa92734e 100644 --- a/skills/agent-tmux/bin/trigger-journal.mjs +++ b/skills/agent-tmux/bin/trigger-journal.mjs @@ -4,7 +4,7 @@ import { createHash, randomUUID } from 'node:crypto'; import { isAbsolute, join } from 'node:path'; const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); -const terminal = new Set(['verified', 'rolled-back', 'dry-run']); +const terminal = new Set(['verified', 'rolled-back', 'dry-run', 'not-applied']); const statuses = new Set(['planning', 'applying', 'rolling-back', 'uncertain', ...terminal]); const key = trigger => JSON.stringify([trigger.kind, trigger.id]); diff --git a/skills/agent-tmux/bin/trigger-transaction.mjs b/skills/agent-tmux/bin/trigger-transaction.mjs index 557b792a..1b586d77 100644 --- a/skills/agent-tmux/bin/trigger-transaction.mjs +++ b/skills/agent-tmux/bin/trigger-transaction.mjs @@ -11,13 +11,21 @@ export async function reconcileTriggers({ triggers, from, to, transactionId, ada if (!token(trigger?.kind) || !token(trigger?.id) || seen.has(`${trigger.kind}\0${trigger.id}`)) throw new Error('invalid or duplicate trigger'); seen.add(`${trigger.kind}\0${trigger.id}`); } - const receipt = { schema: 'agent-mesh.trigger-transaction.v1', id: transactionId, from, to, dryRun, status: 'planning', triggers: [] }; + const receipt = { schema: 'agent-mesh.trigger-transaction.v1', id: transactionId, from, to, dryRun, status: 'planning', triggers: triggers.map(({ kind, id }) => ({ kind, id, status: 'pending' })) }; await journal.begin({ id: transactionId, triggers: structuredClone(triggers), dryRun }); const save = () => journal.write(structuredClone(receipt)); - for (const trigger of triggers) { - const current = await adapter.read(trigger); - if (!current || current.target !== from || !token(current.version)) throw new Error('trigger source or version not verified'); - receipt.triggers.push({ kind: trigger.kind, id: trigger.id, before: current.version, status: 'planned' }); + for (let i = 0; i < triggers.length; i++) { + let current; + try { current = await adapter.read(triggers[i]); } catch { /* No mutation has been attempted. */ } + if (!current || current.target !== from || !token(current.version)) { + receipt.triggers[i].status = 'unverified'; + receipt.status = 'not-applied'; + receipt.reason = 'trigger source or version not verified'; + await save(); + return receipt; + } + receipt.triggers[i].before = current.version; + receipt.triggers[i].status = 'planned'; } receipt.status = dryRun ? 'dry-run' : 'applying'; await save(); From 64677e9ae6e847bc2abafeeff0cf3b1d3e060bfc Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:40:43 +0000 Subject: [PATCH 067/113] Observe final notice in local Claude transcripts --- docs/design/plexus-channels.md | 8 ++- .../bin/handover-claude-observation.mjs | 63 +++++++++++++++++++ .../test/handover-claude-observation.test.mjs | 53 ++++++++++++++++ .../bin/handover-claude-observation.mjs | 63 +++++++++++++++++++ 4 files changed, 185 insertions(+), 2 deletions(-) create mode 100644 packages/tmux-bridge/bin/handover-claude-observation.mjs create mode 100644 packages/tmux-bridge/test/handover-claude-observation.test.mjs create mode 100644 skills/agent-tmux/bin/handover-claude-observation.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index fec9c1f6..9572d3e3 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -103,8 +103,12 @@ matching completed turn. It fails closed for ambiguous files, malformed or partial records, and identity mismatches. It returns hashes, never transcript contents. This observation is local evidence at the instant read, not proof that no later turn can arrive; safe finality still requires exclusive lifecycle -control and an authenticated source. Claude and cloud transcripts are not -supported by this observer. +control and an authenticated source. + +`handover-claude-observation.mjs` performs a comparable local Claude snapshot +check bound to session, request nonce, exact notice and completed turn. It +rejects later user turns and tool calls. Both observers return evidence only; +neither sends a message, proves remote cloud delivery, or enables a cutover. # Role-scoped restart preparation The `agent-mesh.restart.v1` YAML handover block requires `role_profile` when diff --git a/packages/tmux-bridge/bin/handover-claude-observation.mjs b/packages/tmux-bridge/bin/handover-claude-observation.mjs new file mode 100644 index 00000000..2123c009 --- /dev/null +++ b/packages/tmux-bridge/bin/handover-claude-observation.mjs @@ -0,0 +1,63 @@ +/** Read-only final-notice evidence from one stable local Claude transcript snapshot. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const MAX_TRANSCRIPT = 128 * 1024 * 1024; + +/** Proves only the stable snapshot read; later turns can invalidate the notice. */ +export async function observeClaudeFinalNotice({ root, id, nonce, message }) { + if (typeof root !== 'string' || !isAbsolute(root) || typeof id !== 'string' || !UUID.test(id) || + typeof nonce !== 'string' || !nonce.startsWith('handover-') || !UUID.test(nonce.slice('handover-'.length)) || + typeof message !== 'string' || !message || Buffer.byteLength(message) > 8192) throw new Error('invalid notice observation request'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const candidates = entries.filter(entry => entry.isFile() && entry.name.toLowerCase() === `${id.toLowerCase()}.jsonl`) + .map(entry => join(entry.parentPath, entry.name)); + if (candidates.length !== 1) throw new Error('transcript identity unavailable or ambiguous'); + const path = candidates[0]; + if (await realpath(path) !== path) throw new Error('non-canonical transcript'); + const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await handle.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > MAX_TRANSCRIPT) throw new Error('invalid transcript file'); + bytes = await handle.readFile(); + const after = await handle.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + } finally { await handle.close(); } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let anchored = false, responseId = null, answer = '', completed = false; + for (const line of text.split('\n')) { + if (!line) continue; + let record; + try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + if (record.isSidechain || record.isMeta || !['user', 'assistant'].includes(record.type)) continue; + if (record.sessionId !== id) throw new Error('transcript session mismatch'); + const content = record.message?.content; + if (record.type === 'user') { + const parts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text) : []; + if (parts.length) { anchored = parts.join('\n').includes(`[HANDOVER:${nonce}]`); responseId = null; answer = ''; completed = false; } + continue; + } + if (!anchored) continue; + const native = record.message; + if (!native || typeof native.id !== 'string' || !native.id || !Array.isArray(content)) throw new Error('invalid assistant record'); + if (native.id !== responseId) { responseId = native.id; answer = ''; completed = false; } + const toolUse = content.some(part => part?.type === 'tool_use'); + const parts = content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text); + if (parts.length) answer += parts.join('\n'); + if (native.stop_reason === 'end_turn' && !toolUse) completed = true; + else if (native.stop_reason !== null && native.stop_reason !== undefined) completed = false; + } + if (!anchored || !completed || answer !== message) throw new Error('final notice not proven in transcript snapshot'); + return { schema: 'agent-mesh.final-notice-observation.v1', session: `claude:${id}`, nonce, + messageSha256: createHash('sha256').update(message).digest('hex'), transcriptSha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length }; +} diff --git a/packages/tmux-bridge/test/handover-claude-observation.test.mjs b/packages/tmux-bridge/test/handover-claude-observation.test.mjs new file mode 100644 index 00000000..efe8ec0d --- /dev/null +++ b/packages/tmux-bridge/test/handover-claude-observation.test.mjs @@ -0,0 +1,53 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { mkdtemp, mkdir, writeFile, rm, link } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { observeClaudeFinalNotice } from '../bin/handover-claude-observation.mjs'; + +const id = '22222222-2222-4222-8222-222222222222'; +const nonce = 'handover-33333333-3333-4333-8333-333333333333'; +const message = 'Sleeping. Continue [here](codex://threads/22222222-2222-4222-8222-222222222222)'; +const request = { type: 'user', sessionId: id, message: { content: `[HANDOVER:${nonce}] fixture` } }; +const assistant = (content, stop = 'end_turn', nativeId = 'message-1') => ({ type: 'assistant', sessionId: id, message: { id: nativeId, stop_reason: stop, content } }); +const answer = assistant([{ type: 'text', text: message }]); +async function fixture(t, records) { + const root = await mkdtemp(join(tmpdir(), 'claude-notice-')); + t.after(() => rm(root, { recursive: true, force: true })); + const project = join(root, 'project'); await mkdir(project); + const path = join(project, `${id}.jsonl`); + await writeFile(path, records.map(value => JSON.stringify(value)).join('\n') + '\n', { mode: 0o600 }); + return { root, path, observe: () => observeClaudeFinalNotice({ root, id, nonce, message }) }; +} + +test('a completed exact local Claude response is bound to its session and anchor', async t => { + const f = await fixture(t, [request, assistant([{ type: 'thinking', thinking: 'synthetic' }]), answer]); + const proof = await f.observe(); + assert.equal(proof.session, `claude:${id}`); + assert.match(proof.transcriptSha256, /^[a-f0-9]{64}$/); + assert.equal(proof.nonce, nonce); +}); + +test('later turns, tool use, incomplete answers and session mismatch fail closed', async t => { + for (const records of [ + [request, answer, { ...request, message: { content: 'later turn' } }], + [request, answer, assistant([{ type: 'tool_use', id: 'fixture', name: 'fixture' }], 'tool_use', 'message-2')], + [request, assistant([{ type: 'text', text: message }], 'tool_use')], + [request, assistant([{ type: 'text', text: message }, { type: 'tool_use', id: 'fixture' }], 'end_turn')], + [request, { ...answer, sessionId: '44444444-4444-4444-8444-444444444444' }], + [{ ...request, message: { content: 'wrong anchor' } }, answer], + [request, assistant([{ type: 'text', text: `${message} extra` }])], + ]) { + const f = await fixture(t, records); + await assert.rejects(f.observe()); + } +}); + +test('incomplete or hard-linked transcript is rejected', async t => { + const f = await fixture(t, [request, answer]); + await writeFile(f.path, JSON.stringify(request), { mode: 0o600 }); + await assert.rejects(f.observe(), /partial/); + await writeFile(f.path, `${JSON.stringify(request)}\n${JSON.stringify(answer)}\n`); + await link(f.path, join(f.root, 'other-link')); + await assert.rejects(f.observe(), /invalid transcript file/); +}); diff --git a/skills/agent-tmux/bin/handover-claude-observation.mjs b/skills/agent-tmux/bin/handover-claude-observation.mjs new file mode 100644 index 00000000..2123c009 --- /dev/null +++ b/skills/agent-tmux/bin/handover-claude-observation.mjs @@ -0,0 +1,63 @@ +/** Read-only final-notice evidence from one stable local Claude transcript snapshot. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const MAX_TRANSCRIPT = 128 * 1024 * 1024; + +/** Proves only the stable snapshot read; later turns can invalidate the notice. */ +export async function observeClaudeFinalNotice({ root, id, nonce, message }) { + if (typeof root !== 'string' || !isAbsolute(root) || typeof id !== 'string' || !UUID.test(id) || + typeof nonce !== 'string' || !nonce.startsWith('handover-') || !UUID.test(nonce.slice('handover-'.length)) || + typeof message !== 'string' || !message || Buffer.byteLength(message) > 8192) throw new Error('invalid notice observation request'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const candidates = entries.filter(entry => entry.isFile() && entry.name.toLowerCase() === `${id.toLowerCase()}.jsonl`) + .map(entry => join(entry.parentPath, entry.name)); + if (candidates.length !== 1) throw new Error('transcript identity unavailable or ambiguous'); + const path = candidates[0]; + if (await realpath(path) !== path) throw new Error('non-canonical transcript'); + const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await handle.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > MAX_TRANSCRIPT) throw new Error('invalid transcript file'); + bytes = await handle.readFile(); + const after = await handle.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + } finally { await handle.close(); } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let anchored = false, responseId = null, answer = '', completed = false; + for (const line of text.split('\n')) { + if (!line) continue; + let record; + try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + if (record.isSidechain || record.isMeta || !['user', 'assistant'].includes(record.type)) continue; + if (record.sessionId !== id) throw new Error('transcript session mismatch'); + const content = record.message?.content; + if (record.type === 'user') { + const parts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text) : []; + if (parts.length) { anchored = parts.join('\n').includes(`[HANDOVER:${nonce}]`); responseId = null; answer = ''; completed = false; } + continue; + } + if (!anchored) continue; + const native = record.message; + if (!native || typeof native.id !== 'string' || !native.id || !Array.isArray(content)) throw new Error('invalid assistant record'); + if (native.id !== responseId) { responseId = native.id; answer = ''; completed = false; } + const toolUse = content.some(part => part?.type === 'tool_use'); + const parts = content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text); + if (parts.length) answer += parts.join('\n'); + if (native.stop_reason === 'end_turn' && !toolUse) completed = true; + else if (native.stop_reason !== null && native.stop_reason !== undefined) completed = false; + } + if (!anchored || !completed || answer !== message) throw new Error('final notice not proven in transcript snapshot'); + return { schema: 'agent-mesh.final-notice-observation.v1', session: `claude:${id}`, nonce, + messageSha256: createHash('sha256').update(message).digest('hex'), transcriptSha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length }; +} From f2a6abaa9964450719077d16250f9946501a00ec Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:44:45 +0000 Subject: [PATCH 068/113] Add local native final notice adapter --- docs/design/plexus-channels.md | 8 +++ .../bin/handover-notice-transport.mjs | 48 ++++++++++++++++ .../test/handover-notice-transport.test.mjs | 56 +++++++++++++++++++ .../bin/handover-notice-transport.mjs | 48 ++++++++++++++++ 4 files changed, 160 insertions(+) create mode 100644 packages/tmux-bridge/bin/handover-notice-transport.mjs create mode 100644 packages/tmux-bridge/test/handover-notice-transport.test.mjs create mode 100644 skills/agent-tmux/bin/handover-notice-transport.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 9572d3e3..aaba3b29 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -109,6 +109,14 @@ control and an authenticated source. check bound to session, request nonce, exact notice and completed turn. It rejects later user turns and tool calls. Both observers return evidence only; neither sends a message, proves remote cloud delivery, or enables a cutover. + +`handover-notice-transport.mjs` can enqueue a correlated final-notice request +through the existing local native transport and independently inspect the +resulting local transcript. Queue acceptance is not publication proof. The +caller must first durably reserve the request, verify the successor, and hold +exclusive lifecycle control; a failed or held enqueue must not be retried +blindly. These prerequisites are not yet connected, and this adapter is not +wired to cutover or cloud delivery. # Role-scoped restart preparation The `agent-mesh.restart.v1` YAML handover block requires `role_profile` when diff --git a/packages/tmux-bridge/bin/handover-notice-transport.mjs b/packages/tmux-bridge/bin/handover-notice-transport.mjs new file mode 100644 index 00000000..1107f141 --- /dev/null +++ b/packages/tmux-bridge/bin/handover-notice-transport.mjs @@ -0,0 +1,48 @@ +/** Native queue adapter; this module does not authorize or perform a cutover. */ +import { execFile } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { formatFinalNotice } from './handover-notice.mjs'; +import { observeCodexFinalNotice } from './handover-codex-observation.mjs'; +import { observeClaudeFinalNotice } from './handover-claude-observation.mjs'; + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); +const digest = value => createHash('sha256').update(value).digest('hex'); +const exec = (command, args, { input, ...options }) => new Promise((resolve, reject) => { + const child = execFile(command, args, options, (error, stdout) => error ? reject(new Error('native notice delivery uncertain')) : resolve({ stdout })); + child.stdin.on('error', () => {}); + child.stdin.end(input); +}); + +/** The caller must first durably reserve this nonce and verify the successor. */ +export async function queueLocalFinalNotice({ session, nonce, target, label, prefix, managedInboxRoot }, runNative = exec) { + if (typeof session !== 'string') throw new Error('invalid local notice session'); + const [agent, id, ...extra] = session.split(':'); + if (!['codex', 'claude'].includes(agent) || !uuid.test(id || '') || extra.length || typeof nonce !== 'string' || !nonce.startsWith('handover-') || !uuid.test(nonce.slice('handover-'.length))) throw new Error('invalid local notice request'); + if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); + if (agent === 'codex' && managedInboxRoot !== undefined) throw new Error('managed inbox only for Claude'); + const notice = formatFinalNotice({ target, label, prefix }); + const prompt = `[HANDOVER:${nonce}] The successor has been verified. As your final message, output exactly the following notice and nothing else. Do not call any tools after writing it.\n${notice}`; + const args = [nativeBin, '--agent', agent, '--session', id, '--correlation-id', nonce, '--timeout', '5', '--message-stdin', '--delivery-only']; + if (agent === 'codex') args.push('--no-resume'); + else args.push('--managed-inbox-root', managedInboxRoot); + let result; + try { result = await runNative(process.execPath, args, { input: prompt, timeout: 10000, maxBuffer: 8192 }); } + catch { throw new Error('native notice delivery uncertain; do not resend'); } + let receipt; + try { receipt = JSON.parse(result?.stdout); } catch { throw new Error('native notice delivery uncertain; do not resend'); } + if (!receipt || receipt.agent !== agent || receipt.sessionId !== id || receipt.correlationId !== nonce || receipt.held === true || receipt.status !== 'queued') throw new Error('native notice delivery unconfirmed; do not resend'); + return { schema: 'agent-mesh.notice-queue.v1', session, nonce, noticeSha256: digest(notice), status: 'queued-unverified' }; +} + +/** Obtain local native transcript evidence independently from the queue receipt. */ +export async function observeLocalFinalNotice({ session, nonce, target, label, prefix, transcriptRoot }) { + if (typeof session !== 'string') throw new Error('invalid local notice session'); + const [agent, id, ...extra] = session.split(':'); + if (!['codex', 'claude'].includes(agent) || !uuid.test(id || '') || extra.length) throw new Error('invalid local notice session'); + const message = formatFinalNotice({ target, label, prefix }); + const observe = agent === 'codex' ? observeCodexFinalNotice : observeClaudeFinalNotice; + return observe({ root: transcriptRoot, id, nonce, message }); +} diff --git a/packages/tmux-bridge/test/handover-notice-transport.test.mjs b/packages/tmux-bridge/test/handover-notice-transport.test.mjs new file mode 100644 index 00000000..a76acfe0 --- /dev/null +++ b/packages/tmux-bridge/test/handover-notice-transport.test.mjs @@ -0,0 +1,56 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { queueLocalFinalNotice, observeLocalFinalNotice } from '../bin/handover-notice-transport.mjs'; +import { formatFinalNotice } from '../bin/handover-notice.mjs'; + +const id = '22222222-2222-4222-8222-222222222222'; +const nonce = 'handover-33333333-3333-4333-8333-333333333333'; +const options = { session: `claude:${id}`, nonce, target: { kind: 'codex', id }, prefix: 'Sleeping.', label: 'Continue here', managedInboxRoot: '/synthetic/inbox' }; +const notice = formatFinalNotice(options); +const response = { status: 'queued', agent: 'claude', sessionId: id, correlationId: nonce }; + +test('native adapter sends the correlated notice request on stdin and reports queue only', async () => { + let called = 0; + const queued = await queueLocalFinalNotice(options, async (command, args, config) => { + called++; + assert.equal(command, process.execPath); + assert.ok(args.includes('--delivery-only')); + assert.ok(args.includes('--managed-inbox-root')); + assert.ok(args.includes('--message-stdin')); + assert.ok(!args.includes(notice)); + assert.ok(config.input.includes(`[HANDOVER:${nonce}]`)); + assert.ok(config.input.endsWith(notice)); + return { stdout: JSON.stringify(response) }; + }); + assert.equal(called, 1); + assert.equal(queued.status, 'queued-unverified'); + assert.equal(queued.session, options.session); + assert.match(queued.noticeSha256, /^[a-f0-9]{64}$/); +}); + +test('a held, mismatched or failed enqueue is never declared delivered', async () => { + for (const value of [{ ...response, held: true }, { ...response, correlationId: 'other' }, { ...response, status: 'delivered' }, null]) { + await assert.rejects(queueLocalFinalNotice(options, async () => ({ stdout: JSON.stringify(value) })), /unconfirmed/); + } + await assert.rejects(queueLocalFinalNotice(options, async () => { throw new Error('fixture'); }), /uncertain; do not resend/); + await assert.rejects(queueLocalFinalNotice({ ...options, session: 'claude:broken' }, async () => { throw new Error('should not run'); }), /invalid/); +}); + +test('queue is followed by separately observed Claude transcript evidence', async t => { + const root = await mkdtemp(join(tmpdir(), 'notice-route-')); + t.after(() => rm(root, { recursive: true, force: true })); + const project = join(root, 'project'); await mkdir(project); + const records = [ + { type: 'user', sessionId: id, message: { content: `[HANDOVER:${nonce}] synthetic request` } }, + { type: 'assistant', sessionId: id, message: { id: 'response-1', stop_reason: 'end_turn', content: [{ type: 'text', text: notice }] } } + ]; + await writeFile(join(project, `${id}.jsonl`), records.map(item => JSON.stringify(item)).join('\n') + '\n', { mode: 0o600 }); + const queue = await queueLocalFinalNotice(options, async () => ({ stdout: JSON.stringify(response) })); + const proof = await observeLocalFinalNotice({ ...options, transcriptRoot: root }); + assert.equal(proof.session, queue.session); + assert.equal(proof.messageSha256, queue.noticeSha256); + assert.equal(proof.nonce, queue.nonce); +}); diff --git a/skills/agent-tmux/bin/handover-notice-transport.mjs b/skills/agent-tmux/bin/handover-notice-transport.mjs new file mode 100644 index 00000000..1107f141 --- /dev/null +++ b/skills/agent-tmux/bin/handover-notice-transport.mjs @@ -0,0 +1,48 @@ +/** Native queue adapter; this module does not authorize or perform a cutover. */ +import { execFile } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { formatFinalNotice } from './handover-notice.mjs'; +import { observeCodexFinalNotice } from './handover-codex-observation.mjs'; +import { observeClaudeFinalNotice } from './handover-claude-observation.mjs'; + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); +const digest = value => createHash('sha256').update(value).digest('hex'); +const exec = (command, args, { input, ...options }) => new Promise((resolve, reject) => { + const child = execFile(command, args, options, (error, stdout) => error ? reject(new Error('native notice delivery uncertain')) : resolve({ stdout })); + child.stdin.on('error', () => {}); + child.stdin.end(input); +}); + +/** The caller must first durably reserve this nonce and verify the successor. */ +export async function queueLocalFinalNotice({ session, nonce, target, label, prefix, managedInboxRoot }, runNative = exec) { + if (typeof session !== 'string') throw new Error('invalid local notice session'); + const [agent, id, ...extra] = session.split(':'); + if (!['codex', 'claude'].includes(agent) || !uuid.test(id || '') || extra.length || typeof nonce !== 'string' || !nonce.startsWith('handover-') || !uuid.test(nonce.slice('handover-'.length))) throw new Error('invalid local notice request'); + if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); + if (agent === 'codex' && managedInboxRoot !== undefined) throw new Error('managed inbox only for Claude'); + const notice = formatFinalNotice({ target, label, prefix }); + const prompt = `[HANDOVER:${nonce}] The successor has been verified. As your final message, output exactly the following notice and nothing else. Do not call any tools after writing it.\n${notice}`; + const args = [nativeBin, '--agent', agent, '--session', id, '--correlation-id', nonce, '--timeout', '5', '--message-stdin', '--delivery-only']; + if (agent === 'codex') args.push('--no-resume'); + else args.push('--managed-inbox-root', managedInboxRoot); + let result; + try { result = await runNative(process.execPath, args, { input: prompt, timeout: 10000, maxBuffer: 8192 }); } + catch { throw new Error('native notice delivery uncertain; do not resend'); } + let receipt; + try { receipt = JSON.parse(result?.stdout); } catch { throw new Error('native notice delivery uncertain; do not resend'); } + if (!receipt || receipt.agent !== agent || receipt.sessionId !== id || receipt.correlationId !== nonce || receipt.held === true || receipt.status !== 'queued') throw new Error('native notice delivery unconfirmed; do not resend'); + return { schema: 'agent-mesh.notice-queue.v1', session, nonce, noticeSha256: digest(notice), status: 'queued-unverified' }; +} + +/** Obtain local native transcript evidence independently from the queue receipt. */ +export async function observeLocalFinalNotice({ session, nonce, target, label, prefix, transcriptRoot }) { + if (typeof session !== 'string') throw new Error('invalid local notice session'); + const [agent, id, ...extra] = session.split(':'); + if (!['codex', 'claude'].includes(agent) || !uuid.test(id || '') || extra.length) throw new Error('invalid local notice session'); + const message = formatFinalNotice({ target, label, prefix }); + const observe = agent === 'codex' ? observeCodexFinalNotice : observeClaudeFinalNotice; + return observe({ root: transcriptRoot, id, nonce, message }); +} From 1f41606da44ca631b890131376869187f54be211 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:50:12 +0000 Subject: [PATCH 069/113] Reserve final notices before local delivery --- docs/design/plexus-channels.md | 6 +++- packages/tmux-bridge/bin/channel-state.mjs | 18 ++++++++++++ .../bin/handover-notice-transport.mjs | 6 ++++ packages/tmux-bridge/bin/mesh-graph.mjs | 19 ++++++++++-- .../tmux-bridge/test/channel-state.test.mjs | 16 +++++++++- .../test/handover-notice-transport.test.mjs | 14 ++++++++- .../test/plexus-channel-store.test.mjs | 29 +++++++++++++++++++ skills/agent-tmux/bin/channel-state.mjs | 18 ++++++++++++ .../bin/handover-notice-transport.mjs | 6 ++++ skills/agent-tmux/bin/mesh-graph.mjs | 19 ++++++++++-- 10 files changed, 144 insertions(+), 7 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index aaba3b29..4c18e819 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -116,7 +116,11 @@ resulting local transcript. Queue acceptance is not publication proof. The caller must first durably reserve the request, verify the successor, and hold exclusive lifecycle control; a failed or held enqueue must not be retried blindly. These prerequisites are not yet connected, and this adapter is not -wired to cutover or cloud delivery. +wired to cutover or cloud delivery. A graph `channel reserve-notice` transition +requires verified state and a freshly verified Codex successor, binds the +notice digest and nonce, and survives replay. The adapter can bind an enqueue +to that reservation, but does not acquire lifecycle exclusion or settle the +receipt in the graph. The actual cutover remains disabled. # Role-scoped restart preparation The `agent-mesh.restart.v1` YAML handover block requires `role_profile` when diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 05661ab6..5bdc7be8 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -91,8 +91,26 @@ export function completeStatePreparation(state, proof) { return next; } +// The durable reservation survives crashes; only authenticated evidence can +// settle it. It does not itself verify the successor or send a notice. +export function reserveFinalNotice(state, id, successor, noticeSha256) { + if (state.phase !== 'handover' || state.finalNotice || state.statePreparation?.status !== 'verified' || state.statePreparation.session !== state.session || state.statePreparation.generation !== state.generation || !identifier(id) || !identifier(successor) || successor === state.session || !/^[a-f0-9]{64}$/.test(noticeSha256 || '') || state.queue.some(item => item.state === 'inflight')) throw new Error('final notice reservation unavailable'); + const next = copy(state); + next.finalNotice = { id, session: state.session, generation: state.generation, successor, noticeSha256, status: 'requested' }; + return next; +} + +export function recordNoticeQueued(state, receipt) { + const pending = state.finalNotice; + if (state.phase !== 'handover' || !pending || pending.status !== 'requested' || pending.session !== state.session || pending.generation !== state.generation || !receipt || receipt.schema !== 'agent-mesh.notice-queue.v1' || receipt.status !== 'queued-unverified' || receipt.session !== pending.session || receipt.nonce !== pending.id || receipt.noticeSha256 !== pending.noticeSha256) throw new Error('notice queue receipt does not match reservation'); + const next = copy(state); + next.finalNotice.status = 'queued-unverified'; + return next; +} + export function finishHandover(state, session, verified) { if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); + if (state.finalNotice && state.finalNotice.status !== 'verified') throw new Error('final notice unresolved'); if (state.statePreparation && state.statePreparation.status !== 'verified') throw new Error('state preparation unresolved'); if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); const next = copy(state); diff --git a/packages/tmux-bridge/bin/handover-notice-transport.mjs b/packages/tmux-bridge/bin/handover-notice-transport.mjs index 1107f141..455f37df 100644 --- a/packages/tmux-bridge/bin/handover-notice-transport.mjs +++ b/packages/tmux-bridge/bin/handover-notice-transport.mjs @@ -37,6 +37,12 @@ export async function queueLocalFinalNotice({ session, nonce, target, label, pre return { schema: 'agent-mesh.notice-queue.v1', session, nonce, noticeSha256: digest(notice), status: 'queued-unverified' }; } +/** Call only after reserving in the trusted graph and acquiring lifecycle exclusion. */ +export async function queueReservedFinalNotice({ reservation, target, label, prefix, managedInboxRoot }, runNative = exec) { + if (!reservation || reservation.status !== 'requested' || typeof reservation.session !== 'string' || typeof reservation.id !== 'string' || !target || target.kind !== 'codex' || reservation.successor !== `codex:${target.id}` || reservation.noticeSha256 !== digest(formatFinalNotice({ target, label, prefix }))) throw new Error('final notice reservation does not match request'); + return queueLocalFinalNotice({ session: reservation.session, nonce: reservation.id, target, label, prefix, managedInboxRoot }, runNative); +} + /** Obtain local native transcript evidence independently from the queue receipt. */ export async function observeLocalFinalNotice({ session, nonce, target, label, prefix, transcriptRoot }) { if (typeof session !== 'string') throw new Error('invalid local notice session'); diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 296d3e3d..b6c45f39 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -37,9 +37,10 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice } from "./channel-state.mjs"; import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; +import { formatFinalNotice } from "./handover-notice.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -130,7 +131,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -221,6 +222,20 @@ try { next = reserveWake(current, requiredSingleLine(values.id, "--id"), session, Number(values.generation), queueId); } else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; + else if (subcommand === "reserve-notice") { + const target = requiredSingleLine(values.to, "--to"); + const match = /^codex:([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(target); + if (!match) throw new Error("successor native verification unavailable"); + const content = JSON.parse(requiredSingleLine(channelInput, "--input")); + if (!content || typeof content !== "object" || Array.isArray(content) || Object.keys(content).sort().join(",") !== "label,prefix") throw new Error("invalid notice content"); + const notice = formatFinalNotice({ target: { kind: "codex", id: match[1] }, label: content.label, prefix: content.prefix }); + const matches = graph.nodes.filter(node => plexus.sessionIdOf(node) === target), node = matches[0], proof = node?.sessionLink; + const started = Date.parse(current.handoverStartedAt), checked = Date.parse(proof?.checkedAt); + if (matches.length !== 1 || node.status === "closed" || node.surface?.archived === true || proof?.status !== "ok" || proof.resolvedSession !== target || proof.source !== "codex-threads" || proof.link !== target || proof.lastKnown === true || !Number.isFinite(started) || !Number.isFinite(checked) || checked < started || checked > Date.now()) throw new Error("successor requires fresh verified link"); + const writer = probeWriter({ harness: "codex", nativeId: match[1] }); + if (writer?.agent !== "codex" || writer.sessionId !== match[1] || !Array.isArray(writer.writers) || writer.writers.length !== 1 || !Number.isSafeInteger(writer.writers[0]?.pid) || writer.writers[0].pid <= 0 || writer.writers[0].kind !== "codex") throw new Error("successor requires one verified writer"); + next = reserveFinalNotice(current, `handover-${randomUUID()}`, target, createHash("sha256").update(notice).digest("hex")); + } else if (subcommand === "finish-handover") { const target = requiredSingleLine(values.to, "--to"); if (current.phase === "active" && current.session === target && current.handoverReceipt?.successor === target) return { graph, result: { channel: current, duplicate: true } }; diff --git a/packages/tmux-bridge/test/channel-state.test.mjs b/packages/tmux-bridge/test/channel-state.test.mjs index f4fd4936..6be5649d 100644 --- a/packages/tmux-bridge/test/channel-state.test.mjs +++ b/packages/tmux-bridge/test/channel-state.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, finishHandover, reserveWake, reserveStatePreparation, completeStatePreparation } from '../bin/channel-state.mjs'; +import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, finishHandover, reserveWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeQueued } from '../bin/channel-state.mjs'; test('a wake reservation prevents handover and requires exact accepted queue identity', () => { const session = 'codex:22222222-2222-4222-8222-222222222222'; @@ -67,3 +67,17 @@ test('handover queues work and never reroutes an uncertain delivery', () => { assert.deepEqual(enqueue(channel, 'message-2', 'queued'), channel); assert.throws(() => enqueue(channel, 'message-2', 'different'), /conflict/); }); + +test('final notice reservation binds the queue receipt and blocks cutover', () => { + let state = beginHandover(createChannel('example', 'codex:old')); + assert.throws(() => reserveFinalNotice(state, 'handover-1', 'codex:new', 'a'.repeat(64)), /unavailable/); + state = reserveStatePreparation(state, 'state-1'); + state = completeStatePreparation(state, { schema: 'agent-mesh.handover-state.v1', session: 'codex:old', nonce: 'state-1', filename: 'state.yaml', sha256: 'b'.repeat(64), bytes: 2 }); + state = reserveFinalNotice(state, 'handover-1', 'codex:new', 'a'.repeat(64)); + assert.throws(() => reserveFinalNotice(state, 'handover-2', 'codex:new', 'a'.repeat(64)), /unavailable/); + const receipt = { schema: 'agent-mesh.notice-queue.v1', status: 'queued-unverified', session: 'codex:old', nonce: 'handover-1', noticeSha256: 'a'.repeat(64) }; + assert.throws(() => recordNoticeQueued(state, { ...receipt, nonce: 'other' }), /reservation/); + state = recordNoticeQueued(state, receipt); + assert.equal(state.finalNotice.status, 'queued-unverified'); + assert.throws(() => finishHandover(state, 'codex:new', true), /final notice unresolved/); +}); diff --git a/packages/tmux-bridge/test/handover-notice-transport.test.mjs b/packages/tmux-bridge/test/handover-notice-transport.test.mjs index a76acfe0..390150af 100644 --- a/packages/tmux-bridge/test/handover-notice-transport.test.mjs +++ b/packages/tmux-bridge/test/handover-notice-transport.test.mjs @@ -3,7 +3,7 @@ import test from 'node:test'; import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; -import { queueLocalFinalNotice, observeLocalFinalNotice } from '../bin/handover-notice-transport.mjs'; +import { queueLocalFinalNotice, queueReservedFinalNotice, observeLocalFinalNotice } from '../bin/handover-notice-transport.mjs'; import { formatFinalNotice } from '../bin/handover-notice.mjs'; const id = '22222222-2222-4222-8222-222222222222'; @@ -54,3 +54,15 @@ test('queue is followed by separately observed Claude transcript evidence', asyn assert.equal(proof.messageSha256, queue.noticeSha256); assert.equal(proof.nonce, queue.nonce); }); + +test('reserved delivery binds session, successor and exact content before native call', async () => { + const { createHash } = await import('node:crypto'); + const reservation = { status: 'requested', session: options.session, id: nonce, successor: `codex:${id}`, noticeSha256: createHash('sha256').update(notice).digest('hex') }; + const args = { reservation, target: options.target, label: options.label, prefix: options.prefix, managedInboxRoot: options.managedInboxRoot }; + let calls = 0; + const run = async () => { calls++; return { stdout: JSON.stringify(response) }; }; + assert.equal((await queueReservedFinalNotice(args, run)).status, 'queued-unverified'); + await assert.rejects(queueReservedFinalNotice({ ...args, label: 'different' }, run), /does not match/); + await assert.rejects(queueReservedFinalNotice({ ...args, reservation: { ...reservation, successor: 'codex:other' } }, run), /does not match/); + assert.equal(calls, 1); +}); diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index 47fee4ef..018ee508 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -120,3 +120,32 @@ test('delivery reservation and matching receipt survive graph replay', async (t) await call('channel', 'acknowledge', '--name', 'example', '--id', 'one', '--input', JSON.stringify({ status: 'accepted', messageId: 'one', session, generation: 1 })); assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'accepted'); }); + +test('final notice reservation persists and refuses a duplicate before any send', async t => { + const state = await mkdtemp(join(tmpdir(), 'notice-reserve-')); + t.after(() => rm(state, { recursive: true, force: true })); + const writer = join(state, 'writer.mjs'), oldId = '22222222-2222-4222-8222-222222222222', nextId = '33333333-3333-4333-8333-333333333333'; + await writeFile(writer, `console.log(JSON.stringify({agent:'codex',sessionId:'${nextId}',writers:[{pid:123,kind:'codex'}]}))`); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args], { env: { ...process.env, MESH_PLEXUS_WRITER_STATUS: writer } })).stdout); + for (const id of [oldId, nextId]) await call('add', '--agent', 'codex', '--tmux-target', `test-${id}`, '--cwd', '/synthetic', '--runtime-uuid', id, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${oldId}`); + await call('channel', 'begin-handover', '--name', 'example'); + const args = ['channel', 'reserve-notice', '--name', 'example', '--to', `codex:${nextId}`, '--input', JSON.stringify({ prefix: 'Sleeping.', label: 'Continue' })]; + await assert.rejects(call(...args), /fresh verified link/); + let graph = await call('show', '--json'); + const node = graph.nodes.find(row => row.runtimeUuid === nextId), checkedAt = new Date().toISOString(); + node.sessionLink = { status: 'ok', resolvedSession: `codex:${nextId}`, link: `codex:${nextId}`, source: 'codex-threads', checkedAt, lastKnown: false }; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-link', type: 'node.upserted', at: checkedAt, node, seq: graph.lastSeq + 1, host: 'local' })}\n`); + await assert.rejects(call(...args), /reservation unavailable/); + graph = await call('show', '--json'); + const channel = graph.channels.find(row => row.id === 'example'); + channel.statePreparation = { status: 'verified', session: `codex:${oldId}`, generation: channel.generation, id: 'state-1', filename: 'state.yaml', sha256: 'b'.repeat(64), bytes: 2 }; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-state', type: 'channel.updated', at: new Date().toISOString(), channel, seq: graph.lastSeq + 1, host: 'local' })}\n`); + const first = (await call(...args)).channel.finalNotice; + assert.equal(first.status, 'requested'); + assert.equal(first.successor, `codex:${nextId}`); + await rm(join(state, 'checkpoint.json'), { force: true }); + assert.deepEqual((await call('channel', 'get', '--name', 'example')).channel.finalNotice, first); + await assert.rejects(call(...args), /reservation unavailable/); +}); diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 05661ab6..5bdc7be8 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -91,8 +91,26 @@ export function completeStatePreparation(state, proof) { return next; } +// The durable reservation survives crashes; only authenticated evidence can +// settle it. It does not itself verify the successor or send a notice. +export function reserveFinalNotice(state, id, successor, noticeSha256) { + if (state.phase !== 'handover' || state.finalNotice || state.statePreparation?.status !== 'verified' || state.statePreparation.session !== state.session || state.statePreparation.generation !== state.generation || !identifier(id) || !identifier(successor) || successor === state.session || !/^[a-f0-9]{64}$/.test(noticeSha256 || '') || state.queue.some(item => item.state === 'inflight')) throw new Error('final notice reservation unavailable'); + const next = copy(state); + next.finalNotice = { id, session: state.session, generation: state.generation, successor, noticeSha256, status: 'requested' }; + return next; +} + +export function recordNoticeQueued(state, receipt) { + const pending = state.finalNotice; + if (state.phase !== 'handover' || !pending || pending.status !== 'requested' || pending.session !== state.session || pending.generation !== state.generation || !receipt || receipt.schema !== 'agent-mesh.notice-queue.v1' || receipt.status !== 'queued-unverified' || receipt.session !== pending.session || receipt.nonce !== pending.id || receipt.noticeSha256 !== pending.noticeSha256) throw new Error('notice queue receipt does not match reservation'); + const next = copy(state); + next.finalNotice.status = 'queued-unverified'; + return next; +} + export function finishHandover(state, session, verified) { if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); + if (state.finalNotice && state.finalNotice.status !== 'verified') throw new Error('final notice unresolved'); if (state.statePreparation && state.statePreparation.status !== 'verified') throw new Error('state preparation unresolved'); if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); const next = copy(state); diff --git a/skills/agent-tmux/bin/handover-notice-transport.mjs b/skills/agent-tmux/bin/handover-notice-transport.mjs index 1107f141..455f37df 100644 --- a/skills/agent-tmux/bin/handover-notice-transport.mjs +++ b/skills/agent-tmux/bin/handover-notice-transport.mjs @@ -37,6 +37,12 @@ export async function queueLocalFinalNotice({ session, nonce, target, label, pre return { schema: 'agent-mesh.notice-queue.v1', session, nonce, noticeSha256: digest(notice), status: 'queued-unverified' }; } +/** Call only after reserving in the trusted graph and acquiring lifecycle exclusion. */ +export async function queueReservedFinalNotice({ reservation, target, label, prefix, managedInboxRoot }, runNative = exec) { + if (!reservation || reservation.status !== 'requested' || typeof reservation.session !== 'string' || typeof reservation.id !== 'string' || !target || target.kind !== 'codex' || reservation.successor !== `codex:${target.id}` || reservation.noticeSha256 !== digest(formatFinalNotice({ target, label, prefix }))) throw new Error('final notice reservation does not match request'); + return queueLocalFinalNotice({ session: reservation.session, nonce: reservation.id, target, label, prefix, managedInboxRoot }, runNative); +} + /** Obtain local native transcript evidence independently from the queue receipt. */ export async function observeLocalFinalNotice({ session, nonce, target, label, prefix, transcriptRoot }) { if (typeof session !== 'string') throw new Error('invalid local notice session'); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 296d3e3d..b6c45f39 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -37,9 +37,10 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice } from "./channel-state.mjs"; import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; +import { formatFinalNotice } from "./handover-notice.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -130,7 +131,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -221,6 +222,20 @@ try { next = reserveWake(current, requiredSingleLine(values.id, "--id"), session, Number(values.generation), queueId); } else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; + else if (subcommand === "reserve-notice") { + const target = requiredSingleLine(values.to, "--to"); + const match = /^codex:([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(target); + if (!match) throw new Error("successor native verification unavailable"); + const content = JSON.parse(requiredSingleLine(channelInput, "--input")); + if (!content || typeof content !== "object" || Array.isArray(content) || Object.keys(content).sort().join(",") !== "label,prefix") throw new Error("invalid notice content"); + const notice = formatFinalNotice({ target: { kind: "codex", id: match[1] }, label: content.label, prefix: content.prefix }); + const matches = graph.nodes.filter(node => plexus.sessionIdOf(node) === target), node = matches[0], proof = node?.sessionLink; + const started = Date.parse(current.handoverStartedAt), checked = Date.parse(proof?.checkedAt); + if (matches.length !== 1 || node.status === "closed" || node.surface?.archived === true || proof?.status !== "ok" || proof.resolvedSession !== target || proof.source !== "codex-threads" || proof.link !== target || proof.lastKnown === true || !Number.isFinite(started) || !Number.isFinite(checked) || checked < started || checked > Date.now()) throw new Error("successor requires fresh verified link"); + const writer = probeWriter({ harness: "codex", nativeId: match[1] }); + if (writer?.agent !== "codex" || writer.sessionId !== match[1] || !Array.isArray(writer.writers) || writer.writers.length !== 1 || !Number.isSafeInteger(writer.writers[0]?.pid) || writer.writers[0].pid <= 0 || writer.writers[0].kind !== "codex") throw new Error("successor requires one verified writer"); + next = reserveFinalNotice(current, `handover-${randomUUID()}`, target, createHash("sha256").update(notice).digest("hex")); + } else if (subcommand === "finish-handover") { const target = requiredSingleLine(values.to, "--to"); if (current.phase === "active" && current.session === target && current.handoverReceipt?.successor === target) return { graph, result: { channel: current, duplicate: true } }; From 71a2036217f7ad15fb26a481eeafb75a72c16684 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:54:03 +0000 Subject: [PATCH 070/113] Record local final notice observation in graph --- docs/design/plexus-channels.md | 6 +++-- packages/tmux-bridge/bin/channel-state.mjs | 10 ++++++++ packages/tmux-bridge/bin/mesh-graph.mjs | 25 +++++++++++++++++-- .../test/plexus-channel-store.test.mjs | 21 ++++++++++++++-- skills/agent-tmux/bin/channel-state.mjs | 10 ++++++++ skills/agent-tmux/bin/mesh-graph.mjs | 25 +++++++++++++++++-- 6 files changed, 89 insertions(+), 8 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 4c18e819..34268d62 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -119,8 +119,10 @@ blindly. These prerequisites are not yet connected, and this adapter is not wired to cutover or cloud delivery. A graph `channel reserve-notice` transition requires verified state and a freshly verified Codex successor, binds the notice digest and nonce, and survives replay. The adapter can bind an enqueue -to that reservation, but does not acquire lifecycle exclusion or settle the -receipt in the graph. The actual cutover remains disabled. +to that reservation. `channel observe-notice` records a matching local +transcript snapshot against the reservation, but does not acquire lifecycle +exclusion or establish that a later turn cannot occur. The actual cutover +remains disabled. # Role-scoped restart preparation The `agent-mesh.restart.v1` YAML handover block requires `role_profile` when diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 5bdc7be8..343d4254 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -108,6 +108,16 @@ export function recordNoticeQueued(state, receipt) { return next; } +// A transcript snapshot is evidence of a completed message at read time, +// not exclusive finality and not authorization to finish a handover. +export function recordNoticeObservation(state, proof) { + const pending = state.finalNotice; + if (state.phase !== 'handover' || !pending || !['requested', 'queued-unverified'].includes(pending.status) || pending.session !== state.session || pending.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.final-notice-observation.v1' || proof.session !== pending.session || proof.nonce !== pending.id || proof.messageSha256 !== pending.noticeSha256 || !/^[a-f0-9]{64}$/.test(proof.transcriptSha256 || '') || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('notice observation does not match reservation'); + const next = copy(state); + next.finalNotice = { ...pending, status: 'observed-snapshot', transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.bytes }; + return next; +} + export function finishHandover(state, session, verified) { if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); if (state.finalNotice && state.finalNotice.status !== 'verified') throw new Error('final notice unresolved'); diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index b6c45f39..27fa1a9d 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -37,10 +37,11 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; import { formatFinalNotice } from "./handover-notice.mjs"; +import { observeLocalFinalNotice } from "./handover-notice-transport.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -131,7 +132,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -153,6 +154,26 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "observe-notice") { + const content = JSON.parse(requiredSingleLine(channelInput, "--input")); + if (!content || typeof content !== "object" || Array.isArray(content) || Object.keys(content).sort().join(",") !== "label,prefix") throw new Error("invalid notice content"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name), pending = channel?.finalNotice; + const target = /^codex:([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(pending?.successor || ""); + const agent = pending?.session?.split(":")[0]; + if (!pending || !["requested", "queued-unverified"].includes(pending.status) || !target || !["codex", "claude"].includes(agent)) throw new Error("local notice reservation unavailable"); + const root = agent === "codex" ? process.env.CODEX_SESSION_ROOT || join(process.env.CODEX_HOME || join(homedir(), ".codex"), "sessions") : process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeLocalFinalNotice({ session: pending.session, nonce: pending.id, target: { kind: "codex", id: target[1] }, label: content.label, prefix: content.prefix, transcriptRoot: root }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + const next = recordNoticeObservation(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next } }; + }); + printResult(result, { json: true }); + break; + } if (subcommand === "settle-wake") { const session = requiredSingleLine(values.session, "--session"); const evidence = requiredSingleLine(channelInput, "--input"); diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index 018ee508..f4d9df20 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -124,9 +124,10 @@ test('delivery reservation and matching receipt survive graph replay', async (t) test('final notice reservation persists and refuses a duplicate before any send', async t => { const state = await mkdtemp(join(tmpdir(), 'notice-reserve-')); t.after(() => rm(state, { recursive: true, force: true })); - const writer = join(state, 'writer.mjs'), oldId = '22222222-2222-4222-8222-222222222222', nextId = '33333333-3333-4333-8333-333333333333'; + const writer = join(state, 'writer.mjs'), sessions = join(state, 'sessions'), oldId = '22222222-2222-4222-8222-222222222222', nextId = '33333333-3333-4333-8333-333333333333'; + await mkdir(sessions, { mode: 0o700 }); await writeFile(writer, `console.log(JSON.stringify({agent:'codex',sessionId:'${nextId}',writers:[{pid:123,kind:'codex'}]}))`); - const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args], { env: { ...process.env, MESH_PLEXUS_WRITER_STATUS: writer } })).stdout); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args], { env: { ...process.env, MESH_PLEXUS_WRITER_STATUS: writer, CODEX_SESSION_ROOT: sessions } })).stdout); for (const id of [oldId, nextId]) await call('add', '--agent', 'codex', '--tmux-target', `test-${id}`, '--cwd', '/synthetic', '--runtime-uuid', id, '--json'); await call('migrate', '--apply', '--json'); await call('channel', 'create', '--name', 'example', '--session', `codex:${oldId}`); @@ -148,4 +149,20 @@ test('final notice reservation persists and refuses a duplicate before any send' await rm(join(state, 'checkpoint.json'), { force: true }); assert.deepEqual((await call('channel', 'get', '--name', 'example')).channel.finalNotice, first); await assert.rejects(call(...args), /reservation unavailable/); + const notice = `Sleeping. [Continue](codex://threads/${nextId})`; + const records = [ + { type: 'session_meta', payload: { id: oldId } }, + { type: 'event_msg', payload: { type: 'user_message', message: `[HANDOVER:${first.id}] synthetic request` } }, + { type: 'response_item', payload: { type: 'message', role: 'assistant', phase: 'final_answer', content: [{ type: 'output_text', text: notice }] } }, + { type: 'event_msg', payload: { type: 'task_complete', last_agent_message: notice } } + ]; + await writeFile(join(sessions, `rollout-${oldId}.jsonl`), records.map(row => JSON.stringify(row)).join('\n') + '\n', { mode: 0o600 }); + const observe = ['channel', 'observe-notice', '--name', 'example', '--input', JSON.stringify({ prefix: 'Sleeping.', label: 'Continue' })]; + await assert.rejects(call('channel', 'observe-notice', '--name', 'example', '--input', JSON.stringify({ prefix: 'wrong', label: 'Continue' })), /not proven/); + const observed = (await call(...observe)).channel.finalNotice; + assert.equal(observed.status, 'observed-snapshot'); + assert.match(observed.transcriptSha256, /^[a-f0-9]{64}$/); + await rm(join(state, 'checkpoint.json'), { force: true }); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.finalNotice.status, 'observed-snapshot'); + await assert.rejects(call('channel', 'finish-handover', '--name', 'example', '--to', `codex:${nextId}`), /old-session state verification unavailable/); }); diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 5bdc7be8..343d4254 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -108,6 +108,16 @@ export function recordNoticeQueued(state, receipt) { return next; } +// A transcript snapshot is evidence of a completed message at read time, +// not exclusive finality and not authorization to finish a handover. +export function recordNoticeObservation(state, proof) { + const pending = state.finalNotice; + if (state.phase !== 'handover' || !pending || !['requested', 'queued-unverified'].includes(pending.status) || pending.session !== state.session || pending.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.final-notice-observation.v1' || proof.session !== pending.session || proof.nonce !== pending.id || proof.messageSha256 !== pending.noticeSha256 || !/^[a-f0-9]{64}$/.test(proof.transcriptSha256 || '') || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('notice observation does not match reservation'); + const next = copy(state); + next.finalNotice = { ...pending, status: 'observed-snapshot', transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.bytes }; + return next; +} + export function finishHandover(state, session, verified) { if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); if (state.finalNotice && state.finalNotice.status !== 'verified') throw new Error('final notice unresolved'); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index b6c45f39..27fa1a9d 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -37,10 +37,11 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; import { formatFinalNotice } from "./handover-notice.mjs"; +import { observeLocalFinalNotice } from "./handover-notice-transport.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -131,7 +132,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -153,6 +154,26 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "observe-notice") { + const content = JSON.parse(requiredSingleLine(channelInput, "--input")); + if (!content || typeof content !== "object" || Array.isArray(content) || Object.keys(content).sort().join(",") !== "label,prefix") throw new Error("invalid notice content"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name), pending = channel?.finalNotice; + const target = /^codex:([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(pending?.successor || ""); + const agent = pending?.session?.split(":")[0]; + if (!pending || !["requested", "queued-unverified"].includes(pending.status) || !target || !["codex", "claude"].includes(agent)) throw new Error("local notice reservation unavailable"); + const root = agent === "codex" ? process.env.CODEX_SESSION_ROOT || join(process.env.CODEX_HOME || join(homedir(), ".codex"), "sessions") : process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeLocalFinalNotice({ session: pending.session, nonce: pending.id, target: { kind: "codex", id: target[1] }, label: content.label, prefix: content.prefix, transcriptRoot: root }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + const next = recordNoticeObservation(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next } }; + }); + printResult(result, { json: true }); + break; + } if (subcommand === "settle-wake") { const session = requiredSingleLine(values.session, "--session"); const evidence = requiredSingleLine(channelInput, "--input"); From 3051907aaa36154e33b0e69ea6046c2b974695ff Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 20:58:08 +0000 Subject: [PATCH 071/113] Prepare bounded Codex MCP connection sampling --- docs/design/plexus-channels.md | 10 +++++ .../tmux-bridge/bin/codex-mcp-observation.mjs | 40 ++++++++++++++++++ .../test/codex-mcp-observation.test.mjs | 41 +++++++++++++++++++ .../agent-tmux/bin/codex-mcp-observation.mjs | 40 ++++++++++++++++++ 4 files changed, 131 insertions(+) create mode 100644 packages/tmux-bridge/bin/codex-mcp-observation.mjs create mode 100644 packages/tmux-bridge/test/codex-mcp-observation.test.mjs create mode 100644 skills/agent-tmux/bin/codex-mcp-observation.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 34268d62..e0466f5f 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -157,3 +157,13 @@ for the child close before reporting any result; failure to observe closure stop the plan. Missing or invalid private probe configuration stops planning rather than being classified as an unreachable MCP. Other probe implementations must honor cancellation themselves; an unconfirmed cancellation stops the plan. + +`codex-mcp-observation.mjs` prepares an opt-in, bounded app-server connection +sample for a requested thread. It discards server names and endpoint data, fails +on ambiguous pagination, and reports an observed connection count separately +from the unknown number of processes started and unknown startup tokens. Its +profile and generation bindings are caller claims, the server does not echo the +thread identifier in each page, and pagination is not atomic. Provider behavior, +including whether listing triggers discovery, is not qualified; do not call it +on a live thread or treat it as launch evidence until those conditions are +verified. Tests use only a synthetic app-server callback. diff --git a/packages/tmux-bridge/bin/codex-mcp-observation.mjs b/packages/tmux-bridge/bin/codex-mcp-observation.mjs new file mode 100644 index 00000000..afd23225 --- /dev/null +++ b/packages/tmux-bridge/bin/codex-mcp-observation.mjs @@ -0,0 +1,40 @@ +/** Bounded, opt-in app-server sample. It does not start or resume a thread. */ +import { withCodexAppServer } from './codex-app-server.mjs'; + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const statuses = new Set(['notStarted', 'starting', 'connected', 'authenticationRequired', 'failed', 'cancelled', 'disabled']); +const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); + +/** + * Do not treat this as launch or process evidence. Pagination is not an atomic + * snapshot, and the provider does not echo the requested thread in a response. + * Calling the provider may initiate discovery; qualify it before live use. + */ +export async function sampleCodexMcpConnections({ threadId, generation, profileSha256 }, connect = withCodexAppServer) { + if (typeof threadId !== 'string' || !uuid.test(threadId) || !Number.isSafeInteger(generation) || generation < 1 || typeof profileSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(profileSha256) || typeof connect !== 'function') throw new Error('invalid MCP sample request'); + return connect({ clientName: 'agent-mesh-mcp-sample', timeout: 30000, timeoutMessage: 'MCP sample timed out' }, async request => { + const startedAt = new Date().toISOString(), cursors = new Set(), names = new Set(); + let cursor = null, pages = 0, connected = 0, unavailable = 0; + for (;;) { + if (++pages > 32) throw new Error('MCP pagination limit exceeded'); + const result = await request('mcpServerStatus/list', { threadId, cursor, limit: 100, detail: 'toolsAndAuthOnly' }); + if (!result || !Array.isArray(result.data) || !Object.hasOwn(result, 'nextCursor') || !(result.nextCursor === null || (typeof result.nextCursor === 'string' && result.nextCursor.length > 0 && result.nextCursor.length <= 4096))) throw new Error('invalid MCP page'); + for (const item of result.data) { + if (!item || !validName(item.name) || names.has(item.name)) throw new Error('invalid or duplicate MCP identity'); + names.add(item.name); + if (names.size > 4096) throw new Error('MCP sample limit exceeded'); + const status = item.runtimeStatus ?? null; + if (status !== null && !statuses.has(status)) throw new Error('invalid MCP runtime status'); + if (status === 'connected') connected++; + if (status === null) unavailable++; + } + if (result.nextCursor === null) break; + if (cursors.has(result.nextCursor)) throw new Error('MCP cursor loop'); + cursors.add(result.nextCursor); cursor = result.nextCursor; + } + return { schema: 'agent-mesh.codex-mcp-sample.v1', requestedThreadId: threadId, claimedGeneration: generation, + claimedProfileSha256: profileSha256, profileBinding: 'unverified', startedAt, endedAt: new Date().toISOString(), pages, + serversReturned: names.size, connectedObserved: connected, unavailableStatus: unavailable, + completeness: 'unverified-non-atomic', mcpStarted: null, startupTokens: null }; + }); +} diff --git a/packages/tmux-bridge/test/codex-mcp-observation.test.mjs b/packages/tmux-bridge/test/codex-mcp-observation.test.mjs new file mode 100644 index 00000000..33cbf4ca --- /dev/null +++ b/packages/tmux-bridge/test/codex-mcp-observation.test.mjs @@ -0,0 +1,41 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { sampleCodexMcpConnections } from '../bin/codex-mcp-observation.mjs'; + +const input = { threadId: '22222222-2222-4222-8222-222222222222', generation: 1, profileSha256: 'a'.repeat(64) }; +const connect = fn => async (_options, work) => work(fn); + +test('pagination returns a partial connection sample with no names or claimed startup count', async () => { + const requests = []; + const result = await sampleCodexMcpConnections(input, connect(async (method, params) => { + requests.push({ method, params }); + return params.cursor === null ? { data: [{ name: 'first', runtimeStatus: 'connected', httpOrigin: 'private-fixture' }], nextCursor: 'page-2' } : { data: [{ name: 'second', runtimeStatus: null }], nextCursor: null }; + })); + assert.equal(requests.length, 2); + assert.ok(requests.every(item => item.method === 'mcpServerStatus/list' && item.params.threadId === input.threadId)); + assert.equal(result.connectedObserved, 1); + assert.equal(result.unavailableStatus, 1); + assert.equal(result.mcpStarted, null); + assert.equal(result.startupTokens, null); + assert.equal(result.profileBinding, 'unverified'); + assert.equal(result.completeness, 'unverified-non-atomic'); + assert.ok(!JSON.stringify(result).includes('first')); + assert.ok(!JSON.stringify(result).includes('private-fixture')); +}); + +test('cursor loops, duplicate identities, omitted pagination and invalid status fail closed', async () => { + for (const page of [ + { data: [], nextCursor: 'again' }, + { data: [{ name: 'same', runtimeStatus: 'connected' }, { name: 'same', runtimeStatus: 'failed' }], nextCursor: null }, + { data: [] }, + { data: [{ name: 'one', runtimeStatus: 'invented' }], nextCursor: null } + ]) await assert.rejects(sampleCodexMcpConnections(input, connect(async () => page))); + await assert.rejects(sampleCodexMcpConnections({ ...input, threadId: 'invalid' }, connect(async () => { throw new Error('must not call'); })), /invalid/); +}); + +test('an empty response does not claim a zero startup count', async () => { + const result = await sampleCodexMcpConnections(input, connect(async () => ({ data: [], nextCursor: null }))); + assert.equal(result.connectedObserved, 0); + assert.equal(result.mcpStarted, null); + assert.equal(result.completeness, 'unverified-non-atomic'); +}); diff --git a/skills/agent-tmux/bin/codex-mcp-observation.mjs b/skills/agent-tmux/bin/codex-mcp-observation.mjs new file mode 100644 index 00000000..afd23225 --- /dev/null +++ b/skills/agent-tmux/bin/codex-mcp-observation.mjs @@ -0,0 +1,40 @@ +/** Bounded, opt-in app-server sample. It does not start or resume a thread. */ +import { withCodexAppServer } from './codex-app-server.mjs'; + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const statuses = new Set(['notStarted', 'starting', 'connected', 'authenticationRequired', 'failed', 'cancelled', 'disabled']); +const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); + +/** + * Do not treat this as launch or process evidence. Pagination is not an atomic + * snapshot, and the provider does not echo the requested thread in a response. + * Calling the provider may initiate discovery; qualify it before live use. + */ +export async function sampleCodexMcpConnections({ threadId, generation, profileSha256 }, connect = withCodexAppServer) { + if (typeof threadId !== 'string' || !uuid.test(threadId) || !Number.isSafeInteger(generation) || generation < 1 || typeof profileSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(profileSha256) || typeof connect !== 'function') throw new Error('invalid MCP sample request'); + return connect({ clientName: 'agent-mesh-mcp-sample', timeout: 30000, timeoutMessage: 'MCP sample timed out' }, async request => { + const startedAt = new Date().toISOString(), cursors = new Set(), names = new Set(); + let cursor = null, pages = 0, connected = 0, unavailable = 0; + for (;;) { + if (++pages > 32) throw new Error('MCP pagination limit exceeded'); + const result = await request('mcpServerStatus/list', { threadId, cursor, limit: 100, detail: 'toolsAndAuthOnly' }); + if (!result || !Array.isArray(result.data) || !Object.hasOwn(result, 'nextCursor') || !(result.nextCursor === null || (typeof result.nextCursor === 'string' && result.nextCursor.length > 0 && result.nextCursor.length <= 4096))) throw new Error('invalid MCP page'); + for (const item of result.data) { + if (!item || !validName(item.name) || names.has(item.name)) throw new Error('invalid or duplicate MCP identity'); + names.add(item.name); + if (names.size > 4096) throw new Error('MCP sample limit exceeded'); + const status = item.runtimeStatus ?? null; + if (status !== null && !statuses.has(status)) throw new Error('invalid MCP runtime status'); + if (status === 'connected') connected++; + if (status === null) unavailable++; + } + if (result.nextCursor === null) break; + if (cursors.has(result.nextCursor)) throw new Error('MCP cursor loop'); + cursors.add(result.nextCursor); cursor = result.nextCursor; + } + return { schema: 'agent-mesh.codex-mcp-sample.v1', requestedThreadId: threadId, claimedGeneration: generation, + claimedProfileSha256: profileSha256, profileBinding: 'unverified', startedAt, endedAt: new Date().toISOString(), pages, + serversReturned: names.size, connectedObserved: connected, unavailableStatus: unavailable, + completeness: 'unverified-non-atomic', mcpStarted: null, startupTokens: null }; + }); +} From 7f7059f14f8176600827b783982026266b98797d Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:03:26 +0000 Subject: [PATCH 072/113] Require explicit isolated MCP sample connector --- docs/design/plexus-channels.md | 10 ++++++---- packages/tmux-bridge/bin/codex-mcp-observation.mjs | 5 ++--- .../tmux-bridge/test/codex-mcp-observation.test.mjs | 4 ++++ skills/agent-tmux/bin/codex-mcp-observation.mjs | 5 ++--- 4 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index e0466f5f..677f5cc2 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -163,7 +163,9 @@ sample for a requested thread. It discards server names and endpoint data, fails on ambiguous pagination, and reports an observed connection count separately from the unknown number of processes started and unknown startup tokens. Its profile and generation bindings are caller claims, the server does not echo the -thread identifier in each page, and pagination is not atomic. Provider behavior, -including whether listing triggers discovery, is not qualified; do not call it -on a live thread or treat it as launch evidence until those conditions are -verified. Tests use only a synthetic app-server callback. +thread identifier in each page, and pagination is not atomic. An isolated Codex CLI 0.169.0 experiment showed that listing after the +fixture MCP process was stopped restarted it; a control without listing did +not restart it during the observation window. This is an active discovery +operation, not a read-only health check. There is no default live connector; do +not call it on a live thread or treat it as launch evidence. Unit tests use +only a synthetic app-server callback. diff --git a/packages/tmux-bridge/bin/codex-mcp-observation.mjs b/packages/tmux-bridge/bin/codex-mcp-observation.mjs index afd23225..108ad5d9 100644 --- a/packages/tmux-bridge/bin/codex-mcp-observation.mjs +++ b/packages/tmux-bridge/bin/codex-mcp-observation.mjs @@ -1,5 +1,4 @@ /** Bounded, opt-in app-server sample. It does not start or resume a thread. */ -import { withCodexAppServer } from './codex-app-server.mjs'; const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; const statuses = new Set(['notStarted', 'starting', 'connected', 'authenticationRequired', 'failed', 'cancelled', 'disabled']); @@ -8,9 +7,9 @@ const validName = name => typeof name === 'string' && name.length > 0 && name.le /** * Do not treat this as launch or process evidence. Pagination is not an atomic * snapshot, and the provider does not echo the requested thread in a response. - * Calling the provider may initiate discovery; qualify it before live use. + * A real provider call can restart an MCP; connect only to an isolated fixture. */ -export async function sampleCodexMcpConnections({ threadId, generation, profileSha256 }, connect = withCodexAppServer) { +export async function sampleCodexMcpConnections({ threadId, generation, profileSha256 }, connect) { if (typeof threadId !== 'string' || !uuid.test(threadId) || !Number.isSafeInteger(generation) || generation < 1 || typeof profileSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(profileSha256) || typeof connect !== 'function') throw new Error('invalid MCP sample request'); return connect({ clientName: 'agent-mesh-mcp-sample', timeout: 30000, timeoutMessage: 'MCP sample timed out' }, async request => { const startedAt = new Date().toISOString(), cursors = new Set(), names = new Set(); diff --git a/packages/tmux-bridge/test/codex-mcp-observation.test.mjs b/packages/tmux-bridge/test/codex-mcp-observation.test.mjs index 33cbf4ca..52bfcd60 100644 --- a/packages/tmux-bridge/test/codex-mcp-observation.test.mjs +++ b/packages/tmux-bridge/test/codex-mcp-observation.test.mjs @@ -39,3 +39,7 @@ test('an empty response does not claim a zero startup count', async () => { assert.equal(result.mcpStarted, null); assert.equal(result.completeness, 'unverified-non-atomic'); }); + +test('there is no default live app-server connection', async () => { + await assert.rejects(sampleCodexMcpConnections(input), /invalid MCP sample request/); +}); diff --git a/skills/agent-tmux/bin/codex-mcp-observation.mjs b/skills/agent-tmux/bin/codex-mcp-observation.mjs index afd23225..108ad5d9 100644 --- a/skills/agent-tmux/bin/codex-mcp-observation.mjs +++ b/skills/agent-tmux/bin/codex-mcp-observation.mjs @@ -1,5 +1,4 @@ /** Bounded, opt-in app-server sample. It does not start or resume a thread. */ -import { withCodexAppServer } from './codex-app-server.mjs'; const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; const statuses = new Set(['notStarted', 'starting', 'connected', 'authenticationRequired', 'failed', 'cancelled', 'disabled']); @@ -8,9 +7,9 @@ const validName = name => typeof name === 'string' && name.length > 0 && name.le /** * Do not treat this as launch or process evidence. Pagination is not an atomic * snapshot, and the provider does not echo the requested thread in a response. - * Calling the provider may initiate discovery; qualify it before live use. + * A real provider call can restart an MCP; connect only to an isolated fixture. */ -export async function sampleCodexMcpConnections({ threadId, generation, profileSha256 }, connect = withCodexAppServer) { +export async function sampleCodexMcpConnections({ threadId, generation, profileSha256 }, connect) { if (typeof threadId !== 'string' || !uuid.test(threadId) || !Number.isSafeInteger(generation) || generation < 1 || typeof profileSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(profileSha256) || typeof connect !== 'function') throw new Error('invalid MCP sample request'); return connect({ clientName: 'agent-mesh-mcp-sample', timeout: 30000, timeoutMessage: 'MCP sample timed out' }, async request => { const startedAt = new Date().toISOString(), cursors = new Set(), names = new Set(); From 39e50da223d4aec633b07d07655d8cc9fbd32206 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:08:53 +0000 Subject: [PATCH 073/113] Observe Codex MCP startup notifications passively --- docs/design/plexus-channels.md | 10 +++ packages/tmux-bridge/bin/codex-app-server.mjs | 15 ++++- .../bin/codex-mcp-startup-notifications.mjs | 33 ++++++++++ .../codex-mcp-startup-notifications.test.mjs | 66 +++++++++++++++++++ skills/agent-tmux/bin/codex-app-server.mjs | 15 ++++- .../bin/codex-mcp-startup-notifications.mjs | 33 ++++++++++ 6 files changed, 166 insertions(+), 6 deletions(-) create mode 100644 packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs create mode 100644 packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs create mode 100644 skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 677f5cc2..71adaee1 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -169,3 +169,13 @@ not restart it during the observation window. This is an active discovery operation, not a read-only health check. There is no default live connector; do not call it on a live thread or treat it as launch evidence. Unit tests use only a synthetic app-server callback. + +`codex-mcp-startup-notifications.mjs` can accumulate the app-server's native +startup notifications on an already established connection without issuing an +inventory request. In an isolated Codex CLI 0.169.0 experiment, a synthetic +thread emitted `starting` and `ready` notifications bound to that thread. The +observer keeps names only in memory, bounds its buffer and reports only counts; +its completeness is unverified and it never claims a process-start or token +count. Integration must attach before the authorized isolated startup, bind the +actual thread response, and independently establish session, profile and event +coverage before using the result as a receipt. It is not enabled for live use. diff --git a/packages/tmux-bridge/bin/codex-app-server.mjs b/packages/tmux-bridge/bin/codex-app-server.mjs index 1027b662..fbc65a14 100644 --- a/packages/tmux-bridge/bin/codex-app-server.mjs +++ b/packages/tmux-bridge/bin/codex-app-server.mjs @@ -64,7 +64,8 @@ function readFrame(buffer) { return { fin: Boolean(buffer[0] & 0x80), opcode: buffer[0] & 0x0f, payload: buffer.subarray(offset, offset + size), end: offset + size }; } -export async function withCodexAppServer({ clientName, timeout, timeoutMessage }, work) { +export async function withCodexAppServer({ clientName, timeout, timeoutMessage, onNotification }, work) { + if (onNotification !== undefined && typeof onNotification !== "function") throw new Error("invalid notification handler"); const path = codexSocket(); const key = randomBytes(16).toString("base64"); const accept = createHash("sha1").update(key + WS_GUID).digest("base64"); @@ -86,7 +87,13 @@ export async function withCodexAppServer({ clientName, timeout, timeoutMessage } let parsed; try { parsed = JSON.parse(text); } catch { rejectAll(new Error("invalid JSON from app-server")); return; } - if (parsed.method) return; + if (parsed.method) { + if (onNotification) { + try { onNotification(parsed); } + catch { rejectAll(new Error("notification handler failed")); socket.destroy(); } + } + return; + } const waiter = pending.get(parsed.id); if (!waiter) return; pending.delete(parsed.id); @@ -163,7 +170,9 @@ export async function withCodexAppServer({ clientName, timeout, timeoutMessage } capabilities: { experimentalApi: true }, }); sendText({ method: "initialized" }); - return await work(request); + const result = await work(request); + if (failure) throw failure; + return result; } finally { clearTimeout(timer); socket.destroy(); diff --git a/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs b/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs new file mode 100644 index 00000000..b6279934 --- /dev/null +++ b/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs @@ -0,0 +1,33 @@ +/** Passive, bounded sampling of already delivered native startup notifications. */ +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const statuses = new Set(['starting', 'ready', 'failed', 'cancelled']); +const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); + +// Attach before starting the thread. The native response can bind the thread +// after notifications arrive. Captured names never leave this in-memory object. +export function createCodexMcpStartupObserver() { + const buffered = []; let threadId = null, invalid = false; + return { + onNotification(event) { + if (event?.method !== 'mcpServer/startupStatus/updated') return; + const p = event.params; + if (!p || typeof p.threadId !== 'string' || !uuid.test(p.threadId) || !validName(p.name) || !statuses.has(p.status)) { invalid = true; return; } + if (threadId && p.threadId !== threadId) return; + if (buffered.length >= 4096) { invalid = true; return; } + buffered.push({ threadId: p.threadId, name: p.name, status: p.status }); + }, + bindThread(id) { + if (threadId !== null || typeof id !== 'string' || !uuid.test(id)) throw new Error('invalid startup thread binding'); + threadId = id; + }, + snapshot() { + if (!threadId) throw new Error('startup thread is not bound'); + const latest = new Map(); + for (const row of buffered) if (row.threadId === threadId) latest.set(row.name, row.status); + const counts = { starting: 0, ready: 0, failed: 0, cancelled: 0 }; + for (const status of latest.values()) counts[status]++; + return { schema: 'agent-mesh.codex-mcp-notification-sample.v1', requestedThreadId: threadId, counts, + completeness: 'unverified', invalidOrOverflow: invalid, mcpStarted: null, startupTokens: null }; + } + }; +} diff --git a/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs b/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs new file mode 100644 index 00000000..27a4873e --- /dev/null +++ b/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs @@ -0,0 +1,66 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { mkdtemp, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { createAppServer } from './fixtures/fake-app-server.mjs'; +import { withCodexAppServer } from '../bin/codex-app-server.mjs'; +import { createCodexMcpStartupObserver } from '../bin/codex-mcp-startup-notifications.mjs'; + +const id = '22222222-2222-4222-8222-222222222222'; +const other = '33333333-3333-4333-8333-333333333333'; +const event = (threadId, name, status) => ({ method: 'mcpServer/startupStatus/updated', params: { threadId, name, status } }); + +test('passive notifications are bound after native thread response without exposing names', () => { + const observer = createCodexMcpStartupObserver(); + observer.onNotification(event(id, 'private-fixture', 'starting')); + observer.onNotification(event(other, 'other-fixture', 'ready')); + observer.bindThread(id); + observer.onNotification(event(id, 'private-fixture', 'ready')); + observer.onNotification(event(other, 'other-fixture', 'failed')); + const receipt = observer.snapshot(); + assert.deepEqual(receipt.counts, { starting: 0, ready: 1, failed: 0, cancelled: 0 }); + assert.equal(receipt.completeness, 'unverified'); + assert.equal(receipt.mcpStarted, null); + assert.equal(receipt.startupTokens, null); + assert.ok(!JSON.stringify(receipt).includes('private-fixture')); + assert.throws(() => observer.bindThread(other), /binding/); +}); + +test('missing identity and notification overflow make the sample explicitly incomplete', () => { + const observer = createCodexMcpStartupObserver(); + observer.onNotification(event(null, 'fixture', 'ready')); + observer.bindThread(id); + for (let i = 0; i < 4097; i++) observer.onNotification(event(id, 'fixture', 'ready')); + const receipt = observer.snapshot(); + assert.equal(receipt.invalidOrOverflow, true); + assert.equal(receipt.mcpStarted, null); +}); + +test('existing app-server client forwards notifications without issuing an inventory request', async t => { + const root = await mkdtemp(join(tmpdir(), 'passive-notify-')); + const socket = join(root, 'test.sock'); + const requests = []; + const server = createAppServer((msg, peer) => { + if (msg.method === 'initialize') peer.send({ id: msg.id, result: {} }); + else if (msg.method === 'thread/start') { + requests.push(msg.method); + peer.send(event(id, 'fixture-server', 'starting')); + peer.send({ id: msg.id, result: { thread: { id } } }); + peer.send(event(id, 'fixture-server', 'ready')); + } else if (msg.id !== undefined) requests.push(msg.method); + }); + await new Promise((resolve, reject) => server.listen(socket, resolve).once('error', reject)); + const old = process.env.CODEX_REMOTE_SOCK; process.env.CODEX_REMOTE_SOCK = socket; + t.after(async () => { if (old === undefined) delete process.env.CODEX_REMOTE_SOCK; else process.env.CODEX_REMOTE_SOCK = old; await new Promise(resolve => server.close(resolve)); await rm(root, { recursive: true, force: true }); }); + const observer = createCodexMcpStartupObserver(); + const receipt = await withCodexAppServer({ clientName: 'test', timeout: 3000, timeoutMessage: 'timeout', onNotification: observer.onNotification }, async request => { + const result = await request('thread/start', { ephemeral: true }); + observer.bindThread(result.thread.id); + await new Promise(resolve => setTimeout(resolve, 30)); + return observer.snapshot(); + }); + assert.deepEqual(requests, ['thread/start']); + assert.equal(receipt.counts.ready, 1); + assert.equal(receipt.mcpStarted, null); +}); diff --git a/skills/agent-tmux/bin/codex-app-server.mjs b/skills/agent-tmux/bin/codex-app-server.mjs index 1027b662..fbc65a14 100644 --- a/skills/agent-tmux/bin/codex-app-server.mjs +++ b/skills/agent-tmux/bin/codex-app-server.mjs @@ -64,7 +64,8 @@ function readFrame(buffer) { return { fin: Boolean(buffer[0] & 0x80), opcode: buffer[0] & 0x0f, payload: buffer.subarray(offset, offset + size), end: offset + size }; } -export async function withCodexAppServer({ clientName, timeout, timeoutMessage }, work) { +export async function withCodexAppServer({ clientName, timeout, timeoutMessage, onNotification }, work) { + if (onNotification !== undefined && typeof onNotification !== "function") throw new Error("invalid notification handler"); const path = codexSocket(); const key = randomBytes(16).toString("base64"); const accept = createHash("sha1").update(key + WS_GUID).digest("base64"); @@ -86,7 +87,13 @@ export async function withCodexAppServer({ clientName, timeout, timeoutMessage } let parsed; try { parsed = JSON.parse(text); } catch { rejectAll(new Error("invalid JSON from app-server")); return; } - if (parsed.method) return; + if (parsed.method) { + if (onNotification) { + try { onNotification(parsed); } + catch { rejectAll(new Error("notification handler failed")); socket.destroy(); } + } + return; + } const waiter = pending.get(parsed.id); if (!waiter) return; pending.delete(parsed.id); @@ -163,7 +170,9 @@ export async function withCodexAppServer({ clientName, timeout, timeoutMessage } capabilities: { experimentalApi: true }, }); sendText({ method: "initialized" }); - return await work(request); + const result = await work(request); + if (failure) throw failure; + return result; } finally { clearTimeout(timer); socket.destroy(); diff --git a/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs b/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs new file mode 100644 index 00000000..b6279934 --- /dev/null +++ b/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs @@ -0,0 +1,33 @@ +/** Passive, bounded sampling of already delivered native startup notifications. */ +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const statuses = new Set(['starting', 'ready', 'failed', 'cancelled']); +const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); + +// Attach before starting the thread. The native response can bind the thread +// after notifications arrive. Captured names never leave this in-memory object. +export function createCodexMcpStartupObserver() { + const buffered = []; let threadId = null, invalid = false; + return { + onNotification(event) { + if (event?.method !== 'mcpServer/startupStatus/updated') return; + const p = event.params; + if (!p || typeof p.threadId !== 'string' || !uuid.test(p.threadId) || !validName(p.name) || !statuses.has(p.status)) { invalid = true; return; } + if (threadId && p.threadId !== threadId) return; + if (buffered.length >= 4096) { invalid = true; return; } + buffered.push({ threadId: p.threadId, name: p.name, status: p.status }); + }, + bindThread(id) { + if (threadId !== null || typeof id !== 'string' || !uuid.test(id)) throw new Error('invalid startup thread binding'); + threadId = id; + }, + snapshot() { + if (!threadId) throw new Error('startup thread is not bound'); + const latest = new Map(); + for (const row of buffered) if (row.threadId === threadId) latest.set(row.name, row.status); + const counts = { starting: 0, ready: 0, failed: 0, cancelled: 0 }; + for (const status of latest.values()) counts[status]++; + return { schema: 'agent-mesh.codex-mcp-notification-sample.v1', requestedThreadId: threadId, counts, + completeness: 'unverified', invalidOrOverflow: invalid, mcpStarted: null, startupTokens: null }; + } + }; +} From d078e6fdddec87a63b8d01506e8d1f1557bed3e4 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:17:56 +0000 Subject: [PATCH 074/113] Prepare explicit role MCP exclusions for Codex --- docs/design/plexus-channels.md | 10 +++++++ .../bin/codex-role-mcp-overrides.mjs | 21 +++++++++++++++ .../test/codex-role-mcp-overrides.test.mjs | 27 +++++++++++++++++++ .../bin/codex-role-mcp-overrides.mjs | 21 +++++++++++++++ 4 files changed, 79 insertions(+) create mode 100644 packages/tmux-bridge/bin/codex-role-mcp-overrides.mjs create mode 100644 packages/tmux-bridge/test/codex-role-mcp-overrides.test.mjs create mode 100644 skills/agent-tmux/bin/codex-role-mcp-overrides.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 71adaee1..fa57db8f 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -179,3 +179,13 @@ its completeness is unverified and it never claims a process-start or token count. Integration must attach before the authorized isolated startup, bind the actual thread response, and independently establish session, profile and event coverage before using the result as a receipt. It is not enabled for live use. + +`codex-role-mcp-overrides.mjs` prepares explicit disabled entries for servers +outside a role launch plan from a supplied effective inventory, without copying +server commands or enabling a previously disabled server. In isolated Codex CLI +0.169.0 experiments, an empty `mcp_servers` override inherited both configured +fixture servers, while an explicit disabled entry suppressed the excluded +fixture. The generated override produced the same result in that fixture. This +is not proof of complete isolation: the inventory may change or omit dynamic +plugin servers, and permissions and plugins require independent enforcement. +No live launch is wired to this planner. diff --git a/packages/tmux-bridge/bin/codex-role-mcp-overrides.mjs b/packages/tmux-bridge/bin/codex-role-mcp-overrides.mjs new file mode 100644 index 00000000..1cab0d2e --- /dev/null +++ b/packages/tmux-bridge/bin/codex-role-mcp-overrides.mjs @@ -0,0 +1,21 @@ +/** Prepare explicit exclusions from an operator-supplied effective Codex config. */ +const name = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const names = value => Array.isArray(value) && value.length <= 256 && value.every(name) && new Set(value).size === value.length; +const object = value => value !== null && typeof value === 'object' && !Array.isArray(value); + +// This is only a candidate override. Dynamic/plugin servers, changes between +// reading and launching, and permission enforcement require separate evidence. +export function planCodexMcpOverrides({ launchPlan, effectiveServers }) { + if (!object(launchPlan) || launchPlan.schema !== 'agent-mesh.role-launch-plan.v1' || !names(launchPlan.mcpToStart) || !names(launchPlan.mcpUnavailable) || launchPlan.mcpToStart.some(item => launchPlan.mcpUnavailable.includes(item)) || !object(effectiveServers)) throw new Error('invalid MCP override inputs'); + const keys = Object.keys(effectiveServers); + if (keys.length > 4096 || keys.some(key => !name(key) || !object(effectiveServers[key]) || (effectiveServers[key].enabled !== undefined && typeof effectiveServers[key].enabled !== 'boolean'))) throw new Error('invalid effective MCP inventory'); + for (const requested of launchPlan.mcpToStart) { + if (!Object.hasOwn(effectiveServers, requested)) throw new Error('requested MCP missing from effective inventory'); + if (effectiveServers[requested].enabled === false) throw new Error('requested MCP is disabled'); + } + const allowed = new Set(launchPlan.mcpToStart); + const excluded = keys.filter(key => !allowed.has(key)).sort(); + const servers = Object.create(null); + for (const key of excluded) servers[key] = { enabled: false }; + return { schema: 'agent-mesh.codex-mcp-overrides.v1', config: { mcp_servers: servers }, excludedCount: excluded.length, isolation: 'unverified' }; +} diff --git a/packages/tmux-bridge/test/codex-role-mcp-overrides.test.mjs b/packages/tmux-bridge/test/codex-role-mcp-overrides.test.mjs new file mode 100644 index 00000000..4a82e26b --- /dev/null +++ b/packages/tmux-bridge/test/codex-role-mcp-overrides.test.mjs @@ -0,0 +1,27 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { planCodexMcpOverrides } from '../bin/codex-role-mcp-overrides.mjs'; + +const launchPlan = { schema: 'agent-mesh.role-launch-plan.v1', mcpToStart: ['allowed'], mcpUnavailable: ['offline'] }; +const inventory = { allowed: { enabled: true }, offline: { enabled: true }, extra: { command: 'private-fixture' } }; + +test('explicitly disables each excluded effective server without copying its config', () => { + const result = planCodexMcpOverrides({ launchPlan, effectiveServers: inventory }); + assert.deepEqual(JSON.parse(JSON.stringify(result.config)), { mcp_servers: { extra: { enabled: false }, offline: { enabled: false } } }); + assert.equal(result.excludedCount, 2); + assert.equal(result.isolation, 'unverified'); + assert.ok(!JSON.stringify(result).includes('private-fixture')); +}); + +test('missing, disabled, malformed and overlapping inputs fail closed', () => { + assert.throws(() => planCodexMcpOverrides({ launchPlan, effectiveServers: { other: {} } }), /missing/); + assert.throws(() => planCodexMcpOverrides({ launchPlan, effectiveServers: { allowed: { enabled: false } } }), /disabled/); + assert.throws(() => planCodexMcpOverrides({ launchPlan, effectiveServers: { allowed: { enabled: 'yes' } } }), /invalid/); + assert.throws(() => planCodexMcpOverrides({ launchPlan: { ...launchPlan, mcpUnavailable: ['allowed'] }, effectiveServers: inventory }), /invalid/); +}); + +test('an empty allowed role disables every server in the supplied inventory', () => { + const result = planCodexMcpOverrides({ launchPlan: { ...launchPlan, mcpToStart: [] }, effectiveServers: inventory }); + assert.equal(result.excludedCount, 3); + assert.ok(Object.values(result.config.mcp_servers).every(item => item.enabled === false)); +}); diff --git a/skills/agent-tmux/bin/codex-role-mcp-overrides.mjs b/skills/agent-tmux/bin/codex-role-mcp-overrides.mjs new file mode 100644 index 00000000..1cab0d2e --- /dev/null +++ b/skills/agent-tmux/bin/codex-role-mcp-overrides.mjs @@ -0,0 +1,21 @@ +/** Prepare explicit exclusions from an operator-supplied effective Codex config. */ +const name = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const names = value => Array.isArray(value) && value.length <= 256 && value.every(name) && new Set(value).size === value.length; +const object = value => value !== null && typeof value === 'object' && !Array.isArray(value); + +// This is only a candidate override. Dynamic/plugin servers, changes between +// reading and launching, and permission enforcement require separate evidence. +export function planCodexMcpOverrides({ launchPlan, effectiveServers }) { + if (!object(launchPlan) || launchPlan.schema !== 'agent-mesh.role-launch-plan.v1' || !names(launchPlan.mcpToStart) || !names(launchPlan.mcpUnavailable) || launchPlan.mcpToStart.some(item => launchPlan.mcpUnavailable.includes(item)) || !object(effectiveServers)) throw new Error('invalid MCP override inputs'); + const keys = Object.keys(effectiveServers); + if (keys.length > 4096 || keys.some(key => !name(key) || !object(effectiveServers[key]) || (effectiveServers[key].enabled !== undefined && typeof effectiveServers[key].enabled !== 'boolean'))) throw new Error('invalid effective MCP inventory'); + for (const requested of launchPlan.mcpToStart) { + if (!Object.hasOwn(effectiveServers, requested)) throw new Error('requested MCP missing from effective inventory'); + if (effectiveServers[requested].enabled === false) throw new Error('requested MCP is disabled'); + } + const allowed = new Set(launchPlan.mcpToStart); + const excluded = keys.filter(key => !allowed.has(key)).sort(); + const servers = Object.create(null); + for (const key of excluded) servers[key] = { enabled: false }; + return { schema: 'agent-mesh.codex-mcp-overrides.v1', config: { mcp_servers: servers }, excludedCount: excluded.length, isolation: 'unverified' }; +} From c723f551e1211f8fda328a58cdb3b1ca25794a4e Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:23:52 +0000 Subject: [PATCH 075/113] Assess observed Codex role start against policy --- docs/design/plexus-channels.md | 9 +++++ .../bin/codex-mcp-startup-notifications.mjs | 20 ++++++++--- .../bin/codex-role-start-assessment.mjs | 23 +++++++++++++ .../codex-mcp-startup-notifications.test.mjs | 12 +++++++ .../test/codex-role-start-assessment.test.mjs | 34 +++++++++++++++++++ .../bin/codex-mcp-startup-notifications.mjs | 20 ++++++++--- .../bin/codex-role-start-assessment.mjs | 23 +++++++++++++ 7 files changed, 133 insertions(+), 8 deletions(-) create mode 100644 packages/tmux-bridge/bin/codex-role-start-assessment.mjs create mode 100644 packages/tmux-bridge/test/codex-role-start-assessment.test.mjs create mode 100644 skills/agent-tmux/bin/codex-role-start-assessment.mjs diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index fa57db8f..348873c9 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -189,3 +189,12 @@ fixture. The generated override produced the same result in that fixture. This is not proof of complete isolation: the inventory may change or omit dynamic plugin servers, and permissions and plugins require independent enforcement. No live launch is wired to this planner. + +`codex-role-start-assessment.mjs` compares the complete native permission +profile and sandbox objects against a trusted expected policy and flags observed +approval or elicitation requests for rollback. It does not perform rollback or +prove that no prompt was missed. A matching response remains incomplete while +plugin isolation, MCP event coverage and startup token evidence are unknown. +The Codex CLI 0.169.0 generated schema says its `disabledPluginIds` response +field does not yet filter plugin capabilities; it must not be treated as proof +that excluded plugins are inactive. No live launch uses this assessment. diff --git a/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs b/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs index b6279934..51657c25 100644 --- a/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs +++ b/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs @@ -1,6 +1,7 @@ /** Passive, bounded sampling of already delivered native startup notifications. */ const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; const statuses = new Set(['starting', 'ready', 'failed', 'cancelled']); +const permissionMethods = new Set(['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval', 'mcpServer/elicitation/request']); const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); // Attach before starting the thread. The native response can bind the thread @@ -9,8 +10,16 @@ export function createCodexMcpStartupObserver() { const buffered = []; let threadId = null, invalid = false; return { onNotification(event) { - if (event?.method !== 'mcpServer/startupStatus/updated') return; + const permission = permissionMethods.has(event?.method); + if (!permission && event?.method !== 'mcpServer/startupStatus/updated') return; const p = event.params; + if (permission) { + if (!Object.hasOwn(event, 'id') || !p || typeof p.threadId !== 'string' || !uuid.test(p.threadId)) { invalid = true; return; } + if (threadId && p.threadId !== threadId) return; + if (buffered.length >= 4096) { invalid = true; return; } + buffered.push({ threadId: p.threadId, permission: true }); + return; + } if (!p || typeof p.threadId !== 'string' || !uuid.test(p.threadId) || !validName(p.name) || !statuses.has(p.status)) { invalid = true; return; } if (threadId && p.threadId !== threadId) return; if (buffered.length >= 4096) { invalid = true; return; } @@ -22,12 +31,15 @@ export function createCodexMcpStartupObserver() { }, snapshot() { if (!threadId) throw new Error('startup thread is not bound'); - const latest = new Map(); - for (const row of buffered) if (row.threadId === threadId) latest.set(row.name, row.status); + const latest = new Map(); let permissionRequestObserved = null; + for (const row of buffered) if (row.threadId === threadId) { + if (row.permission) permissionRequestObserved = true; + else latest.set(row.name, row.status); + } const counts = { starting: 0, ready: 0, failed: 0, cancelled: 0 }; for (const status of latest.values()) counts[status]++; return { schema: 'agent-mesh.codex-mcp-notification-sample.v1', requestedThreadId: threadId, counts, - completeness: 'unverified', invalidOrOverflow: invalid, mcpStarted: null, startupTokens: null }; + completeness: 'unverified', invalidOrOverflow: invalid, permissionRequestObserved, mcpStarted: null, startupTokens: null }; } }; } diff --git a/packages/tmux-bridge/bin/codex-role-start-assessment.mjs b/packages/tmux-bridge/bin/codex-role-start-assessment.mjs new file mode 100644 index 00000000..6b89ff56 --- /dev/null +++ b/packages/tmux-bridge/bin/codex-role-start-assessment.mjs @@ -0,0 +1,23 @@ +/** Compare a native start response and passive observations to trusted policy. */ +import { isDeepStrictEqual } from 'node:util'; + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const object = value => value !== null && typeof value === 'object' && !Array.isArray(value); + +// Neither argument authenticates itself. The caller must bind the start response +// and events to the same trusted native connection and authorized role policy. +export function assessCodexRoleStart({ startResponse, sample, expected }) { + if (!object(startResponse) || !object(sample) || sample.schema !== 'agent-mesh.codex-mcp-notification-sample.v1' || !object(expected) || !object(expected.profile) || typeof expected.profile.id !== 'string' || !expected.profile.id || !object(expected.sandbox) || expected.approvalPolicy !== 'never' || typeof startResponse.thread?.id !== 'string' || !uuid.test(startResponse.thread.id) || sample.requestedThreadId !== startResponse.thread.id || ![true, null].includes(sample.permissionRequestObserved) || typeof sample.invalidOrOverflow !== 'boolean' || !object(sample.counts) || !Number.isSafeInteger(sample.counts.ready) || sample.counts.ready < 0) throw new Error('invalid role start observation'); + const failures = []; + if (sample.permissionRequestObserved === true) failures.push('unexpected-permission-request'); + if (startResponse.approvalPolicy !== expected.approvalPolicy) failures.push('approval-policy-mismatch'); + if (startResponse.activePermissionProfile != null && !isDeepStrictEqual(startResponse.activePermissionProfile, expected.profile)) failures.push('permission-profile-mismatch'); + if (startResponse.sandbox != null && !isDeepStrictEqual(startResponse.sandbox, expected.sandbox)) failures.push('sandbox-mismatch'); + const unknown = ['plugin-isolation', 'mcp-coverage', 'startup-tokens']; + if (startResponse.activePermissionProfile == null) unknown.push('permission-profile'); + if (startResponse.sandbox == null) unknown.push('sandbox'); + if (sample.invalidOrOverflow) unknown.push('notification-integrity'); + return { schema: 'agent-mesh.codex-role-start-assessment.v1', session: `codex:${startResponse.thread.id}`, + status: failures.length ? 'rollback-required' : 'observed-incomplete', failures, unknown, + readyObserved: sample.counts.ready, mcpStarted: null, startupTokens: null }; +} diff --git a/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs b/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs index 27a4873e..e14d3ef2 100644 --- a/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs +++ b/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs @@ -64,3 +64,15 @@ test('existing app-server client forwards notifications without issuing an inven assert.equal(receipt.counts.ready, 1); assert.equal(receipt.mcpStarted, null); }); + +test('a native permission request for the bound thread is observed without retaining content', () => { + const observer = createCodexMcpStartupObserver(); + observer.onNotification({ id: 12, method: 'item/permissions/requestApproval', params: { threadId: id, permissions: 'private-fixture' } }); + observer.onNotification({ id: 13, method: 'item/fileChange/requestApproval', params: { threadId: other } }); + observer.bindThread(id); + const sample = observer.snapshot(); + assert.equal(sample.permissionRequestObserved, true); + assert.ok(!JSON.stringify(sample).includes('private-fixture')); + const empty = createCodexMcpStartupObserver(); empty.bindThread(id); + assert.equal(empty.snapshot().permissionRequestObserved, null); +}); diff --git a/packages/tmux-bridge/test/codex-role-start-assessment.test.mjs b/packages/tmux-bridge/test/codex-role-start-assessment.test.mjs new file mode 100644 index 00000000..24c0e260 --- /dev/null +++ b/packages/tmux-bridge/test/codex-role-start-assessment.test.mjs @@ -0,0 +1,34 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { assessCodexRoleStart } from '../bin/codex-role-start-assessment.mjs'; + +const id = '22222222-2222-4222-8222-222222222222'; +const expected = { profile: { id: ':read-only', extends: null }, approvalPolicy: 'never', sandbox: { type: 'readOnly', networkAccess: false } }; +const startResponse = { thread: { id }, activePermissionProfile: expected.profile, approvalPolicy: 'never', sandbox: expected.sandbox }; +const sample = { schema: 'agent-mesh.codex-mcp-notification-sample.v1', requestedThreadId: id, permissionRequestObserved: null, invalidOrOverflow: false, counts: { ready: 1 } }; + +test('matching native fields remain incomplete without plugin and event coverage', () => { + const receipt = assessCodexRoleStart({ startResponse, sample, expected }); + assert.equal(receipt.status, 'observed-incomplete'); + assert.equal(receipt.readyObserved, 1); + assert.equal(receipt.mcpStarted, null); + assert.equal(receipt.startupTokens, null); + assert.ok(receipt.unknown.includes('plugin-isolation')); +}); + +test('permission request or exact-policy mismatch demands rollback', () => { + const pending = assessCodexRoleStart({ startResponse, sample: { ...sample, permissionRequestObserved: true }, expected }); + assert.equal(pending.status, 'rollback-required'); + assert.ok(pending.failures.includes('unexpected-permission-request')); + const wrong = assessCodexRoleStart({ startResponse: { ...startResponse, sandbox: { type: 'readOnly', networkAccess: true } }, sample, expected }); + assert.equal(wrong.status, 'rollback-required'); + assert.ok(wrong.failures.includes('sandbox-mismatch')); + assert.throws(() => assessCodexRoleStart({ startResponse, sample: { ...sample, requestedThreadId: 'different' }, expected }), /invalid/); +}); + +test('unobserved fields and broken event coverage cannot prove readiness', () => { + const receipt = assessCodexRoleStart({ startResponse: { ...startResponse, activePermissionProfile: null }, sample: { ...sample, invalidOrOverflow: true }, expected }); + assert.equal(receipt.status, 'observed-incomplete'); + assert.ok(receipt.unknown.includes('permission-profile')); + assert.ok(receipt.unknown.includes('notification-integrity')); +}); diff --git a/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs b/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs index b6279934..51657c25 100644 --- a/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs +++ b/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs @@ -1,6 +1,7 @@ /** Passive, bounded sampling of already delivered native startup notifications. */ const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; const statuses = new Set(['starting', 'ready', 'failed', 'cancelled']); +const permissionMethods = new Set(['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval', 'mcpServer/elicitation/request']); const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); // Attach before starting the thread. The native response can bind the thread @@ -9,8 +10,16 @@ export function createCodexMcpStartupObserver() { const buffered = []; let threadId = null, invalid = false; return { onNotification(event) { - if (event?.method !== 'mcpServer/startupStatus/updated') return; + const permission = permissionMethods.has(event?.method); + if (!permission && event?.method !== 'mcpServer/startupStatus/updated') return; const p = event.params; + if (permission) { + if (!Object.hasOwn(event, 'id') || !p || typeof p.threadId !== 'string' || !uuid.test(p.threadId)) { invalid = true; return; } + if (threadId && p.threadId !== threadId) return; + if (buffered.length >= 4096) { invalid = true; return; } + buffered.push({ threadId: p.threadId, permission: true }); + return; + } if (!p || typeof p.threadId !== 'string' || !uuid.test(p.threadId) || !validName(p.name) || !statuses.has(p.status)) { invalid = true; return; } if (threadId && p.threadId !== threadId) return; if (buffered.length >= 4096) { invalid = true; return; } @@ -22,12 +31,15 @@ export function createCodexMcpStartupObserver() { }, snapshot() { if (!threadId) throw new Error('startup thread is not bound'); - const latest = new Map(); - for (const row of buffered) if (row.threadId === threadId) latest.set(row.name, row.status); + const latest = new Map(); let permissionRequestObserved = null; + for (const row of buffered) if (row.threadId === threadId) { + if (row.permission) permissionRequestObserved = true; + else latest.set(row.name, row.status); + } const counts = { starting: 0, ready: 0, failed: 0, cancelled: 0 }; for (const status of latest.values()) counts[status]++; return { schema: 'agent-mesh.codex-mcp-notification-sample.v1', requestedThreadId: threadId, counts, - completeness: 'unverified', invalidOrOverflow: invalid, mcpStarted: null, startupTokens: null }; + completeness: 'unverified', invalidOrOverflow: invalid, permissionRequestObserved, mcpStarted: null, startupTokens: null }; } }; } diff --git a/skills/agent-tmux/bin/codex-role-start-assessment.mjs b/skills/agent-tmux/bin/codex-role-start-assessment.mjs new file mode 100644 index 00000000..6b89ff56 --- /dev/null +++ b/skills/agent-tmux/bin/codex-role-start-assessment.mjs @@ -0,0 +1,23 @@ +/** Compare a native start response and passive observations to trusted policy. */ +import { isDeepStrictEqual } from 'node:util'; + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const object = value => value !== null && typeof value === 'object' && !Array.isArray(value); + +// Neither argument authenticates itself. The caller must bind the start response +// and events to the same trusted native connection and authorized role policy. +export function assessCodexRoleStart({ startResponse, sample, expected }) { + if (!object(startResponse) || !object(sample) || sample.schema !== 'agent-mesh.codex-mcp-notification-sample.v1' || !object(expected) || !object(expected.profile) || typeof expected.profile.id !== 'string' || !expected.profile.id || !object(expected.sandbox) || expected.approvalPolicy !== 'never' || typeof startResponse.thread?.id !== 'string' || !uuid.test(startResponse.thread.id) || sample.requestedThreadId !== startResponse.thread.id || ![true, null].includes(sample.permissionRequestObserved) || typeof sample.invalidOrOverflow !== 'boolean' || !object(sample.counts) || !Number.isSafeInteger(sample.counts.ready) || sample.counts.ready < 0) throw new Error('invalid role start observation'); + const failures = []; + if (sample.permissionRequestObserved === true) failures.push('unexpected-permission-request'); + if (startResponse.approvalPolicy !== expected.approvalPolicy) failures.push('approval-policy-mismatch'); + if (startResponse.activePermissionProfile != null && !isDeepStrictEqual(startResponse.activePermissionProfile, expected.profile)) failures.push('permission-profile-mismatch'); + if (startResponse.sandbox != null && !isDeepStrictEqual(startResponse.sandbox, expected.sandbox)) failures.push('sandbox-mismatch'); + const unknown = ['plugin-isolation', 'mcp-coverage', 'startup-tokens']; + if (startResponse.activePermissionProfile == null) unknown.push('permission-profile'); + if (startResponse.sandbox == null) unknown.push('sandbox'); + if (sample.invalidOrOverflow) unknown.push('notification-integrity'); + return { schema: 'agent-mesh.codex-role-start-assessment.v1', session: `codex:${startResponse.thread.id}`, + status: failures.length ? 'rollback-required' : 'observed-incomplete', failures, unknown, + readyObserved: sample.counts.ready, mcpStarted: null, startupTokens: null }; +} From d59aaf3ae22e262c18a636f32f43b20a7d6bd003 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:39:27 +0000 Subject: [PATCH 076/113] Add fail-closed namespace execution gate --- docs/design/plexus-channels.md | 9 +++ .../tmux-bridge/bin/namespace-exec-gate.py | 43 ++++++++++++ .../scripts/test-isolation-regression.sh | 1 + .../test/namespace-exec-gate.test.py | 66 +++++++++++++++++++ skills/agent-tmux/bin/namespace-exec-gate.py | 43 ++++++++++++ 5 files changed, 162 insertions(+) create mode 100644 packages/tmux-bridge/bin/namespace-exec-gate.py create mode 100644 packages/tmux-bridge/test/namespace-exec-gate.test.py create mode 100644 skills/agent-tmux/bin/namespace-exec-gate.py diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 348873c9..1470d3f2 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -198,3 +198,12 @@ plugin isolation, MCP event coverage and startup token evidence are unknown. The Codex CLI 0.169.0 generated schema says its `disabledPluginIds` response field does not yet filter plugin capabilities; it must not be treated as proof that excluded plugins are inactive. No live launch uses this assessment. + +`namespace-exec-gate.py` is a coordination gate for a future dedicated +launcher: it executes only after an explicit `GO` record on an owner-private +FIFO and fails closed on EOF, a different record or an unsafe FIFO. It does not +authenticate a same-user writer, establish process ownership, or implement +rollback. Isolated tests covered coordinator exit and a child that changes +process group inside a PID namespace; production launcher ownership, pidfd +recovery, runtime compatibility and remote effects remain unverified. The gate +is not connected to live handover. diff --git a/packages/tmux-bridge/bin/namespace-exec-gate.py b/packages/tmux-bridge/bin/namespace-exec-gate.py new file mode 100644 index 00000000..5fea1f1c --- /dev/null +++ b/packages/tmux-bridge/bin/namespace-exec-gate.py @@ -0,0 +1,43 @@ +#!/usr/bin/env python3 +"""Execute a trusted command only after an explicit private FIFO release. + +This gate is a fail-closed coordination primitive, not an authorization boundary. +The caller owns the namespace, FIFO, command, environment and lifecycle. +""" +import os +from pathlib import Path +import stat +import sys + + +def main(argv): + if len(argv) < 3 or argv[1] != '--' or not os.path.isabs(argv[0]) or not os.path.isabs(argv[2]): + return 125 + fifo = Path(argv[0]) + try: + parent = fifo.parent + directory = parent.lstat() + entry = fifo.lstat() + if (not stat.S_ISDIR(directory.st_mode) or directory.st_uid != os.getuid() or directory.st_mode & 0o077 or + parent.resolve(strict=True) != parent or not stat.S_ISFIFO(entry.st_mode) or + entry.st_uid != os.getuid() or entry.st_mode & 0o077 or entry.st_nlink != 1): + return 125 + fd = os.open(fifo, os.O_RDONLY | os.O_NOFOLLOW) + try: + opened = os.fstat(fd) + if (not stat.S_ISFIFO(opened.st_mode) or opened.st_uid != os.getuid() or opened.st_mode & 0o077 or opened.st_nlink != 1 or + opened.st_dev != entry.st_dev or opened.st_ino != entry.st_ino): + return 125 + permit = os.read(fd, 4) + finally: + os.close(fd) + if permit != b'GO\n': + return 125 + os.execv(argv[2], argv[2:]) + except OSError: + return 125 + return 125 + + +if __name__ == '__main__': + raise SystemExit(main(sys.argv[1:])) diff --git a/packages/tmux-bridge/scripts/test-isolation-regression.sh b/packages/tmux-bridge/scripts/test-isolation-regression.sh index 543f8022..8eb0018c 100644 --- a/packages/tmux-bridge/scripts/test-isolation-regression.sh +++ b/packages/tmux-bridge/scripts/test-isolation-regression.sh @@ -63,6 +63,7 @@ python3 test/session-inbox.test.py python3 test/run-receipt.test.py python3 test/agent-waker.test.py python3 test/agent-waker-channel.test.py +python3 test/namespace-exec-gate.test.py python3 test/session-controller.test.py python3 test/owner-notify.test.py scripts/socket-isolation-test.sh diff --git a/packages/tmux-bridge/test/namespace-exec-gate.test.py b/packages/tmux-bridge/test/namespace-exec-gate.test.py new file mode 100644 index 00000000..85f85cad --- /dev/null +++ b/packages/tmux-bridge/test/namespace-exec-gate.test.py @@ -0,0 +1,66 @@ +import os +from pathlib import Path +import subprocess +import sys +import tempfile +import time +import unittest + +GATE = Path(__file__).resolve().parents[1] / 'bin' / 'namespace-exec-gate.py' + + +class NamespaceExecGateTest(unittest.TestCase): + def launch(self, fifo, marker): + code = 'import pathlib,sys;pathlib.Path(sys.argv[1]).write_text("executed")' + return subprocess.Popen([sys.executable, '-B', str(GATE), str(fifo), '--', sys.executable, '-c', code, str(marker)], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) + + def writer(self, fifo): + for _ in range(200): + try: + return os.open(fifo, os.O_WRONLY | os.O_NONBLOCK) + except OSError as exc: + if exc.errno != 6: + raise + time.sleep(.01) + self.fail('fixture reader unavailable') + + def test_eof_and_wrong_permit_never_execute(self): + for permit in (b'', b'NO\n', b'GO\nX'): + with self.subTest(permit=permit), tempfile.TemporaryDirectory() as root: + fifo, marker = Path(root) / 'gate', Path(root) / 'ran' + os.mkfifo(fifo, 0o600) + process = self.launch(fifo, marker) + fd = self.writer(fifo) + if permit: + os.write(fd, permit) + os.close(fd) + self.assertEqual(process.wait(timeout=5), 125) + self.assertFalse(marker.exists()) + + def test_explicit_permit_executes_only_fixture(self): + with tempfile.TemporaryDirectory() as root: + fifo, marker = Path(root) / 'gate', Path(root) / 'ran' + os.mkfifo(fifo, 0o600) + process = self.launch(fifo, marker) + fd = self.writer(fifo) + os.write(fd, b'GO\n'); os.close(fd) + self.assertEqual(process.wait(timeout=5), 0) + self.assertTrue(marker.exists()) + + def test_regular_file_symlink_and_public_directory_are_rejected(self): + with tempfile.TemporaryDirectory() as root: + root = Path(root) + real, link, marker = root / 'real', root / 'link', root / 'ran' + real.write_text('GO\n') + self.assertEqual(self.launch(real, marker).wait(timeout=5), 125) + link.symlink_to(real) + self.assertEqual(self.launch(link, marker).wait(timeout=5), 125) + os.mkfifo(root / 'fifo', 0o600) + os.chmod(root, 0o755) + self.assertEqual(self.launch(root / 'fifo', marker).wait(timeout=5), 125) + os.chmod(root, 0o700) + self.assertFalse(marker.exists()) + + +if __name__ == '__main__': + unittest.main() diff --git a/skills/agent-tmux/bin/namespace-exec-gate.py b/skills/agent-tmux/bin/namespace-exec-gate.py new file mode 100644 index 00000000..5fea1f1c --- /dev/null +++ b/skills/agent-tmux/bin/namespace-exec-gate.py @@ -0,0 +1,43 @@ +#!/usr/bin/env python3 +"""Execute a trusted command only after an explicit private FIFO release. + +This gate is a fail-closed coordination primitive, not an authorization boundary. +The caller owns the namespace, FIFO, command, environment and lifecycle. +""" +import os +from pathlib import Path +import stat +import sys + + +def main(argv): + if len(argv) < 3 or argv[1] != '--' or not os.path.isabs(argv[0]) or not os.path.isabs(argv[2]): + return 125 + fifo = Path(argv[0]) + try: + parent = fifo.parent + directory = parent.lstat() + entry = fifo.lstat() + if (not stat.S_ISDIR(directory.st_mode) or directory.st_uid != os.getuid() or directory.st_mode & 0o077 or + parent.resolve(strict=True) != parent or not stat.S_ISFIFO(entry.st_mode) or + entry.st_uid != os.getuid() or entry.st_mode & 0o077 or entry.st_nlink != 1): + return 125 + fd = os.open(fifo, os.O_RDONLY | os.O_NOFOLLOW) + try: + opened = os.fstat(fd) + if (not stat.S_ISFIFO(opened.st_mode) or opened.st_uid != os.getuid() or opened.st_mode & 0o077 or opened.st_nlink != 1 or + opened.st_dev != entry.st_dev or opened.st_ino != entry.st_ino): + return 125 + permit = os.read(fd, 4) + finally: + os.close(fd) + if permit != b'GO\n': + return 125 + os.execv(argv[2], argv[2:]) + except OSError: + return 125 + return 125 + + +if __name__ == '__main__': + raise SystemExit(main(sys.argv[1:])) From ba29806c1c5cbd4317902f26fe5f95b98b846364 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:47:18 +0000 Subject: [PATCH 077/113] Prepare owned isolated PID namespace lease --- docs/design/plexus-channels.md | 11 + .../tmux-bridge/bin/isolated-pid-namespace.py | 199 ++++++++++++++++++ .../scripts/test-isolation-regression.sh | 1 + .../test/isolated-pid-namespace.test.py | 96 +++++++++ .../agent-tmux/bin/isolated-pid-namespace.py | 199 ++++++++++++++++++ 5 files changed, 506 insertions(+) create mode 100644 packages/tmux-bridge/bin/isolated-pid-namespace.py create mode 100644 packages/tmux-bridge/test/isolated-pid-namespace.test.py create mode 100644 skills/agent-tmux/bin/isolated-pid-namespace.py diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 1470d3f2..a7b0b0b7 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -207,3 +207,14 @@ rollback. Isolated tests covered coordinator exit and a child that changes process group inside a PID namespace; production launcher ownership, pidfd recovery, runtime compatibility and remote effects remain unverified. The gate is not connected to live handover. + +`isolated-pid-namespace.py` prepares a network-isolated experimental child +behind that gate. It checks the namespace init's parent, owner, namespace ID +and pidfd identity before opening the gate. Its stop operation targets only +the pinned init and reports local init exit with descendant and remote effects +still unverified. Preparation failure closes the gate without releasing it; if +ownership or cleanup cannot be established it reports uncertainty. The lease +must remain in the creating process and is not a persistent recovery mechanism, +an authorization boundary or an integrated live session launcher. The sandbox +uses a read-only host filesystem with a private writable workspace and is for +isolated fixtures only. diff --git a/packages/tmux-bridge/bin/isolated-pid-namespace.py b/packages/tmux-bridge/bin/isolated-pid-namespace.py new file mode 100644 index 00000000..002b6e93 --- /dev/null +++ b/packages/tmux-bridge/bin/isolated-pid-namespace.py @@ -0,0 +1,199 @@ +#!/usr/bin/env python3 +"""Experimental, network-isolated PID namespace lease for owned processes. + +No handover or session lifecycle uses this module. It is not an authorization +boundary and cannot undo remote effects. A caller must keep the lease alive. +""" +import errno +import json +import os +from pathlib import Path +import select +import signal +import stat +import subprocess +import sys +import time +import uuid + +BWRAP = '/usr/bin/bwrap' +GATE = str(Path(__file__).resolve().with_name('namespace-exec-gate.py')) + + +def _identity(pid): + proc = Path('/proc') / str(pid) + meta = proc.stat() + fields = (proc / 'stat').read_text().rsplit(')', 1)[1].split() + status = (proc / 'status').read_text().splitlines() + nested = next(line for line in status if line.startswith('NSpid:')).split()[1:] + return meta.st_uid, int(fields[1]), fields[19], nested, (proc / 'ns/pid').stat().st_ino + + +def _pidfd_pid(fd): + lines = Path(f'/proc/self/fdinfo/{fd}').read_text().splitlines() + return int(next(line for line in lines if line.startswith('Pid:')).split()[1]) + + +class IsolatedNamespace: + """An owned lease, prepared but not released; do not target external PIDs.""" + def __init__(self, process, pidfd, gatefd): + self.process = process + self._pidfd = pidfd + self._gatefd = gatefd + self._released = False + self._stopped = False + + @classmethod + def prepare(cls, workspace, command, *, timeout=5): + if not hasattr(os, 'pidfd_open') or not hasattr(signal, 'pidfd_send_signal'): + raise RuntimeError('pidfd support unavailable') + root = Path(workspace) + if not root.is_absolute() or root.resolve(strict=True) != root: + raise ValueError('workspace must be canonical') + info = root.lstat() + if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('workspace must be private') + if not isinstance(command, list) or not command or len(command) > 64 or not os.path.isabs(command[0]) or any(not isinstance(item, str) or not item or len(item) > 8192 or '\x00' in item for item in command) or isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 0 < timeout <= 30: + raise ValueError('invalid isolated command') + fifo = root / f'.namespace-gate-{uuid.uuid4().hex}' + os.mkfifo(fifo, 0o600) + before = fifo.lstat() + readfd, writefd = os.pipe() + process = None + pidfd = None + gatefd = None + verified = False + try: + args = [BWRAP, '--ro-bind', '/', '/', '--tmpfs', '/tmp', '--bind', str(root), str(root), + '--proc', '/proc', '--dev', '/dev', '--unshare-pid', '--unshare-net', '--die-with-parent', + '--info-fd', str(writefd), '--clearenv', '--setenv', 'PATH', '/usr/bin:/bin', + '--chdir', str(root), sys.executable, '-B', GATE, str(fifo), '--', *command] + process = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, + pass_fds=(writefd,), start_new_session=True) + os.close(writefd) + writefd = None + deadline = time.monotonic() + timeout + raw = b'' + while True: + remaining = deadline - time.monotonic() + if remaining <= 0 or not select.select([readfd], [], [], remaining)[0]: + raise RuntimeError('namespace information unavailable') + chunk = os.read(readfd, 8193 - len(raw)) + if not chunk: + raise RuntimeError('incomplete namespace information') + raw += chunk + if len(raw) > 8192: + raise RuntimeError('invalid namespace information') + try: + record = json.loads(raw) + break + except json.JSONDecodeError: + continue + pid, inode = record.get('child-pid'), record.get('pid-namespace') + if isinstance(pid, bool) or not isinstance(pid, int) or pid < 2 or isinstance(inode, bool) or not isinstance(inode, int): + raise RuntimeError('invalid namespace identity') + first = _identity(pid) + if first[0] != os.getuid() or first[1] != process.pid or first[3][-1:] != ['1'] or first[4] != inode or inode == Path('/proc/self/ns/pid').stat().st_ino: + raise RuntimeError('namespace ownership unverified') + pidfd = os.pidfd_open(pid) + if _pidfd_pid(pidfd) != pid or _identity(pid) != first: + raise RuntimeError('namespace identity changed') + verified = True + deadline = time.monotonic() + timeout + while True: + try: + gatefd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK | os.O_NOFOLLOW) + break + except OSError as exc: + if exc.errno != errno.ENXIO or time.monotonic() >= deadline: + raise + time.sleep(.01) + opened = os.fstat(gatefd) + if not stat.S_ISFIFO(opened.st_mode) or opened.st_uid != os.getuid() or opened.st_mode & 0o077 or opened.st_nlink != 1 or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + raise RuntimeError('gate identity changed') + result = cls(process, pidfd, gatefd) + pidfd = None + return result + except Exception as exc: + # Never release the gate on error. If ownership was verified, the + # pinned namespace init can be stopped without targeting another PID. + if pidfd is not None: + if verified: + try: + signal.pidfd_send_signal(pidfd, signal.SIGKILL) + except ProcessLookupError: + pass + os.close(pidfd) + if gatefd is not None: + os.close(gatefd) + elif process is not None and not verified: + # An empty writer makes the trusted gate refuse execution. Do + # not touch a FIFO that no longer has the original identity. + deadline = time.monotonic() + 2 + while time.monotonic() < deadline: + abortfd = None + try: + abortfd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK | os.O_NOFOLLOW) + opened = os.fstat(abortfd) + if not stat.S_ISFIFO(opened.st_mode) or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + break + break + except OSError as abort_error: + if abort_error.errno != errno.ENXIO: + break + time.sleep(.01) + finally: + if abortfd is not None: + os.close(abortfd) + if process is not None: + try: + process.wait(timeout=2) + except subprocess.TimeoutExpired: + # An unverified namespace may need operator reconciliation. + pass + for stream in (process.stdin, process.stdout, process.stderr): + if stream: + stream.close() + raise RuntimeError('isolated preparation failed; cleanup may be unverified') from exc + finally: + os.close(readfd) + if writefd is not None: + os.close(writefd) + + def release(self): + if self._stopped or self._released or self._gatefd is None: + raise RuntimeError('gate unavailable') + try: + if os.write(self._gatefd, b'GO\n') != 3: + raise RuntimeError('gate release uncertain') + finally: + os.close(self._gatefd) + self._gatefd = None + self._released = True + + def stop(self, *, timeout=5): + if self._stopped or self._pidfd is None or isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 0 < timeout <= 30: + raise RuntimeError('namespace lease unavailable') + try: + signal.pidfd_send_signal(self._pidfd, signal.SIGKILL) + except ProcessLookupError: + pass + poller = select.poll() + poller.register(self._pidfd, select.POLLIN) + if not poller.poll(int(timeout * 1000)): + raise RuntimeError('namespace init exit unverified') + try: + self.process.wait(timeout=timeout) + except subprocess.TimeoutExpired as exc: + raise RuntimeError('namespace wrapper exit unverified') from exc + if self._gatefd is not None: + os.close(self._gatefd) + self._gatefd = None + os.close(self._pidfd) + self._pidfd = None + self._stopped = True + for stream in (self.process.stdin, self.process.stdout, self.process.stderr): + if stream: + stream.close() + return {'schema': 'agent-mesh.isolated-namespace-stop.v1', 'status': 'init-exited', + 'descendants': 'unverified', 'remoteEffects': 'unverified'} diff --git a/packages/tmux-bridge/scripts/test-isolation-regression.sh b/packages/tmux-bridge/scripts/test-isolation-regression.sh index 8eb0018c..0cb4637c 100644 --- a/packages/tmux-bridge/scripts/test-isolation-regression.sh +++ b/packages/tmux-bridge/scripts/test-isolation-regression.sh @@ -64,6 +64,7 @@ python3 test/run-receipt.test.py python3 test/agent-waker.test.py python3 test/agent-waker-channel.test.py python3 test/namespace-exec-gate.test.py +python3 test/isolated-pid-namespace.test.py python3 test/session-controller.test.py python3 test/owner-notify.test.py scripts/socket-isolation-test.sh diff --git a/packages/tmux-bridge/test/isolated-pid-namespace.test.py b/packages/tmux-bridge/test/isolated-pid-namespace.test.py new file mode 100644 index 00000000..17e93389 --- /dev/null +++ b/packages/tmux-bridge/test/isolated-pid-namespace.test.py @@ -0,0 +1,96 @@ +import importlib.util +import os +from pathlib import Path +import subprocess +import sys +import tempfile +import time +import unittest +from unittest.mock import patch + +BIN = Path(__file__).resolve().parents[1] / 'bin' +spec = importlib.util.spec_from_file_location('isolated_namespace', BIN / 'isolated-pid-namespace.py') +module = importlib.util.module_from_spec(spec) +spec.loader.exec_module(module) + + +def supported(): + if not hasattr(os, 'pidfd_open') or not Path('/usr/bin/bwrap').exists(): + return False + result = subprocess.run(['/usr/bin/bwrap', '--ro-bind', '/', '/', '--proc', '/proc', '--dev', '/dev', + '--unshare-pid', '--unshare-net', '--', '/usr/bin/true'], + stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=5) + return result.returncode == 0 + + +@unittest.skipUnless(supported(), 'isolated PID namespaces or pidfd unavailable') +class IsolatedPidNamespaceTest(unittest.TestCase): + def wait_for(self, path): + for _ in range(200): + if path.exists(): + return + time.sleep(.01) + self.fail('fixture did not start') + + def test_stop_before_release_does_not_execute_command(self): + with tempfile.TemporaryDirectory() as directory: + marker = Path(directory) / 'ran' + code = 'import pathlib,sys;pathlib.Path(sys.argv[1]).write_text("ran")' + lease = module.IsolatedNamespace.prepare(directory, [sys.executable, '-c', code, str(marker)]) + self.assertFalse(marker.exists()) + receipt = lease.stop() + self.assertEqual(receipt['status'], 'init-exited') + self.assertEqual(receipt['descendants'], 'unverified') + self.assertEqual(receipt['remoteEffects'], 'unverified') + self.assertFalse(marker.exists()) + with self.assertRaises(RuntimeError): + lease.release() + + def test_release_and_stop_own_namespace_with_escaped_fixture(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + marker, child_started, late = root / 'ran', root / 'child-started', root / 'late' + escaped = root / 'escaped.py' + escaped.write_text('import os,pathlib,signal,sys,time\nos.setsid()\nsignal.signal(signal.SIGTERM,signal.SIG_IGN)\npathlib.Path(sys.argv[1]).write_text("started")\ntime.sleep(2)\npathlib.Path(sys.argv[2]).write_text("late")\n') + payload = root / 'payload.py' + payload.write_text('import pathlib,subprocess,sys,time\nsubprocess.Popen([sys.executable,sys.argv[1],sys.argv[3],sys.argv[4]])\npathlib.Path(sys.argv[2]).write_text("ran")\nwhile True: time.sleep(1)\n') + lease = module.IsolatedNamespace.prepare(directory, [sys.executable, str(payload), str(escaped), str(marker), str(child_started), str(late)]) + try: + self.assertFalse(marker.exists()) + lease.release() + self.wait_for(marker) + self.wait_for(child_started) + with self.assertRaises(RuntimeError): + lease.release() + self.assertEqual(lease.stop()['status'], 'init-exited') + time.sleep(2.2) + self.assertFalse(late.exists()) + finally: + if not lease._stopped: + lease.stop() + + def test_unverified_identity_closes_gate_without_running_fixture(self): + with tempfile.TemporaryDirectory() as directory: + marker = Path(directory) / 'ran' + code = 'import pathlib,sys;pathlib.Path(sys.argv[1]).write_text("ran")' + with patch.object(module, '_identity', return_value=(-1, -1, '0', ['1'], -1)): + with self.assertRaisesRegex(RuntimeError, 'cleanup may be unverified'): + module.IsolatedNamespace.prepare(directory, [sys.executable, '-c', code, str(marker)]) + self.assertFalse(marker.exists()) + listing = subprocess.run(['ps', '-eo', 'args'], capture_output=True, text=True, check=True).stdout + self.assertNotIn(directory, listing) + + def test_invalid_workspace_or_command_does_not_launch(self): + with tempfile.TemporaryDirectory() as directory: + with self.assertRaises(ValueError): + module.IsolatedNamespace.prepare(directory, ['relative-command']) + os.chmod(directory, 0o755) + try: + with self.assertRaises(ValueError): + module.IsolatedNamespace.prepare(directory, ['/usr/bin/true']) + finally: + os.chmod(directory, 0o700) + + +if __name__ == '__main__': + unittest.main() diff --git a/skills/agent-tmux/bin/isolated-pid-namespace.py b/skills/agent-tmux/bin/isolated-pid-namespace.py new file mode 100644 index 00000000..002b6e93 --- /dev/null +++ b/skills/agent-tmux/bin/isolated-pid-namespace.py @@ -0,0 +1,199 @@ +#!/usr/bin/env python3 +"""Experimental, network-isolated PID namespace lease for owned processes. + +No handover or session lifecycle uses this module. It is not an authorization +boundary and cannot undo remote effects. A caller must keep the lease alive. +""" +import errno +import json +import os +from pathlib import Path +import select +import signal +import stat +import subprocess +import sys +import time +import uuid + +BWRAP = '/usr/bin/bwrap' +GATE = str(Path(__file__).resolve().with_name('namespace-exec-gate.py')) + + +def _identity(pid): + proc = Path('/proc') / str(pid) + meta = proc.stat() + fields = (proc / 'stat').read_text().rsplit(')', 1)[1].split() + status = (proc / 'status').read_text().splitlines() + nested = next(line for line in status if line.startswith('NSpid:')).split()[1:] + return meta.st_uid, int(fields[1]), fields[19], nested, (proc / 'ns/pid').stat().st_ino + + +def _pidfd_pid(fd): + lines = Path(f'/proc/self/fdinfo/{fd}').read_text().splitlines() + return int(next(line for line in lines if line.startswith('Pid:')).split()[1]) + + +class IsolatedNamespace: + """An owned lease, prepared but not released; do not target external PIDs.""" + def __init__(self, process, pidfd, gatefd): + self.process = process + self._pidfd = pidfd + self._gatefd = gatefd + self._released = False + self._stopped = False + + @classmethod + def prepare(cls, workspace, command, *, timeout=5): + if not hasattr(os, 'pidfd_open') or not hasattr(signal, 'pidfd_send_signal'): + raise RuntimeError('pidfd support unavailable') + root = Path(workspace) + if not root.is_absolute() or root.resolve(strict=True) != root: + raise ValueError('workspace must be canonical') + info = root.lstat() + if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('workspace must be private') + if not isinstance(command, list) or not command or len(command) > 64 or not os.path.isabs(command[0]) or any(not isinstance(item, str) or not item or len(item) > 8192 or '\x00' in item for item in command) or isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 0 < timeout <= 30: + raise ValueError('invalid isolated command') + fifo = root / f'.namespace-gate-{uuid.uuid4().hex}' + os.mkfifo(fifo, 0o600) + before = fifo.lstat() + readfd, writefd = os.pipe() + process = None + pidfd = None + gatefd = None + verified = False + try: + args = [BWRAP, '--ro-bind', '/', '/', '--tmpfs', '/tmp', '--bind', str(root), str(root), + '--proc', '/proc', '--dev', '/dev', '--unshare-pid', '--unshare-net', '--die-with-parent', + '--info-fd', str(writefd), '--clearenv', '--setenv', 'PATH', '/usr/bin:/bin', + '--chdir', str(root), sys.executable, '-B', GATE, str(fifo), '--', *command] + process = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, + pass_fds=(writefd,), start_new_session=True) + os.close(writefd) + writefd = None + deadline = time.monotonic() + timeout + raw = b'' + while True: + remaining = deadline - time.monotonic() + if remaining <= 0 or not select.select([readfd], [], [], remaining)[0]: + raise RuntimeError('namespace information unavailable') + chunk = os.read(readfd, 8193 - len(raw)) + if not chunk: + raise RuntimeError('incomplete namespace information') + raw += chunk + if len(raw) > 8192: + raise RuntimeError('invalid namespace information') + try: + record = json.loads(raw) + break + except json.JSONDecodeError: + continue + pid, inode = record.get('child-pid'), record.get('pid-namespace') + if isinstance(pid, bool) or not isinstance(pid, int) or pid < 2 or isinstance(inode, bool) or not isinstance(inode, int): + raise RuntimeError('invalid namespace identity') + first = _identity(pid) + if first[0] != os.getuid() or first[1] != process.pid or first[3][-1:] != ['1'] or first[4] != inode or inode == Path('/proc/self/ns/pid').stat().st_ino: + raise RuntimeError('namespace ownership unverified') + pidfd = os.pidfd_open(pid) + if _pidfd_pid(pidfd) != pid or _identity(pid) != first: + raise RuntimeError('namespace identity changed') + verified = True + deadline = time.monotonic() + timeout + while True: + try: + gatefd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK | os.O_NOFOLLOW) + break + except OSError as exc: + if exc.errno != errno.ENXIO or time.monotonic() >= deadline: + raise + time.sleep(.01) + opened = os.fstat(gatefd) + if not stat.S_ISFIFO(opened.st_mode) or opened.st_uid != os.getuid() or opened.st_mode & 0o077 or opened.st_nlink != 1 or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + raise RuntimeError('gate identity changed') + result = cls(process, pidfd, gatefd) + pidfd = None + return result + except Exception as exc: + # Never release the gate on error. If ownership was verified, the + # pinned namespace init can be stopped without targeting another PID. + if pidfd is not None: + if verified: + try: + signal.pidfd_send_signal(pidfd, signal.SIGKILL) + except ProcessLookupError: + pass + os.close(pidfd) + if gatefd is not None: + os.close(gatefd) + elif process is not None and not verified: + # An empty writer makes the trusted gate refuse execution. Do + # not touch a FIFO that no longer has the original identity. + deadline = time.monotonic() + 2 + while time.monotonic() < deadline: + abortfd = None + try: + abortfd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK | os.O_NOFOLLOW) + opened = os.fstat(abortfd) + if not stat.S_ISFIFO(opened.st_mode) or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + break + break + except OSError as abort_error: + if abort_error.errno != errno.ENXIO: + break + time.sleep(.01) + finally: + if abortfd is not None: + os.close(abortfd) + if process is not None: + try: + process.wait(timeout=2) + except subprocess.TimeoutExpired: + # An unverified namespace may need operator reconciliation. + pass + for stream in (process.stdin, process.stdout, process.stderr): + if stream: + stream.close() + raise RuntimeError('isolated preparation failed; cleanup may be unverified') from exc + finally: + os.close(readfd) + if writefd is not None: + os.close(writefd) + + def release(self): + if self._stopped or self._released or self._gatefd is None: + raise RuntimeError('gate unavailable') + try: + if os.write(self._gatefd, b'GO\n') != 3: + raise RuntimeError('gate release uncertain') + finally: + os.close(self._gatefd) + self._gatefd = None + self._released = True + + def stop(self, *, timeout=5): + if self._stopped or self._pidfd is None or isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 0 < timeout <= 30: + raise RuntimeError('namespace lease unavailable') + try: + signal.pidfd_send_signal(self._pidfd, signal.SIGKILL) + except ProcessLookupError: + pass + poller = select.poll() + poller.register(self._pidfd, select.POLLIN) + if not poller.poll(int(timeout * 1000)): + raise RuntimeError('namespace init exit unverified') + try: + self.process.wait(timeout=timeout) + except subprocess.TimeoutExpired as exc: + raise RuntimeError('namespace wrapper exit unverified') from exc + if self._gatefd is not None: + os.close(self._gatefd) + self._gatefd = None + os.close(self._pidfd) + self._pidfd = None + self._stopped = True + for stream in (self.process.stdin, self.process.stdout, self.process.stderr): + if stream: + stream.close() + return {'schema': 'agent-mesh.isolated-namespace-stop.v1', 'status': 'init-exited', + 'descendants': 'unverified', 'remoteEffects': 'unverified'} From 565ebfff3e3a4ab3a9f0d6cd7f5c0ec61238998a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:51:17 +0000 Subject: [PATCH 078/113] Test supervisor death around namespace release --- docs/design/plexus-channels.md | 8 +++++--- .../test/isolated-pid-namespace.test.py | 16 ++++++++++++++++ 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index a7b0b0b7..745de7f1 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -215,6 +215,8 @@ the pinned init and reports local init exit with descendant and remote effects still unverified. Preparation failure closes the gate without releasing it; if ownership or cleanup cannot be established it reports uncertainty. The lease must remain in the creating process and is not a persistent recovery mechanism, -an authorization boundary or an integrated live session launcher. The sandbox -uses a read-only host filesystem with a private writable workspace and is for -isolated fixtures only. +an authorization boundary or an integrated live session launcher. Isolated +tests cover abrupt supervisor exit both before and after release, including a +child that changes process group; neither case proves behavior for external +services or other runtime configurations. The sandbox uses a read-only host +filesystem with a private writable workspace and is for isolated fixtures only. diff --git a/packages/tmux-bridge/test/isolated-pid-namespace.test.py b/packages/tmux-bridge/test/isolated-pid-namespace.test.py index 17e93389..690f8f86 100644 --- a/packages/tmux-bridge/test/isolated-pid-namespace.test.py +++ b/packages/tmux-bridge/test/isolated-pid-namespace.test.py @@ -69,6 +69,22 @@ def test_release_and_stop_own_namespace_with_escaped_fixture(self): if not lease._stopped: lease.stop() + def test_supervisor_death_before_and_after_release(self): + for phase in ('before', 'after'): + with self.subTest(phase=phase), tempfile.TemporaryDirectory() as directory: + root = Path(directory) + escaped, payload, supervisor = root / 'escaped.py', root / 'payload.py', root / 'supervisor.py' + escaped.write_text('import os,pathlib,signal,sys,time\nos.setsid()\nsignal.signal(signal.SIGTERM,signal.SIG_IGN)\npathlib.Path(sys.argv[1]).write_text("started")\ntime.sleep(2)\npathlib.Path(sys.argv[2]).write_text("late")\n') + payload.write_text('import subprocess,sys,time\nsubprocess.Popen([sys.executable,sys.argv[1],sys.argv[2],sys.argv[3]])\nwhile True:time.sleep(1)\n') + supervisor.write_text('import importlib.util,os,pathlib,sys,time\nspec=importlib.util.spec_from_file_location("owned",sys.argv[1]);m=importlib.util.module_from_spec(spec);spec.loader.exec_module(m)\nroot=pathlib.Path(sys.argv[2]);lease=m.IsolatedNamespace.prepare(str(root),[sys.executable,str(root/"payload.py"),str(root/"escaped.py"),str(root/"started"),str(root/"late")])\nif sys.argv[3]=="before":os._exit(0)\nlease.release()\nfor _ in range(500):\n if (root/"started").exists():os._exit(0)\n time.sleep(.01)\nos._exit(2)\n') + result = subprocess.run([sys.executable, '-B', str(supervisor), str(BIN / 'isolated-pid-namespace.py'), directory, phase], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=12) + self.assertEqual(result.returncode, 0) + time.sleep(2.4) + self.assertEqual((root / 'started').exists(), phase == 'after') + self.assertFalse((root / 'late').exists()) + listing = subprocess.run(['ps', '-eo', 'args'], capture_output=True, text=True, check=True).stdout + self.assertNotIn(directory, listing) + def test_unverified_identity_closes_gate_without_running_fixture(self): with tempfile.TemporaryDirectory() as directory: marker = Path(directory) / 'ran' From e143de0185b6b856064424b30d8616e4fb0da0e7 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:56:30 +0000 Subject: [PATCH 079/113] Record uncertain trigger readback outcomes --- .../tmux-bridge/bin/trigger-transaction.mjs | 6 ++- .../tmux-bridge/test/trigger-journal.test.mjs | 47 +++++++++++++++++++ skills/agent-tmux/bin/trigger-transaction.mjs | 6 ++- 3 files changed, 55 insertions(+), 4 deletions(-) diff --git a/packages/tmux-bridge/bin/trigger-transaction.mjs b/packages/tmux-bridge/bin/trigger-transaction.mjs index 1b586d77..af48dd6b 100644 --- a/packages/tmux-bridge/bin/trigger-transaction.mjs +++ b/packages/tmux-bridge/bin/trigger-transaction.mjs @@ -47,13 +47,15 @@ export async function reconcileTriggers({ triggers, from, to, transactionId, ada try { rollback = await adapter.move({ kind: prior.kind, id: prior.id, expectedTarget: to, expectedVersion: prior.after, target: from, operationId: rollbackId }); } catch { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } if (rollback?.status !== 'applied' || !token(rollback.version)) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } - const observed = await adapter.read(prior); + let observed; + try { observed = await adapter.read(prior); } catch { /* The rollback may have applied. */ } if (observed?.target !== from || observed.version !== rollback.version || observed.lastOperationId !== rollbackId) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } prior.status = 'rolled-back'; prior.rollbackVersion = rollback.version; await save(); } receipt.status = 'rolled-back'; await save(); return receipt; } - const observed = await adapter.read(row); + let observed; + try { observed = await adapter.read(row); } catch { /* The move may have applied. */ } if (observed?.target !== to || observed.version !== response.version || observed.lastOperationId !== operationId) { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } row.after = response.version; row.status = 'verified'; await save(); } diff --git a/packages/tmux-bridge/test/trigger-journal.test.mjs b/packages/tmux-bridge/test/trigger-journal.test.mjs index aeae672a..a0a5bbae 100644 --- a/packages/tmux-bridge/test/trigger-journal.test.mjs +++ b/packages/tmux-bridge/test/trigger-journal.test.mjs @@ -129,3 +129,50 @@ test('preflight read failure is durably not-applied and releases the reservation assert.equal(stored.receipt.reason, 'trigger source or version not verified'); await triggerJournal(root).begin({ id: 'second', triggers, dryRun: true }); }); + +test('lost forward readback is durable and can recover the proven move', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-readback-')); + t.after(() => rm(root, { recursive: true, force: true })); + let state = { target: 'codex:old', version: 'v1' }, reads = 0, moves = 0; + const adapter = { + read: async () => { if (++reads === 2) throw new Error('read unavailable'); return structuredClone(state); }, + move: async args => { + moves++; + assert.equal(state.target, args.expectedTarget); assert.equal(state.version, args.expectedVersion); + state = { target: args.target, version: `v${moves + 1}`, lastOperationId: args.operationId }; + return { status: 'applied', version: state.version }; + } + }; + const journal = triggerJournal(root), triggers = [{ kind: 'timer', id: 'one' }]; + const result = await reconcileTriggers({ triggers, from: 'codex:old', to: 'codex:new', transactionId: 'tx', adapter, journal, dryRun: false }); + assert.equal(result.status, 'uncertain'); assert.equal((await triggerJournal(root).get('tx')).status, 'uncertain'); + await assert.rejects(triggerJournal(root).begin({ id: 'other', triggers, dryRun: false }), /overlapping/); + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal: triggerJournal(root) }); + assert.equal(recovered.status, 'rolled-back'); assert.equal(state.target, 'codex:old'); assert.equal(moves, 2); +}); + +test('lost rollback readback stays uncertain until the rollback is observed', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-readback-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = new Map(['one', 'two'].map(id => [id, { target: 'codex:old', version: 'v1' }])); + let failRead = false, moves = 0; + const adapter = { + read: async ({ id }) => { if (failRead) { failRead = false; throw new Error('read unavailable'); } return structuredClone(state.get(id)); }, + move: async args => { + moves++; + if (args.id === 'two') return { status: 'not-applied' }; + const current = state.get(args.id); + assert.equal(current.target, args.expectedTarget); assert.equal(current.version, args.expectedVersion); + const next = { target: args.target, version: `v${moves + 1}`, lastOperationId: args.operationId }; + state.set(args.id, next); + if (args.operationId.includes(':rollback:')) failRead = true; + return { status: 'applied', version: next.version }; + } + }; + const journal = triggerJournal(root), triggers = ['one', 'two'].map(id => ({ kind: 'timer', id })); + const result = await reconcileTriggers({ triggers, from: 'codex:old', to: 'codex:new', transactionId: 'tx', adapter, journal, dryRun: false }); + assert.equal(result.status, 'uncertain'); assert.equal(state.get('one').target, 'codex:old'); + assert.equal((await triggerJournal(root).get('tx')).status, 'uncertain'); + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal: triggerJournal(root) }); + assert.equal(recovered.status, 'rolled-back'); assert.equal(moves, 3); +}); diff --git a/skills/agent-tmux/bin/trigger-transaction.mjs b/skills/agent-tmux/bin/trigger-transaction.mjs index 1b586d77..af48dd6b 100644 --- a/skills/agent-tmux/bin/trigger-transaction.mjs +++ b/skills/agent-tmux/bin/trigger-transaction.mjs @@ -47,13 +47,15 @@ export async function reconcileTriggers({ triggers, from, to, transactionId, ada try { rollback = await adapter.move({ kind: prior.kind, id: prior.id, expectedTarget: to, expectedVersion: prior.after, target: from, operationId: rollbackId }); } catch { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } if (rollback?.status !== 'applied' || !token(rollback.version)) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } - const observed = await adapter.read(prior); + let observed; + try { observed = await adapter.read(prior); } catch { /* The rollback may have applied. */ } if (observed?.target !== from || observed.version !== rollback.version || observed.lastOperationId !== rollbackId) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } prior.status = 'rolled-back'; prior.rollbackVersion = rollback.version; await save(); } receipt.status = 'rolled-back'; await save(); return receipt; } - const observed = await adapter.read(row); + let observed; + try { observed = await adapter.read(row); } catch { /* The move may have applied. */ } if (observed?.target !== to || observed.version !== response.version || observed.lastOperationId !== operationId) { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } row.after = response.version; row.status = 'verified'; await save(); } From 439dc45290dfe7fabc70a1285c0565fe436dfb7a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:05:31 +0000 Subject: [PATCH 080/113] Separate channel switch from predecessor notice --- docs/design/plexus-architecture.mmd | 2 ++ docs/design/plexus-channels.md | 7 ++++ packages/tmux-bridge/bin/agent-waker.py | 2 +- packages/tmux-bridge/bin/channel-state.mjs | 32 +++++++++++++------ packages/tmux-bridge/bin/handover-dry-run.mjs | 8 +++-- .../tmux-bridge/test/channel-state.test.mjs | 31 ++++++++++++------ .../test/handover-dry-run.test.mjs | 2 +- scripts/plexus-diagram.mjs | 2 ++ skills/agent-tmux/bin/agent-waker.py | 2 +- skills/agent-tmux/bin/channel-state.mjs | 32 +++++++++++++------ skills/agent-tmux/bin/handover-dry-run.mjs | 8 +++-- 11 files changed, 90 insertions(+), 38 deletions(-) diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 575aa838..c7c61660 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -24,3 +24,5 @@ flowchart LR 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 diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 745de7f1..90864bd2 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -220,3 +220,10 @@ tests cover abrupt supervisor exit both before and after release, including a child that changes process group; neither case proves behavior for external services or other runtime configurations. The sandbox uses a read-only host filesystem with a private writable workspace and is for isolated fixtures only. + +The pure handover model separates switching to a successor from observing the +messages queued before the switch, then reserving the final notice for the +predecessor. Provider queue acceptance is not recipient observation. The +observation argument is a host-supplied contract, not an authenticated adapter; +no graph operation accepts it or enables live cutover. The rehearsal stops at +the switched-and-awaiting-delivery phase and cannot prove notice finality. diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index d5869764..325ebc22 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -256,7 +256,7 @@ def run_channel(args: argparse.Namespace) -> int: state.pop('inFlight', None) save_state(path, state) channel = channel_call(args, 'get') - if channel.get('phase') != 'active': + if channel.get('phase') not in ('active', 'draining'): print(json.dumps({'job': args.job, 'outcome': 'queued', 'reason': 'handover'})) return 0 if any(item.get('state') == 'inflight' for item in channel['queue']): diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 343d4254..50f5c1e4 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -21,7 +21,7 @@ export function enqueue(state, id, payload) { } export function beginDelivery(state, id, expectedSession, expectedGeneration) { - if (state.phase !== 'active') throw new Error('handover in progress'); + if (!['active', 'draining'].includes(state.phase)) throw new Error('handover in progress'); if (expectedSession !== undefined && state.session !== expectedSession) throw new Error('channel recipient changed'); if (expectedGeneration !== undefined && (!Number.isSafeInteger(expectedGeneration) || expectedGeneration < 1 || state.generation !== expectedGeneration)) throw new Error('channel generation changed'); if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); @@ -94,15 +94,16 @@ export function completeStatePreparation(state, proof) { // The durable reservation survives crashes; only authenticated evidence can // settle it. It does not itself verify the successor or send a notice. export function reserveFinalNotice(state, id, successor, noticeSha256) { - if (state.phase !== 'handover' || state.finalNotice || state.statePreparation?.status !== 'verified' || state.statePreparation.session !== state.session || state.statePreparation.generation !== state.generation || !identifier(id) || !identifier(successor) || successor === state.session || !/^[a-f0-9]{64}$/.test(noticeSha256 || '') || state.queue.some(item => item.state === 'inflight')) throw new Error('final notice reservation unavailable'); + const handover = state.handover; + if (state.phase !== 'draining' || !handover || state.finalNotice || successor !== state.session || handover.successor !== successor || !identifier(id) || !/^[a-f0-9]{64}$/.test(noticeSha256 || '') || handover.backlog.some(id => !state.queue.some(item => item.id === id && item.state === 'observed' && item.session === successor && item.generation === state.generation))) throw new Error('final notice reservation unavailable'); const next = copy(state); - next.finalNotice = { id, session: state.session, generation: state.generation, successor, noticeSha256, status: 'requested' }; + next.finalNotice = { id, session: handover.predecessor, generation: handover.previousGeneration, successor, noticeSha256, status: 'requested' }; return next; } export function recordNoticeQueued(state, receipt) { const pending = state.finalNotice; - if (state.phase !== 'handover' || !pending || pending.status !== 'requested' || pending.session !== state.session || pending.generation !== state.generation || !receipt || receipt.schema !== 'agent-mesh.notice-queue.v1' || receipt.status !== 'queued-unverified' || receipt.session !== pending.session || receipt.nonce !== pending.id || receipt.noticeSha256 !== pending.noticeSha256) throw new Error('notice queue receipt does not match reservation'); + if (state.phase !== 'draining' || !pending || pending.status !== 'requested' || pending.session !== state.handover?.predecessor || pending.generation !== state.handover?.previousGeneration || !receipt || receipt.schema !== 'agent-mesh.notice-queue.v1' || receipt.status !== 'queued-unverified' || receipt.session !== pending.session || receipt.nonce !== pending.id || receipt.noticeSha256 !== pending.noticeSha256) throw new Error('notice queue receipt does not match reservation'); const next = copy(state); next.finalNotice.status = 'queued-unverified'; return next; @@ -112,20 +113,31 @@ export function recordNoticeQueued(state, receipt) { // not exclusive finality and not authorization to finish a handover. export function recordNoticeObservation(state, proof) { const pending = state.finalNotice; - if (state.phase !== 'handover' || !pending || !['requested', 'queued-unverified'].includes(pending.status) || pending.session !== state.session || pending.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.final-notice-observation.v1' || proof.session !== pending.session || proof.nonce !== pending.id || proof.messageSha256 !== pending.noticeSha256 || !/^[a-f0-9]{64}$/.test(proof.transcriptSha256 || '') || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('notice observation does not match reservation'); + if (state.phase !== 'draining' || !pending || !['requested', 'queued-unverified'].includes(pending.status) || pending.session !== state.handover?.predecessor || pending.generation !== state.handover?.previousGeneration || !proof || proof.schema !== 'agent-mesh.final-notice-observation.v1' || proof.session !== pending.session || proof.nonce !== pending.id || proof.messageSha256 !== pending.noticeSha256 || !/^[a-f0-9]{64}$/.test(proof.transcriptSha256 || '') || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('notice observation does not match reservation'); const next = copy(state); next.finalNotice = { ...pending, status: 'observed-snapshot', transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.bytes }; return next; } -export function finishHandover(state, session, verified) { +// These are pure transitions. The host must independently authenticate the successor +// and delivery evidence before applying them; the operational cutover stays disabled. +export function switchHandover(state, session, verified) { if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); - if (state.finalNotice && state.finalNotice.status !== 'verified') throw new Error('final notice unresolved'); - if (state.statePreparation && state.statePreparation.status !== 'verified') throw new Error('state preparation unresolved'); - if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + if (state.finalNotice || state.queue.some(item => item.state === 'inflight')) throw new Error('unresolved inflight delivery or notice'); + if (state.statePreparation?.status !== 'verified' || state.statePreparation.session !== state.session || state.statePreparation.generation !== state.generation) throw new Error('state preparation unresolved'); const next = copy(state); + next.handover = { predecessor: state.session, previousGeneration: state.generation, successor: session, backlog: state.queue.filter(item => item.state === 'pending').map(item => item.id) }; next.session = session; next.generation += 1; - next.phase = 'active'; + next.phase = 'draining'; + return next; +} + +// An accepted provider queue receipt is not proof of recipient observation. +export function observeDelivery(state, id, proof) { + const item = state.queue.find(row => row.id === id); + if (state.phase !== 'draining' || !state.handover?.backlog.includes(id) || !item || item.state !== 'accepted' || item.session !== state.session || item.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.delivery-observation.v1' || proof.messageId !== id || proof.session !== item.session || proof.generation !== item.generation || typeof proof.evidence !== 'string' || !identifier(proof.evidence)) throw new Error('delivery observation does not match backlog'); + const next = copy(state), observed = next.queue.find(row => row.id === id); + observed.state = 'observed'; observed.observation = proof.evidence; return next; } diff --git a/packages/tmux-bridge/bin/handover-dry-run.mjs b/packages/tmux-bridge/bin/handover-dry-run.mjs index f1a5b747..c37ca21b 100644 --- a/packages/tmux-bridge/bin/handover-dry-run.mjs +++ b/packages/tmux-bridge/bin/handover-dry-run.mjs @@ -1,5 +1,5 @@ /** In-memory rehearsal only. No native session, service, timer or graph is changed. */ -import { beginHandover, createChannel, enqueue, finishHandover } from './channel-state.mjs'; +import { beginHandover, createChannel, enqueue, switchHandover, reserveStatePreparation, completeStatePreparation } from './channel-state.mjs'; import { planRoleLaunch, assessRoleLaunch } from './role-launch-profile.mjs'; export async function rehearseHandover({ role, oldSession, newSession, profile, authority, offlineMcp = [], fault = 'none', messageDuringHandover = false }) { @@ -13,6 +13,8 @@ export async function rehearseHandover({ role, oldSession, newSession, profile, channel = { ...channel, phase: 'active' }; return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'rolled-back', reason: fault === 'none' ? launch.reason : fault, channel, launch }; } - channel = finishHandover(channel, newSession, true); - return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'switched', reason: null, channel, launch }; + channel = reserveStatePreparation(channel, 'fixture-state'); + channel = completeStatePreparation(channel, { schema: 'agent-mesh.handover-state.v1', session: oldSession, nonce: 'fixture-state', filename: 'fixture.yaml', sha256: 'a'.repeat(64), bytes: 1 }); + channel = switchHandover(channel, newSession, true); + return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'switched-awaiting-delivery', reason: null, channel, launch }; } diff --git a/packages/tmux-bridge/test/channel-state.test.mjs b/packages/tmux-bridge/test/channel-state.test.mjs index 6be5649d..7cf0a39a 100644 --- a/packages/tmux-bridge/test/channel-state.test.mjs +++ b/packages/tmux-bridge/test/channel-state.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, finishHandover, reserveWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeQueued } from '../bin/channel-state.mjs'; +import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, switchHandover, observeDelivery, reserveWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeQueued } from '../bin/channel-state.mjs'; test('a wake reservation prevents handover and requires exact accepted queue identity', () => { const session = 'codex:22222222-2222-4222-8222-222222222222'; @@ -32,7 +32,7 @@ test('state preparation reserves once and binds proof to the channel generation' let channel = beginHandover(createChannel('example', 'codex:old')); channel = reserveStatePreparation(channel, 'handover-1'); assert.throws(() => reserveStatePreparation(channel, 'handover-2'), /unresolved/); - assert.throws(() => finishHandover(channel, 'codex:new', true), /unresolved/); + assert.throws(() => switchHandover(channel, 'codex:new', true), /unresolved/); channel = enqueue(channel, 'queued', 'fixture'); const proof = { schema: 'agent-mesh.handover-state.v1', session: 'codex:old', nonce: 'handover-1', filename: 'state.yaml', sha256: 'a'.repeat(64), bytes: 42 }; assert.throws(() => completeStatePreparation(channel, { ...proof, nonce: 'other' }), /invalid/); @@ -56,11 +56,13 @@ test('handover queues work and never reroutes an uncertain delivery', () => { channel = beginHandover(channel); channel = enqueue(channel, 'message-2', 'queued'); assert.throws(() => beginDelivery(channel, 'message-2'), /handover/); - assert.throws(() => finishHandover(channel, 'session:two', true), /inflight/); + assert.throws(() => switchHandover(channel, 'session:two', true), /inflight/); assert.throws(() => acknowledge(channel, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'session:two', generation: 1 }), /receipt/); channel = acknowledge(channel, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'session:one', generation: 1 }); - assert.throws(() => finishHandover(channel, 'session:two', false), /successor/); - channel = finishHandover(channel, 'session:two', true); + assert.throws(() => switchHandover(channel, 'session:two', false), /successor/); + channel = reserveStatePreparation(channel, 'state-1'); + channel = completeStatePreparation(channel, { schema: 'agent-mesh.handover-state.v1', session: 'session:one', nonce: 'state-1', filename: 'state.yaml', sha256: 'a'.repeat(64), bytes: 1 }); + channel = switchHandover(channel, 'session:two', true); channel = beginDelivery(channel, 'message-0'); assert.equal(channel.queue[1].session, 'session:two'); assert.equal(channel.queue[1].generation, 2); @@ -68,16 +70,27 @@ test('handover queues work and never reroutes an uncertain delivery', () => { assert.throws(() => enqueue(channel, 'message-2', 'different'), /conflict/); }); -test('final notice reservation binds the queue receipt and blocks cutover', () => { +test('switch drains observed backlog before reserving a predecessor notice', () => { let state = beginHandover(createChannel('example', 'codex:old')); - assert.throws(() => reserveFinalNotice(state, 'handover-1', 'codex:new', 'a'.repeat(64)), /unavailable/); + state = enqueue(state, 'message-1', 'fixture'); + assert.throws(() => switchHandover(state, 'codex:new', true), /state preparation/); state = reserveStatePreparation(state, 'state-1'); state = completeStatePreparation(state, { schema: 'agent-mesh.handover-state.v1', session: 'codex:old', nonce: 'state-1', filename: 'state.yaml', sha256: 'b'.repeat(64), bytes: 2 }); + state = switchHandover(state, 'codex:new', true); + assert.equal(state.phase, 'draining'); assert.equal(state.handover.predecessor, 'codex:old'); + assert.throws(() => reserveFinalNotice(state, 'handover-1', 'codex:new', 'a'.repeat(64)), /unavailable/); + state = beginDelivery(state, 'message-1'); + state = acknowledge(state, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'codex:new', generation: 2 }); + assert.throws(() => reserveFinalNotice(state, 'handover-1', 'codex:new', 'a'.repeat(64)), /unavailable/); + const proof = { schema: 'agent-mesh.delivery-observation.v1', messageId: 'message-1', session: 'codex:new', generation: 2, evidence: 'fixture-proof' }; + assert.throws(() => observeDelivery(state, 'message-1', { ...proof, session: 'codex:old' }), /observation/); + state = observeDelivery(state, 'message-1', proof); + assert.throws(() => reserveFinalNotice(state, 'handover-1', 'codex:other', 'a'.repeat(64)), /unavailable/); state = reserveFinalNotice(state, 'handover-1', 'codex:new', 'a'.repeat(64)); - assert.throws(() => reserveFinalNotice(state, 'handover-2', 'codex:new', 'a'.repeat(64)), /unavailable/); + assert.equal(state.finalNotice.session, 'codex:old'); assert.equal(state.finalNotice.generation, 1); const receipt = { schema: 'agent-mesh.notice-queue.v1', status: 'queued-unverified', session: 'codex:old', nonce: 'handover-1', noticeSha256: 'a'.repeat(64) }; assert.throws(() => recordNoticeQueued(state, { ...receipt, nonce: 'other' }), /reservation/); state = recordNoticeQueued(state, receipt); assert.equal(state.finalNotice.status, 'queued-unverified'); - assert.throws(() => finishHandover(state, 'codex:new', true), /final notice unresolved/); + assert.equal(state.phase, 'draining'); }); diff --git a/packages/tmux-bridge/test/handover-dry-run.test.mjs b/packages/tmux-bridge/test/handover-dry-run.test.mjs index 0b20cfb1..0cea9a82 100644 --- a/packages/tmux-bridge/test/handover-dry-run.test.mjs +++ b/packages/tmux-bridge/test/handover-dry-run.test.mjs @@ -9,7 +9,7 @@ test('two synthetic roles preserve messages and rollback on isolated faults', as const fixture = role(name); const offline = await rehearseHandover({ ...fixture, offlineMcp: ['optional'], messageDuringHandover: true }); assert.equal(offline.simulated, true); - assert.equal(offline.outcome, 'switched'); + assert.equal(offline.outcome, 'switched-awaiting-delivery'); assert.equal(offline.channel.session, fixture.newSession); assert.equal(offline.channel.queue[0].state, 'pending'); assert.equal(offline.launch.mcpStarted, 1); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 5ff41fd8..22baa075 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -25,4 +25,6 @@ export const plexusDiagram = `flowchart LR 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 `; diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index d5869764..325ebc22 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -256,7 +256,7 @@ def run_channel(args: argparse.Namespace) -> int: state.pop('inFlight', None) save_state(path, state) channel = channel_call(args, 'get') - if channel.get('phase') != 'active': + if channel.get('phase') not in ('active', 'draining'): print(json.dumps({'job': args.job, 'outcome': 'queued', 'reason': 'handover'})) return 0 if any(item.get('state') == 'inflight' for item in channel['queue']): diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 343d4254..50f5c1e4 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -21,7 +21,7 @@ export function enqueue(state, id, payload) { } export function beginDelivery(state, id, expectedSession, expectedGeneration) { - if (state.phase !== 'active') throw new Error('handover in progress'); + if (!['active', 'draining'].includes(state.phase)) throw new Error('handover in progress'); if (expectedSession !== undefined && state.session !== expectedSession) throw new Error('channel recipient changed'); if (expectedGeneration !== undefined && (!Number.isSafeInteger(expectedGeneration) || expectedGeneration < 1 || state.generation !== expectedGeneration)) throw new Error('channel generation changed'); if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); @@ -94,15 +94,16 @@ export function completeStatePreparation(state, proof) { // The durable reservation survives crashes; only authenticated evidence can // settle it. It does not itself verify the successor or send a notice. export function reserveFinalNotice(state, id, successor, noticeSha256) { - if (state.phase !== 'handover' || state.finalNotice || state.statePreparation?.status !== 'verified' || state.statePreparation.session !== state.session || state.statePreparation.generation !== state.generation || !identifier(id) || !identifier(successor) || successor === state.session || !/^[a-f0-9]{64}$/.test(noticeSha256 || '') || state.queue.some(item => item.state === 'inflight')) throw new Error('final notice reservation unavailable'); + const handover = state.handover; + if (state.phase !== 'draining' || !handover || state.finalNotice || successor !== state.session || handover.successor !== successor || !identifier(id) || !/^[a-f0-9]{64}$/.test(noticeSha256 || '') || handover.backlog.some(id => !state.queue.some(item => item.id === id && item.state === 'observed' && item.session === successor && item.generation === state.generation))) throw new Error('final notice reservation unavailable'); const next = copy(state); - next.finalNotice = { id, session: state.session, generation: state.generation, successor, noticeSha256, status: 'requested' }; + next.finalNotice = { id, session: handover.predecessor, generation: handover.previousGeneration, successor, noticeSha256, status: 'requested' }; return next; } export function recordNoticeQueued(state, receipt) { const pending = state.finalNotice; - if (state.phase !== 'handover' || !pending || pending.status !== 'requested' || pending.session !== state.session || pending.generation !== state.generation || !receipt || receipt.schema !== 'agent-mesh.notice-queue.v1' || receipt.status !== 'queued-unverified' || receipt.session !== pending.session || receipt.nonce !== pending.id || receipt.noticeSha256 !== pending.noticeSha256) throw new Error('notice queue receipt does not match reservation'); + if (state.phase !== 'draining' || !pending || pending.status !== 'requested' || pending.session !== state.handover?.predecessor || pending.generation !== state.handover?.previousGeneration || !receipt || receipt.schema !== 'agent-mesh.notice-queue.v1' || receipt.status !== 'queued-unverified' || receipt.session !== pending.session || receipt.nonce !== pending.id || receipt.noticeSha256 !== pending.noticeSha256) throw new Error('notice queue receipt does not match reservation'); const next = copy(state); next.finalNotice.status = 'queued-unverified'; return next; @@ -112,20 +113,31 @@ export function recordNoticeQueued(state, receipt) { // not exclusive finality and not authorization to finish a handover. export function recordNoticeObservation(state, proof) { const pending = state.finalNotice; - if (state.phase !== 'handover' || !pending || !['requested', 'queued-unverified'].includes(pending.status) || pending.session !== state.session || pending.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.final-notice-observation.v1' || proof.session !== pending.session || proof.nonce !== pending.id || proof.messageSha256 !== pending.noticeSha256 || !/^[a-f0-9]{64}$/.test(proof.transcriptSha256 || '') || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('notice observation does not match reservation'); + if (state.phase !== 'draining' || !pending || !['requested', 'queued-unverified'].includes(pending.status) || pending.session !== state.handover?.predecessor || pending.generation !== state.handover?.previousGeneration || !proof || proof.schema !== 'agent-mesh.final-notice-observation.v1' || proof.session !== pending.session || proof.nonce !== pending.id || proof.messageSha256 !== pending.noticeSha256 || !/^[a-f0-9]{64}$/.test(proof.transcriptSha256 || '') || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('notice observation does not match reservation'); const next = copy(state); next.finalNotice = { ...pending, status: 'observed-snapshot', transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.bytes }; return next; } -export function finishHandover(state, session, verified) { +// These are pure transitions. The host must independently authenticate the successor +// and delivery evidence before applying them; the operational cutover stays disabled. +export function switchHandover(state, session, verified) { if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); - if (state.finalNotice && state.finalNotice.status !== 'verified') throw new Error('final notice unresolved'); - if (state.statePreparation && state.statePreparation.status !== 'verified') throw new Error('state preparation unresolved'); - if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + if (state.finalNotice || state.queue.some(item => item.state === 'inflight')) throw new Error('unresolved inflight delivery or notice'); + if (state.statePreparation?.status !== 'verified' || state.statePreparation.session !== state.session || state.statePreparation.generation !== state.generation) throw new Error('state preparation unresolved'); const next = copy(state); + next.handover = { predecessor: state.session, previousGeneration: state.generation, successor: session, backlog: state.queue.filter(item => item.state === 'pending').map(item => item.id) }; next.session = session; next.generation += 1; - next.phase = 'active'; + next.phase = 'draining'; + return next; +} + +// An accepted provider queue receipt is not proof of recipient observation. +export function observeDelivery(state, id, proof) { + const item = state.queue.find(row => row.id === id); + if (state.phase !== 'draining' || !state.handover?.backlog.includes(id) || !item || item.state !== 'accepted' || item.session !== state.session || item.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.delivery-observation.v1' || proof.messageId !== id || proof.session !== item.session || proof.generation !== item.generation || typeof proof.evidence !== 'string' || !identifier(proof.evidence)) throw new Error('delivery observation does not match backlog'); + const next = copy(state), observed = next.queue.find(row => row.id === id); + observed.state = 'observed'; observed.observation = proof.evidence; return next; } diff --git a/skills/agent-tmux/bin/handover-dry-run.mjs b/skills/agent-tmux/bin/handover-dry-run.mjs index f1a5b747..c37ca21b 100644 --- a/skills/agent-tmux/bin/handover-dry-run.mjs +++ b/skills/agent-tmux/bin/handover-dry-run.mjs @@ -1,5 +1,5 @@ /** In-memory rehearsal only. No native session, service, timer or graph is changed. */ -import { beginHandover, createChannel, enqueue, finishHandover } from './channel-state.mjs'; +import { beginHandover, createChannel, enqueue, switchHandover, reserveStatePreparation, completeStatePreparation } from './channel-state.mjs'; import { planRoleLaunch, assessRoleLaunch } from './role-launch-profile.mjs'; export async function rehearseHandover({ role, oldSession, newSession, profile, authority, offlineMcp = [], fault = 'none', messageDuringHandover = false }) { @@ -13,6 +13,8 @@ export async function rehearseHandover({ role, oldSession, newSession, profile, channel = { ...channel, phase: 'active' }; return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'rolled-back', reason: fault === 'none' ? launch.reason : fault, channel, launch }; } - channel = finishHandover(channel, newSession, true); - return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'switched', reason: null, channel, launch }; + channel = reserveStatePreparation(channel, 'fixture-state'); + channel = completeStatePreparation(channel, { schema: 'agent-mesh.handover-state.v1', session: oldSession, nonce: 'fixture-state', filename: 'fixture.yaml', sha256: 'a'.repeat(64), bytes: 1 }); + channel = switchHandover(channel, newSession, true); + return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'switched-awaiting-delivery', reason: null, channel, launch }; } From e267497ebf79eac2388d91792df94496b78b4c12 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:11:18 +0000 Subject: [PATCH 081/113] Bind wake readback to channel backlog --- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-channels.md | 7 ++++++ packages/tmux-bridge/bin/channel-state.mjs | 8 +++++-- .../tmux-bridge/bin/codex-wake-evidence.mjs | 13 +++++++---- .../tmux-bridge/test/channel-state.test.mjs | 22 ++++++++++++++++++- .../test/codex-wake-evidence.test.mjs | 12 ++++++++-- scripts/plexus-diagram.mjs | 1 + skills/agent-tmux/bin/channel-state.mjs | 8 +++++-- skills/agent-tmux/bin/codex-wake-evidence.mjs | 13 +++++++---- 9 files changed, 70 insertions(+), 15 deletions(-) diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index c7c61660..4111471d 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -26,3 +26,4 @@ flowchart LR Handover["Handover"] -. "planned verified cutover" .-> Channel Channel -. "pure switch model" .-> Drain["Observe queued deliveries"] Drain -. "then reserve" .-> Notice + Wake -. "bound native proof" .-> Drain diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 90864bd2..673bc16f 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -227,3 +227,10 @@ predecessor. Provider queue acceptance is not recipient observation. The observation argument is a host-supplied contract, not an authenticated adapter; no graph operation accepts it or enables live cutover. The rehearsal stops at the switched-and-awaiting-delivery phase and cannot prove notice finality. + +A new Codex wake proof binds the native queued payload to the channel, +generation, queue ID and correlation before starting it, then reads back the +exact native message. When this proof is verified and settled in a draining +channel, it marks that backlog message observed. Older proof schemas remain +valid wake evidence but cannot establish this stronger delivery binding. +This is not a cloud or Claude delivery adapter; native cutover remains disabled. diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 50f5c1e4..f7ae3356 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -1,4 +1,5 @@ /** Pure channel transitions. A host must persist each transition atomically. */ +import { createHash } from 'node:crypto'; const identifier = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); const channelIdentifier = (value) => typeof value === 'string' && /^#?[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); const copy = (state) => structuredClone(state); @@ -56,7 +57,7 @@ export function beginHandover(state) { // A reservation is durable and has no expiry: a crashed native call is unknown. export function reserveWake(state, id, session, generation, nativeQueueId) { - if (state.phase !== 'active' || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); + if (!['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && !item.wakeEvidence && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); const next = copy(state); @@ -66,10 +67,13 @@ export function reserveWake(state, id, session, generation, nativeQueueId) { export function settleWake(state, proof) { const reservation = state.wakeReservation; - if (!reservation || state.phase !== 'active' || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + if (!reservation || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); if (!item) throw new Error('wake item unavailable'); item.wakeEvidence = proof.evidence; + if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && proof.schema === 'agent-mesh.codex-wake-evidence.v4' && proof.source === 'codex-app-server.queue-start-bound-readback' && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { + item.state = 'observed'; item.observation = proof.evidence; + } delete next.wakeReservation; return next; } diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index 39ceb3ae..612a97cd 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -82,7 +82,9 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); let value; try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } - if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || !((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && ((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')); + const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && value.source === 'codex-app-server.queue-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); + if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } @@ -120,8 +122,12 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge if (!Array.isArray(listed?.data) || listed.nextCursor != null || listed.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length !== 1) throw new Error('queued waker identity unavailable'); const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); if (reserved.error || reserved.status !== 0) throw new Error('wake reservation unavailable or uncertain'); - let reservation; try { reservation = JSON.parse(reserved.stdout)?.channel?.wakeReservation; } catch { throw new Error('wake reservation receipt unavailable'); } + let reservedChannel; try { reservedChannel = JSON.parse(reserved.stdout)?.channel; } catch { throw new Error('wake reservation receipt unavailable'); } + const reservation = reservedChannel?.wakeReservation; if (!reservation || reservation.id !== correlation || reservation.session !== session || reservation.generation !== generation || reservation.nativeQueueId !== queueId) throw new Error('wake reservation receipt mismatch'); + const queued = listed.data.find(item => item?.id === queueId && item.clientUserMessageId === correlation); + const boundItems = Array.isArray(reservedChannel.queue) ? reservedChannel.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string') : []; + if (reservedChannel.id !== channel || reservedChannel.session !== session || reservedChannel.generation !== generation || boundItems.length !== 1 || JSON.stringify(queued.input) !== JSON.stringify([{ type: 'text', text: boundItems[0].payload, text_elements: [] }])) throw new Error('native queue payload does not match channel reservation'); await createDurable(evidenceRoot, `intent-${intent}.json`, `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`); const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); const turn = started?.turn; @@ -131,9 +137,8 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge const turns = Array.isArray(observed?.turns) ? observed.turns.filter(item => item?.id === turn.id) : []; const observedTurn = turns[0]; const messages = Array.isArray(observedTurn?.items) ? observedTurn.items.filter(item => item?.type === 'userMessage' && item.clientId === correlation) : []; - const queued = listed.data.find(item => item?.id === queueId && item.clientUserMessageId === correlation); if (observed?.id !== thread || turns.length !== 1 || (observedTurn.itemsView !== undefined && observedTurn.itemsView !== 'full') || observedTurn.startedAt !== turn.startedAt || messages.length !== 1 || !Array.isArray(messages[0].content) || JSON.stringify(messages[0].content) !== JSON.stringify(queued.input)) throw new Error('wake readback unavailable; outcome uncertain'); - return { schema: 'agent-mesh.codex-wake-evidence.v2', source: 'codex-app-server.queue-start-readback', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt }; + return { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.queue-start-bound-readback', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt, channel, generation, payloadSha256: hash(boundItems[0].payload) }; }); const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); diff --git a/packages/tmux-bridge/test/channel-state.test.mjs b/packages/tmux-bridge/test/channel-state.test.mjs index 7cf0a39a..834f3e28 100644 --- a/packages/tmux-bridge/test/channel-state.test.mjs +++ b/packages/tmux-bridge/test/channel-state.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, switchHandover, observeDelivery, reserveWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeQueued } from '../bin/channel-state.mjs'; +import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, switchHandover, observeDelivery, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeQueued } from '../bin/channel-state.mjs'; test('a wake reservation prevents handover and requires exact accepted queue identity', () => { const session = 'codex:22222222-2222-4222-8222-222222222222'; @@ -94,3 +94,23 @@ test('switch drains observed backlog before reserving a predecessor notice', () assert.equal(state.finalNotice.status, 'queued-unverified'); assert.equal(state.phase, 'draining'); }); + + +test('bound native wake evidence observes only its exact draining backlog', async () => { + const { createHash } = await import('node:crypto'); + let state = beginHandover(createChannel('example', 'codex:old')); + state = enqueue(state, 'message-1', 'fixture'); + state = reserveStatePreparation(state, 'state-1'); + state = completeStatePreparation(state, { schema: 'agent-mesh.handover-state.v1', session: 'codex:old', nonce: 'state-1', filename: 'state.yaml', sha256: 'b'.repeat(64), bytes: 2 }); + state = switchHandover(state, 'codex:new', true); + state = beginDelivery(state, 'message-1'); + state = acknowledge(state, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'codex:new', generation: 2, nativeQueueId: 'queue-1' }); + state = reserveWake(state, 'message-1', 'codex:new', 2, 'queue-1'); + const proof = { session: 'codex:new', correlation: 'message-1', queueId: 'queue-1', evidence: `codex-wake:${'a'.repeat(64)}`, schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.queue-start-bound-readback', channel: 'example', generation: 2, payloadSha256: createHash('sha256').update('fixture').digest('hex') }; + const mismatch = settleWake(state, { ...proof, channel: 'other' }); + assert.equal(mismatch.queue[0].state, 'accepted'); + assert.throws(() => reserveFinalNotice(mismatch, 'notice', 'codex:new', 'a'.repeat(64)), /unavailable/); + state = settleWake(state, proof); + assert.equal(state.queue[0].state, 'observed'); + assert.equal(reserveFinalNotice(state, 'notice', 'codex:new', 'a'.repeat(64)).finalNotice.session, 'codex:old'); +}); diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 0bc28aaa..9ddb3169 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -37,7 +37,7 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const server = createAppServer((request, peer) => { if (!request.id) return; requests.push(request); - if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: 'fixture', text_elements: [] }] }], nextCursor: null } }); + if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: mode === 'wrong-queue-payload' ? 'different' : 'fixture', text_elements: [] }] }], nextCursor: null } }); else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: 123456789, items: [] } } }); else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, status: 'completed', startedAt: mode === 'wrong-time' ? 123456788 : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture', text_elements: [] }] }] }] } } }); else peer.send({ id: request.id, result: {} }); @@ -54,7 +54,13 @@ test('queued wake needs explicit apply, a native start and durable correlated pr assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 0); mode = 'wrong'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); assert.deepEqual(await readdir(evidence), []); - mode = 'success'; + nativeId = 'queued-payload'; await prepareChannel('payload', nativeId); + mode = 'wrong-queue-payload'; + await assert.rejects(exec(process.execPath, [bin, '--apply', '--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'payload', '--generation', '1', '--evidence-root', evidence, '--graph-state', state], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 0); + assert.equal((await call('channel', 'get', '--name', 'payload')).channel.wakeReservation.nativeQueueId, nativeId); + assert.deepEqual(await readdir(evidence), []); + nativeId = 'queued-1'; mode = 'success'; const first = JSON.parse((await exec(process.execPath, [bin, '--apply', ...args], { env })).stdout); assert.equal(first.duplicate, false); const success = (await call('channel', 'get', '--name', 'success')).channel; @@ -64,6 +70,8 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const verified = await verifyCodexWakeEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }); assert.equal(verified.turn, turn); assert.equal(verified.correlation, correlation); + assert.equal(verified.schema, 'agent-mesh.codex-wake-evidence.v4'); + assert.equal(verified.channel, 'success'); assert.equal(verified.generation, 1); assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 1); await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 1); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 22baa075..676ffae2 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -27,4 +27,5 @@ export const plexusDiagram = `flowchart LR Handover["Handover"] -. "planned verified cutover" .-> Channel Channel -. "pure switch model" .-> Drain["Observe queued deliveries"] Drain -. "then reserve" .-> Notice + Wake -. "bound native proof" .-> Drain `; diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 50f5c1e4..f7ae3356 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -1,4 +1,5 @@ /** Pure channel transitions. A host must persist each transition atomically. */ +import { createHash } from 'node:crypto'; const identifier = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); const channelIdentifier = (value) => typeof value === 'string' && /^#?[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); const copy = (state) => structuredClone(state); @@ -56,7 +57,7 @@ export function beginHandover(state) { // A reservation is durable and has no expiry: a crashed native call is unknown. export function reserveWake(state, id, session, generation, nativeQueueId) { - if (state.phase !== 'active' || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); + if (!['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && !item.wakeEvidence && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); const next = copy(state); @@ -66,10 +67,13 @@ export function reserveWake(state, id, session, generation, nativeQueueId) { export function settleWake(state, proof) { const reservation = state.wakeReservation; - if (!reservation || state.phase !== 'active' || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + if (!reservation || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); if (!item) throw new Error('wake item unavailable'); item.wakeEvidence = proof.evidence; + if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && proof.schema === 'agent-mesh.codex-wake-evidence.v4' && proof.source === 'codex-app-server.queue-start-bound-readback' && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { + item.state = 'observed'; item.observation = proof.evidence; + } delete next.wakeReservation; return next; } diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index 39ceb3ae..612a97cd 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -82,7 +82,9 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); let value; try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } - if (!value || Object.keys(value).sort().join(',') !== 'correlation,queueId,schema,session,source,startedAt,turn' || `${JSON.stringify(value)}\n` !== body || !((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && ((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')); + const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && value.source === 'codex-app-server.queue-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); + if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } @@ -120,8 +122,12 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge if (!Array.isArray(listed?.data) || listed.nextCursor != null || listed.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length !== 1) throw new Error('queued waker identity unavailable'); const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); if (reserved.error || reserved.status !== 0) throw new Error('wake reservation unavailable or uncertain'); - let reservation; try { reservation = JSON.parse(reserved.stdout)?.channel?.wakeReservation; } catch { throw new Error('wake reservation receipt unavailable'); } + let reservedChannel; try { reservedChannel = JSON.parse(reserved.stdout)?.channel; } catch { throw new Error('wake reservation receipt unavailable'); } + const reservation = reservedChannel?.wakeReservation; if (!reservation || reservation.id !== correlation || reservation.session !== session || reservation.generation !== generation || reservation.nativeQueueId !== queueId) throw new Error('wake reservation receipt mismatch'); + const queued = listed.data.find(item => item?.id === queueId && item.clientUserMessageId === correlation); + const boundItems = Array.isArray(reservedChannel.queue) ? reservedChannel.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string') : []; + if (reservedChannel.id !== channel || reservedChannel.session !== session || reservedChannel.generation !== generation || boundItems.length !== 1 || JSON.stringify(queued.input) !== JSON.stringify([{ type: 'text', text: boundItems[0].payload, text_elements: [] }])) throw new Error('native queue payload does not match channel reservation'); await createDurable(evidenceRoot, `intent-${intent}.json`, `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`); const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); const turn = started?.turn; @@ -131,9 +137,8 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge const turns = Array.isArray(observed?.turns) ? observed.turns.filter(item => item?.id === turn.id) : []; const observedTurn = turns[0]; const messages = Array.isArray(observedTurn?.items) ? observedTurn.items.filter(item => item?.type === 'userMessage' && item.clientId === correlation) : []; - const queued = listed.data.find(item => item?.id === queueId && item.clientUserMessageId === correlation); if (observed?.id !== thread || turns.length !== 1 || (observedTurn.itemsView !== undefined && observedTurn.itemsView !== 'full') || observedTurn.startedAt !== turn.startedAt || messages.length !== 1 || !Array.isArray(messages[0].content) || JSON.stringify(messages[0].content) !== JSON.stringify(queued.input)) throw new Error('wake readback unavailable; outcome uncertain'); - return { schema: 'agent-mesh.codex-wake-evidence.v2', source: 'codex-app-server.queue-start-readback', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt }; + return { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.queue-start-bound-readback', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt, channel, generation, payloadSha256: hash(boundItems[0].payload) }; }); const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); From ed286b135d12d5b49be91bce2a2ba5b9d68a7c61 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:17:23 +0000 Subject: [PATCH 082/113] Test notice reservation after channel draining --- .../tmux-bridge/test/plexus-channel-store.test.mjs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index f4d9df20..afeac546 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -121,7 +121,7 @@ test('delivery reservation and matching receipt survive graph replay', async (t) assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'accepted'); }); -test('final notice reservation persists and refuses a duplicate before any send', async t => { +test('predecessor notice after a synthetic draining transition persists across replay', async t => { const state = await mkdtemp(join(tmpdir(), 'notice-reserve-')); t.after(() => rm(state, { recursive: true, force: true })); const writer = join(state, 'writer.mjs'), sessions = join(state, 'sessions'), oldId = '22222222-2222-4222-8222-222222222222', nextId = '33333333-3333-4333-8333-333333333333'; @@ -143,6 +143,14 @@ test('final notice reservation persists and refuses a duplicate before any send' const channel = graph.channels.find(row => row.id === 'example'); channel.statePreparation = { status: 'verified', session: `codex:${oldId}`, generation: channel.generation, id: 'state-1', filename: 'state.yaml', sha256: 'b'.repeat(64), bytes: 2 }; await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-state', type: 'channel.updated', at: new Date().toISOString(), channel, seq: graph.lastSeq + 1, host: 'local' })}\n`); + // The operational cutover is disabled. Inject only a synthetic graph event to + // exercise the following durable state; this is not a native cutover proof. + await assert.rejects(call(...args), /reservation unavailable/); + graph = await call('show', '--json'); + const draining = graph.channels.find(row => row.id === 'example'); + draining.handover = { predecessor: `codex:${oldId}`, previousGeneration: 1, successor: `codex:${nextId}`, backlog: [] }; + draining.session = `codex:${nextId}`; draining.generation = 2; draining.phase = 'draining'; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-draining', type: 'channel.updated', at: new Date().toISOString(), channel: draining, seq: graph.lastSeq + 1, host: 'local' })}\n`); const first = (await call(...args)).channel.finalNotice; assert.equal(first.status, 'requested'); assert.equal(first.successor, `codex:${nextId}`); From f7ca30ff63afede7eb07675108a1ec226bfec483 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:24:06 +0000 Subject: [PATCH 083/113] Observe local Claude delivery in transcript --- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-channels.md | 7 +++ .../bin/claude-delivery-observation.mjs | 53 +++++++++++++++++++ packages/tmux-bridge/bin/mesh-graph.mjs | 24 ++++++++- .../test/claude-delivery-observation.test.mjs | 31 +++++++++++ .../test/plexus-channel-store.test.mjs | 27 ++++++++++ scripts/mesh-readiness.mjs | 1 + scripts/plexus-diagram.mjs | 1 + scripts/plexus-privacy.mjs | 2 +- .../bin/claude-delivery-observation.mjs | 53 +++++++++++++++++++ skills/agent-tmux/bin/mesh-graph.mjs | 24 ++++++++- 11 files changed, 219 insertions(+), 5 deletions(-) create mode 100644 packages/tmux-bridge/bin/claude-delivery-observation.mjs create mode 100644 packages/tmux-bridge/test/claude-delivery-observation.test.mjs create mode 100644 skills/agent-tmux/bin/claude-delivery-observation.mjs diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 4111471d..1da27b6f 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -27,3 +27,4 @@ flowchart LR Channel -. "pure switch model" .-> Drain["Observe queued deliveries"] Drain -. "then reserve" .-> Notice Wake -. "bound native proof" .-> Drain + ClaudeReadback["Local Claude transcript observer"] -. "observed inbox record" .-> Drain diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 673bc16f..f9f2592d 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -234,3 +234,10 @@ exact native message. When this proof is verified and settled in a draining channel, it marks that backlog message observed. Older proof schemas remain valid wake evidence but cannot establish this stronger delivery binding. This is not a cloud or Claude delivery adapter; native cutover remains disabled. + +For a draining local Claude channel, `observe-claude-delivery` checks one +managed inbox record in a stable local user transcript snapshot, binding its +correlation, payload, session and generation before marking the backlog item +observed. An enqueue-only record is insufficient. This source does not prove +execution, attention, finality or cloud delivery; its real transport transcript +shape still requires isolated qualification. Operational cutover remains disabled. diff --git a/packages/tmux-bridge/bin/claude-delivery-observation.mjs b/packages/tmux-bridge/bin/claude-delivery-observation.mjs new file mode 100644 index 00000000..7cff511c --- /dev/null +++ b/packages/tmux-bridge/bin/claude-delivery-observation.mjs @@ -0,0 +1,53 @@ +/** Read-only observation of one managed inbox record in a local Claude transcript. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = data => createHash('sha256').update(data).digest('hex'); + +export async function observeClaudeDelivery({ root, session, generation, messageId, payload }) { + if (typeof root !== 'string' || !isAbsolute(root) || typeof session !== 'string' || !session.startsWith('claude:') || !UUID.test(session.slice(7)) || !Number.isSafeInteger(generation) || generation < 1 || typeof messageId !== 'string' || !TOKEN.test(messageId) || typeof payload !== 'string' || !payload || Buffer.byteLength(payload) > 65536) throw new Error('invalid delivery observation request'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || directory.uid !== process.getuid() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const matches = entries.filter(entry => entry.isFile() && entry.name.toLowerCase() === `${session.slice(7).toLowerCase()}.jsonl`).map(entry => join(entry.parentPath, entry.name)); + if (matches.length !== 1 || await realpath(matches[0]) !== matches[0]) throw new Error('transcript identity unavailable or ambiguous'); + const path = matches[0], file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > 128 * 1024 * 1024) throw new Error('invalid transcript file'); + bytes = await file.readFile(); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + } finally { await file.close(); } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let found = 0; + for (const line of text.split('\n')) { + if (!line) continue; + let record; try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + if (record.type !== 'user' || record.isSidechain || record.isMeta) continue; + if (record.sessionId !== session.slice(7)) throw new Error('transcript session mismatch'); + const content = record.message?.content; + const parts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text) : []; + for (const part of parts) for (const entry of part.split('\n')) { + if (!entry.startsWith('AGENT_MESH_INBOX ')) continue; + let inbox; try { inbox = JSON.parse(entry.slice('AGENT_MESH_INBOX '.length)); } catch { throw new Error('invalid inbox record'); } + if (inbox?.deliveryId === messageId || inbox?.meshId === messageId) { + if (inbox.schema !== 'agent-mesh.monitor-inbox.v1' || inbox.deliveryId !== messageId || inbox.meshId !== messageId || inbox.prompt !== payload) throw new Error('inbox correlation mismatch'); + found++; + } + } + } + if (found !== 1) throw new Error('delivery not uniquely observed'); + const payloadSha256 = hash(payload), transcriptSha256 = hash(bytes); + const evidence = `claude-transcript:${hash(JSON.stringify([session, generation, messageId, payloadSha256, transcriptSha256]))}`; + return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, evidence }; +} diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 27fa1a9d..e7b93d8b 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -37,7 +37,8 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, observeDelivery, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; +import { observeClaudeDelivery } from "./claude-delivery-observation.mjs"; import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; import { formatFinalNotice } from "./handover-notice.mjs"; @@ -132,7 +133,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -154,6 +155,25 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "observe-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const pending = channel?.queue?.filter(item => item.id === id && item.state === "accepted" && item.session === channel.session && item.generation === channel.generation); + if (channel?.phase !== "draining" || !channel.handover?.backlog?.includes(id) || pending?.length !== 1 || !channel.session.startsWith("claude:")) throw new Error("Claude delivery observation unavailable"); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeClaudeDelivery({ root, session: channel.session, generation: channel.generation, messageId: id, payload: pending[0].payload }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + const item = current?.queue?.find(row => row.id === id); + if (!item || typeof item.payload !== "string" || createHash("sha256").update(item.payload).digest("hex") !== proof.payloadSha256) throw new Error("delivery changed during observation"); + const next = observeDelivery(current, id, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: "observed" } }; + }); + printResult(result, { json: true }); + break; + } if (subcommand === "observe-notice") { const content = JSON.parse(requiredSingleLine(channelInput, "--input")); if (!content || typeof content !== "object" || Array.isArray(content) || Object.keys(content).sort().join(",") !== "label,prefix") throw new Error("invalid notice content"); diff --git a/packages/tmux-bridge/test/claude-delivery-observation.test.mjs b/packages/tmux-bridge/test/claude-delivery-observation.test.mjs new file mode 100644 index 00000000..d50a3198 --- /dev/null +++ b/packages/tmux-bridge/test/claude-delivery-observation.test.mjs @@ -0,0 +1,31 @@ +import assert from 'node:assert/strict'; +import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import test from 'node:test'; +import { observeClaudeDelivery } from '../bin/claude-delivery-observation.mjs'; + +const id = '22222222-2222-4222-8222-222222222222', session = `claude:${id}`; +const inbox = { schema: 'agent-mesh.monitor-inbox.v1', deliveryId: 'message-1', meshId: 'message-1', prompt: 'fixture' }; +const options = { session, generation: 2, messageId: 'message-1', payload: 'fixture' }; +const user = entry => ({ type: 'user', sessionId: id, message: { content: `Agent Mesh inbox records\nAGENT_MESH_INBOX ${JSON.stringify(entry)}` } }); + +test('only a unique correlated user transcript record proves local inbox observation', async t => { + const root = await mkdtemp(join(tmpdir(), 'claude-observation-')); + t.after(() => rm(root, { recursive: true, force: true })); + const project = join(root, 'project'); await mkdir(project, { mode: 0o700 }); + const path = join(project, `${id}.jsonl`); + const put = rows => writeFile(path, rows.map(row => JSON.stringify(row)).join('\n') + '\n', { mode: 0o600 }); + const message = user(inbox).message.content; + await put([{ type: 'queue-operation', operation: 'enqueue', content: message }]); + await assert.rejects(observeClaudeDelivery({ root, ...options }), /not uniquely observed/); + await put([user(inbox)]); + const proof = await observeClaudeDelivery({ root, ...options }); + assert.equal(proof.session, session); assert.equal(proof.generation, 2); + assert.match(proof.evidence, /^claude-transcript:[a-f0-9]{64}$/); + await assert.rejects(observeClaudeDelivery({ root, ...options, payload: 'changed' }), /correlation mismatch/); + await put([user(inbox), user(inbox)]); + await assert.rejects(observeClaudeDelivery({ root, ...options }), /not uniquely observed/); + await put([{ ...user(inbox), sessionId: '33333333-3333-4333-8333-333333333333' }]); + await assert.rejects(observeClaudeDelivery({ root, ...options }), /session mismatch/); +}); diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index afeac546..ce47fc54 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -174,3 +174,30 @@ test('predecessor notice after a synthetic draining transition persists across r assert.equal((await call('channel', 'get', '--name', 'example')).channel.finalNotice.status, 'observed-snapshot'); await assert.rejects(call('channel', 'finish-handover', '--name', 'example', '--to', `codex:${nextId}`), /old-session state verification unavailable/); }); + +test('local Claude delivery is observed only from a matching user transcript and persists', async t => { + const root = await mkdtemp(join(tmpdir(), 'claude-channel-observe-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = join(root, 'graph'), sessions = join(root, 'sessions'), project = join(sessions, 'project'); + await mkdir(sessions, { mode: 0o700 }); await mkdir(project, { mode: 0o700 }); + const oldId = '22222222-2222-4222-8222-222222222222', newId = '33333333-3333-4333-8333-333333333333', target = `claude:${newId}`; + const env = { ...process.env, CLAUDE_SESSION_ROOT: sessions }; + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args], { env })).stdout); + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', oldId, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${oldId}`); + const graph = await call('show', '--json'), channel = graph.channels.find(row => row.id === 'example'); + channel.session = target; channel.generation = 2; channel.phase = 'draining'; + channel.handover = { predecessor: `codex:${oldId}`, previousGeneration: 1, successor: target, backlog: ['one'] }; + channel.queue = [{ id: 'one', payload: 'fixture', state: 'accepted', session: target, generation: 2 }]; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-draining', type: 'channel.updated', at: new Date().toISOString(), channel, seq: graph.lastSeq + 1, host: 'local' })}\n`); + const inbox = { schema: 'agent-mesh.monitor-inbox.v1', deliveryId: 'one', meshId: 'one', prompt: 'fixture' }; + const text = `AGENT_MESH_INBOX ${JSON.stringify(inbox)}`, path = join(project, `${newId}.jsonl`); + await writeFile(path, JSON.stringify({ type: 'queue-operation', operation: 'enqueue', content: text }) + '\n', { mode: 0o600 }); + await assert.rejects(call('channel', 'observe-claude-delivery', '--name', 'example', '--id', 'one'), /not uniquely observed/); + await appendFile(path, JSON.stringify({ type: 'user', sessionId: newId, message: { content: text } }) + '\n'); + const result = await call('channel', 'observe-claude-delivery', '--name', 'example', '--id', 'one'); + assert.equal(result.status, 'observed'); assert.match(result.evidence, /^claude-transcript:[a-f0-9]{64}$/); + await rm(join(state, 'checkpoint.json'), { force: true }); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'observed'); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index a496e239..d021df83 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -46,6 +46,7 @@ const agentTmuxBundleFiles = [ "bin/mesh-graph.mjs", "bin/plexus.mjs", "bin/channel-state.mjs", + "bin/claude-delivery-observation.mjs", "bin/handover-state-proof.mjs", "bin/handover-notice.mjs", "bin/handover-dry-run.mjs", diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 676ffae2..230b0e24 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -28,4 +28,5 @@ export const plexusDiagram = `flowchart LR Channel -. "pure switch model" .-> Drain["Observe queued deliveries"] Drain -. "then reserve" .-> Notice Wake -. "bound native proof" .-> Drain + ClaudeReadback["Local Claude transcript observer"] -. "observed inbox record" .-> Drain `; diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs index 0747fda6..1a2a8542 100644 --- a/scripts/plexus-privacy.mjs +++ b/scripts/plexus-privacy.mjs @@ -6,7 +6,7 @@ const privatePatterns = [ ]; export function isPlexusMechanismFile(relativePath) { - return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|cloud-(?:account|native)-|codex-(?:compaction|wake)-|module-batches|mesh-(?:graph|channel)|agent-waker|role-(?:launch|mcp)-|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); + return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|claude-delivery-|cloud-(?:account|native)-|codex-(?:compaction|wake)-|module-batches|mesh-(?:graph|channel)|agent-waker|role-(?:launch|mcp)-|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); } export function containsPrivatePlexusPolicy(text) { diff --git a/skills/agent-tmux/bin/claude-delivery-observation.mjs b/skills/agent-tmux/bin/claude-delivery-observation.mjs new file mode 100644 index 00000000..7cff511c --- /dev/null +++ b/skills/agent-tmux/bin/claude-delivery-observation.mjs @@ -0,0 +1,53 @@ +/** Read-only observation of one managed inbox record in a local Claude transcript. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = data => createHash('sha256').update(data).digest('hex'); + +export async function observeClaudeDelivery({ root, session, generation, messageId, payload }) { + if (typeof root !== 'string' || !isAbsolute(root) || typeof session !== 'string' || !session.startsWith('claude:') || !UUID.test(session.slice(7)) || !Number.isSafeInteger(generation) || generation < 1 || typeof messageId !== 'string' || !TOKEN.test(messageId) || typeof payload !== 'string' || !payload || Buffer.byteLength(payload) > 65536) throw new Error('invalid delivery observation request'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || directory.uid !== process.getuid() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const matches = entries.filter(entry => entry.isFile() && entry.name.toLowerCase() === `${session.slice(7).toLowerCase()}.jsonl`).map(entry => join(entry.parentPath, entry.name)); + if (matches.length !== 1 || await realpath(matches[0]) !== matches[0]) throw new Error('transcript identity unavailable or ambiguous'); + const path = matches[0], file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > 128 * 1024 * 1024) throw new Error('invalid transcript file'); + bytes = await file.readFile(); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + } finally { await file.close(); } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let found = 0; + for (const line of text.split('\n')) { + if (!line) continue; + let record; try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + if (record.type !== 'user' || record.isSidechain || record.isMeta) continue; + if (record.sessionId !== session.slice(7)) throw new Error('transcript session mismatch'); + const content = record.message?.content; + const parts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text) : []; + for (const part of parts) for (const entry of part.split('\n')) { + if (!entry.startsWith('AGENT_MESH_INBOX ')) continue; + let inbox; try { inbox = JSON.parse(entry.slice('AGENT_MESH_INBOX '.length)); } catch { throw new Error('invalid inbox record'); } + if (inbox?.deliveryId === messageId || inbox?.meshId === messageId) { + if (inbox.schema !== 'agent-mesh.monitor-inbox.v1' || inbox.deliveryId !== messageId || inbox.meshId !== messageId || inbox.prompt !== payload) throw new Error('inbox correlation mismatch'); + found++; + } + } + } + if (found !== 1) throw new Error('delivery not uniquely observed'); + const payloadSha256 = hash(payload), transcriptSha256 = hash(bytes); + const evidence = `claude-transcript:${hash(JSON.stringify([session, generation, messageId, payloadSha256, transcriptSha256]))}`; + return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, evidence }; +} diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 27fa1a9d..e7b93d8b 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -37,7 +37,8 @@ import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; -import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, observeDelivery, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; +import { observeClaudeDelivery } from "./claude-delivery-observation.mjs"; import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; import { formatFinalNotice } from "./handover-notice.mjs"; @@ -132,7 +133,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -154,6 +155,25 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "observe-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const pending = channel?.queue?.filter(item => item.id === id && item.state === "accepted" && item.session === channel.session && item.generation === channel.generation); + if (channel?.phase !== "draining" || !channel.handover?.backlog?.includes(id) || pending?.length !== 1 || !channel.session.startsWith("claude:")) throw new Error("Claude delivery observation unavailable"); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeClaudeDelivery({ root, session: channel.session, generation: channel.generation, messageId: id, payload: pending[0].payload }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + const item = current?.queue?.find(row => row.id === id); + if (!item || typeof item.payload !== "string" || createHash("sha256").update(item.payload).digest("hex") !== proof.payloadSha256) throw new Error("delivery changed during observation"); + const next = observeDelivery(current, id, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: "observed" } }; + }); + printResult(result, { json: true }); + break; + } if (subcommand === "observe-notice") { const content = JSON.parse(requiredSingleLine(channelInput, "--input")); if (!content || typeof content !== "object" || Array.isArray(content) || Object.keys(content).sort().join(",") !== "label,prefix") throw new Error("invalid notice content"); From 04d7022491d12da1d5df784a97530de372146494 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:29:38 +0000 Subject: [PATCH 084/113] Correlate native Claude inbox observations --- docs/design/plexus-channels.md | 4 +++- .../bin/claude-delivery-observation.mjs | 15 +++++++++------ .../test/claude-delivery-observation.test.mjs | 15 ++++++++++----- .../test/plexus-channel-store.test.mjs | 4 ++-- .../bin/claude-delivery-observation.mjs | 15 +++++++++------ 5 files changed, 33 insertions(+), 20 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index f9f2592d..307e9133 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -238,6 +238,8 @@ This is not a cloud or Claude delivery adapter; native cutover remains disabled. For a draining local Claude channel, `observe-claude-delivery` checks one managed inbox record in a stable local user transcript snapshot, binding its correlation, payload, session and generation before marking the backlog item -observed. An enqueue-only record is insufficient. This source does not prove +observed. It requires a unique matching native enqueue preceding the user +record; an enqueue-only record is insufficient. Native inbox user records can +carry the `isMeta` flag and remain eligible when this correlation is proven. This source does not prove execution, attention, finality or cloud delivery; its real transport transcript shape still requires isolated qualification. Operational cutover remains disabled. diff --git a/packages/tmux-bridge/bin/claude-delivery-observation.mjs b/packages/tmux-bridge/bin/claude-delivery-observation.mjs index 7cff511c..0d6b7a77 100644 --- a/packages/tmux-bridge/bin/claude-delivery-observation.mjs +++ b/packages/tmux-bridge/bin/claude-delivery-observation.mjs @@ -28,25 +28,28 @@ export async function observeClaudeDelivery({ root, session, generation, message let text; try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } if (!text.endsWith('\n')) throw new Error('partial transcript record'); - let found = 0; + let found = 0, queued = 0, queuedLine = null; for (const line of text.split('\n')) { if (!line) continue; let record; try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); - if (record.type !== 'user' || record.isSidechain || record.isMeta) continue; - if (record.sessionId !== session.slice(7)) throw new Error('transcript session mismatch'); - const content = record.message?.content; + const isQueue = record.type === 'queue-operation' && record.operation === 'enqueue'; + const isUser = record.type === 'user' && !record.isSidechain && record.message?.role === 'user'; + if (!isQueue && !isUser) continue; + const content = isQueue ? record.content : record.message?.content; const parts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text) : []; for (const part of parts) for (const entry of part.split('\n')) { if (!entry.startsWith('AGENT_MESH_INBOX ')) continue; let inbox; try { inbox = JSON.parse(entry.slice('AGENT_MESH_INBOX '.length)); } catch { throw new Error('invalid inbox record'); } if (inbox?.deliveryId === messageId || inbox?.meshId === messageId) { + if (record.sessionId !== session.slice(7)) throw new Error('transcript session mismatch'); if (inbox.schema !== 'agent-mesh.monitor-inbox.v1' || inbox.deliveryId !== messageId || inbox.meshId !== messageId || inbox.prompt !== payload) throw new Error('inbox correlation mismatch'); - found++; + if (isQueue) { queued++; queuedLine = entry; } + else { if (queued !== 1 || queuedLine !== entry) throw new Error('matching prior enqueue unavailable'); found++; } } } } - if (found !== 1) throw new Error('delivery not uniquely observed'); + if (queued !== 1 || found !== 1) throw new Error('delivery not uniquely observed'); const payloadSha256 = hash(payload), transcriptSha256 = hash(bytes); const evidence = `claude-transcript:${hash(JSON.stringify([session, generation, messageId, payloadSha256, transcriptSha256]))}`; return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, evidence }; diff --git a/packages/tmux-bridge/test/claude-delivery-observation.test.mjs b/packages/tmux-bridge/test/claude-delivery-observation.test.mjs index d50a3198..9eea0008 100644 --- a/packages/tmux-bridge/test/claude-delivery-observation.test.mjs +++ b/packages/tmux-bridge/test/claude-delivery-observation.test.mjs @@ -8,7 +8,7 @@ import { observeClaudeDelivery } from '../bin/claude-delivery-observation.mjs'; const id = '22222222-2222-4222-8222-222222222222', session = `claude:${id}`; const inbox = { schema: 'agent-mesh.monitor-inbox.v1', deliveryId: 'message-1', meshId: 'message-1', prompt: 'fixture' }; const options = { session, generation: 2, messageId: 'message-1', payload: 'fixture' }; -const user = entry => ({ type: 'user', sessionId: id, message: { content: `Agent Mesh inbox records\nAGENT_MESH_INBOX ${JSON.stringify(entry)}` } }); +const user = entry => ({ type: 'user', isMeta: true, sessionId: id, message: { role: 'user', content: `Agent Mesh inbox records\nAGENT_MESH_INBOX ${JSON.stringify(entry)}` } }); test('only a unique correlated user transcript record proves local inbox observation', async t => { const root = await mkdtemp(join(tmpdir(), 'claude-observation-')); @@ -17,15 +17,20 @@ test('only a unique correlated user transcript record proves local inbox observa const path = join(project, `${id}.jsonl`); const put = rows => writeFile(path, rows.map(row => JSON.stringify(row)).join('\n') + '\n', { mode: 0o600 }); const message = user(inbox).message.content; - await put([{ type: 'queue-operation', operation: 'enqueue', content: message }]); + const queued = { type: 'queue-operation', operation: 'enqueue', sessionId: id, content: message }; + await put([queued]); await assert.rejects(observeClaudeDelivery({ root, ...options }), /not uniquely observed/); - await put([user(inbox)]); + await put([queued, user(inbox)]); const proof = await observeClaudeDelivery({ root, ...options }); assert.equal(proof.session, session); assert.equal(proof.generation, 2); assert.match(proof.evidence, /^claude-transcript:[a-f0-9]{64}$/); await assert.rejects(observeClaudeDelivery({ root, ...options, payload: 'changed' }), /correlation mismatch/); - await put([user(inbox), user(inbox)]); + await put([queued, user(inbox), user(inbox)]); await assert.rejects(observeClaudeDelivery({ root, ...options }), /not uniquely observed/); - await put([{ ...user(inbox), sessionId: '33333333-3333-4333-8333-333333333333' }]); + await put([queued, { ...user(inbox), sessionId: '33333333-3333-4333-8333-333333333333' }]); await assert.rejects(observeClaudeDelivery({ root, ...options }), /session mismatch/); + await put([user(inbox), queued]); + await assert.rejects(observeClaudeDelivery({ root, ...options }), /prior enqueue/); + await put([queued, queued, user(inbox)]); + await assert.rejects(observeClaudeDelivery({ root, ...options }), /prior enqueue|uniquely/); }); diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index ce47fc54..b473ff04 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -193,9 +193,9 @@ test('local Claude delivery is observed only from a matching user transcript and await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-draining', type: 'channel.updated', at: new Date().toISOString(), channel, seq: graph.lastSeq + 1, host: 'local' })}\n`); const inbox = { schema: 'agent-mesh.monitor-inbox.v1', deliveryId: 'one', meshId: 'one', prompt: 'fixture' }; const text = `AGENT_MESH_INBOX ${JSON.stringify(inbox)}`, path = join(project, `${newId}.jsonl`); - await writeFile(path, JSON.stringify({ type: 'queue-operation', operation: 'enqueue', content: text }) + '\n', { mode: 0o600 }); + await writeFile(path, JSON.stringify({ type: 'queue-operation', operation: 'enqueue', sessionId: newId, content: text }) + '\n', { mode: 0o600 }); await assert.rejects(call('channel', 'observe-claude-delivery', '--name', 'example', '--id', 'one'), /not uniquely observed/); - await appendFile(path, JSON.stringify({ type: 'user', sessionId: newId, message: { content: text } }) + '\n'); + await appendFile(path, JSON.stringify({ type: 'user', isMeta: true, sessionId: newId, message: { role: 'user', content: text } }) + '\n'); const result = await call('channel', 'observe-claude-delivery', '--name', 'example', '--id', 'one'); assert.equal(result.status, 'observed'); assert.match(result.evidence, /^claude-transcript:[a-f0-9]{64}$/); await rm(join(state, 'checkpoint.json'), { force: true }); diff --git a/skills/agent-tmux/bin/claude-delivery-observation.mjs b/skills/agent-tmux/bin/claude-delivery-observation.mjs index 7cff511c..0d6b7a77 100644 --- a/skills/agent-tmux/bin/claude-delivery-observation.mjs +++ b/skills/agent-tmux/bin/claude-delivery-observation.mjs @@ -28,25 +28,28 @@ export async function observeClaudeDelivery({ root, session, generation, message let text; try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } if (!text.endsWith('\n')) throw new Error('partial transcript record'); - let found = 0; + let found = 0, queued = 0, queuedLine = null; for (const line of text.split('\n')) { if (!line) continue; let record; try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); - if (record.type !== 'user' || record.isSidechain || record.isMeta) continue; - if (record.sessionId !== session.slice(7)) throw new Error('transcript session mismatch'); - const content = record.message?.content; + const isQueue = record.type === 'queue-operation' && record.operation === 'enqueue'; + const isUser = record.type === 'user' && !record.isSidechain && record.message?.role === 'user'; + if (!isQueue && !isUser) continue; + const content = isQueue ? record.content : record.message?.content; const parts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text) : []; for (const part of parts) for (const entry of part.split('\n')) { if (!entry.startsWith('AGENT_MESH_INBOX ')) continue; let inbox; try { inbox = JSON.parse(entry.slice('AGENT_MESH_INBOX '.length)); } catch { throw new Error('invalid inbox record'); } if (inbox?.deliveryId === messageId || inbox?.meshId === messageId) { + if (record.sessionId !== session.slice(7)) throw new Error('transcript session mismatch'); if (inbox.schema !== 'agent-mesh.monitor-inbox.v1' || inbox.deliveryId !== messageId || inbox.meshId !== messageId || inbox.prompt !== payload) throw new Error('inbox correlation mismatch'); - found++; + if (isQueue) { queued++; queuedLine = entry; } + else { if (queued !== 1 || queuedLine !== entry) throw new Error('matching prior enqueue unavailable'); found++; } } } } - if (found !== 1) throw new Error('delivery not uniquely observed'); + if (queued !== 1 || found !== 1) throw new Error('delivery not uniquely observed'); const payloadSha256 = hash(payload), transcriptSha256 = hash(bytes); const evidence = `claude-transcript:${hash(JSON.stringify([session, generation, messageId, payloadSha256, transcriptSha256]))}`; return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, evidence }; From 79fc605cb453df95f09d1cd69e8e1b7a304ec2e9 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:35:23 +0000 Subject: [PATCH 085/113] Recover uncertain wake during channel draining --- docs/design/plexus-channels.md | 5 ++++- packages/tmux-bridge/bin/channel-state.mjs | 2 +- .../tmux-bridge/bin/codex-wake-evidence.mjs | 8 ++++--- .../test/codex-wake-evidence.test.mjs | 21 ++++++++++++++++++- skills/agent-tmux/bin/channel-state.mjs | 2 +- skills/agent-tmux/bin/codex-wake-evidence.mjs | 8 ++++--- 6 files changed, 36 insertions(+), 10 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 307e9133..86c7d042 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -233,7 +233,10 @@ generation, queue ID and correlation before starting it, then reads back the exact native message. When this proof is verified and settled in a draining channel, it marks that backlog message observed. Older proof schemas remain valid wake evidence but cannot establish this stronger delivery binding. -This is not a cloud or Claude delivery adapter; native cutover remains disabled. +If a native start outcome is uncertain, the explicit readback-only recovery can +settle a draining reservation with a separately named bound-recovery source; +it never starts the queue again. This is not a cloud or Claude delivery adapter; +native cutover remains disabled. For a draining local Claude channel, `observe-claude-delivery` checks one managed inbox record in a stable local user transcript snapshot, binding its diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index f7ae3356..7b9009ee 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -71,7 +71,7 @@ export function settleWake(state, proof) { const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); if (!item) throw new Error('wake item unavailable'); item.wakeEvidence = proof.evidence; - if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && proof.schema === 'agent-mesh.codex-wake-evidence.v4' && proof.source === 'codex-app-server.queue-start-bound-readback' && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { + if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && proof.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(proof.source) && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { item.state = 'observed'; item.observation = proof.evidence; } delete next.wakeReservation; diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index 612a97cd..cc1bcff2 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -45,7 +45,7 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); let state; try { state = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } const reservation = state?.wakeReservation; - if (result.error || result.status !== 0 || state?.phase !== 'active' || !reservation || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); + if (result.error || result.status !== 0 || !['active', 'draining'].includes(state?.phase) || !reservation || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); const { session, id: correlation, nativeQueueId: queueId, generation } = reservation; const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string'); if (items.length !== 1) throw new Error('wake item unavailable'); @@ -60,7 +60,9 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap } const candidate = matching[0]; if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('wake readback not uniquely verified'); - const evidence = { schema: 'agent-mesh.codex-wake-evidence.v3', source: 'codex-app-server.correlated-recovery', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt }; + const evidence = state.phase === 'draining' + ? { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.correlated-recovery-bound', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt, channel, generation, payloadSha256: hash(items[0].payload) } + : { schema: 'agent-mesh.codex-wake-evidence.v3', source: 'codex-app-server.correlated-recovery', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt }; const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } @@ -83,7 +85,7 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session let value; try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && ((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')); - const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && value.source === 'codex-app-server.queue-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); + const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(value.source) && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 9ddb3169..afd501bf 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { execFile } from 'node:child_process'; -import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'; +import { appendFile, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -125,6 +125,25 @@ test('queued wake needs explicit apply, a native start and durable correlated pr } const mismatchFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); assert.equal(mismatchFeed.events.filter(e => e.type === 'session.woken').length, 2); + // Simulate persisted draining state only; no operational cutover is enabled. + const drainRoot = join(root, 'drain'); await mkdir(drainRoot, { mode: 0o700 }); + nativeId = 'queued-drain'; await prepareChannel('drain', nativeId); + let graphState = await call('show', '--json'); + const draining = graphState.channels.find(item => item.id === 'drain'); + draining.phase = 'draining'; draining.handover = { predecessor: 'codex:old-fixture', previousGeneration: 0, successor: session, backlog: [correlation] }; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-drain', type: 'channel.updated', at: new Date().toISOString(), channel: draining, seq: graphState.lastSeq + 1, host: 'local' })}\n`); + const drainArgs = ['--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'drain', '--generation', '1', '--evidence-root', drainRoot, '--graph-state', state]; + mode = 'uncertain'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...drainArgs], { env })); + const callsBeforeRecovery = requests.filter(r => r.method === 'thread/queue/start').length; + mode = 'success'; + const drainResult = JSON.parse((await exec(process.execPath, [bin, '--apply', '--reconcile', '--channel', 'drain', '--evidence-root', drainRoot, '--graph-state', state], { env })).stdout); + const drainProof = await verifyCodexWakeEvidence({ evidenceRoot: drainRoot, reference: drainResult.evidence, session }); + assert.equal(drainProof.schema, 'agent-mesh.codex-wake-evidence.v4'); + assert.equal(drainProof.source, 'codex-app-server.correlated-recovery-bound'); + assert.equal(drainProof.channel, 'drain'); assert.equal(drainProof.generation, 1); + const drained = (await call('channel', 'get', '--name', 'drain')).channel; + assert.equal(drained.queue[0].state, 'observed'); assert.equal(drained.wakeReservation, undefined); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, callsBeforeRecovery); const file = join(evidence, `wake-${first.evidence.slice('codex-wake:'.length)}.json`); const saved = JSON.parse(await readFile(file, 'utf8')); saved.startedAt++; await writeFile(file, `${JSON.stringify(saved)}\n`); diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index f7ae3356..7b9009ee 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -71,7 +71,7 @@ export function settleWake(state, proof) { const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); if (!item) throw new Error('wake item unavailable'); item.wakeEvidence = proof.evidence; - if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && proof.schema === 'agent-mesh.codex-wake-evidence.v4' && proof.source === 'codex-app-server.queue-start-bound-readback' && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { + if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && proof.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(proof.source) && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { item.state = 'observed'; item.observation = proof.evidence; } delete next.wakeReservation; diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index 612a97cd..cc1bcff2 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -45,7 +45,7 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); let state; try { state = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } const reservation = state?.wakeReservation; - if (result.error || result.status !== 0 || state?.phase !== 'active' || !reservation || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); + if (result.error || result.status !== 0 || !['active', 'draining'].includes(state?.phase) || !reservation || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); const { session, id: correlation, nativeQueueId: queueId, generation } = reservation; const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string'); if (items.length !== 1) throw new Error('wake item unavailable'); @@ -60,7 +60,9 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap } const candidate = matching[0]; if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('wake readback not uniquely verified'); - const evidence = { schema: 'agent-mesh.codex-wake-evidence.v3', source: 'codex-app-server.correlated-recovery', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt }; + const evidence = state.phase === 'draining' + ? { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.correlated-recovery-bound', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt, channel, generation, payloadSha256: hash(items[0].payload) } + : { schema: 'agent-mesh.codex-wake-evidence.v3', source: 'codex-app-server.correlated-recovery', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt }; const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } @@ -83,7 +85,7 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session let value; try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && ((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')); - const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && value.source === 'codex-app-server.queue-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); + const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(value.source) && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } From 6c4d6cf15ab50507b10109b0a9f82c3e2ee3aa03 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:40:57 +0000 Subject: [PATCH 086/113] Revalidate restart state before handover --- docs/design/plexus-architecture.mmd | 3 +- docs/design/plexus-channels.md | 6 ++++ .../tmux-bridge/bin/handover-state-proof.mjs | 17 +++++++++-- .../test/handover-state-proof.test.mjs | 29 ++++++++++++++++++- scripts/plexus-diagram.mjs | 3 +- .../agent-tmux/bin/handover-state-proof.mjs | 17 +++++++++-- 6 files changed, 68 insertions(+), 7 deletions(-) diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 1da27b6f..e856cb5e 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -17,7 +17,8 @@ flowchart LR RoleProfile -. "synthetic rehearsal" .-> Rehearsal["In-memory handover rehearsal"] RoleProfile -. "planned runtime launch" .-> Handover StatePrep --> Journal - StatePrep -. "planned proof revalidation" .-> Handover + 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 diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 86c7d042..b8f716cf 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -246,3 +246,9 @@ record; an enqueue-only record is insufficient. Native inbox user records can carry the `isMeta` flag and remain eligible when this correlation is proven. This source does not prove execution, attention, finality or cloud delivery; its real transport transcript shape still requires isolated qualification. Operational cutover remains disabled. + +A previously verified restart-state receipt can be revalidated against the +current private file before a future cutover. Revalidation checks generation, +session, digest, size and YAML, and rejects path replacement during the read. +It is a snapshot, not an exclusion lock: the host must bind it to the later +operation. The live cutover does not yet call it and remains disabled. diff --git a/packages/tmux-bridge/bin/handover-state-proof.mjs b/packages/tmux-bridge/bin/handover-state-proof.mjs index f091917b..c3c247e8 100644 --- a/packages/tmux-bridge/bin/handover-state-proof.mjs +++ b/packages/tmux-bridge/bin/handover-state-proof.mjs @@ -62,8 +62,8 @@ export async function verifyStateResponse({ session, channel, nonce, response, r const before = await file.stat(); if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 1024 * 1024) throw new Error('invalid state file'); const bytes = await file.readFile(); - const after = await file.stat(); - if (before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('state file changed during verification'); + const after = await file.stat(), current = await lstat(join(root, filename)), currentRoot = await lstat(root); + if (!current.isFile() || current.isSymbolicLink() || current.ino !== after.ino || current.dev !== after.dev || current.size !== after.size || current.mtimeMs !== after.mtimeMs || current.ctimeMs !== after.ctimeMs || !currentRoot.isDirectory() || currentRoot.isSymbolicLink() || currentRoot.ino !== rootInfo.ino || currentRoot.dev !== rootInfo.dev || before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('state file changed during verification'); const digest = createHash('sha256').update(bytes).digest('hex'); if (digest !== attestation.sha256) throw new Error('state file digest mismatch'); if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); @@ -72,6 +72,19 @@ export async function verifyStateResponse({ session, channel, nonce, response, r let restart; try { restart = JSON.parse(decoded.stdout); } catch { throw new Error('invalid restart YAML result'); } validateRestartState(restart, { session, channel, requireRoleProfile: true }); + const final = await lstat(join(root, filename)), finalRoot = await lstat(root); + if (!final.isFile() || final.isSymbolicLink() || final.dev !== after.dev || final.ino !== after.ino || final.size !== after.size || final.mtimeMs !== after.mtimeMs || final.ctimeMs !== after.ctimeMs || !finalRoot.isDirectory() || finalRoot.isSymbolicLink() || finalRoot.dev !== rootInfo.dev || finalRoot.ino !== rootInfo.ino) throw new Error('state file changed during verification'); return { schema: attestation.schema, session, nonce, filename, sha256: digest, bytes: bytes.length }; } finally { await file.close(); } } + +// Revalidate the bytes referenced by a previously authenticated graph receipt. +// The caller owns lifecycle exclusion and must also bind this check to its +// subsequent action; a snapshot cannot prevent later file replacement. +export async function revalidateStateProof({ root, channel, session, generation, statePreparation }) { + if (!statePreparation || statePreparation.status !== 'verified' || statePreparation.session !== session || !Number.isSafeInteger(generation) || generation < 1 || statePreparation.generation !== generation || typeof statePreparation.id !== 'string' || typeof statePreparation.filename !== 'string' || !/^[0-9a-f]{64}$/.test(statePreparation.sha256 || '') || !Number.isSafeInteger(statePreparation.bytes) || statePreparation.bytes < 1) throw new Error('state preparation receipt mismatch'); + const response = JSON.stringify({ schema: 'agent-mesh.handover-state.v1', session, nonce: statePreparation.id, filename: statePreparation.filename, sha256: statePreparation.sha256 }); + const result = await verifyStateResponse({ session, channel, nonce: statePreparation.id, response, root, filename: statePreparation.filename }); + if (result.bytes !== statePreparation.bytes) throw new Error('state preparation size mismatch'); + return result; +} diff --git a/packages/tmux-bridge/test/handover-state-proof.test.mjs b/packages/tmux-bridge/test/handover-state-proof.test.mjs index ce5342fb..2ac2021c 100644 --- a/packages/tmux-bridge/test/handover-state-proof.test.mjs +++ b/packages/tmux-bridge/test/handover-state-proof.test.mjs @@ -4,7 +4,7 @@ import { chmod, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import test from 'node:test'; -import { prepareState, requestStateProof, verifyStateResponse } from '../bin/handover-state-proof.mjs'; +import { prepareState, requestStateProof, verifyStateResponse, revalidateStateProof } from '../bin/handover-state-proof.mjs'; import { beginHandover, completeStatePreparation, createChannel, enqueue, reserveStatePreparation } from '../bin/channel-state.mjs'; test('preparation reserves before transport, retains a lost response, and binds concurrent queue changes', async () => { @@ -32,6 +32,14 @@ test('state proof binds correlated response to private file bytes', async (t) => const response = { schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }; const verify = (overrides = {}) => verifyStateResponse({ session, channel, nonce, filename, root, response: JSON.stringify(response), ...overrides }); assert.equal((await verify()).bytes, Buffer.byteLength(content)); + const prepared = { status: 'verified', session, generation: 1, id: nonce, filename, sha256: response.sha256, bytes: Buffer.byteLength(content) }; + const revalidate = (overrides = {}) => revalidateStateProof({ root, channel, session, generation: 1, statePreparation: prepared, ...overrides }); + assert.equal((await revalidate()).sha256, response.sha256); + await assert.rejects(revalidate({ generation: 2 }), /receipt mismatch/); + await assert.rejects(revalidate({ statePreparation: { ...prepared, bytes: prepared.bytes + 1 } }), /size mismatch/); + await writeFile(join(root, filename), content.replace('operator', 'operatOr'), { mode: 0o600 }); + await assert.rejects(revalidate(), /digest mismatch/); + await writeFile(join(root, filename), content, { mode: 0o600 }); await assert.rejects(verify({ channel: '#other' }), /channel mismatch/); await assert.rejects(verify({ nonce: 'other' }), /binding/); const malformed = content + 'harness: other\n'; @@ -69,3 +77,22 @@ test('native request binds response to its own correlation without resuming', as await assert.rejects(requestStateProof({ session, channel: '#example', root, filename }, async () => ({ stdout: JSON.stringify({ status: 'held' }) })), /binding/); await assert.rejects(requestStateProof({ session, channel: '#example', root, filename }, async () => { throw new Error('timeout'); }), /timeout/); }); + +test('state verification rejects path replacement during YAML decoding', async t => { + const root = await mkdtemp(join(tmpdir(), 'state-replacement-')); + t.after(() => rm(root, { recursive: true, force: true })); + const session = 'codex:22222222-2222-4222-8222-222222222222', channel = '#example', filename = 'state.yaml', nonce = 'attempt-1'; + const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\nrole_profile:\n schema: agent-mesh.role-profile.v1\n role: operator\n permissions: []\n mcp: []\n plugins: []\n`; + const state = join(root, filename), shim = join(root, 'decoder-shim'); + await writeFile(state, content, { mode: 0o600 }); + await writeFile(shim, '#!/bin/sh\npython3 "$@"\ncp -- "$TEST_STATE_FILE" "$TEST_STATE_FILE.swap"\nmv -- "$TEST_STATE_FILE.swap" "$TEST_STATE_FILE"\n', { mode: 0o700 }); + const oldPython = process.env.PYTHON, oldState = process.env.TEST_STATE_FILE; + process.env.PYTHON = shim; process.env.TEST_STATE_FILE = state; + try { + const response = JSON.stringify({ schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }); + await assert.rejects(verifyStateResponse({ root, channel, session, nonce, filename, response }), /state file changed/); + } finally { + if (oldPython === undefined) delete process.env.PYTHON; else process.env.PYTHON = oldPython; + if (oldState === undefined) delete process.env.TEST_STATE_FILE; else process.env.TEST_STATE_FILE = oldState; + } +}); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 230b0e24..1502b88d 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -18,7 +18,8 @@ export const plexusDiagram = `flowchart LR RoleProfile -. "synthetic rehearsal" .-> Rehearsal["In-memory handover rehearsal"] RoleProfile -. "planned runtime launch" .-> Handover StatePrep --> Journal - StatePrep -. "planned proof revalidation" .-> Handover + 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 diff --git a/skills/agent-tmux/bin/handover-state-proof.mjs b/skills/agent-tmux/bin/handover-state-proof.mjs index f091917b..c3c247e8 100644 --- a/skills/agent-tmux/bin/handover-state-proof.mjs +++ b/skills/agent-tmux/bin/handover-state-proof.mjs @@ -62,8 +62,8 @@ export async function verifyStateResponse({ session, channel, nonce, response, r const before = await file.stat(); if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 1024 * 1024) throw new Error('invalid state file'); const bytes = await file.readFile(); - const after = await file.stat(); - if (before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('state file changed during verification'); + const after = await file.stat(), current = await lstat(join(root, filename)), currentRoot = await lstat(root); + if (!current.isFile() || current.isSymbolicLink() || current.ino !== after.ino || current.dev !== after.dev || current.size !== after.size || current.mtimeMs !== after.mtimeMs || current.ctimeMs !== after.ctimeMs || !currentRoot.isDirectory() || currentRoot.isSymbolicLink() || currentRoot.ino !== rootInfo.ino || currentRoot.dev !== rootInfo.dev || before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('state file changed during verification'); const digest = createHash('sha256').update(bytes).digest('hex'); if (digest !== attestation.sha256) throw new Error('state file digest mismatch'); if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); @@ -72,6 +72,19 @@ export async function verifyStateResponse({ session, channel, nonce, response, r let restart; try { restart = JSON.parse(decoded.stdout); } catch { throw new Error('invalid restart YAML result'); } validateRestartState(restart, { session, channel, requireRoleProfile: true }); + const final = await lstat(join(root, filename)), finalRoot = await lstat(root); + if (!final.isFile() || final.isSymbolicLink() || final.dev !== after.dev || final.ino !== after.ino || final.size !== after.size || final.mtimeMs !== after.mtimeMs || final.ctimeMs !== after.ctimeMs || !finalRoot.isDirectory() || finalRoot.isSymbolicLink() || finalRoot.dev !== rootInfo.dev || finalRoot.ino !== rootInfo.ino) throw new Error('state file changed during verification'); return { schema: attestation.schema, session, nonce, filename, sha256: digest, bytes: bytes.length }; } finally { await file.close(); } } + +// Revalidate the bytes referenced by a previously authenticated graph receipt. +// The caller owns lifecycle exclusion and must also bind this check to its +// subsequent action; a snapshot cannot prevent later file replacement. +export async function revalidateStateProof({ root, channel, session, generation, statePreparation }) { + if (!statePreparation || statePreparation.status !== 'verified' || statePreparation.session !== session || !Number.isSafeInteger(generation) || generation < 1 || statePreparation.generation !== generation || typeof statePreparation.id !== 'string' || typeof statePreparation.filename !== 'string' || !/^[0-9a-f]{64}$/.test(statePreparation.sha256 || '') || !Number.isSafeInteger(statePreparation.bytes) || statePreparation.bytes < 1) throw new Error('state preparation receipt mismatch'); + const response = JSON.stringify({ schema: 'agent-mesh.handover-state.v1', session, nonce: statePreparation.id, filename: statePreparation.filename, sha256: statePreparation.sha256 }); + const result = await verifyStateResponse({ session, channel, nonce: statePreparation.id, response, root, filename: statePreparation.filename }); + if (result.bytes !== statePreparation.bytes) throw new Error('state preparation size mismatch'); + return result; +} From 2af8d3009575cba32a8ecbd8763b48b37a09f800 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:45:39 +0000 Subject: [PATCH 087/113] Bind restart revalidation to channel state --- docs/design/plexus-channels.md | 4 ++- packages/tmux-bridge/bin/mesh-graph.mjs | 16 ++++++++++-- .../test/plexus-channel-store.test.mjs | 26 +++++++++++++++++++ skills/agent-tmux/bin/mesh-graph.mjs | 16 ++++++++++-- 4 files changed, 57 insertions(+), 5 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index b8f716cf..efb2151e 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -251,4 +251,6 @@ A previously verified restart-state receipt can be revalidated against the current private file before a future cutover. Revalidation checks generation, session, digest, size and YAML, and rejects path replacement during the read. It is a snapshot, not an exclusion lock: the host must bind it to the later -operation. The live cutover does not yet call it and remains disabled. +operation. The graph `channel revalidate-state` command binds the snapshot to the +persisted preparation and checks the channel again after reading without changing +the graph. The live cutover does not yet call it and remains disabled. diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index e7b93d8b..3ce78418 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -40,7 +40,7 @@ import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, observeDelivery, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; import { observeClaudeDelivery } from "./claude-delivery-observation.mjs"; import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; -import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; +import { prepareState, requestStateProof, revalidateStateProof } from "./handover-state-proof.mjs"; import { formatFinalNotice } from "./handover-notice.mjs"; import { observeLocalFinalNotice } from "./handover-notice-transport.mjs"; @@ -133,7 +133,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -212,6 +212,18 @@ try { printResult(result, { json: true }); break; } + if (subcommand === "revalidate-state") { + const root = requiredSingleLine(values["state-root"], "--state-root"); + if (!isAbsolute(root)) throw new Error("absolute state root required"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + if (!channel || channel.phase !== "handover" || channel.wakeReservation || channel.queue?.some(item => item.state === "inflight")) throw new Error("state revalidation unavailable"); + const proof = await revalidateStateProof({ root, channel: name, session: channel.session, generation: channel.generation, statePreparation: channel.statePreparation }); + assertPrivateChannelState(stateDir); + const current = (loadGraph(stateDir).channels || []).find(item => item.id === name); + if (!current || current.phase !== "handover" || current.session !== channel.session || current.generation !== channel.generation || current.wakeReservation || current.queue?.some(item => item.state === "inflight") || JSON.stringify(current.statePreparation) !== JSON.stringify(channel.statePreparation)) throw new Error("channel changed during state revalidation"); + printResult({ schema: "agent-mesh.state-revalidation.v1", channel: name, session: channel.session, generation: channel.generation, filename: proof.filename, sha256: proof.sha256, bytes: proof.bytes, status: "verified-snapshot" }, { json: true }); + break; + } if (subcommand === "prepare-state") { const root = requiredSingleLine(values["state-root"], "--state-root"), filename = requiredSingleLine(values.filename, "--filename"); if (!isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error("invalid state preparation path"); diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index b473ff04..543ec1a7 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -201,3 +201,29 @@ test('local Claude delivery is observed only from a matching user transcript and await rm(join(state, 'checkpoint.json'), { force: true }); assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'observed'); }); + +test('graph revalidates the bound restart file without advancing handover', async t => { + const { createHash } = await import('node:crypto'); + const root = await mkdtemp(join(tmpdir(), 'handover-revalidate-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = join(root, 'graph'), files = join(root, 'files'); await mkdir(files, { mode: 0o700 }); + const id = '22222222-2222-4222-8222-222222222222', session = `codex:${id}`, filename = 'state.yaml'; + const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\nrole_profile:\n schema: agent-mesh.role-profile.v1\n role: operator\n permissions: []\n mcp: []\n plugins: []\n`; + await writeFile(join(files, filename), content, { mode: 0o600 }); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args])).stdout); + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', id, '--json'); + await call('migrate', '--apply', '--json'); await call('channel', 'create', '--name', '#example', '--session', session); + await call('channel', 'begin-handover', '--name', '#example'); + let graph = await call('show', '--json'); + const channel = graph.channels.find(row => row.id === '#example'); + channel.statePreparation = { status: 'verified', session, generation: 1, id: 'fixture-state', filename, sha256: createHash('sha256').update(content).digest('hex'), bytes: Buffer.byteLength(content) }; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-state', type: 'channel.updated', at: new Date().toISOString(), channel, seq: graph.lastSeq + 1, host: 'local' })}\n`); + graph = await call('show', '--json'); const seq = graph.lastSeq; + const args = ['channel', 'revalidate-state', '--name', '#example', '--state-root', files]; + const proof = await call(...args); + assert.equal(proof.status, 'verified-snapshot'); assert.equal(proof.generation, 1); + assert.equal((await call('show', '--json')).lastSeq, seq); + await writeFile(join(files, filename), content.replace('operator', 'operatOr'), { mode: 0o600 }); + await assert.rejects(call(...args), /digest mismatch/); + assert.equal((await call('channel', 'get', '--name', '#example')).channel.phase, 'handover'); +}); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index e7b93d8b..3ce78418 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -40,7 +40,7 @@ import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, observeDelivery, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; import { observeClaudeDelivery } from "./claude-delivery-observation.mjs"; import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; -import { prepareState, requestStateProof } from "./handover-state-proof.mjs"; +import { prepareState, requestStateProof, revalidateStateProof } from "./handover-state-proof.mjs"; import { formatFinalNotice } from "./handover-notice.mjs"; import { observeLocalFinalNotice } from "./handover-notice-transport.mjs"; @@ -133,7 +133,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -212,6 +212,18 @@ try { printResult(result, { json: true }); break; } + if (subcommand === "revalidate-state") { + const root = requiredSingleLine(values["state-root"], "--state-root"); + if (!isAbsolute(root)) throw new Error("absolute state root required"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + if (!channel || channel.phase !== "handover" || channel.wakeReservation || channel.queue?.some(item => item.state === "inflight")) throw new Error("state revalidation unavailable"); + const proof = await revalidateStateProof({ root, channel: name, session: channel.session, generation: channel.generation, statePreparation: channel.statePreparation }); + assertPrivateChannelState(stateDir); + const current = (loadGraph(stateDir).channels || []).find(item => item.id === name); + if (!current || current.phase !== "handover" || current.session !== channel.session || current.generation !== channel.generation || current.wakeReservation || current.queue?.some(item => item.state === "inflight") || JSON.stringify(current.statePreparation) !== JSON.stringify(channel.statePreparation)) throw new Error("channel changed during state revalidation"); + printResult({ schema: "agent-mesh.state-revalidation.v1", channel: name, session: channel.session, generation: channel.generation, filename: proof.filename, sha256: proof.sha256, bytes: proof.bytes, status: "verified-snapshot" }, { json: true }); + break; + } if (subcommand === "prepare-state") { const root = requiredSingleLine(values["state-root"], "--state-root"), filename = requiredSingleLine(values.filename, "--filename"); if (!isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error("invalid state preparation path"); From d03039c1caac7c89a366279c40b92cd5f4449704 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:56:14 +0000 Subject: [PATCH 088/113] Cover an automatically drained wake queue --- docs/design/plexus-channels.md | 8 ++++++++ packages/tmux-bridge/test/codex-wake-evidence.test.mjs | 9 ++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index efb2151e..0f6febd3 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -254,3 +254,11 @@ It is a snapshot, not an exclusion lock: the host must bind it to the later operation. The graph `channel revalidate-state` command binds the snapshot to the persisted preparation and checks the channel again after reading without changing the graph. The live cutover does not yet call it and remains disabled. + +A network-isolated experiment with Codex CLI 0.169.0 and a temporary home +observed a queued submission leave the queue and a turn start before an +explicit queue/start call. Without model connectivity, the full turn readback +did not expose a correlated user item in the observation window. The existing +producer refuses an empty queue and does not retry the start; it cannot yet +prove this automatic-start path or count it as zero. An authenticated, uniquely +correlated observation path is still required. diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index afd501bf..389e7472 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -37,7 +37,7 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const server = createAppServer((request, peer) => { if (!request.id) return; requests.push(request); - if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: mode === 'wrong-queue-payload' ? 'different' : 'fixture', text_elements: [] }] }], nextCursor: null } }); + if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: mode === 'auto-drained' ? [] : [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: mode === 'wrong-queue-payload' ? 'different' : 'fixture', text_elements: [] }] }], nextCursor: null } }); else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: 123456789, items: [] } } }); else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, status: 'completed', startedAt: mode === 'wrong-time' ? 123456788 : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture', text_elements: [] }] }] }] } } }); else peer.send({ id: request.id, result: {} }); @@ -54,6 +54,13 @@ test('queued wake needs explicit apply, a native start and durable correlated pr assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 0); mode = 'wrong'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); assert.deepEqual(await readdir(evidence), []); + nativeId = 'queued-auto'; await prepareChannel('auto-drained', nativeId); + mode = 'auto-drained'; + await assert.rejects(exec(process.execPath, [bin, '--apply', '--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'auto-drained', '--generation', '1', '--evidence-root', evidence, '--graph-state', state], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 0); + const auto = (await call('channel', 'get', '--name', 'auto-drained')).channel; + assert.equal(auto.queue[0].state, 'accepted'); assert.equal(auto.wakeReservation, undefined); + assert.deepEqual(await readdir(evidence), []); nativeId = 'queued-payload'; await prepareChannel('payload', nativeId); mode = 'wrong-queue-payload'; await assert.rejects(exec(process.execPath, [bin, '--apply', '--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'payload', '--generation', '1', '--evidence-root', evidence, '--graph-state', state], { env })); From 514482d12510525e633f057ae8b191d7398ed785 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:07:08 +0000 Subject: [PATCH 089/113] Reconcile automatically started wake by readback --- docs/design/plexus-architecture.mmd | 1 + docs/design/plexus-channels.md | 10 ++-- packages/tmux-bridge/bin/channel-state.mjs | 12 +++-- .../tmux-bridge/bin/codex-wake-evidence.mjs | 49 +++++++++++++++++-- packages/tmux-bridge/bin/mesh-graph.mjs | 6 ++- .../test/codex-wake-evidence.test.mjs | 23 ++++++++- scripts/plexus-diagram.mjs | 1 + skills/agent-tmux/bin/channel-state.mjs | 12 +++-- skills/agent-tmux/bin/codex-wake-evidence.mjs | 49 +++++++++++++++++-- skills/agent-tmux/bin/mesh-graph.mjs | 6 ++- 10 files changed, 142 insertions(+), 27 deletions(-) diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index e856cb5e..1a8dbf31 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -27,5 +27,6 @@ flowchart LR Handover["Handover"] -. "planned verified cutover" .-> Channel Channel -. "pure switch model" .-> Drain["Observe queued deliveries"] Drain -. "then reserve" .-> Notice + AutoWake["Explicit auto-wake readback"] --> Wake Wake -. "bound native proof" .-> Drain ClaudeReadback["Local Claude transcript observer"] -. "observed inbox record" .-> Drain diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 0f6febd3..90508c41 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -259,6 +259,10 @@ A network-isolated experiment with Codex CLI 0.169.0 and a temporary home observed a queued submission leave the queue and a turn start before an explicit queue/start call. Without model connectivity, the full turn readback did not expose a correlated user item in the observation window. The existing -producer refuses an empty queue and does not retry the start; it cannot yet -prove this automatic-start path or count it as zero. An authenticated, uniquely -correlated observation path is still required. +explicit-start producer refuses an empty queue and does not retry the start. +An explicit `--observe-auto` path reserves a distinct observation mode and +uses native full-turn readback to bind the queued client ID and exact payload. +It requires the turn start timestamp to be strictly later than the durable +dispatch reservation. Since native turn time has one-second precision, many +valid same-second starts remain unknown; they must never be counted as zero. +No waker invokes this path automatically and its live behavior is not qualified. diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 7b9009ee..275cc253 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -56,22 +56,24 @@ export function beginHandover(state) { } // A reservation is durable and has no expiry: a crashed native call is unknown. -export function reserveWake(state, id, session, generation, nativeQueueId) { - if (!['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); +export function reserveWake(state, id, session, generation, nativeQueueId, mode = 'start') { + if (!['start', 'auto-readback'].includes(mode) || !['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && !item.wakeEvidence && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); const next = copy(state); - next.wakeReservation = { id, session, generation, nativeQueueId }; + next.wakeReservation = { id, session, generation, nativeQueueId, mode }; return next; } export function settleWake(state, proof) { const reservation = state.wakeReservation; - if (!reservation || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + if (!reservation || (proof?.source === 'codex-app-server.auto-start-bound-readback' ? reservation.mode !== 'auto-readback' : reservation.mode === 'auto-readback') || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); if (!item) throw new Error('wake item unavailable'); item.wakeEvidence = proof.evidence; - if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && proof.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(proof.source) && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { + const boundWake = proof.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(proof.source); + const autoWake = proof.schema === 'agent-mesh.codex-wake-evidence.v5' && proof.source === 'codex-app-server.auto-start-bound-readback' && proof.dispatchReservedAtMs === item.dispatchReservedAtMs; + if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && (boundWake || autoWake) && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { item.state = 'observed'; item.observation = proof.evidence; } delete next.wakeReservation; diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index cc1bcff2..827cf4d3 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -45,7 +45,7 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); let state; try { state = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } const reservation = state?.wakeReservation; - if (result.error || result.status !== 0 || !['active', 'draining'].includes(state?.phase) || !reservation || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); + if (result.error || result.status !== 0 || !['active', 'draining'].includes(state?.phase) || !reservation || reservation.mode === 'auto-readback' || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); const { session, id: correlation, nativeQueueId: queueId, generation } = reservation; const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string'); if (items.length !== 1) throw new Error('wake item unavailable'); @@ -69,6 +69,44 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); } +// Read-only reconciliation of a submission consumed automatically by the native +// queue. A distinct reservation mode prevents racing an explicit queue/start. +export async function observeAutoCodexWake({ channel, thread, queueId, correlation, generation, graphState, evidenceRoot, apply }) { + if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || !Number.isSafeInteger(generation) || generation < 1 || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit auto wake identity required'); + await privateRoot(graphState); await privateRoot(evidenceRoot); + const session = `codex:${thread.toLowerCase()}`; + const getChannel = () => { + const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); + if (result.error || result.status !== 0) throw new Error('channel unavailable'); + let value; try { value = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } + return value; + }; + let state = getChannel(); + if (!state?.wakeReservation) { + const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId, '--source', 'auto-readback'], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (reserved.error || reserved.status !== 0) throw new Error('auto wake reservation unavailable or uncertain'); + state = getChannel(); + } + const reservation = state?.wakeReservation; + if (!['active', 'draining'].includes(state?.phase) || state.id !== channel || state.session !== session || state.generation !== generation || !reservation || reservation.mode !== 'auto-readback' || reservation.id !== correlation || reservation.session !== session || reservation.generation !== generation || reservation.nativeQueueId !== queueId) throw new Error('auto wake reservation mismatch'); + const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string' && Number.isSafeInteger(item.dispatchReservedAtMs) && item.dispatchReservedAtMs > 0); + if (items.length !== 1) throw new Error('auto wake item unavailable'); + const observed = await withCodexAppServer({ clientName: 'agent-mesh-auto-wake-readback', timeout: 30000, timeoutMessage: 'native read unavailable' }, request => request('thread/read', { threadId: thread.toLowerCase(), includeTurns: true })); + if (observed?.thread?.id !== thread.toLowerCase() || !Array.isArray(observed.thread.turns)) throw new Error('native read unavailable'); + const matching = []; + for (const turn of observed.thread.turns) { + if (!Array.isArray(turn.items) || (turn.itemsView !== undefined && turn.itemsView !== 'full')) throw new Error('incomplete native read'); + for (const item of turn.items) if (item?.type === 'userMessage' && item.clientId === correlation) matching.push({ turn, item }); + } + const candidate = matching[0]; + if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || !Number.isSafeInteger(candidate.item.startedAtMs) || candidate.item.startedAtMs < items[0].dispatchReservedAtMs || candidate.turn.startedAt * 1000 <= items[0].dispatchReservedAtMs || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('auto wake readback not uniquely verified'); + const evidence = { schema: 'agent-mesh.codex-wake-evidence.v5', source: 'codex-app-server.auto-start-bound-readback', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt, channel, generation, payloadSha256: hash(items[0].payload), dispatchReservedAtMs: items[0].dispatchReservedAtMs, itemStartedAtMs: candidate.item.startedAtMs }; + const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; + try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } + catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } + return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); +} + export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { if (typeof reference !== 'string' || !/^codex-wake:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid wake verification request'); await privateRoot(evidenceRoot); @@ -86,7 +124,8 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && ((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')); const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(value.source) && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); - if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + const auto = value && Object.keys(value).sort().join(',') === 'channel,correlation,dispatchReservedAtMs,generation,itemStartedAtMs,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v5' && value.source === 'codex-app-server.auto-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256) && Number.isSafeInteger(value.dispatchReservedAtMs) && value.dispatchReservedAtMs > 0 && Number.isSafeInteger(value.itemStartedAtMs) && value.itemStartedAtMs >= value.dispatchReservedAtMs && Number.isSafeInteger(value.startedAt) && value.startedAt * 1000 > value.dispatchReservedAtMs; + if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound || auto) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } @@ -149,9 +188,11 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { try { - const { values } = parseArgs({ options: { apply: { type: 'boolean' }, reconcile: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, reconcile: { type: 'boolean' }, 'observe-auto': { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + if (values['observe-auto'] && (values.reconcile || values.verify || values.publish)) throw new Error('conflicting wake operations'); let result; - if (values.reconcile) result = await reconcileCodexWake({ channel: values.channel, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + if (values['observe-auto']) result = await observeAutoCodexWake({ channel: values.channel, thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + else if (values.reconcile) result = await reconcileCodexWake({ channel: values.channel, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); else if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'], channel: values.channel }); else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, channel: values.channel, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 3ce78418..1f21a08d 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -263,7 +263,9 @@ try { if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), channelInput); else if (subcommand === "begin-delivery") { if (values.generation !== undefined && !/^[1-9][0-9]*$/.test(values.generation)) throw new Error("invalid channel generation"); - next = beginDelivery(current, requiredSingleLine(values.id, "--id"), values.session === undefined ? undefined : requiredSingleLine(values.session, "--session"), values.generation === undefined ? undefined : Number(values.generation)); + const messageId = requiredSingleLine(values.id, "--id"); + next = beginDelivery(current, messageId, values.session === undefined ? undefined : requiredSingleLine(values.session, "--session"), values.generation === undefined ? undefined : Number(values.generation)); + next.queue.find(item => item.id === messageId).dispatchReservedAtMs = Date.now(); } else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); else if (subcommand === "reserve-wake") { @@ -272,7 +274,7 @@ try { const sourceId = `codex-wake-${createHash("sha256").update(JSON.stringify([session, queueId])).digest("hex")}`; const receiptId = createHash("sha256").update(sourceId).digest("hex"); if ((graph.lifecycleReceipts || []).some(item => item.id === receiptId) || (graph.channels || []).some(item => item.id !== name && item.wakeReservation?.session === session && item.wakeReservation?.nativeQueueId === queueId)) throw new Error("wake identity already reserved or recorded"); - next = reserveWake(current, requiredSingleLine(values.id, "--id"), session, Number(values.generation), queueId); + next = reserveWake(current, requiredSingleLine(values.id, "--id"), session, Number(values.generation), queueId, values.source === undefined ? 'start' : requiredSingleLine(values.source, '--source')); } else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "reserve-notice") { diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 389e7472..776976fa 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -33,13 +33,13 @@ test('queued wake needs explicit apply, a native start and durable correlated pr } await prepareChannel('success'); const cursor = (await call('query', 'changes', '--input', JSON.stringify({ initial: 'head' }))).cursor; - const requests = []; let mode = 'success', nativeId = 'queued-1'; + const requests = []; let mode = 'success', nativeId = 'queued-1', autoReservedMs = 0; const server = createAppServer((request, peer) => { if (!request.id) return; requests.push(request); if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: mode === 'auto-drained' ? [] : [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: mode === 'wrong-queue-payload' ? 'different' : 'fixture', text_elements: [] }] }], nextCursor: null } }); else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: 123456789, items: [] } } }); - else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, status: 'completed', startedAt: mode === 'wrong-time' ? 123456788 : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture', text_elements: [] }] }] }] } } }); + else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, status: 'completed', startedAt: mode === 'wrong-time' ? 123456788 : mode === 'auto-same-second' ? Math.floor(autoReservedMs / 1000) : nativeId === 'queued-auto-proof' && mode !== 'auto-old-turn' ? Math.floor(Date.now() / 1000) : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', startedAtMs: nativeId === 'queued-auto-proof' ? Date.now() : 123456789001, clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture', text_elements: [] }] }] }] } } }); else peer.send({ id: request.id, result: {} }); }); await new Promise(resolve => server.listen(socket, resolve)); @@ -151,6 +151,25 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const drained = (await call('channel', 'get', '--name', 'drain')).channel; assert.equal(drained.queue[0].state, 'observed'); assert.equal(drained.wakeReservation, undefined); assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, callsBeforeRecovery); + // An auto-consumed queue item is reconciled by readback only, never started. + const autoRoot = join(root, 'auto-proof'); await mkdir(autoRoot, { mode: 0o700 }); + nativeId = 'queued-auto-proof'; await prepareChannel('auto-proof', nativeId); + autoReservedMs = (await call('channel', 'get', '--name', 'auto-proof')).channel.queue[0].dispatchReservedAtMs; + await new Promise(resolve => setTimeout(resolve, 1100)); // native turn timestamps have one-second precision + const autoArgs = ['--observe-auto', '--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'auto-proof', '--generation', '1', '--evidence-root', autoRoot, '--graph-state', state]; + mode = 'wrong-client'; const autoStarts = requests.filter(r => r.method === 'thread/queue/start').length; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...autoArgs], { env })); + assert.equal((await call('channel', 'get', '--name', 'auto-proof')).channel.wakeReservation.mode, 'auto-readback'); + await assert.rejects(exec(process.execPath, [bin, '--apply', '--reconcile', '--channel', 'auto-proof', '--evidence-root', autoRoot, '--graph-state', state], { env })); + mode = 'wrong-input'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...autoArgs], { env })); + mode = 'auto-old-turn'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...autoArgs], { env })); + mode = 'auto-same-second'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...autoArgs], { env })); + mode = 'success'; + const autoResult = JSON.parse((await exec(process.execPath, [bin, '--apply', ...autoArgs], { env })).stdout); + const autoProof = await verifyCodexWakeEvidence({ evidenceRoot: autoRoot, reference: autoResult.evidence, session }); + assert.equal(autoProof.source, 'codex-app-server.auto-start-bound-readback'); + assert.equal(autoProof.channel, 'auto-proof'); assert.equal(autoResult.settled, true); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, autoStarts); const file = join(evidence, `wake-${first.evidence.slice('codex-wake:'.length)}.json`); const saved = JSON.parse(await readFile(file, 'utf8')); saved.startedAt++; await writeFile(file, `${JSON.stringify(saved)}\n`); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 1502b88d..7eef9271 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -28,6 +28,7 @@ export const plexusDiagram = `flowchart LR Handover["Handover"] -. "planned verified cutover" .-> Channel Channel -. "pure switch model" .-> Drain["Observe queued deliveries"] Drain -. "then reserve" .-> Notice + AutoWake["Explicit auto-wake readback"] --> Wake Wake -. "bound native proof" .-> Drain ClaudeReadback["Local Claude transcript observer"] -. "observed inbox record" .-> Drain `; diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 7b9009ee..275cc253 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -56,22 +56,24 @@ export function beginHandover(state) { } // A reservation is durable and has no expiry: a crashed native call is unknown. -export function reserveWake(state, id, session, generation, nativeQueueId) { - if (!['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); +export function reserveWake(state, id, session, generation, nativeQueueId, mode = 'start') { + if (!['start', 'auto-readback'].includes(mode) || !['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && !item.wakeEvidence && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); const next = copy(state); - next.wakeReservation = { id, session, generation, nativeQueueId }; + next.wakeReservation = { id, session, generation, nativeQueueId, mode }; return next; } export function settleWake(state, proof) { const reservation = state.wakeReservation; - if (!reservation || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + if (!reservation || (proof?.source === 'codex-app-server.auto-start-bound-readback' ? reservation.mode !== 'auto-readback' : reservation.mode === 'auto-readback') || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); if (!item) throw new Error('wake item unavailable'); item.wakeEvidence = proof.evidence; - if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && proof.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(proof.source) && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { + const boundWake = proof.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(proof.source); + const autoWake = proof.schema === 'agent-mesh.codex-wake-evidence.v5' && proof.source === 'codex-app-server.auto-start-bound-readback' && proof.dispatchReservedAtMs === item.dispatchReservedAtMs; + if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && (boundWake || autoWake) && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { item.state = 'observed'; item.observation = proof.evidence; } delete next.wakeReservation; diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index cc1bcff2..827cf4d3 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -45,7 +45,7 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); let state; try { state = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } const reservation = state?.wakeReservation; - if (result.error || result.status !== 0 || !['active', 'draining'].includes(state?.phase) || !reservation || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); + if (result.error || result.status !== 0 || !['active', 'draining'].includes(state?.phase) || !reservation || reservation.mode === 'auto-readback' || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); const { session, id: correlation, nativeQueueId: queueId, generation } = reservation; const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string'); if (items.length !== 1) throw new Error('wake item unavailable'); @@ -69,6 +69,44 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); } +// Read-only reconciliation of a submission consumed automatically by the native +// queue. A distinct reservation mode prevents racing an explicit queue/start. +export async function observeAutoCodexWake({ channel, thread, queueId, correlation, generation, graphState, evidenceRoot, apply }) { + if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || !Number.isSafeInteger(generation) || generation < 1 || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit auto wake identity required'); + await privateRoot(graphState); await privateRoot(evidenceRoot); + const session = `codex:${thread.toLowerCase()}`; + const getChannel = () => { + const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); + if (result.error || result.status !== 0) throw new Error('channel unavailable'); + let value; try { value = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } + return value; + }; + let state = getChannel(); + if (!state?.wakeReservation) { + const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId, '--source', 'auto-readback'], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (reserved.error || reserved.status !== 0) throw new Error('auto wake reservation unavailable or uncertain'); + state = getChannel(); + } + const reservation = state?.wakeReservation; + if (!['active', 'draining'].includes(state?.phase) || state.id !== channel || state.session !== session || state.generation !== generation || !reservation || reservation.mode !== 'auto-readback' || reservation.id !== correlation || reservation.session !== session || reservation.generation !== generation || reservation.nativeQueueId !== queueId) throw new Error('auto wake reservation mismatch'); + const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string' && Number.isSafeInteger(item.dispatchReservedAtMs) && item.dispatchReservedAtMs > 0); + if (items.length !== 1) throw new Error('auto wake item unavailable'); + const observed = await withCodexAppServer({ clientName: 'agent-mesh-auto-wake-readback', timeout: 30000, timeoutMessage: 'native read unavailable' }, request => request('thread/read', { threadId: thread.toLowerCase(), includeTurns: true })); + if (observed?.thread?.id !== thread.toLowerCase() || !Array.isArray(observed.thread.turns)) throw new Error('native read unavailable'); + const matching = []; + for (const turn of observed.thread.turns) { + if (!Array.isArray(turn.items) || (turn.itemsView !== undefined && turn.itemsView !== 'full')) throw new Error('incomplete native read'); + for (const item of turn.items) if (item?.type === 'userMessage' && item.clientId === correlation) matching.push({ turn, item }); + } + const candidate = matching[0]; + if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || !Number.isSafeInteger(candidate.item.startedAtMs) || candidate.item.startedAtMs < items[0].dispatchReservedAtMs || candidate.turn.startedAt * 1000 <= items[0].dispatchReservedAtMs || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('auto wake readback not uniquely verified'); + const evidence = { schema: 'agent-mesh.codex-wake-evidence.v5', source: 'codex-app-server.auto-start-bound-readback', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt, channel, generation, payloadSha256: hash(items[0].payload), dispatchReservedAtMs: items[0].dispatchReservedAtMs, itemStartedAtMs: candidate.item.startedAtMs }; + const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; + try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } + catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } + return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); +} + export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { if (typeof reference !== 'string' || !/^codex-wake:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid wake verification request'); await privateRoot(evidenceRoot); @@ -86,7 +124,8 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && ((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')); const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(value.source) && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); - if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + const auto = value && Object.keys(value).sort().join(',') === 'channel,correlation,dispatchReservedAtMs,generation,itemStartedAtMs,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v5' && value.source === 'codex-app-server.auto-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256) && Number.isSafeInteger(value.dispatchReservedAtMs) && value.dispatchReservedAtMs > 0 && Number.isSafeInteger(value.itemStartedAtMs) && value.itemStartedAtMs >= value.dispatchReservedAtMs && Number.isSafeInteger(value.startedAt) && value.startedAt * 1000 > value.dispatchReservedAtMs; + if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound || auto) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } @@ -149,9 +188,11 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { try { - const { values } = parseArgs({ options: { apply: { type: 'boolean' }, reconcile: { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, reconcile: { type: 'boolean' }, 'observe-auto': { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + if (values['observe-auto'] && (values.reconcile || values.verify || values.publish)) throw new Error('conflicting wake operations'); let result; - if (values.reconcile) result = await reconcileCodexWake({ channel: values.channel, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + if (values['observe-auto']) result = await observeAutoCodexWake({ channel: values.channel, thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + else if (values.reconcile) result = await reconcileCodexWake({ channel: values.channel, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); else if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'], channel: values.channel }); else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, channel: values.channel, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 3ce78418..1f21a08d 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -263,7 +263,9 @@ try { if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), channelInput); else if (subcommand === "begin-delivery") { if (values.generation !== undefined && !/^[1-9][0-9]*$/.test(values.generation)) throw new Error("invalid channel generation"); - next = beginDelivery(current, requiredSingleLine(values.id, "--id"), values.session === undefined ? undefined : requiredSingleLine(values.session, "--session"), values.generation === undefined ? undefined : Number(values.generation)); + const messageId = requiredSingleLine(values.id, "--id"); + next = beginDelivery(current, messageId, values.session === undefined ? undefined : requiredSingleLine(values.session, "--session"), values.generation === undefined ? undefined : Number(values.generation)); + next.queue.find(item => item.id === messageId).dispatchReservedAtMs = Date.now(); } else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); else if (subcommand === "reserve-wake") { @@ -272,7 +274,7 @@ try { const sourceId = `codex-wake-${createHash("sha256").update(JSON.stringify([session, queueId])).digest("hex")}`; const receiptId = createHash("sha256").update(sourceId).digest("hex"); if ((graph.lifecycleReceipts || []).some(item => item.id === receiptId) || (graph.channels || []).some(item => item.id !== name && item.wakeReservation?.session === session && item.wakeReservation?.nativeQueueId === queueId)) throw new Error("wake identity already reserved or recorded"); - next = reserveWake(current, requiredSingleLine(values.id, "--id"), session, Number(values.generation), queueId); + next = reserveWake(current, requiredSingleLine(values.id, "--id"), session, Number(values.generation), queueId, values.source === undefined ? 'start' : requiredSingleLine(values.source, '--source')); } else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; else if (subcommand === "reserve-notice") { From e514cc11afa4e58636f7ae97ddb2f34d5629bb18 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:19:56 +0000 Subject: [PATCH 090/113] Disable unproven automatic wake observations --- docs/design/plexus-architecture.mmd | 2 +- docs/design/plexus-channels.md | 11 +++-- packages/tmux-bridge/bin/channel-state.mjs | 7 ++- .../tmux-bridge/bin/codex-wake-evidence.mjs | 43 +++---------------- .../test/codex-wake-evidence.test.mjs | 28 ++++++------ scripts/plexus-diagram.mjs | 2 +- skills/agent-tmux/bin/channel-state.mjs | 7 ++- skills/agent-tmux/bin/codex-wake-evidence.mjs | 43 +++---------------- 8 files changed, 36 insertions(+), 107 deletions(-) diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 1a8dbf31..31b41889 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -27,6 +27,6 @@ flowchart LR Handover["Handover"] -. "planned verified cutover" .-> Channel Channel -. "pure switch model" .-> Drain["Observe queued deliveries"] Drain -. "then reserve" .-> Notice - AutoWake["Explicit auto-wake readback"] --> Wake + AutoWake["Auto-wake observation disabled"] -. "consumption unproven" .-> Wake Wake -. "bound native proof" .-> Drain ClaudeReadback["Local Claude transcript observer"] -. "observed inbox record" .-> Drain diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 90508c41..03835c19 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -260,9 +260,8 @@ observed a queued submission leave the queue and a turn start before an explicit queue/start call. Without model connectivity, the full turn readback did not expose a correlated user item in the observation window. The existing explicit-start producer refuses an empty queue and does not retry the start. -An explicit `--observe-auto` path reserves a distinct observation mode and -uses native full-turn readback to bind the queued client ID and exact payload. -It requires the turn start timestamp to be strictly later than the durable -dispatch reservation. Since native turn time has one-second precision, many -valid same-second starts remain unknown; they must never be counted as zero. -No waker invokes this path automatically and its live behavior is not qualified. +An isolated counterexample shows that a native turn may start with empty input +and then accept a steer with the same client ID and payload while the queued +submission is still pending. Therefore `--observe-auto` is disabled and v5 +proofs are rejected: readback alone does not establish queue consumption. +No waker invokes this path and a trustworthy consumption source is still needed. diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 275cc253..45cd4904 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -57,7 +57,7 @@ export function beginHandover(state) { // A reservation is durable and has no expiry: a crashed native call is unknown. export function reserveWake(state, id, session, generation, nativeQueueId, mode = 'start') { - if (!['start', 'auto-readback'].includes(mode) || !['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); + if (mode !== 'start' || !['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && !item.wakeEvidence && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); const next = copy(state); @@ -67,13 +67,12 @@ export function reserveWake(state, id, session, generation, nativeQueueId, mode export function settleWake(state, proof) { const reservation = state.wakeReservation; - if (!reservation || (proof?.source === 'codex-app-server.auto-start-bound-readback' ? reservation.mode !== 'auto-readback' : reservation.mode === 'auto-readback') || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + if (!reservation || (reservation.mode === 'auto-readback' || proof?.source === 'codex-app-server.auto-start-bound-readback') || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); if (!item) throw new Error('wake item unavailable'); item.wakeEvidence = proof.evidence; const boundWake = proof.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(proof.source); - const autoWake = proof.schema === 'agent-mesh.codex-wake-evidence.v5' && proof.source === 'codex-app-server.auto-start-bound-readback' && proof.dispatchReservedAtMs === item.dispatchReservedAtMs; - if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && (boundWake || autoWake) && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { + if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && boundWake && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { item.state = 'observed'; item.observation = proof.evidence; } delete next.wakeReservation; diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index 827cf4d3..5fafcabe 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -69,42 +69,10 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); } -// Read-only reconciliation of a submission consumed automatically by the native -// queue. A distinct reservation mode prevents racing an explicit queue/start. -export async function observeAutoCodexWake({ channel, thread, queueId, correlation, generation, graphState, evidenceRoot, apply }) { - if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || !Number.isSafeInteger(generation) || generation < 1 || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit auto wake identity required'); - await privateRoot(graphState); await privateRoot(evidenceRoot); - const session = `codex:${thread.toLowerCase()}`; - const getChannel = () => { - const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); - if (result.error || result.status !== 0) throw new Error('channel unavailable'); - let value; try { value = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } - return value; - }; - let state = getChannel(); - if (!state?.wakeReservation) { - const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId, '--source', 'auto-readback'], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); - if (reserved.error || reserved.status !== 0) throw new Error('auto wake reservation unavailable or uncertain'); - state = getChannel(); - } - const reservation = state?.wakeReservation; - if (!['active', 'draining'].includes(state?.phase) || state.id !== channel || state.session !== session || state.generation !== generation || !reservation || reservation.mode !== 'auto-readback' || reservation.id !== correlation || reservation.session !== session || reservation.generation !== generation || reservation.nativeQueueId !== queueId) throw new Error('auto wake reservation mismatch'); - const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string' && Number.isSafeInteger(item.dispatchReservedAtMs) && item.dispatchReservedAtMs > 0); - if (items.length !== 1) throw new Error('auto wake item unavailable'); - const observed = await withCodexAppServer({ clientName: 'agent-mesh-auto-wake-readback', timeout: 30000, timeoutMessage: 'native read unavailable' }, request => request('thread/read', { threadId: thread.toLowerCase(), includeTurns: true })); - if (observed?.thread?.id !== thread.toLowerCase() || !Array.isArray(observed.thread.turns)) throw new Error('native read unavailable'); - const matching = []; - for (const turn of observed.thread.turns) { - if (!Array.isArray(turn.items) || (turn.itemsView !== undefined && turn.itemsView !== 'full')) throw new Error('incomplete native read'); - for (const item of turn.items) if (item?.type === 'userMessage' && item.clientId === correlation) matching.push({ turn, item }); - } - const candidate = matching[0]; - if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || !Number.isSafeInteger(candidate.item.startedAtMs) || candidate.item.startedAtMs < items[0].dispatchReservedAtMs || candidate.turn.startedAt * 1000 <= items[0].dispatchReservedAtMs || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('auto wake readback not uniquely verified'); - const evidence = { schema: 'agent-mesh.codex-wake-evidence.v5', source: 'codex-app-server.auto-start-bound-readback', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt, channel, generation, payloadSha256: hash(items[0].payload), dispatchReservedAtMs: items[0].dispatchReservedAtMs, itemStartedAtMs: candidate.item.startedAtMs }; - const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; - try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } - catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } - return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); +// Disabled: a matching client ID can also come from a steer while the queued +// submission remains pending. Readback alone cannot prove queue consumption. +export async function observeAutoCodexWake() { + throw new Error('auto wake observation disabled: queue consumption is unproven'); } export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { @@ -124,8 +92,7 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && ((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')); const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(value.source) && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); - const auto = value && Object.keys(value).sort().join(',') === 'channel,correlation,dispatchReservedAtMs,generation,itemStartedAtMs,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v5' && value.source === 'codex-app-server.auto-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256) && Number.isSafeInteger(value.dispatchReservedAtMs) && value.dispatchReservedAtMs > 0 && Number.isSafeInteger(value.itemStartedAtMs) && value.itemStartedAtMs >= value.dispatchReservedAtMs && Number.isSafeInteger(value.startedAt) && value.startedAt * 1000 > value.dispatchReservedAtMs; - if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound || auto) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 776976fa..74a94532 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -1,5 +1,6 @@ import assert from 'node:assert/strict'; import { execFile } from 'node:child_process'; +import { createHash } from 'node:crypto'; import { appendFile, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; @@ -151,25 +152,22 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const drained = (await call('channel', 'get', '--name', 'drain')).channel; assert.equal(drained.queue[0].state, 'observed'); assert.equal(drained.wakeReservation, undefined); assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, callsBeforeRecovery); - // An auto-consumed queue item is reconciled by readback only, never started. + // Readback alone cannot distinguish a queued item from a steered message. const autoRoot = join(root, 'auto-proof'); await mkdir(autoRoot, { mode: 0o700 }); nativeId = 'queued-auto-proof'; await prepareChannel('auto-proof', nativeId); - autoReservedMs = (await call('channel', 'get', '--name', 'auto-proof')).channel.queue[0].dispatchReservedAtMs; - await new Promise(resolve => setTimeout(resolve, 1100)); // native turn timestamps have one-second precision const autoArgs = ['--observe-auto', '--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'auto-proof', '--generation', '1', '--evidence-root', autoRoot, '--graph-state', state]; - mode = 'wrong-client'; const autoStarts = requests.filter(r => r.method === 'thread/queue/start').length; + const callsBeforeAuto = requests.length; await assert.rejects(exec(process.execPath, [bin, '--apply', ...autoArgs], { env })); - assert.equal((await call('channel', 'get', '--name', 'auto-proof')).channel.wakeReservation.mode, 'auto-readback'); - await assert.rejects(exec(process.execPath, [bin, '--apply', '--reconcile', '--channel', 'auto-proof', '--evidence-root', autoRoot, '--graph-state', state], { env })); - mode = 'wrong-input'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...autoArgs], { env })); - mode = 'auto-old-turn'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...autoArgs], { env })); - mode = 'auto-same-second'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...autoArgs], { env })); - mode = 'success'; - const autoResult = JSON.parse((await exec(process.execPath, [bin, '--apply', ...autoArgs], { env })).stdout); - const autoProof = await verifyCodexWakeEvidence({ evidenceRoot: autoRoot, reference: autoResult.evidence, session }); - assert.equal(autoProof.source, 'codex-app-server.auto-start-bound-readback'); - assert.equal(autoProof.channel, 'auto-proof'); assert.equal(autoResult.settled, true); - assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, autoStarts); + assert.equal(requests.length, callsBeforeAuto); + const autoState = (await call('channel', 'get', '--name', 'auto-proof')).channel; + assert.equal(autoState.queue[0].state, 'accepted'); + assert.equal(autoState.wakeReservation, undefined); + assert.deepEqual(await readdir(autoRoot), []); + await assert.rejects(call('channel', 'reserve-wake', '--name', 'auto-proof', '--id', correlation, '--session', session, '--generation', '1', '--input', nativeId, '--source', 'auto-readback')); + const oldProof = { schema: 'agent-mesh.codex-wake-evidence.v5', source: 'codex-app-server.auto-start-bound-readback', session, queueId: nativeId, correlation, turn, startedAt: 123456789, channel: 'auto-proof', generation: 1, payloadSha256: createHash('sha256').update('fixture').digest('hex') }; + const oldBody = `${JSON.stringify(oldProof)}\n`, oldDigest = createHash('sha256').update(oldBody).digest('hex'); + await writeFile(join(autoRoot, `wake-${oldDigest}.json`), oldBody, { mode: 0o600 }); + await assert.rejects(verifyCodexWakeEvidence({ evidenceRoot: autoRoot, reference: `codex-wake:${oldDigest}`, session }), /identity mismatch/); const file = join(evidence, `wake-${first.evidence.slice('codex-wake:'.length)}.json`); const saved = JSON.parse(await readFile(file, 'utf8')); saved.startedAt++; await writeFile(file, `${JSON.stringify(saved)}\n`); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 7eef9271..71b46ac9 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -28,7 +28,7 @@ export const plexusDiagram = `flowchart LR Handover["Handover"] -. "planned verified cutover" .-> Channel Channel -. "pure switch model" .-> Drain["Observe queued deliveries"] Drain -. "then reserve" .-> Notice - AutoWake["Explicit auto-wake readback"] --> Wake + AutoWake["Auto-wake observation disabled"] -. "consumption unproven" .-> Wake Wake -. "bound native proof" .-> Drain ClaudeReadback["Local Claude transcript observer"] -. "observed inbox record" .-> Drain `; diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 275cc253..45cd4904 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -57,7 +57,7 @@ export function beginHandover(state) { // A reservation is durable and has no expiry: a crashed native call is unknown. export function reserveWake(state, id, session, generation, nativeQueueId, mode = 'start') { - if (!['start', 'auto-readback'].includes(mode) || !['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); + if (mode !== 'start' || !['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && !item.wakeEvidence && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); const next = copy(state); @@ -67,13 +67,12 @@ export function reserveWake(state, id, session, generation, nativeQueueId, mode export function settleWake(state, proof) { const reservation = state.wakeReservation; - if (!reservation || (proof?.source === 'codex-app-server.auto-start-bound-readback' ? reservation.mode !== 'auto-readback' : reservation.mode === 'auto-readback') || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + if (!reservation || (reservation.mode === 'auto-readback' || proof?.source === 'codex-app-server.auto-start-bound-readback') || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); if (!item) throw new Error('wake item unavailable'); item.wakeEvidence = proof.evidence; const boundWake = proof.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(proof.source); - const autoWake = proof.schema === 'agent-mesh.codex-wake-evidence.v5' && proof.source === 'codex-app-server.auto-start-bound-readback' && proof.dispatchReservedAtMs === item.dispatchReservedAtMs; - if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && (boundWake || autoWake) && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { + if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && boundWake && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { item.state = 'observed'; item.observation = proof.evidence; } delete next.wakeReservation; diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index 827cf4d3..5fafcabe 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -69,42 +69,10 @@ export async function reconcileCodexWake({ channel, graphState, evidenceRoot, ap return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); } -// Read-only reconciliation of a submission consumed automatically by the native -// queue. A distinct reservation mode prevents racing an explicit queue/start. -export async function observeAutoCodexWake({ channel, thread, queueId, correlation, generation, graphState, evidenceRoot, apply }) { - if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || !Number.isSafeInteger(generation) || generation < 1 || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit auto wake identity required'); - await privateRoot(graphState); await privateRoot(evidenceRoot); - const session = `codex:${thread.toLowerCase()}`; - const getChannel = () => { - const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); - if (result.error || result.status !== 0) throw new Error('channel unavailable'); - let value; try { value = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } - return value; - }; - let state = getChannel(); - if (!state?.wakeReservation) { - const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId, '--source', 'auto-readback'], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); - if (reserved.error || reserved.status !== 0) throw new Error('auto wake reservation unavailable or uncertain'); - state = getChannel(); - } - const reservation = state?.wakeReservation; - if (!['active', 'draining'].includes(state?.phase) || state.id !== channel || state.session !== session || state.generation !== generation || !reservation || reservation.mode !== 'auto-readback' || reservation.id !== correlation || reservation.session !== session || reservation.generation !== generation || reservation.nativeQueueId !== queueId) throw new Error('auto wake reservation mismatch'); - const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string' && Number.isSafeInteger(item.dispatchReservedAtMs) && item.dispatchReservedAtMs > 0); - if (items.length !== 1) throw new Error('auto wake item unavailable'); - const observed = await withCodexAppServer({ clientName: 'agent-mesh-auto-wake-readback', timeout: 30000, timeoutMessage: 'native read unavailable' }, request => request('thread/read', { threadId: thread.toLowerCase(), includeTurns: true })); - if (observed?.thread?.id !== thread.toLowerCase() || !Array.isArray(observed.thread.turns)) throw new Error('native read unavailable'); - const matching = []; - for (const turn of observed.thread.turns) { - if (!Array.isArray(turn.items) || (turn.itemsView !== undefined && turn.itemsView !== 'full')) throw new Error('incomplete native read'); - for (const item of turn.items) if (item?.type === 'userMessage' && item.clientId === correlation) matching.push({ turn, item }); - } - const candidate = matching[0]; - if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || !Number.isSafeInteger(candidate.item.startedAtMs) || candidate.item.startedAtMs < items[0].dispatchReservedAtMs || candidate.turn.startedAt * 1000 <= items[0].dispatchReservedAtMs || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('auto wake readback not uniquely verified'); - const evidence = { schema: 'agent-mesh.codex-wake-evidence.v5', source: 'codex-app-server.auto-start-bound-readback', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt, channel, generation, payloadSha256: hash(items[0].payload), dispatchReservedAtMs: items[0].dispatchReservedAtMs, itemStartedAtMs: candidate.item.startedAtMs }; - const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; - try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } - catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } - return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); +// Disabled: a matching client ID can also come from a steer while the queued +// submission remains pending. Readback alone cannot prove queue consumption. +export async function observeAutoCodexWake() { + throw new Error('auto wake observation disabled: queue consumption is unproven'); } export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { @@ -124,8 +92,7 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && ((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')); const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(value.source) && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); - const auto = value && Object.keys(value).sort().join(',') === 'channel,correlation,dispatchReservedAtMs,generation,itemStartedAtMs,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v5' && value.source === 'codex-app-server.auto-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256) && Number.isSafeInteger(value.dispatchReservedAtMs) && value.dispatchReservedAtMs > 0 && Number.isSafeInteger(value.itemStartedAtMs) && value.itemStartedAtMs >= value.dispatchReservedAtMs && Number.isSafeInteger(value.startedAt) && value.startedAt * 1000 > value.dispatchReservedAtMs; - if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound || auto) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } From 0c54ca48247dc6bc9e685a2ed5c524f52ecd94eb Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:25:56 +0000 Subject: [PATCH 091/113] Reject ambiguous wake recovery evidence --- docs/design/plexus-channels.md | 9 ++-- packages/tmux-bridge/bin/channel-state.mjs | 4 +- .../tmux-bridge/bin/codex-wake-evidence.mjs | 48 +++---------------- .../test/codex-wake-evidence.test.mjs | 30 ++++++------ skills/agent-tmux/bin/channel-state.mjs | 4 +- skills/agent-tmux/bin/codex-wake-evidence.mjs | 48 +++---------------- 6 files changed, 36 insertions(+), 107 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 03835c19..b0c0f3e2 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -233,10 +233,11 @@ generation, queue ID and correlation before starting it, then reads back the exact native message. When this proof is verified and settled in a draining channel, it marks that backlog message observed. Older proof schemas remain valid wake evidence but cannot establish this stronger delivery binding. -If a native start outcome is uncertain, the explicit readback-only recovery can -settle a draining reservation with a separately named bound-recovery source; -it never starts the queue again. This is not a cloud or Claude delivery adapter; -native cutover remains disabled. +If a native start outcome is uncertain, readback-only recovery is disabled: a +steered message can match while the submission remains queued. Recovery evidence +schemas v3 and v4 with the correlated-recovery source are rejected. Reservations +remain unresolved until an independently verified consumption source exists. +This is not a cloud or Claude delivery adapter; native cutover remains disabled. For a draining local Claude channel, `observe-claude-delivery` checks one managed inbox record in a stable local user transcript snapshot, binding its diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs index 45cd4904..4ae54186 100644 --- a/packages/tmux-bridge/bin/channel-state.mjs +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -67,11 +67,11 @@ export function reserveWake(state, id, session, generation, nativeQueueId, mode export function settleWake(state, proof) { const reservation = state.wakeReservation; - if (!reservation || (reservation.mode === 'auto-readback' || proof?.source === 'codex-app-server.auto-start-bound-readback') || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + if (!reservation || (reservation.mode === 'auto-readback' || ['codex-app-server.auto-start-bound-readback', 'codex-app-server.correlated-recovery', 'codex-app-server.correlated-recovery-bound'].includes(proof?.source)) || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); if (!item) throw new Error('wake item unavailable'); item.wakeEvidence = proof.evidence; - const boundWake = proof.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(proof.source); + const boundWake = proof.schema === 'agent-mesh.codex-wake-evidence.v4' && proof.source === 'codex-app-server.queue-start-bound-readback'; if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && boundWake && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { item.state = 'observed'; item.observation = proof.evidence; } diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index 5fafcabe..ba131171 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -27,46 +27,10 @@ async function createDurable(root, name, body) { try { await directory.sync(); } finally { await directory.close(); } } -async function readIntent(root, session, queueId, correlation) { - const path = join(root, `intent-${hash(JSON.stringify([session, queueId]))}.json`); - const fd = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); - try { - const before = await fd.stat(); - if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid intent'); - const body = await fd.readFile('utf8'), after = await fd.stat(), current = await lstat(path); - if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || body !== `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`) throw new Error('intent mismatch'); - } finally { await fd.close(); } -} - -// Reconcile only from a completed readback; never start or resume a thread. -export async function reconcileCodexWake({ channel, graphState, evidenceRoot, apply }) { - if (apply !== true || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit recovery scope required'); - await privateRoot(graphState); await privateRoot(evidenceRoot); - const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); - let state; try { state = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } - const reservation = state?.wakeReservation; - if (result.error || result.status !== 0 || !['active', 'draining'].includes(state?.phase) || !reservation || reservation.mode === 'auto-readback' || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); - const { session, id: correlation, nativeQueueId: queueId, generation } = reservation; - const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string'); - if (items.length !== 1) throw new Error('wake item unavailable'); - await readIntent(evidenceRoot, session, queueId, correlation); - const thread = session.slice(6); - const observed = await withCodexAppServer({ clientName: 'agent-mesh-wake-reconcile', timeout: 30000, timeoutMessage: 'native read unavailable' }, request => request('thread/read', { threadId: thread, includeTurns: true })); - if (observed?.thread?.id !== thread || !Array.isArray(observed.thread.turns)) throw new Error('native read unavailable'); - const matching = []; - for (const turn of observed.thread.turns) { - if (!Array.isArray(turn.items) || (turn.itemsView !== undefined && turn.itemsView !== 'full')) throw new Error('incomplete native read'); - for (const item of turn.items) if (item?.type === 'userMessage' && item.clientId === correlation) matching.push({ turn, item }); - } - const candidate = matching[0]; - if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('wake readback not uniquely verified'); - const evidence = state.phase === 'draining' - ? { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.correlated-recovery-bound', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt, channel, generation, payloadSha256: hash(items[0].payload) } - : { schema: 'agent-mesh.codex-wake-evidence.v3', source: 'codex-app-server.correlated-recovery', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt }; - const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; - try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } - catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } - return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); +// A readback can contain a steered message while the submission is still queued. +// Keep the durable reservation unresolved until queue consumption is provable. +export async function reconcileCodexWake() { + throw new Error('wake reconciliation disabled: queue consumption is unproven'); } // Disabled: a matching client ID can also come from a steer while the queued @@ -90,8 +54,8 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); let value; try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } - const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && ((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')); - const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(value.source) && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); + const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && (value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback'); + const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && value.source === 'codex-app-server.queue-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 74a94532..06ce3b4e 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -104,17 +104,14 @@ test('queued wake needs explicit apply, a native start and durable correlated pr assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, starts); const recoverArgs = ['--reconcile', '--channel', 'uncertain', '--evidence-root', uncertainRoot, '--graph-state', state]; await assert.rejects(exec(process.execPath, [bin, ...recoverArgs], { env })); - mode = 'wrong-client'; + const callsBeforeReconcile = requests.length; + mode = 'success'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...recoverArgs], { env })); + assert.equal(requests.length, callsBeforeReconcile); assert.ok((await call('channel', 'get', '--name', 'uncertain')).channel.wakeReservation); - mode = 'success'; - const recovered = JSON.parse((await exec(process.execPath, [bin, '--apply', ...recoverArgs], { env })).stdout); - assert.equal(recovered.settled, true); - assert.equal((await verifyCodexWakeEvidence({ evidenceRoot: uncertainRoot, reference: recovered.evidence, session })).source, 'codex-app-server.correlated-recovery'); assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, starts); - assert.equal((await call('channel', 'get', '--name', 'uncertain')).channel.wakeReservation, undefined); const uncertainFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); - assert.equal(uncertainFeed.events.filter(e => e.type === 'session.woken').length, 2); + assert.equal(uncertainFeed.events.filter(e => e.type === 'session.woken').length, 1); const partialRoot = join(root, 'partial'); await mkdir(partialRoot, { mode: 0o700 }); nativeId = 'queued-partial'; await prepareChannel('partial', nativeId); const partialArgs = ['--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'partial', '--generation', '1', '--evidence-root', partialRoot, '--graph-state', state]; @@ -122,7 +119,7 @@ test('queued wake needs explicit apply, a native start and durable correlated pr await assert.rejects(exec(process.execPath, [bin, '--apply', ...partialArgs], { env })); assert.deepEqual((await readdir(partialRoot)).map(name => name.split('-')[0]), ['intent']); const partialFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); - assert.equal(partialFeed.events.filter(e => e.type === 'session.woken').length, 2); + assert.equal(partialFeed.events.filter(e => e.type === 'session.woken').length, 1); for (const mismatch of ['wrong-thread', 'wrong-turn', 'wrong-time', 'wrong-client', 'wrong-input']) { const mismatchRoot = join(root, mismatch); await mkdir(mismatchRoot, { mode: 0o700 }); nativeId = `queued-${mismatch}`; await prepareChannel(mismatch, nativeId); @@ -132,7 +129,7 @@ test('queued wake needs explicit apply, a native start and durable correlated pr assert.deepEqual((await readdir(mismatchRoot)).map(name => name.split('-')[0]), ['intent']); } const mismatchFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); - assert.equal(mismatchFeed.events.filter(e => e.type === 'session.woken').length, 2); + assert.equal(mismatchFeed.events.filter(e => e.type === 'session.woken').length, 1); // Simulate persisted draining state only; no operational cutover is enabled. const drainRoot = join(root, 'drain'); await mkdir(drainRoot, { mode: 0o700 }); nativeId = 'queued-drain'; await prepareChannel('drain', nativeId); @@ -144,14 +141,17 @@ test('queued wake needs explicit apply, a native start and durable correlated pr mode = 'uncertain'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...drainArgs], { env })); const callsBeforeRecovery = requests.filter(r => r.method === 'thread/queue/start').length; mode = 'success'; - const drainResult = JSON.parse((await exec(process.execPath, [bin, '--apply', '--reconcile', '--channel', 'drain', '--evidence-root', drainRoot, '--graph-state', state], { env })).stdout); - const drainProof = await verifyCodexWakeEvidence({ evidenceRoot: drainRoot, reference: drainResult.evidence, session }); - assert.equal(drainProof.schema, 'agent-mesh.codex-wake-evidence.v4'); - assert.equal(drainProof.source, 'codex-app-server.correlated-recovery-bound'); - assert.equal(drainProof.channel, 'drain'); assert.equal(drainProof.generation, 1); + await assert.rejects(exec(process.execPath, [bin, '--apply', '--reconcile', '--channel', 'drain', '--evidence-root', drainRoot, '--graph-state', state], { env })); const drained = (await call('channel', 'get', '--name', 'drain')).channel; - assert.equal(drained.queue[0].state, 'observed'); assert.equal(drained.wakeReservation, undefined); + assert.equal(drained.queue[0].state, 'accepted'); assert.ok(drained.wakeReservation); assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, callsBeforeRecovery); + // Both unbound v3 and bound v4 recovery receipts fail closed, even with a valid digest. + for (const bound of [false, true]) { + const old = { schema: `agent-mesh.codex-wake-evidence.v${bound ? 4 : 3}`, source: `codex-app-server.correlated-recovery${bound ? '-bound' : ''}`, session, queueId: nativeId, correlation, turn, startedAt: 123456789, ...(bound ? { channel: 'drain', generation: 1, payloadSha256: createHash('sha256').update('fixture').digest('hex') } : {}) }; + const body = `${JSON.stringify(old)}\n`, digest = createHash('sha256').update(body).digest('hex'); + await writeFile(join(drainRoot, `wake-${digest}.json`), body, { mode: 0o600 }); + await assert.rejects(verifyCodexWakeEvidence({ evidenceRoot: drainRoot, reference: `codex-wake:${digest}`, session }), /identity mismatch/); + } // Readback alone cannot distinguish a queued item from a steered message. const autoRoot = join(root, 'auto-proof'); await mkdir(autoRoot, { mode: 0o700 }); nativeId = 'queued-auto-proof'; await prepareChannel('auto-proof', nativeId); diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs index 45cd4904..4ae54186 100644 --- a/skills/agent-tmux/bin/channel-state.mjs +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -67,11 +67,11 @@ export function reserveWake(state, id, session, generation, nativeQueueId, mode export function settleWake(state, proof) { const reservation = state.wakeReservation; - if (!reservation || (reservation.mode === 'auto-readback' || proof?.source === 'codex-app-server.auto-start-bound-readback') || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + if (!reservation || (reservation.mode === 'auto-readback' || ['codex-app-server.auto-start-bound-readback', 'codex-app-server.correlated-recovery', 'codex-app-server.correlated-recovery-bound'].includes(proof?.source)) || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); if (!item) throw new Error('wake item unavailable'); item.wakeEvidence = proof.evidence; - const boundWake = proof.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(proof.source); + const boundWake = proof.schema === 'agent-mesh.codex-wake-evidence.v4' && proof.source === 'codex-app-server.queue-start-bound-readback'; if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && boundWake && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { item.state = 'observed'; item.observation = proof.evidence; } diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index 5fafcabe..ba131171 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -27,46 +27,10 @@ async function createDurable(root, name, body) { try { await directory.sync(); } finally { await directory.close(); } } -async function readIntent(root, session, queueId, correlation) { - const path = join(root, `intent-${hash(JSON.stringify([session, queueId]))}.json`); - const fd = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); - try { - const before = await fd.stat(); - if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid intent'); - const body = await fd.readFile('utf8'), after = await fd.stat(), current = await lstat(path); - if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || body !== `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`) throw new Error('intent mismatch'); - } finally { await fd.close(); } -} - -// Reconcile only from a completed readback; never start or resume a thread. -export async function reconcileCodexWake({ channel, graphState, evidenceRoot, apply }) { - if (apply !== true || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit recovery scope required'); - await privateRoot(graphState); await privateRoot(evidenceRoot); - const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'get', '--name', channel], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); - let state; try { state = JSON.parse(result.stdout)?.channel; } catch { throw new Error('channel unavailable'); } - const reservation = state?.wakeReservation; - if (result.error || result.status !== 0 || !['active', 'draining'].includes(state?.phase) || !reservation || reservation.mode === 'auto-readback' || state.session !== reservation.session || state.generation !== reservation.generation || typeof reservation.session !== 'string' || !reservation.session.startsWith('codex:') || !UUID.test(reservation.session.slice(6)) || typeof reservation.id !== 'string' || !reservation.id.startsWith('waker-') || !UUID.test(reservation.id.slice(6)) || typeof reservation.nativeQueueId !== 'string' || !TOKEN.test(reservation.nativeQueueId)) throw new Error('wake reservation unavailable'); - const { session, id: correlation, nativeQueueId: queueId, generation } = reservation; - const items = state.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string'); - if (items.length !== 1) throw new Error('wake item unavailable'); - await readIntent(evidenceRoot, session, queueId, correlation); - const thread = session.slice(6); - const observed = await withCodexAppServer({ clientName: 'agent-mesh-wake-reconcile', timeout: 30000, timeoutMessage: 'native read unavailable' }, request => request('thread/read', { threadId: thread, includeTurns: true })); - if (observed?.thread?.id !== thread || !Array.isArray(observed.thread.turns)) throw new Error('native read unavailable'); - const matching = []; - for (const turn of observed.thread.turns) { - if (!Array.isArray(turn.items) || (turn.itemsView !== undefined && turn.itemsView !== 'full')) throw new Error('incomplete native read'); - for (const item of turn.items) if (item?.type === 'userMessage' && item.clientId === correlation) matching.push({ turn, item }); - } - const candidate = matching[0]; - if (matching.length !== 1 || typeof candidate.turn.id !== 'string' || !UUID.test(candidate.turn.id) || !Number.isSafeInteger(candidate.turn.startedAt) || candidate.turn.startedAt <= 0 || !['inProgress', 'completed', 'failed', 'interrupted'].includes(candidate.turn.status) || JSON.stringify(candidate.item.content) !== JSON.stringify([{ type: 'text', text: items[0].payload, text_elements: [] }])) throw new Error('wake readback not uniquely verified'); - const evidence = state.phase === 'draining' - ? { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.correlated-recovery-bound', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt, channel, generation, payloadSha256: hash(items[0].payload) } - : { schema: 'agent-mesh.codex-wake-evidence.v3', source: 'codex-app-server.correlated-recovery', session, queueId, correlation, turn: candidate.turn.id, startedAt: candidate.turn.startedAt }; - const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; - try { await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); } - catch (error) { if (error.code !== 'EEXIST') throw error; await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); } - return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); +// A readback can contain a steered message while the submission is still queued. +// Keep the durable reservation unresolved until queue consumption is provable. +export async function reconcileCodexWake() { + throw new Error('wake reconciliation disabled: queue consumption is unproven'); } // Disabled: a matching client ID can also come from a steer while the queued @@ -90,8 +54,8 @@ export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); let value; try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } - const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && ((value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback') || (value.schema === 'agent-mesh.codex-wake-evidence.v3' && value.source === 'codex-app-server.correlated-recovery')); - const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && ['codex-app-server.queue-start-bound-readback', 'codex-app-server.correlated-recovery-bound'].includes(value.source) && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); + const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && (value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback'); + const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && value.source === 'codex-app-server.queue-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); return { ...value, evidence: reference }; } From 0ada6a35d3e87a41bf5b71b99834b057626f830a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:40:59 +0000 Subject: [PATCH 092/113] Contain role MCP probes in a PID namespace --- docs/design/plexus-channels.md | 24 ++++++------ packages/tmux-bridge/bin/role-mcp-probe.mjs | 38 +++++++++++++++---- .../tmux-bridge/test/role-mcp-probe.test.mjs | 28 ++++++++++++++ skills/agent-tmux/bin/role-mcp-probe.mjs | 38 +++++++++++++++---- 4 files changed, 103 insertions(+), 25 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index b0c0f3e2..6935a80b 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -146,17 +146,19 @@ permission prompt, interrupted start, quota exhaustion and a queued message. It does not verify native delivery, rollback or the real pilot. An optional stdio probe resolves MCP names exclusively through a trusted -operator-supplied allowlist and launches a short-lived isolated process without -a shell. It requires an MCP initialization response and ping, bounds output -and time, and terminates its process group. It currently supports protocol -`2024-11-05` only and has been tested with synthetic processes; successful -probing does not prove that an MCP started in the successor session. It is not -scheduled or wired to the live handover. Planner deadlines signal cancellation; -the supplied stdio probe terminates its process group on that signal and waits -for the child close before reporting any result; failure to observe closure stops -the plan. Missing or invalid private probe configuration stops planning rather than -being classified as an unreachable MCP. Other probe implementations must -honor cancellation themselves; an unconfirmed cancellation stops the plan. +operator-supplied allowlist and launches without a shell. On Linux the probe +uses bubblewrap with a separate PID namespace and a blocked gate; it checks the +namespace init owner, parent and namespace identity before releasing the command. +It requires an MCP initialization response and ping, bounds output and time, +then terminates the owned process group and waits for wrapper closure. Missing +or unverified containment stops planning instead of classifying the MCP offline. +A synthetic detached-child test checks for a delayed local effect after closure. +This is not a security boundary: the authorized command retains its configured +filesystem and network access, and remote effects and all runtime environments +remain unverified. It supports protocol `2024-11-05` only; a successful probe +does not prove that an MCP started in the successor. It is not scheduled or +wired to live handover. Other probes must honor cancellation themselves; an +unconfirmed cancellation stops the plan. `codex-mcp-observation.mjs` prepares an opt-in, bounded app-server connection sample for a requested thread. It discards server names and endpoint data, fails diff --git a/packages/tmux-bridge/bin/role-mcp-probe.mjs b/packages/tmux-bridge/bin/role-mcp-probe.mjs index 6ef7b435..928b33e2 100644 --- a/packages/tmux-bridge/bin/role-mcp-probe.mjs +++ b/packages/tmux-bridge/bin/role-mcp-probe.mjs @@ -1,9 +1,23 @@ -/** Probe one operator-authorized stdio MCP in its own process group. */ +/** Probe one authorized stdio MCP in a verified PID namespace. */ import { spawn } from 'node:child_process'; +import { readFileSync, statSync } from 'node:fs'; import { isAbsolute } from 'node:path'; const configurationError = message => Object.assign(new Error(message), { code: 'MCP_PROBE_CONFIGURATION' }); +// The launcher is not an authorization boundary: the command is still trusted +// and retains the caller's filesystem and network access. Verify that bubblewrap +// created a separate PID namespace with an owned init before accepting a probe. +function verifyNamespace(raw, child) { + const info = JSON.parse(raw), pid = info?.['child-pid'], inode = info?.['pid-namespace']; + if (!Number.isSafeInteger(pid) || pid < 2 || !Number.isSafeInteger(inode) || !child.pid) throw new Error('invalid namespace identity'); + const path = `/proc/${pid}`, proc = statSync(path), ns = statSync(`${path}/ns/pid`); + const stat = readFileSync(`${path}/stat`, 'utf8').split(') ').at(-1).split(' '); + const status = readFileSync(`${path}/status`, 'utf8'); + const nested = status.match(/^NSpid:\s*(.*)$/m)?.[1].trim().split(/\s+/); + if (proc.uid !== process.getuid() || Number(stat[1]) !== child.pid || ns.ino !== inode || ns.ino === statSync('/proc/self/ns/pid').ino || nested?.at(-1) !== '1') throw new Error('namespace ownership unverified'); +} + export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw configurationError('invalid MCP allowlist'); return (name, { signal } = {}) => { @@ -19,24 +33,33 @@ export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal, spawnProcess = spawn }) { if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw configurationError('invalid MCP probe configuration'); return new Promise((resolve, reject) => { - let child, timer, reapTimer, buffer = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false; + let child, timer, reapTimer, buffer = '', info = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false, namespaceVerified = false, protocolReady = false; let onAbort; - const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); resolve(result); } }; + const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); if (!namespaceVerified) reject(configurationError('MCP probe containment unverified')); else resolve(result); } }; const finish = result => { if (finished) return; finished = true; desired = result; clearTimeout(timer); if (signal && onAbort) signal.removeEventListener('abort', onAbort); - if (child?.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } + if (!closed && child?.pid && child.exitCode == null && child.signalCode == null) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } if (!child || closed) done(child ? desired : false); else reapTimer = setTimeout(() => { if (!resolved) { resolved = true; reject(new Error('probe cancellation unconfirmed')); } }, 1000); }; - if (signal?.aborted) { finish(false); return; } - try { child = spawnProcess(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } + if (signal?.aborted) { resolved = true; resolve(false); return; } + try { child = spawnProcess('/usr/bin/bwrap', ['--info-fd', '3', '--block-fd', '4', '--die-with-parent', '--bind', '/', '/', '--proc', '/proc', '--dev-bind', '/dev', '/dev', '--unshare-pid', '--', ...command], { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore', 'pipe', 'pipe'], env }); } catch { finish(false); return; } timer = setTimeout(() => finish(false), timeoutMs); onAbort = () => finish(false); signal?.addEventListener('abort', onAbort, { once: true }); if (signal?.aborted) { finish(false); return; } + if (!child.stdio?.[3] || !child.stdio?.[4]) { finish(false); return; } + child.stdio[4].on('error', () => { if (!namespaceVerified) finish(false); }); + child.stdio[3].setEncoding('utf8'); + child.stdio[3].on('data', data => { info += data; if (Buffer.byteLength(info) > 8192) finish(false); }); + child.stdio[3].on('end', () => { + if (finished) return; + try { verifyNamespace(info, child); namespaceVerified = true; child.stdio[4].end('GO'); if (protocolReady) finish(true); } + catch { finish(false); } + }); child.once('error', () => finish(false)); child.once('close', () => { closed = true; if (!finished) finish(false); else done(desired); }); child.stdin.on('error', () => finish(false)); @@ -57,7 +80,8 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa write({ jsonrpc: '2.0', method: 'notifications/initialized' }); write({ jsonrpc: '2.0', id: 2, method: 'ping', params: {} }); } else if (phase === 'ping' && reply.id === 2) { - finish(!reply.error && !!reply.result && typeof reply.result === 'object' && !Array.isArray(reply.result)); + if (reply.error || !reply.result || typeof reply.result !== 'object' || Array.isArray(reply.result)) finish(false); + else { protocolReady = true; if (namespaceVerified) finish(true); } } else if (reply.id !== undefined) return finish(false); } }); diff --git a/packages/tmux-bridge/test/role-mcp-probe.test.mjs b/packages/tmux-bridge/test/role-mcp-probe.test.mjs index 144bb25d..84dce705 100644 --- a/packages/tmux-bridge/test/role-mcp-probe.test.mjs +++ b/packages/tmux-bridge/test/role-mcp-probe.test.mjs @@ -13,6 +13,7 @@ test('only an initialized and responsive MCP is accepted by role planning', asyn const offline = { command: [process.execPath, '--input-type=module', '-e', 'setInterval(() => {}, 1000)'], timeoutMs: 150 }; assert.equal(await probeStdioMcp(good), true); assert.equal(await probeStdioMcp(offline), false); + assert.equal(await probeStdioMcp({ command: ['/bin/false'], timeoutMs: 2000 }), false); const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['good', 'offline'], plugins: [] }; const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['good', 'offline'], plugins: [] }; const allowlist = { good, offline }; @@ -64,6 +65,7 @@ test('unobserved process closure fails planning instead of treating MCP as offli const child = new EventEmitter(); child.stdin = new EventEmitter(); child.stdin.write = () => true; child.stdout = new EventEmitter(); child.stdout.setEncoding = () => {}; + child.stdio = [child.stdin, child.stdout, null, new EventEmitter(), new EventEmitter()]; child.stdio[3].setEncoding = () => {}; child.stdio[4].end = () => {}; const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['stuck'], plugins: [] }; const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['stuck'], plugins: [] }; const probe = (_name, { signal }) => probeStdioMcp({ command: [process.execPath], timeoutMs: 5, signal, spawnProcess: () => child }); @@ -76,3 +78,29 @@ test('missing or invalid private MCP configuration stops planning', async () => await assert.rejects(planRoleLaunch({ profile, authority, probe: roleProbeFromAllowlist({}) }), /not allowlisted/); await assert.rejects(planRoleLaunch({ profile, authority, probe: roleProbeFromAllowlist({ wanted: { command: ['relative-program'] } }) }), /invalid MCP probe configuration/); }); + +test('the contained probe stops a detached descendant before returning', async t => { + const root = await mkdtemp(join(tmpdir(), 'mcp-contained-')); + t.after(() => rm(root, { recursive: true, force: true })); + const late = join(root, 'late'), started = join(root, 'started'); + const childCode = `require('node:fs').writeFileSync(process.argv[1], 'started'); setTimeout(() => require('node:fs').writeFileSync(process.argv[2], 'late'), 600); setInterval(() => {}, 1000)`; + const server = `const {spawn}=require('node:child_process'); const c=spawn(process.execPath,['-e',${JSON.stringify(childCode)},${JSON.stringify(started)},${JSON.stringify(late)}],{detached:true,stdio:'ignore'});c.unref(); let b='';process.stdin.on('data',d=>{b+=d;let n;while((n=b.indexOf('\\n'))>=0){const x=JSON.parse(b.slice(0,n));b=b.slice(n+1);if(x.method==='initialize')console.log(JSON.stringify({jsonrpc:'2.0',id:1,result:{protocolVersion:'2024-11-05',capabilities:{},serverInfo:{name:'fixture',version:'1'}}}));if(x.method==='ping'){const timer=setInterval(()=>{if(require('node:fs').existsSync(${JSON.stringify(started)})){clearInterval(timer);console.log(JSON.stringify({jsonrpc:'2.0',id:2,result:{}}));}},10);}}});`; + assert.equal(await probeStdioMcp({ command: [process.execPath, '-e', server], timeoutMs: 2000 }), true); + await access(started); + await new Promise(resolve => setTimeout(resolve, 900)); + await assert.rejects(access(late)); +}); + +test('unavailable namespace containment stops planning before command release', async () => { + const { EventEmitter } = await import('node:events'); + const child = new EventEmitter(); + child.stdin = new EventEmitter(); child.stdin.write = () => true; + child.stdout = new EventEmitter(); child.stdout.setEncoding = () => {}; + const info = new EventEmitter(); info.setEncoding = () => {}; + const gate = new EventEmitter(); let released = false; gate.end = () => { released = true; }; + child.stdio = [child.stdin, child.stdout, null, info, gate]; + const result = probeStdioMcp({ command: [process.execPath], timeoutMs: 1000, spawnProcess: () => child }); + queueMicrotask(() => { info.emit('data', '{}'); info.emit('end'); child.emit('close'); }); + await assert.rejects(result, error => error.code === 'MCP_PROBE_CONFIGURATION'); + assert.equal(released, false); +}); diff --git a/skills/agent-tmux/bin/role-mcp-probe.mjs b/skills/agent-tmux/bin/role-mcp-probe.mjs index 6ef7b435..928b33e2 100644 --- a/skills/agent-tmux/bin/role-mcp-probe.mjs +++ b/skills/agent-tmux/bin/role-mcp-probe.mjs @@ -1,9 +1,23 @@ -/** Probe one operator-authorized stdio MCP in its own process group. */ +/** Probe one authorized stdio MCP in a verified PID namespace. */ import { spawn } from 'node:child_process'; +import { readFileSync, statSync } from 'node:fs'; import { isAbsolute } from 'node:path'; const configurationError = message => Object.assign(new Error(message), { code: 'MCP_PROBE_CONFIGURATION' }); +// The launcher is not an authorization boundary: the command is still trusted +// and retains the caller's filesystem and network access. Verify that bubblewrap +// created a separate PID namespace with an owned init before accepting a probe. +function verifyNamespace(raw, child) { + const info = JSON.parse(raw), pid = info?.['child-pid'], inode = info?.['pid-namespace']; + if (!Number.isSafeInteger(pid) || pid < 2 || !Number.isSafeInteger(inode) || !child.pid) throw new Error('invalid namespace identity'); + const path = `/proc/${pid}`, proc = statSync(path), ns = statSync(`${path}/ns/pid`); + const stat = readFileSync(`${path}/stat`, 'utf8').split(') ').at(-1).split(' '); + const status = readFileSync(`${path}/status`, 'utf8'); + const nested = status.match(/^NSpid:\s*(.*)$/m)?.[1].trim().split(/\s+/); + if (proc.uid !== process.getuid() || Number(stat[1]) !== child.pid || ns.ino !== inode || ns.ino === statSync('/proc/self/ns/pid').ino || nested?.at(-1) !== '1') throw new Error('namespace ownership unverified'); +} + export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw configurationError('invalid MCP allowlist'); return (name, { signal } = {}) => { @@ -19,24 +33,33 @@ export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal, spawnProcess = spawn }) { if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw configurationError('invalid MCP probe configuration'); return new Promise((resolve, reject) => { - let child, timer, reapTimer, buffer = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false; + let child, timer, reapTimer, buffer = '', info = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false, namespaceVerified = false, protocolReady = false; let onAbort; - const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); resolve(result); } }; + const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); if (!namespaceVerified) reject(configurationError('MCP probe containment unverified')); else resolve(result); } }; const finish = result => { if (finished) return; finished = true; desired = result; clearTimeout(timer); if (signal && onAbort) signal.removeEventListener('abort', onAbort); - if (child?.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } + if (!closed && child?.pid && child.exitCode == null && child.signalCode == null) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } if (!child || closed) done(child ? desired : false); else reapTimer = setTimeout(() => { if (!resolved) { resolved = true; reject(new Error('probe cancellation unconfirmed')); } }, 1000); }; - if (signal?.aborted) { finish(false); return; } - try { child = spawnProcess(command[0], command.slice(1), { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore'], env }); } + if (signal?.aborted) { resolved = true; resolve(false); return; } + try { child = spawnProcess('/usr/bin/bwrap', ['--info-fd', '3', '--block-fd', '4', '--die-with-parent', '--bind', '/', '/', '--proc', '/proc', '--dev-bind', '/dev', '/dev', '--unshare-pid', '--', ...command], { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore', 'pipe', 'pipe'], env }); } catch { finish(false); return; } timer = setTimeout(() => finish(false), timeoutMs); onAbort = () => finish(false); signal?.addEventListener('abort', onAbort, { once: true }); if (signal?.aborted) { finish(false); return; } + if (!child.stdio?.[3] || !child.stdio?.[4]) { finish(false); return; } + child.stdio[4].on('error', () => { if (!namespaceVerified) finish(false); }); + child.stdio[3].setEncoding('utf8'); + child.stdio[3].on('data', data => { info += data; if (Buffer.byteLength(info) > 8192) finish(false); }); + child.stdio[3].on('end', () => { + if (finished) return; + try { verifyNamespace(info, child); namespaceVerified = true; child.stdio[4].end('GO'); if (protocolReady) finish(true); } + catch { finish(false); } + }); child.once('error', () => finish(false)); child.once('close', () => { closed = true; if (!finished) finish(false); else done(desired); }); child.stdin.on('error', () => finish(false)); @@ -57,7 +80,8 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa write({ jsonrpc: '2.0', method: 'notifications/initialized' }); write({ jsonrpc: '2.0', id: 2, method: 'ping', params: {} }); } else if (phase === 'ping' && reply.id === 2) { - finish(!reply.error && !!reply.result && typeof reply.result === 'object' && !Array.isArray(reply.result)); + if (reply.error || !reply.result || typeof reply.result !== 'object' || Array.isArray(reply.result)) finish(false); + else { protocolReady = true; if (namespaceVerified) finish(true); } } else if (reply.id !== undefined) return finish(false); } }); From 49a3520d610c18f8c0b6bb1e8c5722bcbd1014d4 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:46:14 +0000 Subject: [PATCH 093/113] Require an explicit permit before MCP probe execution --- docs/design/plexus-channels.md | 6 ++-- .../tmux-bridge/bin/role-mcp-exec-gate.py | 27 ++++++++++++++++ packages/tmux-bridge/bin/role-mcp-probe.mjs | 20 +++++++----- .../tmux-bridge/test/role-mcp-probe.test.mjs | 31 +++++++++++++++++++ skills/agent-tmux/bin/role-mcp-exec-gate.py | 27 ++++++++++++++++ skills/agent-tmux/bin/role-mcp-probe.mjs | 20 +++++++----- 6 files changed, 115 insertions(+), 16 deletions(-) create mode 100644 packages/tmux-bridge/bin/role-mcp-exec-gate.py create mode 100644 skills/agent-tmux/bin/role-mcp-exec-gate.py diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 6935a80b..b83b0639 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -147,8 +147,10 @@ It does not verify native delivery, rollback or the real pilot. An optional stdio probe resolves MCP names exclusively through a trusted operator-supplied allowlist and launches without a shell. On Linux the probe -uses bubblewrap with a separate PID namespace and a blocked gate; it checks the -namespace init owner, parent and namespace identity before releasing the command. +uses bubblewrap with a separate PID namespace and a strict stdin gate; it checks +the namespace init owner, parent and namespace identity before releasing the +command. The gate requires an explicit permit and rejects EOF or partial input; +a missing gate acknowledgement is a containment error, not an offline result. It requires an MCP initialization response and ping, bounds output and time, then terminates the owned process group and waits for wrapper closure. Missing or unverified containment stops planning instead of classifying the MCP offline. diff --git a/packages/tmux-bridge/bin/role-mcp-exec-gate.py b/packages/tmux-bridge/bin/role-mcp-exec-gate.py new file mode 100644 index 00000000..b3eddf44 --- /dev/null +++ b/packages/tmux-bridge/bin/role-mcp-exec-gate.py @@ -0,0 +1,27 @@ +#!/usr/bin/env python3 +"""Fail-closed stdin gate for an owned experimental MCP probe process.""" +import os +import sys + + +def main(argv): + if len(argv) < 2 or argv[0] != '--' or not os.path.isabs(argv[1]): + return 125 + permit = b'' + try: + while len(permit) < 3: + part = os.read(0, 3 - len(permit)) + if not part: + return 125 + permit += part + if permit != b'GO\n': + return 125 + os.write(1, b'{"agentMeshMcpGate":"released"}\n') + os.execv(argv[1], argv[1:]) + except OSError: + return 125 + return 125 + + +if __name__ == '__main__': + raise SystemExit(main(sys.argv[1:])) diff --git a/packages/tmux-bridge/bin/role-mcp-probe.mjs b/packages/tmux-bridge/bin/role-mcp-probe.mjs index 928b33e2..f2d56b3a 100644 --- a/packages/tmux-bridge/bin/role-mcp-probe.mjs +++ b/packages/tmux-bridge/bin/role-mcp-probe.mjs @@ -2,7 +2,9 @@ import { spawn } from 'node:child_process'; import { readFileSync, statSync } from 'node:fs'; import { isAbsolute } from 'node:path'; +import { fileURLToPath } from 'node:url'; +const gateProgram = fileURLToPath(new URL('./role-mcp-exec-gate.py', import.meta.url)); const configurationError = message => Object.assign(new Error(message), { code: 'MCP_PROBE_CONFIGURATION' }); // The launcher is not an authorization boundary: the command is still trusted @@ -33,9 +35,9 @@ export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal, spawnProcess = spawn }) { if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw configurationError('invalid MCP probe configuration'); return new Promise((resolve, reject) => { - let child, timer, reapTimer, buffer = '', info = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false, namespaceVerified = false, protocolReady = false; + let child, timer, reapTimer, buffer = '', info = '', phase = 'gate', finished = false, closed = false, desired = false, resolved = false, namespaceVerified = false, gateAcknowledged = false, protocolReady = false; let onAbort; - const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); if (!namespaceVerified) reject(configurationError('MCP probe containment unverified')); else resolve(result); } }; + const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); if (!namespaceVerified || !gateAcknowledged) reject(configurationError('MCP probe containment or gate unverified')); else resolve(result); } }; const finish = result => { if (finished) return; finished = true; desired = result; clearTimeout(timer); @@ -45,19 +47,18 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa else reapTimer = setTimeout(() => { if (!resolved) { resolved = true; reject(new Error('probe cancellation unconfirmed')); } }, 1000); }; if (signal?.aborted) { resolved = true; resolve(false); return; } - try { child = spawnProcess('/usr/bin/bwrap', ['--info-fd', '3', '--block-fd', '4', '--die-with-parent', '--bind', '/', '/', '--proc', '/proc', '--dev-bind', '/dev', '/dev', '--unshare-pid', '--', ...command], { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore', 'pipe', 'pipe'], env }); } + try { child = spawnProcess('/usr/bin/bwrap', ['--info-fd', '3', '--die-with-parent', '--bind', '/', '/', '--proc', '/proc', '--dev-bind', '/dev', '/dev', '--unshare-pid', '--', '/usr/bin/python3', '-B', gateProgram, '--', ...command], { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore', 'pipe'], env }); } catch { finish(false); return; } timer = setTimeout(() => finish(false), timeoutMs); onAbort = () => finish(false); signal?.addEventListener('abort', onAbort, { once: true }); if (signal?.aborted) { finish(false); return; } - if (!child.stdio?.[3] || !child.stdio?.[4]) { finish(false); return; } - child.stdio[4].on('error', () => { if (!namespaceVerified) finish(false); }); + if (!child.stdio?.[3]) { finish(false); return; } child.stdio[3].setEncoding('utf8'); child.stdio[3].on('data', data => { info += data; if (Buffer.byteLength(info) > 8192) finish(false); }); child.stdio[3].on('end', () => { if (finished) return; - try { verifyNamespace(info, child); namespaceVerified = true; child.stdio[4].end('GO'); if (protocolReady) finish(true); } + try { verifyNamespace(info, child); namespaceVerified = true; child.stdin.write('GO\n'); } catch { finish(false); } }); child.once('error', () => finish(false)); @@ -73,6 +74,12 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa while (!finished && (index = buffer.indexOf('\n')) >= 0) { const line = buffer.slice(0, index); buffer = buffer.slice(index + 1); let reply; try { reply = JSON.parse(line); } catch { return finish(false); } + if (phase === 'gate') { + if (!namespaceVerified || Object.keys(reply || {}).join(',') !== 'agentMeshMcpGate' || reply.agentMeshMcpGate !== 'released') return finish(false); + gateAcknowledged = true; phase = 'initialize'; + write({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'role-profile-probe', version: '1' } } }); + continue; + } if (reply?.jsonrpc !== '2.0') return finish(false); if (phase === 'initialize' && reply.id === 1) { if (reply.error || !reply.result || reply.result.protocolVersion !== '2024-11-05' || !reply.result.capabilities || typeof reply.result.capabilities !== 'object' || Array.isArray(reply.result.capabilities) || typeof reply.result.serverInfo?.name !== 'string' || !reply.result.serverInfo.name || typeof reply.result.serverInfo.version !== 'string' || !reply.result.serverInfo.version) return finish(false); @@ -85,6 +92,5 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa } else if (reply.id !== undefined) return finish(false); } }); - write({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'role-profile-probe', version: '1' } } }); }); } diff --git a/packages/tmux-bridge/test/role-mcp-probe.test.mjs b/packages/tmux-bridge/test/role-mcp-probe.test.mjs index 84dce705..d029600d 100644 --- a/packages/tmux-bridge/test/role-mcp-probe.test.mjs +++ b/packages/tmux-bridge/test/role-mcp-probe.test.mjs @@ -104,3 +104,34 @@ test('unavailable namespace containment stops planning before command release', await assert.rejects(result, error => error.code === 'MCP_PROBE_CONFIGURATION'); assert.equal(released, false); }); + +test('the execution gate rejects EOF, partial and invalid permits', async t => { + const { spawn } = await import('node:child_process'); + const { fileURLToPath } = await import('node:url'); + const root = await mkdtemp(join(tmpdir(), 'mcp-gate-')); + t.after(() => rm(root, { recursive: true, force: true })); + const gate = fileURLToPath(new URL('../bin/role-mcp-exec-gate.py', import.meta.url)); + const execute = (input, marker) => new Promise((resolve, reject) => { + const child = spawn('/usr/bin/python3', ['-B', gate, '--', '/usr/bin/touch', marker], { stdio: ['pipe', 'pipe', 'ignore'] }); + let output = ''; child.stdout.on('data', chunk => { output += chunk; }); + child.on('error', reject); child.on('close', code => resolve({ code, output })); + child.stdin.end(input); + }); + for (const input of ['', 'G', 'NO\n']) { + const marker = join(root, `no-${input.length}`); + const result = await execute(input, marker); + assert.equal(result.code, 125); assert.equal(result.output, ''); + await assert.rejects(access(marker)); + } + const marker = join(root, 'yes'); + const result = await execute('GO\n', marker); + assert.equal(result.code, 0); assert.equal(result.output, '{"agentMeshMcpGate":"released"}\n'); + await access(marker); +}); + +test('an already cancelled probe never starts a process', async () => { + const controller = new AbortController(); controller.abort(); + let spawned = false; + const result = await probeStdioMcp({ command: [process.execPath], signal: controller.signal, spawnProcess: () => { spawned = true; } }); + assert.equal(result, false); assert.equal(spawned, false); +}); diff --git a/skills/agent-tmux/bin/role-mcp-exec-gate.py b/skills/agent-tmux/bin/role-mcp-exec-gate.py new file mode 100644 index 00000000..b3eddf44 --- /dev/null +++ b/skills/agent-tmux/bin/role-mcp-exec-gate.py @@ -0,0 +1,27 @@ +#!/usr/bin/env python3 +"""Fail-closed stdin gate for an owned experimental MCP probe process.""" +import os +import sys + + +def main(argv): + if len(argv) < 2 or argv[0] != '--' or not os.path.isabs(argv[1]): + return 125 + permit = b'' + try: + while len(permit) < 3: + part = os.read(0, 3 - len(permit)) + if not part: + return 125 + permit += part + if permit != b'GO\n': + return 125 + os.write(1, b'{"agentMeshMcpGate":"released"}\n') + os.execv(argv[1], argv[1:]) + except OSError: + return 125 + return 125 + + +if __name__ == '__main__': + raise SystemExit(main(sys.argv[1:])) diff --git a/skills/agent-tmux/bin/role-mcp-probe.mjs b/skills/agent-tmux/bin/role-mcp-probe.mjs index 928b33e2..f2d56b3a 100644 --- a/skills/agent-tmux/bin/role-mcp-probe.mjs +++ b/skills/agent-tmux/bin/role-mcp-probe.mjs @@ -2,7 +2,9 @@ import { spawn } from 'node:child_process'; import { readFileSync, statSync } from 'node:fs'; import { isAbsolute } from 'node:path'; +import { fileURLToPath } from 'node:url'; +const gateProgram = fileURLToPath(new URL('./role-mcp-exec-gate.py', import.meta.url)); const configurationError = message => Object.assign(new Error(message), { code: 'MCP_PROBE_CONFIGURATION' }); // The launcher is not an authorization boundary: the command is still trusted @@ -33,9 +35,9 @@ export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal, spawnProcess = spawn }) { if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw configurationError('invalid MCP probe configuration'); return new Promise((resolve, reject) => { - let child, timer, reapTimer, buffer = '', info = '', phase = 'initialize', finished = false, closed = false, desired = false, resolved = false, namespaceVerified = false, protocolReady = false; + let child, timer, reapTimer, buffer = '', info = '', phase = 'gate', finished = false, closed = false, desired = false, resolved = false, namespaceVerified = false, gateAcknowledged = false, protocolReady = false; let onAbort; - const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); if (!namespaceVerified) reject(configurationError('MCP probe containment unverified')); else resolve(result); } }; + const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); if (!namespaceVerified || !gateAcknowledged) reject(configurationError('MCP probe containment or gate unverified')); else resolve(result); } }; const finish = result => { if (finished) return; finished = true; desired = result; clearTimeout(timer); @@ -45,19 +47,18 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa else reapTimer = setTimeout(() => { if (!resolved) { resolved = true; reject(new Error('probe cancellation unconfirmed')); } }, 1000); }; if (signal?.aborted) { resolved = true; resolve(false); return; } - try { child = spawnProcess('/usr/bin/bwrap', ['--info-fd', '3', '--block-fd', '4', '--die-with-parent', '--bind', '/', '/', '--proc', '/proc', '--dev-bind', '/dev', '/dev', '--unshare-pid', '--', ...command], { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore', 'pipe', 'pipe'], env }); } + try { child = spawnProcess('/usr/bin/bwrap', ['--info-fd', '3', '--die-with-parent', '--bind', '/', '/', '--proc', '/proc', '--dev-bind', '/dev', '/dev', '--unshare-pid', '--', '/usr/bin/python3', '-B', gateProgram, '--', ...command], { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore', 'pipe'], env }); } catch { finish(false); return; } timer = setTimeout(() => finish(false), timeoutMs); onAbort = () => finish(false); signal?.addEventListener('abort', onAbort, { once: true }); if (signal?.aborted) { finish(false); return; } - if (!child.stdio?.[3] || !child.stdio?.[4]) { finish(false); return; } - child.stdio[4].on('error', () => { if (!namespaceVerified) finish(false); }); + if (!child.stdio?.[3]) { finish(false); return; } child.stdio[3].setEncoding('utf8'); child.stdio[3].on('data', data => { info += data; if (Buffer.byteLength(info) > 8192) finish(false); }); child.stdio[3].on('end', () => { if (finished) return; - try { verifyNamespace(info, child); namespaceVerified = true; child.stdio[4].end('GO'); if (protocolReady) finish(true); } + try { verifyNamespace(info, child); namespaceVerified = true; child.stdin.write('GO\n'); } catch { finish(false); } }); child.once('error', () => finish(false)); @@ -73,6 +74,12 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa while (!finished && (index = buffer.indexOf('\n')) >= 0) { const line = buffer.slice(0, index); buffer = buffer.slice(index + 1); let reply; try { reply = JSON.parse(line); } catch { return finish(false); } + if (phase === 'gate') { + if (!namespaceVerified || Object.keys(reply || {}).join(',') !== 'agentMeshMcpGate' || reply.agentMeshMcpGate !== 'released') return finish(false); + gateAcknowledged = true; phase = 'initialize'; + write({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'role-profile-probe', version: '1' } } }); + continue; + } if (reply?.jsonrpc !== '2.0') return finish(false); if (phase === 'initialize' && reply.id === 1) { if (reply.error || !reply.result || reply.result.protocolVersion !== '2024-11-05' || !reply.result.capabilities || typeof reply.result.capabilities !== 'object' || Array.isArray(reply.result.capabilities) || typeof reply.result.serverInfo?.name !== 'string' || !reply.result.serverInfo.name || typeof reply.result.serverInfo.version !== 'string' || !reply.result.serverInfo.version) return finish(false); @@ -85,6 +92,5 @@ export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signa } else if (reply.id !== undefined) return finish(false); } }); - write({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'role-profile-probe', version: '1' } } }); }); } From 6452c315fd86c2ce9570bb1aeda9886bebee6492 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:49:33 +0000 Subject: [PATCH 094/113] Check namespace cleanup without host PID assumptions --- .../tmux-bridge/test/role-mcp-probe.test.mjs | 20 ++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/packages/tmux-bridge/test/role-mcp-probe.test.mjs b/packages/tmux-bridge/test/role-mcp-probe.test.mjs index d029600d..c8152eb0 100644 --- a/packages/tmux-bridge/test/role-mcp-probe.test.mjs +++ b/packages/tmux-bridge/test/role-mcp-probe.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { mkdtemp, access, readFile, rm } from 'node:fs/promises'; +import { mkdtemp, access, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { probeStdioMcp, roleProbeFromAllowlist } from '../bin/role-mcp-probe.mjs'; @@ -37,10 +37,8 @@ test('a cancelled probe terminates its temporary MCP process', async t => { try { await access(started); seen = true; } catch { await new Promise(resolve => setTimeout(resolve, 10)); } } assert.equal(seen, true, 'fixture process started'); - const pid = Number(await readFile(started, 'utf8')); controller.abort(); assert.equal(await probe, false); - assert.throws(() => process.kill(pid, 0), error => error.code === 'ESRCH'); await new Promise(resolve => setTimeout(resolve, 600)); await assert.rejects(access(late)); }); @@ -135,3 +133,19 @@ test('an already cancelled probe never starts a process', async () => { const result = await probeStdioMcp({ command: [process.execPath], signal: controller.signal, spawnProcess: () => { spawned = true; } }); assert.equal(result, false); assert.equal(spawned, false); }); + + +test('missing gate acknowledgement is a configuration error, not an offline MCP', async t => { + const { spawn } = await import('node:child_process'); + const root = await mkdtemp(join(tmpdir(), 'mcp-no-ack-')); + t.after(() => rm(root, { recursive: true, force: true })); + const fakeGate = join(root, 'no-ack.py'), marker = join(root, 'target-started'); + await writeFile(fakeGate, 'import os\nos.read(0, 3)\n'); + const spawnWithoutAcknowledgement = (command, args, options) => { + const modified = [...args], index = modified.findIndex(value => value.endsWith('/role-mcp-exec-gate.py')); + assert.notEqual(index, -1); modified[index] = fakeGate; + return spawn(command, modified, options); + }; + await assert.rejects(probeStdioMcp({ command: ['/usr/bin/touch', marker], timeoutMs: 2000, spawnProcess: spawnWithoutAcknowledgement }), error => error.code === 'MCP_PROBE_CONFIGURATION'); + await assert.rejects(access(marker)); +}); From 9374094a37ac3a0a938d971842279fe008c7464a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:53:40 +0000 Subject: [PATCH 095/113] Make offline probe fixture independent of startup timing --- packages/tmux-bridge/test/role-mcp-probe.test.mjs | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/packages/tmux-bridge/test/role-mcp-probe.test.mjs b/packages/tmux-bridge/test/role-mcp-probe.test.mjs index c8152eb0..aed61a52 100644 --- a/packages/tmux-bridge/test/role-mcp-probe.test.mjs +++ b/packages/tmux-bridge/test/role-mcp-probe.test.mjs @@ -9,16 +9,15 @@ import { planRoleLaunch } from '../bin/role-launch-profile.mjs'; const fixture = `let buffer = ''; process.stdin.setEncoding('utf8'); process.stdin.on('data', data => { buffer += data; let index; while ((index = buffer.indexOf('\\n')) >= 0) { const line = buffer.slice(0, index); buffer = buffer.slice(index + 1); const request = JSON.parse(line); if (request.method === 'initialize') console.log(JSON.stringify({jsonrpc:'2.0',id:1,result:{protocolVersion:'2024-11-05',capabilities:{},serverInfo:{name:'fixture',version:'1'}}})); if (request.method === 'ping') console.log(JSON.stringify({jsonrpc:'2.0',id:2,result:{}})); } });`; test('only an initialized and responsive MCP is accepted by role planning', async () => { - const good = { command: [process.execPath, '--input-type=module', '-e', fixture], timeoutMs: 2000 }; - const offline = { command: [process.execPath, '--input-type=module', '-e', 'setInterval(() => {}, 1000)'], timeoutMs: 150 }; + const good = { command: [process.execPath, '--input-type=module', '-e', fixture], timeoutMs: 5000 }; + const offline = { command: ['/bin/false'], timeoutMs: 5000 }; assert.equal(await probeStdioMcp(good), true); assert.equal(await probeStdioMcp(offline), false); - assert.equal(await probeStdioMcp({ command: ['/bin/false'], timeoutMs: 2000 }), false); const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['good', 'offline'], plugins: [] }; const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['good', 'offline'], plugins: [] }; const allowlist = { good, offline }; - const probe = roleProbeFromAllowlist(allowlist, 1000); - const plan = await planRoleLaunch({ profile, authority, probe, timeoutMs: 3000 }); + const probe = roleProbeFromAllowlist(allowlist, 3000); + const plan = await planRoleLaunch({ profile, authority, probe, timeoutMs: 5000 }); assert.deepEqual(plan.mcpToStart, ['good']); assert.deepEqual(plan.mcpUnavailable, ['offline']); assert.throws(() => probe('unlisted'), /allowlisted/); @@ -31,9 +30,9 @@ test('a cancelled probe terminates its temporary MCP process', async t => { const started = join(root, 'started'), late = join(root, 'late'); const code = "import {writeFileSync} from 'node:fs'; writeFileSync(process.argv[1], String(process.pid)); setTimeout(() => writeFileSync(process.argv[2], 'late'), 500); setInterval(() => {}, 1000);"; const controller = new AbortController(); - const probe = probeStdioMcp({ command: [process.execPath, '--input-type=module', '-e', code, started, late], timeoutMs: 2000, signal: controller.signal }); + const probe = probeStdioMcp({ command: [process.execPath, '--input-type=module', '-e', code, started, late], timeoutMs: 5000, signal: controller.signal }); let seen = false; - for (let i = 0; i < 100 && !seen; i++) { + for (let i = 0; i < 300 && !seen; i++) { try { await access(started); seen = true; } catch { await new Promise(resolve => setTimeout(resolve, 10)); } } assert.equal(seen, true, 'fixture process started'); @@ -83,7 +82,7 @@ test('the contained probe stops a detached descendant before returning', async t const late = join(root, 'late'), started = join(root, 'started'); const childCode = `require('node:fs').writeFileSync(process.argv[1], 'started'); setTimeout(() => require('node:fs').writeFileSync(process.argv[2], 'late'), 600); setInterval(() => {}, 1000)`; const server = `const {spawn}=require('node:child_process'); const c=spawn(process.execPath,['-e',${JSON.stringify(childCode)},${JSON.stringify(started)},${JSON.stringify(late)}],{detached:true,stdio:'ignore'});c.unref(); let b='';process.stdin.on('data',d=>{b+=d;let n;while((n=b.indexOf('\\n'))>=0){const x=JSON.parse(b.slice(0,n));b=b.slice(n+1);if(x.method==='initialize')console.log(JSON.stringify({jsonrpc:'2.0',id:1,result:{protocolVersion:'2024-11-05',capabilities:{},serverInfo:{name:'fixture',version:'1'}}}));if(x.method==='ping'){const timer=setInterval(()=>{if(require('node:fs').existsSync(${JSON.stringify(started)})){clearInterval(timer);console.log(JSON.stringify({jsonrpc:'2.0',id:2,result:{}}));}},10);}}});`; - assert.equal(await probeStdioMcp({ command: [process.execPath, '-e', server], timeoutMs: 2000 }), true); + assert.equal(await probeStdioMcp({ command: [process.execPath, '-e', server], timeoutMs: 5000 }), true); await access(started); await new Promise(resolve => setTimeout(resolve, 900)); await assert.rejects(access(late)); From e2edc3db362f4cc890ebd0355877638b56894a3b Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 00:11:53 +0000 Subject: [PATCH 096/113] Observe legacy Codex approval requests --- docs/design/plexus-channels.md | 3 +- .../bin/codex-mcp-startup-notifications.mjs | 10 ++-- .../codex-mcp-startup-notifications.test.mjs | 48 +++++++++++++++++++ .../bin/codex-mcp-startup-notifications.mjs | 10 ++-- 4 files changed, 62 insertions(+), 9 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index b83b0639..60817aa5 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -196,7 +196,8 @@ No live launch is wired to this planner. `codex-role-start-assessment.mjs` compares the complete native permission profile and sandbox objects against a trusted expected policy and flags observed -approval or elicitation requests for rollback. It does not perform rollback or +approval or elicitation requests for rollback, including the legacy Codex +approval requests identified by conversation ID. It does not perform rollback or prove that no prompt was missed. A matching response remains incomplete while plugin isolation, MCP event coverage and startup token evidence are unknown. The Codex CLI 0.169.0 generated schema says its `disabledPluginIds` response diff --git a/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs b/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs index 51657c25..5a85201d 100644 --- a/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs +++ b/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs @@ -1,7 +1,8 @@ /** Passive, bounded sampling of already delivered native startup notifications. */ const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; const statuses = new Set(['starting', 'ready', 'failed', 'cancelled']); -const permissionMethods = new Set(['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval', 'mcpServer/elicitation/request']); +const legacyApprovalMethods = new Set(['applyPatchApproval', 'execCommandApproval']); +const permissionMethods = new Set(['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval', 'mcpServer/elicitation/request', ...legacyApprovalMethods]); const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); // Attach before starting the thread. The native response can bind the thread @@ -14,10 +15,11 @@ export function createCodexMcpStartupObserver() { if (!permission && event?.method !== 'mcpServer/startupStatus/updated') return; const p = event.params; if (permission) { - if (!Object.hasOwn(event, 'id') || !p || typeof p.threadId !== 'string' || !uuid.test(p.threadId)) { invalid = true; return; } - if (threadId && p.threadId !== threadId) return; + const requestId = event.id, subject = legacyApprovalMethods.has(event.method) ? p?.conversationId : p?.threadId; + if (!(typeof requestId === 'string' || (typeof requestId === 'number' && Number.isFinite(requestId))) || typeof subject !== 'string' || !uuid.test(subject)) { invalid = true; return; } + if (threadId && subject !== threadId) return; if (buffered.length >= 4096) { invalid = true; return; } - buffered.push({ threadId: p.threadId, permission: true }); + buffered.push({ threadId: subject, permission: true }); return; } if (!p || typeof p.threadId !== 'string' || !uuid.test(p.threadId) || !validName(p.name) || !statuses.has(p.status)) { invalid = true; return; } diff --git a/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs b/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs index e14d3ef2..461e68c0 100644 --- a/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs +++ b/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs @@ -6,6 +6,7 @@ import { join } from 'node:path'; import { createAppServer } from './fixtures/fake-app-server.mjs'; import { withCodexAppServer } from '../bin/codex-app-server.mjs'; import { createCodexMcpStartupObserver } from '../bin/codex-mcp-startup-notifications.mjs'; +import { assessCodexRoleStart } from '../bin/codex-role-start-assessment.mjs'; const id = '22222222-2222-4222-8222-222222222222'; const other = '33333333-3333-4333-8333-333333333333'; @@ -76,3 +77,50 @@ test('a native permission request for the bound thread is observed without retai const empty = createCodexMcpStartupObserver(); empty.bindThread(id); assert.equal(empty.snapshot().permissionRequestObserved, null); }); + + +test('legacy approval requests bind by conversation and fail closed without leaking fields', () => { + for (const method of ['applyPatchApproval', 'execCommandApproval']) { + const observer = createCodexMcpStartupObserver(); + observer.onNotification({ id: 'legacy-request', method, params: { conversationId: id, reason: 'private-fixture' } }); + observer.bindThread(id); + const sample = observer.snapshot(); + assert.equal(sample.permissionRequestObserved, true); + assert.equal(sample.invalidOrOverflow, false); + const expected = { profile: { id: ':read-only', extends: null }, approvalPolicy: 'never', sandbox: { type: 'readOnly', networkAccess: false } }; + const response = { thread: { id }, activePermissionProfile: expected.profile, approvalPolicy: 'never', sandbox: expected.sandbox }; + const assessment = assessCodexRoleStart({ startResponse: response, sample, expected }); + assert.equal(assessment.status, 'rollback-required'); + assert.ok(assessment.failures.includes('unexpected-permission-request')); + assert.ok(!JSON.stringify(sample).includes('private-fixture')); + const otherObserver = createCodexMcpStartupObserver(); otherObserver.bindThread(id); + otherObserver.onNotification({ id: 0, method, params: { conversationId: other } }); + assert.equal(otherObserver.snapshot().permissionRequestObserved, null); + const malformed = createCodexMcpStartupObserver(); malformed.bindThread(id); + malformed.onNotification({ id: null, method, params: { conversationId: id } }); + assert.equal(malformed.snapshot().invalidOrOverflow, true); + } +}); + +test('app-server client forwards legacy approval requests without answering them', async t => { + const root = await mkdtemp(join(tmpdir(), 'legacy-approval-')), socket = join(root, 'test.sock'), received = []; + const server = createAppServer((msg, peer) => { + received.push(msg); + if (msg.method === 'initialize') peer.send({ id: msg.id, result: {} }); + else if (msg.method === 'thread/start') { + peer.send({ id: 'server-request', method: 'execCommandApproval', params: { conversationId: id, command: ['private-fixture'] } }); + peer.send({ id: msg.id, result: { thread: { id } } }); + } + }); + await new Promise((resolve, reject) => server.listen(socket, resolve).once('error', reject)); + const old = process.env.CODEX_REMOTE_SOCK; process.env.CODEX_REMOTE_SOCK = socket; + t.after(async () => { if (old === undefined) delete process.env.CODEX_REMOTE_SOCK; else process.env.CODEX_REMOTE_SOCK = old; await new Promise(resolve => server.close(resolve)); await rm(root, { recursive: true, force: true }); }); + const observer = createCodexMcpStartupObserver(); + const sample = await withCodexAppServer({ clientName: 'test', timeout: 3000, timeoutMessage: 'timeout', onNotification: observer.onNotification }, async request => { + const result = await request('thread/start', { ephemeral: true }); observer.bindThread(result.thread.id); + await new Promise(resolve => setTimeout(resolve, 30)); return observer.snapshot(); + }); + assert.equal(sample.permissionRequestObserved, true); + assert.ok(!received.some(msg => msg.id === 'server-request')); + assert.ok(!JSON.stringify(sample).includes('private-fixture')); +}); diff --git a/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs b/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs index 51657c25..5a85201d 100644 --- a/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs +++ b/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs @@ -1,7 +1,8 @@ /** Passive, bounded sampling of already delivered native startup notifications. */ const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; const statuses = new Set(['starting', 'ready', 'failed', 'cancelled']); -const permissionMethods = new Set(['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval', 'mcpServer/elicitation/request']); +const legacyApprovalMethods = new Set(['applyPatchApproval', 'execCommandApproval']); +const permissionMethods = new Set(['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval', 'mcpServer/elicitation/request', ...legacyApprovalMethods]); const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); // Attach before starting the thread. The native response can bind the thread @@ -14,10 +15,11 @@ export function createCodexMcpStartupObserver() { if (!permission && event?.method !== 'mcpServer/startupStatus/updated') return; const p = event.params; if (permission) { - if (!Object.hasOwn(event, 'id') || !p || typeof p.threadId !== 'string' || !uuid.test(p.threadId)) { invalid = true; return; } - if (threadId && p.threadId !== threadId) return; + const requestId = event.id, subject = legacyApprovalMethods.has(event.method) ? p?.conversationId : p?.threadId; + if (!(typeof requestId === 'string' || (typeof requestId === 'number' && Number.isFinite(requestId))) || typeof subject !== 'string' || !uuid.test(subject)) { invalid = true; return; } + if (threadId && subject !== threadId) return; if (buffered.length >= 4096) { invalid = true; return; } - buffered.push({ threadId: p.threadId, permission: true }); + buffered.push({ threadId: subject, permission: true }); return; } if (!p || typeof p.threadId !== 'string' || !uuid.test(p.threadId) || !validName(p.name) || !statuses.has(p.status)) { invalid = true; return; } From 4d67759341377b7202a30fe433f8c8fad8fe2ef1 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 00:23:16 +0000 Subject: [PATCH 097/113] Add opt-in isolated Codex rollback exercise --- docs/design/plexus-channels.md | 9 ++ .../scripts/test-isolation-regression.sh | 1 + .../test/codex-native-rollback.integration.py | 128 ++++++++++++++++++ 3 files changed, 138 insertions(+) create mode 100644 packages/tmux-bridge/test/codex-native-rollback.integration.py diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 60817aa5..0e2b705a 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -226,6 +226,15 @@ child that changes process group; neither case proves behavior for external services or other runtime configurations. The sandbox uses a read-only host filesystem with a private writable workspace and is for isolated fixtures only. +The optional `codex-native-rollback.integration.py` exercise accepts an absolute +Codex executable through `AGENT_MESH_TEST_CODEX_BIN`. It creates only temporary +state, two dedicated network-isolated app servers and synthetic MCP/provider +processes. A synthetic interactive approval request causes the test supervisor +to stop the successor namespace, then check that the predecessor accepts a new +turn. This does not wire rollback into handover, prove remote cleanup or permit +interactive approvals in a live role. Without the variable the test reports a +skip; an unavailable or incompatible runtime with the variable set is a failure. + The pure handover model separates switching to a successor from observing the messages queued before the switch, then reserving the final notice for the predecessor. Provider queue acceptance is not recipient observation. The diff --git a/packages/tmux-bridge/scripts/test-isolation-regression.sh b/packages/tmux-bridge/scripts/test-isolation-regression.sh index 0cb4637c..895d1667 100644 --- a/packages/tmux-bridge/scripts/test-isolation-regression.sh +++ b/packages/tmux-bridge/scripts/test-isolation-regression.sh @@ -65,6 +65,7 @@ python3 test/agent-waker.test.py python3 test/agent-waker-channel.test.py python3 test/namespace-exec-gate.test.py python3 test/isolated-pid-namespace.test.py +python3 -B test/codex-native-rollback.integration.py python3 test/session-controller.test.py python3 test/owner-notify.test.py scripts/socket-isolation-test.sh diff --git a/packages/tmux-bridge/test/codex-native-rollback.integration.py b/packages/tmux-bridge/test/codex-native-rollback.integration.py new file mode 100644 index 00000000..d1b18612 --- /dev/null +++ b/packages/tmux-bridge/test/codex-native-rollback.integration.py @@ -0,0 +1,128 @@ +#!/usr/bin/env python3 +"""Opt-in isolated Codex rollback integration test. Never uses live state.""" +import importlib.util, json, os, pathlib, selectors, subprocess, tempfile, time +base = pathlib.Path(__file__).resolve().parents[1] / 'bin' +spec = importlib.util.spec_from_file_location('owned', base / 'isolated-pid-namespace.py') +module = importlib.util.module_from_spec(spec) +spec.loader.exec_module(module) +binary = os.environ.get('AGENT_MESH_TEST_CODEX_BIN') +if not binary: + print('SKIP: set AGENT_MESH_TEST_CODEX_BIN to an absolute Codex binary path') + raise SystemExit(0) +if not os.path.isabs(binary) or not os.path.isfile(binary) or (not os.access(binary, os.X_OK)): + raise RuntimeError('test Codex binary must be an absolute executable file') + +class Client: + + def __init__(self, lease): + self.lease = lease + self.seq = 0 + self.buffer = b'' + self.events = [] + self.sel = selectors.DefaultSelector() + self.sel.register(lease.process.stdout, selectors.EVENT_READ) + + def write(self, entry): + self.lease.process.stdin.write((json.dumps(entry) + '\n').encode()) + self.lease.process.stdin.flush() + + def request(self, method, params, timeout=15): + self.seq += 1 + rid = self.seq + self.write({'id': rid, 'method': method, 'params': params}) + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + if b'\n' not in self.buffer: + if not self.sel.select(max(0, deadline - time.monotonic())): + break + data = os.read(self.lease.process.stdout.fileno(), 65536) + if not data: + break + self.buffer += data + while b'\n' in self.buffer: + line, self.buffer = self.buffer.split(b'\n', 1) + try: + row = json.loads(line) + except ValueError: + continue + if row.get('method'): + self.events.append(row) + continue + if row.get('id') == rid: + if 'error' in row: + raise RuntimeError('RPC error ' + str(row['error'].get('code'))) + return row['result'] + raise RuntimeError('RPC timeout') + + def init(self): + self.request('initialize', {'clientInfo': {'name': 'rollback-isolated', 'version': '1'}, 'capabilities': {'experimentalApi': True}}) + self.write({'method': 'initialized', 'params': {}}) +with tempfile.TemporaryDirectory(prefix='permission-rollback-isolated-') as td: + root = pathlib.Path(td) + (root / 'home').mkdir(mode=448) + for name in ['old', 'new']: + (root / name).mkdir(mode=448) + fixture = root / 'elicitation.py' + beat = root / 'heartbeat' + fixture.write_text('import json,sys,pathlib,threading,time\np=pathlib.Path(sys.argv[1])\ndef tick():\n n=0\n while True:\n n+=1;p.write_text(str(n));time.sleep(.1)\nthreading.Thread(target=tick,daemon=True).start()\nfor line in sys.stdin:\n try:req=json.loads(line)\n except:continue\n m=req.get("method")\n if m=="initialize":result={"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"fixture","version":"1"}}\n elif m=="tools/list":result={"tools":[]}\n elif m=="notifications/initialized":\n print(json.dumps({"jsonrpc":"2.0","id":"synthetic","method":"elicitation/create","params":{"message":"synthetic","requestedSchema":{"type":"object","properties":{}}}}),flush=True);continue\n else:continue\n if "id" in req:print(json.dumps({"jsonrpc":"2.0","id":req["id"],"result":result}),flush=True)\n') + (root / 'old' / 'config.toml').write_text('model_provider = "fixture"\nmodel = "fixture"\n[model_providers.fixture]\nname = "fixture"\nbase_url = "http://127.0.0.1:18765/v1"\nwire_api = "responses"\nrequires_openai_auth = false\n') + provider = root / 'provider.py' + provider.write_text('from http.server import HTTPServer,BaseHTTPRequestHandler\nfrom pathlib import Path\nclass H(BaseHTTPRequestHandler):\n def do_POST(self):\n self.rfile.read(int(self.headers.get("content-length",0)));Path(' + repr(str(root / 'provider-seen')) + ').write_text("seen");self.send_response(503);self.end_headers();self.wfile.write(b"{}")\n def log_message(self,*a):pass\nHTTPServer(("127.0.0.1",18765),H).serve_forever()\n') + launcher = root / 'launcher.py' + launcher.write_text('import os,subprocess,sys\nsubprocess.Popen([sys.executable,sys.argv[1]],stdin=subprocess.DEVNULL,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)\nos.execv(sys.argv[2],sys.argv[2:])\n') + (root / 'new' / 'config.toml').write_text('[mcp_servers.fixture]\ncommand = "/usr/bin/python3"\nargs = [' + json.dumps(str(fixture)) + ', ' + json.dumps(str(beat)) + ']\n') + + def open_server(name): + command = ['/usr/bin/env', 'HOME=' + str(root / 'home'), 'CODEX_HOME=' + str(root / name), 'PATH=/usr/bin:/bin'] + (['/usr/bin/python3', str(launcher), str(provider)] if name == 'old' else []) + [binary, 'app-server', '--listen', 'stdio://'] + lease = module.IsolatedNamespace.prepare(td, command) + leases.append(lease) + lease.release() + client = Client(lease) + client.init() + return (lease, client) + leases = [] + try: + old, oldc = open_server('old') + oldthread = oldc.request('thread/start', {'ephemeral': True, 'cwd': td, 'approvalPolicy': 'never', 'sandbox': 'read-only'})['thread']['id'] + new, newc = open_server('new') + started = newc.request('thread/start', {'ephemeral': True, 'cwd': td, 'approvalPolicy': 'on-request', 'sandbox': 'read-only'}) + newthread = started['thread']['id'] + deadline = time.monotonic() + 8 + req = None + while time.monotonic() < deadline: + newc.request('thread/loaded/list', {'limit': 100}) + req = next((x for x in newc.events if x.get('method') == 'mcpServer/elicitation/request' and x.get('params', {}).get('threadId') == newthread), None) + if req and beat.exists(): + break + time.sleep(0.1) + if not req or not beat.exists(): + raise RuntimeError('expected isolated elicitation unavailable') + js = "import {createCodexMcpStartupObserver} from OBS;import {assessCodexRoleStart} from ASSESS;const x=JSON.parse(await new Promise(r=>{let s='';process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>r(s))}));const o=createCodexMcpStartupObserver();o.onNotification(x.event);o.bindThread(x.started.thread.id);const expected={profile:{id:':read-only',extends:null},approvalPolicy:'never',sandbox:{type:'readOnly',networkAccess:false}};const a=assessCodexRoleStart({startResponse:x.started,sample:o.snapshot(),expected});console.log(JSON.stringify({status:a.status,failures:a.failures}));" + js = js.replace('OBS', json.dumps((base / 'codex-mcp-startup-notifications.mjs').as_uri())).replace('ASSESS', json.dumps((base / 'codex-role-start-assessment.mjs').as_uri())) + assessed = json.loads(subprocess.check_output(['/usr/bin/node', '--input-type=module', '-e', js], input=json.dumps({'started': started, 'event': req}).encode(), timeout=5)) + if assessed['status'] != 'rollback-required' or 'unexpected-permission-request' not in assessed['failures']: + raise RuntimeError('assessment did not require rollback') + first = beat.read_text() + time.sleep(0.35) + observed_before = beat.read_text() + if observed_before == first: + raise RuntimeError('fixture heartbeat was not active') + receipt = new.stop() + time.sleep(0.8) + observed_after = beat.read_text() + oldRead = oldc.request('thread/loaded/list', {'limit': 100}) + turn = oldc.request('turn/start', {'threadId': oldthread, 'input': [{'type': 'text', 'text': 'synthetic recovery check', 'text_elements': []}]}) + deadline = time.monotonic() + 3 + while time.monotonic() < deadline and (not (root / 'provider-seen').exists()): + time.sleep(0.05) + if turn.get('turn', {}).get('status') != 'inProgress' or not (root / 'provider-seen').exists(): + raise RuntimeError('predecessor did not accept isolated turn') + if observed_before != observed_after or oldthread not in oldRead.get('data', []): + raise RuntimeError('rollback isolation check failed') + if receipt.get('status') != 'init-exited': + raise RuntimeError('namespace init exit not verified') + print(json.dumps({'predecessorAcceptedNewTurn': turn.get('turn', {}).get('status') == 'inProgress', 'localProviderObserved': (root / 'provider-seen').exists(), 'isolatedNetwork': True, 'temporaryHome': True, 'realSuccessorElicitation': True, 'permissionResponseSent': False, 'assessment': assessed['status'], 'permissionFailure': True, 'namespaceStop': receipt, 'successorFixtureHeartbeatStopped': observed_before == observed_after, 'predecessorStillLoaded': oldthread in oldRead.get('data', []), 'syntheticSessionsOnly': True})) + finally: + for lease in reversed(leases): + if not lease._stopped: + lease.stop() From d12aa230c39b8d9c44331794b6507696a523d4ab Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 00:29:48 +0000 Subject: [PATCH 098/113] Connect isolated role assessment to owned rollback --- docs/design/plexus-architecture.mmd | 2 + docs/design/plexus-channels.md | 11 +++ .../tmux-bridge/bin/isolated-role-rollback.py | 55 +++++++++++++++ .../scripts/test-isolation-regression.sh | 1 + .../test/codex-native-rollback.integration.py | 13 +++- .../test/isolated-role-rollback.test.py | 70 +++++++++++++++++++ scripts/plexus-diagram.mjs | 2 + .../agent-tmux/bin/isolated-role-rollback.py | 55 +++++++++++++++ 8 files changed, 207 insertions(+), 2 deletions(-) create mode 100644 packages/tmux-bridge/bin/isolated-role-rollback.py create mode 100644 packages/tmux-bridge/test/isolated-role-rollback.test.py create mode 100644 skills/agent-tmux/bin/isolated-role-rollback.py diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd index 31b41889..63a9c4f8 100644 --- a/docs/design/plexus-architecture.mmd +++ b/docs/design/plexus-architecture.mmd @@ -15,6 +15,8 @@ flowchart LR 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"] diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 0e2b705a..5bf1e955 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -235,6 +235,17 @@ turn. This does not wire rollback into handover, prove remote cleanup or permit interactive approvals in a live role. Without the variable the test reports a skip; an unavailable or incompatible runtime with the variable set is a failure. +`isolated-role-rollback.py` connects a caller-bound Codex role assessment to +one stop of a caller-owned isolated successor. An incomplete assessment blocks +handover without stopping; an unsafe one records its stop attempt in memory +before the callback and does not retry an uncertain result in that process. A +crash loses this record, so recovery must not retry automatically. Even a +confirmed namespace init exit leaves descendant and remote effects unverified +and handover blocked. The +caller must authenticate the assessment and bind it to the correct native +connection and namespace lease; this primitive does not establish those facts, +move a channel, or provide a live rollback controller. + The pure handover model separates switching to a successor from observing the messages queued before the switch, then reserving the final notice for the predecessor. Provider queue acceptance is not recipient observation. The diff --git a/packages/tmux-bridge/bin/isolated-role-rollback.py b/packages/tmux-bridge/bin/isolated-role-rollback.py new file mode 100644 index 00000000..7f38afba --- /dev/null +++ b/packages/tmux-bridge/bin/isolated-role-rollback.py @@ -0,0 +1,55 @@ +#!/usr/bin/env python3 +"""Stop an owned isolated successor after an unsafe role-start assessment. + +This is an experimental, in-process coordinator, not a handover controller or +an authorization boundary. The caller must bind the assessment to the native +connection and the stop callback to that successor's owned namespace lease. +No channel, trigger, predecessor or remote state is changed here. +""" +import copy +import re +import threading + + +SESSION = re.compile(r'^codex:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$', re.I) + + +class IsolatedRoleRollback: + def __init__(self, expected_session, stop_owned_successor): + if not isinstance(expected_session, str) or not SESSION.fullmatch(expected_session) or not callable(stop_owned_successor): + raise ValueError('invalid isolated successor binding') + self._session = expected_session + self._stop = stop_owned_successor + self._lock = threading.Lock() + self._receipt = None + + def apply(self, assessment): + if (not isinstance(assessment, dict) or assessment.get('schema') != 'agent-mesh.codex-role-start-assessment.v1' + or assessment.get('session') != self._session or assessment.get('status') not in ('observed-incomplete', 'rollback-required') + or not isinstance(assessment.get('failures'), list) + or any(not isinstance(item, str) or not item for item in assessment['failures'])): + raise ValueError('invalid or mismatched role assessment') + if assessment['status'] == 'rollback-required' and not assessment['failures']: + raise ValueError('rollback requires a stated failure') + if assessment['status'] == 'observed-incomplete' and assessment['failures']: + raise ValueError('inconsistent incomplete assessment') + with self._lock: + if self._receipt is not None: + return copy.deepcopy(self._receipt) + if assessment['status'] == 'observed-incomplete': + return {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'blocked-incomplete', + 'session': self._session, 'handover': 'blocked'} + # Mark the attempt before invoking the callback: a lost response must + # never cause a second stop against an uncertain process identity. + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', + 'session': self._session, 'handover': 'blocked'} + try: + receipt = self._stop() + except Exception: + return copy.deepcopy(self._receipt) + if (isinstance(receipt, dict) and receipt.get('schema') == 'agent-mesh.isolated-namespace-stop.v1' + and receipt.get('status') == 'init-exited' and receipt.get('descendants') == 'unverified' + and receipt.get('remoteEffects') == 'unverified'): + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'local-init-exited', + 'session': self._session, 'handover': 'blocked', 'namespaceStop': copy.deepcopy(receipt)} + return copy.deepcopy(self._receipt) diff --git a/packages/tmux-bridge/scripts/test-isolation-regression.sh b/packages/tmux-bridge/scripts/test-isolation-regression.sh index 895d1667..3bab2634 100644 --- a/packages/tmux-bridge/scripts/test-isolation-regression.sh +++ b/packages/tmux-bridge/scripts/test-isolation-regression.sh @@ -65,6 +65,7 @@ python3 test/agent-waker.test.py python3 test/agent-waker-channel.test.py python3 test/namespace-exec-gate.test.py python3 test/isolated-pid-namespace.test.py +python3 -B test/isolated-role-rollback.test.py python3 -B test/codex-native-rollback.integration.py python3 test/session-controller.test.py python3 test/owner-notify.test.py diff --git a/packages/tmux-bridge/test/codex-native-rollback.integration.py b/packages/tmux-bridge/test/codex-native-rollback.integration.py index d1b18612..7ed592e3 100644 --- a/packages/tmux-bridge/test/codex-native-rollback.integration.py +++ b/packages/tmux-bridge/test/codex-native-rollback.integration.py @@ -5,6 +5,9 @@ spec = importlib.util.spec_from_file_location('owned', base / 'isolated-pid-namespace.py') module = importlib.util.module_from_spec(spec) spec.loader.exec_module(module) +rollback_spec = importlib.util.spec_from_file_location('isolated_rollback', base / 'isolated-role-rollback.py') +rollback_module = importlib.util.module_from_spec(rollback_spec) +rollback_spec.loader.exec_module(rollback_module) binary = os.environ.get('AGENT_MESH_TEST_CODEX_BIN') if not binary: print('SKIP: set AGENT_MESH_TEST_CODEX_BIN to an absolute Codex binary path') @@ -97,7 +100,7 @@ def open_server(name): time.sleep(0.1) if not req or not beat.exists(): raise RuntimeError('expected isolated elicitation unavailable') - js = "import {createCodexMcpStartupObserver} from OBS;import {assessCodexRoleStart} from ASSESS;const x=JSON.parse(await new Promise(r=>{let s='';process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>r(s))}));const o=createCodexMcpStartupObserver();o.onNotification(x.event);o.bindThread(x.started.thread.id);const expected={profile:{id:':read-only',extends:null},approvalPolicy:'never',sandbox:{type:'readOnly',networkAccess:false}};const a=assessCodexRoleStart({startResponse:x.started,sample:o.snapshot(),expected});console.log(JSON.stringify({status:a.status,failures:a.failures}));" + js = "import {createCodexMcpStartupObserver} from OBS;import {assessCodexRoleStart} from ASSESS;const x=JSON.parse(await new Promise(r=>{let s='';process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>r(s))}));const o=createCodexMcpStartupObserver();o.onNotification(x.event);o.bindThread(x.started.thread.id);const expected={profile:{id:':read-only',extends:null},approvalPolicy:'never',sandbox:{type:'readOnly',networkAccess:false}};const a=assessCodexRoleStart({startResponse:x.started,sample:o.snapshot(),expected});console.log(JSON.stringify(a));" js = js.replace('OBS', json.dumps((base / 'codex-mcp-startup-notifications.mjs').as_uri())).replace('ASSESS', json.dumps((base / 'codex-role-start-assessment.mjs').as_uri())) assessed = json.loads(subprocess.check_output(['/usr/bin/node', '--input-type=module', '-e', js], input=json.dumps({'started': started, 'event': req}).encode(), timeout=5)) if assessed['status'] != 'rollback-required' or 'unexpected-permission-request' not in assessed['failures']: @@ -107,7 +110,13 @@ def open_server(name): observed_before = beat.read_text() if observed_before == first: raise RuntimeError('fixture heartbeat was not active') - receipt = new.stop() + rollback = rollback_module.IsolatedRoleRollback('codex:' + newthread, new.stop) + decision = rollback.apply(assessed) + if decision['status'] != 'local-init-exited' or decision['handover'] != 'blocked': + raise RuntimeError('owned rollback did not verify namespace init exit') + if rollback.apply(assessed) != decision: + raise RuntimeError('replayed rollback changed its receipt') + receipt = decision['namespaceStop'] time.sleep(0.8) observed_after = beat.read_text() oldRead = oldc.request('thread/loaded/list', {'limit': 100}) diff --git a/packages/tmux-bridge/test/isolated-role-rollback.test.py b/packages/tmux-bridge/test/isolated-role-rollback.test.py new file mode 100644 index 00000000..73584beb --- /dev/null +++ b/packages/tmux-bridge/test/isolated-role-rollback.test.py @@ -0,0 +1,70 @@ +import importlib.util +from pathlib import Path +import threading +import unittest + + +BIN = Path(__file__).resolve().parents[1] / 'bin' +spec = importlib.util.spec_from_file_location('isolated_role_rollback', BIN / 'isolated-role-rollback.py') +module = importlib.util.module_from_spec(spec) +spec.loader.exec_module(module) +SESSION = 'codex:22222222-2222-4222-8222-222222222222' +ASSESSMENT = {'schema': 'agent-mesh.codex-role-start-assessment.v1', 'session': SESSION, + 'status': 'rollback-required', 'failures': ['unexpected-permission-request']} +STOP = {'schema': 'agent-mesh.isolated-namespace-stop.v1', 'status': 'init-exited', + 'descendants': 'unverified', 'remoteEffects': 'unverified'} + + +class IsolatedRoleRollbackTest(unittest.TestCase): + def test_incomplete_observation_keeps_handover_blocked_without_stop(self): + calls = [] + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True)) + assessment = {**ASSESSMENT, 'status': 'observed-incomplete', 'failures': []} + self.assertEqual(coordinator.apply(assessment)['status'], 'blocked-incomplete') + self.assertEqual(calls, []) + + def test_wrong_session_or_invalid_assessment_never_stops(self): + calls = [] + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True)) + for assessment in ({**ASSESSMENT, 'session': 'codex:33333333-3333-4333-8333-333333333333'}, + {**ASSESSMENT, 'failures': []}, {**ASSESSMENT, 'status': 'ready'}): + with self.assertRaises(ValueError): + coordinator.apply(assessment) + self.assertEqual(calls, []) + + def test_unsafe_assessment_stops_once_and_preserves_uncertainty(self): + calls = [] + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP) + first = coordinator.apply(ASSESSMENT) + self.assertEqual(first['status'], 'local-init-exited') + self.assertEqual(first['handover'], 'blocked') + self.assertEqual(first['namespaceStop']['descendants'], 'unverified') + first['namespaceStop']['status'] = 'altered' + self.assertEqual(coordinator.apply(ASSESSMENT)['namespaceStop']['status'], 'init-exited') + self.assertEqual(calls, [True]) + + def test_lost_or_invalid_stop_receipt_stays_uncertain_without_retry(self): + for stop in (lambda: (_ for _ in ()).throw(RuntimeError('lost')), lambda: {'status': 'ok'}): + calls = [] + def wrapped(): + calls.append(True) + return stop() + coordinator = module.IsolatedRoleRollback(SESSION, wrapped) + self.assertEqual(coordinator.apply(ASSESSMENT)['status'], 'stop-uncertain') + self.assertEqual(coordinator.apply(ASSESSMENT)['status'], 'stop-uncertain') + self.assertEqual(calls, [True]) + + def test_concurrent_assessments_do_not_repeat_stop(self): + calls, receipts = [], [] + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP) + threads = [threading.Thread(target=lambda: receipts.append(coordinator.apply(ASSESSMENT))) for _ in range(8)] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + self.assertEqual(calls, [True]) + self.assertEqual([receipt['status'] for receipt in receipts], ['local-init-exited'] * 8) + + +if __name__ == '__main__': + unittest.main() diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs index 71b46ac9..00ece577 100644 --- a/scripts/plexus-diagram.mjs +++ b/scripts/plexus-diagram.mjs @@ -16,6 +16,8 @@ export const plexusDiagram = `flowchart LR 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"] diff --git a/skills/agent-tmux/bin/isolated-role-rollback.py b/skills/agent-tmux/bin/isolated-role-rollback.py new file mode 100644 index 00000000..7f38afba --- /dev/null +++ b/skills/agent-tmux/bin/isolated-role-rollback.py @@ -0,0 +1,55 @@ +#!/usr/bin/env python3 +"""Stop an owned isolated successor after an unsafe role-start assessment. + +This is an experimental, in-process coordinator, not a handover controller or +an authorization boundary. The caller must bind the assessment to the native +connection and the stop callback to that successor's owned namespace lease. +No channel, trigger, predecessor or remote state is changed here. +""" +import copy +import re +import threading + + +SESSION = re.compile(r'^codex:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$', re.I) + + +class IsolatedRoleRollback: + def __init__(self, expected_session, stop_owned_successor): + if not isinstance(expected_session, str) or not SESSION.fullmatch(expected_session) or not callable(stop_owned_successor): + raise ValueError('invalid isolated successor binding') + self._session = expected_session + self._stop = stop_owned_successor + self._lock = threading.Lock() + self._receipt = None + + def apply(self, assessment): + if (not isinstance(assessment, dict) or assessment.get('schema') != 'agent-mesh.codex-role-start-assessment.v1' + or assessment.get('session') != self._session or assessment.get('status') not in ('observed-incomplete', 'rollback-required') + or not isinstance(assessment.get('failures'), list) + or any(not isinstance(item, str) or not item for item in assessment['failures'])): + raise ValueError('invalid or mismatched role assessment') + if assessment['status'] == 'rollback-required' and not assessment['failures']: + raise ValueError('rollback requires a stated failure') + if assessment['status'] == 'observed-incomplete' and assessment['failures']: + raise ValueError('inconsistent incomplete assessment') + with self._lock: + if self._receipt is not None: + return copy.deepcopy(self._receipt) + if assessment['status'] == 'observed-incomplete': + return {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'blocked-incomplete', + 'session': self._session, 'handover': 'blocked'} + # Mark the attempt before invoking the callback: a lost response must + # never cause a second stop against an uncertain process identity. + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', + 'session': self._session, 'handover': 'blocked'} + try: + receipt = self._stop() + except Exception: + return copy.deepcopy(self._receipt) + if (isinstance(receipt, dict) and receipt.get('schema') == 'agent-mesh.isolated-namespace-stop.v1' + and receipt.get('status') == 'init-exited' and receipt.get('descendants') == 'unverified' + and receipt.get('remoteEffects') == 'unverified'): + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'local-init-exited', + 'session': self._session, 'handover': 'blocked', 'namespaceStop': copy.deepcopy(receipt)} + return copy.deepcopy(self._receipt) From b51754ab3c0081b80756a7f1fc89cbf94595a746 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 00:36:26 +0000 Subject: [PATCH 099/113] Persist isolated rollback intent before stopping --- docs/design/plexus-channels.md | 16 +-- .../tmux-bridge/bin/isolated-role-rollback.py | 101 +++++++++++++--- .../test/codex-native-rollback.integration.py | 4 +- .../test/isolated-role-rollback.test.py | 108 +++++++++++++++++- .../agent-tmux/bin/isolated-role-rollback.py | 101 +++++++++++++--- 5 files changed, 277 insertions(+), 53 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 5bf1e955..9debf395 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -237,14 +237,14 @@ skip; an unavailable or incompatible runtime with the variable set is a failure. `isolated-role-rollback.py` connects a caller-bound Codex role assessment to one stop of a caller-owned isolated successor. An incomplete assessment blocks -handover without stopping; an unsafe one records its stop attempt in memory -before the callback and does not retry an uncertain result in that process. A -crash loses this record, so recovery must not retry automatically. Even a -confirmed namespace init exit leaves descendant and remote effects unverified -and handover blocked. The -caller must authenticate the assessment and bind it to the correct native -connection and namespace lease; this primitive does not establish those facts, -move a channel, or provide a live rollback controller. +handover without stopping; an unsafe one reserves a session-keyed intent in an +owned private journal and syncs it before the stop callback. A second coordinator +using that same journal refuses to retry after a crash or uncertain response; +results are recorded separately. Even a confirmed namespace init exit leaves +descendant and remote effects unverified and handover blocked. The caller must +use a stable journal root, authenticate the assessment and bind it to the correct +native connection and namespace lease; this primitive does not establish those +facts, move a channel, or provide a live rollback controller. The pure handover model separates switching to a successor from observing the messages queued before the switch, then reserving the final notice for the diff --git a/packages/tmux-bridge/bin/isolated-role-rollback.py b/packages/tmux-bridge/bin/isolated-role-rollback.py index 7f38afba..516df67e 100644 --- a/packages/tmux-bridge/bin/isolated-role-rollback.py +++ b/packages/tmux-bridge/bin/isolated-role-rollback.py @@ -1,25 +1,69 @@ #!/usr/bin/env python3 -"""Stop an owned isolated successor after an unsafe role-start assessment. +"""Crash-conservative stop of an owned isolated successor. -This is an experimental, in-process coordinator, not a handover controller or -an authorization boundary. The caller must bind the assessment to the native -connection and the stop callback to that successor's owned namespace lease. -No channel, trigger, predecessor or remote state is changed here. +This is not a handover controller or an authorization boundary. The caller +must bind the native assessment and owned stop callback to the same successor, +and consistently use the same private journal root for that session. """ import copy +import hashlib +import json +import os +from pathlib import Path import re +import stat import threading SESSION = re.compile(r'^codex:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$', re.I) +def _open_private_root(root): + if not isinstance(root, str) or not os.path.isabs(root) or str(Path(root).resolve(strict=True)) != root: + raise ValueError('journal root must be absolute and canonical') + before = os.lstat(root) + if not stat.S_ISDIR(before.st_mode) or before.st_uid != os.getuid() or before.st_mode & 0o077: + raise ValueError('journal root must be private and owned') + fd = os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW) + opened = os.fstat(fd) + if (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + os.close(fd) + raise ValueError('journal root changed') + return fd + + +def _verify_root(root, fd): + current = os.lstat(root) + opened = os.fstat(fd) + if (not stat.S_ISDIR(current.st_mode) or current.st_uid != os.getuid() or current.st_mode & 0o077 + or (current.st_dev, current.st_ino) != (opened.st_dev, opened.st_ino)): + raise ValueError('journal root changed') + + +def _write_once(directory_fd, name, record): + body = (json.dumps(record, separators=(',', ':'), sort_keys=True) + '\n').encode() + fd = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=directory_fd) + try: + view = memoryview(body) + while view: + written = os.write(fd, view) + if written <= 0: + raise OSError('journal write incomplete') + view = view[written:] + os.fsync(fd) + finally: + os.close(fd) + os.fsync(directory_fd) + + class IsolatedRoleRollback: - def __init__(self, expected_session, stop_owned_successor): - if not isinstance(expected_session, str) or not SESSION.fullmatch(expected_session) or not callable(stop_owned_successor): + def __init__(self, expected_session, stop_owned_successor, journal_root): + if not isinstance(expected_session, str) or not SESSION.fullmatch(expected_session) or expected_session != expected_session.lower() or not callable(stop_owned_successor): raise ValueError('invalid isolated successor binding') self._session = expected_session self._stop = stop_owned_successor + self._journal_root = journal_root + self._key = hashlib.sha256(expected_session.encode()).hexdigest() self._lock = threading.Lock() self._receipt = None @@ -39,17 +83,36 @@ def apply(self, assessment): if assessment['status'] == 'observed-incomplete': return {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'blocked-incomplete', 'session': self._session, 'handover': 'blocked'} - # Mark the attempt before invoking the callback: a lost response must - # never cause a second stop against an uncertain process identity. - self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', - 'session': self._session, 'handover': 'blocked'} + directory_fd = _open_private_root(self._journal_root) try: - receipt = self._stop() - except Exception: + intent = {'schema': 'agent-mesh.isolated-role-stop-intent.v1', 'session': self._session} + try: + _write_once(directory_fd, f'stop-{self._key}.intent.json', intent) + except FileExistsError: + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', + 'session': self._session, 'handover': 'blocked'} + return copy.deepcopy(self._receipt) + _verify_root(self._journal_root, directory_fd) + # Persist and fsync the attempt before the side effect. Never retry + # automatically after a crash or an ambiguous callback result. + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', + 'session': self._session, 'handover': 'blocked'} + try: + receipt = self._stop() + except Exception: + receipt = None + result = copy.deepcopy(self._receipt) + if (isinstance(receipt, dict) and receipt.get('schema') == 'agent-mesh.isolated-namespace-stop.v1' + and receipt.get('status') == 'init-exited' and receipt.get('descendants') == 'unverified' + and receipt.get('remoteEffects') == 'unverified'): + result = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'local-init-exited', + 'session': self._session, 'handover': 'blocked', + 'namespaceStop': {key: receipt[key] for key in ('schema', 'status', 'descendants', 'remoteEffects')}} + try: + _write_once(directory_fd, f'stop-{self._key}.result.json', result) + except OSError: + return copy.deepcopy(self._receipt) + self._receipt = result return copy.deepcopy(self._receipt) - if (isinstance(receipt, dict) and receipt.get('schema') == 'agent-mesh.isolated-namespace-stop.v1' - and receipt.get('status') == 'init-exited' and receipt.get('descendants') == 'unverified' - and receipt.get('remoteEffects') == 'unverified'): - self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'local-init-exited', - 'session': self._session, 'handover': 'blocked', 'namespaceStop': copy.deepcopy(receipt)} - return copy.deepcopy(self._receipt) + finally: + os.close(directory_fd) diff --git a/packages/tmux-bridge/test/codex-native-rollback.integration.py b/packages/tmux-bridge/test/codex-native-rollback.integration.py index 7ed592e3..08509444 100644 --- a/packages/tmux-bridge/test/codex-native-rollback.integration.py +++ b/packages/tmux-bridge/test/codex-native-rollback.integration.py @@ -110,7 +110,9 @@ def open_server(name): observed_before = beat.read_text() if observed_before == first: raise RuntimeError('fixture heartbeat was not active') - rollback = rollback_module.IsolatedRoleRollback('codex:' + newthread, new.stop) + journal = root / 'rollback-journal' + journal.mkdir(mode=0o700) + rollback = rollback_module.IsolatedRoleRollback('codex:' + newthread, new.stop, str(journal)) decision = rollback.apply(assessed) if decision['status'] != 'local-init-exited' or decision['handover'] != 'blocked': raise RuntimeError('owned rollback did not verify namespace init exit') diff --git a/packages/tmux-bridge/test/isolated-role-rollback.test.py b/packages/tmux-bridge/test/isolated-role-rollback.test.py index 73584beb..d58f3f89 100644 --- a/packages/tmux-bridge/test/isolated-role-rollback.test.py +++ b/packages/tmux-bridge/test/isolated-role-rollback.test.py @@ -1,6 +1,13 @@ import importlib.util +import hashlib +import json from pathlib import Path import threading +import tempfile +import os +import subprocess +import sys +from unittest.mock import patch import unittest @@ -16,16 +23,23 @@ class IsolatedRoleRollbackTest(unittest.TestCase): + def setUp(self): + self.directory = tempfile.TemporaryDirectory(prefix='rollback-journal-test-') + self.addCleanup(self.directory.cleanup) + self.root = self.directory.name + def test_incomplete_observation_keeps_handover_blocked_without_stop(self): calls = [] - coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True)) + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True), self.root) assessment = {**ASSESSMENT, 'status': 'observed-incomplete', 'failures': []} self.assertEqual(coordinator.apply(assessment)['status'], 'blocked-incomplete') self.assertEqual(calls, []) def test_wrong_session_or_invalid_assessment_never_stops(self): + with self.assertRaises(ValueError): + module.IsolatedRoleRollback(SESSION.upper(), lambda: STOP, self.root) calls = [] - coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True)) + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True), self.root) for assessment in ({**ASSESSMENT, 'session': 'codex:33333333-3333-4333-8333-333333333333'}, {**ASSESSMENT, 'failures': []}, {**ASSESSMENT, 'status': 'ready'}): with self.assertRaises(ValueError): @@ -34,7 +48,7 @@ def test_wrong_session_or_invalid_assessment_never_stops(self): def test_unsafe_assessment_stops_once_and_preserves_uncertainty(self): calls = [] - coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP) + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) first = coordinator.apply(ASSESSMENT) self.assertEqual(first['status'], 'local-init-exited') self.assertEqual(first['handover'], 'blocked') @@ -43,20 +57,32 @@ def test_unsafe_assessment_stops_once_and_preserves_uncertainty(self): self.assertEqual(coordinator.apply(ASSESSMENT)['namespaceStop']['status'], 'init-exited') self.assertEqual(calls, [True]) + def test_persisted_receipts_exclude_extra_callback_fields(self): + coordinator = module.IsolatedRoleRollback(SESSION, lambda: {**STOP, 'extra': 'private-fixture'}, self.root) + receipt = coordinator.apply(ASSESSMENT) + key = hashlib.sha256(SESSION.encode()).hexdigest() + intent = json.loads((Path(self.root) / f'stop-{key}.intent.json').read_text()) + saved = json.loads((Path(self.root) / f'stop-{key}.result.json').read_text()) + self.assertEqual(intent['session'], SESSION) + self.assertEqual(saved, receipt) + self.assertNotIn('private-fixture', json.dumps(saved)) + def test_lost_or_invalid_stop_receipt_stays_uncertain_without_retry(self): - for stop in (lambda: (_ for _ in ()).throw(RuntimeError('lost')), lambda: {'status': 'ok'}): + for index, stop in enumerate((lambda: (_ for _ in ()).throw(RuntimeError('lost')), lambda: {'status': 'ok'})): + root = Path(self.root) / str(index) + root.mkdir(mode=0o700) calls = [] def wrapped(): calls.append(True) return stop() - coordinator = module.IsolatedRoleRollback(SESSION, wrapped) + coordinator = module.IsolatedRoleRollback(SESSION, wrapped, str(root)) self.assertEqual(coordinator.apply(ASSESSMENT)['status'], 'stop-uncertain') self.assertEqual(coordinator.apply(ASSESSMENT)['status'], 'stop-uncertain') self.assertEqual(calls, [True]) def test_concurrent_assessments_do_not_repeat_stop(self): calls, receipts = [], [] - coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP) + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) threads = [threading.Thread(target=lambda: receipts.append(coordinator.apply(ASSESSMENT))) for _ in range(8)] for thread in threads: thread.start() @@ -66,5 +92,75 @@ def test_concurrent_assessments_do_not_repeat_stop(self): self.assertEqual([receipt['status'] for receipt in receipts], ['local-init-exited'] * 8) + def test_distinct_coordinators_share_a_single_durable_reservation(self): + calls, receipts = [], [] + coordinators = [module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) for _ in range(8)] + threads = [threading.Thread(target=lambda c=c: receipts.append(c.apply(ASSESSMENT))) for c in coordinators] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + self.assertEqual(calls, [True]) + self.assertEqual(sum(item['status'] == 'local-init-exited' for item in receipts), 1) + self.assertTrue(all(item['handover'] == 'blocked' for item in receipts)) + + def test_process_death_after_reservation_blocks_retry(self): + path = str(BIN / 'isolated-role-rollback.py') + code = "import importlib.util,json,os,sys;spec=importlib.util.spec_from_file_location('r',sys.argv[1]);m=importlib.util.module_from_spec(spec);spec.loader.exec_module(m);c=m.IsolatedRoleRollback(sys.argv[2],lambda:os._exit(43),sys.argv[3]);c.apply(json.loads(sys.argv[4]))" + result = subprocess.run([sys.executable, '-B', '-c', code, path, SESSION, self.root, json.dumps(ASSESSMENT)], timeout=5) + self.assertEqual(result.returncode, 43) + calls = [] + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + self.assertEqual(coordinator.apply(ASSESSMENT)['status'], 'stop-uncertain') + self.assertEqual(calls, []) + + def test_unwritable_or_invalid_journal_never_invokes_stop(self): + calls = [] + os.chmod(self.root, 0o755) + try: + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + with self.assertRaises(ValueError): + coordinator.apply(ASSESSMENT) + finally: + os.chmod(self.root, 0o700) + self.assertEqual(calls, []) + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + with patch.object(module, '_write_once', side_effect=OSError('intent unavailable')): + with self.assertRaises(OSError): + coordinator.apply(ASSESSMENT) + self.assertEqual(calls, []) + + def test_replaced_journal_root_blocks_before_stop(self): + root = Path(self.root) / 'journal' + root.mkdir(mode=0o700) + renamed = Path(self.root) / 'renamed' + original = module._write_once + calls = [] + def replace_after_reservation(directory_fd, name, value): + original(directory_fd, name, value) + root.rename(renamed) + root.mkdir(mode=0o700) + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, str(root)) + with patch.object(module, '_write_once', side_effect=replace_after_reservation): + with self.assertRaisesRegex(ValueError, 'root changed'): + coordinator.apply(ASSESSMENT) + self.assertEqual(calls, []) + self.assertEqual(len(list(renamed.glob('*.intent.json'))), 1) + + def test_lost_result_persistence_remains_uncertain_without_retry(self): + calls = [] + original = module._write_once + def write(directory_fd, name, value): + if name.endswith('.result.json'): + raise OSError('result unavailable') + return original(directory_fd, name, value) + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + with patch.object(module, '_write_once', side_effect=write): + self.assertEqual(coordinator.apply(ASSESSMENT)['status'], 'stop-uncertain') + restarted = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + self.assertEqual(restarted.apply(ASSESSMENT)['status'], 'stop-uncertain') + self.assertEqual(calls, [True]) + + if __name__ == '__main__': unittest.main() diff --git a/skills/agent-tmux/bin/isolated-role-rollback.py b/skills/agent-tmux/bin/isolated-role-rollback.py index 7f38afba..516df67e 100644 --- a/skills/agent-tmux/bin/isolated-role-rollback.py +++ b/skills/agent-tmux/bin/isolated-role-rollback.py @@ -1,25 +1,69 @@ #!/usr/bin/env python3 -"""Stop an owned isolated successor after an unsafe role-start assessment. +"""Crash-conservative stop of an owned isolated successor. -This is an experimental, in-process coordinator, not a handover controller or -an authorization boundary. The caller must bind the assessment to the native -connection and the stop callback to that successor's owned namespace lease. -No channel, trigger, predecessor or remote state is changed here. +This is not a handover controller or an authorization boundary. The caller +must bind the native assessment and owned stop callback to the same successor, +and consistently use the same private journal root for that session. """ import copy +import hashlib +import json +import os +from pathlib import Path import re +import stat import threading SESSION = re.compile(r'^codex:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$', re.I) +def _open_private_root(root): + if not isinstance(root, str) or not os.path.isabs(root) or str(Path(root).resolve(strict=True)) != root: + raise ValueError('journal root must be absolute and canonical') + before = os.lstat(root) + if not stat.S_ISDIR(before.st_mode) or before.st_uid != os.getuid() or before.st_mode & 0o077: + raise ValueError('journal root must be private and owned') + fd = os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW) + opened = os.fstat(fd) + if (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + os.close(fd) + raise ValueError('journal root changed') + return fd + + +def _verify_root(root, fd): + current = os.lstat(root) + opened = os.fstat(fd) + if (not stat.S_ISDIR(current.st_mode) or current.st_uid != os.getuid() or current.st_mode & 0o077 + or (current.st_dev, current.st_ino) != (opened.st_dev, opened.st_ino)): + raise ValueError('journal root changed') + + +def _write_once(directory_fd, name, record): + body = (json.dumps(record, separators=(',', ':'), sort_keys=True) + '\n').encode() + fd = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=directory_fd) + try: + view = memoryview(body) + while view: + written = os.write(fd, view) + if written <= 0: + raise OSError('journal write incomplete') + view = view[written:] + os.fsync(fd) + finally: + os.close(fd) + os.fsync(directory_fd) + + class IsolatedRoleRollback: - def __init__(self, expected_session, stop_owned_successor): - if not isinstance(expected_session, str) or not SESSION.fullmatch(expected_session) or not callable(stop_owned_successor): + def __init__(self, expected_session, stop_owned_successor, journal_root): + if not isinstance(expected_session, str) or not SESSION.fullmatch(expected_session) or expected_session != expected_session.lower() or not callable(stop_owned_successor): raise ValueError('invalid isolated successor binding') self._session = expected_session self._stop = stop_owned_successor + self._journal_root = journal_root + self._key = hashlib.sha256(expected_session.encode()).hexdigest() self._lock = threading.Lock() self._receipt = None @@ -39,17 +83,36 @@ def apply(self, assessment): if assessment['status'] == 'observed-incomplete': return {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'blocked-incomplete', 'session': self._session, 'handover': 'blocked'} - # Mark the attempt before invoking the callback: a lost response must - # never cause a second stop against an uncertain process identity. - self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', - 'session': self._session, 'handover': 'blocked'} + directory_fd = _open_private_root(self._journal_root) try: - receipt = self._stop() - except Exception: + intent = {'schema': 'agent-mesh.isolated-role-stop-intent.v1', 'session': self._session} + try: + _write_once(directory_fd, f'stop-{self._key}.intent.json', intent) + except FileExistsError: + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', + 'session': self._session, 'handover': 'blocked'} + return copy.deepcopy(self._receipt) + _verify_root(self._journal_root, directory_fd) + # Persist and fsync the attempt before the side effect. Never retry + # automatically after a crash or an ambiguous callback result. + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', + 'session': self._session, 'handover': 'blocked'} + try: + receipt = self._stop() + except Exception: + receipt = None + result = copy.deepcopy(self._receipt) + if (isinstance(receipt, dict) and receipt.get('schema') == 'agent-mesh.isolated-namespace-stop.v1' + and receipt.get('status') == 'init-exited' and receipt.get('descendants') == 'unverified' + and receipt.get('remoteEffects') == 'unverified'): + result = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'local-init-exited', + 'session': self._session, 'handover': 'blocked', + 'namespaceStop': {key: receipt[key] for key in ('schema', 'status', 'descendants', 'remoteEffects')}} + try: + _write_once(directory_fd, f'stop-{self._key}.result.json', result) + except OSError: + return copy.deepcopy(self._receipt) + self._receipt = result return copy.deepcopy(self._receipt) - if (isinstance(receipt, dict) and receipt.get('schema') == 'agent-mesh.isolated-namespace-stop.v1' - and receipt.get('status') == 'init-exited' and receipt.get('descendants') == 'unverified' - and receipt.get('remoteEffects') == 'unverified'): - self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'local-init-exited', - 'session': self._session, 'handover': 'blocked', 'namespaceStop': copy.deepcopy(receipt)} - return copy.deepcopy(self._receipt) + finally: + os.close(directory_fd) From b11e306f6d75a598b0cacde1928223fcd347d42d Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 00:49:49 +0000 Subject: [PATCH 100/113] test: qualify isolated Claude mailbox delivery --- .../scripts/test-isolation-regression.sh | 1 + .../test/claude-native-mailbox.integration.py | 83 +++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 packages/tmux-bridge/test/claude-native-mailbox.integration.py diff --git a/packages/tmux-bridge/scripts/test-isolation-regression.sh b/packages/tmux-bridge/scripts/test-isolation-regression.sh index 3bab2634..15ac22ee 100644 --- a/packages/tmux-bridge/scripts/test-isolation-regression.sh +++ b/packages/tmux-bridge/scripts/test-isolation-regression.sh @@ -67,6 +67,7 @@ python3 test/namespace-exec-gate.test.py python3 test/isolated-pid-namespace.test.py python3 -B test/isolated-role-rollback.test.py python3 -B test/codex-native-rollback.integration.py +python3 -B test/claude-native-mailbox.integration.py python3 test/session-controller.test.py python3 test/owner-notify.test.py scripts/socket-isolation-test.sh diff --git a/packages/tmux-bridge/test/claude-native-mailbox.integration.py b/packages/tmux-bridge/test/claude-native-mailbox.integration.py new file mode 100644 index 00000000..bdf20337 --- /dev/null +++ b/packages/tmux-bridge/test/claude-native-mailbox.integration.py @@ -0,0 +1,83 @@ +import json,os,pathlib,subprocess,sys,tempfile,threading,time,uuid +from http.server import HTTPServer,BaseHTTPRequestHandler +BINARY=os.environ.get('AGENT_MESH_TEST_CLAUDE_BIN') +if not BINARY: + print('SKIP: set AGENT_MESH_TEST_CLAUDE_BIN to an absolute Claude binary path');sys.exit(0) +if not os.path.isabs(BINARY) or not os.path.isfile(BINARY) or not os.access(BINARY,os.X_OK): + raise RuntimeError('test Claude binary must be an absolute executable file') +BASE=pathlib.Path(__file__).resolve().parents[1]/'bin' +NODE=os.environ.get('AGENT_MESH_TEST_NODE_BIN','/usr/local/bin/node') +if not os.path.isabs(NODE) or not os.access(NODE,os.X_OK):raise RuntimeError('test Node binary must be absolute and executable') +if len(sys.argv)>1: + root=pathlib.Path(sys.argv[1]); count=[0] + class H(BaseHTTPRequestHandler): + def do_POST(self): + self.rfile.read(int(self.headers.get('Content-Length',0))); count[0]+=1; time.sleep(2 if count[0]==1 else 0) + es=[('message_start',{'type':'message_start','message':{'id':'msg_fixture','type':'message','role':'assistant','model':'fixture','content':[],'stop_reason':None,'stop_sequence':None,'usage':{'input_tokens':1,'output_tokens':1}}}),('content_block_start',{'type':'content_block_start','index':0,'content_block':{'type':'text','text':''}}),('content_block_delta',{'type':'content_block_delta','index':0,'delta':{'type':'text_delta','text':'fixture reply'}}),('content_block_stop',{'type':'content_block_stop','index':0}),('message_delta',{'type':'message_delta','delta':{'stop_reason':'end_turn','stop_sequence':None},'usage':{'output_tokens':2}}),('message_stop',{'type':'message_stop'})] + body=''.join('event: '+n+'\ndata: '+json.dumps(v)+'\n\n' for n,v in es).encode(); self.send_response(200); self.send_header('Content-Type','text/event-stream'); self.send_header('Content-Length',str(len(body))); self.end_headers(); self.wfile.write(body) + def log_message(self,*args): pass + server=HTTPServer(('127.0.0.1',18984),H);threading.Thread(target=server.serve_forever,daemon=True).start(); sid=str(uuid.uuid4()) + cmd=[BINARY,'--print','--input-format','stream-json','--output-format','stream-json','--verbose','--model','claude-sonnet-4-5','--permission-mode','dontAsk','--session-id',sid,'--name','fixture-peer','--tools','','--strict-mcp-config','--mcp-config','{"mcpServers":{}}','--disable-slash-commands','--settings','{"disableAllHooks":true}'] + p=subprocess.Popen(cmd,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE,text=True) + rec={'schema':'agent-mesh.monitor-inbox.v1','deliveryId':'fixture-1','meshId':'fixture-1','prompt':'synthetic delivery'} + def send(content):p.stdin.write(json.dumps({'type':'user','message':{'role':'user','content':content}})+'\n');p.stdin.flush() + send('first synthetic turn');time.sleep(.7) + import importlib.util + native=str(BASE/'agent-inbox-native.py') + spec=importlib.util.spec_from_file_location('native',native); m=importlib.util.module_from_spec(spec);spec.loader.exec_module(m) + os.environ['CLAUDE_BIN']=BINARY + try: + owner=m.identity(p.pid); match=m.registration(sid,owner) + with m.NativeClient() as client: listing=m.tool_json(client.request('tools/call',{'name':'ListAgents','arguments':{}})) + native_result={'registrationFound':bool(match),'sections':[(x.get('kind'),len(x.get('rows',[]))) for x in listing.get('sections',[])]} + except Exception as e:native_result={'errorType':type(e).__name__,'error':str(e)[:180]} + inbox_script=native.replace('agent-inbox-native.py','agent-session-inbox.py') + inbox_spec=importlib.util.spec_from_file_location('mailbox',inbox_script); inbox_mod=importlib.util.module_from_spec(inbox_spec); inbox_spec.loader.exec_module(inbox_mod) + inbox_root=root/'inbox'; inbox=inbox_mod.prepare(inbox_root,sid) + os.environ['MESH_COMMS_STATE']=str(root/'comms'); os.environ['XDG_STATE_HOME']=str(root/'state') + watcher=subprocess.Popen(['/usr/bin/python3',inbox_script,'serve','--root',str(inbox_root),'--session',sid,'--owner-pid',str(p.pid),'--owner-start',owner['start'],'--batch-seconds','0.1','--retry-seconds','0.05'],stdout=subprocess.DEVNULL,stderr=subprocess.PIPE,text=True) + deadline=time.monotonic()+5 + while time.monotonic() Date: Tue, 17 Nov 2026 00:57:32 +0000 Subject: [PATCH 101/113] Report inbox hook budget expiry --- packages/tmux-bridge/bin/agent-session-inbox.py | 10 +++++++++- packages/tmux-bridge/test/session-inbox.test.py | 12 ++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/packages/tmux-bridge/bin/agent-session-inbox.py b/packages/tmux-bridge/bin/agent-session-inbox.py index 3dc205cd..0141c7c6 100755 --- a/packages/tmux-bridge/bin/agent-session-inbox.py +++ b/packages/tmux-bridge/bin/agent-session-inbox.py @@ -23,6 +23,10 @@ DUPLICATE = "AGENT_MESH_INBOX_DUPLICATE do-not-relaunch" +class HookBudgetExpired(TimeoutError): + pass + + def process_identity(pid): """Use kernel start ticks as well as PID, so PID reuse is not ownership.""" if not isinstance(pid, int) or pid <= 1: @@ -434,7 +438,7 @@ def main(): return if args.mode in {'hook', 'status'}: def expire(_signum, _frame): - raise TimeoutError('hook budget expired') + raise HookBudgetExpired('hook budget expired') previous = signal.signal(signal.SIGALRM, expire) signal.setitimer(signal.ITIMER_REAL, 0.2) try: @@ -446,6 +450,10 @@ def expire(_signum, _frame): if not active: raise ValueError('no live owner-bound supervisor') print(json.dumps(active)) + except HookBudgetExpired: + print('agent-session-inbox: hook budget expired', file=sys.stderr, flush=True) + if args.mode == 'status': + raise SystemExit(1) except Exception: if args.mode == 'status': raise SystemExit(1) diff --git a/packages/tmux-bridge/test/session-inbox.test.py b/packages/tmux-bridge/test/session-inbox.test.py index a689e11a..fb678fcf 100644 --- a/packages/tmux-bridge/test/session-inbox.test.py +++ b/packages/tmux-bridge/test/session-inbox.test.py @@ -49,6 +49,18 @@ def tearDown(self): proc.communicate(timeout=5) self.temp.cleanup() + def test_hook_timeout_reports_fixed_diagnostic_without_context(self): + spec = importlib.util.spec_from_file_location('hook_timeout_test', SCRIPT) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + stdout, stderr = io.StringIO(), io.StringIO() + with patch.object(module, 'hook', side_effect=module.HookBudgetExpired()), \ + patch.object(sys, 'argv', [str(SCRIPT), 'hook', '--root', str(self.root)]), \ + contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr): + module.main() + self.assertEqual(stdout.getvalue(), '') + self.assertEqual(stderr.getvalue(), 'agent-session-inbox: hook budget expired\n') + def hook(self, agent='claude', session=SESSION, event='SessionStart', owner=None, extra_env=None, payload=None): env = {**os.environ, 'AGENT_MESH_HARNESS_PID': str(owner or os.getpid()), **(extra_env or {})} return subprocess.run([sys.executable, str(SCRIPT), 'hook', '--root', str(self.root), '--agent', agent], From 8f4850dfa3c5f27cfa857a6afb9de2a269a130b5 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 01:00:42 +0000 Subject: [PATCH 102/113] Keep inbox hook timeout diagnostics opt in --- packages/tmux-bridge/bin/agent-session-inbox.py | 3 ++- packages/tmux-bridge/test/session-inbox.test.py | 9 ++++++--- skills/agent-tmux/bin/agent-session-inbox.py | 11 ++++++++++- 3 files changed, 18 insertions(+), 5 deletions(-) diff --git a/packages/tmux-bridge/bin/agent-session-inbox.py b/packages/tmux-bridge/bin/agent-session-inbox.py index 0141c7c6..fc161036 100755 --- a/packages/tmux-bridge/bin/agent-session-inbox.py +++ b/packages/tmux-bridge/bin/agent-session-inbox.py @@ -451,7 +451,8 @@ def expire(_signum, _frame): raise ValueError('no live owner-bound supervisor') print(json.dumps(active)) except HookBudgetExpired: - print('agent-session-inbox: hook budget expired', file=sys.stderr, flush=True) + if os.environ.get('AGENT_MESH_INBOX_DIAGNOSTICS') == '1': + print('agent-session-inbox: hook budget expired', file=sys.stderr, flush=True) if args.mode == 'status': raise SystemExit(1) except Exception: diff --git a/packages/tmux-bridge/test/session-inbox.test.py b/packages/tmux-bridge/test/session-inbox.test.py index fb678fcf..95ac0d35 100644 --- a/packages/tmux-bridge/test/session-inbox.test.py +++ b/packages/tmux-bridge/test/session-inbox.test.py @@ -54,7 +54,8 @@ def test_hook_timeout_reports_fixed_diagnostic_without_context(self): module = importlib.util.module_from_spec(spec) spec.loader.exec_module(module) stdout, stderr = io.StringIO(), io.StringIO() - with patch.object(module, 'hook', side_effect=module.HookBudgetExpired()), \ + with patch.dict(os.environ, {'AGENT_MESH_INBOX_DIAGNOSTICS': '1'}), \ + patch.object(module, 'hook', side_effect=module.HookBudgetExpired()), \ patch.object(sys, 'argv', [str(SCRIPT), 'hook', '--root', str(self.root)]), \ contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr): module.main() @@ -62,7 +63,7 @@ def test_hook_timeout_reports_fixed_diagnostic_without_context(self): self.assertEqual(stderr.getvalue(), 'agent-session-inbox: hook budget expired\n') def hook(self, agent='claude', session=SESSION, event='SessionStart', owner=None, extra_env=None, payload=None): - env = {**os.environ, 'AGENT_MESH_HARNESS_PID': str(owner or os.getpid()), **(extra_env or {})} + env = {**os.environ, 'AGENT_MESH_INBOX_DIAGNOSTICS': '1', 'AGENT_MESH_HARNESS_PID': str(owner or os.getpid()), **(extra_env or {})} return subprocess.run([sys.executable, str(SCRIPT), 'hook', '--root', str(self.root), '--agent', agent], input=json.dumps(payload if payload is not None else {'session_id': session, 'hook_event_name': event}), env=env, text=True, capture_output=True, check=True) @@ -268,7 +269,9 @@ def test_long_lived_print_sessions_keep_watcher_activation(self): (['-n', '-p'], {'CLAUDE_CODE_ENVIRONMENT_KIND': ''}), (['-np'], {'CLAUDE_CODE_ENVIRONMENT_KIND': ''})) for flags, env in cases: - context = json.loads(self.hook(owner=self.fake_owner(*flags), extra_env=env).stdout) + result = self.hook(owner=self.fake_owner(*flags), extra_env=env) + self.assertTrue(result.stdout, f'no hook context for {flags}: {result.stderr}') + context = json.loads(result.stdout) self.assertIn('Do not launch or rearm', context['hookSpecificOutput']['additionalContext']) def test_codex_and_automation_disabled_without_side_effects(self): diff --git a/skills/agent-tmux/bin/agent-session-inbox.py b/skills/agent-tmux/bin/agent-session-inbox.py index 3dc205cd..fc161036 100755 --- a/skills/agent-tmux/bin/agent-session-inbox.py +++ b/skills/agent-tmux/bin/agent-session-inbox.py @@ -23,6 +23,10 @@ DUPLICATE = "AGENT_MESH_INBOX_DUPLICATE do-not-relaunch" +class HookBudgetExpired(TimeoutError): + pass + + def process_identity(pid): """Use kernel start ticks as well as PID, so PID reuse is not ownership.""" if not isinstance(pid, int) or pid <= 1: @@ -434,7 +438,7 @@ def main(): return if args.mode in {'hook', 'status'}: def expire(_signum, _frame): - raise TimeoutError('hook budget expired') + raise HookBudgetExpired('hook budget expired') previous = signal.signal(signal.SIGALRM, expire) signal.setitimer(signal.ITIMER_REAL, 0.2) try: @@ -446,6 +450,11 @@ def expire(_signum, _frame): if not active: raise ValueError('no live owner-bound supervisor') print(json.dumps(active)) + except HookBudgetExpired: + if os.environ.get('AGENT_MESH_INBOX_DIAGNOSTICS') == '1': + print('agent-session-inbox: hook budget expired', file=sys.stderr, flush=True) + if args.mode == 'status': + raise SystemExit(1) except Exception: if args.mode == 'status': raise SystemExit(1) From 3d113aecdb1a0d747d2038a386fe576aaefb5574 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 01:09:56 +0000 Subject: [PATCH 103/113] Observe Claude channel backlog before dispatch --- docs/design/plexus-channels.md | 10 +++-- packages/tmux-bridge/bin/agent-waker.py | 18 +++++++++ .../test/agent-waker-channel.test.py | 37 +++++++++++++++++++ skills/agent-tmux/bin/agent-waker.py | 18 +++++++++ 4 files changed, 80 insertions(+), 3 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 9debf395..d5b9a61a 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -269,9 +269,13 @@ managed inbox record in a stable local user transcript snapshot, binding its correlation, payload, session and generation before marking the backlog item observed. It requires a unique matching native enqueue preceding the user record; an enqueue-only record is insufficient. Native inbox user records can -carry the `isMeta` flag and remain eligible when this correlation is proven. This source does not prove -execution, attention, finality or cloud delivery; its real transport transcript -shape still requires isolated qualification. Operational cutover remains disabled. +carry the `isMeta` flag and remain eligible when this correlation is proven. +The channel waker attempts observation for an accepted local Claude backlog item +before dispatching another item. Missing evidence blocks the run without a +resend; later runs may inspect the graph and transcript again. An opt-in test +has qualified the native transport and transcript shape in an isolated local +fixture. This source does not prove execution, attention, finality or cloud +delivery. Operational cutover remains disabled. A previously verified restart-state receipt can be revalidated against the current private file before a future cutover. Revalidation checks generation, diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index 325ebc22..dbdf2427 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -193,6 +193,17 @@ def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dic return value['channel'] +def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str) -> None: + command = ['node', str(BIN / 'mesh-graph.mjs')] + if args.graph_state: + command += ['--state', args.graph_state] + command += ['channel', 'observe-claude-delivery', '--name', args.channel, '--id', message_id] + result = subprocess.run(command, text=True, capture_output=True, timeout=30, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or value.get('status') != 'observed' or value.get('channel') != args.channel or value.get('messageId') != message_id: + raise ValueError('invalid delivery observation') + + def cloud_target(target: str, root: str | None) -> tuple[str, str, str]: match = re.fullmatch(r'claude-cloud:([a-z][a-z0-9-]{0,63}):((?:session|cse)_[A-Za-z0-9]{1,128})', target) if not match or not root: @@ -262,6 +273,13 @@ def run_channel(args: argparse.Namespace) -> int: if any(item.get('state') == 'inflight' for item in channel['queue']): print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unresolved delivery'})) return 3 + if channel.get('phase') == 'draining' and channel.get('session', '').startswith('claude:'): + backlog = channel.get('handover', {}).get('backlog', []) + awaiting = next((item for item in channel['queue'] if item.get('id') in backlog and item.get('state') == 'accepted'), None) + if awaiting: + observe_claude_channel_delivery(args, awaiting['id']) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'delivery observed'})) + return 0 pending = next((item for item in channel['queue'] if item.get('state') == 'pending'), None) if not pending: print(json.dumps({'job': args.job, 'outcome': 'noop'})) diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index 7c36fb23..78e0e69a 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -2,6 +2,7 @@ import importlib.util import io import json +import os from pathlib import Path import subprocess import tempfile @@ -17,6 +18,42 @@ class ChannelWakerTest(unittest.TestCase): + def test_draining_claude_backlog_waits_for_observation_without_resending(self): + with tempfile.TemporaryDirectory() as directory: + tmp = Path(directory) + state, sessions = tmp / 'graph', tmp / 'sessions' + project = sessions / 'project' + project.mkdir(parents=True, mode=0o700) + sessions.chmod(0o700) + successor = '33333333-3333-4333-8333-333333333333' + target = f'claude:{successor}' + def call(*parts): + proc = subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *parts], capture_output=True, text=True, check=True) + return json.loads(proc.stdout) + call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') + graph = call('show', '--json') + channel = graph['channels'][0] + channel.update(session=target, generation=2, phase='draining', handover={'predecessor': f'codex:{uuid}', 'previousGeneration': 1, 'successor': target, 'backlog': ['one']}, queue=[{'id': 'one', 'payload': 'fixture', 'state': 'accepted', 'session': target, 'generation': 2}]) + event = {'schema': 'agent-mesh.session-graph-event.v1', 'id': 'fixture-draining', 'type': 'channel.updated', 'at': '2026-01-01T00:00:00Z', 'channel': channel, 'seq': graph['lastSeq'] + 1, 'host': 'local'} + with (state / 'events.jsonl').open('a') as stream: + stream.write(json.dumps(event) + '\n') + args = SimpleNamespace(state=str(tmp / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + record = {'schema': 'agent-mesh.monitor-inbox.v1', 'deliveryId': 'one', 'meshId': 'one', 'prompt': 'fixture'} + message = 'AGENT_MESH_INBOX ' + json.dumps(record) + transcript = project / (successor + '.jsonl') + transcript.write_text(json.dumps({'type': 'queue-operation', 'operation': 'enqueue', 'sessionId': successor, 'content': message}) + '\n') + transcript.chmod(0o600) + with patch.dict(os.environ, {'CLAUDE_SESSION_ROOT': str(sessions)}), patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + with transcript.open('a') as stream: + stream.write(json.dumps({'type': 'user', 'sessionId': successor, 'message': {'role': 'user', 'content': message}}) + '\n') + self.assertEqual(waker.run(args), 0) + self.assertEqual(waker.run(args), 0) + deliver.assert_not_called() + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'observed') + def test_wake_reservation_survives_reload_and_blocks_handover(self): with tempfile.TemporaryDirectory() as directory: state = Path(directory) / 'graph' diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index 325ebc22..dbdf2427 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -193,6 +193,17 @@ def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dic return value['channel'] +def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str) -> None: + command = ['node', str(BIN / 'mesh-graph.mjs')] + if args.graph_state: + command += ['--state', args.graph_state] + command += ['channel', 'observe-claude-delivery', '--name', args.channel, '--id', message_id] + result = subprocess.run(command, text=True, capture_output=True, timeout=30, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or value.get('status') != 'observed' or value.get('channel') != args.channel or value.get('messageId') != message_id: + raise ValueError('invalid delivery observation') + + def cloud_target(target: str, root: str | None) -> tuple[str, str, str]: match = re.fullmatch(r'claude-cloud:([a-z][a-z0-9-]{0,63}):((?:session|cse)_[A-Za-z0-9]{1,128})', target) if not match or not root: @@ -262,6 +273,13 @@ def run_channel(args: argparse.Namespace) -> int: if any(item.get('state') == 'inflight' for item in channel['queue']): print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unresolved delivery'})) return 3 + if channel.get('phase') == 'draining' and channel.get('session', '').startswith('claude:'): + backlog = channel.get('handover', {}).get('backlog', []) + awaiting = next((item for item in channel['queue'] if item.get('id') in backlog and item.get('state') == 'accepted'), None) + if awaiting: + observe_claude_channel_delivery(args, awaiting['id']) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'delivery observed'})) + return 0 pending = next((item for item in channel['queue'] if item.get('state') == 'pending'), None) if not pending: print(json.dumps({'job': args.job, 'outcome': 'noop'})) From fb1afce9649d2ea8fec62feb8978a452153c9d59 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 01:14:58 +0000 Subject: [PATCH 104/113] Recover Claude delivery from transcript evidence --- docs/design/plexus-channels.md | 5 +++ packages/tmux-bridge/bin/agent-waker.py | 15 ++++++--- packages/tmux-bridge/bin/mesh-graph.mjs | 22 ++++++++++++- .../test/agent-waker-channel.test.py | 32 +++++++++++++++++++ skills/agent-tmux/bin/agent-waker.py | 15 ++++++--- skills/agent-tmux/bin/mesh-graph.mjs | 22 ++++++++++++- 6 files changed, 101 insertions(+), 10 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index d5b9a61a..eb3a714c 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -22,6 +22,11 @@ The graph command can also reserve a pending message and record a matching acceptance receipt. Reservation is durable before transport; a crash or uncertain outcome leaves the item in flight and blocks handover. A local caller is responsible for verifying transport receipts before recording them. +For a local Claude in-flight item, the waker may recover without resending only +after a stable transcript independently proves the correlated enqueue and user +message. The graph rechecks the session, generation, payload and phase before +settling; missing or ambiguous evidence leaves the item unresolved. This does +not establish delivery for cloud or Codex recipients. Handover completion is disabled until an adapter can verify that the old session wrote its state. A path or caller assertion is not sufficient proof. diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index dbdf2427..9c4f93e7 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -193,14 +193,16 @@ def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dic return value['channel'] -def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str) -> None: +def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str, recovery: bool = False) -> None: command = ['node', str(BIN / 'mesh-graph.mjs')] if args.graph_state: command += ['--state', args.graph_state] - command += ['channel', 'observe-claude-delivery', '--name', args.channel, '--id', message_id] + operation = 'recover-claude-delivery' if recovery else 'observe-claude-delivery' + command += ['channel', operation, '--name', args.channel, '--id', message_id] result = subprocess.run(command, text=True, capture_output=True, timeout=30, check=True) value = json.loads(result.stdout) - if not isinstance(value, dict) or value.get('status') != 'observed' or value.get('channel') != args.channel or value.get('messageId') != message_id: + allowed = ('accepted', 'observed') if recovery else ('observed',) + if not isinstance(value, dict) or value.get('status') not in allowed or value.get('channel') != args.channel or value.get('messageId') != message_id: raise ValueError('invalid delivery observation') @@ -270,7 +272,12 @@ def run_channel(args: argparse.Namespace) -> int: if channel.get('phase') not in ('active', 'draining'): print(json.dumps({'job': args.job, 'outcome': 'queued', 'reason': 'handover'})) return 0 - if any(item.get('state') == 'inflight' for item in channel['queue']): + inflight = next((item for item in channel['queue'] if item.get('state') == 'inflight'), None) + if inflight and channel.get('session', '').startswith('claude:'): + observe_claude_channel_delivery(args, inflight['id'], recovery=True) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'delivery recovered'})) + return 0 + if inflight: print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unresolved delivery'})) return 3 if channel.get('phase') == 'draining' and channel.get('session', '').startswith('claude:'): diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 1f21a08d..f588daf6 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -133,7 +133,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "recover-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -155,6 +155,26 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "recover-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const pending = channel?.queue?.filter(item => item.id === id && item.state === "inflight" && item.session === channel.session && item.generation === channel.generation); + if (!['active', 'draining'].includes(channel?.phase) || pending?.length !== 1 || !channel.session.startsWith("claude:")) throw new Error("Claude delivery recovery unavailable"); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeClaudeDelivery({ root, session: channel.session, generation: channel.generation, messageId: id, payload: pending[0].payload }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + const item = current?.queue?.find(row => row.id === id); + if (!item || current.phase !== channel.phase || item.state !== 'inflight' || item.session !== proof.session || item.generation !== proof.generation || current.session !== proof.session || current.generation !== proof.generation || typeof item.payload !== 'string' || createHash('sha256').update(item.payload).digest('hex') !== proof.payloadSha256) throw new Error('delivery changed during recovery'); + let next = acknowledge(current, id, { status: 'accepted', messageId: id, session: proof.session, generation: proof.generation }); + if (next.phase === 'draining' && next.handover?.backlog?.includes(id)) next = observeDelivery(next, id, proof); + return { graph, event: event('channel.updated', { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: next.queue.find(row => row.id === id).state } }; + }); + printResult(result, { json: true }); + break; + } if (subcommand === "observe-claude-delivery") { const id = requiredSingleLine(values.id, "--id"); const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index 78e0e69a..e6530419 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -18,6 +18,38 @@ class ChannelWakerTest(unittest.TestCase): + def test_lost_claude_receipt_recovers_from_correlated_transcript_without_resend(self): + with tempfile.TemporaryDirectory() as directory: + tmp = Path(directory) + state, sessions = tmp / 'graph', tmp / 'sessions' + project = sessions / 'project' + project.mkdir(parents=True, mode=0o700) + sessions.chmod(0o700) + target = f'claude:{uuid}' + def call(*parts): + proc = subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *parts], capture_output=True, text=True, check=True) + return json.loads(proc.stdout) + call('add', '--agent', 'claude', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', target) + call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'fixture') + call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', target, '--generation', '1') + record = {'schema': 'agent-mesh.monitor-inbox.v1', 'deliveryId': 'one', 'meshId': 'one', 'prompt': 'fixture'} + message = 'AGENT_MESH_INBOX ' + json.dumps(record) + transcript = project / (uuid + '.jsonl') + transcript.write_text(json.dumps({'type': 'queue-operation', 'operation': 'enqueue', 'sessionId': uuid, 'content': message}) + '\n') + transcript.chmod(0o600) + args = SimpleNamespace(state=str(tmp / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + with patch.dict(os.environ, {'CLAUDE_SESSION_ROOT': str(sessions)}), patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'inflight') + with transcript.open('a') as stream: + stream.write(json.dumps({'type': 'user', 'sessionId': uuid, 'message': {'role': 'user', 'content': message}}) + '\n') + self.assertEqual(waker.run(args), 0) + self.assertEqual(waker.run(args), 0) + deliver.assert_not_called() + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'accepted') + def test_draining_claude_backlog_waits_for_observation_without_resending(self): with tempfile.TemporaryDirectory() as directory: tmp = Path(directory) diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index dbdf2427..9c4f93e7 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -193,14 +193,16 @@ def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dic return value['channel'] -def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str) -> None: +def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str, recovery: bool = False) -> None: command = ['node', str(BIN / 'mesh-graph.mjs')] if args.graph_state: command += ['--state', args.graph_state] - command += ['channel', 'observe-claude-delivery', '--name', args.channel, '--id', message_id] + operation = 'recover-claude-delivery' if recovery else 'observe-claude-delivery' + command += ['channel', operation, '--name', args.channel, '--id', message_id] result = subprocess.run(command, text=True, capture_output=True, timeout=30, check=True) value = json.loads(result.stdout) - if not isinstance(value, dict) or value.get('status') != 'observed' or value.get('channel') != args.channel or value.get('messageId') != message_id: + allowed = ('accepted', 'observed') if recovery else ('observed',) + if not isinstance(value, dict) or value.get('status') not in allowed or value.get('channel') != args.channel or value.get('messageId') != message_id: raise ValueError('invalid delivery observation') @@ -270,7 +272,12 @@ def run_channel(args: argparse.Namespace) -> int: if channel.get('phase') not in ('active', 'draining'): print(json.dumps({'job': args.job, 'outcome': 'queued', 'reason': 'handover'})) return 0 - if any(item.get('state') == 'inflight' for item in channel['queue']): + inflight = next((item for item in channel['queue'] if item.get('state') == 'inflight'), None) + if inflight and channel.get('session', '').startswith('claude:'): + observe_claude_channel_delivery(args, inflight['id'], recovery=True) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'delivery recovered'})) + return 0 + if inflight: print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unresolved delivery'})) return 3 if channel.get('phase') == 'draining' and channel.get('session', '').startswith('claude:'): diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 1f21a08d..f588daf6 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -133,7 +133,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "recover-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -155,6 +155,26 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "recover-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const pending = channel?.queue?.filter(item => item.id === id && item.state === "inflight" && item.session === channel.session && item.generation === channel.generation); + if (!['active', 'draining'].includes(channel?.phase) || pending?.length !== 1 || !channel.session.startsWith("claude:")) throw new Error("Claude delivery recovery unavailable"); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeClaudeDelivery({ root, session: channel.session, generation: channel.generation, messageId: id, payload: pending[0].payload }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + const item = current?.queue?.find(row => row.id === id); + if (!item || current.phase !== channel.phase || item.state !== 'inflight' || item.session !== proof.session || item.generation !== proof.generation || current.session !== proof.session || current.generation !== proof.generation || typeof item.payload !== 'string' || createHash('sha256').update(item.payload).digest('hex') !== proof.payloadSha256) throw new Error('delivery changed during recovery'); + let next = acknowledge(current, id, { status: 'accepted', messageId: id, session: proof.session, generation: proof.generation }); + if (next.phase === 'draining' && next.handover?.backlog?.includes(id)) next = observeDelivery(next, id, proof); + return { graph, event: event('channel.updated', { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: next.queue.find(row => row.id === id).state } }; + }); + printResult(result, { json: true }); + break; + } if (subcommand === "observe-claude-delivery") { const id = requiredSingleLine(values.id, "--id"); const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); From 33813e67216d4d371480dd04c3246fd78ceb791c Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 01:19:23 +0000 Subject: [PATCH 105/113] Qualify Claude recovery against native transcript --- .../test/claude-native-mailbox.integration.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/packages/tmux-bridge/test/claude-native-mailbox.integration.py b/packages/tmux-bridge/test/claude-native-mailbox.integration.py index bdf20337..b4324dc5 100644 --- a/packages/tmux-bridge/test/claude-native-mailbox.integration.py +++ b/packages/tmux-bridge/test/claude-native-mailbox.integration.py @@ -39,6 +39,18 @@ def send(content):p.stdin.write(json.dumps({'type':'user','message':{'role':'use deadline=time.monotonic()+5 while time.monotonic() Date: Tue, 17 Nov 2026 01:26:40 +0000 Subject: [PATCH 106/113] Recheck Claude transcript before delivery settlement --- docs/design/plexus-channels.md | 7 +++++-- .../bin/claude-delivery-observation.mjs | 17 ++++++++++++++--- packages/tmux-bridge/bin/mesh-graph.mjs | 4 +++- .../test/claude-delivery-observation.test.mjs | 9 +++++++-- .../bin/claude-delivery-observation.mjs | 17 ++++++++++++++--- skills/agent-tmux/bin/mesh-graph.mjs | 4 +++- 6 files changed, 46 insertions(+), 12 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index eb3a714c..c8c66699 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -25,8 +25,11 @@ caller is responsible for verifying transport receipts before recording them. For a local Claude in-flight item, the waker may recover without resending only after a stable transcript independently proves the correlated enqueue and user message. The graph rechecks the session, generation, payload and phase before -settling; missing or ambiguous evidence leaves the item unresolved. This does -not establish delivery for cloud or Codex recipients. +settling, and rechecks transcript file identity and metadata under the graph +lock; missing, changed or ambiguous evidence leaves the item unresolved. This +narrows a race but does not exclude a transcript writer after the check or +provide an immutable audit copy. It does not establish delivery for cloud or +Codex recipients. Handover completion is disabled until an adapter can verify that the old session wrote its state. A path or caller assertion is not sufficient proof. diff --git a/packages/tmux-bridge/bin/claude-delivery-observation.mjs b/packages/tmux-bridge/bin/claude-delivery-observation.mjs index 0d6b7a77..2abf8179 100644 --- a/packages/tmux-bridge/bin/claude-delivery-observation.mjs +++ b/packages/tmux-bridge/bin/claude-delivery-observation.mjs @@ -1,5 +1,5 @@ /** Read-only observation of one managed inbox record in a local Claude transcript. */ -import { constants } from 'node:fs'; +import { constants, lstatSync, realpathSync } from 'node:fs'; import { lstat, open, realpath, readdir } from 'node:fs/promises'; import { createHash } from 'node:crypto'; import { isAbsolute, join, resolve } from 'node:path'; @@ -17,13 +17,14 @@ export async function observeClaudeDelivery({ root, session, generation, message const matches = entries.filter(entry => entry.isFile() && entry.name.toLowerCase() === `${session.slice(7).toLowerCase()}.jsonl`).map(entry => join(entry.parentPath, entry.name)); if (matches.length !== 1 || await realpath(matches[0]) !== matches[0]) throw new Error('transcript identity unavailable or ambiguous'); const path = matches[0], file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); - let bytes; + let bytes, snapshotIdentity; try { const before = await file.stat(); if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > 128 * 1024 * 1024) throw new Error('invalid transcript file'); bytes = await file.readFile(); const after = await file.stat(), current = await lstat(path); if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + snapshotIdentity = { path, dev: after.dev, ino: after.ino, size: after.size, mtimeMs: after.mtimeMs, ctimeMs: after.ctimeMs }; } finally { await file.close(); } let text; try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } @@ -52,5 +53,15 @@ export async function observeClaudeDelivery({ root, session, generation, message if (queued !== 1 || found !== 1) throw new Error('delivery not uniquely observed'); const payloadSha256 = hash(payload), transcriptSha256 = hash(bytes); const evidence = `claude-transcript:${hash(JSON.stringify([session, generation, messageId, payloadSha256, transcriptSha256]))}`; - return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, evidence }; + return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, evidence, snapshotIdentity }; +} + +// Narrows the snapshot-to-graph race; it cannot exclude a writer after this check. +export function assertClaudeDeliverySnapshotCurrent(proof) { + const snapshot = proof?.snapshotIdentity; + if (!snapshot || typeof snapshot.path !== 'string' || !isAbsolute(snapshot.path)) throw new Error('transcript snapshot identity unavailable'); + let current; + try { current = lstatSync(snapshot.path); if (realpathSync(snapshot.path) !== snapshot.path) throw new Error(); } + catch { throw new Error('transcript snapshot unavailable'); } + if (!current.isFile() || current.isSymbolicLink() || current.uid !== process.getuid() || current.nlink !== 1 || (current.mode & 0o022) !== 0 || current.dev !== snapshot.dev || current.ino !== snapshot.ino || current.size !== snapshot.size || current.mtimeMs !== snapshot.mtimeMs || current.ctimeMs !== snapshot.ctimeMs) throw new Error('transcript changed after observation'); } diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index f588daf6..ad63b625 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -38,7 +38,7 @@ import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, observeDelivery, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; -import { observeClaudeDelivery } from "./claude-delivery-observation.mjs"; +import { observeClaudeDelivery, assertClaudeDeliverySnapshotCurrent } from "./claude-delivery-observation.mjs"; import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; import { prepareState, requestStateProof, revalidateStateProof } from "./handover-state-proof.mjs"; import { formatFinalNotice } from "./handover-notice.mjs"; @@ -168,6 +168,7 @@ try { const current = (graph.channels || []).find(item => item.id === name); const item = current?.queue?.find(row => row.id === id); if (!item || current.phase !== channel.phase || item.state !== 'inflight' || item.session !== proof.session || item.generation !== proof.generation || current.session !== proof.session || current.generation !== proof.generation || typeof item.payload !== 'string' || createHash('sha256').update(item.payload).digest('hex') !== proof.payloadSha256) throw new Error('delivery changed during recovery'); + assertClaudeDeliverySnapshotCurrent(proof); let next = acknowledge(current, id, { status: 'accepted', messageId: id, session: proof.session, generation: proof.generation }); if (next.phase === 'draining' && next.handover?.backlog?.includes(id)) next = observeDelivery(next, id, proof); return { graph, event: event('channel.updated', { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: next.queue.find(row => row.id === id).state } }; @@ -188,6 +189,7 @@ try { const current = (graph.channels || []).find(item => item.id === name); const item = current?.queue?.find(row => row.id === id); if (!item || typeof item.payload !== "string" || createHash("sha256").update(item.payload).digest("hex") !== proof.payloadSha256) throw new Error("delivery changed during observation"); + assertClaudeDeliverySnapshotCurrent(proof); const next = observeDelivery(current, id, proof); return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: "observed" } }; }); diff --git a/packages/tmux-bridge/test/claude-delivery-observation.test.mjs b/packages/tmux-bridge/test/claude-delivery-observation.test.mjs index 9eea0008..8b1c9835 100644 --- a/packages/tmux-bridge/test/claude-delivery-observation.test.mjs +++ b/packages/tmux-bridge/test/claude-delivery-observation.test.mjs @@ -1,9 +1,9 @@ import assert from 'node:assert/strict'; -import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'; +import { mkdtemp, mkdir, writeFile, rm, rename } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import test from 'node:test'; -import { observeClaudeDelivery } from '../bin/claude-delivery-observation.mjs'; +import { observeClaudeDelivery, assertClaudeDeliverySnapshotCurrent } from '../bin/claude-delivery-observation.mjs'; const id = '22222222-2222-4222-8222-222222222222', session = `claude:${id}`; const inbox = { schema: 'agent-mesh.monitor-inbox.v1', deliveryId: 'message-1', meshId: 'message-1', prompt: 'fixture' }; @@ -24,6 +24,11 @@ test('only a unique correlated user transcript record proves local inbox observa const proof = await observeClaudeDelivery({ root, ...options }); assert.equal(proof.session, session); assert.equal(proof.generation, 2); assert.match(proof.evidence, /^claude-transcript:[a-f0-9]{64}$/); + assert.doesNotThrow(() => assertClaudeDeliverySnapshotCurrent(proof)); + await writeFile(path + '.new', JSON.stringify(queued) + '\n', { mode: 0o600 }); + await rename(path + '.new', path); + assert.throws(() => assertClaudeDeliverySnapshotCurrent(proof), /transcript changed after observation/); + await put([queued, user(inbox)]); await assert.rejects(observeClaudeDelivery({ root, ...options, payload: 'changed' }), /correlation mismatch/); await put([queued, user(inbox), user(inbox)]); await assert.rejects(observeClaudeDelivery({ root, ...options }), /not uniquely observed/); diff --git a/skills/agent-tmux/bin/claude-delivery-observation.mjs b/skills/agent-tmux/bin/claude-delivery-observation.mjs index 0d6b7a77..2abf8179 100644 --- a/skills/agent-tmux/bin/claude-delivery-observation.mjs +++ b/skills/agent-tmux/bin/claude-delivery-observation.mjs @@ -1,5 +1,5 @@ /** Read-only observation of one managed inbox record in a local Claude transcript. */ -import { constants } from 'node:fs'; +import { constants, lstatSync, realpathSync } from 'node:fs'; import { lstat, open, realpath, readdir } from 'node:fs/promises'; import { createHash } from 'node:crypto'; import { isAbsolute, join, resolve } from 'node:path'; @@ -17,13 +17,14 @@ export async function observeClaudeDelivery({ root, session, generation, message const matches = entries.filter(entry => entry.isFile() && entry.name.toLowerCase() === `${session.slice(7).toLowerCase()}.jsonl`).map(entry => join(entry.parentPath, entry.name)); if (matches.length !== 1 || await realpath(matches[0]) !== matches[0]) throw new Error('transcript identity unavailable or ambiguous'); const path = matches[0], file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); - let bytes; + let bytes, snapshotIdentity; try { const before = await file.stat(); if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > 128 * 1024 * 1024) throw new Error('invalid transcript file'); bytes = await file.readFile(); const after = await file.stat(), current = await lstat(path); if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + snapshotIdentity = { path, dev: after.dev, ino: after.ino, size: after.size, mtimeMs: after.mtimeMs, ctimeMs: after.ctimeMs }; } finally { await file.close(); } let text; try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } @@ -52,5 +53,15 @@ export async function observeClaudeDelivery({ root, session, generation, message if (queued !== 1 || found !== 1) throw new Error('delivery not uniquely observed'); const payloadSha256 = hash(payload), transcriptSha256 = hash(bytes); const evidence = `claude-transcript:${hash(JSON.stringify([session, generation, messageId, payloadSha256, transcriptSha256]))}`; - return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, evidence }; + return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, evidence, snapshotIdentity }; +} + +// Narrows the snapshot-to-graph race; it cannot exclude a writer after this check. +export function assertClaudeDeliverySnapshotCurrent(proof) { + const snapshot = proof?.snapshotIdentity; + if (!snapshot || typeof snapshot.path !== 'string' || !isAbsolute(snapshot.path)) throw new Error('transcript snapshot identity unavailable'); + let current; + try { current = lstatSync(snapshot.path); if (realpathSync(snapshot.path) !== snapshot.path) throw new Error(); } + catch { throw new Error('transcript snapshot unavailable'); } + if (!current.isFile() || current.isSymbolicLink() || current.uid !== process.getuid() || current.nlink !== 1 || (current.mode & 0o022) !== 0 || current.dev !== snapshot.dev || current.ino !== snapshot.ino || current.size !== snapshot.size || current.mtimeMs !== snapshot.mtimeMs || current.ctimeMs !== snapshot.ctimeMs) throw new Error('transcript changed after observation'); } diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index f588daf6..ad63b625 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -38,7 +38,7 @@ import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, observeDelivery, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; -import { observeClaudeDelivery } from "./claude-delivery-observation.mjs"; +import { observeClaudeDelivery, assertClaudeDeliverySnapshotCurrent } from "./claude-delivery-observation.mjs"; import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; import { prepareState, requestStateProof, revalidateStateProof } from "./handover-state-proof.mjs"; import { formatFinalNotice } from "./handover-notice.mjs"; @@ -168,6 +168,7 @@ try { const current = (graph.channels || []).find(item => item.id === name); const item = current?.queue?.find(row => row.id === id); if (!item || current.phase !== channel.phase || item.state !== 'inflight' || item.session !== proof.session || item.generation !== proof.generation || current.session !== proof.session || current.generation !== proof.generation || typeof item.payload !== 'string' || createHash('sha256').update(item.payload).digest('hex') !== proof.payloadSha256) throw new Error('delivery changed during recovery'); + assertClaudeDeliverySnapshotCurrent(proof); let next = acknowledge(current, id, { status: 'accepted', messageId: id, session: proof.session, generation: proof.generation }); if (next.phase === 'draining' && next.handover?.backlog?.includes(id)) next = observeDelivery(next, id, proof); return { graph, event: event('channel.updated', { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: next.queue.find(row => row.id === id).state } }; @@ -188,6 +189,7 @@ try { const current = (graph.channels || []).find(item => item.id === name); const item = current?.queue?.find(row => row.id === id); if (!item || typeof item.payload !== "string" || createHash("sha256").update(item.payload).digest("hex") !== proof.payloadSha256) throw new Error("delivery changed during observation"); + assertClaudeDeliverySnapshotCurrent(proof); const next = observeDelivery(current, id, proof); return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: "observed" } }; }); From de479326c63a72c61adecfe242826fd3888aa4a5 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 01:32:19 +0000 Subject: [PATCH 107/113] Make Claude delivery snapshots recheckable --- docs/design/plexus-channels.md | 6 ++++++ .../bin/claude-delivery-observation.mjs | 9 +++++++-- packages/tmux-bridge/bin/mesh-graph.mjs | 20 ++++++++++++++++++- .../test/plexus-channel-store.test.mjs | 8 +++++++- .../bin/claude-delivery-observation.mjs | 9 +++++++-- skills/agent-tmux/bin/mesh-graph.mjs | 20 ++++++++++++++++++- 6 files changed, 65 insertions(+), 7 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index c8c66699..cb2d3e71 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -285,6 +285,12 @@ has qualified the native transport and transcript shape in an isolated local fixture. This source does not prove execution, attention, finality or cloud delivery. Operational cutover remains disabled. +The graph stores the observed prefix length and digest, without copying the +transcript. `verify-claude-delivery` can recheck the same prefix after ordinary +appends. If the prefix is changed, truncated or unavailable, verification +fails; a digest alone is not an immutable copy or proof of later finality. +Older observations without this metadata cannot be reverified by this command. + A previously verified restart-state receipt can be revalidated against the current private file before a future cutover. Revalidation checks generation, session, digest, size and YAML, and rejects path replacement during the read. diff --git a/packages/tmux-bridge/bin/claude-delivery-observation.mjs b/packages/tmux-bridge/bin/claude-delivery-observation.mjs index 2abf8179..cab69f8d 100644 --- a/packages/tmux-bridge/bin/claude-delivery-observation.mjs +++ b/packages/tmux-bridge/bin/claude-delivery-observation.mjs @@ -8,8 +8,9 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a- const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; const hash = data => createHash('sha256').update(data).digest('hex'); -export async function observeClaudeDelivery({ root, session, generation, messageId, payload }) { +export async function observeClaudeDelivery({ root, session, generation, messageId, payload, snapshotBytes }) { if (typeof root !== 'string' || !isAbsolute(root) || typeof session !== 'string' || !session.startsWith('claude:') || !UUID.test(session.slice(7)) || !Number.isSafeInteger(generation) || generation < 1 || typeof messageId !== 'string' || !TOKEN.test(messageId) || typeof payload !== 'string' || !payload || Buffer.byteLength(payload) > 65536) throw new Error('invalid delivery observation request'); + if (snapshotBytes !== undefined && (!Number.isSafeInteger(snapshotBytes) || snapshotBytes < 1 || snapshotBytes > 128 * 1024 * 1024)) throw new Error('invalid transcript snapshot size'); root = resolve(root); const directory = await lstat(root); if (!directory.isDirectory() || directory.isSymbolicLink() || directory.uid !== process.getuid() || await realpath(root) !== root) throw new Error('invalid transcript root'); @@ -26,6 +27,10 @@ export async function observeClaudeDelivery({ root, session, generation, message if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); snapshotIdentity = { path, dev: after.dev, ino: after.ino, size: after.size, mtimeMs: after.mtimeMs, ctimeMs: after.ctimeMs }; } finally { await file.close(); } + if (snapshotBytes !== undefined) { + if (snapshotBytes > bytes.length) throw new Error('transcript snapshot truncated'); + bytes = bytes.subarray(0, snapshotBytes); + } let text; try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } if (!text.endsWith('\n')) throw new Error('partial transcript record'); @@ -53,7 +58,7 @@ export async function observeClaudeDelivery({ root, session, generation, message if (queued !== 1 || found !== 1) throw new Error('delivery not uniquely observed'); const payloadSha256 = hash(payload), transcriptSha256 = hash(bytes); const evidence = `claude-transcript:${hash(JSON.stringify([session, generation, messageId, payloadSha256, transcriptSha256]))}`; - return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, evidence, snapshotIdentity }; + return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, transcriptBytes: bytes.length, evidence, snapshotIdentity }; } // Narrows the snapshot-to-graph race; it cannot exclude a writer after this check. diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index ad63b625..9093c826 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -133,7 +133,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "recover-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "recover-claude-delivery", "verify-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -155,6 +155,22 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "verify-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const items = channel?.queue?.filter(item => item.id === id && ['accepted', 'observed'].includes(item.state) && item.session?.startsWith('claude:')); + const item = items?.length === 1 ? items[0] : undefined, saved = item?.deliveryProof; + if (!saved || typeof saved.evidence !== 'string' || !/^[0-9a-f]{64}$/.test(saved.transcriptSha256 || '') || !Number.isSafeInteger(saved.transcriptBytes)) throw new Error('Claude delivery proof unavailable'); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects'); + if (!isAbsolute(root)) throw new Error('invalid configured transcript root'); + const proof = await observeClaudeDelivery({ root, session: item.session, generation: item.generation, messageId: id, payload: item.payload, snapshotBytes: saved.transcriptBytes }); + assertClaudeDeliverySnapshotCurrent(proof); + if (proof.evidence !== saved.evidence || proof.transcriptSha256 !== saved.transcriptSha256) throw new Error('Claude delivery proof mismatch'); + const latest = (loadGraph(stateDir).channels || []).find(row => row.id === name)?.queue?.find(row => row.id === id); + if (!latest || latest.session !== item.session || latest.generation !== item.generation || latest.payload !== item.payload || JSON.stringify(latest.deliveryProof) !== JSON.stringify(saved)) throw new Error('delivery changed during verification'); + printResult({ channel: name, messageId: id, status: 'verified', evidence: proof.evidence }, { json: true }); + break; + } if (subcommand === "recover-claude-delivery") { const id = requiredSingleLine(values.id, "--id"); const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); @@ -171,6 +187,7 @@ try { assertClaudeDeliverySnapshotCurrent(proof); let next = acknowledge(current, id, { status: 'accepted', messageId: id, session: proof.session, generation: proof.generation }); if (next.phase === 'draining' && next.handover?.backlog?.includes(id)) next = observeDelivery(next, id, proof); + next.queue.find(row => row.id === id).deliveryProof = { evidence: proof.evidence, transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.transcriptBytes }; return { graph, event: event('channel.updated', { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: next.queue.find(row => row.id === id).state } }; }); printResult(result, { json: true }); @@ -191,6 +208,7 @@ try { if (!item || typeof item.payload !== "string" || createHash("sha256").update(item.payload).digest("hex") !== proof.payloadSha256) throw new Error("delivery changed during observation"); assertClaudeDeliverySnapshotCurrent(proof); const next = observeDelivery(current, id, proof); + next.queue.find(row => row.id === id).deliveryProof = { evidence: proof.evidence, transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.transcriptBytes }; return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: "observed" } }; }); printResult(result, { json: true }); diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs index 543ec1a7..770f6435 100644 --- a/packages/tmux-bridge/test/plexus-channel-store.test.mjs +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import { execFile } from 'node:child_process'; -import { appendFile, chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { appendFile, chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -198,6 +198,12 @@ test('local Claude delivery is observed only from a matching user transcript and await appendFile(path, JSON.stringify({ type: 'user', isMeta: true, sessionId: newId, message: { role: 'user', content: text } }) + '\n'); const result = await call('channel', 'observe-claude-delivery', '--name', 'example', '--id', 'one'); assert.equal(result.status, 'observed'); assert.match(result.evidence, /^claude-transcript:[a-f0-9]{64}$/); + await appendFile(path, JSON.stringify({ type: 'assistant', sessionId: newId }) + '\n'); + assert.equal((await call('channel', 'verify-claude-delivery', '--name', 'example', '--id', 'one')).status, 'verified'); + const original = await readFile(path, 'utf8'); + await writeFile(path, original.replace('fixture', 'changed')); + await assert.rejects(call('channel', 'verify-claude-delivery', '--name', 'example', '--id', 'one')); + await writeFile(path, original); await rm(join(state, 'checkpoint.json'), { force: true }); assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'observed'); }); diff --git a/skills/agent-tmux/bin/claude-delivery-observation.mjs b/skills/agent-tmux/bin/claude-delivery-observation.mjs index 2abf8179..cab69f8d 100644 --- a/skills/agent-tmux/bin/claude-delivery-observation.mjs +++ b/skills/agent-tmux/bin/claude-delivery-observation.mjs @@ -8,8 +8,9 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a- const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; const hash = data => createHash('sha256').update(data).digest('hex'); -export async function observeClaudeDelivery({ root, session, generation, messageId, payload }) { +export async function observeClaudeDelivery({ root, session, generation, messageId, payload, snapshotBytes }) { if (typeof root !== 'string' || !isAbsolute(root) || typeof session !== 'string' || !session.startsWith('claude:') || !UUID.test(session.slice(7)) || !Number.isSafeInteger(generation) || generation < 1 || typeof messageId !== 'string' || !TOKEN.test(messageId) || typeof payload !== 'string' || !payload || Buffer.byteLength(payload) > 65536) throw new Error('invalid delivery observation request'); + if (snapshotBytes !== undefined && (!Number.isSafeInteger(snapshotBytes) || snapshotBytes < 1 || snapshotBytes > 128 * 1024 * 1024)) throw new Error('invalid transcript snapshot size'); root = resolve(root); const directory = await lstat(root); if (!directory.isDirectory() || directory.isSymbolicLink() || directory.uid !== process.getuid() || await realpath(root) !== root) throw new Error('invalid transcript root'); @@ -26,6 +27,10 @@ export async function observeClaudeDelivery({ root, session, generation, message if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); snapshotIdentity = { path, dev: after.dev, ino: after.ino, size: after.size, mtimeMs: after.mtimeMs, ctimeMs: after.ctimeMs }; } finally { await file.close(); } + if (snapshotBytes !== undefined) { + if (snapshotBytes > bytes.length) throw new Error('transcript snapshot truncated'); + bytes = bytes.subarray(0, snapshotBytes); + } let text; try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } if (!text.endsWith('\n')) throw new Error('partial transcript record'); @@ -53,7 +58,7 @@ export async function observeClaudeDelivery({ root, session, generation, message if (queued !== 1 || found !== 1) throw new Error('delivery not uniquely observed'); const payloadSha256 = hash(payload), transcriptSha256 = hash(bytes); const evidence = `claude-transcript:${hash(JSON.stringify([session, generation, messageId, payloadSha256, transcriptSha256]))}`; - return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, evidence, snapshotIdentity }; + return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, transcriptBytes: bytes.length, evidence, snapshotIdentity }; } // Narrows the snapshot-to-graph race; it cannot exclude a writer after this check. diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index ad63b625..9093c826 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -133,7 +133,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "recover-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "recover-claude-delivery", "verify-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -155,6 +155,22 @@ try { printResult({ channel }, { json: true }); break; } + if (subcommand === "verify-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const items = channel?.queue?.filter(item => item.id === id && ['accepted', 'observed'].includes(item.state) && item.session?.startsWith('claude:')); + const item = items?.length === 1 ? items[0] : undefined, saved = item?.deliveryProof; + if (!saved || typeof saved.evidence !== 'string' || !/^[0-9a-f]{64}$/.test(saved.transcriptSha256 || '') || !Number.isSafeInteger(saved.transcriptBytes)) throw new Error('Claude delivery proof unavailable'); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects'); + if (!isAbsolute(root)) throw new Error('invalid configured transcript root'); + const proof = await observeClaudeDelivery({ root, session: item.session, generation: item.generation, messageId: id, payload: item.payload, snapshotBytes: saved.transcriptBytes }); + assertClaudeDeliverySnapshotCurrent(proof); + if (proof.evidence !== saved.evidence || proof.transcriptSha256 !== saved.transcriptSha256) throw new Error('Claude delivery proof mismatch'); + const latest = (loadGraph(stateDir).channels || []).find(row => row.id === name)?.queue?.find(row => row.id === id); + if (!latest || latest.session !== item.session || latest.generation !== item.generation || latest.payload !== item.payload || JSON.stringify(latest.deliveryProof) !== JSON.stringify(saved)) throw new Error('delivery changed during verification'); + printResult({ channel: name, messageId: id, status: 'verified', evidence: proof.evidence }, { json: true }); + break; + } if (subcommand === "recover-claude-delivery") { const id = requiredSingleLine(values.id, "--id"); const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); @@ -171,6 +187,7 @@ try { assertClaudeDeliverySnapshotCurrent(proof); let next = acknowledge(current, id, { status: 'accepted', messageId: id, session: proof.session, generation: proof.generation }); if (next.phase === 'draining' && next.handover?.backlog?.includes(id)) next = observeDelivery(next, id, proof); + next.queue.find(row => row.id === id).deliveryProof = { evidence: proof.evidence, transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.transcriptBytes }; return { graph, event: event('channel.updated', { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: next.queue.find(row => row.id === id).state } }; }); printResult(result, { json: true }); @@ -191,6 +208,7 @@ try { if (!item || typeof item.payload !== "string" || createHash("sha256").update(item.payload).digest("hex") !== proof.payloadSha256) throw new Error("delivery changed during observation"); assertClaudeDeliverySnapshotCurrent(proof); const next = observeDelivery(current, id, proof); + next.queue.find(row => row.id === id).deliveryProof = { evidence: proof.evidence, transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.transcriptBytes }; return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: "observed" } }; }); printResult(result, { json: true }); From b1b3a0cfd059e18b7f0a06830bc00ec60de5a1da Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 01:40:12 +0000 Subject: [PATCH 108/113] Gate explicit Codex backlog wake evidence --- docs/design/plexus-channels.md | 7 ++++ packages/tmux-bridge/bin/agent-waker.py | 39 +++++++++++++++++++ .../test/agent-waker-channel.test.py | 22 +++++++++++ skills/agent-tmux/bin/agent-waker.py | 39 +++++++++++++++++++ 4 files changed, 107 insertions(+) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index cb2d3e71..f464b446 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -272,6 +272,13 @@ schemas v3 and v4 with the correlated-recovery source are rejected. Reservations remain unresolved until an independently verified consumption source exists. This is not a cloud or Claude delivery adapter; native cutover remains disabled. +The channel waker can opt in to explicit Codex backlog wake with absolute +private graph and evidence roots, and without resume. It persists an attempt +before calling the producer, checks the graph settlement, and never retries an +uncertain attempt automatically. A submission that already left the native +queue remains unverified; this route does not provide complete wake coverage. +The option is disabled unless explicitly supplied and does not enable timers. + For a draining local Claude channel, `observe-claude-delivery` checks one managed inbox record in a stable local user transcript snapshot, binding its correlation, payload, session and generation before marking the backlog item diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index 9c4f93e7..37ac736e 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -206,6 +206,21 @@ def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str, r raise ValueError('invalid delivery observation') +def start_codex_channel_wake(args: argparse.Namespace, item: dict[str, Any], channel: dict[str, Any]) -> str: + session = channel['session'] + if not session.startswith('codex:') or not args.graph_state or not os.path.isabs(args.graph_state) or not os.path.isabs(args.wake_evidence_root): + raise ValueError('explicit private wake and graph roots required') + command = ['node', str(BIN / 'codex-wake-evidence.mjs'), '--apply', '--thread', session[6:], + '--queue-id', item['nativeQueueId'], '--correlation', item['id'], '--channel', args.channel, + '--generation', str(channel['generation']), '--evidence-root', args.wake_evidence_root, + '--graph-state', args.graph_state] + result = subprocess.run(command, text=True, capture_output=True, timeout=45, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or value.get('schema') != 'agent-mesh.wake-record.v1' or value.get('session') != session or value.get('settled') is not True or not re.fullmatch(r'codex-wake:[a-f0-9]{64}', str(value.get('evidence', ''))): + raise ValueError('wake proof not verified') + return value['evidence'] + + def cloud_target(target: str, root: str | None) -> tuple[str, str, str]: match = re.fullmatch(r'claude-cloud:([a-z][a-z0-9-]{0,63}):((?:session|cse)_[A-Za-z0-9]{1,128})', target) if not match or not root: @@ -287,6 +302,27 @@ def run_channel(args: argparse.Namespace) -> int: observe_claude_channel_delivery(args, awaiting['id']) print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'delivery observed'})) return 0 + if channel.get('phase') == 'draining' and channel.get('session', '').startswith('codex:') and getattr(args, 'wake_evidence_root', None): + backlog = channel.get('handover', {}).get('backlog', []) + awaiting = next((item for item in channel['queue'] if item.get('id') in backlog and item.get('state') == 'accepted'), None) + if awaiting: + identity = {'channel': args.channel, 'session': channel['session'], 'generation': channel['generation'], 'id': awaiting['id'], 'queueId': awaiting.get('nativeQueueId')} + if channel.get('wakeReservation') or state.get('wakeAttempt', {}).get('identity') == identity: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'wake attempt unresolved; inspect before retry'})) + return 3 + if not isinstance(identity['queueId'], str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', identity['queueId']): + raise ValueError('native queue identity unavailable') + state['wakeAttempt'] = {'identity': identity, 'status': 'attempted'} + save_state(path, state) + evidence = start_codex_channel_wake(args, awaiting, channel) + current = channel_call(args, 'get') + matched = [item for item in current['queue'] if item.get('id') == identity['id'] and item.get('session') == identity['session'] and item.get('generation') == identity['generation'] and item.get('state') == 'observed' and item.get('wakeEvidence') == evidence] + if current.get('session') != identity['session'] or current.get('generation') != identity['generation'] or len(matched) != 1: + raise ValueError('wake settlement not observed') + state['wakeAttempt']['status'] = 'verified' + save_state(path, state) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'wake verified'})) + return 0 pending = next((item for item in channel['queue'] if item.get('state') == 'pending'), None) if not pending: print(json.dumps({'job': args.job, 'outcome': 'noop'})) @@ -400,6 +436,7 @@ def main(argv: list[str] | None = None) -> int: recipient.add_argument("--session", help="owning session UUID") recipient.add_argument("--channel", help="stable channel identifier") runner.add_argument("--graph-state", help="override graph state for isolated tests") + runner.add_argument("--wake-evidence-root", help="opt in to explicit Codex backlog wake with a private evidence root") runner.add_argument("--cloud-profile-root", help="private directory for scoped cloud account profiles") runner.add_argument("--managed-inbox-root", help="required for Claude sessions") runner.add_argument("--delivery-only", action="store_true", help="acknowledge the native queue, without waiting for a result") @@ -408,6 +445,8 @@ def main(argv: list[str] | None = None) -> int: runner.add_argument("--producer-timeout", type=int, default=280) runner.add_argument("producer", nargs=argparse.REMAINDER, help="-- command that prints the JSON report") args = parser.parse_args(argv) + if args.wake_evidence_root and (not args.channel or not args.graph_state or not os.path.isabs(args.graph_state) or not os.path.isabs(args.wake_evidence_root) or args.resume): + parser.error('--wake-evidence-root requires --channel, absolute --graph-state, and no --resume') if args.channel and not args.delivery_only: parser.error("--channel requires --delivery-only") if args.resume and not args.channel and args.agent != "codex": diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index e6530419..74c0bd9a 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -18,6 +18,28 @@ class ChannelWakerTest(unittest.TestCase): + def test_codex_backlog_wake_is_opt_in_and_uncertainty_is_not_retried(self): + with tempfile.TemporaryDirectory() as directory: + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(Path(directory) / 'graph'), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False, wake_evidence_root=str(Path(directory) / 'evidence')) + channel = {'phase': 'draining', 'session': f'codex:{uuid}', 'generation': 2, 'handover': {'backlog': ['one']}, 'queue': [{'id': 'one', 'state': 'accepted', 'session': f'codex:{uuid}', 'generation': 2, 'nativeQueueId': 'queue-1'}]} + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', return_value=channel), patch.object(waker, 'start_codex_channel_wake', side_effect=ValueError('uncertain')) as start, patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + self.assertEqual(waker.run(args), 3) + self.assertEqual(start.call_count, 1) + deliver.assert_not_called() + self.assertEqual(json.loads(Path(args.state).read_text())['wakeAttempt']['status'], 'attempted') + + def test_codex_backlog_wake_requires_graph_settlement(self): + with tempfile.TemporaryDirectory() as directory: + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(Path(directory) / 'graph'), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False, wake_evidence_root=str(Path(directory) / 'evidence')) + evidence = 'codex-wake:' + 'a' * 64 + channel = {'phase': 'draining', 'session': f'codex:{uuid}', 'generation': 2, 'handover': {'backlog': ['one']}, 'queue': [{'id': 'one', 'state': 'accepted', 'session': f'codex:{uuid}', 'generation': 2, 'nativeQueueId': 'queue-1'}]} + observed = {**channel, 'queue': [{**channel['queue'][0], 'state': 'observed', 'wakeEvidence': evidence}]} + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', side_effect=[channel, observed]), patch.object(waker, 'start_codex_channel_wake', return_value=evidence), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 0) + deliver.assert_not_called() + self.assertEqual(json.loads(Path(args.state).read_text())['wakeAttempt']['status'], 'verified') + def test_lost_claude_receipt_recovers_from_correlated_transcript_without_resend(self): with tempfile.TemporaryDirectory() as directory: tmp = Path(directory) diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index 9c4f93e7..37ac736e 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -206,6 +206,21 @@ def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str, r raise ValueError('invalid delivery observation') +def start_codex_channel_wake(args: argparse.Namespace, item: dict[str, Any], channel: dict[str, Any]) -> str: + session = channel['session'] + if not session.startswith('codex:') or not args.graph_state or not os.path.isabs(args.graph_state) or not os.path.isabs(args.wake_evidence_root): + raise ValueError('explicit private wake and graph roots required') + command = ['node', str(BIN / 'codex-wake-evidence.mjs'), '--apply', '--thread', session[6:], + '--queue-id', item['nativeQueueId'], '--correlation', item['id'], '--channel', args.channel, + '--generation', str(channel['generation']), '--evidence-root', args.wake_evidence_root, + '--graph-state', args.graph_state] + result = subprocess.run(command, text=True, capture_output=True, timeout=45, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or value.get('schema') != 'agent-mesh.wake-record.v1' or value.get('session') != session or value.get('settled') is not True or not re.fullmatch(r'codex-wake:[a-f0-9]{64}', str(value.get('evidence', ''))): + raise ValueError('wake proof not verified') + return value['evidence'] + + def cloud_target(target: str, root: str | None) -> tuple[str, str, str]: match = re.fullmatch(r'claude-cloud:([a-z][a-z0-9-]{0,63}):((?:session|cse)_[A-Za-z0-9]{1,128})', target) if not match or not root: @@ -287,6 +302,27 @@ def run_channel(args: argparse.Namespace) -> int: observe_claude_channel_delivery(args, awaiting['id']) print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'delivery observed'})) return 0 + if channel.get('phase') == 'draining' and channel.get('session', '').startswith('codex:') and getattr(args, 'wake_evidence_root', None): + backlog = channel.get('handover', {}).get('backlog', []) + awaiting = next((item for item in channel['queue'] if item.get('id') in backlog and item.get('state') == 'accepted'), None) + if awaiting: + identity = {'channel': args.channel, 'session': channel['session'], 'generation': channel['generation'], 'id': awaiting['id'], 'queueId': awaiting.get('nativeQueueId')} + if channel.get('wakeReservation') or state.get('wakeAttempt', {}).get('identity') == identity: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'wake attempt unresolved; inspect before retry'})) + return 3 + if not isinstance(identity['queueId'], str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', identity['queueId']): + raise ValueError('native queue identity unavailable') + state['wakeAttempt'] = {'identity': identity, 'status': 'attempted'} + save_state(path, state) + evidence = start_codex_channel_wake(args, awaiting, channel) + current = channel_call(args, 'get') + matched = [item for item in current['queue'] if item.get('id') == identity['id'] and item.get('session') == identity['session'] and item.get('generation') == identity['generation'] and item.get('state') == 'observed' and item.get('wakeEvidence') == evidence] + if current.get('session') != identity['session'] or current.get('generation') != identity['generation'] or len(matched) != 1: + raise ValueError('wake settlement not observed') + state['wakeAttempt']['status'] = 'verified' + save_state(path, state) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'wake verified'})) + return 0 pending = next((item for item in channel['queue'] if item.get('state') == 'pending'), None) if not pending: print(json.dumps({'job': args.job, 'outcome': 'noop'})) @@ -400,6 +436,7 @@ def main(argv: list[str] | None = None) -> int: recipient.add_argument("--session", help="owning session UUID") recipient.add_argument("--channel", help="stable channel identifier") runner.add_argument("--graph-state", help="override graph state for isolated tests") + runner.add_argument("--wake-evidence-root", help="opt in to explicit Codex backlog wake with a private evidence root") runner.add_argument("--cloud-profile-root", help="private directory for scoped cloud account profiles") runner.add_argument("--managed-inbox-root", help="required for Claude sessions") runner.add_argument("--delivery-only", action="store_true", help="acknowledge the native queue, without waiting for a result") @@ -408,6 +445,8 @@ def main(argv: list[str] | None = None) -> int: runner.add_argument("--producer-timeout", type=int, default=280) runner.add_argument("producer", nargs=argparse.REMAINDER, help="-- command that prints the JSON report") args = parser.parse_args(argv) + if args.wake_evidence_root and (not args.channel or not args.graph_state or not os.path.isabs(args.graph_state) or not os.path.isabs(args.wake_evidence_root) or args.resume): + parser.error('--wake-evidence-root requires --channel, absolute --graph-state, and no --resume') if args.channel and not args.delivery_only: parser.error("--channel requires --delivery-only") if args.resume and not args.channel and args.agent != "codex": From 9cd04ec98babc315e3efda217478ec615ee06a8c Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 01:46:26 +0000 Subject: [PATCH 109/113] Check Codex wake readiness before reservation --- docs/design/plexus-channels.md | 6 ++++- packages/tmux-bridge/bin/agent-waker.py | 16 +++++++++++++ .../tmux-bridge/bin/codex-wake-evidence.mjs | 23 +++++++++++++++++-- .../test/agent-waker-channel.test.py | 13 +++++++++-- .../test/codex-wake-evidence.test.mjs | 9 ++++++++ skills/agent-tmux/bin/agent-waker.py | 16 +++++++++++++ skills/agent-tmux/bin/codex-wake-evidence.mjs | 23 +++++++++++++++++-- 7 files changed, 99 insertions(+), 7 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index f464b446..5f09e032 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -274,9 +274,13 @@ This is not a cloud or Claude delivery adapter; native cutover remains disabled. The channel waker can opt in to explicit Codex backlog wake with absolute private graph and evidence roots, and without resume. It persists an attempt -before calling the producer, checks the graph settlement, and never retries an +after a read-only native idle/queue preflight and before calling the producer, +checks the graph settlement, and never retries an uncertain attempt automatically. A submission that already left the native queue remains unverified; this route does not provide complete wake coverage. +The producer repeats the preflight before reserving a wake. Status may change +after either read; a raced or uncertain start remains unresolved rather than +being retried. The option is disabled unless explicitly supplied and does not enable timers. For a draining local Claude channel, `observe-claude-delivery` checks one diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index 37ac736e..10db0928 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -206,6 +206,19 @@ def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str, r raise ValueError('invalid delivery observation') +def preflight_codex_channel_wake(item: dict[str, Any], channel: dict[str, Any]) -> bool: + session = channel['session'] + if not session.startswith('codex:'): + raise ValueError('invalid Codex wake target') + command = ['node', str(BIN / 'codex-wake-evidence.mjs'), '--preflight', '--thread', session[6:], + '--queue-id', item['nativeQueueId'], '--correlation', item['id']] + result = subprocess.run(command, text=True, capture_output=True, timeout=20, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or value.get('schema') != 'agent-mesh.wake-preflight.v1' or value.get('session') != session or value.get('queueId') != item['nativeQueueId'] or value.get('correlation') != item['id'] or value.get('status') not in ('ready', 'not-ready'): + raise ValueError('invalid wake preflight') + return value['status'] == 'ready' + + def start_codex_channel_wake(args: argparse.Namespace, item: dict[str, Any], channel: dict[str, Any]) -> str: session = channel['session'] if not session.startswith('codex:') or not args.graph_state or not os.path.isabs(args.graph_state) or not os.path.isabs(args.wake_evidence_root): @@ -312,6 +325,9 @@ def run_channel(args: argparse.Namespace) -> int: return 3 if not isinstance(identity['queueId'], str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', identity['queueId']): raise ValueError('native queue identity unavailable') + if not preflight_codex_channel_wake(awaiting, channel): + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'wake not ready'})) + return 3 state['wakeAttempt'] = {'identity': identity, 'status': 'attempted'} save_state(path, state) evidence = start_codex_channel_wake(args, awaiting, channel) diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index ba131171..ae61d3b9 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -39,6 +39,22 @@ export async function observeAutoCodexWake() { throw new Error('auto wake observation disabled: queue consumption is unproven'); } +async function wakeReadiness(request, thread, queueId, correlation) { + const read = await request('thread/read', { threadId: thread, includeTurns: false }); + if (read?.thread?.id !== thread || !['idle', 'active', 'notLoaded', 'systemError'].includes(read.thread.status?.type)) throw new Error('native thread status unavailable'); + if (read.thread.status.type !== 'idle') return false; + const queue = await request('thread/queue/list', { threadId: thread, limit: 100 }); + if (!Array.isArray(queue?.data) || queue.nextCursor != null) throw new Error('native queue inventory incomplete'); + return queue.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length === 1; +} + +export async function preflightCodexWake({ thread, queueId, correlation }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6))) throw new Error('invalid wake preflight identity'); + thread = thread.toLowerCase(); + const ready = await withCodexAppServer({ clientName: 'agent-mesh-wake-preflight', timeout: 15000, timeoutMessage: 'native preflight unavailable' }, request => wakeReadiness(request, thread, queueId, correlation)); + return { schema: 'agent-mesh.wake-preflight.v1', session: `codex:${thread}`, queueId, correlation, status: ready ? 'ready' : 'not-ready' }; +} + export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { if (typeof reference !== 'string' || !/^codex-wake:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid wake verification request'); await privateRoot(evidenceRoot); @@ -90,6 +106,7 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge if (result.error || result.status !== 0 || !graph.migrated || matches.length !== 1 || matches[0].status === 'closed' || matches[0].surface?.archived === true) throw new Error('wake session not registered or closed'); const intent = hash(JSON.stringify([session, queueId])); const evidence = await withCodexAppServer({ clientName: 'agent-mesh-wake-evidence', timeout: 30000, timeoutMessage: 'native wake outcome uncertain' }, async request => { + if (!await wakeReadiness(request, thread, queueId, correlation)) throw new Error('native wake not ready'); const listed = await request('thread/queue/list', { threadId: thread, limit: 100 }); if (!Array.isArray(listed?.data) || listed.nextCursor != null || listed.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length !== 1) throw new Error('queued waker identity unavailable'); const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); @@ -119,10 +136,12 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { try { - const { values } = parseArgs({ options: { apply: { type: 'boolean' }, reconcile: { type: 'boolean' }, 'observe-auto': { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, preflight: { type: 'boolean' }, reconcile: { type: 'boolean' }, 'observe-auto': { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + if (values.preflight && (values.apply || values.reconcile || values['observe-auto'] || values.verify || values.publish)) throw new Error('conflicting wake operations'); if (values['observe-auto'] && (values.reconcile || values.verify || values.publish)) throw new Error('conflicting wake operations'); let result; - if (values['observe-auto']) result = await observeAutoCodexWake({ channel: values.channel, thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + if (values.preflight) result = await preflightCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation }); + else if (values['observe-auto']) result = await observeAutoCodexWake({ channel: values.channel, thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); else if (values.reconcile) result = await reconcileCodexWake({ channel: values.channel, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); else if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'], channel: values.channel }); diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py index 74c0bd9a..9ce7312c 100644 --- a/packages/tmux-bridge/test/agent-waker-channel.test.py +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -22,7 +22,7 @@ def test_codex_backlog_wake_is_opt_in_and_uncertainty_is_not_retried(self): with tempfile.TemporaryDirectory() as directory: args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(Path(directory) / 'graph'), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False, wake_evidence_root=str(Path(directory) / 'evidence')) channel = {'phase': 'draining', 'session': f'codex:{uuid}', 'generation': 2, 'handover': {'backlog': ['one']}, 'queue': [{'id': 'one', 'state': 'accepted', 'session': f'codex:{uuid}', 'generation': 2, 'nativeQueueId': 'queue-1'}]} - with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', return_value=channel), patch.object(waker, 'start_codex_channel_wake', side_effect=ValueError('uncertain')) as start, patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', return_value=channel), patch.object(waker, 'preflight_codex_channel_wake', return_value=True), patch.object(waker, 'start_codex_channel_wake', side_effect=ValueError('uncertain')) as start, patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): self.assertEqual(waker.run(args), 3) self.assertEqual(waker.run(args), 3) self.assertEqual(start.call_count, 1) @@ -35,11 +35,20 @@ def test_codex_backlog_wake_requires_graph_settlement(self): evidence = 'codex-wake:' + 'a' * 64 channel = {'phase': 'draining', 'session': f'codex:{uuid}', 'generation': 2, 'handover': {'backlog': ['one']}, 'queue': [{'id': 'one', 'state': 'accepted', 'session': f'codex:{uuid}', 'generation': 2, 'nativeQueueId': 'queue-1'}]} observed = {**channel, 'queue': [{**channel['queue'][0], 'state': 'observed', 'wakeEvidence': evidence}]} - with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', side_effect=[channel, observed]), patch.object(waker, 'start_codex_channel_wake', return_value=evidence), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', side_effect=[channel, observed]), patch.object(waker, 'preflight_codex_channel_wake', return_value=True), patch.object(waker, 'start_codex_channel_wake', return_value=evidence), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): self.assertEqual(waker.run(args), 0) deliver.assert_not_called() self.assertEqual(json.loads(Path(args.state).read_text())['wakeAttempt']['status'], 'verified') + def test_codex_busy_preflight_does_not_record_or_start_attempt(self): + with tempfile.TemporaryDirectory() as directory: + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(Path(directory) / 'graph'), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False, wake_evidence_root=str(Path(directory) / 'evidence')) + channel = {'phase': 'draining', 'session': f'codex:{uuid}', 'generation': 2, 'handover': {'backlog': ['one']}, 'queue': [{'id': 'one', 'state': 'accepted', 'session': f'codex:{uuid}', 'generation': 2, 'nativeQueueId': 'queue-1'}]} + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', return_value=channel), patch.object(waker, 'preflight_codex_channel_wake', return_value=False), patch.object(waker, 'start_codex_channel_wake') as start, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + start.assert_not_called() + self.assertNotIn('wakeAttempt', json.loads(Path(args.state).read_text())) + def test_lost_claude_receipt_recovers_from_correlated_transcript_without_resend(self): with tempfile.TemporaryDirectory() as directory: tmp = Path(directory) diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index 06ce3b4e..bcca2193 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -40,6 +40,7 @@ test('queued wake needs explicit apply, a native start and durable correlated pr requests.push(request); if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: mode === 'auto-drained' ? [] : [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: mode === 'wrong-queue-payload' ? 'different' : 'fixture', text_elements: [] }] }], nextCursor: null } }); else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: 123456789, items: [] } } }); + else if (request.method === 'thread/read' && request.params.includeTurns === false) peer.send({ id: request.id, result: { thread: { id: thread, status: { type: mode === 'busy' ? 'active' : 'idle' } } } }); else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, status: 'completed', startedAt: mode === 'wrong-time' ? 123456788 : mode === 'auto-same-second' ? Math.floor(autoReservedMs / 1000) : nativeId === 'queued-auto-proof' && mode !== 'auto-old-turn' ? Math.floor(Date.now() / 1000) : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', startedAtMs: nativeId === 'queued-auto-proof' ? Date.now() : 123456789001, clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture', text_elements: [] }] }] }] } } }); else peer.send({ id: request.id, result: {} }); }); @@ -47,6 +48,14 @@ test('queued wake needs explicit apply, a native start and durable correlated pr t.after(() => new Promise(resolve => server.close(resolve))); const env = { ...process.env, CODEX_REMOTE_SOCK: socket, CODEX_NO_REMOTE: '' }; const args = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', 'success', '--generation', '1', '--evidence-root', evidence, '--graph-state', state]; + mode = 'busy'; + const busy = JSON.parse((await exec(process.execPath, [bin, '--preflight', '--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation], { env })).stdout); + assert.equal(busy.status, 'not-ready'); + const beforeBusy = requests.filter(r => r.method === 'thread/queue/start').length; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, beforeBusy); + assert.equal((await call('channel', 'get', '--name', 'success')).channel.wakeReservation, undefined); + mode = 'success'; requests.length = 0; await assert.rejects(exec(process.execPath, [bin, ...args], { env })); assert.equal(requests.length, 0); await prepareChannel('handover'); diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index 37ac736e..10db0928 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -206,6 +206,19 @@ def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str, r raise ValueError('invalid delivery observation') +def preflight_codex_channel_wake(item: dict[str, Any], channel: dict[str, Any]) -> bool: + session = channel['session'] + if not session.startswith('codex:'): + raise ValueError('invalid Codex wake target') + command = ['node', str(BIN / 'codex-wake-evidence.mjs'), '--preflight', '--thread', session[6:], + '--queue-id', item['nativeQueueId'], '--correlation', item['id']] + result = subprocess.run(command, text=True, capture_output=True, timeout=20, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or value.get('schema') != 'agent-mesh.wake-preflight.v1' or value.get('session') != session or value.get('queueId') != item['nativeQueueId'] or value.get('correlation') != item['id'] or value.get('status') not in ('ready', 'not-ready'): + raise ValueError('invalid wake preflight') + return value['status'] == 'ready' + + def start_codex_channel_wake(args: argparse.Namespace, item: dict[str, Any], channel: dict[str, Any]) -> str: session = channel['session'] if not session.startswith('codex:') or not args.graph_state or not os.path.isabs(args.graph_state) or not os.path.isabs(args.wake_evidence_root): @@ -312,6 +325,9 @@ def run_channel(args: argparse.Namespace) -> int: return 3 if not isinstance(identity['queueId'], str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', identity['queueId']): raise ValueError('native queue identity unavailable') + if not preflight_codex_channel_wake(awaiting, channel): + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'wake not ready'})) + return 3 state['wakeAttempt'] = {'identity': identity, 'status': 'attempted'} save_state(path, state) evidence = start_codex_channel_wake(args, awaiting, channel) diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index ba131171..ae61d3b9 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -39,6 +39,22 @@ export async function observeAutoCodexWake() { throw new Error('auto wake observation disabled: queue consumption is unproven'); } +async function wakeReadiness(request, thread, queueId, correlation) { + const read = await request('thread/read', { threadId: thread, includeTurns: false }); + if (read?.thread?.id !== thread || !['idle', 'active', 'notLoaded', 'systemError'].includes(read.thread.status?.type)) throw new Error('native thread status unavailable'); + if (read.thread.status.type !== 'idle') return false; + const queue = await request('thread/queue/list', { threadId: thread, limit: 100 }); + if (!Array.isArray(queue?.data) || queue.nextCursor != null) throw new Error('native queue inventory incomplete'); + return queue.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length === 1; +} + +export async function preflightCodexWake({ thread, queueId, correlation }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6))) throw new Error('invalid wake preflight identity'); + thread = thread.toLowerCase(); + const ready = await withCodexAppServer({ clientName: 'agent-mesh-wake-preflight', timeout: 15000, timeoutMessage: 'native preflight unavailable' }, request => wakeReadiness(request, thread, queueId, correlation)); + return { schema: 'agent-mesh.wake-preflight.v1', session: `codex:${thread}`, queueId, correlation, status: ready ? 'ready' : 'not-ready' }; +} + export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { if (typeof reference !== 'string' || !/^codex-wake:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid wake verification request'); await privateRoot(evidenceRoot); @@ -90,6 +106,7 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge if (result.error || result.status !== 0 || !graph.migrated || matches.length !== 1 || matches[0].status === 'closed' || matches[0].surface?.archived === true) throw new Error('wake session not registered or closed'); const intent = hash(JSON.stringify([session, queueId])); const evidence = await withCodexAppServer({ clientName: 'agent-mesh-wake-evidence', timeout: 30000, timeoutMessage: 'native wake outcome uncertain' }, async request => { + if (!await wakeReadiness(request, thread, queueId, correlation)) throw new Error('native wake not ready'); const listed = await request('thread/queue/list', { threadId: thread, limit: 100 }); if (!Array.isArray(listed?.data) || listed.nextCursor != null || listed.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length !== 1) throw new Error('queued waker identity unavailable'); const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); @@ -119,10 +136,12 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { try { - const { values } = parseArgs({ options: { apply: { type: 'boolean' }, reconcile: { type: 'boolean' }, 'observe-auto': { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, preflight: { type: 'boolean' }, reconcile: { type: 'boolean' }, 'observe-auto': { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + if (values.preflight && (values.apply || values.reconcile || values['observe-auto'] || values.verify || values.publish)) throw new Error('conflicting wake operations'); if (values['observe-auto'] && (values.reconcile || values.verify || values.publish)) throw new Error('conflicting wake operations'); let result; - if (values['observe-auto']) result = await observeAutoCodexWake({ channel: values.channel, thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + if (values.preflight) result = await preflightCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation }); + else if (values['observe-auto']) result = await observeAutoCodexWake({ channel: values.channel, thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); else if (values.reconcile) result = await reconcileCodexWake({ channel: values.channel, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); else if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'], channel: values.channel }); From 1f18b1394fd22ce644cdf7a3f4374958ec220612 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 01:53:41 +0000 Subject: [PATCH 110/113] Confirm delayed Codex wake readback --- docs/design/plexus-channels.md | 3 ++ .../tmux-bridge/bin/codex-wake-evidence.mjs | 30 ++++++++++++++----- .../test/codex-wake-evidence.test.mjs | 12 ++++++-- skills/agent-tmux/bin/codex-wake-evidence.mjs | 30 ++++++++++++++----- 4 files changed, 57 insertions(+), 18 deletions(-) diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md index 5f09e032..116c5c03 100644 --- a/docs/design/plexus-channels.md +++ b/docs/design/plexus-channels.md @@ -266,6 +266,9 @@ generation, queue ID and correlation before starting it, then reads back the exact native message. When this proof is verified and settled in a draining channel, it marks that backlog message observed. Older proof schemas remain valid wake evidence but cannot establish this stronger delivery binding. +When a start response has no timestamp, the producer polls only the readback +for a bounded interval and accepts a timestamp only with the same turn and exact +correlated message. It never repeats the native start after acceptance. If a native start outcome is uncertain, readback-only recovery is disabled: a steered message can match while the submission remains queued. Recovery evidence schemas v3 and v4 with the correlated-recovery source are rejected. Reservations diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs index ae61d3b9..1cb59bd2 100644 --- a/packages/tmux-bridge/bin/codex-wake-evidence.mjs +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -120,14 +120,28 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge await createDurable(evidenceRoot, `intent-${intent}.json`, `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`); const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); const turn = started?.turn; - if (!turn || typeof turn.id !== 'string' || !UUID.test(turn.id) || turn.status !== 'inProgress' || !Number.isSafeInteger(turn.startedAt) || turn.startedAt <= 0) throw new Error('native wake outcome uncertain'); - const readback = await request('thread/read', { threadId: thread, includeTurns: true }); - const observed = readback?.thread; - const turns = Array.isArray(observed?.turns) ? observed.turns.filter(item => item?.id === turn.id) : []; - const observedTurn = turns[0]; - const messages = Array.isArray(observedTurn?.items) ? observedTurn.items.filter(item => item?.type === 'userMessage' && item.clientId === correlation) : []; - if (observed?.id !== thread || turns.length !== 1 || (observedTurn.itemsView !== undefined && observedTurn.itemsView !== 'full') || observedTurn.startedAt !== turn.startedAt || messages.length !== 1 || !Array.isArray(messages[0].content) || JSON.stringify(messages[0].content) !== JSON.stringify(queued.input)) throw new Error('wake readback unavailable; outcome uncertain'); - return { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.queue-start-bound-readback', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt, channel, generation, payloadSha256: hash(boundItems[0].payload) }; + if (!turn || typeof turn.id !== 'string' || !UUID.test(turn.id) || turn.status !== 'inProgress' || (turn.startedAt != null && (!Number.isSafeInteger(turn.startedAt) || turn.startedAt <= 0))) throw new Error('native wake outcome uncertain'); + // Some runtimes return a valid start with startedAt=null before the turn is + // persisted. Poll only readback; never repeat queue/start after acceptance. + const attempts = turn.startedAt == null ? 21 : 1; + let startedAt; + for (let i = 0; i < attempts; i++) { + const readback = await request('thread/read', { threadId: thread, includeTurns: true }); + const observed = readback?.thread; + if (observed?.id !== thread || !Array.isArray(observed.turns)) throw new Error('wake readback unavailable; outcome uncertain'); + const turns = observed.turns.filter(item => item?.id === turn.id); + if (turns.length > 1) throw new Error('wake readback ambiguous'); + const observedTurn = turns[0]; + const messages = Array.isArray(observedTurn?.items) ? observedTurn.items.filter(item => item?.type === 'userMessage' && item.clientId === correlation) : []; + if (messages.length > 1 || (messages.length === 1 && (!Array.isArray(messages[0].content) || JSON.stringify(messages[0].content) !== JSON.stringify(queued.input)))) throw new Error('wake readback mismatch'); + if (observedTurn && (observedTurn.itemsView === undefined || observedTurn.itemsView === 'full') && Number.isSafeInteger(observedTurn.startedAt) && observedTurn.startedAt > 0 && messages.length === 1) { + if (turn.startedAt != null && observedTurn.startedAt !== turn.startedAt) throw new Error('wake readback timestamp mismatch'); + startedAt = observedTurn.startedAt; break; + } + if (i + 1 < attempts) await new Promise(resolve => setTimeout(resolve, 200)); + } + if (!startedAt) throw new Error('wake readback unavailable; outcome uncertain'); + return { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.queue-start-bound-readback', session, queueId, correlation, turn: turn.id, startedAt, channel, generation, payloadSha256: hash(boundItems[0].payload) }; }); const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs index bcca2193..79ee06cd 100644 --- a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -34,13 +34,14 @@ test('queued wake needs explicit apply, a native start and durable correlated pr } await prepareChannel('success'); const cursor = (await call('query', 'changes', '--input', JSON.stringify({ initial: 'head' }))).cursor; - const requests = []; let mode = 'success', nativeId = 'queued-1', autoReservedMs = 0; + const requests = []; let mode = 'success', nativeId = 'queued-1', autoReservedMs = 0, delayedReads = 0; const server = createAppServer((request, peer) => { if (!request.id) return; requests.push(request); if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: mode === 'auto-drained' ? [] : [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: mode === 'wrong-queue-payload' ? 'different' : 'fixture', text_elements: [] }] }], nextCursor: null } }); - else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: 123456789, items: [] } } }); + else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: mode === 'null-start' ? null : 123456789, items: [] } } }); else if (request.method === 'thread/read' && request.params.includeTurns === false) peer.send({ id: request.id, result: { thread: { id: thread, status: { type: mode === 'busy' ? 'active' : 'idle' } } } }); + else if (request.method === 'thread/read' && mode === 'null-start' && delayedReads++ === 0) peer.send({ id: request.id, result: { thread: { id: thread, turns: [{ id: turn, startedAt: null, itemsView: 'full', items: [] }] } } }); else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, status: 'completed', startedAt: mode === 'wrong-time' ? 123456788 : mode === 'auto-same-second' ? Math.floor(autoReservedMs / 1000) : nativeId === 'queued-auto-proof' && mode !== 'auto-old-turn' ? Math.floor(Date.now() / 1000) : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', startedAtMs: nativeId === 'queued-auto-proof' ? Date.now() : 123456789001, clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture', text_elements: [] }] }] }] } } }); else peer.send({ id: request.id, result: {} }); }); @@ -177,6 +178,13 @@ test('queued wake needs explicit apply, a native start and durable correlated pr const oldBody = `${JSON.stringify(oldProof)}\n`, oldDigest = createHash('sha256').update(oldBody).digest('hex'); await writeFile(join(autoRoot, `wake-${oldDigest}.json`), oldBody, { mode: 0o600 }); await assert.rejects(verifyCodexWakeEvidence({ evidenceRoot: autoRoot, reference: `codex-wake:${oldDigest}`, session }), /identity mismatch/); + const delayedRoot = join(root, 'delayed'); await mkdir(delayedRoot, { mode: 0o700 }); + nativeId = 'queued-delayed'; await prepareChannel('delayed', nativeId); mode = 'null-start'; + const beforeDelayed = requests.filter(r => r.method === 'thread/queue/start').length; + const delayed = JSON.parse((await exec(process.execPath, [bin, '--apply', '--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'delayed', '--generation', '1', '--evidence-root', delayedRoot, '--graph-state', state], { env })).stdout); + assert.equal((await verifyCodexWakeEvidence({ evidenceRoot: delayedRoot, reference: delayed.evidence, session })).startedAt, 123456789); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, beforeDelayed + 1); + assert.ok(delayedReads >= 2); const file = join(evidence, `wake-${first.evidence.slice('codex-wake:'.length)}.json`); const saved = JSON.parse(await readFile(file, 'utf8')); saved.startedAt++; await writeFile(file, `${JSON.stringify(saved)}\n`); diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs index ae61d3b9..1cb59bd2 100644 --- a/skills/agent-tmux/bin/codex-wake-evidence.mjs +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -120,14 +120,28 @@ export async function startCodexWake({ thread, queueId, correlation, channel, ge await createDurable(evidenceRoot, `intent-${intent}.json`, `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`); const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); const turn = started?.turn; - if (!turn || typeof turn.id !== 'string' || !UUID.test(turn.id) || turn.status !== 'inProgress' || !Number.isSafeInteger(turn.startedAt) || turn.startedAt <= 0) throw new Error('native wake outcome uncertain'); - const readback = await request('thread/read', { threadId: thread, includeTurns: true }); - const observed = readback?.thread; - const turns = Array.isArray(observed?.turns) ? observed.turns.filter(item => item?.id === turn.id) : []; - const observedTurn = turns[0]; - const messages = Array.isArray(observedTurn?.items) ? observedTurn.items.filter(item => item?.type === 'userMessage' && item.clientId === correlation) : []; - if (observed?.id !== thread || turns.length !== 1 || (observedTurn.itemsView !== undefined && observedTurn.itemsView !== 'full') || observedTurn.startedAt !== turn.startedAt || messages.length !== 1 || !Array.isArray(messages[0].content) || JSON.stringify(messages[0].content) !== JSON.stringify(queued.input)) throw new Error('wake readback unavailable; outcome uncertain'); - return { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.queue-start-bound-readback', session, queueId, correlation, turn: turn.id, startedAt: turn.startedAt, channel, generation, payloadSha256: hash(boundItems[0].payload) }; + if (!turn || typeof turn.id !== 'string' || !UUID.test(turn.id) || turn.status !== 'inProgress' || (turn.startedAt != null && (!Number.isSafeInteger(turn.startedAt) || turn.startedAt <= 0))) throw new Error('native wake outcome uncertain'); + // Some runtimes return a valid start with startedAt=null before the turn is + // persisted. Poll only readback; never repeat queue/start after acceptance. + const attempts = turn.startedAt == null ? 21 : 1; + let startedAt; + for (let i = 0; i < attempts; i++) { + const readback = await request('thread/read', { threadId: thread, includeTurns: true }); + const observed = readback?.thread; + if (observed?.id !== thread || !Array.isArray(observed.turns)) throw new Error('wake readback unavailable; outcome uncertain'); + const turns = observed.turns.filter(item => item?.id === turn.id); + if (turns.length > 1) throw new Error('wake readback ambiguous'); + const observedTurn = turns[0]; + const messages = Array.isArray(observedTurn?.items) ? observedTurn.items.filter(item => item?.type === 'userMessage' && item.clientId === correlation) : []; + if (messages.length > 1 || (messages.length === 1 && (!Array.isArray(messages[0].content) || JSON.stringify(messages[0].content) !== JSON.stringify(queued.input)))) throw new Error('wake readback mismatch'); + if (observedTurn && (observedTurn.itemsView === undefined || observedTurn.itemsView === 'full') && Number.isSafeInteger(observedTurn.startedAt) && observedTurn.startedAt > 0 && messages.length === 1) { + if (turn.startedAt != null && observedTurn.startedAt !== turn.startedAt) throw new Error('wake readback timestamp mismatch'); + startedAt = observedTurn.startedAt; break; + } + if (i + 1 < attempts) await new Promise(resolve => setTimeout(resolve, 200)); + } + if (!startedAt) throw new Error('wake readback unavailable; outcome uncertain'); + return { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.queue-start-bound-readback', session, queueId, correlation, turn: turn.id, startedAt, channel, generation, payloadSha256: hash(boundItems[0].payload) }; }); const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); From 4b422c1e93b8e411f8a53a2de68233d6c2427bc8 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:05:26 +0000 Subject: [PATCH 111/113] Fence delayed trigger moves during recovery --- .../tmux-bridge/bin/trigger-transaction.mjs | 19 ++++---- .../tmux-bridge/test/trigger-journal.test.mjs | 48 +++++++++++++++++-- 2 files changed, 56 insertions(+), 11 deletions(-) diff --git a/packages/tmux-bridge/bin/trigger-transaction.mjs b/packages/tmux-bridge/bin/trigger-transaction.mjs index af48dd6b..5d5c1176 100644 --- a/packages/tmux-bridge/bin/trigger-transaction.mjs +++ b/packages/tmux-bridge/bin/trigger-transaction.mjs @@ -4,6 +4,8 @@ const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-] // begin must atomically reserve this ID and trigger set, rejecting unresolved // overlapping transactions. Each write must be durable before it resolves. // The adapter atomically compares target AND version and stores operationId. +// Every applied move, including a same-target move, must produce a fresh version. +// Versions must never be reused: recovery fences delayed in-flight moves with CAS. export async function reconcileTriggers({ triggers, from, to, transactionId, adapter, journal, dryRun = true }) { if (!Array.isArray(triggers) || triggers.length > 256 || !token(from) || !token(to) || from === to || !token(transactionId) || transactionId.length > 90 || typeof dryRun !== 'boolean' || typeof adapter?.read !== 'function' || typeof adapter?.move !== 'function' || typeof journal?.begin !== 'function' || typeof journal?.write !== 'function') throw new Error('invalid trigger transaction'); const seen = new Set(); @@ -36,7 +38,7 @@ export async function reconcileTriggers({ triggers, from, to, transactionId, ada let response; try { response = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: from, expectedVersion: row.before, target: to, operationId }); } catch { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } - if (response?.status !== 'applied' || !token(response.version)) { + if (response?.status !== 'applied' || !token(response.version) || response.version === row.before) { row.status = response?.status === 'not-applied' ? 'not-applied' : 'uncertain'; receipt.status = row.status === 'uncertain' ? 'uncertain' : 'rolling-back'; await save(); if (row.status === 'uncertain') return receipt; @@ -46,7 +48,7 @@ export async function reconcileTriggers({ triggers, from, to, transactionId, ada let rollback; try { rollback = await adapter.move({ kind: prior.kind, id: prior.id, expectedTarget: to, expectedVersion: prior.after, target: from, operationId: rollbackId }); } catch { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } - if (rollback?.status !== 'applied' || !token(rollback.version)) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + if (rollback?.status !== 'applied' || !token(rollback.version) || rollback.version === prior.after) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } let observed; try { observed = await adapter.read(prior); } catch { /* The rollback may have applied. */ } if (observed?.target !== from || observed.version !== rollback.version || observed.lastOperationId !== rollbackId) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } @@ -79,19 +81,20 @@ export async function recoverUncertainTriggers({ transactionId, adapter, journal } for (let i = receipt.triggers.length - 1; i >= 0; i--) { const row = receipt.triggers[i], { kind, observed } = observations[i]; - if (kind !== 'moved') { - row.status = kind === 'unchanged' ? 'not-applied' : 'rolled-back'; - if (kind === 'rolled-back') row.rollbackVersion = observed.version; + if (kind === 'rolled-back') { + if (observed.version === row.before) throw new Error('rollback version is not a fence'); + row.status = 'rolled-back'; row.rollbackVersion = observed.version; continue; } const operationId = `${transactionId}:rollback:${i}`; - row.after = observed.version; row.status = 'rolling-back'; receipt.status = 'rolling-back'; await save(receipt); + if (kind === 'moved') row.after = observed.version; + row.status = 'rolling-back'; receipt.status = 'rolling-back'; await save(receipt); let result, confirmed; try { - result = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: receipt.to, expectedVersion: observed.version, target: receipt.from, operationId }); + result = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: kind === 'moved' ? receipt.to : receipt.from, expectedVersion: observed.version, target: receipt.from, operationId }); if (result?.status === 'applied' && token(result.version)) confirmed = await adapter.read(row); } catch { /* The outcome may have been applied. */ } - if (confirmed?.target !== receipt.from || confirmed.version !== result?.version || confirmed.lastOperationId !== operationId) { + if (confirmed?.target !== receipt.from || confirmed.version !== result?.version || confirmed.version === observed.version || confirmed.lastOperationId !== operationId) { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(receipt); return receipt; } row.status = 'rolled-back'; row.rollbackVersion = result.version; await save(receipt); diff --git a/packages/tmux-bridge/test/trigger-journal.test.mjs b/packages/tmux-bridge/test/trigger-journal.test.mjs index a0a5bbae..15562212 100644 --- a/packages/tmux-bridge/test/trigger-journal.test.mjs +++ b/packages/tmux-bridge/test/trigger-journal.test.mjs @@ -160,12 +160,12 @@ test('lost rollback readback stays uncertain until the rollback is observed', as read: async ({ id }) => { if (failRead) { failRead = false; throw new Error('read unavailable'); } return structuredClone(state.get(id)); }, move: async args => { moves++; - if (args.id === 'two') return { status: 'not-applied' }; + if (args.id === 'two' && args.target === 'codex:new') return { status: 'not-applied' }; const current = state.get(args.id); assert.equal(current.target, args.expectedTarget); assert.equal(current.version, args.expectedVersion); const next = { target: args.target, version: `v${moves + 1}`, lastOperationId: args.operationId }; state.set(args.id, next); - if (args.operationId.includes(':rollback:')) failRead = true; + if (args.id === 'one' && args.operationId.includes(':rollback:')) failRead = true; return { status: 'applied', version: next.version }; } }; @@ -174,5 +174,47 @@ test('lost rollback readback stays uncertain until the rollback is observed', as assert.equal(result.status, 'uncertain'); assert.equal(state.get('one').target, 'codex:old'); assert.equal((await triggerJournal(root).get('tx')).status, 'uncertain'); const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal: triggerJournal(root) }); - assert.equal(recovered.status, 'rolled-back'); assert.equal(moves, 3); + assert.equal(recovered.status, 'rolled-back'); assert.equal(moves, 4); +}); + + +test('recovery fences a delayed forward CAS before declaring rollback', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-fence-')); + t.after(() => rm(root, { recursive: true, force: true })); + let state = { target: 'old', version: 'v1' }, release, entered; + const reached = new Promise(resolve => { entered = resolve; }); + const gate = new Promise(resolve => { release = resolve; }); + const adapter = { + read: async () => structuredClone(state), + move: async args => { + if (args.operationId === 'tx:0') { entered(); await gate; } + if (state.target !== args.expectedTarget || state.version !== args.expectedVersion) return { status: 'not-applied' }; + state = { target: args.target, version: 'v2', lastOperationId: args.operationId }; + return { status: 'applied', version: state.version }; + } + }; + const journal = triggerJournal(root), triggers = [{ kind: 'fixture', id: 'one' }]; + const writer = reconcileTriggers({ triggers, from: 'old', to: 'new', transactionId: 'tx', adapter, journal, dryRun: false }).catch(error => error); + await reached; + const receipt = (await journal.get('tx')).receipt; + receipt.status = 'uncertain'; receipt.triggers[0].status = 'uncertain'; + await journal.write(receipt); + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); + assert.equal(recovered.status, 'rolled-back'); assert.equal(state.version, 'v2'); + release(); await writer; + assert.equal(state.target, 'old'); assert.equal(state.lastOperationId, 'tx:rollback:0'); + assert.equal((await journal.get('tx')).status, 'rolled-back'); +}); + +test('recovery refuses an adapter which reuses a version for the fence', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-fence-')); + t.after(() => rm(root, { recursive: true, force: true })); + const journal = triggerJournal(root), triggers = [{ kind: 'fixture', id: 'one' }]; + await journal.begin({ id: 'tx', triggers, dryRun: false }); + await journal.write({ schema: 'agent-mesh.trigger-transaction.v1', id: 'tx', from: 'old', to: 'new', dryRun: false, status: 'uncertain', triggers: [{ ...triggers[0], before: 'v1', status: 'uncertain' }] }); + let operation; + const adapter = { read: async () => ({ target: 'old', version: 'v1', lastOperationId: operation }), move: async args => { operation = args.operationId; return { status: 'applied', version: 'v1' }; } }; + const result = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); + assert.equal(result.status, 'uncertain'); + await assert.rejects(journal.begin({ id: 'other', triggers, dryRun: false }), /overlapping/); }); From 169537949ab3c73186855912590d762eff15707e Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:06:50 +0000 Subject: [PATCH 112/113] Fence stale trigger journal writers on recovery --- packages/tmux-bridge/bin/trigger-journal.mjs | 22 ++++++++++----- .../tmux-bridge/bin/trigger-transaction.mjs | 4 +-- .../tmux-bridge/test/trigger-journal.test.mjs | 27 ++++++++++++++++--- 3 files changed, 40 insertions(+), 13 deletions(-) diff --git a/packages/tmux-bridge/bin/trigger-journal.mjs b/packages/tmux-bridge/bin/trigger-journal.mjs index fa92734e..665872ee 100644 --- a/packages/tmux-bridge/bin/trigger-journal.mjs +++ b/packages/tmux-bridge/bin/trigger-journal.mjs @@ -24,7 +24,7 @@ export function triggerJournal(root) { const info = fstatSync(fd); if (!info.isFile() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0 || info.size > 8 * 1024 * 1024) throw new Error('invalid journal file'); const data = JSON.parse(readFileSync(fd, 'utf8')); - if (data?.schema !== 'agent-mesh.trigger-journal.v1' || !Array.isArray(data.entries) || new Set(data.entries.map(entry => entry?.id)).size !== data.entries.length || data.entries.some(entry => !token(entry?.id) || typeof entry.dryRun !== 'boolean' || !Array.isArray(entry.triggers) || entry.triggers.some(t => !token(t?.kind) || !token(t?.id)) || new Set(entry.triggers.map(key)).size !== entry.triggers.length || !statuses.has(entry.status))) throw new Error('invalid journal content'); + if (data?.schema !== 'agent-mesh.trigger-journal.v1' || !Array.isArray(data.entries) || new Set(data.entries.map(entry => entry?.id)).size !== data.entries.length || data.entries.some(entry => !token(entry?.id) || typeof entry.dryRun !== 'boolean' || !Array.isArray(entry.triggers) || entry.triggers.some(t => !token(t?.kind) || !token(t?.id)) || new Set(entry.triggers.map(key)).size !== entry.triggers.length || !statuses.has(entry.status) || (entry.epoch !== undefined && (!Number.isSafeInteger(entry.epoch) || entry.epoch < 0)))) throw new Error('invalid journal content'); return data; } finally { closeSync(fd); } }; @@ -56,13 +56,14 @@ export function triggerJournal(root) { if (data.entries.some(entry => entry.id === id)) throw new Error('transaction already reserved'); const requested = new Set(triggers.map(key)); if (data.entries.some(entry => !terminal.has(entry.status) && entry.triggers.some(trigger => requested.has(key(trigger))))) throw new Error('overlapping transaction unresolved'); - data.entries.push({ id, dryRun, status: 'planning', triggers: structuredClone(triggers), receipt: null }); + data.entries.push({ id, dryRun, status: 'planning', triggers: structuredClone(triggers), receipt: null, epoch: 0 }); + return 0; }); }, - async write(receipt) { + async write(receipt, epoch = 0) { return transaction(data => { const entry = data.entries.find(item => item.id === receipt?.id); - if (!entry || terminal.has(entry.status) || receipt.schema !== 'agent-mesh.trigger-transaction.v1' || receipt.dryRun !== entry.dryRun || !statuses.has(receipt.status) || !Array.isArray(receipt.triggers) || JSON.stringify(receipt.triggers.map(key)) !== JSON.stringify(entry.triggers.map(key))) throw new Error('invalid journal update'); + if (!entry || (entry.epoch ?? 0) !== epoch || terminal.has(entry.status) || receipt.schema !== 'agent-mesh.trigger-transaction.v1' || receipt.dryRun !== entry.dryRun || !statuses.has(receipt.status) || !Array.isArray(receipt.triggers) || JSON.stringify(receipt.triggers.map(key)) !== JSON.stringify(entry.triggers.map(key))) throw new Error('invalid journal update'); entry.status = receipt.status; entry.receipt = structuredClone(receipt); }); }, @@ -81,9 +82,16 @@ export function triggerJournal(root) { catch (error) { if (error.code === 'EEXIST') throw new Error('recovery lock held or requires reconciliation'); throw error; } try { fsyncSync(fd); syncRoot(); - const journal = triggerJournal(root), entry = await journal.get(id); - if (!entry || entry.status !== 'uncertain' || !entry.receipt) throw new Error('transaction not recoverable'); - return await callback(entry.receipt, receipt => journal.write(receipt)); + const journal = triggerJournal(root); + const takeover = transaction(data => { + const entry = data.entries.find(item => item.id === id); + if (!entry || entry.dryRun || !['uncertain', 'applying', 'rolling-back'].includes(entry.status) || !entry.receipt) throw new Error('transaction not recoverable'); + const epoch = (entry.epoch ?? 0) + 1; + if (!Number.isSafeInteger(epoch)) throw new Error('transaction epoch exhausted'); + entry.epoch = epoch; entry.status = 'uncertain'; entry.receipt.status = 'uncertain'; + return { epoch, receipt: structuredClone(entry.receipt) }; + }); + return await callback(takeover.receipt, receipt => journal.write(receipt, takeover.epoch)); } finally { const owned = fstatSync(fd); closeSync(fd); const current = lstatSync(recoveryLock); diff --git a/packages/tmux-bridge/bin/trigger-transaction.mjs b/packages/tmux-bridge/bin/trigger-transaction.mjs index 5d5c1176..87fd0d93 100644 --- a/packages/tmux-bridge/bin/trigger-transaction.mjs +++ b/packages/tmux-bridge/bin/trigger-transaction.mjs @@ -14,8 +14,8 @@ export async function reconcileTriggers({ triggers, from, to, transactionId, ada seen.add(`${trigger.kind}\0${trigger.id}`); } const receipt = { schema: 'agent-mesh.trigger-transaction.v1', id: transactionId, from, to, dryRun, status: 'planning', triggers: triggers.map(({ kind, id }) => ({ kind, id, status: 'pending' })) }; - await journal.begin({ id: transactionId, triggers: structuredClone(triggers), dryRun }); - const save = () => journal.write(structuredClone(receipt)); + const epoch = await journal.begin({ id: transactionId, triggers: structuredClone(triggers), dryRun }); + const save = () => journal.write(structuredClone(receipt), epoch); for (let i = 0; i < triggers.length; i++) { let current; try { current = await adapter.read(triggers[i]); } catch { /* No mutation has been attempted. */ } diff --git a/packages/tmux-bridge/test/trigger-journal.test.mjs b/packages/tmux-bridge/test/trigger-journal.test.mjs index 15562212..06582e89 100644 --- a/packages/tmux-bridge/test/trigger-journal.test.mjs +++ b/packages/tmux-bridge/test/trigger-journal.test.mjs @@ -196,12 +196,11 @@ test('recovery fences a delayed forward CAS before declaring rollback', async t const journal = triggerJournal(root), triggers = [{ kind: 'fixture', id: 'one' }]; const writer = reconcileTriggers({ triggers, from: 'old', to: 'new', transactionId: 'tx', adapter, journal, dryRun: false }).catch(error => error); await reached; - const receipt = (await journal.get('tx')).receipt; - receipt.status = 'uncertain'; receipt.triggers[0].status = 'uncertain'; - await journal.write(receipt); + assert.equal((await journal.get('tx')).status, 'applying'); const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); assert.equal(recovered.status, 'rolled-back'); assert.equal(state.version, 'v2'); - release(); await writer; + release(); const staleWriter = await writer; + assert.match(staleWriter.message, /invalid journal update/); assert.equal(state.target, 'old'); assert.equal(state.lastOperationId, 'tx:rollback:0'); assert.equal((await journal.get('tx')).status, 'rolled-back'); }); @@ -218,3 +217,23 @@ test('recovery refuses an adapter which reuses a version for the fence', async t assert.equal(result.status, 'uncertain'); await assert.rejects(journal.begin({ id: 'other', triggers, dryRun: false }), /overlapping/); }); + + +test('takeover of a crashed applying transaction rolls back a proven move', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-crash-')); + t.after(() => rm(root, { recursive: true, force: true })); + const journal = triggerJournal(root), triggers = [{ kind: 'fixture', id: 'one' }]; + await journal.begin({ id: 'tx', triggers, dryRun: false }); + const interrupted = { schema: 'agent-mesh.trigger-transaction.v1', id: 'tx', from: 'old', to: 'new', dryRun: false, status: 'applying', triggers: [{ ...triggers[0], before: 'v1', status: 'applying', operationId: 'tx:0' }] }; + await journal.write(interrupted); + let state = { target: 'new', version: 'v2', lastOperationId: 'tx:0' }; + const adapter = { read: async () => structuredClone(state), move: async args => { + assert.equal(args.expectedTarget, state.target); assert.equal(args.expectedVersion, state.version); + state = { target: args.target, version: 'v3', lastOperationId: args.operationId }; + return { status: 'applied', version: state.version }; + } }; + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); + assert.equal(recovered.status, 'rolled-back'); assert.equal(state.target, 'old'); + await assert.rejects(journal.write(interrupted, 0), /invalid journal update/); + assert.equal((await journal.get('tx')).epoch, 1); +}); From 907f06e41a73d7802b8456548fa0056279cf87b4 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:08:23 +0000 Subject: [PATCH 113/113] Exercise trigger takeover across processes --- packages/tmux-bridge/docs/lifecycle.md | 6 +++ .../test/trigger-cross-process.test.mjs | 50 +++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 packages/tmux-bridge/test/trigger-cross-process.test.mjs diff --git a/packages/tmux-bridge/docs/lifecycle.md b/packages/tmux-bridge/docs/lifecycle.md index b9221610..3c522d04 100644 --- a/packages/tmux-bridge/docs/lifecycle.md +++ b/packages/tmux-bridge/docs/lifecycle.md @@ -439,3 +439,9 @@ Semantic skips do not consume the eligible-action target. For example, a hook budget of 200 can process 100 refusals and then prepare ten eligible summaries; it stops before creating an eleventh summary or expanding the review pool. Existing larger frozen plans still retain the ten-confirmed-success apply cap. + +### Trigger recovery contract + +Trigger reconciliation is inactive unless an operator supplies an adapter and a private journal. The adapter must atomically compare both target and version, record the operation ID, and issue a fresh, never-reused version on every applied move, including a same-target move. A backend that cannot enforce this contract must not be used for recovery. + +Recovery takes over an `applying`, `rolling-back`, or `uncertain` journal entry by advancing its durable epoch. Stale journal writers are rejected. It reads all targets and uses CAS to restore or fence each one before recording rollback; an unverified response remains uncertain. A process can die while holding a journal or recovery lock: these locks fail closed and require separate reconciliation; this mechanism does not automatically clear them. A successful synthetic test does not establish that any real trigger backend meets the contract. diff --git a/packages/tmux-bridge/test/trigger-cross-process.test.mjs b/packages/tmux-bridge/test/trigger-cross-process.test.mjs new file mode 100644 index 00000000..814274b2 --- /dev/null +++ b/packages/tmux-bridge/test/trigger-cross-process.test.mjs @@ -0,0 +1,50 @@ +import assert from 'node:assert/strict'; +import { execFileSync, fork } from 'node:child_process'; +import { mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; +import test from 'node:test'; +import { triggerJournal } from '../bin/trigger-journal.mjs'; +import { recoverUncertainTriggers } from '../bin/trigger-transaction.mjs'; + +// The SQLite adapter is a disposable, durable CAS fixture, not an adapter for live timers. +const python = `import json, sqlite3, sys\ndb=sqlite3.connect(sys.argv[1], timeout=5, isolation_level=None)\nmode=sys.argv[2]\nif mode=='init':\n db.execute('CREATE TABLE state(target TEXT, version INTEGER, op TEXT)')\n db.execute('INSERT INTO state VALUES(?,?,?)',('old',1,None))\nelif mode=='read':\n r=db.execute('SELECT target,version,op FROM state').fetchone()\n print(json.dumps(dict(target=r[0],version='v'+str(r[1]),lastOperationId=r[2])))\nelse:\n a=json.loads(sys.argv[3]); db.execute('BEGIN IMMEDIATE')\n r=db.execute('SELECT target,version FROM state').fetchone()\n if r[0]!=a['expectedTarget'] or 'v'+str(r[1])!=a['expectedVersion']:\n db.execute('ROLLBACK'); print(json.dumps(dict(status='not-applied')))\n else:\n v=r[1]+1; db.execute('UPDATE state SET target=?,version=?,op=?',(a['target'],v,a['operationId'])); db.execute('COMMIT'); print(json.dumps(dict(status='applied',version='v'+str(v))))\n`; +const worker = `import { execFileSync } from 'node:child_process'; +import { triggerJournal } from ${JSON.stringify(new URL('../bin/trigger-journal.mjs', import.meta.url).href)}; +import { reconcileTriggers } from ${JSON.stringify(new URL('../bin/trigger-transaction.mjs', import.meta.url).href)}; +const [root, script, db, mode] = process.argv.slice(2); +const call = (op, arg) => JSON.parse(execFileSync('python3', [script, db, op, ...(arg ? [JSON.stringify(arg)] : [])], {encoding:'utf8'})); +const adapter = { read: async () => call('read'), move: async args => { + if (mode === 'delayed' && args.operationId === 'tx:0') { process.send('waiting'); await new Promise(resolve => process.once('message', resolve)); } + const result = call('cas', args); + if (mode === 'crash' && args.operationId === 'tx:0') { process.send('applied'); await new Promise(() => {}); } + return result; +} }; +try { await reconcileTriggers({triggers:[{kind:'fixture',id:'one'}],from:'old',to:'new',transactionId:'tx',adapter,journal:triggerJournal(root),dryRun:false}); process.send('completed'); } +catch { process.send('fenced'); } +`; + +for (const mode of ['delayed', 'crash']) test(`cross-process ${mode} trigger recovery`, { timeout: 15000 }, async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-cross-')); + t.after(() => rm(root, { recursive: true, force: true })); + const script = join(root, 'cas.py'), workerFile = join(root, 'worker.mjs'), db = join(root, 'fixture.db'); + await writeFile(script, python); await writeFile(workerFile, worker); + execFileSync('python3', [script, db, 'init']); + const call = (op, arg) => JSON.parse(execFileSync('python3', [script, db, op, ...(arg ? [JSON.stringify(arg)] : [])], { encoding: 'utf8' })); + const adapter = { read: async () => call('read'), move: async args => call('cas', args) }; + const child = fork(workerFile, [root, script, db, mode], { stdio: ['ignore', 'ignore', 'pipe', 'ipc'] }); + t.after(() => { if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL'); }); + const message = () => new Promise((resolve, reject) => { child.once('message', resolve); child.once('error', reject); }); + assert.equal(await message(), mode === 'delayed' ? 'waiting' : 'applied'); + if (mode === 'crash') { + const exited = new Promise(resolve => child.once('exit', resolve)); child.kill('SIGKILL'); await exited; + } + const journal = triggerJournal(root); + assert.equal((await journal.get('tx')).status, 'applying'); + const result = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); + assert.equal(result.status, 'rolled-back'); + if (mode === 'delayed') { const ended = message(); child.send('continue'); assert.equal(await ended, 'fenced'); } + const final = call('read'); + assert.equal(final.target, 'old'); assert.equal(final.lastOperationId, 'tx:rollback:0'); + assert.equal((await journal.get('tx')).status, 'rolled-back'); +});