mixdog 1.4.0 → 1.4.2

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

@@ -0,0 +1,132 @@
+/**
+ * Merging the hosted Lead's retained worktree (or the linked checkout it
+ * works in) into the project folder's checked-out branch, with the optional
+ * cleanup of the merged worktree.
+ */
+import { isWorktreeBound, worktreeError, worktreeRefusal } from '../../runtime/shared/worktrees/contract.mjs';
+import { samePath } from '../../runtime/shared/worktrees/paths.mjs';
+import { mergeConfirmedTarget } from '../../runtime/shared/worktrees/branch-management.mjs';
+import { beginWorkspaceTransition } from './admission-gate.mjs';
+import { assertRetainedFits } from './transition-steps.mjs';
+import { assertRevision, validRevision } from './transition-runner.mjs';
+
+/**
+ * @param {object} deps The session view, assertLeadIdle, withManagementFolders,
+ *   the runner's removeWorktree, `backend()` and `worktreeSettings()`.
+ */
+export function createWorkspaceMerge({
+  hostedSession,
+  currentWorkspace,
+  assertLeadIdle,
+  inspectProject,
+  backend,
+  withManagementFolders,
+  removeWorktree,
+  worktreeSettings,
+  newTxId,
+}) {
+  /**
+   * The merge itself. The retained worktree must belong to this session's
+   * Project (same repository and Project folder — a Project switch may have
+   * left it behind); its branch, or the branch of the linked checkout the
+   * session works in, is merged into the project folder through the shared
+   * guarded path (mergeConfirmedTarget): both folders validated and held.
+   */
+  async function mergeRetainedWorktree(session, { target, ownTurn, expectedRevision }) {
+    const workspace = currentWorkspace(session);
+    assertRevision(workspace.revision, expectedRevision);
+    const leave = beginWorkspaceTransition(session.id, `merge:${newTxId()}`);
+    try {
+      await assertLeadIdle(session, { ownTurn: ownTurn === true });
+      const project = await inspectProject(workspace.projectPath);
+      let branch;
+      if (!workspace.worktreeId && !samePath(workspace.cwd, workspace.projectPath)) {
+        const source = await inspectProject(workspace.cwd);
+        if (!samePath(source.repoCommonDir, project.repoCommonDir)) throw worktreeError('WORKTREE_PROJECT_MISMATCH');
+        branch = source.currentBranch;
+      } else {
+        const backendApi = await backend();
+        const entry = workspace.worktreeId
+          ? await backendApi.findWorktreeContaining(workspace.cwd)
+          : await backendApi.getSessionWorktree(session.id);
+        if (!entry) throw worktreeError('WORKTREE_MISSING', 'This session has no worktree to merge.');
+        assertRetainedFits(entry, project, workspace.projectPath);
+        if (!samePath(entry.projectPath, workspace.projectPath)) {
+          throw worktreeError('WORKTREE_PROJECT_MISMATCH', undefined, {
+            worktreeId: entry.id,
+            worktreeProject: entry.projectPath,
+            projectPath: workspace.projectPath,
+          });
+        }
+        branch = entry.branch;
+      }
+      return await mergeConfirmedTarget(
+        { projectPath: workspace.projectPath, branch, target },
+        (folders, removing, run) => withManagementFolders(folders, removing, run, { actor: session.id })
+      );
+    } finally {
+      leave();
+    }
+  }
+
+  /**
+   * Merge the retained worktree into the project folder's checked-out branch.
+   * `ownTurn` (internal: the Lead's own tool call) tolerates the calling turn.
+   */
+  async function mergeWorkspace(
+    { confirmed = false, target = null, cleanup = false, expectedRevision } = {},
+    { ownTurn = false } = {}
+  ) {
+    if (confirmed !== true) {
+      throw worktreeError('WORKTREE_CONFIRM_REQUIRED', 'mergeWorkspace requires confirmed: true.');
+    }
+    const expected = validRevision(expectedRevision);
+    const session = hostedSession(null);
+    const merged = await mergeRetainedWorktree(session, { target, ownTurn, expectedRevision: expected });
+    if (cleanup !== true || merged.merged !== true) return merged;
+    // "Merge and clean up": with autoCleanup on, the merged worktree goes now
+    // (a dirty one stays, reported); off, nothing is removed automatically.
+    // The merge is committed: a failed or refused cleanup (dirty, retained
+    // file recovery data, ...) is a cleanup notice, never a merge failure.
+    if (worktreeSettings().autoCleanup !== true) {
+      return {
+        ...merged,
+        cleanup: { removed: false, reason: 'auto-cleanup-off', message: 'Auto cleanup is off; the worktree is kept.' },
+      };
+    }
+    // The cleanup never moves a session: while this session still works in the
+    // merged folder (or any other session uses it) the removal is refused.
+    try {
+      if (isWorktreeBound(currentWorkspace(session))) {
+        throw worktreeRefusal('folder-in-use', { sessions: [session.id] });
+      }
+      const entry = await (await backend()).getSessionWorktree(session.id);
+      const removed = await withManagementFolders(
+        entry ? [entry.path] : [],
+        true,
+        () => removeWorktree({ force: false }, { ownTurn }),
+        { actor: session.id }
+      );
+      return { ...merged, cleanup: removed.removed, revision: removed.revision, workspace: removed.workspace };
+    } catch (error) {
+      // The merge stands: a refused or incomplete cleanup (in use, dirty,
+      // unmerged, retained file recovery data, partly removed, …) is
+      // reported, never thrown, with the workspace as it is now.
+      const workspace = currentWorkspace(session);
+      const code = typeof error?.code === 'string' ? error.code : '';
+      return {
+        ...merged,
+        cleanup: {
+          removed: false,
+          reason: code || 'WORKTREE_CLEANUP_FAILED',
+          ...(code ? { code } : {}),
+          message: String(error?.message || error),
+        },
+        revision: workspace.revision,
+        workspace,
+      };
+    }
+  }
+
+  return { mergeWorkspace };
+}

