mixdog 1.4.2 → 1.4.3

package/src/session-runtime/tool-surface.mjs

@@ -6,7 +6,10 @@ import {
   filterDisallowedTools,
   selectDeferredTools,
 } from '../runtime/agent/orchestrator/runtime-core/tool-catalog.mjs';
-import { AGENT_WORKER_DENIED_TOOLS } from '../runtime/agent/orchestrator/session/manager/tool-resolution.mjs';
+import {
+  AGENT_WORKER_DENIED_TOOLS,
+  finalizeSessionToolList,
+} from '../runtime/agent/orchestrator/session/manager/tool-resolution.mjs';
 import { LEAD_DISALLOWED_TOOLS } from '../runtime/agent/orchestrator/runtime-core/tool-defs.mjs';
 import { deferredSurfaceModeForLead, toolSpecForMode } from '../runtime/agent/orchestrator/runtime-core/effort.mjs';
 import { loadSkillToolDependencies } from '../runtime/agent/orchestrator/runtime-core/skill-tool-loading.mjs';
@@ -39,6 +42,11 @@ export function createToolSurface({
   getFeatureDisallowedTools = () => [],
 }) {
   let preSessionSurface = null;
+  // The inputs the cached preview was built from (setters no longer
+  // invalidate it; a config adopt or reload replaces the config object).
+  let preSessionInputs = '';
+  let preSessionConfig = null;
+  let surfaceGeneration = 0;
 
   // A coding Lead keeps `agent` whichever agents exist (the agents reach it as
   // a listing reminder); Solo still offers it (deferred) for explicit user
@@ -122,16 +130,45 @@ export function createToolSurface({
     return selectDeferredTools(session, names, surfaceMode);
   }
 
+  /** Definitions the current session's kind may hold — built-ins included —
+   *  for tools a settings gate opened mid-conversation. */
+  function toolDefinitionsFor(names) {
+    const wanted = new Set((names || []).map(String));
+    const session = getSession();
+    const ownerIsAgent = isAgentOwner(session);
+    const previewTools =
+      typeof mgr.previewSessionTools === 'function'
+        ? mgr.previewSessionTools(toolSpecForMode(mode), [], {
+            mcpScopeId: getMcpScopeId(),
+            modelName: getRoute().model,
+            cwd: getCurrentCwd?.() || null,
+          })
+        : [];
+    const byName = new Map();
+    for (const tool of [...modelStandaloneTools(), ...filterModelToolsForProfile(previewTools, getToolProfile())]) {
+      const name = String(tool?.name || '');
+      if (wanted.has(name) && !byName.has(name)) byName.set(name, tool);
+    }
+    return finalizeSessionToolList([...byName.values()], { ownerIsAgent });
+  }
+
   return {
     modelStandaloneTools,
     activateTools,
+    toolDefinitionsFor,
+    surfaceGeneration: () => surfaceGeneration,
     invalidatePreSessionToolSurface() {
       preSessionSurface = null;
+      surfaceGeneration += 1;
     },
     /** The live session once it exists; the preview surface until then. */
     activeToolSurface() {
       const session = getSession();
       if (session) return session;
+      const inputs = getFeatureDisallowedTools().join(',');
+      if (preSessionConfig !== getConfig() || preSessionInputs !== inputs) preSessionSurface = null;
+      preSessionConfig = getConfig();
+      preSessionInputs = inputs;
       preSessionSurface ??= buildPreSessionSurface();
       return preSessionSurface;
     },

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

@@ -31,6 +31,7 @@ export function createAgentOps(deps) {
     subscribeRuntimeNotification,
     agentTool,
     activeToolSurface,
+    reconcileEmptySession,
     notificationListeners,
     getReservedSessionId,
   } = deps;
@@ -136,7 +137,14 @@ export function createAgentOps(deps) {
     return () => notificationListeners.delete(listener);
   }
 
-  function toolsStatus(query = '') {
+  // An empty session has nothing cached: it is brought to the settings first
+  // (the turn-start reconcile), so the list is what its first turn sends.
+  async function toolsStatus(query = '') {
+    await reconcileEmptySession?.();
+    return toolsStatusNow(query);
+  }
+
+  function toolsStatusNow(query = '') {
     const surface = activeToolSurface();
     let catalog = [];
     if (Array.isArray(surface?.deferredToolCatalog)) catalog = surface.deferredToolCatalog;
@@ -161,7 +169,7 @@ export function createAgentOps(deps) {
   function selectTools(names) {
     const list = Array.isArray(names) ? names : String(names || '').split(/[,\s]+/);
     const result = selectDeferredTools(activeToolSurface(), list, getMode());
-    return { ...result, status: toolsStatus() };
+    return { ...result, status: toolsStatusNow() };
   }
 
   return {

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

@@ -6,6 +6,7 @@ import { normalizeToolMode } from '../../runtime/agent/orchestrator/runtime-core
 import { interruptTaskWaitForSession } from '../../runtime/agent/orchestrator/session/task-wait-control.mjs';
 import { markPendingGoalReminder } from '../../runtime/agent/orchestrator/runtime-core/goal-reminder.mjs';
 import { rearmLateDeferredTools } from '../../runtime/agent/orchestrator/runtime-core/tool-catalog.mjs';
+import { rearmPromptSettingsNotice } from '../../runtime/agent/orchestrator/session/manager/prompt-settings.mjs';
 
 export function createSessionOps(deps) {
   const {
@@ -101,6 +102,7 @@ export function createSessionOps(deps) {
     // The same compaction strips late MCP tool announcements from older turns.
     try {
       rearmLateDeferredTools(getSession());
+      rearmPromptSettingsNotice(getSession());
     } catch {
       /* best-effort: a tool reminder must never break manual compact */
     }

package/src/session-runtime/turn/turn-run/turn-prepare.mjs

@@ -90,6 +90,7 @@ export function createTurnPreparation({
   applyPendingRoute,
   applyPendingAgentProfile,
   applyPendingSessionSwitches,
+  reconcileTurnSettings,
 }) {
   async function admitWorkspace(turn, prompt, options) {
     // Turn admission: waits while this session's workspace transitions or
@@ -149,6 +150,10 @@ export function createTurnPreparation({
     // An orchestration mode or workflow chosen while the previous turn ran
     // applies from this one (before a cold-cache fold can take it in).
     const sessionSwitches = applyPendingSessionSwitches?.();
+    // Settings saved since this session last ran (here or in any other
+    // runtime): an empty session is rebuilt, a conversation takes moved tool
+    // gates live — before a cold-cache fold below can take them in.
+    await reconcileTurnSettings?.();
     // An agent profile saved while the previous turn ran applies from this one.
     await applyPendingAgentProfile?.();
     options.onRouteApplied?.(getSession());

package/src/session-runtime/turn/turn-run.mjs

@@ -85,7 +85,7 @@ export function createTurnRunner(deps) {
           // The agents enabled now (coding Leads), asked for each user turn
           // the ask prepares, for its agent list reminder
           // (manager/agent-listing-notice.mjs).
-          { ...callbacks, agentsNow: currentAgents }
+          { ...callbacks, agentsNow: currentAgents, agentConfig: getConfig }
         );
       } finally {
         releaseWebSearchUsage?.();

package/src/session-runtime/webhook-session-run.mjs

@@ -43,6 +43,7 @@ function runWebhookTurn({
   name,
   prompt,
   ownerAgentId = null,
+  executorAgentId = null,
   cwd = null,
   attachments = null,
   event = '',
@@ -55,6 +56,7 @@ function runWebhookTurn({
     kind: 'webhook',
     name: endpoint,
     ownerAgentId,
+    executorAgentId: executorAgentId || null,
     prompt,
     skillSelection: String(skillSelection ?? ''),
     attachments,

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

@@ -177,10 +177,7 @@ export function createAgentConnectorsApi(deps, editor) {
       return [...names].map((tool) => ({
         connector,
         tool,
-        permission: connectorToolPermission(
-          { off: [], tools },
-          { mcpServerName: connector, mcpToolName: tool }
-        ),
+        permission: connectorToolPermission({ off: [], tools }, { mcpServerName: connector, mcpToolName: tool }),
         explicit: connectorToolEntries(tools, group, tool).length > 0,
       }));
     });

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

@@ -7,7 +7,6 @@ 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';
@@ -227,13 +226,7 @@ export function createAgentRouteApi(deps) {
     return stayOff ? { ...routeToSave, id, disabled: true } : routeToSave;
   }
 
-  // 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 };
+  // Explore's route decides whether the explore tool exists; sessions take a
+  // change of it at their next turn start (reconcileTurnSettings).
+  return { setAgentRoute };
 }

package/src/session-runtime/workflow-agents-api/instruction-files.mjs

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { writeFileAtomicSync } from '../../runtime/shared/atomic-file.mjs';
+import { normalizeText } from '../../runtime/shared/shipped-definitions.mjs';
+import { decodeInstructionFile, INSTRUCTION_FILE_MAX_BYTES } from '../../lib/instruction-text.cjs';
+import { outputStyleMetaFromMarkdown } from '../../lib/output-style-meta.cjs';
+import {
+  readInstructionFile,
+  shippedOrchestrationPath,
+  userOrchestrationPath,
+} from '../../runtime/agent/orchestrator/runtime-core/orchestration.mjs';
+import { ORCHESTRATION_MODES } from '../../runtime/shared/orchestration.mjs';
+import { publishAgentProfileChange } from '../agent-profile-changes.mjs';
+import { STANDALONE_ROOT } from '../runtime-paths.mjs';
+import { resolveDataDir } from './shared.mjs';
+
+// The editable instruction texts: the four orchestration modes (delegation)
+// and the four output-style depth levels. Each has a shipped .md file and a
+// same-name user file in the data dir that replaces it; the set is fixed.
+export const INSTRUCTION_FILE_CONFLICT = 'INSTRUCTION_FILE_CONFLICT';
+
+const MODE_LABELS = { none: 'Solo', focused: 'Focused', balanced: 'Balanced', swarm: 'Swarm' };
+const STYLES = [
+  ['detailed', 'Detailed'],
+  ['simple', 'Simple'],
+  ['minimal', 'Minimal'],
+  ['extreme-minimal', 'Extreme Minimal'],
+];
+const INSTRUCTION_GROUPS = Object.freeze(['delegation', 'outputStyle']);
+
+const FRONTMATTER = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+const bodyOfStyle = (text) =>
+  String(text || '')
+    .replace(FRONTMATTER, '')
+    .trim();
+const hashOf = (text) => createHash('sha256').update(String(text)).digest('hex').slice(0, 24);
+
+// One item's files and the text <-> file mapping. The style editor shows and
+// saves the file's body only: the shipped front matter (name, title,
+// description) is kept, and common.md is not part of it.
+function itemFor(group, id, deps) {
+  if (group === 'delegation') {
+    if (!ORCHESTRATION_MODES.includes(id))
+      throw new Error(`orchestration mode must be one of ${ORCHESTRATION_MODES.join(', ')}`);
+    return {
+      group,
+      id,
+      label: MODE_LABELS[id],
+      shipped: shippedOrchestrationPath(id),
+      user: userOrchestrationPath(id),
+      body: (text) => text,
+      file: (body) => `${body}\n`,
+      accepts: () => true,
+    };
+  }
+  if (group === 'outputStyle') {
+    const style = STYLES.find(([styleId]) => styleId === id);
+    if (!style) throw new Error(`output style must be one of ${STYLES.map(([styleId]) => styleId).join(', ')}`);
+    const shipped = join(deps.rootDir ?? STANDALONE_ROOT, 'output-styles', `${id}.md`);
+    return {
+      group,
+      id,
+      label: style[1],
+      shipped,
+      user: join(resolveDataDir(deps), 'output-styles', `${id}.md`),
+      body: bodyOfStyle,
+      file: (body, shippedText) => `${(FRONTMATTER.exec(shippedText) || [''])[0].trimEnd()}\n\n${body}\n`,
+      // A file whose front matter names another style defines that one instead
+      // (the prompt builder registers it by name): it does not replace this one.
+      accepts: (text) => outputStyleMetaFromMarkdown(text, `${id}.md`)?.id === id,
+    };
+  }
+  throw new Error(`instruction group must be one of ${INSTRUCTION_GROUPS.join(', ')}`);
+}
+
+export function createInstructionFilesApi(deps) {
+  function stateOf(item) {
+    const shipped = readInstructionFile(item.shipped);
+    const defaultBody = item.body(shipped?.text ?? '');
+    const user = readInstructionFile(item.user);
+    const accepted = Boolean(user?.text) && item.accepts(user.text);
+    const userBody = accepted ? item.body(user.text) : '';
+    // An existing user file that cannot serve (empty, too large, not text, a
+    // style under another name) is passed over by the prompt builders: the
+    // built-in applies.
+    const usable = Boolean(userBody);
+    const problem = user && !usable ? (user.problem ?? (accepted ? 'empty' : 'invalid')) : undefined;
+    const body = usable ? userBody : defaultBody;
+    return {
+      group: item.group,
+      id: item.id,
+      label: item.label,
+      body,
+      defaultBody,
+      userOverride: Boolean(user),
+      modified: usable && normalizeText(userBody) !== normalizeText(defaultBody),
+      ...(problem ? { problem } : {}),
+      ...(user ? { path: item.user } : {}),
+      revision: hashOf(`${usable ? 'user' : 'default'}\0${problem ?? ''}\0${body}`),
+    };
+  }
+
+  // A write or reset made against a state that has moved on is refused.
+  function assertCurrent(payloadRevision, before, item) {
+    if (payloadRevision === undefined || String(payloadRevision) === before.revision) return;
+    const conflict = new Error(`${INSTRUCTION_FILE_CONFLICT}: "${item.id}" changed since it was loaded`);
+    conflict.code = INSTRUCTION_FILE_CONFLICT;
+    throw conflict;
+  }
+
+  const get = (group, id) => stateOf(itemFor(group, id, deps));
+
+  function list() {
+    return [...ORCHESTRATION_MODES.map((id) => get('delegation', id)), ...STYLES.map(([id]) => get('outputStyle', id))];
+  }
+
+  async function announce() {
+    deps.invalidateContextStatusCache?.();
+    await publishAgentProfileChange();
+  }
+
+  async function save(payload = {}) {
+    const item = itemFor(payload.group, payload.id, deps);
+    const body = String(payload.body ?? '')
+      .replace(/\r\n/g, '\n')
+      .trim();
+    if (!body) throw new Error('instruction text must not be empty');
+    if (body.includes('\0')) throw new Error('instruction text must be plain text');
+    const before = stateOf(item);
+    assertCurrent(payload.expectedRevision, before, item);
+    if (normalizeText(body) === normalizeText(before.defaultBody)) {
+      // Equal to the shipped text: keep no copy, so it follows the shipped version.
+      rmSync(item.user, { force: true });
+    } else {
+      // The bytes that reach the disk — front matter and newline included —
+      // must pass the reader's check, or the saved file would be ignored.
+      const bytes = Buffer.from(item.file(body, readInstructionFile(item.shipped)?.text ?? ''));
+      if (bytes.length > INSTRUCTION_FILE_MAX_BYTES) throw new Error('instruction text is larger than 256 KB');
+      const problem = decodeInstructionFile(bytes).problem;
+      if (problem) throw new Error(`instruction text cannot be saved (${problem})`);
+      mkdirSync(dirname(item.user), { recursive: true });
+      writeFileAtomicSync(item.user, bytes, { backup: true, mode: 0o644 });
+    }
+    await announce();
+    return stateOf(item);
+  }
+
+  async function reset(group, id, expectedRevision) {
+    const item = itemFor(group, id, deps);
+    if (!existsSync(item.user)) throw new Error(`"${item.id}" has no user override to reset`);
+    assertCurrent(expectedRevision, stateOf(item), item);
+    rmSync(item.user, { force: true });
+    rmSync(`${item.user}.bak`, { force: true });
+    await announce();
+    return stateOf(item);
+  }
+
+  return {
+    listInstructionFiles: list,
+    getInstructionFile: get,
+    saveInstructionFile: save,
+    resetInstructionFile: reset,
+  };
+}

package/src/session-runtime/workflow-agents-api/style-and-mode.mjs

@@ -30,7 +30,9 @@ export function createStyleAndModeApi(deps) {
     scheduleOutputStyleSave(selected.id);
     const freshStatus = { configured: selected.id, current: selected, styles: before.styles };
     seedOutputStyleStatusCache(freshStatus);
-    const appliedToCurrentSession = !getSession()?.id;
+    // An empty session is rebuilt at its next turn start; a conversation is
+    // told then and folds the style in at its next cold point.
+    const appliedToCurrentSession = deps.settingsReachCurrentSession?.() ?? !getSession()?.id;
     invalidateContextStatusCache();
     return { ...freshStatus, appliedToCurrentSession };
   }
@@ -53,10 +55,9 @@ export function createStyleAndModeApi(deps) {
       }
     }
     saveConfigAndAdopt({ ...getConfig(), orchestrationMode: mode });
-    const applied = await deps.refreshEmptySessionToolPolicy?.();
-    deps.invalidatePreSessionToolSurface?.();
+    // An empty session takes it at its next turn start (reconcileTurnSettings).
     invalidateContextStatusCache();
-    return { mode, appliedToCurrentSession: applied?.appliedToCurrentSession !== false };
+    return { mode, appliedToCurrentSession: deps.settingsReachCurrentSession?.() !== false };
   }
 
   return {

package/src/session-runtime/workflow-agents-api/workflow-packs.mjs

@@ -66,9 +66,8 @@ export function createWorkflowPacksApi(deps) {
       if (switched) return { ...switched.workflow, ...switched };
     }
     saveActiveWorkflow(id);
-    const applied = await deps.refreshEmptySessionToolPolicy?.();
-    deps.invalidatePreSessionToolSurface?.();
-    return { ...workflowSummary(pack), appliedToCurrentSession: applied?.appliedToCurrentSession !== false };
+    // An empty session takes it at its next turn start (reconcileTurnSettings).
+    return { ...workflowSummary(pack), appliedToCurrentSession: deps.settingsReachCurrentSession?.() !== false };
   }
 
   function getWorkflowPack(workflowId) {

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

@@ -4,6 +4,7 @@ import { createAgentConnectorsApi } from './workflow-agents-api/agent-connectors
 import { createAgentRouteApi } from './workflow-agents-api/agent-route.mjs';
 import { createWorkflowPacksApi } from './workflow-agents-api/workflow-packs.mjs';
 import { createStyleAndModeApi } from './workflow-agents-api/style-and-mode.mjs';
+import { createInstructionFilesApi } from './workflow-agents-api/instruction-files.mjs';
 
 // Onboarding + agents/workflows/output-style selection surface. Stateless
 // helpers are imported by the phase modules under workflow-agents-api/; the
@@ -20,5 +21,6 @@ export function createWorkflowAgentsApi(deps) {
     ...routeApi,
     ...createWorkflowPacksApi(deps),
     ...createStyleAndModeApi(deps),
+    ...createInstructionFilesApi(deps),
   };
 }

package/src/session-runtime/workspace/project-branches.mjs

@@ -52,7 +52,7 @@ export function createProjectBranchOps({
     return {
       // Detached: branch null and the checked-out commit in baseCommit.
       workspace: project.currentBranch ? workspace : { ...workspace, baseCommit: project.headCommit ?? null },
-      branches: branchMenuEntries(menu.branches, menu.occupancy),
+      branches: branchMenuEntries(menu.branches, menu.occupancy, menu.committedAt),
       occupancy: menu.occupancy,
       retainedWorktree: null,
     };

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

@@ -130,7 +130,7 @@ export function createSessionWorkspaceView({
     return {
       workspace: view,
       pendingWorktree: pendingWorktree(),
-      branches: branchMenuEntries(menu.branches, menu.occupancy),
+      branches: branchMenuEntries(menu.branches, menu.occupancy, menu.committedAt),
       occupancy: menu.occupancy,
       retainedWorktree: selectedEntry ?? menu.retainedWorktree ?? null,
       // Creation notes of the retained worktree (submodules, include entries).

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

@@ -62,12 +62,18 @@ async function defaultRegisteredProject(path) {
  * `move` ({ from, changes }: the session left the project folder `from` for
  * a worktree) adds the uncommitted-changes and path lines to that notice.
  */
-export async function refreshWorkspacePrompt(session, cwd, { loadCoreMemoryContext, move = null } = {}) {
+export async function refreshWorkspacePrompt(
+  session,
+  cwd,
+  { loadCoreMemoryContext, move = null, instructionFilesMode } = {}
+) {
   // A new checkout invalidates observed-file snapshots as well as read/search
   // results. Conversation text remains historical evidence, not a file cache.
   clearReadDedupSession(session?.id);
   resetReadStateAfterCompaction(session?.id);
-  const { environmentContext, instructionFilesContext } = buildWorkspacePromptContext(session, cwd);
+  const { environmentContext, instructionFilesContext } = buildWorkspacePromptContext(session, cwd, {
+    instructionFilesMode,
+  });
   const coreMemoryContext =
     session?.owner === AGENT_OWNER || typeof loadCoreMemoryContext !== 'function'
       ? undefined
@@ -94,8 +100,13 @@ export function publicWorkspaceMethods(api) {
     requestWorktree: (input) => api.requestWorktree(input),
     mergeWorkspace: (input) => api.mergeWorkspace(input),
     removeWorktree: (input) => api.removeWorktree(input),
-    listWorktrees: () => api.listWorktrees(),
-    pruneWorktrees: () => api.pruneWorktrees(),
+    // External callers get the list with its details (Settings → Worktrees).
+    listWorktrees: () => api.listWorktrees({ details: true }),
+    pruneWorktrees: (input) => api.pruneWorktrees({ repoCommonDir: input?.repoCommonDir ?? null }),
+    previewWorktreeCleanup: (input) => api.previewWorktreeCleanup({ repoCommonDir: input?.repoCommonDir ?? null }),
+    deleteWorktree: (input) => api.deleteWorktree(input),
+    getSessionWorktreeWork: (input) => api.getSessionWorktreeWork(input),
+    setArchivedSessionWorktrees: (input) => api.setArchivedSessionWorktrees(input),
   };
 }
 
@@ -285,7 +296,12 @@ export function createWorkspaceTransitions({
     switchProject: runner.switchProject,
     listWorktrees: worktrees.listWorktrees,
     pruneWorktrees: worktrees.pruneWorktrees,
+    previewWorktreeCleanup: worktrees.previewWorktreeCleanup,
+    deleteWorktree: worktrees.deleteWorktree,
     removeOrphanWorktree: worktrees.removeOrphanWorktree,
+    removeOwnedWorktree: worktrees.removeOwnedWorktree,
+    getSessionWorktreeWork: worktrees.getSessionWorktreeWork,
+    setArchivedSessionWorktrees: worktrees.setArchivedSessionWorktrees,
     cleanupDeletedSession: worktrees.cleanupDeletedSession,
     onWorktreeSetup: setup.onWorktreeSetup,
     dispose: checkouts.dispose,

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

@@ -32,14 +32,59 @@ export function createWorktreeMaintenance({
    * 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());
+  async function listWorktrees({ includeSnapshots = false, details = false } = {}) {
+    const rows = await maintenance.listWorktreesWithRetention({
+      ...(await maintenanceScope()),
+      details,
+      settings: worktreeSettings(),
+    });
     return includeSnapshots ? rows : rows.filter((row) => row.kind !== WORKTREE_SNAPSHOT_KIND);
   }
 
-  /** The manual prune: clean, merged worktrees no stored or live session retains. */
+  /** The manual prune: clean, merged worktrees no stored or live session retains
+   *  (plus, with autoCleanup on, what the automatic cleanup would remove). */
   async function pruneWorktrees({ repoCommonDir = null } = {}) {
-    return maintenance.pruneWorktrees({ ...(await maintenanceScope()), repoCommonDir });
+    return maintenance.pruneWorktrees({
+      ...(await maintenanceScope()),
+      repoCommonDir,
+      settings: worktreeSettings(),
+      currentLiveSessionIds: () => listLiveSessions().map((candidate) => candidate?.id),
+    });
+  }
+
+  /** Whether the manual prune could act on anything (no git verification, nothing removed). */
+  async function previewWorktreeCleanup({ repoCommonDir = null } = {}) {
+    const { hasCandidates } = await maintenance.previewWorktreeCleanup({
+      ...(await maintenanceScope()),
+      repoCommonDir,
+      settings: worktreeSettings(),
+    });
+    return { hasCandidates };
+  }
+
+  /**
+   * Delete managed worktree `entryId` from the worktree list (Settings →
+   * Worktrees), whoever owns it: a session the store keeps no longer protects
+   * it, but a live owner or a session or background command working in the
+   * folder refuses (folder-in-use, folder-shell-jobs, workspace-lease), as do
+   * other sessions' shared references and retained recovery data. Dirty or
+   * unmerged work needs `force`; a forced unmerged tip stays under
+   * refs/mixdog/removed/<id>.
+   */
+  async function deleteWorktree({ 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], false, async () => {
+      const { liveSessionIds, listSessionIds, manager: backendApi } = await maintenanceScope();
+      return backendApi.removeOrphanedWorktree({
+        entryId,
+        force: force === true,
+        liveSessionIds,
+        retainedSessionIds: await listSessionIds(),
+        allowRetained: true,
+      });
+    });
+    return { removed, entryId, path: row.path };
   }
 
   /**
@@ -70,11 +115,86 @@ export function createWorktreeMaintenance({
   async function cleanupDeletedSession(sessionId) {
     // Its snapshots go with it below; no turn cleanup keeps retrying them.
     cancelSnapshotCleanups(sessionId);
+    const settings = worktreeSettings();
     return maintenance.cleanupDeletedSessionWorktree(sessionId, {
       manager: await backend(),
-      autoCleanup: worktreeSettings().autoCleanup,
+      autoCleanup: settings.autoCleanup,
+      deleteBranch: settings.deleteBranch,
+    });
+  }
+
+  /**
+   * Remove managed worktree `entryId` this session owns but does not work in
+   * now, without entering it first: the session does not move, so its own
+   * turn and workers elsewhere never block it. The folder's consumers still
+   * refuse (another session or a background command in it), as do dirty or
+   * unmerged work without `force`, other sessions' references and retained
+   * recovery data (the manager's guards).
+   */
+  async function removeOwnedWorktree({ entryId, force = false } = {}) {
+    const session = getSession();
+    const row = (await listWorktrees()).find((item) => item.id === entryId);
+    if (!row) throw worktreeError('WORKTREE_MISSING', undefined, { entryId });
+    if (!session?.id || row.ownerSessionId !== session.id) {
+      throw worktreeError('WORKTREE_BUSY_JOBS', 'This worktree belongs to another session.', {
+        reason: 'workspace-shared',
+        sessions: [row.ownerSessionId].filter(Boolean),
+      });
+    }
+    if (session.workspace?.worktreeId === entryId) {
+      throw worktreeError('WORKTREE_BUSY_JOBS', 'The session works in this worktree; return to the project first.', {
+        reason: 'folder-in-use',
+        sessions: [session.id],
+      });
+    }
+    const removed = await withManagementFolders([row.path], true, async () =>
+      (await backend()).removeManagedWorktree({ entryId, force: force === true, sessionId: session.id })
+    );
+    return { removed, entryId, path: row.path };
+  }
+
+  /**
+   * Of `sessionIds`, the ones owning a managed worktree whose removal would be
+   * refused without `force` (dirty or unmerged work, another session's
+   * reference, retained recovery data): the desktop's auto-delete keeps those
+   * sessions archived. Read-only; a check that fails counts as holding work.
+   */
+  async function getSessionWorktreeWork({ sessionIds = [] } = {}) {
+    const wanted = new Set((Array.isArray(sessionIds) ? sessionIds : []).filter((id) => typeof id === 'string' && id));
+    const holding = new Set();
+    if (!wanted.size) return { sessionIds: [] };
+    const manager = await backend();
+    for (const row of await listWorktrees()) {
+      const owner = row.ownerSessionId;
+      if (!wanted.has(owner) || holding.has(owner)) continue;
+      try {
+        await manager.assertWorktreeRemovable({ entryId: row.id, sessionId: owner });
+      } catch {
+        holding.add(owner);
+      }
+    }
+    return { sessionIds: [...holding] };
+  }
+
+  /** Archived (or restored) sessions: autoCleanup and cleanupArchived decide whether their worktrees become disposable. */
+  async function setArchivedSessionWorktrees({ sessionIds = [], archived = false } = {}) {
+    const settings = worktreeSettings();
+    return maintenance.setArchivedSessionWorktrees(sessionIds, archived === true, {
+      manager: await backend(),
+      autoCleanup: settings.autoCleanup,
+      cleanupArchived: settings.cleanupArchived,
     });
   }
 
-  return { listWorktrees, pruneWorktrees, removeOrphanWorktree, cleanupDeletedSession };
+  return {
+    listWorktrees,
+    pruneWorktrees,
+    previewWorktreeCleanup,
+    deleteWorktree,
+    removeOrphanWorktree,
+    removeOwnedWorktree,
+    getSessionWorktreeWork,
+    setArchivedSessionWorktrees,
+    cleanupDeletedSession,
+  };
 }