zcode-acp-server 0.47.10 → 0.48.1

package/dist/workflow/poller.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Dynamic-workflow run progress poller.
+ *
+ * The backend strips per-actor/per-node workflow progress from the v3 stream
+ * (session-mapper filters `dynamic_workflow_run_progress`; the authoritative
+ * projection lives behind the v4 conversation API), so an ACP client would see
+ * the CreateWorkflow card sit silent for the whole run. This module re-attaches
+ * progress by polling the v4 journal query and folding concise progress lines
+ * into the card as `tool_call_update` notifications.
+ *
+ *   v4/conversation/workflowRunEvents {sessionId, runId, afterSequence, limit}
+ *     → {events: [{sequence, type, payload, truncated?}], hasMore}
+ *
+ * The cursor is the journal sequence (never invalidated), so the poll is
+ * stateless and safe to re-issue. Runs are armed by the background-task
+ * listener (taskKind "workflow", taskId ≡ runId) — the SINGLE arm point,
+ * covering model-launched runs (visible CreateWorkflow card) and
+ * settings-launched ones (synthetic tool call, no live card — the fallback
+ * [background] card is the fold target). Emissions are append DELTAS (only
+ * the lines added since the previous emission) fanned out per-alias via
+ * `server.notifyByZcodeSid`, covering both turn-internal and turn-external
+ * runs.
+ *
+ * Everything here is best-effort: request() resolves `{error}` instead of
+ * throwing, and every failure path only logs — never into the event loop.
+ */
+import type { ZcodeAcpServer } from "../server.js";
+/** Poll cadence (setTimeout chain, timers unref'd). Injectable for tests. */
+export declare const WORKFLOW_POLL_INTERVAL_MS = 3000;
+/** One v4 journal event (transport.ts:599-646). */
+interface WorkflowRunEvent {
+    sequence: number;
+    type: string;
+    payload?: Record<string, unknown>;
+    truncated?: boolean;
+}
+/**
+ * Reduce one journal event to a concise progress line, or null when the event
+ * is chatty (log/report/usage updates) and must not reach the card. Payload
+ * fields are read defensively — engine payload shapes are not part of the v4
+ * wire contract we consume, and raw ids (actorSessionId) are never printed.
+ */
+export declare function workflowEventLine(ev: WorkflowRunEvent): string | null;
+/**
+ * Arm the progress poller for a workflow run. Single-flight per runId: a
+ * re-arm (task status updates repeat the launch payload) is a no-op. The
+ * first poll fires after one interval.
+ */
+export declare function armWorkflowRunPoller(server: ZcodeAcpServer, zcodeSid: string, opts: {
+    runId: string;
+    toolCallId: string;
+    intervalMs?: number;
+}): void;
+/** Stop the poller for one run (background task reached a terminal status). */
+export declare function stopWorkflowRunPoller(runId: string): void;
+/** Stop every poller (bridge shutdown — mirrors background-task shutdown records). */
+export declare function stopAllWorkflowRunPollers(): void;
+/**
+ * Stop every poller armed under one backend session (the session/close
+ * cleanup path). Best-effort, never throws — a closed session's journal
+ * answers can outlive the runtime, and polling it would only end at the hard
+ * cap with a stray timeout notice for a conversation nobody can see anymore.
+ */
+export declare function stopPollersForSession(zcodeSid: string): void;
+/** Test/observability hook: is a poller currently armed for this runId? */
+export declare function workflowPollerActive(runId: string): boolean;
+export {};
+//# sourceMappingURL=poller.d.ts.map

package/dist/workflow/poller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poller.d.ts","sourceRoot":"","sources":["../../src/workflow/poller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAiB9C,mDAAmD;AACnD,UAAU,gBAAgB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AA+BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAqCrE;AA6JD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D,IAAI,CAsBN;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAKzD;AAED,sFAAsF;AACtF,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAI5D;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE3D"}

package/dist/workflow/poller.js

