mixdog 1.3.4 → 1.4.0

package/src/runtime/shared/provider-accounts.mjs

@@ -11,10 +11,11 @@ export const ACCOUNT_PROVIDERS = Object.freeze([
   'command-code-oauth',
   'mimo-oauth',
   'cursor-oauth',
+  'devin-oauth',
   'antigravity-oauth',
   'opencode-go-oauth',
 ]);
-const MAX_ACCOUNTS = 20;
+export const MAX_ACCOUNTS = 20;
 // `dataDir` defaults to this process's data dir; an isolated runtime passes
 // the host's dir explicitly while its own MIXDOG_DATA_DIR points elsewhere.
 const file = (dataDir = resolvePluginData()) => join(dataDir, 'provider-accounts.json');
@@ -95,16 +96,32 @@ export function providerAccountPolicy(pool) {
   return pool?.policy === 'headroom' ? 'headroom' : 'limit';
 }
 
-function normalizePool(pool) {
+// A reading stored before per-model gating is stale: it is dropped on read so
+// it steers nothing until the account is measured again.
+function dropStaleUsage(provider, row) {
+  if (!staleQuotaWindows(provider, row.usage?.windows)) return row;
+  const fresh = { ...row };
+  delete fresh.usage;
+  return fresh;
+}
+
+function normalizePool(provider, pool) {
   if (!pool) return pool;
   const policy = providerAccountPolicy(pool);
-  return { ...normalizeLabels(pool), policy, auto: policy !== 'manual' };
+  const labelled = normalizeLabels(pool);
+  const accounts = labelled.accounts.map((row) => dropStaleUsage(provider, row));
+  return { ...labelled, accounts, policy, auto: policy !== 'manual' };
 }
 
 export function readProviderAccountPool(provider, dataDir = resolvePluginData()) {
   requireAccountProvider(provider);
   return (
-    normalizePool(read(dataDir).providers[provider]) || { accounts: [], selectedId: null, auto: true, policy: 'limit' }
+    normalizePool(provider, read(dataDir).providers[provider]) || {
+      accounts: [],
+      selectedId: null,
+      auto: true,
+      policy: 'limit',
+    }
   );
 }
 
@@ -124,7 +141,7 @@ async function update(provider, mutate) {
     },
     { mode: 0o600, secret: true, fsyncDir: true, backup: true }
   );
