pmx-canvas 0.4.8 → 0.5.1

package/src/server/ax-context.ts

@@ -1,5 +1,6 @@
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
 import {
+  type PmxAxHumanAnnotation,
   buildAxContext,
   buildPendingAxActivity,
   AX_CONTEXT_STEERING_LIMIT,
@@ -12,6 +13,7 @@ import {
   type PmxAxModeRequest,
   type PmxAxPolicy,
 } from './ax-state.js';
+import type { CanvasLayout } from './canvas-state.js';
 import { canvasState, type CanvasNodeState } from './canvas-state.js';
 
 /**
@@ -75,6 +77,48 @@ export function buildCanvasAxPinnedContext(): PmxAxPinnedContext {
   };
 }
 
+/**
+ * Human ink → agent context: each annotation, anchored to the nodes whose
+ * padded frame it overlaps. Without this the human's strokes and notes were
+ * invisible to every agent-facing surface — the annotate tool IS the human
+ * writing to the agent (the pins principle, in ink).
+ */
+function buildHumanAnnotations(layout: CanvasLayout): PmxAxHumanAnnotation[] {
+  const PAD = 40;
+  return canvasState.getAnnotations().map((annotation) => {
+    const xs = annotation.points.map((point) => point.x);
+    const ys = annotation.points.map((point) => point.y);
+    const center = xs.length
+      ? {
+          x: Math.round((Math.min(...xs) + Math.max(...xs)) / 2),
+          y: Math.round((Math.min(...ys) + Math.max(...ys)) / 2),
+        }
+      : { x: 0, y: 0 };
+    const onNodes = layout.nodes
+      .filter((node) => {
+        const left = node.position.x - PAD;
+        const top = node.position.y - PAD;
+        const right = node.position.x + node.size.width + PAD;
+        const bottom = node.position.y + node.size.height + PAD;
+        return (
+          xs.length > 0 &&
+          Math.min(...xs) <= right &&
+          Math.max(...xs) >= left &&
+          Math.min(...ys) <= bottom &&
+          Math.max(...ys) >= top
+        );
+      })
+      .map((node) => ({ id: node.id, title: typeof node.data.title === 'string' ? node.data.title : null }));
+    const text =
+      typeof annotation.text === 'string' && annotation.text
+        ? annotation.text
+        : typeof annotation.label === 'string' && annotation.label
+          ? annotation.label
+          : null;
+    return { id: annotation.id, type: annotation.type, text, onNodes, center };
+  });
+}
+
 export function buildCanvasAxContext(consumer?: string): PmxAxContext {
   const layout = canvasState.getLayout();
   const ax = canvasState.getAxState();
@@ -100,6 +144,7 @@ export function buildCanvasAxContext(consumer?: string): PmxAxContext {
     workItems: ax.workItems,
     approvalGates: ax.approvalGates,
     reviewAnnotations: ax.reviewAnnotations,
+    humanAnnotations: buildHumanAnnotations(layout),
     elicitations: ax.elicitations,
     modeRequests: ax.modeRequests,
     policy: ax.policy,

package/src/server/ax-gate-ttl.ts

@@ -0,0 +1,61 @@
+/**
+ * Unattended-approval sweeper (rail-chrome-v2 phase 4, design item 3).
+ *
+ * A pending gate the human has not answered by `expiresAt` resolves to
+ * `held` — the safe default: the awaiting agent is released with a
+ * non-approval, the action does NOT proceed, and a `policy` event lands in
+ * the timeline so both sides can see why. The gate can be reopened from the
+ * session panel. Same discipline as IntentRegistry's sweeper: a 1s unref'd
+ * interval that only runs while a server is up, emitting through an injected
+ * workbench emitter so this module never imports server.ts.
+ */
+import { formatCountdown } from '../shared/approval-gates.js';
+import { canvasState } from './canvas-state.js';
+
+type GateEmitter = (event: string, payload: Record<string, unknown>) => void;
+
+let sweepTimer: ReturnType<typeof setInterval> | null = null;
+let emit: GateEmitter = () => {};
+
+/** Hold every pending gate whose TTL has elapsed. Returns the gates it held. */
+export function sweepExpiredGates(now = Date.now()): string[] {
+  const held: string[] = [];
+  for (const gate of canvasState.getAxState().approvalGates) {
+    if (gate.status !== 'pending' || !gate.expiresAt) continue;
+    const expires = Date.parse(gate.expiresAt);
+    if (!Number.isFinite(expires) || expires > now) continue;
+    const ttl = Math.max(0, expires - Date.parse(gate.createdAt));
+    const resolved = canvasState.resolveApproval(gate.id, 'held', {
+      resolution: `auto-held: no answer within ${formatCountdown(ttl)}`,
+      source: 'system',
+    });
+    if (!resolved) continue;
+    held.push(gate.id);
+    const event = canvasState.recordAxEvent(
+      {
+        kind: 'policy',
+        summary: `Auto-held "${gate.title}" — no answer within ${formatCountdown(ttl)}; the action did not proceed.`,
+        detail: 'Reopen it from the session panel to answer.',
+        nodeIds: gate.nodeIds,
+        data: { gateId: gate.id, policy: 'unattended-approval', outcome: 'held' },
+      },
+      { source: 'system' },
+    );
+    emit('ax-state-changed', { approvalGate: resolved });
+    emit('ax-event-created', { event });
+  }
+  return held;
+}
+
+export function startGateTtlSweeper(emitter: GateEmitter): void {
+  emit = emitter;
+  if (sweepTimer) return;
+  sweepTimer = setInterval(() => sweepExpiredGates(), 1000);
+  (sweepTimer as { unref?: () => void }).unref?.();
+}
+
+export function stopGateTtlSweeper(): void {
+  if (sweepTimer) clearInterval(sweepTimer);
+  sweepTimer = null;
+  emit = () => {};
+}

package/src/server/ax-interaction.ts

@@ -626,7 +626,6 @@ function materializeFlow(
       zIndex: 1,
       collapsed: false,
       pinned: false,
-      dockPosition: null,
       data: nodeData,
     });
     const workItem = manager.addWorkItem(
@@ -720,6 +719,28 @@ function materializeFlow(
  * underlying AX state event). Never throws on bad input — returns an `ok: false`
  * result with an appropriate HTTP-ish status.
  */
+// ── ax.work.create idempotency window ─────────────
+const WORK_CREATE_DEDUPE_MS = 2_500;
+const recentWorkCreates = new Map<string, { item: PmxAxWorkItem; at: number }>();
+
+function recentWorkCreate(sourceNodeId: string, title: string): PmxAxWorkItem | null {
+  const key = `${sourceNodeId}\u0000${title}`;
+  const hit = recentWorkCreates.get(key);
+  if (hit && Date.now() - hit.at <= WORK_CREATE_DEDUPE_MS) return hit.item;
+  return null;
+}
+
+function rememberWorkCreate(sourceNodeId: string, title: string, item: PmxAxWorkItem): void {
+  const key = `${sourceNodeId}\u0000${title}`;
+  recentWorkCreates.set(key, { item, at: Date.now() });
+  if (recentWorkCreates.size > 64) {
+    const now = Date.now();
+    for (const [k, v] of recentWorkCreates) {
+      if (now - v.at > WORK_CREATE_DEDUPE_MS) recentWorkCreates.delete(k);
+    }
+  }
+}
+
 export function applyAxInteraction(
   manager: AxInteractionManager,
   rawBody: unknown,
@@ -825,6 +846,12 @@ export function applyAxInteraction(
         detail?: string | null;
         nodeIds?: string[];
       };
+      // Idempotency window (joint-gaps bug: a json-render button double-emit
+      // booked two identical work items ~1s apart): the SAME node creating a
+      // work item with the SAME title inside the window gets the first item
+      // back instead of a duplicate.
+      const dupe = recentWorkCreate(sourceNodeId, p.title);
+      if (dupe) return accept(type, sourceNodeId, dupe, 'ax-state-changed', { workItem: dupe });
       const workItem = manager.addWorkItem(
         {
           title: p.title,
@@ -834,6 +861,7 @@ export function applyAxInteraction(
         },
         opts,
       );
+      rememberWorkCreate(sourceNodeId, p.title, workItem);
       return withLayoutBroadcast(accept(type, sourceNodeId, workItem, 'ax-state-changed', { workItem }), manager, [
         workItem,
       ]);

package/src/server/ax-state-manager.ts

@@ -21,6 +21,7 @@
  * `recordMutation`, and a `suppressed` wrapper for history closures.
  */
 
+import { clampGateTtlMs } from '../shared/approval-gates.js';
 import {
   appendAxEventToDB,
   appendAxEvidenceToDB,
@@ -39,6 +40,7 @@ import {
 } from './canvas-db.js';
 import {
   createEmptyAxState,
+  defaultGateTtlMs,
   createEmptyAxHostCapability,
   normalizeAxState,
   normalizeAxHostCapability,
@@ -141,7 +143,20 @@ export class AxStateManager {
 
   /** Replace the canvas-bound partition from a persisted/restored blob, normalized against current nodes. */
   applyPersistedAx(ax: unknown): void {
-    this._axState = this.normalizeForCurrentNodes(ax);
+    const normalized = this.normalizeForCurrentNodes(ax);
+    // A pending gate restored from a snapshot (or loaded on boot) may carry an
+    // already-elapsed TTL; holding it on the next sweeper tick would be safe
+    // but would rob the human who just restored it of any window to answer.
+    // Restart the clock from now.
+    const now = Date.now();
+    this._axState = {
+      ...normalized,
+      approvalGates: normalized.approvalGates.map((gate) =>
+        gate.status === 'pending' && (!gate.expiresAt || Date.parse(gate.expiresAt) <= now)
+          ? { ...gate, expiresAt: new Date(now + defaultGateTtlMs()).toISOString() }
+          : gate,
+      ),
+    };
   }
 
   /** Load the host-capability row from its own table (own partition; not snapshotted). */
@@ -323,7 +338,7 @@ export class AxStateManager {
   }
 
   requestApproval(
-    input: { title: string; detail?: string | null; action?: string | null; nodeIds?: string[] },
+    input: { title: string; detail?: string | null; action?: string | null; nodeIds?: string[]; ttlMs?: number },
     options: { source?: PmxAxSource } = {},
   ): PmxAxApprovalGate {
     const oldAxState = this.getAxState();
@@ -351,7 +366,7 @@ export class AxStateManager {
 
   resolveApproval(
     id: string,
-    decision: 'approved' | 'rejected',
+    decision: 'approved' | 'rejected' | 'held',
     options: { resolution?: string; source?: PmxAxSource } = {},
   ): PmxAxApprovalGate | null {
     const oldAxState = this.getAxState();
@@ -385,6 +400,43 @@ export class AxStateManager {
     return applied.approvalGates.find((g) => g.id === id) ?? null;
   }
 
+  /**
+   * Reopen a resolved gate (typically one the unattended-approval policy
+   * auto-held): back to pending with a fresh TTL, so the human can answer it.
+   */
+  reopenApproval(id: string, options: { ttlMs?: number; source?: PmxAxSource } = {}): PmxAxApprovalGate | null {
+    const oldAxState = this.getAxState();
+    const gate = oldAxState.approvalGates.find((g) => g.id === id);
+    if (!gate || gate.status === 'pending') return null;
+    const reopened: PmxAxApprovalGate = {
+      ...gate,
+      status: 'pending',
+      expiresAt: new Date(Date.now() + clampGateTtlMs(options.ttlMs, defaultGateTtlMs())).toISOString(),
+      resolvedAt: null,
+      resolution: null,
+      source: options.source ?? gate.source,
+    };
+    this.applyAxState({ ...oldAxState, approvalGates: replaceById(oldAxState.approvalGates, reopened) });
+    const applied = this.getAxState();
+    this.deps.scheduleSave();
+    this.deps.notifyChange('ax');
+    this.deps.recordMutation({
+      operationType: 'resolveApproval',
+      description: `Reopened approval ${id}`,
+      forward: this.deps.suppressed(() => {
+        this.applyAxState(applied);
+        this.deps.scheduleSave();
+        this.deps.notifyChange('ax');
+      }),
+      inverse: this.deps.suppressed(() => {
+        this.applyAxState(oldAxState);
+        this.deps.scheduleSave();
+        this.deps.notifyChange('ax');
+      }),
+    });
+    return applied.approvalGates.find((g) => g.id === id) ?? null;
+  }
+
   // ── Review annotations (canvas-bound) ─────────────────────────────
   getReviewAnnotations(): PmxAxReviewAnnotation[] {
     return this.getAxState().reviewAnnotations;
@@ -660,13 +712,33 @@ export class AxStateManager {
 
   /** Merge a declarative tool/prompt policy patch (canvas-bound, snapshotted). */
   setPolicy(
-    patch: { tools?: Partial<PmxAxPolicy['tools']>; prompt?: Partial<PmxAxPolicy['prompt']> },
+    patch: {
+      tools?: Partial<PmxAxPolicy['tools']>;
+      prompt?: Partial<PmxAxPolicy['prompt']>;
+      /** Replace semantics: an object sets the fence, `null` clears it, absent leaves it. */
+      scope?: { nodeIds: string[]; padding?: number } | null;
+      /** Per-key merge: an object sets that agent's territory, `null` clears it, absent keys keep theirs. */
+      agentScopes?: Record<string, { nodeIds: string[]; padding?: number } | null>;
+    },
     _options: { source?: PmxAxSource } = {},
   ): PmxAxPolicy {
     const oldAxState = this.getAxState();
+    const nodeIds = this.deps.getNodeIds();
+    const mergedAgentScopes: Record<string, unknown> = { ...oldAxState.policy.agentScopes };
+    for (const [key, fence] of Object.entries(patch.agentScopes ?? {})) {
+      if (fence === null) delete mergedAgentScopes[key];
+      else mergedAgentScopes[key] = { ...fence, nodeIds: fence.nodeIds.filter((id) => nodeIds.has(id)) };
+    }
     const merged = normalizeAxPolicy({
       tools: { ...oldAxState.policy.tools, ...(patch.tools ?? {}) },
       prompt: { ...oldAxState.policy.prompt, ...(patch.prompt ?? {}) },
+      scope:
+        patch.scope === undefined
+          ? oldAxState.policy.scope
+          : patch.scope === null
+            ? null
+            : { ...patch.scope, nodeIds: patch.scope.nodeIds.filter((id) => nodeIds.has(id)) },
+      agentScopes: mergedAgentScopes,
     });
     this.applyAxState({ ...oldAxState, policy: merged });
     const applied = this.getAxState();
@@ -783,11 +855,11 @@ export class AxStateManager {
     return { ...draft, seq: 0 };
   }
 
-  markSteeringDelivered(id: string): boolean {
+  markSteeringDelivered(id: string, consumer?: string | null): boolean {
     const db = this.deps.getDb();
     if (!db) return false;
     try {
-      const ok = markAxSteeringDeliveredInDB(db, id);
+      const ok = markAxSteeringDeliveredInDB(db, id, consumer);
       if (ok) this.deps.notifyChange('ax-timeline');
       return ok;
     } catch (error) {

package/src/server/ax-state.ts

@@ -1,4 +1,6 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
+import { clampGateTtlMs, DEFAULT_GATE_TTL_MS } from '../shared/approval-gates.js';
+import type { AxApprovalStatus, AxEventKind, AxWorkItemStatus } from '../shared/ax-kinds.js';
 import type { AgentContextNode } from './agent-context.js';
 
 export type PmxAxSource = 'agent' | 'amp' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
@@ -11,19 +13,10 @@ export interface PmxAxFocusState {
 }
 
 // ── New enums ──────────────────────────────────────────────────────
-export type PmxAxEventKind =
-  | 'prompt'
-  | 'assistant-message'
-  | 'tool-start'
-  | 'tool-result'
-  | 'failure'
-  | 'approval'
-  | 'steering'
-  | 'command'
-  | 'note';
+export type PmxAxEventKind = AxEventKind;
 export type PmxAxEvidenceKind = 'logs' | 'tool-result' | 'screenshot' | 'file' | 'diff' | 'test-output';
-export type PmxAxWorkItemStatus = 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
-export type PmxAxApprovalStatus = 'pending' | 'approved' | 'rejected';
+export type PmxAxWorkItemStatus = AxWorkItemStatus;
+export type PmxAxApprovalStatus = AxApprovalStatus;
 export type PmxAxReviewKind = 'comment' | 'finding';
 export type PmxAxReviewSeverity = 'info' | 'warning' | 'error';
 export type PmxAxReviewStatus = 'open' | 'resolved' | 'dismissed';
@@ -50,6 +43,8 @@ export interface PmxAxApprovalGate {
   status: PmxAxApprovalStatus;
   nodeIds: string[];
   createdAt: string;
+  /** When a still-pending gate auto-holds (unattended-approval policy). */
+  expiresAt: string | null;
   resolvedAt: string | null;
   resolution: string | null;
   source: PmxAxSource | null;
@@ -109,6 +104,8 @@ export interface PmxAxSteeringMessage {
   seq: number;
   message: string;
   delivered: boolean;
+  /** Broadcast pickups: which consumers marked this steer (per-consumer delivery). */
+  deliveredTo?: string[];
   createdAt: string;
   source: PmxAxSource | null;
   agentId: string | null;
@@ -192,6 +189,17 @@ export interface PmxAxDeliveryContext {
   pendingActivity: PendingAxActivityItem[];
 }
 
+/** Human ink on the board — freehand strokes and text notes, anchored to the nodes they overlap. */
+export interface PmxAxHumanAnnotation {
+  id: string;
+  type: string;
+  /** The human's words, when this is a text note (or a labelled stroke). */
+  text: string | null;
+  /** Nodes whose padded frame the annotation overlaps — what it is "on". */
+  onNodes: Array<{ id: string; title: string | null }>;
+  center: { x: number; y: number };
+}
+
 export interface PmxAxContext {
   version: 1;
   generatedAt: string;
@@ -208,6 +216,8 @@ export interface PmxAxContext {
   workItems: PmxAxWorkItem[];
   approvalGates: PmxAxApprovalGate[];
   reviewAnnotations: PmxAxReviewAnnotation[];
+  /** What the human drew/wrote on the board (the annotate tool) — not agent review comments. */
+  humanAnnotations: PmxAxHumanAnnotation[];
   elicitations: PmxAxElicitation[];
   modeRequests: PmxAxModeRequest[];
   policy: PmxAxPolicy;
@@ -322,6 +332,8 @@ const AX_EVENT_KINDS = new Set<PmxAxEventKind>([
   'steering',
   'command',
   'note',
+  'policy',
+  'yield',
 ]);
 
 // ── Activity ingestion (harness-forwarded tool/session events) ─────
@@ -396,15 +408,47 @@ export function listAxCommands(): PmxAxCommandDescriptor[] {
 // Declarative policy PMX stores and exposes; host adapters READ and enforce it.
 // PMX does not mutate host prompts or block tools itself. Default = empty (no
 // restrictions) — that is the conservative answer to "how much by default".
+/**
+ * Scope fence (rail-chrome-v2 design item 4): the region an attached agent
+ * may WRITE to — the fenced node set plus `padding` px around its bounding
+ * box for new nodes. Reads are never fenced. `null` = unscoped.
+ */
+export interface PmxAxScopeFence {
+  nodeIds: string[];
+  padding: number;
+}
+
+export const DEFAULT_SCOPE_FENCE_PADDING = 40;
+
 export interface PmxAxPolicy {
   tools: { allowed: string[]; excluded: string[]; approvalRequired: string[] };
   prompt: { systemAppend: string | null; mode: string | null };
+  scope: PmxAxScopeFence | null;
+  /**
+   * Per-agent territories (fleet orchestration): writer key (agentId when the
+   * write carries one, else its source label) → fence. Overrides `scope` for
+   * that writer; agents without an entry fall under the global fence.
+   */
+  agentScopes: Record<string, PmxAxScopeFence>;
 }
 
 export function createEmptyAxPolicy(): PmxAxPolicy {
   return {
     tools: { allowed: [], excluded: [], approvalRequired: [] },
     prompt: { systemAppend: null, mode: null },
+    scope: null,
+    agentScopes: {},
+  };
+}
+
+export function normalizeAxScopeFence(input: unknown): PmxAxScopeFence | null {
+  if (!isRecord(input)) return null;
+  const nodeIds = normalizeStringArray(input.nodeIds);
+  if (nodeIds.length === 0) return null;
+  const padding = Number(input.padding);
+  return {
+    nodeIds,
+    padding: Number.isFinite(padding) && padding >= 0 ? Math.min(400, padding) : DEFAULT_SCOPE_FENCE_PADDING,
   };
 }
 
@@ -426,8 +470,21 @@ export function normalizeAxPolicy(input: unknown): PmxAxPolicy {
       systemAppend: optionalString(prompt.systemAppend),
       mode: optionalString(prompt.mode),
     },
+    scope: normalizeAxScopeFence(input.scope),
+    agentScopes: normalizeAxAgentScopes(input.agentScopes),
   };
 }
+
+export function normalizeAxAgentScopes(input: unknown): Record<string, PmxAxScopeFence> {
+  if (!isRecord(input)) return {};
+  const out: Record<string, PmxAxScopeFence> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (!key.trim()) continue;
+    const fence = normalizeAxScopeFence(value);
+    if (fence) out[key.trim()] = fence;
+  }
+  return out;
+}
 const AX_EVIDENCE_KINDS = new Set<PmxAxEvidenceKind>([
   'logs',
   'tool-result',
@@ -437,7 +494,7 @@ const AX_EVIDENCE_KINDS = new Set<PmxAxEvidenceKind>([
   'test-output',
 ]);
 const AX_WORK_STATUSES = new Set<PmxAxWorkItemStatus>(['todo', 'in-progress', 'blocked', 'done', 'cancelled']);
-const AX_APPROVAL_STATUSES = new Set<PmxAxApprovalStatus>(['pending', 'approved', 'rejected']);
+const AX_APPROVAL_STATUSES = new Set<PmxAxApprovalStatus>(['pending', 'approved', 'rejected', 'held']);
 const AX_REVIEW_KINDS = new Set<PmxAxReviewKind>(['comment', 'finding']);
 const AX_REVIEW_SEVERITIES = new Set<PmxAxReviewSeverity>(['info', 'warning', 'error']);
 const AX_REVIEW_STATUSES = new Set<PmxAxReviewStatus>(['open', 'resolved', 'dismissed']);
@@ -654,6 +711,7 @@ export function normalizeAxApprovalGate(input: unknown, validNodeIds?: Set<strin
       : 'pending',
     nodeIds: normalizeNodeIds(input.nodeIds, validNodeIds),
     createdAt: normalizeTimestamp(input.createdAt) ?? nowIso(),
+    expiresAt: normalizeTimestamp(input.expiresAt),
     resolvedAt: normalizeTimestamp(input.resolvedAt),
     resolution: optionalString(input.resolution),
     source: normalizeSource(input.source),
@@ -795,10 +853,11 @@ export function createAxWorkItem(
 }
 
 export function createAxApprovalGate(
-  input: { title: string; detail?: string | null; action?: string | null; nodeIds?: string[] },
+  input: { title: string; detail?: string | null; action?: string | null; nodeIds?: string[]; ttlMs?: number },
   source: PmxAxSource | null,
   validNodeIds?: Set<string>,
 ): PmxAxApprovalGate {
+  const created = Date.now();
   return {
     id: axId('appr'),
     title: input.title,
@@ -806,13 +865,19 @@ export function createAxApprovalGate(
     action: input.action ?? null,
     status: 'pending',
     nodeIds: normalizeNodeIds(input.nodeIds, validNodeIds),
-    createdAt: nowIso(),
+    createdAt: new Date(created).toISOString(),
+    expiresAt: new Date(created + clampGateTtlMs(input.ttlMs, defaultGateTtlMs())).toISOString(),
     resolvedAt: null,
     resolution: null,
     source,
   };
 }
 
+/** Server default for a gate's TTL: `PMX_CANVAS_GATE_TTL_MS`, else five minutes. */
+export function defaultGateTtlMs(): number {
+  return clampGateTtlMs(process.env.PMX_CANVAS_GATE_TTL_MS, DEFAULT_GATE_TTL_MS);
+}
+
 export function createAxReviewAnnotation(
   input: {
     body: string;
@@ -953,6 +1018,7 @@ export function buildAxContext(input: {
   workItems: PmxAxWorkItem[];
   approvalGates: PmxAxApprovalGate[];
   reviewAnnotations: PmxAxReviewAnnotation[];
+  humanAnnotations: PmxAxHumanAnnotation[];
   elicitations: PmxAxElicitation[];
   modeRequests: PmxAxModeRequest[];
   policy: PmxAxPolicy;
@@ -975,6 +1041,7 @@ export function buildAxContext(input: {
     workItems: input.workItems,
     approvalGates: input.approvalGates,
     reviewAnnotations: input.reviewAnnotations,
+    humanAnnotations: input.humanAnnotations,
     elicitations: input.elicitations,
     modeRequests: input.modeRequests,
     policy: input.policy,

package/src/server/ax-wait.ts

@@ -54,3 +54,36 @@ export async function waitForAxResolution<T extends { status: string }>(opts: {
     opts.signal?.addEventListener('abort', onSettle, { once: true });
   });
 }
+
+/**
+ * Block until `ready()` turns true after a change on `channel` (default
+ * 'ax-timeline'), or the timeout elapses. The steering long-poll: the gate
+ * waiter above is item/status-shaped; this one waits on a plain condition —
+ * the reactive loop for agent hosts that cannot be woken from outside (their
+ * model only runs while their host gives it a turn, so one call parks here
+ * instead of burning that turn on tight polling).
+ */
+export async function waitForAxCondition(opts: {
+  ready: () => boolean;
+  timeoutMs: number;
+  channel?: string;
+}): Promise<void> {
+  const timeoutMs = Math.max(0, Math.min(opts.timeoutMs, AX_WAIT_MAX_MS));
+  if (timeoutMs === 0 || opts.ready()) return;
+  const channel = opts.channel ?? 'ax-timeline';
+  await new Promise<void>((resolve) => {
+    let done = false;
+    const finish = (): void => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      dispose();
+      resolve();
+    };
+    const check = (type: string): void => {
+      if (type === channel && opts.ready()) finish();
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    const dispose = canvasState.onChange(check);
+  });
+}