mixdog 1.2.5 → 1.3.0

package/src/session-runtime/room-member-gate.mjs

@@ -0,0 +1,48 @@
+// A group-room member's tool calls (session/agent-room.mjs). Reads run freely;
+// anything that can change files or state asks the user through the ordinary
+// approval flow, whatever the agent's own permission or hook rules say — even
+// an agent that normally runs auto-approved. A hook's deny still wins.
+import { analyzeShellCommandEffects } from '../runtime/agent/orchestrator/tools/builtin/shell-analysis.mjs';
+
+const READ_ONLY_TOOLS = new Set([
+  'read',
+  'grep',
+  'glob',
+  'find',
+  'list',
+  'code_graph',
+  'load_tool',
+  'skill',
+  'Skill',
+  'recall',
+  'search_memories',
+  'web_search',
+  'web_fetch',
+  'local_fetch',
+  'image_fetch',
+  'ask_user',
+]);
+
+export const ROOM_APPROVAL_REASON = 'Group-room members need your approval before changing anything.';
+
+/** Whether `name(args)` only reads: a read-only tool, or a shell command whose
+ *  every stage the shell analysis classifies as non-mutating. */
+export async function isReadOnlyRoomCall({ name, args, cwd }, analyze = analyzeShellCommandEffects) {
+  if (READ_ONLY_TOOLS.has(name)) return true;
+  if (name !== 'shell' || typeof args?.command !== 'string') return false;
+  try {
+    return (await analyze(args.command, cwd))?.mutationMode === 'none';
+  } catch {
+    return false;
+  }
+}
+
+/** The PreToolUse decision for a room member's call: the hook's own `decision`
+ *  when it denies or the call only reads; otherwise an approval ask that keeps
+ *  any rewrite the hook made. */
+export async function roomMemberToolDecision(call, decision, analyze) {
+  const action = String(decision?.action || decision?.decision || '').toLowerCase();
+  if (action === 'deny' || action === 'block') return decision;
+  if (await isReadOnlyRoomCall(call, analyze)) return decision;
+  return { ...(decision && typeof decision === 'object' ? decision : {}), action: 'ask', reason: ROOM_APPROVAL_REASON };
+}

package/src/session-runtime/routine-home-turn.mjs