-  return normalizePool(result.providers[provider]);
+  return normalizePool(provider, result.providers[provider]);
 }
 
 /**
@@ -256,21 +273,55 @@ export async function recordProviderAccountUsage(provider, id, snapshot) {
     label: String(row.label || '').slice(0, 40),
     usedPct: typeof row.usedPct === 'number' && Number.isFinite(row.usedPct) ? row.usedPct : null,
     resetAt: typeof row.resetAt === 'number' && Number.isFinite(row.resetAt) ? row.resetAt : null,
+    ...windowScopeFields(row),
   }));
   if (!readProviderAccountPool(provider).accounts.some((row) => row.id === id)) return;
   await update(provider, (pool) => {
     const row = pool.accounts.find((entry) => entry.id === id);
     if (!row) return;
     row.usage = { windows, checkedAt: Date.now() };
-    // A fresh observation of available quota releases a prior typed refusal.
-    // Only a MEASURED window can testify: a provider that reports a window
-    // without a percentage says nothing about that meter, and requiring a
-    // number from it kept accounts refused that every real reading had freed.
-    const measured = windows.filter((window) => window.usedPct !== null);
-    if (measured.length && measured.every((window) => window.usedPct < 100)) clearAccountBlock(row);
+    // A fresh observation of available quota releases a prior refusal. Only
+    // the meters the refusal drew on testify (a full Claude/GPT bucket says
+    // nothing about a Gemini refusal), and only a MEASURED window: a provider
+    // that reports a window without a percentage says nothing about that
+    // meter, and requiring a number from it kept accounts refused that every
+    // real reading had freed. Each bucket's block is weighed on its own.
+    const lifted = (block) => {
+      const measured = blockEvidenceWindows(block).filter((window) => window.usedPct !== null);
+      return measured.length > 0 && measured.every((window) => window.usedPct < 100);
+    };
+    setAccountBlocks(
+      row,
+      accountBlocks(row).filter((block) => !lifted(block))
+    );
   });
 }
 
+// The model-id tokens a window's gate names, as recorded: lowercased and bounded.
+function modelTokens(value) {
+  if (!Array.isArray(value)) return null;
+  return value
+    .slice(0, 12)
+    .map((token) =>
+      String(token || '')
+        .trim()
+        .toLowerCase()
+        .slice(0, 80)
+    )
+    .filter(Boolean);
+}
+
+function windowScopeFields(row) {
+  const models = modelTokens(row.models);
+  const except = modelTokens(row.except);
+  const limit = typeof row.limit === 'string' ? row.limit.trim().slice(0, 80) : '';
+  const scope = {};
+  if (models) scope.models = models;
+  else if (except?.length) scope.except = except;
+  if (limit) scope.limit = limit;
+  return scope;
+}
+
 // A refusal window is an AVOIDANCE hint for the roster, not the retry schedule —
 // the request-level retry honours Retry-After on its own. Generous enough to
 // cover a full five-hour burst window, tight enough that a header asking for
@@ -283,18 +334,29 @@ const MAX_BLOCK_MS = 6 * 60 * 60_000;
 // early can tell us anything.
 // `options.quota` records that the block came from a typed quota refusal or an
 // exhausted usage window, so later sends still count it as quota evidence.
+// `options.limit` is the server's id of the limit the refusal named; the block
+// then covers that limit's windows. `options.reset` marks `until` as the
+// quota reset the server named: it is kept as given (a fresh reading showing
+// room still lifts it early), while advice and inferred delays stay capped.
+// A new refusal of the same model replaces that model's block; every other
+// block still running keeps its own deadline, so refusing one bucket never
+// frees another.
 export async function blockProviderAccount(provider, id, until, model = '', source = 'inferred', options = {}) {
   return update(provider, (pool) => {
     const row = pool.accounts.find((entry) => entry.id === id);
     if (!row) return;
-    row.blockedUntil = Math.min(until, Date.now() + MAX_BLOCK_MS);
+    const now = Date.now();
+    const block = { blockedUntil: options.reset === true ? until : Math.min(until, now + MAX_BLOCK_MS) };
     const scope = String(model || '').trim();
-    if (scope) row.blockedModel = scope;
-    else delete row.blockedModel;
-    if (source === 'retry-after') row.blockedSource = source;
-    else delete row.blockedSource;
-    if (options.quota === true) row.blockedQuota = true;
-    else delete row.blockedQuota;
+    if (scope) block.blockedModel = scope;
+    const limit = String(options.limit || '').trim();
+    if (limit) block.blockedLimit = limit;
+    if (source === 'retry-after') block.blockedSource = source;
+    if (options.quota === true) block.blockedQuota = true;
+    const running = accountBlocks(row).filter(
+      (entry) => entry.blockedUntil > now && String(entry.blockedModel || '') !== scope
+    );
+    setAccountBlocks(row, [...running, block]);
   });
 }
 
@@ -312,41 +374,136 @@ export async function clearProviderAccountQuotaState(provider, id) {
   });
 }
 
+const BLOCK_FIELDS = Object.freeze(['blockedUntil', 'blockedModel', 'blockedLimit', 'blockedSource', 'blockedQuota']);
+
 function clearAccountBlock(row) {
-  delete row.blockedUntil;
-  delete row.blockedModel;
-  delete row.blockedSource;
-  delete row.blockedQuota;
+  for (const key of BLOCK_FIELDS) delete row[key];
+  delete row.blockedBuckets;
+}
+
+const blockOf = (source) =>
+  Object.fromEntries(BLOCK_FIELDS.filter((key) => source[key] !== undefined).map((key) => [key, source[key]]));
+
+// Every block the account holds, oldest first, each read beside the account's
+// usage. The row's own fields carry the latest; earlier blocks of other
+// buckets still running sit in `blockedBuckets`.
+function accountBlocks(row) {
+  const blocks = [
+    ...(Array.isArray(row?.blockedBuckets) ? row.blockedBuckets : []),
+    ...(row?.blockedUntil === undefined ? [] : [blockOf(row)]),
+  ];
+  return blocks.map((block) => ({ ...block, usage: row.usage }));
 }
 
-// Single-token weekly labels ("7D Fable", "7D Opus") belong to that Claude
-// family only. A full Fable window must not idle an Opus request. Unscoped
-// 5H/7D meters and multi-word surfaces ("7D OAuth apps") still apply to every
-// model.
+function setAccountBlocks(row, blocks) {
+  clearAccountBlock(row);
+  if (blocks.length) Object.assign(row, blockOf(blocks.at(-1)));
+  if (blocks.length > 1) row.blockedBuckets = blocks.slice(0, -1).map(blockOf);
+  return row;
+}
+
+// The row holding only the blocks `keep` accepts (none by default), so a check
+// can weigh the usage windows, or only the quota refusals, on their own.
+export function providerAccountWithBlocks(row, keep = () => false) {
+  return row && setAccountBlocks({ ...row }, accountBlocks(row).filter(keep));
+}
+
+// Labels every current reading scopes with `models`/`except`. A stored window
+// carrying one of them without a scope predates per-model gating and would
+// read as account-wide, so its whole reading is stale.
+const SCOPED_WINDOW_LABELS = Object.freeze({
+  'anthropic-oauth': ['EXTRA'],
+  'antigravity-oauth': ['7D Argon', '5H Claude/GPT', '7D Claude/GPT'],
+  'cursor-oauth': ['Basic', 'API'],
+});
+
+export function staleQuotaWindows(provider, windows) {
+  const labels = SCOPED_WINDOW_LABELS[provider] || [];
+  return (Array.isArray(windows) ? windows : []).some(
+    (window) =>
+      labels.includes(String(window?.label || '').trim()) &&
+      !Array.isArray(window.models) &&
+      !Array.isArray(window.except)
+  );
+}
+
+// Which models one quota window gates — the single rule every window and every
+// block follows. The usage reading scopes a window to the server's quota
+// bucket: `models` gates only model ids naming one of those tokens (an empty
+// list gates nothing: a display-only meter such as paid extra usage), `except`
+// gates every model but those. A window without either keeps the older label
+// rule: a single-token weekly label ("7D Fable", "7D Opus") belongs to that
+// family only, and every other window (5H/7D, multi-word surfaces such as
+// "7D OAuth apps") gates every model.
 const FAMILY_QUOTA_WINDOW = /^7D\s+([A-Za-z][A-Za-z0-9]*)$/i;
 
+function windowScope(window) {
+  if (Array.isArray(window?.models)) return { models: window.models };
+  if (Array.isArray(window?.except) && window.except.length) return { except: window.except };
+  const family = FAMILY_QUOTA_WINDOW.exec(String(window?.label || '').trim())?.[1];
+  return family ? { models: [family.toLowerCase()] } : null;
+}
+
+const displayOnly = (window) => Array.isArray(window?.models) && window.models.length === 0;
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function namesModel(model, tokens) {
+  const id = String(model).toLowerCase();
+  return tokens.some((token) => new RegExp(`(?:^|[-_/.@])${escapeRegExp(token)}(?:[-_/.@]|$)`).test(id));
+}
+
 export function quotaWindowAppliesToModel(window, model) {
-  const match = FAMILY_QUOTA_WINDOW.exec(String(window?.label || '').trim());
-  if (!match) return true;
-  const family = match[1].toLowerCase();
-  const id = String(model || '').toLowerCase();
-  if (!id) return false;
-  return new RegExp(`(?:^|[-_/.@])${family}(?:[-_/.@]|$)`).test(id);
+  const scope = windowScope(window);
+  if (!scope) return true;
+  if (!model) return false;
+  return scope.models ? namesModel(model, scope.models) : !namesModel(model, scope.except);
+}
+
+// The meters a block stands for: the windows of the limit the refusal named,
+// else the scoped windows that gate the model that earned it.
+function blockWindows(row) {
+  const windows = row?.usage?.windows || [];
+  const limit = String(row?.blockedLimit || '');
+  const named = limit ? windows.filter((window) => window.limit === limit) : [];
+  if (named.length) return named;
+  const earned = String(row?.blockedModel || '').trim();
+  return earned ? windows.filter((window) => windowScope(window) && quotaWindowAppliesToModel(window, earned)) : [];
+}
+
+// The windows a fresh reading must show below 100% to lift a block: the
+// block's own meters plus every meter, scoped or shared, the model that earned
+// it (or, for an account-wide block, any model) draws on.
+function blockEvidenceWindows(row) {
+  const earned = String(row?.blockedModel || '').trim();
+  const gating = (row?.usage?.windows || []).filter((window) =>
+    earned ? quotaWindowAppliesToModel(window, earned) : !displayOnly(window)
+  );
+  return [...new Set([...blockWindows(row), ...gating])];
 }
 
 // A refusal earned by one model must not idle a model that draws on a
-// different meter — the same rule the usage windows already follow. Two models
-// share a block when one scoped window covers both; when the account exposes no
-// scoped meter at all (a plain 5H/7D subscription) the block stays account-wide,
-// because there is no narrower category to attribute it to.
+// different meter — the same rule the usage windows follow. Two models share a
+// block when one of the block's windows gates both; when the account exposes
+// no scoped meter for the model (a plain 5H/7D subscription) the block stays
+// account-wide, because there is no narrower category to attribute it to.
 function blockAppliesToModel(row, model) {
-  const scope = String(row?.blockedModel || '').trim();
-  if (!scope || !model || scope === String(model)) return true;
-  const scoped = (row?.usage?.windows || []).filter((window) =>
-    FAMILY_QUOTA_WINDOW.test(String(window?.label || '').trim())
-  );
-  if (!scoped.length) return true;
-  return scoped.some((window) => quotaWindowAppliesToModel(window, scope) && quotaWindowAppliesToModel(window, model));
+  const earned = String(row?.blockedModel || '').trim();
+  if (!earned || !model || earned === String(model)) return true;
+  const windows = blockWindows(row);
+  if (!windows.length) return true;
+  return windows.some((window) => quotaWindowAppliesToModel(window, model));
+}
+
+// When the blocks holding `model` lift (every block when no model is named):
+// the latest of their deadlines, or null when none holds it. Past deadlines
+// are returned as they are, so a caller compares the result with its clock.
+export function providerAccountBlockedUntil(row, model = '') {
+  const ends = accountBlocks(row)
+    .filter((block) => blockAppliesToModel(block, model))
+    .map((block) => Number(block.blockedUntil))
+    .filter(Number.isFinite);
+  return ends.length ? Math.max(...ends) : null;
 }
 
 // Earliest moment any of the given exhausted accounts can serve `model` again,
@@ -360,8 +517,9 @@ export function providerAccountsResetAt(rows, now = Date.now(), model = '', opti
     if (!providerAccountExhausted(row, now, model, options)) continue;
     const times = [];
     let unknown = false;
-    if (row.blockedUntil > now && blockAppliesToModel(row, model)) {
-      if (row.blockedSource === 'retry-after') times.push(row.blockedUntil);
+    for (const block of accountBlocks(row)) {
+      if (!(block.blockedUntil > now) || !blockAppliesToModel(block, model)) continue;
+      if (block.blockedSource === 'retry-after') times.push(block.blockedUntil);
       else unknown = true;
     }
     if (options.useCredits !== true) {
@@ -381,39 +539,47 @@ function windowFull(row, window, now) {
 }
 
 export function providerAccountExhausted(row, now = Date.now(), model = '', options = {}) {
-  if (row?.blockedUntil > now && blockAppliesToModel(row, model)) return true;
+  if (accountBlocks(row).some((block) => block.blockedUntil > now && blockAppliesToModel(block, model))) return true;
   if (options.useCredits === true) return false;
   return (row?.usage?.windows || []).some(
     (window) => quotaWindowAppliesToModel(window, model) && windowFull(row, window, now)
   );
 }
 
+// The display name of a scoped limit: the family of a legacy "7D Fable" label,
+// else the label without its window prefix ("5H Claude/GPT" → "Claude/GPT").
 function quotaWindowFamily(window) {
-  return FAMILY_QUOTA_WINDOW.exec(String(window?.label || '').trim())?.[1] || '';
+  const label = String(window?.label || '').trim();
+  return FAMILY_QUOTA_WINDOW.exec(label)?.[1] || label.replace(/^(?:5H|7D)\s+/i, '') || label;
 }
 
 // Which limit currently holds the account, independent of any one model:
 // `{ scope: 'account' }` when every request is refused (an unscoped window is
 // full, or a block with no narrower meter to attribute it to), `{ scope:
-// 'model', families }` when only model-family meters ("7D Fable") or a block
-// attributed to one are spent, so other models still run — else null.
+// 'model', families }` when only scoped meters ("7D Fable", "5H Claude/GPT")
+// or a block attributed to one are spent, so other models still run — else null.
 export function providerAccountLimit(row, now = Date.now(), options = {}) {
   if (!row) return null;
   const windows = row.usage?.windows || [];
-  const blocked = row.blockedUntil > now;
-  const scope = String(row.blockedModel || '').trim();
-  const scopedWindows = windows.filter((window) => quotaWindowFamily(window));
-  // A block counts as family-scoped only when a family meter covers the model
-  // that earned it; any other refusal is treated as the account's.
-  const covering = scope ? scopedWindows.filter((window) => quotaWindowAppliesToModel(window, scope)) : [];
-  if (blocked && !covering.length) return { scope: 'account' };
+  // A block counts as scoped only when scoped meters cover it; any other
+  // refusal is treated as the account's.
+  const covering = accountBlocks(row)
+    .filter((block) => block.blockedUntil > now)
+    .map(blockWindows);
+  if (covering.some((meters) => !meters.length || meters.some((window) => !windowScope(window)))) {
+    return { scope: 'account' };
+  }
   const credits = options.useCredits === true;
-  if (!credits && windows.some((window) => !quotaWindowFamily(window) && windowFull(row, window, now))) {
+  if (!credits && windows.some((window) => !windowScope(window) && windowFull(row, window, now))) {
     return { scope: 'account' };
   }
-  const families = new Set(blocked ? covering.map(quotaWindowFamily) : []);
+  const families = new Set(covering.flat().map(quotaWindowFamily));
   if (!credits) {
-    for (const window of scopedWindows) if (windowFull(row, window, now)) families.add(quotaWindowFamily(window));
+    for (const window of windows) {
+      if (windowScope(window) && !displayOnly(window) && windowFull(row, window, now)) {
+        families.add(quotaWindowFamily(window));
+      }
+    }
   }
   return families.size ? { scope: 'model', families: [...families] } : null;
 }
@@ -431,6 +597,12 @@ export function providerAccountExhaustedForModelOnly(row, now = Date.now(), mode
 // enough that yesterday's number cannot send every fallback to one account.
 const USAGE_EVIDENCE_MAX_AGE_MS = 60 * 60_000;
 
+/** Whether a usage reading taken at `checkedAt` may still steer a decision. */
+export function quotaReadingFresh(checkedAt, now = Date.now()) {
+  const at = Number(checkedAt);
+  return at > 0 && now - at <= USAGE_EVIDENCE_MAX_AGE_MS;
+}
+
 // Remaining headroom across every window that applies to this model, or null
 // when nothing recent measured the account. The fullest window decides: an
 // account with 4% of its burst window left cannot serve now, however untouched

