zcode-acp-server 0.14.2 → 0.17.1

package/dist/handlers/session.js

@@ -11,19 +11,24 @@
  * notifications.
  */
 import process from "node:process";
+import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
 import { RequestError } from "@agentclientprotocol/sdk";
 import { EventStreamListener, TurnMonitor } from "../backend/listener.js";
+import { resolveReal } from "../backend/sandbox.js";
 import { buildModes, buildConfigOptions, formatModelValue, loadAllModels, } from "../config/options.js";
 import { emitInitialUsage } from "../config/model-cache.js";
 import { buildProviderRegistry } from "../config/provider-registry.js";
 import { buildResumeRuntimeModel } from "../config/runtime-model.js";
+import { messages } from "../i18n.js";
 import { lookupLazySession, recordMaterializedSession, rememberLazySession, } from "../lazy-sessions.js";
 import { buildDiffContent, EventTranslator, extractLocations, formatTurnError, isTransientTurnError, ProjectionDiffer, } from "../translators/index.js";
 import { log, warn } from "../utils.js";
 import { dispatchEvent } from "./dispatch.js";
 import { sendSessionUpdate, sendTextChunk, withReplayBatch } from "./io.js";
 import { fetchMessages, fullSlice, readTailLimit, replayMessages, sliceTail } from "./replay.js";
