zcode-acp-server 0.31.1 → 0.33.0

package/dist/handlers/session.js

@@ -891,6 +891,24 @@ export async function loadSession(server, params, cx, opts = {}) {
     log(`session/load → ${zcodeSid}`);
     server.ensureBackgroundListener(zcodeSid);
     await adoptStoredTitle(server, acpSid, zcodeSid);
+    // Goal-loop restart recovery (ADR-0022 §6): surface a recovery hint at most
+    // once per bridge process per session — never auto-resume a spend-incurring
+    // loop the user may have meant to stop. A LIVE driver means a second client
+    // attached mid-loop: no hint at all. Only a persisted "running" status
+    // (running without a driver = the bridge died mid-loop) gets the
+    // interrupted wording; user-visible paused states get a neutral line.
+    {
+        const { GoalLoopDriver } = await import("../goal-loop/driver.js");
+        const { readGoalState } = await import("../goal-loop/state.js");
+        if (!GoalLoopDriver.live(server, zcodeSid) && !server.goalLoopLoadHints.has(zcodeSid)) {
+            const prior = readGoalState(cwd, zcodeSid);
+            const interrupted = prior?.status === "running";
+            if (prior && (interrupted || prior.status.startsWith("paused"))) {
+                server.goalLoopLoadHints.add(zcodeSid);
+                await sendTextChunk(cx, acpSid, interrupted ? messages().goalHintInterrupted(prior.objective) : messages().goalHintPaused, `goalhint_${randomUUID().slice(0, 8)}`).catch(() => undefined);
+            }
+        }
+    }
     // Named `history` — a local `messages` would shadow the i18n `messages()`
     // helper used in the error paths above (TDZ crash from the catch block).
     const history = await fetchMessages(server, zcodeSid);
@@ -1016,120 +1034,25 @@ export async function prompt(server, params, cx, requestId, client) {
     server.sandboxContinuations.delete(params.sessionId);
     return result;
 }
-/** One prompt round: subscribe-before-send, run the event-driven turn loop. */
-async function runPrompt(server, params, cx, requestId, continuationRound = false, client) {
-    // Project-level sandbox flip (ADR-0011): a .zcode/acp/sandbox.json created
-    // after the backend spawned unsandboxed must arm on THIS prompt, not on the
-    // next bridge restart — kill the old process; the ensureBackend() below
-    // respawns under the profile and the subscribe-recovery path reloads the
-    // session. No-op unless the config appeared mid-run.
-    await server.applySandboxFlip();
-    const backend = server.ensureBackend();
-    // Extract prompt text + image attachments from ACP ContentBlock[].
-    const text = extractPromptText(params.prompt);
-    const attachments = extractAttachments(params.prompt);
-    // A prompt is valid if it has text OR at least one image attachment (a user
-    // may drag in an image with no accompanying text).
-    if (!text && attachments.length === 0)
-        throw new Error("empty prompt");
-    // Boot-resume banner handshake (see BOOT_RESUME_TRIGGER): martty queues the
-    // auto-submitted trigger until its boot bind, so it arrives as the FIRST
-    // prompt OF THAT CONNECTION — ack with one chunk and end the turn without
-    // touching the backend. Scoped to the arming connection's identity: a
-    // phone app attached to the same bridge may prompt inside the boot window
-    // and must neither spend nor disarm the handshake (observed live: its
-    // prompt raced ahead and the trigger leaked to the model). The same
-    // connection submitting anything else first means the auto-submit was
-    // lost — disarm so the trigger text typed manually later stays a normal
-    // prompt.
-    if (server.bootResumeTriggerConnection !== null &&
-        clientConnectionRoot(client) === server.bootResumeTriggerConnection) {
-        server.bootResumeTriggerConnection = null;
-        if (text === BOOT_RESUME_TRIGGER) {
-            await sendTextChunk(cx, params.sessionId, messages().bootResumeAck, randomUUID());
-            log("session/prompt: boot-resume banner handshake acknowledged");
-            return { stopReason: "end_turn" };
-        }
-    }
-    // Materialize a lazy session/new placeholder on first use. Placed after the
-    // empty-prompt check so an invalid request doesn't create a backend session.
-    const zcodeSid = await ensureRealSession(server, params.sessionId);
-    // Slash-command interception: dispatches directly to ZCode methods and
-    // returns end_turn without entering the turn loop. Known passthrough
-    // commands and unknown /x both return null for the normal turn loop.
-    const { handleSlashCommand, neutralizeSlashText } = await import("./slash.js");
-    const intercepted = await handleSlashCommand(server, cx, params.sessionId, zcodeSid, text);
-    if (intercepted)
-        return intercepted;
-    // Wire text for the backend: unknown `/x` prompts (not advertised commands)
-    // are neutralized so the backend's command resolver never sees them — an
-    // unresolvable name can hard-fail the turn. Known commands pass through
-    // unchanged. The title/auto-compact paths below keep using the raw `text`.
-    const sendText = neutralizeSlashText(text);
-    // Register self + preempt others under a per-session lock. The lock
-    // serializes the critical section so that two concurrent prompts (B, C) for
-    // the same session can't both miss each other and register at once: C waits
-    // for B's section, by which point B is in pendingTurns, so C's preempt finds
-    // and cancels B. Registering INSIDE the lock is what makes the new turn
-    // visible to the next prompt's preempt scan.
-    const turn = {
-        zcodeSid,
-        cancelled: false,
-    };
-    // True when this send cancelled another in-flight prompt (preempt/stop).
-    // Drives the turn-attribution gate: only a preempted prompt can see leftover
-    // events from a prior turn in its listener queue; without preemption any
-    // events before this turn's turn.started belong to a backend-owned turn
-    // (e.g. auto-resumed after compaction) that this send was steered into.
-    let preempted = false;
-    await withPreemptLock(server, zcodeSid, async () => {
-        server.pendingTurns.set(requestId, turn);
-        preempted = preemptInFlightTurn(server, zcodeSid, requestId);
-    });
-    // Discovery: the session is live the moment its turn STARTS — mark it active
-    // here instead of only at turn end, so a freshly created conversation shows
-    // up in remote lists within one heartbeat even while its first (possibly
-    // minutes-long) turn is still running. Until the backend's auto-title lands
-    // at end_turn, seed a provisional title from the prompt text (auto-title
-    // stays authoritative — its set-once gate is the separate sessionTitles).
-    server.markSessionActive(params.sessionId);
-    // Session title: set EXACTLY ONCE, here, from the first prompt of a
-    // freshly created session — immediately, not at end_turn (a preempted
-    // first turn ends "cancelled" and would never be titled; and the
-    // completing prompt must not steal the title). After this, no automatic
-    // path may change the title again: sessionTitles is set-once and a manual
-    // rename is the only later modifier. Resumed/loaded sessions are not
-    // title-eligible — their stored title was adopted on load, or left unset.
-    if (server.titleEligibleSessions.has(params.sessionId) &&
-        text &&
-        !server.sessionTitles.has(params.sessionId)) {
-        // Title = first non-empty line of the prompt, truncated to 80 chars.
-        // Multi-line prompts must not leak newlines into the session title.
-        // Split on any line break (\r\n, \n, \r) so all platforms are covered.
-        const title = text
-            .split(/\r\n|\r|\n/)
-            .map((l) => l.trim())
-            .find((l) => l.length > 0)
-            ?.slice(0, 80) ?? text.slice(0, 80);
-        server.sessionTitles.set(params.sessionId, title);
-        server.touchSessionSummary(params.sessionId, title);
-        const { updateSessionTitle } = await import("../tasks-index.js");
-        void updateSessionTitle(zcodeSid, title, text);
-        void sendSessionUpdate(cx, params.sessionId, {
-            sessionUpdate: "session_info_update",
-            title,
-            updatedAt: new Date().toISOString(),
-        });
-    }
-    // Out-of-band running indicator: clients that did not send this prompt
-    // (re-attached mobile, second editor) learn the turn started here — the
-    // session/load replayMeta only snapshots attach time. Emitted per attached
-    // alias (see server.sessionAliases) so a client holding this conversation
-    // under a different ACP id opens its live turn too. Best-effort: a dead
-    // client must not fail the turn.
+/**
+ * One backend round, shared by the prompt path and the goal-loop driver
+ * (ADR-0022): listener + differ baseline, subscribe with -32004 eviction
+ * recovery, send-busy retry, drain gate after a recent cancel, the
+ * event-driven turn loop with transient-failure retry, and the finally
+ * cleanup (pendingTurns deregistration, discovery/quota refresh, turnState).
+ * Every line here encodes an observed production failure — never reimplement
+ * a second send/subscribe/retry path.
+ */
+export async function runOneTurn(server, opts) {
+    const { backend, cx, acpSid, zcodeSid, requestId, turn, preempted, sendText } = opts;
+    const attachments = opts.attachments ?? [];
+    // Out-of-band running indicator: emitted per attached alias (see
+    // server.sessionAliases) so a client holding this conversation under a
+    // different ACP id opens its live turn too. Best-effort: a dead client must
+    // not fail the turn.
     const emitTurnState = async (running) => {
         const results = await Promise.allSettled(server
-            .sessionAliases(params.sessionId)
+            .sessionAliases(acpSid)
             .map((sid) => cx.notify("$/zcode/turnState", { sessionId: sid, running })));
         for (const r of results) {
             if (r.status === "rejected") {
@@ -1137,7 +1060,6 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
             }
         }
     };
-    await emitTurnState(true);
     const listener = new EventStreamListener(backend, zcodeSid);
     const monitor = new TurnMonitor(backend, zcodeSid, () => server.nextId());
     // Per-session ProjectionDiffer (persists across turns). The baseline mark_seen
@@ -1148,8 +1070,7 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
     // Subscribe BEFORE send so we don't lose early turn.completed on short turns.
     // subscribe() throws on failure, surfacing the backend's real error (reader
     // dead, timeout, pipe broken, method-not-found on old CLI, session error) so
-    // the cause is distinguishable. Clean up the pending turn before propagating
-    // — this call site is outside the try/finally below.
+    // the cause is distinguishable. Clean up the pending turn before propagating.
     let snapshot;
     try {
         try {
@@ -1165,8 +1086,8 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
             const msg = e instanceof Error ? e.message : String(e);
             if (!/session is not active/i.test(msg))
                 throw e;
-            log(`prompt: session ${zcodeSid} no longer active in backend — reloading via session/resume`);
-            await reloadBackendSession(server, params.sessionId, zcodeSid);
+            log(`turn: session ${zcodeSid} no longer active in backend — reloading via session/resume`);
+            await reloadBackendSession(server, acpSid, zcodeSid);
             // The pre-subscribe fetchMessages ran against the evicted session and
             // came back empty — re-baseline the differ so turn completion doesn't
             // diff-replay the whole history as new output.
@@ -1175,7 +1096,7 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
         }
         // A successful subscribe proves the resident runtime is live — refresh
         // the verification so concurrent/later entry points skip a reload.
-        server.markBackendLoaded(params.sessionId);
+        server.markBackendLoaded(acpSid);
     }
     catch (e) {
         server.pendingTurns.delete(requestId);
@@ -1212,7 +1133,7 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
                     return { stopReason: "cancelled" };
                 }
                 differ.markSeen(await fetchMessages(server, zcodeSid));
-                await sendTextChunk(cx, params.sessionId, messages().networkRetry(attempt - 1, MAX_TURN_ATTEMPTS - 1), randomUUID());
+                await sendTextChunk(cx, acpSid, messages().networkRetry(attempt - 1, MAX_TURN_ATTEMPTS - 1), randomUUID());
                 log(`  [retry] transient turn failed, re-sending (attempt ${attempt}/${MAX_TURN_ATTEMPTS})`);
                 await sleep(backoffMs(attempt - 1));
             }
@@ -1223,7 +1144,7 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
                 Date.now() - server.lastCancelledAt.get(zcodeSid) < DRAIN_WINDOW_MS;
             if (cancelledRecently) {
                 const drained = await drainBackendAfterCancel(server, {
-                    acpSid: params.sessionId,
+                    acpSid,
                     zcodeSid,
                     turn,
                     listener,
@@ -1303,8 +1224,8 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
             // bare thinking block with no context. Announce the resumed turn at
             // send-accept so every phase of the allow→restart→continue flow is
             // visibly accounted for (the allow-time hint covers the restart start).
-            if (continuationRound) {
-                await sendTextChunk(cx, params.sessionId, messages().sandboxResumedStatus, randomUUID());
+            if (opts.continuationRound) {
+                await sendTextChunk(cx, acpSid, messages().sandboxResumedStatus, randomUUID());
             }
             try {
                 // Event-driven turn loop: translate events via EventTranslator + dispatch.
@@ -1314,24 +1235,21 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
                 // of this new prompt (see the gate comment in runEventTurn).
                 const gateArmed = preempted ||
                     Date.now() - (server.lastCancelledAt.get(zcodeSid) ?? 0) < CANCEL_RESIDUE_WINDOW_MS;
-                const result = await runEventTurn(server, listener, monitor, differ, cx, params.sessionId, chunkMsgId, turn, gateArmed);
-                // (Session title: already set once at the FIRST prompt, before the
-                // turn loop — nothing here may change it again.)
+                const result = await runEventTurn(server, listener, monitor, differ, cx, acpSid, chunkMsgId, turn, gateArmed);
                 // Auto-compact: if context usage exceeds the threshold, compact before
                 // returning so the next prompt has room. Configured via
                 // ZCODE_ACP_AUTO_COMPACT_THRESHOLD (absolute token count; 0/unset =
                 // disabled). Only on end_turn — cancelled/max_turn_requests skips
                 // compaction, as does a stall-recovered end_turn (the completion was
                 // inferred by the stall heuristic, not confirmed by turn.completed —
-                // compressing an in-flight task's context would destroy the work).
+                // compressing an in-flight task's would destroy the work).
                 // Best-effort: failures are logged inside maybeAutoCompact, never thrown.
-                if (result.stopReason === "end_turn" && !turn.stallRecovered) {
+                if (opts.autoCompact !== false &&
+                    result.stopReason === "end_turn" &&
+                    !turn.stallRecovered) {
                     const { maybeAutoCompact } = await import("../config/auto-compact.js");
-                    await maybeAutoCompact(server, cx, params.sessionId, zcodeSid);
+                    await maybeAutoCompact(server, cx, acpSid, zcodeSid);
                 }
-                // (Sandbox allow-restart continuation: handled by the prompt() wrapper
-                // — the chained round keeps the editor's original request pending so
-                // the restart window stays visibly "running".)
                 return result;
             }
             catch (e) {
@@ -1355,7 +1273,7 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
         // surfacing a hard error and stopping. Skip auto-compact here: compaction
         // after a failed turn is more likely to confuse state than help.
         const errMsg = formatTurnError(lastTurnError) || "turn failed after retries";
-        await sendTextChunk(cx, params.sessionId, messages().requestFailed(errMsg), randomUUID());
+        await sendTextChunk(cx, acpSid, messages().requestFailed(errMsg), randomUUID());
         return { stopReason: "end_turn" };
     }
     finally {
@@ -1365,8 +1283,8 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
         // session discoverable regardless of outcome (end_turn, cancelled, retries
         // exhausted). Also refresh the backend-loaded verification: the resident
         // runtime was demonstrably live through this turn.
-        server.markSessionActive(params.sessionId);
-        server.markBackendLoaded(params.sessionId);
+        server.markSessionActive(acpSid);
+        server.markBackendLoaded(acpSid);
         // Turn end = quota refresh point (ADR-0021): usage moved, the dock should
         // catch up immediately instead of waiting for the 60s interval.
         void forceRefreshQuota();
@@ -1376,6 +1294,158 @@ async function runPrompt(server, params, cx, requestId, continuationRound = fals
         await emitTurnState(stillBusy);
     }
 }
+/** One prompt round: subscribe-before-send, run the event-driven turn loop. */
+async function runPrompt(server, params, cx, requestId, continuationRound = false, client) {
+    // Project-level sandbox flip (ADR-0011): a .zcode/acp/sandbox.json created
+    // after the backend spawned unsandboxed must arm on THIS prompt, not on the
+    // next bridge restart — kill the old process; the ensureBackend() below
+    // respawns under the profile and the subscribe-recovery path reloads the
+    // session. No-op unless the config appeared mid-run.
+    await server.applySandboxFlip();
+    const backend = server.ensureBackend();
+    // Extract prompt text + image attachments from ACP ContentBlock[].
+    const text = extractPromptText(params.prompt);
+    const attachments = extractAttachments(params.prompt);
+    // A prompt is valid if it has text OR at least one image attachment (a user
+    // may drag in an image with no accompanying text).
+    if (!text && attachments.length === 0)
+        throw new Error("empty prompt");
+    // Boot-resume banner handshake (see BOOT_RESUME_TRIGGER): martty queues the
+    // auto-submitted trigger until its boot bind, so it arrives as the FIRST
+    // prompt OF THAT CONNECTION — ack with one chunk and end the turn without
+    // touching the backend. Scoped to the arming connection's identity: a
+    // phone app attached to the same bridge may prompt inside the boot window
+    // and must neither spend nor disarm the handshake (observed live: its
+    // prompt raced ahead and the trigger leaked to the model). The same
+    // connection submitting anything else first means the auto-submit was
+    // lost — disarm so the trigger text typed manually later stays a normal
+    // prompt.
+    if (server.bootResumeTriggerConnection !== null &&
+        clientConnectionRoot(client) === server.bootResumeTriggerConnection) {
+        server.bootResumeTriggerConnection = null;
+        if (text === BOOT_RESUME_TRIGGER) {
+            await sendTextChunk(cx, params.sessionId, messages().bootResumeAck, randomUUID());
+            log("session/prompt: boot-resume banner handshake acknowledged");
+            return { stopReason: "end_turn" };
+        }
+    }
+    // Materialize a lazy session/new placeholder on first use. Placed after the
+    // empty-prompt check so an invalid request doesn't create a backend session.
+    const zcodeSid = await ensureRealSession(server, params.sessionId);
+    // Slash-command interception: dispatches directly to ZCode methods and
+    // returns end_turn without entering the turn loop. Known passthrough
+    // commands and unknown /x both return null for the normal turn loop.
+    const { handleSlashCommand, neutralizeSlashText } = await import("./slash.js");
+    const intercepted = await handleSlashCommand(server, cx, params.sessionId, zcodeSid, text);
+    if (intercepted)
+        return intercepted;
+    // Wire text for the backend: unknown `/x` prompts (not advertised commands)
+    // are neutralized so the backend's command resolver never sees them — an
+    // unresolvable name can hard-fail the turn. Known commands pass through
+    // unchanged. The title/auto-compact paths below keep using the raw `text`.
+    const sendText = neutralizeSlashText(text);
+    // Register self + preempt others under a per-session lock. The lock
+    // serializes the critical section so that two concurrent prompts (B, C) for
+    // the same session can't both miss each other and register at once: C waits
+    // for B's section, by which point B is in pendingTurns, so C's preempt finds
+    // and cancels B. Registering INSIDE the lock is what makes the new turn
+    // visible to the next prompt's preempt scan.
+    const turn = {
+        zcodeSid,
+        cancelled: false,
+    };
+    // True when this send cancelled another in-flight prompt (preempt/stop).
+    // Drives the turn-attribution gate: only a preempted prompt can see leftover
+    // events from a prior turn in its listener queue; without preemption any
+    // events before this turn's turn.started belong to a backend-owned turn
+    // (e.g. auto-resumed after compaction) that this send was steered into.
+    let preempted = false;
+    // Goal-loop parking (ADR-0022 §3): a live loop owns this session's turn
+    // cadence. Park the prompt on the driver — its text merges into the next
+    // round, and the parked request resolves when that round completes —
+    // instead of preempting and cancelling the in-flight goal turn. Checked
+    // INSIDE the preempt lock: the check and the registration are one critical
+    // section, so an /auto start racing this prompt can't register its round
+    // after the check yet before the park (the driver registers through the
+    // same lock). Slash commands /auto pause|resume|stop|status were
+    // intercepted above, so anything reaching here is conversational input.
+    let parked;
+    await withPreemptLock(server, zcodeSid, async () => {
+        const goalLoop = server.goalLoops?.get(zcodeSid);
+        if (goalLoop) {
+            parked = goalLoop.parkPrompt(sendText);
+            return;
+        }
+        server.pendingTurns.set(requestId, turn);
+        preempted = preemptInFlightTurn(server, zcodeSid, requestId);
+    });
+    if (parked)
+        return parked;
+    // Discovery: the session is live the moment its turn STARTS — mark it active
+    // here instead of only at turn end, so a freshly created conversation shows
+    // up in remote lists within one heartbeat even while its first (possibly
+    // minutes-long) turn is still running. Until the backend's auto-title lands
+    // at end_turn, seed a provisional title from the prompt text (auto-title
+    // stays authoritative — its set-once gate is the separate sessionTitles).
+    server.markSessionActive(params.sessionId);
+    // Session title: set EXACTLY ONCE, here, from the first prompt of a
+    // freshly created session — immediately, not at end_turn (a preempted
+    // first turn ends "cancelled" and would never be titled; and the
+    // completing prompt must not steal the title). After this, no automatic
+    // path may change the title again: sessionTitles is set-once and a manual
+    // rename is the only later modifier. Resumed/loaded sessions are not
+    // title-eligible — their stored title was adopted on load, or left unset.
+    if (server.titleEligibleSessions.has(params.sessionId) &&
+        text &&
+        !server.sessionTitles.has(params.sessionId)) {
+        // Title = first non-empty line of the prompt, truncated to 80 chars.
+        // Multi-line prompts must not leak newlines into the session title.
+        // Split on any line break (\r\n, \n, \r) so all platforms are covered.
+        const title = text
+            .split(/\r\n|\r|\n/)
+            .map((l) => l.trim())
+            .find((l) => l.length > 0)
+            ?.slice(0, 80) ?? text.slice(0, 80);
+        server.sessionTitles.set(params.sessionId, title);
+        server.touchSessionSummary(params.sessionId, title);
+        const { updateSessionTitle } = await import("../tasks-index.js");
+        void updateSessionTitle(zcodeSid, title, text);
+        void sendSessionUpdate(cx, params.sessionId, {
+            sessionUpdate: "session_info_update",
+            title,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    // Out-of-band running indicator: clients that did not send this prompt
+    // (re-attached mobile, second editor) learn the turn started here — the
+    // session/load replayMeta only snapshots attach time. Emitted per attached
+    // alias (see server.sessionAliases) so a client holding this conversation
+    // under a different ACP id opens its live turn too. Best-effort: a dead
+    // client must not fail the turn.
+    const emitTurnState = async (running) => {
+        const results = await Promise.allSettled(server
+            .sessionAliases(params.sessionId)
+            .map((sid) => cx.notify("$/zcode/turnState", { sessionId: sid, running })));
+        for (const r of results) {
+            if (r.status === "rejected") {
+                log(`turnState notify failed: ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`);
+            }
+        }
+    };
+    await emitTurnState(true);
+    return runOneTurn(server, {
+        backend,
+        cx,
+        acpSid: params.sessionId,
+        zcodeSid,
+        requestId,
+        turn,
+        preempted,
+        sendText,
+        attachments,
+        continuationRound,
+    });
+}
 /** How long after a cancel a new prompt's attribution gate stays armed (the
  *  abandoned turn may still be streaming its finalisation into the backend). */
 const CANCEL_RESIDUE_WINDOW_MS = 120_000;
@@ -1440,8 +1510,10 @@ export async function cancel(server, params) {
     // could leave the live one running. Each turn guards its own stopSent, so
     // multiple matching turns may each fire the stop pair once — the backend
     // treats both as idempotent, so the duplicate is harmless.
+    let matched = false;
     for (const [, turn] of server.pendingTurns) {
         if (turn.zcodeSid === zcodeSid) {
+            matched = true;
             turn.cancelled = true;
             if (!turn.stopSent) {
                 stopBackendTurn(server, zcodeSid, turn.foregroundExecutionId);
@@ -1452,6 +1524,18 @@ export async function cancel(server, params) {
             server.lastCancelledAt.set(zcodeSid, Date.now());
         }
     }
+    // ESC during a goal loop's quiet windows (compact()'s internal wait, the
+    // judge/announce awaits) has no pendingTurns entry to flag — park the pause
+    // on the driver instead; it takes effect at the next round boundary.
+    // Best-effort: never break cancel for non-goal sessions.
+    if (!matched) {
+        try {
+            server.goalLoops?.get(zcodeSid)?.requestPause();
+        }
+        catch (e) {
+            log(`goal-loop pause request failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
     log(`session/cancel → ${zcodeSid}`);
 }
 /**
@@ -1667,7 +1751,7 @@ export async function drainBackendAfterCancel(server, deps) {
  * synchronous; preempt no longer waits). The turn loop itself runs OUTSIDE
  * this lock — only registration + preempt are serialized.
  */
-function withPreemptLock(server, zcodeSid, body) {
+export function withPreemptLock(server, zcodeSid, body) {
     const prev = server.preemptLocks.get(zcodeSid) ?? Promise.resolve();
     const next = prev.then(body, body); // run body regardless of prior rejection
     server.preemptLocks.set(zcodeSid, next);
@@ -1719,6 +1803,12 @@ export function preemptInFlightTurn(server, zcodeSid, selfRequestId) {
     for (const [reqId, turn] of server.pendingTurns) {
         if (turn.zcodeSid !== zcodeSid || reqId === selfRequestId)
             continue;
+        // Goal-loop rounds (ADR-0022): user prompts PARK on the driver (see the
+        // parking hook in runPrompt) instead of preempting — a goalLoop turn in
+        // this scan means a path that bypassed the hook (defensive); never
+        // cancel it here. ESC/cancel() still cancels it like any pending turn.
+        if (turn.goalLoop)
+            continue;
         turn.cancelled = true; // signal the old turn to stop its retry loops
         if (!turn.stopSent) {
             stopBackendTurn(server, zcodeSid, turn.foregroundExecutionId);
@@ -1974,6 +2064,52 @@ function getOrCreateDiffer(server, zcodeSid) {
     differ.resetTurn();
     return differ;
 }
+/**
+ * Map the backend's merged per-turn usage (`EventTranslator.turnUsage`) onto
+ * the ACP `PromptResponse.usage` shape (UNSTABLE in agent-client-protocol;
+ * per-turn semantics per its "Token usage for this turn" description). The
+ * three required counters are always present in the backend object (its
+ * reducer 0-fills them); the optional ones pass through as null when
+ * unreported. Field renames: reasoningTokens→thoughtTokens,
+ * cacheRead/cacheWriteTokens→cachedRead/cachedWriteTokens.
+ */
+export function toAcpTurnUsage(u) {
+    if (!u)
+        return undefined;
+    const num = (k) => (typeof u[k] === "number" ? u[k] : 0);
+    const numOrNull = (k) => typeof u[k] === "number" ? u[k] : null;
+    return {
+        totalTokens: num("totalTokens"),
+        inputTokens: num("inputTokens"),
+        outputTokens: num("outputTokens"),
+        thoughtTokens: numOrNull("reasoningTokens"),
+        cachedReadTokens: numOrNull("cacheReadTokens"),
+        cachedWriteTokens: numOrNull("cacheWriteTokens"),
+    };
+}
+/**
+ * Build the ACP `session/prompt` result for a concluded turn, attaching the
+ * turn's usage when the backend reported one (absent otherwise — no synthetic
+ * zeros). Spec fields carry the standard counters; backend extras (source,
+ * modelRequestCount, web request counts) ride in `_meta.zcode.usage` per the
+ * bridge's extension policy.
+ */
+export function turnResult(translator, stopReason) {
+    const raw = translator.turnUsage;
+    const usage = toAcpTurnUsage(raw);
+    if (!usage || !raw)
+        return { stopReason };
+    const extras = {};
+    for (const k of ["source", "modelRequestCount", "webFetchRequests", "webSearchRequests"]) {
+        if (raw[k] !== undefined)
+            extras[k] = raw[k];
+    }
+    return {
+        stopReason,
+        usage,
+        _meta: { zcode: { usage: extras } },
+    };
+}
 /**
  * Event-driven turn loop: translate zcode events via EventTranslator and
  * dispatch each internal event to the ACP client. No-progress timeout is 120s
@@ -2093,7 +2229,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                 // Preserve the pre-existing bounded cancel behaviour. A stuck prompt
                 // lock after stop must not keep a user-cancelled turn alive forever.
                 stopBackendTurn(server, turn.zcodeSid, turn.foregroundExecutionId);
-                return { stopReason: "max_turn_requests" };
+                return turnResult(translator, "max_turn_requests");
             }
             else {
                 const frozenMs = Date.now() - lastWatermarkAdvanceAt;
@@ -2121,7 +2257,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                     // (never compress its context; the completion is inferred).
                     turn.stallRecovered = true;
                     log(`  [stall] watermark frozen ${Math.round(frozenMs / 1000)}s; ending turn after delivered output`);
-                    return { stopReason: "end_turn" };
+                    return turnResult(translator, "end_turn");
                 }
                 else {
                     const reply = await fetchLastReply(server, turn.zcodeSid, differ);
@@ -2130,11 +2266,11 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                         await sendTextChunk(cx, acpSid, reply.text, chunkMsgId);
                         turn.stallRecovered = true;
                         log(`  [stall] watermark frozen ${Math.round(frozenMs / 1000)}s; recovered reply via session/messages`);
-                        return { stopReason: "end_turn" };
+                        return turnResult(translator, "end_turn");
                     }
                     log(`  [stall] watermark frozen ${Math.round(frozenMs / 1000)}s with no output; stopping backend turn`);
                     stopBackendTurn(server, turn.zcodeSid, turn.foregroundExecutionId);
-                    return { stopReason: "max_turn_requests" };
+                    return turnResult(translator, "max_turn_requests");
                 }
             }
         }
@@ -2169,7 +2305,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                 stopBackendTurn(server, turn.zcodeSid, turn.foregroundExecutionId);
                 turn.stopSent = true;
             }
-            return { stopReason: "cancelled" };
+            return turnResult(translator, "cancelled");
         }
         const ev = await listener.pollEvent(500);
         if (ev === null) {
@@ -2237,7 +2373,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                         // turn — the completion was inferred, and compressing an
                         // in-flight task's context would destroy the work.
                         turn.stallRecovered = true;
-                        return { stopReason: "end_turn" };
+                        return turnResult(translator, "end_turn");
                     }
                     // Second probe says the backend is still working (or events arrived
                     // mid-probe) — keep waiting; queued events are consumed by the next
@@ -2267,7 +2403,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
         // swallow: report it at once so the user can resend immediately.
         if (ev.type === "turn.steerQueued" && !translator.turnStarted && gateArmed) {
             await sendTextChunk(cx, acpSid, messages().messageSwallowedByTurn, chunkMsgId);
-            return { stopReason: "max_turn_requests" };
+            return turnResult(translator, "max_turn_requests");
         }
         // Turn-attribution gate: before this turn's own turn.started arrives, any
         // event is leftover from a prior turn (cancelled/preempted but still
@@ -2342,7 +2478,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                 if (denial) {
                     await handleSandboxDenial(server, cx, acpSid, denial, toolCallId);
                     if (turn.cancelled)
-                        return { stopReason: "cancelled" };
+                        return turnResult(translator, "cancelled");
                 }
                 else {
                     // No path parsed — one generic hint per session, not one per retry.
@@ -2423,7 +2559,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
             // terminal resultType (cancelled / success / failed), honour the user's
             // intent and report cancelled.
             if (turn.cancelled || translator.turnResultType === "cancelled") {
-                return { stopReason: "cancelled" };
+                return turnResult(translator, "cancelled");
             }
             if (translator.turnFailed) {
                 // Best-effort stop in case the failed turn left a residual lock.
@@ -2461,10 +2597,16 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
             const snapshot = await buildSnapshot(server, turn.zcodeSid);
             const completionEvents = differ.diff(snapshot);
             for (const iev of completionEvents) {
-                if ((iev.kind === "TextDelta" || iev.kind === "ReasoningDelta") &&
-                    iev.messageId &&
-                    translator.deliveredMessageIds.has(iev.messageId)) {
-                    continue;
+                // Per-kind dedup (see deliveredReasoningMessageIds): text and reasoning
+                // share one assistant message id, so the kind that streamed live must
+                // be suppressed while the other kind — typically GLM reasoning that
+                // only exists in the completion snapshot — must still go through.
+                if (iev.kind === "TextDelta" || iev.kind === "ReasoningDelta") {
+                    const delivered = iev.kind === "TextDelta"
+                        ? translator.deliveredMessageIds
+                        : translator.deliveredReasoningMessageIds;
+                    if (iev.messageId && delivered.has(iev.messageId))
+                        continue;
                 }
                 await dispatchEvent(server, cx, acpSid, iev, chunkMsgId);
             }
@@ -2474,7 +2616,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
             // push current_mode_update + config_option_update when it changed since
             // the last value advertised to the client.
             await emitModeIfChanged(server, cx, acpSid, turn.zcodeSid);
-            return { stopReason: "end_turn" };
+            return turnResult(translator, "end_turn");
         }
     }
 }