pmx-canvas 0.3.0 → 0.3.2

package/dist/types/cli/agent.d.ts

@@ -10,4 +10,12 @@
  * - Idempotent operations where possible
  * - --yes for destructive actions, --dry-run for preview
  */
-export declare function runAgentCli(args: string[]): Promise<void>;
+/**
+ * Extract the global `--port <n>` / `--server-url <url>` flags (any position,
+ * `=` or space-separated value) and set the invocation's target override.
+ * Returns the remaining args for command dispatch. Invalid values are a loud
+ * `die` — never a silent fallback to the default port. `--server-url` wins
+ * over `--port` when both are given.
+ */
+export declare function extractGlobalTargetFlags(args: string[]): string[];
+export declare function runAgentCli(rawArgs: string[]): Promise<void>;

package/dist/types/cli/daemon.d.ts

@@ -0,0 +1,74 @@
+export declare function outputJson(data: unknown): void;
+export declare function readPidFile(path: string): number | null;
+export declare function isProcessRunning(pid: number): boolean;
+/**
+ * Whether pid's command line contains `needle`. Returns null when `ps` cannot
+ * answer (no such process, unsupported platform) — callers fall back to the
+ * plain liveness signal.
+ */
+export declare function processCommandMatches(pid: number, needle: string): boolean | null;
+/**
+ * Liveness with a PID-recycling guard: the pid must be alive AND its command
+ * line must still look like our daemon (unless `ps` is unavailable, in which
+ * case the plain liveness signal wins).
+ */
+export declare function isOwnDaemonProcess(pid: number, entryNeedle: string): boolean;
+export declare function removePidFile(path: string): void;
+export interface HealthStatus {
+    responsive: boolean;
+    workspace: string | null;
+}
+export declare function readHealthStatus(url: string): Promise<HealthStatus>;
+export declare function isHealthy(url: string): Promise<boolean>;
+export declare function readLogTail(path: string, maxLines?: number): string | null;
+export declare function waitForHealth(healthUrl: string, timeoutMs: number, getExitMessage: () => string | null): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export declare function waitForShutdown(healthUrl: string, timeoutMs: number, isAlive: () => boolean): Promise<boolean>;
+/** Workspace the daemon child will bind — mirrors startCanvasServer's resolution. */
+export declare function resolveExpectedWorkspace(): string;
+export type PrecheckVerdict = 'not-running' | 'already-running' | 'foreign-port-owner';
+/** Pure decision for the pre-spawn health probe. */
+export declare function classifyPrecheck(health: HealthStatus, expectedWorkspace: string): PrecheckVerdict;
+export type LockResult = {
+    ok: true;
+} | {
+    ok: false;
+    holderPid: number | null;
+    reason: 'running' | 'starting';
+};
+/**
+ * Exclusive pid-file creation IS the spawn lock. A held file with a live
+ * daemon pid means 'running'; a fresh empty file means another starter is
+ * mid-spawn ('starting'); anything stale is reclaimed once.
+ */
+export declare function acquireDaemonLock(pidFile: string, entryNeedle: string): LockResult;
+/**
+ * True when the pid file is a concurrent starter's spawn lock: an EMPTY file
+ * (acquireDaemonLock creates it before writing the child pid) younger than
+ * LOCK_FRESH_MS. `serve status` must NOT delete such a file — clearing it
+ * mid-spawn would defeat the spawn lock and let a racing starter double-spawn.
+ * Mirrors the fresh-lock protection acquireDaemonLock applies. A stat failure
+ * biases toward preserving the lock.
+ */
+export declare function isFreshEmptyLock(pidFile: string): boolean;
+export interface DaemonPaths {
+    port: number;
+    logFile: string;
+    pidFile: string;
+}
+export declare function startDaemonMode(options: DaemonPaths & {
+    baseArgs: string[];
+    waitMs: number;
+    entry: string;
+}): Promise<void>;
+export declare function showServeStatus(options: DaemonPaths & {
+    entry: string;
+}): Promise<void>;
+export declare function stopServeDaemon(options: DaemonPaths & {
+    waitMs: number;
+    entry: string;
+}): Promise<void>;

package/dist/types/cli/watch.d.ts

@@ -1,5 +1,5 @@
 import { ALL_SEMANTIC_WATCH_EVENT_TYPES, formatCompactWatchEvent, SemanticWatchReducer, type SemanticWatchEvent, type SemanticWatchEventType, type SseMessage } from '../shared/semantic-attention.js';
-export { ALL_SEMANTIC_WATCH_EVENT_TYPES, formatCompactWatchEvent, SemanticWatchReducer, };
-export type { SemanticWatchEvent, SemanticWatchEventType, SseMessage, };
+export { ALL_SEMANTIC_WATCH_EVENT_TYPES, formatCompactWatchEvent, SemanticWatchReducer };
+export type { SemanticWatchEvent, SemanticWatchEventType, SseMessage };
 export declare function parseSemanticEventFilter(raw: string | undefined): Set<SemanticWatchEventType>;
 export declare function parseSseStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage>;

package/dist/types/client/canvas/CanvasViewport.d.ts

