pmx-canvas 0.4.3 → 0.4.5

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

@@ -0,0 +1,82 @@
+---
+name: pmx-canvas-orchestration
+description: Choreography for running multi-agent orchestration ON a PMX Canvas board — the agent host (Claude Code, Copilot, Codex) executes; the canvas is the shared graph, state, human-steering surface, and audit trail. Load this in the ORCHESTRATOR session and in EVERY subagent that touches the board.
+---
+
+# PMX Canvas Orchestration
+
+The division of labor is fixed: **the agent host runs the loop** (spawning, scheduling,
+fan-out/join, retries); **the canvas is the graph** (persistent shared state, the live visual,
+human gates and steering, the timeline). The canvas never executes anything. This skill is the
+choreography that makes that split work — both the orchestrator and every subagent must follow
+it, or the board silently diverges from reality.
+
+## Identity
+
+- Every participant picks a stable `agentId` (kebab-case role name: `orchestrator`,
+  `researcher`, `impl-auth`, …) and passes it on EVERY AX write that supports it (work items,
+  timeline events, steering). `source` stays the host label (`mcp`, `cli`, `amp`, …);
+  `agentId` is who within the host.
+- One canvas node + one work item per subagent, created BY THE ORCHESTRATOR at spawn time
+  (title = the agentId). The subagent updates its own work item; it never creates its own
+  identity row.
+- Tag every run: put the same `data.runId` on every NODE (work items carry no free-form data —
+  their run scoping comes from the run-prefixed `agentId`, e.g. `run7:impl-auth`), so
+  consecutive orchestrations don't interleave in the bounded timeline.
+
+## Graph semantics
+
+- `flow` edges = planned sequence. `depends-on` edges = blocking dependency (the visual DAG).
+  `relation`/`references` = context only — never scheduling.
+- The orchestrator owns the topology: it creates all nodes and edges up front with one
+  `canvas_batch`, then only mutates statuses. Subagents mutate their OWN node/work item only.
+- The host's real execution order is authoritative. When the host reorders or skips, the
+  orchestrator updates the edges — a board that contradicts execution is worse than no board.
+
+## Status discipline
+
+- Work-item status is the single source of step state: `todo → in-progress → done`
+  (or `blocked` / `cancelled`). Update the work item FIRST; linked nodes mirror the status automatically
+  (0.4.5+) — do not hand-edit a status node to fake progress.
+- Signal `canvas_intent` before each phase of visible board mutation (the auto-ghost floor
+  covers forgotten signals, but only an explicit signal gives the human a veto window and your
+  reasoning).
+
+## Gates and human input
+
+- ALL approval gates, elicitations, and mode requests are created and awaited by the
+  ORCHESTRATOR, never by subagents. `canvas_ax_gate { action: "await" }` blocks at most ~120s
+  per call — the orchestrator re-awaits in a loop; a subagent burning turns on a gate wait is
+  a bug.
+- A pending gate is NOT approval. Execution-class actions stay blocked until the gate is
+  explicitly `approved`.
+
+## Steering
+
+- Humans steer through the board; agents MUST poll for it — MCP notifications cannot wake a
+  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.
+- 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`.
+- 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.
+
+## Run lifecycle
+
+1. Orchestrator: snapshot the board (`canvas_snapshot save`) before the run.
+2. Orchestrator: one `canvas_batch` creating the run's nodes + edges (+ `data.runId`), one
+   work item per step/subagent, intent-signaled.
+3. Spawn subagents; each loads this skill, learns its `agentId`, node id, and work-item id
+   from the spawn prompt.
+4. Subagents: flip work item to `in-progress`, do the work, attach evidence
+   (`canvas_ax_timeline { action: "add-evidence" }`), flip to `done`, poll steering between
+   steps.
+5. Orchestrator: join on host-side completion (the host knows the real DAG), resolve gates,
+   record a final timeline event, and validate the board (`canvas_query { action: "validate" }`).
+6. On abort/failure: leave work items in their true state (`blocked` + a timeline failure
+   event), never green-wash.
+
+The acceptance bar: a human watching the board and a human reading the host transcript must
+see the same story.

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

@@ -74,6 +74,10 @@ Prefer extending the existing suites before inventing a one-off script.
 - MCP harnesses using the official SDK must wind down BOTH halves: call `client.close()` AND
   `transport.close()` on the `StdioClientTransport`. Closing only the client leaves the spawned
   stdio server process alive after the test exits (0.4.0 cycle finding)
+- Before a version-test cycle, run `pmx-canvas skills sync --check` in the consumer workspace —
+  exit 1 means the installed skill copies are stale against the package; run
+  `pmx-canvas skills sync --yes` to refresh them (whole trees, whatever agent layout owns them) before
+  trusting skill-guided results
 
 ## Layout And Embedded Content Checks
 

package/src/cli/agent.ts

@@ -31,6 +31,7 @@ import './commands/ax.js';
 import './commands/webview.js';
 import './commands/apps.js';
 import './commands/copilot.js';
+import './commands/skills.js';
 
 // Re-exported for existing importers (tests import it from this module).
 export { extractGlobalTargetFlags };

package/src/cli/commands/skills.ts

@@ -0,0 +1,183 @@
+// Skill mirror commands: skills sync (+ --check drift detection).
+//
+// Every release cycle found installed skill copies stale against the package,
+// and testers hand-synced complete trees before results were trustworthy.
+// This command automates that WITHOUT assuming any agent layout: it discovers
+// the pmx-canvas skill copies already installed in the workspace (any
+// `<dir>/skills/<skill-name>/SKILL.md`, whatever agent owns `<dir>`) and
+// compares/replaces whole trees — references, evals, fixtures included. It
+// never creates a mirror where none is installed.
+
+import { cpSync, existsSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cmd, output, parseFlags, showCommandHelp } from '../shared.js';
+
+export const BUNDLED_SKILLS = ['pmx-canvas', 'pmx-canvas-testing', 'pmx-canvas-orchestration'] as const;
+
+function listFilesRecursive(root: string, prefix = ''): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...listFilesRecursive(join(root, entry.name), rel));
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out.sort();
+}
+
+export interface SkillTreeComparison {
+  inSync: boolean;
+  /** Files present in the package tree but missing or different in the mirror. */
+  missingOrDifferent: string[];
+  /** Files present in the mirror but not in the package tree. */
+  extra: string[];
+}
+
+export function compareSkillTrees(sourceRoot: string, targetRoot: string): SkillTreeComparison {
+  const sourceFiles = listFilesRecursive(sourceRoot);
+  const targetFiles = listFilesRecursive(targetRoot);
+  const targetSet = new Set(targetFiles);
+  const missingOrDifferent: string[] = [];
+  for (const rel of sourceFiles) {
+    if (!targetSet.has(rel)) {
+      missingOrDifferent.push(rel);
+      continue;
+    }
+    if (!readFileSync(join(sourceRoot, rel)).equals(readFileSync(join(targetRoot, rel)))) {
+      missingOrDifferent.push(rel);
+    }
+  }
+  const sourceSet = new Set(sourceFiles);
+  const extra = targetFiles.filter((rel) => !sourceSet.has(rel));
+  return { inSync: missingOrDifferent.length === 0 && extra.length === 0, missingOrDifferent, extra };
+}
+
+export interface InstalledSkillMirror {
+  /** The directory that owns the skills/ folder (e.g. ".codex", ".github", or any agent dir). */
+  host: string;
+  skill: string;
+  dir: string;
+}
+
+/**
+ * Find the bundled skills' installed copies in this workspace: any immediate
+ * child directory holding `skills/<skill>/SKILL.md`, regardless of which agent
+ * that directory belongs to. The package's own skills source is excluded so
+ * running inside the pmx-canvas checkout never compares a tree to itself.
+ */
+export function discoverInstalledSkillMirrors(
+  workspaceRoot: string,
+  packageSkillsRoot: string,
+): InstalledSkillMirror[] {
+  const found: InstalledSkillMirror[] = [];
+  for (const entry of readdirSync(workspaceRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === 'node_modules') continue;
+    const skillsDir = join(workspaceRoot, entry.name, 'skills');
+    if (!existsSync(skillsDir)) continue;
+    for (const skill of BUNDLED_SKILLS) {
+      const dir = join(skillsDir, skill);
+      if (!existsSync(join(dir, 'SKILL.md'))) continue;
+      if (resolve(dir) === resolve(join(packageSkillsRoot, skill))) continue;
+      found.push({ host: entry.name, skill, dir });
+    }
+  }
+  return found;
+}
+
+export interface SkillMirrorResult {
+  host: string;
+  skill: string;
+  dir: string;
+  status: 'in-sync' | 'synced' | 'drifted' | 'skipped-not-a-package-copy';
+  missingOrDifferent?: string[];
+  extra?: string[];
+}
+
+/**
+ * A mirror is only replaceable when its SKILL.md frontmatter `name:` matches
+ * the bundled skill it sits under. A user's own skill living in a same-named
+ * directory (different frontmatter identity) must never be deleted — these
+ * trees are typically gitignored, so a wrong replace is unrecoverable.
+ */
+export function mirrorIdentityMatches(mirrorDir: string, skill: string): boolean {
+  try {
+    const head = readFileSync(join(mirrorDir, 'SKILL.md'), 'utf-8').slice(0, 2000);
+    const match = /^name:\s*(\S+)\s*$/m.exec(head);
+    return match?.[1] === skill;
+  } catch {
+    return false;
+  }
+}
+
+/** Sync (or, with check=true, only compare) every INSTALLED mirror against the package trees. */
+export function syncInstalledSkillMirrors(
+  packageSkillsRoot: string,
+  workspaceRoot: string,
+  opts: { check: boolean },
+): SkillMirrorResult[] {
+  const results: SkillMirrorResult[] = [];
+  for (const mirror of discoverInstalledSkillMirrors(workspaceRoot, packageSkillsRoot)) {
+    const source = join(packageSkillsRoot, mirror.skill);
+    if (!mirrorIdentityMatches(mirror.dir, mirror.skill)) {
+      results.push({ ...mirror, status: 'skipped-not-a-package-copy' });
+      continue;
+    }
+    const cmp = compareSkillTrees(source, mirror.dir);
+    if (cmp.inSync) {
+      results.push({ ...mirror, status: 'in-sync' });
+      continue;
+    }
+    if (opts.check) {
+      results.push({ ...mirror, status: 'drifted', ...cmp });
+      continue;
+    }
+    // Full-tree replace: a copy-over would leave deleted package files behind
+    // in the mirror, which is exactly the drift class release audits kept
+    // hitting even when SKILL.md hashes matched. Stage the complete new tree
+    // BESIDE the mirror first, so a crash between the rm and the rename leaves
+    // the staged copy on disk as recovery instead of losing the install.
+    const staging = `${mirror.dir}.pmx-sync-staging`;
+    rmSync(staging, { recursive: true, force: true });
+    cpSync(source, staging, { recursive: true });
+    rmSync(mirror.dir, { recursive: true, force: true });
+    renameSync(staging, mirror.dir);
+    results.push({ ...mirror, status: 'synced' });
+  }
+  return results;
+}
+
+// ── skills sync ──────────────────────────────────────────────
+cmd(
+  'skills sync',
+  'Refresh the pmx-canvas skill copies already installed in this workspace (any agent layout)',
+  ['pmx-canvas skills sync --yes', 'pmx-canvas skills sync --check'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('skills sync');
+
+    const packageSkillsRoot = fileURLToPath(new URL('../../../skills', import.meta.url));
+    // Replacing a mirror deletes a whole installed tree — destructive, so it
+    // follows the CLI's `--yes` contract. Without --yes (or with --check) the
+    // command only reports drift; exit 1 signals stale either way.
+    const check = flags.check === true || flags.yes !== true;
+    const results = syncInstalledSkillMirrors(packageSkillsRoot, process.cwd(), { check });
+
+    const drifted = results.filter((r) => r.status === 'drifted');
+    const ok = drifted.length === 0;
+    output({
+      ok,
+      check,
+      packageSkillsRoot,
+      mirrorsFound: results.length,
+      ...(results.length === 0 ? { note: 'No installed pmx-canvas skill copies found in this workspace.' } : {}),
+      ...(drifted.length > 0 && flags.yes !== true
+        ? { note: 'Drift detected. Re-run with --yes to replace the drifted trees from the installed package.' }
+        : {}),
+      results,
+    });
+    if (!ok) process.exitCode = 1;
+  },
+);

package/src/cli/index.ts

@@ -66,6 +66,7 @@ const AGENT_COMMANDS = new Set([
   'validate',
   'serve',
   'copilot',
+  'skills',
 ]);
 
 const firstArg = args[0] ?? '';
@@ -165,7 +166,13 @@ const serveSubcommand = firstArg === 'serve' ? (args[1] ?? '') : '';
 
 if (firstArg === 'serve' && (serveSubcommand === 'status' || serveSubcommand === 'stop')) {
   const port = parseInt(
-    readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? '4313',
+    readOption('port') ??
+      process.env.PMX_WEB_CANVAS_PORT ??
+      process.env.PMX_CANVAS_PORT ??
+      // Amp orbs assign the portal port via $PORT; honored only under AMP_ORB
+      // so a stray PORT in normal shells never shifts the default.
+      (process.env.AMP_ORB ? process.env.PORT || undefined : undefined) ??
+      '4313',
     10,
   );
   const daemonLogFile = resolve(readOption('log-file') ?? `.pmx-canvas/daemon-${port}.log`);
@@ -213,7 +220,13 @@ if (AGENT_COMMANDS.has(routedCommand) && routedCommand !== 'serve') {
 } else {
   // "serve" is also accessible via flags (backward compat)
   const port = parseInt(
-    readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? '4313',
+    readOption('port') ??
+      process.env.PMX_WEB_CANVAS_PORT ??
+      process.env.PMX_CANVAS_PORT ??
+      // Amp orbs assign the portal port via $PORT; honored only under AMP_ORB
+      // so a stray PORT in normal shells never shifts the default.
+      (process.env.AMP_ORB ? process.env.PORT || undefined : undefined) ??
+      '4313',
     10,
   );
   const demo = hasFlag('demo');
@@ -253,7 +266,7 @@ Server options:
   --log-file=PATH  Daemon log file (default: ./.pmx-canvas/daemon-${port}.log)
   --pid-file=PATH  Optional daemon PID file (default: ./.pmx-canvas/daemon-${port}.pid)
   --wait-ms=MS   Health-check wait budget for daemon mode (default: 10000)
-  --theme=THEME  Theme: dark (default), light, high-contrast, midnight, sepia, arctic, ember, forest
+  --theme=THEME  Theme: dark (default), light, high-contrast, midnight, sepia, arctic, ember, forest, volt
   --webview-automation        Start a headless Bun.WebView automation session for /workbench
   --webview-backend=BACKEND   Bun.WebView backend: chrome or webkit
   --webview-width=PX          Automation WebView width (default: 1280)
@@ -343,6 +356,7 @@ Examples:
   pmx-canvas watch --events context-pin,move-end              Watch semantic deltas
   pmx-canvas clear --dry-run                                  Preview destructive op
   pmx-canvas copilot install-extension --dry-run             Preview Copilot adapter install
+  pmx-canvas skills sync --yes                               Refresh installed pmx-canvas skill copies in this workspace (--check to detect drift)
 `);
     process.exit(0);
   }

