mixdog 1.3.5 → 1.4.1

package/src/runtime/shared/connector-triggers.mjs

@@ -1,30 +1,33 @@
 // Curated selection triggers for catalog connectors (MCP servers). A catalog
 // entry carries its line as `trigger`; the deferred-tool manifest lists each
 // connected server once as `- mcp__<server id>: <trigger>`, so one line must
-// say what the connector is for (plus a close negative where useful), in
-// English, at most CONNECTOR_TRIGGER_MAX_CHARS characters.
+// say WHEN to call the server (the user requests it covers, plus a close
+// negative where useful), not list its capabilities; plain ASCII English, at
+// most CONNECTOR_TRIGGER_MAX_CHARS characters.
 export const CONNECTOR_TRIGGER_MAX_CHARS = 100;
 
 export const CONNECTOR_TRIGGERS = Object.freeze({
   // Not a catalog connector (Mixdog uses the signed-in GitHub CLI), but a
   // user-added `github` MCP server still gets this line.
-  github: 'GitHub repos, issues, pull requests, Actions and code search; not local Git history or diffs.',
-  notion: 'Notion pages, databases and workspace search; create or update team docs and notes.',
-  linear: 'Linear issues, projects, cycles and comments; create, triage or update tickets.',
-  sentry: 'Sentry issues, events, stack traces and releases; triage production errors.',
-  gmail: 'Gmail: send email; with an app password also search, read, archive, label, star, trash.',
-  'google-calendar': 'Google Calendar events on the primary calendar; list, search, create, update or delete.',
-  'google-drive': 'Google Drive files Mixdog created or was given; search, read or create; not local files.',
-  jira: 'Jira issues, projects, sprints and comments; JQL search, create or transition tickets.',
-  confluence: 'Confluence spaces and pages; search, read or edit the team wiki; not Jira tickets.',
-  dropbox: 'Dropbox files and folders; search, read, upload or share cloud files; not local files.',
-  trello: 'Trello boards, lists and cards; create, move or update cards.',
-  airtable: 'Airtable bases, tables and records; query, create or update rows.',
-  stripe: 'Stripe customers, payments, invoices, subscriptions and refunds; billing data and actions.',
-  vercel: 'Vercel projects, deployments, domains and logs; deploy status and build errors.',
-  supabase: 'Supabase projects: Postgres tables and SQL, auth, storage and edge functions.',
-  postgres: 'PostgreSQL schemas, tables and SQL queries on a connected database; not local files.',
-  'hugging-face': 'Hugging Face Hub models, datasets, Spaces and papers; not local GGUF model setup.',
+  github: 'GitHub issues, pull requests, Actions runs and repo code search; not local Git history.',
+  notion: 'Finding, reading or updating Notion pages, databases and team notes.',
+  linear: 'Looking up, creating or triaging Linear issues, projects and cycles.',
+  sentry: 'Investigating production errors, stack traces and releases in Sentry.',
+  // The line never names an account: that arrives with the server's
+  // instructions when its tools are loaded.
+  gmail: 'Gmail email: sending, reading, searching or organizing mail.',
+  'google-calendar': 'Google Calendar: checking, creating or editing events.',
+  'google-drive': 'Google Drive: finding, reading or creating files Mixdog made or was given; not local files.',
+  jira: 'Looking up, creating or transitioning Jira tickets, sprints and JQL searches.',
+  confluence: 'Searching, reading or editing Confluence wiki pages; not Jira tickets.',
+  dropbox: 'Finding, reading, uploading or sharing Dropbox files; not local files.',
+  trello: 'Viewing, creating or moving Trello boards, lists and cards.',
+  airtable: 'Querying or updating Airtable bases, tables and records.',
+  stripe: 'Checking or acting on Stripe payments, invoices, subscriptions and refunds.',
+  vercel: 'Checking Vercel deployments, domains, logs and build errors.',
+  supabase: 'Working with Supabase Postgres tables, SQL, auth, storage or edge functions.',
+  postgres: 'Running SQL or inspecting schemas on a connected PostgreSQL database; not local files.',
+  'hugging-face': 'Finding Hugging Face Hub models, datasets, Spaces or papers; not local GGUF setup.',
 });
 
 // Server ids differ only in separators and case (google_calendar, huggingface).

