pmx-canvas 0.4.7 → 0.5.0

package/.github/extensions/pmx-canvas/extension.mjs

@@ -5,6 +5,7 @@ import { createServer as createNetServer } from "node:net";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CanvasError, createCanvas, joinSession } from "@github/copilot-sdk/extension";
+import { createSteeringDeliveryPump } from "./steering-delivery.mjs";
 
 const EXTENSION_DIR = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = resolve(EXTENSION_DIR, "../../..");
@@ -12,8 +13,10 @@ const DEFAULT_PORT = 4313;
 const MAX_AX_CONTEXT_CHARS = 16_000;
 const MANAGED_START_TIMEOUT_MS = 10_000;
 const HEALTH_TIMEOUT_MS = 500;
+const STEERING_WAIT_MS = 30_000;
 
 let copilotSession;
+let steeringDeliveryPump;
 let managedProcess = null;
 let managedBaseUrl = null;
 let managedWorkspaceRoot = null;
@@ -467,12 +470,97 @@ async function postAxRecord(ctx, path, payload) {
     }
 }
 
+// Agent presence (rail-chrome-v2): the Copilot session attaches itself so the
+// canvas shows its cursor + phase chip, and the server attributes the agent's
+// MCP/HTTP writes to this session. Best-effort and never blocking the host.
+async function postPresence(workspaceRoot, payload, options = {}) {
+    try {
+        const resolved = await resolvePmxServer(
+            { input: {}, session: { workingDirectory: workspaceRoot } },
+            { autoStart: false },
+        );
+        if (!resolved.ok || !resolved.baseUrl) return false;
+        await fetchJson(resolved.baseUrl, "/api/canvas/ax/presence", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ source: "copilot", label: "GitHub Copilot", ...payload }),
+            timeoutMs: options.timeoutMs ?? 1_500,
+        });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function getCopilotPresence() {
+    try {
+        const resolved = await resolvePmxServer(
+            { input: {}, session: { workingDirectory: PROJECT_ROOT } },
+            { autoStart: false },
+        );
+        if (!resolved.ok || !resolved.baseUrl) return null;
+        const snapshot = await fetchJson(resolved.baseUrl, "/api/canvas/ax/presence", { timeoutMs: 1_500 });
+        if (!Array.isArray(snapshot.presences)) return null;
+        return (
+            snapshot.presences.find(
+                (presence) =>
+                    presence?.sessionId === "copilot" ||
+                    (presence?.source === "copilot" && presence?.agentId == null),
+            ) ?? null
+        );
+    } catch {
+        return null;
+    }
+}
+
 // Fire-and-forget mirror of a copilot-originated action onto the AX timeline.
 // Never throws — adapter UX must not depend on the canvas being reachable.
 function recordCopilotSteering(ctx, message) {
     void postAxRecord(ctx, "/api/canvas/ax/steer", { message }).catch(() => {});
 }
 
