mixdog 1.2.2 → 1.2.4

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

@@ -15,10 +15,12 @@ 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';
 import { createQuotaResumeLane } from '../tui/session/quota-resume.mjs';
+import { createGitHeadWatcher } from '../runtime/shared/worktrees/git-head.mjs';
 import { publicQuotaResume, quotaResumeEntry } from '../runtime/shared/quota-resume-store.mjs';
 import { createSessionApi } from '../tui/session/session-api.mjs';
 import { createSessionDraftStore } from '../tui/session/draft-store.mjs';
@@ -27,24 +29,60 @@ 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,
 // busy-queue enqueue/drain). Quiet by default so it can never tear through
 // the alternate-screen render; enable with MIXDOG_TUI_DEBUG=1.
-import { tuiDebug, nextId, createTranscriptSpillBuffer } from '../tui/session/transcript-spill.mjs';
+import {
+  tuiDebug,
+  nextId,
+  createTranscriptSpillBuffer,
+  sweepStaleTranscriptSpillDirsOnce,
+} from '../tui/session/transcript-spill.mjs';
 
 const SESSION_RUNTIME_MODULE = '../mixdog-session-runtime.mjs';
 
 // Shared across create calls so concurrent session startups import the
 // runtime graph once.
 let sessionRuntimeModulePromise = null;
+let sessionRuntimeImporter = () => import(SESSION_RUNTIME_MODULE);
 function importSessionRuntimeModule() {
-  sessionRuntimeModulePromise ??= import(SESSION_RUNTIME_MODULE);
+  // A failed import is forgotten so the next caller retries lazily.
+  sessionRuntimeModulePromise ??= Promise.resolve()
+    .then(() => sessionRuntimeImporter())
+    .catch((error) => {
+      sessionRuntimeModulePromise = null;
+      throw error;
+    });
   return sessionRuntimeModulePromise;
 }
 
