@qwen-code/qwen-code 0.19.7 → 0.19.8-nightly.20260710.205430235

package/chunks/{chunk-U4FRHCLA.js → chunk-DDKUYKHA.js}

@@ -22,7 +22,7 @@ import {
   SessionShellDisabledError,
   WorkspaceMismatchError,
   isNotCurrentlyGeneratingCancelError
-} from "./chunk-B34OV7K2.js";
+} from "./chunk-GGQQA4JW.js";
 import {
   LOAD_REPLAY_BULK_MODE,
   LOAD_REPLAY_META_KEY,
@@ -36,16 +36,15 @@ import {
 import {
   DEFAULT_RING_SIZE,
   EVENT_SCHEMA_VERSION,
-  EventBus
-} from "./chunk-G7ZG7CA6.js";
+  EventBus,
+  serializedBridgeEventByteLength
+} from "./chunk-3UP777ZS.js";
 import {
-  ClientSideConnection,
-  PROTOCOL_VERSION,
-  RequestError
-} from "./chunk-VRDMOSQS.js";
+  normalizeCompactedReplayMaxBytes
+} from "./chunk-GLE2YUPU.js";
 import {
   defaultSpawnChannelFactory
-} from "./chunk-AJBEAUIS.js";
+} from "./chunk-MG2TNCRX.js";
 import {
   BridgeChannelClosedError,
   BridgeTimeoutError,
@@ -54,15 +53,28 @@ import {
   STATUS_SCHEMA_VERSION,
   createIdleWorkspaceExtensionsStatus,
   createIdleWorkspaceHooksStatus
-} from "./chunk-JF7DFPQ5.js";
+} from "./chunk-I3MBKL6Z.js";
+import {
+  ClientSideConnection,
+  PROTOCOL_VERSION,
+  RequestError
+} from "./chunk-VRDMOSQS.js";
 import {
+  SESSION_ARTIFACT_PERSISTENCE_VERSION,
   ShellExecutionService,
-  TrustGateError
-} from "./chunk-YEGT55NW.js";
+  TrustGateError,
+  WORKSPACE_CONTENT_MTIME_MS_METADATA_KEY,
+  WORKSPACE_CONTENT_SHA256_METADATA_KEY,
+  isPrototypeMetadataKey,
+  isReservedWorkspaceMetadataKey,
+  metadataBudgetBytes,
+  normalizeSnapshotPayload,
+  stableSessionArtifactId
+} from "./chunk-ZDAZSR2O.js";
 import {
   DAEMON_TRACEPARENT_META_KEY,
   DAEMON_TRACESTATE_META_KEY
-} from "./chunk-GMOWQOQQ.js";
+} from "./chunk-5ZVIYNLN.js";
 import {
   init_esbuild_shims
 } from "./chunk-A4BMJM77.js";