package/src/session-runtime/workspace/worktree-intents.mjs

@@ -0,0 +1,242 @@
+/**
+ * The pending worktree intent of the hosted Lead: armed at creation (the New
+ * task default or an explicit choice) or by "워크트리", and provisioned at
+ * the start of the next turn (or at once, for a New Task's first send).
+ */
+import {
+  WORKTREE_CARRY_CHOICES,
+  isWorktreeBound,
+  isWorktreeError,
+  worktreeError,
+} from '../../runtime/shared/worktrees/contract.mjs';
+import { sessionHasConversationMessages } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
+import { promptContentText } from '../../runtime/agent/orchestrator/session/manager/prompt-utils.mjs';
+import { assertRevision, validName, validRevision } from './transition-runner.mjs';
+import { readSessionWorkspace } from './workspace-state.mjs';
+
+/**
+ * Creation-time intent: `{ mode: 'worktree', name }` asks for a worktree;
+ * `{ mode: 'default' }` — an interactive Lead the user starts (TUI launch) —
+ * follows the settings `newTaskDefault`; `{ mode: 'branch' }` or no intent
+ * runs in the project folder. Desktop tasks carry their choice from the
+ * renderer, and agents, schedules, webhooks and resumed sessions pass none,
+ * so the default never applies to them.
+ */
+export function creationIntent(worktree, settings) {
+  if (worktree?.mode === 'worktree') {
+    return { name: worktree.name ?? null, confirmLarge: false, explicit: true, sessionId: null, txId: null };
+  }
+  return worktree?.mode === 'default' && settings.newTaskDefault === 'worktree'
+    ? { name: null, confirmLarge: false, explicit: false, sessionId: null, txId: null }
+    : null;
+}
+
+/**
+ * @param {object} deps `initial` (creationIntent), the session view, the
+ *   transition runner, `runPendingSetup` and the host's session hooks.
+ */
+export function createWorktreeIntents({
+  initial,
+  getSession,
+  getReservedSessionId,
+  ensureSession,
+  currentWorkspace,
+  backend,
+  transition,
+  runTransition,
+  runPendingSetup,
+  newTxId,
+}) {
+  let pendingIntent = initial;
+
+  /** The pending worktree intent that applies to `session`'s next turn, if any. */
+  function intentFor(session) {
+    const intent = pendingIntent;
+    if (!intent) return null;
+    if (isWorktreeBound(readSessionWorkspace(session))) {
+      pendingIntent = null;
+      return null;
+    }
+    if (intent.sessionId) return intent.sessionId === session.id ? intent : null;
+    // A creation-time intent belongs to a new task: never to a resumed
+    // conversation this runtime opened instead.
+    const started =
+      sessionHasConversationMessages(session) || sessionHasConversationMessages({ messages: session.liveTurnMessages });
+    return started ? null : intent;
+  }
+
+  /**
+   * Create and enter the worktree `intent` asks for now: its txId is fixed on
+   * first use (`submissionId`, else a fresh one) so a retry reuses the same
+   * worktree, and the prompt text names an unnamed one. A settled intent is
+   * consumed.
+   */
+  async function provisionIntent(session, intent, submissionId, prompt, options) {
+    intent.txId ||= String(submissionId || '').trim() || newTxId();
+    const result = await transition(
+      session,
+      { kind: 'worktree', name: intent.name },
+      { txId: intent.txId, nameHint: promptContentText(prompt), confirmLarge: intent.confirmLarge, ...options }
+    );
+    if (pendingIntent === intent) pendingIntent = null;
+    return result;
+  }
+
+  /**
+   * Turn-start workspace gate, run after the session exists and before the
+   * user row, the review snapshot, hooks, the provider and any worker spawn.
+   * A session in recovery refuses the turn; a pending worktree intent is
+   * provisioned now (txId = the first submission id, reused by retries; an
+   * unnamed worktree takes its slug from the first message).
+   */
+  async function prepareTurnWorkspace({ submissionId = '', prompt = '', signal, confirmLarge = false } = {}) {
+    const session = getSession();
+    if (!session?.id) return null;
+    const stored = readSessionWorkspace(session);
+    if (stored?.transition.state === 'recovery') {
+      throw worktreeError(
+        'WORKTREE_MISSING',
+        'The worktree for this session no longer exists; pick a branch or remove the worktree to continue.',
+        { worktreeId: stored.worktreeId, path: stored.cwd }
+      );
+    }
+    const intent = intentFor(session);
+    let result = null;
+    if (intent) {
+      try {
+        result = await provisionIntent(session, intent, submissionId, prompt, {
+          confirmLarge: intent.confirmLarge || confirmLarge === true,
+          signal,
+          ownTurn: true,
+        });
+      } catch (error) {
+        // The settings default never blocks a task outside a git repository.
+        if (!intent.explicit && isWorktreeError(error, 'WORKTREE_UNSUPPORTED_REPO')) {
+          if (pendingIntent === intent) pendingIntent = null;
+          return null;
+        }
+        throw error;
+      }
+    }
+    await runPendingSetup(session, signal);
+    return result;
+  }
+
+  /**
+   * "워크트리": re-enter the retained worktree now, or arm the lazy creation
+   * for the next message (confirmLarge acknowledges WORKTREE_LARGE_REPO_CONFIRM).
+   *
+   * `provision` (a New Task's first send, before its prompt is submitted)
+   * creates and enters the worktree right away instead: `prompt` names it
+   * like the lazy path would and `txId` (the submission id) makes a resend
+   * reuse it. Typed failures (large repository, disk, busy) therefore reach
+   * the sender while its draft is still unsent, and the turn that follows
+   * finds the session already bound.
+   *
+   * A provisioning that creates a new worktree decides the project folder's
+   * uncommitted changes (tracked and untracked): none → it proceeds; without
+   * `carryChanges` it refuses with WORKTREE_DIRTY_CHOICE (`details.count`);
+   * `leave` starts the worktree at HEAD and leaves them; `carry` moves them
+   * into it (the result's `changes` reports which). Re-entering a retained
+   * worktree never touches them.
+   *
+   * `ownTurn` (internal: the Lead's own tool call) tolerates the calling turn.
+   */
+  async function requestWorktree(
+    {
+      name = null,
+      confirmLarge = false,
+      provision = false,
+      carryChanges,
+      prompt = '',
+      txId = '',
+      expectedRevision,
+    } = {},
+    { ownTurn = false } = {}
+  ) {
+    const nameHint = validName(name);
+    const expected = validRevision(expectedRevision);
+    if (carryChanges !== undefined && carryChanges !== null && !WORKTREE_CARRY_CHOICES.includes(carryChanges)) {
+      throw new TypeError(`carryChanges must be one of ${WORKTREE_CARRY_CHOICES.join(', ')}.`);
+    }
+    const session = provision === true ? await ensureSession() : getSession();
+    // No session yet: the menu it was read from had revision 0.
+    const current = session?.id ? currentWorkspace(session) : null;
+    assertRevision(current?.revision ?? 0, expected);
+    if (current) {
+      if (isWorktreeBound(current)) return { revision: current.revision, workspace: current, pending: false };
+      if (await (await backend()).getSessionWorktree(session.id)) {
+        const entered = await runTransition(
+          { sessionId: session.id },
+          { kind: 'worktree' },
+          { expectedRevision: expected },
+          { ownTurn }
+        );
+        return { ...entered, pending: false };
+      }
+    }
+    const priorIntent = pendingIntent;
+    pendingIntent = {
+      name: nameHint ?? pendingIntent?.name ?? null,
+      confirmLarge: confirmLarge === true || pendingIntent?.confirmLarge === true,
+      explicit: true,
+      sessionId: session?.id || getReservedSessionId?.() || null,
+      txId: pendingIntent?.txId ?? null,
+    };
+    if (provision === true) {
+      const intent = pendingIntent;
+      try {
+        return {
+          ...(await provisionIntent(session, intent, txId, prompt, {
+            expectedRevision: expected,
+            changes: carryChanges ?? 'ask',
+            ownTurn: ownTurn === true,
+          })),
+          pending: false,
+        };
+      } catch (error) {
+        // A refused move (uncommitted changes to decide, busy, …) is never
+        // re-armed for the next turn, where nobody could answer it.
+        if (pendingIntent === intent) pendingIntent = priorIntent;
+        throw error;
+      }
+    }
+    const workspace = session?.id ? currentWorkspace(session) : null;
+    return { revision: workspace?.revision ?? 0, workspace, pending: true };
+  }
+
+  /**
+   * Run in `branch`'s checkout (see enterProjectBranch); a selected branch
+   * settles the session's location, so no worktree intent stays armed.
+   * `ownTurn` (internal: the Lead's own tool call) tolerates the calling turn.
+   */
+  async function selectBranch(
+    { branch, create = false, expectedRevision, confirmLarge = false, txId = '' } = {},
+    { ownTurn = false } = {}
+  ) {
+    const session = await ensureSession();
+    const current = currentWorkspace(session);
+    if (current.branch === branch && current.worktreeId) {
+      assertRevision(current.revision, validRevision(expectedRevision));
+      pendingIntent = null;
+      return { revision: current.revision, workspace: current };
+    }
+    const target = { kind: 'branch', branch, create: create === true };
+    const result = await runTransition(
+      { sessionId: session.id },
+      target,
+      { expectedRevision, confirmLarge },
+      { ownTurn, txId: String(txId || '').trim() }
+    );
+    pendingIntent = null;
+    return result;
+  }
+
+  return {
+    prepareTurnWorkspace,
+    requestWorktree,
+    selectBranch,
+    /** What the branch menu shows of the armed intent (null: none). */
+    pendingWorktree: () => (pendingIntent ? { name: pendingIntent.name } : null),
+  };
+}

