pmx-canvas 0.4.7 → 0.5.0

package/dist/types/shared/auto-arrange.d.ts

@@ -12,7 +12,6 @@ export interface ArrangeNode {
     position: ArrangePosition;
     size: ArrangeSize;
     pinned: boolean;
-    dockPosition: 'left' | 'right' | null;
     data: Record<string, unknown>;
 }
 export interface ArrangeEdge {

package/dist/types/shared/ax-kinds.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AX status and kind unions shared by the server's state model and the
+ * client's session panel, so a new status cannot be added on one side and
+ * silently render unrecognized on the other.
+ */
+export type AxWorkItemStatus = 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
+/** `held` = auto-held by the unattended-approval policy: the action did NOT proceed. */
+export type AxApprovalStatus = 'pending' | 'approved' | 'rejected' | 'held';
+export type AxEventKind = 'prompt' | 'assistant-message' | 'tool-start' | 'tool-result' | 'failure' | 'approval' | 'steering' | 'command' | 'note' | 'policy'
+/** A human took over a node the agent was editing; the agent yielded (rail-chrome-v2 item 6). */
+ | 'yield';

package/dist/types/shared/human-presence.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Human collaborator presence (rail-chrome-v2 phase 8, design items 5 and 6).
+ * Every open workbench tab is a client; the server fans the set out over SSE
+ * so tabs see each other's cursors, and an agent write to a node a human is
+ * holding is refused until the grab ends (user wins). In-memory, TTL-swept,
+ * never persisted — like agent presence.
+ */
+export interface HumanPresence {
+    /** Per-tab id (sessionStorage), never an identity. */
+    clientId: string;
+    /** Display name shown on the cursor tag. */
+    name: string;
+    /** World coordinates of the pointer, null when it left the canvas. */
+    cursor: {
+        x: number;
+        y: number;
+    } | null;
+    /** The node this human is dragging or editing right now. */
+    grabbingNodeId: string | null;
+    lastSeenAt: string;
+}
+export interface HumanPresenceSnapshot {
+    humans: HumanPresence[];
+}
+/** A tab that stops reporting is gone after this. */
+export declare const HUMAN_PRESENCE_TTL_MS = 30000;
+/** A grab the tab stops renewing (crash, tab closed mid-drag) releases after this. */
+export declare const HUMAN_GRAB_TTL_MS = 8000;
+/** Cursor updates are throttled to this on the client. */
+export declare const HUMAN_CURSOR_THROTTLE_MS = 80;
+export declare const MAX_HUMANS = 32;

package/dist/types/shared/iframe-probe.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Handshake contract between /api/canvas/iframe-probe (server document) and
+ * probeSrcIframes (client). The probe document posts this marker to its parent;
+ * receiving it is the ONLY proof that src-URL iframes truly load — hosts that
+ * block sub-frame requests (the Claude Code desktop browser) still fire `load`
+ * on the error page they commit instead.
+ */
+export declare const IFRAME_PROBE_MESSAGE_SOURCE = "pmx-canvas-iframe-probe";

package/dist/types/shared/scope-fence.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Scope fence geometry shared by the server's enforcement and the client's
+ * rendering so both draw the same box: the bounding box of the fenced nodes
+ * plus `padding` px. Null when none of the fenced nodes exist.
+ */
+export interface FenceRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare function fenceRectFromNodes(nodes: Iterable<{
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+}>, padding: number): FenceRect | null;

package/docs/RELEASE.md

@@ -44,6 +44,25 @@ discovery with a `.esm.preflight` loader error (ERR-20260508-001).
 and exercises the CLI flows from
 [`docs/evals/e2e-cli-coverage.md`](evals/e2e-cli-coverage.md).
 
+**Bump the pinned version examples.** `Readme.md` pins an exact version in
+its install/orb-setup snippets *because* it tells readers to pin. Three
+releases in a row shipped pointing at the previous version — twice the
+surrounding prose described features that pin does not have, so a reader
+following it copy-pasted a broken setup.
+
+```bash
+grep -rn "pmx-canvas@0\." Readme.md docs/    # every hit must be the version you are about to ship
+```
+
+**If this release touches CI or the release workflows, review that as
+release content.** A changed gate gets its first real run *on this
+release*: `e2e-cli` once launched Playwright without installing the
+browser, the publish gate once queried `GITHUB_SHA` (the tag object, not
+the commit) so it would have blocked every annotated tag, and
+`test:coverage` once lacked `PMX_CANVAS_DISABLE_BROWSER_OPEN=1` so it
+failed *and* opened a real browser. Ask what happens on a fresh runner
+and on a tag event, not just on your machine.
+
 ## Versioning
 
 Semantic versioning, in 0.x semver honestly (see `docs/api-stability.md`).
@@ -87,6 +106,23 @@ Don't ship a release without a CHANGELOG entry. The GitHub release
 notes file (`/tmp/pmx-canvas-vX.Y.Z-release-notes.md` by convention)
 expands on the CHANGELOG with examples and migration notes.
 
+**Check the entries are under a NEW heading.** Feature commits land bullets
+at the top of the file, and three times in the 0.3.x–0.4.x cycles they were
+appended under the *already-published* section instead — so the release
+notes shipped empty while the previous release's published history claimed
+features it never had. Before tagging:
+
+```bash
+# every bullet added since the last tag must sit above the last released heading
+git diff v<PREVIOUS>..HEAD -- CHANGELOG.md | grep '^+' | head -40
+grep -n '^## \[' CHANGELOG.md | head -3
+```
+
+Same rule in reverse: never retro-edit a published section to describe new
+behavior (a theme's colour was changed in place once, so the released notes
+described a build that never shipped it). Correct it forward under the new
+version instead.
+
 **Release-blocker gate:** a breaking change without a `### Breaking`
 CHANGELOG entry blocks the release (`docs/api-stability.md`). Check the
 diff against the previous tag for removed/renamed public surface — MCP
@@ -95,6 +131,18 @@ anything broke and isn't named under `### Breaking`, add the entry first.
 
 ## Tag → publish
 
+**Immediately before tagging, re-read the Test CI conclusion — never assert it
+from memory.** v0.3.2 was tagged and published while its Test run had concluded
+*failure*: an interruption landed between the watch finishing and the tag step,
+and "CI was green" was recalled rather than checked. A `gh run watch` exiting 0
+is only evidence if you actually read its output.
+
+```bash
+gh run view <run-id> --json status,conclusion -q '.status + " / " + .conclusion'
+gh run view <run-id> --json jobs -q '.jobs[] | .name + ": " + .conclusion'
+# every job must read `success` — a matrix job added in THIS release has never run green before
+```
+
 The publish workflow ([`/.github/workflows/publish.yml`](../.github/workflows/publish.yml))
 triggers on tags matching `v*`:
 
@@ -193,6 +241,12 @@ with `ok: true`, the published tarball is intact end-to-end.
   in `Readme.md` actually needs the refresh.
 - **CHANGELOG dates**: use the actual publish date in the
   `## [version] - YYYY-MM-DD` header, not the day you wrote the entry.
+- **npm publish is asynchronous now**: a successful publish prints "Your
+  package is being processed and may take a few minutes to become
+  available" — `npm view` 404s on the new version and `latest` stays on
+  the old one for several minutes (~4 min observed for 0.4.8). Poll
+  before diagnosing a failed publish; the Publish CI step log's
+  `+ pmx-canvas@X.Y.Z` line is the proof it landed.
 - **Node 24 deprecation timeline**: GitHub Actions is migrating
   `actions/checkout`, `setup-node`, `upload-artifact` to Node 24 by
   June 2, 2026. The publish workflow already pins `@v5` of all three.

package/docs/ax-host-adapter-contract.md

@@ -24,11 +24,28 @@ surface each one binds to.
 | `ingestActivity(event)` | `POST /api/canvas/ax/activity` · `canvas_ingest_activity` — board auto-reacts | Forwarding the host's tool/session hooks |
 | `awaitGate(id)` | `GET /api/canvas/ax/{approval\|elicitation\|mode}/<id>?waitMs=` · `canvas_ax_gate { kind: "approval"\|"elicitation"\|"mode", action: "await" }` | Optionally surfacing a native modal; the agent must await PMX |
 | `mirrorLog(event)` *(optional)* | `GET /api/canvas/ax/timeline` · `canvas://ax-timeline` | Writing AX events into the host's own chat/session log |
+| `presence()` | `POST /api/canvas/ax/presence` · `canvas_ax_state { action: "set-presence" }` — or simply `ingestActivity` with `session-start` / `session-end` / `tool-start` / `tool-result` | Calling it from the host's session and tool hooks. Attach saves a pre-session snapshot; detach emits the `agent-session-ended` receipt — detach on shutdown (bounded, best-effort) so the human gets it promptly. If the host knows the model's token usage, report it as `contextUsage: { used, total }` — the top-bar meter then shows the real window instead of the pinned-context estimate |
 
-## Steering is gated, not pushed (#54)
+### Presence: the cursor works for every adapter
 
-A board action (e.g. an `ax.steer` emit from a surface button) enqueues a steering
-message; it does **not** wake the agent. It reaches the next turn only when:
+An adapter does not need per-call labelling for the canvas to show its agent's
+cursor. Attach once (`attached: true`, or a `session-start` activity) and detach
+on exit; from then on every canvas write the agent makes — through MCP, HTTP,
+the CLI or the SDK, under any transport label — is attributed to that session
+while it is the only one attached. The cursor moves to the node each write
+touched and the phase reads `tooling` during work, `waiting-approval` while a
+gate is pending. Report `thinking` from a prompt/turn hook when the host has one
+(the Copilot extension does); name the agent with `PMX_CANVAS_AGENT_SOURCE` on
+the MCP server when the host runs several agents side by side, and pass
+`agentId` for sub-agents that should keep their own cursor.
+
+## Steering is queued first, then pushed by capable adapters (#54)
+
+A board action (e.g. an `ax.steer` emit from a surface button) always enqueues a steering message
+first. A capable adapter can immediately claim it, call the host's native send, and mark it after
+the host accepts the prompt. The GitHub Copilot reference adapter implements this delivery loop.
+
+When a host cannot wake a turn, queued steering reaches the next turn when:
 
 1. **The pin/focus gate is open.** A typical adapter injects `/api/canvas/ax/context`
    only when something is pinned or focused (`pinned.count > 0 || focus.nodeIds.length > 0`).
@@ -50,17 +67,16 @@ many more are queued so it can drain the FIFO `…/delivery/pending` endpoint wh
 count is non-zero. **Adapters should read `delivery.pendingSteering`** (this compact,
 count-bearing block), not `timeline.pendingSteering`.
 
-### Canvas-origin steering does not wake the agent by itself (#59)
-
-Recording a browser-origin `ax.steer` (and the `ok:true` ack a surface button gets —
-report #55) means the steer is **queued on the timeline**, not delivered into a live
-agent turn. PMX deliberately does not import a host SDK, so the *wake* — turning a
-queued steer into a visible turn — is **adapter-owned**: a cooperating host adapter
-must drain `…/delivery/pending?consumer=<id>` and call its native send (e.g.
-`copilotSession.send`), then `…/delivery/<id>/mark` it. Until an adapter wires that,
-canvas-origin steering is delivered on the next human turn, not pushed. A steering
-surface should therefore label its button honestly ("queued for the agent's next
-turn"), never imply it interrupts the agent now.
+### Canvas-origin steering requires an adapter-owned wake (#59)
+
+Recording a browser-origin `ax.steer` (and the `ok:true` ack a surface button gets — report #55)
+means the steer is durably queued on the timeline. PMX deliberately does not import a host SDK, so
+the *wake* is adapter-owned: a cooperating host adapter drains
+`…/delivery/pending?consumer=<id>`, calls its native send, then marks the delivery. The GitHub
+Copilot adapter does this with a long-polling pump and `copilotSession.send`. It establishes a
+baseline at adapter startup, marking older backlog without replaying it so stale instructions from
+prior sessions cannot flood a newly opened chat. Adapters without a native send retain
+next-human-turn delivery.
 
 ## The two primitives that close the loop
 

package/docs/cli.md

@@ -13,6 +13,42 @@ pmx-canvas node list --port 4750                      # target a non-default dae
 pmx-canvas --server-url http://127.0.0.1:4750 status  # same, by URL
 ```
 
+## pump — reactive steering for CLI agents
+
+`pmx-canvas pump` turns any CLI agent (Codex, Amp, a script) into a steerable
+board citizen: it long-polls the per-consumer delivery claim and runs your
+command once per steer, marking per-consumer on success.
+
+On Windows the exec runs through `cmd.exe` and receives the steer message on
+stdin. The `{message}` and `{id}` placeholders are refused there: `cmd.exe`
+expands `%VAR%` and re-parses the result, so a steer containing shell
+metacharacters could inject commands. Read stdin, or reference
+`PMX_STEER_MESSAGE` / `PMX_STEER_ID` inside your own script.
+
+```bash
+pmx-canvas pump --consumer codex-cli --exec 'codex exec --full-auto {message}'
+pmx-canvas pump --consumer amp --exec 'amp -x {message}' --parent claude-code
+```
+
+The Codex example starts a non-interactive CLI task. It does not steer an open
+Codex desktop task: desktop owns that thread's writer and requires a host
+adapter that uses the app's native follow-up channel.
+
+- The steer text reaches the command as `$PMX_STEER_MESSAGE` (env) and stdin;
+  `{message}` in the template expands to the quoted env reference — steer
+  content is never spliced into the shell line.
+- The delivery envelope rides along as env: `$PMX_STEER_ID`, `$PMX_STEER_SOURCE`
+  (who sent it), `$PMX_STEER_TARGET` (your consumer key, or `ALL` for a
+  broadcast), and `$PMX_STEER_CREATED_AT` — so the host turn can say who
+  steered, whether it was addressed, and how old it is.
+- Startup backlog is marked silently (pass `--backlog deliver` to process it).
+- A failing command is retried twice, then the pump exits non-zero and leaves
+  the steer pending so a failed host injection cannot look delivered.
+- `--parent <key>` rolls the pumped agent up under an orchestrator's chip;
+  `--once` processes a single steer (useful in scripts and tests).
+- Survives daemon restarts; backs off against pre-0.4.9 servers that ignore
+  `waitMs`.
+
 ## Server lifecycle
 
 ```bash
@@ -281,7 +317,7 @@ reports annotation targets and bounds; it does not describe whether the human
 drew an arrow, line, circle, or other shape. Inspect `.annotation-layer path` or
 take a screenshot when the drawn form matters.
 
-Humans draw with the pen toolbar button and remove marks with the eraser button.
+Humans draw with the rail's Annotate popover (pen / text) and remove marks with its eraser.
 If an agent already knows the annotation ID from context, it can remove it through
 MCP with `canvas_view { action: "remove-annotation", id }`.
 

package/docs/environment.md

@@ -20,6 +20,9 @@ optional; defaults are listed.
 | `PMX_CANVAS_DB_PATH` | server | Overrides the SQLite path (default `.pmx-canvas/canvas.db`). |
 | `PMX_CANVAS_STATE_FILE` | server | `.db`-path alias only as of 0.4.0 (non-`.db` values are ignored with a boot warning; the pre-0.2 JSON import was removed). |
 | `PMX_CANVAS_BLOB_THRESHOLD_BYTES` | server | Node payloads above this many JSON bytes are stored as blobs (default `2048`). |
+| `PMX_CANVAS_AGENT_SOURCE` | MCP transport, CLI | Names the agent behind this transport for presence (`codex`, `claude-code`, …) so its writes, attach and cursor share one identity; default is the transport label (`mcp` / `cli`). |
+| `PMX_CANVAS_GATE_TTL_MS` | server | Default TTL for approval gates before the unattended-approval policy auto-holds them (default `300000` = 5 min, clamped to 1 s – 24 h). |
+| `PMX_CANVAS_CONTEXT_BUDGET_TOKENS` | server | `budget.total` in agent presence — the ceiling the top bar's **Pins** meter measures the pinned-context token estimate against (default `32000`). It is not the agent's context window; a host reports that on the presence as `contextUsage`, and the meter then reads **Context**. |
 
 ## Server behavior
 

package/docs/http-api.md

@@ -29,6 +29,12 @@ curl -X POST http://localhost:4313/api/canvas/schema/validate \
   -H "Content-Type: application/json" \
   -d '{"type":"json-render","spec":{"root":"card","elements":{"card":{"type":"Card","props":{"title":"Preview"},"children":[]}}}}'
 
+# Create a json-render node from a spec. `height` and `nodeHeight` are both
+# accepted for the node frame (nodeHeight matches the graph/stream actions).
+curl -X POST http://localhost:4313/api/canvas/json-render \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Panel","nodeHeight":280,"spec":{"root":"card","elements":{"card":{"type":"Card","props":{"title":"Live"},"children":[]}}}}'
+
 # Validate an HTML primitive without creating a node
 curl -X POST http://localhost:4313/api/canvas/schema/validate \
   -H "Content-Type: application/json" \
@@ -73,6 +79,17 @@ with no `fileContent`, plus `data.mimeType` when the type is known
 (`application/pdf` for PDFs). A text file larger than 2 MB is stored truncated
 with `data.truncated: true`.
 
+```bash
+# Repoint a file node at another file — content re-read, watcher rewired,
+# edges/pins/position kept (recreating the node loses all three)
+curl -X PATCH http://localhost:4313/api/canvas/node/node-abc123 \
+  -H "Content-Type: application/json" \
+  -d '{"path":"src/server/canvas-state.ts"}'
+```
+
+The title follows the new filename unless the node was renamed away from the
+old one (or the patch sets `title` explicitly).
+
 ```bash
 # Raw bytes for a binary file node (PDF viewer, downloads)
 curl http://localhost:4313/api/canvas/file-bytes?nodeId=node-abc123
@@ -99,6 +116,16 @@ Search-based edge creation is intentionally strict: `fromSearch` and
 `toSearch` must each resolve to exactly one node. Broad queries that match
 multiple nodes fail; use the full visible title.
 
+```bash
+# Update an edge in place (label, type, style, animated) — empty label clears it
+curl -X PATCH http://localhost:4313/api/canvas/edge/edge-123 \
+  -H "Content-Type: application/json" \
+  -d '{"label":"retries","type":"depends-on","style":"dashed"}'
+```
+
+Retyping an edge onto a from/to/type triple that already exists is refused
+(400) — the same duplicate rule edge creation enforces.
+
 ## Annotations
 
 ```bash
@@ -164,10 +191,10 @@ curl -X POST http://localhost:4313/api/canvas/ax/event \
   -H "Content-Type: application/json" \
   -d '{"kind":"tool-start","summary":"ran tests","source":"api"}'
 
-# Timeline — send a steering message to the active agent session
+# Timeline — send a steering message; `target` addresses ONE consumer, omit to broadcast
 curl -X POST http://localhost:4313/api/canvas/ax/steer \
   -H "Content-Type: application/json" \
-  -d '{"message":"focus on the failing test first","source":"api"}'
+  -d '{"message":"focus on the failing test first","source":"api","target":"copilot"}'
 
 # Timeline — record an evidence item (logs/tool-result/screenshot/file/diff/test-output)
 curl -X POST http://localhost:4313/api/canvas/ax/evidence \
@@ -186,14 +213,21 @@ curl -X PATCH http://localhost:4313/api/canvas/ax/work/<id> \
   -d '{"status":"done"}'
 curl http://localhost:4313/api/canvas/ax/work
 
-# Canvas-bound — request / resolve an approval gate (pending → approved/rejected)
+# Canvas-bound — request / resolve an approval gate (pending → approved/rejected/held)
 curl -X POST http://localhost:4313/api/canvas/ax/approval \
   -H "Content-Type: application/json" \
-  -d '{"title":"Deploy to prod","action":"deploy.prod","source":"api"}'
+  -d '{"title":"Deploy to prod","action":"deploy.prod","ttlMs":300000,"source":"api"}'
 curl -X POST http://localhost:4313/api/canvas/ax/approval/<id>/resolve \
   -H "Content-Type: application/json" \
   -d '{"decision":"approved","source":"api"}'
 curl http://localhost:4313/api/canvas/ax/approval
+# Unattended-approval policy: a gate nobody answers within its TTL (default
+# PMX_CANVAS_GATE_TTL_MS = 5 min, max 24 h) resolves to `held` — the action does
+# NOT proceed, an awaiting agent is released with a non-approval, and a
+# `policy` agent-event explains why. Reopen it (fresh TTL) from the session
+# panel or here; this is the human's path, not an MCP tool.
+curl -X POST http://localhost:4313/api/canvas/ax/approval/<id>/reopen \
+  -H "Content-Type: application/json" -d '{"source":"browser"}'
 
 # Canvas-bound — add a review annotation (comment/finding) anchored to node/file/region
 curl -X POST http://localhost:4313/api/canvas/ax/review \
@@ -216,6 +250,152 @@ reject an unknown `status` with 400 (the tokens are `todo`, `in-progress`,
 and `PATCH /ax/review/:id` return 404 for unknown IDs; approval resolve returns
 404 if the gate is missing or already resolved.
 
+## Agent presence
+
+Who is writing to the board right now, in what phase, and whether a session
+is attached. Presence is *derived*: every agent-originated mutation (anything
+without the workbench's own `x-pmx-workbench: 1` marker) registers its caller
+as a `tooling` writer, the activity feed drives attach/detach and phase
+(`session-start`, `session-end`, `tool-start`, `tool-result`), and adapters
+with richer hooks can set a phase, cursor, or focus explicitly. Writers fade
+90 s after their last write; attached sessions expire after 30 min of quiet
+without a `session-end`.
+
+```bash
+# Read the snapshot (the browser does this on connect)
+curl http://localhost:4313/api/canvas/ax/presence
+# → { ok, presences: [{ sessionId, source, agentId, label, phase, detail,
+#      focusNodeId, cursor, attached, opCount, contextUsage, lastSeenAt }],
+#     budget: { used, total }, sessionActive,
+#     activity: [{ id, at, sessionId, label, op, summary, nodeId }] }  # newest first, last 50
+
+# Attach a session and report a phase (idle | thinking | tooling | waiting-approval)
+curl -X POST http://localhost:4313/api/canvas/ax/presence \
+  -H "Content-Type: application/json" \
+  -d '{"source":"copilot","attached":true,"phase":"thinking","detail":"planning"}'
+
+# Point the agent cursor at a node, then detach
+curl -X POST http://localhost:4313/api/canvas/ax/presence \
+  -H "Content-Type: application/json" \
+  -d '{"source":"copilot","focusNodeId":"<node-id>","cursor":{"x":320,"y":140}}'
+curl -X POST http://localhost:4313/api/canvas/ax/presence \
+  -H "Content-Type: application/json" -d '{"source":"copilot","attached":false}'
+```
+
+`sessionActive` is true when any presence is attached — it is the single gate
+for the agent chrome (session panel, command bar, presence layer). Live but
+unattached writers are the *external steering* case: the browser shows a
+passive top-bar indicator (writers + op count) with an activity feed and a
+connected-writers sheet — visibility only, never permissions. `activity` is
+that feed: one entry per agent write with a human summary ("Created markdown
+“Release plan”"), attributed to the writer (re-attributed to the session when
+a transport writer folds into it), bounded to the last 50 and kept after a
+writer fades. Detaching (`attached: false`, `session-end`) removes the
+presence outright — an ended session never lingers as an external writer.
+
+**The context meter is an estimate unless the host says otherwise.** `budget`
+is a token estimate (chars ÷ 4) of the `pinned-context` payload against
+`PMX_CANVAS_CONTEXT_BUDGET_TOKENS` (default 32000) — what the human's pins
+would cost the agent, not the agent's live window; the top bar labels it
+**Pins**. A host that knows the agent's real usage reports it on the presence
+(`contextUsage: { used, total }` on `POST /api/canvas/ax/presence` /
+`set-presence`); the top bar then shows **Context** with those numbers. The
+bundled Copilot extension reports it from the SDK's `session.usage_info`
+event (root agent, coalesced to one report per 500 ms); the legacy
+`context-usage` workbench event feeds the single attached session the same
+way.
+
+```bash
+curl -X POST http://localhost:4313/api/canvas/ax/presence \
+  -H "Content-Type: application/json" \
+  -d '{"source":"copilot","contextUsage":{"used":42800,"total":128000}}'
+```
+
+**Writer identity and attribution.** Plain HTTP callers read as source `api`,
+the CLI sends `x-pmx-source: cli`, the MCP server sends `mcp` (or
+`PMX_CANVAS_AGENT_SOURCE` when set), the SDK is `sdk`. Those are *transport*
+labels, not agents — so while exactly one session is attached, a transport
+write with no `agentId` is attributed to that session: its cursor moves to
+the touched node, its phase reads `tooling`, and no second writer appears.
+This is what lets a Copilot/Codex/Claude Code session that writes through MCP
+keep one cursor. Pass `agentId` (sub-agents) or a host label to keep a writer
+separate; with several sessions attached, transport writes stay on their own
+label. A session the human started (*Start agent session*, `source: "browser"`)
+is a placeholder for whichever agent comes next: it absorbs agent-less writes
+under *any* label — a host label included — and takes that agent's name. If
+exactly one such writer is already on the board when the human starts the
+session, it is adopted on the spot. One agent arriving over two channels —
+an adapter presence plus its own MCP server, both announcing the same label —
+merges into one session at attach, and the merged channel's writes and detach
+keep landing on it.
+
+**Session lifecycle: pre-session snapshot and receipt.** When a session
+attaches (`attached: true`, or `session-start` on the activity feed) over a
+non-empty board, the server saves a snapshot named
+`Before session · <label> · HH:MM` — the board before the agent touched it.
+When that session ends (`attached: false`, `session-end`, or the idle expiry)
+the stream carries one `agent-session-ended` frame:
+
+```json
+{ "label": "Copilot", "endedAt": "…", "counts": { "items": 4, "done": 3, "vetoed": 1 },
+  "snapshot": { "id": "…", "name": "Before session · Copilot · 14:00" } }
+```
+
+`items`/`done` count the work items on the board; `vetoed` counts cancelled
+items plus rejected or held gates. `snapshot` is null when the board was
+empty at attach. The browser renders this as the session receipt; its *View
+diff* is `GET /api/canvas/snapshots/<id>/diff` against that snapshot, and
+restoring the snapshot undoes the session. Adapters should end their session
+explicitly so the human gets the receipt promptly rather than after the idle
+expiry. The browser's *Start agent session* button is this same endpoint
+(`source: "browser"`, `attached: true`) — subsequent agent-less writes are
+attributed to that session, and the first named agent renames it.
+
+## Human presence (collaborators)
+
+Every open workbench tab reports itself; the server fans the set out as
+`human-presence` SSE frames so tabs see each other's cursors. A node a human
+is holding (dragging) is an edit lock: an agent write targeting it is refused
+with **409** ("being edited by <name> — requeue") until the grab is released
+or goes stale (8 s without renewal). Membership changes count as targeting the
+member: dissolving the group a held node belongs to (`group.remove`, or
+`node.remove` on the group) or pulling it into another group is refused the
+same way. Human heartbeats never count as agent activity.
+
+```bash
+curl http://localhost:4313/api/canvas/human-presence
+# → { ok, humans: [{ clientId, name, cursor, grabbingNodeId, lastSeenAt }] }
+curl -X POST http://localhost:4313/api/canvas/human-presence \
+  -H "Content-Type: application/json" -H "x-pmx-workbench: 1" \
+  -d '{"clientId":"tab-1","name":"mia","cursor":{"x":320,"y":140},"grabbingNodeId":"<node-id>"}'
+```
+
+## Scope fence (agent writes)
+
+The policy's `scope` limits what an attached agent may WRITE: existing-node
+writes must target fenced nodes, new nodes must land inside the fenced
+nodes' bounding box plus `padding` px (default 40), and board-wide writes
+(arrange, clear, restore) are refused. Every refusal is HTTP 403 with a reason
+naming the node or position. Reads are never fenced, nor are the human's own
+workbench writes. A fence is a granted region: a group id in `nodeIds` expands
+to the frame plus every member (nested groups included) when the scope is set.
+The fence is visible to the agent in `canvas://ax-context` (`policy.scope`) and
+drawn on the canvas while a session is attached.
+
+The fence belongs to the human: only workbench calls (`x-pmx-workbench: 1`) may
+set, replace, or clear `scope`. An agent call to `POST /api/canvas/ax/policy`
+that includes `scope` is refused with 403, and the MCP `set-policy` action does
+not take it.
+
+```bash
+# Grant (replace semantics) and clear — workbench calls
+curl -X POST http://localhost:4313/api/canvas/ax/policy \
+  -H "Content-Type: application/json" -H "x-pmx-workbench: 1" \
+  -d '{"scope":{"nodeIds":["<node-a>","<node-b>"],"padding":40},"source":"browser"}'
+curl -X POST http://localhost:4313/api/canvas/ax/policy \
+  -H "Content-Type: application/json" -H "x-pmx-workbench: 1" -d '{"scope":null}'
+```
+
 ## AX interactions, delivery, elicitation, mode, commands & policy
 
 Node interactions are one normalized, capability-gated envelope that maps onto an
@@ -229,12 +409,32 @@ curl -X POST http://localhost:4313/api/canvas/ax/interaction \
   -H "Content-Type: application/json" \
   -d '{"type":"ax.work.create","sourceNodeId":"node-1","payload":{"title":"Wire auth"}}'
 
-# Delivery — claim pending steering for a consumer (loop-safe), then mark delivered
+# Delivery — claim pending steering for a consumer (loop-safe), then mark delivered.
+# The claim returns broadcasts plus steering addressed to THIS consumer; a claim
+# with no `consumer` sees broadcasts only. With several agents connected, the
+# browser composer offers a target picker fed by live presence — always claim
+# with your own label or addressed steering never reaches you.
 curl "http://localhost:4313/api/canvas/ax/delivery/pending?consumer=copilot&limit=20"
+
+# Long-poll: `waitMs` parks the request until steering for this consumer
+# arrives or the timeout elapses (capped at 120000ms) — the reactive loop for
+# hosts whose model only runs while the host gives it a turn. Loop on this
+# instead of tight polling.
+curl "http://localhost:4313/api/canvas/ax/delivery/pending?consumer=copilot&waitMs=120000"
+# Marks are PER CONSUMER for broadcasts: your mark removes the message from
+# YOUR queue only — every other consumer still receives it ("all workers:
+# stop" reaches the whole fleet). Addressed steers stay single-recipient
+# compare-and-set; a consumer-less mark is the anonymous global ack.
 curl -X POST http://localhost:4313/api/canvas/ax/delivery/<steering-id>/mark \
   -H "Content-Type: application/json" \
   -d '{"consumer":"copilot"}'
 
+# Per-agent territories (fleet orchestration): fence a worker to its lane.
+# An agent may fence OTHER writers, never its own key; the human may set any.
+curl -X POST http://localhost:4313/api/canvas/ax/policy \
+  -H "Content-Type: application/json" \
+  -d '{"agentScopes":{"run1:impl":{"nodeIds":["node-a"],"padding":80}}}'
+
 # Elicitation — request structured human input, then respond
 curl -X POST http://localhost:4313/api/canvas/ax/elicitation \
   -H "Content-Type: application/json" \
@@ -352,6 +552,15 @@ curl -N http://localhost:4313/api/workbench/events
 The browser, the CLI `watch` command, and the MCP resource notifications
 all consume this stream. Auto-reconnect with exponential backoff.
 
+`agent-presence` frames carry the full presence snapshot (the same body as
+`GET /api/canvas/ax/presence`) on every change, including TTL expiry — a
+client never needs its own expiry timer. `agent-session-ended` carries the
+session receipt (see [Agent presence](#agent-presence)).
+
+Every frame's payload is wrapped in an envelope that sets `sessionId` (the
+workbench session, used for reconnect/reload detection) and `timestamp` —
+payload keys of those names are overwritten, so event bodies never use them.
+
 ## Polling transport (proxy-safe)
 
 Some proxies (e.g. the Amp orb portal) buffer streaming responses and only
@@ -420,8 +629,16 @@ re-mint them automatically (Finding S).
 curl -X POST http://localhost:4313/api/canvas/undo
 curl -X POST http://localhost:4313/api/canvas/redo
 curl http://localhost:4313/api/canvas/history
+# → { text, entries: [{ id, timestamp, description, actor, operationType, isCurrent, isUndone }],
+#     top: { …the entry undo would revert next… } | null, canUndo, canRedo }
 ```
 
+One shared undo stack, agent and human alike. Each entry's `actor` is `human`
+for workbench writes (`x-pmx-workbench: 1`) and `agent` for everything else;
+`top` is what the next undo reverts. The session panel uses this to offer
+"undo this edit" on the agent's latest board write and tells the agent through
+steering when the human takes it.
+
 ## WebView automation
 
 ```bash

package/docs/mcp.md

@@ -39,18 +39,18 @@ its `action` to the same operation the legacy tool used, so results are identica
 |-----------|-----------------|----------|
 | `canvas_node` | `add` · `get` · `update` · `remove` | `canvas_add_node`, `canvas_get_node`, `canvas_update_node`, `canvas_remove_node`, `canvas_add_html_node` (`add` + `type:"html"`), `canvas_add_html_primitive` (`add` + `type:"html"`, `primitive:"<kind>"`), `canvas_refresh_webpage_node` (`update` + `refresh:true`) |
 | `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` · `workboard` | `canvas_describe_schema`, `canvas_validate_spec`, `canvas_add_json_render_node`, `canvas_stream_json_render_node`, `canvas_add_graph_node` |
-| `canvas_edge` | `add` · `remove` | `canvas_add_edge`, `canvas_remove_edge` |
+| `canvas_edge` | `add` · `update` · `remove` | `canvas_add_edge`, `canvas_update_edge`, `canvas_remove_edge` |
 | `canvas_group` | `create` · `add` · `ungroup` | `canvas_create_group`, `canvas_group_nodes`, `canvas_ungroup` |
 | `canvas_history` | `undo` · `redo` | `canvas_undo`, `canvas_redo` |
 | `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear`, `canvas_remove_annotation` |
 | `canvas_query` | `search` · `layout` · `validate` | `canvas_search`, `canvas_get_layout`, `canvas_validate` |
 | `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | `canvas_webview_status`, `canvas_webview_start`, `canvas_webview_stop`, `canvas_resize`, `canvas_evaluate` |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | `canvas_open_mcp_app`, `canvas_add_diagram`, `canvas_build_web_artifact` |
-| `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` | `canvas_get_ax`, `canvas_set_ax_focus`, `canvas_set_ax_policy`, `canvas_report_host_capability` |
+| `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` · `presence` · `set-presence` | `canvas_get_ax`, `canvas_set_ax_focus`, `canvas_set_ax_policy`, `canvas_report_host_capability` |
 | `canvas_ax_work` | `add` · `update` · `annotate` | `canvas_add_work_item`, `canvas_update_work_item`, `canvas_add_review_annotation` |
 | `canvas_ax_gate` | `request` · `resolve` · `await` × kind `approval` \| `elicitation` \| `mode` | `canvas_request_approval`, `canvas_resolve_approval`, `canvas_await_approval`, `canvas_request_elicitation`, `canvas_respond_elicitation`, `canvas_await_elicitation`, `canvas_request_mode`, `canvas_resolve_mode`, `canvas_await_mode` (9 → 1) |
 | `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` | `canvas_get_ax_timeline`, `canvas_record_ax_event`, `canvas_add_evidence`, `canvas_send_steering` |
-| `canvas_ax_delivery` | `claim` · `mark` | `canvas_claim_ax_delivery`, `canvas_mark_ax_delivery` |
+| `canvas_ax_delivery` | `claim` (long-polls with `timeoutMs`) · `mark` | `canvas_claim_ax_delivery`, `canvas_mark_ax_delivery` |
 | `canvas_intent` | `signal` · `update` · `clear` | _(new — Ghost Cursor of Intent; no legacy standalone tool)_ |
 | `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | `canvas_snapshot` (legacy save tool), `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`, `canvas_diff` — removed in v0.4.0 after one deprecated minor |
 
@@ -135,6 +135,7 @@ migrating an older integration.
 | `canvas_stream_json_render_node` | `canvas_render { action: "stream-json-render" }` |
 | `canvas_add_graph_node` | `canvas_render { action: "add-graph" }` |
 | `canvas_add_edge` | `canvas_edge { action: "add" }` |
+| `canvas_update_edge` | `canvas_edge { action: "update" }` |
 | `canvas_remove_edge` | `canvas_edge { action: "remove" }` |
 | `canvas_create_group` | `canvas_group { action: "create" }` |
 | `canvas_group_nodes` | `canvas_group { action: "add" }` |
@@ -277,8 +278,8 @@ keep annotation context compact: agents see annotation counts, bounds, and targe
 summaries such as the node or empty canvas region that was marked, but not the
 raw stroke geometry or visual shape.
 
-Annotations are a browser-visible markup layer. Use the pen toolbar button to
-draw and the eraser toolbar button to remove an annotation again; agents can also
+Annotations are a browser-visible markup layer. Humans draw with the rail's
+Annotate popover (pen / text / eraser — the eraser removes a mark); agents can also
 remove a known annotation ID with `canvas_view { action: "remove-annotation", id }`.
 
 Use WebView automation when an agent needs to actually see annotations as drawn.