@@ -0,0 +1,156 @@
+/**
+ * A routine fire (schedule or webhook) is a TURN in its owner bot's home
+ * thread (`sess_home_<agentId>`): the routine's instructions are delivered
+ * there as a queued turn the bot handles itself — doing it or delegating as
+ * in any turn — and its reply in the chat is the result. Nothing else is
+ * created: no run session, no result card.
+ *
+ * The turn waits behind the thread's own work (a user turn, another routine):
+ * it rides the thread's queue as its own `routine` entry (one per turn, never
+ * merged or steered into another), shows as a routine marker row, and selects
+ * skills only from the routine's instructions (`skillSelection`), never from a
+ * webhook payload. While it runs the thread counts as unattended, so its
+ * approvals are held for the owner (held-requests.mjs). Resolves with the
+ * reply once the turn ends; rejects when the turn fails, is cancelled, or the
+ * caller's `signal` aborts (which also aborts the turn once it runs).
+ */
+import { randomUUID } from 'node:crypto';
+import { agentHomeSessionId } from '../runtime/agent/orchestrator/session/agent-home.mjs';
+import { routineHumanNeededText } from '../runtime/agent/orchestrator/session/routine-result.mjs';
+import { automationPromptContent } from '../runtime/shared/automation-attachments.mjs';
+import { ROUTINE_LIMITS } from '../runtime/shared/routine-limits.mjs';
+import { normalizeRoutineTrigger, routineTriggerHeader } from '../runtime/shared/routine-trigger.mjs';
+import { agentHomeLiveSurface, scheduleOwnerAgentId } from './agent-home-delivery.mjs';
+import { markUnattendedRun, unattendedRunOf } from './held-requests.mjs';
+
+// Routine turns waiting or running per home thread.
+const waiting = new Map();
+
+const abortError = (signal) =>
+  signal?.reason instanceof Error ? signal.reason : new Error(String(signal?.reason || 'routine run aborted'));
+
+async function defaultLoadSession(sessionId) {
+  const { loadSession } = await import('../runtime/agent/orchestrator/session/store.mjs');
+  return loadSession(sessionId);
+}
+
+function settledError(detail) {
+  if (detail?.status === 'cancelled') return new Error('the routine turn was cancelled');
+  if (detail?.status === 'rejected') return new Error("the bot's chat closed before the routine ran");
+  const error = detail?.error;
+  return new Error(String(error?.message || error || 'the routine turn failed'));
+}
+
+/**
+ * Deliver one fire of routine `name` (`kind` schedule | webhook) to its
+ * owner's home thread. `prompt` is the model-visible body (instructions, plus
+ * a webhook's fenced payload); `skillSelection` its trusted part (default:
+ * the whole body); `event` a short label for the marker (webhook event).
+ */
+export async function runRoutineTurn(
+  {
+    kind,
+    name,
+    ownerAgentId = null,
+    prompt,
+    skillSelection = null,
+    attachments = null,
+    cwd = null,
+    event = '',
+    signal = null,
+  },
+  {
+    surface = agentHomeLiveSurface(),
+    loadSession = defaultLoadSession,
+    limit = ROUTINE_LIMITS.homeQueueLimit,
+    log = (line) => process.stderr.write(`mixdog routines: ${line}\n`),
+  } = {}
+) {
+  const body = String(prompt || '').trim();
+  if (!body) throw new Error(`${kind} "${name}" has no instructions`);
+  if (signal?.aborted) throw abortError(signal);
+  if (typeof surface?.submit !== 'function') throw new Error('routine run: the session service is not running');
+  const agentId = scheduleOwnerAgentId({ ownerAgentId });
+  const homeId = agentHomeSessionId(agentId);
+  const home = await loadSession(homeId);
+  if (!home || home.closed === true) {
+    throw new Error(`the bot "${agentId}" has no chat yet: open it once in the app`);
+  }
+  const queued = waiting.get(homeId) || 0;
+  if (queued >= limit) throw new Error(`${limit} routine runs already wait in this bot's chat`);
+  waiting.set(homeId, queued + 1);
+  const trigger = normalizeRoutineTrigger({ kind, name, event });
+  const header = routineTriggerHeader({ kind, name, project: cwd ? String(cwd) : '' });
+  const content = automationPromptContent(`${header}\n\n${body}`, attachments);
+  return new Promise((resolve, reject) => {
+    let started = false;
+    let aborted = false;
+    let done = false;
+    let unmark = () => {};
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      const left = (waiting.get(homeId) || 1) - 1;
+      if (left > 0) waiting.set(homeId, left);
+      else waiting.delete(homeId);
+      signal?.removeEventListener?.('abort', onAbort);
+    };
+    const finish = (fn, value) => {
+      if (done) return;
+      done = true;
+      fn(value);
+    };
+    const abortTurn = () =>
+      Promise.resolve()
+        .then(() => surface.abort?.(homeId))
+        .catch((error) => log(`aborting ${kind} "${name}" in ${homeId} failed: ${error?.message || error}`));
+    function onAbort() {
+      aborted = true;
+      if (started) void abortTurn();
+      finish(reject, abortError(signal));
+    }
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+    const options = {
+      id: `routine_${randomUUID()}`,
+      mode: 'routine',
+      // Runs after the thread's current turn, never steered into it.
+      priority: 'later',
+      isMeta: true,
+      skipSlashCommands: true,
+      restorable: false,
+      // Esc ends this fire; it is never put back in the queue.
+      abortDiscardOnAbort: true,
+      skillSelection: String(skillSelection ?? body),
+      transcriptMeta: { routineTrigger: trigger },
+      onCommitted: () => {
+        if (started) return;
+        started = true;
+        // Nobody watches this turn: its approvals are held for the owner.
+        unmark = markUnattendedRun(homeId, { kind, agentId, name });
+        if (aborted) void abortTurn();
+      },
+      onSettled: (detail) => {
+        // Read before unmarking: a step only a person can do ended the turn.
+        const human = unattendedRunOf(homeId)?.humanNeeded;
+        unmark();
+        release();
+        if (human) finish(reject, new Error(routineHumanNeededText(human.outcome, human.site)));
+        else if (detail?.status === 'done') {
+          finish(resolve, { sessionId: homeId, result: String(detail?.result?.content || '') });
+        } else finish(reject, settledError(detail));
+      },
+    };
+    Promise.resolve()
+      .then(() => surface.submit(homeId, content, options))
+      .then((accepted) => {
+        if (accepted === true) return;
+        release();
+        finish(reject, new Error(`the bot's chat did not accept the ${kind} "${name}"`));
+      })
+      .catch((error) => {
+        release();
+        finish(reject, error);
+      });
+  });
+}

