mixdog 1.3.2 → 1.3.4

package/src/runtime/agent/orchestrator/session/manager/idle-cleanup.mjs

@@ -2,8 +2,14 @@
 // Periodic idle-session + tombstone sweep.
 // Drives sweepStaleSessions on an unref'd interval; closeSession is imported
 // from session-close.mjs (one-way dependency, no cycle).
-import { sweepStaleSessions, sweepStaleSessionsCooperative, evictIdleLiveSessions } from '../store.mjs';
+import {
+  applySubAgentRetention,
+  sweepStaleSessions,
+  sweepStaleSessionsCooperative,
+  evictIdleLiveSessions,
+} from '../store.mjs';
 import { sweepOrphanedPendingMessages } from './pending-messages.mjs';
+import { applySessionSidebarChange, readSessionSidebarState } from '../../../../shared/session-sidebar-host.mjs';
 import {
   IN_FLIGHT_STAGES,
   _getRuntimeEntry,
@@ -83,6 +89,29 @@ function _logTombstoneSweep(tombstonesCleaned, tombstoneDetails, tombstoneErrors
   }
 }
 
+// Sub-agent trees the sweep found idle: archived after 3 days (through the
+// desktop's archive flag, when one is attached), deleted after 30
+// (store/sweep/sub-agent-retention.mjs).
+async function _retainSubAgents(members) {
+  if (!members?.length) return;
+  try {
+    const flags = await readSessionSidebarState();
+    const applied = await applySubAgentRetention(members, {
+      isSessionLive: _isSessionLive,
+      isArchived: flags && ((id) => Object.hasOwn(flags.archived, id)),
+      setSidebar: applySessionSidebarChange,
+    });
+    for (const id of applied.deleted) if (!_isSessionLive(id)) _clearSessionRuntime(id);
+    if (applied.archived.length || applied.deleted.length) {
+      _sweepLog(
+        `[session-sweep] sub-agent retention: archived ${applied.archived.length}${_previewIds(applied.archived.map((id) => ({ id })))}, deleted ${applied.deleted.length}${_previewIds(applied.deleted.map((id) => ({ id })))}\n`
+      );
+    }
+  } catch (e) {
+    process.stderr.write(`[session-sweep] sub-agent retention error: ${e?.message || e}\n`);
+  }
+}
+
 async function sweepIdleSessions({ includeTombstones = true, sweepIdle = true } = {}) {
   const startedAt = Date.now();
   try {
@@ -90,8 +119,10 @@ async function sweepIdleSessions({ includeTombstones = true, sweepIdle = true }
       sweepIdle,
       tombstoneMaxAgeMs: includeTombstones ? TOMBSTONE_MAX_AGE_MS : 0,
       isSessionLive: _isSessionLive,
+      retainSubAgents: sweepIdle,
     });
     const { cleaned, remaining, details, tombstonesCleaned = 0, tombstoneDetails = [], tombstoneErrors = [] } = result;
+    await _retainSubAgents(result.subAgents);
     if (cleaned > 0) {
       for (const d of details) {
         if (!_finalizeSweptSessionRuntime(d)) continue;

package/src/runtime/agent/orchestrator/session/manager/orchestration-mode-switch-notice.mjs

@@ -15,7 +15,7 @@
 //     the provider accepted it. `from` is the mode the model was last told
 //     about, `to` the session's mode now.
 // Every notice says it replaces the earlier ones, so the latest one wins.
-import { normalizeOrchestrationMode } from '../../../../shared/orchestration.mjs';
+import { normalizeOrchestrationMode, ORCHESTRATION_MODES } from '../../../../shared/orchestration.mjs';
 import { orchestrationInstructions } from '../../runtime-core/orchestration.mjs';
 
 /** The mode's name as its BP3 block titles it (`# Orchestration Mode: …`). */
@@ -31,6 +31,22 @@ export function promptOrchestrationModeOf(session) {
   return session?.orchestrationMode;
 }
 
+/**
+ * Read a shipped coding-mode slice from the actual BP3 message, not the mode
+ * metadata: older profile refreshes could rewrite one without the other.
+ * Only a complete, unambiguous generated slice is evidence. Custom rules,
+ * headings quoted in another slice, and unrecognized legacy layouts are not.
+ */
+export function orchestrationModeFromPrompt(session) {
+  const core = session?.messages?.find(
+    (message) => message?.role === 'system' && message.cacheTier === 'tier3'
+  )?.content;
+  if (typeof core !== 'string') return null;
+  const slices = core.split('\n\n---\n\n');
+  const modes = ORCHESTRATION_MODES.filter((mode) => slices.includes(orchestrationInstructions(mode)));
+  return modes.length === 1 ? modes[0] : null;
+}
+
 const listed = (names) => names.map((name) => `\`${name}\``).join(', ');
 
 /** The reminder that makes the Lead follow `mode`: self-contained (the mode's

package/src/runtime/agent/orchestrator/session/manager/pending-message-entry.mjs

@@ -3,6 +3,7 @@ import { mergeNormalizedContentEntries } from '../loop/steering.mjs';
 import { isDeliveredCompletion, logDuplicateSkip } from './delivered-completions.mjs';
 import { promptContentText } from './prompt-utils.mjs';
 import { parseTaskNotification, taskNotificationId } from '../../../../shared/task-notification-envelope.mjs';
+import { hopOf } from '../../../../shared/bot-hops.mjs';
 
 const STALE_USER_INJECTION_TTL_MS = 30 * 60 * 1000;
 const PENDING_PROCESS_START_MS = Date.now();
@@ -95,11 +96,13 @@ function executionFromCompletionMeta(meta) {
 function completionEntryFields(entry) {
   const executionId = completionExecutionId(entry);
   const execution = normalizeExecution(entry?.execution, executionId);
+  const hop = hopOf(entry?.hop);
   return {
     notificationKind: COMPLETION_NOTIFICATION_KIND,
     mode: PENDING_MODE_TASK_NOTIFICATION,
     ...(executionId ? { executionId } : {}),
     ...(execution ? { execution } : {}),
+    ...(hop ? { hop } : {}),
   };
 }
 
@@ -141,6 +144,8 @@ export function markCompletionEntry(text, options = {}) {
     mode: PENDING_MODE_TASK_NOTIFICATION,
     ...(executionId ? { executionId } : {}),
     ...(execution ? { execution } : {}),
+    // The bot-chain hop of the turn that launched the work (bot-hops.mjs).
+    ...(hopOf(options?.meta?.hop) ? { hop: options.meta.hop } : {}),
     enqueuedAt: Date.now(),
   };
 }
@@ -337,6 +342,7 @@ export function _groupPendingMessageEntries(entries) {
       ...merged,
       mode: PENDING_MODE_TASK_NOTIFICATION,
       ...(normalized.execution ? { execution: normalized.execution } : {}),
+      ...(normalized.hop ? { hop: normalized.hop } : {}),
       ids: idsOf([entry]),
       entries: [entry],
     });

package/src/runtime/agent/orchestrator/session/manager/prompt-utils.mjs

@@ -329,6 +329,42 @@ export function withPresentedWorkspaceSlices(session, nextHead) {
   return [nextHead, instructionFiles, memory].filter((part) => part?.trim()).join(BP3_PART_SEPARATOR);
 }
 
+const AGENT_CATALOG_HEADING = '# Available Agents';
+// One generated catalog line (workflow/context.mjs agentCatalog):
+// `- <name> (<id>)` with an optional `: <description>`.
+const AGENT_CATALOG_ENTRY = /^- (.+?) \(([^()\s]+)\)(?:: .*)?$/;
+
+/** The entries of a generated agent list slice, or null when `slice` is not
+ *  one (only the exact generated format is evidence). */
+export function agentListEntries(slice) {
+  const text = String(slice || '').trim();
+  if (!text.startsWith(`${AGENT_CATALOG_HEADING}\n\n`)) return null;
+  const entries = [];
+  for (const line of text.slice(AGENT_CATALOG_HEADING.length + 2).split('\n')) {
+    const match = AGENT_CATALOG_ENTRY.exec(line);
+    if (!match) return null;
+    entries.push({ id: match[2], name: match[1], line });
+  }
+  return entries;
+}
+
+/**
+ * The "# Available Agents" slice the session's prompt presents: '' when it
+ * carries none, null when what it carries under that heading is not one
+ * complete generated list (custom text, or more than one). A coding Lead's
+ * rebuilt core keeps a presented list, as it keeps the workspace slices: the
+ * list the model saw first stays the baseline every later agent list
+ * reminder applies to (agent-listing-notice.mjs).
+ */
+export function presentedAgentCatalogSlice(session) {
+  const core = session.bp3EnvSplit === true ? textOf(bp3SystemMessage(session)) : String(session.bp3CoreContext || '');
+  const slices = core
+    .split(BP3_PART_SEPARATOR)
+    .filter((slice) => slice === AGENT_CATALOG_HEADING || slice.startsWith(`${AGENT_CATALOG_HEADING}\n`));
+  if (!slices.length) return '';
+  return slices.length === 1 && agentListEntries(slices[0]) ? slices[0] : null;
+}
+
 const WORKSPACE_SLICES = ['environmentContext', 'coreMemoryContext', 'instructionFilesContext'];
 
 /**

package/src/runtime/agent/orchestrator/session/manager/session-crud.mjs

@@ -1,6 +1,7 @@
 // manager/session-crud.mjs
 // Session read + mutate CRUD: lookup (getSession/listSessions/findSessionByScopeKey),
 // message clear (with clear-fork), manual compaction, status update, and metric flush.
+import { createHash } from 'node:crypto';
 import {
   loadSession,
   saveSessionAsync,
@@ -29,6 +30,7 @@ import { hideCompactionArchive } from '../compaction-archive-capture.mjs';
 import { writeStderrBestEffort } from '../../../../shared/best-effort-stderr.mjs';
 import { forgetSideQuestion } from '../side-question-store.mjs';
 import { isAgentHomeSessionId } from '../agent-home.mjs';
+import { messageIdOf } from '../message-ids.mjs';
 
 /** Force-flush session metrics to disk. */
 export async function flushSessionMetrics(sessionId) {
@@ -412,19 +414,36 @@ export async function updateSessionStatus(id, status) {
 export async function rewindSessionMessagesTo(sessionId, options = {}) {
   const session = loadSession(sessionId);
   if (!session || session.closed === true) return null;
+  const targetId = String(options?.messageId ?? '').trim();
   const target = String(options?.text ?? '').trim();
-  if (!target) return null;
+  if (!targetId && !target) return null;
   const messages = Array.isArray(session.messages) ? session.messages : [];
-  let start = -1;
+  // The stable message id is the identity: the stored prompt is the EXPANDED
+  // text (attachment tokens materialized), so display text cannot find it.
+  // Text is only the fallback for a row that carries no id.
+  const matches = targetId
+    ? (message) => messageIdOf(message) === targetId
+    : (message) => promptContentText(message.content).trim() === target;
+  const found = [];
   for (let index = messages.length - 1; index >= 0; index -= 1) {
-    const message = messages[index];
-    if (message?.role !== 'user') continue;
-    if (promptContentText(message.content).trim() !== target) continue;
-    start = index;
-    break;
+    if (messages[index]?.role === 'user' && matches(messages[index])) found.push(index);
   }
-  if (start < 0) return null;
+  // Without an id, text that several prompts repeat cannot say which one the
+  // user picked: refuse rather than rewind the wrong occurrence.
+  if (found.length === 0 || (!targetId && found.length > 1)) return null;
+  const start = found[0];
   const removed = messages.length - start;
+  const rewoundMessage = messages[start];
+  // `dryRun` resolves the target and reports what a rewind would do, changing
+  // nothing: the caller prepares the restore payload first and commits after.
+  // The marker names the exact history the dry run saw (generation alone only
+  // moves on lifecycle changes); the commit passes it back and is refused when
+  // the history differs.
+  const historyMarker = `${session.generation ?? 0}:${messages.length}:${createHash('sha1')
+    .update(JSON.stringify(messages))
+    .digest('hex')}`;
+  if (options?.dryRun === true) return { removed, remaining: start, message: rewoundMessage, historyMarker };
+  if (options?.expectedHistoryMarker != null && options.expectedHistoryMarker !== historyMarker) return null;
   session.messages = messages.slice(0, start);
   // The provider cache is keyed on the exact prefix we just truncated;
   // the prefix-guard snapshot and the /btw fork request describe it too and
@@ -435,5 +454,5 @@ export async function rewindSessionMessagesTo(sessionId, options = {}) {
   session.updatedAt = Date.now();
   session.lastUsedAt = Date.now();
   await saveSessionAsync(session, { expectedGeneration: session.generation });
-  return { removed, remaining: session.messages.length };
+  return { removed, remaining: session.messages.length, message: rewoundMessage };
 }

package/src/runtime/agent/orchestrator/session/manager/session-prompt-composition.mjs

@@ -159,7 +159,7 @@ export function composeSessionSystem(opts, { profile, providerName, modelName, s
         provider: providerName,
         model: modelName,
       });
-  const delegationFree = delegationDisabled(opts, ownerIsAgent);
+  const delegationFree = delegationDisabled({ ...opts, sessionMode }, ownerIsAgent);
   const promptIdentity = {
     systemPrompt: opts.systemPrompt || '',
     skipAgentRules: opts.skipAgentRules === true,

package/src/runtime/agent/orchestrator/session/manager/session-record.mjs

@@ -5,7 +5,7 @@
 // here is field derivation — no ownership, no prompt text; the only read is the
 // parent's record a delegated session takes its root from.
 import { toSessionWorkflowMeta } from '../../runtime-core/workflow.mjs';
-import { delegationForNewSession } from '../human-gate/delegation.mjs';
+import { delegationForNewSession, runForNewSession } from '../human-gate/delegation.mjs';
 import { sessionOrchestrationMode } from '../../../../shared/orchestration.mjs';
 import { preserveBufferConfigFields } from './context-meta.mjs';
 import { positiveInt } from '../../../../shared/numbers.mjs';
@@ -103,16 +103,18 @@ export function sessionOriginFields(opts, { profile, presetObj, providerCacheOpt
     ownerSessionId: opts.ownerSessionId || null,
     visibility: opts.visibility || null,
     clientHostPid: opts.clientHostPid || null,
-    // A sub-agent's or a bot-created task session's root (who it works for, and
-    // how that root was acting), derived from the parent's record — the one
-    // read here — never taken from the options (human-gate/delegation.mjs).
+    // A sub-agent's root and the run (if any) that started a sub-agent or a
+    // bot-created task session, derived from its creator — the one read here —
+    // never taken from the options (human-gate/delegation.mjs).
     ...delegationFields(opts),
   };
 }
 
 function delegationFields(opts) {
   const delegation = delegationForNewSession(opts);
-  return delegation ? { delegation } : {};
+  // Work a schedule/webhook run started (a sub-agent, a task session) stays the run's.
+  const run = runForNewSession(opts);
+  return { ...(delegation ? { delegation } : {}), ...(run ? { run } : {}) };
 }
 
 // The persisted session record.

package/src/runtime/agent/orchestrator/session/manager/session-tool-surface.mjs

@@ -9,15 +9,19 @@ import { collectPromptSkillsCached } from '../../context/collect.mjs';
 import { isAgentOwner } from '../../agent-owner.mjs';
 import { getHiddenAgent } from '../../internal-agents.mjs';
 import { workflowDisallowsAgentTool } from '../../runtime-core/workflow.mjs';
+import { isAgentModeSession } from '../agent-mode.mjs';
 import { finalizeSessionToolList, resolveSessionTools, permissionFromToolSpec } from './tool-resolution.mjs';
 import { unusedModelEditToolName } from '../../../../shared/edit-tool-dialect.mjs';
 import { getAgentRuntimeSync } from './agent-runtime-singleton.mjs';
 
 // A lead session may not delegate when its workflow forbids the agent tool
-// (no delegatable agents); Solo keeps it deferred for explicit user requests.
-// An agent-owned session never gets the tool anyway.
+// (an agent-mode Lead without delegatable agents); Solo keeps it deferred for
+// explicit user requests. An agent-owned session never gets the tool anyway.
 export function delegationDisabled(source, ownerIsAgent) {
-  return !ownerIsAgent && workflowDisallowsAgentTool(source?.workflow);
+  return (
+    !ownerIsAgent &&
+    workflowDisallowsAgentTool(source?.workflow, { agentMode: Boolean(source) && isAgentModeSession(source) })
+  );
 }
 
 // Exactly two schema surfaces exist: Lead and Agent. Every Agent role gets

package/src/runtime/agent/orchestrator/session/pre-send-compact.mjs

@@ -40,6 +40,7 @@ import {
   markPendingGoalReminder,
   snapshotPendingGoalReminder,
 } from '../runtime-core/goal-reminder.mjs';
+import { rearmLateDeferredTools } from '../runtime-core/tool-catalog.mjs';
 
 async function setStage(opts, stage) {
   try {
@@ -552,7 +553,15 @@ async function compactBeforeSend(ctx) {
     return;
   }
   ctx.compactChanged = messagesArrayChanged(messages, run.compacted);
-  if (ctx.compactChanged) adoptCompactedTranscript(ctx, run);
+  if (ctx.compactChanged) {
+    adoptCompactedTranscript(ctx, run);
+    // The adopted compaction strips late MCP tool announcements from older turns.
+    try {
+      rearmLateDeferredTools(sessionRef);
+    } catch {
+      /* best-effort, like the Goal reminder: a tool reminder never fails the compaction */
+    }
+  }
   reportCompactOutcome(ctx, run);
   // PostCompact belongs only to a completed compaction pass, never the
   // ordinary pre-send threshold check.

package/src/runtime/agent/orchestrator/session/routine-result.mjs

@@ -182,8 +182,10 @@ export function agentTaskRelayFailedMessage({ count, tries, at = Date.now(), mes
   };
 }
 
-/** Agent-initiated round trips on one task session before each report asks
- *  the agent to check with the user (session create). */
+/** Bot-descended round trips (sent from a turn another bot's message started)
+ *  on one task session before each report asks the agent to check with the
+ *  user (session create). The user's or a routine's own delegations are not
+ *  counted (agent-home-delivery.mjs `add`). */
 export const TASK_LOOP_CAP = 3;
 
 /** A coding task session's report into the home of the agent that created it
@@ -213,7 +215,8 @@ export function agentTaskMessage({
   const summary = typeof givenSummary === 'string' ? givenSummary : routineSummary(text);
   const reply = textChars > String(text ?? '').length ? { text: String(text), chars: textChars } : boundedReply(text);
   // The files the turn produced: listed for the agent, stored ones carried as
-  // the row's attachments (shown with the report, forwardable by id).
+  // the row's attachments (forwardable by id; the chat's result card does not
+  // show them, the task session does).
   const produced = normalizeHandoffFiles(files);
   const attachments = artifactRecords(produced);
   const label = escapeHarnessTags(String(title).replace(/["\r\n]/g, ''));
@@ -310,7 +313,7 @@ export function agentTaskWakePrompt(messages, { more = 0 } = {}) {
     'Relay the report above to the user now, briefly and in your own words; a report marked (working) is still in progress, not done.',
     ...(files
       ? [
-          'Its files are already shown to the user with the report; name the ones that matter by path, and pass them on to another session or agent with attachments.',
+          'Its files are not shown in this chat: the user sees only the result card and can open the task session for details. Name the files that matter by path yourself, and pass them on to another session or agent with attachments.',
         ]
       : []),
   ].join('\n\n');

package/src/runtime/agent/orchestrator/session/runtime-user-context.mjs

@@ -33,7 +33,9 @@ export function stripRuntimeUserContext(message) {
   } else {
     return message;
   }
-  const { runtimeUserContext: _context, ...meta } = message.meta;
+  // `agentListing` records what the stripped reminder told (agent-listing-
+  // notice.mjs): without the text it must not still count as told.
+  const { runtimeUserContext: _context, agentListing: _agentListing, ...meta } = message.meta;
   const result = { ...message, content, meta };
   if (Object.keys(meta).length === 0) delete result.meta;
   return result;

package/src/runtime/agent/orchestrator/session/send-with-recovery.mjs

@@ -256,7 +256,13 @@ export async function sendWithRecovery(ctx) {
     let response;
     try {
       const { timedOpts } = hooks;
-      const admittedOpts = timedOpts?.admissionOwner ? timedOpts : { ...(timedOpts || {}), admissionOwner: sessionId };
+      const baseOpts = timedOpts?.admissionOwner ? timedOpts : { ...(timedOpts || {}), admissionOwner: sessionId };
+      // A one-shot max_tokens request rides on this send's own copy only: the
+      // shared opts never carry it, so no later attempt can inherit it.
+      const admittedOpts =
+        ctx.maxOutputTokensOverride > 0
+          ? { ...baseOpts, maxOutputTokensOverride: ctx.maxOutputTokensOverride }
+          : baseOpts;
       // Ephemeral tail reminder (tail-reminder-rules.mjs): added to this request's
       // copy only, never to the stored transcript.
       const requestMessages = withTailReminder(messages, { session: ctx.sessionRef, provider, model });
@@ -267,7 +273,10 @@ export async function sendWithRecovery(ctx) {
       stampStreamOutcome(sendErr, hooks.relayWitness);
       return await recoverFromSendError(sendErr, { ...ctx, relayWitness: hooks.relayWitness });
     }
-    return { action: 'proceed', response };
+    // streamedChars: what this send put on screen through onTextDelta (net of
+    // acknowledged retractions), so the loop can withdraw it if it discards
+    // the response and re-sends.
+    return { action: 'proceed', response, streamedChars: hooks.relayWitness.text.length };
   } finally {
     hooks.restore();
   }

package/src/runtime/agent/orchestrator/session/store/sweep/stale-sweep.mjs

@@ -21,8 +21,8 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
   // An unreadable store dir is not an empty one: sweeping (deleting,
   // closing, pruning) on a probe we could not make is never allowed.
   if (probePath(dir).state !== PROBE_PRESENT) {
-    const { openCandidates: _candidates, ...empty } = createSweepTally();
-    return empty;
+    const { openCandidates: _candidates, subAgents, ...empty } = createSweepTally();
+    return plan.retainSubAgents ? { ...empty, subAgents } : empty;
   }
   const rows = collectSweepRows(dir);
   pruneSweepRecordCache(new Set(rows.map((row) => row?.id).filter(Boolean)));
@@ -41,8 +41,9 @@ function* sweepStaleSessionSteps(ttlMs, options = {}) {
   yield* reapOrphanSidecars(ctx);
   queueDeletedSummaryPrune(ctx.tally);
   persistSweepRecordCache();
-  const { openCandidates: _candidates, ...result } = ctx.tally;
-  return result;
+  const { openCandidates: _candidates, subAgents, ...result } = ctx.tally;
+  // `subAgents` only for a caller that applies them (idle-cleanup.mjs).
+  return plan.retainSubAgents ? { ...result, subAgents } : result;
 }
 
 /** Synchronous compatibility surface for explicit maintenance commands/tests. */

package/src/runtime/agent/orchestrator/session/store/sweep/sub-agent-retention.mjs

@@ -0,0 +1,140 @@
+// sweep/sub-agent-retention.mjs
+// Retention of finished sub-agent sessions: the agent-only children (Worker,
+// Reviewer, ...) a Lead's agents spawn, each its own stored session. The idle
+// sweep names every sub-agent record with its STORED activity time (the clock
+// survives restarts); a tree — a top sub-agent under a Lead with every
+// sub-agent below it — is archived once each member is idle
+// SUB_AGENT_ARCHIVE_AFTER_MS and deleted once each is idle
+// SUB_AGENT_DELETE_AFTER_MS. Otherwise the whole tree stays as it is.
+// Never a member: a root Lead, a task session from `session create`, a bot
+// home chat or a group room's log/member session.
+import { agentParentIds, isAgentOnlySession, isRootLeadSession } from '../../store-summary-visibility.mjs';
+import { probePath, PROBE_PRESENT } from '../fs-probe.mjs';
+import { sessionPath } from '../session-paths.mjs';
+import { _queueSummaryIndexPrune } from '../summary-cache.mjs';
+import { deleteSession } from '../session-delete.mjs';
+import { readSweepRecord } from './sweep-record.mjs';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const SUB_AGENT_ARCHIVE_AFTER_MS = 3 * DAY_MS;
+export const SUB_AGENT_DELETE_AFTER_MS = 30 * DAY_MS;
+const PERMANENT_ID = /^sess_(?:home|room|rmem)_/;
+// The desktop change an automatic archive applies: that one session, no
+// cascade (an explicit archive of a parent takes its sub-agents along).
+export const SUB_AGENT_AUTO_ARCHIVE = Object.freeze({ archived: true, cascade: false });
+
+const positive = (value) => (Number(value) > 0 ? Number(value) : 0);
+
+/** Last activity of a stored record: its last conversation turn (`lastUsedAt`;
+ *  `updatedAt` also moves on detach/resume bookkeeping) or its heartbeat. */
+export function subAgentActivityAt(doc) {
+  return Math.max(
+    positive(doc?.lastUsedAt) || positive(doc?.updatedAt) || positive(doc?.createdAt),
+    positive(doc?.lastHeartbeatAt)
+  );
+}
+
+/** `{ id, parentIds, lastActive }` for a sub-agent record (open or closed);
+ *  null for anything else. `parentIds` are the owner and parent links the
+ *  record names (agentParentIds), the same ones an archive cascade follows. */
+export function subAgentMember(id, doc) {
+  if (!doc || PERMANENT_ID.test(id) || doc.taskOrigin) return null;
+  if (isRootLeadSession(doc) || !isAgentOnlySession(doc)) return null;
+  return { id, parentIds: agentParentIds({ ...doc, id }), lastActive: subAgentActivityAt(doc) };
+}
+
+/** The members grouped into trees: members joined by any owner/parent link
+ *  between them (a link to a non-member joins nothing), each tree listing a
+ *  top member (no member parent) first and its members below in link order. */
+export function subAgentTrees(members) {
+  const byId = new Map(members.map((member) => [member.id, member]));
+  const links = new Map(members.map((member) => [member.id, new Set()]));
+  const hasMemberParent = new Set();
+  for (const member of members) {
+    for (const parent of (member.parentIds || []).filter((parentId) => byId.has(parentId))) {
+      links.get(member.id).add(parent);
+      links.get(parent).add(member.id);
+      hasMemberParent.add(member.id);
+    }
+  }
+  const seen = new Set();
+  const trees = [];
+  for (const start of [...members.filter((m) => !hasMemberParent.has(m.id)), ...members]) {
+    if (seen.has(start.id)) continue;
+    const tree = [start];
+    seen.add(start.id);
+    for (let index = 0; index < tree.length; index++) {
+      for (const id of links.get(tree[index].id)) {
+        if (seen.has(id)) continue;
+        seen.add(id);
+        tree.push(byId.get(id));
+      }
+    }
+    trees.push(tree);
+  }
+  return trees;
+}
+
+/** The stored activity time of `id` now; null when its record cannot be read. */
+function storedActivityAt(id) {
+  const path = sessionPath(id);
+  const probe = probePath(path);
+  if (probe.state !== PROBE_PRESENT) return null;
+  const record = readSweepRecord(id, path, probe);
+  return record?.id === id ? subAgentActivityAt(record.doc) : null;
+}
+
+/**
+ * Archives or deletes each idle tree. A tree with a member running here
+ * (`isSessionLive`), or one whose stored activity moved since the sweep read
+ * it, is left alone. An archive goes through the desktop's archive flag
+ * (`setSidebar(id, SUB_AGENT_AUTO_ARCHIVE)`: exactly the members not yet
+ * archived, never a cascade past them — needs
+ * `isArchived`, the desktop's flags); a deleted member that was archived loses
+ * its flag (`{ forgotten: true }`). Returns `{ archived, deleted }` (ids).
+ */
+export async function applySubAgentRetention(
+  members,
+  { isSessionLive = null, isArchived = null, setSidebar = null, now = Date.now() } = {}
+) {
+  const archived = [];
+  const deleted = [];
+  for (const tree of subAgentTrees(members)) {
+    // A member of unknown age (no valid stored timestamp) keeps its tree.
+    if (!tree.every((member) => Number.isFinite(member.lastActive) && member.lastActive > 0)) continue;
+    const idle = now - Math.max(...tree.map((member) => member.lastActive));
+    const expired = idle >= SUB_AGENT_DELETE_AFTER_MS;
+    if (!expired && (idle < SUB_AGENT_ARCHIVE_AFTER_MS || !isArchived)) continue;
+    if (tree.some((member) => isSessionLive?.(member.id))) continue;
+    if (tree.some((member) => storedActivityAt(member.id) !== member.lastActive)) continue;
+    if (expired) {
+      for (const { id } of tree.toReversed()) {
+        try {
+          if (deleteSession(id, { deferSummaryUpdate: true, isSessionLive, legacyOwnerVeto: true })) deleted.push(id);
+        } catch {
+          /* kept; the next pass decides again */
+        }
+      }
+      continue;
+    }
+    for (const { id } of tree) {
+      if (isArchived(id)) continue;
+      try {
+        await setSidebar(id, SUB_AGENT_AUTO_ARCHIVE);
+        archived.push(id);
+      } catch {
+        /* not archived; the next pass decides again */
+      }
+    }
+  }
+  if (deleted.length) _queueSummaryIndexPrune(new Set(deleted));
+  for (const id of deleted) {
+    if (!isArchived?.(id)) continue;
+    try {
+      await setSidebar(id, { forgotten: true });
+    } catch {
+      /* a stale archive stamp hides nothing */
+    }
+  }
+  return { archived, deleted };
+}

package/src/runtime/agent/orchestrator/session/store/sweep/sweep-plan.mjs

@@ -26,6 +26,9 @@ export function resolveSweepPlan(ttlMs, options = {}) {
     retainOpen: sweepIdle && options.retainOpenSessions !== false,
     openMaxAgeMs: Number.isFinite(optAge) && optAge > 0 ? optAge : RESUMABLE_OPEN_MAX_AGE_MS,
     openMaxCount: Number.isFinite(optCount) && optCount >= 0 ? optCount : RESUMABLE_OPEN_MAX_COUNT,
+    // Name every sub-agent session for the tree retention its caller applies
+    // (sweep/sub-agent-retention.mjs). Idle sweep only.
+    retainSubAgents: sweepIdle && options.retainSubAgents === true,
   };
 }
 
@@ -69,5 +72,7 @@ export function createSweepTally() {
     openCandidates: [],
     openPruned: 0,
     openPrunedDetails: [],
+    // Sub-agent sessions with their stored activity (plan.retainSubAgents).
+    subAgents: [],
   };
 }

package/src/runtime/agent/orchestrator/session/store/sweep/sweep-record.mjs

@@ -48,7 +48,7 @@ export const BLANK_SCRATCH_MAX_AGE_MS = 60 * 60 * 1000; // 1h
 // running is still parsed again.
 const sweepRecordCache = new Map();
 const SWEEP_RECORD_CACHE_FILE = 'session-sweep-records.json';
-const SWEEP_RECORD_CACHE_VERSION = 2;
+const SWEEP_RECORD_CACHE_VERSION = 3;
 let sweepRecordCacheDataDir = null;
 let sweepRecordCacheDirty = false;
 let sweepRecordParses = 0;
@@ -82,7 +82,7 @@ function syncSweepRecordCache() {
 }
 
 // The only document fields sweep-row reads (effectiveFields, the closed
-// check). Caching the whole top-level document kept
+// check, the sub-agent retention verdict). Caching the whole top-level document kept
 // every session's tool catalogs, schemas and provider state alive — one
 // entry per session file, measured at ~290MB of a 470MB daemon heap.
 const SWEEP_DOC_FIELDS = [
@@ -97,6 +97,11 @@ const SWEEP_DOC_FIELDS = [
   'createdAt',
   'ownerSessionId',
   'parentSessionId',
+  'lastUsedAt',
+  'agent',
+  'visibility',
+  'sessionVisibility',
+  'taskOrigin',
 ];
 
 function conversationCountOf(doc) {