@@ -0,0 +1,290 @@
+/**
+ * Dynamic-workflow run progress poller.
+ *
+ * The backend strips per-actor/per-node workflow progress from the v3 stream
+ * (session-mapper filters `dynamic_workflow_run_progress`; the authoritative
+ * projection lives behind the v4 conversation API), so an ACP client would see
+ * the CreateWorkflow card sit silent for the whole run. This module re-attaches
+ * progress by polling the v4 journal query and folding concise progress lines
+ * into the card as `tool_call_update` notifications.
+ *
+ *   v4/conversation/workflowRunEvents {sessionId, runId, afterSequence, limit}
+ *     → {events: [{sequence, type, payload, truncated?}], hasMore}
+ *
+ * The cursor is the journal sequence (never invalidated), so the poll is
+ * stateless and safe to re-issue. Runs are armed by the background-task
+ * listener (taskKind "workflow", taskId ≡ runId) — the SINGLE arm point,
+ * covering model-launched runs (visible CreateWorkflow card) and
+ * settings-launched ones (synthetic tool call, no live card — the fallback
+ * [background] card is the fold target). Emissions are append DELTAS (only
+ * the lines added since the previous emission) fanned out per-alias via
+ * `server.notifyByZcodeSid`, covering both turn-internal and turn-external
+ * runs.
+ *
+ * Everything here is best-effort: request() resolves `{error}` instead of
+ * throwing, and every failure path only logs — never into the event loop.
+ */
+import { log } from "../utils.js";
+/** Poll cadence (setTimeout chain, timers unref'd). Injectable for tests. */
+export const WORKFLOW_POLL_INTERVAL_MS = 3000;
+/** Hard cap: no run polls longer than this, whatever the backend says. */
+const WORKFLOW_POLL_HARD_TIMEOUT_MS = 10 * 60_000;
+/** Consecutive poll failures tolerated before the poller gives up. */
+const MAX_CONSECUTIVE_ERRORS = 5;
+/** Page size per workflowRunEvents request (upstream cap 500). */
+const EVENTS_PAGE_LIMIT = 100;
+/** Pages drained back-to-back per tick while `hasMore` (runaway guard). */
+const MAX_PAGES_PER_TICK = 50;
+/** Cap on accumulated progress lines (keep first/last, drop the middle). */
+const MAX_LINES = 200;
+/** Active runs keyed by runId (taskId ≡ runId upstream — one key per run). */
+const activeRuns = new Map();
+/**
+ * Reduce one journal event to a concise progress line, or null when the event
+ * is chatty (log/report/usage updates) and must not reach the card. Payload
+ * fields are read defensively — engine payload shapes are not part of the v4
+ * wire contract we consume, and raw ids (actorSessionId) are never printed.
+ */
+export function workflowEventLine(ev) {
+    const p = ev.payload ?? {};
+    const str = (k) => typeof p[k] === "string" ? p[k] : undefined;
+    const num = (k) => typeof p[k] === "number" ? p[k] : undefined;
+    switch (ev.type) {
+        case "actor-created": {
+            const name = str("name") ?? str("actorName");
+            const ordinal = num("ordinal");
+            const site = str("siteId") ?? str("actorSiteId");
+            const label = name ?? site;
+            const tag = ordinal !== undefined ? `#${ordinal}` : (site ?? "");
+            return label ? `+ actor ${tag} ${label}` : `+ actor ${tag}`.trim();
+        }
+        case "phase-entered": {
+            const phase = str("phaseName") ?? str("name");
+            return phase ? `> phase ${phase}` : "> phase";
+        }
+        case "run-settled": {
+            const status = str("status") ?? "unknown";
+            return `= run settled: ${status}`;
+        }
+        default: {
+            // Node lifecycle: only the SETTLED events carry an outcome worth a line.
+            if (!ev.type.startsWith("node-"))
+                return null;
+            const outcome = str("outcome");
+            if (outcome !== "ok" && outcome !== "failed" && outcome !== "cancelled")
+                return null;
+            const ordinal = num("ordinal");
+            const site = str("siteId");
+            const label = [site, ordinal !== undefined ? `#${ordinal}` : null]
+                .filter((x) => x !== null && x !== undefined && x !== "")
+                .join("/");
+            const icon = outcome === "ok" ? "✓" : outcome === "failed" ? "✗" : "–";
+            return label ? `${icon} node ${label} ${outcome}` : `${icon} node ${outcome}`;
+        }
+    }
+}
+/**
+ * Append a line under the cap: keep first/last halves with an ellipsis mark.
+ * The capped `lines` buffer is trim accounting only — emission sends the
+ * `pending` delta, so a trim that drops still-unemitted lines marks the gap
+ * with a one-time `…` line in that tick's delta.
+ */
+function pushLine(run, line) {
+    run.lines.push(line);
+    run.pending.push(line);
+    if (run.lines.length > MAX_LINES) {
+        const half = Math.floor(MAX_LINES / 2);
+        run.lines = [...run.lines.slice(0, half), "…", ...run.lines.slice(-(half - 1))];
+        run.pending.push("…");
+    }
+}
+/**
+ * Emit the lines added since the previous emission (plus an optional one-off
+ * notice line) onto the CreateWorkflow card — append semantics, per-alias
+ * fan-out. A tick with nothing new emits nothing.
+ */
+async function emitCardUpdate(run, notice) {
+    const delta = [...run.pending, ...(notice ? [notice] : [])];
+    run.pending = [];
+    if (delta.length === 0)
+        return;
+    const update = {
+        sessionUpdate: "tool_call_update",
+        toolCallId: run.toolCallId,
+        content: [{ type: "content", content: { type: "text", text: delta.join("\n") } }],
+        _meta: { workflowRun: { runId: run.runId, sequence: run.afterSequence } },
+    };
+    await run.server.notifyByZcodeSid(run.zcodeSid, update);
+}
+/** Tear the run down: clear the timer and forget it. Idempotent. */
+function teardown(run) {
+    if (run.timer)
+        clearTimeout(run.timer);
+    run.timer = null;
+    run.stopped = true;
+    if (activeRuns.get(run.runId) === run)
+        activeRuns.delete(run.runId);
+}
+function scheduleNext(run) {
+    if (run.stopped)
+        return;
+    const t = setTimeout(() => void pollTick(run), run.intervalMs);
+    t.unref?.();
+    run.timer = t;
+}
+/**
+ * One poll tick: fetch journal pages (draining `hasMore` back-to-back), fold
+ * new lines, emit when something meaningful appeared, schedule the next tick.
+ */
+async function pollTick(run) {
+    run.timer = null;
+    if (run.stopped || run.polling)
+        return;
+    run.polling = true;
+    let emitted = false;
+    try {
+        if (Date.now() - run.startedAt > WORKFLOW_POLL_HARD_TIMEOUT_MS) {
+            log(`workflow poller: run ${run.runId.slice(-8)} hit the 10min hard cap — stopping`);
+            await emitCardUpdate(run, "[progress polling stopped: timeout]");
+            teardown(run);
+            return;
+        }
+        const backend = run.server.backend;
+        if (!backend || backend.isDead) {
+            // Backend gone (respawn/shutdown): counts as an error; consecutive
+            // failures stop the poller naturally. Never ensureBackend() from here —
+            // a poller must not spawn backends as a side effect.
+            await handleError(run, { message: "backend unavailable" });
+            return;
+        }
+        for (let page = 0; page < MAX_PAGES_PER_TICK; page++) {
+            const resp = await backend.request(run.server.nextId(), "v4/conversation/workflowRunEvents", {
+                sessionId: run.zcodeSid,
+                runId: run.runId,
+                afterSequence: run.afterSequence,
+                limit: EVENTS_PAGE_LIMIT,
+            }, 8000);
+            if (resp.error) {
+                await handleError(run, resp.error);
+                return;
+            }
+            const result = resp.result;
+            const events = Array.isArray(result?.events) ? result.events : [];
+            for (const ev of events) {
+                if (typeof ev?.sequence === "number" && ev.sequence > run.afterSequence) {
+                    run.afterSequence = ev.sequence;
+                }
+                const line = workflowEventLine(ev);
+                if (line) {
+                    pushLine(run, line);
+                    emitted = true;
+                }
+                if (ev.type === "run-settled") {
+                    await emitCardUpdate(run);
+                    log(`workflow poller: run ${run.runId.slice(-8)} settled — stopping`);
+                    teardown(run);
+                    return;
+                }
+            }
+            if (!result?.hasMore)
+                break;
+        }
+        run.consecutiveErrors = 0;
+        if (emitted)
+            await emitCardUpdate(run);
+    }
+    catch (e) {
+        // request() never throws; anything here is our own bug — count it as an
+        // error tick so the consecutive-failure stop still applies.
+        await handleError(run, {
+            message: e instanceof Error ? e.message : String(e),
+        });
+    }
+    finally {
+        run.polling = false;
+        // Stop paths tore the run down (stopped=true); transient errors keep
+        // polling. Scheduling from the finally so early `return`s never strand
+        // the chain.
+        scheduleNext(run);
+    }
+}
+/** Classify an error response: -32601 stops silently, everything else counts. */
+async function handleError(run, error) {
+    if (error.code === -32601) {
+        // Backend build without the v4 family — log once, stop without a notice
+        // (the run itself is unaffected; only the progress folding is unavailable).
+        log(`workflow poller: backend has no v4/conversation/workflowRunEvents — ` +
+            `stopping run ${run.runId.slice(-8)}`);
+        teardown(run);
+        return;
+    }
+    run.consecutiveErrors += 1;
+    if (run.consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+        log(`workflow poller: ${run.consecutiveErrors} consecutive failures — ` +
+            `stopping run ${run.runId.slice(-8)}`);
+        await emitCardUpdate(run, "[progress polling stopped: repeated errors]");
+        teardown(run);
+        return;
+    }
+    // Transient (timeout / dead pipe / backend respawn window) — retry next tick.
+}
+/**
+ * Arm the progress poller for a workflow run. Single-flight per runId: a
+ * re-arm (task status updates repeat the launch payload) is a no-op. The
+ * first poll fires after one interval.
+ */
+export function armWorkflowRunPoller(server, zcodeSid, opts) {
+    const { runId, toolCallId } = opts;
+    if (!runId || !toolCallId)
+        return;
+    if (activeRuns.has(runId))
+        return;
+    const run = {
+        server,
+        zcodeSid,
+        runId,
+        toolCallId,
+        afterSequence: 0,
+        lines: [],
+        pending: [],
+        startedAt: Date.now(),
+        intervalMs: opts.intervalMs ?? WORKFLOW_POLL_INTERVAL_MS,
+        consecutiveErrors: 0,
+        stopped: false,
+        timer: null,
+        polling: false,
+    };
+    activeRuns.set(runId, run);
+    log(`workflow poller: armed for run ${runId.slice(-8)} on card ${toolCallId.slice(-12)}`);
+    scheduleNext(run);
+}
+/** Stop the poller for one run (background task reached a terminal status). */
+export function stopWorkflowRunPoller(runId) {
+    const run = activeRuns.get(runId);
+    if (!run)
+        return;
+    teardown(run);
+    log(`workflow poller: stopped run ${runId.slice(-8)}`);
+}
+/** Stop every poller (bridge shutdown — mirrors background-task shutdown records). */
+export function stopAllWorkflowRunPollers() {
+    for (const run of [...activeRuns.values()])
+        teardown(run);
+}
+/**
+ * Stop every poller armed under one backend session (the session/close
+ * cleanup path). Best-effort, never throws — a closed session's journal
+ * answers can outlive the runtime, and polling it would only end at the hard
+ * cap with a stray timeout notice for a conversation nobody can see anymore.
+ */
+export function stopPollersForSession(zcodeSid) {
+    for (const run of [...activeRuns.values()]) {
+        if (run.zcodeSid === zcodeSid)
+            teardown(run);
+    }
+}
+/** Test/observability hook: is a poller currently armed for this runId? */
+export function workflowPollerActive(runId) {
+    return activeRuns.has(runId);
+}
+//# sourceMappingURL=poller.js.map