package/src/session-runtime/workspace/worktree-maintenance.mjs

@@ -0,0 +1,80 @@
+/**
+ * The managed-worktree maintenance the hosted runtime offers: the retention
+ * list, the manual prune, an orphan's removal and a deleted session's
+ * cleanup. Every live session of this process counts as a live owner.
+ */
+import { WORKTREE_SNAPSHOT_KIND, worktreeError } from '../../runtime/shared/worktrees/contract.mjs';
+import * as maintenance from '../../runtime/shared/worktrees/maintenance.mjs';
+
+/**
+ * @param {object} deps The host's session listings, the `backend()` loader,
+ *   withManagementFolders, cancelSnapshotCleanups and `worktreeSettings()`.
+ */
+export function createWorktreeMaintenance({
+  getSession,
+  listLiveSessions,
+  listStoredSessionIds,
+  backend,
+  withManagementFolders,
+  cancelSnapshotCleanups,
+  worktreeSettings,
+}) {
+  /** The maintenance scope here: every live session of this process counts as a live owner. */
+  async function maintenanceScope() {
+    const liveSessionIds = [
+      ...new Set([getSession()?.id, ...listLiveSessions().map((candidate) => candidate?.id)].filter(Boolean)),
+    ];
+    return { liveSessionIds, listSessionIds: listStoredSessionIds, manager: await backend() };
+  }
+
+  /**
+   * Every managed worktree with who retains it (the manual list). Read-only
+   * snapshots (no branch) only with `includeSnapshots` (the git tool); the
+   * desktop list (DesktopManagedWorktreeRow, a branch per row) never gets them.
+   */
+  async function listWorktrees({ includeSnapshots = false } = {}) {
+    const rows = await maintenance.listWorktreesWithRetention(await maintenanceScope());
+    return includeSnapshots ? rows : rows.filter((row) => row.kind !== WORKTREE_SNAPSHOT_KIND);
+  }
+
+  /** The manual prune: clean, merged worktrees no stored or live session retains. */
+  async function pruneWorktrees({ repoCommonDir = null } = {}) {
+    return maintenance.pruneWorktrees({ ...(await maintenanceScope()), repoCommonDir });
+  }
+
+  /**
+   * Remove managed worktree `entryId` whose owner is gone (listed `ownerLive:
+   * false, removable: true`), on an explicit request: no owner lane exists to
+   * do it. No stored or live session may still use the folder; the manager
+   * reads the retention again under the repository lock (an owner that came
+   * back refuses) and keeps its guards: dirty or unmerged work needs `force`,
+   * other sessions' references and retained recovery data refuse, and only
+   * the managed checkout is deleted.
+   */
+  async function removeOrphanWorktree({ entryId, force = false } = {}) {
+    const row = (await listWorktrees()).find((item) => item.id === entryId);
+    if (!row) throw worktreeError('WORKTREE_MISSING', undefined, { entryId });
+    const removed = await withManagementFolders([row.path], true, async () => {
+      const { liveSessionIds, listSessionIds, manager: backendApi } = await maintenanceScope();
+      return backendApi.removeOrphanedWorktree({
+        entryId,
+        force: force === true,
+        liveSessionIds,
+        retainedSessionIds: await listSessionIds(),
+      });
+    });
+    return { removed, entryId, path: row.path };
+  }
+
+  /** After `sessionId` was deleted: autoCleanup removes its clean, merged worktree. */
+  async function cleanupDeletedSession(sessionId) {
+    // Its snapshots go with it below; no turn cleanup keeps retrying them.
+    cancelSnapshotCleanups(sessionId);
+    return maintenance.cleanupDeletedSessionWorktree(sessionId, {
+      manager: await backend(),
+      autoCleanup: worktreeSettings().autoCleanup,
+    });
+  }
+
+  return { listWorktrees, pruneWorktrees, removeOrphanWorktree, cleanupDeletedSession };
+}

