oysterun 1.6.0-beta.2 → 1.6.0-beta.21

package/host-service/session-manager.mjs

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "crypto";
 import { EventEmitter } from "events";
+import { appendTaskProviderLifecycleDiagnostic } from "./host-runtime-diagnostics.mjs";
 import {
   chmodSync,
   copyFileSync,
@@ -19,7 +20,8 @@ import { DebugFixtureProviderAdapter } from "./adapters/debug-fixture-provider-a
 import { DebugLargeToolSpilloverProviderAdapter } from "./adapters/debug-large-tool-spillover-provider-adapter.mjs";
 import { DebugP135CodexReplayProviderAdapter } from "./adapters/debug-p135-codex-replay-provider-adapter.mjs";
 import { DebugRouteCStructuralReplayProviderAdapter } from "./adapters/debug-routec-structural-replay-provider-adapter.mjs";
-import { readConfig } from "./config.mjs";
+import { getConfigDir, readConfig } from "./config.mjs";
+import { DesiredOpenSessionStateOwner } from "./desired-open-session-state.mjs";
 import {
   createProviderUnavailableError,
   getConfiguredProviderCommand,
@@ -30,6 +32,7 @@ import {
   saveSessionRecord,
   updateSessionRecord,
 } from "./session-history.mjs";
+import { canonicalSessionTags, normalizeSessionTags } from "./session-tags.mjs";
 import {
   HOST_SESSION_RESUME_IDENTITY_KIND,
   getAdapterResumeIdentityKind,
@@ -53,6 +56,7 @@ import {
 import { normalizeAssetReadablePaths } from "./workspace-policy.mjs";
 import {
   blockRouteCHost2IntakeProviderDelivery,
+  cancelRouteCHost2IntakeForMatrixEvent,
   claimRouteCHost2IntakeForProviderDelivery,
   getRouteCHost2IntakeProof,
   markRouteCHost2IntakeAgentTurnStarted,
@@ -846,6 +850,19 @@ export class SessionManager extends EventEmitter {
       DEFAULT_CLAUDE_CLAIMED_TURN_NO_OUTPUT_TIMEOUT_MS,
       "claudeClaimedTurnNoOutputTimeoutMs"
     );
+    const desiredOpenStackName =
+      options.desiredOpenStackName ||
+      process.env.OYSTERUN_ROUTEC_STACK_NAME ||
+      process.env.OYSTERUN_STACK_NAME ||
+      process.env.OYSTERUN_STACK ||
+      "default";
+    this.desiredOpenStateOwner =
+      options.desiredOpenStateOwner ||
+      new DesiredOpenSessionStateOwner({
+        configDir: options.configDir || getConfigDir(),
+        stackName: desiredOpenStackName,
+      });
+    this.desiredOpenRestoreOutcomes = new Map();
     /** @type {Map<string, import("./adapters/claude-code-adapter.mjs").ClaudeCodeSession>} sessionId → Session */
     this.sessions = new Map();
     /** @type {Map<string, Set<string>>} agentId → sessionIds */
@@ -877,6 +894,168 @@ export class SessionManager extends EventEmitter {
     return session.providerResumeId || session.resumeSessionId || null;
   }
 
+  buildDesiredOpenSessionRecord(sessionId, session) {
+    return {
+      session_id: sessionId,
+      session_name: session.sessionName || sessionId,
+      tags: canonicalSessionTags(session),
+      agent_id: session.agentId,
+      agent_folder: session.cwd,
+      provider: session.provider || session.adapterId || "claude",
+      model: session.model ?? null,
+      fixture_resume_generation:
+        session.resumeIdentityKind === HOST_SESSION_RESUME_IDENTITY_KIND
+          ? normalizeFixtureResumeGeneration(session.fixtureResumeGeneration)
+          : null,
+      reasoning_effort: session.reasoningEffort ?? null,
+      reasoning_effort_source: session.reasoningEffortSource ?? null,
+      permission_mode: session.permissionMode ?? null,
+      approval_policy: session.approvalPolicy ?? null,
+      sandbox_mode: session.sandboxMode ?? null,
+      dangerous_mode: session.dangerousMode === true,
+      allow_dangerously_skip_permissions:
+        session.allowDangerouslySkipPermissions === true,
+      search_enabled: session.searchEnabled === true,
+      image_input_enabled: session.imageInputEnabled === true,
+      provider_resume_id: this.getEffectiveProviderResumeId(session),
+      provider_thread_id: session.threadId || null,
+      provider_transport: session.transport || null,
+      resume_identity_kind: session.resumeIdentityKind || null,
+      runtime_capabilities: cloneJsonObject(session.runtimeCapabilities) || {},
+      workspace_policy: cloneJsonObject(session.workspacePolicy),
+      asset_readable_paths: Array.isArray(session.assetReadablePaths)
+        ? [...session.assetReadablePaths]
+        : [],
+      started_at: session.historyCreatedAt || session.startedAt || null,
+      last_active_at:
+        session.lastActiveAt ||
+        session.historyCreatedAt ||
+        session.startedAt ||
+        null,
+    };
+  }
+
+  syncDesiredOpenSession(session) {
+    const state = this.desiredOpenStateOwner.upsert(
+      this.buildDesiredOpenSessionRecord(session.id, session)
+    );
+    const existing = this.desiredOpenRestoreOutcomes.get(session.id);
+    if (!existing || existing.state !== "failed") {
+      this.desiredOpenRestoreOutcomes.set(session.id, {
+        session_id: session.id,
+        state: session._ready === true ? "ready" : "restoring",
+        reason: null,
+      });
+    }
+    return state;
+  }
+
+  getDesiredOpenRestoreStatus() {
+    const desired = this.desiredOpenStateOwner.read();
+    if (!desired.valid) {
+      return {
+        status: desired.status,
+        valid: false,
+        sessions: [],
+      };
+    }
+    const sessions = desired.state.sessions.map((record) => ({
+      session_id: record.session_id,
+      session_name: record.session_name,
+      agent_id: record.agent_id,
+      agent_folder: record.agent_folder,
+      provider: record.provider,
+      ...(this.desiredOpenRestoreOutcomes.get(record.session_id) || {
+        state: record.restore_failed_reason ? "failed" : "pending",
+        reason: record.restore_failed_reason || null,
+        ...(record.restore_failed_at
+          ? { restore_failed_at: record.restore_failed_at }
+          : {}),
+      }),
+    }));
+    const desiredIds = new Set(sessions.map((entry) => entry.session_id));
+    for (const outcome of this.desiredOpenRestoreOutcomes.values()) {
+      if (
+        outcome.state === "failed" &&
+        outcome.session_id &&
+        !desiredIds.has(outcome.session_id)
+      ) {
+        sessions.push({ ...outcome });
+      }
+    }
+    return {
+      status: "available",
+      valid: true,
+      sessions,
+    };
+  }
+
+  getDesiredOpenRestoreOutcome(sessionId) {
+    return this.desiredOpenRestoreOutcomes.get(sessionId) || null;
+  }
+
+  markDesiredOpenRestoreReady(sessionId) {
+    if (!this.desiredOpenRestoreOutcomes.has(sessionId)) return null;
+    const outcome = {
+      session_id: sessionId,
+      state: "ready",
+      reason: null,
+    };
+    this.desiredOpenRestoreOutcomes.set(sessionId, outcome);
+    return outcome;
+  }
+
+  finalizeDesiredOpenRestoreFailure(sessionId, details = {}) {
+    const desired = this.desiredOpenStateOwner.read();
+    const record = desired.valid
+      ? desired.state.sessions.find((entry) => entry.session_id === sessionId)
+      : null;
+    const existing = this.desiredOpenRestoreOutcomes.get(sessionId) || {};
+    const outcome = {
+      ...(record || {}),
+      ...existing,
+      ...details,
+      session_id: sessionId,
+      state: "failed",
+      reason:
+        details.reason || existing.reason || "provider_runtime_restore_failed",
+    };
+    if (record) {
+      this.desiredOpenStateOwner.upsert({
+        ...record,
+        restore_failed_reason: outcome.reason,
+        restore_failed_at: new Date().toISOString(),
+      });
+    }
+    this.desiredOpenRestoreOutcomes.set(sessionId, outcome);
+    return outcome;
+  }
+
+  markDesiredOpenRestoreFailure(
+    sessionId,
+    { reason, reconciliationId = null, ...details } = {}
+  ) {
+    const existing = this.desiredOpenRestoreOutcomes.get(sessionId);
+    if (
+      existing?.state === "failed" &&
+      existing.reason === "restore_timeout" &&
+      reason !== "restore_timeout" &&
+      !reconciliationId
+    ) {
+      return existing;
+    }
+    const outcome = {
+      session_id: sessionId,
+      ...details,
+      state: "failed",
+      reason: reason || "provider_runtime_restore_failed",
+      reconciliation_id:
+        reconciliationId || existing?.reconciliation_id || null,
+    };
+    this.desiredOpenRestoreOutcomes.set(sessionId, outcome);
+    return outcome;
+  }
+
   getProviderTrustedFolderStatus({ cwd, provider, env = process.env }) {
     return this.providerTrust.getStatus({ cwd, provider, env });
   }
@@ -1531,10 +1710,23 @@ export class SessionManager extends EventEmitter {
     if (session._claimedProviderTurnNoOutputTimer) {
       clearTimeout(session._claimedProviderTurnNoOutputTimer);
     }
+    const message = messageId ? this.getOutboxMessage(session, messageId) : null;
+    // A primary-timer reset on a still-claimed silent prompt keeps the existing
+    // failsafe. Terminal/visible completion and re-arm clear both handles.
+    const clearFailsafe = resetState || !messageId ||
+      message?.claimedClaudeFinalEventSeen === true ||
+      ["failed", "canceled", "interrupted", "completed"].includes(message?.state);
+    if (clearFailsafe && session._claimedProviderTurnNoOutputFailsafeTimer) {
+      clearTimeout(session._claimedProviderTurnNoOutputFailsafeTimer);
+    }
+    appendTaskProviderLifecycleDiagnostic("claude_no_output_timer_clear", {
+      session_id: session.id, message_id: session._claimedProviderTurnNoOutputMessageId,
+      state: messageId ? this.getOutboxMessage(session, messageId)?.state : null,
+    });
     session._claimedProviderTurnNoOutputTimer = null;
+    if (clearFailsafe) session._claimedProviderTurnNoOutputFailsafeTimer = null;
     session._claimedProviderTurnNoOutputMessageId = null;
     session._claimedProviderTurnNoOutputDeadlineAt = null;
-    const message = messageId ? this.getOutboxMessage(session, messageId) : null;
     if (message) {
       message.claimedClaudeNoOutputDeadlineAt = null;
     }
@@ -2001,7 +2193,9 @@ export class SessionManager extends EventEmitter {
     if (
       message.state === "queued" ||
       message.state === "failed" ||
-      message.state === "canceled"
+      message.state === "canceled" ||
+      message.state === "interrupted" ||
+      message.state === "completed"
     ) {
       return false;
     }
@@ -2530,6 +2724,10 @@ export class SessionManager extends EventEmitter {
       ) {
         return;
       }
+      appendTaskProviderLifecycleDiagnostic("claude_no_output_timer_fire", {
+        session_id: liveSession.id, message_id: messageId,
+        state: targetMessage.state, generation,
+      });
       this.enforceClaimedClaudeNoOutputMessage(liveSession, targetMessage, {
         nowMs: Date.now(),
         phase: "claimed_provider_turn_timeout",
@@ -2548,6 +2746,10 @@ export class SessionManager extends EventEmitter {
         Math.min(50, Math.max(1, this.claudeClaimedTurnNoOutputTimeoutMs))
     );
     failsafeTimer.unref?.();
+    session._claimedProviderTurnNoOutputFailsafeTimer = failsafeTimer;
+    appendTaskProviderLifecycleDiagnostic("claude_no_output_timer_arm", {
+      session_id: session.id, message_id: messageId, state: message.state, generation,
+    });
   }
 
   providerControlKindFromPendingRequest(pendingRequest) {
@@ -2727,6 +2929,7 @@ export class SessionManager extends EventEmitter {
         semantic_body: `Cancel ${outcome} for queued message ${message.id}.`,
         control_outcome_id: controlOutcomeId,
         control_outcome: outcome,
+        cancel_outcome: outcome === "accepted" ? "accepted" : outcome,
         outcome,
         replay_policy: "always",
       })
@@ -2842,17 +3045,69 @@ export class SessionManager extends EventEmitter {
     return message;
   }
 
-  cancelOutboxMessage(sessionId, messageId) {
+  async cancelOutboxMessage(sessionId, messageId) {
     const session = this.requireSession(sessionId);
     const message = this.getOutboxMessage(session, messageId);
     if (!message) {
       throw new Error(`Outbox message ${messageId} not found`);
     }
+    const delivery = message.routeCMatrixDelivery || null;
+    const providerStarted =
+      delivery?.host2_intake_proof?.agent_turn_started === true ||
+      delivery?.agent_turn_started === true ||
+      message.state === "running";
+    if (providerStarted || !["queued", "dispatching"].includes(message.state)) {
+      throw new Error(`Outbox message ${messageId} is not cancelable`);
+    }
+    const dispatchAdapter = message.state === "dispatching"
+      ? this.getAdapter(session.provider || session.adapterId || "claude")
+      : null;
     if (
-      message.id === session._activeOutboxMessageId ||
-      message.state !== "queued"
+      message.state === "dispatching" &&
+      typeof dispatchAdapter?.cancelPendingMessage !== "function"
     ) {
-      throw new Error(`Outbox message ${messageId} is not cancelable`);
+      throw new Error(
+        `Provider ${session.provider || session.adapterId || "unknown"} cannot prove pre-start cancellation`
+      );
+    }
+    if (message.state === "dispatching") {
+      const adapterCancellation = await dispatchAdapter.cancelPendingMessage(
+        session,
+        message.id
+      );
+      if (adapterCancellation?.status === "provider_turn_started") {
+        throw new Error(`Outbox message ${messageId} is too late to cancel`);
+      }
+      if (adapterCancellation?.status === "provider_acceptance_unknown") {
+        const error = new Error(
+          `Outbox message ${messageId} provider acceptance is unknown`,
+        );
+        error.code = "PROVIDER_ACCEPTANCE_UNKNOWN";
+        error.providerAcceptance = "unknown";
+        throw error;
+      }
+      if (adapterCancellation?.status !== "pending_message_cancelled") {
+        throw new Error(
+          `Provider ${session.provider || session.adapterId || "unknown"} did not prove pre-start cancellation`
+        );
+      }
+    }
+    if (delivery?.source_user_event_id) {
+      const cancellation = cancelRouteCHost2IntakeForMatrixEvent({
+        hostSessionId: session.id,
+        matrixRoomId: delivery.matrix_room_id,
+        serverEventId: delivery.source_user_event_id,
+      });
+      if (cancellation.status !== 200) {
+        throw new Error(`Outbox message ${messageId} is too late to cancel`);
+      }
+      delivery.host2_intake_proof = cancellation.body?.proof || delivery.host2_intake_proof;
+    }
+    if (message.state === "dispatching") {
+      session._activeOutboxMessageId = null;
+      session._activeOutboxProgressSeen = false;
+      session._activeOutboxProviderVisibleEventSeen = false;
+      session._activeOutboxToolProgressSeen = false;
     }
     this.emitOutboxCancelControlEvent(session, message, {
       semanticType: "control.request",
@@ -2865,9 +3120,23 @@ export class SessionManager extends EventEmitter {
       outcome: "accepted",
     });
     this.emitDeliveryStateNotice(session);
+    this.drainOutbox(session);
     return message;
   }
 
+  async reconcileProviderMessageCancellation(sessionId, payload) {
+    const session = this.requireSession(sessionId);
+    const adapter = this.getAdapter(session.provider || session.adapterId || "claude");
+    if (typeof adapter?.reconcilePendingMessageCancellation !== "function") {
+      return {
+        status: "provider_acceptance_unknown",
+        message_id: payload?.messageId || null,
+        reason: "provider_cancellation_reconciliation_unsupported",
+      };
+    }
+    return adapter.reconcilePendingMessageCancellation(session, payload);
+  }
+
   handleOysterunProviderSkillInstallSlashCommand(
     session,
     userId,
@@ -3085,6 +3354,7 @@ export class SessionManager extends EventEmitter {
   }
 
   canDrainOutbox(session) {
+    if (session._stopping === true) return false;
     const providerId = session.provider || session.adapterId || "claude";
     const allowFreshClaudeStartupDispatch =
       providerId === "claude" &&
@@ -3192,12 +3462,17 @@ export class SessionManager extends EventEmitter {
       }
       this.armClaimedClaudeNoOutputTimer(session, message);
       adapter.sendMessage(session, {
+        messageId: message.id,
         userId: message.userId,
         nickname: message.nickname,
         text: message.providerText,
         rawText: message.rawText,
         isSlashCommand: message.isSlashCommand,
         slashCommandName: message.slashCommandName,
+        reconcileProviderAcceptance:
+          message.routeCMatrixDelivery?.delivery_kind === "callback_result" &&
+          message.routeCMatrixDelivery?.session_correlation?.reconcile_provider_acceptance === true,
+        providerTurnId: message.providerTurnId,
       });
       this.emit(
         "runtimeEvent",
@@ -3887,6 +4162,8 @@ export class SessionManager extends EventEmitter {
     provider = "claude",
     sessionId,
     sessionName,
+    tags = [],
+    deferTagsPersistence = false,
     parentSessionId = null,
     resumeSessionId,
     fork = false,
@@ -4071,6 +4348,8 @@ export class SessionManager extends EventEmitter {
     session.sandboxMode = session.sandboxMode ?? sandboxMode ?? null;
     session.dangerousMode = dangerousMode === true;
     session.sessionName = resolvedSessionName;
+    session.tags = normalizeSessionTags(tags);
+    session.tagsPersistenceDeferred = deferTagsPersistence === true;
     session.startRequestedAt = new Date().toISOString();
     session.historyCreatedAt =
       session.providerReadinessDeferred === true
@@ -4123,6 +4402,7 @@ export class SessionManager extends EventEmitter {
       session_id: session.id,
       session_name: session.sessionName,
       parent_session_id: session.parentSessionId,
+      ...(session.tagsPersistenceDeferred ? {} : { tags: session.tags }),
       agent_id: agentId,
       agent_folder: cwd,
       runtime: session.provider,
@@ -4138,6 +4418,8 @@ export class SessionManager extends EventEmitter {
       fixture_resume_generation: session.fixtureResumeGeneration,
       created_at: session.historyCreatedAt,
       last_active_at: lastActiveAt,
+      restore_failed_reason: null,
+      restore_failed_at: null,
     });
 
     const buildHistoryMetadataSnapshot = () =>
@@ -4164,6 +4446,7 @@ export class SessionManager extends EventEmitter {
       session.historyCreatedAt ||= new Date().toISOString();
       session.lastActiveAt ||= session.historyCreatedAt;
       saveSessionRecord(buildHistoryRecord());
+      this.syncDesiredOpenSession(session);
       session.historyRecordId = session.id;
       session.historyCommitted = true;
       session.historyMetadataSnapshot = buildHistoryMetadataSnapshot();
@@ -4190,6 +4473,16 @@ export class SessionManager extends EventEmitter {
       }
       this.handleOutboxRuntimeEvent(session, event);
       this.syncSessionRuntimeState(session, event);
+      if (
+        event.type === "session.ready" &&
+        this.desiredOpenRestoreOutcomes.get(session.id)?.state !== "failed"
+      ) {
+        this.desiredOpenRestoreOutcomes.set(session.id, {
+          session_id: session.id,
+          state: "ready",
+          reason: null,
+        });
+      }
       if (event.type === "session.ready" && !session.historyCommitted) {
         try {
           commitHistoryRecord();
@@ -4225,6 +4518,7 @@ export class SessionManager extends EventEmitter {
             buildHistoryRecord(new Date().toISOString())
           );
           session.historyMetadataSnapshot = nextHistoryMetadata;
+          this.syncDesiredOpenSession(session);
         } catch (err) {
           recordBookkeepingWarning("history.runtime_sync_failed", err);
         }
@@ -4235,6 +4529,19 @@ export class SessionManager extends EventEmitter {
       }
     });
     session.on("error", (err) => {
+      if (this.desiredOpenRestoreOutcomes.has(session.id) &&
+          err.codexRequestOutcome !== "pre_acceptance_rejected") {
+        const authFailure = this.classifyProviderAuthFailure(session, null, {
+          type: "runtime.error",
+          error: err.message || String(err),
+        });
+        this.markDesiredOpenRestoreFailure(session.id, {
+          reason: authFailure
+            ? "provider_login_required"
+            : "provider_runtime_restore_failed",
+          error: err.message || String(err),
+        });
+      }
       if (this.shouldSuppressExitDerivedRuntimeError(session, err)) {
         return;
       }
@@ -4280,6 +4587,12 @@ export class SessionManager extends EventEmitter {
       this.handleOutboxExit(session);
       this.sessions.delete(id);
       this.removeAgentSession(agentId, id);
+      if (this.desiredOpenRestoreOutcomes.has(id)) {
+        this.markDesiredOpenRestoreFailure(id, {
+          reason: "provider_runtime_exited",
+          exit_code: code ?? null,
+        });
+      }
       const providerExitEvent = session._lastProviderExitEvent || null;
       try {
         if (session.historyCommitted) {
@@ -4620,6 +4933,7 @@ export class SessionManager extends EventEmitter {
     session.runtimeCapabilities = JSON.parse(
       JSON.stringify(runtimeCapabilities)
     );
+    this.syncDesiredOpenSession(session);
     this.emit(
       "runtimeEvent",
       session.agentId,
@@ -4638,6 +4952,13 @@ export class SessionManager extends EventEmitter {
     return session.runtimeCapabilities;
   }
 
+  updateWorkspacePolicy(sessionId, workspacePolicy) {
+    const session = this.requireSession(sessionId);
+    session.workspacePolicy = cloneJsonObject(workspacePolicy);
+    this.syncDesiredOpenSession(session);
+    return session.workspacePolicy;
+  }
+
   renameSession(sessionId, sessionName) {
     const session = this.requireSession(sessionId);
     const resolvedSessionName = normalizeSessionName(sessionName);
@@ -4661,6 +4982,7 @@ export class SessionManager extends EventEmitter {
       last_active_at: new Date().toISOString(),
     });
     session.sessionName = resolvedSessionName;
+    this.syncDesiredOpenSession(session);
     this.emit(
       "runtimeEvent",
       session.agentId,
@@ -4830,6 +5152,19 @@ export class SessionManager extends EventEmitter {
 
   async stopSession(sessionId) {
     const session = this.requireSession(sessionId);
+    // Stop must leave a durable visible cancellation for never-started user
+    // prompts, while callback results retain their own recovery contract.
+    session._stopping = true;
+    const discarded = [];
+    for (const message of session._outbox || []) {
+      if (message.state !== "queued" ||
+          message.routeCMatrixDelivery?.delivery_kind === "callback_result") continue;
+      await this.cancelOutboxMessage(session.id, message.id);
+      discarded.push(message.id);
+    }
+    appendTaskProviderLifecycleDiagnostic("session_stop_queued_prompts", {
+      session_id: session.id, discarded_message_ids: discarded,
+    });
     const agentId = session.agentId;
     const adapter = this.getAdapter(
       session.provider || session.adapterId || "claude"
@@ -4851,6 +5186,14 @@ export class SessionManager extends EventEmitter {
       adapter.killSession(session);
       await this.waitForSessionExit(session, 5000);
     }
+    this.desiredOpenStateOwner.remove(sessionId);
+    this.desiredOpenRestoreOutcomes.delete(sessionId);
+  }
+
+  removeDesiredOpenSession(sessionId) {
+    const state = this.desiredOpenStateOwner.remove(sessionId);
+    this.desiredOpenRestoreOutcomes.delete(sessionId);
+    return state;
   }
 
   /**
@@ -4934,6 +5277,7 @@ export class SessionManager extends EventEmitter {
       provider: nextProvider,
       sessionId: nextSessionId,
       sessionName: overrides.sessionName ?? session.sessionName,
+      tags: overrides.tags ?? session.tags,
       resumeSessionId: providerResumeId,
       resume: providerResumeId !== undefined,
       model:
@@ -4976,52 +5320,120 @@ export class SessionManager extends EventEmitter {
 
   snapshotHostRestartState() {
     return [...this.sessions.entries()].map(([sessionId, session]) => ({
-      session_id: sessionId,
-      session_name: session.sessionName || null,
-      agent_id: session.agentId,
-      agent_folder: session.cwd,
-      provider: session.provider || "claude",
-      model: session.model ?? null,
-      fixture_resume_generation:
-        session.resumeIdentityKind === HOST_SESSION_RESUME_IDENTITY_KIND
-          ? normalizeFixtureResumeGeneration(session.fixtureResumeGeneration)
-          : null,
-      reasoning_effort: session.reasoningEffort ?? null,
-      permission_mode: session.permissionMode ?? null,
-      approval_policy: session.approvalPolicy ?? null,
-      sandbox_mode: session.sandboxMode ?? null,
-      dangerous_mode: session.dangerousMode === true,
-      provider_resume_id: this.getEffectiveProviderResumeId(session),
-      provider_thread_id: session.threadId || null,
-      provider_transport: session.transport || null,
-      runtime_capabilities: cloneJsonObject(session.runtimeCapabilities) || {},
+      ...this.buildDesiredOpenSessionRecord(sessionId, session),
       runtime_capability_grant: cloneJsonObject(session.runtimeCapabilityGrant),
-      reasoning_effort_source: session.reasoningEffortSource || null,
       native: cloneJsonObject(session.native) || session.native || null,
-      workspace_policy: cloneJsonObject(session.workspacePolicy),
-      asset_readable_paths: Array.isArray(session.assetReadablePaths)
-        ? [...session.assetReadablePaths]
-        : [],
       notification_config: serializeHostRestartNotificationConfig(
         session.notificationConfig
       ),
       notification_config_updated_at: normalizeHostRestartString(
         session.notificationConfigUpdatedAt
       ),
-      search_enabled: session.searchEnabled === true,
-      image_input_enabled: session.imageInputEnabled === true,
-      allow_dangerously_skip_permissions:
-        session.allowDangerouslySkipPermissions === true,
       alive_before_restart: session.alive === true,
       ready_before_restart: session._ready === true,
-      started_at: session.historyCreatedAt || session.startedAt || null,
-      last_active_at:
-        session.lastActiveAt || session.historyCreatedAt || session.startedAt || null,
       restore_policy: "provider_runtime_resume_on_boot",
       prompt_replay: false,
     }));
   }
 
+  restoreDesiredOpenSessions({
+    buildRuntimeCapabilityGrant = null,
+    reconciliationId = null,
+    sessionIds = null,
+  } = {}) {
+    const desired = this.desiredOpenStateOwner.read();
+    if (!desired.valid) {
+      return {
+        restored: [],
+        skipped: [],
+        failed: [{ session_id: null, reason: desired.status }],
+      };
+    }
+    const selectedIds = Array.isArray(sessionIds) ? new Set(sessionIds) : null;
+    const eligible = [];
+    const failed = [];
+    for (const record of desired.state.sessions) {
+      if (selectedIds && !selectedIds.has(record.session_id)) continue;
+      if (record.restore_failed_reason) {
+        this.desiredOpenRestoreOutcomes.set(record.session_id, {
+          ...record,
+          session_id: record.session_id,
+          state: "failed",
+          reason: record.restore_failed_reason,
+        });
+        continue;
+      }
+      this.desiredOpenRestoreOutcomes.set(record.session_id, {
+        session_id: record.session_id,
+        state: "restoring",
+        reason: null,
+        reconciliation_id: reconciliationId,
+      });
+      if (!existsSync(record.agent_folder)) {
+        const failure = {
+          session_id: record.session_id,
+          agent_id: record.agent_id,
+          reason: "agent_folder_missing",
+        };
+        failed.push(failure);
+        this.desiredOpenRestoreOutcomes.set(record.session_id, {
+          ...record,
+          ...failure,
+          state: "failed",
+          reconciliation_id: reconciliationId,
+        });
+        continue;
+      }
+      eligible.push({
+        ...record,
+        alive_before_restart: true,
+        ready_before_restart: true,
+        prompt_replay: false,
+      });
+    }
+    const result = this.restoreHostRestartState(eligible, {
+      restartId: reconciliationId || `desired-open-${randomUUID()}`,
+      buildRuntimeCapabilityGrant,
+    });
+    for (const entry of result.restored) {
+      const session = this.getSession(entry.session_id);
+      this.desiredOpenRestoreOutcomes.set(entry.session_id, {
+        ...desired.state.sessions.find(
+          (record) => record.session_id === entry.session_id
+        ),
+        session_id: entry.session_id,
+        state: session?._ready === true ? "ready" : "restoring",
+        reason: null,
+        reconciliation_id: reconciliationId,
+      });
+    }
+    for (const entry of result.skipped) {
+      const session = this.getSession(entry.session_id);
+      this.desiredOpenRestoreOutcomes.set(entry.session_id, {
+        ...desired.state.sessions.find(
+          (record) => record.session_id === entry.session_id
+        ),
+        ...entry,
+        state:
+          entry.reason === "already_live" && session?._ready !== true
+            ? "restoring"
+            : "ready",
+        reconciliation_id: reconciliationId,
+      });
+    }
+    for (const entry of result.failed) {
+      this.desiredOpenRestoreOutcomes.set(entry.session_id, {
+        ...desired.state.sessions.find(
+          (record) => record.session_id === entry.session_id
+        ),
+        ...entry,
+        state: "failed",
+        reconciliation_id: reconciliationId,
+      });
+    }
+    return { ...result, failed: [...failed, ...result.failed] };
+  }
+
   restoreHostRestartState(
     sessions = [],
     { restartId, restoredAt, buildRuntimeCapabilityGrant = null } = {}
@@ -5051,6 +5463,14 @@ export class SessionManager extends EventEmitter {
         });
         continue;
       }
+      if (!existsSync(agentFolder)) {
+        failed.push({
+          session_id: id,
+          agent_id: agentId,
+          reason: "agent_folder_missing",
+        });
+        continue;
+      }
       const wasLiveOrReady =
         record.alive_before_restart === true ||
         record.ready_before_restart === true;
@@ -5143,6 +5563,7 @@ export class SessionManager extends EventEmitter {
           provider,
           sessionId: id,
           sessionName: record.session_name || id,
+          tags: canonicalSessionTags(record),
           resumeSessionId: providerResumeId,
           resume: true,
           fork: false,
@@ -5247,6 +5668,7 @@ export class SessionManager extends EventEmitter {
           session_id: id,
           session_name: session.sessionName,
           parent_session_id: session.parentSessionId || null,
+          tags: canonicalSessionTags(session),
           agent_id: agentId,
           agent_folder: session.cwd,
           runtime: session.provider,
@@ -5273,6 +5695,18 @@ export class SessionManager extends EventEmitter {
         prompt_replay: false,
       });
     }
+    for (const failure of failed) {
+      if (!failure.session_id) continue;
+      const record = sessions.find(
+        (entry) => entry?.session_id === failure.session_id
+      );
+      this.finalizeDesiredOpenRestoreFailure(failure.session_id, {
+        ...(record || {}),
+        ...failure,
+        reason: failure.reason,
+        reconciliation_id: restartId || null,
+      });
+    }
     return { restored, skipped, failed };
   }
 
@@ -5303,6 +5737,7 @@ export class SessionManager extends EventEmitter {
     return [...this.sessions.entries()].map(([id, s]) => ({
       sessionId: id,
       sessionName: s.sessionName || null,
+      tags: canonicalSessionTags(s),
       agentId: s.agentId,
       provider: s.provider || "claude",
       cwd: s.cwd,