@@ -79,6 +91,7 @@ import * as path3 from "node:path";
 init_esbuild_shims();
 var TURN_BOUNDARY_TYPES = /* @__PURE__ */ new Set(["turn_complete", "turn_error"]);
 var TRANSIENT_TYPES = /* @__PURE__ */ new Set([
+  "history_truncated",
   "slow_client_warning",
   "client_evicted",
   "replay_complete",
@@ -88,17 +101,28 @@ var LATEST_WINS_UPDATES = /* @__PURE__ */ new Set([
   "available_commands_update",
   "current_mode_update"
 ]);
+var REPLAY_SEGMENT_COMPACT_THRESHOLD = 64;
 var TurnBoundaryCompactionEngine = class {
   static {
     __name(this, "TurnBoundaryCompactionEngine");
   }
-  compactedTurns = [];
+  maxReplayBytes;
+  onReplayWindowEviction;
+  replaySegments = [];
+  replaySegmentStart = 0;
+  replayBytes = 0;
   liveJournal = [];
   lastEventId = 0;
   closed = false;
+  truncatedEvents = 0;
+  truncatedTurns = 0;
   slots = [];
   toolSlotIndex = /* @__PURE__ */ new Map();
   textSlotIndex = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    this.maxReplayBytes = normalizeCompactedReplayMaxBytes(opts.maxReplayBytes);
+    this.onReplayWindowEviction = opts.onReplayWindowEviction;
+  }
   ingest(event) {
     if (this.closed) return;
     if (event.id !== void 0) {
@@ -117,16 +141,39 @@ var TurnBoundaryCompactionEngine = class {
     this.slots.push({ kind: "misc", event });
   }
   snapshot() {
+    const compactedTurns = this.flattenReplaySegments();
+    if (this.truncatedEvents > 0) {
+      compactedTurns.unshift(
+        this.makeHistoryTruncatedEvent(compactedTurns.length)
+      );
+    }
     return {
-      compactedTurns: this.compactedTurns.slice(),
+      compactedTurns,
       liveJournal: this.liveJournal.slice(),
       lastEventId: this.lastEventId
     };
   }
   seed(snapshot) {
     if (this.closed) return;
-    this.compactedTurns = snapshot.compactedTurns.slice();
+    this.resetReplayWindow();
     this.lastEventId = snapshot.lastEventId;
+    for (const event of snapshot.compactedTurns) {
+      if (TRANSIENT_TYPES.has(event.type)) continue;
+      this.addReplaySegment([event], 0);
+    }
+    this.liveJournal = [];
+    this.slots = [];
+    this.toolSlotIndex.clear();
+    this.textSlotIndex.clear();
+  }
+  seedReplayEvents(events) {
+    if (this.closed) return;
+    this.resetReplayWindow();
+    for (const event of events) {
+      this.recordLastEventId(event);
+      if (TRANSIENT_TYPES.has(event.type)) continue;
+      this.addReplaySegment([event], 0);
+    }
     this.liveJournal = [];
     this.slots = [];
     this.toolSlotIndex.clear();
@@ -135,7 +182,7 @@ var TurnBoundaryCompactionEngine = class {
   close() {
     if (this.closed) return;
     this.closed = true;
-    this.compactedTurns = [];
+    this.resetReplayWindow();
     this.liveJournal = [];
     this.slots = [];
     this.toolSlotIndex.clear();
@@ -272,12 +319,94 @@ var TurnBoundaryCompactionEngine = class {
       }
     }
     compacted.push(boundaryEvent);
-    this.compactedTurns.push(...compacted);
+    this.addReplaySegment(compacted, 1);
     this.liveJournal = [];
     this.slots = [];
     this.toolSlotIndex.clear();
     this.textSlotIndex.clear();
   }
+  recordLastEventId(event) {
+    if (event.id !== void 0) {
+      this.lastEventId = event.id;
+    }
+  }
+  addReplaySegment(events, turnCount) {
+    if (events.length === 0) return;
+    const bytes = events.reduce(
+      (sum, event) => sum + serializedBridgeEventByteLength(event),
+      0
+    );
+    this.replaySegments.push({ events: events.slice(), bytes, turnCount });
+    this.replayBytes += bytes;
+    this.enforceReplayWindow();
+  }
+  enforceReplayWindow() {
+    let droppedSegmentCount = 0;
+    let droppedBytes = 0;
+    let droppedEvents = 0;
+    let droppedTurns = 0;
+    while (this.replayBytes > this.maxReplayBytes && this.activeReplaySegmentCount() > 1) {
+      const dropped = this.replaySegments[this.replaySegmentStart];
+      this.replaySegmentStart += 1;
+      droppedSegmentCount += 1;
+      droppedBytes += dropped.bytes;
+      droppedEvents += dropped.events.length;
+      droppedTurns += dropped.turnCount;
+      this.replayBytes -= dropped.bytes;
+      this.truncatedEvents += dropped.events.length;
+      this.truncatedTurns += dropped.turnCount;
+    }
+    if (droppedSegmentCount > 0) {
+      this.compactReplaySegmentQueueIfNeeded();
+      this.notifyReplayWindowEviction({
+        droppedBytes,
+        droppedEvents,
+        droppedSegments: droppedSegmentCount,
+        droppedTurns,
+        maxBytes: this.maxReplayBytes,
+        retainedBytes: this.replayBytes,
+        retainedEvents: this.flattenReplaySegments().length
+      });
+    }
+  }
+  flattenReplaySegments() {
+    return this.replaySegments.slice(this.replaySegmentStart).flatMap((segment) => segment.events);
+  }
+  activeReplaySegmentCount() {
+    return this.replaySegments.length - this.replaySegmentStart;
+  }
+  compactReplaySegmentQueueIfNeeded() {
+    if (this.replaySegmentStart < REPLAY_SEGMENT_COMPACT_THRESHOLD) return;
+    this.replaySegments.splice(0, this.replaySegmentStart);
+    this.replaySegmentStart = 0;
+  }
+  notifyReplayWindowEviction(eviction) {
+    try {
+      this.onReplayWindowEviction?.(eviction);
+    } catch {
+    }
+  }
+  makeHistoryTruncatedEvent(retainedEvents) {
+    return {
+      v: EVENT_SCHEMA_VERSION,
+      type: "history_truncated",
+      data: {
+        reason: "replay_window_exceeded",
+        truncatedEvents: this.truncatedEvents,
+        retainedEvents,
+        maxBytes: this.maxReplayBytes,
+        ...this.truncatedTurns > 0 ? { truncatedTurns: this.truncatedTurns } : {},
+        fullTranscriptAvailable: false
+      }
+    };
+  }
+  resetReplayWindow() {
+    this.replaySegments = [];
+    this.replaySegmentStart = 0;
+    this.replayBytes = 0;
+    this.truncatedEvents = 0;
+    this.truncatedTurns = 0;
+  }
 };
 function makeMergedSessionUpdateEvent(sessionUpdate, text, eventId, meta, envelopeMeta) {
   return {
@@ -362,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();
 
@@ -1059,7 +1193,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");
@@ -1202,7 +1337,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;
@@ -1214,6 +1349,7 @@ var BridgeClient = class {
     this.clientMcpSender = clientMcpSender;
     this.ownsSession = ownsSession;
     this.onTokenUsage = onTokenUsage;
+    this.onCreateSubSession = onCreateSubSession;
   }
   static {
     __name(this, "BridgeClient");
@@ -1337,7 +1473,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) {
@@ -1346,7 +1482,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
@@ -1435,9 +1571,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
@@ -1450,6 +1589,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);
     }
@@ -1525,6 +1667,67 @@ 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 } : {}
+    };
+  }
   /**
    * Handle child->bridge ACP `extNotification` calls. Recognized methods are
    * `qwen/notify/session/model-update`,
@@ -1534,8 +1737,8 @@ var BridgeClient = class {
    * `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") {
@@ -2118,7 +2321,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,
@@ -2127,6 +2330,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);
@@ -2138,6 +2353,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");
@@ -2145,15 +2374,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;
@@ -2166,13 +2406,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(
@@ -2183,7 +2440,7 @@ var SessionArtifactStore = class {
             )
           );
         } catch (error) {
-          if (options.strict) {
+          if (validationStrict) {
             throw error;
           }
           const message = error instanceof Error ? error.message : String(error);
@@ -2195,39 +2452,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) {
@@ -2235,7 +2593,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;
@@ -2271,27 +2629,552 @@ 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 } : {}
       };
     });
   }
+  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 recordSnapshot() {
+    const persistence = this.persistence;
+    if (!persistence) {
+      return [
+        "artifact persistence unavailable; restored artifacts not snapshotted"
+      ];
+    }
+    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"];
+      }
+    });
+  }
+  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;
+    }
+  }
+  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(
@@ -2300,7 +3183,21 @@ var SessionArtifactStore = class {
     );
     return result;
   }
-  async normalizeInput(input, receivedSeq, trustedPublisherFromCaller) {
+  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");
     }
@@ -2319,7 +3216,10 @@ var SessionArtifactStore = class {
       );
     }
     const trustedPublisher = trustedPublisherFromCaller;
-    const workspacePath = input.workspacePath ? normalizeWorkspacePath(input.workspacePath, this.workspaceCwd) : void 0;
+    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, {
@@ -2335,14 +3235,26 @@ var SessionArtifactStore = class {
       url,
       trustedPublisher
     });
-    const metadata = normalizeMetadata(input.metadata);
-    const workspaceStatus = workspacePath ? await this.getInitialWorkspaceStatus(workspacePath) : void 0;
+    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 })
     );
@@ -2353,11 +3265,12 @@ var SessionArtifactStore = class {
       managedId,
       url
     });
-    const id = stableArtifactId(this.sessionId, identityKey);
+    const id = stableSessionArtifactId(this.sessionId, identityKey);
     return {
       id,
       identityKey,
       receivedSeq,
+      retentionExplicit: input.retention !== void 0,
       retentionSource: source,
       trustedPublisher,
       kind,
@@ -2371,9 +3284,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),
@@ -2387,6 +3303,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));
@@ -2399,12 +3325,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);
@@ -2420,16 +3358,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) {
@@ -2458,7 +3403,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;
@@ -2486,10 +3442,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;
@@ -2538,7 +3501,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
     };
@@ -2552,6 +3520,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
   };
 }
@@ -2571,9 +3541,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,
@@ -2585,6 +3560,7 @@ function mergeArtifact(existing, incoming) {
     next.title = incoming.title;
     next.description = incoming.description;
     delete next.workspacePath;
+    delete next.hideWorkspacePath;
   }
   const changed = !publicArtifactsEqual(
     toPublicArtifact(existing),
@@ -2596,8 +3572,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) {
@@ -2619,6 +3599,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;
@@ -2626,7 +3624,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;
     }
@@ -2644,7 +3645,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) {
@@ -2700,6 +3701,7 @@ function removePriorChange(changes, artifactId) {
 }
 __name(removePriorChange, "removePriorChange");
 function toPublicArtifact(artifact) {
+  const hideWorkspacePath = "hideWorkspacePath" in artifact && artifact.hideWorkspacePath === true;
   const {
     id,
     kind,
@@ -2714,38 +3716,224 @@ function toPublicArtifact(artifact) {
     mimeType,
     sizeBytes,
     metadata,
+    retention,
+    restoreState,
+    persistenceWarning,
+    persistedAt,
     clientRetained,
     createdAt,
     updatedAt,
     toolCallId,
     toolName,
-    hookEventName,
-    clientId
+    hookEventName
   } = artifact;
   return {
-    id,
-    kind,
-    storage,
-    source,
-    status,
-    title,
-    ...description ? { description } : {},
-    ...workspacePath ? { workspacePath } : {},
-    ...managedId ? { managedId } : {},
-    ...url ? { url } : {},
-    ...mimeType ? { mimeType } : {},
-    ...sizeBytes !== void 0 ? { sizeBytes } : {},
-    ...metadata ? { metadata } : {},
-    clientRetained,
-    createdAt,
-    updatedAt,
-    ...toolCallId ? { toolCallId } : {},
-    ...toolName ? { toolName } : {},
-    ...hookEventName ? { hookEventName } : {},
-    ...clientId ? { clientId } : {}
+    id,
+    kind,
+    storage,
+    source,
+    status,
+    title,
+    ...description ? { description } : {},
+    ...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 } : {}
+  };
+}
+__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(toPublicArtifact, "toPublicArtifact");
+__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(
@@ -2839,10 +4027,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);
 }
@@ -2956,6 +4140,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",
@@ -2965,7 +4155,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;
   }
@@ -2977,6 +4224,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",
@@ -2995,6 +4248,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",
@@ -3013,12 +4272,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"
@@ -3027,6 +4292,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(
@@ -3052,21 +4336,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;
     }
@@ -3077,6 +4423,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);
@@ -3109,6 +4490,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);
 }
@@ -3276,6 +4664,18 @@ function isBridgeAutoMemoryTopic(value) {
   return value === "user" || value === "feedback" || value === "project" || value === "reference";
 }
 __name(isBridgeAutoMemoryTopic, "isBridgeAutoMemoryTopic");
+function touchedScopesFromTopics(topics) {
+  const scopes = /* @__PURE__ */ new Set();
+  for (const topic of topics) {
+    scopes.add(topic === "user" || topic === "feedback" ? "user" : "project");
+  }
+  return ["user", "project"].filter((scope) => scopes.has(scope));
+}
+__name(touchedScopesFromTopics, "touchedScopesFromTopics");
+function isBridgeMemoryScope(value) {
+  return value === "user" || value === "project";
+}
+__name(isBridgeMemoryScope, "isBridgeMemoryScope");
 function parseWorkspaceMemoryForgetMatch(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return null;
@@ -3299,14 +4699,17 @@ function parseWorkspaceMemoryForgetResult(response) {
   const summary = record["summary"];
   const removedEntries = record["removedEntries"];
   const touchedTopics = record["touchedTopics"];
+  const touchedScopes = record["touchedScopes"];
   const parsedRemovedEntries = Array.isArray(removedEntries) ? removedEntries.map(parseWorkspaceMemoryForgetMatch) : [];
-  if (summary !== void 0 && typeof summary !== "string" || !Array.isArray(removedEntries) || parsedRemovedEntries.some((entry) => entry === null) || !Array.isArray(touchedTopics) || !touchedTopics.every(isBridgeAutoMemoryTopic)) {
+  if (summary !== void 0 && typeof summary !== "string" || !Array.isArray(removedEntries) || parsedRemovedEntries.some((entry) => entry === null) || !Array.isArray(touchedTopics) || !touchedTopics.every(isBridgeAutoMemoryTopic) || touchedScopes !== void 0 && (!Array.isArray(touchedScopes) || !touchedScopes.every(isBridgeMemoryScope))) {
     throw new Error("Malformed workspace memory forget response");
   }
+  const parsedTouchedTopics = touchedTopics;
   return {
     ...summary === void 0 ? {} : { summary },
     removedEntries: parsedRemovedEntries,
-    touchedTopics
+    touchedTopics: parsedTouchedTopics,
+    touchedScopes: touchedScopes === void 0 ? touchedScopesFromTopics(parsedTouchedTopics) : touchedScopes
   };
 }
 __name(parseWorkspaceMemoryForgetResult, "parseWorkspaceMemoryForgetResult");
@@ -3523,6 +4926,27 @@ function createAcpSessionBridge(opts) {
   } else {
     maxSessions = opts.maxSessions;
   }
+  const reserveFreshSession = /* @__PURE__ */ __name((context) => opts.freshSessionAdmission?.(context), "reserveFreshSession");
+  const releaseFreshSessionReservation = /* @__PURE__ */ __name((reservation) => {
+    if (!reservation) return;
+    try {
+      reservation.release();
+    } catch (err) {
+      opts.onDiagnosticLine?.(
+        `qwen serve: fresh session admission release failed: ${err instanceof Error ? err.message : String(err)}`,
+        "warn"
+      );
+    }
+  }, "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'.`
@@ -3534,6 +4958,9 @@ function createAcpSessionBridge(opts) {
       `Invalid eventRingSize: ${opts.eventRingSize}. Must be a positive integer in [1, ${MAX_EVENT_RING_SIZE}].`
     );
   }
+  const compactedReplayMaxBytes = normalizeCompactedReplayMaxBytes(
+    opts.compactedReplayMaxBytes
+  );
   const channelFactory = opts.channelFactory ?? defaultSpawnChannelFactory;
   const childEnvOverrides = opts.childEnvOverrides ? Object.freeze({ ...opts.childEnvOverrides }) : Object.freeze({});
   const initTimeoutMs = opts.initializeTimeoutMs ?? DEFAULT_INIT_TIMEOUT_MS;
@@ -3850,7 +5277,11 @@ function createAcpSessionBridge(opts) {
           inputTokens,
           outputTokens,
           durationMs
-        )
+        ),
+        // `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 = {
@@ -3915,6 +5346,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();
@@ -3963,7 +5400,7 @@ function createAcpSessionBridge(opts) {
     }
   }
   __name(ensureChannel, "ensureChannel");
-  async function doSpawn(modelServiceId, effectiveScope, requestedClientId) {
+  async function doSpawn(modelServiceId, effectiveScope, requestedClientId, onSessionRegistered) {
     const ci = await ensureChannel();
     ci.sessionSpawnsInFlight++;
     let sessionRegistered = false;
@@ -4004,6 +5441,7 @@ function createAcpSessionBridge(opts) {
         boundWorkspace
       );
       sessionRegistered = true;
+      onSessionRegistered?.();
       seedSnapshotCaches(entry, newSessionResp);
       const clientId = registerClient(entry, requestedClientId);
       if (effectiveScope === "single" && !defaultEntry) defaultEntry = entry;
@@ -4280,7 +5718,18 @@ function createAcpSessionBridge(opts) {
       );
     }
   }, "broadcastWorkspaceEvent");
