chainlesschain 0.162.159 → 0.162.161

package/src/gateways/ws/background-agent-protocol.js

@@ -8,17 +8,37 @@
  * Routes (request → reply):
  *   bg-list      {all?}            → {type:"bg-list", sessions}
  *   bg-view      {bgId, lines?}    → {type:"bg-view", session, log}
- *   bg-attach    {bgId, lines?}    → {type:"bg-attach", bgId, hello, log}
+ *   bg-attach    {bgId, lines?, sinceSeq?} → {type:"bg-attach", bgId, hello,
+ *                                    log, latestSeq, [reattached, replayed,
+ *                                    replayTruncated]}
  *   bg-prompt    {bgId, text}      → {type:"bg-prompt", bgId, sent}
  *   bg-stop-turn {bgId}            → {type:"bg-stop-turn", bgId, sent}
  *   bg-detach    {bgId}            → {type:"bg-detach", bgId}
  *   bg-stop      {bgId}            → {type:"bg-stop", session}   (kill whole session)
  *
- * While attached, the server pushes unsolicited frames to that client:
- *   {type:"bg-event", bgId, event}   worker lifecycle events (turn-started /
+ * While attached, the server pushes unsolicited frames to that client, each
+ * stamped with a per-attachment monotonic `seq` (additive; older clients
+ * ignore it) so the client can detect gaps and request a replay:
+ *   {type:"bg-event", bgId, seq, event}  worker lifecycle events (turn-started /
  *                                    turn-ended / idle / accepted / error /
  *                                    transport-closed)
- *   {type:"bg-log",   bgId, chunk}   log-file delta (500ms poll)
+ *   {type:"bg-log",   bgId, seq, chunk}  log-file delta (500ms poll)
+ *
+ * Reconnect resilience: a panel whose WS blipped re-sends bg-attach with the
+ * last `seq` it saw (`sinceSeq`); the still-live relay re-pushes the frames it
+ * missed (bounded buffer) and reports `latestSeq`. If the missed range was
+ * already evicted, `replayTruncated:true` tells the client to full-resync from
+ * the log. If the relay was fully torn down (WS closed → cleanup), the fresh
+ * attach returns hello + log tail as before and the client resets its tracker.
+ *
+ * Backpressure: if the WS client drains too slowly (ws.bufferedAmount over the
+ * high water), DROPPABLE frames (bg-log) are shed while CRITICAL ones (bg-event
+ * lifecycle) are always delivered. Dropped frames are still recorded (seq
+ * advances), so the gap on the next delivered frame trips the client's
+ * replaySince recovery. A one-shot {type:"bg-lag", bgId, lagging:true} marks
+ * the start and {type:"bg-lag", bgId, lagging:false, dropped, latestSeq} the
+ * recovery — the UI shows "catching up" instead of freezing. bg-lag frames
+ * carry no seq (out-of-band control; the gap tracker ignores them).
  *
  * The state file's `transport.token` is the local takeover capability — it is
  * NEVER sent over WS. Sessions are serialized with `interactive: true/false`
@@ -26,6 +46,12 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { EventReplayBuffer } from "../../lib/event-seq-replay.js";
+import {
+  BackpressurePolicy,
+  CRITICAL,
+  DROPPABLE,
+} from "../../lib/backpressure-policy.js";
 
 const LOG_POLL_MS = 500;
 
@@ -139,6 +165,20 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
     if (existing) {
       // Idempotent re-attach: reply with the live handshake instead of
       // stacking a second relay (a reconnecting panel re-sends bg-attach).
+      // If the panel reports the last seq it saw (`sinceSeq`), replay the
+      // push frames it missed while the WS was blipped — re-sent as normal
+      // bg-event/bg-log frames (their original seq), so the client's gap
+      // tracker sees a contiguous run. `replayTruncated` tells the client the
+      // hole predates our buffer and it must full-resync (re-read the log).
+      const sinceSeq = Number(message.sinceSeq);
+      let replayTruncated = false;
+      let replayed = 0;
+      if (Number.isFinite(sinceSeq)) {
+        const { frames, truncated } = existing.buffer.replaySince(sinceSeq);
+        replayTruncated = truncated;
+        replayed = frames.length;
+        for (const frame of frames) server._send(ws, frame);
+      }
       server._send(ws, {
         id,
         type: "bg-attach",
@@ -146,6 +186,9 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
         hello: existing.hello,
         log: "",
         reattached: true,
+        latestSeq: existing.buffer.latestSeq,
+        replayed,
+        replayTruncated,
       });
       return;
     }
@@ -172,6 +215,42 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
       );
     }
 
