pmx-canvas 0.4.8 → 0.5.1

package/src/server/operations/invoker.ts

@@ -3,6 +3,7 @@
  * JSON body the HTTP route serves), so MCP/CLI callers format one shape
  * regardless of transport. Failures throw `OperationError`.
  */
+import { SOURCE_LABEL_RE } from '../agent-presence.js';
 import { executeOperation, getOperation } from './registry.js';
 import { OperationError, type OperationErrorStatus } from './types.js';
 
@@ -10,26 +11,52 @@ export interface OperationInvoker {
   invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
 }
 
+/**
+ * The agent-presence label for a transport: `PMX_CANVAS_AGENT_SOURCE` lets a
+ * host name its agent ('codex', 'claude-code', …) so writes, attach and cursor
+ * all key on one identity; otherwise the transport's own label.
+ */
+export function agentSourceLabel(fallback: string): string {
+  const raw = process.env.PMX_CANVAS_AGENT_SOURCE?.trim();
+  return raw && SOURCE_LABEL_RE.test(raw) ? raw : fallback;
+}
+
+/** `ax.presence.set` without an explicit source attaches under the caller's own label. */
+function defaultPresenceSource(name: string, input: Record<string, unknown>, source: string): Record<string, unknown> {
+  return name === 'ax.presence.set' && typeof input.source !== 'string' ? { ...input, source } : input;
+}
+
 /** Runs operations in-process against the shared canvasState singleton. */
 export class LocalOperationInvoker implements OperationInvoker {
+  private readonly source: string;
+
+  /** `source` labels this caller's agent presence ('mcp', 'sdk', …). */
+  constructor(source = 'api') {
+    this.source = agentSourceLabel(source);
+  }
+
   async invoke(name: string, input: Record<string, unknown>): Promise<unknown> {
-    return await executeOperation(name, input);
+    return await executeOperation(name, defaultPresenceSource(name, input, this.source), { source: this.source });
   }
 }
 
 function toOperationErrorStatus(status: number): OperationErrorStatus {
-  return status === 404 ? 404 : status === 409 ? 409 : 400;
+  return status === 404 ? 404 : status === 409 ? 409 : status === 403 ? 403 : 400;
 }
 
 /** Builds the HTTP request from the op's route template (`:id` from input, GET flags to query). */
 export class HttpOperationInvoker implements OperationInvoker {
   private readonly baseUrl: string;
+  private readonly source: string;
 
-  constructor(baseUrl: string) {
+  /** `source` labels this caller's agent presence on the server ('cli', 'mcp', …). */
+  constructor(baseUrl: string, source = 'api') {
     this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.source = agentSourceLabel(source);
   }
 
-  async invoke(name: string, input: Record<string, unknown>): Promise<unknown> {
+  async invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown> {
+    const input = defaultPresenceSource(name, rawInput, this.source);
     const op = getOperation(name);
     const route = op.http;
     if (!route) throw new OperationError(`Operation "${name}" has no HTTP route.`, 400);
@@ -52,7 +79,7 @@ export class HttpOperationInvoker implements OperationInvoker {
     }
 
     let url = `${this.baseUrl}${path}`;
-    const init: RequestInit = { method: route.method };
+    const init: RequestInit = { method: route.method, headers: { 'x-pmx-source': this.source } };
     if (route.method === 'GET' || route.method === 'DELETE') {
       const params = new URLSearchParams();
       for (const [key, value] of Object.entries(rest)) {
@@ -61,7 +88,7 @@ export class HttpOperationInvoker implements OperationInvoker {
       const query = params.toString();
       if (query) url += `?${query}`;
     } else {
-      init.headers = { 'Content-Type': 'application/json' };
+      init.headers = { 'Content-Type': 'application/json', 'x-pmx-source': this.source };
       init.body = JSON.stringify(rest);
     }
 

package/src/server/operations/ops/ax-presence.ts

@@ -0,0 +1,62 @@
+/**
+ * Agent presence operations (rail-chrome-v2 phase 2): the connect-time read
+ * and the explicit update for adapters with richer hooks than the derived
+ * feed provides (`thinking`, cursor, focus, attach/detach).
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import { agentPresence, SOURCE_LABEL_RE, PRESENCE_SET_SHAPE } from '../../agent-presence.js';
+import { defineOperation, type Operation, type OperationContext } from '../types.js';
+
+const emptyShape = {};
+const emptySchema = z.looseObject(emptyShape);
+
+const presenceGetOperation = defineOperation<z.infer<typeof emptySchema>, Record<string, unknown>>({
+  name: 'ax.presence.get',
+  mutates: false,
+  input: emptySchema,
+  inputShape: emptyShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/ax/presence',
+  },
+  handler: () => ({ ok: true, ...agentPresence.snapshot() }),
+});
+
+// One schema (agent-presence.ts) — only the descriptions are added here.
+const presenceSetShape = {
+  source: PRESENCE_SET_SHAPE.source.describe('Host label (copilot, codex, mcp, …); defaults to the transport'),
+  agentId: PRESENCE_SET_SHAPE.agentId.describe('Per-agent identity within the host (sub-agents keep their own cursor)'),
+  label: PRESENCE_SET_SHAPE.label.describe('Display name for this writer'),
+  phase: PRESENCE_SET_SHAPE.phase.describe('idle | thinking | tooling | waiting-approval'),
+  detail: PRESENCE_SET_SHAPE.detail.describe('Tool / step name shown beside the phase'),
+  focusNodeId: PRESENCE_SET_SHAPE.focusNodeId.describe('Node the agent is working on'),
+  cursor: PRESENCE_SET_SHAPE.cursor.describe('Agent cursor in world coordinates'),
+  attached: PRESENCE_SET_SHAPE.attached.describe('true attaches a session (Focus Session chrome); false detaches it'),
+};
+const presenceSetSchema = z.looseObject(presenceSetShape);
+
+const presenceSetOperation = defineOperation<z.infer<typeof presenceSetSchema>, Record<string, unknown>>({
+  name: 'ax.presence.set',
+  // Presence is not canvas state: no layout event, no history entry, no auto-ghost.
+  mutates: false,
+  input: presenceSetSchema,
+  inputShape: presenceSetShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/ax/presence',
+  },
+  handler: (input, _ctx: OperationContext) => {
+    const { source, ...rest } = input;
+    // The presence label is a WRITER label, not an AX source enum value: an
+    // adapter or an MCP server running with PMX_CANVAS_AGENT_SOURCE=claude-code
+    // must attach under the same label its writes carry (SOURCE_LABEL_RE), or
+    // the session and the writer split into two cursors.
+    const label = typeof source === 'string' && SOURCE_LABEL_RE.test(source) ? source : 'api';
+    const presence = agentPresence.set(rest, label);
+    return { ok: true, presence, ...agentPresence.snapshot() };
+  },
+});
+
+export const axPresenceOperations: Operation[] = [presenceGetOperation, presenceSetOperation];

package/src/server/operations/ops/ax-read.ts

@@ -11,6 +11,7 @@
  *
  * This module must never import server.ts or index.ts.
  */
+import { agentPresence } from '../../agent-presence.js';
 import { z } from 'zod';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from '../../agent-context.js';
 import { buildCanvasAxContext, buildCanvasAxSurfaceSnapshot } from '../../ax-context.js';
@@ -248,6 +249,13 @@ const activityIngestOperation = defineOperation<z.infer<typeof activitySchema>,
     if (result.workItem) ctx.emit('ax-state-changed', { workItem: result.workItem });
     if (result.evidence) ctx.emit('ax-event-created', { evidence: result.evidence });
     if (result.review) ctx.emit('ax-state-changed', { reviewAnnotation: result.review });
+    // Presence is derived from this feed: session-start attaches, session-end
+    // detaches, tool-start/-result drive the phase (rail-chrome-v2 phase 2).
+    agentPresence.observeActivity(body.kind, {
+      source: normalizeAxSource(body.source, 'api'),
+      agentId: typeof body.agentId === 'string' ? body.agentId : null,
+      title: body.title,
+    });
     return { ok: true, ...result };
   },
 });

package/src/server/operations/ops/ax-state.ts

@@ -140,11 +140,42 @@ const axFocusSetOperation = defineOperation<z.infer<typeof axFocusSetSchema>, Re
 const axPolicySetShape = {
   tools: z.unknown().optional().describe('Tool policy patch: allowed/excluded/approvalRequired arrays.'),
   prompt: z.unknown().optional().describe('Prompt policy patch: systemAppend/mode.'),
+  scope: z
+    .unknown()
+    .optional()
+    .describe(
+      'Scope fence (human-owned, set from the workbench): { nodeIds, padding? } limits agent WRITES to those nodes plus padding px around them; null clears it. Agent calls that include it are refused (403) — read policy.scope instead.',
+    ),
+  agentScopes: z
+    .unknown()
+    .optional()
+    .describe(
+      'Per-agent territories (fleet orchestration): { "<agentId or source>": { nodeIds, padding? } | null }. Each entry overrides the global fence for that writer; null clears that entry. An agent may fence OTHER writers (its workers) but never its own key.',
+    ),
   source: z.unknown().optional().describe('Optional host/source label. Defaults to mcp.'),
 };
 
 const axPolicySetSchema = z.looseObject(axPolicySetShape);
 
+/**
+ * A fence is a granted REGION: fencing a group frame grants everything inside
+ * it, so group ids expand to their members (nested groups included). Without
+ * this, "Fence to selection" on a frame lets the agent touch the frame only.
+ */
+function withGroupMembers(nodeIds: string[]): string[] {
+  const out = new Set<string>();
+  const visit = (id: string) => {
+    if (out.has(id)) return;
+    out.add(id);
+    const node = canvasState.getNode(id);
+    if (node?.type === 'group' && Array.isArray(node.data.children)) {
+      for (const child of node.data.children) if (typeof child === 'string') visit(child);
+    }
+  };
+  for (const id of nodeIds) visit(id);
+  return [...out];
+}
+
 const axPolicySetOperation = defineOperation<z.infer<typeof axPolicySetSchema>, Record<string, unknown>>({
   name: 'ax.policy.set',
   mutates: false,
@@ -167,12 +198,25 @@ const axPolicySetOperation = defineOperation<z.infer<typeof axPolicySetSchema>,
         })
         .optional(),
       prompt: z.object({ systemAppend: z.string().optional(), mode: z.string().optional() }).optional(),
+      agentScopes: z
+        .record(
+          z.string(),
+          z.union([z.object({ nodeIds: z.array(z.string()), padding: z.number().optional() }), z.null()]),
+        )
+        .optional()
+        .describe(
+          'Per-agent territories: writer key (agentId or source) → { nodeIds, padding? } | null. The orchestration surface — fence each worker to its lane; you cannot set your own key.',
+        ),
       source: z.enum(AX_SOURCES).optional(),
     },
     // Legacy MCP tool forwarded only the present tools/prompt fields (source split out).
+    // The GLOBAL scope fence is human-owned (see checkScopeOwnership) — MCP
+    // callers are agents, so the tool neither advertises nor forwards `scope`.
+    // Per-agent territories ARE the agent surface and forward.
     buildInput: (input) => ({
       ...(input.tools ? { tools: input.tools } : {}),
       ...(input.prompt ? { prompt: input.prompt } : {}),
+      ...(input.agentScopes ? { agentScopes: input.agentScopes } : {}),
       source: normalizeAxSource(input.source, 'mcp'),
     }),
     formatResult: (result) => {
@@ -183,11 +227,72 @@ const axPolicySetOperation = defineOperation<z.infer<typeof axPolicySetSchema>,
     },
   },
   handler: (input, ctx) => {
-    const patch: { tools?: Partial<PmxAxPolicy['tools']>; prompt?: Partial<PmxAxPolicy['prompt']> } = {};
+    const patch: {
+      tools?: Partial<PmxAxPolicy['tools']>;
+      prompt?: Partial<PmxAxPolicy['prompt']>;
+      scope?: { nodeIds: string[]; padding?: number } | null;
+      agentScopes?: Record<string, { nodeIds: string[]; padding?: number } | null>;
+    } = {};
     if (isRecord(input.tools)) patch.tools = input.tools as Partial<PmxAxPolicy['tools']>;
     if (isRecord(input.prompt)) patch.prompt = input.prompt as Partial<PmxAxPolicy['prompt']>;
+    if (isRecord(input.agentScopes)) {
+      const territories: Record<string, { nodeIds: string[]; padding?: number } | null> = {};
+      for (const [key, value] of Object.entries(input.agentScopes)) {
+        if (value === null) {
+          territories[key] = null;
+          continue;
+        }
+        if (!isRecord(value)) continue;
+        const ids = withGroupMembers(
+          Array.isArray(value.nodeIds) ? value.nodeIds.filter((id): id is string => typeof id === 'string') : [],
+        );
+        const pad = Number(value.padding);
+        territories[key] = ids.length > 0 ? { nodeIds: ids, ...(Number.isFinite(pad) ? { padding: pad } : {}) } : null;
+      }
+      patch.agentScopes = territories;
+    }
+    if (input.scope === null) patch.scope = null;
+    else if (isRecord(input.scope)) {
+      const nodeIds = withGroupMembers(
+        Array.isArray(input.scope.nodeIds)
+          ? input.scope.nodeIds.filter((id): id is string => typeof id === 'string')
+          : [],
+      );
+      const padding = Number(input.scope.padding);
+      patch.scope = nodeIds.length > 0 ? { nodeIds, ...(Number.isFinite(padding) ? { padding } : {}) } : null;
+    }
     const policy = canvasState.setPolicy(patch, { source: normalizeAxSource(input.source, 'api') });
     ctx.emit('ax-state-changed', { policy });
+    if (patch.agentScopes && Object.keys(patch.agentScopes).length > 0) {
+      const parts = Object.entries(patch.agentScopes).map(([key, fence]) =>
+        fence ? `${key}: ${fence.nodeIds.length} node${fence.nodeIds.length === 1 ? '' : 's'}` : `${key}: cleared`,
+      );
+      canvasState.recordAxEvent(
+        {
+          kind: 'policy',
+          summary: `Territories updated — ${parts.join('; ')}.`,
+          nodeIds: [],
+          data: { policy: 'agent-scopes', keys: Object.keys(patch.agentScopes) },
+        },
+        { source: normalizeAxSource(input.source, 'api') },
+      );
+    }
+    if (patch.scope !== undefined) {
+      // The agent reads the timeline — tell it the fence moved, and why its
+      // next write outside it will be refused.
+      const event = canvasState.recordAxEvent(
+        {
+          kind: 'policy',
+          summary: policy.scope
+            ? `Scope fence set: agent writes limited to ${policy.scope.nodeIds.length} node${policy.scope.nodeIds.length === 1 ? '' : 's'} (reads unaffected).`
+            : 'Scope fence cleared: the agent may write anywhere on the board.',
+          nodeIds: policy.scope?.nodeIds ?? [],
+          data: { policy: 'scope-fence', nodeIds: policy.scope?.nodeIds ?? [] },
+        },
+        { source: normalizeAxSource(input.source, 'browser') },
+      );
+      ctx.emit('ax-event-created', { event });
+    }
     return { ok: true, policy } as unknown as Record<string, unknown>;
   },
 });

