mixdog 1.4.0 → 1.4.2

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

package/src/session-runtime/workspace/transition-runner.mjs

@@ -0,0 +1,188 @@
+/**
+ * The serialized moves of the hosted Lead: every workspace transition (enter
+ * a worktree, run in a branch's checkout, remove the retained worktree) and
+ * the Project switch. Each one is admitted against turns and other workspace
+ * changes, checks the Lead is idle, and journals its steps so a failure puts
+ * back exactly what already moved. Also the input checks the workspace API
+ * shares (worktree name, target, expected revision).
+ */
+import {
+  isWorktreeBound,
+  normalizeSessionWorkspace,
+  worktreeError,
+  worktreeNameError,
+} from '../../runtime/shared/worktrees/contract.mjs';
+import { throwIfAborted } from '../../runtime/shared/worktrees/git.mjs';
+import { beginWorkspaceTransition } from './admission-gate.mjs';
+import { undoAll } from './transition-steps.mjs';
+import { readSessionWorkspace } from './workspace-state.mjs';
+
+const WORKTREE_BOUND_SWITCH =
+  'The session works in a managed worktree; exit the worktree first (switch to a project-folder branch, or merge or remove the worktree) before moving it to another project.';
+
+/** The in-flight marker state of each transition kind. */
+const TRANSITION_STATE = { worktree: 'provisioning', branch: 'switching', 'remove-worktree': 'removing' };
+
+export function validName(name) {
+  if (name === undefined || name === null) return null;
+  const error = worktreeNameError(name);
+  if (error) throw new TypeError(`worktree name is invalid: ${error}`);
+  return name;
+}
+
+function normalizeTarget(target) {
+  const kind = target?.kind;
+  if (kind === 'worktree') return { kind, name: validName(target.name) };
+  if (kind === 'branch') {
+    if (typeof target.branch !== 'string' || !target.branch.trim()) {
+      throw new TypeError('workspace target branch must be a non-empty string.');
+    }
+    return { kind, branch: target.branch.trim(), create: target.create === true };
+  }
+  if (kind === 'remove-worktree') return { kind, force: target.force === true };
+  throw new TypeError('workspace target kind must be branch, worktree or remove-worktree.');
+}
+
+export function validRevision(value) {
+  if (value === undefined || value === null) return undefined;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError('expectedRevision must be a non-negative integer.');
+  }
+  return value;
+}
+
+/** WORKTREE_REVISION_CONFLICT when the caller expected another workspace revision. */
+export function assertRevision(revision, expectedRevision) {
+  if (expectedRevision !== undefined && expectedRevision !== revision) {
+    throw worktreeError('WORKTREE_REVISION_CONFLICT', undefined, { expectedRevision, revision });
+  }
+}
+
+/**
+ * @param {object} deps The session view (hostedSession, currentWorkspace),
+ *   assertLeadIdle, the transition `steps` and the host's cwd hooks.
+ */
+export function createTransitionRunner({
+  getSession,
+  hostedSession,
+  currentWorkspace,
+  assertLeadIdle,
+  steps,
+  newTxId,
+  applyResolvedCwd,
+  getCurrentCwd,
+}) {
+  async function transition(session, target, options = {}) {
+    throwIfAborted(options.signal);
+    const previous = currentWorkspace(session);
+    assertRevision(previous.revision, options.expectedRevision);
+    const txId = String(options.txId || '').trim() || newTxId();
+    const leave = beginWorkspaceTransition(session.id, txId);
+    const hadRecord = Object.hasOwn(session, 'workspace');
+    const stored = session.workspace;
+    const marker = normalizeSessionWorkspace({
+      ...previous,
+      transition: { state: TRANSITION_STATE[target.kind], txId },
+    });
+    session.workspace = marker;
+    const restore = () => {
+      if (hadRecord) session.workspace = stored;
+      else delete session.workspace;
+    };
+    const journal = [];
+    try {
+      await assertLeadIdle(session, { ownTurn: options.ownTurn === true });
+      const run = { signal: options.signal, txId, journal };
+      // A new checkout gets its dependencies prepared at the start of the
+      // first turn a session runs there (runPendingSetup, from its registry entry).
+      if (target.kind === 'worktree') {
+        return await steps.enterWorktree(session, previous, {
+          ...run,
+          name: target.name,
+          nameHint: options.nameHint,
+          confirmLarge: options.confirmLarge,
+          changes: options.changes,
+        });
+      }
+      if (target.kind === 'branch') {
+        return await steps.enterProjectBranch(session, previous, {
+          ...run,
+          branch: target.branch,
+          create: target.create,
+          confirmLarge: options.confirmLarge,
+        });
+      }
+      return await steps.removeRetainedWorktree(session, previous, { ...run, force: target.force });
+    } catch (error) {
+      // Whatever already moved (cwd, record, prompts, worker roots, lease)
+      // goes back exactly; the previous workspace stays authoritative.
+      await undoAll(journal, error);
+      throw error;
+    } finally {
+      if (session.workspace === marker) restore();
+      leave();
+    }
+  }
+
+  /**
+   * The one entry of every transition. `ownTurn` (internal: the Lead's own
+   * tool call) tolerates the calling turn; `txId` keys the creation.
+   */
+  async function runTransition(sessionRef, target, options = {}, { ownTurn = false, txId = '' } = {}) {
+    const session = hostedSession(sessionRef);
+    return transition(session, normalizeTarget(target), {
+      expectedRevision: validRevision(options.expectedRevision),
+      confirmLarge: options.confirmLarge === true,
+      signal: options.signal,
+      ownTurn: ownTurn === true,
+      txId,
+    });
+  }
+
+  async function removeWorktree({ force = false, expectedRevision } = {}, { ownTurn = false } = {}) {
+    const expected = validRevision(expectedRevision);
+    const session = hostedSession(null);
+    return transition(
+      session,
+      { kind: 'remove-worktree', force: force === true },
+      { ownTurn: ownTurn === true, expectedRevision: expected }
+    );
+  }
+
+  /**
+   * Move the hosted Lead to another Project folder (session set-project, the
+   * desktop/remote setCwd): the one authority for a Project switch, admitted
+   * like a workspace transition. Refused while a turn runs (`ownTurn`: the
+   * Lead's own tool call tolerates its calling turn), while workers run, and
+   * while the session works in a managed worktree. Serialized with turns and
+   * other workspace changes; the prompt refresh of the Lead and its idle
+   * workers completes (or rolls the switch back) before it resolves. Without
+   * a session (a draft) only the runtime cwd and the selection move.
+   * `classifyByMembership` (the desktop/remote move): a folder outside every
+   * registered Project is classified as a task (cwd-apply).
+   * @returns {Promise<string>} the runtime cwd after the switch
+   */
+  async function switchProject(cwd, { ownTurn = false, classifyByMembership = false } = {}) {
+    const selection = { classifyByMembership: classifyByMembership === true };
+    const session = getSession();
+    if (!session?.id) {
+      applyResolvedCwd(cwd, { persistProjectSelection: true, ...selection });
+      return getCurrentCwd();
+    }
+    const leave = beginWorkspaceTransition(session.id, `project:${newTxId()}`);
+    const journal = [];
+    try {
+      await assertLeadIdle(session, { ownTurn: ownTurn === true, shellJobs: false });
+      if (isWorktreeBound(readSessionWorkspace(session))) throw new Error(WORKTREE_BOUND_SWITCH);
+      await steps.switchProject(session, cwd, journal, selection);
+      return getCurrentCwd();
+    } catch (error) {
+      await undoAll(journal, error);
+      throw error;
+    } finally {
+      leave();
+    }
+  }
+
+  return { transition, runTransition, removeWorktree, switchProject };
+}