@@ -7,5 +7,5 @@ interface CanvasViewportProps {
     annotationTool?: AnnotationTool;
 }
 export declare function getRenderableWorldNodes(allNodes: Iterable<CanvasNodeState>, focusedNodeId: string | null): CanvasNodeState[];
-export declare function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu, annotationMode, annotationTool }: CanvasViewportProps): import("preact/src").JSX.Element;
+export declare function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu, annotationMode, annotationTool, }: CanvasViewportProps): import("preact/src").JSX.Element;
 export {};

package/dist/types/client/canvas/CommandPalette.d.ts

@@ -1,4 +1,4 @@
-export declare function CommandPalette({ onClose, onToggleMinimap, }: {
+export declare function CommandPalette({ onClose, onToggleMinimap }: {
     onClose: () => void;
     onToggleMinimap: () => void;
 }): import("preact/src").JSX.Element;

package/dist/types/client/canvas/Minimap.d.ts

@@ -19,5 +19,5 @@ interface MinimapProps {
     containerWidth: number;
     containerHeight: number;
 }
-export declare function Minimap({ viewport, nodes, edges, onNavigate, containerWidth, containerHeight, }: MinimapProps): import("preact/src").JSX.Element;
+export declare function Minimap({ viewport, nodes, edges, onNavigate, containerWidth, containerHeight }: MinimapProps): import("preact/src").JSX.Element;
 export {};

package/dist/types/client/nodes/ExtAppFrame.d.ts

@@ -19,7 +19,15 @@ interface ExtAppHostDimensionsTarget {
  * everywhere we can test (Chrome / Codex / Playwright).
  */
 export declare function isWebKitOnlyHost(userAgent: string): boolean;
-export declare function nextWebkitRepaintSlot(): number;
+export declare const WEBKIT_REMOUNT_SETTLE_MS = 1000;
+export interface WebkitRemountTask {
+    /** Perform the remount. Return false if the node no longer needs it (skips the boot wait). */
+    remount: () => boolean;
+    /** Resolves when the remounted app genuinely boots AND finishes its bootstrap replay, or after a bounded timeout. */
+    awaitBoot: () => Promise<void>;
+}
+export declare function extAppRecoveryLog(nodeId: string, event: string): void;
+export declare function enqueueWebkitRemount(task: WebkitRemountTask): void;
 export declare function shouldScheduleWebKitRepaint(status: ExtAppFrameStatus, hasReplayToolResult: boolean): boolean;
 export declare function getExtAppBridgeInitKey(node: CanvasNodeState, retryKey: number): string;
 export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMode, isExpanded: boolean): {

package/dist/types/client/nodes/FileNode.d.ts

@@ -1,5 +1,5 @@
 import type { CanvasNodeState } from '../types';
-export declare function FileNode({ node, expanded, }: {
+export declare function FileNode({ node, expanded }: {
     node: CanvasNodeState;
     expanded?: boolean;
 }): import("preact/src").JSX.Element;

package/dist/types/client/nodes/ImageNode.d.ts

@@ -4,7 +4,7 @@ import type { CanvasNodeState } from '../types';
  * Supports: file paths (served via /api/canvas/image/:nodeId), data URIs, and URLs.
  * Features: fit-to-container, zoom in/out within node, pan when zoomed.
  */
-export declare function ImageNode({ node, expanded, }: {
+export declare function ImageNode({ node, expanded }: {
     node: CanvasNodeState;
     expanded?: boolean;
 }): import("preact/src").JSX.Element;

package/dist/types/client/nodes/InlineFormatBar.d.ts

@@ -1,7 +1,7 @@
 import type { RefObject } from 'preact';
 /** Floating selection toolbar for a contentEditable host. Mounts once; while
  *  visible, positions itself above the current selection's viewport rect. */
-export declare function InlineFormatBar({ hostRef, onChange, }: {
+export declare function InlineFormatBar({ hostRef, onChange }: {
     hostRef: RefObject<HTMLElement>;
     onChange: () => void;
 }): import("preact").JSX.Element | null;

package/dist/types/client/nodes/MarkdownNode.d.ts

@@ -1,6 +1,6 @@
 import type { JSX } from 'preact';
 import type { CanvasNodeState } from '../types';
-export declare function MarkdownNode({ node, expanded, }: {
+export declare function MarkdownNode({ node, expanded }: {
     node: CanvasNodeState;
     expanded?: boolean;
 }): JSX.Element;

package/dist/types/client/nodes/PromptNode.d.ts

@@ -1,5 +1,5 @@
 import type { CanvasNodeState } from '../types';
-export declare function PromptNode({ node, expanded, }: {
+export declare function PromptNode({ node, expanded }: {
     node: CanvasNodeState;
     expanded?: boolean;
 }): import("preact/src").JSX.Element;

package/dist/types/client/nodes/ResponseNode.d.ts

@@ -1,5 +1,5 @@
 import type { CanvasNodeState } from '../types';
-export declare function ResponseNode({ node, expanded, }: {
+export declare function ResponseNode({ node, expanded }: {
     node: CanvasNodeState;
     expanded?: boolean;
 }): import("preact/src").JSX.Element;

package/dist/types/server/canvas-schema.d.ts

@@ -34,7 +34,7 @@ export interface StructuredValidationResult {
     summary: Record<string, unknown>;
 }
 declare const CANONICAL_GRAPH_TYPES: readonly ["line", "bar", "pie", "area", "scatter", "radar", "stacked-bar", "composed", "sparkline", "dot-plot", "bullet", "slopegraph"];
-type CanvasGraphType = typeof CANONICAL_GRAPH_TYPES[number];
+type CanvasGraphType = (typeof CANONICAL_GRAPH_TYPES)[number];
 export declare function describeCanvasSchema(): {
     ok: true;
     source: 'running-server';

package/dist/types/server/html-primitives.d.ts

@@ -1,5 +1,5 @@
 export declare const HTML_PRIMITIVE_KINDS: readonly ["choice-grid", "plan-timeline", "review-sheet", "pr-writeup", "system-map", "code-walkthrough", "design-sheet", "component-gallery", "interaction-prototype", "flowchart", "deck", "presentation", "illustration-set", "explainer", "status-report", "incident-report", "triage-board", "config-editor", "prompt-tuner"];
-export type HtmlPrimitiveKind = typeof HTML_PRIMITIVE_KINDS[number];
+export type HtmlPrimitiveKind = (typeof HTML_PRIMITIVE_KINDS)[number];
 export interface HtmlPrimitiveDescriptor {
     kind: HtmlPrimitiveKind;
     title: string;

package/dist/types/server/index.d.ts

@@ -13,7 +13,7 @@ import { type SerializedCanvasNode } from './canvas-serialization.js';
 import type { HtmlPrimitiveKind } from './html-primitives.js';
 import { type WebArtifactBuildInput, type WebArtifactCanvasBuildResult } from './web-artifacts.js';
 import { type ExternalMcpTransportConfig } from './mcp-app-runtime.js';
-import { type DiagramPresetOpenInput } from './diagram-presets.js';
+import type { DiagramPresetOpenInput } from './diagram-presets.js';
 import { type GraphNodeInput, type JsonRenderNodeInput, type JsonRenderSpec } from '../json-render/server.js';
 import type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus } from './server.js';
 /**
@@ -557,21 +557,21 @@ export type { CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from '.
 export type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus, PrimaryWorkbenchCanvasPromptRequest, PrimaryWorkbenchIntent, } from './server.js';
 export { emitPrimaryWorkbenchEvent, consumePrimaryWorkbenchIntents, setPrimaryWorkbenchAutoOpenEnabled, setPrimaryWorkbenchCanvasPromptHandler, startCanvasServer, stopCanvasServer, getCanvasServerPort, openUrlInExternalBrowser, getCanvasAutomationWebViewStatus, startCanvasAutomationWebView, stopCanvasAutomationWebView, evaluateCanvasAutomationWebView, resizeCanvasAutomationWebView, screenshotCanvasAutomationWebView, } from './server.js';
 export { canvasState } from './canvas-state.js';
-export type { CanvasAnnotation, CanvasSnapshot, CanvasSnapshotGcResult, CanvasSnapshotListOptions } from './canvas-state.js';
+export type { CanvasAnnotation, CanvasSnapshot, CanvasSnapshotGcResult, CanvasSnapshotListOptions, } from './canvas-state.js';
 export { findOpenCanvasPosition } from './placement.js';
 export { searchNodes, buildSpatialContext, detectClusters, findNeighborhoods } from './spatial-analysis.js';
 export type { SpatialCluster, SpatialContext, SpatialNeighbor, NodeSpatialInfo } from './spatial-analysis.js';
 export { mutationHistory, diffLayouts, formatDiff } from './mutation-history.js';
 export { recomputeCodeGraph, buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 export { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
-export { buildHtmlPrimitive, getHtmlPrimitiveSemanticMetadata, isHtmlPrimitiveKind, listHtmlPrimitiveDescriptors } from './html-primitives.js';
+export { buildHtmlPrimitive, getHtmlPrimitiveSemanticMetadata, isHtmlPrimitiveKind, listHtmlPrimitiveDescriptors, } from './html-primitives.js';
 export { buildWebArtifactOnCanvas, executeWebArtifactBuild, openWebArtifactInCanvas, resolveWebArtifactScriptPath, resolveWorkspacePath, } from './web-artifacts.js';
 export { buildGraphSpec, buildJsonRenderViewerHtml, createJsonRenderNodeData, GRAPH_NODE_SIZE, JSON_RENDER_NODE_SIZE, normalizeAndValidateJsonRenderSpec, } from '../json-render/server.js';
 export type { CodeGraphSummary, CodeGraphEdge } from './code-graph.js';
 export type { MutationEntry, MutationSummary, SnapshotDiffResult } from './mutation-history.js';
 export type { WebArtifactBuildInput, WebArtifactBuildOutput, WebArtifactCanvasBuildResult, WebArtifactCanvasOpenResult, } from './web-artifacts.js';
 export type { GraphNodeInput, JsonRenderNodeInput, JsonRenderSpec } from '../json-render/server.js';
-export type { HtmlPrimitiveKind, HtmlPrimitiveDescriptor, HtmlPrimitiveInput, HtmlPrimitiveBuildResult } from './html-primitives.js';
+export type { HtmlPrimitiveKind, HtmlPrimitiveDescriptor, HtmlPrimitiveInput, HtmlPrimitiveBuildResult, } from './html-primitives.js';
 export { traceManager } from './trace-manager.js';
 export type { PmxAxApprovalGate, PmxAxApprovalStatus, PmxAxCommandDescriptor, PmxAxContext, PmxAxEvent, PmxAxElicitation, PmxAxElicitationStatus, PmxAxEventKind, PmxAxEvidence, PmxAxEvidenceKind, PmxAxFocusState, PmxAxHostCapability, PmxAxMode, PmxAxModeRequest, PmxAxModeRequestStatus, PmxAxPolicy, PmxAxReviewAnchorType, PmxAxReviewAnnotation, PmxAxReviewKind, PmxAxReviewRegion, PmxAxReviewSeverity, PmxAxReviewStatus, PmxAxSource, PmxAxState, PmxAxSteeringMessage, PmxAxTimelineSummary, PmxAxWorkItem, PmxAxWorkItemStatus, } from './ax-state.js';
 export type { AxTimelineQuery } from './canvas-db.js';

package/dist/types/server/operations/index.d.ts

@@ -1,7 +1,7 @@
 export { executeOperation, getOperation, listOperations, registerOperation, setOperationEventEmitter, } from './registry.js';
 export { dispatchOperationRoute } from './http.js';
 export { runCanvasBatchOperation, type BatchEnvelope } from './ops/batch.js';
-export { type OpenMcpAppCoreResult } from './ops/app.js';
+export type { OpenMcpAppCoreResult } from './ops/app.js';
 export { LocalOperationInvoker, HttpOperationInvoker, type OperationInvoker } from './invoker.js';
 export { registerOperationTools, registerCompositeTools, type OperationToolHost } from './mcp.js';
 export { compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';

package/dist/types/server/operations/ops/ax-read.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const axReadOperations: Operation[];

package/dist/types/server/operations/ops/canvas-wire.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const canvasWireOperations: Operation[];

package/dist/types/server/operations/ops/ext-app.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const extAppOperations: Operation[];

package/dist/types/server/server.d.ts

@@ -81,6 +81,14 @@ export declare function setPrimaryWorkbenchAutoOpenEnabled(enabled: boolean): vo
 export declare function isPrimaryWorkbenchAutoOpenEnabled(): boolean;
 export declare function hasWorkbenchSubscribers(): boolean;
 export declare function setPrimaryWorkbenchCanvasPromptHandler(handler: PrimaryWorkbenchCanvasPromptHandler | null): void;
+/**
+ * Containment check for bundle-asset serving. Separator-agnostic: on Windows,
+ * `resolve()` returns backslash paths, so comparing against a `${dir}/` template
+ * rejected every asset — /canvas/index.js 404'd and the SPA never booted (the
+ * 0.3.1 Windows report). Normalizing both sides keeps the check exact on POSIX
+ * and correct on win32, and testable with win32-shaped fixtures on any host.
+ */
+export declare function isCanvasBundlePath(distPath: string, bundleDir: string): boolean;
 export declare function buildMacBrowserOpenScript(appName: string, url: string): string;
 export declare function openUrlInExternalBrowser(url: string): boolean;
 /**

package/docs/cli.md

@@ -2,7 +2,16 @@
 
 The CLI is the shell-native way to run and control PMX Canvas. It targets
 `http://localhost:4313` by default — override with `PMX_CANVAS_URL` or
-`PMX_CANVAS_PORT` when the server runs elsewhere.
+`PMX_CANVAS_PORT` when the server runs elsewhere, or per invocation with the
+global `--port <n>` / `--server-url <url>` flags (any position; `--server-url`
+wins over `--port`, and both win over the environment variables). An invalid
+value for either flag is a hard error — the CLI never falls back silently to
+the default port.
+
+```bash
+pmx-canvas node list --port 4750                      # target a non-default daemon
+pmx-canvas --server-url http://127.0.0.1:4750 status  # same, by URL
+```
 
 ## Server lifecycle
 

package/docs/http-api.md

@@ -276,6 +276,34 @@ and `/ax/mode/:id/resolve` return 404 for unknown IDs; `/ax/activity` requires a
 valid `kind` + `title` (400 otherwise); the single-item gate GETs return 404 for
 unknown IDs and clamp `?waitMs` to ≤120000.
 
+## Ghost Cursor intents (ephemeral)
+
+Intents are verb-routed over HTTP — there is **no `action` field**. That
+discriminator exists only on the MCP `canvas_intent` composite; `POST` always
+signals a *new* intent, so a body like `{"action":"clear"}` is rejected by the
+registry's kind validation. Pick the operation by method + path:
+
+```bash
+# Signal a ghost — returns { ok, intent } with the id. Auto-expires after ttlMs
+# (default 8000, max 60000), so cleanup is optional.
+curl -X POST http://localhost:4313/api/canvas/ax/intent \
+  -H "Content-Type: application/json" \
+  -d '{"kind":"create","position":{"x":400,"y":300},"nodeType":"markdown","label":"Add evidence","reason":"collecting run logs"}'
+
+# Update the ghost (position/label/reason/confidence/ttlMs; vetoed:true dissolves
+# it AND poisons the id so a later linked settle is rejected)
+curl -X PATCH http://localhost:4313/api/canvas/ax/intent/<id> \
+  -H "Content-Type: application/json" \
+  -d '{"position":{"x":520,"y":300},"reason":"moved next to the trace"}'
+
+# Clear the ghost: plain DELETE dissolves it; settle it into the real node it
+# became via settledNodeId, or veto it. Fields are accepted as JSON body or
+# query params (?vetoed=true/false is coerced; other values are rejected 400).
+curl -X DELETE http://localhost:4313/api/canvas/ax/intent/<id>
+curl -X DELETE "http://localhost:4313/api/canvas/ax/intent/<id>?settledNodeId=node-42"
+curl -X DELETE "http://localhost:4313/api/canvas/ax/intent/<id>?vetoed=true"
+```
+
 ## Diagrams (Excalidraw preset)
 
 ```bash

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

@@ -10,9 +10,9 @@ Each item is tagged by shape: **project** (multi-day, own plan/PR), **decision**
 
 | Item | Source | What's open | Shape |
 |---|---|---|---|
-| Complete the registry migration | C1 | Fold the ~50 remaining hand-written routes (44 tombstone comments) in `server.ts` into operations; collapse the 76-method `PmxCanvas` onto `executeOperation`; migrate the CLI's 60 raw `fetch` calls onto the operation invoker. Deletes the M5 handler clones and most M4 envelope inconsistency as side effects. | project |
+| Complete the registry migration | C1 | Fold the remaining hand-written routes in `server.ts` into operations; collapse the 76-method `PmxCanvas` onto `executeOperation`; migrate the CLI's 60 raw `fetch` calls onto the operation invoker. **Slice 1 done post-0.3.0:** the 7 `/api/ext-app/*` routes moved to `ops/ext-app.ts` (~290 lines out of `server.ts`, the 5 clone handlers — old M5 — collapsed to one parametrized definition; wire envelopes byte-identical, no new MCP tools). **Slice 2 done:** the 15 ax wire routes (8 GET lists + `ax/context` + `ax/surface-snapshot` + `pinned-context` + `code-graph` + `ax/activity` + `ax/interaction` + legacy `PATCH /api/canvas/ax`) moved to `ops/ax-read.ts` (~370 more lines out of `server.ts`); `open-external` stays hand-written (coupled to the live server port + system browser opener). **Slice 3 done:** theme GET/POST, canvas update, viewport, annotation POST, and node `:id/refresh` moved to the registry (`ops/canvas-wire.ts`, plus additions to `ops/viewport.ts`, `ops/annotation.ts`, `ops/nodes.ts`); the two dispatch gates unified into one `/api/` gate; `server.ts` is at ~2,980 lines (from 3,873 at the audit). **Remaining routes (~20)** are the deliberate poor fits (SSE, binary, HTML/static, file bodies) plus four server-coupled handlers: `prompt` + workbench `state`/`open`/`intent` (module-local `primaryWorkbench*` session state), `render` (Excalidraw URL-normalizer chain), `open-external` (live port + system browser). Those need state injection like the webview runner — a deliberate follow-up, not mechanical. After routes, the bigger halves remain: `PmxCanvas` (76 methods) onto `executeOperation`, and the CLI's raw fetches onto the invoker. | project (in progress) |
 | One HTTP envelope | M4 residual | Registry ops return bare bodies, legacy ext-app handlers `{ok:true,result}`, 404s plaintext. Unify (naturally falls out of C1). Also: surface persistence save failures via a `/health` degraded flag — `canvas-state.ts` has 63 catch→warn→continue sites. | project (with C1) |
-| `dist/` commit policy | C3 residual | Decide whether `dist/canvas` + `dist/types` stay committed; if yes, add a CI staleness check (every source change currently hand-carries `.d.ts` diffs). | decision |
+| `dist/` commit policy | C3 residual | **Decided + done post-0.3.0:** `dist/` stays committed; `test.yml` now has a `dist/types` staleness gate (rebuild + fail on drift). The `dist/canvas`/`dist/json-render` bundles are deliberately not byte-checked — bundler output varies across bun versions; their staleness story folds into M1. | done |
 | Skill-mirror validator | C2 residual | `validate:agent-skills` exits 0 when the (local-only, gitignored) trees are absent. Docs are honest about this now; decide whether to repoint, gate, or delete the check. | decision |
 | Generate CLAUDE.md/AGENTS.md from one source | M9 residual | The twins are byte-identical again but still hand-maintained; generate or symlink to prevent the next drift. | small |
 
@@ -20,10 +20,10 @@ Each item is tagged by shape: **project** (multi-day, own plan/PR), **decision**
 
 | Item | Source | What's open | Shape |
 |---|---|---|---|
-| Lint/format tooling | H6 | No ESLint/Biome/Prettier anywhere; `docs/RELEASE.md` claims `release:check` lints (it doesn't). Adopt Biome, wire into CI and `release:check`. First run will be a large mechanical diff — land it standalone. | decision + project |
+| Lint/format tooling | H6 | **Done post-0.3.0:** Biome 2.5 adopted — `bun run lint` / `lint:fix`, wired into `release:check` (making RELEASE.md's "lints" claim true) and CI. First-run format sweep landed as its own mechanical commit; 7 lint errors hand-fixed (incl. a real conditional-hooks bug in `SelectionBar.tsx`). Deliberately disabled rules to revisit: a11y group, `useExhaustiveDependencies` (misfires on Preact signals), `noNonNullAssertion` (143 deliberate uses), `noArrayIndexKey` (13 sites). ~77 warnings (unused imports/vars, optional-chain) left as a burn-down list — warnings don't fail the gate. | done |
 | Client + server unit coverage | H7 | Zero component render tests (no DOM test lib in repo); untested big modules: `ax-state-manager.ts` (826 lines), `mcp-app-host.ts` (814), `canvas-schema.ts` (644), `shared/semantic-attention.ts` (600, in zero test files). Coverage is collected but gates nothing; tests aren't typechecked. Add `happy-dom` + `@testing-library/preact`, a tests tsconfig, and a coverage threshold. | project |
-| Daemon port/lock lifecycle | H4 | The server does port fallback but `cli/index.ts:202,268,302` polls the *requested* port: a fallen-back daemon reads as dead and `serve stop` can't kill it. TOCTOU double-spawn between health check and spawn; `isProcessRunning` treats `EPERM` as alive with no PID-recycling guard. Fix: child reports its actual bound port; parent locks before spawn and records the pid immediately. Root cause of the intermittently flaky `pmx-canvas-sdk.test.ts` port collision. | project (small-ish, high value) |
-| Test-suite structure | M8 | Integration monoliths under `tests/unit/` (`server-api` 5,213 lines, `cli-node` 2,903); `getAvailablePort()` copy-pasted in 5 files; `waitForPersistence(650ms)` fixed sleeps in 9 files + ~19 magic `Bun.sleep`s; Playwright lacks `retries`/`forbidOnly`; `test:e2e-cli` (517-line script) runs in no CI workflow. | project |
+| Daemon port/lock lifecycle | H4 | **Fixed post-0.3.0** (`src/cli/daemon.ts` + `tests/unit/cli-daemon.test.ts`). Note the original finding was partly wrong: the daemon child was already strict-port (`PmxCanvas.start` pins `allowPortFallback: false`), so fallback-blind polling could not occur. The real defects — fixed — were: the pre-check accepted any responsive `/health` as "already running" (even a foreign workspace's daemon), a TOCTOU double-spawn window, the pid recorded only after health passed (slow start → unkillable orphan), and no PID-recycling guard. The flaky `pmx-canvas-sdk.test.ts` port collision is NOT this — it's M8's copy-pasted `getAvailablePort()` racing. | done |
+| Test-suite structure | M8 | Integration monoliths under `tests/unit/` (`server-api` 5,213 lines, `cli-node` 2,903); `getAvailablePort()` copy-pasted in 5 files; `waitForPersistence(650ms)` fixed sleeps in 9 files + ~19 magic `Bun.sleep`s; Playwright lacks `retries`/`forbidOnly`; `test:e2e-cli` (517-line script) runs in no CI workflow. *Post-0.3.0:* `operation-parity` now binds port 0 and derives the port from the base URL (removes one reserve-then-rebind race); the shared-helper dedup and the rest remain. Also noted: `ax-parity.test.ts` is a string-matching source-analysis test whose needles broke when Biome re-wrapped `cmd(` calls — its CLI needles are now layout-independent, but any future needle should avoid depending on line layout. **Also noted (2026-07-07):** the `server-api` Excalidraw diagram tests do real network round-trips to the hosted `mcp.excalidraw.com` MCP server and intermittently time out (30s) under full parallel runs — they should be mocked or moved to a network-tagged tier. | project |
 | `noUncheckedIndexedAccess` | L7 residual | Enable in tsconfig; will surface many index-access errors — treat as its own sweep. | small (noisy) |
 
 ## Phase 3 — client consolidation

package/docs/tech-debt-assessment-2026-07.md

@@ -67,8 +67,8 @@ The 3 fully parallel implementations (`canvas_add_html_node`, `canvas_add_html_p
 #### H3. `src/cli/agent.ts` is a 3,337-line monolith with 83 hand-registered commands
 83 `cmd(...)` registrations in one file, routed by a manual three-then-two-then-one word lookup (`agent.ts:3287-3301`); 81 copy-pasted `if (flags.help || flags.h) return showCommandHelp(...)` preambles; a hand-rolled flag parser with a ~40-entry `BOOL_FLAGS` allowlist (`agent.ts:184-193`) that must be updated for every new boolean flag — while `src/cli/index.ts:43-87` independently implements a *second* parser with different rules. **Remediation:** per-domain command modules + a `defineCommand` wrapper + one shared arg parser (and see C1 for the transport).
 
-#### H4. Daemon lifecycle management contradicts the server's own port behavior
-The server does port fallback (`buildPortCandidates()`, `server.ts:2773`, bind loop at `:3533`), but the CLI daemon manager hardcodes `http://localhost:${options.port}/health` (`cli/index.ts:202,268,302`). If the child falls back, the parent polls the wrong port and reports a dead daemon that is actually running — orphaned and unkillable via `serve stop` since the pid file is only written after health succeeds (`:249`). Additional fragility: TOCTOU between the health check (`:206`) and spawn (`:225`) lets two concurrent `serve` calls double-spawn, and `isProcessRunning` treats `EPERM` as alive with no PID-recycling guard (`:105-115`). This port-collision class caused the one flaky unit-test failure in the first verification run (`pmx-canvas-sdk.test.ts`, `EADDRINUSE` on candidate 4799; passed in the 2026-07-06 re-run — the flake is intermittent, the root cause is unfixed). **Remediation:** child reports its actual bound port (pidfile/stdout); parent locks before spawning and records pid immediately.
+#### H4. Daemon lifecycle: races, orphans, and a dishonest pre-check — FIXED post-0.3.0 (finding partly corrected)
+*Correction (2026-07-07):* the original claim that a fallen-back child leaves the parent polling the wrong port was wrong — the daemon child was already strict-port (`PmxCanvas.start` pins `allowPortFallback: false`, `index.ts:176`; only the MCP auto-start path opts into fallback). The real defects were: the pre-check treated **any** responsive `/health` on the port as "already running" (including a different workspace's daemon — the same wrong-workspace class as v0.2.7 Finding I); a TOCTOU window between health check and spawn; the pid file written only after health passed, so a slow-starting daemon outlived its `--wait-ms` budget as an unkillable orphan; and `isProcessRunning` treating `EPERM` as alive with no PID-recycling guard. *Fix (post-0.3.0):* daemon lifecycle extracted to `src/cli/daemon.ts` — the pid file is created exclusively as the spawn lock and records the pid immediately, failed startups kill the child, the pre-check is workspace-aware, and liveness is cross-checked against the process command line (`tests/unit/cli-daemon.test.ts`, 19 tests, plus a live start/double-start/foreign-workspace/status/stop smoke). The intermittent `pmx-canvas-sdk.test.ts` port flake is unrelated — it is M8's copy-pasted `getAvailablePort()` racing.
 
 #### H5. sse-bridge maintains a second, divergent copy of node construction and thread state
 `src/client/state/sse-bridge.ts` (1,066 lines, 34 handlers) has its own `DEFAULT_POSITIONS`/`makeNode` node factory (`:75-114`) fully separate from `canvas-store`'s `addNode`/`parseCanvasNode` — two factories with divergent defaults. Thread/turn reconciliation hand-mutates a `turns[]` array plus a module-level `responseToThreadMap` whose own comment admits it is *"Not cleaned on SSE reconnect"* (`:43`), with heuristic dedup (`:650-654`). Server-side, `syncEventToCanvasState` (`server.ts:3046`, ~330 lines) mirrors this as a giant if/else chain, with node geometry defaults duplicated against `ensureDefaultDockedNodes` under a comment saying *"keep geometry/dock defaults in sync if you change them"* (`:3006`). This is the exact drift class that Canvas Architecture Rule 2 exists to prevent. **Remediation:** one shared node factory; treat `canvas-layout-update` as the single source of truth for thread nodes; table-drive the event sync.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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",
@@ -38,9 +38,11 @@
     "build": "bun run build:client && bun run build:json-render && bun run build:types",
     "start": "bun run src/cli/index.ts --no-open",
     "pack:dry-run": "bun pm pack --dry-run",
-    "release:check": "bun run build && bun run typecheck && bun run test:all",
+    "release:check": "bun run build && bun run typecheck && bun run lint && bun run test:all",
     "release:smoke": "bash scripts/release-smoke.sh",
     "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
     "test": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
     "test:unit": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
     "test:coverage": "bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage",
@@ -76,6 +78,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.2",
     "@playwright/test": "^1.58.2",
     "@tailwindcss/cli": "^4.1.18",
     "@types/bun": "latest",

package/skills/pmx-canvas/SKILL.md

@@ -24,7 +24,8 @@ Humans curate agent context by pinning nodes; agents read that curation through
    `workspace` must equal the intended absolute workspace root. A healthy listener on port 4313
    may belong to another project.
 3. **Read before write.** Search with `canvas_query { action: "search", query }` before creating
-   nodes. Read the full layout only when necessary.
+   nodes. Read the full layout only when necessary. The MCP parameter is `query` — passing the
+   HTTP API's `q` is silently ignored and returns zero results.
 4. **Snapshot before destructive changes.** Use `canvas_snapshot` (deprecated standalone; folds into
    the `canvas_snapshot` composite's `save` action in v0.4) before clear, restore, or a major
    reorganization.
@@ -33,7 +34,8 @@ Humans curate agent context by pinning nodes; agents read that curation through
    or edit, then pass the returned `intent.id` as `intentId` on the mutation so the ghost settles
    into the result. Use it as much as possible to make your next move and your work visible: the
    human watches intent form and can veto mid-thought. Skip it only for trivial in-place tweaks or
-   high-frequency batch churn.
+   high-frequency batch churn. The default TTL (~8s) expires between agent turns: signal with
+   `ttlMs: 30000` and settle by passing `intentId` on the mutation in the same or next call.
 6. **Mutate through current composites.** Prefer the 15 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" }`.
@@ -55,7 +57,9 @@ Both surfaces report `workspace`. It must match the intended workspace root.
 
 - If `responsive: true` but `pidRunning: false`, treat the listener as potentially stale.
 - On mismatch, do not mutate. Start the intended workspace on an explicit free port:
-  `pmx-canvas serve --daemon --no-open --port=<free-port>`.
+  `pmx-canvas serve --daemon --no-open --port=<free-port>`. (`serve --daemon` enforces this
+  itself: pointed at a port owned by another workspace, it refuses with the owner named instead
+  of reporting "already running".)
 - Target that port and re-check `/health`.
 - `PMX_CANVAS_PORT` is the agent CLI target; the server's startup port is controlled by `--port`
   or `PMX_WEB_CANVAS_PORT`.
@@ -213,13 +217,14 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   loads (e.g. the GitHub Copilot app's embedded WKWebView) can render as a black tile — a host
   compositor paint race on the nested iframe, **not** a broken node (the session is healthy and
   `sessionStatus` is `ready`; it renders fine in Chrome, the Codex browser, and for nodes created
-  live after the panel hydrates). The canvas forces a one-time post-boot repaint remount under
-  WebKit, which reliably repaints a **single** present-at-load
-  ext-app — but a board with **several** ext-apps present at WebKit panel-load can still black out
-  (the simultaneous cold-hydration burst overwhelms the WebKit compositor). Recovery is
-  deterministic: **expand-then-close** any black tile (forces a fresh mount in the fullscreen
-  overlay, which always paints), or open the workbench in a normal browser (Chrome). Do not
-  diagnose a healthy app session as a broken node; the durable fix is upstream in the host panel.
+  live after the panel hydrates). Under WebKit the canvas auto-recovers: after boot, each
+  present-at-load ext-app is remounted through a **serialized, boot-aware queue** (one app at a
+  time, each waiting for the previous app's handshake + scene replay), with a watchdog retry for
+  iframes that never boot — so multi-app boards converge to painted tiles within a few seconds of
+  panel load. In rare cases a tile can still end up black (compositing success is not observable
+  from page JS, so retries are bounded); recovery is deterministic: **expand-then-close** the
+  black tile (forces a fresh mount in the fullscreen overlay, which always paints), or open the
+  workbench in a normal browser (Chrome). Do not diagnose a healthy app session as a broken node.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
   reflow on a live window resize in a normal browser. Some single-tab host browsers (e.g. the
   Codex in-app browser) don't deliver live-resize events, so a resized standalone chart can look

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

@@ -151,8 +151,13 @@ pmx-canvas serve stop                                  # Stop the daemon for thi
 
 `serve --daemon` writes a pid file (`.pmx-canvas/daemon-<port>.pid`) and a log file
 (`.pmx-canvas/daemon-<port>.log`); the wait flag blocks until `/health` returns OK so a script
-can rely on the server being responsive when the command returns. `serve stop` reads the pid
-file, sends SIGTERM, and cleans up on exit.
+can rely on the server being responsive when the command returns. The pid file doubles as the
+spawn lock and records the pid immediately, so a starting-but-not-yet-healthy daemon is already
+addressable by `serve stop`, and a failed startup kills the child — no orphans. If the requested
+port already serves a *different* workspace (or a non-canvas app), `serve --daemon` refuses with
+the owner named and a hint to pick another port; it never reports a foreign daemon as "already
+running". `serve stop` reads the pid file, verifies the pid still looks like a canvas daemon
+(recycled pids read as stale), sends SIGTERM, and cleans up on exit.
 
 ### Verify workspace identity BEFORE mutating (required)
 
@@ -170,7 +175,9 @@ file, sends SIGTERM, and cleans up on exit.
 3. **On mismatch, isolate**: start the intended workspace on an explicit free port —
    `pmx-canvas serve --daemon --no-open --port=<free-port>` — and target that port. (`PMX_CANVAS_PORT`
    alone may still attach to an existing `4313` listener; prefer an explicit `--port`.) Then
-   **re-read `/health`** to confirm the workspace now matches.
+   **re-read `/health`** to confirm the workspace now matches. `serve --daemon` also enforces
+   this itself: pointed at a port owned by another workspace, it exits with an error naming the
+   owner instead of attaching to it.
 4. **MCP transport exception:** `pmx-canvas --mcp` launched from an incidental host dir may attach to
    the healthy daemon already on the preferred port when no explicit workspace root is set, so writes
    land in the visible workbench instead of a hidden fallback workspace. Host adapters should set
@@ -503,6 +510,13 @@ surfaces): `canvas_batch`, `canvas_pin_nodes`, `canvas_screenshot`, `canvas_ax_i
 `canvas_diff` — deprecated pending a `canvas_snapshot` composite in v0.4; the name collides with
 the current save-snapshot tool, so the composite cannot land additively).
 
+`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`/
+`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
+`canvas_webview { action: "start" }` first.
+
 > **Removed in v0.3.0 → use the composite instead**: `canvas_open_mcp_app` / `canvas_add_diagram` /
 > `canvas_build_web_artifact` → **`canvas_app`**; `canvas_webview_start` / `canvas_webview_status` /
 > `canvas_webview_stop` / `canvas_resize` / `canvas_evaluate` → **`canvas_webview`**;