+import { extractPermDeniedPath, extractSandboxDenial, GENERIC_HINT_KEY, handleSandboxDenial, READ_ONLY_TOOLS, } from "./sandbox-allow.js";
 import { handleServerRequests } from "./server-requests.js";
 /** Workspace descriptor used in session create/resume calls. */
 function workspaceFor(cwd) {
@@ -39,6 +44,20 @@ function workspaceFor(cwd) {
 function sanitizeClientCwd(client) {
     return client && client !== "/" ? client : null;
 }
+/**
+ * Same-directory check tolerant of spelling: a workspace can be recorded or
+ * reported under a symlinked / non-canonical spelling while the serve bridge
+ * holds the resolved process cwd. Compare realpaths; a vanished path falls
+ * back to raw equality (both sides unchanged → still equal).
+ */
+function sameProjectDir(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return a === b;
+    }
+}
 /**
  * The authoritative Session Root for an EXISTING session: what the bridge
  * already recorded (set at creation, or refreshed from the backend's resume
@@ -100,7 +119,10 @@ function toIso(ms) {
 export async function newSession(server, params) {
     // Creation is the one moment a client's cwd is trusted (the editor
     // declaring its worktree); "/" is still rejected as a degenerate root.
-    const cwd = sanitizeClientCwd(params.cwd) ?? process.cwd();
+    // Serve mode (ADR-0014) is the exception: a headless bridge exists for ONE
+    // hub-chosen project — the process cwd wins and client-supplied values are
+    // ignored, so the remote create-whitelist cannot be bypassed via session/new.
+    const cwd = server.serveMode ? process.cwd() : (sanitizeClientCwd(params.cwd) ?? process.cwd());
     // Placeholder id — the client addresses this session with it until the
     // backend session materializes; never shown in session/list.
     const acpSid = randomUUID();
@@ -165,15 +187,29 @@ export async function ensureRealSession(server, acpSid) {
         // (the backend session still exists — re-register the alias); one without
         // re-hydrates the pending entry so the create path below runs.
         const record = lookupLazySession(acpSid);
+        // Serve mode (ADR-0014) honors durable records for ITS OWN project only.
+        // Aliases are minted by editor bridges, which trust their local client's
+        // session/new cwd — a remote client can mint {sid → arbitrary cwd} there
+        // and then resume it here to drag this bridge into a foreign workspace.
+        // Records from another cwd read as unknown ids. The comparison tolerates
+        // spelling differences (symlinked record cwd vs the resolved process cwd)
+        // — same project under another spelling stays resumable.
+        if (server.serveMode && record && !sameProjectDir(record.cwd, process.cwd())) {
+            log(`ensureRealSession: serve mode ignores a foreign lazy record (${acpSid})`);
+            throw new Error(`session ${acpSid} not found`);
+        }
         if (record?.zcodeSid) {
             server.registerSession(acpSid, record.zcodeSid);
             return record.zcodeSid;
         }
         if (record) {
-            pending = { cwd: record.cwd };
+            // Serve mode pins to its process cwd even here (belt and suspenders —
+            // the guard above already proved the record's cwd matches).
+            const cwd = server.serveMode ? process.cwd() : record.cwd;
+            pending = { cwd };
             server.pendingSessions.set(acpSid, pending);
-            if (record.cwd !== "/")
-                server.sessionCwds.set(acpSid, record.cwd);
+            if (cwd !== "/")
+                server.sessionCwds.set(acpSid, cwd);
         }
     }
     if (!pending)
@@ -248,8 +284,12 @@ export async function ensureRealSession(server, acpSid) {
 export async function listSessions(server, params) {
     const backend = server.ensureBackend();
     const zcParams = {};
-    if (params.cwd) {
-        zcParams.workspace = workspaceFor(params.cwd);
+    // Serve mode (ADR-0014) pins the workspace: a remote client must not use a
+    // client-supplied cwd to enumerate the machine's sessions in OTHER projects
+    // (the backend scopes the listing to the workspace it is given).
+    const listCwd = server.serveMode ? process.cwd() : params.cwd;
+    if (listCwd) {
+        zcParams.workspace = workspaceFor(listCwd);
     }
     const resp = await backend.request(server.nextId(), "session/list", zcParams, 15000);
     if (resp.error)
@@ -342,8 +382,10 @@ export async function resumeSession(server, params, cx) {
     // The Session Root never comes from the client (params.cwd is ignored):
     // start from what the bridge recorded, then let the backend's own resume
     // result correct it below — a remote client must not move a session's
-    // file scope by sending its own cwd.
-    let cwd = authoritativeSessionCwd(server, acpSid);
+    // file scope by sending its own cwd. Serve mode (ADR-0014) skips both
+    // sources: the bridge exists for ONE hub-chosen project, so the root (and
+    // the workspace sent to the backend's resume) stays the process cwd.
+    let cwd = server.serveMode ? process.cwd() : authoritativeSessionCwd(server, acpSid);
     // Lazy placeholders (session/new) resolve to their real backend session
     // here; alreadyLive targets skip the resume RPC because the session is live
     // in this backend subprocess.
@@ -375,9 +417,16 @@ export async function resumeSession(server, params, cx) {
         await repairUnavailableModel(server, zcodeSid);
         // The backend's session record is the root authority: adopt its
         // workspace as the session root (heals any stale/polluted entry).
+        // Serve mode keeps its pinned cwd (see above) — and a session that
+        // genuinely lives in ANOTHER workspace is refused outright: a raw
+        // backend id from session/list elsewhere must not be replayed through
+        // a serve bridge pinned to one project.
         const backendWs = workspaceFromResumeResult(resumeResult);
-        if (backendWs)
+        if (backendWs && !server.serveMode)
             cwd = backendWs;
+        if (server.serveMode && backendWs && !sameProjectDir(backendWs, process.cwd())) {
+            throw new Error("session belongs to another workspace");
+        }
     }
     server.registerSession(acpSid, zcodeSid);
     // The session root for remote file access — backend-authoritative (see
@@ -407,8 +456,9 @@ export async function loadSession(server, params, cx) {
     // The Session Root never comes from the client (params.cwd is ignored):
     // start from what the bridge recorded, then let the backend's own resume
     // result correct it below — a remote client must not move a session's
-    // file scope by sending its own cwd.
-    let cwd = authoritativeSessionCwd(server, acpSid);
+    // file scope by sending its own cwd. Serve mode (ADR-0014) pins the root
+    // (and the workspace sent to resume) to the process cwd throughout.
+    let cwd = server.serveMode ? process.cwd() : authoritativeSessionCwd(server, acpSid);
     // Same placeholder resolution as resumeSession; alreadyLive targets skip the
     // backend resume RPC (the session is live in this subprocess).
     const { zcodeSid, alreadyLive } = await resolveResumeTarget(server, acpSid);
@@ -428,9 +478,14 @@ export async function loadSession(server, params, cx) {
         await repairUnavailableModel(server, zcodeSid);
         // The backend's session record is the root authority: adopt its
         // workspace as the session root (heals any stale/polluted entry).
+        // Serve mode keeps its pinned cwd (see above) — and refuses sessions
+        // from another workspace outright (same rule as resumeSession).
         const backendWs = workspaceFromResumeResult(resumeResult);
-        if (backendWs)
+        if (backendWs && !server.serveMode)
             cwd = backendWs;
+        if (server.serveMode && backendWs && !sameProjectDir(backendWs, process.cwd())) {
+            throw new Error("session belongs to another workspace");
+        }
     }
     server.registerSession(acpSid, zcodeSid);
     // Same as resumeSession: backend-authoritative session root for file access.
@@ -488,8 +543,41 @@ export async function loadSession(server, params, cx) {
     };
     return result;
 }
-/** `session/prompt` → subscribe-before-send, run the event-driven turn loop. */
+/**
+ * `session/prompt` → subscribe-before-send, run the event-driven turn loop.
+ *
+ * Sandbox allow-restart chaining (ADR-0011): when a turn unwinds as cancelled
+ * because the user approved a new writable root (the backend was killed to be
+ * respawned under the widened profile), the continuation prompt runs INSIDE
+ * this same request via runPrompt. The editor's spinner then spans the
+ * respawn+reload window and the resumed work renders as the same turn. A
+ * detached follow-up prompt (the previous design) has no pending editor
+ * request behind it, so the editor showed no running state for it at all —
+ * the window read as "it just stopped", any message typed there preempted
+ * the continuation for real, and only the session/load replay later surfaced
+ * the orphaned continuation bubble.
+ */
 export async function prompt(server, params, cx, requestId) {
+    const result = await runPrompt(server, params, cx, requestId);
+    const continuation = server.sandboxContinuations.get(params.sessionId);
+    if (continuation && result.stopReason === "cancelled") {
+        server.sandboxContinuations.delete(params.sessionId);
+        // Same request, fresh round: runPrompt re-enters the whole machinery
+        // (ensureBackend respawns; ensureRealSession/subscribe-recovery reloads
+        // the session into it). The user's preempt/ESC during the continuation
+        // still cancels it — the round registers itself in pendingTurns.
+        return runPrompt(server, { sessionId: params.sessionId, prompt: [{ type: "text", text: continuation }] }, cx, `sandbox-cont-${randomUUID()}`, true);
+    }
+    return result;
+}
+/** One prompt round: subscribe-before-send, run the event-driven turn loop. */
+async function runPrompt(server, params, cx, requestId, continuationRound = false) {
+    // 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);
@@ -659,7 +747,7 @@ export async function prompt(server, params, cx, requestId) {
                     return { stopReason: "cancelled" };
                 }
                 differ.markSeen(await fetchMessages(server, zcodeSid));
-                await sendTextChunk(cx, params.sessionId, `[网络异常，正在重试 (${attempt - 1}/${MAX_TURN_ATTEMPTS - 1})…]`, randomUUID());
+                await sendTextChunk(cx, params.sessionId, 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));
             }
