synabun 2.0.0 → 2.0.7

package/neural-interface/lib/whatsapp/bridge.js

@@ -13,6 +13,14 @@
 // owner's messages; a synabun.mailbox event is RUNNING(mailbox), a turn the
 // CLI starts itself RUNNING(background), and a turn nobody here submitted (a
 // prompt typed on the desktop) RUNNING(external) — tracked, never forwarded.
+// A task the router continues on another model (a synabun.continuation event:
+// a route decided automatically, by a remembered route, or on a card) answers
+// where its prompt came from: RUNNING(followup) for a prompt from the phone,
+// whose answer is sent once as the reply (not an update, whatever "Forward
+// background results" says), RUNNING(external) for any other. A follow-up is
+// how a turn's answer is delivered, nothing more: what may run unasked or be
+// approved is the runtime's (a continuation is its own turn, never the owner's
+// message: computer use asks once in it) and the owner's typed answers.
 // The turn object exists before submit is called: brain events can arrive
 // before it resolves.
 //
@@ -23,8 +31,9 @@
 // closes WITHOUT being granted (denied, cancelled) and the message goes to the
 // Assistant as the next prompt. An approval is only ever granted by a "yes"
 // the bridge matched on a message the owner typed, aimed at that request while
-// it is open: never by the model, by a forwarded message, by a reply that
-// quotes something else or by anything that merely looks like an answer.
+// it is open: never by the model, by a forwarded message, by a voice note (its
+// transcript is an ordinary message, `voice: true`), by a reply that quotes
+// something else or by anything that merely looks like an answer.
 // Messages that arrive while a turn runs wait as one merged prompt and go in
 // as soon as it ends; a queue watch lets go of a turn whose end never came.
 // A request that appears while such a message waits closes at once, unseen and
@@ -87,14 +96,28 @@ export const BRIDGE_LIMITS = Object.freeze({
   policyTickMs: 30_000,
 });
 
