create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/acp/dsh-prompt-lane.js

@@ -0,0 +1,616 @@
+'use strict';
+
+// WP-4 of docs/deepseek-harness-acp-agent-2026-10-28.html (§6.5 status mapping, §5 D-7, §9 S-32/S-33/S-35).
+//
+// The prompt/cancel/approval lane for a conv-only ACP session (today the DeepSeek Harness, `dsh`).
+// Such a session has no PTY, so the terminal submission path cannot own it: this lane takes the
+// turn instead, and everything that is NOT an ACP session falls straight through to the function it
+// wraps, with identical arguments (§9 S-32 — the wraps are same-line seams in server.js).
+//
+// A turn, in order (§6.5):
+//   1. the user row is appended to the CTM-owned transcript (lib/acp/dsh-transcript.js) — the
+//      transcript is appended to BEFORE the wire write so Conv can never show a prompt the agent
+//      was not yet given;
+//   2. status `received` (the client renders it `accepted`);
+//   3. `session/prompt` goes to the child — the ACP client writes it synchronously;
+//   4. status `durable_user_message_seen` (rendered `sent`) — the request is on the wire;
+//   5. the delivery RETURNS here, and the turn settles in the BACKGROUND (runSettle) when the prompt
+//      promise settles: the transcript's open chunk group is flushed and the chip closes. A JSON-RPC
+//      error is reported `failed` with the bridge's own message ("Insufficient Balance") and becomes
+//      a `dsh_turn_failed` transcript row (assistant-shaped since WP-7d, so Conv renders it); a
+//      cancelled turn settles `blocked`. Anything that needs the turn's END awaits
+//      whenTurnSettled(sessionId).
+// The delivery must not wait for step 5: lib/root-delivery-runtime.js holds the delivery permit
+// until `deliverTerminal` resolves, and a dsh turn can run for many minutes — so its contract
+// ("delivered = the write was confirmed") is honoured by returning at step 4.
+// A second prompt while one is in flight is refused with `dsh_turn_in_flight` by BOTH the preflight
+// wrap and the delivery guard (two preflights can pass before either delivery starts; the bridge
+// admits ONE in-flight prompt per session).
+//
+// Approvals (D-7): a `session/request_permission` becomes a runtime approval whose metadata carries
+// the already-received `tool_call`'s title/input, is answered by the approval executor through the
+// wrapped `isHookPending`/`resolveHook` seams (S-35) and resolves the ACP server request with the
+// ACP-provided `optionId` for the chosen kind. "Answered exactly once" (P-4) is owned by
+// lib/acp/acp-client.js — on cancel/child exit it answers pending permissions `cancelled` itself —
+// so this lane only has to settle its OWN promise and mark the runtime approval `expired` (T-10).
+//
+// Everything outside this module is a dep, so a unit test drives the lane with a fake ACP client,
+// a fake runtime and fake status/approval sinks (D-14, H-7). Nothing here writes a file, spawns a
+// process or invents a WebSocket frame: statuses go through the SAME storeStatus/receipt channel the
+// terminal path uses, and the session chip is fed by the server's own turn-open/turn-close helpers.
+
+const { isAcpSession } = require('../session-transport');
+const { getDataDir } = require('../data-dir');
+
+// ACP permission option kinds (protocol v1) → the CTM runtime-approval decision vocabulary
+// (docs §5 D-7). `allow_always` maps to the project-scoped allow, both reject kinds to `deny`.
+const ACP_KIND_TO_DECISION = Object.freeze({
+  allow_once: 'allow_once',
+  allow_always: 'allow_always_project',
+  reject_once: 'deny',
+  reject_always: 'deny',
+});
+
+const TURN_IN_FLIGHT_MESSAGE = 'A turn is already running on this DeepSeek Harness session.';
+const NOT_RUNNING_MESSAGE = 'The DeepSeek Harness process for this session is not running.';
+const TURN_CANCELLED_MESSAGE = 'The turn was cancelled.';
+const MAX_PROMPT_CHARS = 20000;
+
+// WP-11 (D-20) refusals. `dsh_image_unsupported` is the capability verdict (the child never
+// advertised `promptCapabilities.image`); `dsh_image_unreadable` is the store verdict (the bytes the
+// prompt named could not be read). Both are refused BEFORE anything is written to the wire or the
+// transcript, mirroring the existing `dsh_not_running` door.
+const IMAGE_UNSUPPORTED_CODE = 'dsh_image_unsupported';
+const IMAGE_UNSUPPORTED_MESSAGE =
+  'This DeepSeek Harness session cannot accept images: the agent did not advertise image prompt support.';
+const IMAGE_UNREADABLE_CODE = 'dsh_image_unreadable';
+const IMAGE_UNREADABLE_MESSAGE = 'An image attached to this prompt could not be read.';
+
+// The image extensions CTM's upload store serves (`/api/images/file/<name>`); an attachment with an
+// explicit `image/*` media type is an image regardless of its name.
+const IMAGE_EXT_RE = /\.(?:png|jpe?g|gif|webp|bmp|avif)$/i;
+const MIME_BY_EXT = Object.freeze({
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.bmp': 'image/bmp', '.avif': 'image/avif',
+});
+const nodePath = require('node:path');
+const fsPromises = require('node:fs').promises;
+
+// The image attachments a submission names, normalized to the fields the store resolver needs. Non
+// images are dropped: the terminal path already filters its own attachment list, and a dsh prompt
+// carries only images (D-20).
+function collectImageRefs(attachments) {
+  const refs = [];
+  for (const att of Array.isArray(attachments) ? attachments : []) {
+    if (!att || typeof att !== 'object' || Array.isArray(att)) continue;
+    const mimeType = String(att.mimeType || att.mediaType || att.mime_type || att.media_type || '').toLowerCase();
+    const name = String(att.filename || att.path || att.file_path || att.url || '');
+    if (!mimeType.startsWith('image/') && !IMAGE_EXT_RE.test(name.replace(/[?#].*$/, ''))) continue;
+    refs.push({
+      label: String(att.label || ''),
+      filename: String(att.filename || ''),
+      url: String(att.url || ''),
+      path: String(att.path || att.file_path || ''),
+      id: Number(att.id || 0) || null,
+      mimeType,
+    });
+  }
+  return refs;
+}
+
+// The ONE production source of image bytes: CTM's upload store, `<dataDir>/images`, which is exactly
+// what `/api/images/file/<name>` serves and what a session-image manifest's `target` symlink resolves
+// into (lib/session-image-refs.js `_manifestLinkServedName`). A reference is therefore reduced to the
+// basename CTM itself would serve, and the read is async — never a sync fs call on the main loop.
+function defaultReadImageData(ref) {
+  const raw = String(ref.path || ref.url || ref.filename || '');
+  const decoded = (() => {
+    try { return decodeURIComponent(raw); } catch { return raw; }
+  })();
+  const name = nodePath.basename(decoded.replace(/[?#].*$/, ''));
+  if (!name || name === '.' || name === '..') return Promise.resolve(null);
+  const imagesDir = nodePath.resolve(getDataDir(), 'images');
+  const filePath = nodePath.join(imagesDir, name);
+  if (nodePath.dirname(filePath) !== imagesDir) return Promise.resolve(null);
+  return fsPromises.readFile(filePath).then(
+    (bytes) => (bytes && bytes.length
+      ? { mimeType: ref.mimeType || MIME_BY_EXT[nodePath.extname(name).toLowerCase()] || 'image/png',
+        data: bytes.toString('base64') }
+      : null),
+    // expected: a missing/unreadable file is reported to the caller as an unreadable image, not a throw.
+    () => null,
+  );
+}
+
+function decisionForAcpKind(kind) {
+  return ACP_KIND_TO_DECISION[String(kind || '')] || '';
+}
+
+// The ACP-provided optionId for the chosen decision. `allow` prefers the one-shot allow and falls
+// back to the project-scoped allow; `deny` takes the first reject kind. No match means the bridge
+// offered nothing this decision can be expressed as, and the request is answered `cancelled`.
+//
+// NOTE the resolution SHAPE: lib/acp/acp-client.js hands the resolved value straight to
+// `result: { outcome }`, so what this lane resolves must be the ACP outcome itself —
+// `{ outcome: 'selected', optionId }`, never a pre-wrapped `{ outcome: { … } }`, which its
+// normaliseOutcome() would read as a non-string and silently downgrade to `cancelled`.
+function optionIdForDecision(options, allow) {
+  const wanted = allow ? ['allow_once', 'allow_always_project'] : ['deny'];
+  for (const decision of wanted) {
+    const match = options.find((option) => option.decision === decision);
+    if (match && match.optionId) return match.optionId;
+  }
+  return '';
+}
+
+// A bounded, human-readable summary of the tool call's input — the approval card's command line.
+// The raw input object is never handed to the recorder (it is cleaned there as well).
+function summarizeInput(input, title) {
+  if (typeof input.command === 'string' && input.command) return input.command.slice(0, MAX_PROMPT_CHARS);
+  try {
+    return JSON.stringify(input || {}).slice(0, MAX_PROMPT_CHARS) || title;
+  } catch (error) {
+    // expected: a circular or exotic rawInput is not worth failing an approval over.
+    void error;
+    return title;
+  }
+}
+
+/**
+ * @param {object} deps
+ * @param {(ctmSessionId: string) => object|null} [deps.getSession]
+ * @param {(ctmSessionId: string) => {acpSessionId, client}|null} [deps.getRuntime]  // dshRuntime.get
+ * @param {(sessionId, messageId, remoteStatus, details) => any} [deps.storeStatus]  // _storeRemoteSubmissionStatus
+ * @param {(input: object) => any} [deps.recordRuntimeApprovalRequested]
+ * @param {(approvalId: string, input: object) => any} [deps.resolveRuntimeApproval]
+ * @param {(session: object) => void} [deps.markTurnOpen]
+ * @param {(session: object, blocking: boolean) => void} [deps.markWaiting]
+ * @param {(session: object) => void} [deps.markTurnClosed]
+ * @param {(session: object) => void} [deps.requestWake]   // WP-5: start a deferred (asleep) dsh session
+ * @param {(ref: object) => Promise<{mimeType: string, data: string}|null>} [deps.readImageData]
+ *        WP-11: the ONE async byte source for an image attachment (default: CTM's `<dataDir>/images`
+ *        upload store). A null answer refuses the prompt with `dsh_image_unreadable`.
+ * @param {() => number} [deps.now]
+ * @param {(entry: {level: string, msg: string}) => void} [deps.log]
+ */
+function createDshPromptLane(deps = {}) {
+  const getSession = typeof deps.getSession === 'function' ? deps.getSession : () => null;
+  const getRuntime = typeof deps.getRuntime === 'function' ? deps.getRuntime : () => null;
+  const storeStatus = typeof deps.storeStatus === 'function' ? deps.storeStatus : () => null;
+  const recordRuntimeApprovalRequested = typeof deps.recordRuntimeApprovalRequested === 'function'
+    ? deps.recordRuntimeApprovalRequested : () => null;
+  const resolveRuntimeApproval = typeof deps.resolveRuntimeApproval === 'function'
+    ? deps.resolveRuntimeApproval : () => null;
+  const markTurnOpen = typeof deps.markTurnOpen === 'function' ? deps.markTurnOpen : () => {};
+  const markWaiting = typeof deps.markWaiting === 'function' ? deps.markWaiting : () => {};
+  const markTurnClosed = typeof deps.markTurnClosed === 'function' ? deps.markTurnClosed : () => {};
+  const requestWake = typeof deps.requestWake === 'function' ? deps.requestWake : () => {};
+  // WP-8 step 3 (§9b M-16): the completed-turn observation writer (lib/session-create/dsh-session.js
+  // `observeDshCompletedTurn`). Optional: a harness without the model-state runtime simply skips it.
+  const observeCompletedTurn = typeof deps.observeCompletedTurn === 'function' ? deps.observeCompletedTurn : () => {};
+  // WP-11: an injected byte reader keeps the lane testable without touching a real store; the default
+  // is CTM's own upload store (see defaultReadImageData above).
+  const readImageData = typeof deps.readImageData === 'function' ? deps.readImageData : defaultReadImageData;
+  const now = typeof deps.now === 'function' ? deps.now : Date.now;
+  const log = typeof deps.log === 'function' ? deps.log : () => {};
+
+  const turns = new Map();        // ctmSessionId → in-flight turn record
+  const settles = new Map();      // ctmSessionId → the in-flight turn's background-settle promise
+  const permissions = new Map();  // ctmSessionId → Array<pending permission record>
+  const toolCalls = new Map();    // ctmSessionId → the latest `tool_call` update
+
+  function warn(msg) {
+    try { log({ level: 'warn', msg }); } catch (error) { void error; } // expected: a broken log sink is never fatal
+  }
+
+  function emitStatus(sessionId, messageId, status, details) {
+    if (!messageId) return;
+    try {
+      storeStatus(sessionId, messageId, status, { ...details, source: details.source || 'dsh' });
+    } catch (error) {
+      warn(`dsh-prompt-lane: status ${status} failed (${error && error.message})`);
+    }
+  }
+
+  function safeCall(fn, label, ...args) {
+    try { return fn(...args); } catch (error) {
+      warn(`dsh-prompt-lane: ${label} failed (${error && error.message})`);
+      return undefined;
+    }
+  }
+
+  function pendingList(sessionId) {
+    return permissions.get(sessionId) || [];
+  }
+
+  function dropPermission(sessionId, record) {
+    const list = pendingList(sessionId);
+    const at = list.indexOf(record);
+    if (at >= 0) list.splice(at, 1);
+    if (!list.length) permissions.delete(sessionId);
+  }
+
+  // --- tool_call tracking (§9 S-37: the runtime forwards every session/update here) ------------
+
+  /** One ACP `session/update` for a session this lane owns. Tracks the latest tool call. */
+  function onUpdate(ctmSessionId, update) {
+    if (!ctmSessionId || !update || typeof update !== 'object') return;
+    if (update.sessionUpdate === 'tool_call' && update.toolCallId) {
+      toolCalls.set(ctmSessionId, update);
+    }
+    const turn = turns.get(ctmSessionId);
+    if (turn) turn.sawUpdate = true;
+  }
+
+  // --- prompt lane (§9 S-32) -------------------------------------------------------------------
+
+  // The ONE refusal shape for "this session already has a turn in flight". The preflight wrap and
+  // the delivery guard below both use it, so the two doors cannot describe the same state
+  // differently (AC-4e).
+  function turnInFlightBlocker() {
+    return {
+      ok: false,
+      error: 'dsh_turn_in_flight',
+      reason: 'dsh_turn_in_flight',
+      retryable: true,
+      message: TURN_IN_FLIGHT_MESSAGE,
+    };
+  }
+
+  // WP-5 (D-5/D-9, AC-5c): this session's child is gone (it died, or CTM restarted) and it is an
+  // ordinary deferred placeholder again. Ask for the wake and answer with the ONE in-set transient
+  // blocker, exactly like every other asleep session — the prompt is not silently dropped.
+  function asleepBlocker(session) {
+    safeCall(requestWake, 'requestWake', session);
+    return {
+      ok: false,
+      error: 'session_resume_not_ready',
+      reason: 'dsh_restore_starting',
+      retryable: true,
+      message: 'The DeepSeek Harness session is restarting; this message will be delivered when it is ready.',
+    };
+  }
+
+  /** Wrap the root prompt flow's synchronous preflight: ACP sessions refuse a second turn. */
+  function wrapPreflight(existing) {
+    return function preflight(...args) {
+      const [sessionId, session] = args;
+      if (!isAcpSession(session)) return existing(...args);
+      if (session && session._restoreDeferred) return asleepBlocker(session);
+      const turn = turns.get(sessionId);
+      if (turn && turn.inFlight) return turnInFlightBlocker();
+      return null;
+    };
+  }
+
+  // The background half of one turn. It must never throw (its caller catches anyway) and it is
+  // idempotent about releasing the seat, so a child exit that already cleared the turn is harmless.
+  function runSettle(session, turn, stopReason, failure) {
+    const sessionId = turn.sessionId;
+    const source = turn.source;
+    turn.inFlight = false;
+    if (turns.get(sessionId) === turn) turns.delete(sessionId);
+    if (settles.get(sessionId) === turn.settled) settles.delete(sessionId);
+    const transcript = session && session._dshTranscript;
+    safeCall(() => transcript?.flush(), 'flush');
+    settlePermissions(sessionId, 'cancelled');
+    safeCall(() => markTurnClosed(session), 'markTurnClosed');
+
+    if (failure) {
+      const message = (failure && failure.message) || 'DeepSeek Harness turn failed';
+      if (failure.code === 'acp_turn_failed') {
+        safeCall(() => transcript?.appendTurnFailed(message), 'appendTurnFailed');
+      }
+      emitStatus(sessionId, turn.receiptId, 'failed', { reason: 'dsh_turn_failed', message, source });
+      turn.outcome = { ok: false, status: 'failed', code: 'dsh_turn_failed', error: 'dsh_turn_failed',
+        retryable: false, message };
+      return turn.outcome;
+    }
+    if (turn.cancelled || stopReason === 'cancelled') {
+      emitStatus(sessionId, turn.receiptId, 'blocked',
+        { reason: 'dsh_turn_cancelled', message: TURN_CANCELLED_MESSAGE, source });
+      turn.outcome = { ok: false, status: 'blocked', code: 'dsh_turn_cancelled', error: 'dsh_turn_cancelled',
+        retryable: false, message: TURN_CANCELLED_MESSAGE };
+      return turn.outcome;
+    }
+    // WP-8 step 3 (§9b M-16, D-13): a COMPLETED turn is the second half of the model evidence — the
+    // bridge's `configOptions` show what the session ran, and the turn proves it actually ran. The
+    // model-state runtime owns the write (source `dsh:turn`); this lane only reports the edge, exactly
+    // once, and a failed observation write can never turn a completed turn into a failed one.
+    safeCall(() => observeCompletedTurn(session, configOptionsFor(sessionId)), 'observeCompletedTurn');
+    turn.outcome = { ok: true, status: 'sent', signal: 'durable_row', source };
+    return turn.outcome;
+  }
+
+  // §6.5 + §9 S-32. The delivery contract the root flow enforces is "delivered = the write was
+  // confirmed" (lib/root-delivery-runtime.js awaits this, then re-checks the delivery lease and the
+  // permit stays issued until it returns). A dsh turn can run for many minutes, so this returns as
+  // soon as `session/prompt` is on the wire and the turn settles in the BACKGROUND through
+  // runSettle — otherwise a long turn would report root_delivery_expired and pin the permit.
+  async function deliverAcp(session, args) {
+    const sessionId = session.id;
+    // Two preflights can pass before either delivery starts (§9 S-32), so the door is guarded here
+    // too: refuse exactly like the preflight wrap and send nothing.
+    if (turns.get(sessionId)?.inFlight) return turnInFlightBlocker();
+    // Two preflights can pass before either delivery starts (§9 S-32), and a wake can lose the race
+    // with a crash — so the door checks the asleep state too, and still sends nothing.
+    if (session._restoreDeferred) return asleepBlocker(session);
+    const receiptId = String(args.submissionId || args.parentReceiptId || '');
+    const source = String(args.source || 'dsh');
+    const runtime = getRuntime(sessionId);
+    if (!runtime || typeof runtime.client?.prompt !== 'function') {
+      return { ok: false, status: 'failed', code: 'dsh_not_running', error: 'dsh_not_running',
+        retryable: false, message: NOT_RUNNING_MESSAGE };
+    }
+    const transcript = session._dshTranscript;
+    const text = String(args.text ?? '');
+    // WP-11 (D-20): the images this submission names ride the submission's OWN `attachments` field
+    // (the same field lib/root-prompt-admission.js captures and lib/root-delivery-runtime.js hands to
+    // `deliverTerminal`). The capability door is checked FIRST, so an unsupported prompt writes
+    // nothing to the wire and nothing to the transcript (AC-11b).
+    const imageRefs = collectImageRefs(args.attachments);
+    if (imageRefs.length && runtime.imageInput !== true) {
+      return { ok: false, status: 'failed', code: IMAGE_UNSUPPORTED_CODE, error: IMAGE_UNSUPPORTED_CODE,
+        retryable: false, message: IMAGE_UNSUPPORTED_MESSAGE };
+    }
+    let images = [];
+    let blocks = null;
+    if (imageRefs.length) {
+      // Off the main loop: the bytes come from the async upload-store read (never sync fs), and an
+      // image CTM cannot read refuses the whole prompt rather than sending a prompt that quietly
+      // dropped it.
+      try {
+        images = (await Promise.all(imageRefs.map((ref) => Promise.resolve(readImageData(ref))))).filter(Boolean);
+      } catch (error) {
+        warn(`dsh-prompt-lane: image read failed (${error && error.message})`);
+        images = [];
+      }
+      if (images.length !== imageRefs.length) {
+        return { ok: false, status: 'failed', code: IMAGE_UNREADABLE_CODE, error: IMAGE_UNREADABLE_CODE,
+          retryable: false, message: IMAGE_UNREADABLE_MESSAGE };
+      }
+      // ACP content blocks: the text block first, then one block per image — the shape
+      // lib/acp/acp-client.js `prompt({ blocks })` already writes.
+      blocks = [{ type: 'text', text },
+        ...images.map((image) => ({ type: 'image', mimeType: image.mimeType || 'image/png', data: image.data }))];
+    }
+    const turn = {
+      inFlight: true, cancelled: false, childExited: false, startedAt: now(), sawUpdate: false,
+      sessionId, receiptId, source, settled: null, outcome: null,
+    };
+    turns.set(sessionId, turn);
+    safeCall(() => transcript?.appendUserPrompt({ text, clientMessageId: receiptId || null, images }),
+      'appendUserPrompt');
+    emitStatus(sessionId, receiptId, 'received', { source });
+    safeCall(() => markTurnOpen(session), 'markTurnOpen');
+
+    let promptPromise;
+    try {
+      // A text-only prompt is passed EXACTLY as before (`{sessionId, text}` — no `blocks` key), so the
+      // bytes on the wire for every existing dsh prompt are unchanged (AC-11c).
+      promptPromise = blocks
+        ? runtime.client.prompt({ sessionId: runtime.acpSessionId, text, blocks })
+        : runtime.client.prompt({ sessionId: runtime.acpSessionId, text });
+    } catch (error) {
+      // A synchronous throw means nothing reached the wire: keep the immediate failure result.
+      turns.delete(sessionId);
+      safeCall(() => markTurnClosed(session), 'markTurnClosed');
+      const message = (error && error.message) || NOT_RUNNING_MESSAGE;
+      safeCall(() => transcript?.appendTurnFailed(message), 'appendTurnFailed');
+      emitStatus(sessionId, receiptId, 'failed', { reason: 'dsh_turn_failed', message });
+      return { ok: false, status: 'failed', code: 'dsh_turn_failed', error: 'dsh_turn_failed',
+        retryable: false, message };
+    }
+    // The ACP client writes `session/prompt` synchronously inside prompt(), so the request is on the
+    // wire by the time the call returns and the durable signal is truthful here (§6.5).
+    emitStatus(sessionId, receiptId, 'durable_user_message_seen', { reason: 'dsh_prompt_written', source });
+
+    const settleOnce = (stopReason, failure) => {
+      try { return runSettle(session, turn, stopReason, failure); }
+      catch (error) {
+        warn(`dsh-prompt-lane: turn settle failed (${error && error.message})`);
+        return null;
+      }
+    };
+    // Both arms route through settleOnce, so this promise cannot reject — no unhandled rejection can
+    // ever come out of a dsh turn (T-10).
+    turn.settled = Promise.resolve(promptPromise).then(
+      (result) => settleOnce(String((result && result.stopReason) || ''), null),
+      (error) => settleOnce('', error),
+    );
+    settles.set(sessionId, turn.settled);
+    return { ok: true, status: 'sent', signal: 'durable_row', source };
+  }
+
+  /** Wrap the root prompt flow's terminal deliverer: ACP sessions take the prompt themselves. */
+  function wrapDeliver(existing) {
+    return function deliverTerminal(...args) {
+      const submission = args[0] || {};
+      const session = getSession(submission.sessionId) || submission.target?.session || null;
+      if (!isAcpSession(session)) return existing(...args);
+      return deliverAcp(session, submission);
+    };
+  }
+
+  /**
+   * Resolves once the in-flight turn's background settle has finished (with the settle outcome), or
+   * immediately with `null` when no turn is in flight. Test/WP-5 seam: the delivery itself no longer
+   * waits for the turn, so anything asserting the turn's END has to await this.
+   */
+  function whenTurnSettled(sessionId) {
+    const pending = sessionId ? settles.get(sessionId) : null;
+    if (!pending) return Promise.resolve(null);
+    return pending.then(
+      (outcome) => outcome || null,
+      (error) => { warn(`dsh-prompt-lane: turn settle rejected (${error && error.message})`); return null; },
+    );
+  }
+
+  // --- cancel (§9 S-33) ------------------------------------------------------------------------
+
+  /** Stop an in-flight ACP turn. Anything else (including an idle ACP session) uses the fallback. */
+  function interruptOr(session, fallback) {
+    if (!isAcpSession(session)) return fallback;
+    const sessionId = session && session.id;
+    const turn = sessionId ? turns.get(sessionId) : null;
+    if (!turn || !turn.inFlight) return fallback;
+    const runtime = getRuntime(sessionId);
+    if (!runtime || typeof runtime.client?.cancel !== 'function') return fallback;
+    turn.cancelled = true;
+    try {
+      // The client answers this session's pending permissions `cancelled` itself (P-4); the lane
+      // then settles its own promises, so a permission is still answered exactly once.
+      runtime.client.cancel({ sessionId: runtime.acpSessionId });
+    } catch (error) {
+      warn(`dsh-prompt-lane: session/cancel failed (${error && error.message})`);
+      turn.cancelled = false;
+      return fallback;
+    }
+    settlePermissions(sessionId, 'cancelled');
+    return { ok: true };
+  }
+
+  // --- approvals (D-7, §9 S-35, T-10) ----------------------------------------------------------
+
+  /** One `session/request_permission`: register a runtime approval, park until a decision. */
+  function onRequestPermission(ctmSessionId, params = {}) {
+    const session = getSession(ctmSessionId);
+    const options = Array.isArray(params.options) ? params.options : [];
+    const toolCallId = String(params.toolCall?.toolCallId || '');
+    const tracked = toolCalls.get(ctmSessionId);
+    const tool = tracked && (!toolCallId || String(tracked.toolCallId || '') === toolCallId)
+      ? tracked
+      : (params.toolCall && typeof params.toolCall === 'object' ? params.toolCall : {});
+    const title = String(tool.title || tool.name || tool.kind || 'Tool call');
+    const rawInput = tool.rawInput && typeof tool.rawInput === 'object' ? tool.rawInput : {};
+    const approvalOptions = options.map((option) => ({
+      optionId: String(option?.optionId || ''),
+      label: String(option?.name || ''),
+      decision: decisionForAcpKind(option?.kind),
+    }));
+    // `hook:` is the prefix lib/runtime-approval-executor.js routes to the isHookPending/resolveHook
+    // seam — the seam the server wraps for ACP sessions (S-35).
+    const approvalId = `hook:dsh:${ctmSessionId}:${toolCallId || 'permission'}`;
+    const record = { approvalId, ctmSessionId, toolCallId, options: approvalOptions, settled: false, resolve: null };
+    const pending = new Promise((resolve) => { record.resolve = resolve; });
+    const list = pendingList(ctmSessionId);
+    list.push(record);
+    permissions.set(ctmSessionId, list);
+    safeCall(recordRuntimeApprovalRequested, 'recordRuntimeApprovalRequested', {
+      approvalId,
+      ctmSessionId,
+      adapter: 'dsh',
+      source: 'dsh-acp',
+      turnId: turns.get(ctmSessionId)?.turnId || '',
+      toolCallId,
+      toolName: title,
+      prompt: summarizeInput(rawInput, title),
+      approvalOptions,
+      metadata: { toolCallId },
+    });
+    safeCall(() => markWaiting(session, true), 'markWaiting');
+    return pending;
+  }
+
+  /** Is an ACP permission pending for this session? (The executor's isHookPending seam, S-35.) */
+  function isPending(sessionId) {
+    return pendingList(sessionId).some((record) => !record.settled);
+  }
+
+  // Answers the ACP request with the optionId the bridge itself offered for this decision.
+  function answerPermission(record, allow) {
+    if (record.settled) return false;
+    record.settled = true;
+    dropPermission(record.ctmSessionId, record);
+    const optionId = optionIdForDecision(record.options, allow);
+    record.resolve(optionId ? { outcome: 'selected', optionId } : { outcome: 'cancelled' });
+    safeCall(() => markWaiting(getSession(record.ctmSessionId), false), 'markWaiting');
+    return true;
+  }
+
+  /** The executor's resolveHook seam (S-35): resolve a pending ACP permission. */
+  function resolvePermission(sessionId, decision, source, approvalId) {
+    const list = pendingList(sessionId).filter((record) => !record.settled);
+    if (!list.length) return false;
+    const record = (approvalId && list.find((entry) => entry.approvalId === approvalId)) || list[0];
+    const allow = String(decision || '').toLowerCase() === 'allow';
+    void source; // the executor persists the decision through resolveRuntimeApproval itself
+    return answerPermission(record, allow);
+  }
+
+  // Every pending permission answers `cancelled` exactly once and its runtime approval resolves
+  // `expired` (T-10). Idempotent: a settled record is never touched again.
+  function settlePermissions(sessionId, outcome) {
+    let settled = 0;
+    for (const record of [...pendingList(sessionId)]) {
+      if (record.settled) continue;
+      record.settled = true;
+      dropPermission(sessionId, record);
+      record.resolve({ outcome });
+      safeCall(resolveRuntimeApproval, 'resolveRuntimeApproval', record.approvalId, {
+        ctmSessionId: sessionId,
+        status: 'expired',
+        decidedBy: 'dsh-session',
+        metadata: { toolCallId: record.toolCallId },
+      });
+      settled += 1;
+    }
+    return settled;
+  }
+
+  /** The ACP child is gone (stop, cancel-after-exit, or a crash): nothing may stay parked. */
+  function onChildExit(ctmSessionId) {
+    const turn = turns.get(ctmSessionId);
+    if (turn) {
+      turn.inFlight = false;
+      turn.childExited = true;
+      turns.delete(ctmSessionId);
+    }
+    const settled = settlePermissions(ctmSessionId, 'cancelled');
+    toolCalls.delete(ctmSessionId);
+    return settled;
+  }
+
+  function turnState(sessionId) {
+    const turn = turns.get(sessionId);
+    return turn ? { inFlight: !!turn.inFlight, cancelled: !!turn.cancelled } : null;
+  }
+
+  // WP-8 step 3 (§6.7): the read-only half of `turnState` for callers that only need the yes/no — the
+  // ACP runtime refuses a config-option write while a prompt is in flight (never queues it), and it
+  // asks through this one predicate. Anything but an explicit `true` reads as "no turn".
+  function isTurnInFlight(sessionId) {
+    return turns.get(sessionId)?.inFlight === true;
+  }
+
+  // The bridge's own `configOptions` for a live ACP child — what the session is ACTUALLY running. A
+  // gone child (the runtime entry is dropped on exit) reads as null, never as a stale list.
+  function configOptionsFor(sessionId) {
+    const runtime = getRuntime(sessionId);
+    return runtime && Array.isArray(runtime.configOptions) ? runtime.configOptions : null;
+  }
+
+  return {
+    wrapPreflight,
+    wrapDeliver,
+    interruptOr,
+    onUpdate,
+    onRequestPermission,
+    isPending,
+    resolvePermission,
+    onChildExit,
+    turnState,
+    isTurnInFlight,
+    whenTurnSettled,
+  };
+}
+
+module.exports = {
+  createDshPromptLane,
+  ACP_KIND_TO_DECISION,
+  TURN_IN_FLIGHT_MESSAGE,
+  IMAGE_UNSUPPORTED_CODE,
+  IMAGE_UNSUPPORTED_MESSAGE,
+  IMAGE_UNREADABLE_CODE,
+  IMAGE_UNREADABLE_MESSAGE,
+};