package/src/runtime/shared/provider-api-key.mjs

@@ -26,16 +26,27 @@ function providerSecretEnv(provider) {
     .toUpperCase()}_APIKEY`;
 }
 
-function environmentApiKey(provider) {
-  const id = String(provider || '').trim();
+// The environment variable that supplies a provider's key, in the resolver's
+// precedence (standard name, MIXDOG_AGENT_<ID>_APIKEY, then aliases); null when none is set.
+function environmentKeyName(id) {
   const standardEnv = AGENT_PROVIDER_ENV[id];
-  if (standardEnv && process.env[standardEnv]) return process.env[standardEnv];
+  if (standardEnv && process.env[standardEnv]) return standardEnv;
   const mixdogEnv = providerSecretEnv(id);
-  if (process.env[mixdogEnv]) return process.env[mixdogEnv];
-  for (const alias of AGENT_PROVIDER_ENV_ALIASES[id] || []) {
-    if (process.env[alias]) return process.env[alias];
-  }
-  return null;
+  if (process.env[mixdogEnv]) return mixdogEnv;
+  return (AGENT_PROVIDER_ENV_ALIASES[id] || []).find((alias) => process.env[alias]) ?? null;
+}
+
+function environmentApiKey(provider) {
+  const name = environmentKeyName(String(provider || '').trim());
+  return name ? process.env[name] : null;
+}
+
+/** Name of the environment variable getAgentApiKey would return for `provider`
+ *  (it wins over any stored key), or null when the effective key is not an
+ *  environment one. Provenance for the setup views; never the value. */
+export function agentApiKeyEnvName(provider) {
+  if (modelProxyClientMode()) return null;
+  return environmentKeyName(String(provider || '').trim());
 }
 
 /** Presence-only credential probe. On Windows this is a cheap DPAPI-file

package/src/runtime/shared/provider-display-name.mjs

@@ -0,0 +1,29 @@
+// Display names for provider ids; an unknown id displays as itself.
+const PROVIDER_DISPLAY_NAMES = new Map([
+  ['openai-oauth', 'OpenAI OAuth'],
+  ['anthropic-oauth', 'Anthropic OAuth'],
+  ['grok-oauth', 'Grok OAuth'],
+  ['muse-code-oauth', 'Muse Code'],
+  ['command-code-oauth', 'Command Code'],
+  ['mimo-oauth', 'MiMo'],
+  ['cursor-oauth', 'Cursor OAuth'],
+  ['devin-oauth', 'Devin'],
+  ['antigravity-oauth', 'Antigravity OAuth'],
+  ['openai', 'OpenAI API'],
+  ['openai-api', 'OpenAI API'],
+  ['anthropic', 'Anthropic API'],
+  ['anthropic-api', 'Anthropic API'],
+  ['gemini', 'Gemini API'],
+  ['gemini-api', 'Gemini API'],
+  ['xai', 'xAI API'],
+  ['xai-api', 'xAI API'],
+  ['deepseek', 'DeepSeek API'],
+  ['deepseek-api', 'DeepSeek API'],
+  ['opencode-go-oauth', 'OpenCode Go OAuth'],
+  ['openrouter', 'OpenRouter'],
+  ['mixdog-local', 'Local Provider'],
+  ['default', 'Default'],
+]);
+
+export const providerDisplayName = (provider) =>
+  PROVIDER_DISPLAY_NAMES.get(String(provider || '').toLowerCase()) ?? (provider || 'Provider');

package/src/runtime/shared/provider-timeout-phase.mjs

@@ -8,6 +8,8 @@ export const TIMEOUT_PHASE = Object.freeze({
   FIRST_CHUNK: 'first-chunk',
   // A stream that already produced output went silent.
   IDLE: 'idle',
+  // A sign-in token refresh did not answer: an auth problem, not a slow model.
+  AUTH: 'auth',
 });
 
 /** A timeout before the model produced anything: headers or first chunk. */

package/src/runtime/shared/routine-trigger.d.mts

@@ -4,6 +4,8 @@ export interface RoutineTrigger {
   event?: string;
 }
 
+export declare const ROUTINE_QUIET: 'ROUTINE_QUIET';
+export declare function isRoutineQuietReply(text: unknown): boolean;
 export declare function routineTriggerHeader(input: {
   kind: string;
   name: string;

package/src/runtime/shared/routine-trigger.mjs

@@ -9,6 +9,15 @@ import { localTimestampParts } from './time-format.mjs';
 const HEADER_PREFIX = '[Routine trigger]';
 const KINDS = new Set(['schedule', 'webhook']);
 
+/** The whole reply of a routine turn with nothing new to tell: kept in the
+ *  record, never painted, previewed, counted unread or notified. */
+export const ROUTINE_QUIET = 'ROUTINE_QUIET';
+
+/** Whether a reply is exactly the routine quiet sentinel. */
+export function isRoutineQuietReply(text) {
+  return String(text ?? '').trim() === ROUTINE_QUIET;
+}
+
 /** The first line of a routine turn's prompt: which routine fired, when (local
  *  time and zone: the turn gets no other date), and how to treat the turn.
  *  It is the routine's only conduct text. Only the turn's content carries it,
@@ -24,10 +33,53 @@ export function routineTriggerHeader({ kind, name, project = '', now = new Date(
     'Payments and permanent deletes are refused here: report that and suggest doing it from the chat.',
     'If a sign-in, code or CAPTCHA blocks you, stop and say which site needs the user.',
     'Reply in this chat in plain words, without tool names; if you handed work off, say it started — its result arrives here later.',
+    `Tell what is new in a fitting tone; if nothing is worth telling, reply with exactly ${ROUTINE_QUIET}.`,
     ...(project ? [`Project folder: ${project}`] : []),
   ].join(' ');
 }
 
+/** The whole reply of a heartbeat turn that has nothing to tell the user. */
+export const HEARTBEAT_QUIET = 'HEARTBEAT_QUIET';
+/** The routine name a heartbeat turn runs under and its hidden session's source. */
+export const HEARTBEAT_SOURCE = 'heartbeat';
+/** A heartbeat turn's bounds: its tool calls; when it is told to reply with no
+ *  more tools (session/loop/turn-limits.mjs); when it is cut off without a
+ *  reply (session-runtime/routine-home-turn.mjs). */
+export const HEARTBEAT_TURN_LIMITS = Object.freeze({ maxToolCalls: 8, wrapUpMs: 60_000, wallClockMs: 90_000 });
+
+// Mixy's hidden heartbeat sessions (mixy-heartbeat.mjs wakeMixy), marked in
+// this process from creation until their close lands. Only the mark counts:
+// stored fields (source, owner) can be supplied by any session create.
+const heartbeatSessions = new Set();
+
+/** Mark `sessionId` as a heartbeat session; `unmark` ends it. */
+export function markHeartbeatSession(sessionId, unmark = false) {
+  const id = String(sessionId || '');
+  if (unmark) heartbeatSessions.delete(id);
+  else if (id) heartbeatSessions.add(id);
+}
+
+/** Whether `sessionId` is a marked heartbeat session. */
+export function isHeartbeatSession(sessionId) {
+  return heartbeatSessions.has(String(sessionId || ''));
+}
+
+/** The first line of a heartbeat turn (session-runtime/mixy-heartbeat.mjs):
+ *  a system check-in, never the user, and it grants no approval. */
+export function heartbeatTriggerHeader({ now = new Date() } = {}) {
+  const at = localTimestampParts(now);
+  return [
+    `${HEADER_PREFIX} Heartbeat: a system check-in from Mixdog, not a message from the user; it grants no approval.`,
+    ...(at ? [`Local time: ${at.date} ${at.time.slice(0, 5)} ${at.timeZone} (${at.offset}).`] : []),
+    'Nobody is watching this turn and nothing asks for approval: act within your permissions.',
+    'Payments and permanent deletes are refused here.',
+    'Do not start agents, task sessions, session sends, Goals or background commands here: this session closes when the turn ends, so their results would reach nobody; propose them instead.',
+    'Handle the items below as your heartbeat instructions say, finishing in this turn:',
+    'only its final reply is posted in your chat with the user, as your message.',
+    `If nothing is worth telling the user, reply with exactly ${HEARTBEAT_QUIET} and nothing else.`,
+  ].join(' ');
+}
+
 /** `text` without the header line a routine turn opens with. */
 export function stripRoutineTriggerHeader(text) {
   const value = String(text ?? '');

package/src/runtime/shared/sensitive-path-rules.d.mts

@@ -1,15 +1,7 @@
 export interface SensitiveScope {
+  /** A Mixdog home or data folder, as path segments; only its secret subset is denied. */
   root: string[];
-  /** Subfolders of the root that stay reachable. */
-  except: readonly string[];
-  /** Whole tree (a registered private root) or Mixdog's secret subset. */
-  whole: boolean;
 }
-export function sensitivePathSegments(path: string): string[];
-export function matchesSensitivePath(
-  path: string,
-  within?: readonly SensitiveScope[],
-  options?: { envTemplates?: boolean }
-): boolean;
+export function matchesSensitivePath(path: string, within?: readonly SensitiveScope[]): boolean;
 export function mixdogSensitiveScopes(extraData?: readonly string[]): SensitiveScope[];
 export function isSensitiveLocalPath(path: string, options?: { extraData?: readonly string[] }): boolean;