mixdog 1.4.0 → 1.4.1

package/src/session-runtime/services/agent-tool/execute.mjs

@@ -66,15 +66,20 @@ export function createAgentExecute({
             });
           }
           // Targetless status is the same compact overview as list.
-          return renderResult({
-            // Idle workers stay open for follow-ups; the model must see them to close them.
-            workers: views.list({
-              scanSessions: registry.wantsSessionScan(args),
-              context: scopedContext,
-              includeIdle: true,
-            }),
-            jobs: views.listJobs(scopedContext),
-          });
+          return renderResult(
+            {
+              // Idle workers stay open for follow-ups; the roster counts them and
+              // lists a bounded tail (or the `tag` matches) so they can be closed.
+              workers: views.list({
+                scanSessions: registry.wantsSessionScan(args),
+                context: scopedContext,
+                includeIdle: true,
+                includeClosed: true,
+              }),
+              jobs: views.listJobs(scopedContext),
+            },
+            { listFilter: clean(args.tag) }
+          );
         case 'read':
           return await readJob(args, scopedContext);
         case 'cleanup':

package/src/session-runtime/services/agent-tool/job-views/agent-list.mjs

@@ -27,8 +27,12 @@ export function isActiveWorkerRow(row = {}) {
 
 // A finished worker that is still open: it takes follow-ups and can be closed.
 function isOpenIdleRow(row = {}) {
-  const status = String(row.status ?? '').trim().toLowerCase();
-  const stage = String(row.stage ?? '').trim().toLowerCase();
+  const status = String(row.status ?? '')
+    .trim()
+    .toLowerCase();
+  const stage = String(row.stage ?? '')
+    .trim()
+    .toLowerCase();
   if (CANCELLED_WORKER_STATUS.test(stage) || CANCELLED_WORKER_STATUS.test(status)) return false;
   return (status || stage) === 'idle';
 }
@@ -86,7 +90,13 @@ function agentRow({ tag, session, runtime, progress, now, indexRow = null }) {
 }
 
 export function createAgentList({ mgr, refreshTagsFromSessions, agentSessionEntries, progress }) {
-  return function list({ scanSessions = false, context = {}, includeTerminal = false, includeIdle = false } = {}) {
+  return function list({
+    scanSessions = false,
+    context = {},
+    includeTerminal = false,
+    includeIdle = false,
+    includeClosed = false,
+  } = {}) {
     refreshTagsFromSessions({ scanSessions, context });
     const now = Date.now();
     const rows = [];
@@ -98,7 +108,13 @@ export function createAgentList({ mgr, refreshTagsFromSessions, agentSessionEntr
       // 2 s) would otherwise read every worker it ever ran, whole transcripts
       // on first sight, synchronously on the daemon loop.
       const state = rowState(session, runtime);
-      if (!includeTerminal && !isActiveWorkerRow(state) && !(includeIdle && isOpenIdleRow(state))) continue;
+      if (
+        !includeTerminal &&
+        !isActiveWorkerRow(state) &&
+        !(includeIdle && isOpenIdleRow(state)) &&
+        !(includeClosed && state.status === 'closed')
+      )
+        continue;
       rows.push(
         agentRow({
           tag,

package/src/session-runtime/services/agent-tool/model-select.mjs

@@ -1,9 +1,10 @@
 // One-off model selection for a spawn the user explicitly pinned to a model.
 // The agent's preset route stays the default; this only runs when `model` is
-// passed. The query is matched against the live provider catalog — exact id,
-// then exact display name, then every query word — and a catalog miss retries
-// once on a refreshed catalog. One match runs; several or none fail with
-// candidates instead of substituting another model.
+// passed. The query is matched against the quick/cached provider catalog —
+// literal id, then normalized id, then exact display name, then every query
+// word — and a catalog miss retries once on a catalog refreshed for the
+// requested provider (concurrent misses share that refresh). One match runs;
+// several or none fail with candidates instead of substituting another model.
 import { clean } from './helpers.mjs';
 
 const CANDIDATE_LIMIT = 8;
@@ -20,7 +21,7 @@ const terms = (value) =>
     .filter(Boolean);
 const label = (row) => `${row.provider}/${row.id}`;
 
-function providerRows(rows, provider) {
+export function providerRows(rows, provider) {
   if (!provider) return rows;
   const wanted = norm(provider);
   const exact = rows.filter((row) => norm(row.provider) === wanted);
@@ -33,6 +34,8 @@ function matchModels(rows, query) {
   // Nothing to match on ("???"): `[].every` would accept every row.
   if (!words.length) return [];
   const tiers = [
+    // A literal id wins over its normalized look-alikes (`foo-bar` vs `foo_bar`).
+    (row) => row.id === query,
     (row) => norm(row.id) === wanted,
     (row) => norm(row.display) === wanted,
     (row) => words.every((word) => `${norm(row.id)} ${norm(row.display)}`.includes(word)),
@@ -49,6 +52,34 @@ function candidates(rows) {
   return rows.length > CANDIDATE_LIMIT ? `${shown}, … (${rows.length} total)` : shown;
 }
 
+// A quick read answered from the loaded catalog marks every row complete.
+// Otherwise a hit stands only when it is a literal id of the exact provider the
+// caller named, which the full catalog would pick the same way.
+function quickAnswerHolds(rows, hits, model, provider) {
+  if (rows.length > 0 && rows.every((row) => row.catalogComplete === true)) return true;
+  const wanted = norm(provider);
+  return hits.length > 0 && wanted !== '' && hits.every((row) => row.id === model && norm(row.provider) === wanted);
+}
+
+// The forced refresh in flight per catalog reader and provider scope: concurrent
+// misses share it instead of each refreshing.
+const refreshing = new WeakMap();
+
+// One forced refresh, scoped to the requested provider when one is given.
+function refreshedRows(listProviderModels, provider) {
+  if (!refreshing.has(listProviderModels)) refreshing.set(listProviderModels, new Map());
+  const inflight = refreshing.get(listProviderModels);
+  const scope = norm(provider);
+  if (!inflight.has(scope)) {
+    const request = listProviderModels({ force: true, ...(provider ? { provider } : {}) });
+    inflight.set(
+      scope,
+      request.finally(() => inflight.delete(scope))
+    );
+  }
+  return inflight.get(scope);
+}
+
 /** Resolve args.provider/args.model to one exact catalog route. Without a
  *  catalog (headless/daemon surfaces) exact provider + model pass through. */
 export async function resolveRequestedModel(args, listProviderModels) {
@@ -64,10 +95,20 @@ export async function resolveRequestedModel(args, listProviderModels) {
     if (!terms(model).length) throw new Error(`agent spawn: model "${model}" for provider "${provider}" not found`);
     return args;
   }
-  let pool = providerRows(await listProviderModels(), provider);
+  // The quick/cached catalog answers first. A loaded catalog is final, so its
+  // hit never waits on a provider; an incomplete one (cold or partial) may
+  // lack the model that wins, or one that makes the name ambiguous, so only a
+  // literal id inside an exact, explicitly named provider is taken from it.
+  // Anything else waits for the full catalog.
+  const quickRows = await listProviderModels({ quick: true });
+  let pool = providerRows(quickRows, provider);
   let hits = matchModels(pool, model);
+  if (!quickAnswerHolds(quickRows, hits, model, provider)) {
+    pool = providerRows(await listProviderModels(), provider);
+    hits = matchModels(pool, model);
+  }
   if (!hits.length) {
-    pool = providerRows(await listProviderModels({ force: true }), provider);
+    pool = providerRows(await refreshedRows(listProviderModels, provider), provider);
     hits = matchModels(pool, model);
   }
   if (hits.length === 1) return { ...args, provider: hits[0].provider, model: hits[0].id };

package/src/session-runtime/services/agent-tool/render.mjs

@@ -1,5 +1,7 @@
 // Pure result-rendering and finish-classification helpers.
 import { oneLine } from '../../../runtime/shared/clean.mjs';
+import { isActiveWorkerRow } from './job-views/agent-list.mjs';
+import { isTerminalJobStatus } from './job-views/session-progress.mjs';
 import { compactIso, elapsedFromStamps, stripFinalAnswerWrapper } from './helpers.mjs';
 
 // A worker that gets truncated mid-synthesis or produces an empty terminal
@@ -32,25 +34,77 @@ export function abnormalEmptyFinishError(result, agent) {
   }
 }
 
-// The /agents roster: worker rows then task rows.
-function renderRoster(value) {
+const ROSTER_TAIL = 5;
+const ROSTER_MATCH_CAP = 25;
+
+function workerLine(worker) {
+  const status = worker.status || 'idle';
+  const stage = worker.worker_stage || worker.stage;
+  const progress = oneLine(worker.last_progress);
+  const summary = progress.length > 60 ? `${progress.slice(0, 59)}…` : progress;
+  return `- ${worker.tag}  ${status}${stage && stage !== status ? `/${stage}` : ''}${summary ? `  ${summary}` : ''}`;
+}
+
+function jobLine(job) {
+  const error = job.status === 'failed' ? oneLine(job.error) : '';
+  return `- ${job.task_id}  ${job.type}  ${job.status}  ${job.tag || '-'}${error ? ` error=${error}` : ''}`;
+}
+
+const stamp = (row) => String(row.updatedAt || row.lastUsedAt || row.finishedAt || row.startedAt || '');
+
+// Inactive rows: newest first (stable for rows without stamps).
+const newestFirst = (rows) => rows.slice().sort((a, b) => stamp(b).localeCompare(stamp(a)));
+
+// Inactive rows collapse to a count plus a short tail. A `tag` filter lists the
+// matching inactive rows (bounded) so a specific one can still be found.
+function inactiveSection(label, rows, render, tagOf, filter) {
+  if (rows.length === 0) return [];
+  const needle = filter.toLowerCase();
+  const matched = needle
+    ? rows.filter((row) =>
+        String(tagOf(row) ?? '')
+          .toLowerCase()
+          .includes(needle)
+      )
+    : null;
+  const shown = newestFirst(matched ?? rows).slice(0, matched ? ROSTER_MATCH_CAP : ROSTER_TAIL);
+  const shownFilter = filter.replace(/\s+/g, ' ');
+  const head = matched
+    ? `${label}: ${rows.length} (${matched.length} match tag "${shownFilter}", showing ${shown.length})`
+    : `${label}: ${rows.length} (latest ${shown.length}; pass tag=<text> to find one)`;
+  // Bulleted: a non-bullet line would make the list read as an authored response.
+  return [`- ${head}`, ...shown.map(render)];
+}
+
+// The /agents roster: active workers and running tasks in full; idle/closed
+// workers and finished tasks as counts with a bounded tail.
+function renderRoster(value, filter = '') {
   const workers = Array.isArray(value.workers) ? value.workers : [];
   const jobs = Array.isArray(value.jobs) ? value.jobs : [];
   const lines = [`agents: ${workers.length} · tasks: ${jobs.length}`];
+  const isActive = (worker) => Boolean(worker.awaitingUser) || isActiveWorkerRow(worker);
+  const isRunning = (job) => !isTerminalJobStatus(job.status);
   // Keep list bullets: agent cards distinguish these rows from authored responses.
-  for (const worker of workers) {
-    const status = worker.status || 'idle';
-    const stage = worker.worker_stage || worker.stage;
-    const progress = oneLine(worker.last_progress);
-    const summary = progress.length > 60 ? `${progress.slice(0, 59)}…` : progress;
-    lines.push(
-      `- ${worker.tag}  ${status}${stage && stage !== status ? `/${stage}` : ''}${summary ? `  ${summary}` : ''}`
-    );
-  }
-  for (const job of jobs) {
-    const error = job.status === 'failed' ? oneLine(job.error) : '';
-    lines.push(`- ${job.task_id}  ${job.type}  ${job.status}  ${job.tag || '-'}${error ? ` error=${error}` : ''}`);
-  }
+  lines.push(...workers.filter(isActive).map(workerLine));
+  lines.push(...jobs.filter(isRunning).map(jobLine));
+  lines.push(
+    ...inactiveSection(
+      'idle/closed agents',
+      workers.filter((w) => !isActive(w)),
+      workerLine,
+      (w) => w.tag,
+      filter
+    )
+  );
+  lines.push(
+    ...inactiveSection(
+      'finished tasks',
+      jobs.filter((j) => !isRunning(j)),
+      jobLine,
+      (j) => j.tag || j.task_id,
+      filter
+    )
+  );
   if (workers.length === 0 && jobs.length === 0) lines.push('(no agents or tasks)');
   return lines.join('\n');
 }
@@ -151,11 +205,11 @@ function renderContent(value) {
   return `${header}\n${stripFinalAnswerWrapper(value.content)}`;
 }
 
-export function renderResult(value, { includeDiagnostics = false } = {}) {
+export function renderResult(value, { includeDiagnostics = false, listFilter = '' } = {}) {
   if (value === undefined || value === null) return '';
   if (typeof value === 'string') return value;
   if (value && typeof value === 'object') {
-    if (Array.isArray(value.workers) || Array.isArray(value.jobs)) return renderRoster(value);
+    if (Array.isArray(value.workers) || Array.isArray(value.jobs)) return renderRoster(value, listFilter);
     // close-flow results carry `closed` plus task_id: render the close outcome.
     // close-flow results carry `closed` plus task_id: render the close outcome.
     if (value.closed !== undefined) return renderClosed(value);

package/src/session-runtime/services/agent-tool/spawn-preset.mjs

@@ -1,4 +1,5 @@
 import { configuredAgentRouteCandidates } from '../../../runtime/shared/agent-route-config.mjs';
+import { executionFallbacks } from '../../../runtime/shared/model-route-chain.mjs';
 import {
   agentPresetName,
   clean,
@@ -29,8 +30,11 @@ export function resolveAgentSpawnPreset(config, args = {}) {
   const agentName = normalizeAgentName(args.agent);
   // The agent's stored route: config.agents, or a store bot's own folder.
   const candidates = !clean(args.preset) ? configuredAgentRouteCandidates(config, agentName) : [];
-  const agentRoute = candidates.map((candidate) => normalizeAgentRoute(candidate)).find(Boolean) || null;
-  const storedFallbacks = candidates.find((candidate) => normalizeAgentRoute(candidate))?.fallbacks;
+  const storedCandidate = candidates.find((candidate) => normalizeAgentRoute(candidate));
+  const agentRoute = storedCandidate ? normalizeAgentRoute(storedCandidate) : null;
+  const storedFallbacks = agentRoute
+    ? executionFallbacks({ ...agentRoute, fallbacks: storedCandidate.fallbacks })
+    : undefined;
   // Where the spawned session reads its fallback chain at each hop
   // (route-fallback-chain.mjs): this agent's route, else Main's.
   const fallbackSource = { agent: agentName };

package/src/session-runtime/services/agent-tool/tool-def.mjs

@@ -28,7 +28,7 @@ export const AGENT_TOOL = {
     agentHidden: false,
   },
   description:
-    'Run scoped agent work as background tasks. spawn/send return task_id immediately. Reuse one tag for one scope for its whole lifetime; give distinct tags only to independent scopes. Never mint a new tag because a session expired or was lost — same-tag spawn respawns it with the full brief. Wait for completion notifications; use status/read only for manual recovery. Close finished agents yourself.',
+    'Run scoped agent work as background tasks. spawn/send return task_id immediately. Reuse one tag for one scope for its whole lifetime; give distinct tags only to independent scopes. Never mint a new tag because a session expired or was lost — same-tag spawn respawns it with the full brief. Completion notifications arrive automatically; use status/read only for manual recovery. Close finished agents yourself.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -36,21 +36,21 @@ export const AGENT_TOOL = {
         type: 'string',
         enum: ['spawn', 'send', 'list', 'close', 'cancel', 'status', 'read', 'cleanup'],
         description:
-          'Required action. New spawn requires agent and one of prompt/message/file; send requires tag and one of prompt/message/file; read/status/close/cancel require task_id or tag; list/cleanup require no target.',
+          'Required action. New spawn requires agent and one of prompt/message/file; send requires tag and one of prompt/message/file; read/status/close/cancel require task_id or tag; list/cleanup require no target. list shows active agents and running tasks in full; idle/closed agents and finished tasks are counts plus a short latest tail (list with tag=<text> shows matching ones: case-insensitive substring, at most 25 per section).',
       },
-      task_id: { type: 'string', description: 'Task ID returned by spawn/send; target for read/status/close/cancel.' },
+      task_id: { type: 'string', description: 'Task ID returned by spawn/send.' },
       agent: {
         type: 'string',
-        description: 'Workflow agent id. Required for a new spawn; same-tag reuse can inherit it.',
+        description: 'Workflow agent id; same-tag reuse can inherit it.',
       },
       tag: {
         type: 'string',
         description:
-          'Stable scope handle. Reuse the same tag for the same scope; never derive a variant by appending a number or suffix. send requires it, while spawn can generate one when omitted.',
+          'Stable scope handle; never derive a variant by appending a number or suffix. spawn generates one when omitted.',
       },
-      prompt: { type: 'string', description: 'Spawn task brief; also accepted for send.' },
-      message: { type: 'string', description: 'Send follow-up; also accepted for spawn.' },
-      file: { type: 'string', description: 'Path to task text; alternative to prompt/message for spawn/send.' },
+      prompt: { type: 'string', description: 'Spawn task brief.' },
+      message: { type: 'string', description: 'Send follow-up.' },
+      file: { type: 'string', description: 'Path to task text; used instead of prompt/message.' },
       cwd: { type: 'string', description: 'Project directory for a new or respawned agent.' },
       context: { type: 'string', description: 'Extra context for the spawn/send turn.' },
       attachments: {
@@ -63,7 +63,7 @@ export const AGENT_TOOL = {
       model: {
         type: 'string',
         description:
-          "Spawn only, and only when the user explicitly names a model: runs this one spawn on it instead of the agent's preset route, which stays the default (omit otherwise). Id, display name, or words of it; ambiguous or unknown names fail with candidates. The agent still supplies role and permissions.",
+          "Spawn only, and only when the user explicitly names a model: runs this one spawn on it instead of the agent's preset route. Id, display name, or words of it; ambiguous or unknown names fail with candidates. The agent still supplies role and permissions.",
       },
       provider: { type: 'string', description: 'Narrows model to one provider; requires model.' },
       effort: { type: 'string', description: 'Reasoning effort for an explicit model.' },

package/src/session-runtime/services/provider-admin.mjs

@@ -1179,7 +1179,8 @@ export async function saveCustomProvider(cfgMod, rawInput) {
 export async function saveCustomProviderKey(cfgMod, rawId, rawKey) {
   requireLocalProviderManagement();
   const id = String(rawId || '').trim();
-  if (typeof rawKey !== 'string' || rawKey.length > CUSTOM_API_KEY_MAX) throw new TypeError('custom provider apiKey is invalid');
+  if (typeof rawKey !== 'string' || rawKey.length > CUSTOM_API_KEY_MAX)
+    throw new TypeError('custom provider apiKey is invalid');
   const key = rawKey.trim();
   if (!key) throw new Error('API key is required');
   const takesStoredKey = () => {

package/src/session-runtime/tool-policy/policy-stage.mjs

@@ -135,6 +135,7 @@ export function createPolicyStage({
         : _buildBaseRules({
             omitTools: [...denied, unusedModelEditToolName(getRoute()?.model)],
             allowTools: schemaAllowedTools,
+            ownerIsAgent,
             provider: getRoute()?.provider,
             model: getRoute()?.model,
           });

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

@@ -19,7 +19,11 @@ import {
   writeJsonAtomicSync,
 } from '../../runtime/shared/atomic-file.mjs';
 import { clean } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
-import { agentEntryFile, agentEntryPath, parseManifestText } from '../../runtime/agent/orchestrator/runtime-core/workflow/agents.mjs';
+import {
+  agentEntryFile,
+  agentEntryPath,
+  parseManifestText,
+} from '../../runtime/agent/orchestrator/runtime-core/workflow/agents.mjs';
 import { hasOwn } from '../../runtime/shared/object.mjs';
 import { serializeFrontmatterDoc } from '../../runtime/shared/markdown-frontmatter.mjs';
 import { isHiddenAgent } from '../../runtime/agent/orchestrator/internal-agents.mjs';

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

@@ -22,7 +22,11 @@ import {
 
 /** Mixy's runtime id (agent-home.mjs MIXY_AGENT_ID). */
 const MIXY_RUNTIME_ID = 'lead';
-import { routeChain, validateRouteChainProviders } from '../../runtime/shared/model-route-chain.mjs';
+import {
+  canonicalRouteProvider,
+  routeChain,
+  validateRouteChainProviders,
+} from '../../runtime/shared/model-route-chain.mjs';
 
 // Agent route persistence. Route-scope isolation: an agent route owns its
 // model AND its effort/fast, stored in config.agents[<id>]. The shared
@@ -183,18 +187,25 @@ export function createAgentRouteApi(deps) {
     }
     if (!clean(requested.provider)) return clearOverride(id);
     if (!clean(requested.model)) throw new Error('agent route requires provider and model');
+    // An explicit list is validated; the stored one may hold a fallback on the
+    // picked model's provider, which stays saved untouched and inactive.
+    const explicitFallbacks = hasOwn(requested, 'fallbacks');
     const chain = routeChain({
       ...requested,
-      fallbacks: hasOwn(requested, 'fallbacks') ? requested.fallbacks : stored.fallbacks,
+      fallbacks: explicitFallbacks ? requested.fallbacks : stored.fallbacks,
     });
-    validateRouteChainProviders(chain);
+    validateRouteChainProviders(chain, { allowDuplicates: !explicitFallbacks });
     const storedChain = routeChain(stored);
     const resolved = [];
+    const usedProviders = new Set();
     for (const entry of chain) {
+      const provider = canonicalRouteProvider(entry.provider);
+      const inactive = usedProviders.has(provider);
+      usedProviders.add(provider);
       const previous = storedChain.find(
         (candidate) => candidate.provider === entry.provider && candidate.model === entry.model
       );
-      resolved.push(await resolveChainEntry(deps, entry, previous || {}));
+      resolved.push(inactive ? entry : await resolveChainEntry(deps, entry, previous || {}));
     }
     const [primary, ...fallbacks] = resolved;
     const routeToSave = normalizeWorkflowRoute({ ...primary, fallbacks });

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

@@ -20,7 +20,7 @@ import { resolveDataDir } from './shared.mjs';
 function applyWorkflowSlots(workflowInput, draft) {
   for (const slot of WORKFLOW_ROUTE_SLOTS) {
     if (!hasOwn(workflowInput, slot)) continue;
-    const normalized = normalizeWorkflowRoute(workflowInput[slot]);
+    const normalized = normalizeWorkflowRoute(workflowInput[slot], {}, { strict: true });
     if (slot === 'lead') {
       if (!normalized) continue;
       draft.presets = upsertWorkflowPreset(draft.presets, 'lead', normalized);
@@ -40,7 +40,7 @@ function applyAgentRouteInput(agentInput, agentRoutes, configurableIds) {
   const nextAgents = { ...agentRoutes };
   for (const id of configurableIds) {
     if (!hasOwn(agentInput, id)) continue;
-    const routeToSave = normalizeWorkflowRoute(agentInput[id]);
+    const routeToSave = normalizeWorkflowRoute(agentInput[id], {}, { strict: true });
     if (routeToSave) nextAgents[id] = routeToSave;
     else delete nextAgents[id];
   }
@@ -67,7 +67,7 @@ export function createOnboardingApi(deps) {
       const config = getConfig();
       const nextConfig = { ...config };
       const defaultRoute = hasOwn(payload, 'defaultRoute')
-        ? normalizeWorkflowRoute(payload.defaultRoute, getRoute())
+        ? normalizeWorkflowRoute(payload.defaultRoute, getRoute(), { strict: true })
         : null;
       const draft = {
         presets: Array.isArray(nextConfig.presets) ? nextConfig.presets.slice() : [],

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

@@ -752,6 +752,30 @@ export function createWorkspaceTransitions({
     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.
@@ -1219,6 +1243,7 @@ export function createWorkspaceTransitions({
     switchProject,
     listWorktrees,
     pruneWorktrees,
+    removeOrphanWorktree,
     cleanupDeletedSession,
     onWorktreeSetup,
     dispose,

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

@@ -27,12 +27,7 @@ const loadManager = () => import('../../runtime/shared/worktrees/manager.mjs');
  * @param {((args: object, context: object) => Promise<any>)|null} [deps.executeSessionControl] Cross-session lane.
  * @param {object|null} [deps.manager] Managed-worktree backend override (tests).
  */
-export function createWorktreeToolHost({
-  getSession,
-  getWorkspaceApi,
-  executeSessionControl = null,
-  manager = null,
-}) {
+export function createWorktreeToolHost({ getSession, getWorkspaceApi, executeSessionControl = null, manager = null }) {
   const backend = () => (manager ? Promise.resolve(manager) : loadManager());
 
   function workspaceApi() {
@@ -102,7 +97,11 @@ export function createWorktreeToolHost({
         'The project folder has no checked-out branch to return to (detached HEAD).'
       );
     }
-    return lane.call('selectBranch', { branch: projectBranch, expectedRevision: workspace.revision, txId: request.txId });
+    return lane.call('selectBranch', {
+      branch: projectBranch,
+      expectedRevision: workspace.revision,
+      txId: request.txId,
+    });
   }
 
   /** The desktop's "merge": into the confirmed merge target, then the cleanup autoCleanup allows. */
@@ -116,6 +115,15 @@ export function createWorktreeToolHost({
     });
   }
 
+  /**
+   * The listed worktree matching `predicate` whose owner is gone and that the
+   * list reports removable, or null: no owner lane can remove it.
+   */
+  async function orphan(predicate) {
+    const rows = await workspaceApi().listWorktrees();
+    return rows.find((row) => predicate(row) && row.ownerLive === false && row.removable === true) ?? null;
+  }
+
   /**
    * `git worktree remove <path>`: the managed removal of whichever owner
    * holds it — this session's snapshot, or the worktree a session retains
@@ -129,6 +137,9 @@ export function createWorktreeToolHost({
       );
     }
     if (entry.kind === 'snapshot') return workspaceApi().removeSnapshot({ path: entry.path, force: request.force });
+    if (entry.ownerSessionId !== callerSessionId && (await orphan((row) => row.id === entry.id))) {
+      return workspaceApi().removeOrphanWorktree({ entryId: entry.id, force: request.force === true });
+    }
     if (!entry.ownerSessionId) {
       throw new Error(
         `git worktree remove: no session retains ${entry.path}; git worktree prune removes it once it is clean and merged`
@@ -161,8 +172,14 @@ export function createWorktreeToolHost({
         return back(lane(), request);
       case 'merge':
         return merge(lane());
-      case 'remove':
-        return lane().call('removeWorktree', { force: request.force === true });
+      case 'remove': {
+        const force = request.force === true;
+        if (request.sessionId && request.sessionId !== callerSessionId) {
+          const gone = await orphan((row) => row.ownerSessionId === request.sessionId);
+          if (gone) return workspaceApi().removeOrphanWorktree({ entryId: gone.id, force });
+        }
+        return lane().call('removeWorktree', { force });
+      }
       case 'list':
         return workspaceApi().listWorktrees({ includeSnapshots: true });
       case 'prune':

package/src/standalone/daemon-session-control.mjs

@@ -7,6 +7,7 @@ import {
 import { createAgentTaskSessions, taskSessionPendingWork } from '../session-runtime/agent-task-sessions.mjs';
 import { createBotStatus, scanCatalog, scopedBot } from '../session-runtime/bot-status.mjs';
 import { handoffContent } from '../session-runtime/handoff-attachments.mjs';
+import { BOT_TARGET_ACTIONS, isBotShaped, unknownBotError } from '../session-runtime/bot-target.mjs';
 import { checkEffort, readModelCatalog } from '../session-runtime/task-session-route.mjs';
 import { assertBotChainTarget, botChainOf } from '../runtime/shared/bot-hops.mjs';
 import { agentIdOfHomeSession } from '../runtime/agent/orchestrator/session/agent-home.mjs';
@@ -82,7 +83,8 @@ async function storedTitle(sessionId) {
 export function createSessionControl({
   getSessionService,
   agentTasks = createAgentTaskSessions({ getSessionService }),
-  botStatus = createBotStatus({ getSessionService }),
+  listBots,
+  botStatus = createBotStatus({ getSessionService, listBots }),
   // Agent work a session handed off and still waits on (agent-task-sessions.mjs).
   pendingWork = taskSessionPendingWork,
   liveWork = storedLiveWork,
@@ -92,7 +94,7 @@ export function createSessionControl({
   const worktreeControl = createWorktreeControl(getSessionService);
   const routeControl = createRouteControl(getSessionService);
 
-  return async function executeSessionControl(args = {}, context = {}) {
+  async function control(args = {}, context = {}) {
     const action = args.action;
     const caller = requestCaller(action, context);
     // `callerAgentId`: set only for an attended agent conversation (workspace-tools.mjs).
@@ -263,5 +265,19 @@ export function createSessionControl({
       agentsWorking: (await pendingWork(sessionId)) === true,
       quotaResume: snapshot.quotaResume ?? null,
     };
+  }
+
+  return async function executeSessionControl(args = {}, context = {}) {
+    try {
+      return await control(args, context);
+    } catch (error) {
+      // A bot id is resolved to its home chat before this (workspace-tools.mjs),
+      // so a bot-shaped id the session service found no session for is no bot
+      // either: say which ids are.
+      const id = typeof args.session_id === 'string' ? args.session_id.trim() : '';
+      const missing = [`${id} is not available`, `${id} is unavailable`].some((text) => error?.message?.includes(text));
+      if (!BOT_TARGET_ACTIONS.has(args.action) || !isBotShaped(id) || !missing) throw error;
+      throw await unknownBotError(id, listBots, error);
+    }
   };
 }