package/dist/workflow/poller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poller.js","sourceRoot":"","sources":["../../src/workflow/poller.ts"],"names":[],"mappings":"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"}

package/docs/ARCHITECTURE.md

@@ -153,11 +153,13 @@ API only because the ZCode backend itself sends them for inference.
 
 ### `backend/` — ZCode process communication
 
-| File          | Responsibility                                                                                  |
-| ------------- | ----------------------------------------------------------------------------------------------- |
-| `client.ts`   | Spawn/manage the zcode subprocess, reader-loop, request/response multiplexing, process watchdog |
-| `listener.ts` | EventStreamListener (subscribe/consume the event stream) and TurnMonitor (snapshot polling)     |
-| `types.ts`    | ZCode JSON-RPC message type definitions                                                         |
+| File               | Responsibility                                                                                              |
+| ------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `adapter.ts`       | `BackendAdapter` seam (ADR-0023): `BackendKind`, the capability table (single gate source), wire vocabulary |
+| `jsonrpc-child.ts` | Shared stdio JSON-RPC transport: spawn, reader-loop, request multiplexing, watchdog, dialect hooks          |
+| `client.ts`        | `ZcodeBackend` — the zcode dialect over `JsonRpcChild` (bare frames, arrival responders)                    |
+| `listener.ts`      | EventStreamListener (subscribe/consume the event stream) and TurnMonitor (snapshot polling)                 |
+| `types.ts`         | ZCode JSON-RPC message type definitions                                                                     |
 
 ### `translators/` — Event translation
 