+    // Per-attachment replay buffer: stamps a monotonic seq on every push frame
+    // and retains a bounded tail so a reconnecting client can fill gaps
+    // (bg-attach { sinceSeq }). One buffer per relay instance — seq restarts
+    // at 1 on a fresh attach, so the client resets its tracker then.
+    const buffer = new EventReplayBuffer();
+    // Backpressure: if the WS client drains too slowly (ws.bufferedAmount grows
+    // past the high water), shed DROPPABLE frames (bg-log — recoverable) while
+    // still delivering CRITICAL ones (bg-event lifecycle). Dropped frames are
+    // still RECORDED (seq advances), so the seq gap on the next delivered frame
+    // trips the client's replaySince recovery; a one-shot bg-lag notice lets
+    // the UI show "catching up" instead of freezing. Buffer stays 0 in the
+    // normal case → byte-identical legacy behavior.
+    const backpressure = new BackpressurePolicy();
+    const bufferedBytes = () =>
+      ws && Number.isFinite(ws.bufferedAmount) ? ws.bufferedAmount : 0;
+    const pushFrame = (base, frameClass) => {
+      const frame = buffer.record(base); // record always → seq advances, replay recovers drops
+      const d = backpressure.evaluate(bufferedBytes(), frameClass);
+      if (d.lagStarted)
+        server._send(ws, { type: "bg-lag", bgId, lagging: true });
+      if (d.send) server._send(ws, frame);
+      if (d.lagEnded) {
+        server._send(ws, {
+          type: "bg-lag",
+          bgId,
+          lagging: false,
+          dropped: d.dropped,
+          latestSeq: buffer.latestSeq,
+        });
+      }
+    };
+    const pushEvent = (event) =>
+      pushFrame({ type: "bg-event", bgId, event }, CRITICAL);
+    const pushLog = (chunk) =>
+      pushFrame({ type: "bg-log", bgId, chunk }, DROPPABLE);
+
     const { connectBackgroundSession } =
       await import("../../lib/background-session-transport.js");
     let conn;
@@ -179,16 +258,10 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
       conn = await connectBackgroundSession({
         pipePath: session.transport.pipe,
         token: session.transport.token,
-        onEvent: (event) => {
-          server._send(ws, { type: "bg-event", bgId, event });
-        },
+        onEvent: (event) => pushEvent(event),
         onClose: () => {
           if (dropAttachment(client, bgId)) {
-            server._send(ws, {
-              type: "bg-event",
-              bgId,
-              event: { type: "transport-closed" },
-            });
+            pushEvent({ type: "transport-closed" });
           }
         },
       });
@@ -212,7 +285,7 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
         if (text.length > offset) {
           const chunk = text.slice(offset);
           offset = text.length;
-          server._send(ws, { type: "bg-log", bgId, chunk });
+          pushLog(chunk);
         }
       } catch {
         /* transient read failures skip one tick */
@@ -220,7 +293,7 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
     }, LOG_POLL_MS);
     poll.unref?.();
 