package/src/server/operations/ops/ax-timeline.ts

@@ -46,9 +46,11 @@
  * This module must never import server.ts or index.ts.
  */
 import { z } from 'zod';
+import { agentPresence } from '../../agent-presence.js';
 import { canvasState } from '../../canvas-state.js';
 import { buildPendingAxActivity, isAxEventKind, isAxEvidenceKind } from '../../ax-state.js';
 import type { PmxAxEventKind, PmxAxEvidenceKind } from '../../ax-state.js';
+import { waitForAxCondition } from '../../ax-wait.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
 import {
@@ -238,6 +240,10 @@ const axSteerOperation = defineOperation<z.infer<typeof axSteerSchema>, Record<s
       ...(typeof input.target === 'string' ? { target: input.target } : {}),
     });
     ctx.emit('ax-event-created', { steering });
+    // Roster rows show each steerable writer's unclaimed-queue depth — a new
+    // steer changes that count even when the sender is the human (whose write
+    // never touches agent presence), so re-emit the snapshot explicitly.
+    agentPresence.refresh();
     return { ok: true, steering } as unknown as Record<string, unknown>;
   },
 });
@@ -283,6 +289,10 @@ const axDeliveryPendingShape = {
   consumer: z.unknown().optional().describe('Consumer/source label to exclude from results (e.g. copilot, mcp).'),
   limit: z.unknown().optional().describe('Max steering messages to return.'),
   order: z.unknown().optional().describe('"oldest" (FIFO, default) or "newest" first.'),
+  timeoutMs: z
+    .unknown()
+    .optional()
+    .describe('Max ms to block until steering arrives (0/omitted = immediate read; capped at 120000).'),
 };
 
 const axDeliveryPendingSchema = z.looseObject(axDeliveryPendingShape);
