mixdog 1.2.3 → 1.2.4

package/src/standalone/daemon-stored-session-views.mjs

@@ -11,6 +11,23 @@ import {
   readStoredGoalSnapshot,
 } from '../runtime/agent/orchestrator/runtime-core/goal-runtime.mjs';
 
+/** Catalog rows with the daemon's in-memory turn activity overlaid: `working`
+ *  on a session whose own turn is in flight, `agentWorking` on a Lead with an
+ *  in-flight Agent session. Every session runs in this process, so the runtime
+ *  state is the whole answer — storage carries no liveness. */
+async function withRuntimeActivity(rows) {
+  // The import-free leaf holding the runtime map: no session manager graph.
+  const { inFlightSessionActivity } = await import('../runtime/agent/orchestrator/session/manager/runtime-state.mjs');
+  const { working, agentWorking } = inFlightSessionActivity();
+  if (!working.size) return rows;
+  return rows.map((row) => {
+    const own = working.has(row?.id);
+    const agents = agentWorking.has(row?.id);
+    if (!own && !agents) return row;
+    return { ...row, ...(own ? { working: true } : {}), ...(agents ? { agentWorking: true } : {}) };
+  });
+}
+
 export function createStoredSessionViews({ desktopRuntime, dataDir }) {
   return {
     // Settled identity of the files a stored projection is built from; the
@@ -86,11 +103,14 @@ export function createStoredSessionViews({ desktopRuntime, dataDir }) {
       // ignored, full array). An authoritative refresh is never paged.
       const page = options.page && typeof options.page === 'object' ? options.page : null;
       if (page && !refreshFromStorage && store.listStoredSessionSummaryPage) {
-        return store.listStoredSessionSummaryPage({ limit: page.limit, cursor: page.cursor });
+        const listed = await store.listStoredSessionSummaryPage({ limit: page.limit, cursor: page.cursor });
+        return { ...listed, sessions: await withRuntimeActivity(listed.sessions) };
       }
       // The async listing may answer from the session catalog DB.
-      if (store.listStoredSessionSummariesAsync) return store.listStoredSessionSummariesAsync({ refreshFromStorage });
-      return store.listStoredSessionSummaries({ refreshFromStorage });
+      const rows = store.listStoredSessionSummariesAsync
+        ? await store.listStoredSessionSummariesAsync({ refreshFromStorage })
+        : store.listStoredSessionSummaries({ refreshFromStorage });
+      return withRuntimeActivity(rows);
     },
   };
 }

package/src/standalone/daemon.mjs

@@ -91,6 +91,7 @@ import { createLagProfiler } from './daemon-lag-profiler.mjs';
 import { createChannelsRuntimeLoader } from './daemon-channels-loader.mjs';
 import { createDesktopRuntime } from './daemon-desktop-runtime.mjs';
 import { createCanonicalAgentControl } from './daemon-agent-control.mjs';
+import { createSessionControl } from './daemon-session-control.mjs';
 import { flushAllIndexWrites } from '../session-runtime/services/agent-tool/index-write-queue.mjs';
 import { registerAutomationAgentTool } from '../session-runtime/automation-agents.mjs';
 import {
@@ -913,6 +914,7 @@ async function main() {
     log,
     measureBootPhase: bootPhases.measure,
     executeAgentControl: agentControl.execute,
+    executeSessionControl: createSessionControl({ getSessionService: () => sessionService }),
   });
   // Codex-style runtime: daemon routing and independent async session actors
   // share one V8 isolate and module graph. CPU-heavy work stays in bounded

package/src/standalone/local-session-runtime.mjs

@@ -15,6 +15,7 @@ import { createGoalContinuation } from '../tui/session/goal-continuation.mjs';
 import { createToolApproval } from '../tui/session/tool-approval.mjs';
 import { createToolCardResults } from '../tui/session/tool-card-results.mjs';
 import { createAgentJobFeed } from '../tui/session/agent-job-feed.mjs';
+import { createWorktreeSetupNotices } from '../tui/session/worktree-setup-notice.mjs';
 import { createContextState } from '../tui/session/context-state.mjs';
 import { createSessionFlow } from '../tui/session/session-flow.mjs';
 import { createRunTurn } from '../tui/session/turn.mjs';