-  const createSessionEventBus = /* @__PURE__ */ __name(() => new EventBus(eventRingSize, void 0, new TurnBoundaryCompactionEngine()), "createSessionEventBus");
+  const createSessionEventBus = /* @__PURE__ */ __name(() => new EventBus(
+    eventRingSize,
+    void 0,
+    new TurnBoundaryCompactionEngine({
+      maxReplayBytes: compactedReplayMaxBytes,
+      onReplayWindowEviction: /* @__PURE__ */ __name((eviction) => {
+        teeServeDebugLine(
+          `replay window evicted ${JSON.stringify(eviction)}`
+        );
+      }, "onReplayWindowEviction")
+    })
+  ), "createSessionEventBus");
   const publishModelSwitched = /* @__PURE__ */ __name((entry, modelId, originatorClientId) => {
     entry.currentModelId = modelId;
     entry.modelPublishGeneration++;
@@ -4369,7 +5818,11 @@ function createAcpSessionBridge(opts) {
       channel: ci.channel,
       connection: ci.connection,
       events,
-      artifacts: new SessionArtifactStore({ sessionId, workspaceCwd }),
+      artifacts: new SessionArtifactStore({
+        sessionId,
+        workspaceCwd,
+        persistence: createSessionArtifactPersistence(ci.connection, sessionId)
+      }),
       promptQueue: Promise.resolve(),
       pendingPromptCount: 0,
       pendingPromptList: [],
@@ -4390,6 +5843,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);
     }
@@ -4404,6 +5863,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,
@@ -4416,6 +5911,8 @@ function createAcpSessionBridge(opts) {
       mimeType: artifact.mimeType,
       sizeBytes: artifact.sizeBytes,
       metadata: artifact.metadata,
+      retention: artifact.retention,
+      clientRetained: artifact.clientRetained,
       source: "client"
     };
     if (clientId) {
@@ -4423,6 +5920,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) {
@@ -4470,7 +5992,38 @@ function createAcpSessionBridge(opts) {
     }
     return { lastEventId: snapshot.lastEventId, ...replayStatus };
   }, "replayFieldsFor");
