@qwen-code/qwen-code 0.19.8 → 0.19.9-preview.0

package/chunks/{chunk-PMFULMLX.js → chunk-HCJTURZD.js}

@@ -6,19 +6,19 @@ import {
   LOAD_REPLAY_MODE_META_KEY,
   LOAD_REPLAY_VERSION,
   MID_TURN_QUEUE_DRAIN_METHOD
-} from "./chunk-AGHU5VRK.js";
+} from "./chunk-PZL23GTM.js";
 import {
   DEFAULT_RING_SIZE,
   EVENT_SCHEMA_VERSION,
   EventBus,
   serializedBridgeEventByteLength
-} from "./chunk-3UP777ZS.js";
+} from "./chunk-6RLROE6G.js";
 import {
   normalizeCompactedReplayMaxBytes
-} from "./chunk-GLE2YUPU.js";
+} from "./chunk-COH43MRJ.js";
 import {
   MCP_RESTART_SERVER_DEADLINE_MS
-} from "./chunk-P7M4GA57.js";
+} from "./chunk-OCPBI7J5.js";
 import {
   BranchWhilePromptActiveError,
   CancelSentinelCollisionError,
@@ -38,18 +38,10 @@ import {
   SessionShellDisabledError,
   WorkspaceMismatchError,
   isNotCurrentlyGeneratingCancelError
-} from "./chunk-GGQQA4JW.js";
-import {
-  canonicalizeWorkspace
-} from "./chunk-ER3BKOLB.js";
-import {
-  ClientSideConnection,
-  PROTOCOL_VERSION,
-  RequestError
-} from "./chunk-VRDMOSQS.js";
+} from "./chunk-KSO42X3Z.js";
 import {
   defaultSpawnChannelFactory
-} from "./chunk-BOBOCR5H.js";
+} from "./chunk-VEETSXYX.js";
 import {
   BridgeChannelClosedError,
   BridgeTimeoutError,
@@ -58,18 +50,34 @@ import {
   STATUS_SCHEMA_VERSION,
   createIdleWorkspaceExtensionsStatus,
   createIdleWorkspaceHooksStatus
-} from "./chunk-LAXNEOBG.js";
+} from "./chunk-FI2WSOWX.js";
+import {
+  canonicalizeWorkspace
+} from "./chunk-W7FJ3N32.js";
 import {
+  ClientSideConnection,
+  PROTOCOL_VERSION,
+  RequestError
+} from "./chunk-UDXSXLER.js";
+import {
+  SESSION_ARTIFACT_PERSISTENCE_VERSION,
   ShellExecutionService,
-  TrustGateError
-} from "./chunk-3GNOQZDC.js";
+  TrustGateError,
+  WORKSPACE_CONTENT_MTIME_MS_METADATA_KEY,
+  WORKSPACE_CONTENT_SHA256_METADATA_KEY,
+  isPrototypeMetadataKey,
+  isReservedWorkspaceMetadataKey,
+  metadataBudgetBytes,
+  normalizeSnapshotPayload,
+  stableSessionArtifactId
+} from "./chunk-HJUDVNCO.js";
 import {
   DAEMON_TRACEPARENT_META_KEY,
   DAEMON_TRACESTATE_META_KEY
-} from "./chunk-BUZ6HGL4.js";
+} from "./chunk-HWTL6MPR.js";
 import {
   init_esbuild_shims
-} from "./chunk-A4BMJM77.js";
+} from "./chunk-5O2XNYP6.js";
 import {
   __name
 } from "./chunk-J2S4EL5Y.js";
@@ -388,7 +396,7 @@ var TurnBoundaryCompactionEngine = class {
         retainedEvents,
         maxBytes: this.maxReplayBytes,
         ...this.truncatedTurns > 0 ? { truncatedTurns: this.truncatedTurns } : {},
-        fullTranscriptAvailable: false
+        fullTranscriptAvailable: true
       }
     };
   }
@@ -483,6 +491,11 @@ import * as path from "node:path";
 init_esbuild_shims();
 var MID_TURN_MESSAGE_INJECTED_EVENT = "mid_turn_message_injected";
 
+// packages/acp-bridge/src/bridgeOptions.ts
+init_esbuild_shims();
+var MAX_SUB_SESSION_PROMPT_CHARS = 1e5;
+var MAX_SUB_SESSION_NAME_CHARS = 200;
+
 // packages/acp-bridge/src/permissionMediator.ts
 init_esbuild_shims();
 