package/src/session-runtime/routine-owner.mjs

@@ -0,0 +1,48 @@
+/**
+ * Routines are bot-based: a schedule or webhook runs in its owner bot's home
+ * thread (routine-home-turn.mjs) and nowhere else. An owner that does not
+ * exist — Mixy before the representative bot was created, a bot archived or
+ * deleted — makes the routine paused: it does not fire, the lists show why,
+ * and a new routine cannot name it.
+ */
+import { MIXY_AGENT_ID } from '../runtime/agent/orchestrator/session/agent-home.mjs';
+import { scheduleOwnerAgentId } from './agent-home-delivery.mjs';
+
+/** `ownerProblem` codes and the error each one raises. */
+export const ROUTINE_OWNER_PROBLEMS = Object.freeze({
+  'no-mixy': 'Create the representative bot first.',
+  'owner-deleted': 'The bot that owns this routine no longer exists. Pick another bot.',
+});
+
+let editor = null;
+async function defaultProbe() {
+  if (!editor) {
+    const [{ getPluginData }, { createAgentEditorApi }] = await Promise.all([
+      import('../runtime/agent/orchestrator/config.mjs'),
+      import('./workflow-agents-api/agent-editor.mjs'),
+    ]);
+    editor = createAgentEditorApi({ cfgMod: { getPluginData } });
+  }
+  return {
+    // An undecided profile (null) counts as having Mixy: nobody is blocked by
+    // a flag the host has not written yet.
+    mixyExists: () => editor.getLeadStatus().created !== false,
+    presence: (agentId) => editor.agentDefinitionPresence([agentId])[agentId],
+  };
+}
+
+/** Why `ownerAgentId` (none = Mixy) cannot own or run a routine: a
+ *  ROUTINE_OWNER_PROBLEMS code, '' when it can. Only a proven deletion
+ *  counts for a bot; a read fault never pauses anything. */
+export async function routineOwnerProblem(ownerAgentId, probe = null) {
+  const owner = scheduleOwnerAgentId({ ownerAgentId });
+  const check = probe || (await defaultProbe());
+  if (owner === MIXY_AGENT_ID) return check.mixyExists() ? '' : 'no-mixy';
+  return check.presence(owner) === 'deleted' ? 'owner-deleted' : '';
+}
+
+/** Rejects with the owner's problem; resolves when it can own a routine. */
+export async function assertRoutineOwner(ownerAgentId, probe = null) {
+  const problem = await routineOwnerProblem(ownerAgentId, probe);
+  if (problem) throw new Error(ROUTINE_OWNER_PROBLEMS[problem]);
+}

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

@@ -1,71 +1,37 @@
 /**
- * Run a schedule as a VISIBLE Mixdog session instead of a hidden agent
- * dispatch. Shared by the engine run-now capability and the channels-worker
- * scheduler so both paths leave the same trail: a resumable session with
- * owner 'user' + sourceType 'schedule' (admitted by the lead-session list
- * filter as its own type, so it shows in desktop Recent / TUI resume), the
- * schedule's provider/model route, and the schedule's project cwd.
+ * Run a schedule fire: its instructions become one turn in its owner bot's
+ * home thread (routine-home-turn.mjs), under the owned-routine guards
+ * (owned-automation-run.mjs). Shared by the engine's "Run now" and the
+ * channels-worker scheduler.
  */
