mixdog 1.4.1 → 1.4.2

package/src/session-runtime/turn/agent-ops.mjs

@@ -72,6 +72,27 @@ export function createAgentOps(deps) {
     });
   }
 
+  // `/stop`: the background shells this session would stop, then stopping all
+  // of them through the same per-task cancel.
+  async function listStoppableShellJobs() {
+    const session = getSession();
+    const { listStoppableShellJobs: list } = await import(
+      '../../runtime/agent/orchestrator/tools/builtin/task-tool.mjs'
+    );
+    return {
+      jobs: list({ callerSessionId: session?.id || null, clientHostPid: session?.clientHostPid || process.pid }),
+    };
+  }
+
+  async function stopShellJobs() {
+    const session = getSession();
+    const { stopBackgroundShellJobs } = await import('../../runtime/agent/orchestrator/tools/builtin/task-tool.mjs');
+    return stopBackgroundShellJobs({
+      callerSessionId: session?.id || null,
+      clientHostPid: session?.clientHostPid || process.pid,
+    });
+  }
+
   // Explicit user force-release ("Release anyway") of a shell job whose
   // termination is unconfirmed: drops its workspace hold. The surface has
   // already asked the user to confirm. The caller session's own holds, and
@@ -147,6 +168,8 @@ export function createAgentOps(deps) {
     agentControl,
     taskControl,
     stopShellJob,
+    listStoppableShellJobs,
+    stopShellJobs,
     releaseShellJob,
     listShellJobs,
     onNotification,

package/src/session-runtime/workflow-agents-api/agent-connectors.mjs

@@ -4,6 +4,9 @@ import {
   assertConnectorPolicyNotWidened,
   CONNECTOR_PERMISSIONS,
   connectorEnabled,
+  connectorGroupId,
+  connectorToolEntries,
+  connectorToolPermission,
   DENY_ALL_CONNECTORS,
   migrateLegacyConnectorPolicy,
   NO_WIDEN_MESSAGE,
@@ -108,8 +111,8 @@ export function createAgentConnectorsApi(deps, editor) {
     return getAgentConnectors(agentId);
   }
 
-  // Older per-tool overrides keep working (the profile no longer shows them):
-  // `permission` null drops the tool's entry, so the tool is auto again.
+  // One tool's permission (the profile's tool list, getAgentConnectorTools):
+  // `permission` null drops the tool's entry, so the tool is on its default again.
   async function setAgentConnectorToolPermission(agentId, connectorId, toolName, permission, options) {
     if (permission != null && !CONNECTOR_PERMISSIONS.includes(permission)) {
       throw new Error(`permission must be one of ${CONNECTOR_PERMISSIONS.join(', ')}`);
@@ -117,19 +120,25 @@ export function createAgentConnectorsApi(deps, editor) {
     const server = requireId(connectorId, 'connector id');
     const tool = requireId(toolName, 'tool name');
     const policy = editablePolicy(agentId);
-    const own = { ...policy.tools[server] };
+    // The accounts of one connector (`gmail`, `gmail-2`…) share the permission,
+    // stored once under the connector's id; an entry an account kept of its own
+    // for this tool goes in the same write.
+    const group = connectorGroupId(server);
+    const tools = Object.fromEntries(
+      Object.entries(policy.tools).map(([id, entries]) => {
+        if (id === group || connectorGroupId(id) !== group) return [id, entries];
+        const { [tool]: _dropped, ...rest } = entries;
+        return [id, rest];
+      })
+    );
+    const own = { ...tools[group] };
     if (permission == null) delete own[tool];
     else own[tool] = permission;
+    tools[group] = own;
     if (options?.noWiden) {
-      assertConnectorPolicyNotWidened(editor.getAgentConnectorPolicy(agentId), {
-        off: policy.off,
-        tools: { ...policy.tools, [server]: own },
-      });
+      assertConnectorPolicyNotWidened(editor.getAgentConnectorPolicy(agentId), { off: policy.off, tools });
     }
-    return editor.setAgentConnectorPolicy(
-      agentId,
-      storedConnectorPolicy({ off: policy.off, tools: { ...policy.tools, [server]: own } })
-    );
+    return editor.setAgentConnectorPolicy(agentId, storedConnectorPolicy({ off: policy.off, tools }));
   }
 
   // A card's "항상 허용" for a connector tool saves through this same writer.
@@ -149,6 +158,34 @@ export function createAgentConnectorsApi(deps, editor) {
       .sort((a, b) => a.connector.localeCompare(b.connector) || a.tool.localeCompare(b.tool));
   }
 
+  /** `[{ connector, tool, permission, explicit }]`: each installed connector's
+   *  tools (the connected server's own, and any the agent's policy names) with
+   *  the permission the agent has for the tool itself, so a connector switched
+   *  off does not change it, and whether that is an entry of its own policy
+   *  rather than the tool's default. The profile's per-tool editor reads it. */
+  function getAgentConnectorTools(agentId) {
+    const { tools } = editablePolicy(agentId);
+    return installedIds().flatMap((connector) => {
+      const group = connectorGroupId(connector);
+      const accounts = Object.entries(tools).filter(([id]) => connectorGroupId(id) === group);
+      const names = new Set([
+        ...listConnectorTools(connector).map(({ name }) => name),
+        ...accounts.flatMap(([, entries]) => Object.keys(entries)),
+      ]);
+      // Accounts share one permission (stored under the connector); entries an
+      // account kept of its own follow the topmost.
+      return [...names].map((tool) => ({
+        connector,
+        tool,
+        permission: connectorToolPermission(
+          { off: [], tools },
+          { mcpServerName: connector, mcpToolName: tool }
+        ),
+        explicit: connectorToolEntries(tools, group, tool).length > 0,
+      }));
+    });
+  }
+
   /** Replace the agent's connector policy (null removes it). With `options.noWiden`
    *  the replacement may not give any tool more authority than the stored policy. */
   async function setAgentConnectors(agentId, connectors, options) {
@@ -279,6 +316,7 @@ export function createAgentConnectorsApi(deps, editor) {
     setAgentConnectorEnabled,
     setAgentConnectorToolPermission,
     getAgentAlwaysAllowedTools,
+    getAgentConnectorTools,
     getProjectConnectors,
     setProjectConnectorEnabled,
     migrateConnectorPolicies,

package/src/session-runtime/workflow-agents-api/agent-route.mjs

@@ -7,6 +7,7 @@ import { ensureProviderEnabled } from '../../runtime/agent/orchestrator/runtime-
 import { resolveRouteContextState, selectionFastCapable } from '../route-state.mjs';
 import {
   canonicalizeAgentRouteStorage,
+  EXPLORE_AGENT_ID,
   isAgentDisabled,
   withAgentDisabled,
 } from '../../runtime/shared/agent-route-config.mjs';
@@ -226,5 +227,13 @@ export function createAgentRouteApi(deps) {
     return stayOff ? { ...routeToSave, id, disabled: true } : routeToSave;
   }
 
-  return { setAgentRoute };
+  // Explore's route decides whether the explore tool exists, so the empty
+  // session rebuilds its tool surface on any change of it.
+  async function setAgentRouteAndRefresh(agentId, next) {
+    const saved = await setAgentRoute(agentId, next);
+    if (agentEditorId(agentId) === EXPLORE_AGENT_ID) await deps.refreshEmptySessionToolPolicy?.();
+    return saved;
+  }
+
+  return { setAgentRoute: setAgentRouteAndRefresh };
 }

package/src/session-runtime/workspace/activity-guards.mjs

@@ -0,0 +1,176 @@
+/**
+ * The activity checks every workspace change runs first: whether the hosted
+ * Lead (its turn, workers and background shells) is idle, and whether other
+ * sessions work in a shared checkout — then holding that checkout so new
+ * turns there wait until the change settles (admission gate).
+ */
+import { worktreeError, worktreeRefusal } from '../../runtime/shared/worktrees/contract.mjs';
+import { isWithin } from '../../runtime/shared/worktrees/paths.mjs';
+import {
+  holdWorkspaceActivity,
+  isExternalCheckout,
+  releaseAll,
+} from '../../runtime/shared/worktrees/activity-gate.mjs';
+import { AGENT_OWNER } from '../../runtime/agent/orchestrator/agent-owner.mjs';
+import { holdCheckoutFolder } from './admission-gate.mjs';
+
+const ACTIVE_STAGES = new Set(['connecting', 'requesting', 'streaming', 'tool_running', 'running', 'cancelling']);
+const BUSY_WORKER_STATES = new Set([...ACTIVE_STAGES, 'starting', 'spawning', 'queued', 'pending']);
+const BUSY_JOB_STATES = new Set(['starting', 'spawning', 'queued', 'pending', 'running']);
+
+const lower = (value) => String(value || '').toLowerCase();
+
+/** @param {object} deps The activity sources of createWorkspaceTransitions. */
+export function createActivityGuards({
+  getActiveTurnCount,
+  agentStatusState,
+  countOwnShellJobs,
+  listLiveSessions,
+  sessionManager,
+  listWorkspaceConsumers,
+  listWorkspaceJobs,
+}) {
+  function isSessionActive(session) {
+    const runtime = sessionManager?.getSessionRuntime?.(session.id);
+    if (runtime?.controller?.signal && !runtime.controller.signal.aborted) return true;
+    return ACTIVE_STAGES.has(lower(runtime?.stage || session.status));
+  }
+
+  const workersOf = (session) =>
+    listLiveSessions().filter(
+      (candidate) =>
+        candidate?.id &&
+        candidate.id !== session.id &&
+        candidate.owner === AGENT_OWNER &&
+        candidate.closed !== true &&
+        (candidate.ownerSessionId === session.id || candidate.parentSessionId === session.id)
+    );
+
+  /**
+   * WORKTREE_BUSY_JOBS while this Lead has a turn, workers or background
+   * shells running (`shellJobs: false` tolerates background shells).
+   */
+  async function assertLeadIdle(session, { ownTurn = false, shellJobs: checkShellJobs = true } = {}) {
+    if (!ownTurn && getActiveTurnCount() > 0) {
+      throw worktreeError('WORKTREE_BUSY_JOBS', 'The session is running a turn; wait for it to finish.', {
+        reason: 'turn',
+      });
+    }
+    const status = agentStatusState?.() || {};
+    const workers = Array.isArray(status.agentWorkers) ? status.agentWorkers : [];
+    const jobs = Array.isArray(status.agentJobs) ? status.agentJobs : [];
+    const busyWorkers = workers.filter(
+      (row) => BUSY_WORKER_STATES.has(lower(row?.status)) || BUSY_WORKER_STATES.has(lower(row?.stage))
+    ).length;
+    const busyJobs = jobs.filter((row) => BUSY_JOB_STATES.has(lower(row?.status))).length;
+    if (busyWorkers || busyJobs) {
+      throw worktreeError('WORKTREE_BUSY_JOBS', undefined, { reason: 'workers', workers: busyWorkers, jobs: busyJobs });
+    }
+    if (!checkShellJobs) return;
+    const ids = new Set([session.id, ...workers.map((row) => row?.sessionId).filter(Boolean)]);
+    for (const worker of workersOf(session)) ids.add(worker.id);
+    const shellJobs = await countOwnShellJobs([...ids]);
+    if (shellJobs > 0) throw worktreeError('WORKTREE_BUSY_JOBS', undefined, { reason: 'shell-jobs', shellJobs });
+  }
+
+  /**
+   * A checkout or merge in the shared checkout `folder` refuses while another
+   * session (not this Lead's own workers) works there, then holds the folder
+   * until the returned release: other sessions' turns that arrive meanwhile
+   * wait (admission gate). `sessionId` null: a session-less (draft) change.
+   * @returns {() => void}
+   */
+  function holdProjectFolder(sessionId, folder, { hold = true } = {}) {
+    const users = listLiveSessions().filter(
+      (candidate) =>
+        candidate?.id &&
+        candidate.id !== sessionId &&
+        candidate.closed !== true &&
+        (!sessionId || (candidate.ownerSessionId !== sessionId && candidate.parentSessionId !== sessionId)) &&
+        typeof candidate.cwd === 'string' &&
+        isWithin(folder, candidate.cwd) &&
+        isSessionActive(candidate)
+    );
+    if (users.length) throw worktreeRefusal('folder-in-use', { sessions: users.map((candidate) => candidate.id) });
+    return holdCheckoutFolder(sessionId, folder, { hold });
+  }
+
+  /** Run `fn` holding the checkout `folder` (holdProjectFolder); released when it settles. */
+  async function withProjectFolder(sessionId, folder, fn) {
+    const release = holdProjectFolder(sessionId, folder);
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Before a carry clears the shared checkout `folder` (held by the caller,
+   * so no new turn starts there): WORKTREE_BUSY_JOBS while any other session
+   * working in it — idle or not, this Lead's workers included — owns a
+   * running background shell (holdProjectFolder already refused running
+   * turns and agents there, assertLeadIdle this Lead's own). Processes
+   * outside Mixdog (editors, watchers) cannot be excluded.
+   */
+  async function assertCheckoutQuiet(session, folder) {
+    const sharing = listLiveSessions()
+      .filter(
+        (candidate) =>
+          candidate?.id &&
+          candidate.id !== session.id &&
+          candidate.closed !== true &&
+          typeof candidate.cwd === 'string' &&
+          isWithin(folder, candidate.cwd)
+      )
+      .map((candidate) => candidate.id);
+    if (!sharing.length) return;
+    const shellJobs = await countOwnShellJobs(sharing);
+    if (shellJobs > 0) throw worktreeRefusal('folder-shell-jobs', { shellJobs });
+  }
+
+  /**
+   * The shared admission of every merge and folder cleanup (manageProjectBranch):
+   * refuses while a session or worker runs in an affected folder, or a
+   * background command does; `removing` refuses while any session still uses
+   * one. Then holds the folders — Mixdog checkouts only; an external checkout
+   * takes no lease from this profile — so new Mixdog work there waits until `run`
+   * settles. `actor`: the session acting on its own checkout, whose own turn
+   * and workers its caller already checked (assertLeadIdle).
+   */
+  async function withManagementFolders(folders, removing, run, { actor = null } = {}) {
+    const release = [];
+    try {
+      for (const folder of [...new Set(folders)].sort()) {
+        release.push(holdProjectFolder(actor, folder, { hold: !isExternalCheckout(folder) }));
+      }
+      release.push(holdWorkspaceActivity(folders, { sessionId: actor }));
+      const stored = await listWorkspaceConsumers();
+      const consumers = new Map(stored.map((session) => [session.id, session]));
+      for (const session of listLiveSessions()) if (session?.closed !== true) consumers.set(session.id, session);
+      const affected = [...consumers.values()].filter((session) =>
+        folders.some((folder) => session.cwd && isWithin(folder, session.cwd))
+      );
+      const blocking = removing
+        ? affected
+        : affected.filter(
+            (session) =>
+              !(actor && [session.id, session.ownerSessionId, session.parentSessionId].includes(actor)) &&
+              isSessionActive(session)
+          );
+      if (blocking.length) throw worktreeRefusal('folder-in-use', { sessions: blocking.map((session) => session.id) });
+      const jobs = await listWorkspaceJobs();
+      if (jobs.some((job) => !job.terminal && folders.some((folder) => isWithin(folder, job.cwd)))) {
+        throw worktreeRefusal('folder-shell-jobs');
+      }
+      if ((await countOwnShellJobs(affected.map((session) => session.id))) > 0) {
+        throw worktreeRefusal('folder-shell-jobs');
+      }
+      return await run([...consumers.keys()]);
+    } finally {
+      releaseAll(release);
+    }
+  }
+
+  return { workersOf, assertLeadIdle, withProjectFolder, assertCheckoutQuiet, withManagementFolders };
+}

package/src/session-runtime/workspace/session-view.mjs

@@ -0,0 +1,149 @@
+/**
+ * The hosted Lead's workspace as the transitions read it: the session this
+ * runtime hosts, its stored (or project-folder) workspace record, the live
+ * view the session snapshot publishes and the branch menu.
+ */
+import { isDeepStrictEqual } from 'node:util';
+import {
+  branchMenuEntries,
+  isWorktreeBound,
+  normalizeSessionWorkspace,
+  worktreeError,
+} from '../../runtime/shared/worktrees/contract.mjs';
+import { samePath } from '../../runtime/shared/worktrees/paths.mjs';
+import { readGitHead } from '../../runtime/shared/worktrees/git-head.mjs';
+import { readSessionWorkspace } from './workspace-state.mjs';
+
+/**
+ * @param {object} deps The host hooks of createWorkspaceTransitions plus its
+ *   `backend()` loader and `pendingWorktree()` (the armed worktree intent).
+ */
+export function createSessionWorkspaceView({
+  getSession,
+  getCurrentCwd,
+  getDesktopSession,
+  createCurrentSession,
+  inspectProject,
+  backend,
+  pendingWorktree,
+}) {
+  function hostedSession(sessionRef) {
+    const session = getSession();
+    const requested = String(sessionRef?.sessionId || '').trim();
+    if (!session?.id || (requested && requested !== session.id)) {
+      throw new Error(`workspace: session ${requested || '(none)'} is not hosted by this runtime.`);
+    }
+    return session;
+  }
+
+  async function ensureSession() {
+    if (!getSession()?.id && typeof createCurrentSession === 'function') await createCurrentSession('workspace');
+    return hostedSession(null);
+  }
+
+  function projectPathOf(session) {
+    const desktop = getDesktopSession?.() || session?.desktopSession;
+    if (desktop?.classification === 'project' && desktop.projectPath) return desktop.projectPath;
+    return session?.cwd || getCurrentCwd();
+  }
+
+  /** The stored record, or the project-folder workspace (revision 0) of a session that never moved. */
+  function currentWorkspace(session) {
+    const stored = readSessionWorkspace(session);
+    if (stored) return stored;
+    const projectPath = projectPathOf(session);
+    return normalizeSessionWorkspace({ projectPath, cwd: getCurrentCwd() || projectPath, revision: 0 });
+  }
+
+  let liveWorkspace = null;
+
+  /**
+   * The workspace the session publishes: a worktree-bound record as stored; a
+   * project-folder session (never moved, back from a worktree, or carrying a
+   * transition stub) with the folder's checked-out branch / detached commit and
+   * repoCommonDir read straight from HEAD — no git process. Null outside a git
+   * repository for a session without a record. Identity-stable while equal.
+   */
+  function getLiveWorkspace() {
+    const session = getSession();
+    const stored = readSessionWorkspace(session);
+    if (isWorktreeBound(stored)) return session.workspace;
+    let base;
+    try {
+      base = stored ?? currentWorkspace(session);
+    } catch {
+      return session?.workspace ?? null;
+    }
+    const head = readGitHead(base.cwd);
+    if (!head) return session?.workspace ?? null;
+    const next = {
+      ...base,
+      repoCommonDir: head.repoCommonDir,
+      branch: head.branch,
+      baseCommit: head.branch ? base.baseCommit : head.commit,
+    };
+    if (!liveWorkspace || !isDeepStrictEqual(liveWorkspace, next)) liveWorkspace = next;
+    return liveWorkspace;
+  }
+
+  /** WORKTREE_PROJECT_MISMATCH unless `repoCommonDir` (when given) is the session Project's repository. */
+  async function sessionProject(session, repoCommonDir) {
+    const workspace = currentWorkspace(session);
+    const project = await inspectProject(workspace.projectPath);
+    if (repoCommonDir && !samePath(repoCommonDir, project.repoCommonDir)) {
+      throw worktreeError(
+        'WORKTREE_PROJECT_MISMATCH',
+        "Managed worktrees belong to this session's Project repository; run the command there.",
+        { projectPath: workspace.projectPath, repoCommonDir }
+      );
+    }
+    return { workspace, project };
+  }
+
+  async function getBranchMenu() {
+    const session = getSession();
+    const workspace = session?.id
+      ? currentWorkspace(session)
+      : normalizeSessionWorkspace({ projectPath: projectPathOf(null), cwd: getCurrentCwd(), revision: 0 });
+    const menu = await (await backend()).listBranchOccupancy({
+      projectPath: workspace.projectPath,
+      sessionId: session?.id || null,
+    });
+    const selectedEntry = workspace.worktreeId ? await (await backend()).findWorktreeContaining(workspace.cwd) : null;
+    // A session outside a managed worktree (the project folder — never moved,
+    // or back from a worktree — or a linked checkout of the selected branch)
+    // is on whatever that folder has checked out now.
+    // Its repository is the project's (a never-moved session has no stored
+    // record), and a detached checkout shows branch null with the commit in
+    // baseCommit — never mistaken for "not a repository".
+    let view = workspace;
+    if (!isWorktreeBound(workspace)) {
+      const project = await inspectProject(workspace.cwd);
+      const checkedOut = project.currentBranch ?? null;
+      view = {
+        ...workspace,
+        repoCommonDir: project.repoCommonDir ?? workspace.repoCommonDir,
+        branch: checkedOut,
+        baseCommit: checkedOut ? workspace.baseCommit : (project.headCommit ?? null),
+      };
+    }
+    return {
+      workspace: view,
+      pendingWorktree: pendingWorktree(),
+      branches: branchMenuEntries(menu.branches, menu.occupancy),
+      occupancy: menu.occupancy,
+      retainedWorktree: selectedEntry ?? menu.retainedWorktree ?? null,
+      // Creation notes of the retained worktree (submodules, include entries).
+      warnings: Array.isArray(menu.retainedWorktree?.warnings) ? [...menu.retainedWorktree.warnings] : [],
+    };
+  }
+
+  return {
+    hostedSession,
+    ensureSession,
+    currentWorkspace,
+    getLiveWorkspace,
+    sessionProject,
+    getBranchMenu,
+  };
+}

package/src/session-runtime/workspace/side-checkouts.mjs

@@ -0,0 +1,203 @@
+/**
+ * Managed checkouts the hosted Lead makes without moving into them: a branch
+ * worktree (`git worktree add`) and the read-only snapshots of its turns,
+ * which the turn's admission release removes once nothing runs in them.
+ */
+import { setTimeout as delay } from 'node:timers/promises';
+import { WORKTREE_SNAPSHOT_KIND, worktreeError } from '../../runtime/shared/worktrees/contract.mjs';
+import { admitTurn } from './admission-gate.mjs';
+
+// A settled turn's snapshot cleanup waits at most 2^5 times its first delay between attempts.
+const SNAPSHOT_BACKOFF_STEPS = 5;
+
+/**
+ * A managed worktree for `branch` without moving the session (`git
+ * worktree add`): retained by this session like a branch it selected, so
+ * entering it later (selectBranch) reuses it. A branch already checked out
+ * elsewhere is WORKTREE_BRANCH_OCCUPIED, except in this session's own
+ * managed worktree, which is returned as it is. `startPoint` (with
+ * `create`): the commit the new branch starts at.
+ */
+async function addBranchWorktree(
+  { hostedSession, sessionProject, backend, runtimeToken, newTxId },
+  { branch, create = false, startPoint = null, confirmLarge = false, txId = '', repoCommonDir = null } = {}
+) {
+  const session = hostedSession(null);
+  const { workspace } = await sessionProject(session, repoCommonDir);
+  const backendApi = await backend();
+  const { occupancy } = await backendApi.listBranchOccupancy({
+    projectPath: workspace.projectPath,
+    sessionId: session.id,
+  });
+  const held = occupancy.find((row) => row.branch === branch && row.kind !== 'free');
+  if (held && !(held.kind === 'session' && held.sessionId === session.id)) {
+    throw worktreeError('WORKTREE_BRANCH_OCCUPIED', `Branch ${branch} is checked out in ${held.path}.`, {
+      branch,
+      path: held.path,
+      kind: held.kind,
+      ...(held.sessionId ? { sessionId: held.sessionId } : {}),
+    });
+  }
+  const resolved = await backendApi.resolveBranchWorkspace({
+    projectPath: workspace.projectPath,
+    branch,
+    create: create === true,
+    startPoint,
+    sessionId: session.id,
+    runtimeToken,
+    txId: String(txId || '').trim() || newTxId(),
+    confirmLarge: confirmLarge === true,
+  });
+  return {
+    path: resolved.path,
+    branch,
+    worktreeId: resolved.entry?.id ?? null,
+    created: resolved.created === true,
+    baseCommit: resolved.entry?.baseCommit ?? null,
+    mergeTarget: resolved.entry?.mergeTarget ?? null,
+  };
+}
+
+/**
+ * Remove this session's snapshot at `path` now; a dirty one only with
+ * `force`, and none while a worker or background shell runs in it.
+ */
+async function removeSnapshot({ hostedSession, backend }, { path, force = false } = {}) {
+  const session = hostedSession(null);
+  const backendApi = await backend();
+  const entry = await backendApi.getWorktreeByPath(path);
+  if (entry?.kind !== WORKTREE_SNAPSHOT_KIND) throw worktreeError('WORKTREE_MISSING', undefined, { path });
+  if (entry.holderSessionId !== session.id) {
+    throw worktreeError(
+      'WORKTREE_BUSY_JOBS',
+      "This snapshot belongs to another session's turn; it is removed when that turn ends, or by a prune.",
+      { reason: 'snapshot-held', sessionId: entry.holderSessionId, entryId: entry.id }
+    );
+  }
+  const removed = await backendApi.removeSnapshotWorktree({ entryId: entry.id, force: force === true });
+  return { ...removed, entryId: entry.id, path: entry.path };
+}
+
+/**
+ * @param {object} deps The session view (hostedSession, sessionProject), the
+ *   `backend()` loader, the runtime identity and the snapshot retry bounds.
+ */
+export function createSideCheckouts({
+  getSession,
+  getCurrentCwd,
+  hostedSession,
+  sessionProject,
+  backend,
+  runtimeToken,
+  newTxId,
+  snapshotRetryMs,
+  snapshotRetryLimit,
+}) {
+  // The creation txIds of the read-only snapshots the current admitted turn
+  // made. Each turn owns its own set, so its cleanup never touches a later
+  // turn's snapshots (a txId, unlike a freed slug, is never reused).
+  let turnSnapshots = null;
+  // The running cleanups of settled turns' snapshots (controller → session id).
+  const snapshotCleanups = new Map();
+  let disposed = false;
+
+  /**
+   * Turn admission (see admission-gate admitTurn); resolves the release. The
+   * release also starts the removal of the read-only snapshots this turn
+   * made — only those (removeTurnSnapshots).
+   */
+  async function admitTurnWorkspace({ signal } = {}) {
+    const release = await admitTurn({ sessionId: getSession()?.id || '', cwd: () => getCurrentCwd() || '', signal });
+    const made = new Set();
+    turnSnapshots = made;
+    return () => {
+      release();
+      if (turnSnapshots === made) turnSnapshots = null;
+      const sessionId = getSession()?.id;
+      if (made.size && sessionId) void removeTurnSnapshots(sessionId, [...made]);
+    };
+  }
+
+  /**
+   * Remove a settled turn's snapshots (by creation `txIds`) once nothing runs
+   * in them: a worker turn or background shell holding a workspace lease
+   * inside one keeps it (manager removeSessionSnapshots reports it `in-use`).
+   * Those are retried with a doubling delay (`snapshotRetryMs`, at most
+   * 2^SNAPSHOT_BACKOFF_STEPS times it) for at most `snapshotRetryLimit`
+   * attempts; a snapshot removal that fails otherwise is not retried. What is
+   * left then — or when the runtime is disposed, the session closes, is
+   * deleted or is no longer the one hosted here — is the prune's and the
+   * startup reconcile's. Admission is not held meanwhile: the removal only
+   * ever names this turn's snapshots.
+   */
+  async function removeTurnSnapshots(sessionId, txIds) {
+    if (disposed) return;
+    const controller = new AbortController();
+    snapshotCleanups.set(controller, sessionId);
+    try {
+      let pending = txIds;
+      for (let attempt = 0; pending.length && attempt < snapshotRetryLimit; attempt++) {
+        if (attempt > 0) {
+          const wait = snapshotRetryMs * 2 ** Math.min(attempt - 1, SNAPSHOT_BACKOFF_STEPS);
+          await delay(wait, undefined, { ref: false, signal: controller.signal });
+        }
+        const session = getSession();
+        if (session?.id !== sessionId || session.closed === true) return;
+        const report = await (await backend()).removeSessionSnapshots(sessionId, { txIds: pending });
+        pending = report.kept.filter((row) => row.reason === 'in-use').map((row) => row.txId);
+      }
+    } catch {
+      // Cancelled, or the backend failed: the rest is the maintenance's.
+    } finally {
+      snapshotCleanups.delete(controller);
+    }
+  }
+
+  /** Stop the snapshot cleanups of `sessionId` (every session's when null). */
+  function cancelSnapshotCleanups(sessionId = null) {
+    for (const [controller, owner] of snapshotCleanups) {
+      if (sessionId === null || owner === sessionId) controller.abort();
+    }
+  }
+
+  /** Runtime teardown: no snapshot cleanup runs on (prune / startup reconcile finish them). */
+  function dispose() {
+    disposed = true;
+    cancelSnapshotCleanups();
+  }
+
+  /**
+   * A read-only snapshot of `commit` for this session's turn (`git worktree
+   * add --detach`): a detached managed checkout no session works in,
+   * removed when the turn settles (and nothing runs in it any more). The
+   * session does not move. Only inside an admitted turn: a snapshot always
+   * belongs to the turn that made it.
+   */
+  async function createSnapshot({ commit = 'HEAD', confirmLarge = false, txId = '', repoCommonDir = null } = {}) {
+    const session = hostedSession(null);
+    const made = turnSnapshots;
+    if (!made) throw new Error('A read-only snapshot belongs to a turn; none is running in this session.');
+    const { workspace } = await sessionProject(session, repoCommonDir);
+    const tx = String(txId || '').trim() || newTxId();
+    const entry = await (await backend()).createSnapshotWorktree({
+      projectPath: workspace.projectPath,
+      sessionId: session.id,
+      runtimeToken,
+      commit,
+      txId: tx,
+      confirmLarge: confirmLarge === true,
+    });
+    made.add(tx);
+    return entry;
+  }
+
+  return {
+    admitTurnWorkspace,
+    addBranchWorktree: (input) =>
+      addBranchWorktree({ hostedSession, sessionProject, backend, runtimeToken, newTxId }, input),
+    createSnapshot,
+    removeSnapshot: (input) => removeSnapshot({ hostedSession, backend }, input),
+    cancelSnapshotCleanups,
+    dispose,
+  };
+}