@@ -295,11 +305,22 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
   http: {
     method: 'GET',
     path: '/api/canvas/ax/delivery/pending',
+    // `?waitMs` long-polls like the gate awaits: park until steering for this
+    // consumer arrives or the timeout elapses. Custom readInput replaces the
+    // default query merge, so re-read the standard params here too.
+    readInput: (_req, params, url) => {
+      const raw = Number(url.searchParams.get('waitMs') ?? '');
+      return {
+        ...Object.fromEntries(url.searchParams),
+        ...params,
+        timeoutMs: Number.isFinite(raw) && raw > 0 ? raw : 0,
+      };
+    },
   },
   mcp: {
     toolName: 'canvas_claim_ax_delivery',
     description:
-      'Claim pending PMX AX deliveries for a consumer (adapterless delivery). Returns `pending` undelivered steering (mark each with canvas_mark_ax_delivery after acting) AND `pendingActivity`: open canvas-bound AX items awaiting the agent (open work items, pending approval gates / elicitations / mode requests) — typically created by the human in the browser. Both exclude items the consumer itself originated (loop prevention). `pending` defaults to oldest-first (FIFO, for ordered processing); pass `order:"newest"` to surface the human\'s LATEST in-canvas steering first when a small `limit` would otherwise bury it behind a stale backlog (report #68). pendingActivity is read-only here: resolve each via its own tool (canvas_resolve_approval / canvas_respond_elicitation / canvas_resolve_mode / canvas_update_work_item), not canvas_mark_ax_delivery.',
+      'Claim pending PMX AX deliveries for a consumer (adapterless delivery). Returns `pending` undelivered steering (mark each with canvas_mark_ax_delivery after acting) AND `pendingActivity`: open canvas-bound AX items awaiting the agent (open work items, pending approval gates / elicitations / mode requests) — typically created by the human in the browser. Both exclude items the consumer itself originated (loop prevention). `pending` defaults to oldest-first (FIFO, for ordered processing); pass `order:"newest"` to surface the human\'s LATEST in-canvas steering first when a small `limit` would otherwise bury it behind a stale backlog (report #68). pendingActivity is read-only here: resolve each via its own tool (canvas_resolve_approval / canvas_respond_elicitation / canvas_resolve_mode / canvas_update_work_item), not canvas_mark_ax_delivery. Pass `timeoutMs` to LONG-POLL: the call blocks until steering for the consumer arrives or the timeout elapses (max 120000) — loop on this to react to canvas steering promptly without burning your turn on tight polls.',
     extraShape: {
       consumer: z.string().optional().describe('Consumer/source label to exclude from results (e.g. copilot, mcp).'),
       limit: z.number().optional().describe('Max steering messages to return.'),
@@ -309,12 +330,21 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
         .describe(
           'Order of returned steering: "oldest" (FIFO, default) for ordered processing, or "newest" first to see the latest browser action when limited.',
         ),
+      timeoutMs: z
+        .number()
+        .min(0)
+        .max(120000)
+        .optional()
+        .describe('Max ms to block until steering arrives (0/omitted = immediate read).'),
     },
     // `consumer` is a loop-safety scope, not a source label — never defaulted.
     formatResult: axJsonResult,
   },