package/src/cli/shared.ts

@@ -163,6 +163,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
     'permissions',
     'files',
     'ui-prompts',
+    'check',
   ]);
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];

package/src/client/canvas/CanvasNode.tsx

@@ -140,7 +140,15 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
     requestAnimationFrame(() => renameRef.current?.focus());
   }, []);
 
-  const title = (node.data.title as string) || TYPE_LABELS[node.type];
+  const title =
+    (node.data.title as string) ||
+    // Untitled file nodes (created before titles were synthesized server-side)
+    // still show their filename instead of a bare type label.
+    (node.type === 'file'
+      ? // Separator-agnostic: node paths are OS-native (backslashes on Windows).
+        (((node.data.path as string) || (node.data.content as string) || '').split(/[\\/]/).pop() ?? '')
+      : '') ||
+    TYPE_LABELS[node.type];
 
   const commitRename = useCallback(
     (value: string) => {
@@ -254,6 +262,9 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
           })()}
         </span>
         <span class="node-type-badge">{TYPE_LABELS[node.type]}</span>
+        {typeof node.data.axWorkStatus === 'string' && (
+          <span class={`node-ax-status node-ax-status-${node.data.axWorkStatus}`}>{node.data.axWorkStatus}</span>
+        )}
         {renaming ? (
           <input
             ref={renameRef}

package/src/client/canvas/IntentLayer.tsx

@@ -59,8 +59,10 @@ function center(rect: Rect): { x: number; y: number } {
 }
 
 function ghostOpacity(intent: ClientIntent): number {
-  if (typeof intent.confidence !== 'number') return 0.82;
-  return 0.4 + Math.max(0, Math.min(1, intent.confidence)) * 0.55;
+  const base = typeof intent.confidence !== 'number' ? 0.82 : 0.4 + Math.max(0, Math.min(1, intent.confidence)) * 0.55;
+  // Auto-ghosts (server-synthesized, no deliberate signal) read lighter than
+  // an explicit canvas_intent so the two are visually distinguishable.
+  return intent.auto ? base * 0.62 : base;
 }
 
 function bezierPath(a: { x: number; y: number }, b: { x: number; y: number }): string {
@@ -89,7 +91,7 @@ function GhostInfo({ intent }: { intent: ClientIntent }) {
         )}
         <span class="intent-chip-label">{label}</span>
         {confidencePct && <span class="intent-confidence">{confidencePct}</span>}
-        {intent.phase === 'forming' && (
+        {intent.phase === 'forming' && !intent.auto && (
           <button
             type="button"
             class="intent-veto"
@@ -114,7 +116,7 @@ function GhostBox({ intent, rect }: { intent: ClientIntent; rect: Rect }) {
   const typeLabel = isKnownNodeType(intent.nodeType) ? TYPE_LABELS[intent.nodeType] : 'Node';
   return (
     <div
-      class={`intent-ghost intent-ghost-box is-${intent.phase}`}
+      class={`intent-ghost intent-ghost-box is-${intent.phase}${intent.auto ? ' is-auto' : ''}`}
       data-intent-id={intent.id}
       style={{
         left: `${rect.left}px`,
@@ -138,7 +140,7 @@ function GhostBox({ intent, rect }: { intent: ClientIntent; rect: Rect }) {
 function GhostOverlay({ intent, rect, variant }: { intent: ClientIntent; rect: Rect; variant: 'remove' | 'edit' }) {
   return (
     <div
-      class={`intent-ghost intent-ghost-${variant} is-${intent.phase}`}
+      class={`intent-ghost intent-ghost-${variant} is-${intent.phase}${intent.auto ? ' is-auto' : ''}`}
       data-intent-id={intent.id}
       style={{
         left: `${rect.left}px`,
@@ -199,7 +201,7 @@ function renderGhost(intent: ClientIntent) {
       return (
         <div
           key={intent.id}
-          class={`intent-ghost intent-ghost-connect is-${intent.phase}`}
+          class={`intent-ghost intent-ghost-connect is-${intent.phase}${intent.auto ? ' is-auto' : ''}`}
           data-intent-id={intent.id}
           style={{
             left: `${rect.left}px`,

package/src/client/state/intent-bridge.ts

@@ -2,9 +2,18 @@ function logRequestError(action: string, error: unknown): void {
   console.error(`[intent-bridge] ${action} failed`, error);
 }
 
+/**
+ * Every workbench-originated request carries this marker so the server never
+ * synthesizes an auto-ghost for it — a human dragging or editing in the
+ * browser is not agent activity (the ghost cursor shows AGENT moves).
+ */
+function withWorkbenchMarker(init?: RequestInit): RequestInit {
+  return { ...init, headers: { ...(init?.headers as Record<string, string> | undefined), 'X-PMX-Workbench': '1' } };
+}
+
 async function requestJson<T>(action: string, url: string, fallback: T, init?: RequestInit): Promise<T> {
   try {
-    const res = await fetch(url, init);
+    const res = await fetch(url, withWorkbenchMarker(init));
     return (await res.json()) as T;
   } catch (error) {
     logRequestError(action, error);
@@ -14,7 +23,7 @@ async function requestJson<T>(action: string, url: string, fallback: T, init?: R
 
 async function requestOk(action: string, url: string, init?: RequestInit): Promise<{ ok: boolean }> {
   try {
-    const res = await fetch(url, init);
+    const res = await fetch(url, withWorkbenchMarker(init));
     return { ok: res.ok };
   } catch (error) {
     logRequestError(action, error);
@@ -24,7 +33,7 @@ async function requestOk(action: string, url: string, init?: RequestInit): Promi
 
 async function requestBestEffort(action: string, url: string, init?: RequestInit): Promise<void> {
   try {
-    await fetch(url, init);
+    await fetch(url, withWorkbenchMarker(init));
   } catch (error) {
     logRequestError(action, error);
   }

package/src/client/state/intent-store.ts

@@ -23,8 +23,16 @@ export const hoveredIntentId = signal<string | null>(null);
 
 const SETTLE_MS = 480;
 const DISSOLVE_MS = 320;
+/**
+ * Minimum time a ghost stays in its forming state before a settle/dissolve
+ * plays. Fast agents (and every server auto-ghost) signal and settle within
+ * milliseconds — without this floor, correct ghost usage is imperceptible.
+ */
+export const MIN_FORMING_MS = 650;
 
 const exitTimers = new Map<string, ReturnType<typeof setTimeout>>();
+const phaseDelayTimers = new Map<string, ReturnType<typeof setTimeout>>();
+const formedAt = new Map<string, number>();
 let pruneTimer: ReturnType<typeof setInterval> | null = null;
 
 function writeIntents(next: Map<string, ClientIntent>): void {
@@ -40,9 +48,19 @@ function clearExitTimer(id: string): void {
   }
 }
 
+function clearPhaseDelay(id: string): void {
+  const timer = phaseDelayTimers.get(id);
+  if (timer) {
+    clearTimeout(timer);
+    phaseDelayTimers.delete(id);
+  }
+}
+
 /** A live `ax-intent` frame: (re)place the ghost in its forming state. */
 export function upsertIntent(intent: PmxAxIntent): void {
   clearExitTimer(intent.id);
+  clearPhaseDelay(intent.id);
+  if (!intents.value.has(intent.id)) formedAt.set(intent.id, Date.now());
   const next = new Map(intents.value);
   next.set(intent.id, { ...intent, phase: 'forming' });
   writeIntents(next);
@@ -50,6 +68,8 @@ export function upsertIntent(intent: PmxAxIntent): void {
 
 export function removeIntent(id: string): void {
   clearExitTimer(id);
+  clearPhaseDelay(id);
+  formedAt.delete(id);
   if (!intents.value.has(id)) return;
   const next = new Map(intents.value);
   next.delete(id);
@@ -69,19 +89,44 @@ function setPhase(id: string, phase: IntentPhase, ms: number, settledNodeId?: st
   );
 }
 
+/**
+ * Minimum-dwell wrapper: when a settle/dissolve arrives before the ghost has
+ * been visible for MIN_FORMING_MS, hold the forming state until the floor
+ * elapses, then play the exit phase.
+ */
+function setPhaseAfterDwell(id: string, phase: IntentPhase, ms: number, settledNodeId?: string): void {
+  clearPhaseDelay(id);
+  const elapsed = Date.now() - (formedAt.get(id) ?? 0);
+  const delay = Math.max(0, MIN_FORMING_MS - elapsed);
+  if (delay === 0) {
+    setPhase(id, phase, ms, settledNodeId);
+    return;
+  }
+  phaseDelayTimers.set(
+    id,
+    setTimeout(() => {
+      phaseDelayTimers.delete(id);
+      setPhase(id, phase, ms, settledNodeId);
+    }, delay),
+  );
+}
+
 /** Resolve a ghost into a real node — the settle morph, then removal. */
 export function settleIntent(id: string, settledNodeId?: string): void {
-  setPhase(id, 'settling', SETTLE_MS, settledNodeId);
+  setPhaseAfterDwell(id, 'settling', SETTLE_MS, settledNodeId);
 }
 
 /** Dissolve a ghost (expired / vetoed / evicted / abandoned), then remove it. */
 export function dissolveIntent(id: string): void {
-  setPhase(id, 'dissolving', DISSOLVE_MS);
+  setPhaseAfterDwell(id, 'dissolving', DISSOLVE_MS);
 }
 
 export function resetIntents(): void {
   for (const timer of exitTimers.values()) clearTimeout(timer);
   exitTimers.clear();
+  for (const timer of phaseDelayTimers.values()) clearTimeout(timer);
+  phaseDelayTimers.clear();
+  formedAt.clear();
   if (pruneTimer) {
     clearInterval(pruneTimer);
     pruneTimer = null;

package/src/client/state/sse-bridge.ts

@@ -57,10 +57,17 @@ let pollSeq: number | null = null;
 let pollGeneration = 0;
 let sseFirstEventWatchdog: ReturnType<typeof setTimeout> | null = null;
 
-function forcedTransport(): 'poll' | 'sse' | null {
-  if (typeof location === 'undefined') return null;
+export function forcedTransport(): 'poll' | 'sse' | null {
+  if (typeof location === 'undefined' || typeof window === 'undefined') return null;
   const value = new URLSearchParams(location.search).get('transport');
-  return value === 'poll' || value === 'sse' ? value : null;
+  if (value === 'poll' || value === 'sse') return value;
+  // Amp orbs: the portal proxy buffers SSE, so auto mode burns the 3s
+  // watchdog before falling back — and on slow proxy days that trips the
+  // boot modal. The server stamps the orb flag into the page (canvasSpaHtml);
+  // go straight to the transport that works there. `?transport=sse` above
+  // still overrides for diagnosis.
+  if ((window as Window & { __PMX_AMP_ORB?: unknown }).__PMX_AMP_ORB === true) return 'poll';
+  return null;
 }
 
 // Maps responseNodeId → thread prompt node ID so response deltas/completions
@@ -1124,6 +1131,10 @@ export function connectSSE(): () => void {
       sseFirstEventWatchdog = null;
       if (gotFirstEvent || eventSource !== source) return;
       console.warn('[sse-bridge] No SSE event within watchdog window — switching to polling transport.');
+      // Give the bootstrap card a fresh deadline for the fallback transport so
+      // the "did not finish booting" modal doesn't fire while polling is
+      // already recovering the boot (the inline bootstrap script listens).
+      window.dispatchEvent(new Event('pmx-canvas-boot-extend'));
       source.close();
       eventSource = null;
       startPollingTransport();