+/**
+ * Background warm-up for the daemon (scheduled after the ready signal): loads
+ * the session-runtime module tree and runs the one-per-process transcript
+ * spill sweep, so the first session.create pays for neither. Failures are
+ * swallowed — create falls back to the same lazy import.
+ */
+export async function warmLocalSessionRuntime() {
+  try {
+    await importSessionRuntimeModule();
+    // Separate turn: let queued I/O run between the import and the sync sweep.
+    await new Promise((resolve) => setImmediate(resolve));
+    sweepStaleTranscriptSpillDirsOnce();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Test seam: replace the dynamic import of the session-runtime module. */
+export function setSessionRuntimeImporterForTest(importer) {
+  sessionRuntimeImporter = importer || (() => import(SESSION_RUNTIME_MODULE));
+  sessionRuntimeModulePromise = null;
+}
+
 const TOOL_APPROVAL_TIMEOUT_MS = (() => {
   const value = Number(process.env.MIXDOG_TOOL_APPROVAL_TIMEOUT_MS);
   return Number.isFinite(value) && value > 0 ? Math.max(1000, Math.round(value)) : 120_000;
@@ -72,7 +110,6 @@ export { parseBackgroundTaskEnvelope } from '../tui/session/agent-envelope.mjs';
  */
 export function createRuntimePulse({
   flags,
-  liveShareMirroring,
   getState,
   getPublishedState,
   set,
@@ -98,16 +135,9 @@ export function createRuntimePulse({
     if (!set(changed)) emit();
     return true;
   };
-  return () => {
+  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(),
@@ -115,6 +145,12 @@ export function createRuntimePulse({
       ...agentStatusState(),
     });
   };
+  /** Publishes just the workspace (a HEAD change): no stats or agent recompute. */
+  pulse.publishWorkspace = () => {
+    if (flags.disposed || flags.pendingSessionReset) return;
+    publishChanged({ workspace: routeState().workspace });
+  };
+  return pulse;
 }
 
 export async function createLocalSessionRuntime({
@@ -134,6 +170,7 @@ export async function createLocalSessionRuntime({
   sessionProfile,
   worktree,
   executeAgentControl,
+  executeSessionControl,
 } = {}) {
   const startedAt = performance.now();
   bootProfile('session:create:start', { provider: providerName, model, toolMode, remote });
@@ -166,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();
@@ -277,20 +315,28 @@ export async function createLocalSessionRuntime({
       timeoutMs: TOOL_APPROVAL_TIMEOUT_MS,
     }
   );
-  lifecycle.runtimePulseTimer = setInterval(
-    createRuntimePulse({
-      flags,
-      liveShareMirroring: () => bag.liveShareMirroring?.() === true,
-      getState,
-      getPublishedState,
-      set,
-      emit: store.emit,
-      routeState,
-      agentStatusState,
-      syncContextStats,
-    }),
-    2000
-  );
+  const runtimePulse = createRuntimePulse({
+    flags,
+    getState,
+    getPublishedState,
+    set,
+    emit: store.emit,
+    routeState,
+    agentStatusState,
+    syncContextStats,
+  });
+  // A `git switch` from any terminal reaches the island within ~a frame; the
+  // pulse retargets the watch when the session's folder moves.
+  const headWatch = createGitHeadWatcher({
+    getCwd: () => runtime.getLiveWorkspace?.()?.cwd || runtime.cwd,
+    onChange: runtimePulse.publishWorkspace,
+  });
+  headWatch.retarget();
+  lifecycle.unsubscribeGitHeadWatch = headWatch.dispose;
+  lifecycle.runtimePulseTimer = setInterval(() => {
+    headWatch.retarget();
+    runtimePulse();
+  }, 2000);
   lifecycle.runtimePulseTimer.unref?.();
 
   const {
@@ -322,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?.();
     });
@@ -405,8 +456,7 @@ export async function createLocalSessionRuntime({
   Object.assign(bag, createSessionFlow(bag));
   // Runtime-driven completion wakes (no attached surface acked the completion)
   // get the same idle auto-clear as a user submit.
-  lifecycle.unsubscribeCompletionWakeGate =
-    runtime.setCompletionWakeGate?.(() => bag.autoClearBeforeWake()) || null;
+  lifecycle.unsubscribeCompletionWakeGate = runtime.setCompletionWakeGate?.(() => bag.autoClearBeforeWake()) || null;
   Object.assign(
     bag,
     createGoalContinuation({
@@ -423,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-client.mjs

@@ -21,6 +21,7 @@ import { withHeapCap } from '../runtime/shared/heap-cap.mjs';
 import { daemonCrashCaptureDir, daemonDataDir } from '../session-runtime/services/daemon-crash-capture.mjs';
 import { forkDaemonCandidate } from '../session-runtime/services/daemon-candidate.mjs';
 import { daemonOwnerIsStale, proveDaemonOwnerRecord } from './daemon-owner.mjs';
+import { IN_TREE_DAEMON_STOP_GRACE_MS } from './daemon-stop-budget.mjs';
 import { createAttachmentCalls } from './session-client/attachment-calls.mjs';
 import { daemonUnavailableError } from './session-client/daemon-unavailable.mjs';
 import { createLeaseHeartbeat } from './session-client/lease-heartbeat.mjs';
@@ -324,6 +325,12 @@ async function replaceLowerDaemon(discovery, initialHealth, { log, onUpgradeWait
  *  caller then re-reads discovery and attaches to whoever won. The shared fork
  *  and crash capture live in ./daemon-candidate.mjs.
  *  `entry` is a test seam; production always forks the real daemon. */
+// Daemons this process forked into its own process tree (daemonShouldDetach
+// false: the packaged Windows Desktop). Such a child is killed with its
+// launcher (libuv's kill-on-close job), which skips its whole teardown —
+// PostgreSQL stop included — so the launcher's quit stops it first.
+const inTreeDaemons = new Map();
+
 export function spawnDaemonCandidate({ cwd, log, timeoutMs = 30_000, entry = daemonEntry() }) {
   const t0 = performance.now();
   const at = () => Math.round(performance.now() - t0);
@@ -353,6 +360,10 @@ export function spawnDaemonCandidate({ cwd, log, timeoutMs = 30_000, entry = dae
       const forkMs = at();
       child.once('spawn', () => {
         log(`daemon fork: forkMs=${forkMs} spawnEventMs=${at()}`);
+        if (!detached && child.pid) {
+          inTreeDaemons.set(child.pid, child);
+          child.once('exit', () => inTreeDaemons.delete(child.pid));
+        }
       });
     },
     onReady: () => log(`daemon ready at=${at()}ms`),
@@ -634,6 +645,37 @@ export async function shutdownDaemon(
   return true;
 }
 
+/** Launcher quit: a daemon this process forked into its own tree would die
+ *  with it, so ask the serving one to stop (forced — its work cannot outlive
+ *  this tree anyway) and wait, bounded, for every such child's graceful exit.
+ *  One that already unpublished its endpoint is mid-teardown: only waited on.
+ *  False when no such child is alive (detached, or another launcher's). */
+export async function stopInTreeDaemon({
+  timeoutMs = IN_TREE_DAEMON_STOP_GRACE_MS,
+  discovery = readSessionDiscovery(),
+} = {}) {
+  const pids = [...inTreeDaemons.keys()].filter((pid) => isPidAlive(pid));
+  if (!pids.length) return false;
+  if (discovery?.port && pids.includes(Number(discovery.pid))) {
+    try {
+      await request({
+        port: discovery.port,
+        token: discovery.token,
+        method: 'POST',
+        path: '/stop',
+        body: { force: true },
+        timeoutMs: 3000,
+        control: true,
+      });
+    } catch {
+      // Past its front door already: only the wait remains.
+    }
+  }
+  const deadline = Date.now() + Math.max(1, Number(timeoutMs) || IN_TREE_DAEMON_STOP_GRACE_MS);
+  while (pids.some((pid) => isPidAlive(pid)) && Date.now() < deadline) await delay(50);
+  return !pids.some((pid) => isPidAlive(pid));
+}
+
 export async function shutdownDaemonForRuntimeRoot(root, options = {}) {
   const runtimeRoot = String(root || '').trim();
   if (!runtimeRoot) return false;

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',
@@ -30,6 +33,7 @@ export const SESSION_READ_ACTIONS = Object.freeze([
   'getQuotaAutoResume',
   'getQuotaHistory',
   'getRecapSettings',
+  'getSessionTitleSettings',
   'getWebSearchRoute',
   'getSettingsSnapshot',
   'getSystemShell',
@@ -41,9 +45,11 @@ export const SESSION_READ_ACTIONS = Object.freeze([
   'inspectHuggingFaceModel',
   'getLocalProviderModelDetails',
   'getSessionReviewDiff',
+  'getSessionReviewFilePatch',
   'getSessionUsage',
   'getTurnChanges',
   'getTurnReviewDiff',
+  'getTurnReviewFilePatch',
   'getTurnLiveness',
   'getUpdateSettings',
   'getUpdateStatus',
@@ -68,6 +74,7 @@ export const SESSION_READ_ACTIONS = Object.freeze([
   'listProviders',
   'listWebSearchModels',
   'listThemes',
+  'listShellJobs',
   'listWorkflows',
   'mcpStatus',
   'pluginsStatus',
@@ -84,6 +91,7 @@ export const SESSION_CONFIGURE_ACTIONS = Object.freeze([
   'addPlugin',
   'addSkill',
   'agentControl',
+  'askSide',
   'authenticateProvider',
   'beginOAuthProviderLogin',
   'beginMcpOAuthLogin',
@@ -93,6 +101,7 @@ export const SESSION_CONFIGURE_ACTIONS = Object.freeze([
   'cancelOAuthProviderLogin',
   'cancelMcpOAuthLogin',
   'cancelConversationImport',
+  'cancelSide',
   'checkForUpdate',
   'clear',
   'compact',
@@ -110,6 +119,7 @@ export const SESSION_CONFIGURE_ACTIONS = Object.freeze([
   'removeCustomProvider',
   'updateCustomProviderModel',
   'testCustomProvider',
+  'checkCustomProviderKeyEnv',
   'discoverCustomProviderModels',
   'deleteSession',
   'deleteWebhook',
@@ -188,12 +198,14 @@ export const SESSION_CONFIGURE_ACTIONS = Object.freeze([
   'startLocalProviderModelMaintenance',
   'deleteLocalProviderModel',
   'setMediaDefault',
+  'setMediaPin',
   'setModel',
   'setOutputStyle',
   'setPluginEnabled',
   'setProfile',
   'setProgressHint',
   'setRecapEnabled',
+  'setAiSessionTitles',
   'setRoute',
   'setScheduleEnabled',
   'setWebSearchRoute',
@@ -212,6 +224,7 @@ export const SESSION_CONFIGURE_ACTIONS = Object.freeze([
   'startConversationImport',
   'startMediaJob',
   'stopShellJob',
+  'releaseShellJob',
   'switchContext',
   'taskControl',
   'testWebhook',
@@ -226,6 +239,7 @@ export const SESSION_CONFIGURE_ACTIONS = Object.freeze([
   'selectBranch',
   'selectProjectBranch',
   'mergeProjectBranch',
+  'manageProjectBranch',
   'requestWorktree',
   'mergeWorkspace',
   'removeWorktree',

package/src/standalone/session-proxy/projection.mjs

@@ -8,6 +8,35 @@
  */
 import { applySessionStatePatch } from '../session-state-patch.mjs';
 
+// Desktop-only live fields: `streamingPartial` is the unfinished streamed
+// line the desktop paints ahead of the line-gated tail. This terminal view
+// keeps the line-gated text, so it never holds the field nor re-renders for it.
+const DESKTOP_ONLY_FIELDS = ['streamingPartial'];
+
+function terminalState(full) {
+  if (!full || typeof full !== 'object' || !DESKTOP_ONLY_FIELDS.some((key) => Object.hasOwn(full, key))) return full;
+  const next = { ...full };
+  for (const key of DESKTOP_ONLY_FIELDS) delete next[key];
+  return next;
+}
+
+/** The patch without desktop-only fields, or null when nothing else moved. */
+function terminalPatch(patch) {
+  const set = patch.set && typeof patch.set === 'object' ? patch.set : {};
+  const remove = Array.isArray(patch.remove) ? patch.remove : [];
+  if (!patch.partialAppend && !DESKTOP_ONLY_FIELDS.some((key) => Object.hasOwn(set, key) || remove.includes(key))) {
+    return patch;
+  }
+  const nextSet = { ...set };
+  for (const key of DESKTOP_ONLY_FIELDS) delete nextSet[key];
+  const nextRemove = remove.filter((key) => !DESKTOP_ONLY_FIELDS.includes(key));
+  if (Object.keys(nextSet).length === 0 && nextRemove.length === 0 && !patch.itemsAppend && !patch.itemsPrepend) {
+    return null;
+  }
+  const { partialAppend: _desktopOnly, ...rest } = patch;
+  return { ...rest, set: nextSet, remove: nextRemove };
+}
+
 export function createProjection({ binding, log }) {
   let state = {};
   let revision = 0;
@@ -40,7 +69,7 @@ export function createProjection({ binding, log }) {
     const incomingRevision = Number(body.revision);
     if (revisionAttachment !== sourceAttachment || revisionSessionId !== binding.sessionId) {
       if (body.full === undefined || body.full === null) return false;
-      state = body.full;
+      state = terminalState(body.full);
       revision = Number.isFinite(incomingRevision) ? incomingRevision : 0;
       revisionAttachment = sourceAttachment;
       revisionSessionId = binding.sessionId;
@@ -49,7 +78,7 @@ export function createProjection({ binding, log }) {
     }
     if (Number.isFinite(incomingRevision) && incomingRevision < revision) return true;
     if (body.full !== undefined && body.full !== null) {
-      state = body.full;
+      state = terminalState(body.full);
       revision = Number.isFinite(incomingRevision) ? incomingRevision : revision;
       emit();
       return true;
@@ -57,8 +86,16 @@ export function createProjection({ binding, log }) {
     if (body.patch) {
       if (Number(body.revision) === revision && Number(body.baseRevision) === revision - 1) return true;
       if (Number(body.baseRevision) !== revision) return false;
-      state = applySessionStatePatch(state, body.patch);
+      const patch = terminalPatch(body.patch);
+      // Only a desktop-only field moved: the terminal view advances silently.
+      if (!patch) {
+        revision = Number(body.revision) || revision;
+        return true;
+      }
+      const patched = applySessionStatePatch(state, patch);
+      if (!patched) return false;
       revision = Number(body.revision) || revision;
+      state = patched;
       emit();
       return true;
     }
@@ -76,7 +113,7 @@ export function createProjection({ binding, log }) {
   return {
     // The create result seeds the projection for the current binding.
     seed(created) {
-      state = created?.full ?? {};
+      state = terminalState(created?.full ?? {});
       revision = Number(created?.revision) || 0;
       revisionAttachment = binding.attachment;
       revisionSessionId = binding.sessionId;

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

@@ -50,6 +50,20 @@ export function createInlineBootLoaders({
     return localModulePromise;
   }
 
+  // Background warm-up of the session-local module graph. Independent of the
+  // keychain gate (the ESM cache makes the later localModule() import free);
+  // never throws — a failed warm-up leaves create on its lazy path.
+  async function warmLocalRuntime() {
+    if (isClosed()) return false;
+    try {
+      const module = await loadLocalModule();
+      if (isClosed()) return false;
+      return (await module.warmLocalSessionRuntime?.()) !== false;
+    } catch {
+      return false;
+    }
+  }
+
   function agentGraph() {
     agentGraphPromise ??= measured('agent-dispatch-graph-import', () => {
       assertOpen();
@@ -92,5 +106,5 @@ export function createInlineBootLoaders({
     await tracked;
   }
 
-  return { prewarmKeychain, localModule, agentGraph, prepareAgentProviders };
+  return { prewarmKeychain, warmLocalRuntime, localModule, agentGraph, prepareAgentProviders };
 }

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 {
@@ -74,6 +76,7 @@ export function createInlineSessionRuntimeHost({
   return {
     create,
     prewarmKeychain: loaders.prewarmKeychain,
+    warmLocalRuntime: loaders.warmLocalRuntime,
     agentDispatch: dispatch.agentDispatch,
     async agentControl(args = {}, context = {}) {
       if (closed) throw new Error('session runtime host is closed');

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 };