pmx-canvas 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to `pmx-canvas` are documented here. This project follows
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-06-17
+
+### Fixed
+
+- **Compact AX context surfaces the NEWEST steering first (report #57).** The
+  `delivery.pendingSteering` lead block on `GET /api/canvas/ax/context` /
+  `canvas://ax-context` returned the OLDEST 10 undelivered steers, so on a long-lived
+  board a fresh steer was buried behind old unacked ones and never appeared in the
+  compact block. It now returns the **newest** undelivered steering first (capped at
+  10), so a fresh steer is always visible. The FIFO claim/ack delivery queue
+  (`/api/canvas/ax/delivery/pending`, `canvas_ax_delivery { action: "claim" }`) is
+  unchanged — still oldest-first for ordered processing.
+
+### Added
+
+- **AX context delivery backlog counts (report #57).** `delivery` now includes
+  `totalPending` (undelivered steering for the consumer, loop-safe) and `omittedPending`
+  (`= totalPending − pendingSteering.length`), so an agent can tell the compact block
+  omitted a backlog and drain the full FIFO queue when `omittedPending > 0`. Additive,
+  non-breaking.
+- **Blessed AX HTML Control Surface recipe (report #60).** New
+  `skills/pmx-canvas/references/ax-html-control-surface.md` (linked from `SKILL.md`): a
+  copy-paste-safe template (awaited `emit` + live ack display + `pmx-ax-update`
+  reflection) plus the three footguns that make a hand-rolled AX node look inert — the
+  sandboxed opaque-origin iframe throws on `localStorage`/`sessionStorage`/cookies,
+  `emit` must be awaited, and `ax.steer` is recorded (queued), not delivered.
+
+### Docs
+
+- **Canvas-origin steering does not wake the active agent by itself (report #59).** The
+  host-adapter contract, `SKILL.md`, and the GitHub Copilot adapter reference now state
+  plainly that a browser-origin `ax.steer` (and its `ok:true` emit ack) is *queued*, not
+  pushed into the live session; the wake is host-adapter-owned (drain
+  `canvas_ax_delivery { action: "claim" }` → native send → `mark`), and a steering button
+  must be labeled "queued for the agent's next turn." Adapters should read steering from
+  the compact `delivery.pendingSteering` block, not `timeline.pendingSteering`.
+
 ## [0.2.0] - 2026-06-16
 
 ### Breaking
@@ -2234,6 +2271,7 @@ otherwise have to discover by trial and error.
 - Regression coverage for snapshot flat-`id` aliases on both MCP and
   HTTP surfaces, plus async / top-level-`await` WebView script bodies.
 
+[0.2.1]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.1
 [0.2.0]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.0
 [0.1.36]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.36
 [0.1.35]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.35

package/dist/types/server/ax-state-manager.d.ts

@@ -245,6 +245,17 @@ export declare class AxStateManager {
         consumer?: string;
         limit?: number;
     }): PmxAxSteeringMessage[];
+    /**
+     * NEWEST undelivered steering first, for the compact AX context lead block (report
+     * #57) — so a fresh steer is visible even behind a long backlog. Loop-safe like
+     * getPendingSteering, but ordered DESC instead of the FIFO ASC delivery queue.
+     */
+    getPendingSteeringForContext(options?: {
+        consumer?: string;
+        limit?: number;
+    }): PmxAxSteeringMessage[];
+    /** Total undelivered steering for a consumer (loop-safe), for the context backlog counts. */
+    getPendingSteeringCount(consumer?: string): number;
     getAxTimelineSummary(): PmxAxTimelineSummary;
     getAxTimeline(q?: AxTimelineQuery): {
         events: PmxAxEvent[];

package/dist/types/server/ax-state.d.ts

@@ -145,6 +145,8 @@ export interface PendingAxActivityItem {
 }
 export interface PmxAxDeliveryContext {
     pendingSteering: PmxAxSteeringMessage[];
+    totalPending: number;
+    omittedPending: number;
     pendingActivity: PendingAxActivityItem[];
 }
 export interface PmxAxContext {

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

@@ -53,6 +53,19 @@ export declare function loadPendingAxSteeringFromDB(db: Database, options?: {
     consumer?: string;
     limit?: number;
 }): PmxAxSteeringMessage[];
+/**
+ * NEWEST undelivered steering first (report #57) for the compact AX context lead
+ * block — so a fresh steer is visible even behind a long backlog. Loop-safe: excludes
+ * the consumer's own steering in SQL so the LIMIT applies after loop-prevention.
+ * Distinct from loadPendingAxSteeringFromDB (FIFO oldest-first) which the claim/ack
+ * delivery queue uses for ordered processing.
+ */
+export declare function loadNewestPendingAxSteeringFromDB(db: Database, options?: {
+    consumer?: string;
+    limit?: number;
+}): PmxAxSteeringMessage[];
+/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own). */
+export declare function countPendingAxSteeringFromDB(db: Database, consumer?: string): number;
 export declare function loadAxTimelineSummaryFromDB(db: Database): PmxAxTimelineSummary;
 export declare function upsertAxHostCapabilityToDB(db: Database, cap: PmxAxHostCapability): void;
 export declare function loadAxHostCapabilityFromDB(db: Database): PmxAxHostCapability | null;

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

@@ -431,6 +431,11 @@ declare class CanvasStateManager {
         consumer?: string;
         limit?: number;
     }): PmxAxSteeringMessage[];
+    getPendingSteeringForContext(options?: {
+        consumer?: string;
+        limit?: number;
+    }): PmxAxSteeringMessage[];
+    getPendingSteeringCount(consumer?: string): number;
     getAxTimelineSummary(): PmxAxTimelineSummary;
     getAxTimeline(q?: AxTimelineQuery): {
         events: PmxAxEvent[];

package/docs/ax-host-adapter-contract.md

@@ -42,7 +42,25 @@ message; it does **not** wake the agent. It reaches the next turn only when:
 
 The `delivery` lead block (`GET /api/canvas/ax/context?consumer=<id>`) is the
 robustness hedge: it's compact and sits above the full dump, so an adapter can inject
-it un-truncated even on a busy board where the full context is clipped.
+it un-truncated even on a busy board where the full context is clipped. Its
+`pendingSteering` is **newest-first** (most recent at index 0), capped at 10, so a
+*fresh* steer is always visible even behind a long backlog of old unacked steers
+(report #57); `delivery.totalPending` / `delivery.omittedPending` tell the agent how
+many more are queued so it can drain the FIFO `…/delivery/pending` endpoint when the
+count is non-zero. **Adapters should read `delivery.pendingSteering`** (this compact,
+count-bearing block), not `timeline.pendingSteering`.
+
+### Canvas-origin steering does not wake the agent by itself (#59)
+
+Recording a browser-origin `ax.steer` (and the `ok:true` ack a surface button gets —
+report #55) means the steer is **queued on the timeline**, not delivered into a live
+agent turn. PMX deliberately does not import a host SDK, so the *wake* — turning a
+queued steer into a visible turn — is **adapter-owned**: a cooperating host adapter
+must drain `…/delivery/pending?consumer=<id>` and call its native send (e.g.
+`copilotSession.send`), then `…/delivery/<id>/mark` it. Until an adapter wires that,
+canvas-origin steering is delivered on the next human turn, not pushed. A steering
+surface should therefore label its button honestly ("queued for the agent's next
+turn"), never imply it interrupts the agent now.
 
 ## The two primitives that close the loop
 

package/docs/http-api.md

@@ -246,6 +246,10 @@ curl "http://localhost:4313/api/canvas/ax/mode/<id>?waitMs=30000"
 
 # Context — optional ?consumer= filters the compact, loop-safe `delivery` lead block
 # (undelivered steering + open work/approvals it can act on) for per-turn injection.
+# `delivery.pendingSteering` is NEWEST-first (most recent first), capped at 10, so a
+# fresh steer is visible even behind a backlog; `delivery.totalPending` /
+# `delivery.omittedPending` report how many more are queued. Drain the full FIFO
+# (oldest-first) backlog via /api/canvas/ax/delivery/pending when omittedPending > 0.
 curl "http://localhost:4313/api/canvas/ax/context?consumer=copilot"
 
 # Commands — list the registry, invoke a command (records a `command` agent-event)

package/docs/mcp.md

@@ -157,7 +157,7 @@ Individual bundled skills are also readable at `canvas://skills/<name>`.
 |----------|-------------|
 | `canvas://pinned-context` | Content of pinned nodes + nearby unpinned neighbors |
 | `canvas://ax` | PMX AX state: focus, work items, approval gates, review annotations |
-| `canvas://ax-context` | Agent-readable pinned and focused AX context, plus timeline summary and host capability |
+| `canvas://ax-context` | Agent-readable pinned and focused AX context, plus a compact `delivery` lead block (`pendingSteering` newest-first + `totalPending`/`omittedPending` counts), timeline summary, and host capability |
 | `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations, elicitations, mode requests, and tool/prompt policy |
 | `canvas://ax-timeline` | Bounded AX timeline: recent agent-events, evidence, and steering messages |
 | `canvas://ax-pending-steering` | Undelivered steering an adapterless MCP client can claim, act on, and mark delivered |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",

package/skills/pmx-canvas/SKILL.md

@@ -889,15 +889,23 @@ nodes.
     live. Clients that **poll** instead should poll `canvas_ax_delivery { action: "claim" }` —
     `pendingActivity` is how non-steering browser changes reach them. Only steering
     flows through the claim/ack queue.
-  - **Steering is gated, not pushed.** A surface button that emits `ax.steer`
-    enqueues a steer — it does NOT wake the agent. With a prompt-injecting host
-    adapter (e.g. Copilot), it reaches the next turn only when (1) the **pin/focus
-    gate is open** (something pinned or focused — so keep a steering board pinned, or
-    have its button also emit `ax.focus.set` on itself), (2) a **human message** fires
-    the turn, and (3) the agent **acts then acks** (`canvas_ax_delivery { action: "mark" }`),
-    or the steer re-injects every gated turn. `GET /api/canvas/ax/context?consumer=<id>` adds
-    a compact, loop-safe `delivery: { pendingSteering, pendingActivity }` lead block an
-    adapter can inject un-truncated, so steering survives the full-context char clip.
+  - **Steering is gated, not pushed (and does NOT wake the agent).** A surface button
+    that emits `ax.steer` *records/queues* a steer (the `ok:true` emit ack means
+    "recorded", not "the agent woke") — it does NOT interrupt or notify the active
+    session. With a prompt-injecting host adapter (e.g. Copilot), it reaches the next
+    turn only when (1) the **pin/focus gate is open** (something pinned or focused — so
+    keep a steering board pinned, or have its button also emit `ax.focus.set` on
+    itself), (2) a **human message** fires the turn, and (3) the agent **acts then acks**
+    (`canvas_ax_delivery { action: "mark" }`), or the steer re-injects every gated turn.
+    Immediate wake (turning a queued steer into a visible turn) is **host-adapter-owned**
+    — the adapter must drain `canvas_ax_delivery { action: "claim" }` and call its native
+    send. So a steering button should label itself honestly ("queued for the agent's next
+    turn"), never imply it steers the agent *now*. `GET /api/canvas/ax/context?consumer=<id>`
+    adds a compact, loop-safe `delivery: { pendingSteering, totalPending, omittedPending,
+    pendingActivity }` lead block an adapter injects un-truncated; `pendingSteering` is
+    **newest-first** (most recent first), capped at 10, so a fresh steer is visible even
+    behind a backlog, and the counts say how many more to drain from the FIFO
+    `canvas_ax_delivery { action: "claim" }` queue (which stays oldest-first).
 - **Activity ingestion (bidirectional board):** a host adapter forwards the agent's
   tool/session events with `canvas_ingest_activity` (standalone; HTTP `POST /api/canvas/ax/activity`)
   and the board auto-reacts — `failure`/`error` (or `outcome:"failure"`) → a blocked
@@ -1028,6 +1036,20 @@ This is the right home for a deliberate, interactive AX experience — not the
 native node buttons. Any agent (via MCP/SDK) can also create/update the same work
 items, and the board reflects them live.
 
+> **Authoring an AX HTML node? Use the blessed, copy-paste-safe recipe in
+> [`references/ax-html-control-surface.md`](references/ax-html-control-surface.md)**
+> and avoid the common footguns:
+> - **The iframe is sandboxed opaque-origin** (no `allow-same-origin`): `localStorage`,
+>   `sessionStorage`, and cookies **throw** and will halt your startup script, making the
+>   node look inert. Keep state in plain JS variables / `window.PMX_AX.state`, or wrap any
+>   storage access in `try/catch`.
+> - **`window.PMX_AX.emit` is async — `await` it** (or use `.then`/`window.PMX_AX.on('ack')`);
+>   don't read a result synchronously. It's injected only when the node is opted in
+>   (`axCapabilities.enabled = true`).
+> - **`ax.steer` is recorded, not delivered** — a successful emit means the steer is
+>   *queued for the agent's next turn*, not that the agent woke (see "Steering is gated").
+>   Label steering buttons accordingly.
+
 > Security note: an AX-enabled surface can READ the whole canvas AX board (all
 > work items, focus, approval gates, etc. — human review comment text is redacted),
 > while its EMITS are clamped to its own node. Under the single-workspace

package/skills/pmx-canvas/references/ax-html-control-surface.md

@@ -0,0 +1,93 @@
+# AX HTML Control Surface — a blessed, copy-paste-safe recipe
+
+A canvas `html` node can be a live **AX control surface**: it emits AX interactions
+(create work, request approval, steer the agent, …) and reflects the current AX board
+back, all from inside the sandboxed iframe. The bridge is already injected for you —
+you do **not** need to read `axToken` from the URL or hand-post `pmx-canvas-ax`
+messages. Just opt the node in and use `window.PMX_AX`.
+
+## Opt in
+
+```js
+// MCP / SDK
+canvas_add_html_node({
+  title: "AX Control Room",
+  html: "<!-- see below -->",
+  axCapabilities: { enabled: true, allowed: ["ax.work.create", "ax.steer"] },
+});
+// HTTP: POST /api/canvas/node  { type:"html", title, html, axCapabilities }  (top-level html + axCapabilities both accepted)
+```
+
+Without `axCapabilities.enabled = true`, `window.PMX_AX` is **not** injected — the node
+renders but can't emit. `allowed` narrows what it may emit (never escalates the type's
+ceiling). Flip an existing node on with `canvas_node({ action: "update", id, axCapabilities: { enabled: true, allowed: [...] } })`.
+
+## Three footguns (this is why a hand-rolled node looks "inert")
+
+1. **The iframe is sandboxed opaque-origin** (no `allow-same-origin`). `localStorage`,
+   `sessionStorage`, and `document.cookie` **throw** — and an uncaught throw at script
+   start aborts the whole script, so the node renders blank/inert. Keep state in plain
+   JS variables (or `window.PMX_AX.state`); if you must touch storage, wrap it in
+   `try/catch`.
+2. **`window.PMX_AX.emit(type, payload)` is async.** It returns a Promise that resolves
+   with the result once the canvas acks it. `await` it (or `.then` / `window.PMX_AX.on('ack', cb)`).
+   Reading a result synchronously gets you `undefined`.
+3. **`ax.steer` is recorded, not delivered.** A successful emit (`{ ok: true }`) means
+   the steer was **queued** on the timeline — it does **not** wake or notify the active
+   agent. A cooperating host adapter must drain the delivery queue and call its native
+   send to create a visible turn (host-owned). Otherwise the steer is picked up on the
+   human's next turn. Label steering buttons honestly ("Queued for the agent's next turn").
+
+## Drop-in template (work + steer, with ack + live reflection)
+
+```html
+<style>
+  body { font: 13px system-ui; margin: 0; padding: 12px; }
+  button { cursor: pointer; }
+  #s { margin-left: 8px; color: #6b7280; }
+  ul { padding-left: 18px; }
+</style>
+<button id="add">+ Work item</button>
+<button id="steer">Steer agent</button>
+<span id="s"></span>
+<ul id="q"></ul>
+<script>
+  // In-memory only — NO localStorage/sessionStorage/cookies (sandboxed: they throw).
+  const $ = (id) => document.getElementById(id);
+  const flash = (msg) => { $('s').textContent = msg; setTimeout(() => { $('s').textContent = ''; }, 1500); };
+
+  function render(state) {
+    const items = (state && state.workItems) || [];
+    $('q').innerHTML = items.map((w) => '<li>[' + w.status + '] ' + w.title + '</li>').join('');
+  }
+
+  $('add').onclick = async () => {
+    const r = await window.PMX_AX.emit('ax.work.create', { title: 'New task' });
+    flash(r && r.ok ? 'queued ✓' : ('failed: ' + (r && (r.error || r.code))));
+  };
+  $('steer').onclick = async () => {
+    const r = await window.PMX_AX.emit('ax.steer', { message: 'Prioritize the auth refactor' });
+    // Honest: recorded/queued, NOT delivered to the live agent.
+    flash(r && r.ok ? 'queued for next turn ✓' : 'failed');
+  };
+
+  // Reflect: seeded once at load, then live via the pmx-ax-update event.
+  render(window.PMX_AX && window.PMX_AX.state);
+  window.addEventListener('pmx-ax-update', (e) => render(e.detail));
+</script>
+```
+
+## API surface (injected by PMX when opted in)
+
+- `window.PMX_AX.emit(type, payload) → Promise<{ ok, primitive?, status?, code?, error? }>`
+  — `ok:true` on accept; `ok:false` with `code`/`error` on reject; falls back to an
+  `ax-ack-timeout` result after 10s so `await` never hangs.
+- `window.PMX_AX.on('ack', (result, interaction) => …)` — also fires a `pmx-ax-ack`
+  CustomEvent; use instead of `await` if you prefer a listener.
+- `window.PMX_AX.state` — compact board snapshot `{ focus, workItems, approvalGates,
+  reviewAnnotations, elicitations, modeRequests, policy }` (human review text redacted).
+- `pmx-ax-update` window event — fires with the fresh snapshot on every AX change.
+
+Allowed `type`s are gated per node capability (see the node-capability matrix in
+`SKILL.md`). Emits are clamped to the surface's own node; the server re-validates every
+interaction — the bridge is convenience, not a trust boundary.

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -52,20 +52,36 @@ panel.
 ### Agent behavior — steering is gated, not pushed
 
 `onUserPromptSubmitted` injects the whole `/api/canvas/ax/context` (pins, focus, work
-items, approval gates, and `timeline.pendingSteering`) as hidden context — but only
-when the **pin/focus gate is open** (`pinned.count > 0 || focus.nodeIds.length > 0`),
-and it is clipped to a char budget. Three consequences the adapter/agent must honor:
+items, approval gates, and the compact `delivery` lead block) as hidden context — but
+only when the **pin/focus gate is open** (`pinned.count > 0 || focus.nodeIds.length > 0`),
+and it is clipped to a char budget. Read steering from **`delivery.pendingSteering`**
+(the compact, count-bearing block — newest-first, capped at 10), not the full
+`timeline.pendingSteering`. Three consequences the adapter/agent must honor:
 
 1. A steering board must **stay pinned** (or its button must also emit `ax.focus.set`
    on the board node) to hold the gate open.
 2. A sandbox button click does **not** wake a turn — a human message does. The click
    only enqueues the steer.
-3. The agent must **act on injected `pendingSteering` / `pendingActivity` and then ack**
-   (`canvas_ax_delivery { action: "mark" }`), or it re-injects every gated turn.
+3. The agent must **act on injected `delivery.pendingSteering` / `pendingActivity` and
+   then ack** (`canvas_ax_delivery { action: "mark" }`), or it re-injects every gated turn.
 
-To be robust to the char clip, prefer injecting the compact loop-safe lead block from
+To be robust to the char clip, prefer injecting that compact loop-safe lead block from
 `GET /api/canvas/ax/context?consumer=copilot` (`delivery.pendingSteering` +
-`delivery.pendingActivity`) **above** the full dump.
+`delivery.totalPending` / `delivery.omittedPending` + `delivery.pendingActivity`)
+**above** the full dump. When `omittedPending > 0`, drain the full FIFO backlog from
+`canvas_ax_delivery { action: "claim", consumer: "copilot" }` (oldest-first).
+
+#### Waking the agent from a canvas steer (#59) — adapter-owned
+
+Recording a browser-origin `ax.steer` does **not** wake the active session by itself
+(report #59); PMX only queues it (the `ok:true` emit ack = "recorded", not "delivered").
+To make a canvas **Steer** button actually create a visible turn, the adapter must, on
+its own cadence (e.g. an SSE subscription or poll), **drain**
+`canvas_ax_delivery { action: "claim", consumer: "copilot" }`, call the host's native
+send (`copilotSession.send` / the working `send_instruction` path) with each steer, then
+`canvas_ax_delivery { action: "mark" }` it (loop-safe). This wake is intentionally
+host-owned — PMX never imports the host SDK. Until the adapter wires it, a steering
+button must be labeled "queued for the agent's next turn", not "steer now".
 
 ### Closing the loop (optional, recommended)
 

package/src/server/ax-context.ts

@@ -79,10 +79,17 @@ export function buildCanvasAxContext(consumer?: string): PmxAxContext {
   const focusNodes = ax.focus.nodeIds
     .map((id) => canvasState.getNode(id))
     .filter((node): node is CanvasNodeState => node !== undefined);
+  // Report #57: surface the NEWEST undelivered steering (so a fresh steer is visible
+  // even behind a long backlog) + counts so the agent can detect an omitted backlog.
+  // The FIFO claim/ack queue (getPendingSteering) stays oldest-first for processing.
+  const pendingSteering = canvasState.getPendingSteeringForContext({ consumer, limit: AX_CONTEXT_STEERING_LIMIT });
+  const totalPending = canvasState.getPendingSteeringCount(consumer);
   return buildAxContext({
     layout,
     delivery: {
-      pendingSteering: canvasState.getPendingSteering({ consumer, limit: AX_CONTEXT_STEERING_LIMIT }),
+      pendingSteering,
+      totalPending,
+      omittedPending: Math.max(0, totalPending - pendingSteering.length),
       pendingActivity: buildPendingAxActivity(ax, consumer),
     },
     pinned: buildCanvasAxPinnedContext(),

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

@@ -29,6 +29,8 @@ import {
   loadAxEvidenceFromDB,
   loadAxSteeringFromDB,
   loadPendingAxSteeringFromDB,
+  loadNewestPendingAxSteeringFromDB,
+  countPendingAxSteeringFromDB,
   loadAxTimelineSummaryFromDB,
   upsertAxHostCapabilityToDB,
   loadAxHostCapabilityFromDB,
@@ -790,6 +792,22 @@ export class AxStateManager {
     return db ? loadPendingAxSteeringFromDB(db, options) : [];
   }
 
+  /**
+   * NEWEST undelivered steering first, for the compact AX context lead block (report
+   * #57) — so a fresh steer is visible even behind a long backlog. Loop-safe like
+   * getPendingSteering, but ordered DESC instead of the FIFO ASC delivery queue.
+   */
+  getPendingSteeringForContext(options: { consumer?: string; limit?: number } = {}): PmxAxSteeringMessage[] {
+    const db = this.deps.getDb();
+    return db ? loadNewestPendingAxSteeringFromDB(db, options) : [];
+  }
+
+  /** Total undelivered steering for a consumer (loop-safe), for the context backlog counts. */
+  getPendingSteeringCount(consumer?: string): number {
+    const db = this.deps.getDb();
+    return db ? countPendingAxSteeringFromDB(db, consumer) : 0;
+  }
+
   getAxTimelineSummary(): PmxAxTimelineSummary {
     const db = this.deps.getDb();
     return db

package/src/server/ax-state.ts

@@ -168,8 +168,16 @@ export interface PendingAxActivityItem {
 }
 
 // ── Delivery lead block (compact, un-truncated; for per-turn injection) ──
+// `pendingSteering` here is NEWEST-first (most recent at index 0), capped at
+// AX_CONTEXT_STEERING_LIMIT, so a fresh steer is always visible even behind a long
+// backlog (report #57). This is "what's new?" awareness — distinct from the FIFO
+// claim/ack delivery queue (`/api/canvas/ax/delivery/pending`, getPendingSteering),
+// which stays OLDEST-first for ordered processing. The counts let an agent detect a
+// backlog the compact block omits.
 export interface PmxAxDeliveryContext {
   pendingSteering: PmxAxSteeringMessage[];
+  totalPending: number;
+  omittedPending: number;
   pendingActivity: PendingAxActivityItem[];
 }
 

package/src/server/canvas-db.ts

@@ -921,6 +921,41 @@ export function loadPendingAxSteeringFromDB(
     .filter((s): s is PmxAxSteeringMessage => s !== null);
 }
 
+/**
+ * NEWEST undelivered steering first (report #57) for the compact AX context lead
+ * block — so a fresh steer is visible even behind a long backlog. Loop-safe: excludes
+ * the consumer's own steering in SQL so the LIMIT applies after loop-prevention.
+ * Distinct from loadPendingAxSteeringFromDB (FIFO oldest-first) which the claim/ack
+ * delivery queue uses for ordered processing.
+ */
+export function loadNewestPendingAxSteeringFromDB(
+  db: Database,
+  options: { consumer?: string; limit?: number } = {},
+): PmxAxSteeringMessage[] {
+  interface Row { seq: number; id: string; message: string; delivered: number; created_at: string; source: string | null }
+  const limit = clampTimelineLimit(options.limit);
+  const rows = options.consumer
+    ? db.query<Row, [string, number]>(
+        'SELECT * FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?) ORDER BY seq DESC LIMIT ?',
+      ).all(options.consumer, limit)
+    : db.query<Row, [number]>(
+        'SELECT * FROM ax_steering WHERE delivered = 0 ORDER BY seq DESC LIMIT ?',
+      ).all(limit);
+  return rows
+    .map((r) => normalizeAxSteeringMessage({ ...r, createdAt: r.created_at, delivered: r.delivered === 1 }))
+    .filter((s): s is PmxAxSteeringMessage => s !== null);
+}
+
+/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own). */
+export function countPendingAxSteeringFromDB(db: Database, consumer?: string): number {
+  const n = consumer
+    ? db.query<{ n: number }, [string]>(
+        'SELECT COUNT(*) AS n FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?)',
+      ).get(consumer)?.n
+    : db.query<{ n: number }, []>('SELECT COUNT(*) AS n FROM ax_steering WHERE delivered = 0').get()?.n;
+  return Number(n ?? 0);
+}
+
 function countRows(db: Database, table: 'ax_events' | 'ax_evidence' | 'ax_steering'): number {
   return Number(db.query<{ n: number }, []>(`SELECT COUNT(*) AS n FROM ${table}`).get()?.n ?? 0);
 }

package/src/server/canvas-state.ts

@@ -1957,6 +1957,14 @@ class CanvasStateManager {
     return this.ax.getPendingSteering(options);
   }
 
+  getPendingSteeringForContext(options: { consumer?: string; limit?: number } = {}): PmxAxSteeringMessage[] {
+    return this.ax.getPendingSteeringForContext(options);
+  }
+
+  getPendingSteeringCount(consumer?: string): number {
+    return this.ax.getPendingSteeringCount(consumer);
+  }
+
   getAxTimelineSummary(): PmxAxTimelineSummary {
     return this.ax.getAxTimelineSummary();
   }