mixdog 1.4.1 → 1.4.3

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

@@ -55,14 +55,10 @@ export {
 // deployment recalibrate without a code change; values are clamped to a
 // plausible band.
 //
-// The Anthropic factor was 1.9 while opaque replay blobs were projected as a
-// fixed marker — that is, while a transcript's entire reasoning stream (15-35%
-// of it) was priced at zero, and the multiplier was silently covering the gap.
-// Now that those blobs carry their measured cost, the ratio was re-measured
-// against the provider's own token counter on twenty real transcripts:
-// 1.23-1.40, median 1.32 (previously 1.72-2.48 — a fifth of the spread, since
-// the multiplier no longer has to absorb a variable amount of reasoning).
-// 1.4 covers the measured maximum without double counting.
+// Opaque replay blobs carry their measured cost, so the Anthropic ratio does
+// not have to absorb a variable amount of reasoning. Measured against the
+// provider's own token counter on twenty real transcripts: 1.23-1.40, median
+// 1.32. 1.4 covers the measured maximum without double counting.
 //
 // Only Anthropic-style providers can be calibrated against reported usage at
 // all, because only they resend the whole transcript every turn. OpenAI/xAI
@@ -96,10 +92,10 @@ export { estimateRequestReserveTokens, estimateToolSchemaTokens, toolSchemaSigna
 
 // Opaque replay payloads (Anthropic thinking signatures, OpenAI encrypted
 // reasoning blobs, redacted data) are long base64-ish strings that ARE billed
-// proportionally to their serialized length — see the measurement below. They
-// were previously replaced with a fixed marker, which priced a provider's
-// entire reasoning stream at nearly zero. Project them at their measured cost
-// instead. Projection is KEY-SCOPED: only fields that structurally carry
+// proportionally to their serialized length — see the measurement below. A
+// fixed marker would price a provider's entire reasoning stream at nearly zero,
+// so they are projected at their measured cost. Projection is KEY-SCOPED: only
+// fields that structurally carry
 // opaque replay
 // material (signatures / encrypted / redacted / raw data blobs) are eligible,
 // so genuine long model text (e.g. Gemini thought text) keeps its real cost.

package/src/runtime/agent/orchestrator/session/conversation-import/claude.mjs

@@ -14,6 +14,7 @@ import {
   IMAGE_OMITTED_TEXT,
   IMPORT_WARNING_IMAGE_OMITTED,
   isWholeElement,
+  stringOrNull,
   textPart,
   titleFromText,
   toolNote,
@@ -78,7 +79,7 @@ export function unwrapClaudePastes(text) {
   return unwrapped.trim() ? unwrapped : text;
 }
 
-export function isClaudeEnvelopeText(text) {
+function isClaudeEnvelopeText(text) {
   const trimmed = String(text || '').trim();
   if (!trimmed) return true;
   return (
@@ -92,7 +93,7 @@ export function isClaudeEnvelopeText(text) {
 const tagValue = (text, tag) => new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`).exec(text)?.[1].trim() || '';
 
 /** A slash-command envelope as Claude Code shows it (`/name args`), else null. */
-export function claudeCommandText(text) {
+function claudeCommandText(text) {
   const trimmed = String(text || '').trim();
   if (!SLASH_COMMAND_RE.test(trimmed)) return null;
   const name = (tagValue(trimmed, 'command-name') || tagValue(trimmed, 'command-message')).replace(/^\//, '');
@@ -101,7 +102,6 @@ export function claudeCommandText(text) {
 }
 
 const isMessageEntry = (record) => record?.type === 'user' || record?.type === 'assistant';
-const stringOrNull = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
 const uuidOrNull = (value) => (typeof value === 'string' ? value : null);
 const timestampOrNull = (value) => (typeof value === 'string' || typeof value === 'number' ? value : null);
 // Rough fixed cost of one retained entry object, so tiny entries still count.
@@ -193,7 +193,7 @@ function entryParts(role, content, warnings, marks) {
  * (a cleared rename) ends the name tier without falling back to the AI title.
  * Other record types, such as `task-summary` or `agent-name`, never name it.
  */
-export function createClaudeTitleScan() {
+function createClaudeTitleScan() {
   let custom;
   let ai;
   let summary;

package/src/runtime/agent/orchestrator/session/conversation-import/codex.mjs

@@ -5,7 +5,14 @@
  * messages, Codex's own wrapper user messages, tool outputs, reasoning,
  * event_msg, token counts and turn_context.
  */
-import { IMAGE_OMITTED_TEXT, IMPORT_WARNING_IMAGE_OMITTED, isWholeElement, textPart, toolNote } from './turns.mjs';
+import {
+  IMAGE_OMITTED_TEXT,
+  IMPORT_WARNING_IMAGE_OMITTED,
+  isWholeElement,
+  stringOrNull,
+  textPart,
+  toolNote,
+} from './turns.mjs';
 
 // User-role envelopes Codex injects itself (environment, instructions, abort
 // notices, plugin hints, shell-command echoes, image wrappers).
@@ -21,7 +28,7 @@ const CODEX_ENVELOPE_TAGS = [
 ];
 const TOOL_CALL_TYPES = new Set(['function_call', 'custom_tool_call', 'local_shell_call']);
 
-export function isCodexEnvelopeText(text) {
+function isCodexEnvelopeText(text) {
   const trimmed = String(text || '').trim();
   if (!trimmed) return true;
   if (/^# AGENTS\.md instructions\b/.test(trimmed) && trimmed.includes('<INSTRUCTIONS>')) return true;
@@ -36,7 +43,7 @@ export function isCodexEnvelopeText(text) {
 const USER_REQUEST_HEADING = '## My request for Codex:';
 
 /** A user text part as Codex displays it. */
-export function codexUserDisplayText(text) {
+function codexUserDisplayText(text) {
   const at = text.lastIndexOf(USER_REQUEST_HEADING);
   return at < 0 ? text : text.slice(at + USER_REQUEST_HEADING.length).trim();
 }
@@ -64,8 +71,6 @@ function toolName(payload) {
   return payload.type === 'local_shell_call' ? 'local_shell' : '';
 }
 
-const stringOrNull = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
-
 // `session_meta.thread_source` values Codex gives threads it runs for itself.
 const INTERNAL_THREAD_SOURCES = {
   subagent: 'subagent',
@@ -81,7 +86,7 @@ const INTERNAL_THREAD_SOURCES = {
  * is the approval reviewer) or `{ internal: … }`. Other sources (cli, vscode,
  * exec, mcp, custom) and features (automation, voice chat) are the user's.
  */
-export function codexInternalKind(payload) {
+function codexInternalKind(payload) {
   const byThread = INTERNAL_THREAD_SOURCES[payload?.thread_source];
   if (byThread) return byThread;
   const source = payload?.source;

package/src/runtime/agent/orchestrator/session/conversation-import/convert.mjs

@@ -14,7 +14,7 @@ import {
   normalizeTurns,
 } from './turns.mjs';
 
-export const IMPORT_SOURCES = Object.freeze(['codex', 'claude']);
+const IMPORT_SOURCES = Object.freeze(['codex', 'claude', 'cowork']);
 /** A line or converted transcript beyond the import limits fails the file. */
 export const IMPORT_ERROR_TOO_LARGE = 'tooLarge';
 export const IMPORT_MAX_LINE_BYTES = 32 * 1024 * 1024;
@@ -58,7 +58,7 @@ export function createConversationConverter(
   let records = 0;
   let malformed = 0;
   let tooLarge = false;
-  let historyPartial = false;
+  let historyPartial = null;
   return {
     /** True while every message seen so far is a Claude sidechain message. */
     get sidechainOnly() {
@@ -67,9 +67,9 @@ export function createConversationConverter(
     markTooLarge() {
       tooLarge = true;
     },
-    /** A history base could not be followed in full. */
-    markHistoryPartial() {
-      historyPartial = true;
+    /** A history base could not be followed in full; `warning` names why. */
+    markHistoryPartial(warning = IMPORT_WARNING_HISTORY_PARTIAL) {
+      historyPartial = warning;
     },
     /** Feed a line for the stored title only (Claude Code's tail window); other sources ignore it. */
     pushTitleLine(raw) {
@@ -117,7 +117,7 @@ export function createConversationConverter(
       if (transcriptChars(turns) > maxTranscriptChars) tooLarge = true;
       const warnings = new Set(parsed.warnings);
       if (malformed) warnings.add(IMPORT_WARNING_MALFORMED);
-      if (historyPartial) warnings.add(IMPORT_WARNING_HISTORY_PARTIAL);
+      if (historyPartial) warnings.add(historyPartial);
       let errorCode = null;
       if (tooLarge) errorCode = IMPORT_ERROR_TOO_LARGE;
       else if (parsed.internalKind) errorCode = IMPORT_ERROR_INTERNAL;

package/src/runtime/agent/orchestrator/session/conversation-import/imported-session.mjs

@@ -12,11 +12,15 @@ import { writeStderrBestEffort } from '../../../../shared/best-effort-stderr.mjs
 import { IMPORTED_MESSAGE_SOURCE } from '../imported-message.mjs';
 import { ingestSessionTurn } from '../../../../session-search/session-search-ingest.mjs';
 
-export const IMPORT_ORIGIN_VERSION = 1;
+const IMPORT_ORIGIN_VERSION = 1;
 
-/** Dedupe identity: the foreign session id, else the canonical source path. */
+/**
+ * Dedupe identity: the foreign session id, else the canonical source path.
+ * Cowork transcripts are Claude Code transcripts, so both share the `claude` namespace.
+ */
 export function importOriginKey(source, foreignSessionId, canonicalPath) {
-  return foreignSessionId ? `${source}:${foreignSessionId}` : `${source}:path:${canonicalPath}`;
+  const namespace = source === 'cowork' ? 'claude' : source;
+  return foreignSessionId ? `${namespace}:${foreignSessionId}` : `${namespace}:path:${canonicalPath}`;
 }
 
 export function buildImportOrigin({ source, sourcePath, foreignSessionId = null, sourceCwd = null, importedAt }) {

package/src/runtime/agent/orchestrator/session/conversation-import/turns.mjs

@@ -11,6 +11,13 @@ export const IMPORT_WARNING_MALFORMED = 'malformed';
 export const IMPORT_WARNING_CWD_MISSING = 'cwdMissing';
 /** The conversation continues a history stored in another file that was not followed. */
 export const IMPORT_WARNING_HISTORY_PARTIAL = 'historyPartial';
+/** Earlier history was left out because following it would pass the import size limit. */
+export const IMPORT_WARNING_HISTORY_SIZE_LIMIT = 'historySizeLimit';
+/** Earlier history was left out because its file is missing or could not be read. */
+export const IMPORT_WARNING_HISTORY_UNAVAILABLE = 'historyUnavailable';
+
+/** A compressed rollout needs a Node.js runtime with zstd; used as the failure code and as the warning of an unreadable base. */
+export const IMPORT_ERROR_NEEDS_NEWER_NODE = 'needsNewerNode';
 
 /** Failure code of a record the source app writes for its own use (not a conversation). */
 export const IMPORT_ERROR_INTERNAL = 'internalRecord';
@@ -33,7 +40,7 @@ export function toolNote(name) {
 }
 
 /** Longest model-facing run line, and the longest tool name shown in it. */
-export const TOOL_RUN_LINE_MAX_CHARS = 400;
+const TOOL_RUN_LINE_MAX_CHARS = 400;
 const TOOL_RUN_NAME_MAX_CHARS = 40;
 
 /**
@@ -67,6 +74,9 @@ function toolRunCounts(notes) {
   return [...counts].map(([name, count]) => ({ name, count }));
 }
 
+/** A trimmed non-blank string, else null. */
+export const stringOrNull = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+
 export function textPart(text) {
   return { text: String(text), note: false };
 }

package/src/runtime/agent/orchestrator/session/eager-dispatch.mjs

@@ -39,9 +39,10 @@ export function createEagerDispatcher({
     repeatFailLimit,
   });
   const barriers = createEagerBarriers({ cwd });
-  // A capped turn runs its calls in order, so none past its cap starts early
-  // (loop/turn-limits.mjs).
-  const capped = turnLimitsOf(opts) !== null;
+  // A turn capped by calls or time runs its calls in order, so none past its
+  // cap starts early (loop/turn-limits.mjs).
+  const limits = turnLimitsOf(opts);
+  const capped = limits !== null && (limits.maxToolCalls !== Infinity || limits.wrapUpAt !== Infinity);
   const execute = (call, entry) =>
     executeToolFn(call.name, call.arguments, cwd, sessionId, sessionRef, {
       toolCallId: call.id,

package/src/runtime/agent/orchestrator/session/human-gate/held-message.mjs

@@ -7,7 +7,7 @@
 // user's words; the structured `heldRequest` payload is for the UI only.
 import { escapeHarnessTags } from '../../../../shared/shell-output-summary.mjs';
 
-export const HELD_REQUEST_SOURCE = 'held-request';
+const HELD_REQUEST_SOURCE = 'held-request';
 const STATUSES = new Set(['pending', 'approved', 'denied', 'expired']);
 
 const clean = (value, limit = 200) =>

package/src/runtime/agent/orchestrator/session/human-gate/requests.mjs

@@ -7,13 +7,19 @@
 //   secret     — the user types a value into a target field; the request names
 //                the target and the field label, never a value;
 //   takeover   — the user does a step themselves and says "done";
-//   permission — the user picks one of the offered scopes.
-// A response is one of HUMAN_RESPONSES plus a `remember` scope; a policy lists
+//   permission — the user picks one of the offered scopes;
+//   connector  — a bot asks for more authority on one connector tool of its
+//                own: the card names the tool, its current level and the one
+//                asked for, and the person picks the level (`scope`: one of
+//                `choices`) or denies. Answered once, never remembered.
+// A response is one of RESPONSES_BY_KIND for its kind plus a `remember` scope; a policy lists
 // the scopes it allows and can leave out `always`. Nothing here ever carries a
 // secret value: a decision that names one is stripped to its verdict.
 
-const HUMAN_REQUEST_KINDS = Object.freeze(['approval', 'outbound', 'secret', 'takeover', 'permission']);
-const HUMAN_RESPONSES = Object.freeze(['approve', 'deny', 'edit-and-approve', 'provide-secret', 'skip', 'done']);
+const HUMAN_REQUEST_KINDS = Object.freeze(['approval', 'outbound', 'secret', 'takeover', 'permission', 'connector']);
+/** The levels a connector card may raise a tool to. */
+export const CONNECTOR_WIDEN_LEVELS = Object.freeze(['needs_approval', 'auto']);
+const CONNECTOR_LEVELS = ['disabled', ...CONNECTOR_WIDEN_LEVELS];
 const REMEMBER_SCOPES = Object.freeze(['once', 'agent', 'always']);
 export const SECRET_REQUEST_TIMEOUT_MS = 120_000;
 /** What a secret's bound field is: a sign-in form (아이디 + 비밀번호), a lone
@@ -36,6 +42,7 @@ const RESPONSES_BY_KIND = Object.freeze({
   secret: ['provide-secret', 'skip'],
   takeover: ['done', 'deny'],
   permission: ['approve', 'deny'],
+  connector: ['approve', 'deny'],
 });
 const GRANTING_RESPONSES = new Set(['approve', 'edit-and-approve', 'provide-secret', 'done']);
 const TEXT_LIMIT = 200;
@@ -89,12 +96,15 @@ function rememberScopes(value) {
   return ['once', ...new Set(listed.filter((scope) => scope !== 'once'))];
 }
 
-/** The kind-specific fields of a request, whitelisted. Spread onto the
- *  presented request; `args` is replaced for a secret so no value rides it. */
+/** The kind-specific fields of a request, whitelisted, plus the connector
+ *  `account` a tool call is bound to (any kind; the card names it). Spread
+ *  onto the presented request; `args` is replaced for a secret so no value
+ *  rides it. */
 export function humanRequestFields(input = {}) {
+  const bound = text(input?.account) ? { account: text(input.account) } : {};
   const kind = input?.kind;
-  if (!HUMAN_REQUEST_KINDS.includes(kind)) return {};
-  const fields = { remember: rememberScopes(input.remember) };
+  if (!HUMAN_REQUEST_KINDS.includes(kind)) return bound;
+  const fields = { ...bound, remember: rememberScopes(input.remember) };
   // The agent the request acts for (its name on the card and the remembered grant).
   if (text(input.agentId)) fields.agentId = text(input.agentId);
   if (kind === 'outbound' && isRecord(input.outbound)) {
@@ -187,6 +197,20 @@ export function humanRequestFields(input = {}) {
         })),
     };
   }
+  if (kind === 'connector') {
+    const connector = isRecord(input.connector) ? input.connector : {};
+    const level = (value) => (CONNECTOR_LEVELS.includes(value) ? value : '');
+    fields.connector = {
+      server: text(connector.server),
+      tool: text(connector.tool),
+      from: level(connector.from),
+      requested: level(connector.requested),
+      choices: (Array.isArray(connector.choices) ? connector.choices : []).filter((choice) =>
+        CONNECTOR_WIDEN_LEVELS.includes(choice)
+      ),
+    };
+    fields.remember = ['once'];
+  }
   return fields;
 }
 
@@ -226,6 +250,11 @@ export function normalizeHumanResponse(request, approved, extra = {}) {
     const ids = (request?.permission?.scopes || []).map((scope) => scope.id);
     if (ids.includes(extra?.scope)) result.scope = extra.scope;
   }
+  // The level the person picked; none of the offered ones picks nothing.
+  if (kind === 'connector' && polarity) {
+    const choices = Array.isArray(request?.connector?.choices) ? request.connector.choices : [];
+    if (choices.includes(extra?.scope)) result.scope = extra.scope;
+  }
   return result;
 }
 

package/src/runtime/agent/orchestrator/session/human-gate/run-policy.mjs

@@ -20,7 +20,7 @@ export const AUTOMATION_GRANT_REASON =
 export const isGrantedRun = (run) => Boolean(run) && run.kind !== 'room';
 
 /** Whether an outbound request is a payment or permanent delete. */
-export function isForbiddenInRun(request) {
+function isForbiddenInRun(request) {
   const category = request?.kind === 'outbound' ? request.outbound?.category : '';
   return ACTION_KINDS.includes(category) && !isRememberableAction(category);
 }

package/src/runtime/agent/orchestrator/session/image-strip-recovery.mjs

@@ -151,7 +151,7 @@ export function persistsConfirmedImageRejection(err, strip) {
   return strip.uniqueImages === 1;
 }
 
-export const PREPARATION_FAILED_CODE = 'anthropic_image_preparation_failed';
+const PREPARATION_FAILED_CODE = 'anthropic_image_preparation_failed';
 
 /** True for prepareAnthropicImages' local "this image is invalid" rejection. */
 export function isImagePreparationFailed(err) {

package/src/runtime/agent/orchestrator/session/loop/completion-guards.mjs

@@ -37,7 +37,17 @@ export function crossTurnSignature(name, args) {
 // they must not reset the escalation ladder's "zero edit" condition. Skill /
 // recall / agent / task / cwd / load_tool are exploration/meta plumbing.
 // (tool_search kept as legacy alias for old transcripts.)
-const NON_PROGRESS_TOOLS = new Set(['Skill', 'recall', 'agent', 'task', 'cwd', 'session', 'load_tool', 'tool_search']);
+const NON_PROGRESS_TOOLS = new Set([
+  'Skill',
+  'recall',
+  'agent',
+  'task',
+  'cwd',
+  'session',
+  'load_tool',
+  'tool_search',
+  'todo',
+]);
 
 // True when a successfully-executed tool represents real edit/progress. A tool
 // counts as progress only if its def lacks readOnlyHint (not eager) AND it is

package/src/runtime/agent/orchestrator/session/loop/context-overflow.mjs

@@ -55,7 +55,7 @@ const tokens = (value) => `${Number(value || 0).toLocaleString('en-US')} tokens`
 // for any history, so compacting the history cannot help and is not tried.
 // The wording avoids provider context-overflow phrasing on purpose: this is
 // not a "conversation too long" refusal and must not be routed as one.
-export class ToolSurfaceExceedsContextError extends Error {
+class ToolSurfaceExceedsContextError extends Error {
   constructor({ sessionId, provider, model, overhead }) {
     const target = [provider, model].filter(Boolean).join('/') || 'this model';
     const reserve = overhead.kind === 'configured_reserve';

package/src/runtime/agent/orchestrator/session/loop/fresh-context.mjs

@@ -281,9 +281,11 @@ function currentSkillResolver(sessionRef, { preview = false } = {}) {
     const { resource } = delivery;
     // The tools whose use counts as use of the skill: its tool dependencies,
     // an MCP server as `mcp:<server>`.
-    const tools = (resource.toolDependencies || []).flatMap(({ type, value }) =>
-      type === 'tool' ? [value] : type === 'mcp' ? [`mcp:${value}`] : []
-    );
+    const tools = (resource.toolDependencies || []).flatMap(({ type, value }) => {
+      if (type === 'tool') return [value];
+      if (type === 'mcp') return [`mcp:${value}`];
+      return [];
+    });
     if (preview) return { body: delivery.body, native: undefined, tools };
     const envelope = loadSkillToolDependencies(
       buildSkillToolEnvelope(name, resource.content, resource.dir, resource),

package/src/runtime/agent/orchestrator/session/loop/loop-state.mjs

@@ -129,6 +129,8 @@ export function createLoopState({ provider, messages, model, tools, cwd, sendOpt
     opts,
     sessionId,
     onSkillPrompt: (content, message) => state.pendingSkillPrompts.push({ content, message }),
+    // Input taken into the turn at any boundary is new work to answer.
+    onInjected: () => state.noToolTurn.noteNewInput(),
   });
   // Bounded recovery for provider turns that returned no client tool calls
   // (max-output ladder, refusal retry, provider continuation, empty-turn
@@ -143,6 +145,8 @@ export function createLoopState({ provider, messages, model, tools, cwd, sendOpt
     escalateMaxTokens: () => state.provider?.escalatedMaxTokens?.(state.model, state.opts, state.lastSendTools) ?? null,
     // Characters the latest send put on screen through the live text stream.
     streamedChars: () => state.lastStreamedChars,
+    // A capped turn was told to reply; it may end without the todo check.
+    turnLimited: () => state.turnLimitNoticed === true,
   });
   return state;
 }
@@ -155,6 +159,9 @@ export function finishLoop(state) {
   // A reaction-only turn is a successful completion, never an empty finish.
   const terminationReason = classifyTerminationReason(response, { sessionAgent: state.sessionAgent });
   const reactionCompleted = terminationReason === 'empty' && state.noToolTurn.reactionCompleted;
+  // So is an empty end after a kept answer only todo bookkeeping followed:
+  // that answer is the turn's report (no-tool-turn.mjs).
+  const reportCompleted = terminationReason === 'empty' && state.noToolTurn.reportStands;
   return {
     ...response,
     usage: state.lastUsage || response.usage,
@@ -165,7 +172,7 @@ export function finishLoop(state) {
     toolCallsTotal: state.toolCallsTotal,
     providerState: state.providerState,
     providerStateUpdated: state.providerStateUpdated,
-    terminationReason: reactionCompleted ? undefined : terminationReason,
+    terminationReason: reactionCompleted || reportCompleted ? undefined : terminationReason,
     ...(reactionCompleted ? { reactionCompleted: true } : {}),
     providerContinuations: state.noToolTurn.providerContinuations,
     ...(state.routeUsageHops?.length

package/src/runtime/agent/orchestrator/session/loop/no-tool-turn/todo-check.mjs

@@ -0,0 +1,196 @@
+// End-of-turn completion check for the session's todo list.
+//
+// A turn that ends without a tool call while pending/in-progress items remain
+// gets one hidden reminder naming them, and the loop sends again. Bounded:
+// at most MAX_TODO_REMINDERS per user cycle (reset only by a genuine user
+// prompt, never by an automatic continuation), and silent after a reminder
+// that produced no progress (no tool batch since). Skipped while the turn is
+// genuinely waiting: on the user (an approval denied or a question left
+// unanswered this turn), on an agent, or on a background shell started this
+// user cycle (background-wait.mjs).
+// Cancelled, failed and usage-limited turns never reach this point.
+//
+// With an active Goal whose items are all closed, the same check asks once
+// per cycle for the completion audit: complete the Goal or append the rest.
+import { resolvePluginData } from '../../../../../shared/plugin-paths.mjs';
+import { awaitingBackgroundWork, beginUserCycle } from '../../../../../shared/background-wait.mjs';
+import { readStoredGoalSnapshot } from '../../../runtime-core/goal-storage.mjs';
+import {
+  clearTodo,
+  openTodoItems,
+  todoAllClosed,
+  todoPhases,
+  unfinishedTodoItems,
+} from '../../../runtime-core/todo-list.mjs';
+import { TODO_TOOL } from '../../../runtime-core/todo-tool-defs.mjs';
+import { HIDDEN_AGENT_NAMES } from '../hidden-agents.mjs';
+import { _isMutationTool, _isShellTool } from '../tool-classify.mjs';
+
+const MAX_TODO_REMINDERS = 3;
+
+// Sessions whose current turn waits on the user's decision (in memory: the
+// turn itself is in memory, and a new turn clears it).
+const userWaits = new Set();
+
+/** The current turn now waits on the user (approval denied, question dismissed). */
+export function noteTodoUserWait(sessionId) {
+  if (sessionId) userWaits.add(String(sessionId));
+}
+
+function checkState(session) {
+  const current = session.todoCheck;
+  if (current && typeof current === 'object') return current;
+  session.todoCheck = { reminders: 0, awaitingProgress: false, auditAsked: false };
+  return session.todoCheck;
+}
+
+/** A turn starts: `genuine` (a real user prompt) opens a new reminder cycle. */
+export function beginTodoTurn(session, { genuine = false } = {}) {
+  if (!session || typeof session !== 'object') return;
+  if (session.id) userWaits.delete(String(session.id));
+  if (genuine) {
+    session.todoCheck = { reminders: 0, awaitingProgress: false, auditAsked: false };
+    beginUserCycle(session.id);
+    // A finished list stays on screen until the user moves on, then goes the
+    // way a finished Goal does. An active Goal keeps it for its audit.
+    if (todoAllClosed(session) && !activeGoal(session.id)) clearTodo(session);
+  }
+}
+
+/**
+ * A delegated agent received a new brief or follow-up (a genuine prompt) with
+ * no open list: the hidden reminder trailing that prompt, once per prompt, or
+ * null. The tool description alone was read past on short multi-ask briefs.
+ */
+export function todoStartReminder(session) {
+  if (!session || typeof session !== 'object' || session.owner !== 'agent') return null;
+  if (HIDDEN_AGENT_NAMES.has(session.agent)) return null;
+  if (!session.tools?.some((tool) => tool?.name === TODO_TOOL.name)) return null;
+  if (openTodoItems(session).length) return null;
+  // `init` refuses while any item is unfinished (blocked included), so such a
+  // list is reconciled or appended to, never re-initialized.
+  if (unfinishedTodoItems(session).length) {
+    return [
+      '<system-reminder>',
+      'The todo list still has blocked items. If this brief adds asks, append them; first done, drop or unblock each blocked item that this brief settles. Do not init over them. Do not mention this reminder.',
+      '</system-reminder>',
+    ].join('\n');
+  }
+  return [
+    '<system-reminder>',
+    'If this brief has three or more steps or several asks, init the todo list with every ask as its own item in the same response as your first tool call; each item the brief lists is its own todo item, never folded into one. A single step or a plain answer needs none. Do not mention this reminder.',
+    '</system-reminder>',
+  ].join('\n');
+}
+
+/** A tool batch ran: the last reminder produced progress. */
+export function noteTodoProgress(session) {
+  if (session?.todoCheck?.awaitingProgress) session.todoCheck.awaitingProgress = false;
+}
+
+// Mid-turn nudge: a long turn can finish items without ever touching the list,
+// leaving the progress shown to the user stale. After this many successful
+// mutating tool calls with no todo call (and no earlier nudge), one hidden
+// reminder is appended. Counted per call, not per batch, so a turn of parallel
+// edits ages the list faster than a turn of reads; a batch of three edits is
+// three. What mutates is the work the list tracks: file edits, command
+// execution (shell, as a bash tool is) and mutating git/github requests.
+const STALE_TODO_MUTATIONS = 10;
+
+function mutatingCall(call, results) {
+  const name = call?.name ?? call?.function?.name;
+  const args = call?.arguments ?? call?.function?.arguments;
+  if (!_isMutationTool(name, args) && !_isShellTool(name)) return false;
+  const result = results.find((message) => message?.toolCallId === call.id);
+  // A call that failed or was skipped (a dependency guard after a failed edit) changed nothing.
+  return result?.toolKind !== 'error' && result?.toolKind !== 'skipped';
+}
+
+/**
+ * A tool batch ran with `calls` (and their result messages): the hidden
+ * stale-list reminder to append to the transcript, or null. Calls are read in
+ * order: a todo call restarts the count, a successful mutating call adds one.
+ * Outside the end-of-turn budget (`todoCheck.reminders`) and its progress gate.
+ */
+export function staleTodoReminder(session, calls = [], results = [], { sessionAgent = null } = {}) {
+  if (!session || typeof session !== 'object' || HIDDEN_AGENT_NAMES.has(sessionAgent)) return null;
+  const check = checkState(session);
+  for (const call of calls) {
+    if ((call?.name ?? call?.function?.name) === TODO_TOOL.name) check.staleMutations = 0;
+    else if (mutatingCall(call, results)) check.staleMutations = (check.staleMutations || 0) + 1;
+  }
+  const phases = todoPhases(session);
+  // A finished list needs nothing more; no list at all is nudged once per
+  // user cycle (long runs that never made one), an open list repeatedly.
+  if (phases.length && !openTodoItems(session).length) {
+    check.staleMutations = 0;
+    return null;
+  }
+  if (!phases.length && check.createNudged) return null;
+  if ((check.staleMutations || 0) < STALE_TODO_MUTATIONS) return null;
+  check.staleMutations = 0;
+  if (!phases.length) {
+    check.createNudged = true;
+    return [
+      '<system-reminder>',
+      'No todo list exists for this work yet. If it has three or more steps, init one now with the steps left and keep it current; if it is a single step, ignore this. Keep working; do not mention this reminder.',
+      '</system-reminder>',
+    ].join('\n');
+  }
+  return [
+    '<system-reminder>',
+    'The todo tool has not been used for a while. Mark finished items done now (one call each, never batched at the end) so the in-progress pointer is on what you are doing. Keep working; do not mention this reminder.',
+    ...phases.flatMap((phase) => phase.tasks.map((task) => `- [${task.status}] ${task.content}`)),
+    '</system-reminder>',
+  ].join('\n');
+}
+
+function activeGoal(sessionId) {
+  try {
+    const goal = readStoredGoalSnapshot({ dataDir: resolvePluginData(), sessionId });
+    return goal?.status === 'active' ? goal : null;
+  } catch {
+    return null;
+  }
+}
+
+function openItemsReminder(open, count) {
+  return [
+    '<system-reminder>',
+    `You ended the turn with ${open.length} open todo item(s):`,
+    ...open.map((task) => `- ${task.content}`),
+    'Continue them, or close each with the todo tool (done, drop, or block with its reason).',
+    `(Reminder ${count}/${MAX_TODO_REMINDERS})`,
+    '</system-reminder>',
+  ].join('\n');
+}
+
+const GOAL_AUDIT_REMINDER = [
+  '<system-reminder>',
+  'Every todo item is closed but the Goal is still active. Audit each user condition of the Goal objective against current evidence: when all are proven met, call goal with action complete; otherwise append the remaining work to todo and continue.',
+  '</system-reminder>',
+].join('\n');
+
+/** The reminder to send before the turn may end, or null to let it end. */
+export function todoCompletionReminder(session, { sessionId = null, sessionAgent = null, turnLimited = false } = {}) {
+  if (!session || typeof session !== 'object' || turnLimited) return null;
+  if (HIDDEN_AGENT_NAMES.has(sessionAgent)) return null;
+  const id = String(sessionId || session.id || '');
+  const phases = todoPhases(session);
+  if (!phases.length) return null;
+  const check = checkState(session);
+  if (check.awaitingProgress || userWaits.has(id)) return null;
+  const open = openTodoItems(session);
+  if (open.length) {
+    if (check.reminders >= MAX_TODO_REMINDERS) return null;
+    if (awaitingBackgroundWork({ sessionId: id })) return null;
+    check.reminders += 1;
+    check.awaitingProgress = true;
+    return openItemsReminder(open, check.reminders);
+  }
+  if (check.auditAsked || !id || !activeGoal(id)) return null;
+  if (awaitingBackgroundWork({ sessionId: id })) return null;
+  check.auditAsked = true;
+  check.awaitingProgress = true;
+  return GOAL_AUDIT_REMINDER;
+}