@@ -28,7 +29,7 @@ import { createActiveToolTracker } from '../tui/session/active-tool-summary.mjs'
 import { createTranscriptStore } from '../tui/session/transcript-store.mjs';
 import { createTranscriptIntake } from '../tui/session/transcript-intake.mjs';
 import { createNoticeSurface } from '../tui/session/notice-surface.mjs';
-import { attachCrossSurfaceShare } from '../tui/session/cross-surface-share.mjs';
+import { rearmGoalContinuationOnSessionBoundaries } from '../tui/session/goal-continuation/session-boundary.mjs';
 import { createTranscriptRouteMetadata } from '../runtime/shared/transcript-metadata.mjs';
 import { formatDoctorReport, runDoctorChecks } from '../tui/app/doctor.mjs';
 // tuiDebug is an opt-in diagnostic trace for the hang chain (runTurn start/end,
@@ -109,7 +110,6 @@ export { parseBackgroundTaskEnvelope } from '../tui/session/agent-envelope.mjs';
  */
 export function createRuntimePulse({
   flags,
-  liveShareMirroring,
   getState,
   getPublishedState,
   set,
@@ -138,13 +138,6 @@ export function createRuntimePulse({
   const pulse = () => {
     if (flags.disposed) return;
     if (flags.pendingSessionReset) return;
-    // Attached viewer with a live pipe: the owner's frames are authoritative
-    // for stats/agent/tool state. Recomputing them locally here would stomp
-    // the mirror with this process's empty registries every 2s.
-    if (liveShareMirroring()) {
-      publishChanged({ ...routeState() });
-      return;
-    }
     syncContextStats({ allowEstimated: true });
     publishChanged({
       ...routeState(),
@@ -177,6 +170,7 @@ export async function createLocalSessionRuntime({
   sessionProfile,
   worktree,
   executeAgentControl,
+  executeSessionControl,
 } = {}) {
   const startedAt = performance.now();
   bootProfile('session:create:start', { provider: providerName, model, toolMode, remote });
@@ -209,6 +203,7 @@ export async function createLocalSessionRuntime({
     // Session creation worktree intent; consumed by the workspace transition scope.
     ...(worktree && typeof worktree === 'object' ? { worktree } : {}),
     ...(typeof executeAgentControl === 'function' ? { executeAgentControl } : {}),
+    ...(typeof executeSessionControl === 'function' ? { executeSessionControl } : {}),
   });
   bootProfile('session:create:runtime-ready', { ms: (performance.now() - startedAt).toFixed(1) });
   const runtimeCwd = runtime.cwd || process.cwd();
@@ -322,7 +317,6 @@ export async function createLocalSessionRuntime({
   );
   const runtimePulse = createRuntimePulse({
     flags,
-    liveShareMirroring: () => bag.liveShareMirroring?.() === true,
     getState,
     getPublishedState,
     set,
@@ -374,9 +368,14 @@ export async function createLocalSessionRuntime({
     itemIndexById,
   });
   lifecycle.unsubscribeRuntimeNotifications = subscribeRuntimeNotifications();
+  if (typeof runtime.onWorktreeSetup === 'function') {
+    lifecycle.unsubscribeWorktreeSetup = runtime.onWorktreeSetup(
+      createWorktreeSetupNotices({ pushItem, patchItem, nextId })
+    );
+  }
   if (typeof runtime.onAgentStatusChange === 'function') {
     lifecycle.unsubscribeAgentStatus = runtime.onAgentStatusChange(() => {
-      if (flags.disposed || flags.pendingSessionReset || bag.liveShareMirroring?.()) return;
+      if (flags.disposed || flags.pendingSessionReset) return;
       set({ ...agentStatusState({ force: true }) });
       bag.scheduleGoalContinuation?.();
     });
@@ -474,7 +473,7 @@ export async function createLocalSessionRuntime({
   bag.runTurn = createRunTurn(bag);
   bag.doctor = { runDoctorChecks, formatDoctorReport };
   const api = createSessionApi(bag);
-  attachCrossSurfaceShare({ runtime, api, bag, flags, getState, getPublishedState, listeners, set });
+  rearmGoalContinuationOnSessionBoundaries({ api, bag });
   void Promise.resolve(bag.restoreLeadSteeringFromDisk())
     .catch(() => {})
     .finally(() => {

package/src/standalone/session-protocol.mjs

@@ -6,6 +6,8 @@
  */
 
 export const SESSION_READ_ACTIONS = Object.freeze([
+  'inspectProjectBranch',
+  'isSessionTerminal',
   'contextStatus',
   'getAgentDefinition',
   'getAutoClear',
@@ -18,6 +20,7 @@ export const SESSION_READ_ACTIONS = Object.freeze([
   'getDisabledSkills',
   'getMediaDefault',
   'getMediaJob',
+  'getMediaPins',
   'getMcpServerConfig',
   'getMcpOAuthLoginStatus',
   'getOnboardingStatus',
@@ -71,6 +74,7 @@ export const SESSION_READ_ACTIONS = Object.freeze([
   'listProviders',
   'listWebSearchModels',
   'listThemes',
+  'listShellJobs',
   'listWorkflows',
   'mcpStatus',
   'pluginsStatus',
@@ -194,6 +198,7 @@ export const SESSION_CONFIGURE_ACTIONS = Object.freeze([
   'startLocalProviderModelMaintenance',
   'deleteLocalProviderModel',
   'setMediaDefault',
+  'setMediaPin',
   'setModel',
   'setOutputStyle',
   'setPluginEnabled',
@@ -219,6 +224,7 @@ export const SESSION_CONFIGURE_ACTIONS = Object.freeze([
   'startConversationImport',
   'startMediaJob',
   'stopShellJob',
+  'releaseShellJob',
   'switchContext',
   'taskControl',
   'testWebhook',
@@ -233,6 +239,7 @@ export const SESSION_CONFIGURE_ACTIONS = Object.freeze([
   'selectBranch',
   'selectProjectBranch',
   'mergeProjectBranch',
+  'manageProjectBranch',
   'requestWorktree',
   'mergeWorkspace',
   'removeWorktree',

package/src/standalone/session-runtime-inline-host.mjs

@@ -27,6 +27,7 @@ export function createInlineSessionRuntimeHost({
     await keychain.prewarmSecrets();
   },
   executeAgentControl = null,
+  executeSessionControl = null,
 } = {}) {
   let closed = false;
   let closePromise = null;
@@ -59,6 +60,7 @@ export function createInlineSessionRuntimeHost({
       ...options,
       ...(options.cwd ? {} : { cwd }),
       ...(typeof executeAgentControl === 'function' ? { executeAgentControl } : {}),
+      ...(typeof executeSessionControl === 'function' ? { executeSessionControl } : {}),
     });
     if (closed) {
       try {

package/src/standalone/session-service/agent-tree/agent-cancel.mjs

@@ -24,7 +24,7 @@ export function createAgentCancellation({
   log,
   rememberCancelTranscript,
 }) {
-  const agentCancelRuns = new Map();
+  const agentCloseRuns = new Map();
 
   /** The runtime entry that can close this descriptor: the live owner, else a
    *  freshly loaded one (null when loading fails, which is logged). */
@@ -44,66 +44,108 @@ export function createAgentCancellation({
     }
   };
 
-  function cancelAgentTree(sessionId, reason = 'agent session cancelled') {
-    const id = String(sessionId || '').trim();
-    if (!id) return Promise.resolve(false);
-    const active = agentCancelRuns.get(id);
+  function closeOne(id, reason, options) {
+    const active = agentCloseRuns.get(id);
     if (active) return active;
     let run;
-    run = (async () => {
-      await rehydrateAgentSessions();
-      cancelBackgroundTasks({
-        surface: 'agent',
-        callerSessionId: id,
-        reason,
+    run = Promise.resolve()
+      .then(async () => {
+        cancelBackgroundTasks({
+          surface: 'agent',
+          callerSessionId: id,
+          reason,
+        });
+        cancelOwnAgentTasks(id, reason);
+        const descriptor = registry.get(id);
+        if (!descriptor) return false;
+        if ((await sessionOwner(id)?.runtime?.isSessionTerminal?.()) === true) return true;
+        const entry = await closableEntry(id, descriptor);
+        const closeCanonical = entry?.runtime?.closeCanonicalSession;
+        if (typeof closeCanonical !== 'function') {
+          throw new TypeError('session runtime must implement closeCanonicalSession');
+        }
+        // The close clears the transcript: capture a running turn's transcript
+        // first so the cancelled turn still hands off its partial output.
+        if (descriptor.status === 'running') {
+          try {
+            const { messages } = await entry.runtime.readModelMessages(0);
+            rememberCancelTranscript(id, messages);
+          } catch (error) {
+            log(`agent cancel transcript read failed session=${id}: ${error?.message || error}`);
+          }
+        }
+        const closed = await closeCanonical.call(entry.runtime, reason, { tombstone: options.tombstone === true });
+        if (closed !== true) throw new Error(`agent session ${id} could not be durably closed`);
+        descriptor.closed = options.tombstone === true;
+        descriptor.status = descriptor.closed ? 'closed' : 'cancelled';
+        descriptor.stage = descriptor.status;
+        descriptor.updatedAt = Date.now();
+        return true;
+      })
+      .finally(() => {
+        if (agentCloseRuns.get(id) === run) agentCloseRuns.delete(id);
       });
-      const children = registry.childrenOf(id);
-      await Promise.all(children.map((childId) => cancelAgentTree(childId, reason)));
-      cancelOwnAgentTasks(id, reason);
-      const descriptor = registry.get(id);
-      if (!descriptor) return children.length > 0;
-      if (descriptor.closed) return true;
-      const entry = await closableEntry(id, descriptor);
-      const closeCanonical = entry?.runtime?.closeCanonicalSession;
-      if (typeof closeCanonical !== 'function') {
-        throw new TypeError('session runtime must implement closeCanonicalSession');
-      }
-      // The close clears the transcript: capture a running turn's transcript
-      // first so the cancelled turn still hands off its partial output.
-      if (descriptor.status === 'running') {
+    agentCloseRuns.set(id, run);
+    return run;
+  }
+
+  async function cancelAgentTree(sessionId, reason = 'agent session cancelled', options = {}) {
+    const id = String(sessionId || '').trim();
+    if (!id) return false;
+    await rehydrateAgentSessions();
+    const seen = new Set();
+    const ordered = [];
+    const visit = (current) => {
+      if (seen.has(current)) return;
+      seen.add(current);
+      for (const child of registry.childrenOf(current)) visit(child);
+      ordered.push(current);
+    };
+    visit(id);
+    const release = registry.beginCancellation(ordered);
+    try {
+      let closed = false;
+      const failures = [];
+      // Descendant-first, one at a time; a failed member never skips the rest.
+      for (const current of ordered) {
         try {
-          const { messages } = await entry.runtime.readModelMessages(0);
-          rememberCancelTranscript(id, messages);
+          closed = (await closeOne(current, reason, options)) || closed;
         } catch (error) {
-          log(`agent cancel transcript read failed session=${id}: ${error?.message || error}`);
+          log(`agent cancel failed session=${current}: ${error?.message || error}`);
+          failures.push(error);
         }
       }
-      const closed = await closeCanonical.call(entry.runtime, reason);
-      if (closed !== true) throw new Error(`agent session ${id} could not be durably closed`);
-      descriptor.closed = true;
-      descriptor.status = 'closed';
-      descriptor.stage = 'closed';
-      descriptor.updatedAt = Date.now();
-      return true;
-    })().finally(() => {
-      if (agentCancelRuns.get(id) === run) agentCancelRuns.delete(id);
-    });
-    agentCancelRuns.set(id, run);
-    return run;
+      if (failures.length === 1) throw failures[0];
+      if (failures.length) {
+        const details = failures.map((error) => error?.message || String(error)).join('; ');
+        throw new AggregateError(
+          failures,
+          `agent tree cancel failed for ${failures.length} of ${ordered.length} sessions: ${details}`
+        );
+      }
+      return closed;
+    } finally {
+      release();
+    }
   }
 
   async function cancelAgentDescendants(parentSessionId, reason = 'parent session cancelled') {
     await rehydrateAgentSessions();
     const parentId = String(parentSessionId || '');
-    cancelBackgroundTasks({
-      surface: 'agent',
-      callerSessionId: parentId,
-      reason,
-    });
-    const children = registry.childrenOf(parentId);
-    if (!children.length) return false;
-    await Promise.all(children.map((childId) => cancelAgentTree(childId, reason)));
-    return true;
+    const release = registry.beginCancellation([parentId]);
+    try {
+      cancelBackgroundTasks({
+        surface: 'agent',
+        callerSessionId: parentId,
+        reason,
+      });
+      const children = registry.childrenOf(parentId);
+      if (!children.length) return false;
+      await Promise.all(children.map((childId) => cancelAgentTree(childId, reason)));
+      return true;
+    } finally {
+      release();
+    }
   }
 
   return { cancelAgentTree, cancelAgentDescendants };

package/src/standalone/session-service/agent-tree/agent-child.mjs

@@ -3,11 +3,12 @@
 // caller's spec, creation of the runtime behind it, and the descriptor linked
 // into the agent registry. Running a turn on that child is ./agent-turns.mjs.
 
-export function createAgentChildFactory({ registry, rehydrateAgentSessions, createSession }) {
+export function createAgentChildFactory({ registry, rehydrateAgentSessions, createSession, entryForSession }) {
   return async function createAgentChild({ spec = {}, tag = null } = {}) {
     await rehydrateAgentSessions();
     const parentSessionId = String(spec.parentSessionId || '').trim();
     if (!parentSessionId) throw new TypeError('agent child parentSessionId is required');
+    const parentEpoch = registry.assertAdmission(parentSessionId);
     const ownerSessionId = String(
       spec.ownerSessionId || registry.get(parentSessionId)?.ownerSessionId || parentSessionId
     );
@@ -29,6 +30,7 @@ export function createAgentChildFactory({ registry, rehydrateAgentSessions, crea
       sourceType: spec.sourceType || 'agent',
       sourceName: spec.sourceName || spec.agent || 'agent',
       clientHostPid: spec.clientHostPid || null,
+      ...(preset.fallbacks !== undefined ? { routeFallbacks: preset.fallbacks } : {}),
     };
     const created = await createSession({
       cwd: spec.cwd || process.cwd(),
@@ -45,6 +47,22 @@ export function createAgentChildFactory({ registry, rehydrateAgentSessions, crea
       toolMode: 'full',
       sessionProfile,
     });
+    try {
+      registry.assertAdmission(parentSessionId, parentEpoch);
+    } catch (error) {
+      // The parent was cancelled while the runtime was being created: close it
+      // like any cancelled child instead of leaving it unlinked and open.
+      try {
+        const entry = await entryForSession?.(created.sessionId, {
+          cwd: spec.cwd || process.cwd(),
+          provider,
+          model,
+          toolMode: 'full',
+        });
+        await entry?.runtime?.closeCanonicalSession?.('parent cancelled during agent creation', { tombstone: false });
+      } catch {}
+      throw error;
+    }
     const descriptor = registry.linkAgentDescriptor({
       id: created.sessionId,
       ...sessionProfile,

package/src/standalone/session-service/agent-tree/agent-registry.mjs

@@ -6,6 +6,8 @@ export const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
 export function createAgentRegistry() {
   const agentSessions = new Map();
   const agentChildren = new Map();
+  const cancellationCounts = new Map();
+  const cancellationEpochs = new Map();
 
   function linkAgentDescriptor(descriptor) {
     const sessionId = String(descriptor?.id || '').trim();
@@ -54,6 +56,27 @@ export function createAgentRegistry() {
   }
 
   return {
+    assertAdmission(id, epoch = cancellationEpochs.get(id) || 0) {
+      if (cancellationCounts.has(id) || (cancellationEpochs.get(id) || 0) !== epoch) {
+        throw new Error(`agent session ${id} was cancelled during admission`);
+      }
+      return epoch;
+    },
+    beginCancellation(ids) {
+      for (const id of ids) {
+        cancellationCounts.set(id, (cancellationCounts.get(id) || 0) + 1);
+        cancellationEpochs.set(id, (cancellationEpochs.get(id) || 0) + 1);
+      }
+      return () => {
+        for (const id of ids) {
+          const remaining = (cancellationCounts.get(id) || 0) - 1;
+          if (remaining > 0) cancellationCounts.set(id, remaining);
+          else cancellationCounts.delete(id);
+        }
+      };
+    },
+    isCancelling: (id) => cancellationCounts.has(id),
+    cancellationEpoch: (id) => cancellationEpochs.get(id) || 0,
     linkAgentDescriptor,
     agentDescendantSessionIds,
     get: (sessionId) => agentSessions.get(String(sessionId || '').trim()),
@@ -68,6 +91,8 @@ export function createAgentRegistry() {
     clear() {
       agentSessions.clear();
       agentChildren.clear();
+      cancellationCounts.clear();
+      cancellationEpochs.clear();
     },
   };
 }

package/src/standalone/session-service/agent-tree/agent-turns.mjs

@@ -14,7 +14,12 @@ export function createAgentTurns({
   takeWatchdogStop,
   takeCancelTranscript,
 }) {
-  const createAgentChild = createAgentChildFactory({ registry, rehydrateAgentSessions, createSession });
+  const createAgentChild = createAgentChildFactory({
+    registry,
+    rehydrateAgentSessions,
+    createSession,
+    entryForSession,
+  });
 
   // The turn was stopped (progress watchdog or cancellation): rethrow its error
   // carrying the assistant text the turn produced, so the owner still gets a
@@ -35,6 +40,7 @@ export function createAgentTurns({
   async function runAgentTurn({ session, prompt, context = null, onToolResult, onTerminalResult } = {}) {
     await rehydrateAgentSessions();
     const sessionId = String(session?.id || session || '').trim();
+    const cancelEpoch = registry.assertAdmission(sessionId);
     const descriptor = registry.get(sessionId);
     if (!descriptor || descriptor.closed) {
       throw new Error(`agent session ${sessionId || '(empty)'} is closed`);
@@ -46,6 +52,7 @@ export function createAgentTurns({
       toolMode: 'full',
     });
     const target = entry.runtime.submitAndWait;
+    registry.assertAdmission(sessionId, cancelEpoch);
     if (typeof target !== 'function') {
       throw new TypeError('session runtime must implement submitAndWait');
     }
@@ -55,6 +62,7 @@ export function createAgentTurns({
     // Transcript length before this turn: where a watchdog stop's partial
     // output starts.
     const { messageCount: messageStart } = await entry.runtime.readModelMessages(Number.MAX_SAFE_INTEGER);
+    registry.assertAdmission(sessionId, cancelEpoch);
     descriptor.status = 'running';
     descriptor.stage = 'running';
     descriptor.updatedAt = Date.now();

package/src/standalone/session-service/agent-tree.mjs

@@ -109,9 +109,34 @@ export function createAgentTree({
     canRun: (session) => Boolean(registry.get(session?.id)),
     createChild: createAgentChild,
     runTurn: runAgentTurn,
+    /** A model or tuning change for a reused child goes through the session's
+     *  own route API: saved at once, applied from the next turn (never refused
+     *  because a turn is running). `route` may be partial; the route write
+     *  completes it against the latest selected route. The descriptor follows
+     *  the selected route. */
+    async setRoute({ session, route }) {
+      const descriptor = registry.get(session?.id);
+      if (!descriptor || descriptor.closed) throw new Error('agent session is closed');
+      const entry = await entryForSession(descriptor.id, {
+        cwd: descriptor.cwd,
+        provider: descriptor.provider,
+        model: descriptor.model,
+        toolMode: 'full',
+      });
+      try {
+        const applied = await entry.runtime.setRoute({ ...route, sessionOnly: true });
+        descriptor.provider = applied?.provider || route.provider || descriptor.provider;
+        descriptor.model = applied?.model || route.model || descriptor.model;
+        descriptor.updatedAt = Date.now();
+        return applied;
+      } finally {
+        retainUnwatched(entry, 'agent route change');
+      }
+    },
     async enqueueTurn({ session, prompt, context = null }) {
       const descriptor = registry.get(session?.id);
       if (!descriptor || descriptor.closed) throw new Error('agent session is closed');
+      const cancelEpoch = registry.assertAdmission(descriptor.id);
       const runtime = sessionOwner(descriptor.id)?.runtime;
       if (!runtime || !stateBusy(runtime.getState())) return null;
       const accepted = await runtime.submitAsync(String(prompt || ''), {
@@ -122,6 +147,7 @@ export function createAgentTree({
         transcriptMeta: { sender: 'lead' },
       });
       if (accepted === false) throw new Error('agent follow-up was not accepted');
+      registry.assertAdmission(descriptor.id, cancelEpoch);
       return { queueDepth: runtime.getState()?.queued?.length ?? null };
     },
   });
@@ -167,9 +193,9 @@ export function createAgentTree({
       if (handoff) descriptor.lastHandoff = handoff;
       return handoff;
     },
-    async closeSession(sessionId, reason = 'agent session closed') {
+    async closeSession(sessionId, reason = 'agent session closed', options = {}) {
       await rehydrateAgentSessions();
-      return cancelAgentTree(sessionId, reason);
+      return cancelAgentTree(sessionId, reason, options);
     },
     unloadSessionRuntime: (sessionId) => {
       progress.delete(sessionId);

package/src/standalone/session-service/entries/session-loads.mjs

@@ -6,6 +6,7 @@
 // converge on one runtime.
 
 export function createSessionLoads({
+  pendingViewers,
   sessionExists,
   log,
   assertAvailable,
@@ -20,12 +21,21 @@ export function createSessionLoads({
   const sessionLoads = new Map(); // sessionId -> Promise<entry>
 
   function getOrCreateSessionEntry(sessionId, create) {
-    const owner = sessionOwner(sessionId);
-    if (owner) return Promise.resolve(owner);
     const inFlight = sessionLoads.get(sessionId);
     if (inFlight) return inFlight;
     const loading = Promise.resolve()
-      .then(create)
+      .then(async () => {
+        const owner = sessionOwner(sessionId);
+        if (owner) {
+          if ((await owner.runtime.isSessionTerminal?.()) !== true) return owner;
+          if (owner.subscribers?.size) {
+            if (!pendingViewers.has(sessionId)) pendingViewers.set(sessionId, new Set());
+            for (const subscriber of owner.subscribers) pendingViewers.get(sessionId).add(subscriber);
+          }
+          await destroy(owner, 'replace terminal runtime', { keepBackgroundWork: true, announce: false });
+        }
+        return create();
+      })
       .finally(() => {
         if (sessionLoads.get(sessionId) === loading) sessionLoads.delete(sessionId);
       });
@@ -84,11 +94,12 @@ export function createSessionLoads({
    *  flight), or null where answering would take a fresh load. */
   async function hostedEntryForSession(sessionId) {
     assertAvailable();
+    if (sessionLoads.has(sessionId)) return sessionLoads.get(sessionId);
     const owner = sessionOwner(sessionId);
-    if (owner) return owner;
+    if (owner) return (await owner.runtime.isSessionTerminal?.()) === true ? null : owner;
     const external = await bindExternalSessionView(sessionId);
     const acquiredOwner = sessionOwner(sessionId);
-    if (acquiredOwner) return acquiredOwner;
+    if (acquiredOwner) return (await acquiredOwner.runtime.isSessionTerminal?.()) === true ? null : acquiredOwner;
     if (external?.runtime?.externalAction === true) return external;
     return sessionLoads.get(sessionId) || null;
   }

package/src/standalone/session-service/entries.mjs

@@ -70,6 +70,7 @@ export function createSessionEntries({
     publishExternalSessionState,
   });
   const loads = createSessionLoads({
+    pendingViewers,
     sessionExists,
     log,
     assertAvailable: lifecycle.assertAvailable,

package/src/standalone/session-service/projection/transcript-window.mjs

@@ -386,3 +386,42 @@ export async function loadLiveTranscriptHead(entry, sessionId, readStoredSession
   view.headOlder = from > 0 || stored.transcriptHasOlder === true;
   return true;
 }
+
+/** A one-shot range must not grow or rebudget an attached desktop's window. */
+export async function readTranscriptRange(entry, sessionId, readStoredSession, { offset, limit }) {
+  if (
+    !Number.isSafeInteger(offset) ||
+    offset < 0 ||
+    !Number.isInteger(limit) ||
+    limit < 1 ||
+    limit > 100 ||
+    !Number.isSafeInteger(offset + limit)
+  )
+    throw new TypeError('invalid transcript range');
+  const requested = offset + limit;
+  let snapshot;
+  if (entry) {
+    const state = entry.runtime.getState();
+    const isolated = { runtime: { getState: () => state } };
+    requestLiveTranscriptWindow(isolated, { limit: requested, byteBudget: null, pageBase: 0 });
+    windowTranscriptSnapshot(isolated, state);
+    isolated.transcriptView.paged = true;
+    await loadLiveTranscriptHead(isolated, sessionId, readStoredSession);
+    snapshot = windowTranscriptSnapshot(isolated, state);
+  } else {
+    snapshot = await readStoredSession(sessionId, { transcriptItemLimit: requested });
+  }
+  if (!snapshot) throw new Error(`session ${sessionId} is not available`);
+  const source = snapshot.items || [];
+  if (offset >= source.length && snapshot.transcriptHasOlder) {
+    throw new Error('session: requested history is not available in the retained projection');
+  }
+  const end = Math.max(0, source.length - offset);
+  const start = Math.max(0, end - limit);
+  return {
+    sessionId,
+    offset,
+    items: sanitizeForWire(source.slice(start, end)),
+    hasOlder: start > 0 || snapshot.transcriptHasOlder === true,
+  };
+}