+async function claimCopilotSteering(consumer) {
+    const workspaceRoot = PROJECT_ROOT;
+    const resolved = await resolvePmxServer(
+        { input: {}, session: { workingDirectory: workspaceRoot } },
+        { autoStart: false },
+    );
+    if (!resolved.ok || !resolved.baseUrl) {
+        throw new Error(resolved.error ?? "PMX Canvas server is unavailable.");
+    }
+    const delivery = await fetchJson(
+        resolved.baseUrl,
+        `/api/canvas/ax/delivery/pending?consumer=${encodeURIComponent(consumer)}&limit=1&order=oldest&waitMs=${STEERING_WAIT_MS}`,
+        { timeoutMs: STEERING_WAIT_MS + 2_000 },
+    );
+    return Array.isArray(delivery.pending) ? delivery.pending : [];
+}
+
+async function markCopilotSteering(id, consumer) {
+    const workspaceRoot = PROJECT_ROOT;
+    const resolved = await resolvePmxServer(
+        { input: {}, session: { workingDirectory: workspaceRoot } },
+        { autoStart: false },
+    );
+    if (!resolved.ok || !resolved.baseUrl) {
+        throw new Error(resolved.error ?? "PMX Canvas server is unavailable.");
+    }
+    await fetchJson(resolved.baseUrl, `/api/canvas/ax/delivery/${encodeURIComponent(id)}/mark`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ consumer }),
+        timeoutMs: 2_000,
+    });
+}
+
+let lastSteeringDeliveryError = null;
+function reportSteeringDeliveryError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message === lastSteeringDeliveryError) return;
+    lastSteeringDeliveryError = message;
+    process.stderr.write(`[pmx-canvas] Copilot steering delivery retrying: ${message}\n`);
+}
+
 async function getAxTimeline(ctx, limit) {
     const resolved = await resolvePmxServer(ctx, { autoStart: false });
     if (!resolved.ok || !resolved.baseUrl) return { ok: false, error: resolved.error };
@@ -766,6 +854,10 @@ copilotSession = await joinSession({
     hooks: {
         onUserPromptSubmitted: async (input) => {
             const workspaceRoot = resolve(input?.workingDirectory ?? copilotSession?.workspacePath ?? PROJECT_ROOT);
+            // A submitted prompt means the agent is about to think: attach (idempotent)
+            // and flip the phase. The agent's subsequent canvas writes reach the server
+            // as MCP/HTTP tool calls and are attributed to this session.
+            void postPresence(workspaceRoot, { attached: true, phase: "thinking", detail: null });
             const resolved = await resolvePmxServer({ input: {}, session: { workingDirectory: workspaceRoot } }, { autoStart: false });
             if (!resolved.ok || !resolved.baseUrl) return undefined;
             const context = await getAxContext(resolved.baseUrl, workspaceRoot, {});
@@ -775,11 +867,68 @@ copilotSession = await joinSession({
     },
 });
 
-process.once("SIGTERM", () => {
-    stopManagedServer();
-    process.exit(0);
+steeringDeliveryPump = createSteeringDeliveryPump({
+    consumer: "copilot",
+    claim: claimCopilotSteering,
+    send: async (message) => await copilotSession.send({ prompt: message }),
+    mark: markCopilotSteering,
+    getPresence: getCopilotPresence,
+    setPresence: async (patch) => await postPresence(PROJECT_ROOT, patch),
+    shouldSend: (() => {
+        const startedAt = Date.now();
+        return (steering) => Date.parse(steering.createdAt) >= startedAt;
+    })(),
+    pause: delay,
+    onError: reportSteeringDeliveryError,
 });
-process.once("SIGINT", () => {
+void steeringDeliveryPump.start();
+
+// Attach the session as soon as the host joins (the canvas may not be running
+// yet — the prompt hook above re-attaches lazily in that case).
+void postPresence(resolve(copilotSession?.workspacePath ?? PROJECT_ROOT), { attached: true });
+
+// Real context window (rail-chrome-v2): Copilot emits `session.usage_info`
+// with the live token count and the model's window after each turn. Report it
+// on the presence so the board's top-bar meter shows the agent's ACTUAL window
+// instead of the pinned-context estimate. Root agent only — sub-agent events
+// carry an `agentId` and have their own windows. Coalesced to one POST per
+// 500ms: a turn can emit several usage events back to back.
+let usageFlush = null;
+let pendingUsage = null;
+function reportContextUsage(event) {
+    const data = event?.data;
+    if (event?.agentId || !data || typeof data.currentTokens !== "number" || typeof data.tokenLimit !== "number" || data.tokenLimit <= 0) {
+        return;
+    }
+    pendingUsage = { used: Math.max(0, Math.round(data.currentTokens)), total: Math.round(data.tokenLimit) };
+    if (usageFlush) return;
+    usageFlush = setTimeout(() => {
+        usageFlush = null;
+        const usage = pendingUsage;
+        pendingUsage = null;
+        if (usage) void postPresence(resolve(copilotSession?.workspacePath ?? PROJECT_ROOT), { contextUsage: usage });
+    }, 500);
+}
+if (typeof copilotSession?.on === "function") {
+    try {
+        copilotSession.on("session.usage_info", reportContextUsage);
+    } catch {
+        // An SDK without the event keeps the estimate — the meter says so.
+    }
+}
+
+async function shutdown() {
+    steeringDeliveryPump?.stop();
+    // Detach the presence first so the canvas returns to the quiet board the
+    // moment the host goes away, then stop any managed server. The whole
+    // detach is capped at 800ms (server probing + the POST) so a host with a
+    // short SIGTERM grace window can never be held past it.
+    await Promise.race([
+        postPresence(resolve(copilotSession?.workspacePath ?? PROJECT_ROOT), { attached: false }, { timeoutMs: 500 }),
+        delay(800),
+    ]);
     stopManagedServer();
     process.exit(0);
-});
+}
+process.once("SIGTERM", () => void shutdown());
+process.once("SIGINT", () => void shutdown());

package/.github/extensions/pmx-canvas/steering-delivery.mjs

@@ -0,0 +1,79 @@
+export function createSteeringDeliveryPump({
+    consumer,
+    claim,
+    send,
+    mark,
+    shouldSend = () => true,
+    getPresence,
+    setPresence,
+    pause,
+    onError,
+    retryMs = 1_000,
+}) {
+    let stopped = false;
+    let loopPromise = null;
+    const awaitingMark = [];
+
+    async function flushMarks() {
+        while (awaitingMark.length > 0) {
+            const id = awaitingMark[0];
+            await mark(id, consumer);
+            awaitingMark.shift();
+        }
+    }
+
+    async function sendWithOwnedPhase(message) {
+        const detail = `steer: ${message.slice(0, 60)}`;
+        const presence = await getPresence?.();
+        const ownsPhase =
+            presence?.phase === "idle" &&
+            typeof setPresence === "function" &&
+            (await setPresence({ phase: "tooling", detail })) !== false;
+
+        try {
+            await send(message);
+        } finally {
+            if (ownsPhase && typeof getPresence === "function" && typeof setPresence === "function") {
+                const current = await getPresence();
+                if (current?.phase === "tooling" && current.detail === detail) {
+                    await setPresence({ phase: "idle", detail: null });
+                }
+            }
+        }
+    }
+
+    async function runOnce() {
+        await flushMarks();
+        const pending = await claim(consumer);
+        for (const steering of pending) {
+            if (stopped) break;
+            if (shouldSend(steering)) await sendWithOwnedPhase(steering.message);
+            awaitingMark.push(steering.id);
+            await flushMarks();
+        }
+        return pending.length;
+    }
+
+    async function run() {
+        while (!stopped) {
+            try {
+                const claimed = await runOnce();
+                if (claimed === 0 && !stopped) await pause(retryMs);
+            } catch (error) {
+                onError(error);
+                if (!stopped) await pause(retryMs);
+            }
+        }
+    }
+
+    return {
+        runOnce,
+        start() {
+            if (!loopPromise) loopPromise = run();
+            return loopPromise;
+        },
+        stop() {
+            stopped = true;
+        },
+    };
+}

package/CHANGELOG.md

@@ -3,6 +3,160 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.5.0] - 2026-08-28
+
+The multi-agent workbench release. The canvas becomes a live, shared surface
+where several agents and a human can work at once — everyone can see who is
+writing where, steer any connected agent, and take the board back when they
+need it.
+
+
+### Breaking
+
+- Node docking is gone. `dockPosition` is removed from node payloads, from
+  `canvas_update_node`'s input, and from the SDK's `CanvasNodeState` and node
+  updates; the docked HUD pills and the first-run docked status/context widgets
+  are retired. Nodes always live on the canvas now — use `position` and
+  `pinned`. Old boards load fine and previously docked nodes appear as normal
+  nodes. The validator's advisory `hiddenEdgeEndpoints` field went with them.
+- Ungrouping now dissolves the group in one undo step: children are released
+  (into the enclosing group when nested) and the frame is removed — it no
+  longer survives to be deleted separately. A missing group now returns 404,
+  and an empty group dissolves instead of erroring. To release children while
+  keeping the frame, patch the group with `childIds: []`.
+- Approval gates no longer wait forever: an unanswered gate auto-resolves to
+  the new `held` status (a non-approval — the action does not proceed) after
+  its TTL, default 5 minutes via `PMX_CANVAS_GATE_TTL_MS`; reopen it with
+  `POST /api/canvas/ax/approval/:id/reopen`. Consumers switching on gate status
+  must handle `held`.
+- Broadcast steering is delivered per consumer: marking a broadcast with your
+  `consumer` clears it from your queue only, and every other consumer still
+  receives it (previously the first mark removed it for everyone — fleets must
+  no longer rely on that for dedupe). Unclaimed broadcasts leave the pending
+  queue after 15 minutes; addressed steers still wait for their consumer
+  indefinitely.
+### Highlights
+
+- See who is on the board in real time — every writing agent paints a named,
+  colored cursor and a phase, and a top-bar indicator shows external steering
+  even for agents that aren't attached.
+- Steer any connected agent from the composer: address one by name or broadcast
+  to the whole fleet, and `pmx-canvas pump` turns any CLI agent into a steerable
+  board citizen.
+- Human-wins editing: grab a node and agents are locked out of it until you let
+  go, and you can undo an agent's last edit straight from the session panel.
+- A redesigned board — tool rail, top bar, session panel, command bar, minimap,
+  History drawer, groups, and an expanded node view.
+- Unattended approval gates now resolve themselves safely instead of hanging
+  forever, and an orchestrator can fence each agent to its own lane.
+
+### Added
+
+- Agent presence: a live view of every agent writing to the board — identity
+  color, phase (thinking / working / waiting), a cursor that tracks where it is
+  working, and whether a session is attached. Read it at
+  `GET /api/canvas/ax/presence` or set it via `canvas_ax_state`
+  (`presence` / `set-presence`).
+- Human presence and a user-wins edit lock: your cursor is shared with agents,
+  and while you are holding a node an agent write to it is refused until you
+  release it.
+- Addressed steering: the composer picks which connected agent to steer, and a
+  broadcast reaches every consumer in the fleet; the steering timeline names the
+  agent behind each message.
+- `pmx-canvas pump` — a new CLI command that makes any CLI agent (Codex, Amp, a
+  script) steerable: it long-polls for steers and runs your command once per
+  message. Supports `--consumer`, `--exec`, `--parent`, `--once`, and
+  `--backlog`. On Windows the command runs through `cmd.exe` and receives the
+  steer on stdin; the `{message}` / `{id}` placeholders are refused there,
+  because `cmd.exe` re-parses expanded variables and a steer could inject
+  commands.
+- Edges can be edited in place — update an edge's label, type, style, or
+  animation without deleting and redrawing it (`PATCH /api/canvas/edge/:id`,
+  `canvas_edge { action: "update" }`).
+- File nodes can be repointed at another file with a patch — content is re-read
+  and the watcher rewired, keeping the node's edges, pins, and position
+  (`PATCH /api/canvas/node/:id` with `path`).
+- Shared undo of agent edits: when an agent's change tops the history stack, a
+  fixed "Undo" row appears in the session panel and taking it back posts a
+  steering note.
+- Unattended-approval policy: an approval gate nobody answers within its TTL
+  resolves to `held` (the action does not proceed) instead of hanging; reopen it
+  with a fresh clock from the session panel or
+  `POST /api/canvas/ax/approval/:id/reopen`.
+- Scope fence: an orchestrator can fence each agent to a set of nodes, and
+  agent writes outside the fence are refused (403) — the human is never fenced.
+- Session receipts that say why a session ended (by you, by the agent, or idle
+  timeout), and a History drawer that stops hoarding duplicate snapshots.
+- A redesigned board: tool rail with hover labels and shortcuts, top bar,
+  command bar, session panel, minimap v2, groups v2, an empty state, a palette,
+  a selection bar, a connection banner, and an expanded node view.
+- An honest context meter: it shows the agent's real context window when the
+  host reports usage, and otherwise a "Pins" estimate of what your pinned
+  context would cost.
+- In-canvas prompt entry (Shift+F / W / I everywhere), right-click Delete and
+  "Remove from ‹frame›" on member cards, and a work-item Assistant filter.
+- New environment variables: `PMX_CANVAS_AGENT_SOURCE` (name the agent behind a
+  transport), `PMX_CANVAS_CONTEXT_BUDGET_TOKENS` (the Pins-meter ceiling,
+  default 32000), and `PMX_CANVAS_GATE_TTL_MS` (approval-gate TTL, default 5 min).
+
+### Changed
+
+- Create and patch now reject the dead `path` (on non-image nodes) and `src`
+  (anywhere) fields with a clear 400 instead of silently dropping them and
+  leaving an empty node — the canonical field is `content`. The image-node
+  `path` alias still works.
+- Approval gates report a new `held` outcome (from the unattended-approval
+  policy); consumers reading gate status should tolerate it alongside
+  `approved` / `rejected`.
+- Steering delivery claims can long-poll (`timeoutMs`) so a host that can't be
+  woken parks on the claim, and delivery is per-consumer so a broadcast reaches
+  the whole fleet without double-delivering.
+- Auto-arrange is cluster-aware — each on-board neighborhood packs in place
+  instead of being interleaved with the others.
+- Saving a snapshot on an unchanged board now returns the existing snapshot (marked `reused`) instead of creating a duplicate — a checkpoint-by-name on an unchanged board keeps the earlier snapshot's name.
+- Cancelled work items no longer read as vetoed backlog in the timeline.
+- Keyboard shortcuts are platform-aware on Windows keyboards (Ctrl+Y redo,
+  AltGr guard, platform-correct labels).
+- Humans now draw annotations from the rail's Annotate popover (pen / text /
+  eraser) rather than separate toolbar buttons.
+
+### Fixed
+
+- Node headlines stay crisp at high zoom instead of blurring.
+- HTML and mermaid surfaces render in embedded hosts that block sub-frame
+  requests or use `srcdoc` (Copilot, Codex, Claude panels).
+- Open webpage / file / image work on every surface — no flow depends on
+  `window.prompt`, which is a silent no-op in embedded browser panes.
+- Edges no longer draw as degenerate straight lines — side-tangent bezier
+  routing gives them a real bend, and the draw preview no longer jumps.
+- A focus glow no longer wraps the whole board when an attention region spans
+  everything.
+- Card checkboxes survive a human-speed press, expanded-view checkboxes tick,
+  and closing a document with Esc no longer wipes it.
+- Stale browser tabs self-heal on a dev rebuild instead of faithfully
+  reproducing already-fixed bugs.
+- Timeline filter hints and selection-bar tooltips render in-flow as styled
+  hints (native title tooltips never show in embedded panes), and the filter
+  chips fit one row.
+- Presence overlay expiry always emits, held gates no longer pin the session
+  panel open, and Copilot presence is preserved during steering.
+
+## [0.4.8] - 2026-08-20
+
+### Fixed
+
+- Saving now writes only what actually changed instead of rewriting the whole
+  board on every save, so the write cost of dragging one node no longer grows
+  with board size ([#22](https://github.com/pskoett/pmx-canvas/issues/22)).
+- Saves are now fsynced (`synchronous=FULL`), so an abrupt host crash no longer
+  loses the most recent saves — affordable now that saves are incremental.
+- Orphaned large-content blobs are removed on shutdown — only when nothing
+  else has the canvas open, so a second live process can never lose content —
+  and `canvas.db` no longer grows without bound as node content is edited.
+- MCP-app tiles now recover from black tiles in embedded hosts that never
+  report the page as visible (e.g. the GitHub Copilot panel), and recovery
+  logs no longer claim an unverified paint as a success there.
+
 ## [0.4.7] - 2026-08-09
 
 ### Added
@@ -3105,6 +3259,8 @@ otherwise have to discover by trial and error.
 - Regression coverage for snapshot flat-`id` aliases on both MCP and
   HTTP surfaces, plus async / top-level-`await` WebView script bodies.
 
+[0.5.0]: https://github.com/pskoett/pmx-canvas/compare/v0.4.8...v0.5.0
+[0.4.8]: https://github.com/pskoett/pmx-canvas/compare/v0.4.7...v0.4.8
 [0.4.7]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.4.7
 [0.4.6]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.4.6
 [0.4.5]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.4.5

package/Readme.md

@@ -9,9 +9,10 @@ project. Pin what matters and the agent reads your spatial curation as
 structured context.
 
 <p align="center">
-  <img src="docs/screenshots/welcome-dark.png" alt="Empty canvas — dark theme" width="49%" />
-  <img src="docs/screenshots/welcome-light.png" alt="Empty canvas — light theme" width="49%" />
+  <img src="docs/screenshots/workbench-live-dark.png" alt="Live multi-agent workbench — dark theme: two agents on the board, review cards, an architecture diagram, and the writers pill" width="49%" />
+  <img src="docs/screenshots/workbench-live-light.png" alt="Live multi-agent workbench — light theme" width="49%" />
 </p>
+<p align="center"><sub>A real working board: two agents attached (the writers pill, top right), review cards they co-wrote, and a mermaid architecture diagram — dark and light themes.</sub></p>
 
 <p align="center">
   <img src="docs/screenshots/demo-workbench-dark.png" alt="Structured workbench demo — dark theme" width="49%" />
@@ -28,7 +29,11 @@ communication — proximity means relatedness, pinning means *focus here*.
 
 ### 01 / Curate
 
-Drag, group, arrange, and **pin** nodes spatially. Curation is the channel
+Drag, group, arrange, and **pin** nodes spatially. Connect nodes with typed
+edges — flow, depends-on, relation, references — drawn as smooth curves that
+leave each card perpendicular to its border and bend toward their target.
+Edges stay editable in place: right-click one to relabel, retype, restyle, or
+delete it, or click it and press Delete. Curation is the channel
 from human intent to agent context — the agent reads `canvas://pinned-context`
 and `canvas://spatial-context` (proximity clusters, reading order, pinned
 neighborhoods) and uses your layout to ground its next action.
@@ -38,7 +43,8 @@ neighborhoods) and uses your layout to ground its next action.
 Files, web pages, screenshots, structured panels, charts, diagrams, embedded
 MCP Apps, and bundled web artifacts all live on the same surface. A file node
 follows the file on disk as the agent edits it — source with line numbers, a
-CSV or TSV as a real table, a PDF inline. Anything else binary shows its name
+CSV or TSV as a real table, a PDF inline — and can be re-pointed at another
+file (patch its `path`) without losing its edges, pins, or position. Anything else binary shows its name
 and size rather than decoded gibberish, and a very large text file renders
 truncated with a note saying so. Code review has its own node: a unified
 diff with per-file headers and colored added and removed lines. Diagrams can
@@ -91,11 +97,16 @@ canvas into a shared workspace between you and the agent:
   commands (`pmx.plan`, `pmx.review`, …), and read a tool/prompt policy.
 - **Host capability** — adapters report what the host can do, for diagnostics.
 
-Recent additions in this layer: agent-native nodes can now complete the full
-AX loop; agent tool/session activity can flow back into the board as work,
-evidence, and findings; approval, input, and mode gates can wait for a human
-decision instead of polling; and AX-enabled HTML/web-artifact or MCP app
-controls can show an in-surface confirmation after an action is accepted.
+Recent additions in this layer: a **composer** steers directly from the board
+(with a target picker when several agents are connected); the **session panel**
+shows work items, approval gates, and a filterable timeline where every row
+names its writer; a shared **undo stack** knows whether the human or the agent
+made each edit, and undoing an agent's edit tells the agent as steering; a
+**scope fence** confines an agent's writes to selected nodes; and grabbing a
+node in the browser locks it against agent edits while you hold it. Dialogs,
+prompts, and tooltips are all in-canvas — every flow works identically in
+embedded browser panes (Copilot, Codex, Claude Code desktop) where native
+browser UI doesn't exist.
 
 Canvas-bound state (focus, work items, approvals, review annotations,
 elicitations, mode requests, policy) rides canvas snapshots and restore; the
@@ -105,7 +116,40 @@ snapshot. Every primitive is reachable from MCP, the HTTP API, the SDK, and
 GitHub Copilot app) map onto the same neutral surfaces without making PMX Canvas
 vendor-specific.
 
-### 05 / Save
+### 05 / Run several agents on one board
+
+The canvas is built for more than one writer. Every connected agent gets a
+stable **identity color** carried by its cursor, its top-bar session chip, and
+its minimap dot — you always see who is where. Workers roll up under their
+orchestrator's chip (`+2 workers`), each session chip has its own End button,
+and an idle board with no writers stays byte-clean.
+
+<p align="center">
+  <img src="docs/screenshots/multi-agent-live.png" alt="Two agent sessions and three rolled-up workers live on one board — identity-colored cursors on the cards, per-chip End buttons, the attributed session timeline, and the all-agents composer" width="100%" />
+</p>
+<p align="center"><sub>Two agent sessions (Claude Code +3 workers, GitHub Copilot) and their cursors live on one board, with the writer-attributed timeline and the all-agents composer.</sub></p>
+
+Steering is **addressed and reliable**: the composer's picker lists every
+connected writer with live pump health (`· polling`, `· 2 queued`), an
+addressed steer waits in that agent's delivery queue until the agent claims
+and marks it, and broadcasts age out instead of greeting every future
+consumer. Each host wakes its own way — the GitHub Copilot extension pumps
+steers into real Copilot turns, Codex picks them up through its app-native
+heartbeat, and any CLI agent becomes reactive with one command:
+
+```bash
+pmx-canvas pump --consumer amp --exec 'amp -x {message}'
+```
+
+A failed hand-off is never silently swallowed: the steer stays pending and the
+pump exits non-zero. Presence is honest too — "thinking" settles to idle after
+silence, tool calls never clobber an explicit phase, and an attached writer
+that has never made a spatial write still parks its cursor at its last
+activity so it cannot be invisible. Agents coordinate with each other over the
+same steering queue (agent-to-agent hand-offs, reviews, and territory splits),
+and the `pmx-canvas-orchestration` skill documents the choreography.
+
+### 06 / Save
 
 Spatial state auto-saves to `.pmx-canvas/canvas.db` (debounced ~500 ms) —
 git-committable, shareable across machines, and survives both browser
@@ -114,7 +158,7 @@ undo/redo, and an auto-detected code graph (JS/TS, Python, Go, Rust) make
 the canvas durable rather than throwaway. Stop the server before committing
 the DB so SQLite WAL data is checkpointed into the file.
 
-### 06 / Any agent
+### 07 / Any agent
 
 Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (22 tools,
 14 resources, change notifications), the [CLI](docs/cli.md), the
@@ -124,7 +168,7 @@ Claude Code, the GitHub Copilot app and CLI, Codex, Amp, Cursor, Windsurf, or
 any agent that can spawn an MCP stdio server, call a CLI, or hit an HTTP
 endpoint.
 
-### 07 / Native app adapters
+### 08 / Native app adapters
 
 PMX Canvas doesn't just run in a browser tab — it embeds **natively inside the
 agent apps you already use**, as a thin adapter layer over the same neutral AX
@@ -153,11 +197,11 @@ surfaces (the core never imports a host SDK).
 - **GitHub Copilot app** — a committed project canvas extension
   (`.github/extensions/pmx-canvas/`) opens the live PMX workbench in a native
   Copilot panel (light-themed by default to match the app, via the `?theme=`
-  session override), injects pinned/focused AX context on prompt submission, and
-  exposes actions for focus, session steering, work items, approval gates,
-  review annotations, the AX timeline, and host-capability reporting. Install it
-  into any repo with `pmx-canvas copilot install-extension` (`--dry-run` to
-  preview).
+  session override), wakes Copilot when the board sends a steer, injects
+  pinned/focused AX context on prompt submission, and exposes actions for focus,
+  work items, approval gates, review annotations, the AX timeline, and
+  host-capability reporting. Install it into any repo with
+  `pmx-canvas copilot install-extension` (`--dry-run` to preview).
 - **Codex app** — native through the Codex in-app Browser (opened to
   `/workbench`) plus the PMX MCP server: agents read `canvas://ax-context` /
   `canvas_ax_state { action: "get" }` and label Codex-originated focus with
@@ -222,9 +266,13 @@ bunx pmx-canvas --mcp        # Run as MCP server (stdio)
 bunx pmx-canvas --help       # All commands
 ```
 
-Themes are a toolbar picker away too, and any one panel can override the
+Themes are a tool-rail picker away too, and any one panel can override the
 shared theme for itself with `?theme=<name|auto>`.
 
+Press `?` on the board for the full keyboard map. Shortcuts follow the
+platform — `⌘` on a Mac, `Ctrl` on Windows and Linux, where `Ctrl+Y` also
+redoes and `Backspace`/`Delete` both delete the selection.
+
 The canvas opens at `http://localhost:4313`. Try `--demo` first — it seeds a
 showcase board with every node type on it: notes and status, files, a diff, a
 CSV table, charts of every kind, mermaid diagrams, the HTML primitives,
@@ -307,7 +355,7 @@ services:
 ```bash
 # .agents/setup — install the CLI (pin the exact version: a fresh orb running
 # @latest can silently pick up a newer release than the one you validated)
-npm install -g pmx-canvas@0.4.7
+npm install -g pmx-canvas@0.5.0
 ```
 
 The server binds the portal-assigned `$PORT` automatically (gated on the
@@ -371,10 +419,11 @@ the agent can read `canvas://skills` and pull in companion skills
 ## Scope
 
 - **Single-machine, today.** One canvas per `bunx pmx-canvas` instance, on
-  one machine. No built-in multi-user auth or presence — collaboration means
-  human ↔ agent on the same machine, plus any other browser tab/agent
-  pointed at the same `localhost:4313`. To share across machines, commit
-  `.pmx-canvas/canvas.db`.
+  one machine. No built-in multi-user auth — collaboration means humans and
+  agents on the same machine: every browser tab and every connected agent
+  pointed at the same `localhost:4313` shares one live board, with per-writer
+  presence (cursors, chips, minimap dots) for all of them. To share across
+  machines, commit `.pmx-canvas/canvas.db`.
 - **What leaves your machine.** The core canvas runs entirely on
   `localhost`. Network egress only happens for explicit, opt-in flows:
   `webpage` nodes and remote-URL `image` nodes fetch the address you give