@@ -729,7 +817,9 @@ export async function prompt(server, params, cx, requestId) {
                     sendErrMsg.includes("prompt is running") ||
                     sendErrMsg.includes("already running");
                 if (!isBusy) {
-                    // Non-busy error (auth, malformed, etc.) — don't retry, surface it.
+                    // Non-busy error (auth, malformed, stale model, etc.) — don't
+                    // retry, surface it. The stale-history-model case is repaired
+                    // before the send (repairUnavailableModel on every resume path).
                     throw new Error(`zcode send failed: ${sendResp.error.message ?? ""}`);
                 }
                 if (Date.now() - sendT0 > SEND_RETRY_TIMEOUT_MS) {
@@ -737,6 +827,14 @@ export async function prompt(server, params, cx, requestId) {
                 }
                 log(`  [send] backend busy (${sendResp.error.message ?? ""}), retrying in ${SEND_RETRY_INTERVAL_MS}ms`);
             }
+            // Continuation round status line: the respawn+reload window (~seconds)
+            // shows only the editor spinner before the model's first output — a
+            // 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());
+            }
             try {
                 // Event-driven turn loop: translate events via EventTranslator + dispatch.
                 // Arm the attribution gate also on a recent cancel: the abandoned turn
@@ -760,6 +858,9 @@ export async function prompt(server, params, cx, requestId) {
                     const { maybeAutoCompact } = await import("../config/auto-compact.js");
                     await maybeAutoCompact(server, cx, params.sessionId, 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) {
@@ -783,7 +884,7 @@ export async function prompt(server, params, cx, requestId) {
         // 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, `[请求失败：${errMsg}。会话仍可用，请重新发送消息重试。]`, randomUUID());
+        await sendTextChunk(cx, params.sessionId, messages().requestFailed(errMsg), randomUUID());
         return { stopReason: "end_turn" };
     }
     finally {
@@ -1064,7 +1165,7 @@ export async function drainBackendAfterCancel(server, deps) {
         }
         if (!noticed) {
             noticed = true;
-            await sendTextChunk(cx, acpSid, "[上一个回复仍在生成，等待结束后发送…]", randomUUID());
+            await sendTextChunk(cx, acpSid, messages().promptQueuedBehindTurn, randomUUID());
         }
         await sleep(DRAIN_POLL_MS);
     }
@@ -1299,12 +1400,22 @@ async function resumeBackendSession(server, zcParams) {
  * fails). Marks the session backend-loaded on success.
  */
 async function reloadBackendSession(server, acpSid, zcodeSid) {
+    const cwd = server.sessionCwds.get(acpSid) ?? process.cwd();
     const zcParams = {
         sessionId: zcodeSid,
-        workspace: workspaceFor(server.sessionCwds.get(acpSid) ?? process.cwd()),
+        workspace: workspaceFor(cwd),
     };
+    // Same pre-resume steps as the ACP resume/load handlers: register the
+    // provider registry (a resumed session's history references a model the
+    // fresh backend can't process until its provider is registered — sends
+    // then fail with the backend's stale-history-model error, persistent, not
+    // transient), then repair a model that is no longer enabled. Skipping
+    // these made every backend respawn (sandbox allow-restart, eviction
+    // recovery) deaf-fail its first sends.
+    await syncProviderRegistry(server, cwd);
     await resumePreservingModel(server, zcParams);
     server.markBackendLoaded(acpSid);
+    await repairUnavailableModel(server, zcodeSid);
 }
 /**
  * Resume WITHOUT pinning a model, so the session keeps its own selection (the
@@ -1383,8 +1494,34 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
     const translator = new EventTranslator();
     differ.resetTurn();
     const NO_PROGRESS_MS = 120_000;
+    // Stall termination policy. Two candidate liveness signals were verified
+    // against the Aug-28 app-server and both are unusable for kill decisions:
+    //   - `session/goal show` succeeds mid-turn (never reports the 1308 lock),
+    //   - a probe `session/send` is ACCEPTED while the turn runs (queued as
+    //     steer input) — the prompt lock is only held during finalisation.
+    // So "lock released" proves nothing about turn liveness, and killing on it
+    // murdered live sub-agent turns after 120s of stream silence. The honest
+    // signal is the read-projection watermark: contextUsed / totalTokenCount /
+    // turnCount / currentTurnId advance while the backend makes progress
+    // (verified: a sub-agent turn advanced the watermark for 5+ minutes with
+    // zero stream events). A live turn may still freeze the watermark for a
+    // while (long CoT, quiet tools — observed 60s+ pauses), so a freeze alone
+    // never kills: only a freeze sustained past STALE_FREEZE_MS ends the turn,
+    // reply-fetch first, stop as the last resort.
+    const STALE_FREEZE_MS = 600_000;
     let lastProtocolProgressAt = Date.now();
     let nextNoProgressDecisionAt = lastProtocolProgressAt + NO_PROGRESS_MS;
+    let lastWatermarkAdvanceAt = Date.now();
+    let watermark = "";
+    const noteWatermark = (proj) => {
+        if (!proj)
+            return;
+        const next = `${proj.contextUsed ?? 0}/${proj.totalTokenCount ?? 0}/${proj.turnCount ?? 0}/${proj.currentTurnId ?? ""}`;
+        if (next !== watermark) {
+            watermark = next;
+            lastWatermarkAdvanceAt = Date.now();
+        }
+    };
     let lastStallCheck = Date.now();
     let emittedText = false;
     let emittedOutput = false;
@@ -1416,19 +1553,34 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                 return { stopReason: "max_turn_requests" };
             }
             else {
-                const lockState = await probePromptLock(server, turn.zcodeSid);
-                if (lockState === "held") {
-                    // A prompt-lock failure is direct evidence that the backend still owns
-                    // an active turn. It is liveness, not protocol progress: leave
-                    // lastProtocolProgressAt untouched and schedule a later decision.
-                    // This protects legitimately long model/tool operations without
-                    // allowing a stale `projection.status=running` to refresh the clock.
+                const frozenMs = Date.now() - lastWatermarkAdvanceAt;
+                if (frozenMs < STALE_FREEZE_MS) {
+                    // The read watermark moved recently — direct evidence the backend is
+                    // still making progress (typically a sub-agent or slow tool working
+                    // behind a silent stream). Keep waiting; the 15s stall-reconcile
+                    // below keeps refreshing the watermark via session/read.
                     const activeTools = [...translator.seenToolIds].filter((toolId) => !translator.finalToolIds.has(toolId)).length;
-                    log(`  [stall] prompt lock still held after ${Math.round((Date.now() - lastProtocolProgressAt) / 1000)}s silence (activeTools=${activeTools}); deferring terminal decision`);
+                    log(`  [stall] watermark advanced within the last ${Math.round(frozenMs / 1000)}s (activeTools=${activeTools}); deferring terminal decision`);
                     nextNoProgressDecisionAt = Date.now() + NO_PROGRESS_MS;
                 }
+                else if (emittedText || emittedOutput) {
+                    // Watermark frozen past the budget and something was already
+                    // delivered — treat as a completed-but-terminal-event-lost turn
+                    // (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" };
+                }
                 else {
-                    log(`  [stall] no-progress deadline reached; prompt lock=${lockState}`);
+                    const reply = await fetchLastReply(server, turn.zcodeSid, differ);
+                    if (reply) {
+                        registerFetchedReply(translator, reply);
+                        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" };
+                    }
+                    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" };
                 }
@@ -1483,7 +1635,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                 thinkingHintSent = true;
                 await sendSessionUpdate(cx, acpSid, {
                     sessionUpdate: "agent_thought_chunk",
-                    content: { type: "text", text: "正在思考…" },
+                    content: { type: "text", text: messages().thinkingPlaceholder },
                     messageId: `thinking_${chunkMsgId}`,
                 });
             }
@@ -1498,6 +1650,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                 Date.now() - lastStallCheck > 15_000) {
                 lastStallCheck = Date.now();
                 const proj = await monitor.pollOnce();
+                noteWatermark(proj);
                 if (proj?.status === "idle") {
                     // A single idle probe can also fire mid-work: the backend is silent
                     // during the model's thinking/connection phase and may report idle
@@ -1511,6 +1664,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                         continue; // alive — events will be consumed by the next poll
                     }
                     const proj2 = await monitor.pollOnce();
+                    noteWatermark(proj2);
                     if (proj2?.status === "idle" && !listener.hasQueuedEvents()) {
                         // Turn completed but the event was lost (double-confirmed).
                         if (!emittedText) {
@@ -1558,7 +1712,7 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
         // with the message lost. turn.steerQueued is definitive proof of the
         // swallow: report it at once so the user can resend immediately.
         if (ev.type === "turn.steerQueued" && !translator.turnStarted && gateArmed) {
-            await sendTextChunk(cx, acpSid, "[消息被并入仍在生成的回合，将被丢弃，请重新发送]", chunkMsgId);
+            await sendTextChunk(cx, acpSid, messages().messageSwallowedByTurn, chunkMsgId);
             return { stopReason: "max_turn_requests" };
         }
         // Turn-attribution gate: before this turn's own turn.started arrives, any
@@ -1611,6 +1765,68 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
                 differ.setLastUsage(iev.used);
             await dispatchEvent(server, cx, acpSid, iev, chunkMsgId);
         }
+        // Filesystem-permission failure surfacing (the tool output itself already
+        // reached the editor above). Two scans, both only on tool.updated so
+        // mid-stream deltas aren't scanned, and both skipping read-only tools —
+        // their output merely ECHOES text, and acting on it would raise a phantom
+        // ask for a path nothing tried to touch.
+        if (ev.type === "tool.updated") {
+            const outputText = JSON.stringify(ev.payload ?? {});
+            const toolCallId = String(ev.payload?.toolCallId ?? "");
+            const toolName = (translator.toolNames.get(toolCallId) ?? "").toLowerCase();
+            // Case-insensitive: zsh prints redirects as "operation not permitted".
+            const lower = outputText.toLowerCase();
+            const scannable = !READ_ONLY_TOOLS.has(toolName);
+            if (scannable && server.backendSandboxed && lower.includes("operation not permitted")) {
+                // Sandbox write-denial (ADR-0011): EPERM outside the Seatbelt
+                // whitelist → dynamic-allow flow (ask → persist → kill backend → the
+                // turn unwinds as cancelled; prompt() fires the continuation). Gated
+                // on the PROCESS fact backendSandboxed (not the config wish) — EPERM
+                // can only come from a sandboxed process; unsandboxed EPERM is
+                // ordinary filesystem permissions.
+                const denial = extractSandboxDenial(outputText);
+                if (denial) {
+                    await handleSandboxDenial(server, cx, acpSid, turn, denial, toolCallId);
+                    if (turn.cancelled)
+                        return { stopReason: "cancelled" };
+                }
+                else {
+                    // No path parsed — one generic hint per session, not one per retry.
+                    let asked = server.sandboxAskedPaths.get(acpSid);
+                    if (!asked) {
+                        asked = new Set();
+                        server.sandboxAskedPaths.set(acpSid, asked);
+                    }
+                    if (!asked.has(GENERIC_HINT_KEY)) {
+                        asked.add(GENERIC_HINT_KEY);
+                        await sendTextChunk(cx, acpSid, messages().sandboxGenericDenialHint, chunkMsgId);
+                    }
+                }
+            }
+            else if (scannable && lower.includes("permission denied")) {
+                // EACCES — ordinary filesystem permissions, sandbox or not. Nothing
+                // the bridge can "allow" (no popup fixes chmod/ownership), so surface
+                // it as a one-time hint per path per session; without it the model
+                // silently swallows the failure and reroutes, and the user never
+                // learns why the command died.
+                const deniedPath = extractPermDeniedPath(outputText);
+                if (deniedPath) {
+                    const cwd = server.sessionCwds.get(acpSid);
+                    const real = resolveReal(path.isAbsolute(deniedPath)
+                        ? deniedPath
+                        : path.resolve(cwd ?? process.cwd(), deniedPath));
+                    let hinted = server.fsDeniedPaths.get(acpSid);
+                    if (!hinted) {
+                        hinted = new Set();
+                        server.fsDeniedPaths.set(acpSid, hinted);
+                    }
+                    if (!hinted.has(real)) {
+                        hinted.add(real);
+                        await sendTextChunk(cx, acpSid, messages().fsPermDeniedHint(real), chunkMsgId);
+                    }
+                }
+            }
+        }
         // Edit/Write diff eager dispatch: on tool.updated result, grab the
         // structured patch from session/messages immediately (don't wait for turn
         // completion — model rate-limiting could delay it indefinitely).
@@ -1708,37 +1924,6 @@ export async function runEventTurn(server, listener, monitor, differ, cx, acpSid
         }
     }
 }
-/**
- * Probe the backend's authoritative prompt lock without waiting for it to
- * change. `session/read` projection status is intentionally not considered:
- * that projection can remain stale at `running`, which is the condition this
- * probe is used to disambiguate.
- */
-async function probePromptLock(server, zcodeSid) {
-    const backend = server.ensureBackend();
-    if (backend.isDead)
-        return "unknown";
-    try {
-        const resp = await backend.request(server.nextId(), "session/goal", { sessionId: zcodeSid, action: "show" }, 10_000);
-        if (!resp.error)
-            return "released";
-        // Lock-busy must match by error CODE, not message text: backend message
-        // wording drifts between releases (repo Gotcha), and a missed match kills
-        // a live turn. 1308 is the prompt-lock-busy code (same one the send-retry
-        // loop keys on); message matching kept as a legacy fallback.
-        if (resp.error.code === 1308)
-            return "held";
-        const message = (resp.error.message ?? "").toLowerCase();
-        if (message.includes("prompt is running") || message.includes("already running")) {
-            return "held";
-        }
-        return "unknown";
-    }
-    catch (e) {
-        log(`  [stall] prompt-lock probe failed: ${e instanceof Error ? e.message : String(e)}`);
-        return "unknown";
-    }
-}
 /**
  * Turn-attribution gate decision (pure, exported for tests): whether an event
  * observed before this turn's own `turn.started` should be dropped as leftover