-  async function restoreSession(action, req) {
+  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");
     }
@@ -4533,6 +6086,17 @@ function createAcpSessionBridge(opts) {
     let registeredEntry;
     let ci;
     const coalesceState = { count: 0 };
+    const admission = options.skipFreshSessionAdmission === true ? void 0 : reserveFreshSession({
+      operation: action,
+      workspaceCwd: workspaceKey,
+      sessionId: req.sessionId
+    });
+    let admissionReleased = false;
+    const releaseAdmissionOnce = /* @__PURE__ */ __name(() => {
+      if (admissionReleased) return;
+      admissionReleased = true;
+      releaseFreshSessionReservation(admission);
+    }, "releaseAdmissionOnce");
     const promise = (async () => {
       pendingRestoreEvents.set(req.sessionId, restoreEvents);
       ci = await ensureChannel();
@@ -4636,18 +6200,39 @@ function createAcpSessionBridge(opts) {
         req.sessionId,
         workspaceKey,
         restoreEvents,
-        { drainEarlyEvents: replayUpdates.length === 0 }
+        {
+          drainEarlyEvents: replayUpdates.length === 0,
+          lifecycleReason: action
+        }
       );
-      entry.restoreState = state;
+      releaseAdmissionOnce();
+      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);
@@ -4659,20 +6244,29 @@ function createAcpSessionBridge(opts) {
         attached: false,
         clientId,
         createdAt: entry.createdAt,
-        state,
+        state: publicState,
+        ...artifactRestoreWarnings.length > 0 ? { artifactWarnings: artifactRestoreWarnings } : {},
         hasActivePrompt: entry.promptActive,
         ...replayFieldsFor(entry, action)
       };
     })().finally(async () => {
+      releaseAdmissionOnce();
       ci?.pendingRestoreIds.delete(req.sessionId);
       ci?.client.clearRestoreInFlight(req.sessionId);
       pendingRestoreEvents.delete(req.sessionId);
       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)) {
@@ -4740,6 +6334,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({
@@ -4788,6 +6388,7 @@ function createAcpSessionBridge(opts) {
           maxSessions: maxSessions === Infinity ? null : maxSessions,
           maxPendingPromptsPerSession: maxPendingPromptsPerSession === Infinity ? null : maxPendingPromptsPerSession,
           eventRingSize,
+          compactedReplayMaxBytes,
           channelIdleTimeoutMs: resolvedChannelIdleTimeoutMs(),
           sessionIdleTimeoutMs
         },
@@ -4917,12 +6518,28 @@ function createAcpSessionBridge(opts) {
       if (byId.size + inFlightSpawns.size + inFlightRestores.size >= maxSessions) {
         throw new SessionLimitExceededError(maxSessions);
       }
-      const promise = doSpawn(req.modelServiceId, effectiveScope, req.clientId);
+      const admission = reserveFreshSession({
+        operation: "spawn",
+        workspaceCwd: workspaceKey
+      });
+      let admissionReleased = false;
+      const releaseAdmissionOnce = /* @__PURE__ */ __name(() => {
+        if (admissionReleased) return;
+        admissionReleased = true;
+        releaseFreshSessionReservation(admission);
+      }, "releaseAdmissionOnce");
+      const promise = doSpawn(
+        req.modelServiceId,
+        effectiveScope,
+        req.clientId,
+        releaseAdmissionOnce
+      );
       const tracker = effectiveScope === "single" ? workspaceKey : `${workspaceKey}#${randomUUID2()}`;
       inFlightSpawns.set(tracker, promise);
       try {
         return await promise;
       } finally {
+        releaseAdmissionOnce();
         inFlightSpawns.delete(tracker);
       }
     },
@@ -5379,67 +6996,89 @@ function createAcpSessionBridge(opts) {
         if (byId.size + inFlightSpawns.size + inFlightRestores.size >= maxSessions) {
           throw new SessionLimitExceededError(maxSessions);
         }
-        const ci = await ensureChannel();
-        const result = await withTimeout(
-          ci.connection.extMethod(SERVE_CONTROL_EXT_METHODS.sessionBranch, {
-            sessionId,
-            cwd: boundWorkspace,
-            name: req.name
-          }),
-          initTimeoutMs,
-          "branchSession"
-        );
-        if (!result || typeof result.newSessionId !== "string") {
-          throw new Error(
-            `branchSession: agent returned invalid response: ${JSON.stringify(result)}`
-          );
-        }
-        const rawBranchName = result.displayName ?? result.title;
-        const branchDisplayName = typeof rawBranchName === "string" ? rawBranchName : result.newSessionId.slice(0, 8);
-        let restored;
+        const admission = reserveFreshSession({
+          operation: "branch",
+          workspaceCwd: boundWorkspace,
+          sourceSessionId: sessionId
+        });
+        let admissionReleased = false;
+        const releaseAdmissionOnce = /* @__PURE__ */ __name(() => {
+          if (admissionReleased) return;
+          admissionReleased = true;
+          releaseFreshSessionReservation(admission);
+        }, "releaseAdmissionOnce");
         try {
-          restored = await restoreSession("load", {
-            sessionId: result.newSessionId,
-            workspaceCwd: boundWorkspace,
-            clientId: context?.clientId
-          });
-        } catch (restoreErr) {
-          writeStderrLine(
-            `qwen serve: branchSession load failed for ${result.newSessionId}, attempting cleanup...`
+          const ci = await ensureChannel();
+          const result = await withTimeout(
+            ci.connection.extMethod(SERVE_CONTROL_EXT_METHODS.sessionBranch, {
+              sessionId,
+              cwd: boundWorkspace,
+              name: req.name
+            }),
+            initTimeoutMs,
+            "branchSession"
           );
+          if (!result || typeof result.newSessionId !== "string") {
+            throw new Error(
+              `branchSession: agent returned invalid response: ${JSON.stringify(result)}`
+            );
+          }
+          const rawBranchName = result.displayName ?? result.title;
+          const branchDisplayName = typeof rawBranchName === "string" ? rawBranchName : result.newSessionId.slice(0, 8);
+          let restored;
           try {
-            await ci.connection.extMethod(
-              SERVE_CONTROL_EXT_METHODS.sessionClose,
-              { sessionId: result.newSessionId, cwd: boundWorkspace }
+            restored = await restoreSession(
+              "load",
+              {
+                sessionId: result.newSessionId,
+                workspaceCwd: boundWorkspace,
+                clientId: context?.clientId
+              },
+              {
+                skipFreshSessionAdmission: true
+              }
             );
-          } catch (cleanupErr) {
+            releaseAdmissionOnce();
+          } catch (restoreErr) {
             writeStderrLine(
-              `qwen serve: branchSession cleanup of ${result.newSessionId} failed: ${cleanupErr instanceof Error ? cleanupErr.message : cleanupErr}`
+              `qwen serve: branchSession load failed for ${result.newSessionId}, attempting cleanup...`
             );
+            try {
+              await ci.connection.extMethod(
+                SERVE_CONTROL_EXT_METHODS.sessionClose,
+                { sessionId: result.newSessionId, cwd: boundWorkspace }
+              );
+            } catch (cleanupErr) {
+              writeStderrLine(
+                `qwen serve: branchSession cleanup of ${result.newSessionId} failed: ${cleanupErr instanceof Error ? cleanupErr.message : cleanupErr}`
+              );
+            }
+            throw restoreErr;
           }
-          throw restoreErr;
+          const newEntry = byId.get(result.newSessionId);
+          if (newEntry) newEntry.displayName = branchDisplayName;
+          const eventData = {
+            sourceSessionId: sessionId,
+            newSessionId: result.newSessionId,
+            displayName: branchDisplayName
+          };
+          const branchEnvelope = {
+            type: "session_branched",
+            data: eventData,
+            ...originatorClientId ? { originatorClientId } : {}
+          };
+          newEntry?.events.publish(branchEnvelope);
+          return {
+            ...restored,
+            displayName: branchDisplayName,
+            forkedFrom: {
+              sessionId,
+              displayName: entry.displayName ?? sessionId.slice(0, 8)
+            }
+          };
+        } finally {
+          releaseAdmissionOnce();
         }
-        const newEntry = byId.get(result.newSessionId);
-        if (newEntry) newEntry.displayName = branchDisplayName;
-        const eventData = {
-          sourceSessionId: sessionId,
-          newSessionId: result.newSessionId,
-          displayName: branchDisplayName
-        };
-        const branchEnvelope = {
-          type: "session_branched",
-          data: eventData,
-          ...originatorClientId ? { originatorClientId } : {}
-        };
-        newEntry?.events.publish(branchEnvelope);
-        return {
-          ...restored,
-          displayName: branchDisplayName,
-          forkedFrom: {
-            sessionId,
-            displayName: entry.displayName ?? sessionId.slice(0, 8)
-          }
-        };
       });
       entry.promptQueue = branchResult.then(
         () => void 0,
@@ -5556,9 +7195,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) {
@@ -5566,9 +7206,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);
@@ -5576,7 +7220,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 [];
@@ -6554,6 +8199,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",
@@ -6562,7 +8249,8 @@ function createAcpSessionBridge(opts) {
             promptId: req.promptId,
             targetTurnIndex,
             filesChanged,
-            filesFailed
+            filesFailed,
+            ...artifactWarnings.length > 0 ? { warnings: artifactWarnings } : {}
           },
           ...originatorClientId ? { originatorClientId } : {}
         });
@@ -6572,7 +8260,8 @@ function createAcpSessionBridge(opts) {
         rewound: filesFailed.length === 0,
         targetTurnIndex,
         filesChanged,
-        filesFailed
+        filesFailed,
+        ...artifactWarnings.length > 0 ? { warnings: artifactWarnings } : {}
       };
     },
     async manageMcpServer(serverName, action, originatorClientId) {
@@ -6708,6 +8397,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(
@@ -6757,8 +8452,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();
@@ -6781,6 +8485,12 @@ function createAcpSessionBridge(opts) {
       byId.clear();
       for (const e of entries) {
         telemetry.metrics?.sessionLifecycle("die");
+        emitSessionLifecycle({
+          type: "removed",
+          sessionId: e.sessionId,
+          workspaceCwd: e.workspaceCwd,
+          reason: "daemon_shutdown"
+        });
         try {
           e.events.publish({
             type: "session_died",
@@ -6842,6 +8552,7 @@ var createHttpAcpBridge = createAcpSessionBridge;
 
 export {
   SessionArtifactValidationError,
+  SessionArtifactAuthorizationError,
   extractErrorMessage,
   extractErrorCode,
   classifyTurnErrorKind,