-  handler: (input) => {
+  handler: async (input) => {
     const consumer = typeof input.consumer === 'string' ? input.consumer : undefined;
+    // A claim is proof this consumer polls steering — its presence (session or
+    // external writer) becomes a legitimate composer steer target.
+    if (consumer) agentPresence.noteSteeringConsumer(consumer);
     const limitRaw = Number(input.limit ?? '');
     const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? limitRaw : undefined;
     // #68: default FIFO (oldest-first) for ordered processing; `order:"newest"`
@@ -323,7 +353,18 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
     // queries apply the same loop-safe consumer filter before the limit.
     const newest = input.order === 'newest';
     const scope = { ...(consumer ? { consumer } : {}), ...(limit ? { limit } : {}) };
-    const pending = newest ? canvasState.getPendingSteeringForContext(scope) : canvasState.getPendingSteering(scope);
+    const readPending = () =>
+      newest ? canvasState.getPendingSteeringForContext(scope) : canvasState.getPendingSteering(scope);
+    let pending = readPending();
+    const timeoutRaw = Number(input.timeoutMs ?? '');
+    const timeoutMs = Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 0;
+    if (pending.length === 0 && timeoutMs > 0) {
+      // Long-poll: hosts that cannot be woken from outside (Copilot, Codex —
+      // their model runs only while the host gives it a turn) park here and
+      // wake the moment steering lands, instead of burning the turn polling.
+      await waitForAxCondition({ ready: () => readPending().length > 0, timeoutMs });
+      pending = readPending();
+    }
     // The MCP tool aggregated pendingActivity; one wire body now serves it over
     // HTTP too (documented broadening). Loop-safe: consumer scopes both queries.
     const pendingActivity = buildPendingAxActivity(canvasState.getAxState(), consumer);
@@ -335,6 +376,12 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
 
 const axDeliveryMarkShape = {
   id: z.string().optional().catch(undefined).describe('The steering message id to mark delivered.'),
+  consumer: z
+    .unknown()
+    .optional()
+    .describe(
+      'The marking consumer. Broadcasts are delivered PER consumer — pass your label so the message stays pending for the other agents.',
+    ),
 };
 
 const axDeliveryMarkSchema = z.looseObject(axDeliveryMarkShape);
@@ -351,15 +398,17 @@ const axDeliveryMarkOperation = defineOperation<z.infer<typeof axDeliveryMarkSch
   mcp: {
     toolName: 'canvas_mark_ax_delivery',
     description:
-      'Mark a PMX AX steering message as delivered so it is not handed out again. Compare-and-set: `delivered:true` only on the actual undelivered→delivered transition — a false means the id was unknown OR another consumer already marked it, so do NOT treat the message as your delivery.',
+      'Mark a PMX AX steering message as delivered so it is not handed out again. ADDRESSED steers: compare-and-set — `delivered:true` only on the actual undelivered→delivered transition. BROADCASTS are delivered PER consumer: pass `consumer` and your mark removes it from YOUR queue only (every other agent still receives it) — an "all workers: stop" reaches the whole fleet. A false means the id was unknown or you (or, for addressed steers, someone) already marked it.',
     extraShape: {
       id: z.string().describe('The steering message id to mark delivered.'),
+      consumer: z.string().optional().describe('Your consumer label — required for per-consumer broadcast delivery.'),
     },
     formatResult: axJsonResult,
   },
   handler: (input, ctx) => {
     const id = typeof input.id === 'string' ? input.id : '';
-    const delivered = canvasState.markSteeringDelivered(id);
+    const consumer = typeof input.consumer === 'string' ? input.consumer : undefined;
+    const delivered = canvasState.markSteeringDelivered(id, consumer);
     // Legacy handleAxDeliveryMark only broadcasts when a message was marked.
     if (delivered) {
       ctx.emit('ax-event-created', { steeringDelivered: id });

package/src/server/operations/ops/ax-work.ts

@@ -378,6 +378,10 @@ const axApprovalRequestShape = {
   detail: z.unknown().optional().describe('Optional explanation of the action and its impact.'),
   action: z.unknown().optional().describe('Optional machine-readable action identifier the approval gates.'),
   nodeIds: z.unknown().optional().describe('Optional node IDs this approval relates to.'),
+  ttlMs: z
+    .unknown()
+    .optional()
+    .describe('Unattended-approval TTL in ms; the gate auto-holds if unanswered (default 5 min, max 24 h).'),
   source: z.unknown().optional().describe('Optional host/source label. Defaults to mcp.'),
 };
 
@@ -401,6 +405,10 @@ const axApprovalRequestOperation = defineOperation<z.infer<typeof axApprovalRequ
       detail: z.string().optional().describe('Optional explanation of the action and its impact.'),
       action: z.string().optional().describe('Optional machine-readable action identifier the approval gates.'),
       nodeIds: z.array(z.string()).optional().describe('Optional node IDs this approval relates to.'),
+      ttlMs: z
+        .number()
+        .optional()
+        .describe('Unattended-approval TTL in ms; the gate auto-holds if unanswered (default 5 min, max 24 h).'),
       source: AX_SOURCE_SHAPE,
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
@@ -410,12 +418,14 @@ const axApprovalRequestOperation = defineOperation<z.infer<typeof axApprovalRequ
     if (typeof input.title !== 'string' || !input.title.trim()) {
       throw new OperationError('approval request requires a title.');
     }
+    const ttlMs = Number(input.ttlMs);
     const approvalGate = canvasState.requestApproval(
       {
         title: input.title,
         ...(typeof input.detail === 'string' ? { detail: input.detail } : {}),
         ...(typeof input.action === 'string' ? { action: input.action } : {}),
         ...(Array.isArray(input.nodeIds) ? { nodeIds: normalizeAxNodeIds(input.nodeIds) } : {}),
+        ...(Number.isFinite(ttlMs) && ttlMs > 0 ? { ttlMs } : {}),
       },
       { source: normalizeAxSource(input.source, 'api') },
     );
@@ -424,6 +434,41 @@ const axApprovalRequestOperation = defineOperation<z.infer<typeof axApprovalRequ
   },
 });
 
+// ── ax.approval.reopen (session panel; human-facing) ──────────
+
+const axApprovalReopenShape = {
+  id: z.unknown().optional().describe('Approval gate id.'),
+  ttlMs: z.unknown().optional().describe('Fresh TTL in ms (default 5 min).'),
+  source: z.unknown().optional().describe('Optional host/source label.'),
+};
+const axApprovalReopenSchema = z.looseObject(axApprovalReopenShape);
+
+/**
+ * Reopen a resolved gate — the unattended-approval policy's "auto-held" exit.
+ * HTTP + SDK only: reopening is the HUMAN answering late, not an agent op.
+ */
+const axApprovalReopenOperation = defineOperation<z.infer<typeof axApprovalReopenSchema>, Record<string, unknown>>({
+  name: 'ax.approval.reopen',
+  mutates: false,
+  input: axApprovalReopenSchema,
+  inputShape: axApprovalReopenShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/ax/approval/:id/reopen',
+  },
+  handler: (input, ctx) => {
+    const id = typeof input.id === 'string' ? input.id : '';
+    const ttlMs = Number(input.ttlMs);
+    const approvalGate = canvasState.reopenApproval(id, {
+      ...(Number.isFinite(ttlMs) && ttlMs > 0 ? { ttlMs } : {}),
+      source: normalizeAxSource(input.source, 'browser'),
+    });
+    if (!approvalGate) throw new OperationError(`Approval gate "${id}" is not resolved (or does not exist).`, 404);
+    ctx.emit('ax-state-changed', { approvalGate });
+    return { ok: true, approvalGate } as unknown as Record<string, unknown>;
+  },
+});
+
 // ── ax.approval.resolve (canvas_resolve_approval) ─────────────
 
 const axApprovalResolveShape = {
@@ -676,6 +721,7 @@ export const axWorkOperations: Operation[] = [
   axReviewUpdateOperation,
   axApprovalRequestOperation,
   axApprovalResolveOperation,
+  axApprovalReopenOperation,
   axElicitationRequestOperation,
   axElicitationRespondOperation,
   axModeRequestOperation,

package/src/server/operations/ops/batch.ts

@@ -239,7 +239,9 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
       }
       const dispatch = resolveDispatch(operation.op, args);
       // Batch churn is exempt from auto-ghosts (matches the skill's explicit
-      // ghost-cursor exemption for batch operations).
+      // ghost-cursor exemption for batch operations). No `fromWorkbench`: the
+      // browser never issues batches, so inner writes are agent writes and the
+      // scope fence applies to each of them.
       const raw = await executeOperation(dispatch.name, dispatch.args, { suppressAutoGhost: true });
       const result = shapeBatchEntry(operation.op, raw);
       results.push(result);

package/src/server/operations/ops/edges.ts

@@ -5,7 +5,7 @@
  */
 import { z } from 'zod';
 import type { CanvasEdge } from '../../canvas-state.js';
-import { addCanvasEdge, removeCanvasEdge } from '../../canvas-operations.js';
+import { addCanvasEdge, removeCanvasEdge, updateCanvasEdge } from '../../canvas-operations.js';
 import { readJsonValue } from '../http.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
@@ -124,6 +124,92 @@ const edgeAddOperation = defineOperation<z.infer<typeof edgeAddSchema>, CanvasEd
   serialize: (edge) => ({ ok: true, ...edge }),
 });
 
