mixdog 1.3.4 → 1.4.0

package/src/session-runtime/agent-home-delivery.mjs

@@ -1,15 +1,18 @@
 /**
  * Rows posted into an agent's home thread (`sess_home_<owner>`) from outside
  * its turns: held requests of unattended runs, reports of task sessions the
- * agent created, and routine results left by runs from before routines ran as
- * turns in the thread itself (routine-home-turn.mjs).
+ * agent created, the agent's own reply of a turn it ran in a hidden session
+ * (Mixy's heartbeat), and routine results left by runs from before routines
+ * ran as turns in the thread itself (routine-home-turn.mjs).
  *
  * Delivery is durable. The finished run is first ENQUEUED in a persisted
  * per-home queue (`routine-results.json`), keyed by the run id, so a retried
  * enqueue adds nothing and a crash between posting and dequeuing never posts
  * twice (the posted message id is derived from the run id). One drainer per
  * home appends every queued result FIFO once the thread is idle; posting never
- * starts a turn. A home thread that does not exist yet keeps its results
+ * starts a turn. Rows that wake nobody (a task session's progress updates,
+ * among others) also post right before any turn of the thread starts
+ * (postBeforeTurn), so that turn reads them ahead of its prompt. A home thread that does not exist yet keeps its results
  * queued until it does; a deleted owner's results move to Mixy's home. Each
  * home keeps at most ROUTINE_LIMITS.homeQueueLimit results (the oldest drop
  * behind one "n omitted" notice), and posted run ids stay in a ledger so a
@@ -57,6 +60,7 @@ import {
   routineSummary,
 } from '../runtime/agent/orchestrator/session/routine-result.mjs';
 import { readJsonState, updateJsonAtomic } from '../runtime/shared/atomic-file.mjs';
+import { endHandoff, noteHandoff } from '../runtime/shared/delegated-approval-host.mjs';
 import { ROUTINE_LIMITS } from '../runtime/shared/routine-limits.mjs';
 import { submissionIdsOf, submissionOutcome } from './agent-task-sessions.mjs';
 import {
@@ -64,22 +68,50 @@ import {
   heldRequestNotice,
 } from '../runtime/agent/orchestrator/session/human-gate/held-message.mjs';
 
+/** `message` marked as posted outside any turn (`meta.transcript.posted`):
+ *  its row is a turn of its own, never part of the rows around it
+ *  (transcript-turn-keys.mjs). */
+function postedMessage(message) {
+  return { ...message, meta: { ...message.meta, transcript: { ...message.meta?.transcript, posted: true } } };
+}
+
 /** A queued item's stored message and live notice: a routine result, or a
  *  held request of an unattended run (session-runtime/held-requests.mjs). */
 function deliveredRow(item, messageId) {
+  const row = queuedRow(item, messageId);
+  return { ...row, message: postedMessage(row.message) };
+}
+
+/** A task report past the round-trip cap with another agent's own thread:
+ *  each wake could answer the other agent again without end. */
+const taskWakeCapped = (item) =>
+  (isAgentHomeSessionId(item.taskSessionId) || isRoomThreadSessionId(item.taskSessionId)) &&
+  (item.round || 0) > TASK_LOOP_CAP;
+
+/** Whether queued `item` wakes the agent once posted: a task turn's end (not
+ *  its start, a wait for the user or a progress update), unless capped. */
+const wakesAgent = (item) => item.kind === 'agent-task' && item.roundTrip === true && !taskWakeCapped(item);
+
+const MIXY_HOME = agentHomeSessionId(MIXY_AGENT_ID);
+/** A heartbeat report: Mixy's own reply from a check turn (mixy-heartbeat.mjs
+ *  wakeMixy, its only sender of agent messages). */
+const isHeartbeatReport = (item) => item?.kind === 'agent-message';
+
+function queuedRow(item, messageId) {
+  // The agent's own words from a turn it ran elsewhere (mixy-heartbeat.mjs):
+  // one ordinary reply of the agent in its thread.
+  if (item.kind === 'agent-message') {
+    const message = { role: 'assistant', content: item.text, meta: { transcript: { at: item.at, messageId } } };
+    return { message, notice: { text: item.text, tone: 'info', assistant: true } };
+  }
   if (item.kind === 'held-request') {
     const message = heldRequestMessage({ ...item.held, at: item.at, messageId });
     return { message, notice: heldRequestNotice(message) };
   }
   if (item.kind === 'agent-task') {
-    // A turn's end (not its start or a wait for the user) wakes the agent —
-    // except past the round-trip cap with another agent's own thread, where
-    // each wake could answer the other agent again without end.
-    const capped =
-      (isAgentHomeSessionId(item.taskSessionId) || isRoomThreadSessionId(item.taskSessionId)) &&
-      (item.round || 0) > TASK_LOOP_CAP;
+    const capped = taskWakeCapped(item);
     const message = agentTaskMessage({ ...item, messageId, ...(capped ? { woken: false } : {}) });
-    return { message, notice: routineResultNotice(message), wake: item.roundTrip === true && !capped };
+    return { message, notice: routineResultNotice(message), wake: wakesAgent(item) };
   }
   const message = routineResultMessage({ ...item, messageId });
   return { message, notice: routineResultNotice(message) };
@@ -124,9 +156,11 @@ export function scheduleOwnerAgentId(schedule) {
 }
 
 let liveSurface = null;
-/** `{ busy(sessionId), notice(sessionId, notice), wake(sessionId, prompt, { id }),
- *  submit(sessionId, prompt, options), abort(sessionId) }` from the session
- *  service; `wake` starts one hidden turn with submission `id` (resolves
+/** `{ busy(sessionId), notice(sessionId, notice), react(sessionId, messageId,
+ *  reactions), wake(sessionId, prompt, { id }), submit(sessionId, prompt,
+ *  options), abort(sessionId) }` from the session service; `react` shows a
+ *  message's new reactions in the runtime hosting it (message-reactions.mjs),
+ *  `wake` starts one hidden turn with submission `id` (resolves
  *  false when it was refused, else `{ settled }`: a promise of the turn's end
  *  status, 'done' when it finished), `submit` queues a routine turn
  *  (resolves whether it was accepted), `abort` stops the running turn. */
@@ -143,14 +177,14 @@ export function agentHomeLiveSurface() {
 // even into a thread that was reset ("대화 새로 시작") since.
 const DELIVERED_LEDGER = 500;
 // A target's round-trip count left idle this long starts over.
-export const ROUND_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const ROUND_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 // Per home: round-trip targets counted (least recently counted drop first),
 // reporting turns watched at once, and posted results owed a wake.
 export const QUEUE_CAPS = Object.freeze({ roundTargets: 100, watches: 200, wakeRunIds: 100 });
 // Waits before the 2nd, 3rd and 4th try of a relay (wake) turn that did not finish.
-export const WAKE_RETRY_DELAYS_MS = Object.freeze([30_000, 120_000, 600_000]);
+const WAKE_RETRY_DELAYS_MS = Object.freeze([30_000, 120_000, 600_000]);
 // Refused wake submissions of one batch, a minute apart, before it is given up.
-export const WAKE_REFUSAL_LIMIT = 10;
+const WAKE_REFUSAL_LIMIT = 10;
 
 /** `homeId`'s wake obligations in `wakes`: posted task results not in a batch
  *  yet (`owed`), those past the cap collapsed into one marker (`overflow`:
@@ -255,6 +289,25 @@ function withDequeued(doc, homeId, runIds, omitted) {
   return { ...doc, homes, omitted: omittedNow, delivered };
 }
 
+/** `{ doc, item }`: task report `item` for `homeId` and the `doc` it joins,
+ *  so that a final report never repeats progress update `progressRunId` that
+ *  carried the same answer. Posted (`posted`: the thread holds it, or the
+ *  ledger says so), the final report points to it instead of repeating its
+ *  text (the row's one-line summary stays); only queued, that update is
+ *  dropped and the final report carries the answer in its place. */
+function withoutRepeatedProgress(doc, homeId, item, posted) {
+  const { progressRunId, ...report } = item;
+  if (!progressRunId) return { doc, item };
+  if (posted || (doc.delivered[homeId] || []).includes(progressRunId)) {
+    const { text: _text, textChars: _textChars, ...rest } = report;
+    return { doc, item: { ...rest, text: '', answerAbove: true } };
+  }
+  const queued = doc.homes[homeId] || [];
+  if (!queued.some((row) => row.runId === progressRunId)) return { doc, item: report };
+  const homes = { ...doc.homes, [homeId]: queued.filter((row) => row.runId !== progressRunId) };
+  return { doc: { ...doc, homes }, item: report };
+}
+
 /** The persisted queue at `filePath`: `{ homes: { [homeSessionId]: item[] },
  *  omitted: { [homeSessionId]: { id, count } }, delivered: { [homeSessionId]:
  *  runId[] } }`. A home keeps at most `limit` items: past it the oldest drop,
@@ -290,16 +343,23 @@ export function createRoutineResultQueue(
   }
   /** Read-modify-write under the file lock (`mutator(doc)` returns the next
    *  doc, or nothing to keep the file); every write also retires stale and
-   *  surplus round counts. */
-  function update(mutator) {
-    return updateJsonAtomic(
+   *  surplus round counts. The watches a write added or removed, by any path
+   *  (a report, a turn never taken, a cap eviction, a pruned home), start or
+   *  end their hand-offs (delegated-approval-host.mjs). */
+  async function update(mutator) {
+    let watches = null;
+    const result = await updateJsonAtomic(
       filePath,
       (raw) => {
-        const next = mutator(parts(raw));
+        const doc = parts(raw);
+        const next = mutator(doc);
+        watches = { before: doc.watches, after: next ? section(next, 'watches') : doc.watches };
         return next ? { ...next, rounds: tidyRounds(next.rounds) } : undefined;
       },
       { backup: true }
     );
+    if (watches) syncHandoffs(watches.before, watches.after);
+    return result;
   }
   const appended = (doc, homeId, items, omittedCount = 0) => appendedItems(doc, homeId, items, limit, omittedCount);
   return {
@@ -413,10 +473,15 @@ export function createRoutineResultQueue(
     async omitted(homeId) {
       return (await read()).omitted[homeId] || null;
     },
-    /** Queue `item` for `homeId`; `unwatch` drops that watch in the same write,
-     *  also when the item was queued or posted before. */
-    async add(homeId, item, { unwatch = '' } = {}) {
-      await update((doc) => {
+    /** Queue `item` for `homeId`; `unwatch` (run ids) drops those watches in the
+     *  same write, also when the item was queued or posted before.
+     *  `progressPosted`: the thread holds the progress update a final report
+     *  names (withoutRepeatedProgress). `progressed` (`{ runId, turnId }`):
+     *  watch `runId` reported turn `turnId` as progress — its durable mark,
+     *  stored in the same write (agent-task-sessions.mjs progressedThrough). */
+    async add(homeId, queued, { unwatch = [], progressPosted = false, progressed = null } = {}) {
+      await update((stored) => {
+        const { doc, item } = withoutRepeatedProgress(stored, homeId, queued, progressPosted);
         let next = null;
         if (item.roundTrip !== true) next = appended(doc, homeId, [item]);
         else {
@@ -434,10 +499,19 @@ export function createRoutineResultQueue(
             next = { ...next, rounds: { ...doc.rounds, [homeId]: counted } };
           }
         }
-        if (!unwatch || !doc.watches[unwatch]) return next ?? undefined;
-        const watches = { ...doc.watches };
-        delete watches[unwatch];
-        return { ...(next || doc), watches };
+        let watches = doc.watches;
+        const marked = progressed?.turnId && watches[progressed.runId];
+        if (marked && marked.progressed !== progressed.turnId) {
+          watches = { ...watches, [progressed.runId]: { ...marked, progressed: progressed.turnId } };
+        }
+        const dropped = unwatch.filter((runId) => watches[runId]);
+        if (dropped.length) {
+          watches = { ...watches };
+          for (const runId of dropped) delete watches[runId];
+        }
+        const base = next || doc;
+        if (watches === doc.watches) return base === stored ? undefined : base;
+        return { ...base, watches };
       });
     },
     /** Keep `watch` ({ runId, agentId, homeSessionId, taskSessionId, title,
@@ -459,9 +533,12 @@ export function createRoutineResultQueue(
       });
     },
     watchCap: caps.watches,
-    /** Every stored watch, oldest first. */
+    /** Every stored watch, oldest first; each is a live hand-off (after a
+     *  restart, this read brings them back). */
     async watches() {
-      return Object.values((await read()).watches);
+      const watches = Object.values((await read()).watches);
+      for (const watch of watches) noteHandoff(watch ?? {});
+      return watches;
     },
     /** The watch of `runId` follows the turn submitted as `submissionId`: a
      *  room member's one turn answering several sends, or a fresh turn
@@ -527,7 +604,7 @@ const messageIdOf = (runId) => `routine_${runId}`;
  *  or false (logged) when the surface threw. */
 function noticeLive(live, log, homeId, notice) {
   try {
-    return live()?.notice?.(homeId, notice);
+    return live()?.notice?.(homeId, { ...notice, posted: true });
   } catch (error) {
     log(`live notice in ${homeId} failed: ${error?.message || error}`);
     return false;
@@ -561,6 +638,13 @@ function routineResultItem(row, result) {
   };
 }
 
+/** End the hand-off of each watch in `before` and not `after`, and start
+ *  each one `after` added (both keyed by run id). */
+function syncHandoffs(before, after) {
+  for (const runId of Object.keys(before)) if (!after[runId]) endHandoff(runId);
+  for (const [runId, watch] of Object.entries(after)) if (!before[runId]) noteHandoff(watch ?? {});
+}
+
 /** The run ids of `watches` a home at its watch `cap` gives up before
  *  storing `watch`: its oldest whose target sessions are proven deleted. */
 function watchesToDrop(watches, watch, cap, sessionDeleted) {
@@ -584,8 +668,24 @@ function homeProvenDeleted(homeId, agentPresence, roomPresence) {
   return Boolean(roomId) && roomPresence(roomId) === 'deleted';
 }
 
+// Task report statuses that post a row and wake nobody.
+const QUIET_TASK_STATUSES = new Set(['started', 'blocked', 'working']);
+
 /** The queued item of one task report (enqueueTask). */
-function taskReportItem({ runId, taskSessionId, title, status, text = '', target, files = [], omitted = 0, hop = 0 }) {
+function taskReportItem({
+  runId,
+  taskSessionId,
+  title,
+  status,
+  text = '',
+  target,
+  files = [],
+  omitted = 0,
+  hop = 0,
+  watchId = '',
+  watchIds = [],
+  progressRunId = '',
+}) {
   // The model-facing reply keeps its lines up to REPLY_LIMIT; the row's
   // one-line summary is derived from it (agentTaskMessage).
   const reply = boundedReply(text);
@@ -601,9 +701,19 @@ function taskReportItem({ runId, taskSessionId, title, status, text = '', target
     ...(reply.chars > reply.text.length ? { textChars: reply.chars } : {}),
     // Any session other than a task session the agent created.
     ...(target === 'session' ? { target } : {}),
+    // The send this report ends (the `sendId` the send's result named).
+    ...(watchId ? { sendId: String(watchId) } : {}),
+    // Every send this one turn answered (sends folded into a running turn
+    // report once); `sendId` is the first of them.
+    ...(watchIds.length > 1 ? { sendIds: watchIds.map(String) } : {}),
     // The files the turn produced (handoff-attachments.mjs collectTurnArtifacts).
     ...(Array.isArray(files) && files.length ? { files, ...(omitted > 0 ? { omitted } : {}) } : {}),
-    roundTrip: status !== 'started' && status !== 'blocked',
+    // The progress update that carried this final report's answer, if one
+    // did: the queue keeps the answer from being repeated (withoutRepeatedProgress).
+    ...(progressRunId ? { progressRunId: String(progressRunId) } : {}),
+    // Only a turn's end wakes the agent and counts a round trip: not its
+    // start, a wait for the user, or a progress update (status 'working').
+    roundTrip: !QUIET_TASK_STATUSES.has(status),
     ...(hop > 0 ? { hop } : {}),
     at: Date.now(),
   };
@@ -617,7 +727,7 @@ function postQueuedRows(session, items, omitted) {
   const fresh = [];
   const omittedId = omitted ? messageIdOf(omitted.id) : '';
   if (omitted && !posted.has(omittedId)) {
-    const message = routineOmittedMessage({ count: omitted.count, messageId: omittedId });
+    const message = postedMessage(routineOmittedMessage({ count: omitted.count, messageId: omittedId }));
     session.messages.push(message);
     fresh.push({ message, notice: routineResultNotice(message) });
   }
@@ -689,15 +799,17 @@ function createHomeRelay({
     log(`the relay turn in ${homeId} ${why}; its results stay posted unrelayed`);
     const messageId = messageIdOf(`relay_${batch.id}`);
     if (!session.messages.some((message) => message?.meta?.transcript?.messageId === messageId)) {
-      const message = agentTaskRelayFailedMessage({
-        count: batch.runIds.length + (batch.overflow?.count || 0),
-        tries,
-        messageId,
-      });
+      const message = postedMessage(
+        agentTaskRelayFailedMessage({
+          count: batch.runIds.length + (batch.overflow?.count || 0),
+          tries,
+          messageId,
+        })
+      );
       session.messages.push(message);
       session.updatedAt = Date.now();
       await saveSession(session);
-      noticeLive(live, log, homeId, { ...routineResultNotice(message), messageId });
+      noticeLive(live, log, homeId, { ...routineResultNotice(message), messageId, at: message.meta.transcript.at });
     }
     await queue.woke(homeId, batch.id);
     return true;
@@ -780,6 +892,200 @@ function createHomeRelay({
   return { wakeOwed };
 }
 
+/** Whether home thread `sessionId` is busy: a turn in flight in this process,
+ *  or the `live()` surface says so (false when it threw). */
+const homeBusy = (turnInFlight, live) => (sessionId) => {
+  if (turnInFlight(sessionId)) return true;
+  try {
+    return live()?.busy?.(sessionId) === true;
+  } catch {
+    return false;
+  }
+};
+
+/** `later(homeId, ms)`: drain `homeId` again after `ms`, one retry timer per
+ *  home armed at a time. */
+function createRetryTimer(retryLater, drain) {
+  const waiting = new Set(); // homes with a retry timer armed
+  return function later(homeId, ms) {
+    if (waiting.has(homeId)) return;
+    waiting.add(homeId);
+    retryLater(() => {
+      waiting.delete(homeId);
+      void drain(homeId);
+    }, ms);
+  };
+}
+
+/** The held requests shown live in a busy thread. A held request waits on the
+ *  user, possibly raised by the very turn that keeps its thread busy (a
+ *  routine turn): `show` shows it live at once; the stored row (same
+ *  messageId) replaces it once the thread is idle, and `forget` lets a later
+ *  one show again. */
+function createHeldLiveDisplay(live, log) {
+  const shownLive = new Set(); // held-request message ids shown live in a busy thread
+  return {
+    show(homeId, items) {
+      for (const item of items) {
+        if (item.kind !== 'held-request') continue;
+        const messageId = messageIdOf(item.runId);
+        if (shownLive.has(messageId)) continue;
+        shownLive.add(messageId);
+        noticeLive(live, log, homeId, { ...deliveredRow(item, messageId).notice, messageId, at: item.at });
+      }
+    },
+    forget(items) {
+      for (const item of items) shownLive.delete(messageIdOf(item.runId));
+    },
+  };
+}
+
+/** The queues a drain drops unposted instead of retrying them. */
+function createQueueDrops({ queue, log, homeAgent, homeDeleted, sessionDeleted }) {
+  /** A room thread proven gone: its queued rows are dropped, never retried. */
+  async function dropGoneRoomThread(homeId, items, omitted) {
+    if (!isRoomThreadSessionId(homeId) || !(homeDeleted(homeId) || sessionDeleted(homeId))) return false;
+    log(`${items.length} task report(s) for the deleted ${homeId} are dropped`);
+    await dropQueued(queue, homeId, items, omitted);
+    return true;
+  }
+
+  /** A room log's queued rows: task reports go to member sessions now, so what
+   *  an earlier version left under the log's id is dropped, never posted. */
+  async function dropRoomLogQueue(logId, items, omitted) {
+    log(`${items.length} legacy task report(s) queued for the room log ${logId} are dropped`);
+    await dropQueued(queue, logId, items, omitted);
+  }
+
+  /** A missing home of an agent that can never have one (no bot): its queued
+   *  rows are dropped with a log line, never retried. */
+  async function dropHomeless(homeId, items, omitted) {
+    const agentId = agentIdOfHomeSession(homeId);
+    if (!agentId || agentId === MIXY_AGENT_ID || homeAgent(agentId) !== 'none') return false;
+    log(`${items.length} result(s) for ${homeId} are dropped: ${agentId} is not a bot, so it has no chat`);
+    await dropQueued(queue, homeId, items, omitted);
+    return true;
+  }
+
+  return { dropGoneRoomThread, dropRoomLogQueue, dropHomeless };
+}
+
+/** The durable intake of a home: each enqueue persists its row for the home
+ *  thread, then starts draining it, and resolves once it is queued. */
+function createHomeEnqueue(queue, drain, { postingFor, postedIn }) {
+  /** Persist `result` ({ runId, kind, ok, text, runSessionId }) of a schedule
+   *  or webhook `row` for its owner's home, then start draining it. Resolves
+   *  once it is queued. */
+  async function enqueue(row, result) {
+    const homeId = agentHomeSessionId(scheduleOwnerAgentId(row));
+    if (!result?.runId) throw new Error('routine result: runId required');
+    await queue.add(homeId, routineResultItem(row, result));
+    void drain(homeId);
+    return homeId;
+  }
+
+  /** Persist one held-request row (`held`: normalizeHeldRequest fields) for
+   *  `agentId`'s home thread, then start draining it. Each status posts once. */
+  async function enqueueHeld(agentId, held) {
+    const homeId = agentHomeSessionId(agentId) || agentHomeSessionId(MIXY_AGENT_ID);
+    if (!held?.id) throw new Error('held request: id required');
+    await queue.add(homeId, {
+      runId: `${held.id}_${held.status || 'pending'}`,
+      kind: 'held-request',
+      held,
+      at: Date.now(),
+    });
+    void drain(homeId);
+    return homeId;
+  }
+
+  /** Persist one report of a coding task session `agentId` created (session
+   *  create) for its home thread, then start draining it. `status` 'started'
+   *  and 'blocked' only post a line; a turn's end also wakes the agent. */
+  async function enqueueTask(agentId, report) {
+    const { runId, taskSessionId, watchId = '', watchIds = [], from = '' } = report;
+    const homeId = agentHomeSessionId(agentId) || agentHomeSessionId(MIXY_AGENT_ID);
+    if (!runId || !taskSessionId) throw new Error('task report: runId and taskSessionId required');
+    const item = taskReportItem(report);
+    const unwatch = [...new Set([watchId, ...watchIds].filter(Boolean).map(String))];
+    // A room member's own work reports to its member session, never its home.
+    const target = roomMemberOfSession(from)?.agentId === agentId ? from : homeId;
+    if (item.progressRunId) {
+      // Whether its answer already went out as that progress update is
+      // decided in the thread's posting turn, against the thread itself: a
+      // row being posted (or posted before a crash, not dequeued yet) counts
+      // as posted, never as still queued.
+      await postingFor(target, async () =>
+        queue.add(target, item, { unwatch, progressPosted: postedIn(target, item.progressRunId) })
+      );
+    } else {
+      // A progress update moves its send's watch mark (`progressed`) to the
+      // turn it carries, in the same write: a restart never reports it again.
+      const progressed = report.progressWatchId
+        ? { runId: String(report.progressWatchId), turnId: String(report.answerId || '') }
+        : null;
+      await queue.add(target, item, { unwatch, progressed });
+    }
+    void drain(target);
+    return target;
+  }
+
+  /** Persist `text`, the agent's own reply from turn `runId` it ran outside
+   *  its thread, for `agentId`'s home thread, then start draining it. It posts
+   *  once, as the agent's message; no turn follows. */
+  async function enqueueMessage(agentId, { runId, text }) {
+    const homeId = agentHomeSessionId(agentId) || agentHomeSessionId(MIXY_AGENT_ID);
+    if (!runId || !String(text || '').trim()) throw new Error('agent message: runId and text required');
+    await queue.add(homeId, { runId: String(runId), kind: 'agent-message', text: String(text).trim(), at: Date.now() });
+    void drain(homeId);
+    return homeId;
+  }
+
+  return { enqueue, enqueueHeld, enqueueTask, enqueueMessage };
+}
+
+/** The queue's bookkeeping across processes: report watches and the restart
+ *  recovery that retires deleted homes and drains what was left queued. */
+function createHomeBookkeeping({ queue, log, homeDeleted, sessionDeleted, drain }) {
+  /** Retire the bookkeeping of deleted homes (and stale round counts). */
+  async function prune() {
+    await queue.prune((await queue.bookkeptHomes()).filter(homeDeleted));
+  }
+
+  /** Store `watch`; a home at its watch cap first gives up its oldest watches
+   *  whose target sessions are proven deleted, and refuses the watch (so the
+   *  send claims no report) when that frees too few. */
+  async function watchTask(watch) {
+    const drop = watchesToDrop(await queue.watches(), watch, queue.watchCap, sessionDeleted);
+    if (drop.length) {
+      log(`${watch.homeSessionId} is at its watch cap: dropped ${drop.length} watch(es) of deleted sessions`);
+    }
+    await queue.watch(watch, { drop });
+  }
+
+  /** Drain every queue left by an earlier process, after retiring stale bookkeeping. */
+  async function recover() {
+    try {
+      await prune();
+    } catch (error) {
+      log(`pruning the routine results failed: ${error?.message || error}`);
+    }
+    // The stored watches name the hand-offs an earlier process left open:
+    // reading them notes each one now, so a target that asks again after the
+    // restart reaches the chat that handed it the work.
+    try {
+      await queue.watches();
+    } catch (error) {
+      log(`reading the report watches failed: ${error?.message || error}`);
+    }
+    const homes = await queue.pendingHomes();
+    for (const homeId of homes) void drain(homeId);
+    return homes;
+  }
+
+  return { watchTask, recover };
+}
+
 export function createAgentHomeDelivery({
   loadSession,
   saveSession,
@@ -801,6 +1107,9 @@ export function createAgentHomeDelivery({
   // at all. 'none' (proven: a workflow agent such as Reviewer) drops the rows
   // queued for its missing home instead of waiting on it forever.
   homeAgent = () => 'unknown',
+  // Whether the representative bot exists (mixy-presence.mjs): while it does
+  // not, heartbeat reports queued for its home are dropped.
+  mixyExists = async () => true,
   // Waits before each new try of a relay turn that did not finish; past the
   // last one the results stay posted with a note and nobody is woken.
   wakeRetryDelaysMs = WAKE_RETRY_DELAYS_MS,
@@ -813,19 +1122,20 @@ export function createAgentHomeDelivery({
   roomRelay = (sessionId, prompt, options) => agentRoomHost().relay(sessionId, prompt, options),
   log = (line) => process.stderr.write(`mixdog routines: ${line}\n`),
 }) {
-  const busy = (sessionId) => {
-    if (turnInFlight(sessionId)) return true;
-    try {
-      return live()?.busy?.(sessionId) === true;
-    } catch {
-      return false;
-    }
-  };
+  const busy = homeBusy(turnInFlight, live);
   const draining = new Map(); // home → the running pass
   const again = new Set(); // homes enqueued to while their pass ran
-  const waiting = new Set(); // homes with a retry timer armed
-  const shownLive = new Set(); // held-request message ids shown live in a busy thread
   const waitLogged = new Set(); // missing homes whose wait was logged
+  const later = createRetryTimer(retryLater, drain);
+  const heldLive = createHeldLiveDisplay(live, log);
+  const homeDeleted = (homeId) => homeProvenDeleted(homeId, agentPresence, roomPresence);
+  const { dropGoneRoomThread, dropRoomLogQueue, dropHomeless } = createQueueDrops({
+    queue,
+    log,
+    homeAgent,
+    homeDeleted,
+    sessionDeleted,
+  });
   const relay = createHomeRelay({
     queue,
     saveSession,
@@ -840,61 +1150,123 @@ export function createAgentHomeDelivery({
     busyRetryMs,
     missingRetryMs,
   });
-
-  /** A held request waits on the user, possibly raised by the very turn that
-   *  keeps its thread busy (a routine turn): show it live at once; the stored
-   *  row (same messageId) replaces it once the thread is idle. */
-  function showHeldLive(homeId, items) {
-    for (const item of items) {
-      if (item.kind !== 'held-request') continue;
-      const messageId = messageIdOf(item.runId);
-      if (shownLive.has(messageId)) continue;
-      shownLive.add(messageId);
-      noticeLive(live, log, homeId, { ...deliveredRow(item, messageId).notice, messageId });
-    }
+  // Per thread, one posting turn at a time: push queued rows, save the
+  // thread, dequeue them (the drain, the turn prelude), and a final report's
+  // check whether its answer already went out as a progress update. No pass
+  // ever dequeues rows another pushed but has not saved yet, and a row being
+  // posted is never mistaken for one still queued.
+  const postingChains = new Map();
+  function postingFor(homeId, fn) {
+    const run = (postingChains.get(homeId) || Promise.resolve()).then(fn);
+    const tail = run.then(
+      () => {},
+      () => {}
+    );
+    postingChains.set(homeId, tail);
+    void tail.then(() => {
+      if (postingChains.get(homeId) === tail) postingChains.delete(homeId);
+    });
+    return run;
   }
+  /** Whether queued row `runId` is in thread `homeId` (posted, saved or not). */
+  const postedIn = (homeId, runId) => {
+    const messages = loadSession(homeId)?.messages;
+    const messageId = messageIdOf(runId);
+    return Array.isArray(messages) && messages.some((message) => message?.meta?.transcript?.messageId === messageId);
+  };
+  const intake = createHomeEnqueue(queue, drain, { postingFor, postedIn });
+  const { watchTask, recover } = createHomeBookkeeping({ queue, log, homeDeleted, sessionDeleted, drain });
 
-  function later(homeId, ms) {
-    if (waiting.has(homeId)) return;
-    waiting.add(homeId);
-    retryLater(() => {
-      waiting.delete(homeId);
-      void drain(homeId);
-    }, ms);
+  /** Append `items` (and the omission notice `omitted`) not posted before to
+   *  `homeId`'s thread `session`, store it and show the new rows live.
+   *  Returns the run ids owed a wake (postQueuedRows). Nothing awaits before
+   *  the push, so no turn can start in between. */
+  async function postRows(homeId, session, items, omitted) {
+    if (!Array.isArray(session.messages)) session.messages = [];
+    const { fresh, toWake } = postQueuedRows(session, items, omitted);
+    heldLive.forget(items);
+    // The caller dequeues `items` (and `omitted`) next: the thread holding
+    // them is saved first, also when an earlier pass pushed them but its save
+    // failed (they are in the thread in memory, not on disk).
+    if (items.length || omitted) {
+      if (fresh.length) session.updatedAt = Date.now();
+      await saveSession(session);
+    }
+    for (const { message, notice } of fresh) {
+      const { messageId, at } = message.meta.transcript;
+      noticeLive(live, log, homeId, { ...notice, messageId, at });
+    }
+    return toWake;
   }
 
-  /** A room thread proven gone: its queued rows are dropped, never retried. */
-  async function dropGoneRoomThread(homeId, items, omitted) {
-    if (!isRoomThreadSessionId(homeId) || !(homeDeleted(homeId) || sessionDeleted(homeId))) return false;
-    log(`${items.length} task report(s) for the deleted ${homeId} are dropped`);
-    await dropQueued(queue, homeId, items, omitted);
-    return true;
+  /** Right before a turn of thread `homeId` takes its prompt (whatever started
+   *  it: the user, a routine, a wake): post its queued rows that wake nobody —
+   *  progress updates of the sessions its agent handed work to, start and wait
+   *  lines, held requests, routine results — in queue order, so the turn reads
+   *  them before its prompt. Rows that wake the agent stay for the drain after
+   *  the turn, which posts them and wakes it as before. The caller starts the
+   *  turn, so the thread's busy state is its own. Rows the queue dropped past
+   *  its limit are announced first by the "n omitted" notice, retired in the
+   *  same write that dequeues the posted rows (as the drain does). It runs
+   *  in the thread's posting turn (postingFor), never beside the drain's. A
+   *  failure is logged; the turn goes on and the drain posts the rows later. */
+  async function postBeforeTurn(homeId) {
+    try {
+      await postingFor(homeId, async () => {
+        const items = (await queue.items(homeId)).filter((item) => !wakesAgent(item));
+        const omitted = await queue.omitted(homeId);
+        if (!items.length && !omitted) return;
+        const session = loadSession(homeId);
+        if (!session || session.closed === true) return;
+        await postRows(homeId, session, items, omitted);
+        await queue.remove(
+          homeId,
+          items.map((item) => item.runId),
+          omitted
+        );
+      });
+    } catch (error) {
+      log(`posting the rows owed before a turn of ${homeId} failed: ${error?.message || error}`);
+    }
   }
 
-  /** A room log's queued rows: task reports go to member sessions now, so what
-   *  an earlier version left under the log's id is dropped, never posted. */
-  async function dropRoomLogQueue(logId, items, omitted) {
-    log(`${items.length} legacy task report(s) queued for the room log ${logId} are dropped`);
-    await dropQueued(queue, logId, items, omitted);
+  /** Mixy's heartbeat reports queued for her home while she does not exist
+   *  are dropped, never posted once she is created (issue #243); so is the
+   *  omission notice when nothing else waits (the rows it counts were these
+   *  reports too). Returns what is left to post. */
+  async function dropHeartbeatReports(homeId, items, omitted) {
+    const kept = items.filter((item) => !isHeartbeatReport(item));
+    const retired = kept.length ? null : omitted;
+    log(`${items.length - kept.length} heartbeat report(s) for ${homeId} are dropped: Mixy was never created`);
+    await queue.remove(
+      homeId,
+      items.filter(isHeartbeatReport).map((item) => item.runId),
+      retired
+    );
+    return { items: kept, omitted: retired ? null : omitted };
   }
 
-  /** A missing home of an agent that can never have one (no bot): its queued
-   *  rows are dropped with a log line, never retried. */
-  async function dropHomeless(homeId, items, omitted) {
-    const agentId = agentIdOfHomeSession(homeId);
-    if (!agentId || agentId === MIXY_AGENT_ID || homeAgent(agentId) !== 'none') return false;
-    log(`${items.length} result(s) for ${homeId} are dropped: ${agentId} is not a bot, so it has no chat`);
-    await dropQueued(queue, homeId, items, omitted);
-    return true;
+  /** Post every queued result of `homeId` if its thread is idle, in its
+   *  posting turn, then wake the agent for what it owes; else retry later.
+   *  The wake runs outside the posting turn: the turn it starts posts first
+   *  (postBeforeTurn). */
+  async function drainOnce(homeId) {
+    const session = await postingFor(homeId, () => postIdle(homeId));
+    if (session) await relay.wakeOwed(homeId, session);
   }
 
-  /** Post every queued result of `homeId` if its thread is idle; else retry later. */
-  async function drainOnce(homeId) {
-    const items = await queue.items(homeId);
-    const omitted = await queue.omitted(homeId);
+  /** drainOnce's posting: the thread it posted to; nothing when nothing is
+   *  owed or the pass ends here (moved, busy, missing, dropped). */
+  async function postIdle(homeId) {
+    let items = await queue.items(homeId);
+    let omitted = await queue.omitted(homeId);
     const owed = owesWake(await queue.wakes(homeId));
     if (!items.length && !omitted && !owed) return;
     if (roomIdOfSession(homeId)) return dropRoomLogQueue(homeId, items, omitted);
+    if (homeId === MIXY_HOME && items.some(isHeartbeatReport) && !(await mixyExists())) {
+      ({ items, omitted } = await dropHeartbeatReports(homeId, items, omitted));
+      if (!items.length && !omitted && !owed) return;
+    }
     const agentId = agentIdOfHomeSession(homeId);
     if (agentId && agentId !== MIXY_AGENT_ID && agentPresence(agentId) === 'deleted') {
       // The owner is gone (its home archived): Mixy, the default owner, gets them.
@@ -906,7 +1278,7 @@ export function createAgentHomeDelivery({
       return;
     }
     if (busy(homeId)) {
-      showHeldLive(homeId, items);
+      heldLive.show(homeId, items);
       return later(homeId, busyRetryMs);
     }
     // From here to the push nothing awaits, so no turn can start in between.
@@ -921,16 +1293,7 @@ export function createAgentHomeDelivery({
       }
       return later(homeId, missingRetryMs);
     }
-    if (!Array.isArray(session.messages)) session.messages = [];
-    const { fresh, toWake } = postQueuedRows(session, items, omitted);
-    for (const item of items) shownLive.delete(messageIdOf(item.runId));
-    if (fresh.length) {
-      session.updatedAt = Date.now();
-      await saveSession(session);
-      for (const { message, notice } of fresh) {
-        noticeLive(live, log, homeId, { ...notice, messageId: message.meta.transcript.messageId });
-      }
-    }
+    const toWake = await postRows(homeId, session, items, omitted);
     // Dequeuing and owing the wake are one write: no restart between posting
     // and waking loses the wake.
     const { overflowed } = await queue.remove(
@@ -940,7 +1303,7 @@ export function createAgentHomeDelivery({
       { wake: toWake }
     );
     if (overflowed) log(`${homeId} is at its wake cap: ${overflowed} result(s) ride the next wake as a count`);
-    await relay.wakeOwed(homeId, session);
+    return session;
   }
 
   /** The single drainer of `homeId`; a call during a pass runs one more pass. */
@@ -967,48 +1330,6 @@ export function createAgentHomeDelivery({
     return pass;
   }
 
-  /** Persist `result` ({ runId, kind, ok, text, runSessionId }) of a schedule
-   *  or webhook `row` for its owner's home, then start draining it. Resolves
-   *  once it is queued. */
-  async function enqueue(row, result) {
-    const homeId = agentHomeSessionId(scheduleOwnerAgentId(row));
-    if (!result?.runId) throw new Error('routine result: runId required');
-    await queue.add(homeId, routineResultItem(row, result));
-    void drain(homeId);
-    return homeId;
-  }
-
-  /** Persist one held-request row (`held`: normalizeHeldRequest fields) for
-   *  `agentId`'s home thread, then start draining it. Each status posts once. */
-  async function enqueueHeld(agentId, held) {
-    const homeId = agentHomeSessionId(agentId) || agentHomeSessionId(MIXY_AGENT_ID);
-    if (!held?.id) throw new Error('held request: id required');
-    await queue.add(homeId, {
-      runId: `${held.id}_${held.status || 'pending'}`,
-      kind: 'held-request',
-      held,
-      at: Date.now(),
-    });
-    void drain(homeId);
-    return homeId;
-  }
-
-  /** Persist one report of a coding task session `agentId` created (session
-   *  create) for its home thread, then start draining it. `status` 'started'
-   *  and 'blocked' only post a line; a turn's end also wakes the agent. */
-  async function enqueueTask(agentId, report) {
-    const { runId, taskSessionId, watchId = '', from = '' } = report;
-    const homeId = agentHomeSessionId(agentId) || agentHomeSessionId(MIXY_AGENT_ID);
-    if (!runId || !taskSessionId) throw new Error('task report: runId and taskSessionId required');
-    const item = taskReportItem(report);
-    const unwatch = watchId ? String(watchId) : '';
-    // A room member's own work reports to its member session, never its home.
-    const target = roomMemberOfSession(from)?.agentId === agentId ? from : homeId;
-    await queue.add(target, item, { unwatch });
-    void drain(target);
-    return target;
-  }
-
   /** Show `run`'s live-only row (routineRunNotice: `running`, or a result whose
    *  delivery failed) in `row`'s owner home when it is open and idle. Nothing
    *  is stored and no turn or unread mark follows; the posted result (same
@@ -1020,42 +1341,11 @@ export function createAgentHomeDelivery({
     return noticeLive(live, log, homeId, notice) === true;
   }
 
-  const homeDeleted = (homeId) => homeProvenDeleted(homeId, agentPresence, roomPresence);
-
-  /** Retire the bookkeeping of deleted homes (and stale round counts). */
-  async function prune() {
-    await queue.prune((await queue.bookkeptHomes()).filter(homeDeleted));
-  }
-
-  /** Store `watch`; a home at its watch cap first gives up its oldest watches
-   *  whose target sessions are proven deleted, and refuses the watch (so the
-   *  send claims no report) when that frees too few. */
-  async function watchTask(watch) {
-    const drop = watchesToDrop(await queue.watches(), watch, queue.watchCap, sessionDeleted);
-    if (drop.length) {
-      log(`${watch.homeSessionId} is at its watch cap: dropped ${drop.length} watch(es) of deleted sessions`);
-    }
-    await queue.watch(watch, { drop });
-  }
-
-  /** Drain every queue left by an earlier process, after retiring stale bookkeeping. */
-  async function recover() {
-    try {
-      await prune();
-    } catch (error) {
-      log(`pruning the routine results failed: ${error?.message || error}`);
-    }
-    const homes = await queue.pendingHomes();
-    for (const homeId of homes) void drain(homeId);
-    return homes;
-  }
-
   return {
-    enqueue,
-    enqueueHeld,
-    enqueueTask,
+    ...intake,
     announce,
     drain,
+    postBeforeTurn,
     recover,
     watchTask,
     unwatchTask: (runId) => queue.unwatch(runId),
@@ -1097,6 +1387,9 @@ async function processDelivery() {
       // A home chat exists only for bots; only a definition read successfully
       // can prove an agent is none (readHomeAgent).
       homeAgent: (agentId) => readHomeAgent({ dataDir: getPluginData(), shippedRoot: mixdogRoot(), id: agentId }),
+      // The one rule (mixy-presence.mjs; routine-owner.mjs imports this
+      // module, hence late).
+      mixyExists: async () => (await import('./routine-owner.mjs')).readMixyExists(),
       // Deleting a session unlinks its record (session-delete.mjs) and leaves
       // no tombstone: only an absent file with no in-memory copy proves it.
       // An unreadable file probes 'unreadable' and stays.
@@ -1128,6 +1421,11 @@ export async function deliverHeldRequest(agentId, held) {
   return (await processDelivery()).enqueueHeld(agentId, held);
 }
 
+/** Queue the agent's own reply of a turn it ran outside its home thread. */
+export async function deliverAgentMessage(agentId, message) {
+  return (await processDelivery()).enqueueMessage(agentId, message);
+}
+
 /** Queue one report of a task session for `agentId`'s home thread. */
 export async function deliverAgentTask(agentId, report) {
   return (await processDelivery()).enqueueTask(agentId, report);
@@ -1158,6 +1456,15 @@ export async function agentTaskWatches() {
   return (await processDelivery()).taskWatches();
 }
 
+/** The session turn prelude (session-turn-prelude.mjs) of the daemon: before a
+ *  turn of an agent's home thread or a room member session starts, its queued
+ *  rows that wake nobody post first (postBeforeTurn). Null for any other
+ *  session: nothing to wait for. */
+export function postBeforeAgentTurn(sessionId) {
+  if (!isAgentHomeSessionId(sessionId) && !roomMemberOfSession(sessionId)) return null;
+  return processDelivery().then((delivery) => delivery.postBeforeTurn(sessionId));
+}
+
 /** Daemon start: post the results an earlier process left queued. */
 export async function recoverScheduleResults() {
   return (await processDelivery()).recover();