-import { loadConfig } from '../runtime/agent/orchestrator/config.mjs';
-import { createSession } from '../runtime/agent/orchestrator/session/manager/session-lifecycle.mjs';
-import { askSession } from '../runtime/agent/orchestrator/session/manager/ask-session.mjs';
-import { modelRouteFields, parseScheduleModelRef } from '../runtime/shared/schedule-model-ref.mjs';
-import { migrateCodexRoute } from '../runtime/agent/orchestrator/providers/openai-oauth-catalog-store.mjs';
-import { automationWorkflowOpts } from './automation-workflow.mjs';
-import { runAutomationTurns } from './automation-agents.mjs';
-import { automationPromptContent } from '../runtime/shared/automation-attachments.mjs';
-
-/** Resolve schedule.model into a {provider,model,effort?,fast?} route. */
-function scheduleRouteFromModelRef(modelRef, config = null) {
-  const ref = parseScheduleModelRef(modelRef);
-  // A model the provider catalog superseded runs on its successor.
-  if (ref && typeof ref === 'object') return migrateCodexRoute(ref);
-  const cfg = config || loadConfig({ secrets: false });
-  const preset = cfg.presets?.find((p) => p.id === ref || p.name === ref);
-  if (!preset) {
-    throw new Error(`schedule model "${ref}" is neither a provider/model route nor a known preset name`);
-  }
-  return modelRouteFields(preset);
-}
+import { markScheduleSkipped } from '../runtime/channels/lib/schedules-db.mjs';
+import { runOwnedAutomation } from './owned-automation-run.mjs';
+import { runRoutineTurn } from './routine-home-turn.mjs';
 
 /**
- * Create the visible schedule session and run the prompt in it.
- * `prompt` overrides schedule.prompt when the caller (channels worker) has
- * already resolved/wrapped the prompt body; the override is used verbatim
- * while the fallback gets a small origin header.
+ * One fire of `schedule`. `prompt` overrides schedule.prompt when the caller
+ * (channels worker) already resolved the body; `attended` marks a person's
+ * "Run now" (no failure backoff).
  */
