mixdog 1.2.1 → 1.2.3

package/src/session-runtime/cwd-plugins/cwd-apply.mjs

@@ -21,20 +21,21 @@ export function createCwdApply({
   updateCurrentCwdOverride,
   persistSession,
   onCwdChanged,
+  isProjectFolder,
   clean,
   resolve,
   statSync,
 }) {
   function resolveCwdPath(value) {
     const raw = clean(value);
-    if (!raw) throw new Error('cwd: path is required for action=set');
+    if (!raw) throw new Error('session: path is required for action=set-project');
     const next = resolve(getCurrentCwd() || process.cwd(), raw);
     const stat = statSync(next);
     if (!stat.isDirectory()) throw new Error(`cwd: not a directory: ${next}`);
     return next;
   }
 
-  function persistProjectSelection(session, currentCwd) {
+  function persistProjectSelection(session, currentCwd, classifyByMembership) {
     // A Lead in its worktree keeps the registered Project as projectPath; a
     // switch elsewhere leaves the worktree at a new workspace revision.
     const { workspace, projectPath } = workspaceForProjectSelection(session, currentCwd);
@@ -44,7 +45,13 @@ export function createCwdApply({
     }
     const desktop = getDesktopSession?.() || session?.desktopSession;
     if (desktop && typeof desktop === 'object') {
-      const nextDesktop = { classification: 'project', projectPath };
+      // A desktop/remote move (classifyByMembership) names a registered
+      // Project or the task workspace: outside every registered Project it is
+      // a task again. The model's own set-project keeps any folder it picked.
+      const nextDesktop =
+        classifyByMembership && !isProjectFolder(projectPath)
+          ? { classification: 'task', projectPath: null }
+          : { classification: 'project', projectPath };
       setDesktopSession?.(nextDesktop);
       if (session) session.desktopSession = nextDesktop;
     }
@@ -59,7 +66,7 @@ export function createCwdApply({
   // message history. The live execution cwd is retargeted in place; the BP3
   // session snapshot remains the session-start environment. `onCwdChanged`
   // lets MCP reconnect only the plugin servers that run in the session cwd.
-  function applyResolvedCwd(nextCwd, { persistProjectSelection: persist = false } = {}) {
+  function applyResolvedCwd(nextCwd, { persistProjectSelection: persist = false, classifyByMembership = false } = {}) {
     const resolved = resolve(nextCwd);
     const stat = statSync(resolved);
     if (!stat.isDirectory()) throw new Error(`cwd: not a directory: ${resolved}`);
@@ -70,7 +77,7 @@ export function createCwdApply({
     if (session) session.cwd = currentCwd;
     updateCurrentCwdOverride?.(currentCwd);
     writeLastSessionCwd(currentCwd, session?.clientHostPid);
-    if (persist) persistProjectSelection(session, currentCwd);
+    if (persist) persistProjectSelection(session, currentCwd, classifyByMembership);
     // Lazy mode: before the first turn (e.g. the initial project-selection
     // cwd set), do NOT prewarm — that is exactly the post-first-frame freeze
     // we are avoiding. Once a turn has run, an in-session cwd switch DOES

package/src/session-runtime/internal-tool-executor/ask-user-tool.mjs

@@ -0,0 +1,65 @@
+// ask_user: put 1-4 multiple-choice questions to the user through the session's
+// tool-approval hook (kind: 'question') and report the answers to the model.
+import { validateAskUserQuestions, ASK_USER_MAX_TEXT } from '../../runtime/agent/orchestrator/runtime-core/ask-user-tool-defs.mjs';
+import { createCallerContextResolvers } from './caller-context.mjs';
+
+export const ASK_USER_TIMEOUT_MS = 30 * 60 * 1000;
+export const APPROVAL_TIMED_OUT_REASON = 'approval timed out';
+
+const NO_USER = 'No user is available to answer in this session. Proceed with your best judgment and state the choices you made.';
+const DISMISSED =
+  'User closed the questions without answering. Proceed with your best judgment; ask again only if something new depends on it.';
+const TIMED_OUT = `User did not answer in time. ${DISMISSED}`;
+
+/** Wire answers -> array aligned with questions; invalid entries become null. */
+export function normalizeAskUserAnswers(answers, questions) {
+  const list = Array.isArray(answers) ? answers.slice(0, 4) : [];
+  return questions.map((q, i) => {
+    const entry = list[i];
+    if (!entry || typeof entry !== 'object') return null;
+    const labels = new Set(q.options.map((o) => o.label));
+    const rawSelected = entry.selected == null ? [] : entry.selected;
+    if (!Array.isArray(rawSelected) || !rawSelected.every((l) => typeof l === 'string' && labels.has(l))) return null;
+    if (entry.text != null && (typeof entry.text !== 'string' || entry.text.length > ASK_USER_MAX_TEXT)) return null;
+    const selected = q.multi_select === true ? [...new Set(rawSelected)] : rawSelected.slice(0, 1);
+    const text = typeof entry.text === 'string' ? entry.text.trim() : '';
+    if (!selected.length && !text) return null;
+    return text ? { selected, text } : { selected };
+  });
+}
+
+// Strings are JSON-quoted so a quote inside one cannot end it early; typed
+// text stays apart from the picked labels (`"picked" + "typed" (typed)`).
+export function formatAskUserAnswers(questions, answers) {
+  const quote = (text) => JSON.stringify(text);
+  const parts = questions.map((q, i) => {
+    const a = answers[i];
+    if (!a) return `${quote(q.question)}=(no answer)`;
+    const picked = a.selected.length ? quote(a.selected.join(', ')) : '';
+    const typed = a.text ? `${quote(a.text)} (typed)` : '';
+    return `${quote(q.question)}=${[picked, typed].filter(Boolean).join(' + ')}`;
+  });
+  return `User has answered your questions: ${parts.join('; ')}. You can now continue with these answers in mind.`;
+}
+
+export function createAskUserToolHandlers({ rt }) {
+  const { sessionIdFor } = createCallerContextResolvers(rt);
+  return {
+    ask_user: async (args, { callerCtx }) => {
+      const questions = validateAskUserQuestions(args);
+      const hook = callerCtx?.toolApprovalHook;
+      if (typeof hook !== 'function') return NO_USER;
+      const result = await hook({
+        name: 'ask_user',
+        kind: 'question',
+        args: { questions },
+        reason: '',
+        timeoutMs: ASK_USER_TIMEOUT_MS,
+        sessionId: sessionIdFor(callerCtx),
+        toolCallId: callerCtx?.toolCallId || null,
+      });
+      if (result?.approved === true) return formatAskUserAnswers(questions, normalizeAskUserAnswers(result.answers, questions));
+      return result?.reason === APPROVAL_TIMED_OUT_REASON ? TIMED_OUT : DISMISSED;
+    },
+  };
+}

package/src/session-runtime/internal-tool-executor/bridge-tools.mjs

@@ -40,13 +40,15 @@ export function createBridgeToolHandlers({ rt }) {
     });
   };
 
-  // Read-only: no approval hook, no working directory.
+  // `run` is gated by the exec policy; the elevation approval comes from the
+  // runtime's gate (callerCtx), never from the model's args.
   const terminal = async (args, { callerCtx }) => {
     if (environmentDisabled(callerCtx, 'MIXDOG_FEATURE_TERMINAL')) {
       throw new Error('the terminal tool is disabled in this environment');
     }
     return await executeTerminalTool(args, {
       sessionId: sessionIdFor(callerCtx),
+      elevationApproved: callerCtx?.elevationApproved === true,
       signal: signalFor(callerCtx),
     });
   };

package/src/session-runtime/internal-tool-executor/knowledge-tools.mjs

@@ -1,6 +1,7 @@
 // Tools that read rather than act: web search/fetch, memory, the code graph,
 // the deferred tool catalog, and skill bodies.
 import { refreshDeferredMcpToolCatalog, renderToolSearch } from '../../runtime/agent/orchestrator/runtime-core/tool-catalog.mjs';
+import { resolveDeferredSelectMode } from '../../runtime/agent/orchestrator/session/loop/deferred-call-through.mjs';
 import { dispatchWebSearchRuntimeTool, memoryToolArgsForCaller } from '../runtime-tool-routing.mjs';
 import { createCallerContextResolvers } from './caller-context.mjs';
 
@@ -31,10 +32,16 @@ export function createKnowledgeToolHandlers({
     return await memoryMod.handleToolCall(name, memoryToolArgsForCaller(args, callerCwd), signalFor(callerCtx));
   };
 
-  const toolSearch = (args) => {
-    const surface = activeToolSurface();
-    refreshDeferredMcpToolCatalog(surface, rt.config);
-    return renderToolSearch(args, surface, rt.mode, { mcpStatus });
+  // Catalog tools answer for the calling session's own scope, bridge or
+  // native: a worker sees its own catalog (its own allow/deny), never the
+  // lead's. Only a call that names no session uses the active surface.
+  const scopeSession = (callerCtx) => callerCtx?.callerSession || activeToolSurface();
+  const scopeMode = (session) => session?.deferredSurfaceMode || resolveDeferredSelectMode(session) || rt.mode;
+
+  const toolSearch = (args, { callerCtx } = {}) => {
+    const session = scopeSession(callerCtx);
+    refreshDeferredMcpToolCatalog(session, rt.config);
+    return renderToolSearch(args, session, scopeMode(session), { mcpStatus });
   };
 
   return {

package/src/session-runtime/internal-tool-executor/workspace-tools.mjs

@@ -3,26 +3,35 @@
 import { statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { listProjects } from '../../runtime/shared/projects.mjs';
+import { applySessionSidebarChange } from '../../runtime/shared/session-sidebar-host.mjs';
 import { clean } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 
+const USER_TITLE_ERROR = 'session: the user already titled this session; the title was not changed';
+
 export function createWorkspaceToolHandlers({
   rt,
   goalRuntime,
   agentTool,
   notifyFnForSession,
-  applyResolvedCwd,
   getWorkspaceApi = () => null,
+  getSessionManager = () => null,
+  getLifecycleApi = () => null,
 }) {
   // The Lead's own worktree, on the user's request: the same authority the
   // branch chip menu drives, tolerating the calling turn but nothing else
   // running (workers, background shells).
-  const worktreeAction = async (action, args, callerCtx) => {
-    const workspace = getWorkspaceApi();
-    if (!workspace) throw new Error(`cwd: ${action} is unavailable in this runtime`);
+  const assertLead = (action, callerCtx) => {
     const callerSessionId = callerCtx?.callerSessionId || rt.session?.id || null;
     if (!rt.session?.id || callerSessionId !== rt.session.id) {
-      throw new Error(`cwd: ${action} belongs to the Lead session`);
+      throw new Error(`session: ${action} belongs to the Lead session`);
     }
+    return rt.session.id;
+  };
+
+  const worktreeAction = async (action, args, callerCtx) => {
+    const workspace = getWorkspaceApi();
+    if (!workspace) throw new Error(`session: ${action} is unavailable in this runtime`);
+    assertLead(action, callerCtx);
     const result =
       action === 'merge-worktree'
         ? await workspace.mergeWorkspace({ confirmed: true }, { ownTurn: true })
@@ -35,12 +44,95 @@ export function createWorkspaceToolHandlers({
   };
 
   const WORKTREE_ACTIONS = new Set(['merge-worktree', 'remove-worktree', 'list-worktrees', 'prune-worktrees']);
+  const SIDEBAR_ACTIONS = new Set(['favorite', 'archive']);
 
-  const cwd = async (args, { callerCtx, callerCwd }) => {
-    const action = clean(args?.action || (args?.path ? 'set' : 'get')).toLowerCase();
+  // Sidebar flags only (the desktop's favorite/archive metadata).
+  const sidebarAction = async (action, args, callerCtx) => {
+    const sessionId = assertLead(action, callerCtx);
+    if (typeof args?.value !== 'boolean') throw new Error(`session: value (boolean) is required for action=${action}`);
+    const change = action === 'favorite' ? { favorite: args.value } : { archived: args.value };
+    try {
+      await applySessionSidebarChange(sessionId, change);
+    } catch (error) {
+      throw new Error(`session: ${action} failed (${error?.message || error})`);
+    }
+    return JSON.stringify({ action, sessionId, ...change }, null, 2);
+  };
+
+  const session = async (args, { callerCtx, callerCwd }) => {
+    const action = clean(args?.action || (args?.path ? 'set-project' : 'status')).toLowerCase();
     if (WORKTREE_ACTIONS.has(action)) return worktreeAction(action, args, callerCtx);
+    if (SIDEBAR_ACTIONS.has(action)) return sidebarAction(action, args, callerCtx);
     let currentCwd = callerCwd;
-    if (action === 'list') {
+    if (action === 'status' || action === 'list-projects' || action === 'set-project') assertLead(action, callerCtx);
+    if (action === 'rename') {
+      const sessionId = assertLead(action, callerCtx);
+      if (rt.config?.aiSessionTitles === false) throw new Error('session: AI session titles are disabled in settings');
+      const title = clean(args?.title);
+      if (!title) throw new Error('session: title is required for action=rename');
+      const result = await getSessionManager()?.updateSessionAiTitle(sessionId, title);
+      if (!result?.ok) {
+        throw new Error(
+          result?.reason === 'user-title'
+            ? USER_TITLE_ERROR
+            : `session: rename failed (${result?.reason || 'unavailable'})`
+        );
+      }
+      // Mirror the store's truth onto the live session, never the AI title
+      // itself: a manual rename that landed while the save was awaited wins.
+      const stored = getSessionManager()?.getSession?.(sessionId);
+      if (stored && rt.session?.id === sessionId && stored !== rt.session) {
+        rt.session.title = stored.title;
+        rt.session.titleLocked = stored.titleLocked;
+        rt.session.titleSource = stored.titleSource;
+        rt.session.titleUpdatedAt = stored.titleUpdatedAt;
+      }
+      if (stored && stored.titleSource === 'user') throw new Error(USER_TITLE_ERROR);
+      return JSON.stringify({ action, sessionId, title: result.title }, null, 2);
+    }
+    if (action === 'compact') {
+      const sessionId = assertLead(action, callerCtx);
+      rt.pendingCompactSessionIds ??= new Set();
+      rt.pendingCompactSessionIds.add(sessionId);
+      return JSON.stringify(
+        { action, sessionId, scheduled: true, note: 'Compaction runs right after the current turn finishes.' },
+        null,
+        2
+      );
+    }
+    if (action === 'fork') {
+      const sessionId = assertLead(action, callerCtx);
+      const lifecycle = getLifecycleApi();
+      if (typeof lifecycle?.inheritToNewSession !== 'function') {
+        throw new Error('session: fork is unavailable in this runtime');
+      }
+      const result = await lifecycle.inheritToNewSession(sessionId, {
+        compact: args?.compact === true,
+        titleSuffix: ' (Fork)',
+      });
+      return JSON.stringify(
+        { action, sourceSessionId: sessionId, sessionId: result.sessionId, compacted: result.compacted === true },
+        null,
+        2
+      );
+    }
+    if (action === 'status') {
+      const current = rt.session;
+      return JSON.stringify(
+        {
+          sessionId: callerCtx?.callerSessionId || current?.id || null,
+          title: current?.title || null,
+          titleSource: current?.titleSource || null,
+          cwd: currentCwd,
+          project: current?.workspace?.projectPath || current?.desktopSession?.projectPath || currentCwd,
+          provider: current?.provider || null,
+          model: current?.model || null,
+        },
+        null,
+        2
+      );
+    }
+    if (action === 'list-projects') {
       return JSON.stringify(
         {
           cwd: currentCwd,
@@ -50,18 +142,23 @@ export function createWorkspaceToolHandlers({
         2
       );
     }
-    if (action === 'set') {
+    if (action === 'set-project') {
       const rawPath = clean(args?.path);
-      if (!rawPath) throw new Error('cwd: path is required for action=set');
+      if (!rawPath) throw new Error('session: path is required for action=set-project');
       const nextCwd = resolve(callerCwd || process.cwd(), rawPath);
       const stat = statSync(nextCwd);
-      if (!stat.isDirectory()) throw new Error(`cwd: not a directory: ${nextCwd}`);
-      currentCwd =
-        typeof callerCtx?.setCallerCwd === 'function'
-          ? clean(await callerCtx.setCallerCwd(nextCwd)) || nextCwd
-          : applyResolvedCwd(nextCwd, { persistProjectSelection: true });
-    } else if (action !== 'get') {
-      throw new Error(`cwd: unknown action "${action}"`);
+      if (!stat.isDirectory()) throw new Error(`session: not a directory: ${nextCwd}`);
+      // The Lead's own call: the runtime's Project switch authority admits it
+      // during the calling turn and refuses inside a managed worktree.
+      if (typeof callerCtx?.setCallerCwd === 'function') {
+        currentCwd = clean(await callerCtx.setCallerCwd(nextCwd)) || nextCwd;
+      } else {
+        const workspace = getWorkspaceApi();
+        if (!workspace) throw new Error('session: set-project is unavailable in this runtime');
+        currentCwd = await workspace.switchProject(nextCwd, { ownTurn: true });
+      }
+    } else {
+      throw new Error(`session: unknown action "${action}"`);
     }
     return JSON.stringify(
       {
@@ -74,7 +171,7 @@ export function createWorkspaceToolHandlers({
   };
 
   return {
-    cwd,
+    session,
     goal: async (args, { name, callerCtx }) =>
       await goalRuntime.executeTool(name, args || {}, {
         callerSessionId: callerCtx?.callerSessionId || rt.session?.id || rt.reservedSessionId || null,

package/src/session-runtime/internal-tool-executor.mjs

@@ -6,6 +6,7 @@
  * to channel tools.
  */
 import { clean } from '../runtime/agent/orchestrator/runtime-core/session-text.mjs';
+import { createAskUserToolHandlers } from './internal-tool-executor/ask-user-tool.mjs';
 import { createBridgeToolHandlers } from './internal-tool-executor/bridge-tools.mjs';
 import { createFeatureToolHandlers } from './internal-tool-executor/feature-tools.mjs';
 import { createKnowledgeToolHandlers } from './internal-tool-executor/knowledge-tools.mjs';
@@ -29,12 +30,14 @@ export function createInternalToolExecutor({
   runNativeWebSearch,
   activeToolSurface,
   mcpStatus,
-  applyResolvedCwd,
   skillToolContent,
   getWorkspaceApi,
+  getSessionManager,
+  getLifecycleApi,
 }) {
   const handlers = {
     ...createBridgeToolHandlers({ rt }),
+    ...createAskUserToolHandlers({ rt }),
     ...createFeatureToolHandlers({ rt, setupTool, officeToolsEnabled, mediaToolEnabled, tidyToolEnabled }),
     ...createKnowledgeToolHandlers({
       rt,
@@ -52,8 +55,9 @@ export function createInternalToolExecutor({
       goalRuntime,
       agentTool,
       notifyFnForSession,
-      applyResolvedCwd,
       getWorkspaceApi,
+      getSessionManager,
+      getLifecycleApi,
     }),
   };
 

package/src/session-runtime/lifecycle/cold-heir.mjs

@@ -0,0 +1,188 @@
+/**
+ * src/session-runtime/lifecycle/cold-heir.mjs - the record of a heir that is
+ * NOT opened: a sibling of the source session on the same route, cwd and
+ * Project, persisted to the store and left cold for a later resume.
+ *
+ * The heir starts from the source's own record (same provider/model, tool
+ * surface, system layer, desktop classification) the way /clear's cold fork
+ * does, minus everything that belongs to the source alone: its conversation,
+ * in-flight turn, provider continuation, usage readings, title, worktree and
+ * ownership/lineage links — the heir is a root Lead of its own, linked to the
+ * source only through `inheritedFromSessionId`.
+ */
+import {
+  ensureCodexWireSessionId,
+  mintSessionId,
+} from '../../runtime/agent/orchestrator/session/manager/session-id.mjs';
+import {
+  refreshSessionWorkspaceContext,
+  resetSessionBp3Environment,
+} from '../../runtime/agent/orchestrator/session/manager/prompt-utils.mjs';
+import { buildWorkspacePromptContext } from '../../runtime/agent/orchestrator/session/manager/session-prompt-composition.mjs';
+import {
+  invalidateContextUsageSnapshot,
+  invalidateProviderContextBaseline,
+} from '../../runtime/agent/orchestrator/session/loop/compact-policy.mjs';
+import { deleteSession, evictLiveSession, saveSessionAsync } from '../../runtime/agent/orchestrator/session/store.mjs';
+import { projectWorkspace } from '../../runtime/shared/worktrees/contract.mjs';
+import { writeStderrBestEffort } from '../../runtime/shared/best-effort-stderr.mjs';
+import { replacementSessionCwd } from '../workspace/workspace-state.mjs';
+
+// Per-turn and per-process state of the source: the in-flight turn, its
+// transient serializer-stripped aliases, and one-shot pending work.
+const SOURCE_RUNTIME_FIELDS = [
+  'liveTurnMessages',
+  'toolApprovalHook',
+  '_providerPrefixGuardState',
+  'activeTurnCheckpoint',
+  'remoteAttached',
+  'deferredInitialRefreshPending',
+  'pendingGoalReminder',
+  'goalReminderRevision',
+  'pendingCacheBreakIntent',
+  'contextPressureUnanchoredAfterRestart',
+  'contextPressureUnanchoredReason',
+  // Store read-back projections of the SOURCE file.
+  'storageMtimeMs',
+  'storageSize',
+];
+
+// Identity the source owns: its title (the carry decides the heir's), import
+// provenance (a dedupe key), its own inheritance link (the carry sets the
+// heir's), Codex wire identity, lifecycle provenance (a 'cli-resume' detach
+// hides a row from Recent), and every ownership / lineage / visibility link —
+// a self-link copied from a recovered root Lead would point at the source and
+// classify the heir as an agent-only child.
+const SOURCE_IDENTITY_FIELDS = [
+  'title',
+  'titleLocked',
+  'titleSource',
+  'titleUpdatedAt',
+  'importOrigin',
+  'inheritedFromSessionId',
+  'codexWireSessionId',
+  'detachedReason',
+  'sessionVisibility',
+  'task_id',
+  'taskId',
+];
+
+// The heir is an ordinary, user-visible root Lead owned by nobody but itself,
+// whatever the source's ownership history (same identity a new Lead session
+// or an imported conversation gets).
+const ROOT_LEAD_IDENTITY = Object.freeze({
+  owner: 'cli',
+  agent: 'lead',
+  lane: 'cli',
+  sourceType: 'lead',
+  sourceName: 'main',
+  parentSessionId: null,
+  ownerSessionId: null,
+  visibility: null,
+  agentTag: null,
+  taskType: null,
+  permissionMode: null,
+  scopeKey: null,
+});
+
+/**
+ * The source as of its last committed turn. Mid-turn, `messages` already
+ * holds the in-flight user prompt (pre-committed before the provider call)
+ * while `liveTurnMessages` holds the turn's working transcript; the prompt is
+ * not part of the conversation yet, so it does not travel. Never mutates.
+ */
+export function committedSource(source) {
+  const messages = Array.isArray(source?.messages) ? source.messages : [];
+  const live = source?.liveTurnMessages;
+  if (!Array.isArray(live) || live === messages || messages.at(-1)?.role !== 'user') return source;
+  return { ...source, messages: messages.slice(0, -1) };
+}
+
+/** A fresh, empty heir record of `source` — system layer only, nothing saved. */
+export function buildColdHeir(source, now = Date.now()) {
+  const heir = {
+    ...source,
+    id: mintSessionId(),
+    // The heir runs on the very route that built these blocks; copies, so
+    // the heir never shares a message object with the source.
+    messages: structuredClone((source.messages || []).filter((message) => message?.role === 'system')),
+    closed: false,
+    status: 'idle',
+    generation: 0,
+    createdAt: now,
+    updatedAt: now,
+    lastUsedAt: now,
+    lastHeartbeatAt: null,
+    mcpPid: process.pid,
+    clientHostPid: null,
+    providerState: undefined,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalToolCalls: 0,
+    reasoningUsage: null,
+    totalCachedReadTokens: 0,
+    totalCacheWriteTokens: 0,
+    tokensCumulative: 0,
+    lastInputTokens: 0,
+    lastOutputTokens: 0,
+    lastCachedReadTokens: 0,
+    lastCacheWriteTokens: 0,
+    lastContextTokens: 0,
+    lastContextTokensUpdatedAt: now,
+    lastContextTokensStaleAfterCompact: false,
+    ...ROOT_LEAD_IDENTITY,
+  };
+  for (const key of [...SOURCE_RUNTIME_FIELDS, ...SOURCE_IDENTITY_FIELDS]) delete heir[key];
+  ensureCodexWireSessionId(heir);
+  // The compaction archive sidecar is keyed by the source id.
+  if (heir.compaction?.archive) {
+    heir.compaction = { ...heir.compaction };
+    delete heir.compaction.archive;
+  }
+  // A worktree belongs to the session that created it: like /new, the heir
+  // starts in the Project folder instead of sharing (and on delete, removing)
+  // the source's worktree.
+  const projectFolder = replacementSessionCwd(source);
+  if (projectFolder) {
+    heir.cwd = projectFolder;
+    heir.workspace = projectWorkspace({ projectPath: projectFolder });
+  }
+  // The source's staged working-folder change (its prompt still rooted at an
+  // earlier folder) is the source's own: the heir's prompt is built for the
+  // folder it actually starts in. Project memory follows the Project, which a
+  // worktree shares, so the source's current memory slice carries over.
+  const pending = source.workspaceReroot;
+  delete heir.workspaceReroot;
+  if ((projectFolder || pending) && heir.cwd) {
+    refreshSessionWorkspaceContext(heir, {
+      cwd: heir.cwd,
+      ...buildWorkspacePromptContext(heir, heir.cwd),
+      coreMemoryContext: pending?.target?.coreMemoryContext,
+    });
+  }
+  invalidateContextUsageSnapshot(heir);
+  invalidateProviderContextBaseline(heir);
+  // The `# Session` block names the session it was stamped for; the heir's
+  // first turn stamps its own.
+  resetSessionBp3Environment(heir);
+  return heir;
+}
+
+/**
+ * Persist the heir durably, then drop it from the same-process live cache:
+ * it is a cold session until someone resumes it. A failed save removes the
+ * half-made record and rejects.
+ */
+export async function persistColdHeir(heir) {
+  try {
+    await saveSessionAsync(heir);
+  } catch (error) {
+    try {
+      deleteSession(heir.id);
+    } catch (cleanupError) {
+      writeStderrBestEffort(`[inherit] cleanup of ${heir.id} failed: ${cleanupError?.message || cleanupError}\n`);
+    }
+    throw error;
+  }
+  evictLiveSession(heir.id);
+}