package/src/runtime/shared/defaults-separation.mjs

@@ -40,13 +40,12 @@ const AGENT_SECTION_DEFAULTS = Object.freeze({
 const MODULE_DEFAULTS = Object.freeze({ enabled: true });
 
 export const CHANNELS_DEFAULTS = Object.freeze({
-  access: Object.freeze({ dmPolicy: 'allowlist', allowFrom: [], channels: {} }),
   webhook: Object.freeze({ enabled: true, port: 3333 }),
 });
 
 // Disabled-agent roster shipped before `advisor` joined the defaults
 // (worker … writer plus the Maintainer). Stored full lists are read against it.
-export const PREVIOUS_DISABLED_AGENT_ROSTER = Object.freeze([
+const PREVIOUS_DISABLED_AGENT_ROSTER = Object.freeze([
   'front-worker',
   'heavy-worker',
   'maintainer',
@@ -168,17 +167,6 @@ function removeLegacyKeys(root, dataDir) {
     if (isPlainObject(agent.agents)) agent.agents = withoutRetiredAgentRoutes(agent.agents, dataDir);
     next.agent = agent;
   }
-  const channelEntries = next.channels?.access?.channels;
-  if (isPlainObject(channelEntries)) {
-    const channels = Object.fromEntries(
-      Object.entries(channelEntries).map(([id, entry]) => {
-        if (!isPlainObject(entry)) return [id, entry];
-        const { requireMention: _retired, ...rest } = entry;
-        return [id, rest];
-      })
-    );
-    next.channels = { ...next.channels, access: { ...next.channels.access, channels } };
-  }
   return next;
 }
 
@@ -188,10 +176,7 @@ function removeLegacyKeys(root, dataDir) {
  * not set the marker. `stripRouteDefaults` drops shipped presets and
  * maintenance routes (their defaults live with the agent config).
  */
-export function separateDefaultsInConfig(
-  root,
-  { stripRouteDefaults = (agent) => agent, dataDir = resolvePluginData() } = {}
-) {
+function separateDefaultsInConfig(root, { stripRouteDefaults = (agent) => agent, dataDir = resolvePluginData() } = {}) {
   const from = Number(root?.[DEFAULTS_VERSION_KEY]) || 0;
   let next = { ...(root || {}) };
   if (from < 1) {

package/src/runtime/shared/delegated-approval-host.mjs

@@ -6,14 +6,86 @@
 // owner, and the copy is withdrawn as soon as the owner settles (answered in
 // either place, timed out, its turn ended). Like held-request-host.mjs this
 // registry is process-wide and dependency-free.
+// Hand-offs take the same path: a session chats handed work to (`session`
+// send / create from a bot conversation, agent-task-sessions.mjs) shows its
+// own approvals in EVERY chat whose hand-off to it still owes its report, one
+// copy per chat, all settling the one request. The report watch store
+// (session-runtime/agent-home-delivery.mjs) notes and ends hand-offs as its
+// watches come and go, whatever removes them; a chat
+// whose last hand-off to the session ends loses its copy, the others keep
+// theirs.
 
 const KEY = Symbol.for('mixdog.delegatedApprovalHost.v1');
 
 function registry() {
-  globalThis[KEY] ??= { queues: new Set(), pending: new Map(), opener: null };
+  globalThis[KEY] ??= { queues: new Set(), pending: new Map(), opener: null, handoffs: new Map(), ended: new Set() };
   return globalThis[KEY];
 }
 
+/** The chats with a live hand-off to `sessionId`, each once (in noting order)
+ *  with the name its latest hand-off gave the session: Map chat → `{ title }`. */
+export function handoffChatsOf(sessionId) {
+  const chats = new Map();
+  for (const handoff of registry().handoffs.values()) {
+    if (handoff.sessionId !== sessionId) continue;
+    chats.delete(handoff.surfaceSessionId);
+    chats.set(handoff.surfaceSessionId, { title: handoff.title });
+  }
+  return chats;
+}
+
+/** Bring each pending request of `sessionId` that hand-offs reach to exactly
+ *  the chats now handing it work: a new chat gets its copy, a chat whose
+ *  hand-offs all ended loses only its own. */
+function syncHandoffCopies(sessionId) {
+  const { pending } = registry();
+  const chats = handoffChatsOf(sessionId);
+  for (const asked of pending.values()) {
+    if (!asked.copies || asked.sessionId !== sessionId) continue;
+    for (const [chat, copy] of asked.copies) {
+      if (chats.has(chat)) continue;
+      asked.copies.delete(chat);
+      for (const queue of liveQueuesOf(chat)) queue.withdraw(copy.id, null);
+    }
+    for (const [chat, handoff] of chats) {
+      if (asked.copies.has(chat)) continue;
+      const copy = { id: asked.id, sessionId: chat, request: asked.copyFor(chat, handoff), answer: asked.answer };
+      asked.copies.set(chat, copy);
+      deliver(copy, () => pending.get(asked.id) === asked && asked.copies.get(chat) === copy);
+    }
+  }
+}
+
+// Run ids of hand-offs that ended: never noted again (a watch read before it
+// was removed must not bring it back, however many hand-offs ended since).
+// Run ids are never reused, so an ended id is final for the life of the
+// process and there is nothing to age out: no count decides what is
+// forgotten. One id string is kept per ended hand-off.
+
+/** Chat `homeSessionId` handed session `taskSessionId` work (`title`: the
+ *  target's name in that chat) under report watch `runId`. */
+export function noteHandoff({ runId, taskSessionId, homeSessionId, title }) {
+  if (!runId || !taskSessionId || !homeSessionId || taskSessionId === homeSessionId) return;
+  if (registry().ended.has(String(runId))) return;
+  registry().handoffs.set(String(runId), {
+    sessionId: String(taskSessionId),
+    surfaceSessionId: String(homeSessionId),
+    title: String(title || ''),
+  });
+  syncHandoffCopies(String(taskSessionId));
+}
+
+/** The report watch `runId` is gone (its work reported back, was never
+ *  taken, or the watch was retired): its hand-off ends for good. */
+export function endHandoff(runId) {
+  const { handoffs, ended } = registry();
+  ended.add(String(runId));
+  const handoff = handoffs.get(String(runId));
+  if (!handoff) return;
+  handoffs.delete(String(runId));
+  syncHandoffCopies(handoff.sessionId);
+}
+
 /** `queue`: `{ sessionId() → string, disposed() → boolean, offer(delegated),
  *  withdraw(id, result) }` — one session runtime's approval queue. */
 export function registerApprovalQueue(queue) {
@@ -46,20 +118,36 @@ function offerTo(sessionId, delegated) {
   return live.length > 0;
 }
 
-/** Show `delegated` (`{ id, sessionId, request, answer(...finishArgs) → boolean }`,
- *  `sessionId` being the top-level conversation) there, now or once it loads. */
-export function delegateApproval(delegated) {
-  const { pending, opener } = registry();
-  pending.set(delegated.id, delegated);
-  if (offerTo(delegated.sessionId, delegated) || typeof opener !== 'function') return;
+/** Offer `copy` in its chat now, or once that chat loads while `current()`
+ *  still holds. */
+function deliver(copy, current) {
+  const { opener } = registry();
+  if (offerTo(copy.sessionId, copy) || typeof opener !== 'function') return;
   void Promise.resolve()
-    .then(() => opener(delegated.sessionId))
+    .then(() => opener(copy.sessionId))
     .then(() => {
-      if (pending.get(delegated.id) === delegated) offerTo(delegated.sessionId, delegated);
+      if (current()) offerTo(copy.sessionId, copy);
     })
     .catch(() => {});
 }
 
+/** Show `delegated` (`{ id, sessionId, request, answer(...finishArgs) → boolean }`,
+ *  `sessionId` being the top-level conversation) there, now or once it loads. */
+export function delegateApproval(delegated) {
+  const { pending } = registry();
+  pending.set(delegated.id, delegated);
+  deliver(delegated, () => pending.get(delegated.id) === delegated);
+}
+
+/** A top-level session's request (`{ id, sessionId, request, answer }`,
+ *  `sessionId` being the asking session) that every chat handing it work
+ *  shows too, now and while it waits: `copyFor(chat, { title })` is the
+ *  request as that chat shows it. */
+export function delegateToHandoffs(asked) {
+  registry().pending.set(asked.id, { ...asked, copies: new Map() });
+  syncHandoffCopies(asked.sessionId);
+}
+
 /** The owner settled `id`: every copy goes away. `result` (`{ approved, device }`)
  *  lets the copy say who answered. */
 export function withdrawDelegatedApproval(id, result = null) {
@@ -68,7 +156,11 @@ export function withdrawDelegatedApproval(id, result = null) {
   for (const queue of queues) queue.withdraw(id, result);
 }
 
-/** The pending delegated approvals a top-level session should show. */
+/** The pending delegated approvals (and hand-off copies) a top-level session
+ *  should show. */
 export function delegatedApprovalsFor(sessionId) {
-  return [...registry().pending.values()].filter((delegated) => delegated.sessionId === sessionId);
+  return [...registry().pending.values()].flatMap((delegated) => {
+    if (delegated.copies) return delegated.copies.has(sessionId) ? [delegated.copies.get(sessionId)] : [];
+    return delegated.sessionId === sessionId ? [delegated] : [];
+  });
 }

package/src/runtime/shared/err-text.mjs

@@ -206,24 +206,25 @@ function hasTypedEvidence(error) {
   );
 }
 
-// The window a provider timeout names (providerTimeoutError's message), or 0.
-const timedOutMs = (text) => Number(/timed out after (\d+)ms/i.exec(text)?.[1]) || 0;
+// The window a provider timeout names (providerTimeoutError's message, or a
+// first-byte watchdog's "within Nms"), or 0.
+const timedOutMs = (text) => Number(/(?:timed out after|within) (\d+)ms/i.exec(text)?.[1]) || 0;
 
 // A provider timeout before the model produced anything (isFirstByteTimeout):
-// the model is slow, not the connection.
-function stillThinkingText(error, text) {
+// the model is slow, not the connection. The provider name comes from the
+// caller's own provider config, never from the error.
+function stillThinkingText(error, text, providerLabel) {
   const ms = Number(error.waitedMs) || timedOutMs(text);
-  const provider =
-    typeof error.providerLabel === 'string' && error.providerLabel ? error.providerLabel : 'the provider';
+  const provider = typeof providerLabel === 'string' && providerLabel ? providerLabel : 'the provider';
   const attempts = Number(error.attempts) > 0 ? `; attempts: ${Math.floor(Number(error.attempts))}` : '';
   return `Model still thinking: no output in ${formatDurationMs(ms)}; ${provider} sent nothing yet${attempts}.`;
 }
 
 // Stamped provider timeout phases and stream cuts. Null when the error names
 // neither, so the text rules below decide.
-function typedStreamFailureText(error, text) {
+function typedStreamFailureText(error, text, providerLabel) {
   if (!error || typeof error !== 'object') return null;
-  if (isFirstByteTimeout(error)) return stillThinkingText(error, text);
+  if (isFirstByteTimeout(error)) return stillThinkingText(error, text, providerLabel);
   if (error.timeoutPhase === TIMEOUT_PHASE.IDLE) {
     const ms = timedOutMs(text);
     return ms > 0 ? `No progress ${formatDurationMs(ms)}.` : 'No progress.';
@@ -267,7 +268,7 @@ export function presentErrorText(error, options = {}) {
   if (embeddedError) text = embeddedError;
   text = oneLine(stripErrorPrefix(text));
   if (!text) return 'Unknown error';
-  const streamFailure = typedStreamFailureText(error, text);
+  const streamFailure = typedStreamFailureText(error, text, options.providerLabel);
   if (streamFailure) return streamFailure;
 
   if (code === 'PROVIDER_PREFIX_MUTATION' || name === 'ProviderPrefixMutationError') {
@@ -369,12 +370,20 @@ export function presentErrorText(error, options = {}) {
   return capText(safeErrorDetails(text) || 'Unknown error', max);
 }
 
-/** Why a provider request is being retried, as one short status phrase. */
-export function retryReasonText(error, options = {}) {
-  return presentErrorText(error, {
-    surface: options.surface || 'request',
-    max: options.max ?? 120,
-  }).replace(/\.$/, '');
+/**
+ * Our own wording for a typed timeout retry (`first_response_timeout` /
+ * `stalled`), built only from the error's stamps and the window in its
+ * message; null for any other class. No error text is ever echoed.
+ */
+export function retryTimeoutText(error, reasonClass, providerLabel = null) {
+  const text = String(error?.message ?? '');
+  const ms = timedOutMs(text);
+  if (reasonClass === 'first_response_timeout') {
+    if (isFirstByteTimeout(error)) return stillThinkingText(error, text, providerLabel).replace(/\.$/, '');
+    return ms > 0 ? `No first response ${formatDurationMs(ms)}` : 'No first response';
+  }
+  if (reasonClass === 'stalled') return ms > 0 ? `No progress ${formatDurationMs(ms)}` : 'No progress';
+  return null;
 }
 
 /** The one retry status line every surface shows: `reason · retry n/max in 15s`. */

package/src/runtime/shared/fetch-safe-listen.d.mts

@@ -0,0 +1,16 @@
+import type { Server } from 'node:net';
+
+export const FETCH_BLOCKED_PORTS: ReadonlySet<number>;
+
+export const FETCH_SAFE_ATTEMPTS: number;
+
+export function listenOnFetchSafePort(
+  server: Server,
+  host: string,
+  onListening: () => void,
+  options?: {
+    attempts?: number;
+    isCurrent?: () => boolean;
+    portOf?: (server: Server) => number;
+  }
+): void;

package/src/runtime/shared/fetch-safe-listen.mjs

@@ -0,0 +1,50 @@
+// Ports the WHATWG Fetch spec blocks ("bad port"): fetch (undici) and Chromium
+// refuse to connect to them, so a loopback server that a fetch client or a
+// browser context must reach cannot live on one. https://fetch.spec.whatwg.org/#port-blocking
+export const FETCH_BLOCKED_PORTS = new Set([
+  0, 1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95, 101, 102, 103, 104, 109, 110,
+  111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179, 389, 427, 465, 512, 513, 514, 515, 526, 530, 531, 532,
+  540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993, 995, 1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061,
+  6000, 6566, 6665, 6666, 6667, 6668, 6669, 6679, 6697, 10080,
+]);
+
+/** How many more OS-assigned ports a listener takes after a blocked one. */
+export const FETCH_SAFE_ATTEMPTS = 16;
+
+const assignedPort = (server) => {
+  const address = server.address();
+  return address && typeof address === 'object' ? address.port : 0;
+};
+
+/**
+ * `server.listen(0, host)` that never settles on a fetch-blocked port: when the
+ * OS assigns one, the server is closed and listened again, at most `attempts`
+ * more times. `onListening` runs once, on a safe port. When the attempts run
+ * out the server is closed and an 'error' is emitted, like a failed listen.
+ * `isCurrent` lets a caller that stopped the server meanwhile cancel the retry;
+ * `portOf` reads the assigned port.
+ */
+export function listenOnFetchSafePort(
+  server,
+  host,
+  onListening,
+  { attempts = FETCH_SAFE_ATTEMPTS, isCurrent = () => true, portOf = assignedPort } = {}
+) {
+  let retries = attempts;
+  const attempt = () => {
+    server.listen(0, host, () => {
+      if (!FETCH_BLOCKED_PORTS.has(portOf(server))) {
+        onListening();
+        return;
+      }
+      const exhausted = retries <= 0;
+      retries -= 1;
+      server.close(() => {
+        if (!isCurrent()) return;
+        if (exhausted) server.emit('error', new Error('no fetch-safe loopback port was assigned'));
+        else attempt();
+      });
+    });
+  };
+  attempt();
+}

package/src/runtime/shared/file-permissions.d.mts

@@ -3,14 +3,6 @@ export function enforceOwnerOnlyAclWin32(targetPath: string, options?: { fresh?:
 /** Test hook: the live per-process ACL helper, or null. */
 export function ownerOnlyAclHelperForTests(): import('node:child_process').ChildProcess | null;
 
-/** Test/diagnostic hook: helper attachment, pending requests, starts in the restart window. */
-export function ownerOnlyAclHelperStats(): {
-  alive: boolean;
-  pid: number | null;
-  pending: number;
-  recentStarts: number;
-};
-
 /** Non-fresh calls verify (and tighten) the real DACL on every call through a shared helper. */
 export function enforceOwnerOnlyAclWin32Async(targetPath: string, options?: { fresh?: boolean }): Promise<void>;
 

package/src/runtime/shared/file-permissions.mjs

@@ -267,17 +267,6 @@ export async function prewarmOwnerOnlyAclWin32({ bridge = true } = {}) {
   }
 }
 
-/** Test/diagnostic hook: whether a helper is attached, its requests awaiting
- *  an answer, and the starts inside the current restart window. */
-export function ownerOnlyAclHelperStats() {
-  return {
-    alive: aclHelper !== null,
-    pid: aclHelper?.child.pid ?? null,
-    pending: aclHelper?.pending.size ?? 0,
-    recentStarts: aclHelperStartTimes.length,
-  };
-}
-
 /** Test hook: the live helper process, or null. */
 export function ownerOnlyAclHelperForTests() {
   return aclHelper?.child ?? null;

package/src/runtime/shared/git-direct.test-support.mjs

@@ -0,0 +1,19 @@
+// Side-effect import for the git-heavy suites. Import it before anything that
+// spawns git or snapshots process.env.
+//
+// On Windows `git` on PATH is usually Git for Windows' cmd\git.exe launcher,
+// which starts the real git.exe as a second process, so every spawn pays two
+// process creations (~75 ms instead of ~40 ms). These suites spawn hundreds of
+// git processes, test and code under test alike (the git runner worker shares
+// process.env), so the real binary's directory (`git --exec-path`, where git
+// itself resolves its subcommands) goes first on PATH. Same git, same config;
+// only the launcher hop is skipped. Elsewhere `git` already is the binary.
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { delimiter, join, normalize } from 'node:path';
+
+if (process.platform === 'win32') {
+  const probe = spawnSync('git', ['--exec-path'], { encoding: 'utf8', windowsHide: true });
+  const dir = probe.status === 0 ? normalize(probe.stdout.trim()) : '';
+  if (dir && existsSync(join(dir, 'git.exe'))) process.env.PATH = `${dir}${delimiter}${process.env.PATH}`;
+}

package/src/runtime/shared/handoff-artifacts.d.mts

@@ -8,7 +8,8 @@ export interface HandoffFile {
   id?: string;
 }
 export function normalizeHandoffFiles(files: unknown): HandoffFile[];
-export function artifactLines(files: unknown, omitted?: number, options?: { ids?: boolean }): string[];
+export function artifactLines(files: unknown, omitted?: number): string[];
+export function producedFileLines(files: unknown, omitted?: number): string[];
 export interface HandoffRecord {
   id: string;
   attachmentRef: string;

package/src/runtime/shared/handoff-artifacts.mjs

@@ -31,20 +31,30 @@ export function normalizeHandoffFiles(files) {
     }));
 }
 
-/** The model-facing list of `files`, empty when there are none. `ids`: the
- *  row also records the stored files as its attachments (a task report), so
- *  their ids can be forwarded; a plain-text handoff (an agent completion)
- *  lists paths only — an id named in text is never trusted. */
-export function artifactLines(files, omitted = 0, { ids = true } = {}) {
+/** An agent completion's compact list of files it produced (name and path
+ *  only; the Lead forwards or links by path), empty when there are none. */
+export function producedFileLines(files, omitted = 0) {
   const list = normalizeHandoffFiles(files);
   if (!list.length) return [];
-  const attachable = (file) => (ids ? ` [attachment:${file.id}]` : ' (attachable: forward it by path)');
   return [
-    `Files from this turn (forward one with attachments: [${ids ? 'id or path' : 'path'}]; link a path to show it):`,
+    'Files produced:',
+    ...list.map((file) => `- ${oneLine(file.name)} — ${oneLine(file.path)}`),
+    ...(omitted > 0 ? [`- …and ${omitted} more`] : []),
+  ];
+}
+
+/** The model-facing list of a bot task report's `files`, empty when there are
+ *  none; the row also records the stored files as its attachments, so their
+ *  ids can be forwarded. */
+export function artifactLines(files, omitted = 0) {
+  const list = normalizeHandoffFiles(files);
+  if (!list.length) return [];
+  return [
+    'Files from this turn (forward one with attachments: [id or path]; link a path to show it):',
     ...list.map(
       (file) =>
         `- ${oneLine(file.name)} (${oneLine(file.mimeType)}, ${sizeLabel(file.size)}) — ${oneLine(file.path)}${
-          file.id ? attachable(file) : ' (too large or unsupported to attach; link the path)'
+          file.id ? ` [attachment:${file.id}]` : ' (too large or unsupported to attach; link the path)'
         }`
     ),
     ...(omitted > 0 ? [`- …and ${omitted} more file(s)`] : []),

package/src/runtime/shared/heartbeat-interval.d.mts

@@ -0,0 +1,4 @@
+export const HEARTBEAT_INTERVAL_CHOICES: readonly number[];
+export const DEFAULT_HEARTBEAT_INTERVAL_MINUTES: number;
+export function normalizeHeartbeatIntervalMinutes(value: unknown): number;
+export function requireHeartbeatIntervalMinutes(value: unknown): number;

package/src/runtime/shared/heartbeat-interval.mjs

@@ -0,0 +1,19 @@
+// Mixy's heartbeat interval setting (`heartbeatIntervalMinutes` in the config):
+// one of a few fixed choices, shared by the runtime, the desktop's IPC check
+// and the Settings picker. "Off" is the separate `heartbeat` switch.
+export const HEARTBEAT_INTERVAL_CHOICES = Object.freeze([30, 60, 120, 240]);
+export const DEFAULT_HEARTBEAT_INTERVAL_MINUTES = 60;
+
+/** `value` when it is one of the choices, else the default (a stored value
+ *  that is no longer, or never was, a choice reads as the default). */
+export function normalizeHeartbeatIntervalMinutes(value) {
+  return HEARTBEAT_INTERVAL_CHOICES.includes(value) ? value : DEFAULT_HEARTBEAT_INTERVAL_MINUTES;
+}
+
+/** `value` when it is one of the choices; throws otherwise (a write). */
+export function requireHeartbeatIntervalMinutes(value) {
+  if (!HEARTBEAT_INTERVAL_CHOICES.includes(value)) {
+    throw new Error(`heartbeat interval must be one of ${HEARTBEAT_INTERVAL_CHOICES.join(', ')} minutes`);
+  }
+  return value;
+}

package/src/runtime/shared/idle-auto-clear-gate.mjs

@@ -0,0 +1,126 @@
+// idle-auto-clear-gate.mjs — the idle auto-clear predicate, shared by the
+// submit gate (tui/session/session-flow/auto-clear.mjs); the cache warmer
+// (agent/orchestrator/session/cache-warm.mjs) registers its successful warms,
+// which count as cache use (sessionActivityTimestamp). A thread is cleared before
+// a submit when auto-clear is on, it has been idle for at least the window
+// since its activity timestamp, and its context is not below the minimum
+// share of the compaction trigger.
+import { attachmentTextForPart, isAttachmentReference } from '../attachments/store.mjs';
+
+export function promptContentText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === 'string') return part;
+        if (part?.type === 'text') return isAttachmentReference(part) ? attachmentTextForPart(part) : part.text || '';
+        if (part?.type === 'image') return '[Image]';
+        if (part?.type === 'file') return '[File]';
+        return part?.text || '';
+      })
+      .filter(Boolean)
+      .join('\n');
+  }
+  return String(content ?? '');
+}
+
+function timestampMs(value) {
+  if (value == null || value === '') return 0;
+  const n = Number(value);
+  if (Number.isFinite(n) && n > 0) return n;
+  const parsed = Date.parse(String(value));
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+function hasModelVisibleConversation(session) {
+  const messages = Array.isArray(session?.messages) ? session.messages : [];
+  return messages.some((message) => {
+    const role = message?.role;
+    if (role !== 'user' && role !== 'assistant' && role !== 'tool') return false;
+    const text = promptContentText(message.content).trim();
+    if (role === 'user' && text.startsWith('<system-reminder>')) return false;
+    if (role === 'assistant' && text === '.' && !Array.isArray(message.toolCalls)) return false;
+    return !!text || role === 'assistant' || role === 'tool';
+  });
+}
+
+// A session's last successful cache-warm use (a read with no write),
+// registered by the warmer (cache-warm.mjs, from its durable touch store):
+// `{ at, provider, model, accountId }` — when, and the route and account whose
+// cached prefix it read — or a bare epoch-ms time; null/0 when none.
+let lastCacheWarmUse = () => null;
+
+/** Register the source of a session's last successful cache-warm use
+ *  (`(sessionId) => { at, provider, model, accountId } | epoch ms | null`);
+ *  null restores none. */
+export function setCacheWarmUseSource(source) {
+  lastCacheWarmUse = typeof source === 'function' ? source : () => null;
+}
+
+/** When a successful cache warm last used the session's prompt cache (epoch
+ *  ms), or 0: the warm read and refreshed the cached prefix without moving
+ *  any of the session's own timestamps. */
+export function lastCacheWarmUseAt(sessionId) {
+  const use = sessionId ? lastCacheWarmUse(sessionId) : null;
+  return timestampMs(use && typeof use === 'object' ? use.at : use);
+}
+
+/** When a successful cache warm last used the prefix a request on `provider`
+ *  / `model` / `accountId` reads (epoch ms), or 0: a warm on another route or
+ *  account refreshed an entry this request cannot read, and a use without a
+ *  recorded identity matches nothing. */
+export function cacheWarmUseFor(sessionId, { provider, model, accountId = '' } = {}) {
+  const use = sessionId ? lastCacheWarmUse(sessionId) : null;
+  if (!use || typeof use !== 'object' || !use.provider) return 0;
+  const matches =
+    use.provider === provider && use.model === model && String(use.accountId || '') === String(accountId || '');
+  return matches ? timestampMs(use.at) : 0;
+}
+
+/**
+ * When the session was last active (0: no model-visible conversation): the
+ * latest of its own activity and the last successful cache warm. Idleness is
+ * measured from the last time the cached prompt was actually used, and a warm
+ * that read the cache without writing used it; the session's own timestamps
+ * are never moved.
+ */
+export function sessionActivityTimestamp(session, fallback = 0) {
+  if (!hasModelVisibleConversation(session)) return 0;
+  const own = timestampMs(session?.lastUsedAt) || timestampMs(session?.updatedAt) || timestampMs(fallback);
+  return Math.max(own, lastCacheWarmUseAt(session?.id));
+}
+
+// A zero is often an unavailable/stale meter field, not an authoritative
+// measurement. Do not let it mask the sibling live estimate.
+function contextUsageBelowThreshold(runtime, minContextPercent) {
+  if (!(minContextPercent > 0)) return false;
+  const status = runtime.contextStatus?.() || null;
+  const usedTokens = Math.max(
+    0,
+    Number(status?.usedTokens) || 0,
+    Number(status?.currentEstimatedTokens) || 0,
+    Number(status?.compaction?.currentEstimatedTokens) || 0
+  );
+  const triggerTokens = Number(
+    status?.compaction?.triggerTokens ||
+      status?.compaction?.autoCompactTokenLimit ||
+      runtime.session?.autoCompactTokenLimit ||
+      0
+  );
+  if (!Number.isFinite(usedTokens) || !Number.isFinite(triggerTokens) || !(usedTokens > 0 && triggerTokens > 0)) {
+    return true;
+  }
+  return (usedTokens / triggerTokens) * 100 < minContextPercent;
+}
+
+/**
+ * Whether the idle gate clears the thread before a submit at `at`: `cfg` is
+ * the auto-clear state (`enabled`, `idleMs`, `minContextPercent`), the
+ * activity is `activityAt` (sessionActivityTimestamp) and `runtime` answers
+ * `contextStatus()` for the thread. The submit gate adds its own transient
+ * conditions (busy, queued input, a clear already running).
+ */
+export function idleAutoClearDue({ cfg, activityAt, at, runtime }) {
+  if (!cfg?.enabled || !activityAt || at - activityAt < cfg.idleMs) return false;
+  return !contextUsageBelowThreshold(runtime, Number(cfg.minContextPercent ?? 10));
+}