@empirical-gauzza/cli 1.0.36 → 1.0.38

package/lib/setupCommands.js

@@ -12,70 +12,759 @@ 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':
+    case 'GUIDED_SETUP_WORKSPACE_NOT_WAITING':
+      return [`See the current question and its key with: ${resume}`];
+    case 'GUIDED_SETUP_VOICE_BUSY':
+    case 'GUIDED_SETUP_WORKSPACE_BUSY':
+      return [`Wait a moment, then pick it up with: ${resume}`];
+    // The workspace interview's own refusals. The server's message already carries the price of a new
+    // interview (it is the effective one), so these lines name no number. An abandoned interview is
+    // not refunded, which is said before the person is pointed at starting again.
+    case 'GUIDED_SETUP_WORKSPACE_SESSION_LIMIT':
+      return [`If a draft was already shown, you can read it with ${resume} and confirm it; the limit can be reached before there is one. Starting a new interview is charged again, and stopping this one with empirical setup abandon ${sid} does not return what it cost.`];
+    case 'GUIDED_SETUP_WORKSPACE_GENERATION_FAILED':
+      return [`Your answers are saved. Run ${resume} to see where the setup is, then answer again.`];
+    case 'GUIDED_SETUP_WORKSPACE_UNAVAILABLE':
+      return ['Nothing was started or charged. Run the command again in a few minutes.'];
+    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;
+}
+
+// The server words its errors for every client, and one clause tells an AGENT to call a tool. At a terminal the
+// same step is a command, so that clause (and only that clause) becomes the real command.
+function cliConfirmWording(text, sessionId) {
+  return String(text === undefined || text === null ? '' : text).replace(
+    /\b([Cc])all confirm_guided_setup with this session's sessionId and the draftHash shown with the draft/g,
+    (_m, c) => `${c === 'C' ? 'Run' : 'run'} empirical setup confirm ${sessionId || '<sessionId>'} <draftHash>`
+  );
+}
+function forTerminal(error, sessionId) {
+  if (!error) return error;
+  if (typeof error.message === 'string') error.message = cliConfirmWording(error.message, sessionId);
+  if (typeof error.serverMessage === 'string') error.serverMessage = cliConfirmWording(error.serverMessage, sessionId);
+  return error;
+}
+
+function failWith(error, pathSuffix, body) {
+  forTerminal(error, sessionIdFromPath(pathSuffix));
+  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));
+  }
+  // The workspace interview words its own examples (built from the options on offer, and in the 'add Name'
+  // form its parser reads); this Writing Voice line would show "2,5" for a list that may have two options.
+  if (question.kind === 'pick_and_edit' && !isWorkspaceQuestion(question)) 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`;
+}
+
+// A workspace draft is a list of plain sentences (no hub or rules), the people to be invited, and
+// anything that stops it being confirmed. The Writing Voice branch below would print "Hub: undefined".
+function isWorkspaceDraft(question) {
+  return Boolean(question && question.draft && Array.isArray(question.draft.lines));
+}
+
+function formatWorkspaceDraftLines(question) {
+  const t = sanitizeForTerminal;
+  const confirm = question.confirm || {};
+  const lines = [];
+  for (const l of [...question.draft.lines, ...(Array.isArray(question.draft.statusSummary) ? question.draft.statusSummary : [])]) lines.push(`- ${t(l)}`);
+  if (Array.isArray(confirm.invites)) {
+    lines.push(confirm.invites.length
+      ? `Invites: ${confirm.invites.map((i) => `${t(i.email)} (${t(i.role)})`).join(', ')}`
+      : 'Invites: nobody yet.');
+  }
+  if (confirm.inviteNote) lines.push(t(confirm.inviteNote));
+  if (confirm.canConfirm === false) {
+    lines.push('This draft cannot be confirmed as it is:');
+    for (const b of Array.isArray(confirm.blockers) ? confirm.blockers : []) lines.push(`- ${t(b)}`);
+    lines.push('Type a change to fix it. Nothing has been created or changed.');
+  } else if (question.prompt) {
+    // The server's own review wording: what the person can do next (next, confirm, a change, a rename).
+    lines.push(workspaceReviewPrompt(question.prompt));
+  }
+  return lines;
+}
+
+// The server words the review for every client, and its one tool-call clause (how an AGENT confirms) means
+// nothing at a terminal, where the person types the word that is asked for below. Everything else is the
+// server's own text, unchanged, so every example in it works as typed.
+function workspaceReviewPrompt(prompt) {
+  return sanitizeForTerminal(prompt)
+    .replace(/\s*\(call confirm_guided_setup[^)]*\)/, '')
+    .replace(/To (?:create the workspace|save these changes), call confirm_guided_setup[^.]*\.\s*/, '')
+    .trim();
+}
+
+function formatDraftLines(question, progress = {}) {
+  if (isWorkspaceDraft(question)) return formatWorkspaceDraftLines(question);
+  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;
+}
+
+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 (isWorkspaceDraft(question) && confirm.canConfirm === false) {
+    warn(`Ask for a change with: empirical setup answer ${sid} ${key} <the change you want>`);
+    return;
+  }
+  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));
+  // A confirmed workspace interview has no install job: it names the workspace and what to do next.
+  if (result && result.workspaceId && !(result && result.installId)) {
+    const id = sanitizeForTerminal(result.workspaceId);
+    log(`Workspace id: ${id}`);
+    log(`Switch to it with: ${WORKSPACE_USE_LINE(id)}`);
+    log(`Change its shape later with: ${WORKSPACE_SHAPE_LINE(id)}`);
+    return;
+  }
+  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.
+//
+// start carries any extra start fields. For the workspace interview that is targetWorkspaceId, the one
+// explicit way to ask for a re-shape (no field means a new workspace). Its start is also where a setup
+// that is switched off for the person answers 404, which is explained instead of left as a bare error.
+async function startWithCost(setupId, { acceptCost, prompter, start = {} }) {
+  const first = await startCall({ setupId, ...start, ...(acceptCost ? { acceptEmpiricalTokenCost: true } : {}) });
+  if (!isCostPreview(first)) return reportTokensUsed(first);
+  await confirmCostOrExit(first, { prompter, warn, sanitize: sanitizeForTerminal });
+  return reportTokensUsed(await startCall({ setupId, ...start, acceptEmpiricalTokenCost: true }));
+}
+
+async function startCall(body) {
+  const { data, error } = await tryApi('POST', '/start', body);
+  if (!error) return data;
+  if (body.setupId === WORKSPACE_SETUP_ID && error.statusCode === 404) {
+    printApiError(error);
+    warn('The workspace interview is not switched on for your account, so nothing was started or charged.');
+    process.exit(1);
+  }
+  return failWith(error, '/start', body);
+}
+
+// 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) {
+async function runNonInteractive(setupId, answersFilePath, acceptCost, start) {
   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, start });
+  hintAbandon(current);
+  let confirmed = false;
+  const reviewTurns = {};
 
-  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' && isFirstWorkspaceReview(question) && Object.prototype.hasOwnProperty.call(answersByQuestionKey, questionKey) && answersByQuestionKey[questionKey] !== 'confirm') {
+      // The first review of a workspace: the file's value is the answer, so a script can reach the invites.
+      // A list is taken in order (a rename, then next); a single string is sent once.
+      const wanted = answersByQuestionKey[questionKey];
+      const queue = Array.isArray(wanted) ? wanted : [wanted];
+      const turn = (reviewTurns[questionKey] = (reviewTurns[questionKey] || 0) + 1) - 1;
+      if (turn < queue.length) {
+        current = await callApi('POST', `/${current.sessionId}/continue`, answerBody(question, queue[turn]));
+        continue;
+      }
     }
-    current = await callApi('POST', `/${current.sessionId}/continue`, { answer: answersByQuestionKey[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);
+      // A workspace draft with blockers has no hash to confirm; the file's "confirm" is not sent for it.
+      const confirmable = !(question.confirm && question.confirm.canConfirm === false);
+      if (answersByQuestionKey[questionKey] === 'confirm' && !stale && confirmable) {
+        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`, 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);
+}
+
+// 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;
 }
 
