pmx-canvas 0.4.7 → 0.5.0

package/docs/node-types.md

@@ -328,7 +328,9 @@ Groups are spatial containers that visually contain other nodes. They render
 as dashed-border frames with a title bar and optional accent color.
 
 - Select 2+ nodes and click "Group" in the selection bar
-- Right-click a group to ungroup
+- Ungroup from the frame's ⋯ menu, the right-click menu, or Shift+G — the frame dissolves and
+  its children stay as independent nodes (one undo step); `canvas_group { action: "ungroup" }`
+  does exactly the same
 - Collapsing a group hides children and shows a summary
 - By default, group creation preserves the children's current positions and
   expands the frame around them

package/docs/plans/plan-009-tech-debt-backlog.md

@@ -79,3 +79,16 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 | Finding U — sticky `-32001` session-error banner over rendering content | **Presentation fix field-confirmed (0.4.3 reports, both hosts); root cause open:** forced error state renders the soft saved-content notice. The underlying stressed-reconnect MCP timeout is still not clean-reproducible — investigate session re-establishment retry/backoff if a future cycle reproduces it. |
 | Skill-mirror drift automation | **Done (2026-08-05):** `pmx-canvas skills sync` (+ `--check`, exit 1 on drift) discovers the skill copies already installed in the workspace — no assumed host layout, per maintainer direction — and whole-tree-replaces them from the package. Closes the recurring every-cycle hand-sync complaint in the audit addenda. Remaining audit ask: a true model-vs-baseline benchmark of the 17 eval prompts (a test-harness task, not a repo artifact). |
 | Registry-migration dead-code sweep | **Done (2026-08-03):** removed the orphaned `describeOp`/`describeGateOp` (composites.ts, dead since the v0.3.0 registration filter) and the `compactNodePayload`/`compactLayoutPayload`/`wantsFullPayload` duplicates in `mcp/server.ts` (live copies are in `ops/nodes.ts`). |
+
+## Added during rail-chrome-v2 (2026-08-23, phases 1–5)
+
+Recorded while the redesign's phases land so nothing rides in silently. Plan: `design/rail-chrome-v2/PLAN.md`.
+
+| Item | What's open |
+|---|---|
+| `window.prompt`-based rail creates | The rail's palette (`ToolRail.tsx` `promptedCreate`) collects a title/URL via `window.prompt`, which headless hosts and some embedded WebViews suppress (the create silently no-ops). Replace with an inline popover form once the phase-7 command-palette restyle lands; until then it is the same behavior the old toolbar had. |
+| `dockPosition` retirement (phase 5c) | **Done (2026-08-23, rail-chrome-v2 phase 5c):** the HUD pill layer, `DockedNode`, first-run seeding, `undockNode`/`hasOpenDockedContextPanel`, the validator's `hiddenEdgeEndpoints` rule, the `--dock-position` CLI flag, the `dock_position` SQLite columns (dead column left in existing DBs, no migration), and the HUD/docked/context-dock CSS are all removed; the demo fixture was regenerated. Note for future removals: `tsc` never deletes stale emits under the committed `dist/types/` — delete the orphaned `.d.ts` by hand. |
+| `annotationMode` / `annotationTool` redundancy | `CanvasViewport` takes both a boolean `annotationMode` prop and the `annotationTool` enum, and `App.tsx` derives the former from the latter (`annotationTool !== null`). Collapse to the enum alone in the phase-7 quality wave — `CanvasViewport.tsx` only. |
+| Agents can resolve their own gates | Pre-existing design question surfaced by the session panel: `ax.approval.resolve` accepts any caller, so an agent could approve its own gate over HTTP/MCP. The panel and the `held` TTL path assume the human answers. Either gate `resolve` on the workbench marker (like the scope fence) or document it as a cooperating-agent contract; decide before the next adapter ships. |
+| Batch never carries `fromWorkbench` | `canvas.batch` inner dispatches are always agent writes (the browser never uses batch), so the scope fence and presence treat them as such. Holds by construction today; if the client ever adopts batch, the marker must thread through `ops/batch.ts`. Comment at the dispatch site. |
+| Presence registry is a second single-slot listener family | `setSessionStartListener` / `setSessionEndListener` / `setEmitter` on `agentPresence` follow architecture rule 8 (owned by `server.ts`). If a third consumer ever needs session lifecycle (e.g. an audit log), fan out inside the existing registration — do not add a competing one. |

package/docs/sdk.md

