@empirical-gauzza/cli 1.0.35 → 1.0.37

package/lib/setupCommands.js

@@ -12,70 +12,595 @@ const { httpJson, printApiError } = require('./http');
 const { parseOption } = require('./env');
 const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
 const { warn, log, createPrompter } = require('./ui');
+const { resetLabel, confirmCostOrExit, isCostPreview, isInteractiveTerminal } = require('./empiricalTokensFormat');
+
+// What to do with a saved voice once it is installed. The same commands and the same standing
+// instruction the portal and the install status show (packages/shared/src/voiceInstall.ts); the CLI
+// package ships on its own, so the text is repeated here and tests/unit/cli/voicePluginOffer.test.js
+// keeps the two copies equal.
+const VOICE_PLUGIN_COMMANDS = {
+  claude: ['claude plugin marketplace add mattgauzza/empirical-memory-plugin', 'claude plugin install empirical-voice@empirical-memory --scope user'],
+  codex: ['codex marketplace add mattgauzza/empirical-memory-plugin', 'codex plugin add empirical-voice@empirical-memory']
+};
+const VOICE_STANDING_INSTRUCTION = "Before you write anything I will send or publish as myself, look up my writing voice first: call query_memories with the query 'how this person writes', tags ['writing-voice'], topK 50, and follow those rules.";
 
 function apiUrl(pathSuffix) {
   return new URL(`/api/v1/guided-setups${pathSuffix}`, resolveApiBaseUrl()).toString();
 }
 