@@ -476,7 +478,7 @@ when the bridge exits cleanly enough for its signal handlers to fire
 crash, OOM), the handler never runs and the zcode subprocess group is
 orphaned.
 
-The watchdog (`backend/client.ts:startWatchdog`) closes that gap. It is a tiny
+The watchdog (`backend/jsonrpc-child.ts:startWatchdog`) closes that gap. It is a tiny
 detached child that polls the bridge pid every 2s and, once the bridge is
 gone, sends SIGKILL to the zcode process group, then exits. It is its own
 process-group leader and `unref`'d, so it never holds the event loop open and

package/docs/BACKLOG.md

@@ -23,6 +23,19 @@ version). Full audit detail with `file:line` evidence:
 `.zcode/scratch/alignment-protocol.md` (protocol surface) and
 `.zcode/scratch/alignment-hacks.md` (Gotchas verification).
 
+**3.14.3 audit (2026-09-24, commit `328c1a0` — no bridge impact)**: the single
+upstream release commit is entirely the dynamic-workflow subsystem (runtime
+concurrency adjustment, modify/restart reuse, large-run status rendering,
+script-submit token cost) plus bot delivery (`botDeliveryTarget` on
+`session/send` and `automation/create` — both OPTIONAL fields the bridge
+never sends — and the bots providers: feishu/telegram/weixin/webhook).
+app-server stays `0.16.9`; `server-operations.ts` touches only the
+botDeliveryTarget passthrough (stop's `activeAbortController` and compact's
+`state.updated` swallow unchanged); provider bootstrap / runtime headers /
+setModel / goal / fork untouched. `bundled-skills.ts` is the DWF skill pack's
+own distribution channel (explicitly not in the settings page or `$` panel)
+— no overlap with the bridge's filesystem skill discovery.
+
 **3.14.0 audit (2026-09-20, app-server 0.16.9 — live-probed end to end)**: the
 dynamic-workflow family (ten model tools led by `CreateWorkflow`) is OFF by
 default headless and enabled per PROCESS via