package/src/session-runtime/workspace/worktree-setup.mjs

@@ -0,0 +1,85 @@
+/**
+ * The one-time preparation of a session's new worktree at the first turn it
+ * runs there (frozen dependency installs), with its progress for viewers and
+ * the compact note the agent gets with that turn.
+ */
+import { isWorktreeBound } from '../../runtime/shared/worktrees/contract.mjs';
+import { throwIfAborted } from '../../runtime/shared/worktrees/git.mjs';
+import { worktreePreparationNote } from '../../runtime/shared/worktrees/preparation-report.mjs';
+import { readSessionWorkspace } from './workspace-state.mjs';
+
+/** The dependency installs a new worktree folder still needs (dependencies.mjs). */
+export async function defaultPlanWorktreeSetup(input) {
+  const { planDependencySetup } = await import('../../runtime/shared/worktrees/dependencies.mjs');
+  return planDependencySetup(input);
+}
+
+export async function defaultRunWorktreeSetup(input) {
+  const { runWorktreeSetupCommands } = await import('../../runtime/shared/worktrees/setup-commands.mjs');
+  return runWorktreeSetupCommands(input);
+}
+
+/** @param {object} deps The `backend()` loader, `newTxId` and the setup planner and runner. */
+export function createWorktreeSetup({ backend, newTxId, planWorktreeSetup, runWorktreeSetup }) {
+  const setupListeners = new Set();
+
+  /**
+   * Prepare the session's new worktree, once, under the turn (its admission
+   * keeps the folder from being merged or removed; its signal — the Stop
+   * button — cancels): the frozen installs the links made at creation did
+   * not cover. While an install runs, every onWorktreeSetup listener gets its
+   * one-line progress; nothing else reaches the user. The agent gets one
+   * compact note with this turn (`session.pendingSetupNotice`): the main
+   * checkout, what was copied, linked and installed, what failed (with the
+   * output tail) and what was skipped. A failure or timeout is in the note
+   * and the turn goes on; a cancel aborts the turn like any other stop. The
+   * worktree stays either way. The setup belongs to the worktree it was made
+   * for, whichever path made it (a worktree task, a branch selection, `git
+   * worktree add`): its registry entry keeps it pending (manager
+   * claimWorktreeSetup) until the first turn a session runs there, never in
+   * another folder.
+   */
+  async function runPendingSetup(session, signal) {
+    const here = readSessionWorkspace(session);
+    if (!isWorktreeBound(here)) return;
+    const claimed = await (await backend()).claimWorktreeSetup(here.worktreeId);
+    if (!claimed) return;
+    const id = newTxId();
+    const report = {
+      root: claimed.prepared?.root || here.projectPath,
+      prepared: claimed.prepared,
+      dependencyNotes: [],
+      installs: null,
+      notes: [],
+    };
+    const emit = (event) => {
+      for (const listener of setupListeners) {
+        try {
+          listener({ ...event, id, sessionId: session.id, cwd: here.cwd });
+        } catch {
+          /* a viewer's failure never stops the setup */
+        }
+      }
+    };
+    try {
+      const plan = await planWorktreeSetup({ worktreeDir: here.cwd, mainDir: here.projectPath, signal });
+      report.dependencyNotes = plan.notes;
+      if (plan.commands.length) {
+        report.installs = await runWorktreeSetup({ commands: plan.commands, signal, onProgress: emit });
+      }
+    } catch (error) {
+      if (!signal?.aborted) report.notes.push(`Dependencies could not be prepared: ${error?.message || error}`);
+    }
+    session.pendingSetupNotice = { revision: Date.now(), content: worktreePreparationNote(report) };
+    throwIfAborted(signal);
+  }
+
+  /** Subscribe to worktree setup progress; returns the unsubscribe. */
+  function onWorktreeSetup(listener) {
+    if (typeof listener !== 'function') return () => {};
+    setupListeners.add(listener);
+    return () => setupListeners.delete(listener);
+  }
+
+  return { runPendingSetup, onWorktreeSetup };
+}