-export async function runScheduleSession(schedule, { config = null, prompt: promptOverride = null } = {}) {
-  if (!schedule?.name) throw new Error('runScheduleSession: schedule row required');
-  const prompt = String(promptOverride ?? schedule.prompt ?? '').trim();
-  if (!prompt) throw new Error(`schedule "${schedule.name}" has no instructions`);
-  if (!schedule.model) {
-    throw new Error(`schedule "${schedule.name}" has no model configured — edit it and choose a model first`);
-  }
-  const route = scheduleRouteFromModelRef(schedule.model, config);
-  const cwd = schedule.cwd ? String(schedule.cwd) : null;
-  // Every fire is a fresh New task (user decision): one prompt, the
-  // schedule's model/workflow/project, a brand-new session in the sidebar
-  // Automations section (newest per name wins there).
-  const session = createSession({
-    ...modelRouteFields(route),
-    owner: 'user',
-    sourceType: 'schedule',
-    sourceName: schedule.name,
-    ...(cwd ? { cwd } : {}),
-    desktopSession: cwd
-      ? { classification: 'project', projectPath: cwd }
-      : { classification: 'task', projectPath: null },
-    ...automationWorkflowOpts(schedule.workflow),
-  });
-  // The user message is the schedule's instructions verbatim: the desktop
-  // title/preview derive from it, so no "[Scheduled task: …]" header noise.
-  // Stored attachments ride along as composer-style content parts.
-  const content = automationPromptContent(prompt, schedule.attachments);
-  // Agents the run delegates to report back; each result is the next turn.
-  const result = await runAutomationTurns(
-    session.id,
-    () => askSession(session.id, content, null, null, cwd || undefined),
-    (completions, askOpts) => askSession(session.id, completions, null, null, cwd || undefined, undefined, askOpts)
+export async function runScheduleSession(schedule, { attended = false, prompt = null, signal = null } = {}) {
+  const body = String(prompt ?? schedule.prompt ?? '').trim();
+  return runOwnedSchedule(
+    schedule,
+    ({ signal: runSignal }) =>
+      runRoutineTurn({
+        kind: 'schedule',
+        name: schedule.name,
+        ownerAgentId: schedule.ownerAgentId,
+        prompt: body,
+        attachments: schedule.attachments,
+        cwd: schedule.cwd || null,
+        signal: runSignal,
+      }),
+    { attended, signal }
   );
-  return { sessionId: session.id, result: String(result?.content || '') };
+}
+
+/** One owned run of `schedule` (owned-automation-run.mjs). */
+export function runOwnedSchedule(schedule, run, { recordSkip = markScheduleSkipped, ...deps } = {}) {
+  return runOwnedAutomation('schedule', schedule, run, { recordSkip, ...deps });
 }

package/src/session-runtime/services/agent-tool/close-flow.mjs

@@ -8,6 +8,7 @@ import {
 import { agentScope, clean, clearAgentStatuslineRoute } from './helpers.mjs';
 import { isLeadPoolAgent } from './worker-rows.mjs';
 import { createCloseAll } from './close-flow/close-all.mjs';
+import { closeManagedSession } from '../../lifecycle/shared.mjs';
 
 const CLOSE_REASON = 'cancelled by agent close';
 
@@ -68,7 +69,7 @@ export function createCloseFlow({ mgr, registry, views }) {
     // below is an idempotent no-op fallback once terminal.
     // Closing a runtime cancels its work; only explicit session deletion
     // may tombstone the conversation.
-    const ok = await mgr.closeSession(sessionId, 'cli-agent-close', { tombstone: false });
+    const ok = await closeManagedSession(mgr, sessionId, 'cli-agent-close', { tombstone: false });
     if (task?.taskId) cancelBackgroundTask(task.taskId, CLOSE_REASON);
     // Drop the row only once the cancellation is DURABLY recorded: a failed
     // close that still forgot the row would leave no cancelled state behind.

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

@@ -352,6 +352,16 @@ export function readAgentFrontmatterPermission(agent, dataDir, standaloneSourceR
   );
 }
 
+const _frontmatterKindCache = new Map(); // key -> { value, atMs }
+
+/** The agent definition's frontmatter `kind` (isContactAgentId reads it), or
+ *  null when it sets none. */
+export function readAgentFrontmatterKind(agent, dataDir, standaloneSourceRoot) {
+  return cachedFrontmatterValue(_frontmatterKindCache, agent, dataDir, standaloneSourceRoot, (fm) =>
+    typeof fm.kind === 'string' && fm.kind.trim() ? fm.kind.trim() : null
+  );
+}
+
 /** The agent definition's `firstResponseTimeoutMs` (a non-negative integer;
  *  0 disables the first-response deadline), or null when it sets none. */
 export function readAgentFirstResponseTimeoutMs(agent, dataDir, standaloneSourceRoot) {

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

@@ -76,13 +76,21 @@ export function createAgentList({ mgr, refreshTagsFromSessions, agentSessionEntr
   return function list({ scanSessions = false, context = {}, includeTerminal = false } = {}) {
     refreshTagsFromSessions({ scanSessions, context });
     const now = Date.now();
-    const rows = agentSessionEntries({ scanSessions, context }).map(({ tag, session, indexRow }) =>
+    const rows = agentSessionEntries({ scanSessions, context }).map(({ tag, session, indexRow, loaded }) =>
       agentRow({
         tag,
         session,
         indexRow,
         runtime: mgr.getSessionRuntime?.(session.id),
-        progress: progress.sessionProgressExtras(session.id, session.agent || null, now),
+        // A tag-bound entry is the getSession answer itself; an index row or
+        // a scanned summary is only a projection and still reads the session.
+        progress: progress.sessionProgressExtras(
+          session.id,
+          session.agent || null,
+          now,
+          null,
+          loaded ? { loaded: session } : {}
+        ),
         now,
       })
     );

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

@@ -58,9 +58,16 @@ export function liveAgentStatusRow(row) {
 }
 
 export function createSessionProgress({ mgr }) {
-  function sessionProgressExtras(sessionId, role, now = Date.now(), taskStatus = null) {
+  /** `loaded`: the caller's own getSession(sessionId) answer from this same
+   *  read, so the session is not loaded a second time. */
+  function sessionProgressExtras(sessionId, role, now = Date.now(), taskStatus = null, { loaded } = {}) {
     if (!sessionId) return {};
-    const session = mgr.getSession(sessionId);
+    // Only the session's status is read here: the manager's stamp-validated
+    // status lookup spares a whole-transcript read per idle worker per pulse.
+    let sessionStatus;
+    if (loaded !== undefined) sessionStatus = loaded?.status || null;
+    else if (typeof mgr.loadSessionStatus === 'function') sessionStatus = mgr.loadSessionStatus(sessionId) || null;
+    else sessionStatus = mgr.getSession(sessionId)?.status || null;
     const runtime = mgr.getSessionRuntime?.(sessionId) || null;
     const snapshot =
       typeof mgr.getSessionProgressSnapshot === 'function' ? mgr.getSessionProgressSnapshot(sessionId) : null;
@@ -72,8 +79,8 @@ export function createSessionProgress({ mgr }) {
       typeof mgr.getSessionPendingMessageDepth === 'function' ? mgr.getSessionPendingMessageDepth(sessionId) : null;
     return buildAgentTaskProgressFields({
       now,
-      sessionStatus: session?.status || null,
-      runtimeStage: runtime?.stage || snapshot?.stage || session?.status || null,
+      sessionStatus,
+      runtimeStage: runtime?.stage || snapshot?.stage || sessionStatus,
       snapshot,
       runtime,
       policy,
@@ -96,6 +103,8 @@ export function createSessionProgress({ mgr }) {
       stage: progress.worker_stage || runtime?.stage || status,
       // Additive: present only while the worker's turn waits on a user approval.
       ...(runtime?.awaitingUser ? { awaitingUser: runtime.awaitingUser } : {}),
+      // Additive: present only while the worker's turn sits in `task wait`.
+      ...(runtime?.taskWaits > 0 ? { awaitingTask: 'wait' } : {}),
       clientHostPid: session.clientHostPid || null,
       lastStreamDeltaAt: runtime?.lastStreamDeltaAt ? new Date(runtime.lastStreamDeltaAt).toISOString() : null,
       ...progress,

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

@@ -9,7 +9,7 @@ import {
 import { clean } from './helpers.mjs';
 import { createEarlyCompletionNotice } from './notify/early-completion.mjs';
 
-export function createNotify(mgr, { notifySessionCompletion } = {}) {
+export function createNotify(mgr, { notifySessionCompletion, onWorkerCompletionQueued = null } = {}) {
   function enqueueCompletionMessage(sessionId, text, meta = {}) {
     const target = clean(sessionId);
     if (!target || typeof mgr.enqueuePendingMessage !== 'function') return false;
@@ -28,8 +28,8 @@ export function createNotify(mgr, { notifySessionCompletion } = {}) {
         logDuplicateSkip('notify-enqueue', { executionId: meta?.execution_id, text: visible });
         return true;
       }
-      // Mark this as a deferred completion/task notification so a later session
-      // resume drops it rather than replaying it out-of-order (owner decision).
+      // Mark this as a completion/task notification: delivery dedupes it by
+      // execution id, and it stays queued (durably) until the model gets it.
       return Boolean(
         mgr.enqueuePendingMessage(
           target,
@@ -67,7 +67,18 @@ export function createNotify(mgr, { notifySessionCompletion } = {}) {
       // appear as a second Lead-level completion card. Agent task completion
       // has its own owner delivery path below; only that terminal handoff
       // crosses the parent boundary.
-      return workerId ? enqueueCompletionMessage(workerId, text, meta) : false;
+      if (!workerId) return false;
+      const queued = enqueueCompletionMessage(workerId, text, meta);
+      // A busy worker takes the completion at its next tool boundary; an idle
+      // one is woken so the result reaches it now, not at its next message.
+      if (queued && typeof onWorkerCompletionQueued === 'function') {
+        setImmediate(() => {
+          try {
+            onWorkerCompletionQueued(workerId);
+          } catch {}
+        });
+      }
+      return queued;
     };
   }
 

package/src/session-runtime/services/agent-tool/restart-notify.mjs

@@ -0,0 +1,134 @@
+// agent-tool/restart-notify.mjs
+// Agent tasks live in process memory, so a daemon restart ends every in-flight
+// one without a word: the successor only sees worker rows left `failed`
+// (process-restart). This tells each task's owner, exactly once.
+//
+// Order is what makes it safe: the failure notification is enqueued in the
+// owner's persisted pending queue under a stable id (`restart:<taskId>`) and
+// flushed to the spool FIRST; only then is the row stamped `restartNotified`.
+// A crash or a throw before the stamp leaves the row retryable, and the retry
+// re-enqueues the same id — the queue is id-idempotent, so the owner still
+// sees it once.
+import {
+  acknowledgeBackgroundTaskCompletion,
+  completeBackgroundTask,
+  getBackgroundTask,
+  registerBackgroundTask,
+} from '../../../runtime/shared/background-tasks.mjs';
+import { renderAgentCompletionEnvelope } from '../../../runtime/shared/task-notification-envelope.mjs';
+import { modelVisibleToolCompletionMessage } from '../../../runtime/shared/tool-execution-contract.mjs';
+import { clean } from './helpers.mjs';
+
+const RESTART_FAILURE_ERROR = 'process restart: the daemon restarted while this agent task was running';
+const SETTLE_TIMEOUT_MS = 5000;
+
+/** Stable dedup id of one lost task's notification. A row that never recorded
+ *  a task id falls back to its session and settle time. */
+export function restartNotificationId(row) {
+  return `restart:${clean(row.task_id) || `${clean(row.sessionId)}:${clean(row.finishedAt)}`}`;
+}
+
+/** `pendingRestartFailures()` lists rows whose owner is not yet told;
+ *  `markRestartNotified(rows)` stamps them. `mgr` supplies the persisted
+ *  pending queue (enqueuePendingMessage / markCompletionEntry /
+ *  settlePendingMessageWrites). `notifySessionCompletion` is only the live,
+ *  best-effort emit to attached surfaces after the durable enqueue. */
+export function createRestartFailureNotifier({
+  pendingRestartFailures,
+  markRestartNotified,
+  mgr,
+  notifySessionCompletion,
+}) {
+  function enqueueDurably(row) {
+    const owner = clean(row.ownerSessionId);
+    const executionId = restartNotificationId(row);
+    const meta = {
+      type: 'agent_task_result',
+      execution_surface: 'agent',
+      execution_id: executionId,
+      status: 'failed',
+      caller_session_id: owner,
+    };
+    const text = renderAgentCompletionEnvelope({
+      id: clean(row.task_id) || executionId,
+      tag: row.tag,
+      status: 'failed',
+      error: RESTART_FAILURE_ERROR,
+    });
+    const entry = mgr.markCompletionEntry(modelVisibleToolCompletionMessage(text, meta), { executionId, meta });
+    return { owner, text, meta, entry };
+  }
+
+  // Lets `agent status <id>` resolve after the restart; best-effort.
+  function registerFailedTask(row) {
+    const taskId = clean(row.task_id);
+    if (!taskId || getBackgroundTask(taskId)) return;
+    const owner = clean(row.ownerSessionId);
+    registerBackgroundTask({
+      taskId,
+      surface: 'agent',
+      operation: 'restart',
+      label: row.tag,
+      input: { type: 'restart', tag: row.tag, sessionId: row.sessionId, agent: row.agent || null },
+      context: { callerSessionId: owner, ownerSessionId: owner, clientHostPid: row.clientHostPid || null },
+      meta: {
+        tag: row.tag,
+        sessionId: row.sessionId,
+        agent: row.agent || null,
+        provider: row.provider || null,
+        model: row.model || null,
+        preset: row.preset || null,
+        effort: row.effort || null,
+      },
+      resultType: 'agent_task_result',
+    });
+    completeBackgroundTask(taskId, {
+      status: 'failed',
+      error: RESTART_FAILURE_ERROR,
+      terminalReason: 'process-restart',
+      notify: false,
+    });
+    acknowledgeBackgroundTaskCompletion(taskId);
+  }
+
+  async function notifyRow(row) {
+    const { owner, text, meta, entry } = enqueueDurably(row);
+    if (!(mgr.enqueuePendingMessage(owner, entry) > 0)) throw new Error(`restart notification refused for ${owner}`);
+    if (!(await mgr.settlePendingMessageWrites({ timeoutMs: SETTLE_TIMEOUT_MS }))) {
+      throw new Error(`restart notification for ${owner} did not reach the spool`);
+    }
+    markRestartNotified([row]);
+    try {
+      registerFailedTask(row);
+    } catch {
+      /* status lookup only */
+    }
+    try {
+      // Same execution id as the queued entry: the queue dedups the mirror.
+      notifySessionCompletion?.(owner, text, meta);
+    } catch {
+      /* the durable queue is authoritative */
+    }
+  }
+
+  let inFlight = null;
+  async function run() {
+    for (const row of pendingRestartFailures()) {
+      try {
+        await notifyRow(row);
+      } catch (err) {
+        // Not stamped: the next pass or restart retries this row.
+        process.stderr.write(`[agent-tool] restart notification retry pending: ${err?.message || err}\n`);
+      }
+    }
+  }
+
+  return function notifyRestartFailures() {
+    inFlight ||= run()
+      .catch((err) => process.stderr.write(`[agent-tool] restart notification pass failed: ${err?.message || err}\n`))
+      .finally(() => {
+        inFlight = null;
+      });
+    return inFlight;
+  };
+}