@@ -102,7 +115,7 @@ when a concrete ACP/editor need appears. Ranked shortlist in
 | `process/childProcesses` (3.12.3)                                                                                                                                                                                                                                                                                                                               | List a session's child processes (`{pid, serverName, mcpSource, pluginName?}`, pure memory)                                                               | Not used; potentially useful for background-task diagnostics                                                                                                                                                                                                                                                    |
 | `skills/referenceCatalog`, `plugins/referenceCatalog[WithCategory]` (categorized variant new in 0.16.9)                                                                                                                                                                                                                                                         | Session-scoped FROZEN catalogs — the authoritative per-session view vs the bridge's live disk reads                                                       | Not used; fixes the stale-catalog class of bug (backend freezes discovery at session start)                                                                                                                                                                                                                     |
 | `workspace/readPresentation` (3.12.3)                                                                                                                                                                                                                                                                                                                           | The backend's own view of workspace mode + slash-command list                                                                                             | Not used; cross-check the bridge's disk-based slash discovery for drift                                                                                                                                                                                                                                         |
-| `workflows/*` family (NEW 0.16.9: `list/get/updateMeta/delete/runs/move`, `index.ts:2685-2937, 3618-3625`)                                                                                                                                                                                                                                                      | Session-less management of saved dynamic workflows (`<cwd>/.zcode/workflows/`, project+global scopes), run history with `artifacts`, cross-cwd runs query | Not used; pairs with v4 commands `startSavedWorkflow` / `resumeWorkflowRun`                                                                                                                                                                                                                                     |
+| `workflows/*` family (NEW 0.16.9: `list/get/updateMeta/delete/runs/move`, `index.ts:2685-2937, 3618-3625`)                                                                                                                                                                                                                                                      | Session-less management of saved dynamic workflows (`<cwd>/.zcode/workflows/`, project+global scopes), run history with `artifacts`, cross-cwd runs query | **WIRED (2026-09-24, ADR-0029)**: proxied under `/settings/workflows*` + the local `/workflows` slash listing; availability is the remote `/client/configs` verdict (`src/config/workflow-gate.ts`), and `v4/command startSavedWorkflow`/`resumeWorkflowRun` + the `workflowRun*` queries are wired with it (see the v4 section below) |
 | `provider/testModelConnectivity` (3.12.3)                                                                                                                                                                                                                                                                                                                       | Probe a provider/model endpoint                                                                                                                           | Not used; model availability comes from the `session/create` response                                                                                                                                                                                                                                           |
 | `runtime/capabilities` (3.12.3; returns `{independentPlanState:true}`)                                                                                                                                                                                                                                                                                          | Trivial capability handshake                                                                                                                              | Not used; cheap preflight for a `zcode-acp doctor` command                                                                                                                                                                                                                                                      |
 | `interaction/providerRuntimeHeadersCancelled` notification (`index.ts:336, 2396-2406`)                                                                                                                                                                                                                                                                          | Backend cancels a pending runtime-headers refresh (workspace/session/requestId scoped)                                                                    | Not handled; drop pending answerers immediately on turn cancel instead of waiting them out                                                                                                                                                                                                                      |
@@ -212,7 +225,12 @@ Topic model (`transport.ts:83-161`): subscribe with
 toSeq]` deltas — the watermark/CAS vocabulary row-targeting commands require
 (`baseRevision` + `baseLogEpoch`, `command.ts:293-317`).
 
-The bridge already speaks `v4/command` (the dual stop). Its payload union
+The bridge already speaks `v4/command` (the dual stop), and since 2026-09-24
+also `startSavedWorkflow` / `resumeWorkflowRun` (Settings API launch routes,
+ADR-0029 — the ack is terminal, awaited via `request()`) plus the seven
+`v4/conversation/workflowRun*` read queries (run progress poller + run-detail
+routes). The launch consent is the API call itself (upstream skips the
+permission popup for hub clicks). Its payload union
 (`command.ts:43-244`) is a single-method stepping stone to
 rewind/edit-turn/feedback/queue UX over ACP without implementing the v4
 subscription mesh: `sendText (requestedDelivery startNow|queue|guide,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcode-acp-server",
-  "version": "0.47.10",
+  "version": "0.48.1",
   "description": "Agent Client Protocol (ACP) server bridging headless ZCode to editors like Zed and JetBrains.",
   "type": "module",
   "license": "Apache-2.0",