-async function callApi(method, pathSuffix, body) {
+// The session id a request path names, for the recovery hints below.
+function sessionIdFromPath(pathSuffix) {
+  const m = /^\/([^/]+)\//.exec(String(pathSuffix || ''));
+  return m ? decodeURIComponent(m[1]) : '';
+}
+
+// The stale-draft hint depends on where the person is: rebuild at the topic step returns to the
+// topic step, at the review it returns to the review.
+function draftStaleHint(resume, sid, step) {
+  if (/^vc\d+_topic$/.test(step)) {
+    return `This draft is out of date, so no sample can be written from it. Answer this step with rebuild (empirical setup answer ${sid} ${step} rebuild), then pick a topic again or skip.`;
+  }
+  if (step === 'q5_confirm' || step === 'confirm') {
+    return `This draft is out of date. Rebuild it with empirical setup answer ${sid} q5_confirm rebuild, then read the new draft and confirm that one.`;
+  }
+  return `This draft is out of date. Run ${resume} to see the current question, answer it with rebuild, and go on from there.`;
+}
+
+// Readable next steps for the refusals a text client can recover from. The server message says
+// what happened; these lines say which command to run. A stale-key refusal does not name the
+// current question, so the hint points at `setup resume`, which prints it with its key.
+function recoveryHints(error, sessionId, step = '') {
+  const sid = sanitizeForTerminal(sessionId || '<sessionId>');
+  const resume = `empirical setup resume ${sid}`;
+  switch (error && error.code) {
+    case 'GUIDED_SETUP_VOICE_NOT_WAITING':
+    case 'GUIDED_SETUP_VOICE_STALE':
+      return [`See the current question and its key with: ${resume}`];
+    case 'GUIDED_SETUP_VOICE_BUSY':
+      return [`Wait a moment, then pick it up with: ${resume}`];
+    case 'EMPIRICAL_TOKENS_ATTEMPT_CLOSED':
+      return ['This attempt is already closed, so it cannot be continued. Start a new one with: empirical setup run <setupId>'];
+    case 'EMPIRICAL_TOKEN_KEY_OWNER_MISMATCH':
+      return ['This request was made with a key that belongs to a different account than the one you are signed in as. Sign in with the account that started it, then try again.'];
+    case 'PLAN_CHANGE_FAILED':
+      return ['Your plan change did not go through. Check your plan, then try again.'];
+    case 'TRIAL_END_IN_PROGRESS':
+      return ['Your trial is ending right now. Wait a minute, then try again.'];
+    case 'PLAN_LIMIT_EMPIRICAL_TOKENS_REACHED':
+      return [tokensShortfallHint(error)];
+    case 'GUIDED_SETUP_DRAFT_STALE':
+      return [draftStaleHint(resume, sid, sanitizeForTerminal(step))];
+    case 'GUIDED_SETUP_DRAFT_CHANGED':
+      return [`Run ${resume} to read the latest draft and its hash (or finish the waiting step first), then confirm that draft.`];
+    case 'GUIDED_SETUP_NOT_READY_TO_CONFIRM':
+      return [`Finish the questions first. See where the setup is with: ${resume}`];
+    case 'GUIDED_SETUP_CONFIRM_REQUIRED':
+      return [`Installing is its own command: read the draft with ${resume}, then run empirical setup confirm ${sid} <draftHash>.`];
+    default:
+      return [];
+  }
+}
+
+// The 403's details carry remaining, needed and resetsAt. A partial shortfall (some left, not enough)
+// must not read as "used all", so the numbers are quoted when the server sent them.
+function tokensShortfallHint(error) {
+  const d = (error && error.details) || {};
+  const reset = resetLabel(d.resetsAt);
+  const known = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+  if (known(d.remaining) && known(d.needed)) {
+    return `You have ${d.remaining.toLocaleString('en-US')} left and this needs ${d.needed.toLocaleString('en-US')}.${reset ? ` They reset on ${reset}.` : ''}`;
+  }
+  return `There are not enough Empirical Tokens left this month.${reset ? ` They reset on ${reset}.` : ' They reset at the start of next month.'}`;
+}
+
+// The step a request was for: the question key it carried, or the confirm route.
+function stepOf(pathSuffix, body) {
+  if (body && typeof body.questionKey === 'string') return body.questionKey;
+  return /\/confirm$/.test(String(pathSuffix || '')) ? 'confirm' : '';
+}
+
+// A refund is stated once per run, in words. The server sends details.refunded as a boolean
+// (true = this attempt's Empirical Tokens were returned); a count line is used only for a
+// numeric value above one.
+let refundShown = false;
+function refundLine(error) {
+  const refunded = error && error.details && error.details.refunded;
+  if (refundShown) return null;
+  // Some refusals already say so in their own message ("Your Empirical Tokens for this attempt were
+  // returned."): the CLI line would only repeat it.
+  if (/\breturned\b/i.test(String((error && (error.serverMessage || error.message)) || ''))) return null;
+  if (refunded === true) {
+    refundShown = true;
+    return 'Your Empirical Tokens for this attempt were returned.';
+  }
+  if (typeof refunded === 'number' && Number.isFinite(refunded) && refunded > 1) {
+    refundShown = true;
+    return `${refunded.toLocaleString('en-US')} Empirical Tokens were returned to your balance.`;
+  }
+  return null;
+}
+
+function failWith(error, pathSuffix, body) {
+  printApiError(error);
+  for (const line of recoveryHints(error, sessionIdFromPath(pathSuffix), stepOf(pathSuffix, body))) warn(line);
+  const refund = refundLine(error);
+  if (refund) warn(refund);
+  process.exit(1);
+}
+
+async function tryApi(method, pathSuffix, body) {
   const accessToken = requireAccessToken();
   try {
     const response = await httpJson(apiUrl(pathSuffix), method, body, buildApiAuthHeaders(accessToken));
-    return response && response.data ? response.data : response;
+    return { data: response && response.data ? response.data : response };
   } catch (error) {
-    printApiError(error);
-    process.exit(1);
+    return { error };
   }
 }
 
+async function callApi(method, pathSuffix, body) {
+  const { data, error } = await tryApi(method, pathSuffix, body);
+  if (error) failWith(error, pathSuffix, body);
+  return data;
+}
+
+// The structured meter (progress.dimensions, which carries the person's quotes and answer text) and
+// the re-pick lists (progress.repick) are for the portal's chips only; the CLI shows the meter as
+// progress.meterLine. JSON.stringify leaves C1 controls unescaped, so they are escaped here.
+function forJsonOutput(result) {
+  if (!result || typeof result !== 'object' || !result.progress || typeof result.progress !== 'object') return result;
+  const { dimensions: _dimensions, repick: _repick, ...progress } = result.progress;
+  return { ...result, progress };
+}
+
+function printJson(value) {
+  log(JSON.stringify(forJsonOutput(value), null, 2).replace(/[\x80-\x9f]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`));
+}
+
 async function runList() {
   const { setups } = await callApi('GET', '', undefined);
-  log(JSON.stringify(setups, null, 2));
+  printJson(setups);
+}
+
+// Server and user text is printed to a terminal, so control sequences are removed first:
+// whole OSC and CSI sequences, then any remaining C0/C1 control character except newline and tab.
+function sanitizeForTerminal(value) {
+  return String(value === undefined || value === null ? '' : value)
+    .replace(/\u001b\][^\u0007\u001b\u009c]*(?:\u0007|\u001b\\|\u009c)?/g, '')
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g, '');
+}
+
+// What leaving the follow-up loop leads to (the server's question.next), in the person's words.
+const LOOP_EXIT_NEXT = {
+  avoid: 'two last steps (habits to rule out, and the common AI-writing tells), then a short sample in your voice',
+  tropes: 'one last step (the common AI-writing tells), then a short sample in your voice',
+  review: 'the draft, written for you to review'
+};
+
+function loopHint(question, progress) {
+  const after = LOOP_EXIT_NEXT[question.next];
+  if (progress.ready) {
+    return after ? `Type check to go on to ${after}, or keep answering.` : 'Type check to see a short sample in your voice, or keep answering.';
+  }
+  return after
+    ? `Type enough to stop here and go on to ${after}; with areas still missing the voice may come out inconsistent.`
+    : 'Type enough to stop here; with areas still missing the voice may come out inconsistent.';
+}
+
+// Voice questions as plain lines for a terminal. A preference round is a lettered list in the
+// server's order; only the letter and the text of each version are printed (blind choice: never
+// any other field of a version or the round). Every piece of server text is sanitised.
+function formatQuestionLines(question, progress = {}) {
+  const t = sanitizeForTerminal;
+  const p = progress || {};
+  const lines = [t(question.prompt)];
+  if (question.kind === 'voice_check') {
+    lines.push(`Sample on "${t(question.topic)}":`, ...String(question.passage || '').split('\n').map((l) => t(l)));
+  }
+  if (question.kind === 'prefer') {
+    if (question.situation) lines.push(`Situation: ${t(question.situation)}`);
+    for (const v of question.versions || []) {
+      lines.push(`${t(v.letter)})`, ...String(v.text || '').split('\n').map((l) => `   ${t(l)}`));
+    }
+  }
+  // A topic step on a stale draft refuses topics (the server writes no sample from it).
+  const staleTopic = question.kind === 'pick_or_write' && question.stale;
+  if (Array.isArray(question.options) && !staleTopic) {
+    for (const o of question.options) {
+      const description = o.description ? `: ${t(o.description)}` : '';
+      lines.push(`  ${t(o.id)}. ${t(o.title)}${description}`);
+    }
+  }
+  const key = String(question.questionKey || '');
+  if ((question.kind === 'text' && /^(g\d+|f_)/.test(key)) || question.kind === 'prefer') {
+    if (p.meterLine) lines.push(t(p.meterLine));
+    // During the rounds "enough" ends the comparisons only, and a question focused from the portal
+    // records whatever is typed, so the end-early hint belongs to the follow-up loop alone.
+    if (p.meterLine && question.kind === 'text' && /^g\d+$/.test(key) && !question.focus) lines.push(loopHint(question, p));
+  }
+  if (question.kind === 'pick_and_edit') lines.push('Reply with the numbers that fit, like 2,5, and optionally a | and your own changes.');
+  if (question.kind === 'pick_one') lines.push('Reply with one number.');
+  if (question.kind === 'yes_no') lines.push('Reply yes or no.');
+  if (staleTopic) {
+    lines.push('Your answers changed after this draft was written, so no sample can be written from it. Type rebuild to write a new draft first, or skip to go straight to the review.');
+  } else if (question.kind === 'pick_or_write') {
+    lines.push('Reply with one number, or a | and your own topic. Type skip to go straight to the review.');
+  }
+  if (question.kind === 'prefer') lines.push('Reply with one letter, like b, and optionally a | and why, like b | shorter is me. Type none if no version fits, skip for a different set, or enough to stop comparing.');
+  if (question.kind === 'voice_check') lines.push('Reply yes if it sounds like you, or no with the numbers of what is off and your own words after a |, like no 1,3 | too stiff.');
+  return lines;
+}
+
+// "Personal Workspace" is already a place; "Work" becomes "Work workspace".
+function workspacePlace(name) {
+  const n = String(name || '').trim() || 'selected';
+  return /\bworkspace$/i.test(n) ? n : `${n} workspace`;
+}
+
+function formatDraftLines(question, progress = {}) {
+  const t = sanitizeForTerminal;
+  const draft = question.draft || {};
+  const confirm = question.confirm || {};
+  const lines = [];
+  const place = t(workspacePlace(confirm.workspace && confirm.workspace.name));
+  const memoryCount = Number.isFinite(confirm.memoryCount) ? confirm.memoryCount : 0;
+  const replacesCount = Number.isFinite(confirm.replacesCount) ? confirm.replacesCount : 0;
+  lines.push(`Hub: ${t(draft.hub)}`);
+  // Rules the person did not write get their own labeled block with a plain reason (absent on an
+  // older server, which prints every rule in one list as before).
+  const fixed = Array.isArray(confirm.fixedRules) ? confirm.fixedRules : [];
+  const fixedTexts = new Set(fixed.map((f) => f.text));
+  for (const r of Array.isArray(draft.rules) ? draft.rules : []) {
+    if (fixedTexts.has(r.text)) continue;
+    lines.push(`- (${t(r.kind)}${r.context ? `, ${t(r.context)}` : ''}) ${t(r.text)}`);
+  }
+  if (fixed.length > 0) {
+    lines.push('Rules every voice keeps (you did not write these):');
+    for (const f of fixed) {
+      lines.push(`- ${t(f.text)}`);
+      lines.push(`  ${t(f.reason)}`);
+    }
+    if (fixed.some((f) => f.removable === true)) lines.push('To remove one that can be removed, type the change in your own words.');
+  }
+  lines.push(`${memoryCount} memories in your ${place}${replacesCount ? `; your current voice (${replacesCount} memories) will be replaced` : ''}.`);
+  if (confirm.fitsPlan === false) {
+    const free = Number.isFinite(confirm.free) ? confirm.free : 0;
+    lines.push(`Warning: this does not fit your plan. You have room for ${free} more memories, so the install will be refused until you upgrade for more memory or free up space under Manage memories in the portal.`);
+  }
+  if (confirm.stale) lines.push('Your answers changed after this draft was written. Type rebuild to write a new draft before installing.');
+  if (progress && progress.meterLine && progress.ready === false) lines.push(`${t(progress.meterLine)} The voice may come out inconsistent.`);
+  const vc = confirm.voiceCheck;
+  // The server refuses another check while the draft is stale or the checks are used up.
+  if (vc && vc.stale) {
+    lines.push(vc.canCheckAgain && !confirm.stale
+      ? 'The sample passage was written before your last change. Type check to see a new one.'
+      : 'The sample passage was written before your last change.');
+  }
+  return lines;
 }
 
-async function runNonInteractive(setupId, answersFilePath) {
+function printQuestion(question, progress) {
+  for (const line of formatQuestionLines(question, progress)) warn(line);
+}
+
+function printDraft(question, progress) {
+  for (const line of formatDraftLines(question, progress)) warn(line);
+}
+
+// `setup resume` and `setup answer` print the result as JSON on stdout; a voice question is also
+// printed as text on stderr, so a person can read the lettered list or the sample and answer it.
+function printCurrentQuestion(result) {
+  const question = result && result.question;
+  if (!question || !question.kind) return;
+  const sid = sanitizeForTerminal(result.sessionId);
+  const key = sanitizeForTerminal(question.questionKey);
+  if (question.kind !== 'confirm') {
+    printQuestion(question, result.progress);
+    warn(`Answer with: empirical setup answer ${sid} ${key} <your answer>`);
+    return;
+  }
+  printDraft(question, result.progress);
+  const confirm = question.confirm || {};
+  if (confirm.stale) {
+    warn(`Rebuild it with: empirical setup answer ${sid} ${key} rebuild`);
+  } else if (confirm.draftHash) {
+    warn(`Install this draft with: empirical setup confirm ${sid} ${sanitizeForTerminal(confirm.draftHash)}`);
+  }
+  warn(`Ask for a change with: empirical setup answer ${sid} ${key} <the change you want>`);
+}
+
+function printNothingInstalled(sessionId, draftHash) {
+  warn('Nothing was installed.');
+  if (sessionId && draftHash) {
+    warn('When you are ready, confirm this exact draft with:');
+    warn(`  empirical setup confirm ${sanitizeForTerminal(sessionId)} ${sanitizeForTerminal(draftHash)}`);
+  }
+}
+
+const TERMINAL_INSTALL_STATUSES = ['succeeded', 'failed', 'rolled_back', 'dead_letter', 'uninstalled'];
+
+// The voice is written by a background job. Poll the install status a bounded number of times;
+// EMPIRICAL_SETUP_POLL_MS shortens the delay for tests.
+async function fetchInstallStatus(installId) {
+  const attempts = 10;
+  const configured = process.env.EMPIRICAL_SETUP_POLL_MS;
+  const delayMs = configured !== undefined && Number(configured) >= 0 ? Number(configured) : 3000;
+  const url = new URL(`/api/v1/blueprints/installs/${encodeURIComponent(installId)}`, resolveApiBaseUrl()).toString();
+  for (let i = 0; i < attempts; i += 1) {
+    try {
+      const response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(requireAccessToken()));
+      const status = response && response.data ? response.data : response;
+      if (status && TERMINAL_INSTALL_STATUSES.includes(String(status.jobStatus))) return status;
+    } catch (error) {
+      return { error: true, message: error && error.message ? error.message : 'unknown error' };
+    }
+    if (i < attempts - 1) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  return null;
+}
+
+// Inside Claude Code the host is known; anywhere else the person says which one.
+function insideClaudeCode(env) {
+  return Boolean(env && (env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT));
+}
+
+// The existing `empirical plugin install <host> --voice` code path, loaded only when asked for.
+async function installVoiceSkillFor(host) {
+  const { runPluginCommand } = require('./pluginCommands');
+  await runPluginCommand(['install', host, '--voice']);
+}
+
+// Offered once, after the voice is installed, to a person at a terminal. Enter or anything but a
+// yes installs nothing. A failure never fails the setup that already succeeded: it says what to run.
+async function offerVoicePluginInstall({ prompter, env = process.env, install = installVoiceSkillFor, warn: say = warn }) {
+  const reply = String(await prompter.askText('Install the voice skill into Claude Code/Codex now? (y/N)')).trim();
+  if (!/^(y|yes)$/i.test(reply)) return false;
+  let hosts = ['claude'];
+  if (!insideClaudeCode(env)) {
+    const which = String(await prompter.askText('Which one? Type claude, codex, or both (Enter for both)')).trim().toLowerCase();
+    hosts = which === 'claude' ? ['claude'] : which === 'codex' ? ['codex'] : ['claude', 'codex'];
+  }
+  let ok = true;
+  for (const host of hosts) {
+    try {
+      await install(host);
+    } catch (error) {
+      ok = false;
+      say(`Could not install the voice skill into ${host}: ${sanitizeForTerminal(error && error.message ? error.message : 'unknown error')}`);
+      say('Run these yourself, in order:');
+      for (const line of VOICE_PLUGIN_COMMANDS[host]) say(`  ${line}`);
+    }
+  }
+  return ok;
+}
+
+// offer: { prompter } when a person at a terminal ran the interview; absent for scripted runs.
+async function reportConfirmed(result, offer) {
+  if (result && result.message) log(sanitizeForTerminal(result.message));
+  const installId = result && result.installId;
+  if (!installId) return;
+  const status = await fetchInstallStatus(installId);
+  if (status && status.error) {
+    log(`Could not check on the install right now (${sanitizeForTerminal(status.message)}). Check it later with:`);
+    log(`  empirical blueprint status ${sanitizeForTerminal(installId)}`);
+    return;
+  }
+  if (status && status.jobStatus === 'succeeded') {
+    if (Array.isArray(status.nextPrompts) && status.nextPrompts.length > 0) {
+      log('');
+      log('Your voice is installed. Prompts you can use right away:');
+      status.nextPrompts.forEach((p, i) => log(`${i + 1}. ${sanitizeForTerminal(p)}`));
+    } else {
+      log('Your voice is installed.');
+    }
+    // The prompts above work in any assistant. In a coding agent the optional plugin does it
+    // automatically, so show the install commands the person can paste (nothing here is sent to a model).
+    log('');
+    log('In Claude Code or Codex, the optional empirical-voice plugin makes your agent use this voice automatically. Run these in order:');
+    for (const line of [...VOICE_PLUGIN_COMMANDS.claude, ...VOICE_PLUGIN_COMMANDS.codex]) log(`  ${line}`);
+    log('');
+    log('In a chat assistant such as ChatGPT or Claude.ai there is no skill to install. Save this once in its custom instructions or memory:');
+    log(`  ${VOICE_STANDING_INSTRUCTION}`);
+    if (offer && offer.prompter && isInteractiveTerminal()) {
+      log('');
+      await offerVoicePluginInstall({ prompter: offer.prompter });
+    }
+    return;
+  }
+  if (status) {
+    log(`The install did not finish: ${sanitizeForTerminal(status.jobStatus)}${status.failureReason ? ` (${sanitizeForTerminal(status.failureReason)})` : ''}.`);
+    return;
+  }
+  log('Your voice is still being written. Check on it later with:');
+  log(`  empirical blueprint status ${sanitizeForTerminal(installId)}`);
+}
+
+// Spec 7.3: a priced setup returns a cost preview first. Acceptance is sent only from the explicit
+// --accept-cost flag; a first call without it stops at the cost and starts nothing. A person at a
+// terminal is asked instead, and a non-interactive run stops.
+async function startWithCost(setupId, { acceptCost, prompter }) {
+  const first = await callApi('POST', '/start', acceptCost ? { setupId, acceptEmpiricalTokenCost: true } : { setupId });
+  if (!isCostPreview(first)) return reportTokensUsed(first);
+  await confirmCostOrExit(first, { prompter, warn, sanitize: sanitizeForTerminal });
+  return reportTokensUsed(await callApi('POST', '/start', { setupId, acceptEmpiricalTokenCost: true }));
+}
+
+// After a paid start, say what it cost, but only when the response carries the amount. stderr, so
+// the JSON the command prints on stdout stays parseable.
+function reportTokensUsed(result) {
+  const used = result && result.empiricalTokensCharged;
+  if (typeof used === 'number' && used > 0) warn(`Used ${used.toLocaleString('en-US')} Empirical Tokens.`);
+  return result;
+}
+
+async function runNonInteractive(setupId, answersFilePath, acceptCost) {
   const raw = fs.readFileSync(path.resolve(answersFilePath), 'utf8');
   const answersByQuestionKey = JSON.parse(raw);
 
-  let current = await callApi('POST', '/start', { setupId });
+  let current = await startWithCost(setupId, { acceptCost, prompter: null });
+  let confirmed = false;
 
-  while (current.status !== 'completed' && current.status !== 'finished_early') {
-    const questionKey = current.question.questionKey;
-    if (!Object.prototype.hasOwnProperty.call(answersByQuestionKey, questionKey)) {
-      warn(`Answers file is missing an answer for unknown question "${questionKey}"`);
-      process.exit(1);
+  while (current.question && current.status !== 'completed' && current.status !== 'finished_early') {
+    const question = current.question;
+    const questionKey = question.questionKey;
+    if (question.kind === 'confirm') {
+      // Confirming is its own step: only an explicit "confirm" for q5_confirm installs, never a stale draft.
+      const stale = Boolean(question.confirm && question.confirm.stale);
+      if (answersByQuestionKey[questionKey] === 'confirm' && !stale) {
+        current = await callApi('POST', `/${current.sessionId}/confirm`, { draftHash: question.confirm.draftHash });
+        confirmed = true;
+      } else if (stale) {
+        warn('This draft is out of date. Answer q5_confirm with rebuild first:');
+        warn(`  empirical setup answer ${sanitizeForTerminal(current.sessionId)} q5_confirm rebuild`);
+      }
+      break; // otherwise stop here and print the draft and its hash below
+    }
+    let answer;
+    if (Object.prototype.hasOwnProperty.call(answersByQuestionKey, questionKey)) {
+      answer = answersByQuestionKey[questionKey];
+    } else {
+      answer = scriptedDefault(question);
+      if (answer === undefined) {
+        warn(`Answers file is missing an answer for unknown question "${sanitizeForTerminal(questionKey)}"`);
+        process.exit(1);
+      }
+      warn(`No answer for ${sanitizeForTerminal(questionKey)} in the answers file, so the run sends ${answer}.`);
     }
-    current = await callApi('POST', `/${current.sessionId}/continue`, { answer: answersByQuestionKey[questionKey] });
+    current = await callApi('POST', `/${current.sessionId}/continue`, answerBody(question, answer));
   }
 
-  log(JSON.stringify(current, null, 2));
+  if (confirmed) return reportConfirmed(current);
+  exitIfBusy(current);
+  printJson(current);
+}
+
+// Every answer carries the key of the question it answers, so an answer meant for a question that
+// moved on (another window, a resend) is refused instead of being saved on the current one: a
+// round pick saved on the wrong round would be false evidence.
+function answerBody(question, answer) {
+  return question && question.questionKey ? { answer, questionKey: question.questionKey } : { answer };
+}
+
+// An active session with no question means a step is still being worked on (a model call can take
+// a minute). That is not a finished run: say so and exit non-zero.
+function exitIfBusy(result) {
+  if (!result || result.status !== 'active' || result.question) return;
+  warn('The setup is busy finishing the last step. Wait a moment, then run:');
+  warn(`  empirical setup resume ${sanitizeForTerminal(result.sessionId)}`);
+  process.exit(1);
 }
 
-async function runInteractive(setupId) {
+// Answers files written before Phase 2 have no keys for the preference rounds (p1, p2, ...) or
+// the voice check (vc1_topic, vc1, ...). Those steps are optional, so a missing key ends the
+// comparisons or skips the check and the run still reaches the confirm step. A stranded step
+// (retry) is finished with retry.
+function scriptedDefault(question) {
+  const key = String(question.questionKey || '');
+  if (question.kind === 'prefer' && /^p\d+$/.test(key)) return 'enough';
+  if (question.kind === 'pick_or_write' && /^vc\d+_topic$/.test(key)) return 'skip';
+  if (question.kind === 'voice_check' && /^vc\d+$/.test(key)) return 'skip';
+  // A step stranded by a failed model call: any reply finishes it.
+  if (key === 'retry') return 'retry';
+  return undefined;
+}
+
+const MAX_EMPTY_REPLIES = 3;
+
+// An answer the server refuses at a terminal (a mistyped letter, a stale draft, a question that
+// moved on in another window) is explained and the current question is read again, instead of
+// ending the whole interview. Other failures (plan, sign-in, server errors) still stop the run.
+async function sendInteractiveAnswer(current, answer) {
+  const pathSuffix = `/${current.sessionId}/continue`;
+  const body = answerBody(current.question, answer);
+  const { data, error } = await tryApi('POST', pathSuffix, body);
+  if (!error) return data;
+  if (error.statusCode !== 400 && error.statusCode !== 409) failWith(error, pathSuffix, body);
+  if (error.code === 'GUIDED_SETUP_CONFIRM_REQUIRED') warn('To install this draft, type yes.');
+  else warn(sanitizeForTerminal(error.serverMessage || error.message));
+  return callApi('POST', pathSuffix, {});
+}
+
+async function runInteractive(setupId, acceptCost) {
   const prompter = createPrompter(process.stderr);
+  let abortMessage = null;
+  let finalResult = null;
+  let confirmed = false;
   try {
-    let current = await callApi('POST', '/start', { setupId });
+    let current = await startWithCost(setupId, { acceptCost, prompter });
+    if (!current) return;
+    let emptyReplies = 0;
     while (current.question && current.status !== 'completed' && current.status !== 'finished_early') {
-      const answer = await prompter.askText(current.question.prompt);
-      current = await callApi('POST', `/${current.sessionId}/continue`, { answer });
+      const question = current.question;
+      if (question.kind === 'confirm') {
+        printDraft(question, current.progress);
+        const reply = (await prompter.askText('Install this? (type yes to install, or type a change you want)')).trim();
+        if (!reply) {
+          const sessionId = current.sessionId;
+          abortMessage = () => printNothingInstalled(sessionId, question.confirm && question.confirm.draftHash);
+          break;
+        }
+        if (/^(y|yes)$/i.test(reply)) {
+          if (question.confirm && question.confirm.stale) {
+            warn('This draft is out of date. Type rebuild to write a new one first.');
+            continue;
+          }
+          current = await callApi('POST', `/${current.sessionId}/confirm`, { draftHash: question.confirm.draftHash });
+          confirmed = true;
+          break;
+        }
+        current = await sendInteractiveAnswer(current, reply);
+        continue;
+      }
+      printQuestion(question, current.progress);
+      const answer = await prompter.askText('>');
+      if (!answer.trim()) {
+        emptyReplies += 1;
+        if (emptyReplies >= MAX_EMPTY_REPLIES || process.stdin.readableEnded) {
+          const sessionId = current.sessionId;
+          abortMessage = () => {
+            warn('No answer was given, so the interview stopped here and nothing was installed.');
+            warn(`Pick it up again with: empirical setup resume ${sanitizeForTerminal(sessionId)}`);
+          };
+          break;
+        }
+        continue;
+      }
+      emptyReplies = 0;
+      current = await sendInteractiveAnswer(current, answer);
     }
-    log(JSON.stringify(current, null, 2));
+    finalResult = current;
   } finally {
-    prompter.close();
+    // A confirmed run keeps the prompter for the voice skill offer; it is closed below.
+    if (!confirmed) prompter.close();
+  }
+  if (abortMessage) {
+    abortMessage();
+    process.exit(1);
   }
+  if (confirmed) {
+    try {
+      return await reportConfirmed(finalResult, { prompter });
+    } finally {
+      prompter.close();
+    }
+  }
+  exitIfBusy(finalResult);
+  printJson(finalResult);
 }
 
 async function runRun(args) {
   const setupId = args[0] && !args[0].startsWith('--') ? args[0] : '';
   if (!setupId) {
-    warn('Usage: empirical setup run <setupId> [--answers <file.json>]');
+    warn('Usage: empirical setup run <setupId> [--answers <file.json>] [--accept-cost]');
     process.exit(1);
   }
   const answersFile = parseOption(args, '--answers', '');
+  const acceptCost = args.includes('--accept-cost');
   if (answersFile) {
-    await runNonInteractive(setupId, answersFile);
+    await runNonInteractive(setupId, answersFile, acceptCost);
   } else {
-    await runInteractive(setupId);
+    await runInteractive(setupId, acceptCost);
   }
 }
 
@@ -85,8 +610,11 @@ async function runAnswer(args) {
     warn('Usage: empirical setup answer <sessionId> <questionKey> <value>');
     process.exit(1);
   }
-  const result = await callApi('POST', `/${sessionId}/continue`, { answer: valueParts.join(' '), questionKey });
-  log(JSON.stringify(result, null, 2));
+  // The key from `setup resume` goes with the answer, so an answer meant for a question that has
+  // since moved on is refused instead of being saved on the current one.
+  const result = await callApi('POST', `/${encodeURIComponent(sessionId)}/continue`, { answer: valueParts.join(' '), questionKey });
+  printJson(result);
+  printCurrentQuestion(result);
 }
 
 async function runFinish(args) {
@@ -95,8 +623,8 @@ async function runFinish(args) {
     warn('Usage: empirical setup finish <sessionId>');
     process.exit(1);
   }
-  const result = await callApi('POST', `/${sessionId}/finish`, {});
-  log(JSON.stringify(result, null, 2));
+  const result = await callApi('POST', `/${encodeURIComponent(sessionId)}/finish`, {});
+  printJson(result);
 }
 
 async function runResume(args) {
@@ -105,8 +633,19 @@ async function runResume(args) {
     warn('Usage: empirical setup resume <sessionId>');
     process.exit(1);
   }
-  const result = await callApi('POST', `/${sessionId}/continue`, {});
-  log(JSON.stringify(result, null, 2));
+  const result = await callApi('POST', `/${encodeURIComponent(sessionId)}/continue`, {});
+  printJson(result);
+  printCurrentQuestion(result);
+}
+
+async function runConfirm(args) {
+  const [sessionId, draftHash] = args;
+  if (!sessionId || !draftHash) {
+    warn('Usage: empirical setup confirm <sessionId> <draftHash>');
+    process.exit(1);
+  }
+  const result = await callApi('POST', `/${encodeURIComponent(sessionId)}/confirm`, { draftHash });
+  await reportConfirmed(result);
 }
 
 async function runSetupCommand(args) {
@@ -116,8 +655,12 @@ async function runSetupCommand(args) {
   if (sub === 'answer') return runAnswer(rest);
   if (sub === 'finish') return runFinish(rest);
   if (sub === 'resume') return runResume(rest);
-  warn('Usage: empirical setup <list|run|answer|finish|resume> ...');
+  if (sub === 'confirm') return runConfirm(rest);
+  warn('Usage: empirical setup <list|run|answer|finish|resume|confirm> ...');
   process.exit(1);
 }
 
-module.exports = { runSetupCommand };
+module.exports = {
+  refundLine, runSetupCommand, formatQuestionLines, formatDraftLines, sanitizeForTerminal,
+  offerVoicePluginInstall, VOICE_PLUGIN_COMMANDS, VOICE_STANDING_INSTRUCTION
+};