@@ -115,7 +115,7 @@ canvas.submitAxInteraction({ type: 'ax.work.create', sourceNodeId: n1, payload:
 
 // Delivery — claim pending steering for a consumer (loop-safe), then acknowledge
 const pending = canvas.getPendingSteering({ consumer: 'copilot', limit: 20 });
-if (pending[0]) canvas.markSteeringDelivered(pending[0].id, { consumer: 'copilot' });
+if (pending[0]) canvas.markSteeringDelivered(pending[0].id, 'copilot');
 
 // Elicitation + mode requests (canvas-bound, snapshotted)
 const elic = canvas.requestElicitation({ prompt: 'Who owns this?', fields: ['owner'] }, { source: 'sdk' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -49,7 +49,12 @@ Humans curate agent context by pinning nodes; agents read that curation through
    floor, not a replacement: only an explicit signal gives the human a real pre-mutation veto
    window, your reasoning (`reason`), and staged multi-step previews. Batch and browser-human
    actions never auto-ghost.
-6. **Mutate through current composites.** Prefer the 16 composite MCP tools below.
+6. **Attach a session so the human can see you (0.4.8+).** Start board work with
+   `canvas_ax_state { action: "set-presence", attached: true, label: "<who you are>" }` and end
+   it with `{ attached: false }` — detaching hands the human a receipt. Everything the session
+   gives you and asks of you (cursor + phase chip, the session panel, steering, the scope fence's
+   403s, the human edit lock's 409s, unattended approvals) is in **Sessions & the human** below.
+7. **Mutate through current composites.** Prefer the 16 composite MCP tools below.
 7. **Arrange and validate.** After batch changes, use `canvas_view { action: "arrange" }` when
    appropriate and always finish with `canvas_query { action: "validate" }`.
 7b. **Show the human.** After creating user-facing output, bring the camera to it: a single node
@@ -135,7 +140,7 @@ this table is kept in sync with the server's composite registry; `tools/list` on
 |-----------|---------|
 | `canvas_node` | `add`, `get`, `update`, `remove` |
 | `canvas_render` | `describe-schema`, `validate`, `add-json-render`, `stream-json-render`, `add-graph` |
-| `canvas_edge` | `add`, `remove` |
+| `canvas_edge` | `add`, `update`, `remove` |
 | `canvas_group` | `create`, `add`, `ungroup` |
 | `canvas_history` | `undo`, `redo` |
 | `canvas_view` | `arrange`, `focus`, `fit`, `clear`, `remove-annotation` |
@@ -199,10 +204,9 @@ distant nodes, an auto-placed node lands off-camera.
    `fit` over the new ids. Manual pixel math is what produces long-line, unbalanced boards.
 6. `fit` sizes itself to the connected browser window (0.4.6+) — you do not need to guess
    `width`/`height`. Pass them only to fit for a window other than the human's.
-7. **Docking is explicit (0.4.6+).** Nodes render on the canvas where you put them; a node is
-   only a HUD pill if you set `dockPosition`. An edge whose endpoint is docked cannot be drawn —
-   `validate` reports it as `hiddenEdgeEndpoints` and fails `ok`, because the edge visually
-   trails off into empty canvas.
+7. **Every node is a canvas card.** Nodes render on the canvas where you put them — there is
+   no docked/HUD placement and no `dockPosition` (removed in the rail-chrome redesign); `status`
+   and `context` nodes are ordinary cards like the rest.
 
 **Size for content.** Omitting `width`/`height` gives readable per-type defaults — prefer them:
 markdown 640×420, status 360×200, file 520×360, diff 640×420, mermaid 640×460, html 720×640,
@@ -233,24 +237,107 @@ Do not confuse context pinning with **Lock position**, which only excludes a nod
 Every node type, including `status`, can be removed through `canvas_node { action: "remove" }`, the
 title-bar × control, or the **Close** context-menu action.
 
+## Sessions & the human
+
+The board has three modes, all gated on one fact — whether a session is attached:
+
+- **Quiet board** (nobody attached, nobody writing): a plain canvas. Your writes still show as
+  ghosts, nothing else changes.
+- **External steering** (you write with no session attached): the top bar shows a passive
+  writers indicator with an activity feed listing each write under your label, plus a
+  connected-writers sheet. Identify yourself (`PMX_CANVAS_AGENT_SOURCE`, or `x-pmx-source` on
+  HTTP) so the feed names you, not the transport. Pending explicit intents carry an inline Veto
+  there.
+- **Focus session** (attached): your cursor sits on the node you last touched with a phase chip
+  (`idle` / `thinking` / `tooling` / `waiting-approval`); every MCP/HTTP write is attributed to
+  your session automatically (pass `agentId` only to keep a sub-agent separate); the human gets
+  the session panel (work items, approval gates, timeline of your tool runs, board writes,
+  evidence and steering), a command bar that posts steering you read on your next turn (with a target
+  picker when several agents are connected), a timeline filterable by kind (Updates / Steer /
+  Events / Evidence), and a context meter. That meter is the pinned-context payload estimated against a configured budget
+  ("Pins") unless your host reports your real token usage on the presence
+  (`set-presence { contextUsage: { used, total } }`) — then it shows your actual window
+  ("Context"). The Copilot extension reports it automatically; other hosts report it themselves. Report `phase: "thinking"` before a long reasoning stretch if your host
+  gives you a hook; `tooling` is derived from your writes. Hosts with adapters (the Copilot
+  extension) attach for you; the human can also start a session from the board's *Start agent
+  session* button — your writes (transport or `PMX_CANVAS_AGENT_SOURCE` label alike) are
+  attributed to it and it takes your name.
+
+What the session asks of you:
+
+- **Detach explicitly** (`attached: false` or a `session-end` activity). Attaching over a
+  non-empty board saved a `Before session · …` snapshot; detaching emits the receipt (items
+  done / vetoed, a diff against that snapshot, one-click restore) — an idle timeout delays it.
+- **403 = outside the scope fence.** The human may fence you to a region (`policy.scope`): writes
+  outside it are refused with a reason naming the node or position (a fenced group frame
+  grants its members too). Read `policy.scope` in `canvas://ax-context`, ask the human to widen
+  it, never retry blindly. The fence is the human's: `set-policy` does not take `scope`.
+- **409 = a human is holding that node** (dragging or editing it right now). Requeue the change
+  and retry in a moment. If you had signalled an intent on it, it was vetoed — a `yield` timeline
+  event says who took over.
+- **A gate you do not answer auto-holds** (`held`, default TTL 5 min). `held` is a non-approval:
+  do not proceed; the human can reopen it from the panel. A rejection reaches you as steering.
+- **Your latest edit can be undone from the panel.** One shared undo stack: when the human undoes
+  it you get steering ("Undid your edit: …"); treat the board as the truth, not your last write.
+- **Steering arrives as `steering-message` rows** in `canvas://ax-timeline` (or claim them via
+  `canvas_ax_delivery`). The command bar, gate rejections, undo and take-overs all speak through
+  it. Steering may be ADDRESSED: with several agents connected the human picks a recipient in
+  the composer, and a claim only returns broadcasts plus messages targeted at your `consumer`
+  label — so always claim as yourself (your `PMX_CANVAS_AGENT_SOURCE` label), or addressed
+  steering never reaches you.
+- **Steering is also the agent-to-agent mailbox.** To coordinate with another agent on the
+  board, send `canvas_ax_timeline { action: "send-steering", message, target: "<their
+  consumer label>" }` — they claim it once on their next turn, you never receive your own, and
+  the human sees the exchange in the panel as "you → them · message". Read
+  `canvas_ax_state { action: "presence" }` for who is connected. Park shared state in work
+  items and evidence; split territory with group frames rather than editing the same node.
+
 ## Browser Workflows
 
 Use the visible workbench when the human is actively curating layout:
 
 - Drag nodes to move them.
-- Shift+drag empty space to lasso-select.
-- Use the selection bar for Pin as context, Group, Connect, and Clear.
+- Drag empty space to lasso-select (Select tool, the default); hold Space or pick the rail's Pan
+  tool to pan instead — the Pan tool pans even when the drag starts on a node.
+- The selection bar (floating bottom-center) offers count, align left/top, distribute,
+  auto-arrange, Group (G), Connect, Pin as context, delete and clear; selected nodes show an
+  accent outline with corner handles.
 - Right-click a node for context pinning, position locking, focus, collapse, connect, refresh,
   open, close, and type-specific actions.
-- Drop files or URLs to create matching nodes.
+- Drop files or URLs to create matching nodes; an empty board shows starter actions (new note,
+  pick files, paste a link, start an agent session).
 - Double-click markdown to edit inline.
-- Use toolbar snapshots before experiments and restore only after confirmation.
-- The toolbar carries view controls (fit, reset, zoom), arrange, minimap, a theme picker (nine
-  themes: dark, light, high-contrast, midnight, sepia, arctic, ember, forest, volt), snapshots, trace,
-  the annotation tools, search (Cmd+K), and shortcuts. On narrow viewports (≤900px — most
-  embedded host panes and mobile) the secondary controls collapse into a single "⋯" More menu at
-  the end of the bar; every action is still there as a labeled row, including the theme list. If
-  an automation script can't find a toolbar button at panel width, open the More menu first.
+- **Groups** are frames with the name pill and an action cluster (auto-arrange children, collapse,
+  ⋯ rename / ungroup / pin all) on the top edge. Membership changes only on release while the
+  "release to add to <group>" pill shows (Esc keeps it out); dragging a child fully out offers
+  "release to remove". A collapsed group is a chip that hides its children (edges to them draw
+  to the chip). G groups the selection, Shift+G ungroups. Ungroup *dissolves* the frame (children
+  stay, nested children move up one level, one undo step) — and your
+  `canvas_group { action: "ungroup" }` is the same operation with the same result.
+- **Edges**: drag from a node port, or pick the rail's Connect tool (C) and drag from anywhere on
+  a node; the target lights up, Esc cancels, L asks for a label on release.
+- The **History** drawer (rail camera button, or the receipt's Full log) lists snapshots and
+  agent sessions in one timeline; save a snapshot there before experiments and restore only after
+  confirmation. Ctrl/Cmd+Z and Shift+Z work the shared undo stack.
+- The **minimap** (bottom-right of the canvas) is a true-scale map; hover magnifies it, click
+  jumps, drag pans. A banner under the top bar reports a dropped stream (reconnecting) or a
+  post-reconnect resync; edits still save over HTTP meanwhile.
+- Other open tabs appear as green cursors with a name tag (`/workbench?name=mia` sets yours);
+  a node you drag is locked for agents until you release it.
+- The chrome is a persistent 52px left tool rail plus a slim 44px top bar (0.4.8+). The rail
+  carries the tools (Select V, Pan Space, Connect C), node creation (markdown M, image I, file
+  Shift+F, webpage W, HTML surface H, group G, annotate A — a popover with draw / text / eraser),
+  and utilities: search & commands (Cmd+K — actions with shortcuts, then jump-to-node), arrange,
+  trace, minimap, history, the theme picker (nine themes: dark, light, high-contrast, midnight,
+  sepia, arctic, ember, forest, volt), and shortcuts (?). The top bar holds the connection dot,
+  workspace title, the session chip / gate badge / context meter while a session is attached
+  (or the external-writers indicator and *Start agent session* otherwise), and the zoom cluster
+  (zoom out, % label = reset, zoom in, fit F). Hovering a rail button shows a tooltip with its
+  shortcut.
+  On viewports ≤1180px the top bar drops its meta text and the session panel becomes a drawer;
+  every control stays in the rail at any width — there is no separate mobile menu.
+- Keyboard: nodes are focusable — arrow keys move to the nearest node, Enter opens it in focus
+  mode (a scrim + inset view with Open in tab), Esc closes the top-most overlay.
 - Embedding hosts can open `/workbench?theme=<name>` (or `?theme=auto` to follow the host's
   light/dark appearance) for a session-local default theme that never changes the server-global
   theme other clients see; an explicit pick from the theme menu ends the override. The bundled
@@ -356,8 +443,12 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   affordance. The connecting overlay stays up until paint is confirmed, so a black layer is
   never presented as ready. The recovery trail
   (`GET /api/canvas/debug/ext-app-recovery` / `window.__PMX_EXTAPP_LOG`) now records
-  `mount-slot`, `paint-ok`, `paint-fail`, `soft-expand-cycle`, and `recovery-exhausted` — when
-  diagnosing, trust `paint-ok`/`paint-fail`, and never assert health from `settled` alone. If a
+  `mount-slot`, `paint-ok`, `paint-fail`, `soft-expand-cycle`, `recovery-exhausted`, and
+  `assume-visible-rearm` — when diagnosing, trust `paint-ok`/`paint-fail`, and never assert
+  health from `settled` alone. Exception: in a host that reports the document hidden (the
+  GitHub Copilot panel does so continuously), `paint-ok` is recorded as
+  `paint-ok (unverified: host hidden)` — the app answered the paint probe, but nothing is
+  proven composited, so do not treat it as a verified paint. If a
   tile still shows the Retry affordance, click Retry (fresh recovery budget) or expand-then-close;
   attach the recovery trail when reporting.
 - Ext-app frame documents live in server memory. Through 0.4.0, killing/restarting the daemon

package/skills/pmx-canvas/references/codex-app-adapter.md

@@ -60,6 +60,34 @@ The MCP server auto-starts the HTTP workbench on first tool call. Open the retur
 in the Codex in-app Browser, usually `http://127.0.0.1:4313/workbench` or
 `http://localhost:4313/workbench`.
 
+### Agent presence (cursor + phase chip)
+
+Name the agent on the MCP server so its writes, its session, and its cursor share one identity:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "bunx",
+      "args": ["pmx-canvas", "--mcp"],
+      "env": { "PMX_CANVAS_AGENT_SOURCE": "codex" }
+    }
+  }
+}
+```
+
+Then attach at the start of a task and detach at the end:
+
+```json
+{ "tool": "canvas_ax_state", "action": "set-presence", "attached": true, "label": "Codex", "phase": "idle" }
+{ "tool": "canvas_ax_state", "action": "set-presence", "attached": false }
+```
+
+While attached the workbench shows the Codex cursor on the node it last touched and a phase chip
+(`thinking` · `tooling` · `waiting-approval` · `idle`). `tooling` and the cursor position are
+derived from Codex's own MCP writes — nothing per call. Even without `PMX_CANVAS_AGENT_SOURCE`,
+writes arriving as plain `mcp` are attributed to the single attached session.
+
 ## Codex-Native Workflow
 
 1. Open `/workbench` in the Codex in-app Browser as the first visible action. If PMX is not running

package/skills/pmx-canvas/references/full-reference.md

@@ -132,8 +132,8 @@ pmx-canvas --theme=light       # Light theme
 pmx-canvas --version           # Print installed version and exit
 ```
 
-`--theme` accepts `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`, or `volt` (0.4.x; the browser toolbar has a matching theme picker). Same value can be set via
-the `PMX_CANVAS_THEME` environment variable, or toggled live in the browser toolbar.
+`--theme` accepts `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`, or `volt` (0.4.x; the rail's theme picker lists the same nine). Same value can be set via
+the `PMX_CANVAS_THEME` environment variable, or picked live from the left tool rail.
 
 Start the canvas once per session, then reuse it. Use `--no-open` when running as an agent — the
 human can open the browser URL themselves.
@@ -202,7 +202,7 @@ server and become part of the authoritative canvas state.
   and type-specific actions. (Every node type, **including `status`, has a remove `×`** in its title
   bar and a `Close` menu item.)
 - Right-click a group node — recolor the group using preset swatches or a custom color picker,
-  and ungroup its children
+  or ungroup it (dissolves the frame; children stay)
 - Drag-and-drop files or URLs — add file, image, markdown, or webpage nodes directly
 - Paste URLs — create webpage nodes from the clipboard
 
@@ -421,7 +421,7 @@ When you do set a color (group/graph), use this palette consistently to convey m
 ## MCP Tools Reference
 
 PMX Canvas exposes **16 action-discriminated composites** (the whole recommended surface) plus
-**6 first-class standalones** — 22 tools total (v0.4.x). The composites fold the older
+**6 first-class standalones** — 22 tools total. The composites fold the older
 single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) discriminator —
 **field names are unchanged**; only the tool name + the `action`/`kind` selector differ.
 
@@ -436,7 +436,7 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 |-----------|-----------------|--------------|
 | `canvas_node` | `add` · `get` · `update` · `remove` | Create / read / mutate / delete a node. **`add` covers html + primitives too**: `{ action:"add", type:"html", html:"…" }` and `{ action:"add", type:"html", primitive:"choice-grid", data:{} }` — no separate add-html tool needed |
 | `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` | Schema introspection, spec dry-run validation, and native json-render / graph node creation |
-| `canvas_edge` | `add` · `remove` | Connect / disconnect nodes |
+| `canvas_edge` | `add` · `update` · `remove` | Connect / edit / disconnect nodes |
 | `canvas_group` | `create` · `add` · `ungroup` | Manage spatial group containers |
 | `canvas_history` | `undo` · `redo` | Time travel through the mutation ring buffer |
 | `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | Named snapshots: save/list/restore/delete, garbage-collect old ones, diff current canvas vs a snapshot (`diff` takes `snapshot`, not `id`) |
@@ -444,7 +444,7 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 | `canvas_query` | `search` · `layout` · `validate` | Find nodes by keyword, read full layout, or **`validate`** the board for node collisions / group-containment / dangling edges |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | Hosted MCP apps, the Excalidraw diagram preset, and bundled web artifacts (folds `canvas_open_mcp_app` / `canvas_add_diagram` / `canvas_build_web_artifact`) |
 | `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | Headless Bun.WebView automation for the workbench (folds the `canvas_webview_*` / `canvas_resize` / `canvas_evaluate` tools) |
-| `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` | Read AX state; set AX focus; patch tool/prompt policy; report host capability |
+| `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` · `presence` · `set-presence` | Read AX state; set AX focus; patch tool/prompt policy (the scope fence is human-set, read-only here); report host capability; read / set agent presence (phase, cursor, focus, attached session) |
 | `canvas_ax_work` | `add` · `update` · `annotate` | Canvas-bound work items + review annotations |
 | `canvas_ax_gate` | `request` · `resolve` · `await` × `kind` `approval` \| `elicitation` \| `mode` | The human-decision gate machine (request → await → resolve) |
 | `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` | The bounded AX diagnostics timeline |
@@ -512,7 +512,7 @@ composite in v0.4.0 (actions `save | list | restore | delete | gc | diff`); the
 standalones were removed after their deprecated 0.3.x window.
 
 `canvas_batch` supports exactly these ops: `node.add`, `node.update`, `node.remove`, `graph.add`,
-`edge.add`, `edge.remove`, `group.create`, `group.add`, `group.remove`, `pin.set`/`pin.add`/
+`edge.add`, `edge.update`, `edge.remove`, `group.create`, `group.add`, `group.remove`, `pin.set`/`pin.add`/
 `pin.remove`, `snapshot.save`, and `arrange`. Anything else fails with "Unsupported canvas_batch
 operation" — batch is non-atomic, so earlier ops stay applied and the response carries
 `failedIndex`. `canvas_screenshot` requires an active automation WebView: call
@@ -692,7 +692,9 @@ In batch/MCP/HTTP payloads, `height` is chart content height and `nodeHeight` is
 
 - **`canvas_group { action: "create", … }`** — visual container; `title`, `childIds` (node IDs), `color`. Auto-sizes to fit children.
 - **`canvas_group { action: "add", groupId, childIds }`** — add nodes to an existing group.
-- **`canvas_group { action: "ungroup", groupId }`** — release all children from a group.
+- **`canvas_group { action: "ungroup", groupId }`** — dissolve the group: its children become
+  independent nodes (members of the enclosing group when nested) and the frame is removed, in one
+  undo step. Exactly what the human's Ungroup does.
 
 ### Group Layout Guidance
 
@@ -827,10 +829,20 @@ Useful workbench selectors:
 - Annotations: `.annotation-layer path` renders human-drawn freehand ink. Use WebView
   to inspect or screenshot annotation shapes; MCP/context resources only expose compact
   annotation target summaries, not the raw visual shape. Humans can remove marks with
-  the eraser toolbar button; agents can remove a known annotation ID with
+  the eraser in the rail's Annotate popover; agents can remove a known annotation ID with
   `canvas_view { action: "remove-annotation" }`.
-- Canvas chrome: `.hud-layer`, `.canvas-toolbar`, `.connection-dot`, `.canvas-bootstrap-card`
-- Nodes do not expose stable `data-node-id` attributes. Use `canvas_query` (`layout` / `search`) or MCP resource data for exact node IDs.
+- Canvas chrome (rail-chrome-v2): `.tool-rail`, `.top-bar` (`.connection-dot`, `.agent-chip`,
+  `.gate-badge`, `.context-budget`, `.external-indicator`, `.start-session-btn`),
+  `.connection-banner`, `.canvas-region`, `.session-panel`, `.command-bar`, `.selection-bar`,
+  `.activity-feed`, `.writers-sheet`, `.session-receipt`, `.snapshot-panel` (the History
+  drawer), `.minimap`, `.empty-state`, `.command-palette`, `.expanded-overlay-panel`.
+- Presence: `.agent-cursor` (attached agent), `.human-cursor` (other tabs), `.scope-fence`,
+  `.canvas-node.agent-mutating` (shimmer), `.node-yield-pill`.
+- Groups: `.canvas-node.group-node` with `.group-name-pill`, `.group-actions`, `.group-chip`
+  (collapsed); `.drop-pill` while a dragged node would join/leave a group; `.edge-hint-pill`
+  during an edge drag.
+- Every `.canvas-node` carries `data-node-id` and `data-node-type` (rail-chrome redesign); `canvas_query`
+  (`layout` / `search`) remains the reliable way to get ids without a browser.
 
 Async script example:
 
@@ -1098,10 +1110,37 @@ nodes.
   `pmx-canvas ax command invoke`; envelope `ax.command.invoke`). Unknown names
   are rejected; an invocation records an `agent-event` of kind `command`.
 - **Policy:** a canvas-bound, snapshotted tool/prompt policy
-  (`tools.allowed|excluded|approvalRequired`, `prompt.systemAppend|mode`) read
-  into `canvas://ax-context`. Patch it with `canvas_ax_state { action: "set-policy" }`
-  (HTTP `GET|POST /api/canvas/ax/policy`; CLI `pmx-canvas ax policy get|set`); patches
-  merge and are normalized server-side.
+  (`tools.allowed|excluded|approvalRequired`, `prompt.systemAppend|mode`, and the
+  **scope fence** `scope: { nodeIds, padding }`) read into `canvas://ax-context`. Patch it
+  with `canvas_ax_state { action: "set-policy" }` (HTTP `GET|POST /api/canvas/ax/policy`;
+  CLI `pmx-canvas ax policy get|set`); patches merge and are normalized server-side.
+  While a fence is set, your canvas WRITES outside it (nodes not in the set, new nodes
+  outside the fenced box, arrange/clear/restore) are refused with HTTP 403 naming the
+  reason; reads are never fenced. The fence is the human's: `set-policy` does not take
+  `scope`, and an HTTP policy call that includes it is refused (403). Read `policy.scope`
+  before writing and ask the human to widen it rather than retrying.
+- **External steering (no session):** a writer with no attached session is shown passively —
+  a top-bar indicator (avatars, "N writers · M ops"), a click-to-open activity feed (one row
+  per write: "Created markdown “…”" under the writer's label, per-writer filters, inline Veto
+  on your pending explicit intents) and a connected-writers sheet. Pure visibility: pmx-canvas
+  is local-first and veto/ghosting is the safety model, not permissions. The feed is
+  `activity` on `GET /api/canvas/ax/presence` (`canvas_ax_state { action: "presence" }`).
+- **Session receipt:** attaching a session (`set-presence { attached: true }` or a
+  `session-start` activity) over a non-empty board saves a `Before session · <label> · HH:MM`
+  snapshot; ending it (`attached: false`, `session-end`, or idle expiry) emits one
+  `agent-session-ended` SSE frame — `{ label, endedAt, counts: { items, done, vetoed },
+  snapshot }` — which the browser shows as a receipt with *View diff* (the session's own
+  changes) and a restore path. End your session explicitly so the receipt is prompt. The
+  human's *Start agent session* button is the same attach with `source: "browser"`.
+- **Human collaborators / user wins:** every open workbench tab is a presence (`GET
+  /api/canvas/human-presence`); a node a human is dragging is locked — an agent write to it is
+  refused with 409 until release (requeue and retry), and a pending explicit intent on it is
+  vetoed with a `yield` timeline event.
+- **Unattended approvals:** a pending approval gate carries a TTL (`ttlMs` on the request,
+  default 5 min). If the human does not answer in time it resolves to `held` — a
+  non-approval: do not proceed — and a `policy` agent-event explains why. The human can
+  reopen it from the session panel; an `await` on the gate returns when it leaves
+  `pending`, so treat any status other than `approved` as "do not proceed".
 
 Interactions request PMX-AX primitives only — never arbitrary shell, tool, MCP,
 or host execution.
@@ -1278,7 +1317,7 @@ All POST/PATCH endpoints accept `Content-Type: application/json`. Default base U
 | POST | `/api/canvas/web-artifact` | Build a bundled web artifact and optionally open it on canvas |
 | POST | `/api/canvas/group` | Create group |
 | POST | `/api/canvas/group/add` | Add nodes to group |
-| POST | `/api/canvas/group/ungroup` | Ungroup |
+| POST | `/api/canvas/group/ungroup` | Ungroup (dissolve: children released, frame removed) |
 | POST | `/api/canvas/arrange` | Auto-arrange |
 | POST | `/api/canvas/focus` | Center viewport on node |
 | POST | `/api/canvas/fit` | Fit viewport to canvas bounds or selected nodes |

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -13,8 +13,9 @@ maps Copilot SDK features onto PMX AX primitives.
 
 ## Quick Start
 
-1. Install the project adapter by copying the packaged extension into the repository:
-   `mkdir -p .github/extensions/pmx-canvas && cp node_modules/pmx-canvas/.github/extensions/pmx-canvas/extension.mjs .github/extensions/pmx-canvas/extension.mjs`
+1. Install the project adapter with `pmx-canvas copilot install-extension --yes`, or copy the
+   packaged extension directory into the repository:
+   `mkdir -p .github/extensions && cp -R node_modules/pmx-canvas/.github/extensions/pmx-canvas .github/extensions/`
 2. Reload Copilot app extensions with `extensions_reload` so `project:pmx-canvas` is registered.
 3. Start or confirm a PMX Canvas daemon for the workspace: `pmx-canvas serve --daemon`
    and `pmx-canvas serve status`. The adapter can auto-start in many local sessions, but a running
@@ -38,6 +39,20 @@ Open it with:
 Use a different `instanceId` for parallel panels. Reusing an `instanceId` focuses/reloads the same
 panel.
 
+## Agent presence (automatic)
+
+The extension also reports Copilot's real context window: the SDK's `session.usage_info`
+event (`currentTokens` / `tokenLimit`, root agent only) is posted to the presence as
+`contextUsage`, so the board's top-bar meter reads **Context** with the live numbers rather
+than the pinned-context estimate (**Pins**).
+
+The extension attaches a Copilot session to the canvas when it joins the host session, flips the
+phase to `thinking` on every submitted prompt, and detaches on exit. While attached the workbench
+shows the Copilot cursor on the node the agent last touched plus a phase chip, and the agent's
+canvas writes — which reach the server as MCP or HTTP tool calls, not as `copilot` — are attributed
+to that session by the server. Nothing to configure; `GET /api/canvas/ax/presence` shows the live
+state.
+
 ## What the Adapter Does
 
 - Opens the live PMX workbench directly in a native Copilot canvas panel.
@@ -49,21 +64,28 @@ panel.
   `onUserPromptSubmitted`.
 - Exposes adapter actions for status, AX context refresh, AX focus, and explicit session steering.
 
-### Agent behavior — steering is gated, not pushed
+### Agent behavior — steering push with a gated fallback
+
+The adapter long-polls the consumer-scoped delivery queue, sends each steer through
+`copilotSession.send`, and marks it only after the host accepts the prompt. Browser-originated
+steering therefore creates a Copilot turn without waiting for another chat message. Addressed
+steers follow their target; broadcasts are marked only for the `copilot` consumer; Copilot-origin
+messages are excluded by the queue's loop-safety filter.
+
+On adapter startup, existing backlog is marked for the `copilot` consumer without creating turns.
+Only steers created after that adapter instance started can wake it, so reopening Copilot cannot
+flood the chat with stale instructions from prior sessions.
 
-`onUserPromptSubmitted` injects the whole `/api/canvas/ax/context` (pins, focus, work
-items, approval gates, and the compact `delivery` lead block) as hidden context — but
-only when the **pin/focus gate is open** (`pinned.count > 0 || focus.nodeIds.length > 0`),
-and it is clipped to a char budget. Read steering from **`delivery.pendingSteering`**
-(the compact, count-bearing block — newest-first, capped at 10), not the full
-`timeline.pendingSteering`. Three consequences the adapter/agent must honor:
+`onUserPromptSubmitted` remains the fallback. It injects the whole `/api/canvas/ax/context`
+(pins, focus, work items, approval gates, and the compact `delivery` lead block) as hidden context,
+but only when the **pin/focus gate is open** (`pinned.count > 0 || focus.nodeIds.length > 0`), and
+it is clipped to a char budget. Read steering from **`delivery.pendingSteering`** (the compact,
+count-bearing block — newest-first, capped at 10), not the full `timeline.pendingSteering`.
 
-1. A steering board must **stay pinned** (or its button must also emit `ax.focus.set`
-   on the board node) to hold the gate open.
-2. A sandbox button click does **not** wake a turn — a human message does. The click
-   only enqueues the steer.
-3. The agent must **act on injected `delivery.pendingSteering` / `pendingActivity` and
-   then ack** (`canvas_ax_delivery { action: "mark" }`), or it re-injects every gated turn.
+If native send fails, the adapter leaves the steer unmarked and retries. If marking fails after a
+successful send, the in-process pump retries the mark without sending the prompt twice. A process
+restart establishes a new delivery baseline and marks older unacknowledged rows without replaying
+them.
 
 To be robust to the char clip, prefer injecting that compact loop-safe lead block from
 `GET /api/canvas/ax/context?consumer=copilot` (`delivery.pendingSteering` +
@@ -73,15 +95,10 @@ To be robust to the char clip, prefer injecting that compact loop-safe lead bloc
 
 #### Waking the agent from a canvas steer (#59) — adapter-owned
 
-Recording a browser-origin `ax.steer` does **not** wake the active session by itself
-(report #59); PMX only queues it (the `ok:true` emit ack = "recorded", not "delivered").
-To make a canvas **Steer** button actually create a visible turn, the adapter must, on
-its own cadence (e.g. an SSE subscription or poll), **drain**
-`canvas_ax_delivery { action: "claim", consumer: "copilot" }`, call the host's native
-send (`copilotSession.send` / the working `send_instruction` path) with each steer, then
-`canvas_ax_delivery { action: "mark" }` it (loop-safe). This wake is intentionally
-host-owned — PMX never imports the host SDK. Until the adapter wires it, a steering
-button must be labeled "queued for the agent's next turn", not "steer now".
+Recording a browser-origin `ax.steer` queues it in PMX; the Copilot adapter owns the wake. Its
+delivery pump long-polls `…/delivery/pending?consumer=copilot`, calls
+`copilotSession.send`, then marks that consumer's delivery. PMX remains host-agnostic and never
+imports the Copilot SDK.
 
 ### Closing the loop (optional, recommended)
 

package/skills/pmx-canvas-orchestration/SKILL.md

@@ -24,6 +24,23 @@ it, or the board silently diverges from reality.
   their run scoping comes from the run-prefixed `agentId`, e.g. `run7:impl-auth`), so
   consecutive orchestrations don't interleave in the bounded timeline.
 
+## Presence (rail-chrome-v2)
+
+- The ORCHESTRATOR attaches the session: `canvas_ax_state { action: "set-presence",
+  attached: true, label: "<run label>" }` at run start and `{ attached: false }` at the end
+  (the human gets a receipt: items done / vetoed, a diff against the pre-run snapshot, one-click
+  restore). Subagents never attach — writes they make through MCP/HTTP with no `agentId` are
+  attributed to the orchestrator's session; a subagent that passes `agentId` shows as its own
+  writer. Pick one: a single cursor for the run (no `agentId` on board writes) or one per
+  subagent (`agentId` everywhere, also in the writers sheet).
+- The board may be fenced (`policy.scope`). A 403 from any participant means "outside the
+  fence": report it to the orchestrator, who asks the human — never widen it yourself (the
+  fence is the human's; `set-policy` cannot set it).
+- A 409 means a human is holding that node right now: requeue that step's write and retry
+  after the next steering poll. A `yield` timeline event names who took over.
+- Unanswered gates auto-hold (`held`) after their TTL: treat `held` as "do not proceed" and
+  keep the subagent's step `blocked` until the human reopens and answers.
+
 ## Graph semantics
 
 - `flow` edges = planned sequence. `depends-on` edges = blocking dependency (the visual DAG).
@@ -57,11 +74,48 @@ it, or the board silently diverges from reality.
   subagent, so everything is pull. Cadence: check `canvas://ax-pending-steering` (or
   `canvas_ax_delivery { action: "claim", consumer: "<agentId or host>" }`) between every major
   step.
+- **Reactive loop (0.4.9+):** pass `timeoutMs` (MCP) / `?waitMs` (HTTP) to the claim and the
+  call BLOCKS until steering for your consumer arrives (capped at 120000ms per call). A host
+  that cannot be woken from outside (Copilot, Codex — their model runs only while the host
+  gives it a turn) reacts to canvas steering by looping on this inside one turn:
+  claim(timeoutMs: 120000) → act on each message → mark → repeat until the human says stop or
+  the turn budget runs out. One standing prompt in the host ("run the canvas steering loop")
+  makes the composer's addressed steers land promptly instead of sitting queued.
 - Address a specific agent with the steering `target` field (0.4.5+). Untargeted steers are
-  broadcast: only the ORCHESTRATOR claims them and re-routes; subagents claim only steers
-  targeted at their own `agentId`.
+  broadcast — and delivered PER CONSUMER (0.4.9+): every agent that claims with its own
+  consumer key receives the broadcast, and marking it (`consumer: "<your key>"`) removes it
+  from YOUR queue only. "All workers: stop" reaches the whole fleet; each worker marks its own
+  copy after acting.
+- **Territories (0.4.9+):** the orchestrator fences each worker to its lane with
+  `ax.policy.set { agentScopes: { "<worker agentId>": { nodeIds, padding } } }` — that worker's
+  writes outside the territory are refused (403) while everyone else roams. An agent can fence
+  OTHER writers but never its own key; the human can set or clear any territory.
+- **Spawn-window ghosts:** the default intent TTL (8 s) dies before a spawned worker's first
+  write — signal spawn choreography with `ttlMs: 30000-60000`. A ghost that expires QUIETLY no
+  longer blocks its linked mutation (it proceeds unlinked; only a human veto refuses), so a slow
+  spawn cannot poison a batch.
+- **Identity discipline:** never pass a worker's `agentId` on writes YOU make on its behalf —
+  attribution follows `agentId`, so the activity feed would book your write as the worker's.
+  Create shared scaffolding (lanes, work items) under your own identity, then let each worker
+  write as itself. Workers should OMIT `attached` entirely (they are writers, not sessions).
+- **CLI hosts (Codex CLI, Amp) become reactive with the pump:** run
+  `pmx-canvas pump --consumer codex-cli --exec 'codex exec --full-auto {message}'` — it
+  long-polls the inbox, hands each steer to a CLI task, and marks per-consumer only after success.
+  This does not steer an open Codex desktop task; desktop requires a host adapter using the app's
+  native follow-up channel. `--parent` rolls the pumped agent under its orchestrator.
+- **No MCP in the subagent?** Workers spawned inside a host often lack the canvas MCP — the
+  plain HTTP API is the worker path: POST /api/canvas/node, /api/canvas/ax/presence,
+  /api/canvas/ax/delivery/pending?consumer=<agentId>, /:id/mark. Same identity rules apply.
+- **Fleet chrome:** every worker should declare its orchestrator on set-presence
+  (`parentAgentId: "<orchestrator key>"`): the top bar rolls workers up into the
+  orchestrator's chip ("+N workers") and their cursors render smaller so a big fleet stays
+  legible.
 - Mark delivery ONLY after acting on the message. The mark is compare-and-set: a
   `delivered:false` response means another consumer owned it — drop it, do not act twice.
+- Steering comes from more places than the command bar: a gate rejection, the human undoing
+  one of your board edits ("Undid your edit: …"), a take-over of a node you were editing, and
+  vetoed ghost intents all arrive as steering. The orchestrator re-routes them to the subagent
+  whose node they name.
 
 ## Run lifecycle