+// ── edge.update ───────────────────────────────────────────────
+
+const edgeUpdateShape = {
+  id: z.string().optional().catch(undefined).describe('Edge ID to update'),
+  type: z.unknown().optional().describe('New edge type: flow, depends-on, relation, or references'),
+  label: z.unknown().optional().describe('New label text; empty string or null clears the label'),
+  style: z.unknown().optional().describe('New stroke style: solid, dashed, or dotted'),
+  animated: z.unknown().optional().describe('Animate the edge stroke'),
+};
+
+const edgeUpdateSchema = z.looseObject(edgeUpdateShape);
+
+const edgeUpdateOperation = defineOperation<z.infer<typeof edgeUpdateSchema>, CanvasEdge>({
+  name: 'edge.update',
+  mutates: true,
+  input: edgeUpdateSchema,
+  inputShape: edgeUpdateShape,
+  http: {
+    method: 'PATCH',
+    path: '/api/canvas/edge/:id',
+  },
+  mcp: {
+    toolName: 'canvas_update_edge',
+    description: 'Update an existing edge in place: change its label, type, stroke style, or animation.',
+    extraShape: {
+      id: z.string().describe('Edge ID to update'),
+      type: z.enum(['flow', 'depends-on', 'relation', 'references']).optional().describe('New edge type'),
+      label: z.string().nullable().optional().describe('New label text; empty string or null clears the label'),
+      style: z.enum(['solid', 'dashed', 'dotted']).optional().describe('New stroke style'),
+      animated: z.boolean().optional().describe('Animate the edge stroke'),
+    },
+    formatResult: (result) => {
+      const body = isRecord(result) ? result : {};
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify(
+              { id: body.id, type: body.type, label: body.label, style: body.style, animated: body.animated },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  },
+  handler: (input) => {
+    const body: Record<string, unknown> = input;
+    const id = typeof body.id === 'string' ? body.id : '';
+    if (!id) {
+      throw new OperationError('Missing required field: id.');
+    }
+    const patch: Partial<Pick<CanvasEdge, 'type' | 'label' | 'style' | 'animated'>> = {};
+    if ('type' in body && body.type !== undefined) {
+      if (typeof body.type !== 'string' || !VALID_EDGE_TYPES.has(body.type)) {
+        throw new OperationError(`Invalid edge type: "${String(body.type)}".`);
+      }
+      patch.type = body.type as CanvasEdge['type'];
+    }
+    if ('label' in body) {
+      // Empty string / null clears the label; the state layer drops undefined.
+      patch.label = typeof body.label === 'string' && body.label.length > 0 ? body.label : undefined;
+    }
+    if ('style' in body && body.style !== undefined) {
+      if (typeof body.style !== 'string' || !VALID_EDGE_STYLES.has(body.style)) {
+        throw new OperationError(`Invalid edge style: "${String(body.style)}". Use solid, dashed, or dotted.`);
+      }
+      patch.style = body.style as CanvasEdge['style'];
+    }
+    if ('animated' in body && body.animated !== undefined) {
+      patch.animated = Boolean(body.animated);
+    }
+    if (Object.keys(patch).length === 0) {
+      throw new OperationError('Nothing to update: provide type, label, style, or animated.');
+    }
+    try {
+      return updateCanvasEdge(id, patch);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Edge update failed.';
+      throw new OperationError(message, message.includes('not found') ? 404 : 400);
+    }
+  },
+  serialize: (edge) => ({ ok: true, ...edge }),
+});
+
 // ── edge.remove ───────────────────────────────────────────────
 
 const edgeRemoveShape = {
@@ -176,4 +262,4 @@ const edgeRemoveOperation = defineOperation<z.infer<typeof edgeRemoveSchema>, Re
   },
 });
 
-export const edgeOperations: Operation[] = [edgeAddOperation, edgeRemoveOperation];
+export const edgeOperations: Operation[] = [edgeAddOperation, edgeUpdateOperation, edgeRemoveOperation];