+/**
+ * Why a voice note was not transcribed (the host's unsupported.reason), told to the phone once per
+ * reason every unsupportedEveryMs. Anything else unsupported gets the generic line.
+ */
+export const AUDIO_NOT_TRANSCRIBED = Object.freeze({
+  transcription_disabled: 'Voice notes are not transcribed: that is turned off in Settings → WhatsApp on your computer. Type your message instead.',
+  transcription_unavailable: 'I can\'t transcribe voice notes yet: this computer needs whisper.cpp, its speech model and FFmpeg (Settings → WhatsApp says what is missing). Type your message instead.',
+  too_large: 'That voice note is too large for me to transcribe (20 MB at most). Send a shorter one, or type it.',
+  too_long: 'That voice note is too long for me to transcribe (10 minutes at most). Send a shorter one, or type it.',
+  stale: 'That voice note was sent a while ago, so I did not transcribe it. Send it again if you still need it.',
+  transcription_failed: 'I couldn\'t transcribe that voice note. Try again, or type your message.',
+});
+
 /** Send refusals that mean "not now": the reply waits in the outbox for the next connect. */
 const RESEND_ON_CONNECT = /DISCONNECT|NOT_CONNECTED|OFFLINE|RECONNECT|CLOSED|TIMEOUT|HOST_UNAVAILABLE/i;
 /**
  * What happens to a reply the transport refused: 'connect' (it waits for the
  * next connect), 'later' (THROTTLED: sent again after its retryAfterMs) or
- * 'drop'. PAUSED (an owner anomaly paused sending) and HELD (the connector
- * kept crashing) drop it: the service records why in the activity log and the
- * Settings tab shows the state.
+ * 'drop'. PAUSED (an owner anomaly paused sending) and HELD (a connector
+ * process of another SynaBun version, down until a restart; a crash is not
+ * HELD: it reads HOST_UNAVAILABLE and the reply waits) drop it: the service
+ * records why in the activity log and the Settings tab shows the state.
  */
 export function outboxPlan(code) {
   const value = String(code || '');
@@ -104,7 +127,7 @@ export function outboxPlan(code) {
 
 const DEFAULT_CONFIG = Object.freeze({
   enabled: true, level: 'ask', progress: 'key', forwardBackground: true, replyLabel: null, maxMessages: 3,
-  rotation: 'idle6h', strictWorkerApprovals: false, computerUse: false, mode: 'self', paused: false, pausedBy: null, autonomousUntil: null,
+  rotation: 'idle6h', strictWorkerApprovals: false, computerUse: false, mode: 'self', paused: false, pausedBy: null,
 });
 const ALREADY_ANSWERED = new Set(['CONTROL_UNKNOWN', 'ROUTE_ALREADY_DECIDED', 'ROUTE_NOT_FOUND', 'CLARIFY_ALREADY_ANSWERED', 'CLARIFY_NOT_FOUND', 'PERMISSION_ALREADY_RESOLVED', 'NO_PENDING_REQUEST', 'RUN_NOT_FOUND']);
 const ROUTE_DONE_PHASES = new Set(['decided', 'auto', 'expired', 'declined', 'cancelled']);
@@ -191,6 +214,8 @@ export function createWhatsAppBridge({
     outboxTimer: null,            // a THROTTLED reply's retry
     staleSkipped: 0,
     staleTimer: null,
+    stoppedAt: 0,                 // when the owner's last /stop was sent (its message time)
+    stopLateNoted: false,         // one note per /stop for what was sent before it and arrived after it
     unsupportedAt: new Map(),
     minuteWindow: { start: 0, count: 0, noticed: false },
     dayWindow: { start: 0, count: 0, noticed: false },
@@ -435,14 +460,16 @@ export function createWhatsAppBridge({
     state.brainApplied = { sessionId, signature };
     persistBridgeState();
   }
+  // Autonomous has no time limit on WhatsApp: the policy carries no autonomousUntil (lib/remote-policy.js effectiveLevel).
+  // WhatsApp turned off on this computer (`enabled: false`, which also stops the connector) ends computer use like the switch.
   function remoteFromConfig(cfg = readConfig()) {
-    return { channel: 'whatsapp', level: cfg.level || 'ask', strictWorkerApprovals: cfg.strictWorkerApprovals === true, autonomousUntil: cfg.autonomousUntil || null, paused: state.paused, computerUse: cfg.computerUse === true && state.computerEnded !== true };
+    return { channel: 'whatsapp', level: cfg.level || 'ask', strictWorkerApprovals: cfg.strictWorkerApprovals === true, paused: state.paused, computerUse: cfg.computerUse === true && cfg.enabled !== false && state.computerEnded !== true };
   }
   /** The policy of one of our sessions: computer use is the current conversation's alone. */
   function remoteFor(id, base = remoteFromConfig()) {
     return id === state.sessionId ? base : { ...base, computerUse: false };
   }
-  const policySignature = (remote) => JSON.stringify([remote.level, remote.strictWorkerApprovals, remote.autonomousUntil, remote.paused, remote.computerUse]);
+  const policySignature = (remote) => JSON.stringify([remote.level, remote.strictWorkerApprovals, remote.paused, remote.computerUse]);
   async function createSession() {
     const rt = runtime();
     if (!rt?.createSession) throw Object.assign(new Error('The Assistant is not available right now.'), { code: 'RUNTIME_UNAVAILABLE' });
@@ -500,9 +527,8 @@ export function createWhatsAppBridge({
   // ── policy ─────────────────────────────────────────────────────────────────
   /**
    * Keep the level of every WhatsApp session in line with the config (level,
-   * strict approvals, the autonomous window, pause). A change — or an
-   * autonomous window that just ran out — re-registers, which makes the
-   * runtime re-apply the clamp and stop runs above it.
+   * strict approvals, pause, computer use). A change re-registers, which makes
+   * the runtime re-apply the clamp and stop runs above it.
    */
   function syncPolicies() {
     const cfg = readConfig();
@@ -652,7 +678,8 @@ export function createWhatsAppBridge({
       if (turn.kind === 'followup') state.followUp = null;
       else { presence('paused'); state.inflight = null; persistBridgeState(); react(turn.sourceIds, 'done'); }
     } else if (turn.kind === 'followup') {
-      // The task the phone decided on a card: its answer is a reply, not an update.
+      // The task the phone decided on a card, or that its prompt carried on to another model: its answer
+      // is a reply, not an update. Said once: the turn is gone already, a repeated end finds nothing.
       state.followUp = null;
       const text = finalText(turn);
       if (outcome === 'failed') await say(`Something went wrong: ${String(message || turn.resultError || 'the turn failed').slice(0, 400)}`, { maxChunks: 1 });
@@ -767,6 +794,12 @@ export function createWhatsAppBridge({
         // Our own prompt (the WhatsApp turn exists already); any other is someone else's turn.
         if (ev.origin !== 'whatsapp' && !state.turns.has(sessionId)) makeTurn(sessionId, 'external');
         return;
+      case 'synabun.continuation':
+        // The router carries a task on (another model, the same conversation), before any of its output.
+        // A prompt from the phone: its answer is the reply to the phone. Anything else stays as before:
+        // someone else's turn, unless a card the phone saw was just decided (ensureTurn).
+        if (!state.turns.has(sessionId)) ensureTurn(sessionId, ev.origin === 'whatsapp' ? 'followup' : 'external');
+        return;
       case 'synabun.mailbox': {
         const items = Array.isArray(ev.items) ? ev.items : [];
         const turn = state.turns.get(sessionId);
@@ -1031,6 +1064,10 @@ export function createWhatsAppBridge({
       case 'help': await say(HELP_TEXT, { maxChunks: 2 }); return;
       case 'status': await say(statusText(statusSnapshot()), { maxChunks: 1 }); return;
       case 'stop': {
+        // What was sent before this /stop and arrives after it (a voice note still being transcribed, and
+        // what waited behind it) is not acted on, as /stop clears what already waits in line.
+        state.stoppedAt = Math.max(state.stoppedAt, tsMs(message.ts, now()));
+        state.stopLateNoted = false;
         const { stoppedRuns, clearedQueue } = await stopEverything({ reason: 'phone' });
         const n = stoppedRuns + clearedQueue;
         await say(`Stopped. Cancelled ${n} task${n === 1 ? '' : 's'}.`, { maxChunks: 1 });
@@ -1067,18 +1104,14 @@ export function createWhatsAppBridge({
   function statusSnapshot() {
     const view = state.sessionId ? sessionView(state.sessionId) : null;
     const turn = state.sessionId ? state.turns.get(state.sessionId) : null;
-    const rt = runtime();
-    let brainCapUsd = null;
-    try { brainCapUsd = rt?.brainCapUsd?.() ?? null; } catch { brainCapUsd = null; }
     const cfg = readConfig();
     const current = currentCard();
     return {
       connected: isConnected(), sessionId: state.sessionId, title: view?.title || null, brain: view?.brain || null,
       running: !!turn || !!view?.running, turnKind: turn?.kind || null, queued: state.queue.length,
       pendingCards: state.cards.size, currentCard: current ? (current.kind === 'route' ? 'where to run a task' : current.kind === 'computer' ? 'controlling your Mac' : current.kind) : null,
-      budget: view?.budget || null, brainUsd: view?.costUsd ?? null, brainCapUsd,
+      budget: view?.budget || null, brainUsd: view?.costUsd ?? null,
       level: state.sessionId ? levelOf(state.sessionId) : cfg.level, paused: state.paused, pausedBy: state.pausedBy,
-      autonomousUntil: cfg.autonomousUntil || null,
     };
   }
   /** /stop and stopAll: the turn, the session's runs, open cards and the queue. */
@@ -1168,6 +1201,16 @@ export function createWhatsAppBridge({
     // `backlog`): never acted on, only counted for one note. Checked first, so a
     // backlog neither uses up the rate limits nor counts as activity.
     if (now() - tsMs(message.ts, now()) > L.staleMs) { noteStale(); return; }
+    // Sent before the owner's last /stop, delivered after it (a typed /stop does not wait for a voice note
+    // being transcribed): /stop already stopped it. A command still runs. What WhatsApp held while SynaBun was
+    // offline arrives in order and is never overtaken (a backlog is never sent ahead), so it is not affected.
+    if (state.stoppedAt && message.backlog !== true && tsMs(message.ts, now()) < state.stoppedAt && !parseCommand(message)) {
+      if (!state.stopLateNoted) {
+        state.stopLateNoted = true;
+        await say('A message you sent before /stop arrived after it, so I did not act on it. Send it again if you still need it.', { maxChunks: 1 });
+      }
+      return;
+    }
     if (rateLimited()) return;
     const activityBefore = state.lastActivityAt;
     state.lastActivityAt = now();
@@ -1178,10 +1221,12 @@ export function createWhatsAppBridge({
     const images = Array.isArray(message.images) ? message.images : [];
     if (message.unsupported && !text.trim() && !images.length) {
       const type = String(message.unsupported.type || 'this kind of');
-      const last = state.unsupportedAt.get(type) || 0;
+      const audio = type === 'audio' && Object.hasOwn(AUDIO_NOT_TRANSCRIBED, String(message.unsupported.reason)) ? AUDIO_NOT_TRANSCRIBED[message.unsupported.reason] : null;
+      const key = audio ? `audio:${message.unsupported.reason}` : type;
+      const last = state.unsupportedAt.get(key) || 0;
       if (now() - last >= L.unsupportedEveryMs) {
-        state.unsupportedAt.set(type, now());
-        await say(`I can read text and pictures for now; ${type} messages are not supported yet.`, { maxChunks: 1 });
+        state.unsupportedAt.set(key, now());
+        await say(audio || `I can read text and pictures for now; ${type} messages are not supported yet.`, { maxChunks: 1 });
       }
       return;
     }
@@ -1198,8 +1243,8 @@ export function createWhatsAppBridge({
     }
     // Something is waiting for the owner: a clear answer answers it; anything else closes it
     // without a grant and carries on as the next prompt. Only words the owner typed can answer:
-    // never a forwarded message, a picture or "//text".
-    const answerable = !images.length && command?.kind !== 'literal' && message.forwarded !== true;
+    // never a forwarded message, a picture, a voice note (its transcript) or "//text".
+    const answerable = !images.length && command?.kind !== 'literal' && message.forwarded !== true && message.voice !== true;
     if (await replyToPending(message, { answerable })) return;
     if (rotationDue(activityBefore)) state.rotateOnNextSubmit = true;
     // A request raised between that look and here is older than this message too (onCard only sees
@@ -1271,7 +1316,7 @@ export function createWhatsAppBridge({
     if (!list.length) return;
     let composed = null;
     try { composed = inbound?.composePrompt ? inbound.composePrompt(list, { rng }) : null; } catch (error) { log('whatsapp:bridge', `compose: ${error?.message || error}`); }
-    if (!composed) composed = { text: list.map((part) => String(part.text || '')).filter(Boolean).join('\n\n'), images: list.flatMap((part) => part.images || []), sourceIds: list.map((part) => part.id).filter(Boolean), untrusted: list.some((part) => part.forwarded || part.quoted) };
+    if (!composed) composed = { text: list.map((part) => String(part.text || '')).filter(Boolean).join('\n\n'), images: list.flatMap((part) => part.images || []), sourceIds: list.map((part) => part.id).filter(Boolean), untrusted: list.some((part) => part.forwarded || part.quoted || part.audioFile === true) };
     const images = Array.isArray(composed.images) ? composed.images.filter(Boolean) : [];
     const job = {
       text: String(composed.text || ''), images,
@@ -1402,22 +1447,21 @@ export function createWhatsAppBridge({
     }
     persistBridgeState();
     react(job.sourceIds, 'failed');
-    if (code === 'SESSION_BUDGET_EXCEEDED' || code === 'BRAIN_BUDGET_EXCEEDED') { await say(budgetText(code, sessionId, result.message), { maxChunks: 1 }); return; }
+    if (code === 'SESSION_BUDGET_EXCEEDED' || code === 'BRAIN_SHARE_EXHAUSTED') { await say(budgetText(code, sessionId, result.message), { maxChunks: 1 }); return; }
     if (code === 'EMPTY_PROMPT') return;
     await say(`Could not start that: ${String(result.message || code).slice(0, 400)}`, { maxChunks: 1 });
   }
-  /** Spend against the cap, and the two ways on: /new or a higher cap. Never a silent new session. */
+  /** Spend against the budget, and the two ways on: /new or a higher budget. Never a silent new session. */
   function budgetText(code, sessionId, fallback) {
     const view = sessionView(sessionId);
+    const budget = view?.budget || null;
     let line = '';
-    if (code === 'SESSION_BUDGET_EXCEEDED' && view?.budget && Number.isFinite(Number(view.budget.hardUsd))) {
-      line = `This conversation spent ${usd(view.budget.totalUsd)} of its ${usd(view.budget.hardUsd)} cap.`;
-    } else if (code === 'BRAIN_BUDGET_EXCEEDED') {
-      let cap = null;
-      try { cap = runtime()?.brainCapUsd?.() ?? null; } catch { cap = null; }
-      line = cap !== null ? `The Assistant spent ${usd(view?.costUsd)} of its ${usd(cap)} cap in this conversation.` : '';
+    if (code === 'SESSION_BUDGET_EXCEEDED' && budget && Number.isFinite(Number(budget.amountUsd))) {
+      line = `This conversation spent ${usd(budget.totalUsd)} of its ${usd(budget.amountUsd)} budget.`;
+    } else if (code === 'BRAIN_SHARE_EXHAUSTED' && budget && Number.isFinite(Number(budget.amountUsd))) {
+      line = `The Assistant's share of this conversation's ${usd(budget.amountUsd)} budget is used up.`;
     }
-    return `${line || String(fallback || 'This conversation reached its budget cap.')} Send /new to start a fresh conversation, or raise the cap in SynaBun.`;
+    return `${line || String(fallback || 'This conversation reached its budget.')} Send /new to start a fresh conversation, or raise the budget (or choose No limit) in SynaBun.`;
   }
 
   // ── lifecycle ──────────────────────────────────────────────────────────────
@@ -1484,14 +1528,14 @@ export function createWhatsAppBridge({
     persistBridgeState();
   }
 
-  // Keep the level in line with the config (Settings edits, the autonomous window running out).
+  // Keep the level in line with the config (a change that reached it without a refresh).
   state.policyTimer = T.setInterval(() => { try { runtime(); syncPolicies(); } catch {} }, L.policyTickMs);
   state.policyTimer?.unref?.();
   runtime();
 
   return {
     onInbound, onConnection, status, newSession, pause, resume, stopAll, shutdown,
-    // Settings changed (level, strict approvals, autonomous window): re-apply now instead of at the next tick.
+    // Settings changed (level, strict approvals, computer use): re-apply now instead of at the next tick.
     refresh: () => { state.policySeen.clear(); runtime(); syncPolicies(); return status(); },
     endComputerUse,
     _internals: { state, finalText, syncPolicies, drain, onPacket, brainTarget, moveOn },

package/neural-interface/lib/whatsapp/commands.js

@@ -2,10 +2,10 @@
 // SynaBun — WhatsApp Link: the owner's slash commands
 // ═══════════════════════════════════════════
 //
-// Pure parsing and fixed texts. A command is the owner's own text — never a
-// forwarded or quoted message — that starts with one of COMMANDS
-// (case-insensitive). Commands run at once, busy or paused. Any other "/x" is
-// a prompt; "//x" sends the literal "/x". No command raises the level or
+// Pure parsing and fixed texts. A command is the owner's own typed text —
+// never a forwarded or quoted message, never a voice note — that starts with
+// one of COMMANDS (case-insensitive). Commands run at once, busy or paused.
+// Any other "/x" is a prompt; "//x" sends the literal "/x". No command raises the level or
 // changes a setting: those names get a fixed refusal (they would otherwise
 // reach the brain's CLI as its own slash commands).
 
@@ -21,7 +21,7 @@ const REFUSED = new Set([
 
 export const HELP_TEXT = [
   '*SynaBun on WhatsApp*',
-  'Write to me like you would in SynaBun. Pictures work too.',
+  'Write to me like you would in SynaBun. Pictures work too, and voice notes when this computer can transcribe them.',
   '',
   '/status — what I am doing, spend and level',
   '/stop — stop the current task, its agents and anything waiting for your answer',
@@ -31,7 +31,7 @@ export const HELP_TEXT = [
   '/cards — ask again what is still waiting for your answer',
   '/help — this list',
   '',
-  'When I ask something, just answer in your own words. An approval takes a plain yes or no; any other message approves nothing and carries on the conversation. Start with // to send text that begins with a slash.',
+  'When I ask something, just answer in your own words. An approval takes a plain yes or no, typed; any other message (a voice note too) approves nothing and carries on the conversation. Start with // to send text that begins with a slash.',
   'Levels, models and other settings change only in SynaBun on your computer (Settings → WhatsApp).',
 ].join('\n');
 
@@ -40,10 +40,10 @@ export const SETTINGS_REFUSAL = 'Settings change only in SynaBun on your compute
 /**
  * An inbound message → { kind: 'command', name, args } | { kind: 'refused', name }
  * | { kind: 'literal', text } ("//x" → "/x") | null (not a command: a prompt).
- * Only the owner's own text counts: forwarded or quoted messages are prompts.
+ * Only the owner's own typed text counts: forwarded or quoted messages and voice notes are prompts.
  */
 export function parseCommand(message) {
-  if (!message || message.owner === false || message.forwarded || message.quoted) return null;
+  if (!message || message.owner === false || message.forwarded || message.quoted || message.voice === true) return null;
   const text = String(message.text ?? '').trim();
   if (!text.startsWith('/')) return null;
   if (text.startsWith('//')) return { kind: 'literal', text: text.slice(1) };
@@ -66,8 +66,8 @@ function levelLabel(level) {
 
 /**
  * /status text from a snapshot: { connected, sessionId, title, brain:{provider,model},
- * running, turnKind, queued, pendingCards, currentCard, budget:{totalUsd, hardUsd},
- * brainUsd, brainCapUsd, level, paused, pausedBy, autonomousUntil }.
+ * running, turnKind, queued, pendingCards, currentCard, budget:{ unlimited, totalUsd, amountUsd, leftUsd },
+ * brainUsd, level, paused, pausedBy }. Autonomous has no time limit: it holds until it is turned off in Settings.
  */
 export function statusText(s = {}) {
   const lines = ['*SynaBun status*'];
@@ -83,10 +83,9 @@ export function statusText(s = {}) {
     : 'idle';
   lines.push(`Now: ${doing}${s.queued ? ` · ${s.queued} message${s.queued === 1 ? '' : 's'} queued` : ''}`);
   if (s.pendingCards) lines.push(`Waiting for you: ${s.pendingCards} question${s.pendingCards === 1 ? '' : 's'} or approval${s.pendingCards === 1 ? '' : 's'}${s.currentCard ? ` (${s.currentCard})` : ''} — /cards asks again`);
-  if (s.budget && Number.isFinite(Number(s.budget.hardUsd))) lines.push(`Spend: ${usd(s.budget.totalUsd)} of ${usd(s.budget.hardUsd)} session cap${Number.isFinite(Number(s.brainCapUsd)) ? ` (brain ${usd(s.brainUsd)} of ${usd(s.brainCapUsd)})` : ''}`);
-  let level = `Level: ${levelLabel(s.level)}`;
-  if (s.level === 'autonomous' && s.autonomousUntil) level += ` until ${new Date(Number(s.autonomousUntil)).toTimeString().slice(0, 5)}`;
-  lines.push(level);
+  if (s.budget?.unlimited === true) lines.push(`Spend: ${usd(s.budget.totalUsd)} (no limit)`);
+  else if (s.budget && Number.isFinite(Number(s.budget.amountUsd))) lines.push(`Spend: ${usd(s.budget.totalUsd)} of the ${usd(s.budget.amountUsd)} budget${Number.isFinite(Number(s.brainUsd)) ? ` (brain ${usd(s.brainUsd)})` : ''}`);
+  lines.push(`Level: ${levelLabel(s.level)}${s.level === 'autonomous' ? ' until turned off' : ''}`);
   if (s.paused) lines.push(`Paused${s.pausedBy === 'desktop' ? ' from your computer' : ''} — ${s.pausedBy === 'desktop' ? 'resume it in SynaBun' : 'send /resume'}`);
   return lines.join('\n');
 }

package/neural-interface/lib/whatsapp/config.js

@@ -10,12 +10,17 @@
 // Two kinds of fields:
 //   user     what Settings edits (update(), validated, versioned: a stale
 //            expectedVersion is a 409 like lib/assistant-config.js)
-//   service  what SynaBun owns (mode, the conversation, the bound owner, the
-//            autonomous window, pause) — written by the service and the
-//            bridge through write(), refused in update().
+//   service  what SynaBun owns (mode, the conversation, the bound owner,
+//            pause) — written by the service and the bridge through
+//            write(), refused in update().
 // Raising the level to 'autonomous' never applies here: update() needs
 // confirmEscalation and answers {pending:true}; the service applies it after
-// the phone answers "ALLOW <code>". Lowering applies at once.
+// the phone answers "ALLOW <code>". Lowering applies at once. Autonomous then
+// stays on until the owner lowers it in Settings, restarts included: there is
+// no time limit. `autonomousUntil` is a legacy field (the end of the 8-hour
+// window of 2.0.5 and before): a level 'autonomous' stored with one was turned
+// on under that rule and is read as 'ask' (migrateLegacyAutonomous), so an
+// update never puts anyone back into Autonomous.
 // `computerUse` is the owner's switch for controlling this Mac from a
 // WhatsApp conversation: off by default, a plain boolean, changed only through
 // update() (Settings on this computer: the guarded PUT /api/whatsapp/config).
@@ -25,9 +30,19 @@
 // Assistant) or { provider, model, effort }. Its shape is checked here; the
 // service checks the model and the effort against the Assistant's catalog
 // before it calls update() (lib/whatsapp/brain.js).
+// Voice notes (lib/whatsapp/transcription.js): `transcriptionEnabled`, the
+// spoken `transcriptionLanguage` ('auto' or a 2-3 letter code) and three
+// paths, '' meaning "find it by itself": the whisper-cli program, the ggml
+// model and FFmpeg. A path is the absolute path of an existing regular file
+// (a program executable), checked when update() stores it and again by the
+// host right before it runs; it is never looked up on PATH. Only update()
+// (Settings on this computer) sets a path: a service write may only clear one,
+// so nothing but the person at this computer chooses what the host runs.
 
 import { LEVELS } from '../remote-policy.js';
 import { cleanBrainChoice } from './brain.js';
+import { TRANSCRIPTION_LANGUAGE_RE } from './protocol.js';
+import { checkToolPath } from './transcription.js';
 
 export const WHATSAPP_CONFIG_KEY = 'whatsapp_config';
 
@@ -44,6 +59,11 @@ export const USER_DEFAULTS = Object.freeze({
   strictWorkerApprovals: false,
   computerUse: false,
   brain: null,
+  transcriptionEnabled: true,
+  transcriptionLanguage: 'auto',
+  transcriptionEnginePath: '',
+  transcriptionModelPath: '',
+  transcriptionFfmpegPath: '',
 });
 
 export const SERVICE_DEFAULTS = Object.freeze({
@@ -51,7 +71,7 @@ export const SERVICE_DEFAULTS = Object.freeze({
   sessionId: null,
   previousSessionIds: Object.freeze([]),
   owner: null,              // { masked, boundAt, via } — never a number
-  autonomousUntil: null,    // epoch ms while an autonomous window is open
+  autonomousUntil: null,    // legacy: the end of 2.0.5's 8-hour Autonomous window; always null now (migrateLegacyAutonomous)
   paused: false,
   pausedBy: null,           // 'desktop' | 'phone'
   version: 0,
@@ -68,6 +88,11 @@ export const ROTATIONS = Object.freeze(['idle6h', 'daily', 'never']);
 export const SELF_TRIGGERS = Object.freeze(['all', 'prefix']);
 export const MODES = Object.freeze(['self', 'dedicated']);
 export const REPLY_LABEL_MAX = 24;
+/** The voice-note settings the host gets (service prefsOf → protocol.js PREFS_SPEC). */
+export const TRANSCRIPTION_FIELDS = Object.freeze(['transcriptionEnabled', 'transcriptionLanguage', 'transcriptionEnginePath', 'transcriptionModelPath', 'transcriptionFfmpegPath']);
+/** The path fields and what each must name (transcription.js checkToolPath). */
+export const TOOL_PATH_FIELDS = Object.freeze({ transcriptionEnginePath: 'program', transcriptionModelPath: 'file', transcriptionFfmpegPath: 'program' });
+const TOOL_PATH_MAX = 4096;
 
 const RANK = Object.freeze({ 'read-only': 0, ask: 1, autonomous: 2 });
 
@@ -81,6 +106,28 @@ function configError(field, message, { code = 'CONFIG_INVALID', status = 400 } =
   return error;
 }
 
+/** A tool path's shape: '' (find it by itself) or an absolute path of one line; undefined when it has neither shape. */
+function cleanToolPath(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value !== 'string') return undefined;
+  const text = value.trim();
+  if (!text) return '';
+  if (text.length > TOOL_PATH_MAX || /[\u0000-\u001f\u007f]/.test(text)) return undefined;
+  return checkToolPath(text, 'program', { fs: SHAPE_ONLY_FS }) === 'not_absolute' ? undefined : text;
+}
+// checkToolPath against nothing on disk: only its shape rules run (absolute, not a network path).
+const SHAPE_ONLY_FS = Object.freeze({ statSync: () => { throw new Error('shape only'); }, accessSync: () => {}, constants: {} });
+
+const TOOL_PATH_PROBLEMS = Object.freeze({
+  not_absolute: 'must be an absolute path (it is never looked up on PATH)',
+  network: 'must be a path on this computer, not on a network share',
+  missing: 'names a file that does not exist',
+  not_file: 'must name a regular file',
+  not_executable: process.platform === 'win32' ? 'must name a program (.exe)' : 'names a file that is not executable (chmod +x it)',
+  unreadable: 'names a file this account cannot read',
+  empty: 'names an empty file',
+});
+
 /** A reply label: printable, one line, 1-24 characters; '' → null (the mode's default label). */
 function cleanLabel(value) {
   if (value === null || value === undefined) return null;
@@ -102,6 +149,8 @@ const CHECKS = {
   activityText: (v) => typeof v === 'boolean',
   strictWorkerApprovals: (v) => typeof v === 'boolean',
   computerUse: (v) => typeof v === 'boolean',
+  transcriptionEnabled: (v) => typeof v === 'boolean',
+  transcriptionLanguage: (v) => typeof v === 'string' && TRANSCRIPTION_LANGUAGE_RE.test(v),
 };
 const MESSAGES = {
   enabled: 'enabled must be true or false',
@@ -116,10 +165,21 @@ const MESSAGES = {
   strictWorkerApprovals: 'strictWorkerApprovals must be true or false',
   computerUse: 'computerUse must be true or false',
   brain: 'brain must be null (same as the Assistant) or { provider, model, effort } with a provider of claude-code, codex or opencode',
+  transcriptionEnabled: 'transcriptionEnabled must be true or false',
+  transcriptionLanguage: "transcriptionLanguage must be 'auto' or a 2-3 letter lowercase language code, such as en or pt",
+  transcriptionEnginePath: 'transcriptionEnginePath must be empty (find whisper-cli by itself) or the absolute path of the whisper-cli program',
+  transcriptionModelPath: 'transcriptionModelPath must be empty (ggml-small.bin in the transcription folder) or the absolute path of a whisper.cpp model file',
+  transcriptionFfmpegPath: 'transcriptionFfmpegPath must be empty (find ffmpeg by itself) or the absolute path of the ffmpeg program',
 };
 
-/** Validate a user patch (Settings fields only). → the cleaned patch; throws 400 CONFIG_INVALID {field}. */
-export function validateConfigPatch(patch = {}) {
+/** Whether a tool path can be used on this computer: null, or why not (transcription.js checkToolPath). */
+const defaultCheckPath = (value, kind) => checkToolPath(value, kind);
+
+/**
+ * Validate a user patch (Settings fields only). → the cleaned patch; throws 400 CONFIG_INVALID {field}.
+ * `checkPath(value, kind)` → null or a problem: how a tool path is checked on disk (tests pass a fake).
+ */
+export function validateConfigPatch(patch = {}, { checkPath = defaultCheckPath } = {}) {
   if (!isPlainObject(patch)) throw configError('config', 'config must be an object');
   const out = {};
   for (const [key, value] of Object.entries(patch)) {
@@ -138,6 +198,14 @@ export function validateConfigPatch(patch = {}) {
       out.brain = brain;
       continue;
     }
+    if (TOOL_PATH_FIELDS[key]) {
+      const toolPath = cleanToolPath(value);
+      if (toolPath === undefined) throw configError(key, MESSAGES[key]);
+      const problem = toolPath ? checkPath(toolPath, TOOL_PATH_FIELDS[key]) : null;
+      if (problem) throw configError(key, `${key} ${TOOL_PATH_PROBLEMS[problem] || 'names a file that cannot be used'}: ${toolPath}`);
+      out[key] = toolPath;
+      continue;
+    }
     if (!CHECKS[key](value)) throw configError(key, MESSAGES[key]);
     out[key] = value;
   }
@@ -157,13 +225,28 @@ function cleanOwner(value) {
   return { masked, boundAt: toMs(value.boundAt), via: value.via === 'claim' ? 'claim' : 'self_confirm' };
 }
 
+/**
+ * A level 'autonomous' stored with an `autonomousUntil` (any value but null) was turned on under
+ * the 8-hour rule of 2.0.5 and before, whether that window is still open or not: it does not
+ * become Autonomous without a time limit. → the stored value as level 'ask' with no
+ * autonomousUntil, or null when `stored` is not such a value. Autonomous stored with
+ * autonomousUntil null is today's state and stays.
+ */
+export function migrateLegacyAutonomous(stored) {
+  if (!isPlainObject(stored) || stored.level !== 'autonomous') return null;
+  if (stored.autonomousUntil === null || stored.autonomousUntil === undefined) return null;
+  return { ...stored, level: 'ask', autonomousUntil: null };
+}
+
 /** Defaults + stored values; a bad stored value falls back to its default, field by field. */
 export function effectiveConfig(stored = {}) {
-  const raw = isPlainObject(stored) ? stored : {};
+  const raw = isPlainObject(stored) ? migrateLegacyAutonomous(stored) || stored : {};
   const out = {};
   for (const key of USER_FIELDS) {
     if (key === 'replyLabel') { const label = cleanLabel(raw.replyLabel); out.replyLabel = label === undefined ? null : label; continue; }
     if (key === 'brain') { const brain = cleanBrainChoice(raw.brain); out.brain = brain === undefined ? null : brain; continue; }
+    // A stored path keeps its shape only: whether the file still works is the host's check, right before it runs.
+    if (TOOL_PATH_FIELDS[key]) { const toolPath = cleanToolPath(raw[key]); out[key] = toolPath === undefined ? '' : toolPath; continue; }
     out[key] = raw[key] !== undefined && CHECKS[key](raw[key]) ? raw[key] : USER_DEFAULTS[key];
   }
   out.mode = MODES.includes(raw.mode) ? raw.mode : SERVICE_DEFAULTS.mode;
@@ -172,7 +255,7 @@ export function effectiveConfig(stored = {}) {
     ? raw.previousSessionIds.map((id) => (typeof id === 'string' ? id : id?.id)).filter((id) => typeof id === 'string' && id).slice(0, 10)
     : [];
   out.owner = cleanOwner(raw.owner);
-  out.autonomousUntil = toMs(raw.autonomousUntil);
+  out.autonomousUntil = null; // legacy: Autonomous has no time limit (migrateLegacyAutonomous)
   out.paused = raw.paused === true;
   out.pausedBy = out.paused && (raw.pausedBy === 'desktop' || raw.pausedBy === 'phone') ? raw.pausedBy : null;
   out.version = Number.isSafeInteger(raw.version) && raw.version >= 0 ? raw.version : 0;
@@ -181,18 +264,23 @@ export function effectiveConfig(stored = {}) {
   return out;
 }
 
-/** 'autonomous' only while its window is open; an expired window reads as 'ask'. */
-export function currentLevel(config, now = Date.now()) {
-  if (config?.level !== 'autonomous') return LEVELS.includes(config?.level) ? config.level : 'ask';
-  return toMs(config.autonomousUntil) > now ? 'autonomous' : 'ask';
+/**
+ * The configured level ('ask' when it is not a known one). Autonomous has no time limit: it
+ * holds until the owner lowers it. A legacy 8-hour Autonomous (migrateLegacyAutonomous) is 'ask'.
+ */
+export function currentLevel(config) {
+  if (migrateLegacyAutonomous(config)) return 'ask';
+  return LEVELS.includes(config?.level) ? config.level : 'ask';
 }
 
 /**
  * @param {object} deps
  * @param {(key:string)=>string|null} deps.get   getKvConfig
  * @param {(key:string, value:string)=>void} deps.set  setKvConfig
+ * @param {() => void} [deps.onLegacyAutonomous]  a legacy 8-hour Autonomous was stored as Ask (once, after it was saved)
+ * @param {(value:string, kind:'program'|'file') => string|null} [deps.checkPath]  how update() checks a tool path on disk
  */
-export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.now, log = () => {} } = {}) {
+export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.now, log = () => {}, onLegacyAutonomous = null, checkPath = defaultCheckPath } = {}) {
   let cache = null; // { at, value }
 
   function readStored() {
@@ -202,12 +290,34 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
     if (!raw) return {};
     try {
       const value = JSON.parse(raw);
-      return isPlainObject(value) ? value : {};
+      return isPlainObject(value) ? migrateStored(value) : {};
     } catch (error) {
       log('whatsapp:config-corrupt', error?.message || String(error));
       return {};
     }
   }
+  /**
+   * A legacy 8-hour Autonomous (migrateLegacyAutonomous) found by any read is stored as Ask at
+   * once, with the version bumped (an open Settings tab reloads before it saves), and reported
+   * once. A store that cannot be written still reads it as Ask, and tries again at the next read.
+   */
+  function migrateStored(value) {
+    const migrated = migrateLegacyAutonomous(value);
+    if (!migrated) return value;
+    const version = Number.isSafeInteger(value.version) && value.version >= 0 ? value.version : 0;
+    const next = { ...migrated, version: version + 1 };
+    try {
+      if (typeof set !== 'function') return next;
+      set(WHATSAPP_CONFIG_KEY, JSON.stringify(next));
+    } catch (error) {
+      log('whatsapp:config-unwritable', `the earlier Autonomous could not be stored as Ask: ${error?.message || String(error)}`);
+      return next;
+    }
+    cache = null;
+    log('whatsapp:config-migrated', 'Autonomous from an earlier version (8-hour window) ended; the level is Ask');
+    try { onLegacyAutonomous?.(); } catch {}
+    return next;
+  }
   function persist(value) {
     if (typeof set === 'function') set(WHATSAPP_CONFIG_KEY, JSON.stringify(value));
     cache = null;
@@ -221,8 +331,8 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
 
   /**
    * Service-owned write: service fields, internal state and user fields the
-   * service decides (the confirmed autonomous level, its expiry). A change to
-   * a user field bumps the version so an open Settings tab reloads first.
+   * service decides (the confirmed autonomous level). A change to a user field
+   * bumps the version so an open Settings tab reloads first.
    */
   function write(patch = {}) {
     if (!isPlainObject(patch)) return read();
@@ -239,6 +349,10 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
       if (key === 'version') continue;
       // Computer use is turned on by the person at this computer only (update()); the service may only turn it off.
       if (key === 'computerUse' && value !== false) { log('whatsapp:config-ignored', 'computerUse is turned on in Settings only'); continue; }
+      // What the host runs (whisper-cli, FFmpeg) and the model it loads are chosen in Settings only; a service write may clear them.
+      if (TOOL_PATH_FIELDS[key] && value !== '' && value !== null) { log('whatsapp:config-ignored', `${key} is set in Settings only`); continue; }
+      // A legacy field: Autonomous has no time limit, so nothing writes an expiry (only null, which clears it).
+      if (key === 'autonomousUntil' && value !== null) { log('whatsapp:config-ignored', 'autonomousUntil is a legacy field: Autonomous has no time limit'); continue; }
       next[key] = value;
       if (USER_FIELDS.includes(key) && JSON.stringify(effectiveConfig(next)[key]) !== JSON.stringify(before[key])) userChanged = true;
     }
@@ -253,7 +367,7 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
    * level waits for the phone (the service holds the escalation).
    */
   function update(patch = {}, { expectedVersion = null, confirmEscalation = false } = {}) {
-    const clean = validateConfigPatch(patch);
+    const clean = validateConfigPatch(patch, { checkPath });
     const stored = readStored();
     const current = effectiveConfig(stored);
     if (expectedVersion !== null && expectedVersion !== undefined && Number(expectedVersion) !== current.version) {
@@ -263,7 +377,7 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
     }
     let pending = false;
     if (clean.level !== undefined) {
-      const effective = currentLevel(current, now());
+      const effective = currentLevel(current);
       if (clean.level === 'autonomous') {
         if (effective !== 'autonomous') {
           if (confirmEscalation !== true) throw configError('level', 'Autonomous needs a second confirmation on this computer, then an ALLOW code from your phone.', { code: 'CONFIRM_REQUIRED' });
@@ -271,7 +385,7 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
         }
         delete clean.level;
       } else if (RANK[clean.level] < RANK[effective] || clean.level !== current.level) {
-        // Lowering (or leaving an expired autonomous) applies at once and closes the window.
+        // Lowering applies at once (and clears the legacy autonomousUntil).
         clean.autonomousUntil = null;
       }
     }