-async function runInteractive(setupId) {
+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(cliConfirmWording(error.serverMessage || error.message, current.sessionId)));
+  return callApi('POST', pathSuffix, {});
+}
+
+async function runInteractive(setupId, acceptCost, start) {
   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, start });
+    if (!current) return;
+    hintAbandon(current);
+    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(confirmPromptFor(question))).trim();
+        if (!reply) {
+          const sessionId = current.sessionId;
+          abortMessage = () => printNothingInstalled(sessionId, question.confirm && question.confirm.draftHash);
+          break;
+        }
+        const firstReview = isFirstWorkspaceReview(question);
+        if (firstReview && /^(y|yes)$/i.test(reply)) {
+          warn('Yes is not one of the choices here. Type next to choose who to invite, or confirm to finish without inviting anyone.');
+          continue;
+        }
+        if (firstReview ? /^confirm$/i.test(reply) : /^(y|yes|confirm)$/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;
+          }
+          if (isWorkspaceDraft(question) && (question.confirm.canConfirm === false || !question.confirm.draftHash)) {
+            warn('This draft cannot be confirmed as it is. Type a change to fix what is listed above.');
+            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);
+}
+
+const WORKSPACE_SETUP_ID = 'setup_workspace';
+// The commands printed after a workspace is made, built from the real id so they work as typed.
+const WORKSPACE_USE_LINE = (id) => `empirical workspace use ${id}`;
+const WORKSPACE_SHAPE_LINE = (id) => `empirical workspace shape --workspace-id ${id}`;
+
+// The question at the review step. The workspace interview creates or changes a workspace, not an install.
+// The first review (questionKey draft) is BEFORE the invitations, so a bare yes is not a choice there: the
+// person picks next (to choose who to invite) or confirm (finish with nobody invited). The final review
+// (after the invitations) is the one a yes confirms.
+function isFirstWorkspaceReview(question) {
+  return isWorkspaceDraft(question) && question.questionKey === 'draft';
+}
+function confirmPromptFor(question) {
+  if (!isWorkspaceDraft(question)) return 'Install this? (type yes to install, or type a change you want)';
+  const reshape = question.confirm && question.confirm.mode === 'reshape';
+  if (question.confirm && question.confirm.canConfirm === false) return 'What next? (type a change you want)';
+  if (isFirstWorkspaceReview(question)) return `What next? (type next to choose who to invite, confirm to ${reshape ? 'save these changes' : 'create the workspace'} without inviting anyone, or type a change you want)`;
+  return `${reshape ? 'Apply this to the workspace?' : 'Create this workspace?'} (type yes to confirm, or type a change you want)`;
+}
+
+// Printed once after a workspace interview starts. An abandoned interview is NOT refunded, and the
+// line says so, so nobody stops one expecting their Empirical Tokens back.
+function hintAbandon(result) {
+  if (!result || !result.sessionId || !result.question) return;
+  if (!isWorkspaceQuestion(result.question)) return;
+  const sid = sanitizeForTerminal(result.sessionId);
+  warn(`If you want to stop this interview, run: empirical setup abandon ${sid} (what it cost is not returned).`);
+}
+
+// Workspace questions are the only ones with these keys; the Writing Voice engine has none of them.
+function isWorkspaceQuestion(question) {
+  const key = String((question && question.questionKey) || '');
+  return key === 'purpose' || key === 'types' || key === 'nesting' || key === 'policy' || key === 'invites'
+    || key === 'draft' || /^(statuses|fields):/.test(key);
+}
+
+// The workspace interview from the workspace commands. targetWorkspaceId present means re-shape that
+// workspace, absent means create a new one; nothing else decides it.
+async function runWorkspaceInterview({ targetWorkspaceId, answersFile = '', acceptCost = false } = {}) {
+  const start = targetWorkspaceId ? { targetWorkspaceId } : {};
+  if (answersFile) return runNonInteractive(WORKSPACE_SETUP_ID, answersFile, acceptCost, start);
+  return runInteractive(WORKSPACE_SETUP_ID, acceptCost, start);
 }
 
 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 +774,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 +787,20 @@ 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 runAbandon(args) {
+  const [sessionId] = args;
+  if (!sessionId) {
+    warn('Usage: empirical setup abandon <sessionId>');
+    process.exit(1);
+  }
+  const result = await callApi('POST', `/${encodeURIComponent(sessionId)}/abandon`, {});
+  log(result && result.status === 'abandoned'
+    ? 'The interview was stopped. Nothing was created or changed, and what it cost was not returned.'
+    : 'That interview was already finished or stopped. Nothing was changed, and no Empirical Tokens were returned.');
 }
 
 async function runResume(args) {
@@ -105,8 +809,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 +831,13 @@ 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);
+  if (sub === 'abandon') return runAbandon(rest);
+  warn('Usage: empirical setup <list|run|answer|finish|resume|confirm|abandon> ...');
   process.exit(1);
 }
 
-module.exports = { runSetupCommand };
+module.exports = {
+  refundLine, cliConfirmWording, runSetupCommand, runWorkspaceInterview, WORKSPACE_SETUP_ID, recoveryHints, formatQuestionLines, formatDraftLines, sanitizeForTerminal,
+  offerVoicePluginInstall, VOICE_PLUGIN_COMMANDS, VOICE_STANDING_INSTRUCTION
+};