mixdog 1.3.5 → 1.4.0

package/src/session-runtime/agent-task-sessions.mjs

@@ -7,8 +7,13 @@
  * Only turns the origin agent starts (the brief, a later `send` from it)
  * report: when such a turn ends its result is queued durably for the agent's
  * home (agent-home-delivery.mjs), which posts it and wakes the agent once to
- * relay it. A turn blocked on the user's answer or approval posts one faint
- * line instead; the card stays in the task session for the user.
+ * relay it. The session's other answers in that chain (given while work it
+ * handed to its agents still runs) are queued as progress updates that wake
+ * nobody: the agent reads them before its next turn, whatever starts it
+ * (agent-home-delivery.mjs postBeforeTurn), and the final report never
+ * repeats one that already carried its answer. A turn blocked on the user's
+ * answer or approval posts one faint line instead; the card stays in the task
+ * session for the user.
  *
  * An agent's send to any other session reports the same way, by an origin for
  * that send only (reportOrigin). Every reporting turn is also watched durably
@@ -79,12 +84,15 @@ const turnStatus = (detail) =>
 
 const INTERRUPTED = /^\[Request interrupted/;
 
-const messageText = (content) =>
-  typeof content === 'string'
-    ? content
-    : (Array.isArray(content) ? content : [])
-        .map((part) => (typeof part === 'string' ? part : part?.type === 'text' ? part.text || '' : ''))
-        .join('');
+const partText = (part) => {
+  if (typeof part === 'string') return part;
+  return part?.type === 'text' ? part.text || '' : '';
+};
+
+const messageText = (content) => {
+  if (typeof content === 'string') return content;
+  return (Array.isArray(content) ? content : []).map(partText).join('');
+};
 
 /** The submissions a stored user message delivered: a turn's prompt
  *  (`checkpointId`, `submissionIds` of a merged batch) or a steered message. */
@@ -106,13 +114,21 @@ export function submissionIdsOf(message) {
 export function submissionOutcome(messages, runId) {
   const list = Array.isArray(messages) ? messages : [];
   const start = list.findIndex((message) => submissionIdsOf(message).includes(runId));
-  if (start < 0) return null;
+  return start < 0 ? null : outcomeFrom(list, start);
+}
+
+/** submissionOutcome of the turn whose prompt is `list[start]`, read in
+ *  place: the scan stops at that turn's end (its completion, an
+ *  interruption, or the next turn's prompt). */
+function outcomeFrom(list, start) {
   for (let index = start; index < list.length; index += 1) {
     const message = list[index];
     const completion = message?.meta?.transcript?.completion;
     if (completion) {
       const status = turnStatus(completion);
-      const text = status === 'failed' ? completion.detail || '' : message.role === 'assistant' ? message.content : '';
+      let text = '';
+      if (status === 'failed') text = completion.detail || '';
+      else if (message.role === 'assistant') text = message.content;
       return { status, text: messageText(text) };
     }
     if (index === start || message?.role !== 'user') continue;
@@ -142,7 +158,9 @@ const callArguments = (call) => {
  *  no task. Empty when the turn recorded none. */
 function consumedTaskIds(message) {
   const recorded = message?.meta?.transcript?.consumedExecutionIds;
-  const ids = Array.isArray(recorded) ? recorded : message?.meta?.execution?.id ? [message.meta.execution.id] : [];
+  let ids = [];
+  if (Array.isArray(recorded)) ids = recorded;
+  else if (message?.meta?.execution?.id) ids = [message.meta.execution.id];
   return ids.map((id) => (id ? agentTaskIdOfExecution(id) : null));
 }
 
@@ -164,7 +182,9 @@ export function latestTurnOutcome(messages, runId) {
   return chain && { id: chain.id, outcome: chain.outcome, at: chain.at, ambiguous: chain.ambiguous };
 }
 
-/** latestTurnOutcome with what a report's wait needs besides: `taskIds`, the
+/** latestTurnOutcome with what a report's wait needs besides: `answers`,
+ *  every turn of the chain that recorded its end, oldest first (`{ id,
+ *  status, text }`: its submission id and submissionOutcome); `taskIds`, the
  *  agent tasks the chain's turns started — the only tasks proven the chain's
  *  — and `busyIsOthers`: the session's last stored turn is one outside the
  *  chain that recorded no end yet, and a stored turn took the result of every
@@ -187,6 +207,8 @@ function turnChain(messages, runId) {
   // The turn the walk is in: where its prompt is stored and its submission id.
   let turnAt = start;
   let turnId = runId;
+  // Every turn of the chain, in order: where its prompt is stored, its id.
+  const turns = [{ at: start, id: runId }];
   for (let index = start; index < list.length; index += 1) {
     const message = list[index];
     const checkpointId = index > start && message?.role === 'user' ? message.meta?.transcript?.checkpointId : '';
@@ -209,6 +231,7 @@ function turnChain(messages, runId) {
         inChain = true;
         at = turnAt;
         id = turnId;
+        if (turns.at(-1).id !== turnId) turns.push({ at: turnAt, id: turnId });
       } else if (!delivered.length || delivered.includes(null)) {
         ambiguous = true;
       }
@@ -227,14 +250,27 @@ function turnChain(messages, runId) {
     if (Array.isArray(message.agentTaskIds)) for (const taskId of message.agentTaskIds) started.add(String(taskId));
     else if (message.toolKind !== 'error') ambiguous = true;
   }
-  const turn = list.slice(at);
-  const ended = turn.find((message) => message?.meta?.transcript?.completion);
-  const last = turnId === id ? null : submissionOutcome(list.slice(turnAt), turnId);
+  // Read in place, never on copied suffixes: each chain turn's outcome scan
+  // stops at that turn's end, so the turns' scans cover disjoint stretches
+  // and the whole walk stays linear in the transcript.
+  let ended = null;
+  for (let index = at; index < list.length && !ended; index += 1) {
+    if (list[index]?.meta?.transcript?.completion) ended = list[index];
+  }
+  const last = turnId === id ? null : outcomeFrom(list, turnAt);
+  const answers = [];
+  let outcome = null;
+  for (const chainTurn of turns) {
+    const turnOutcome = outcomeFrom(list, chainTurn.at);
+    if (chainTurn.at === at) outcome = turnOutcome;
+    if (turnOutcome !== 'open') answers.push({ id: chainTurn.id, ...turnOutcome });
+  }
   return {
     id,
-    outcome: submissionOutcome(turn, id),
+    outcome,
     at: Number(ended?.meta?.transcript?.at) || 0,
     ambiguous,
+    answers,
     taskIds: started,
     busyIsOthers: last === 'open' && [...started].every((taskId) => taken.has(taskId)),
   };
@@ -333,7 +369,7 @@ function chainPendingWork(sessionId, taskIds, { owed, pool, agentTaskOwners, wor
 /** The agent results queued for `sessionId` that no turn has taken yet (its
  *  durable pending queue: an agent's completion, a restart failure): `{ text,
  *  meta }` as the notification bus delivers them. */
-export async function owedAgentResults(sessionId) {
+async function owedAgentResults(sessionId) {
   const [{ _getPendingMessagesForSession }, { completionIsDelivered, isCompletionNotificationEntry }] =
     await Promise.all([
       import('../runtime/agent/orchestrator/session/manager/pending-messages.mjs'),
@@ -399,9 +435,6 @@ const LOST_TEXT = 'The message never ran: the app restarted before its turn star
 const GONE_TEXT = 'The session no longer exists.';
 const RESUME_FAILED_TEXT =
   'The agent task session could not continue after the app restarted: its agents’ results never reached it. Check that session.';
-const PENDING_CAP_MS = 30 * 60_000;
-const STILL_WORKING_TEXT =
-  'Still in progress: its agents are still working 30+ minutes after this answer. This is the latest answer; the final one is reported when they finish.';
 // Deliveries of a restarted task session's queued agent results before its
 // report gives up as RESUME_FAILED_TEXT.
 const OWED_WAKE_TRIES = 3;
@@ -472,27 +505,54 @@ async function lastUsedSessionRoute(sessionService) {
  *  without the provenance to tell (no stored turn, `ambiguous`) the whole
  *  session must be idle with none pending. `immediate` is runId's own end,
  *  when this process saw it.
- *  `finish(status, text)` runs once; `check` re-evaluates (call it on every
- *  state change of `runtime`), `stop` ends the wait. */
+ *  Every other answer of the chain — each ended turn a later turn of the
+ *  chain followed, and the latest while its work still runs or its
+ *  provenance is missing — goes to `interim({ id, status, text })` once, in
+ *  chain order (`id`: the submission of the turn that gave it): a progress
+ *  update, which wakes nobody. Every check lists all the chain's ended turns,
+ *  so answers that end close together are each reported. `progressedThrough`:
+ *  the last turn an earlier process reported (the watch's durable mark):
+ *  it and the turns before it are not reported again.
+ *  `finish(status, text, answerId)` runs once (`answerId`: the turn whose
+ *  answer it is, none for a report of no turn); `check` re-evaluates (call it
+ *  on every state change of `runtime`), `stop` ends the wait. */
 function followTaskToFinal(
-  { loadSession, owedResults, deliverCompletion, pendingWork, settleMs, pollMs, pendingCapMs, log },
-  { sessionId, runId, runtime, immediate = null, wakeOwed = false, finish, progress = null }
+  { loadSession, owedResults, deliverCompletion, pendingWork, settleMs, pollMs, log },
+  { sessionId, runId, runtime, immediate = null, wakeOwed = false, finish, interim = null, progressedThrough = '' }
 ) {
-  let progressed = false;
-  let pendingSince = 0;
-  // Agent work still pending `pendingCapMs` after the chain's latest turn
-  // ended: `progress(text)` reports that answer once, marked still in
-  // progress, and the wait for the final one goes on. `latest`: the chain's
-  // latest turn (turnChain).
-  async function reportProgress(latest) {
-    if (progressed || typeof progress !== 'function') return;
-    let end = latest?.outcome && latest.outcome !== 'open' ? latest.outcome : null;
-    if (immediate && (!latest || latest.id === runId)) end = immediate;
-    if (!end) return;
-    pendingSince ||= Date.now();
-    if (Date.now() - (latest?.at || pendingSince) < pendingCapMs) return;
-    progressed = true;
-    await progress(`${STILL_WORKING_TEXT}\n\n${end.text}`);
+  // The chain's ended answers, oldest first, `{ id, status, text }`; runId's
+  // own is `immediate` when this process saw it. `latest`: turnChain's.
+  const answersOf = (latest) => {
+    const stored = latest?.answers || [];
+    if (!immediate) return stored;
+    return [{ id: runId, ...immediate }, ...stored.filter((answer) => answer.id !== runId)];
+  };
+  // The answers already handed to `interim`, by turn.
+  const interimIds = new Set();
+  /** Hand `answer` to `interim` once; false when that failed (logged): it is
+   *  tried again at the next check, and no later answer goes out before it. */
+  async function reportInterim(answer) {
+    if (!answer?.id || !String(answer.text || '').trim() || typeof interim !== 'function') return true;
+    if (interimIds.has(answer.id)) return true;
+    try {
+      await interim(answer);
+    } catch (error) {
+      log(`progress update of ${sessionId} failed, retried at the next check: ${error?.message || error}`);
+      return false;
+    }
+    interimIds.add(answer.id);
+    return true;
+  }
+  /** Report, in order, every one of `answers` past the durable mark but
+   *  `held` (the final candidate, reported only when it proves not final);
+   *  false, stopping there, at the first that could not be queued. */
+  async function reportEarlier(answers, held) {
+    const through = progressedThrough ? answers.findIndex((answer) => answer.id === progressedThrough) : -1;
+    for (const [index, answer] of answers.entries()) {
+      if (index <= through) interimIds.add(answer.id);
+      else if (answer !== held && !(await reportInterim(answer))) return false;
+    }
+    return true;
   }
   let done = false;
   let checking = false;
@@ -553,6 +613,14 @@ function followTaskToFinal(
     const latest = turnChain(stored?.messages, runId);
     // The chain's agent tasks; null (the whole session) without its provenance.
     const taskIds = latest && !latest.ambiguous ? latest.taskIds : null;
+    // Every answer of the chain but its latest turn's is no final one: each
+    // goes out as progress, whatever the session does now.
+    const answers = answersOf(latest);
+    const latestId = latest ? latest.id : runId;
+    const answer = answers.at(-1)?.id === latestId ? answers.at(-1) : null;
+    // An answer that could not be queued holds the chain (later answers, the
+    // final report) until a later check queues it: the poll retries it.
+    if (!(await reportEarlier(answers, answer))) return null;
     // A busy session may run the chain's turn unless that turn is provably another's.
     const busy = Boolean(runtime?.getState?.()?.busy);
     if (busy && !(taskIds && latest.busyIsOthers)) return null;
@@ -561,18 +629,16 @@ function followTaskToFinal(
       if (woke !== undefined) return woke;
     }
     if (await pendingWork(sessionId, { taskIds })) {
-      await reportProgress(latest);
+      await reportInterim(answer);
       return null;
     }
     if (!stored && !immediate) return { key: 'gone', status: 'cancelled', text: GONE_TEXT };
     // Provenance the chain needs is missing: its answer may not be final.
     if (latest?.ambiguous) {
-      await reportProgress(latest);
+      await reportInterim(answer);
       return null;
     }
-    if (immediate && (!latest || latest.id === runId)) return { key: runId, ...immediate };
-    if (!latest?.outcome || latest.outcome === 'open') return null;
-    return { key: `${latest.id}:${latest.outcome.status}`, ...latest.outcome };
+    return answer && { key: `${answer.id}:${answer.status}`, ...answer };
   }
   async function check() {
     if (done) return;
@@ -598,7 +664,7 @@ function followTaskToFinal(
           arm(candidateAt + settleMs - Date.now());
         } else {
           stop();
-          await finish(end.status, end.text);
+          await finish(end.status, end.text, end.id);
         }
       } while (again && !done);
     } finally {
@@ -756,7 +822,7 @@ async function rearmTaskWatch(
   // The turn that answers: the watched submission's own, or the one it
   // follows (a room member's turn under another submission id).
   const turnId = watch.follows || watch.runId;
-  const finish = async (status, text = '') =>
+  const finish = async (status, text = '', answerId = '') =>
     deliver(watch.agentId, {
       runId: `${watch.runId}_end`,
       taskSessionId: sessionId,
@@ -767,6 +833,7 @@ async function rearmTaskWatch(
       ...(watch.hop > 0 ? { hop: watch.hop } : {}),
       ...roomFrom(watch.homeSessionId),
       watchId: watch.runId,
+      ...progressOf(watch.runId, answerId),
       ...(watch.textOnly || text === GONE_TEXT || text === LOST_TEXT ? {} : await artifactFields(sessionId, turnId)),
     });
   if (!(await loadSession(sessionId))) return finish('cancelled', GONE_TEXT);
@@ -812,21 +879,25 @@ async function rearmTaskWatch(
             runId: turnId,
             runtime,
             wakeOwed: true,
-            progress: (text) =>
+            // The turns an earlier process already reported as progress.
+            progressedThrough: watch.progressed || '',
+            interim: (answer) =>
               deliver(watch.agentId, {
-                runId: `${watch.runId}_progress`,
+                runId: progressRunId(watch.runId, answer.id),
                 taskSessionId: sessionId,
                 title: watch.title,
                 status: 'working',
-                text,
+                text: answer.text,
+                progressWatchId: watch.runId,
+                answerId: answer.id,
                 ...(watch.target === 'session' ? { target: 'session' } : {}),
                 ...(watch.hop > 0 ? { hop: watch.hop } : {}),
                 ...roomFrom(watch.homeSessionId),
               }),
-            finish: async (status, text) => {
+            finish: async (status, text, answerId) => {
               done = true;
               unsubscribe();
-              await finish(status, text);
+              await finish(status, text, answerId);
             },
           });
         } else if (end) {
@@ -845,6 +916,161 @@ async function rearmTaskWatch(
   await check();
 }
 
+/** The settlement of sends one turn answers: they settle together with the
+ *  same `detail` object (a send steered into the turn while it ran, or queued
+ *  and taken as one batch), and that turn reports once, closing every one of
+ *  them. `nextSeq()` numbers the sends in submission order: the earliest of
+ *  the sends one turn answers reports for them. */
+function createSendSettlement(log) {
+  const settledTurns = new WeakMap();
+  let sendCount = 0;
+
+  /** Add send `member` (`{ seq, id, unwatch, settle }`) to the settlement
+   *  `detail` of its turn, per reporting conversation. The sends of one turn
+   *  settle in the same tick; after it the earliest (the turn's own, whose
+   *  record holds the whole turn) settles with all their ids and the others
+   *  stand down. */
+  function join(detail, origin, member) {
+    const key = `${origin.agentId}\0${origin.sessionId}`;
+    let groups = settledTurns.get(detail);
+    if (!groups) {
+      groups = new Map();
+      settledTurns.set(detail, groups);
+    }
+    let members = groups.get(key);
+    if (!members) {
+      members = [];
+      groups.set(key, members);
+      const settling = members;
+      void Promise.resolve()
+        .then(() => {
+          const [first, ...others] = settling.sort((a, b) => a.seq - b.seq);
+          for (const other of others) other.unwatch();
+          first.settle(settling.map((entry) => entry.id));
+        })
+        .catch((error) => log(`settling the sends of one turn failed: ${error?.message || error}`));
+    }
+    members.push(member);
+  }
+
+  const nextSeq = () => {
+    sendCount += 1;
+    return sendCount;
+  };
+
+  return { join, nextSeq };
+}
+
+/** The queue row of send `id`'s progress update carrying the answer of turn
+ *  `answerId` (followToFinal `interim`): one per answer, across restarts. */
+const progressRunId = (id, answerId) => `${id}_progress_${answerId}`;
+
+/** The queue row of send `id`'s report of `status`. 'working': a progress
+ *  update (progressRunId), not the end. A wait for approval belongs to the
+ *  target session, not to this send: every watcher of it names the same row,
+ *  so it posts once. */
+const turnReportRunId = (sessionId, id, status, { approvalId = '', answerId = '' } = {}) => {
+  if (status === 'blocked') return `${sessionId}_${approvalId}_blocked`;
+  return status === 'working' ? progressRunId(id, answerId) : `${id}_end`;
+};
+
+/** The report fields naming the progress update that may have carried the
+ *  final answer of turn `answerId` already (the queue then does not repeat
+ *  it); none for a report of no turn. */
+const progressOf = (id, answerId) => (answerId ? { progressRunId: progressRunId(id, answerId) } : {});
+
+/** The handler of send `id`'s task-session state: a wait for the user's
+ *  approval reports blocked once; a later, different one reports again. */
+function approvalWaitReporter(id, report) {
+  // The approval wait last reported.
+  let reportedApproval = null;
+  return (state) => {
+    if (!state.toolApproval) {
+      reportedApproval = null;
+      return;
+    }
+    const approvalId = String(state.toolApproval.id ?? 'approval');
+    if (approvalId === reportedApproval) return;
+    // A send still queued behind the running turn is not the turn
+    // waiting: that turn's own watcher reports it.
+    if ((state.queued || []).some((entry) => entry?.id === id)) return;
+    reportedApproval = approvalId;
+    void report('blocked', '', { approvalId });
+  };
+}
+
+/** The transcript meta of a send from `origin`. `fromAgent`: the sending bot,
+ *  recorded when it writes into another bot's home chat (otherwise the row
+ *  would read as the user's); `hop`: its place in a bot-to-bot chain
+ *  (bot-hops.mjs). */
+const sendTranscriptMeta = (origin) => ({
+  sender: 'lead',
+  ...(origin.envelopeName ? { fromAgent: origin.agentId } : {}),
+  ...(origin.hop > 0 ? { hop: origin.hop } : {}),
+  // The bots that handed this work on, the sender last (bot-hops.mjs).
+  ...(origin.botChain?.length ? { botChain: origin.botChain } : {}),
+});
+
+/** What a send tells its caller once submitted. */
+const sendResult = (accepted, notify, id, noReport) => ({
+  accepted,
+  // Names this send; its terminal report carries it back (routine.sendId).
+  ...(accepted && notify ? { sendId: id } : {}),
+  reportsBack: accepted && notify,
+  ...(accepted && !notify ? { reportsBackReason: noReport } : {}),
+});
+
+/** create's brief and `worktree` location, checked before anything runs. */
+function createRequest(args, callerAgentId, callerScope) {
+  if (!callerAgentId) throw new Error('session: create is only for an agent conversation');
+  const brief = typeof args.brief === 'string' ? args.brief.trim() : '';
+  if (!brief) throw new Error('session: brief is required for action=create');
+  const location = taskLocation(args.worktree);
+  if (location.mode === 'worktree') assertWorktreeMutationAllowed(callerScope, 'session: create with a worktree');
+  return { brief, location };
+}
+
+/** Where create starts (resolveTaskProject). An explicit worktree is never
+ *  silently dropped: it needs a registered Project. */
+function createWhere(args, projects, callerCwd, location) {
+  const where = resolveTaskProject(args.project, { projects, cwd: callerCwd || process.cwd() });
+  const registered = where.project && projects.some((entry) => samePath(entry.path, where.project.path));
+  if (location.mode === 'worktree' && !registered) {
+    throw taskWorktreeFailure(
+      worktreeError('WORKTREE_PROJECT_UNKNOWN', 'A worktree needs a registered Project; run list-projects.', {
+        projectPath: where.project?.path ?? null,
+      })
+    );
+  }
+  return where;
+}
+
+/** The worktree failure `error` of task session `sessionId` whose empty
+ *  session could not be dropped (`dropFailure`): the model must know the
+ *  empty session is still there to delete. */
+const orphanSessionError = (error, sessionId, dropFailure) =>
+  Object.assign(
+    new Error(
+      `${error?.message || error} The empty task session ${sessionId} could not be deleted either (${dropFailure?.message || dropFailure}); delete it with session action=delete session_id=${sessionId}.`
+    ),
+    {
+      ...(typeof error?.code === 'string' ? { code: error.code } : {}),
+      ...(error?.details ? { details: error.details } : {}),
+      orphanSessionId: sessionId,
+      cause: error,
+    }
+  );
+
+/** `ready` resolves once `started()` runs: "Started" lands in the home before
+ *  any report of the brief's turn. */
+function startedGate() {
+  let started = () => {};
+  const ready = new Promise((resolveReady) => {
+    started = resolveReady;
+  });
+  return { ready, started };
+}
+
 export function createAgentTaskSessions({
   getSessionService,
   deliver = async (agentId, report) => (await import('./agent-home-delivery.mjs')).deliverAgentTask(agentId, report),
@@ -868,7 +1094,7 @@ export function createAgentTaskSessions({
     (await import('../runtime/agent/orchestrator/config.mjs')).loadConfig({ secrets: false }).worktree?.newTaskDefault,
   modelRoute = configModelRoute,
   // The model menu's catalog rows, read through the calling session's runtime.
-  modelCatalog = (sessionId) => readModelCatalog(service(), sessionId),
+  modelCatalog = (sessionId) => readModelCatalog(getSessionService(), sessionId),
   // The Lead (Main) route of the config — what a desktop New task starts on.
   leadRoute = configLeadRoute,
   // The model the user last used in a coding session.
@@ -899,9 +1125,6 @@ export function createAgentTaskSessions({
   owedResults = owedAgentResults,
   deliverCompletion = null,
   settleAgentResults = async () => {},
-  // Pending agent work this long after the latest answer reports that answer
-  // as still in progress (once); the final report still follows.
-  pendingCapMs = PENDING_CAP_MS,
   log = (line) => process.stderr.write(`mixdog task sessions: ${line}\n`),
 }) {
   /** The report fields of turn `runId`'s files; none when it produced none. */
@@ -923,44 +1146,9 @@ export function createAgentTaskSessions({
   };
 
   const followToFinal = (follow) =>
-    followTaskToFinal(
-      { loadSession, owedResults, deliverCompletion, pendingWork, settleMs, pollMs, pendingCapMs, log },
-      follow
-    );
-
-  // Sends one turn answers settle together with the same `detail` object: a
-  // send steered into the turn while it ran, or queued and taken as one batch.
-  // That turn reports once, closing every one of them.
-  const settledTurns = new WeakMap();
-  let sendCount = 0;
+    followTaskToFinal({ loadSession, owedResults, deliverCompletion, pendingWork, settleMs, pollMs, log }, follow);
 
-  /** Add send `member` (`{ seq, id, unwatch, settle }`) to the settlement
-   *  `detail` of its turn, per reporting conversation. The sends of one turn
-   *  settle in the same tick; after it the earliest (the turn's own, whose
-   *  record holds the whole turn) settles with all their ids and the others
-   *  stand down. */
-  function joinSettlement(detail, origin, member) {
-    const key = `${origin.agentId}\0${origin.sessionId}`;
-    let groups = settledTurns.get(detail);
-    if (!groups) {
-      groups = new Map();
-      settledTurns.set(detail, groups);
-    }
-    let members = groups.get(key);
-    if (!members) {
-      members = [];
-      groups.set(key, members);
-      const settling = members;
-      void Promise.resolve()
-        .then(() => {
-          const [first, ...others] = settling.sort((a, b) => a.seq - b.seq);
-          for (const other of others) other.unwatch();
-          first.settle(settling.map((entry) => entry.id));
-        })
-        .catch((error) => log(`settling the sends of one turn failed: ${error?.message || error}`));
-    }
-    members.push(member);
-  }
+  const settlement = createSendSettlement(log);
 
   /** Submit `prompt` as the origin agent's turn; its end (and a wait for the
    *  user in it) reports to the agent's home. Resolves on intake. `submit`
@@ -982,41 +1170,49 @@ export function createAgentTaskSessions({
       watches.remove(id).catch((error) => log(`dropping the watch of ${sessionId} failed: ${error?.message || error}`));
     let runtime = null;
     // The sends this turn's end closes: this one, plus any that its turn
-    // answered too (joinSettlement).
+    // answered too (createSendSettlement).
     let sendIds = [id];
     // A report that cannot be queued is retried in this process; when every try
     // fails the durable watch stays and restart recovery delivers it (the queue
     // dedupes by runId, so a retry never posts twice).
-    const report = (status, text = '') =>
-      Promise.resolve(beforeReport)
-        .then(async () =>
-          deliverWithRetries({ deliver, retryDelaysMs, log }, origin.agentId, sessionId, {
-            // 'working': a still-in-progress answer (followToFinal), not the end.
-            runId: `${id}_${{ blocked: 'blocked', working: 'progress' }[status] || 'end'}`,
-            taskSessionId: sessionId,
-            title: origin.title,
-            status,
-            text,
-            ...target,
-            ...(origin.hop > 0 ? { hop: origin.hop } : {}),
-            ...roomFrom(origin.sessionId),
-            // A turn's end brings back the files it produced, when the agent
-            // may receive them (reportOrigin `textOnly`).
-            ...(status === 'blocked' || status === 'working'
-              ? {}
-              : {
-                  watchId: id,
-                  ...(sendIds.length > 1 ? { watchIds: sendIds } : {}),
-                  ...(origin.textOnly ? {} : await artifactFields(sessionId, id, runtime)),
-                }),
-          })
-        )
-        .catch((error) => log(`report of ${sessionId} failed: ${error?.message || error}`));
+    // `answerId`: the turn whose answer a progress update or the end carries.
+    // `deliverReport` rejects once every try failed (a progress update is
+    // tried again at the follow's next check); `report` logs it instead.
+    const deliverReport = (status, text = '', { approvalId = '', answerId = '' } = {}) =>
+      Promise.resolve(beforeReport).then(async () =>
+        deliverWithRetries({ deliver, retryDelaysMs, log }, origin.agentId, sessionId, {
+          runId: turnReportRunId(sessionId, id, status, { approvalId, answerId }),
+          taskSessionId: sessionId,
+          title: origin.title,
+          status,
+          text,
+          ...target,
+          ...(origin.hop > 0 ? { hop: origin.hop } : {}),
+          ...roomFrom(origin.sessionId),
+          // A progress update moves this send's durable mark to its turn
+          // (agent-home-delivery.mjs enqueueTask), in the same write.
+          ...(status === 'working' ? { progressWatchId: id, answerId } : {}),
+          // A turn's end brings back the files it produced, when the agent
+          // may receive them (reportOrigin `textOnly`).
+          ...(status === 'blocked' || status === 'working'
+            ? {}
+            : {
+                watchId: id,
+                ...(sendIds.length > 1 ? { watchIds: sendIds } : {}),
+                ...progressOf(id, answerId),
+                ...(origin.textOnly ? {} : await artifactFields(sessionId, id, runtime)),
+              }),
+        })
+      );
+    const report = (status, text = '', options = {}) =>
+      deliverReport(status, text, options).catch((error) =>
+        log(`report of ${sessionId} failed: ${error?.message || error}`)
+      );
     let unwatch = () => {};
     // Set once the turn ended completed: the report waits for the final answer.
     let follow = null;
     let result;
-    /** This send ends the turn `detail` for the sends `answered` (joinSettlement). */
+    /** This send ends the turn `detail` for the sends `answered` (createSendSettlement). */
     const settleTurn = (detail, answered) => {
       sendIds = answered;
       const status = turnStatus(detail);
@@ -1033,24 +1229,23 @@ export function createAgentTaskSessions({
         runId: id,
         runtime,
         immediate: { status, text },
-        finish: async (endStatus, endText) => {
+        finish: async (endStatus, endText, answerId) => {
           unwatch();
-          await report(endStatus, endText);
+          await report(endStatus, endText, { answerId });
         },
-        progress: (progressText) => report('working', progressText),
+        // Each other answer of its chain: a progress update that wakes nobody.
+        interim: (answer) => deliverReport('working', answer.text, { answerId: answer.id }),
       });
       follow.check();
     };
     try {
       if (notify) {
         runtime = await sessions.materializeSession(sessionId);
-        let blocked = false;
+        const onState = approvalWaitReporter(id, report);
         unwatch =
           runtime?.subscribe?.(() => {
             follow?.check();
-            if (blocked || !runtime.getState?.()?.toolApproval) return;
-            blocked = true;
-            void report('blocked');
+            onState(runtime.getState?.() || {});
           }) || unwatch;
       }
       // A bot's send to a session that is not its own task session reaches the
@@ -1059,22 +1254,11 @@ export function createAgentTaskSessions({
         ? wrapAgentMessage(prompt, { name: origin.envelopeName, agentId: origin.agentId })
         : prompt;
       const take = submit ?? ((options) => sessions.submitSession({ sessionId, prompt: sent, options }));
-      // Submission order: the earliest of the sends one turn answers reports for them.
-      sendCount += 1;
-      const seq = sendCount;
+      const seq = settlement.nextSeq();
       result = await take({
         id,
         mode: 'prompt',
-        // `fromAgent`: the sending bot, recorded when it writes into another
-        // bot's home chat (otherwise the row would read as the user's);
-        // `hop`: its place in a bot-to-bot chain (bot-hops.mjs).
-        transcriptMeta: {
-          sender: 'lead',
-          ...(origin.envelopeName ? { fromAgent: origin.agentId } : {}),
-          ...(origin.hop > 0 ? { hop: origin.hop } : {}),
-          // The bots that handed this work on, the sender last (bot-hops.mjs).
-          ...(origin.botChain?.length ? { botChain: origin.botChain } : {}),
-        },
+        transcriptMeta: sendTranscriptMeta(origin),
         ...(notify
           ? {
               // A room answers this send in a turn under another submission
@@ -1082,7 +1266,7 @@ export function createAgentTaskSessions({
               // short): the watch follows that turn, recorded before it runs.
               follow: (submissionId) => watches.follow?.(id, submissionId),
               onSettled: (detail) =>
-                joinSettlement(detail, origin, {
+                settlement.join(detail, origin, {
                   seq,
                   id,
                   unwatch: () => unwatch(),
@@ -1101,13 +1285,7 @@ export function createAgentTaskSessions({
       unwatch();
       if (notify) await dropWatch();
     }
-    return {
-      accepted,
-      // Names this send; its terminal report carries it back (routine.sendId).
-      ...(accepted && notify ? { sendId: id } : {}),
-      reportsBack: accepted && notify,
-      ...(accepted && !notify ? { reportsBackReason: noReport } : {}),
-    };
+    return sendResult(accepted, notify, id, noReport);
   }
 
   const rearm = (watch) =>
@@ -1160,22 +1338,8 @@ export function createAgentTaskSessions({
       attachmentParts = [],
     } = {}
   ) {
-    if (!callerAgentId) throw new Error('session: create is only for an agent conversation');
-    const brief = typeof args.brief === 'string' ? args.brief.trim() : '';
-    if (!brief) throw new Error('session: brief is required for action=create');
-    const location = taskLocation(args.worktree);
-    if (location.mode === 'worktree') assertWorktreeMutationAllowed(callerScope, 'session: create with a worktree');
-    const projects = await listProjects();
-    const where = resolveTaskProject(args.project, { projects, cwd: callerCwd || process.cwd() });
-    // An explicit worktree is never silently dropped: it needs a registered Project.
-    const registered = where.project && projects.some((entry) => samePath(entry.path, where.project.path));
-    if (location.mode === 'worktree' && !registered) {
-      throw taskWorktreeFailure(
-        worktreeError('WORKTREE_PROJECT_UNKNOWN', 'A worktree needs a registered Project; run list-projects.', {
-          projectPath: where.project?.path ?? null,
-        })
-      );
-    }
+    const { brief, location } = createRequest(args, callerAgentId, callerScope);
+    const where = createWhere(args, await listProjects(), callerCwd, location);
     const requestId = `atask_${randomUUID()}`;
     const title = (clean(args.title) || clean(brief.split('\n')[0])).slice(0, TITLE_LIMIT);
     const taskOrigin = {
@@ -1243,25 +1407,10 @@ export function createAgentTaskSessions({
         }
         if (dropFailure) log(`dropping ${sessionId} failed: ${dropFailure?.message || dropFailure}`);
         if (!dropFailure) throw error;
-        // The model must know the empty session is still there to delete.
-        throw Object.assign(
-          new Error(
-            `${error?.message || error} The empty task session ${sessionId} could not be deleted either (${dropFailure?.message || dropFailure}); delete it with session action=delete session_id=${sessionId}.`
-          ),
-          {
-            ...(typeof error?.code === 'string' ? { code: error.code } : {}),
-            ...(error?.details ? { details: error.details } : {}),
-            orphanSessionId: sessionId,
-            cause: error,
-          }
-        );
+        throw orphanSessionError(error, sessionId, dropFailure);
       }
     }
-    // "Started" lands in the home before any report of the brief's turn.
-    let started = () => {};
-    const ready = new Promise((resolveReady) => {
-      started = resolveReady;
-    });
+    const { ready, started } = startedGate();
     // The brief carries the files the agent forwarded (workspace-tools.mjs).
     const prompt = handoffContent(brief, attachmentParts);
     const botChain = botChainOf(callerBotChain);