mixdog 0.9.95 → 0.9.97

package/src/runtime/agent/orchestrator/tools/patch/v4a-convert.mjs

@@ -28,6 +28,8 @@ import {
   findLineSequence,
   findLineSequenceEscapeEquiv,
   longestCommonSubstringLen,
+  boundedEditDistance,
+  EDIT_DISTANCE_ALLOWANCE_PER_LINE,
   splitTextLinesForPatch,
   firstMeaningfulPatchLine,
   nearestPatchLineHint,
@@ -162,6 +164,18 @@ function noteV4AHunkAmbiguity(displayPath, sourceLines, loc) {
   );
 }
 
+// `*** End of File` was relaxed to locate this hunk: report where it actually
+// landed so a mid-file hunk that carried the marker by mistake is visible in
+// the same turn instead of silently looking like an end-of-file edit.
+function noteV4AEofSignalIgnored(displayPath, loc) {
+  if (_v4aAmbiguityNotices.size >= V4A_AMBIGUITY_NOTICE_CAP) return;
+  if (!loc?.eofSignalIgnored) return;
+  _v4aAmbiguityNotices.add(
+    `${displayPath}: hunk carried *** End of File but its context is at line ${loc.oldStartIdx + 1}, `
+    + 'not the end of file; the marker was ignored. Drop it unless the hunk really ends the file.',
+  );
+}
+
 export function drainV4AAmbiguityNotices() {
   if (_v4aAmbiguityNotices.size === 0) return [];
   const list = [..._v4aAmbiguityNotices];
@@ -299,14 +313,50 @@ function findContextTolerantWindow(sourceLines, oldLines, oldTags) {
   return windows.length === 1 ? { start: windows[0] } : null;
 }
 
-// Last-resort recovery for a model that accidentally copied 1-2 unrelated
-// unchanged context lines just outside the real edit. Trim only contiguous
-// outer ' ' lines — never '-' or '+' lines — and accept the shortened old
-// block only when it matches byte-exactly at exactly one place in the ENTIRE
-// file. Requiring a deletion keeps this fallback off insertion-only hunks;
-// exact whole-block matching proves every deletion line is current. Any
-// competing trim plan or duplicate occurrence is ambiguous and stays a hard
-// context miss.
+// Bounded edit-distance tier (fuzzy, after the context-tolerance tier).
+// Recovers the block a model retyped from memory with a couple of characters
+// off — a dropped bracket, a mistyped short token — where the tolerance tier
+// refuses because the drift sits on a deletion line. Guards keep it safe:
+//   - TOTAL distance across the block stays within ~0.34 characters per line
+//     (3 lines buy exactly 1 character), measured on trimmed text;
+//   - at least 2 non-blank lines must match byte-exactly as anchors;
+//   - the qualifying window must be UNIQUE across the ENTIRE file;
+//   - the caller REMAPS every old line to the file's on-disk text, so the
+//     emitted hunk stays byte-exact for the applier.
+function findEditDistanceWindow(sourceLines, oldLines) {
+  const n = (oldLines || []).length;
+  const maxDistance = Math.floor(n * EDIT_DISTANCE_ALLOWANCE_PER_LINE);
+  if (n < 3 || maxDistance <= 0) return null;
+  const windows = [];
+  for (let i = 0; i + n <= sourceLines.length && windows.length < 2; i++) {
+    let total = 0;
+    let exact = 0;
+    let ok = true;
+    for (let k = 0; k < n; k++) {
+      const pat = String(oldLines[k] ?? '');
+      const src = String(sourceLines[i + k] ?? '');
+      if (src === pat) {
+        if (pat.trim()) exact++;
+        continue;
+      }
+      total += boundedEditDistance(src.trim(), pat.trim(), maxDistance - total);
+      if (total > maxDistance) { ok = false; break; }
+    }
+    if (ok && total > 0 && exact >= 2) windows.push(i);
+  }
+  return windows.length === 1 ? { start: windows[0] } : null;
+}
+
+// Recovery for outer context the model got wrong — a stray copied line, or a
+// whole surrounding block retyped from memory — around an edit whose deletion
+// lines are current. Trim only contiguous outer ' ' lines — never '-' or '+'
+// lines — smallest trim first, and accept the shortened old block only when it
+// matches byte-exactly at exactly one place in the ENTIRE file. That
+// uniqueness IS the position proof, so the trim budget runs to all available
+// outer context: a byte-exact, file-unique deletion core cannot land anywhere
+// else, whatever the caller wrote around it. Requiring a deletion keeps this
+// off insertion-only hunks (they carry no payload to anchor on), and any
+// competing trim plan or duplicate occurrence stays a hard context miss.
 function findOuterContextTrimmedWindow(sourceLines, hunk, stats) {
   const body = (hunk?.lines || []).filter(
     (line) => typeof line === 'string'
@@ -325,7 +375,8 @@ function findOuterContextTrimmedWindow(sourceLines, hunk, stats) {
   ) trailingAvailable++;
   if (leadingAvailable === 0 && trailingAvailable === 0) return null;
 
-  for (let totalTrimmed = 1; totalTrimmed <= 2; totalTrimmed++) {
+  const maxTrimmed = leadingAvailable + trailingAvailable;
+  for (let totalTrimmed = 1; totalTrimmed <= maxTrimmed; totalTrimmed++) {
     const plans = [];
     let ambiguous = false;
     for (let leading = 0; leading <= Math.min(totalTrimmed, leadingAvailable); leading++) {
@@ -424,7 +475,23 @@ function resolveV4AHunkPosition(sourceLines, hunk, nextSearchLine, options = {})
   // of the patch's real character. On match, remap old/context lines to the
   // file's on-disk form so untouched context stays byte-identical and the
   // escape representation survives the edit.
-  if (oldStartIdx < 0 && fuzzy && !eof && oldLinesPattern.length > 0) {
+  // `*** End of File` is a HINT, not a hard constraint. When the EOF-anchored
+  // seek misses, retry the pattern as an ordinary in-file search: a mid-file
+  // hunk that carried the marker by mistake used to fail with a "context not
+  // found" that pointed at its own byte-perfect context, costing a whole retry
+  // turn. Once that happens the EOF signal is exhausted, so every recovery
+  // tier below treats the hunk as unmarked.
+  let eofSignalIgnored = false;
+  if (oldStartIdx < 0 && eof && oldLinesPattern.length > 0) {
+    const relaxedFrom = Math.max(0, anchorLine - 1);
+    const relaxed = findLineSequence(sourceLines, oldLinesPattern, relaxedFrom, relaxedFrom, { fuzzy, eof: false });
+    if (relaxed >= 0) {
+      oldStartIdx = relaxed;
+      eofSignalIgnored = true;
+    }
+  }
+  if (oldStartIdx < 0 && fuzzy && oldLinesPattern.length > 0) {
+    if (eof) eofSignalIgnored = true;
     const from = Math.max(0, anchorLine - 1);
     const alt = findLineSequenceEscapeEquiv(sourceLines, oldLinesPattern, from, from);
     if (alt >= 0) {
@@ -447,7 +514,7 @@ function resolveV4AHunkPosition(sourceLines, hunk, nextSearchLine, options = {})
   // lines are remapped to the file's actual lines on BOTH the old and new
   // side (same shape as the escape-equiv remap above); remapping bails on any
   // string ambiguity so an unrelated occurrence can never be rewritten.
-  if (oldStartIdx < 0 && fuzzy && !eof && oldLinesPattern.length >= 3) {
+  if (oldStartIdx < 0 && fuzzy && oldLinesPattern.length >= 3) {
     const tolTags = trimmedTrailing ? stats.oldTags.slice(0, -1) : stats.oldTags;
     const tol = findContextTolerantWindow(sourceLines, oldLinesPattern, tolTags);
     if (tol) {
@@ -474,7 +541,7 @@ function resolveV4AHunkPosition(sourceLines, hunk, nextSearchLine, options = {})
   // This fallback is deliberately narrower than the context-tolerance tier:
   // fuzzy mode only, non-EOF, no newline-sentinel interaction, deletion hunks
   // only, byte-exact remaining block, and one unique whole-file location.
-  if (oldStartIdx < 0 && fuzzy && !eof && trimmedTrailing === 0) {
+  if (oldStartIdx < 0 && fuzzy && trimmedTrailing === 0) {
     const trimmed = findOuterContextTrimmedWindow(sourceLines, hunk, stats);
     if (trimmed) {
       oldStartIdx = trimmed.start;
@@ -484,6 +551,31 @@ function resolveV4AHunkPosition(sourceLines, hunk, nextSearchLine, options = {})
       trimmedTrailingContext = trimmed.trailing;
     }
   }
+  // Edit-distance tier: same remap contract as the context-tolerance tier —
+  // the window's on-disk lines replace the patch's near-miss lines on BOTH
+  // sides, and any string ambiguity abandons the rescue.
+  if (oldStartIdx < 0 && fuzzy && oldLinesPattern.length >= 3) {
+    const near = findEditDistanceWindow(sourceLines, oldLinesPattern);
+    if (near) {
+      const remapped = new Map();
+      let ambiguous = false;
+      for (let k = 0; k < oldLinesPattern.length; k++) {
+        const pat = oldLinesPattern[k];
+        const src = sourceLines[near.start + k];
+        if (src === pat) continue;
+        if (
+          oldLinesPattern.filter((l) => l === pat).length > 1
+          || (remapped.has(pat) && remapped.get(pat) !== src)
+        ) { ambiguous = true; break; }
+        remapped.set(pat, src);
+      }
+      if (!ambiguous) {
+        newLinesPattern = newLinesPattern.map((l) => remapped.get(l) ?? l);
+        oldLinesPattern = oldLinesPattern.map((_, k) => sourceLines[near.start + k]);
+        oldStartIdx = near.start;
+      }
+    }
+  }
   if (oldStartIdx < 0) {
     const msg = `V4A hunk context not found: ${formatV4AHunkLocator(hunk)};${formatV4AContextMissHint(sourceLines, stats, anchorLine)}`;
     return { error: msg };
@@ -506,6 +598,9 @@ function resolveV4AHunkPosition(sourceLines, hunk, nextSearchLine, options = {})
     // hunk carried an @@ anchor (an anchored hunk is never ambiguous).
     pattern: oldLinesPattern,
     anchored: (hunk.anchors || []).filter(Boolean).length > 0,
+    // True when the hunk's `*** End of File` marker had to be relaxed to
+    // locate it (drives the non-fatal notice on the success output).
+    eofSignalIgnored,
   };
 }
 
@@ -1011,6 +1106,7 @@ export async function convertV4ASectionsToUnifiedPatch(sections, basePath, optio
         ],
       });
       noteV4AHunkAmbiguity(displayPath, sourceLines, loc);
+      noteV4AEofSignalIgnored(displayPath, loc);
       nextSearchLine = loc.nextSearchLine;
     }
     sectionHunkEntries.sort((a, b) => (a.start - b.start) || (a.order - b.order));

package/src/runtime/agent/orchestrator/tools/patch-tool-defs.mjs

@@ -1,5 +1,6 @@
-const APPLY_PATCH_LARK_GRAMMAR = `start: begin_patch hunk+ end_patch
+const APPLY_PATCH_LARK_GRAMMAR = `start: begin_patch root_line? hunk+ end_patch
 begin_patch: "*** Begin Patch" LF
+root_line: "*** Root: " filename LF
 end_patch: "*** End Patch" LF?
 
 hunk: add_hunk | delete_hunk | update_hunk
@@ -28,7 +29,7 @@ eof_line: "*** End of File" LF
 // Batching stays a rules-level policy: every new edit goes in one patch, with
 // one file block per target.
 const APPLY_PATCH_FREEFORM_DESCRIPTION =
-  'Use the `apply_patch` tool to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.';
+  'Edit files with `apply_patch`. FREEFORM input; do not wrap the patch in JSON.';
 
 // JSON-schema fallback providers (Anthropic and other non-grammar surfaces)
 // get the full V4A instructions inline: without a grammar the model has
@@ -41,13 +42,10 @@ const APPLY_PATCH_JSON_DESCRIPTION = [
   '*** Begin Patch',
   '[file sections]',
   '*** End Patch',
-  'Every section starts with exactly one header:',
-  '- *** Add File: <path> then +content lines.',
-  '- *** Delete File: <path> with nothing after it.',
-  '- *** Update File: <path>, optionally followed by *** Move to: <new path>.',
-  'Update hunks open with @@ or @@ <enclosing class/function>; prefix every line with space (context), - (remove), or + (add); a hunk at end of file may close with *** End of File.',
-  'Copy 3 context lines above and below verbatim from the newest tool output of the file (after your own patch, use post-patch content; never retype from memory). Do not duplicate overlapping context; if context is not unique, add enclosing @@ headers.',
-  'Use project-relative paths. Every added file line needs +. Never submit a compacted-history marker; re-read and create a fresh patch.',
+  'Every section starts with exactly one header: *** Add File: <path> (+content lines), *** Delete File: <path> (nothing after), *** Update File: <path> (optional *** Move to: <new path>).',
+  'Hunks open with @@ or @@ <symbol>; prefix lines with space, -, or +; an end-of-file hunk may close with *** End of File.',
+  'Copy 3 context lines above/below verbatim from the newest tool output — after your own patch use its post-patch body, never memory. No duplicate overlapping context; if still ambiguous, stack @@ headers: @@ class Foo then @@ def bar.',
+  'Project-relative paths; every added line needs +. Never submit a compacted-history marker — re-read and send a fresh patch.',
 ].join('\n');
 
 export const PATCH_TOOL_DEFS = [
@@ -65,8 +63,11 @@ export const PATCH_TOOL_DEFS = [
     inputSchema: {
       type: 'object',
       properties: {
-        patch: { type: 'string', description: 'The V4A patch text to apply (format and context rules in the tool description).' },
-        post_shell: { type: 'string', description: 'Verification command run when the patch applies; skipped on patch failure.' },
+        patch: { type: 'string', description: 'V4A patch text to apply; rules above.' },
+        root: {
+          type: 'string',
+          description: 'Write root; required only for targets outside the session directory.',
+        },
       },
       required: ['patch'],
       additionalProperties: false,

package/src/runtime/agent/orchestrator/tools/patch.mjs

@@ -20,7 +20,7 @@
 //   ./patch/orchestrator.mjs  — apply_patch orchestration + executePatchTool
 //     + replay capture + UI-diff side-channel.
 //
-// Backend is unchanged: NATIVE-ONLY dispatch to the mixdog-patch Rust engine,
+// Executor is unchanged: NATIVE-ONLY dispatch to the mixdog-patch Rust engine,
 // no JS apply fallback. Public exports below match the pre-split surface.
 
 // Side-effect import: schedules the native-patch prewarm on module load, as

package/src/runtime/agent/orchestrator/tools/shell-command.mjs

@@ -75,8 +75,8 @@ const SHELL_ADMISSION_WAIT_MS = Number.isFinite(_envAdmissionWait) && _envAdmiss
   ? _envAdmissionWait
   : 30_000;
 
-// CC parity default: capture child output via file fds (TaskOutput direct
-// mode) instead of parent-side pipes. Opt back into pipe capture with
+// Default: capture child output via file fds (direct mode) instead of
+// parent-side pipes. Opt back into pipe capture with
 // MIXDOG_SHELL_PIPE_CAPTURE=1 (diagnostic escape hatch).
 // win32 EXCEPTION: fd-based stdio entries are UV_INHERIT_FD, which makes
 // libuv DROP CREATE_NO_WINDOW (libuv PR #1659) — the child shell then
@@ -145,9 +145,30 @@ function _abortableDelay(ms, signal) {
   });
 }
 
-export async function acquireShellLeaseBounded(admission, { abortSignal, label, dependency = 'scoped' } = {}) {
+// True when an abort was raised because the user sent a NEW message while the
+// command was running (session-api.mjs raises 'interrupt' when steering is
+// pending, 'user-cancel' for a plain ESC). The reason travels as the
+// SessionClosedError's `reason` field; a bare string / message fallback keeps
+// non-session callers working. Anything unrecognized is treated as a real
+// cancellation, so the kill path stays the default.
+export function _abortReasonIsInterrupt(abortSignal) {
+  const raw = abortSignal?.reason;
+  if (!raw) return false;
+  if (typeof raw === 'string') return raw === 'interrupt';
+  if (typeof raw === 'object') {
+    if (raw.reason === 'interrupt') return true;
+    if (typeof raw.message === 'string' && /\breason=interrupt\b/.test(raw.message)) return true;
+  }
+  return false;
+}
+
+export async function acquireShellLeaseBounded(admission, {
+  abortSignal, label, dependency = 'scoped', ownerKey = null,
+} = {}) {
   if (!(SHELL_ADMISSION_WAIT_MS > 0)) {
-    return admission.acquire('shell', { signal: abortSignal || null, label, dependency });
+    return admission.acquire('shell', {
+      signal: abortSignal || null, label, dependency, ownerKey,
+    });
   }
   const ctl = new AbortController();
   const onAbort = () => {
@@ -165,7 +186,9 @@ export async function acquireShellLeaseBounded(admission, { abortSignal, label,
   try {
     for (;;) {
       try {
-        const lease = await admission.acquire('shell', { signal: ctl.signal, label, dependency });
+        const lease = await admission.acquire('shell', {
+          signal: ctl.signal, label, dependency, ownerKey,
+        });
         // Hand governance back to the caller's signal: the internal deadline
         // controller may still fire in a lost race after grant, and a stale
         // aborted signal on the lease would poison later parent-restore paths.
@@ -235,6 +258,7 @@ export function execShellCommand({
   ownerSessionId,
   backgroundOnTimeout,
   promotedTimeoutMs = 0,
+  backgroundDeadlineMs = 0,
   admission = resourceAdmission,
 }) {
   return new Promise(async (resolve) => {
@@ -363,6 +387,7 @@ export function execShellCommand({
       resourceLease = await acquireShellLeaseBounded(admission, {
         abortSignal,
         label: String(command || '').slice(0, 120),
+        ownerKey: ownerSessionId,
       });
       const _policyErr = await _execPolicyBlockMessage(command);
       if (_policyErr) {
@@ -443,7 +468,6 @@ export function execShellCommand({
         childPid: child.pid,
         childGroupPid: child.pid,
         label: 'shell-command',
-        protectHostMemory: true,
       });
       // Windows has no process-group handle. Begin observing while the owned
       // root still exists so descendants can be proven before root exit.
@@ -768,7 +792,12 @@ export function execShellCommand({
       const stdoutPath = taskOutput.spilled ? taskOutput.stdoutPath : null;
       const stderrPath = taskOutput.spilled ? taskOutput.stderrPath : null;
       let job = null;
-      const adoptedTimeoutMs = reason === 'timeout' ? promotedTimeoutMs : 0;
+      const elapsedMs = Math.max(0, Date.now() - _startMs);
+      const adoptedTimeoutMs = reason === 'timeout'
+        ? promotedTimeoutMs
+        : (backgroundDeadlineMs > 0
+          ? Math.max(1, backgroundDeadlineMs - elapsedMs)
+          : 0);
       try {
         job = adoptForegroundShellJob({
           command,
@@ -830,7 +859,12 @@ export function execShellCommand({
       // Re-check after the awaited capture reads: cancellation can race after
       // adoption commits. Never report that cancelled process as a successful
       // still-running background task.
-      if (abortSignal && abortSignal.aborted) {
+      // EXCEPTION: an interrupt-driven promotion starts FROM an aborted signal
+      // by design (the user typed a new message), so this guard must not undo
+      // the very transition it was asked to perform. A plain cancellation still
+      // reverts adoption and kills.
+      if (abortSignal && abortSignal.aborted
+        && !(reason === 'interrupt' && _abortReasonIsInterrupt(abortSignal))) {
         killed = true;
         killCause = 'cancellation';
         try { killShellJob(jobId); } catch {}
@@ -855,7 +889,7 @@ export function execShellCommand({
         }));
         return;
       }
-      // CC parity (BashTool completed-during-promotion race): the child
+      // Completed-during-promotion race: the child
       // finished while adoption was committing. Report a clean COMPLETED
       // result instead of backgrounded — the caller then never arms the
       // completion watcher, so no redundant task notification fires. Write
@@ -1037,6 +1071,26 @@ export function execShellCommand({
 
     if (abortSignal) {
       abortHandler = () => {
+        // Interrupt (the user typed a NEW message while this was running) is a
+        // "also look at this" signal, not "stop that" — CC backgrounds instead
+        // of killing there, and throwing away a long build the user never asked
+        // to stop is the worse outcome. Explicit cancellation (ESC) keeps the
+        // kill. The promotion reuses the timeout path's guards verbatim so a
+        // detached / already-settled / already-exited child can never be
+        // adopted as a job.
+        if (
+          _abortReasonIsInterrupt(abortSignal) &&
+          backgroundOnTimeout &&
+          !_isBackground &&
+          !settled &&
+          !autoBackgrounded &&
+          !killed &&
+          child?.exitCode == null &&
+          child?.signalCode == null
+        ) {
+          fireAutoBackground({ reason: 'interrupt' });
+          return;
+        }
         _treeKillForceSettle('cancellation');
       };
       try {

package/src/runtime/agent/orchestrator/tools/shell-exec-output.mjs

@@ -209,7 +209,7 @@ export class TaskOutput {
     this.stdoutFileSize = 0;
     this.stderrFileSize = 0;
     this.writeError = null;
-    // CC parity: direct-capture mode hands the spill files to the child as
+    // Direct-capture mode hands the spill files to the child as
     // stdio fds (no JS pipes). Sizes are then tracked via stat, not writes.
     this.direct = false;
     // fsync throttle: task wait/read + tail-read polling can call getStdout/
@@ -292,7 +292,7 @@ export class TaskOutput {
     this._ensureFileBacking();
   }
 
-  // CC parity (ShellCommand file mode): open the spill files BEFORE spawn and
+  // File mode: open the spill files BEFORE spawn and
   // hand their fds to the child as stdio[1]/stdio[2]. The child (and any
   // grandchildren) write straight to disk with no parent-side pipes, so a
   // surviving grandchild can never wedge the caller by holding a pipe handle.

package/src/runtime/channels/lib/config.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, mkdirSync } from "fs";
 import { join } from "path";
-import { DiscordBackend } from "../backends/discord.mjs";
-import { TelegramBackend } from "../backends/telegram.mjs";
+import { DiscordProvider } from "../providers/discord.mjs";
+import { TelegramProvider } from "../providers/telegram.mjs";
 import {
   readSection,
   updateSection,
@@ -22,11 +22,11 @@ const DEFAULT_ACCESS = {
   channels: {}
 };
 const DEFAULT_CONFIG = {
-  backend: "discord",
+  provider: "discord",
   discord: { token: "" },
   telegram: { token: "" },
   access: DEFAULT_ACCESS,
-  channel: { channelId: "" }
+  channel: {}
 };
 // Shared defaults layer. Merge semantics: user values win; defaults
 // only fill missing fields. Helper is exported so the setup UI and
@@ -40,18 +40,18 @@ function applyDefaults(config) {
   return out;
 }
 
-function channelIdForBackend(entry = {}, backend = "discord") {
-  if (backend === "telegram") {
-    return String(entry?.telegramChatId || (entry?.discordChannelId ? "" : entry?.channelId) || "");
+function channelIdForProvider(entry = {}, provider = "discord") {
+  if (provider === "telegram") {
+    return String(entry?.telegramChatId || "");
   }
-  return String(entry?.discordChannelId || (entry?.telegramChatId ? "" : entry?.channelId) || "");
+  return String(entry?.discordChannelId || "");
 }
 
-// Resolve the single active-backend channel id from the config's `channel`
+// Resolve the single active-provider channel id from the config's `channel`
 // section. Disk config carries a single `channel` object only.
-function resolveChannelId(raw = {}, backend = "discord") {
+function resolveChannelId(raw = {}, provider = "discord") {
   const channel = raw.channel && typeof raw.channel === "object" ? raw.channel : null;
-  if (channel) return channelIdForBackend(channel, backend);
+  if (channel) return channelIdForProvider(channel, provider);
   return "";
 }
 
@@ -88,20 +88,20 @@ async function loadConfig({ freshSecrets = false } = {}) {
     if (discordTokenProblem) {
       process.stderr.write(`mixdog: discord token ignored: ${discordTokenProblem}\n`);
     }
-    // Single-backend select: config.backend picks ONE of discord|telegram.
+    // Single-provider select: config.provider picks ONE of discord|telegram.
     // Anything else falls back to the discord default.
-    const backend = raw.backend === "telegram" ? "telegram" : "discord";
+    const provider = raw.provider === "telegram" ? "telegram" : "discord";
     const telegramToken = getTelegramToken();
-    const channelId = resolveChannelId(raw, backend);
+    const channelId = resolveChannelId(raw, provider);
     // The runtime reads only the resolved `channelId`; disk carries a single
     // `channel` object, so spread `raw` directly.
     return applyDefaults({
       ...DEFAULT_CONFIG,
       ...raw,
-      backend,
+      provider,
       channelId,
       discord: { ...DEFAULT_CONFIG.discord, ...(({ token: _, ...rest }) => rest)(raw.discord || {}), ...(discordToken && !discordTokenProblem ? { token: discordToken } : {}) },
-      // Merge the keychain-resolved telegram token (harmless when backend is
+      // Merge the keychain-resolved telegram token (harmless when provider is
       // discord; the secret never lands in the on-disk config either way).
       telegram: { ...DEFAULT_CONFIG.telegram, ...(({ token: _t, ...rest }) => rest)(raw.telegram || {}), ...(telegramToken ? { token: telegramToken } : {}) },
       access: {
@@ -117,7 +117,7 @@ async function loadConfig({ freshSecrets = false } = {}) {
       updateSection("channels", () => DEFAULT_CONFIG);
       process.stderr.write(
         `mixdog: default channels config created in ${MIXDOG_CONFIG_PATH}
-  edit discord.token and channel.channelId to connect.
+  edit the active provider channel id to connect.
 `
       );
       return applyDefaults(DEFAULT_CONFIG);
@@ -125,7 +125,7 @@ async function loadConfig({ freshSecrets = false } = {}) {
     throw err;
   }
 }
-const HEADLESS_BACKEND = {
+const HEADLESS_PROVIDER = {
   name: "headless",
   MAX_MESSAGE_LENGTH: 2000,
   formatOutgoing(t) {
@@ -156,31 +156,31 @@ const HEADLESS_BACKEND = {
   on() {
   }
 };
-function createBackend(config) {
+function createProvider(config) {
   // Channels-module toggle is MESSAGING-ONLY: automation (scheduler/webhooks)
-  // keeps the worker alive, so a disabled module runs the headless backend
+  // keeps the worker alive, so a disabled module runs the headless provider
   // instead of blocking the whole runtime.
   if (config.enabled === false) {
     process.stderr.write("mixdog: channels messaging disabled; channel runtime running in headless mode\n");
-    return HEADLESS_BACKEND;
+    return HEADLESS_PROVIDER;
   }
-  // Single-backend select: exactly one backend is constructed based on
-  // config.backend (discord|telegram). The two are mutually exclusive.
-  if (config.backend === "telegram") {
+  // Single-provider select: exactly one provider is constructed based on
+  // config.provider (discord|telegram). The two are mutually exclusive.
+  if (config.provider === "telegram") {
     const telegramToken = getTelegramToken();
     if (!telegramToken) {
       process.stderr.write("mixdog: telegram bot not configured; channel runtime running in headless mode\n");
-      return HEADLESS_BACKEND;
+      return HEADLESS_PROVIDER;
     }
     const tgStateDir = config.telegram?.stateDir ?? join(DATA_DIR, "telegram");
     mkdirSync(tgStateDir, { recursive: true });
-    return new TelegramBackend({
+    return new TelegramProvider({
       ...config.telegram,
       configPath: CONFIG_FILE,
       access: config.access,
       // Single-source channel setup: the main chat is auto-allowed inside
-      // TelegramBackend.loadAccess() so a configured channel.channelId
-      // is enough for both inbound gating and outbound.
+      // TelegramProvider.loadAccess() so the configured Telegram target is
+      // enough for both inbound gating and outbound.
       mainChannelId: config.channelId
     }, tgStateDir);
   }
@@ -189,19 +189,19 @@ function createBackend(config) {
   if (discordTokenProblem) {
     process.stderr.write(`mixdog: discord token ignored: ${discordTokenProblem}\n`);
   }
-  if (config.backend !== "discord" || !discordToken || discordTokenProblem) {
+  if (config.provider !== "discord" || !discordToken || discordTokenProblem) {
     process.stderr.write("mixdog: discord bot not configured; channel runtime running in headless mode\n");
-    return HEADLESS_BACKEND;
+    return HEADLESS_PROVIDER;
   }
   const stateDir = config.discord.stateDir ?? join(DATA_DIR, "discord");
   mkdirSync(stateDir, { recursive: true });
-  return new DiscordBackend({
+  return new DiscordProvider({
     ...config.discord,
     configPath: CONFIG_FILE,
     access: config.access,
     // Single-source channel setup: the main channel is auto-allowed inside
-    // DiscordBackend.loadAccess() so a configured channel.channelId
-    // is enough for both inbound and outbound — no separate access.channels entry.
+    // DiscordProvider.loadAccess() so the configured Discord target is enough
+    // for both inbound and outbound — no separate access.channels entry.
     mainChannelId: config.channelId
   }, stateDir);
 }
@@ -215,7 +215,7 @@ function loadProfileConfig() {
 }
 export {
   DATA_DIR,
-  createBackend,
+  createProvider,
   getDiscordToken,
   getTelegramToken,
   loadConfig,

package/src/runtime/channels/lib/inbound-handler.mjs

@@ -7,14 +7,14 @@ import {
 import { refreshActiveInstance } from "./runtime-paths.mjs";
 import { isNetworkError, retryOnNetwork } from "./network-retry.mjs";
 // Inbound message pipeline extracted from channels/index.mjs (behavior-
-// preserving): serial inbound queue, backend.onMessage transcript (re)bind +
+// preserving): serial inbound queue, provider.onMessage transcript (re)bind +
 // steal logic, and handleInbound voice-transcription + parent notify. Bound to
 // live runtime getters and shared primitives.
 function isImageAttachment(contentType) {
   return typeof contentType === "string" && contentType.toLowerCase().startsWith("image/");
 }
 export function createInboundHandler({
-  getBackend,
+  getProvider,
   getConfig,
   getBridgeRuntimeConnected,
   getChannelBridgeActive,
@@ -55,7 +55,7 @@ const inboundQueue = (() => {
   };
 })();
 
-getBackend().onMessage = (msg) => {
+getProvider().onMessage = (msg) => {
   const receivedAtMs = Number.isFinite(msg.receivedAtMs) ? msg.receivedAtMs : Date.now();
   const onMessageAtMs = Date.now();
   const gateBlocked = (!getBridgeRuntimeConnected() || !getBridgeOwnershipSnapshot().owned)
@@ -63,7 +63,7 @@ getBackend().onMessage = (msg) => {
     : (!getChannelBridgeActive() ? "bridge-inactive" : "");
   if (gateBlocked) {
     if (gateBlocked === "bridge-seat") refreshBridgeOwnershipSafe();
-    // CC parity: an inbound message is never silently swallowed. The bridge
+    // An inbound message is never silently swallowed. The bridge
     // seat may be mid-handover or the channel bridge may still be activating
     // (app relaunch / boot); retry with backoff before giving up, and make
     // the final drop loud so a real loss stays diagnosable.
@@ -72,7 +72,7 @@ getBackend().onMessage = (msg) => {
       msg.__bridgeGateRetries = attempt;
       msg.receivedAtMs = receivedAtMs;
       setTimeout(() => {
-        try { getBackend().onMessage?.(msg); } catch { /* best-effort */ }
+        try { getProvider().onMessage?.(msg); } catch { /* best-effort */ }
       }, 2000 * attempt)?.unref?.();
     } else {
       try { process.stderr.write(`mixdog: inbound message dropped after ${attempt - 1} ${gateBlocked} retries (channel=${msg.chatId}, id=${msg.messageId})\n`); } catch {}
@@ -242,7 +242,7 @@ getBackend().onMessage = (msg) => {
   });
   void (async () => {
     try {
-      await getBackend().react(msg.chatId, msg.messageId, "\u{1F914}");
+      await getProvider().react(msg.chatId, msg.messageId, "\u{1F914}");
     } catch {
     }
     await bindingDone;
@@ -271,7 +271,7 @@ async function handleInbound(msg, route, options = {}) {
         const files = await retryOnNetwork(
           // Short per-attempt timeout (vs the 180s default) bounds worst-case
           // blockage of the serial inboundQueue on a bad voice message.
-          () => getBackend().downloadAttachment(msg.chatId, msg.messageId, { timeoutMs: 20_000 }),
+          () => getProvider().downloadAttachment(msg.chatId, msg.messageId, { timeoutMs: 20_000 }),
           { label: "voice.download" }
         );
         // concurrency handled inside transcribeVoice queue; loop is sequential so last att wins
@@ -312,7 +312,7 @@ async function handleInbound(msg, route, options = {}) {
   if (imageAtts.length > 0) {
     try {
       const files = (await retryOnNetwork(
-        () => getBackend().downloadAttachment(msg.chatId, msg.messageId, {
+        () => getProvider().downloadAttachment(msg.chatId, msg.messageId, {
           timeoutMs: 20_000,
           filter: (a) => isImageAttachment(a.contentType),
         }),