@@ -1169,6 +1182,60 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 __name(isRecord, "isRecord");
+function pendingInteractionOptions(options) {
+  return options.map((option) => ({
+    optionId: String(option.optionId ?? ""),
+    ...typeof option.name === "string" ? { label: option.name } : {},
+    ...typeof option.kind === "string" ? { kind: option.kind } : {}
+  }));
+}
+__name(pendingInteractionOptions, "pendingInteractionOptions");
+function pendingInteractionFromRequest(requestId, params) {
+  const toolCall = params.toolCall;
+  const meta = isRecord(toolCall["_meta"]) ? toolCall["_meta"] : void 0;
+  const rawInput = toolCall["rawInput"];
+  const options = pendingInteractionOptions(
+    Array.isArray(params.options) ? params.options : []
+  );
+  const isUserQuestion = meta?.["qwenInteractionKind"] === "user_question";
+  if (isUserQuestion) {
+    const rawQuestions = Array.isArray(meta?.["qwenQuestions"]) ? meta["qwenQuestions"] : isRecord(rawInput) && Array.isArray(rawInput["questions"]) ? rawInput["questions"] : [];
+    return {
+      requestId,
+      kind: "user_question",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...typeof toolCall["title"] === "string" ? { title: toolCall["title"] } : {},
+      questions: rawQuestions.flatMap(
+        (question, index) => isRecord(question) ? [{ ...question, answerKey: String(index) }] : []
+      ),
+      options
+    };
+  }
+  return {
+    requestId,
+    kind: "permission",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    action: {
+      ...typeof toolCall["kind"] === "string" ? { type: toolCall["kind"] } : {},
+      ...typeof toolCall["title"] === "string" ? { title: toolCall["title"] } : {},
+      ...toolCall["content"] !== void 0 ? { content: toolCall["content"] } : {},
+      ...toolCall["locations"] !== void 0 ? { locations: toolCall["locations"] } : {},
+      ...rawInput !== void 0 ? { input: rawInput } : {}
+    },
+    options
+  };
+}
+__name(pendingInteractionFromRequest, "pendingInteractionFromRequest");
+function fallbackPendingPermissionInteraction(requestId, options) {
+  return {
+    requestId,
+    kind: "permission",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    action: {},
+    options: pendingInteractionOptions(options)
+  };
+}
+__name(fallbackPendingPermissionInteraction, "fallbackPendingPermissionInteraction");
 function artifactPayloadFields(artifact) {
   return {
     title: artifact["title"],
@@ -1180,7 +1247,8 @@ function artifactPayloadFields(artifact) {
     url: artifact["url"],
     mimeType: artifact["mimeType"],
     sizeBytes: artifact["sizeBytes"],
-    metadata: artifact["metadata"]
+    metadata: artifact["metadata"],
+    retention: artifact["retention"]
   };
 }
 __name(artifactPayloadFields, "artifactPayloadFields");
@@ -1264,7 +1332,8 @@ function isTrustedArtifactToolUpdate(params, updateMeta) {
 __name(isTrustedArtifactToolUpdate, "isTrustedArtifactToolUpdate");
 function preserveFsErrorOverAcp(err) {
   if (isFsErrorShape(err)) {
-    throw new RequestError(-32603, err.message, {
+    const code = err.kind === "parse_error" ? -32602 : -32603;
+    throw new RequestError(code, err.message, {
       errorKind: err.kind,
       ...err.hint !== void 0 ? { hint: err.hint } : {},
       ...err.status !== void 0 ? { status: err.status } : {}
@@ -1323,7 +1392,7 @@ function sliceLineRange(content, startLine, endLine) {
 }
 __name(sliceLineRange, "sliceLineRange");
 var BridgeClient = class {
-  constructor(resolveEntry, resolvePendingRestoreEvents, mediator, permissionTimeoutMs, maxPendingPerSession, fileSystem, onModelPromoted, onModePromoted, clientMcpSender, ownsSession = () => true, onTokenUsage) {
+  constructor(resolveEntry, resolvePendingRestoreEvents, mediator, permissionTimeoutMs, maxPendingPerSession, fileSystem, onModelPromoted, onModePromoted, clientMcpSender, ownsSession = () => true, onTokenUsage, onCreateSubSession) {
     this.resolveEntry = resolveEntry;
     this.resolvePendingRestoreEvents = resolvePendingRestoreEvents;
     this.mediator = mediator;
@@ -1335,6 +1404,7 @@ var BridgeClient = class {
     this.clientMcpSender = clientMcpSender;
     this.ownsSession = ownsSession;
     this.onTokenUsage = onTokenUsage;
+    this.onCreateSubSession = onCreateSubSession;
   }
   static {
     __name(this, "BridgeClient");
@@ -1348,10 +1418,9 @@ var BridgeClient = class {
       );
       return { outcome: { outcome: "cancelled" } };
     }
+    const options = Array.isArray(params.options) ? params.options : [];
     const allowedOptionIds = new Set(
-      params.options.map(
-        (o) => String(o.optionId ?? "")
-      )
+      options.map((o) => String(o.optionId ?? ""))
     );
     allowedOptionIds.delete("");
     const requestId = randomUUID();
@@ -1364,12 +1433,25 @@ var BridgeClient = class {
         requestId,
         sessionId: entry.sessionId,
         toolCall: params.toolCall,
-        options: params.options
+        options
       },
       ...entry.activePromptOriginatorClientId ? { originatorClientId: entry.activePromptOriginatorClientId } : {}
     });
     if (!published) return { outcome: { outcome: "cancelled" } };
+    let interaction;
+    try {
+      interaction = pendingInteractionFromRequest(requestId, {
+        ...params,
+        options
+      });
+    } catch (error) {
+      writeStderrLine(
+        `qwen serve: failed to snapshot pending interaction ${requestId}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      interaction = fallbackPendingPermissionInteraction(requestId, options);
+    }
     entry.pendingPermissionIds.add(requestId);
+    if (interaction) entry.pendingInteractions.set(requestId, interaction);
     try {
       const record = {
         requestId,
@@ -1385,6 +1467,7 @@ var BridgeClient = class {
       return resolutionToAcpResponse(resolution);
     } finally {
       entry.pendingPermissionIds.delete(requestId);
+      entry.pendingInteractions.delete(requestId);
     }
   }
   async sessionUpdate(params) {
@@ -1458,7 +1541,7 @@ var BridgeClient = class {
       trustedPublisher: isTrustedArtifactToolUpdate(params, updateMeta)
     };
   }
-  async seedSessionUpdates(entry, updates) {
+  async seedSessionUpdates(entry, updates, options = {}) {
     const frames = [];
     const artifactBatches = [];
     for (const update of updates) {
@@ -1467,7 +1550,7 @@ var BridgeClient = class {
         entry
       );
       frames.push(...prepared.frames);
-      if (prepared.artifacts.length > 0) {
+      if (options.ingestArtifacts !== false && prepared.artifacts.length > 0) {
         artifactBatches.push({
           artifacts: prepared.artifacts,
           trustedPublisher: prepared.trustedPublisher
@@ -1505,18 +1588,23 @@ var BridgeClient = class {
       return;
     }
     const durationMs = updateMeta?.["durationMs"];
+    const apiErrors = updateMeta?.["apiErrors"];
+    const apiRetries = updateMeta?.["apiRetries"];
     this.onTokenUsage(
       typeof inputTokens === "number" ? inputTokens : 0,
       typeof outputTokens === "number" ? outputTokens : 0,
-      typeof durationMs === "number" ? durationMs : void 0
+      typeof durationMs === "number" ? durationMs : void 0,
+      typeof apiErrors === "number" ? apiErrors : 0,
+      typeof apiRetries === "number" ? apiRetries : 0
     );
   }
   /**
-   * Bounded early-event buffer. Frames are keyed by sessionId; each
-   * entry tracks its `expiresAt` for lazy TTL-based eviction in
-   * `bufferEarlyEvent`. Drained by `drainEarlyEvents` whenever the
-   * bridge registers a session with a matching id. See
-   * MAX_EARLY_EVENT_* constants for capacity bounds.
+   * Bounded early-event buffer. The map is scoped to this BridgeClient and
+   * therefore to one channel; a stale channel cannot seed a fresh channel's
+   * future session. Frames are keyed by sessionId; each entry tracks its
+   * `expiresAt` for lazy TTL-based eviction in `bufferEarlyEvent`. Drained by
+   * `drainEarlyEvents` whenever the bridge registers a session with a matching
+   * id. See MAX_EARLY_EVENT_* constants for capacity bounds.
    */
   earlyEvents = /* @__PURE__ */ new Map();
   /**
@@ -1541,7 +1629,7 @@ var BridgeClient = class {
   /**
    * Allow-list of sessionIds currently being restored via
    * `session/load` / `session/resume`. Bypasses the tombstone check
-   * in `bufferEarlyEvent` so restore-time guardrail events for a
+   * in `bufferEarlyEvent` so restore-time events for a
    * previously-closed id flow through to the future
    * `createSessionEntry -> drainEarlyEvents` call.
    *
@@ -1556,9 +1644,12 @@ var BridgeClient = class {
   inFlightRestoreIds = /* @__PURE__ */ new Set();
   /**
    * Handle child->bridge ACP `extMethod` requests (calls that expect a
-   * response, unlike `extNotification`). The only method served today is
-   * `craft/drainMidTurnQueue`: the ACP child calls it between tool batches to
-   * pull any messages the browser queued mid-turn. We splice the per-session
+   * response, unlike `extNotification`). Served methods:
+   * `qwen/control/client_mcp/message` (reverse tool channel),
+   * `qwen/control/create-sub-session` (the `create_sub_session` tool → daemon
+   * spawns a sub-session and, for `'first-turn'`, returns its first-turn
+   * result), and `craft/drainMidTurnQueue`: the ACP child calls the last one
+   * between tool batches to pull any messages the browser queued mid-turn. We splice the per-session
    * queue, return them to the child as the response, and — when non-empty —
    * publish a `mid_turn_message_injected` SSE frame so the browser can move
    * those messages out of its pending queue (a dedupe signal, not a transcript
@@ -1571,6 +1662,9 @@ var BridgeClient = class {
     if (method === SERVE_CONTROL_EXT_METHODS.clientMcpMessage) {
       return this.handleClientMcpMessage(params);
     }
+    if (method === SERVE_CONTROL_EXT_METHODS.createSubSession) {
+      return this.handleCreateSubSession(params);
+    }
     if (method !== MID_TURN_QUEUE_DRAIN_METHOD) {
       throw RequestError.methodNotFound(method);
     }
@@ -1646,17 +1740,80 @@ var BridgeClient = class {
     const response = await send(payload);
     return { payload: response };
   }
+  /**
+   * Handle the `create_sub_session` tool's request: validate, then forward to
+   * the daemon-host `onCreateSubSession` callback (which spawns a fresh
+   * top-level sub-session and, for `'first-turn'`, waits for its first turn and
+   * returns the result). No host wired → `methodNotFound`, which the tool
+   * surfaces as "daemon-only".
+   */
+  async handleCreateSubSession(params) {
+    if (!this.onCreateSubSession) {
+      throw RequestError.methodNotFound(
+        SERVE_CONTROL_EXT_METHODS.createSubSession
+      );
+    }
+    const prompt = params["prompt"];
+    if (typeof prompt !== "string" || prompt.length === 0) {
+      throw RequestError.invalidParams(
+        void 0,
+        "`prompt` must be a non-empty string"
+      );
+    }
+    if (prompt.length > MAX_SUB_SESSION_PROMPT_CHARS) {
+      throw RequestError.invalidParams(
+        void 0,
+        `\`prompt\` exceeds the ${MAX_SUB_SESSION_PROMPT_CHARS}-character limit`
+      );
+    }
+    const completion = params["completion"];
+    if (completion !== "sent" && completion !== "first-turn") {
+      throw RequestError.invalidParams(
+        void 0,
+        "`completion` must be 'sent' or 'first-turn'"
+      );
+    }
+    const name = params["name"];
+    if (typeof name === "string" && name.length > MAX_SUB_SESSION_NAME_CHARS) {
+      throw RequestError.invalidParams(
+        void 0,
+        `\`name\` exceeds the ${MAX_SUB_SESSION_NAME_CHARS}-character limit`
+      );
+    }
+    const callerSessionId = params["callerSessionId"];
+    if (typeof callerSessionId !== "string" || callerSessionId.length === 0 || !this.ownsSession(callerSessionId)) {
+      throw RequestError.invalidParams(
+        void 0,
+        "`callerSessionId` is required and must name a session owned by this connection"
+      );
+    }
+    const model = params["model"];
+    const result = await this.onCreateSubSession({
+      prompt,
+      completion,
+      ...typeof model === "string" && model.length > 0 && model.length <= 128 ? { model } : {},
+      ...typeof name === "string" && name.length > 0 ? { name } : {},
+      callerSessionId
+    });
+    return {
+      sessionId: result.sessionId,
+      ...result.result !== void 0 ? { result: result.result } : {},
+      ...result.stopReason !== void 0 ? { stopReason: result.stopReason } : {},
+      ...result.parentSessionPersisted !== void 0 ? { parentSessionPersisted: result.parentSessionPersisted } : {}
+    };
+  }
   /**
    * Handle child->bridge ACP `extNotification` calls. Recognized methods are
    * `qwen/notify/session/model-update`,
    * `qwen/notify/session/mode-update`,
    * `qwen/notify/session/title-update` (auto/in-process session titles),
+   * `qwen/notify/session/recording-degraded`,
    * `qwen/notify/session/prompt-suggestion` (followup assist),
    * `qwen/notify/session/artifact-event` (hook artifacts),
    * `qwen/notify/session/terminal-sequence`, and
    * `qwen/notify/session/mcp-budget-event` — each translated into a
-   * session-scoped SSE frame. Unknown methods are dropped silently
-   * for forward-compat.
+   * session-scoped SSE frame. Unknown methods are dropped silently for
+   * forward-compat.
    */
   async extNotification(method, params) {
     if (method === "qwen/notify/session/model-update") {
@@ -1687,6 +1844,28 @@ var BridgeClient = class {
       }
       return;
     }
+    if (method === "qwen/notify/session/recording-degraded") {
+      const sessionId2 = params["sessionId"];
+      if (params["v"] !== 1 || typeof sessionId2 !== "string" || sessionId2.length === 0 || params["reason"] !== "write_failed") {
+        writeStderrLine(
+          `[demux] session=${typeof sessionId2 === "string" ? sessionId2 : "<missing>"} type=session_recording_degraded action=dropped reason=malformed`
+        );
+        return;
+      }
+      const entry = this.resolveEntry(sessionId2);
+      if (entry && !this.ownsSession(sessionId2)) {
+        writeStderrLine(
+          `[demux] session=${sessionId2} type=session_recording_degraded action=dropped reason=session_not_owned`
+        );
+        return;
+      }
+      if (entry) entry.recordingDegraded = true;
+      this.publishExtNotification(sessionId2, "session_recording_degraded", {
+        sessionId: sessionId2,
+        reason: "write_failed"
+      });
+      return;
+    }
     if (method === "qwen/notify/session/prompt-suggestion") {
       const sessionId2 = params["sessionId"];
       const suggestion = params["suggestion"];
@@ -1943,7 +2122,7 @@ var BridgeClient = class {
     this.sweepExpiredTombstones(now);
     if (this.tombstonedSessionIds.has(sessionId) && !this.inFlightRestoreIds.has(sessionId)) {
       writeStderrLine(
-        `qwen serve: dropping mcp guardrail extNotification for tombstoned session ${JSON.stringify(sessionId)} (post-close stale event)`
+        `qwen serve: dropping early extNotification for tombstoned session ${JSON.stringify(sessionId)} (post-close stale event)`
       );
       return;
     }
@@ -1952,7 +2131,7 @@ var BridgeClient = class {
     if (!buf) {
       if (this.earlyEvents.size >= MAX_EARLY_EVENT_SESSIONS) {
         writeStderrLine(
-          `qwen serve: dropping mcp guardrail extNotification \u2014 early-event buffer at MAX_EARLY_EVENT_SESSIONS (${MAX_EARLY_EVENT_SESSIONS}); possible session-id fanout abuse`
+          `qwen serve: dropping early extNotification \u2014 early-event buffer at MAX_EARLY_EVENT_SESSIONS (${MAX_EARLY_EVENT_SESSIONS}); possible session-id fanout abuse`
         );
         return;
       }
@@ -1961,7 +2140,7 @@ var BridgeClient = class {
     }
     if (buf.frames.length >= MAX_EARLY_EVENTS_PER_SESSION) {
       writeStderrLine(
-        `qwen serve: dropping mcp guardrail extNotification for session ${JSON.stringify(sessionId)} \u2014 per-session cap (${MAX_EARLY_EVENTS_PER_SESSION}) reached`
+        `qwen serve: dropping early extNotification for session ${JSON.stringify(sessionId)} \u2014 per-session cap (${MAX_EARLY_EVENTS_PER_SESSION}) reached`
       );
       return;
     }
@@ -1995,7 +2174,7 @@ var BridgeClient = class {
    * Mark a sessionId as currently being restored via `session/load` /
    * `session/resume`. While in this set, `bufferEarlyEvent` accepts
    * frames for the id even if it's tombstoned — so restore-time
-   * guardrail events from the freshly-restored child reach
+   * early events from the freshly-restored child reach
    * `drainEarlyEvents` instead of being rejected by the tombstone.
    *
    * Bridge factory calls this BEFORE awaiting the ACP restore call.
@@ -2029,7 +2208,12 @@ var BridgeClient = class {
     this.tombstonedSessionIds.delete(sessionId);
     const buf = this.earlyEvents.get(sessionId);
     if (!buf) return;
-    for (const frame of buf.frames) entry.events.publish(frame);
+    for (const frame of buf.frames) {
+      if (frame.type === "session_recording_degraded") {
+        entry.recordingDegraded = true;
+      }
+      entry.events.publish(frame);
+    }
     this.earlyEvents.delete(sessionId);
   }
   async writeTextFile(params) {
@@ -2096,6 +2280,18 @@ var BridgeClient = class {
     if (typeof params.limit === "number" && params.limit <= 0) {
       return { content: "" };
     }
+    if (typeof params.limit === "number" && params.limit > 0 && !Number.isSafeInteger(params.limit)) {
+      throw RequestError.invalidParams(
+        void 0,
+        `\`limit\` must be a positive integer, got ${params.limit}`
+      );
+    }
+    if (typeof params.line === "number" && params.line > 0 && !Number.isSafeInteger(params.line)) {
+      throw RequestError.invalidParams(
+        void 0,
+        `\`line\` must be a positive integer, got ${params.line}`
+      );
+    }
     const READ_FILE_SIZE_CAP = 100 * 1024 * 1024;
     const stats = await fs.stat(params.path);
     if (!stats.isFile()) {
@@ -2239,7 +2435,7 @@ __name(extractA2uiToolUpdate, "extractA2uiToolUpdate");
 // packages/acp-bridge/src/sessionArtifacts.ts
 init_esbuild_shims();
 import { createHash } from "node:crypto";
-import { promises as fs2 } from "node:fs";
+import { constants as fsConstants, promises as fs2 } from "node:fs";
 import path2 from "node:path";
 var SOURCE_RESERVATIONS = {
   tool: 100,
@@ -2248,6 +2444,18 @@ var SOURCE_RESERVATIONS = {
 };
 var WORKSPACE_STATUS_REFRESH_TTL_MS = 5e3;
 var WORKSPACE_STATUS_REFRESH_BATCH_SIZE = 20;
+var SNAPSHOT_AFTER_DURABLE_EVENTS = 50;
+var MAX_SNAPSHOT_BACKOFF_MULTIPLIER = 4;
+var MAX_TOMBSTONED_IDS = 500;
+var MAX_STICKY_EPHEMERAL_IDS = 500;
+var MAX_WORKSPACE_HASH_BYTES = 100 * 1024 * 1024;
+var SECRET_TOKEN_VALUE_PATTERN = /(?:^|\s)(?:bearer\s+\S{8,}|sk-[A-Za-z0-9_-]{12,}|(?:gh[pousr]|github_pat)_[A-Za-z0-9_/-]{12,}|[a-f0-9]{40,}|[A-Za-z0-9+/]{48,}={0,2})(?:$|\s)/i;
+var RESTORE_FAILED_WARNING_PREFIX = "artifact snapshot restore failed";
+var RESTORE_PARTIAL_FAILED_WARNING_PREFIX = "artifact snapshot restore partially failed";
+function isArtifactRestoreFailureWarning(warning) {
+  return warning.startsWith(RESTORE_FAILED_WARNING_PREFIX) || warning.startsWith(RESTORE_PARTIAL_FAILED_WARNING_PREFIX);
+}
+__name(isArtifactRestoreFailureWarning, "isArtifactRestoreFailureWarning");
 var SessionArtifactValidationError = class extends Error {
   constructor(message, field) {
     super(message);
@@ -2259,6 +2467,20 @@ var SessionArtifactValidationError = class extends Error {
   }
   code = "VALIDATION_FAILED";
 };
+var SessionArtifactAuthorizationError = class extends Error {
+  constructor(sessionId, artifactId, ownerClientId, requesterClientId) {
+    super(`artifact ${artifactId} is owned by a different client`);
+    this.sessionId = sessionId;
+    this.artifactId = artifactId;
+    this.ownerClientId = ownerClientId;
+    this.requesterClientId = requesterClientId;
+    this.name = "SessionArtifactAuthorizationError";
+  }
+  static {
+    __name(this, "SessionArtifactAuthorizationError");
+  }
+  code = "SESSION_ARTIFACT_FORBIDDEN";
+};
 var SessionArtifactStore = class {
   static {
     __name(this, "SessionArtifactStore");
@@ -2266,15 +2488,26 @@ var SessionArtifactStore = class {
   sessionId;
   workspaceCwd;
   maxArtifacts;
+  persistence;
   artifacts = /* @__PURE__ */ new Map();
   receivedSeq = 0;
   insertSeq = 0;
+  persistenceSeq = 0;
+  durableEventsSinceSnapshot = 0;
+  consecutiveSnapshotFailures = 0;
   realWorkspaceCwdPromise;
   operationQueue = Promise.resolve();
+  tombstonedIds = /* @__PURE__ */ new Set();
+  tombstonedClientIds = /* @__PURE__ */ new Map();
+  stickyEphemeralIds = /* @__PURE__ */ new Set();
+  markerArtifacts = /* @__PURE__ */ new Map();
+  lastRestoreWarnings = [];
+  lastRestoreWarningDetails = [];
   constructor(options) {
     this.sessionId = options.sessionId;
     this.workspaceCwd = options.workspaceCwd;
     this.maxArtifacts = options.maxArtifacts ?? 200;
+    this.persistence = options.persistence;
   }
   inputBatchLimit() {
     return this.maxArtifacts * 2;
@@ -2287,13 +2520,30 @@ var SessionArtifactStore = class {
         sessionId: this.sessionId,
         artifacts: Array.from(this.artifacts.values()).sort((a, b) => a.insertSeq - b.insertSeq).map(toPublicArtifact),
         generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        limits: { maxArtifacts: this.maxArtifacts }
+        limits: { maxArtifacts: this.maxArtifacts },
+        ...this.lastRestoreWarnings.length > 0 ? { warnings: [...this.lastRestoreWarnings] } : {},
+        ...this.lastRestoreWarningDetails.length > 0 ? { warningDetails: [...this.lastRestoreWarningDetails] } : {}
       };
     });
   }
+  async get(artifactId) {
+    return this.enqueue(async () => {
+      const artifact = this.artifacts.get(artifactId);
+      if (!artifact) return void 0;
+      if (artifact.workspacePath && shouldRefreshWorkspaceStatus(artifact, Date.now())) {
+        await this.refreshWorkspaceStatus(artifact, { onError: "missing" });
+      }
+      return toPublicArtifact(artifact);
+    });
+  }
   async upsertMany(inputs, options = {}) {
     return this.enqueue(async () => {
+      const validationStrict = options.validationStrict ?? options.strict;
+      const persistenceStrict = options.persistenceStrict ?? options.strict;
+      const before = this.cloneState();
       const normalizedResults = [];
+      const warnings = [];
+      const warningDetails = [];
       for (const input of inputs) {
         try {
           normalizedResults.push(
@@ -2304,7 +2554,7 @@ var SessionArtifactStore = class {
             )
           );
         } catch (error) {
-          if (options.strict) {
+          if (validationStrict) {
             throw error;
           }
           const message = error instanceof Error ? error.message : String(error);
@@ -2316,39 +2566,140 @@ var SessionArtifactStore = class {
         }
       }
       const changes = [];
-      for (const artifact of coalesceByIdentity(normalizedResults)) {
-        const existing = this.artifacts.get(artifact.id) ?? this.findPublishedUpgradeTarget(artifact) ?? this.findPublishedWorkspaceTarget(artifact);
-        if (!existing) {
-          const stored = {
-            ...artifact,
-            insertSeq: ++this.insertSeq
-          };
-          this.artifacts.set(stored.id, stored);
-          changes.push({
-            action: "created",
-            artifactId: stored.id,
-            artifact: toPublicArtifact(stored)
-          });
-          continue;
+      try {
+        for (const normalized of coalesceByIdentity(normalizedResults)) {
+          const artifact = this.applyStickyEphemeralOverride(normalized);
+          if (this.shouldSuppressTombstonedUpsert(artifact)) {
+            writeStderrLine(
+              `[artifacts] session=${this.sessionId} action=tombstone_replay_suppressed artifactId=${artifact.id}`
+            );
+            continue;
+          }
+          const existing = this.artifacts.get(artifact.id) ?? this.findPublishedUpgradeTarget(artifact) ?? this.findPublishedWorkspaceTarget(artifact);
+          if (!existing) {
+            const stored = {
+              ...artifact,
+              insertSeq: ++this.insertSeq
+            };
+            this.artifacts.set(stored.id, stored);
+            changes.push({
+              action: "created",
+              artifactId: stored.id,
+              artifact: toPublicArtifact(stored)
+            });
+            continue;
+          }
+          try {
+            this.denyCrossClientMutation("upsert", existing.id, existing, {
+              clientId: artifact.clientId
+            });
+          } catch (error) {
+            if (validationStrict) {
+              throw error;
+            }
+            if (error instanceof SessionArtifactAuthorizationError) {
+              warnings.push(error.message);
+              continue;
+            }
+            throw error;
+          }
+          const updated = mergeArtifact(existing, artifact);
+          if (updated.changed) {
+            if (updated.artifact.id !== existing.id) {
+              const removeChange = {
+                action: "removed",
+                artifactId: existing.id,
+                artifact: toPublicArtifact(existing),
+                reason: "explicit",
+                durableTombstoneRequired: existing.durableTombstoneRequired || existing.persistedAt !== void 0,
+                removedClientId: existing.clientId
+              };
+              changes.push(removeChange);
+              this.artifacts.delete(existing.id);
+            } else if (shouldRecordEphemeralUnpin(existing, artifact)) {
+              changes.push({
+                action: "removed",
+                artifactId: existing.id,
+                artifact: toPublicArtifact(existing),
+                reason: "unpin_to_ephemeral",
+                durableTombstoneRequired: true
+              });
+            }
+            this.artifacts.set(updated.artifact.id, updated.artifact);
+            changes.push({
+              action: "updated",
+              artifactId: updated.artifact.id,
+              artifact: toPublicArtifact(updated.artifact)
+            });
+          }
         }
-        const updated = mergeArtifact(existing, artifact);
-        if (updated.changed) {
-          if (updated.artifact.id !== existing.id) {
-            this.artifacts.delete(existing.id);
+        const createdIds = new Set(
+          changes.filter((change) => change.action === "created").map((change) => change.artifactId)
+        );
+        changes.push(
+          ...await this.evictOverflow(createdIds, changes, persistenceStrict)
+        );
+        const hasStrictDurableTransition = changes.some(
+          shouldCommitBeforeDurablePersistence
+        );
+        let persistenceWarnings;
+        if (hasStrictDurableTransition && !persistenceStrict) {
+          try {
+            persistenceWarnings = await this.persistChanges(changes, true);
+          } catch (error) {
+            this.restoreState(before);
+            const artifactIds = changes.filter(shouldCommitBeforeDurablePersistence).map((change) => change.artifactId);
+            const warning = "artifact durable removal not persisted; live changes rolled back";
+            writeStderrLine(
+              `[artifacts] session=${this.sessionId} action=upsert_rollback warning=${JSON.stringify(
+                warning
+              )} artifactIds=${JSON.stringify(artifactIds)} error=${JSON.stringify(
+                error instanceof Error ? error.message : String(error)
+              )}`
+            );
+            return {
+              v: 1,
+              sessionId: this.sessionId,
+              changes: [],
+              warnings: [warning],
+              warningDetails: [
+                persistenceFailureDetail({
+                  message: warning,
+                  operation: "upsert",
+                  artifactIds,
+                  error
+                })
+              ]
+            };
           }
-          this.artifacts.set(updated.artifact.id, updated.artifact);
-          changes.push({
-            action: "updated",
-            artifactId: updated.artifact.id,
-            artifact: toPublicArtifact(updated.artifact)
-          });
+        } else {
+          persistenceWarnings = await this.persistChanges(
+            changes,
+            persistenceStrict
+          );
+        }
+        warnings.push(...persistenceWarnings);
+        warningDetails.push(
+          ...detailsForPersistenceWarnings(
+            persistenceWarnings,
+            changes,
+            "upsert"
+          )
+        );
+        stripDurableTombstoneMarkers(changes);
+      } catch (error) {
+        if (validationStrict || persistenceStrict || error instanceof SessionArtifactAuthorizationError) {
+          this.restoreState(before);
         }
+        throw error;
       }
-      const createdIds = new Set(
-        changes.filter((change) => change.action === "created").map((change) => change.artifactId)
-      );
-      changes.push(...await this.evictOverflow(createdIds, changes));
-      return { v: 1, sessionId: this.sessionId, changes };
+      return {
+        v: 1,
+        sessionId: this.sessionId,
+        changes,
+        ...warnings.length > 0 ? { warnings } : {},
+        ...warningDetails.length > 0 ? { warningDetails } : {}
+      };
     });
   }
   findPublishedUpgradeTarget(artifact) {
@@ -2356,7 +2707,7 @@ var SessionArtifactStore = class {
       return void 0;
     }
     const byUrl = this.artifacts.get(
-      stableArtifactId(this.sessionId, `url:${artifact.url}`)
+      stableSessionArtifactId(this.sessionId, `url:${artifact.url}`)
     );
     if (byUrl && (byUrl.storage !== "published" || byUrl.managedId === artifact.managedId)) {
       return byUrl;
@@ -2392,93 +2743,648 @@ var SessionArtifactStore = class {
       if (!existing) {
         return { v: 1, sessionId: this.sessionId, changes: [] };
       }
-      if (existing.source === "client" && existing.clientId !== void 0 && existing.clientId !== options?.clientId) {
-        writeStderrLine(
-          `[artifacts] session=${this.sessionId} action=remove_denied artifactId=${artifactId} owner=${existing.clientId} requester=${options?.clientId ?? "<anonymous>"}`
-        );
-        return { v: 1, sessionId: this.sessionId, changes: [] };
+      this.denyCrossClientMutation("remove", artifactId, existing, options);
+      const removeChange = {
+        action: "removed",
+        artifactId,
+        artifact: toPublicArtifact(existing),
+        reason: "explicit",
+        durableTombstoneRequired: existing.durableTombstoneRequired || existing.retention !== "ephemeral" ? true : void 0,
+        removedClientId: existing.clientId
+      };
+      const changes = [removeChange];
+      const needsDurableTombstone = removeChange.durableTombstoneRequired === true;
+      if (needsDurableTombstone) {
+        const before = this.cloneState();
+        this.artifacts.delete(artifactId);
+        try {
+          await this.persistChanges(changes, true);
+        } catch (error) {
+          this.restoreState(before);
+          const warning = "artifact removal not persisted; live artifact kept";
+          return {
+            v: 1,
+            sessionId: this.sessionId,
+            changes: [],
+            warnings: [warning],
+            warningDetails: [
+              persistenceFailureDetail({
+                message: warning,
+                operation: "remove",
+                artifactIds: [artifactId],
+                error
+              })
+            ]
+          };
+        }
+      }
+      if (!needsDurableTombstone) {
+        this.artifacts.delete(artifactId);
       }
-      this.artifacts.delete(artifactId);
+      const warnings = needsDurableTombstone ? [] : await this.persistChanges(changes, false);
+      stripDurableTombstoneMarkers(changes);
+      const warningDetails = detailsForPersistenceWarnings(
+        warnings,
+        changes,
+        "remove"
+      );
       return {
         v: 1,
         sessionId: this.sessionId,
-        changes: [
-          {
-            action: "removed",
-            artifactId,
-            artifact: toPublicArtifact(existing),
-            reason: "explicit"
-          }
-        ]
+        changes,
+        ...warnings.length > 0 ? { warnings } : {},
+        ...warningDetails.length > 0 ? { warningDetails } : {}
       };
     });
   }
-  enqueue(operation) {
-    const result = this.operationQueue.then(operation, operation);
-    this.operationQueue = result.then(
-      () => void 0,
-      () => void 0
-    );
-    return result;
+  async restore(snapshot, options = {}) {
+    if (!snapshot) return [];
+    return this.enqueue(async () => {
+      const warnings = [...snapshot?.warnings ?? []];
+      const baselineWarnings = [...warnings];
+      const previousState = this.cloneState();
+      const preservedLiveEphemeralArtifacts = options.preserveLiveEphemeral ? Array.from(this.artifacts.values()).filter((artifact) => artifact.retention === "ephemeral").map(cloneStoredArtifact) : [];
+      let restoredCount = 0;
+      this.artifacts.clear();
+      this.tombstonedIds.clear();
+      this.tombstonedClientIds.clear();
+      this.stickyEphemeralIds.clear();
+      this.markerArtifacts.clear();
+      if (snapshot) {
+        this.insertSeq = 0;
+        this.persistenceSeq = snapshot.sequence;
+        this.durableEventsSinceSnapshot = 0;
+        this.consecutiveSnapshotFailures = 0;
+        for (const id of snapshot.tombstonedIds) {
+          this.tombstonedIds.add(id);
+        }
+        for (const id of snapshot.stickyEphemeralIds.slice(
+          -MAX_STICKY_EPHEMERAL_IDS
+        )) {
+          this.stickyEphemeralIds.add(id);
+        }
+        const markerIds = /* @__PURE__ */ new Set([
+          ...this.tombstonedIds,
+          ...this.stickyEphemeralIds
+        ]);
+        for (const artifact of snapshot.markerArtifacts ?? []) {
+          if (!markerIds.has(artifact.id)) continue;
+          const markerArtifact = await this.normalizeRestoredMarkerArtifact(
+            artifact,
+            warnings
+          );
+          if (markerArtifact)
+            this.markerArtifacts.set(artifact.id, markerArtifact);
+        }
+      }
+      for (const artifact of snapshot?.artifacts ?? []) {
+        try {
+          const input = persistedArtifactToInput(artifact);
+          if (input.retention === "pinned") {
+            input.retention = "restorable";
+            warnings.push(
+              `pinned artifact ${artifact.id} downgraded to restorable; runtime does not support pinned retention`
+            );
+          }
+          let normalized = await this.normalizeInput(
+            input,
+            ++this.receivedSeq,
+            artifact.storage === "published" && !isFileArtifactUrl(artifact.url),
+            {
+              metadataBudget: "persisted",
+              workspaceExpected: workspaceExpectedFromArtifact(artifact),
+              hashWorkspaceContent: false
+            }
+          );
+          if (this.stickyEphemeralIds.has(normalized.id) && normalized.retention !== "ephemeral") {
+            normalized = {
+              ...normalized,
+              retention: "ephemeral",
+              persistenceWarning: "sticky_override_active"
+            };
+          }
+          const stickyApplied = normalized.persistenceWarning === "sticky_override_active";
+          if (normalized.id !== artifact.id) {
+            warnings.push(`skipped artifact with mismatched id ${artifact.id}`);
+            continue;
+          }
+          const retention = normalized.retention;
+          let persistenceWarning;
+          if (stickyApplied) {
+            persistenceWarning = "sticky_override_active";
+          } else if (normalized.status !== "available") {
+            persistenceWarning = "metadata_only_restore";
+          }
+          const stored = {
+            ...normalized,
+            retention,
+            clientRetained: artifact.clientRetained,
+            createdAt: artifact.createdAt,
+            updatedAt: artifact.updatedAt,
+            persistedAt: artifact.persistedAt,
+            status: normalized.status,
+            restoreState: "restored",
+            persistenceWarning,
+            durableTombstoneRequired: retention !== "ephemeral" ? true : void 0,
+            insertSeq: ++this.insertSeq
+          };
+          this.artifacts.set(stored.id, stored);
+          restoredCount++;
+        } catch (error) {
+          warnings.push(
+            `skipped artifact restore: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+      if (snapshot.artifacts.length > 0 && restoredCount === 0) {
+        this.restoreState(previousState);
+        const rollbackWarnings = [
+          ...baselineWarnings,
+          `${RESTORE_FAILED_WARNING_PREFIX}; kept existing live artifacts`
+        ];
+        this.setLastRestoreWarnings(rollbackWarnings);
+        return rollbackWarnings;
+      }
+      if (previousState.artifacts.size > 0 && baselineWarnings.some(isArtifactSnapshotCompletenessWarning)) {
+        this.restoreState(previousState);
+        const rollbackWarnings = [
+          ...baselineWarnings,
+          restoredCount === 0 ? `${RESTORE_FAILED_WARNING_PREFIX}; kept existing live artifacts` : `${RESTORE_PARTIAL_FAILED_WARNING_PREFIX}; kept existing live artifacts`
+        ];
+        this.setLastRestoreWarnings(rollbackWarnings);
+        return rollbackWarnings;
+      }
+      for (const artifact of preservedLiveEphemeralArtifacts) {
+        if (this.artifacts.has(artifact.id) || this.tombstonedIds.has(artifact.id)) {
+          continue;
+        }
+        this.artifacts.set(artifact.id, {
+          ...artifact,
+          insertSeq: ++this.insertSeq
+        });
+      }
+      const evicted = await this.evictOverflow(/* @__PURE__ */ new Set(), []);
+      if (evicted.length > 0) {
+        warnings.push("restored artifact list pruned to live limit");
+        warnings.push(...await this.persistChanges(evicted, false));
+      }
+      this.setLastRestoreWarnings(warnings);
+      return warnings;
+    });
   }
-  async normalizeInput(input, receivedSeq, trustedPublisherFromCaller) {
-    if (!input || typeof input !== "object") {
-      throw new SessionArtifactValidationError("Artifact must be an object");
-    }
-    const title = normalizeString(input.title, "title", 200, true);
-    const description = normalizeString(
-      input.description,
-      "description",
-      1e3,
-      false
-    );
-    const source = input.source ?? "tool";
-    if (source !== "tool" && source !== "hook" && source !== "client") {
-      throw new SessionArtifactValidationError(
-        "source must be tool, hook, or client",
-        "source"
-      );
+  async recordSnapshot() {
+    const persistence = this.persistence;
+    if (!persistence) {
+      return [
+        "artifact persistence unavailable; restored artifacts not snapshotted"
+      ];
     }
-    const trustedPublisher = trustedPublisherFromCaller;
-    const workspacePath = input.workspacePath ? normalizeWorkspacePath(input.workspacePath, this.workspaceCwd) : void 0;
-    const managedId = normalizeManagedId(input.managedId);
-    const rawStorage = input.storage;
-    const storage = inferStorage(rawStorage, {
-      workspacePath,
-      managedId,
-      url: input.url,
-      trustedPublisher
-    });
-    const url = input.url ? normalizeArtifactUrl(input.url, trustedPublisher) : void 0;
-    validateLocator(storage, {
-      workspacePath,
-      managedId,
-      url,
-      trustedPublisher
+    return this.enqueue(async () => {
+      const recordedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const sequence = this.persistenceSeq + 1;
+      try {
+        await persistence.recordSnapshot(
+          this.buildSnapshotPayload(recordedAt, sequence)
+        );
+        this.persistenceSeq = sequence;
+        this.durableEventsSinceSnapshot = 0;
+        this.consecutiveSnapshotFailures = 0;
+        return [];
+      } catch (error) {
+        writeStderrLine(
+          `[artifacts] session=${this.sessionId} action=snapshot_failed reason=${JSON.stringify(
+            error instanceof Error ? error.message : String(error)
+          )}`
+        );
+        return ["artifact snapshot not persisted"];
+      }
     });
-    const metadata = normalizeMetadata(input.metadata);
-    const workspaceStatus = workspacePath ? await this.getInitialWorkspaceStatus(workspacePath) : void 0;
-    if (workspaceStatus?.escaped) {
-      throw new SessionArtifactValidationError(
-        "workspacePath must stay inside the workspace",
-        "workspacePath"
+  }
+  async normalizeRestoredMarkerArtifact(artifact, warnings) {
+    try {
+      const input = persistedArtifactToInput(artifact);
+      if (input.retention === "pinned") {
+        input.retention = "restorable";
+        warnings.push(
+          `pinned marker artifact ${artifact.id} downgraded to restorable; runtime does not support pinned retention`
+        );
+      }
+      const normalized = await this.normalizeInput(
+        input,
+        ++this.receivedSeq,
+        artifact.storage === "published" && !isFileArtifactUrl(artifact.url),
+        {
+          metadataBudget: "persisted",
+          workspaceExpected: workspaceExpectedFromArtifact(artifact),
+          hashWorkspaceContent: false
+        }
+      );
+      if (normalized.id !== artifact.id) {
+        warnings.push(
+          `skipped marker artifact with mismatched id ${artifact.id}`
+        );
+        return void 0;
+      }
+      return toPersistedArtifact(
+        {
+          ...normalized,
+          clientRetained: artifact.clientRetained,
+          createdAt: artifact.createdAt,
+          updatedAt: artifact.updatedAt,
+          persistedAt: artifact.persistedAt
+        },
+        artifact.persistedAt ?? artifact.updatedAt
+      );
+    } catch (error) {
+      warnings.push(
+        `skipped marker artifact ${artifact.id}: ${error instanceof Error ? error.message : String(error)}`
       );
+      return void 0;
     }
-    const kind = normalizeKind(
-      input.kind ?? inferKind({ storage, workspacePath, url })
-    );
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const identityKey = buildIdentityKey({
-      storage,
-      workspacePath,
-      managedId,
-      url
-    });
-    const id = stableArtifactId(this.sessionId, identityKey);
+  }
+  cloneState() {
+    return {
+      artifacts: new Map(
+        Array.from(this.artifacts.entries()).map(([id, artifact]) => [
+          id,
+          cloneStoredArtifact(artifact)
+        ])
+      ),
+      receivedSeq: this.receivedSeq,
+      insertSeq: this.insertSeq,
+      persistenceSeq: this.persistenceSeq,
+      durableEventsSinceSnapshot: this.durableEventsSinceSnapshot,
+      consecutiveSnapshotFailures: this.consecutiveSnapshotFailures,
+      tombstonedIds: new Set(this.tombstonedIds),
+      tombstonedClientIds: new Map(this.tombstonedClientIds),
+      stickyEphemeralIds: new Set(this.stickyEphemeralIds),
+      markerArtifacts: new Map(this.markerArtifacts),
+      lastRestoreWarnings: [...this.lastRestoreWarnings],
+      lastRestoreWarningDetails: [...this.lastRestoreWarningDetails]
+    };
+  }
+  restoreState(state) {
+    this.artifacts.clear();
+    for (const [id, artifact] of state.artifacts) {
+      this.artifacts.set(id, cloneStoredArtifact(artifact));
+    }
+    this.receivedSeq = state.receivedSeq;
+    this.insertSeq = state.insertSeq;
+    this.persistenceSeq = state.persistenceSeq;
+    this.durableEventsSinceSnapshot = state.durableEventsSinceSnapshot;
+    this.consecutiveSnapshotFailures = state.consecutiveSnapshotFailures;
+    this.tombstonedIds.clear();
+    for (const id of state.tombstonedIds) {
+      this.tombstonedIds.add(id);
+    }
+    this.tombstonedClientIds.clear();
+    for (const [id, clientId] of state.tombstonedClientIds) {
+      this.tombstonedClientIds.set(id, clientId);
+    }
+    this.stickyEphemeralIds.clear();
+    for (const id of state.stickyEphemeralIds) {
+      this.stickyEphemeralIds.add(id);
+    }
+    this.markerArtifacts.clear();
+    for (const [id, artifact] of state.markerArtifacts) {
+      this.markerArtifacts.set(id, artifact);
+    }
+    this.setLastRestoreWarnings(state.lastRestoreWarnings);
+    this.lastRestoreWarningDetails = [...state.lastRestoreWarningDetails];
+  }
+  async persistChanges(changes, strict = false) {
+    const durableChanges = changes.filter(isDurablePersistenceChange);
+    if (durableChanges.length === 0) {
+      return [];
+    }
+    if (!this.persistence) {
+      if (strict) {
+        throw new SessionArtifactValidationError(
+          "artifact persistence is unavailable",
+          "retention"
+        );
+      }
+      const warnings = this.downgradeDurableChanges(durableChanges);
+      this.applyDurableMarkers(durableChanges);
+      return warnings;
+    }
+    const recordedAt = (/* @__PURE__ */ new Date()).toISOString();
+    for (const change of durableChanges) {
+      if (change.action === "removed") continue;
+      const stored = this.artifacts.get(change.artifactId);
+      if (!stored) continue;
+      const artifact = {
+        ...toPublicArtifact(stored),
+        persistedAt: recordedAt
+      };
+      change.artifact = artifact;
+    }
+    const sequence = this.persistenceSeq + 1;
+    const payload = {
+      v: SESSION_ARTIFACT_PERSISTENCE_VERSION,
+      sessionId: this.sessionId,
+      sequence,
+      recordedAt,
+      changes: durableChanges.map(
+        (change) => toPersistedChange(change, recordedAt)
+      )
+    };
+    try {
+      await this.persistence.recordEvent(payload);
+      this.persistenceSeq = sequence;
+      for (const change of durableChanges) {
+        if (change.action === "removed") continue;
+        const stored = this.artifacts.get(change.artifactId);
+        if (!stored) continue;
+        stored.persistedAt = recordedAt;
+        stored.durableTombstoneRequired = true;
+        change.artifact = toPublicArtifact(stored);
+      }
+      this.applyDurableMarkers(durableChanges);
+      await this.maybeRecordSnapshot(recordedAt);
+      return [];
+    } catch (error) {
+      if (strict) {
+        throw error;
+      }
+      const reason = error instanceof Error ? error.message : String(error);
+      const artifactIds = durableChanges.map((change) => change.artifactId);
+      writeStderrLine(
+        `[artifacts] session=${this.sessionId} action=persist_failed sequence=${payload.sequence} artifactIds=${JSON.stringify(
+          artifactIds
+        )} reason=${JSON.stringify(reason)}`
+      );
+      const warnings = this.downgradeDurableChanges(durableChanges);
+      this.applyDurableMarkers(durableChanges);
+      return warnings;
+    }
+  }
+  async maybeRecordSnapshot(recordedAt) {
+    if (!this.persistence) return;
+    this.durableEventsSinceSnapshot++;
+    const snapshotThreshold = SNAPSHOT_AFTER_DURABLE_EVENTS * Math.min(
+      MAX_SNAPSHOT_BACKOFF_MULTIPLIER,
+      2 ** this.consecutiveSnapshotFailures
+    );
+    if (this.durableEventsSinceSnapshot < snapshotThreshold) {
+      return;
+    }
+    const sequence = this.persistenceSeq + 1;
+    try {
+      await this.persistence.recordSnapshot(
+        this.buildSnapshotPayload(recordedAt, sequence)
+      );
+      this.persistenceSeq = sequence;
+      this.durableEventsSinceSnapshot = 0;
+      this.consecutiveSnapshotFailures = 0;
+    } catch (error) {
+      this.consecutiveSnapshotFailures = Math.min(
+        this.consecutiveSnapshotFailures + 1,
+        Math.log2(MAX_SNAPSHOT_BACKOFF_MULTIPLIER)
+      );
+      writeStderrLine(
+        `[artifacts] session=${this.sessionId} action=snapshot_failed reason=${JSON.stringify(
+          error instanceof Error ? error.message : String(error)
+        )}`
+      );
+    }
+  }
+  buildSnapshotPayload(recordedAt, sequence) {
+    const artifacts = Array.from(this.artifacts.values()).filter((artifact) => artifact.retention !== "ephemeral").sort((a, b) => a.insertSeq - b.insertSeq).map((artifact) => toPersistedArtifact(artifact, recordedAt));
+    const stickyEphemeralIds = Array.from(this.stickyEphemeralIds).filter(
+      (id) => this.artifacts.has(id) || this.markerArtifacts.has(id)
+    );
+    const markerArtifacts = this.buildMarkerArtifacts(
+      recordedAt,
+      stickyEphemeralIds
+    );
+    return {
+      v: SESSION_ARTIFACT_PERSISTENCE_VERSION,
+      sessionId: this.sessionId,
+      sequence,
+      recordedAt,
+      artifacts,
+      tombstonedIds: Array.from(this.tombstonedIds),
+      stickyEphemeralIds,
+      ...markerArtifacts.length > 0 ? { markerArtifacts } : {}
+    };
+  }
+  buildMarkerArtifacts(recordedAt, stickyEphemeralIds) {
+    const markerIds = [...this.tombstonedIds, ...stickyEphemeralIds];
+    const artifacts = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const id of markerIds) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+      const live = this.artifacts.get(id);
+      if (live) {
+        artifacts.push(toPersistedArtifact(toPublicArtifact(live), recordedAt));
+        continue;
+      }
+      const markerArtifact = this.markerArtifacts.get(id);
+      if (markerArtifact) {
+        artifacts.push(markerArtifact);
+      }
+    }
+    return artifacts;
+  }
+  downgradeDurableChanges(changes) {
+    let downgraded = false;
+    let removalNotPersisted = false;
+    for (const change of changes) {
+      if (change.action === "removed") {
+        removalNotPersisted = true;
+        if (change.reason === "explicit") {
+          this.rememberTombstone(change);
+          this.stickyEphemeralIds.delete(change.artifactId);
+        }
+        continue;
+      }
+      const stored = this.artifacts.get(change.artifactId);
+      if (!stored) continue;
+      stored.retention = "ephemeral";
+      stored.persistenceWarning = "persistence_unavailable";
+      stored.durableTombstoneRequired = stored.durableTombstoneRequired || stored.persistedAt !== void 0;
+      delete stored.persistedAt;
+      change.artifact = toPublicArtifact(stored);
+      downgraded = true;
+    }
+    const warnings = [];
+    if (downgraded) {
+      warnings.push(
+        "artifact persistence unavailable; durable artifacts kept ephemeral"
+      );
+    }
+    if (removalNotPersisted) {
+      warnings.push("artifact removal not persisted; live removal kept");
+    }
+    return warnings;
+  }
+  applyDurableMarkers(changes) {
+    for (const change of changes) {
+      if (change.action === "removed") {
+        if (change.reason === "explicit") {
+          this.rememberTombstone(change);
+          this.stickyEphemeralIds.delete(change.artifactId);
+        } else if (change.reason === "eviction") {
+          this.stickyEphemeralIds.delete(change.artifactId);
+          this.markerArtifacts.delete(change.artifactId);
+        } else if (change.reason === "unpin_to_ephemeral") {
+          this.rememberStickyEphemeral(change);
+        }
+        continue;
+      }
+      if (change.artifact && change.artifact.retention !== "ephemeral") {
+        this.tombstonedIds.delete(change.artifactId);
+        this.tombstonedClientIds.delete(change.artifactId);
+        this.stickyEphemeralIds.delete(change.artifactId);
+        this.markerArtifacts.delete(change.artifactId);
+      }
+    }
+  }
+  rememberStickyEphemeral(change) {
+    const artifactId = change.artifactId;
+    this.stickyEphemeralIds.delete(artifactId);
+    this.stickyEphemeralIds.add(artifactId);
+    if (change.artifact) {
+      this.markerArtifacts.set(
+        artifactId,
+        toPersistedArtifact(change.artifact, change.artifact.updatedAt)
+      );
+    }
+    while (this.stickyEphemeralIds.size > MAX_STICKY_EPHEMERAL_IDS) {
+      const oldest2 = this.stickyEphemeralIds.values().next().value;
+      if (oldest2 === void 0) break;
+      this.stickyEphemeralIds.delete(oldest2);
+      this.markerArtifacts.delete(oldest2);
+    }
+  }
+  rememberTombstone(change) {
+    this.tombstonedIds.delete(change.artifactId);
+    this.tombstonedIds.add(change.artifactId);
+    this.tombstonedClientIds.set(
+      change.artifactId,
+      change.removedClientId ?? this.artifacts.get(change.artifactId)?.clientId
+    );
+    if (change.artifact) {
+      this.markerArtifacts.set(
+        change.artifactId,
+        toPersistedArtifact(change.artifact, change.artifact.updatedAt)
+      );
+    }
+    while (this.tombstonedIds.size > MAX_TOMBSTONED_IDS) {
+      const oldest2 = this.tombstonedIds.values().next().value;
+      if (oldest2 === void 0) break;
+      writeStderrLine(
+        `[artifacts] session=${this.sessionId} action=tombstone_evicted artifactId=${JSON.stringify(
+          oldest2
+        )} limit=${MAX_TOMBSTONED_IDS}`
+      );
+      this.tombstonedIds.delete(oldest2);
+      this.tombstonedClientIds.delete(oldest2);
+      this.markerArtifacts.delete(oldest2);
+    }
+  }
+  setLastRestoreWarnings(warnings) {
+    this.lastRestoreWarnings = [...warnings];
+    this.lastRestoreWarningDetails = detailsForRestoreWarnings(warnings);
+  }
+  enqueue(operation) {
+    const result = this.operationQueue.then(operation, operation);
+    this.operationQueue = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  }
+  denyCrossClientMutation(action, artifactId, existing, options) {
+    if (existing.source !== "client" || existing.clientId === void 0 || existing.clientId === options?.clientId) {
+      return;
+    }
+    writeStderrLine(
+      `[artifacts] session=${this.sessionId} action=${action}_denied artifactId=${artifactId} owner=${existing.clientId} requester=${options?.clientId ?? "<anonymous>"}`
+    );
+    throw new SessionArtifactAuthorizationError(
+      this.sessionId,
+      artifactId,
+      existing.clientId,
+      options?.clientId
+    );
+  }
+  async normalizeInput(input, receivedSeq, trustedPublisherFromCaller, options = {}) {
+    if (!input || typeof input !== "object") {
+      throw new SessionArtifactValidationError("Artifact must be an object");
+    }
+    const title = normalizeString(input.title, "title", 200, true);
+    const description = normalizeString(
+      input.description,
+      "description",
+      1e3,
+      false
+    );
+    const source = input.source ?? "tool";
+    if (source !== "tool" && source !== "hook" && source !== "client") {
+      throw new SessionArtifactValidationError(
+        "source must be tool, hook, or client",
+        "source"
+      );
+    }
+    const trustedPublisher = trustedPublisherFromCaller;
+    const workspacePath = input.workspacePath ? normalizeWorkspacePath(
+      input.workspacePath,
+      await this.getRealWorkspaceCwdForValidation()
+    ) : void 0;
+    const managedId = normalizeManagedId(input.managedId);
+    const rawStorage = input.storage;
+    const storage = inferStorage(rawStorage, {
+      workspacePath,
+      managedId,
+      url: input.url,
+      trustedPublisher
+    });
+    const url = input.url ? normalizeArtifactUrl(input.url, trustedPublisher) : void 0;
+    validateLocator(storage, {
+      workspacePath,
+      managedId,
+      url,
+      trustedPublisher
+    });
+    const retention = normalizeRetention(input.retention, {
+      persistenceAvailable: this.persistence !== void 0
+    });
+    const workspaceStatus = workspacePath ? await this.getInitialWorkspaceStatus(
+      workspacePath,
+      options.workspaceExpected,
+      { hashContent: options.hashWorkspaceContent !== false }
+    ) : void 0;
+    if (workspaceStatus?.escaped) {
+      throw new SessionArtifactValidationError(
+        "workspacePath must stay inside the workspace",
+        "workspacePath"
+      );
+    }
+    const metadata = withWorkspaceContentHashMetadata(
+      normalizeMetadata(input.metadata, {
+        budget: options.metadataBudget ?? "user"
+      }),
+      workspaceStatus
+    );
+    const kind = normalizeKind(
+      input.kind ?? inferKind({ storage, workspacePath, url })
+    );
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const identityKey = buildIdentityKey({
+      storage,
+      workspacePath,
+      managedId,
+      url
+    });
+    const id = stableSessionArtifactId(this.sessionId, identityKey);
     return {
       id,
       identityKey,
       receivedSeq,
+      retentionExplicit: input.retention !== void 0,
       retentionSource: source,
       trustedPublisher,
       kind,
@@ -2492,9 +3398,12 @@ var SessionArtifactStore = class {
       managedId,
       url,
       mimeType: normalizeString(input.mimeType, "mimeType", 120, false),
-      sizeBytes: input.sizeBytes !== void 0 ? normalizeSizeBytes(input.sizeBytes) : workspaceStatus?.sizeBytes,
+      sizeBytes: workspaceStatus?.sizeBytes !== void 0 ? workspaceStatus.sizeBytes : input.sizeBytes !== void 0 ? normalizeSizeBytes(input.sizeBytes) : void 0,
       metadata,
-      clientRetained: source === "client",
+      retention,
+      restoreState: "live",
+      ...this.persistence === void 0 && retention !== "ephemeral" ? { persistenceWarning: "persistence_unavailable" } : {},
+      clientRetained: source === "client" && (input.clientRetained !== void 0 ? input.clientRetained === true : true),
       createdAt: now,
       updatedAt: now,
       toolCallId: normalizeString(input.toolCallId, "toolCallId", 200, false),
@@ -2508,6 +3417,16 @@ var SessionArtifactStore = class {
       clientId: normalizeString(input.clientId, "clientId", 200, false)
     };
   }
+  shouldSuppressTombstonedUpsert(artifact) {
+    if (!this.tombstonedIds.has(artifact.id)) {
+      return false;
+    }
+    const tombstonedClientId = this.tombstonedClientIds.get(artifact.id);
+    if (artifact.source !== "client") {
+      return false;
+    }
+    return !(artifact.retentionExplicit && artifact.clientId !== void 0 && artifact.clientId === tombstonedClientId);
+  }
   async refreshWorkspaceStatuses() {
     const now = Date.now();
     const staleWorkspaceArtifacts = Array.from(this.artifacts.values()).filter((artifact) => artifact.workspacePath).filter((artifact) => shouldRefreshWorkspaceStatus(artifact, now));
@@ -2520,12 +3439,24 @@ var SessionArtifactStore = class {
       })
     );
   }
-  async getInitialWorkspaceStatus(workspacePath) {
+  applyStickyEphemeralOverride(artifact) {
+    if (!this.stickyEphemeralIds.has(artifact.id) || artifact.retentionExplicit || artifact.retention === "ephemeral") {
+      return artifact;
+    }
+    return {
+      ...artifact,
+      retention: "ephemeral",
+      retentionExplicit: true,
+      persistenceWarning: "sticky_override_active"
+    };
+  }
+  async getInitialWorkspaceStatus(workspacePath, expected, options = { hashContent: true }) {
     try {
       return await getWorkspaceStatus(
-        this.workspaceCwd,
         workspacePath,
-        this.getRealWorkspaceCwd()
+        this.getRealWorkspaceCwd(),
+        expected,
+        options
       );
     } catch (error) {
       const reason = error instanceof Error ? error.message : String(error);
@@ -2541,16 +3472,23 @@ var SessionArtifactStore = class {
     }
     try {
       const status = await getWorkspaceStatus(
-        this.workspaceCwd,
         artifact.workspacePath,
-        this.getRealWorkspaceCwd()
+        this.getRealWorkspaceCwd(),
+        {
+          sizeBytes: artifact.sizeBytes,
+          mtimeMs: artifact.metadata?.[WORKSPACE_CONTENT_MTIME_MS_METADATA_KEY],
+          sha256: artifact.metadata?.[WORKSPACE_CONTENT_SHA256_METADATA_KEY]
+        }
       );
-      artifact.status = status.status;
-      artifact.sizeBytes = status.sizeBytes;
+      const changed = isWorkspaceContentChanged(artifact, status);
+      artifact.status = changed ? "changed" : status.status;
+      if (!changed) {
+        artifact.sizeBytes = status.sizeBytes;
+      }
       if (status.escaped) {
         artifact.status = "missing";
         artifact.sizeBytes = void 0;
-        delete artifact.workspacePath;
+        artifact.hideWorkspacePath = true;
       }
       artifact.lastStatAt = options.now ?? Date.now();
     } catch (error) {
@@ -2579,7 +3517,18 @@ var SessionArtifactStore = class {
     }
     return this.realWorkspaceCwdPromise;
   }
-  async evictOverflow(createdIds, changes) {
+  async getRealWorkspaceCwdForValidation() {
+    try {
+      return await this.getRealWorkspaceCwd();
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new SessionArtifactValidationError(
+        `workspacePath could not be inspected: ${reason}`,
+        "workspacePath"
+      );
+    }
+  }
+  async evictOverflow(createdIds, changes, strict = false) {
     const removed = [];
     if (this.artifacts.size <= this.maxArtifacts) {
       return removed;
@@ -2607,10 +3556,17 @@ var SessionArtifactStore = class {
         action: "removed",
         artifactId: artifact.id,
         artifact: toPublicArtifact(artifact),
+        durableTombstoneRequired: artifact.durableTombstoneRequired,
         reason: "eviction"
       });
     }
     const overflowCreated = Array.from(this.artifacts.values()).filter((artifact) => createdInThisBatch.has(artifact.id)).sort((a, b) => b.receivedSeq - a.receivedSeq);
+    if (strict && overflowCreated.length > 0 && this.artifacts.size > this.maxArtifacts) {
+      throw new SessionArtifactValidationError(
+        "artifact store is full; no eviction candidate is available",
+        "artifactId"
+      );
+    }
     for (const artifact of overflowCreated) {
       if (this.artifacts.size <= this.maxArtifacts) {
         break;
@@ -2659,7 +3615,12 @@ function mergeBatchArtifact(existing, next) {
       trustedPublisher: true,
       createdAt: existing.createdAt,
       receivedSeq: existing.receivedSeq,
+      retentionExplicit: existing.retentionExplicit || next.retentionExplicit,
       retentionSource: existing.retentionSource,
+      retention: mergeRetention(existing, next),
+      restoreState: "live",
+      persistenceWarning: existing.persistenceWarning ?? next.persistenceWarning,
+      persistedAt: existing.persistedAt ?? next.persistedAt,
       clientRetained: existing.clientRetained || next.clientRetained,
       lastStatAt: void 0
     };
@@ -2673,6 +3634,8 @@ function mergeBatchArtifact(existing, next) {
     metadata: mergeMetadata(existing, next),
     clientRetained: existing.clientRetained || next.clientRetained,
     trustedPublisher: existing.trustedPublisher || next.trustedPublisher,
+    retentionExplicit: existing.retentionExplicit || next.retentionExplicit,
+    retention: mergeRetention(existing, next),
     lastStatAt: next.lastStatAt ?? existing.lastStatAt
   };
 }
@@ -2692,9 +3655,14 @@ function mergeArtifact(existing, incoming) {
     managedId: publishedUpdate ? incoming.managedId ?? existing.managedId : existing.managedId,
     url: publishedUpdate ? incoming.url ?? existing.url : existing.url,
     workspacePath: publishedUpdate || existing.storage === "published" ? void 0 : existing.workspacePath ?? incoming.workspacePath,
+    hideWorkspacePath: publishedUpdate || existing.storage === "published" || incoming.workspacePath ? void 0 : existing.hideWorkspacePath,
     mimeType: publishedUpdate ? incoming.mimeType ?? existing.mimeType : existing.mimeType,
     sizeBytes: existing.storage === "published" && !publishedUpdate ? existing.sizeBytes : mergeSizeBytes(existing, incoming),
     metadata: existing.storage === "published" && !publishedUpdate ? existing.metadata : mergeMetadata(existing, incoming),
+    retention: mergeRetention(existing, incoming),
+    restoreState: "live",
+    persistenceWarning: incoming.retentionExplicit && incoming.retention !== "ephemeral" ? incoming.persistenceWarning : existing.persistenceWarning ?? incoming.persistenceWarning,
+    persistedAt: incoming.retentionExplicit && incoming.retention === "ephemeral" ? void 0 : existing.persistedAt ?? incoming.persistedAt,
     source: existing.source,
     retentionSource: existing.retentionSource,
     trustedPublisher: existing.trustedPublisher || incoming.trustedPublisher,
@@ -2706,6 +3674,7 @@ function mergeArtifact(existing, incoming) {
     next.title = incoming.title;
     next.description = incoming.description;
     delete next.workspacePath;
+    delete next.hideWorkspacePath;
   }
   const changed = !publicArtifactsEqual(
     toPublicArtifact(existing),
@@ -2717,8 +3686,12 @@ function mergeArtifact(existing, incoming) {
   return { artifact: changed ? next : existing, changed };
 }
 __name(mergeArtifact, "mergeArtifact");
+function shouldRecordEphemeralUnpin(existing, incoming) {
+  return incoming.retentionExplicit && incoming.retention === "ephemeral" && (existing.retention !== "ephemeral" || existing.persistedAt !== void 0 || existing.durableTombstoneRequired === true);
+}
+__name(shouldRecordEphemeralUnpin, "shouldRecordEphemeralUnpin");
 function publicArtifactsEqual(a, b) {
-  return a.id === b.id && a.kind === b.kind && a.storage === b.storage && a.source === b.source && a.status === b.status && a.title === b.title && a.description === b.description && a.workspacePath === b.workspacePath && a.managedId === b.managedId && a.url === b.url && a.mimeType === b.mimeType && a.sizeBytes === b.sizeBytes && metadataEqual(a.metadata, b.metadata) && a.clientRetained === b.clientRetained && a.createdAt === b.createdAt && a.toolCallId === b.toolCallId && a.toolName === b.toolName && a.hookEventName === b.hookEventName && a.clientId === b.clientId;
+  return a.id === b.id && a.kind === b.kind && a.storage === b.storage && a.source === b.source && a.status === b.status && a.title === b.title && a.description === b.description && a.workspacePath === b.workspacePath && a.managedId === b.managedId && a.url === b.url && a.mimeType === b.mimeType && a.sizeBytes === b.sizeBytes && metadataEqual(a.metadata, b.metadata) && a.retention === b.retention && a.restoreState === b.restoreState && a.persistenceWarning === b.persistenceWarning && a.persistedAt === b.persistedAt && a.clientRetained === b.clientRetained && a.createdAt === b.createdAt && a.updatedAt === b.updatedAt && a.toolCallId === b.toolCallId && a.toolName === b.toolName && a.hookEventName === b.hookEventName && a.clientId === b.clientId;
 }
 __name(publicArtifactsEqual, "publicArtifactsEqual");
 function metadataEqual(a, b) {
@@ -2740,6 +3713,24 @@ function mergeSizeBytes(existing, incoming) {
   return existing.sizeBytes;
 }
 __name(mergeSizeBytes, "mergeSizeBytes");
+function strongestRetention(a, b) {
+  const rank = {
+    ephemeral: 0,
+    restorable: 1
+  };
+  return rank[b] > rank[a] ? b : a;
+}
+__name(strongestRetention, "strongestRetention");
+function mergeRetention(existing, incoming) {
+  if (incoming.retentionExplicit && incoming.retention === "ephemeral") {
+    return "ephemeral";
+  }
+  if (existing.retentionExplicit && existing.retention === "ephemeral" && !incoming.retentionExplicit) {
+    return "ephemeral";
+  }
+  return strongestRetention(existing.retention, incoming.retention);
+}
+__name(mergeRetention, "mergeRetention");
 function mergeMetadata(existing, incoming) {
   if (!incoming.metadata || incoming.source === "hook" || incoming.source !== existing.source) {
     return existing.metadata;
@@ -2747,7 +3738,10 @@ function mergeMetadata(existing, incoming) {
   const merged = { ...existing.metadata ?? {} };
   let changed = false;
   for (const [key, value] of Object.entries(incoming.metadata)) {
-    if (!Object.hasOwn(merged, key)) {
+    if ((key === WORKSPACE_CONTENT_SHA256_METADATA_KEY || key === WORKSPACE_CONTENT_MTIME_MS_METADATA_KEY) && merged[key] !== value) {
+      merged[key] = value;
+      changed = true;
+    } else if (!Object.hasOwn(merged, key)) {
       merged[key] = value;
       changed = true;
     }
@@ -2765,7 +3759,7 @@ function mergeMetadata(existing, incoming) {
 }
 __name(mergeMetadata, "mergeMetadata");
 function isMetadataWithinLimit(metadata) {
-  return Buffer.byteLength(JSON.stringify(metadata), "utf8") <= 4096;
+  return metadataBudgetBytes(metadata, "persisted") <= 4096;
 }
 __name(isMetadataWithinLimit, "isMetadataWithinLimit");
 function countByRetentionSource(artifacts) {
@@ -2821,6 +3815,7 @@ function removePriorChange(changes, artifactId) {
 }
 __name(removePriorChange, "removePriorChange");
 function toPublicArtifact(artifact) {
+  const hideWorkspacePath = "hideWorkspacePath" in artifact && artifact.hideWorkspacePath === true;
   const {
     id,
     kind,
@@ -2835,13 +3830,16 @@ function toPublicArtifact(artifact) {
     mimeType,
     sizeBytes,
     metadata,
+    retention,
+    restoreState,
+    persistenceWarning,
+    persistedAt,
     clientRetained,
     createdAt,
     updatedAt,
     toolCallId,
     toolName,
-    hookEventName,
-    clientId
+    hookEventName
   } = artifact;
   return {
     id,
@@ -2851,22 +3849,205 @@ function toPublicArtifact(artifact) {
     status,
     title,
     ...description ? { description } : {},
-    ...workspacePath ? { workspacePath } : {},
+    ...workspacePath && !hideWorkspacePath ? { workspacePath } : {},
     ...managedId ? { managedId } : {},
     ...url ? { url } : {},
     ...mimeType ? { mimeType } : {},
     ...sizeBytes !== void 0 ? { sizeBytes } : {},
     ...metadata ? { metadata } : {},
+    retention,
+    ...restoreState ? { restoreState } : {},
+    ...persistenceWarning ? { persistenceWarning } : {},
+    ...persistedAt ? { persistedAt } : {},
     clientRetained,
     createdAt,
     updatedAt,
     ...toolCallId ? { toolCallId } : {},
     ...toolName ? { toolName } : {},
-    ...hookEventName ? { hookEventName } : {},
-    ...clientId ? { clientId } : {}
+    ...hookEventName ? { hookEventName } : {}
   };
 }
 __name(toPublicArtifact, "toPublicArtifact");
+function persistedArtifactToInput(artifact) {
+  return {
+    title: artifact.title,
+    kind: artifact.kind,
+    storage: artifact.storage,
+    description: artifact.description,
+    workspacePath: artifact.workspacePath,
+    managedId: artifact.managedId,
+    url: artifact.url,
+    mimeType: artifact.mimeType,
+    sizeBytes: artifact.sizeBytes,
+    metadata: artifact.metadata,
+    source: artifact.source,
+    retention: artifact.retention,
+    clientRetained: artifact.clientRetained,
+    toolCallId: artifact.toolCallId,
+    toolName: artifact.toolName,
+    hookEventName: artifact.hookEventName
+  };
+}
+__name(persistedArtifactToInput, "persistedArtifactToInput");
+function workspaceExpectedFromArtifact(artifact) {
+  if (!artifact.workspacePath) {
+    return void 0;
+  }
+  return {
+    sizeBytes: artifact.sizeBytes,
+    mtimeMs: artifact.metadata?.[WORKSPACE_CONTENT_MTIME_MS_METADATA_KEY],
+    sha256: artifact.metadata?.[WORKSPACE_CONTENT_SHA256_METADATA_KEY]
+  };
+}
+__name(workspaceExpectedFromArtifact, "workspaceExpectedFromArtifact");
+function toPersistedChange(change, recordedAt) {
+  return {
+    action: change.action,
+    artifactId: change.artifactId,
+    ...change.artifact ? { artifact: toPersistedArtifact(change.artifact, recordedAt) } : {},
+    ...change.reason ? { reason: change.reason } : {}
+  };
+}
+__name(toPersistedChange, "toPersistedChange");
+function toPersistedArtifact(artifact, recordedAt) {
+  return {
+    id: artifact.id,
+    kind: artifact.kind,
+    storage: artifact.storage,
+    source: artifact.source,
+    status: artifact.status === "changed" ? "available" : artifact.status,
+    title: artifact.title,
+    ...artifact.description ? { description: artifact.description } : {},
+    ...artifact.workspacePath ? { workspacePath: artifact.workspacePath } : {},
+    ...artifact.managedId ? { managedId: artifact.managedId } : {},
+    ...artifact.url ? { url: artifact.url } : {},
+    ...artifact.mimeType ? { mimeType: artifact.mimeType } : {},
+    ...artifact.sizeBytes !== void 0 ? { sizeBytes: artifact.sizeBytes } : {},
+    ...artifact.metadata ? { metadata: artifact.metadata } : {},
+    retention: artifact.retention,
+    clientRetained: artifact.clientRetained,
+    createdAt: artifact.createdAt,
+    updatedAt: artifact.updatedAt,
+    persistedAt: artifact.persistedAt ?? recordedAt,
+    ...artifact.toolCallId ? { toolCallId: artifact.toolCallId } : {},
+    ...artifact.toolName ? { toolName: artifact.toolName } : {},
+    ...artifact.hookEventName ? { hookEventName: artifact.hookEventName } : {}
+  };
+}
+__name(toPersistedArtifact, "toPersistedArtifact");
+function isFileArtifactUrl(raw) {
+  if (typeof raw !== "string") return false;
+  try {
+    return new URL(raw).protocol === "file:";
+  } catch {
+    return false;
+  }
+}
+__name(isFileArtifactUrl, "isFileArtifactUrl");
+function isArtifactSnapshotCompletenessWarning(warning) {
+  if (warning.startsWith("skipped stale event sequence ")) return false;
+  return warning.startsWith("skipped ") || warning.includes(" list truncated to ");
+}
+__name(isArtifactSnapshotCompletenessWarning, "isArtifactSnapshotCompletenessWarning");
+function shouldCommitBeforeDurablePersistence(change) {
+  return change.action === "removed" && change.durableTombstoneRequired === true;
+}
+__name(shouldCommitBeforeDurablePersistence, "shouldCommitBeforeDurablePersistence");
+function isDurablePersistenceChange(change) {
+  if (change.action === "removed" && change.durableTombstoneRequired === true) {
+    return true;
+  }
+  if (!change.artifact) return false;
+  return change.artifact.retention !== "ephemeral" || change.artifact.persistenceWarning === "persistence_unavailable";
+}
+__name(isDurablePersistenceChange, "isDurablePersistenceChange");
+function stripDurableTombstoneMarkers(changes) {
+  for (const change of changes) {
+    delete change.durableTombstoneRequired;
+    delete change.removedClientId;
+  }
+}
+__name(stripDurableTombstoneMarkers, "stripDurableTombstoneMarkers");
+function detailsForRestoreWarnings(warnings) {
+  return warnings.map((warning) => {
+    if (warning.startsWith(RESTORE_FAILED_WARNING_PREFIX)) {
+      return {
+        code: "ARTIFACT_RESTORE_FAILED",
+        operation: "restore",
+        durability: "unavailable",
+        retryable: true,
+        message: warning
+      };
+    }
+    if (warning.startsWith(RESTORE_PARTIAL_FAILED_WARNING_PREFIX)) {
+      return {
+        code: "ARTIFACT_RESTORE_PARTIAL_FAILED",
+        operation: "restore",
+        durability: "live_only",
+        retryable: true,
+        message: warning
+      };
+    }
+    return {
+      code: "ARTIFACT_WARNING",
+      operation: "restore",
+      message: warning
+    };
+  });
+}
+__name(detailsForRestoreWarnings, "detailsForRestoreWarnings");
+function detailsForPersistenceWarnings(warnings, changes, operation) {
+  if (warnings.length === 0) return [];
+  const artifactIds = changes.filter(isDurablePersistenceChange).map((change) => change.artifactId);
+  return warnings.map((warning) => {
+    if (warning === "artifact persistence unavailable; durable artifacts kept ephemeral") {
+      return {
+        code: "ARTIFACT_PERSISTENCE_UNAVAILABLE",
+        operation,
+        artifactIds,
+        durability: "live_only",
+        retryable: false,
+        message: warning
+      };
+    }
+    if (warning === "artifact removal not persisted; live removal kept") {
+      return {
+        code: "ARTIFACT_REMOVAL_NOT_PERSISTED",
+        operation,
+        artifactIds,
+        durability: "live_only",
+        retryable: true,
+        message: warning
+      };
+    }
+    return {
+      code: "ARTIFACT_WARNING",
+      operation,
+      artifactIds,
+      message: warning
+    };
+  });
+}
+__name(detailsForPersistenceWarnings, "detailsForPersistenceWarnings");
+function persistenceFailureDetail(options) {
+  const unavailable = options.error instanceof SessionArtifactValidationError && options.error.message === "artifact persistence is unavailable";
+  return {
+    code: unavailable ? "ARTIFACT_PERSISTENCE_UNAVAILABLE" : "ARTIFACT_PERSISTENCE_WRITE_FAILED",
+    operation: options.operation,
+    artifactIds: options.artifactIds,
+    durability: "unavailable",
+    retryable: !unavailable,
+    message: options.message
+  };
+}
+__name(persistenceFailureDetail, "persistenceFailureDetail");
+function cloneStoredArtifact(artifact) {
+  return {
+    ...artifact,
+    ...artifact.metadata ? { metadata: { ...artifact.metadata } } : {}
+  };
+}
+__name(cloneStoredArtifact, "cloneStoredArtifact");
 function inferStorage(requested, locators) {
   if (requested !== void 0 && typeof requested !== "string") {
     throw new SessionArtifactValidationError(
@@ -2960,10 +4141,6 @@ function buildIdentityKey(input) {
   );
 }
 __name(buildIdentityKey, "buildIdentityKey");
-function stableArtifactId(sessionId, identityKey) {
-  return createHash("sha256").update(`${sessionId}:${identityKey}`).digest("hex").slice(0, 16);
-}
-__name(stableArtifactId, "stableArtifactId");
 function managedIdForWorkspacePath(workspaceCwd, workspacePath) {
   return createHash("sha1").update(path2.resolve(workspaceCwd, workspacePath)).digest("hex").slice(0, 16);
 }
@@ -3077,6 +4254,12 @@ function normalizeArtifactUrl(raw, allowFile) {
       "url"
     );
   }
+  if (hasSecretLikeUrlComponent(parsed)) {
+    throw new SessionArtifactValidationError(
+      "url must not include secret-like components",
+      "url"
+    );
+  }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:" && !(allowFile && parsed.protocol === "file:")) {
     throw new SessionArtifactValidationError(
       allowFile ? "url must use http, https, or file" : "url must use http or https",
@@ -3086,7 +4269,64 @@ function normalizeArtifactUrl(raw, allowFile) {
   return parsed.href;
 }
 __name(normalizeArtifactUrl, "normalizeArtifactUrl");
-function normalizeMetadata(metadata) {
+function hasSecretLikeUrlComponent(parsed) {
+  for (const [key, value] of parsed.searchParams) {
+    if (isSecretLikeUrlText(key) || isSecretLikeUrlValue(value)) {
+      return true;
+    }
+  }
+  for (const segment of parsed.pathname.split("/").filter(Boolean)) {
+    let decodedSegment = segment;
+    try {
+      decodedSegment = decodeURIComponent(segment);
+    } catch {
+    }
+    if (isSecretLikeUrlValue(decodedSegment)) {
+      return true;
+    }
+  }
+  const fragment = parsed.hash.slice(1);
+  return hasSecretLikeUrlFragment(fragment);
+}
+__name(hasSecretLikeUrlComponent, "hasSecretLikeUrlComponent");
+function hasSecretLikeUrlFragment(fragment) {
+  if (!fragment) return false;
+  const candidates = /* @__PURE__ */ new Set([fragment]);
+  try {
+    candidates.add(decodeURIComponent(fragment));
+  } catch {
+  }
+  for (const candidate of candidates) {
+    if (isSecretLikeUrlText(candidate) || isSecretLikeUrlValue(candidate)) {
+      return true;
+    }
+    for (const [key, value] of new URLSearchParams(candidate)) {
+      if (isSecretLikeUrlText(key) || isSecretLikeUrlValue(value)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+__name(hasSecretLikeUrlFragment, "hasSecretLikeUrlFragment");
+function isSecretLikeUrlText(value) {
+  const normalized = value.replace(/([a-z])([A-Z])/g, "$1-$2");
+  return /(?:^|[-_.])(token|secret|password|passwd|pwd|cookie|authorization|credential|signature|sig|api[-_]?key|access[-_]?key)(?:$|[-_.=&#])/i.test(
+    normalized
+  );
+}
+__name(isSecretLikeUrlText, "isSecretLikeUrlText");
+function isSecretLikeUrlValue(value) {
+  return SECRET_TOKEN_VALUE_PATTERN.test(value.trim());
+}
+__name(isSecretLikeUrlValue, "isSecretLikeUrlValue");
+function isSecretLikeMetadataValue(value) {
+  return /^(?:bearer\s+\S{8,}|sk-[A-Za-z0-9_-]{12,}|(?:gh[pousr]|github_pat)_[A-Za-z0-9_/-]{12,})$/i.test(
+    value.trim()
+  );
+}
+__name(isSecretLikeMetadataValue, "isSecretLikeMetadataValue");
+function normalizeMetadata(metadata, options = {}) {
   if (metadata === void 0) {
     return void 0;
   }
@@ -3098,6 +4338,12 @@ function normalizeMetadata(metadata) {
   }
   const normalized = {};
   for (const [key, value] of Object.entries(metadata)) {
+    if (isPrototypeMetadataKey(key)) {
+      continue;
+    }
+    if (options.budget !== "persisted" && isReservedWorkspaceMetadataKey(key)) {
+      continue;
+    }
     if (!key) {
       throw new SessionArtifactValidationError(
         "metadata keys must not be empty",
@@ -3116,6 +4362,12 @@ function normalizeMetadata(metadata) {
         "metadata"
       );
     }
+    if (isSecretLikeUrlText(key)) {
+      throw new SessionArtifactValidationError(
+        "metadata keys must not contain secret-like names",
+        "metadata"
+      );
+    }
     if (value !== null && typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
       throw new SessionArtifactValidationError(
         "metadata values must be primitive",
@@ -3134,12 +4386,18 @@ function normalizeMetadata(metadata) {
         "metadata"
       );
     }
+    if (typeof value === "string" && !isReservedWorkspaceMetadataKey(key) && isSecretLikeMetadataValue(value)) {
+      throw new SessionArtifactValidationError(
+        "metadata string values must not contain secret-like tokens",
+        "metadata"
+      );
+    }
     normalized[key] = value;
   }
   if (Object.keys(normalized).length === 0) {
     return void 0;
   }
-  if (Buffer.byteLength(JSON.stringify(normalized), "utf8") > 4096) {
+  if (metadataBudgetBytes(normalized, options.budget ?? "user") > 4096) {
     throw new SessionArtifactValidationError(
       "metadata must be 4096 bytes or fewer",
       "metadata"
@@ -3148,6 +4406,25 @@ function normalizeMetadata(metadata) {
   return normalized;
 }
 __name(normalizeMetadata, "normalizeMetadata");
+function normalizeRetention(value, options) {
+  if (value === void 0) {
+    return options.persistenceAvailable ? "restorable" : "ephemeral";
+  }
+  if (value === "ephemeral" || value === "restorable") {
+    return value;
+  }
+  if (value === "pinned") {
+    throw new SessionArtifactValidationError(
+      "pinned retention is not supported by session_artifacts_persistence",
+      "retention"
+    );
+  }
+  throw new SessionArtifactValidationError(
+    "retention must be ephemeral or restorable",
+    "retention"
+  );
+}
+__name(normalizeRetention, "normalizeRetention");
 function normalizeSizeBytes(value) {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
     throw new SessionArtifactValidationError(
@@ -3173,21 +4450,83 @@ function inferKind(input) {
   return input.workspacePath ? "file" : "other";
 }
 __name(inferKind, "inferKind");
-async function getWorkspaceStatus(workspaceCwd, workspacePath, realWorkspaceCwd) {
-  const absolutePath = path2.resolve(workspaceCwd, workspacePath);
+async function getWorkspaceStatus(workspacePath, realWorkspaceCwd, expected, options = { hashContent: true }) {
   const realWorkspace = await realWorkspaceCwd;
+  const absolutePath = path2.resolve(realWorkspace, workspacePath);
   try {
     const realPath = await fs2.realpath(absolutePath);
     const relative = path2.relative(realWorkspace, realPath);
     if (!relative || isOutsidePath(relative)) {
       return { status: "missing", escaped: true };
     }
-    const stat = await fs2.stat(realPath);
-    return {
-      status: "available",
-      ...stat.isFile() ? { sizeBytes: stat.size } : {}
-    };
+    const preOpenStat = await fs2.lstat(realPath);
+    const handle = await fs2.open(
+      realPath,
+      fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW
+    );
+    try {
+      const stat = await handle.stat();
+      if (!isSameFile(preOpenStat, stat)) {
+        return { status: "missing", escaped: true };
+      }
+      if (stat.isFile()) {
+        const expectedMtimeMs = typeof expected?.mtimeMs === "number" ? expected.mtimeMs : void 0;
+        const expectedSha256 = typeof expected?.sha256 === "string" ? expected.sha256 : void 0;
+        const unchanged = expected?.sizeBytes === stat.size && expectedMtimeMs === stat.mtimeMs;
+        const sizeChanged = expected?.sizeBytes !== void 0 && expected.sizeBytes !== stat.size;
+        if (sizeChanged) {
+          return {
+            status: "changed",
+            sizeBytes: stat.size,
+            mtimeMs: stat.mtimeMs
+          };
+        }
+        if (unchanged) {
+          return {
+            status: "available",
+            sizeBytes: stat.size,
+            mtimeMs: stat.mtimeMs
+          };
+        }
+        if (stat.size > MAX_WORKSPACE_HASH_BYTES) {
+          return {
+            status: expectedSha256 ? "changed" : "available",
+            sizeBytes: stat.size,
+            mtimeMs: stat.mtimeMs
+          };
+        }
+        if (!options.hashContent) {
+          return {
+            status: expectedSha256 ? "changed" : "available",
+            sizeBytes: stat.size,
+            mtimeMs: stat.mtimeMs
+          };
+        }
+        const sha256 = await hashFile(handle);
+        if (expectedSha256 && sha256 !== expectedSha256) {
+          return {
+            status: "changed",
+            sizeBytes: stat.size,
+            mtimeMs: stat.mtimeMs
+          };
+        }
+        return {
+          status: "available",
+          sizeBytes: stat.size,
+          mtimeMs: stat.mtimeMs,
+          sha256
+        };
+      }
+      return {
+        status: "available"
+      };
+    } finally {
+      await handle.close();
+    }
   } catch (error) {
+    if (isNoFollowSymlinkError(error)) {
+      return { status: "missing", escaped: true };
+    }
     if (!isNotFoundError(error)) {
       throw error;
     }
@@ -3198,6 +4537,41 @@ async function getWorkspaceStatus(workspaceCwd, workspacePath, realWorkspaceCwd)
   }
 }
 __name(getWorkspaceStatus, "getWorkspaceStatus");
+function isSameFile(before, after) {
+  return before.dev === after.dev && before.ino === after.ino;
+}
+__name(isSameFile, "isSameFile");
+async function hashFile(handle) {
+  const hash = createHash("sha256");
+  for await (const chunk of handle.createReadStream({ start: 0 })) {
+    hash.update(chunk);
+  }
+  return hash.digest("hex");
+}
+__name(hashFile, "hashFile");
+function withWorkspaceContentHashMetadata(metadata, workspaceStatus) {
+  if (workspaceStatus?.status !== "available" || !workspaceStatus.sha256) {
+    return metadata;
+  }
+  const next = {
+    ...metadata ?? {},
+    [WORKSPACE_CONTENT_SHA256_METADATA_KEY]: workspaceStatus.sha256,
+    ...workspaceStatus.mtimeMs !== void 0 ? { [WORKSPACE_CONTENT_MTIME_MS_METADATA_KEY]: workspaceStatus.mtimeMs } : {}
+  };
+  return next;
+}
+__name(withWorkspaceContentHashMetadata, "withWorkspaceContentHashMetadata");
+function isWorkspaceContentChanged(artifact, status) {
+  if (status.status !== "available") {
+    return false;
+  }
+  const expectedSha256 = artifact.metadata?.[WORKSPACE_CONTENT_SHA256_METADATA_KEY];
+  if (artifact.sizeBytes !== void 0 && status.sizeBytes !== void 0 && status.sizeBytes !== artifact.sizeBytes) {
+    return true;
+  }
+  return typeof expectedSha256 === "string" && status.sha256 !== void 0 && status.sha256 !== expectedSha256;
+}
+__name(isWorkspaceContentChanged, "isWorkspaceContentChanged");
 async function danglingSymlinkEscapesWorkspace(absolutePath, realWorkspace) {
   try {
     const stat = await fs2.lstat(absolutePath);
@@ -3230,6 +4604,13 @@ function isNotFoundError(error) {
   return code === "ENOENT" || code === "ENOTDIR";
 }
 __name(isNotFoundError, "isNotFoundError");
+function isNoFollowSymlinkError(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return false;
+  }
+  return error.code === "ELOOP";
+}
+__name(isNoFollowSymlinkError, "isNoFollowSymlinkError");
 function isOutsidePath(relative) {
   return relative === ".." || relative.startsWith(`..${path2.sep}`) || path2.isAbsolute(relative);
 }
@@ -3464,6 +4845,12 @@ function parseWorkspaceMemoryDreamResult(response) {
   };
 }
 __name(parseWorkspaceMemoryDreamResult, "parseWorkspaceMemoryDreamResult");
+function pickUserInputEchoMeta(meta) {
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return {};
+  const inputAnnotations = meta["inputAnnotations"];
+  return Array.isArray(inputAnnotations) ? { inputAnnotations } : {};
+}
+__name(pickUserInputEchoMeta, "pickUserInputEchoMeta");
 function echoPromptToSessionBus(entry, req, originatorClientId) {
   const prompt = req.prompt;
   if (!Array.isArray(prompt) || prompt.length === 0) return;
@@ -3485,7 +4872,11 @@ function echoPromptToSessionBus(entry, req, originatorClientId) {
             // field permitted alongside spec fields, the SDK normalizer
             // reads it from `update._meta`/`data._meta`, and every other
             // agent-emitted session_update carries `_meta` the same way.
-            _meta: { serverTimestamp, source: "bridge-echo" }
+            _meta: {
+              ...pickUserInputEchoMeta(req._meta),
+              serverTimestamp,
+              source: "bridge-echo"
+            }
           }
         },
         ...originatorClientId ? { originatorClientId } : {}
@@ -3582,6 +4973,11 @@ function broadcastTurnError(entry, sessionId, err, promptId, originatorClientId)
     );
   }
   entry.retryAllowed = true;
+  entry.turnError = {
+    message,
+    ...code ? { code } : {},
+    ...errorKind ? { errorKind } : {}
+  };
   try {
     entry.events.publish({
       type: "turn_error",
@@ -3624,6 +5020,7 @@ function extractPromptText(prompt) {
 __name(extractPromptText, "extractPromptText");
 var DEFAULT_INIT_TIMEOUT_MS = 1e4;
 var PERSIST_TIMEOUT_MS = 5e3;
+var MAX_PARENT_PERSIST_ATTEMPTS = 3;
 var MCP_RESTART_TIMEOUT_MS = 3e5;
 var WORKSPACE_MEMORY_REMEMBER_TIMEOUT_MS = 3e5;
 var MCP_OAUTH_TIMEOUT_MS = 6e5;
@@ -3631,6 +5028,7 @@ var DAEMON_RETRY_META_KEY = "qwen.daemon.retry";
 var DAEMON_CONTINUE_META_KEY = "qwen.daemon.continueLastTurn";
 var SESSION_RECAP_TIMEOUT_MS = 6e4;
 var SESSION_BTW_TIMEOUT_MS = 6e4;
+var SESSION_TRANSCRIPT_TIMEOUT_MS = 6e4;
 var SHELL_COMMAND_TIMEOUT_MS = 12e4;
 var MAX_SHELL_OUTPUT_FOR_HISTORY = 1e4;
 var MAX_MID_TURN_QUEUE_DEPTH = 20;
@@ -3671,6 +5069,15 @@ function createAcpSessionBridge(opts) {
       );
     }
   }, "releaseFreshSessionReservation");
+  const emitSessionLifecycle = /* @__PURE__ */ __name((event) => {
+    try {
+      opts.sessionLifecycle?.(event);
+    } catch (err) {
+      const message = `qwen serve: session lifecycle callback failed: ${err instanceof Error ? err.message : String(err)}`;
+      opts.onDiagnosticLine?.(message, "warn");
+      writeStderrLine(message);
+    }
+  }, "emitSessionLifecycle");
   if (defaultSessionScope !== "single" && defaultSessionScope !== "thread") {
     throw new TypeError(
       `Invalid sessionScope: ${JSON.stringify(defaultSessionScope)}. Expected 'single' or 'thread'.`
@@ -3855,14 +5262,33 @@ function createAcpSessionBridge(opts) {
   const aliveChannels = /* @__PURE__ */ new Set();
   let inFlightChannelSpawn;
   const byId = /* @__PURE__ */ new Map();
-  const toSessionSummary = /* @__PURE__ */ __name((entry) => ({
-    sessionId: entry.sessionId,
-    workspaceCwd: entry.workspaceCwd,
-    createdAt: entry.createdAt,
-    displayName: entry.displayName,
-    clientCount: entry.clientIds.size,
-    hasActivePrompt: entry.promptActive
-  }), "toSessionSummary");
+  const inFlightExtensionRefreshes = /* @__PURE__ */ new Map();
+  const toSessionSummary = /* @__PURE__ */ __name((entry) => {
+    let isWaitingForPermission = false;
+    let isWaitingForUserQuestion = false;
+    for (const interaction of entry.pendingInteractions.values()) {
+      if (interaction.kind === "user_question") {
+        isWaitingForUserQuestion = true;
+      } else {
+        isWaitingForPermission = true;
+      }
+    }
+    return {
+      sessionId: entry.sessionId,
+      workspaceCwd: entry.workspaceCwd,
+      createdAt: entry.createdAt,
+      displayName: entry.displayName,
+      ...entry.parentSessionId ? { parentSessionId: entry.parentSessionId } : {},
+      clientCount: entry.clientIds.size,
+      hasActivePrompt: entry.promptActive,
+      isWaitingForPermission,
+      isWaitingForUserQuestion,
+      pendingInteractionCount: entry.pendingInteractions.size,
+      hasTurnError: entry.turnError !== void 0,
+      ...entry.turnError !== void 0 ? { turnError: entry.turnError } : {},
+      pendingInteractions: [...entry.pendingInteractions.values()]
+    };
+  }, "toSessionSummary");
   const permissionConsensusQuorum = opts.permissionConsensusQuorum;
   if (permissionConsensusQuorum !== void 0 && (!Number.isInteger(permissionConsensusQuorum) || permissionConsensusQuorum < 1)) {
     throw new Error(
@@ -3888,6 +5314,7 @@ function createAcpSessionBridge(opts) {
     }
   );
   let shuttingDown = false;
+  let shutdownPromise;
   const teeServeDebugLine = /* @__PURE__ */ __name((message) => {
     writeServeDebugLine(message);
     if (opts.onDiagnosticLine && isServeDebugLoggingEnabled()) {
@@ -3921,6 +5348,22 @@ function createAcpSessionBridge(opts) {
       entry.clientIds.set(clientId, count - 1);
     }
   }, "unregisterClient");
+  const rollbackAttachRegistration = /* @__PURE__ */ __name(async (entry, clientId, attachCountDelta = 1) => {
+    entry.attachCount = Math.max(0, entry.attachCount - attachCountDelta);
+    unregisterClient(entry, clientId);
+    if (entry.spawnOwnerWantedKill && entry.attachCount === 0 && entry.events.subscriberCount === 0) {
+      await bridgeApi.killSession(entry.sessionId).catch(() => {
+      });
+    } else if (entry.clientIds.size === 0 && entry.events.subscriberCount === 0 && !entry.promptActive) {
+      await closeSessionImpl(entry.sessionId, void 0, {
+        reason: "last_client_detached"
+      }).catch((err) => {
+        writeStderrLine(
+          `qwen serve: close-on-attach-rollback failed for ${JSON.stringify(entry.sessionId)}: ${err instanceof Error ? err.stack ?? err.message : String(err)}`
+        );
+      });
+    }
+  }, "rollbackAttachRegistration");
   const resolveTrustedClientId = /* @__PURE__ */ __name((entry, clientId) => {
     if (clientId === void 0) return void 0;
     if (!entry.clientIds.has(clientId)) {
@@ -3997,11 +5440,17 @@ function createAcpSessionBridge(opts) {
         // at the session/update fan-in to the daemon host's metrics ring via
         // the telemetry seam. Optional-chained so non-daemon callers (tests,
         // Mode A) that wire no `tokenUsage` metric are a silent no-op.
-        (inputTokens, outputTokens, durationMs) => telemetry.metrics?.tokenUsage?.(
+        (inputTokens, outputTokens, durationMs, apiErrors, apiRetries) => telemetry.metrics?.tokenUsage?.(
           inputTokens,
           outputTokens,
-          durationMs
-        )
+          durationMs,
+          apiErrors,
+          apiRetries
+        ),
+        // `create_sub_session` tool: forward the request/response hook so a child
+        // tool can ask the daemon to spawn a sub-session and (for 'first-turn')
+        // return its result. Omitted → the method reports daemon-only.
+        opts.onCreateSubSession
       );
       const connection = new ClientSideConnection(() => client, channel.stream);
       const info = {
@@ -4066,6 +5515,12 @@ function createAcpSessionBridge(opts) {
           }
           byId.delete(sid);
           telemetry.metrics?.sessionLifecycle("die");
+          emitSessionLifecycle({
+            type: "removed",
+            sessionId: sid,
+            workspaceCwd: sessEntry.workspaceCwd,
+            reason: "channel_closed"
+          });
           info.client.markSessionClosed(sid);
           if (defaultEntry === sessEntry) defaultEntry = void 0;
           sessEntry.events.close();
@@ -4114,10 +5569,12 @@ function createAcpSessionBridge(opts) {
     }
   }
   __name(ensureChannel, "ensureChannel");
-  async function doSpawn(modelServiceId, effectiveScope, requestedClientId, onSessionRegistered) {
+  async function doSpawn(modelServiceId, effectiveScope, approvalMode, requestedClientId, onSessionRegistered, parentSessionId) {
     const ci = await ensureChannel();
     ci.sessionSpawnsInFlight++;
     let sessionRegistered = false;
+    let sessionRemovedDuringInitialization = false;
+    let initializedSessionId;
     let newSessionResp;
     try {
       try {
@@ -4152,13 +5609,58 @@ function createAcpSessionBridge(opts) {
       const entry = createSessionEntry(
         ci,
         newSessionResp.sessionId,
-        boundWorkspace
+        boundWorkspace,
+        void 0,
+        { parentSessionId }
       );
+      initializedSessionId = entry.sessionId;
       sessionRegistered = true;
       onSessionRegistered?.();
       seedSnapshotCaches(entry, newSessionResp);
       const clientId = registerClient(entry, requestedClientId);
-      if (effectiveScope === "single" && !defaultEntry) defaultEntry = entry;
+      let parentSessionPersisted;
+      if (entry.parentSessionId) {
+        const parentDeadline = Date.now() + initTimeoutMs;
+        let lastParentErr;
+        for (let attempt = 1; attempt <= MAX_PARENT_PERSIST_ATTEMPTS; attempt++) {
+          const remaining = parentDeadline - Date.now();
+          if (remaining <= 0) {
+            parentSessionPersisted = false;
+            lastParentErr = "deadline exceeded";
+            break;
+          }
+          try {
+            const parentResult = await Promise.race([
+              withTimeout(
+                entry.connection.extMethod(
+                  SERVE_CONTROL_EXT_METHODS.sessionParent,
+                  {
+                    sessionId: entry.sessionId,
+                    parentSessionId: entry.parentSessionId
+                  }
+                ),
+                remaining,
+                "sessionParent"
+              ),
+              getTransportClosedReject(entry)
+            ]);
+            parentSessionPersisted = parentResult?.persisted === true;
+            break;
+          } catch (err) {
+            lastParentErr = err instanceof Error ? err.message : String(err);
+            const terminal = err instanceof BridgeTimeoutError || err instanceof BridgeChannelClosedError || attempt === MAX_PARENT_PERSIST_ATTEMPTS;
+            if (terminal) {
+              parentSessionPersisted = false;
+              break;
+            }
+          }
+        }
+        if (parentSessionPersisted === false) {
+          writeStderrLine(
+            `qwen serve: parentSessionId for ${entry.sessionId} was not persisted (${lastParentErr ?? "unknown"}) \u2014 the parent link is live-only until restart (reported to the caller via parentSessionPersisted=false)`
+          );
+        }
+      }
       if (modelServiceId) {
         await applyModelServiceId(
           entry,
@@ -4168,22 +5670,51 @@ function createAcpSessionBridge(opts) {
         ).catch(() => {
         });
       }
+      if (approvalMode) {
+        try {
+          await applyApprovalMode(entry, approvalMode, false, clientId);
+        } catch (err) {
+          try {
+            await closeSessionImpl(entry.sessionId, void 0, {
+              reason: "approval_mode_initialization_failed"
+            });
+            sessionRemovedDuringInitialization = true;
+          } catch {
+          }
+          throw err;
+        }
+      }
       if (!byId.has(entry.sessionId)) {
         throw new Error(
-          `Session ${entry.sessionId} died during model-switch initialization`
+          `Session ${entry.sessionId} died during session initialization`
         );
       }
+      if (effectiveScope === "single" && !defaultEntry) defaultEntry = entry;
       return {
         sessionId: entry.sessionId,
         workspaceCwd: entry.workspaceCwd,
         attached: false,
         clientId,
-        createdAt: entry.createdAt
+        createdAt: entry.createdAt,
+        ...entry.parentSessionId ? { parentSessionPersisted: parentSessionPersisted === true } : {}
       };
     } finally {
       ci.sessionSpawnsInFlight = Math.max(0, ci.sessionSpawnsInFlight - 1);
       if (!sessionRegistered) {
         await reapPendingEmptyChannel(ci);
+      } else if (sessionRemovedDuringInitialization && hasNoChannelWork(ci)) {
+        await reapPendingEmptyChannel(ci);
+        if (!ci.isDying) {
+          await startIdleTimer(
+            ci,
+            `approval-mode initialization failure "${initializedSessionId}"`
+          );
+        }
+      } else if (sessionRegistered && hasNoChannelWork(ci) && !ci.isDying) {
+        await startIdleTimer(
+          ci,
+          `session orphaned during initialization "${initializedSessionId}"`
+        );
       }
     }
   }
@@ -4213,41 +5744,157 @@ function createAcpSessionBridge(opts) {
             key: "model.name",
             value: modelId
           },
-          ...originatorClientId ? { originatorClientId } : {}
-        });
+          ...originatorClientId ? { originatorClientId } : {}
+        });
+        succeeded = true;
+      } catch (err) {
+        entry.events.publish({
+          type: "model_switch_failed",
+          data: {
+            sessionId: entry.sessionId,
+            requestedModelId: modelId,
+            error: err instanceof Error ? err.message : String(err)
+          },
+          ...originatorClientId ? { originatorClientId } : {}
+        });
+        throw err;
+      } finally {
+        entry.modelRoundtripInFlight = false;
+        if (succeeded) {
+          void reconcileAfterRoundtrip(entry, "model");
+        } else {
+          writeStderrLine(
+            `[reconcile] session=${entry.sessionId} target=model action=skipped reason=roundtrip_failed`
+          );
+        }
+      }
+    });
+    entry.modelChangeQueue = work.then(
+      () => void 0,
+      () => void 0
+    );
+    return work;
+  }
+  __name(applyModelServiceId, "applyModelServiceId");
+  async function applyApprovalMode(entry, mode, persist, originatorClientId) {
+    if (persist && !persistApprovalMode) {
+      throw new Error(
+        "setSessionApprovalMode called with `persist: true` but no `persistApprovalMode` callback wired in BridgeOptions. runQwenServe wires the production callback; direct embeds and tests must opt in or omit `persist`."
+      );
+    }
+    const approvalWork = entry.approvalModeQueue.then(async () => {
+      entry.approvalModeRoundtripInFlight = true;
+      let succeeded = false;
+      try {
+        const response = await Promise.race([
+          withTimeout(
+            entry.connection.extMethod(
+              SERVE_CONTROL_EXT_METHODS.sessionApprovalMode,
+              { sessionId: entry.sessionId, mode }
+            ),
+            initTimeoutMs,
+            SERVE_CONTROL_EXT_METHODS.sessionApprovalMode
+          ),
+          getTransportClosedReject(entry)
+        ]);
+        if (typeof response.current !== "string" || !KNOWN_APPROVAL_MODES.has(response.current)) {
+          throw new Error(
+            `Agent returned unknown approval mode: ${JSON.stringify(response.current)}`
+          );
+        }
+        let persisted = false;
+        if (persist) {
+          try {
+            await withTimeout(
+              persistApprovalMode?.(boundWorkspace, mode) ?? Promise.resolve(),
+              PERSIST_TIMEOUT_MS,
+              "persistApprovalMode"
+            );
+            persisted = persistApprovalMode !== void 0;
+          } catch (err) {
+            writeStderrLine(
+              `setSessionApprovalMode: persist failed: ${err instanceof Error ? err.message : String(err)}`
+            );
+          }
+        }
+        publishApprovalModeChanged(
+          entry,
+          {
+            previous: response.previous,
+            next: response.current,
+            persisted
+          },
+          originatorClientId
+        );
+        if (persisted) {
+          broadcastWorkspaceEvent(
+            {
+              type: "approval_mode_changed",
+              data: {
+                sessionId: entry.sessionId,
+                previous: response.previous,
+                next: response.current,
+                persisted
+              },
+              ...originatorClientId ? { originatorClientId } : {}
+            },
+            entry.sessionId
+          );
+          for (const peer of byId.values()) {
+            if (peer.sessionId === entry.sessionId) {
+              continue;
+            }
+            peer.currentApprovalMode = response.current;
+          }
+        }
         succeeded = true;
-      } catch (err) {
-        entry.events.publish({
-          type: "model_switch_failed",
-          data: {
-            sessionId: entry.sessionId,
-            requestedModelId: modelId,
-            error: err instanceof Error ? err.message : String(err)
-          },
-          ...originatorClientId ? { originatorClientId } : {}
-        });
-        throw err;
+        return {
+          sessionId: entry.sessionId,
+          mode: response.current,
+          previous: response.previous,
+          persisted
+        };
       } finally {
-        entry.modelRoundtripInFlight = false;
+        entry.approvalModeRoundtripInFlight = false;
         if (succeeded) {
-          void reconcileAfterRoundtrip(entry, "model");
+          void reconcileAfterRoundtrip(entry, "approvalMode");
         } else {
           writeStderrLine(
-            `[reconcile] session=${entry.sessionId} target=model action=skipped reason=roundtrip_failed`
+            `[reconcile] session=${entry.sessionId} target=approvalMode action=skipped reason=roundtrip_failed`
           );
         }
       }
     });
-    entry.modelChangeQueue = work.then(
+    entry.approvalModeQueue = approvalWork.then(
       () => void 0,
       () => void 0
     );
-    return work;
+    try {
+      return await approvalWork;
+    } catch (err) {
+      const data = err?.data;
+      if (data && typeof data === "object" && "errorKind" in data && data.errorKind === "trust_gate") {
+        const rawMessage = err?.message;
+        const message = typeof rawMessage === "string" ? rawMessage : "Trust-gate rejection from ACP child";
+        throw new TrustGateError(message);
+      }
+      throw err;
+    }
   }
-  __name(applyModelServiceId, "applyModelServiceId");
+  __name(applyApprovalMode, "applyApprovalMode");
+  async function applyApprovalModeForAttach(entry, mode, clientId) {
+    try {
+      await applyApprovalMode(entry, mode, false, clientId);
+    } catch (err) {
+      await rollbackAttachRegistration(entry, clientId);
+      throw err;
+    }
+  }
+  __name(applyApprovalModeForAttach, "applyApprovalModeForAttach");
   const cancelPendingForSession = /* @__PURE__ */ __name((sessionId) => {
     permissionMediator.forgetSession(sessionId);
     byId.get(sessionId)?.pendingPermissionIds.clear();
+    byId.get(sessionId)?.pendingInteractions.clear();
   }, "cancelPendingForSession");
   const getTransportClosedReject = /* @__PURE__ */ __name((entry) => {
     if (!entry.transportClosedReject) {
@@ -4529,10 +6176,16 @@ function createAcpSessionBridge(opts) {
       sessionId,
       workspaceCwd,
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...options.parentSessionId ? { parentSessionId: options.parentSessionId } : {},
       channel: ci.channel,
       connection: ci.connection,
       events,
-      artifacts: new SessionArtifactStore({ sessionId, workspaceCwd }),
+      artifacts: new SessionArtifactStore({
+        sessionId,
+        workspaceCwd,
+        persistence: createSessionArtifactPersistence(ci.connection, sessionId)
+      }),
+      recordingDegraded: false,
       promptQueue: Promise.resolve(),
       pendingPromptCount: 0,
       pendingPromptList: [],
@@ -4542,6 +6195,7 @@ function createAcpSessionBridge(opts) {
       modelPublishGeneration: 0,
       approvalModePublishGeneration: 0,
       pendingPermissionIds: /* @__PURE__ */ new Set(),
+      pendingInteractions: /* @__PURE__ */ new Map(),
       clientIds: /* @__PURE__ */ new Map(),
       clientLastSeenAt: /* @__PURE__ */ new Map(),
       attachCount: 0,
@@ -4553,6 +6207,12 @@ function createAcpSessionBridge(opts) {
     byId.set(entry.sessionId, entry);
     touchActivity();
     telemetry.metrics?.sessionLifecycle("spawn");
+    emitSessionLifecycle({
+      type: "registered",
+      sessionId: entry.sessionId,
+      workspaceCwd: entry.workspaceCwd,
+      reason: options.lifecycleReason ?? "spawn"
+    });
     if (options.drainEarlyEvents !== false) {
       ci.client.drainEarlyEvents(entry.sessionId, entry);
     }
@@ -4567,6 +6227,42 @@ function createAcpSessionBridge(opts) {
       });
     }
   }, "publishArtifactChanges");
+  const artifactReseedChanges = /* @__PURE__ */ __name((before, after) => {
+    const beforeById = new Map(
+      before.map((artifact) => [artifact.id, artifact])
+    );
+    const afterById = new Map(after.map((artifact) => [artifact.id, artifact]));
+    const changes = [];
+    for (const artifact of before) {
+      if (!afterById.has(artifact.id)) {
+        changes.push({
+          action: "removed",
+          artifactId: artifact.id,
+          artifact,
+          reason: "eviction"
+        });
+      }
+    }
+    for (const artifact of after) {
+      const previous = beforeById.get(artifact.id);
+      if (!previous) {
+        changes.push({
+          action: "created",
+          artifactId: artifact.id,
+          artifact
+        });
+        continue;
+      }
+      if (!publicArtifactsEqual(previous, artifact)) {
+        changes.push({
+          action: "updated",
+          artifactId: artifact.id,
+          artifact
+        });
+      }
+    }
+    return changes;
+  }, "artifactReseedChanges");
   const makeClientArtifactInput = /* @__PURE__ */ __name((artifact, clientId) => {
     const input = {
       title: artifact.title,
@@ -4579,6 +6275,8 @@ function createAcpSessionBridge(opts) {
       mimeType: artifact.mimeType,
       sizeBytes: artifact.sizeBytes,
       metadata: artifact.metadata,
+      retention: artifact.retention,
+      clientRetained: artifact.clientRetained,
       source: "client"
     };
     if (clientId) {
@@ -4586,6 +6284,31 @@ function createAcpSessionBridge(opts) {
     }
     return input;
   }, "makeClientArtifactInput");
+  function createSessionArtifactPersistence(connection, sessionId) {
+    return {
+      recordEvent: /* @__PURE__ */ __name(async (payload) => {
+        await connection.extMethod(
+          SERVE_CONTROL_EXT_METHODS.sessionArtifactsPersist,
+          {
+            sessionId,
+            kind: "event",
+            payload
+          }
+        );
+      }, "recordEvent"),
+      recordSnapshot: /* @__PURE__ */ __name(async (payload) => {
+        await connection.extMethod(
+          SERVE_CONTROL_EXT_METHODS.sessionArtifactsPersist,
+          {
+            sessionId,
+            kind: "snapshot",
+            payload
+          }
+        );
+      }, "recordSnapshot")
+    };
+  }
+  __name(createSessionArtifactPersistence, "createSessionArtifactPersistence");
   const seedSnapshotCaches = /* @__PURE__ */ __name((entry, resp) => {
     const model = resp.models?.currentModelId;
     if (typeof model === "string" && model.length > 0) {
@@ -4633,16 +6356,55 @@ function createAcpSessionBridge(opts) {
     }
     return { lastEventId: snapshot.lastEventId, ...replayStatus };
   }, "replayFieldsFor");
+  const restoredArtifactSnapshotFromState = /* @__PURE__ */ __name((state) => {
+    const candidate = state.artifactSnapshot;
+    const warnings = [];
+    const snapshot = normalizeSnapshotPayload(candidate, warnings);
+    if (!snapshot) return void 0;
+    const snapshotWarnings = isRecord2(candidate) && Array.isArray(candidate["warnings"]) ? candidate["warnings"].filter(
+      (warning) => typeof warning === "string" && warning.length <= 1e3
+    ).slice(-500) : [];
+    return {
+      v: SESSION_ARTIFACT_PERSISTENCE_VERSION,
+      sessionId: snapshot.sessionId,
+      sequence: snapshot.sequence,
+      artifacts: snapshot.artifacts,
+      ...snapshot.markerArtifacts ? { markerArtifacts: snapshot.markerArtifacts } : {},
+      tombstonedIds: snapshot.tombstonedIds ?? [],
+      stickyEphemeralIds: snapshot.stickyEphemeralIds ?? [],
+      warnings: [...warnings, ...snapshotWarnings]
+    };
+  }, "restoredArtifactSnapshotFromState");
+  const artifactSnapshotUnavailableReason = /* @__PURE__ */ __name((state) => {
+    const reason = state.artifactSnapshotUnavailable;
+    return typeof reason === "string" && reason ? reason : void 0;
+  }, "artifactSnapshotUnavailableReason");
+  const publicRestoreState = /* @__PURE__ */ __name((state) => {
+    const {
+      artifactSnapshot: _artifactSnapshot,
+      artifactSnapshotUnavailable: _artifactSnapshotUnavailable,
+      ...publicState
+    } = state;
+    return publicState;
+  }, "publicRestoreState");
   async function restoreSession(action, req, options = {}) {
     if (shuttingDown) {
       throw new Error("AcpSessionBridge is shutting down");
     }
     const workspaceKey = resolveWorkspaceKey(req.workspaceCwd);
+    if (req.approvalMode !== void 0 && !KNOWN_APPROVAL_MODES.has(req.approvalMode)) {
+      throw new Error(
+        `Invalid approvalMode: ${JSON.stringify(req.approvalMode)}`
+      );
+    }
     const historyReplay = action === "load" ? req.historyReplay ?? "stream" : "stream";
     const existing = byId.get(req.sessionId);
     if (existing) {
       existing.attachCount++;
       const clientId = registerClient(existing, req.clientId);
+      if (req.approvalMode) {
+        await applyApprovalModeForAttach(existing, req.approvalMode, clientId);
+      }
       return {
         sessionId: existing.sessionId,
         workspaceCwd: existing.workspaceCwd,
@@ -4681,10 +6443,14 @@ function createAcpSessionBridge(opts) {
           "the agent child likely crashed during session restore \u2014 retry to restore the session"
         );
       }
+      const clientId = registerClient(entry, req.clientId);
+      if (req.approvalMode) {
+        await applyApprovalModeForAttach(entry, req.approvalMode, clientId);
+      }
       return {
         ...restored,
         attached: true,
-        clientId: registerClient(entry, req.clientId),
+        clientId,
         createdAt: entry.createdAt,
         hasActivePrompt: entry.promptActive
       };
@@ -4794,6 +6560,23 @@ function createAcpSessionBridge(opts) {
         restoreEvents.close();
         racedEntry.attachCount += 1 + coalesceState.count;
         const clientId2 = registerClient(racedEntry, req.clientId);
+        if (req.approvalMode) {
+          try {
+            await applyApprovalMode(
+              racedEntry,
+              req.approvalMode,
+              false,
+              clientId2
+            );
+          } catch (err) {
+            await rollbackAttachRegistration(
+              racedEntry,
+              clientId2,
+              1 + coalesceState.count
+            );
+            throw err;
+          }
+        }
         return {
           sessionId: racedEntry.sessionId,
           workspaceCwd: racedEntry.workspaceCwd,
@@ -4810,22 +6593,48 @@ function createAcpSessionBridge(opts) {
         req.sessionId,
         workspaceKey,
         restoreEvents,
-        { drainEarlyEvents: replayUpdates.length === 0 }
+        {
+          drainEarlyEvents: replayUpdates.length === 0,
+          lifecycleReason: action,
+          // Re-seed the persisted parent lineage the caller recovered from the
+          // transcript, so a restored sub-session's status reports its parent.
+          ...req.parentSessionId ? { parentSessionId: req.parentSessionId } : {}
+        }
       );
       releaseAdmissionOnce();
-      entry.restoreState = state;
+      const restoredArtifactSnapshot = restoredArtifactSnapshotFromState(state);
+      const publicState = publicRestoreState(state);
+      entry.restoreState = publicState;
       if (replayPartial === true) {
         entry.restoreReplayPartial = true;
       }
       if (replayError !== void 0) {
         entry.restoreReplayError = replayError;
       }
-      seedSnapshotCaches(entry, state);
+      seedSnapshotCaches(entry, publicState);
+      const artifactRestoreWarnings = await entry.artifacts.restore(
+        restoredArtifactSnapshot
+      );
+      for (const warning of artifactRestoreWarnings) {
+        writeStderrLine(
+          `[artifacts] session=${entry.sessionId} action=restore_warning warning=${JSON.stringify(
+            warning
+          )}`
+        );
+      }
+      const artifactRestoreFailed = artifactRestoreWarnings.some(
+        (warning) => isArtifactRestoreFailureWarning(warning)
+      );
       if (replayUpdates.length > 0) {
-        await ci.client.seedSessionUpdates(entry, replayUpdates);
+        await ci.client.seedSessionUpdates(entry, replayUpdates, {
+          ingestArtifacts: restoredArtifactSnapshot === void 0 || artifactRestoreFailed
+        });
         ci.client.drainEarlyEvents(entry.sessionId, entry);
       }
       const clientId = registerClient(entry, req.clientId);
+      if (req.approvalMode) {
+        await applyApprovalModeForAttach(entry, req.approvalMode, clientId);
+      }
       entry.attachCount = coalesceState.count;
       registeredEntry = entry;
       return {
@@ -4834,7 +6643,8 @@ function createAcpSessionBridge(opts) {
         attached: false,
         clientId,
         createdAt: entry.createdAt,
-        state,
+        state: publicState,
+        ...artifactRestoreWarnings.length > 0 ? { artifactWarnings: artifactRestoreWarnings } : {},
         hasActivePrompt: entry.promptActive,
         ...replayFieldsFor(entry, action)
       };
@@ -4846,9 +6656,16 @@ function createAcpSessionBridge(opts) {
       if (!registeredEntry) {
         restoreEvents.close();
         let removedRestoreEntry = false;
-        if (byId.get(req.sessionId)?.events === restoreEvents) {
+        const restoreEntry = byId.get(req.sessionId);
+        if (restoreEntry?.events === restoreEvents) {
           byId.delete(req.sessionId);
           ci?.sessionIds.delete(req.sessionId);
+          emitSessionLifecycle({
+            type: "removed",
+            sessionId: req.sessionId,
+            workspaceCwd: restoreEntry.workspaceCwd,
+            reason: "restore_failed"
+          });
           removedRestoreEntry = true;
         }
         if (removedRestoreEntry && ci && hasNoChannelWork(ci)) {
@@ -4909,6 +6726,7 @@ function createAcpSessionBridge(opts) {
     }
     permissionMediator.forgetSession(sessionId);
     entry.pendingPermissionIds.clear();
+    entry.pendingInteractions.clear();
     if (entry.promptActive) {
       entry.promptActive = false;
       activePromptCounter--;
@@ -4916,6 +6734,12 @@ function createAcpSessionBridge(opts) {
     }
     byId.delete(sessionId);
     telemetry.metrics?.sessionLifecycle("close");
+    emitSessionLifecycle({
+      type: "removed",
+      sessionId,
+      workspaceCwd: entry.workspaceCwd,
+      reason
+    });
     ci?.client.markSessionClosed(sessionId);
     try {
       entry.events.publish({
@@ -5039,6 +6863,11 @@ function createAcpSessionBridge(opts) {
         throw new InvalidSessionScopeError(req.sessionScope);
       }
       const effectiveScope = req.sessionScope ?? defaultSessionScope;
+      if (req.approvalMode !== void 0 && !KNOWN_APPROVAL_MODES.has(req.approvalMode)) {
+        throw new Error(
+          `Invalid approvalMode: ${JSON.stringify(req.approvalMode)}`
+        );
+      }
       if (effectiveScope === "single") {
         const existing = defaultEntry;
         if (existing) {
@@ -5053,6 +6882,13 @@ function createAcpSessionBridge(opts) {
             ).catch(() => {
             });
           }
+          if (req.approvalMode) {
+            await applyApprovalModeForAttach(
+              existing,
+              req.approvalMode,
+              clientId
+            );
+          }
           return {
             sessionId: existing.sessionId,
             workspaceCwd: existing.workspaceCwd,
@@ -5083,6 +6919,13 @@ function createAcpSessionBridge(opts) {
             ).catch(() => {
             });
           }
+          if (req.approvalMode) {
+            await applyApprovalModeForAttach(
+              attachedEntry,
+              req.approvalMode,
+              clientId
+            );
+          }
           return {
             ...session,
             attached: true,
@@ -5107,8 +6950,10 @@ function createAcpSessionBridge(opts) {
       const promise = doSpawn(
         req.modelServiceId,
         effectiveScope,
+        req.approvalMode,
         req.clientId,
-        releaseAdmissionOnce
+        releaseAdmissionOnce,
+        req.parentSessionId
       );
       const tracker = effectiveScope === "single" ? workspaceKey : `${workspaceKey}#${randomUUID2()}`;
       inFlightSpawns.set(tracker, promise);
@@ -5249,6 +7094,7 @@ function createAcpSessionBridge(opts) {
                   return copy;
                 })();
                 entry.promptActive = true;
+                delete entry.turnError;
                 activePromptCounter++;
                 entry.sessionLastSeenAt = Date.now();
                 touchActivity();
@@ -5456,7 +7302,8 @@ function createAcpSessionBridge(opts) {
         data: {
           sessionId: entry.sessionId,
           currentModelId: entry.currentModelId ?? null,
-          currentApprovalMode: entry.currentApprovalMode ?? null
+          currentApprovalMode: entry.currentApprovalMode ?? null,
+          recordingDegraded: entry.recordingDegraded
         }
       }), "snapshotFrame");
       async function* withSnapshot() {
@@ -5750,7 +7597,7 @@ function createAcpSessionBridge(opts) {
               const r = res;
               if (r && r.persisted === false) {
                 writeStderrLine(
-                  `qwen serve: displayName for ${sessionId} was not persisted (recording service unavailable)`
+                  `qwen serve: displayName for ${sessionId} was not persisted`
                 );
               }
             }).catch((err) => {
@@ -5771,9 +7618,10 @@ function createAcpSessionBridge(opts) {
       }
       return { displayName: entry.displayName };
     },
-    async getSessionArtifacts(sessionId) {
+    async getSessionArtifacts(sessionId, context) {
       const entry = byId.get(sessionId);
       if (!entry) throw new SessionNotFoundError(sessionId);
+      resolveTrustedClientId(entry, context?.clientId);
       return entry.artifacts.list();
     },
     async addSessionArtifact(sessionId, artifact, context) {
@@ -5781,9 +7629,13 @@ function createAcpSessionBridge(opts) {
       if (!entry) throw new SessionNotFoundError(sessionId);
       const clientId = resolveTrustedClientId(entry, context?.clientId);
       const input = makeClientArtifactInput(artifact, clientId);
-      const result = await entry.artifacts.upsertMany([input], { strict: true });
+      const result = await entry.artifacts.upsertMany([input], {
+        validationStrict: true,
+        persistenceStrict: false
+      });
       publishArtifactChanges(entry, result.changes, clientId);
-      return result;
+      const warnings = [...result.warnings ?? []];
+      return warnings.length > 0 ? { ...result, warnings } : result;
     },
     async removeSessionArtifact(sessionId, artifactId, context) {
       const entry = byId.get(sessionId);
@@ -5791,7 +7643,8 @@ function createAcpSessionBridge(opts) {
       const clientId = resolveTrustedClientId(entry, context?.clientId);
       const result = await entry.artifacts.remove(artifactId, { clientId });
       publishArtifactChanges(entry, result.changes, clientId);
-      return result;
+      const warnings = [...result.warnings ?? []];
+      return warnings.length > 0 ? { ...result, warnings } : result;
     },
     listWorkspaceSessions(workspaceCwd) {
       if (!path3.isAbsolute(workspaceCwd)) return [];
@@ -6076,6 +7929,35 @@ function createAcpSessionBridge(opts) {
         SERVE_STATUS_EXT_METHODS.sessionLspStatus
       );
     },
+    async getSessionTranscriptPage(req) {
+      const info = await ensureChannel();
+      try {
+        const response = await withWorkspaceControl(
+          info,
+          () => withTimeout(
+            Promise.race([
+              info.connection.extMethod(
+                SERVE_STATUS_EXT_METHODS.sessionTranscript,
+                { ...req, cwd: boundWorkspace }
+              ),
+              getChannelClosedReject(info)
+            ]),
+            Math.max(initTimeoutMs, SESSION_TRANSCRIPT_TIMEOUT_MS),
+            SERVE_STATUS_EXT_METHODS.sessionTranscript
+          )
+        );
+        return response;
+      } catch (err) {
+        if (isAcpSessionResourceNotFound(err, req.sessionId)) {
+          throw new SessionNotFoundError(req.sessionId);
+        }
+        throw err;
+      } finally {
+        if (hasNoChannelWork(info)) {
+          await startIdleTimer(info, "session transcript");
+        }
+      }
+    },
     async cancelSessionTask(sessionId, taskId, taskKind) {
       return requestSessionStatus(
         sessionId,
@@ -6155,12 +8037,26 @@ function createAcpSessionBridge(opts) {
             return { refreshed: 0, failed: 0 };
           }
           try {
-            await Promise.race([
-              withTimeout(
-                entry.connection.extMethod(
+            let inFlight = inFlightExtensionRefreshes.get(entry.sessionId);
+            if (!inFlight || inFlight.connection !== entry.connection) {
+              const promise = (async () => {
+                await entry.connection.extMethod(
                   SERVE_CONTROL_EXT_METHODS.workspaceExtensionsRefresh,
                   { sessionId: entry.sessionId }
-                ),
+                );
+              })();
+              inFlight = { connection: entry.connection, promise };
+              inFlightExtensionRefreshes.set(entry.sessionId, inFlight);
+              const clear = /* @__PURE__ */ __name(() => {
+                if (inFlightExtensionRefreshes.get(entry.sessionId) === inFlight) {
+                  inFlightExtensionRefreshes.delete(entry.sessionId);
+                }
+              }, "clear");
+              void promise.then(clear, clear);
+            }
+            await Promise.race([
+              withTimeout(
+                inFlight.promise,
                 3e4,
                 SERVE_CONTROL_EXT_METHODS.workspaceExtensionsRefresh
               ),
@@ -6314,109 +8210,12 @@ function createAcpSessionBridge(opts) {
         entry,
         context?.clientId
       );
-      if (opts2.persist && !persistApprovalMode) {
-        throw new Error(
-          "setSessionApprovalMode called with `persist: true` but no `persistApprovalMode` callback wired in BridgeOptions. runQwenServe wires the production callback; direct embeds and tests must opt in or omit `persist`."
-        );
-      }
-      const approvalWork = entry.approvalModeQueue.then(async () => {
-        entry.approvalModeRoundtripInFlight = true;
-        let succeeded = false;
-        try {
-          const response = await Promise.race([
-            withTimeout(
-              entry.connection.extMethod(
-                SERVE_CONTROL_EXT_METHODS.sessionApprovalMode,
-                { sessionId, mode }
-              ),
-              initTimeoutMs,
-              SERVE_CONTROL_EXT_METHODS.sessionApprovalMode
-            ),
-            getTransportClosedReject(entry)
-          ]);
-          if (typeof response.current !== "string" || !KNOWN_APPROVAL_MODES.has(response.current)) {
-            throw new Error(
-              `Agent returned unknown approval mode: ${JSON.stringify(response.current)}`
-            );
-          }
-          let persisted = false;
-          if (opts2.persist) {
-            try {
-              await withTimeout(
-                persistApprovalMode?.(boundWorkspace, mode) ?? Promise.resolve(),
-                PERSIST_TIMEOUT_MS,
-                "persistApprovalMode"
-              );
-              persisted = persistApprovalMode !== void 0;
-            } catch (err) {
-              writeStderrLine(
-                `setSessionApprovalMode: persist failed: ${err instanceof Error ? err.message : String(err)}`
-              );
-            }
-          }
-          publishApprovalModeChanged(
-            entry,
-            {
-              previous: response.previous,
-              next: response.current,
-              persisted
-            },
-            originatorClientId
-          );
-          if (persisted) {
-            broadcastWorkspaceEvent(
-              {
-                type: "approval_mode_changed",
-                data: {
-                  sessionId: entry.sessionId,
-                  previous: response.previous,
-                  next: response.current,
-                  persisted
-                },
-                ...originatorClientId ? { originatorClientId } : {}
-              },
-              entry.sessionId
-            );
-            for (const peer of byId.values()) {
-              if (peer.sessionId === entry.sessionId) {
-                continue;
-              }
-              peer.currentApprovalMode = response.current;
-            }
-          }
-          succeeded = true;
-          return {
-            sessionId: entry.sessionId,
-            mode: response.current,
-            previous: response.previous,
-            persisted
-          };
-        } finally {
-          entry.approvalModeRoundtripInFlight = false;
-          if (succeeded) {
-            void reconcileAfterRoundtrip(entry, "approvalMode");
-          } else {
-            writeStderrLine(
-              `[reconcile] session=${entry.sessionId} target=approvalMode action=skipped reason=roundtrip_failed`
-            );
-          }
-        }
-      });
-      entry.approvalModeQueue = approvalWork.then(
-        () => void 0,
-        () => void 0
+      return await applyApprovalMode(
+        entry,
+        mode,
+        opts2.persist,
+        originatorClientId
       );
-      try {
-        return await approvalWork;
-      } catch (err) {
-        const data = err?.data;
-        if (data && typeof data === "object" && "errorKind" in data && data.errorKind === "trust_gate") {
-          const rawMessage = err?.message;
-          const message = typeof rawMessage === "string" ? rawMessage : "Trust-gate rejection from ACP child";
-          throw new TrustGateError(message);
-        }
-        throw err;
-      }
     },
     async generateSessionRecap(sessionId, _context) {
       const entry = byId.get(sessionId);
@@ -6769,6 +8568,48 @@ function createAcpSessionBridge(opts) {
       const targetTurnIndex = response["targetTurnIndex"] ?? 0;
       const filesChanged = response["filesChanged"] ?? [];
       const filesFailed = response["filesFailed"] ?? [];
+      const artifactSnapshot = restoredArtifactSnapshotFromState(
+        response
+      );
+      const artifactSnapshotUnavailable = artifactSnapshotUnavailableReason(
+        response
+      );
+      const beforeArtifacts = (await entry.artifacts.list()).artifacts;
+      const shouldRestoreArtifactSnapshot = artifactSnapshot !== void 0 && artifactSnapshotUnavailable === void 0;
+      const artifactRestoreWarnings = artifactSnapshotUnavailable !== void 0 ? [
+        `artifact snapshot rebuild unavailable during rewind: ${artifactSnapshotUnavailable}`
+      ] : shouldRestoreArtifactSnapshot ? await entry.artifacts.restore(artifactSnapshot, {
+        preserveLiveEphemeral: true
+      }) : [];
+      const artifactRestoreFailed = artifactRestoreWarnings.some(
+        isArtifactRestoreFailureWarning
+      );
+      const shouldRecordArtifactSnapshot = shouldRestoreArtifactSnapshot && !artifactRestoreFailed;
+      const artifactSnapshotWarnings = shouldRecordArtifactSnapshot ? await entry.artifacts.recordSnapshot() : [];
+      const artifactWarnings = [
+        ...artifactRestoreWarnings,
+        ...artifactSnapshotWarnings
+      ];
+      for (const warning of artifactRestoreWarnings) {
+        writeStderrLine(
+          `[artifacts] session=${entry.sessionId} action=rewind_restore_warning warning=${JSON.stringify(
+            warning
+          )}`
+        );
+      }
+      for (const warning of artifactSnapshotWarnings) {
+        writeStderrLine(
+          `[artifacts] session=${entry.sessionId} action=rewind_snapshot_warning warning=${JSON.stringify(
+            warning
+          )}`
+        );
+      }
+      const afterArtifacts = (await entry.artifacts.list()).artifacts;
+      publishArtifactChanges(
+        entry,
+        artifactReseedChanges(beforeArtifacts, afterArtifacts),
+        originatorClientId
+      );
       try {
         entry.events.publish({
           type: "session_rewound",
@@ -6777,7 +8618,8 @@ function createAcpSessionBridge(opts) {
             promptId: req.promptId,
             targetTurnIndex,
             filesChanged,
-            filesFailed
+            filesFailed,
+            ...artifactWarnings.length > 0 ? { warnings: artifactWarnings } : {}
           },
           ...originatorClientId ? { originatorClientId } : {}
         });
@@ -6787,7 +8629,8 @@ function createAcpSessionBridge(opts) {
         rewound: filesFailed.length === 0,
         targetTurnIndex,
         filesChanged,
-        filesFailed
+        filesFailed,
+        ...artifactWarnings.length > 0 ? { warnings: artifactWarnings } : {}
       };
     },
     async manageMcpServer(serverName, action, originatorClientId) {
@@ -6915,6 +8758,7 @@ function createAcpSessionBridge(opts) {
       }
       permissionMediator.forgetSession(sessionId);
       entry.pendingPermissionIds.clear();
+      entry.pendingInteractions.clear();
       if (entry.promptActive) {
         entry.promptActive = false;
         activePromptCounter--;
@@ -6923,6 +8767,12 @@ function createAcpSessionBridge(opts) {
       if (defaultEntry === entry) defaultEntry = void 0;
       byId.delete(sessionId);
       telemetry.metrics?.sessionLifecycle("die");
+      emitSessionLifecycle({
+        type: "removed",
+        sessionId,
+        workspaceCwd: entry.workspaceCwd,
+        reason: "killed"
+      });
       const ci = channelInfoForEntry(entry);
       if (!ci) {
         writeStderrLine(
@@ -6972,8 +8822,17 @@ function createAcpSessionBridge(opts) {
       cancelIdleTimer();
       stopSessionReaper();
       const channels = Array.from(aliveChannels);
+      const entries = Array.from(byId.values());
       defaultEntry = void 0;
       byId.clear();
+      for (const entry of entries) {
+        emitSessionLifecycle({
+          type: "removed",
+          sessionId: entry.sessionId,
+          workspaceCwd: entry.workspaceCwd,
+          reason: "kill_all"
+        });
+      }
       for (const info of channels) {
         try {
           info.channel.killSync();
@@ -6981,53 +8840,71 @@ function createAcpSessionBridge(opts) {
         }
       }
     },
-    async shutdown() {
-      shuttingDown = true;
-      cancelIdleTimer();
-      stopSessionReaper();
-      const entries = Array.from(byId.values());
-      const channels = Array.from(aliveChannels);
-      for (const ci of channels) ci.isDying = true;
-      for (const e of entries) {
-        permissionMediator.forgetSession(e.sessionId);
-        e.pendingPermissionIds.clear();
-      }
-      defaultEntry = void 0;
-      byId.clear();
-      for (const e of entries) {
-        telemetry.metrics?.sessionLifecycle("die");
-        try {
-          e.events.publish({
-            type: "session_died",
-            data: { sessionId: e.sessionId, reason: "daemon_shutdown" }
+    shutdown(options) {
+      if (shutdownPromise) return shutdownPromise;
+      const shutdownReason = options?.reason ?? "daemon_shutdown";
+      let resolveShutdown;
+      let rejectShutdown;
+      shutdownPromise = new Promise((resolve2, reject) => {
+        resolveShutdown = resolve2;
+        rejectShutdown = reject;
+      });
+      void (async () => {
+        shuttingDown = true;
+        cancelIdleTimer();
+        stopSessionReaper();
+        const entries = Array.from(byId.values());
+        const channels = Array.from(aliveChannels);
+        for (const ci of channels) ci.isDying = true;
+        for (const e of entries) {
+          permissionMediator.forgetSession(e.sessionId);
+          e.pendingPermissionIds.clear();
+          e.pendingInteractions.clear();
+        }
+        defaultEntry = void 0;
+        byId.clear();
+        for (const e of entries) {
+          telemetry.metrics?.sessionLifecycle("die");
+          emitSessionLifecycle({
+            type: "removed",
+            sessionId: e.sessionId,
+            workspaceCwd: e.workspaceCwd,
+            reason: shutdownReason
           });
-        } catch {
+          try {
+            e.events.publish({
+              type: "session_died",
+              data: { sessionId: e.sessionId, reason: shutdownReason }
+            });
+          } catch {
+          }
+          e.events.close();
         }
-        e.events.close();
-      }
-      const inFlightSessionAwaits = Array.from(inFlightSpawns.values()).map(
-        (p) => p.then(
-          () => void 0,
-          () => void 0
-        )
-      );
-      const inFlightRestoreAwaits = Array.from(inFlightRestores.values()).map(
-        (restore) => restore.promise.then(
+        const inFlightSessionAwaits = Array.from(inFlightSpawns.values()).map(
+          (p) => p.then(
+            () => void 0,
+            () => void 0
+          )
+        );
+        const inFlightRestoreAwaits = Array.from(inFlightRestores.values()).map(
+          (restore) => restore.promise.then(
+            () => void 0,
+            () => void 0
+          )
+        );
+        const inFlightChannelAwait = inFlightChannelSpawn ? inFlightChannelSpawn.then(
           () => void 0,
           () => void 0
-        )
-      );
-      const inFlightChannelAwait = inFlightChannelSpawn ? inFlightChannelSpawn.then(
-        () => void 0,
-        () => void 0
-      ) : Promise.resolve();
-      await Promise.all([
-        ...channels.map((ci) => ci.channel.kill().catch(() => {
-        })),
-        ...inFlightSessionAwaits,
-        ...inFlightRestoreAwaits,
-        inFlightChannelAwait
-      ]);
+        ) : Promise.resolve();
+        await Promise.all([
+          ...channels.map((ci) => ci.channel.kill().catch(() => {
+          })),
+          ...inFlightSessionAwaits,
+          ...inFlightRestoreAwaits,
+          inFlightChannelAwait
+        ]);
+      })().then(resolveShutdown, rejectShutdown);
+      return shutdownPromise;
     },
     async preheat() {
       if (shuttingDown) return;
@@ -7057,6 +8934,7 @@ var createHttpAcpBridge = createAcpSessionBridge;
 
 export {
   SessionArtifactValidationError,
+  SessionArtifactAuthorizationError,
   extractErrorMessage,
   extractErrorCode,
   classifyTurnErrorKind,