pmx-canvas 0.4.7 → 0.5.0

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

@@ -30,6 +30,16 @@ bun run test:web-canvas     # Browser smoke against a real running app
 bun run test:all            # Bun suite + browser smoke
 ```
 
+**Direct `bun test` is side-effect-guarded by `tests/preload.ts`** (wired via `bunfig.toml`
+`[test].preload`): it defaults `PMX_CANVAS_DISABLE_BROWSER_OPEN=1` so the suite's open-as-site
+tests cannot launch the developer's real browser, whichever way the tests are invoked. The
+preload covers `bun test` only — when you boot a server yourself (`bun run src/cli/index.ts`),
+pass `--no-open` and set `PMX_CANVAS_DISABLE_BROWSER_OPEN=1` explicitly.
+
+**Never pipe a gating command through `tail`, `head`, or `grep`.** The pipeline reports the exit
+code of the LAST command, so `bun run test | tail -5` exits 0 on a red suite. Redirect to a file
+and check `$?`, then read the file.
+
 ## Which Command To Run
 
 - Server/state/API-only changes: run `bun run test`
@@ -79,6 +89,30 @@ Prefer extending the existing suites before inventing a one-off script.
   `pmx-canvas skills sync --yes` to refresh them (whole trees, whatever agent layout owns them) before
   trusting skill-guided results
 
+## Tests That Cannot Fail
+
+A test that passes against the broken code is worse than no test — it certifies the bug. Every
+regression test must be shown to discriminate: run it against the unfixed code (or hard-code the
+broken value) and watch it go red BEFORE you trust the green.
+
+Four ways a test silently stops discriminating in this repo:
+
+- **Polled assertions pass on the first sample.** `expect.poll(fn).toBeGreaterThanOrEqual(180)`
+  succeeds the instant one sample qualifies, so it never observes the failure window. Wait for the
+  settle condition, then assert once.
+- **Committed fixtures embed generated output.** `src/server/demo-state.json` carries each
+  primitive's generated markup; count and coverage assertions are satisfied by stale markup just
+  as well as fresh. Guard generated fixtures by rebuilding from the generator's INPUT and
+  byte-comparing against the current renderer.
+- **Absolute assertions about globally-wired side effects are order-dependent.** Anything flowing
+  through a single-slot listener (architecture rule 8 in `CLAUDE.md`) is wired or not depending on
+  whether an earlier test file booted a server — so the test passes alone and fails in the suite,
+  or vice versa. Assert DIFFERENTIALLY: run the action disarmed and armed, require the deltas to
+  match. Always run the full suite before trusting a new test; a single-file run hides this.
+- **A new node type passes every test and renders nothing.** Server, API, and client-unit
+  assertions all pass while `isCanvasNodeType` drops the type during layout apply. Only a DOM
+  census on a live board catches it.
+
 ## Layout And Embedded Content Checks
 
 - For seeded or generated boards, add API-level geometry assertions: expected node/edge counts,
@@ -95,6 +129,12 @@ Prefer extending the existing suites before inventing a one-off script.
 - When checking embedded frame fit manually, start from a clean seeded state, rebuild stale bundles,
   and inspect the actual iframe document in a browser. Server dimensions can look correct while the
   embedded content is still clipped.
+- **A node's stored content is not render evidence.** An html/primitive node's stored HTML holds
+  every conditional branch — hidden banners, error states, empty states — so a content-level read
+  (search hit, pinned context, `node get`, any text summary) quotes strings the user never saw.
+  The 0.4.7 report filed an "AX bridge unavailable" banner as a live product gap on exactly this
+  basis; the served surface had the bridge injected ahead of the check and the banner was `hidden`
+  in the document. Before filing a rendering bug, fetch the served surface or inspect the DOM.
 - User-facing creation flows must end with the new nodes visible: after the create (plus the
   skill-mandated focus/fit), a screenshot must show them without any manual pan. A `panned: true`
   API result alone is not proof — verify the frame is on-screen and unobscured.
@@ -117,3 +157,20 @@ Before marking work done, report:
 
 For non-trivial changes, the default expectation is `bun run test:all` unless there is a clear
 reason to scope verification more narrowly.
+
+## Presence, sessions, and the redesigned chrome (rail-chrome-v2)
+
+- Agent/human presence is in-memory and TTL-swept. An e2e reset must detach any attached
+  session (`POST /api/canvas/ax/presence { attached: false }` per attached presence), clear the
+  scope fence, and mark its own writes with `x-pmx-workbench: 1` — otherwise the harness reads
+  as an external writer and a leftover fence refuses the next test's `clear`. Unattached writers
+  from earlier tests can still be live (90 s): assert about YOUR writers, not exact totals.
+- Assert SSE frames as received (`readSseEvent` in `tests/unit/agent-presence-api.test.ts`), not
+  the object handed to the emitter — the envelope overwrites `sessionId` and `timestamp`.
+- Two-tab behaviour (human cursors, the edit lock) needs two browser contexts; name them with
+  `/workbench?name=…` so assertions can target a cursor by its tag.
+- The Browser pane reports `visibility: hidden` and never fires rAF: drags, drop pills, edge
+  previews and presence animations only work under Playwright. Use the pane for static checks.
+- Selection is shift-click on the node BODY (the titlebar drags); groups have no ports and
+  their drag handle is the edge row; the selection bar and command bar both float bottom-center
+  (the selection bar lifts during a session).

package/src/cli/agent.ts

@@ -28,6 +28,7 @@ import './commands/query.js';
 import './commands/pins.js';
 import './commands/history.js';
 import './commands/ax.js';
+import './commands/pump.js';
 import './commands/webview.js';
 import './commands/apps.js';
 import './commands/copilot.js';

package/src/cli/commands/copilot.ts

@@ -1,7 +1,7 @@
 // Copilot adapter commands: copilot install-extension.
 
 import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { cmd, die, getStringFlag, output, parseFlags, showCommandHelp } from '../shared.js';
 
@@ -17,18 +17,23 @@ cmd(
     const { flags } = parseFlags(args);
     if (flags.help || flags.h) return showCommandHelp('copilot install-extension');
 
-    const sourcePath = fileURLToPath(new URL('../../../.github/extensions/pmx-canvas/extension.mjs', import.meta.url));
-    if (!existsSync(sourcePath)) {
-      die('Bundled Copilot extension adapter not found.', `Expected at ${sourcePath}`);
+    const sourcePaths = [
+      fileURLToPath(new URL('../../../.github/extensions/pmx-canvas/extension.mjs', import.meta.url)),
+      fileURLToPath(new URL('../../../.github/extensions/pmx-canvas/steering-delivery.mjs', import.meta.url)),
+    ];
+    const missingSource = sourcePaths.find((sourcePath) => !existsSync(sourcePath));
+    if (missingSource) {
+      die('Bundled Copilot extension adapter not found.', `Expected at ${missingSource}`);
     }
 
     const targetPath =
       getStringFlag(flags, 'target') ?? join(process.cwd(), '.github', 'extensions', 'pmx-canvas', 'extension.mjs');
+    const targetPaths = sourcePaths.map((sourcePath) => join(dirname(targetPath), basename(sourcePath)));
     const dryRun = flags['dry-run'] === true;
-    const targetExists = existsSync(targetPath);
+    const targetExists = targetPaths.some((candidate) => existsSync(candidate));
 
     if (dryRun) {
-      output({ ok: true, dryRun: true, sourcePath, targetPath, targetExists, wrote: false });
+      output({ ok: true, dryRun: true, sourcePath: sourcePaths[0], targetPath, targetExists, wrote: false });
       return;
     }
 
@@ -37,7 +42,9 @@ cmd(
     }
 
     mkdirSync(dirname(targetPath), { recursive: true });
-    copyFileSync(sourcePath, targetPath);
-    output({ ok: true, dryRun: false, sourcePath, targetPath, wrote: true });
+    for (let index = 0; index < sourcePaths.length; index += 1) {
+      copyFileSync(sourcePaths[index], targetPaths[index]);
+    }
+    output({ ok: true, dryRun: false, sourcePath: sourcePaths[0], targetPath, wrote: true });
   },
 );

package/src/cli/commands/nodes.ts

@@ -124,7 +124,6 @@ function summarizeNodeResult(node: Record<string, unknown>): Record<string, unkn
     ...(node.size !== undefined ? { size: node.size } : {}),
     ...(node.collapsed !== undefined ? { collapsed: node.collapsed } : {}),
     ...(node.pinned !== undefined ? { pinned: node.pinned } : {}),
-    ...(node.dockPosition !== undefined ? { dockPosition: node.dockPosition } : {}),
     ...(node.path !== undefined ? { path: node.path } : {}),
     ...(node.url !== undefined ? { url: node.url } : {}),
     ...(node.provenance !== undefined ? { provenance: node.provenance } : {}),
@@ -827,8 +826,6 @@ cmd(
     'pmx-canvas node update <node-id> --spec-file ./dashboard.json',
     'pmx-canvas node update <graph-id> --data-file ./metrics.json --chart-height 420',
     'pmx-canvas node update <node-id> --pinned true',
-    'pmx-canvas node update <node-id> --dock-position right',
-    'pmx-canvas node update <node-id> --dock-position none   # undock back to the canvas',
     'pmx-canvas node update <node-id> --lock-arrange',
     'pmx-canvas node update <node-id> --width 840 --full   # full node payload instead of the compact envelope',
   ],
@@ -910,25 +907,10 @@ cmd(
 
     if (pinned !== undefined) body.pinned = pinned;
 
-    // --dock-position left|right|none : dock a node into the top HUD or undock it.
-    // `none`/`null`/empty map to JS null (undock). Assigned with a !== undefined
-    // guard so the null survives JSON.stringify to the server (which accepts a
-    // top-level dockPosition: null). HTTP PATCH already supports this; this is the
-    // CLI path the report (#40) found missing.
-    const dockRaw = getStringFlag(flags, 'dock-position', 'dockPosition');
-    let dockPosition: 'left' | 'right' | null | undefined;
-    if (dockRaw !== undefined) {
-      const v = dockRaw.trim().toLowerCase();
-      if (v === 'left' || v === 'right') dockPosition = v;
-      else if (v === 'none' || v === 'null' || v === '') dockPosition = null;
-      else die(`Invalid --dock-position "${dockRaw}".`, 'Use left, right, or none (to undock).');
-    }
-    if (dockPosition !== undefined) body.dockPosition = dockPosition;
-
     if (Object.keys(body).length === 0) {
       die(
         'No updates specified',
-        'Use --title, --content, --x, --y, --width, --height, --strict-size, --pinned, --dock-position, trace fields, --lock-arrange, --unlock-arrange, or --stdin',
+        'Use --title, --content, --x, --y, --width, --height, --strict-size, --pinned, trace fields, --lock-arrange, --unlock-arrange, or --stdin',
       );
     }
 

package/src/cli/commands/pump.ts

@@ -0,0 +1,252 @@
+/**
+ * `pmx-canvas pump` — the generic reactive steering loop for hosts without a
+ * native adapter (Amp, Codex, any CLI agent). Long-polls the per-consumer
+ * delivery claim and hands each steer to a shell command; the command's exit
+ * code gates the per-consumer mark. This is the same design as the Copilot
+ * extension's delivery pump (send-then-mark, awaiting-mark memory, startup
+ * backlog watermark, old-server backoff) with the "send into the host" step
+ * generalized to "run your command".
+ *
+ * Safety: the steer text reaches the command as env (PMX_STEER_MESSAGE) and
+ * stdin — never spliced into the shell string — so hostile steer content
+ * cannot inject into the command line. `{message}` in the template expands to
+ * the SHELL VARIABLE reference "$PMX_STEER_MESSAGE" (quoted), not the text.
+ * On Windows that guarantee does not hold — cmd.exe expands `%VAR%` and then
+ * re-parses the result — so the placeholders are refused there and the command
+ * takes the message from stdin instead. See `renderExecTemplate`.
+ */
+import { spawn } from 'node:child_process';
+import { cmd, getBaseUrl, getStringFlag, invokeOperation, parseFlags, requireFlag } from '../shared.js';
+
+interface PendingSteer {
+  id: string;
+  message: string;
+  source?: string | null;
+  target?: string | null;
+  createdAt?: string | null;
+}
+
+async function claimPending(consumer: string, waitMs: number): Promise<{ pending: PendingSteer[]; tookMs: number }> {
+  const started = Date.now();
+  const url = `${getBaseUrl()}/api/canvas/ax/delivery/pending?consumer=${encodeURIComponent(consumer)}&limit=1&order=oldest${waitMs > 0 ? `&waitMs=${waitMs}` : ''}`;
+  const res = await fetch(url, { signal: AbortSignal.timeout(waitMs + 15_000) });
+  if (!res.ok) throw new Error(`pending claim failed: HTTP ${res.status}`);
+  const body = (await res.json()) as { pending?: PendingSteer[] };
+  return { pending: Array.isArray(body.pending) ? body.pending : [], tookMs: Date.now() - started };
+}
+
+async function markDelivered(id: string, consumer: string): Promise<boolean> {
+  const result = (await invokeOperation('ax.delivery.mark', { id, consumer })) as { delivered?: boolean };
+  return result.delivered === true;
+}
+
+/**
+ * Windows has no `sh`, so the exec ran nowhere there. cmd.exe can host the
+ * stdin pattern, but NOT the `{message}` / `{id}` placeholders: those expand to
+ * an env-var reference so hostile steer content is never spliced into the
+ * command string, and cmd.exe expands `%VAR%` before re-parsing — a message
+ * containing `& del …` would run. Refuse the placeholders there instead of
+ * silently reintroducing the injection the substitution exists to prevent.
+ */
+export function renderExecTemplate(template: string, windows = process.platform === 'win32'): string {
+  if (windows) {
+    if (template.includes('{message}') || template.includes('{id}')) {
+      throw new Error(
+        'pmx-canvas pump: {message} and {id} are not supported on Windows — cmd.exe re-parses expanded variables, so a steer could inject commands. Read the message from stdin instead (the exec receives it), or use the PMX_STEER_MESSAGE / PMX_STEER_ID environment variables inside your own script.',
+      );
+    }
+    return template;
+  }
+  return template.replaceAll('{message}', '"$PMX_STEER_MESSAGE"').replaceAll('{id}', '"$PMX_STEER_ID"');
+}
+
+function runExec(template: string, steer: PendingSteer, consumer: string): Promise<number> {
+  const rendered = renderExecTemplate(template);
+  return new Promise((resolve) => {
+    // `shell: true` picks sh on POSIX and ComSpec/cmd.exe on Windows, and sets
+    // windowsVerbatimArguments itself — hand-rolling the cmd.exe form escaped
+    // the quotes inside the command, so `bun "C:\path\x.mjs"` arrived as
+    // `""C:\path\x.mjs""`. Let Node own the platform quoting.
+    const child = spawn(rendered, {
+      shell: true,
+      stdio: ['pipe', 'inherit', 'inherit'],
+      env: {
+        ...process.env,
+        PMX_STEER_MESSAGE: steer.message,
+        PMX_STEER_ID: steer.id,
+        PMX_STEER_SOURCE: steer.source ?? '',
+        // Delivery envelope (round-2 review): the command can tell the host
+        // WHO steered, whether it was addressed or a broadcast, and how old
+        // the steer is — without re-querying the board.
+        PMX_STEER_TARGET: steer.target ?? 'ALL',
+        PMX_STEER_CREATED_AT: steer.createdAt ?? '',
+        PMX_STEER_CONSUMER: consumer,
+      },
+    });
+    child.stdin.write(steer.message);
+    child.stdin.end();
+    child.on('close', (code) => resolve(code ?? 1));
+    child.on('error', () => resolve(1));
+  });
+}
+
+async function setPresence(consumer: string, label: string, parent: string | null, patch: Record<string, unknown>) {
+  try {
+    await invokeOperation('ax.presence.set', {
+      source: 'sdk',
+      agentId: consumer,
+      label,
+      ...(parent ? { parentAgentId: parent } : {}),
+      ...patch,
+    });
+  } catch {
+    // presence is best-effort — the pump must survive a rolling daemon
+  }
+}
+
+/**
+ * Settle back to idle ONLY when the visible phase is still the pump's own
+ * `tooling` marker. The host the pump feeds may have set a richer explicit
+ * phase (thinking, waiting-approval) while handling the steer — an
+ * unconditional idle stomped it and active work read as Idle (0.5.0
+ * readiness, Copilot finding).
+ */
+async function settlePresence(consumer: string, label: string, parent: string | null): Promise<void> {
+  try {
+    const res = await fetch(`${getBaseUrl()}/api/canvas/ax/presence`, { signal: AbortSignal.timeout(5_000) });
+    if (res.ok) {
+      const body = (await res.json()) as {
+        presences?: Array<{ sessionId?: string; phase?: string; detail?: string | null }>;
+      };
+      const own = body.presences?.find((p) => p.sessionId === consumer);
+      const ownToolingMarker = own?.phase === 'tooling' && (own.detail ?? '').startsWith('steer: ');
+      if (own && !ownToolingMarker && own.phase !== 'idle') return; // richer phase belongs to the host
+    }
+  } catch {
+    // presence read failed — fall through and settle; better idle than stuck tooling
+  }
+  await setPresence(consumer, label, parent, { phase: 'idle', detail: null });
+}
+
+cmd(
+  'pump',
+  'Reactive steering loop for CLI agents (Amp, Codex CLI): long-poll claims for a consumer and run a command per steer',
+  [
+    `pmx-canvas pump --consumer codex-cli --exec 'codex exec --full-auto {message}'`,
+    `pmx-canvas pump --consumer amp --exec 'amp -x {message}' --parent claude-code`,
+    `pmx-canvas pump --consumer testbot --exec 'cat' --once`,
+  ],
+  async (args) => {
+    const { flags } = parseFlags(args, { boolFlags: ['once'] });
+    const consumer = requireFlag(
+      flags,
+      'consumer',
+      `pmx-canvas pump --consumer <key> --exec '<command with {message}>'`,
+    );
+    const execTemplate = requireFlag(
+      flags,
+      'exec',
+      `pmx-canvas pump --consumer <key> --exec '<command with {message}>'`,
+    );
+    const once = flags.once === true;
+    const waitMsRaw = Number(getStringFlag(flags, 'wait-ms') ?? 120_000);
+    const waitMs = Number.isFinite(waitMsRaw) && waitMsRaw >= 0 ? Math.min(waitMsRaw, 120_000) : 120_000;
+    const label = getStringFlag(flags, 'label') ?? consumer;
+    const parent = getStringFlag(flags, 'parent') ?? null;
+    const deliverBacklog = getStringFlag(flags, 'backlog') === 'deliver';
+    const retryDelayRaw = Number(getStringFlag(flags, 'retry-delay-ms') ?? 5_000);
+    const retryDelayMs = Number.isFinite(retryDelayRaw) && retryDelayRaw >= 0 ? retryDelayRaw : 5_000;
+
+    // Startup watermark: steers queued BEFORE the pump existed are history,
+    // not instructions — mark them silently unless --backlog=deliver.
+    if (!deliverBacklog) {
+      const { pending } = await claimPending(consumer, 0);
+      for (const steer of pending) await markDelivered(steer.id, consumer);
+      let swept = pending.length;
+      // pending is capped at limit=1 — drain the rest.
+      while (swept > 0) {
+        const next = await claimPending(consumer, 0);
+        if (next.pending.length === 0) break;
+        for (const steer of next.pending) await markDelivered(steer.id, consumer);
+        swept = next.pending.length;
+      }
+    }
+
+    // Park via the guard: a pump RESTART while its host is mid-work must not
+    // knock an explicit phase back to idle either.
+    await settlePresence(consumer, label, parent);
+    console.log(`[pump] ${consumer} parked on ${getBaseUrl()} (waitMs=${waitMs}${once ? ', once' : ''})`);
+
+    const awaitingMark = new Set<string>();
+    const failures = new Map<string, number>();
+    let stopped = false;
+    let fastEmpties = 0;
+    process.on('SIGINT', () => {
+      stopped = true;
+      console.log('[pump] stopping');
+      process.exit(0);
+    });
+
+    while (!stopped) {
+      let pending: PendingSteer[];
+      let tookMs: number;
+      try {
+        ({ pending, tookMs } = await claimPending(consumer, waitMs));
+      } catch (error) {
+        // Daemon roll or network blip: back off and re-park, never exit.
+        console.error(`[pump] claim retrying: ${error instanceof Error ? error.message : String(error)}`);
+        await new Promise((resolve) => setTimeout(resolve, 10_000));
+        continue;
+      }
+      if (pending.length === 0) {
+        // Old-server guard: a 0.4.8 daemon ignores waitMs, returning instantly —
+        // without this the loop would spin hot.
+        fastEmpties = tookMs < 1_000 ? fastEmpties + 1 : 0;
+        if (fastEmpties >= 2) await new Promise((resolve) => setTimeout(resolve, 10_000));
+        continue;
+      }
+      fastEmpties = 0;
+      const steer = pending[0]!;
+
+      // Awaiting-mark memory: the exec already ran for this id — a failed mark
+      // must not re-run the command (the duplicate-send race).
+      if (awaitingMark.has(steer.id)) {
+        if (await markDelivered(steer.id, consumer)) awaitingMark.delete(steer.id);
+        continue;
+      }
+
+      await setPresence(consumer, label, parent, { phase: 'tooling', detail: `steer: ${steer.message.slice(0, 60)}` });
+      const age = steer.createdAt
+        ? `, age ${Math.max(0, Math.round((Date.now() - Date.parse(steer.createdAt)) / 1000))}s`
+        : '';
+      console.log(
+        `[pump] steer ${steer.id} from ${steer.source ?? '?'} → ${steer.target ?? 'ALL'}${age}: ${steer.message.slice(0, 120)}`,
+      );
+      const code = await runExec(execTemplate, steer, consumer);
+      if (code === 0) {
+        awaitingMark.add(steer.id);
+        if (await markDelivered(steer.id, consumer)) awaitingMark.delete(steer.id);
+        failures.delete(steer.id);
+        await settlePresence(consumer, label, parent);
+        if (once) return;
+      } else {
+        const count = (failures.get(steer.id) ?? 0) + 1;
+        failures.set(steer.id, count);
+        console.error(`[pump] exec exited ${code} for ${steer.id} (attempt ${count}/3)`);
+        if (count >= 3) {
+          // A failed host injection is still pending work; only successful execs may mark delivery.
+          failures.delete(steer.id);
+          console.error(`[pump] stopped after three failures for ${steer.id} — steer remains pending`);
+          await setPresence(consumer, label, parent, {
+            phase: 'idle',
+            detail: `delivery failed: ${steer.id} remains pending`,
+          });
+          throw new Error(`Pump delivery failed three times for ${steer.id}; steer remains pending.`);
+        } else {
+          await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+        }
+        await settlePresence(consumer, label, parent);
+      }
+    }
+  },
+);

package/src/cli/index.ts

@@ -8,7 +8,6 @@ import { runAgentCli } from './agent.js';
 import { isCanvasTheme } from '../shared/themes.js';
 import { createCanvas } from '../server/index.js';
 import { seedDemoCanvas } from '../server/demo.js';
-import { ensureDefaultDockedNodes } from '../server/server.js';
 
 const args = process.argv.slice(2);
 
@@ -45,6 +44,7 @@ const AGENT_COMMANDS = new Set([
   'screenshot',
   'pin',
   'ax',
+  'pump',
   'undo',
   'redo',
   'history',
@@ -404,10 +404,6 @@ Examples:
 
   if (demo && canvas.getLayout().nodes.length === 0) {
     seedDemoCanvas();
-  } else if (!demo) {
-    // First-run only: dock a status (left) + context (right) widget by default so
-    // a fresh canvas isn't empty. No-op once the workspace has saved state.
-    ensureDefaultDockedNodes();
   }
 
   console.log(`\n  PMX Canvas running at http://localhost:${canvas.port}`);

package/src/cli/shared.ts

@@ -118,7 +118,7 @@ function output(data: unknown): void {
 async function invokeOperation(name: string, input: Record<string, unknown>): Promise<unknown> {
   const base = getBaseUrl();
   try {
-    return await new HttpOperationInvoker(base).invoke(name, input);
+    return await new HttpOperationInvoker(base, 'cli').invoke(name, input);
   } catch (error) {
     if (error instanceof OperationError) {
       die(error.message);