-    attachments(client).set(bgId, { conn, poll, hello: conn.hello });
+    attachments(client).set(bgId, { conn, poll, hello: conn.hello, buffer });
     server._send(ws, {
       id,
       type: "bg-attach",
@@ -229,6 +302,7 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
       log: readBackgroundAgentLog(bgId, {
         lines: Number(message.lines) || 100,
       }),
+      latestSeq: buffer.latestSeq,
     });
   } catch (err) {
     sendError(server, id, ws, "BG_ATTACH_FAILED", err.message);

package/src/harness/jsonl-session-store.js

@@ -271,10 +271,17 @@ export function listJsonlSessions(options = {}) {
       const messageCount = events.filter(
         (e) => e.type === "user_message" || e.type === "assistant_message",
       ).length;
+      // cc session rename appends session_rename events; the LAST one wins.
+      let renamedTitle = null;
+      for (const e of events) {
+        if (e.type === "session_rename" && e.data?.title) {
+          renamedTitle = e.data.title;
+        }
+      }
 
       return {
         id,
-        title: startEvent?.data?.title || "Untitled",
+        title: renamedTitle || startEvent?.data?.title || "Untitled",
         provider: startEvent?.data?.provider || "",
         model: startEvent?.data?.model || "",
         message_count: messageCount,
@@ -296,6 +303,68 @@ export function listJsonlSessions(options = {}) {
   return files;
 }
 
+/**
+ * Rename a session (gap-analysis 2026-07-11 P1 "命名会话"): appends a
+ * `session_rename` event so the hash chain stays intact (no rewrite). The
+ * LAST rename wins when listing/showing.
+ */
+export function renameSession(sessionId, title) {
+  if (!sessionExists(sessionId)) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+  const normalized = String(title || "").trim();
+  if (!normalized) throw new Error("A non-empty title is required");
+  appendEvent(sessionId, "session_rename", { title: normalized.slice(0, 200) });
+  return { id: sessionId, title: normalized.slice(0, 200) };
+}
+
+/**
+ * Prune old sessions (gap-analysis 2026-07-11 P1 "保留期限"): delete session
+ * transcripts whose LAST activity is older than `olderThanDays`, always
+ * keeping the newest `keep` (default 10) regardless of age. Dry-run returns
+ * the same shape without deleting.
+ */
+export function pruneJsonlSessions(options = {}) {
+  const olderThanDays = Number(options.olderThanDays);
+  if (!Number.isFinite(olderThanDays) || olderThanDays < 0) {
+    throw new Error(
+      "prune requires --older-than <days> (a non-negative number)",
+    );
+  }
+  const keep = Number.isFinite(Number(options.keep))
+    ? Math.max(0, Math.floor(Number(options.keep)))
+    : 10;
+  const now = typeof options.now === "number" ? options.now : Date.now();
+  const cutoff = now - olderThanDays * 24 * 60 * 60 * 1000;
+  // listJsonlSessions sorts by last activity DESC — the first `keep` entries
+  // survive unconditionally.
+  const all = listJsonlSessions({ limit: 100000 });
+  const candidates = all.slice(keep).filter((s) => {
+    const last = Date.parse(s.updated_at || s.created_at || "");
+    return Number.isFinite(last) && last < cutoff;
+  });
+  const deleted = [];
+  for (const s of candidates) {
+    if (options.dryRun === true) {
+      deleted.push(s.id);
+      continue;
+    }
+    try {
+      rmSync(sessionPath(s.id), { force: true });
+      _chainTailCache.delete(s.id);
+      deleted.push(s.id);
+    } catch {
+      /* per-file failures never abort the sweep */
+    }
+  }
+  return {
+    scanned: all.length,
+    kept: all.length - deleted.length,
+    deleted,
+    dryRun: options.dryRun === true,
+  };
+}
+
 export function forkSession(sourceId) {
   const events = readEvents(sourceId);
   if (events.length === 0) return null;

package/src/harness/mcp-client.js

@@ -1051,6 +1051,17 @@ export class MCPClient extends EventEmitter {
 
     // Server notification
     if (msg.method) {
+      // tools/resources list_changed (gap 2026-07-11 MCP 生命周期): refetch
+      // the changed list so entry.tools/entry.resources stay live —
+      // `listTools()`, `/mcp` status and callTool routing all see the update.
+      // (The LLM tool array of an in-flight turn is deliberately NOT mutated:
+      // tool-search's prompt-cache stability depends on an append-only,
+      // stable-prefix tool list.)
+      if (msg.method === "notifications/tools/list_changed") {
+        this._refreshServerList(serverName, "tools");
+      } else if (msg.method === "notifications/resources/list_changed") {
+        this._refreshServerList(serverName, "resources");
+      }
       this.emit("notification", {
         server: serverName,
         method: msg.method,
@@ -1059,6 +1070,45 @@ export class MCPClient extends EventEmitter {
     }
   }
 
+  /**
+   * Re-fetch a server's tools / resources list after a `*_list_changed`
+   * notification. Coalesced per server+kind: a burst of notifications folds
+   * into the in-flight refetch plus at most one trailing pass. Best-effort —
+   * a failed refetch keeps the previous list and waits for the next
+   * notification. Emits "tools-changed" / "resources-changed" on update.
+   */
+  async _refreshServerList(serverName, kind) {
+    const entry = this.servers.get(serverName);
+    if (!entry) return;
+    const flags = (entry._listRefresh = entry._listRefresh || {});
+    if (flags[`${kind}Running`]) {
+      flags[`${kind}Dirty`] = true;
+      return;
+    }
+    flags[`${kind}Running`] = true;
+    try {
+      do {
+        flags[`${kind}Dirty`] = false;
+        try {
+          const method = kind === "tools" ? "tools/list" : "resources/list";
+          const result = await this._sendRequest(serverName, method, {});
+          const list =
+            (kind === "tools" ? result?.tools : result?.resources) || [];
+          entry[kind] = list;
+          if (kind === "tools") entry.toolsError = null;
+          this.emit(`${kind}-changed`, {
+            server: serverName,
+            count: list.length,
+          });
+        } catch {
+          break; // keep the previous list; the next notification retries
+        }
+      } while (flags[`${kind}Dirty`]);
+    } finally {
+      flags[`${kind}Running`] = false;
+    }
+  }
+
   /**
    * Answer a server-initiated JSON-RPC request. `roots/list` returns the
    * session's workspace roots (we advertise the roots capability); `ping`

package/src/lib/agent-authority.js

@@ -0,0 +1,251 @@
+/**
+ * Cross-agent authority envelope + approval binding (P0 security slice —
+ * CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12 §"权限来源与跨 Agent
+ * 授权边界").
+ *
+ * When Subagent, Team, Remote Control, Inbound Channel, Hook and MCP all feed
+ * text into one session, "who said this" is a security boundary: another
+ * agent's "the user approved" MUST NOT gain the user's authority, and an
+ * external channel message MUST NOT silently widen the session's permissions.
+ *
+ * This module is the single source of truth for two invariants the runtime
+ * enforces at every trust seam:
+ *
+ *   1. **Who may approve.** Only the local user (UI-owned stdin), an explicit
+ *      permission tool, or a *paired + authenticated + approve-scoped* remote
+ *      device may answer a permission gate. Model / subagent / teammate /
+ *      channel / hook messages top out at `steer` — the string "approved" in
+ *      their payload is just text.
+ *
+ *   2. **What an approval authorizes.** An approval is bound to
+ *      `tool_call_id + normalized_arguments + policy_digest`. A replayed or
+ *      mis-routed approval, or one issued for arguments that have since
+ *      changed, fails the binding check — so a stale "yes" can never green-light
+ *      a different (or tampered) tool call.
+ *
+ * `origin` is always assigned by trusted dispatch code from HOW a message
+ * arrived (which socket / which authenticated device / which internal caller)
+ * — it is never read from untrusted message *content*, which is the whole
+ * point: a model cannot label its own text `origin:"user"`.
+ *
+ * Pure + dependency-light (only node:crypto) so every seam — remote-session
+ * protocol, channels, hooks, subagent dispatch — can share it.
+ */
+
+import { createHash, timingSafeEqual } from "node:crypto";
+
+/** Where a message / approval entered the runtime. Assigned by trusted code. */
+export const ORIGIN = Object.freeze({
+  USER: "user", // the human at the local UI (owns stdin)
+  MODEL: "model", // the assistant's own output
+  SUBAGENT: "subagent", // a spawned sub-agent
+  TEAMMATE: "teammate", // another agent in a team run
+  CHANNEL: "channel", // an inbound channel (webhook / telegram)
+  HOOK: "hook", // a settings/plugin hook result
+  REMOTE: "remote", // a paired remote-control device
+  SYSTEM: "system", // internal runtime event
+  PERMISSION_TOOL: "permission_tool", // an explicit permission-answering tool
+});
+
+/** What a message is allowed to do. Ordered least → most privileged. */
+export const AUTHORITY = Object.freeze({
+  NONE: "none", // ignored for control purposes
+  STEER: "steer", // may add a user turn / guide the conversation
+  APPROVE: "approve", // may answer a permission gate (approve/deny a tool)
+  MANAGE: "manage", // may also manage session lifecycle
+});
+
+const AUTHORITY_RANK = Object.freeze({
+  none: 0,
+  steer: 1,
+  approve: 2,
+  manage: 3,
+});
+
+/** Numeric rank for an authority string (unknown → 0). */
+export function authorityRank(authority) {
+  return AUTHORITY_RANK[authority] ?? 0;
+}
+
+/** Remote scopes that already imply the ability to answer a permission gate. */
+function scopeGrantsApprove(context) {
+  const scopes = normalizeScopes(context);
+  return scopes.has("approve") || scopes.has("manage");
+}
+
+function scopeGrantsSteer(context) {
+  const scopes = normalizeScopes(context);
+  return (
+    scopes.has("prompt") ||
+    scopes.has("interrupt") ||
+    scopes.has("observe") ||
+    scopeGrantsApprove(context)
+  );
+}
+
+function normalizeScopes(context = {}) {
+  const raw = Array.isArray(context.scopes)
+    ? context.scopes
+    : context.scope
+      ? [context.scope]
+      : [];
+  return new Set(raw.map((s) => String(s || "").toLowerCase()));
+}
+
+/**
+ * The MAXIMUM authority an origin may exercise given its authentication
+ * context. This is a ceiling — a caller still passes the specific action
+ * through `canApprove` / `assertCanApprove`.
+ *
+ * The only paths to `approve` are: the local user (`manage`), an explicit
+ * permission tool, or a remote device that is BOTH authenticated AND was
+ * granted the approve scope at pairing. Everything an agent or external
+ * message can say tops out at `steer`.
+ */
+export function authorityForOrigin(origin, context = {}) {
+  switch (origin) {
+    case ORIGIN.USER:
+      return AUTHORITY.MANAGE;
+    case ORIGIN.PERMISSION_TOOL:
+      return AUTHORITY.APPROVE;
+    case ORIGIN.REMOTE:
+      // A paired Remote Approval Bridge acts for the user ONLY when the pairing
+      // is authenticated AND carries the approve scope. Never on the strength
+      // of the message alone.
+      if (context.authenticated === true && scopeGrantsApprove(context)) {
+        return normalizeScopes(context).has("manage")
+          ? AUTHORITY.MANAGE
+          : AUTHORITY.APPROVE;
+      }
+      if (context.authenticated === true && scopeGrantsSteer(context)) {
+        return AUTHORITY.STEER;
+      }
+      return AUTHORITY.NONE;
+    case ORIGIN.MODEL:
+    case ORIGIN.SUBAGENT:
+    case ORIGIN.TEAMMATE:
+    case ORIGIN.CHANNEL:
+    case ORIGIN.HOOK:
+    case ORIGIN.SYSTEM:
+      // May guide the conversation, never speak with the user's approval
+      // authority. "The user approved" in their text is just text.
+      return AUTHORITY.STEER;
+    default:
+      return AUTHORITY.NONE;
+  }
+}
+
+/**
+ * True when this envelope may answer a permission gate. An envelope is
+ * `{ origin, authenticated?, scope?/scopes?, principalId?, sessionId?, … }`.
+ */
+export function canApprove(envelope = {}) {
+  return (
+    authorityRank(authorityForOrigin(envelope.origin, envelope)) >=
+    AUTHORITY_RANK.approve
+  );
+}
+
+/** True when this envelope may manage session lifecycle. */
+export function canManageSession(envelope = {}) {
+  return (
+    authorityRank(authorityForOrigin(envelope.origin, envelope)) >=
+    AUTHORITY_RANK.manage
+  );
+}
+
+/**
+ * Throw a clear, log-safe error when an envelope is NOT allowed to approve.
+ * Callers gate every "resolve a permission" seam through this so the rule
+ * lives in exactly one place.
+ */
+export function assertCanApprove(envelope = {}) {
+  if (canApprove(envelope)) return;
+  const who = envelope.origin || "unknown";
+  const got = authorityForOrigin(envelope.origin, envelope);
+  throw new Error(
+    `origin "${who}" (authority "${got}") is not authorized to approve tool calls — ` +
+      "only the local user, a paired approve-scoped remote device, or an explicit permission tool may",
+  );
+}
+
+// ── Approval binding ─────────────────────────────────────────────────────────
+
+/**
+ * Deterministic, key-order-independent serialization of tool arguments, so
+ * two structurally-equal argument objects hash identically and ANY real value
+ * change hashes differently. Non-objects serialize via JSON.
+ */
+export function normalizeToolArgs(args) {
+  return stableStringify(args === undefined ? null : args);
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value === undefined ? null : value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const keys = Object.keys(value).sort();
+  return (
+    "{" +
+    keys
+      .map((k) => JSON.stringify(k) + ":" + stableStringify(value[k]))
+      .join(",") +
+    "}"
+  );
+}
+
+/**
+ * The identity an approval authorizes: the exact tool call (`toolCallId`), its
+ * normalized arguments, and the policy in force (`policyDigest`). Change any
+ * one and the digest changes, so a "yes" for one call can never be replayed
+ * onto another or onto tampered arguments.
+ */
+export function approvalBindingDigest({ toolCallId, args, policyDigest } = {}) {
+  const h = createHash("sha256");
+  h.update("cc-approval-binding-v1\n");
+  h.update(String(toolCallId ?? "") + "\n");
+  h.update(normalizeToolArgs(args) + "\n");
+  h.update(String(policyDigest ?? "") + "\n");
+  return "ab_" + h.digest("hex").slice(0, 32);
+}
+
+function timingSafeEqualStr(a, b) {
+  const ba = Buffer.from(String(a), "utf8");
+  const bb = Buffer.from(String(b), "utf8");
+  if (ba.length !== bb.length) return false;
+  return timingSafeEqual(ba, bb);
+}
+
+/**
+ * Verify an incoming approval targets the expected pending request. Each side
+ * may be a precomputed digest string or a `{toolCallId, args, policyDigest}`
+ * descriptor. Returns false on any mismatch or missing input (fail closed).
+ * Comparison is constant-time.
+ */
+export function verifyApprovalBinding(expected, provided) {
+  if (!expected || !provided) return false;
+  const e =
+    typeof expected === "string" ? expected : approvalBindingDigest(expected);
+  const p =
+    typeof provided === "string" ? provided : approvalBindingDigest(provided);
+  if (!e || !p) return false;
+  return timingSafeEqualStr(e, p);
+}
+
+/**
+ * A compact, log-safe provenance string for the permission/audit log so it is
+ * always clear WHICH principal, over WHICH session, with WHICH authority
+ * requested or answered a permission. Carries no secrets.
+ */
+export function describeAuthorityChain(envelope = {}) {
+  const parts = [`origin=${envelope.origin || "unknown"}`];
+  if (envelope.principalId) parts.push(`principal=${envelope.principalId}`);
+  if (envelope.sessionId) parts.push(`session=${envelope.sessionId}`);
+  if (envelope.parentAgentId) parts.push(`parent=${envelope.parentAgentId}`);
+  if (envelope.correlationId) parts.push(`corr=${envelope.correlationId}`);
+  parts.push(`authority=${authorityForOrigin(envelope.origin, envelope)}`);
+  return parts.join(" ");
+}

package/src/lib/agent-sandbox.js

@@ -215,11 +215,79 @@ function executeBubblewrapShell(command, sandbox, options, hostCwd, policy) {
   };
 }
 
+/**
+ * The run's TRUE isolation level (gap-analysis 2026-07-11 P0 "OS 级沙箱"):
+ *  - "os-sandbox"  : bubblewrap — kernel namespaces confine the child
+ *  - "container"   : docker — container boundary confines the child
+ *  - "policy-only" : no sandbox — permission rules/shell policy are advisory
+ *                    for already-spawned subprocesses
+ * Surfaced in the headless init event and sandboxSummary so a caller can see
+ * what actually confines tool subprocesses instead of assuming.
+ */
+export function isolationLevel(sandbox) {
+  if (!sandbox) return "policy-only";
+  if (sandbox.engine === "bubblewrap") return "os-sandbox";
+  if (sandbox.engine === "docker") return "container";
+  return "policy-only";
+}
+
+/**
+ * Probe whether the configured sandbox ENGINE is actually runnable on this
+ * host (binary present + responds to a version query). Cheap: one spawnSync
+ * with a short timeout; no container is started.
+ * @returns {{available:boolean, reason:string|null}}
+ */
+export function probeSandboxAvailability(sandbox, deps = _deps) {
+  if (!sandbox) return { available: true, reason: null };
+  const probeArgs =
+    sandbox.engine === "bubblewrap"
+      ? ["bwrap", ["--version"]]
+      : ["docker", ["version", "--format", "{{.Server.Version}}"]];
+  const result = deps.spawnSync(probeArgs[0], probeArgs[1], {
+    encoding: "utf8",
+    timeout: 10000,
+    windowsHide: true,
+  });
+  if (result.error) {
+    return {
+      available: false,
+      reason:
+        result.error.code === "ENOENT"
+          ? `${probeArgs[0]} is not installed`
+          : result.error.message,
+    };
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    return {
+      available: false,
+      reason: `${probeArgs[0]} probe exited ${result.status}: ${(result.stderr || "").trim().slice(0, 200)}`,
+    };
+  }
+  return { available: true, reason: null };
+}
+
+/**
+ * Strict mode (`sandbox.failIfUnavailable: true` in settings): refuse to
+ * START the agent when the configured sandbox engine is unavailable, instead
+ * of silently degrading per command. Throws with an actionable message; a
+ * no-op when the flag is unset or the sandbox is fine.
+ */
+export function assertSandboxAvailable(sandbox, deps = _deps) {
+  if (!sandbox || sandbox.policy?.failIfUnavailable !== true) return;
+  const probe = probeSandboxAvailability(sandbox, deps);
+  if (!probe.available) {
+    throw new Error(
+      `sandbox.failIfUnavailable: ${sandbox.engine} sandbox is unavailable (${probe.reason}) — refusing to start. Install/start ${sandbox.engine === "bubblewrap" ? "bubblewrap" : "Docker"}, or unset failIfUnavailable to allow per-command degradation.`,
+    );
+  }
+}
+
 export function sandboxSummary(sandbox) {
   if (!sandbox) return null;
   return {
     engine: sandbox.engine,
     image: sandbox.image,
+    isolationLevel: isolationLevel(sandbox),
     network: sandbox.network ? "enabled" : "disabled",
     workspace: "read-write",
     policy: {