bareloop 0.30.0 → 0.32.0

package/src/panel/authorsession.js

@@ -0,0 +1,555 @@
+// PANEL-BUILD.md P3 — the chat/authoring session engine. LAYERING LAW
+// (PANEL-BUILD.md §2): this file is one more CALLER of the same `src/`
+// library functions `bareloop interview`/`bareloop author` already call
+// (`src/interviewrun.js`, `src/authorrun.js`) — it mirrors their library
+// calls (the same functions, in the same order, with the same $0-before-paid
+// discipline), it never drives either script's own readline loop, and it
+// never reimplements anything arbiter-territory: `validateJob`,
+// `jobSpecHash`, `prepareSigning`'s gates, `checkApproval` all stay in the
+// library, called here exactly as `src/authorrun.js` calls them.
+//
+// WHAT THIS FILE DOES NOT DO: sign anything (`prepareSigning` only PREPARES —
+// see its own doc, "it stops at prepareSigning"), spawn a run, or read a
+// provider key anywhere but from the injected `env` (never logged, never
+// sent to the page — `src/panel/server.js`'s own routes own that boundary).
+//
+// THE ASK CHANNEL: `runConfirmTurn` (via `authorCloseForJob`) takes one
+// interactive seam, `ask(step) -> Promise<string|null>` — `src/authorrun.js`
+// backs it with a readline loop over stdin; this backs the IDENTICAL seam
+// with an HTTP-driven resolver queue of depth one (`answer()`, called from
+// `src/panel/server.js`'s POST routes). Nothing here changes what a step
+// means or what an answer does — only where the answer comes from.
+
+import { applyConfiguredKey, keyNameFor, modelChoiceFor, rowsForHome } from '../providerrows.js';
+import {
+  mkdirSync, existsSync, writeFileSync, readdirSync,
+} from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import {
+  prepareSource, proveDestination, missingDependencies, looksLikeRepoSource,
+} from '../source.js';
+import { detectLanguage } from '../detectlang.js';
+import {
+  validateJob, jobSpecHash, resolveWorkerModel,
+} from '../job.js';
+import {
+  authorCloseForJob, assembleSpec, AUTHORED_SPEC_FIELDS, CONFIRM_AUTHORED_FIELDS, PLAIN_FOLDER_DEFERRED_FIELDS,
+} from '../authorjob.js';
+import { prepareSigning } from '../authorjob.js';
+import {
+  questionsFor, requiredAnswersFor, makeLoopGenerate, CONFIRM_SYSTEM,
+} from '../authorflow.js';
+import {
+  resolveProvider, buildRunnerProviders, apiKeyProblem,
+} from '../providers.js';
+import { resolveJobJudge, defaultJudgeLoop } from '../judged.js';
+import { closeJudges } from '../kinds.js';
+import { redactSecrets } from '../validate.js';
+import { tallyCalls } from '../text.js';
+
+/**
+ * Plain-language labels for the library's own `onPhase(name, …)` calls
+ * (`src/authorjob.js`/`src/authorflow.js`) — build item 3's progress
+ * indicator shows one of these next to its animated glyph instead of a new
+ * chat bubble per phase. A phase with no entry here leaves the label as it
+ * was (never blanks it — a missing mapping should not flicker the line).
+ * @type {Readonly<Record<string, string>>}
+ */
+const PROGRESS_LABELS = Object.freeze({
+  'confirm-language-pick': 'confirming language',
+  'confirm-round': 'confirming plan',
+  'confirm-done': 'plan confirmed',
+  'author-call': 'drafting',
+  'author-fallback': 'drafting',
+  'seed-read': 'reading repo',
+  'seed-read-done': 'reading repo',
+  stage: 'checking',
+  seed: 'reading repo',
+  scout: 'scouting repo',
+  'scout-done': 'scouting repo',
+  confirm: 'confirming plan',
+  'confirm-turn-done': 'plan confirmed',
+  listing: 'listing files',
+  'listing-done': 'listing files',
+  author: 'drafting',
+  rubric: 'calibrating',
+  'rubric-done': 'calibrating',
+  'rubric-scrubbed': 'calibrating',
+});
+
+/** the confirm turn's own fixed round cap (`src/authorflow.js`'s
+ * `runConfirmTurn`: `for (let round = 1; round <= 2; round += 1)`) — named
+ * here, once, rather than re-guessed at every `onPhase('confirm-round')`
+ * below. Not itself exported from the library as a named constant (it is
+ * the loop bound the confirm turn's own doc calls "D3" / "ruling 5"); this is
+ * this file's one place that would need editing if that cap ever changed. */
+const CONFIRM_ROUND_CAP = 2;
+
+/** @param {string} name @returns {boolean} kebab-case slug, same rule `job.js`'s `SLUG_RE` enforces */
+function isSlug(name) {
+  return typeof name === 'string' && /^[a-z][a-z0-9-]*$/.test(name);
+}
+
+/**
+ * `true` when `jobs/<name>.json` already exists in the repo's own jobs/ dir
+ * (resolved from THIS module's own on-disk location, never `process.cwd()`,
+ * the same rule `src/panel/server.js`'s `jobsDir()` follows) — P3 is new-jobs-
+ * only (Q4=A), so a name collision refuses at $0 rather than silently
+ * overwriting or authoring a second spec under one name.
+ * @param {string} name
+ * @param {{jobsDir?: string}} [opts] test seam
+ * @returns {boolean}
+ */
+export function jobNameTaken(name, opts = {}) {
+  const dir = opts.jobsDir ?? join(new URL('../../jobs', import.meta.url).pathname);
+  if (!existsSync(dir)) return false;
+  try {
+    return readdirSync(dir).includes(`${name}.json`);
+  } catch { return false; }
+}
+
+/**
+ * `$0` validation of the job card fields the server must check BEFORE it
+ * creates a session or spends anything — never inside the async pipeline,
+ * so a bad card refuses synchronously, in the same HTTP response.
+ * @param {any} card
+ * @param {{jobsDir?: string, rows?: readonly import('../providerrows.js').KeyRow[]}} [opts] `rows` = the Settings rows (the Model menu); jobsDir is a server-side test seam — NEVER read off the client card
+ * @returns {{ok: true}|{ok: false, error: string}}
+ */
+export function validateJobCard(card, opts = {}) {
+  if (!card || typeof card !== 'object') return { ok: false, error: 'missing job card' };
+  const { jobName, checkType, model, goal, source, destination, success, guardrails, capUsd } = card;
+  if (!isSlug(jobName)) return { ok: false, error: 'Job name must be a kebab-case slug (letters, digits, dashes)' };
+  if (jobNameTaken(jobName, { jobsDir: opts.jobsDir })) {
+    return { ok: false, error: `a job named "${jobName}" already exists — P3 is new jobs only (Q4=A)` };
+  }
+  if (checkType !== 'deterministic' && checkType !== 'rubric') return { ok: false, error: 'Check type must be deterministic or rubric' };
+  if (!modelChoiceFor(opts.rows ?? [], model)) return { ok: false, error: 'Model must be one of the Names in Settings > Providers' };
+  for (const [field, label] of [[goal, 'Goal'], [source, 'Source'], [destination, 'Destination'], [success, 'Success'], [guardrails, 'Guardrails']]) {
+    if (typeof field !== 'string' || field.trim() === '') return { ok: false, error: `${label} is required` };
+  }
+  if (checkType === 'rubric' && (typeof card.judgeExamples !== 'string' || card.judgeExamples.trim() === '')) {
+    return { ok: false, error: 'Judge examples is required for a rubric (soft-green) check type' };
+  }
+  if (typeof capUsd !== 'number' || !Number.isFinite(capUsd) || capUsd <= 0) {
+    return { ok: false, error: '$ cap is required and must be a positive number' };
+  }
+  return { ok: true };
+}
+
+/**
+ * ONE session's engine — created already RUNNING (the caller awaits nothing;
+ * the pipeline drives itself, reporting through `state`). `state.pendingAsk`
+ * is the ONE thing a person answers next; `answer()`/`send()`/`revise()`/
+ * `signPrepare()` are the only ways in.
+ * @param {any} card the validated job card (see {@link validateJobCard})
+ * @param {{env?: Record<string,string|undefined>, sessionsRoot?: string, home?: string, timeoutMs?: number,
+ *   scout?: any, generate?: Function, confirmGenerate?: Function, authorFn?: Function,
+ *   prepareSigningFn?: Function}} [deps] the last five are TEST SEAMS ONLY — see the note
+ *   just above where each is read, below.
+ * @returns {any} the session object
+ */
+export function createSession(card, deps = {}) {
+  const env = deps.env ?? process.env;
+  const sessionsRoot = deps.sessionsRoot ?? join(process.env.HOME ?? '/tmp', '.config', 'bareloop', 'panel-sessions');
+  // config.json lives beside the sessions dir (~/.config/bareloop) unless a home is injected
+  const configHome = deps.home ?? dirname(sessionsRoot);
+  const timeoutMs = deps.timeoutMs ?? 300_000;
+  // TEST SEAMS ONLY (never set by `src/panel/authorroutes.js`'s real caller):
+  // override the declaration composer and/or `prepareSigning` itself so a
+  // test can drive the REAL confirm turn / ask() channel / revise-round /
+  // hash-matching machinery this file owns, without also re-running (and
+  // re-proving) `authorClose`'s own composer ladder or `prepareSigning`'s own
+  // gates — both already have their own test suites. Absent, both default to
+  // the real library functions, exactly as production always runs.
+  const authorFnOverride = deps.authorFn ?? null;
+  const prepareSigningFn = deps.prepareSigningFn ?? prepareSigning;
+  const id = `s${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+  const outDir = join(sessionsRoot, id);
+  mkdirSync(outDir, { recursive: true });
+
+  /** @type {any} */
+  const state = {
+    id,
+    phase: 'starting',
+    messages: /** @type {{role: string, text: string}[]} */ ([]),
+    pendingAsk: /** @type {any} */ (null),
+    cost: /** @type {any} */ (null),
+    revisesLeft: CONFIRM_ROUND_CAP,
+    specHash: /** @type {string|null} */ (null),
+    resolvedSpecPath: /** @type {string|null} */ (null),
+    error: /** @type {string|null} */ (null),
+    outDir,
+    // draftSpentUsd (hamr's ruling 2026-09-28, "one cap covers drafting +
+    // run") — the KNOWN FLOOR of this session's own drafting spend, updated
+    // by `onCall` below off the SAME `metered` list `state.cost` already
+    // reads (never a second running total). Never $0 when a call came back
+    // unpriced (F6: unpriced is never free) — `known` below is the floor
+    // either way. `signRun` (src/panel/authorroutes.js) reads this figure
+    // straight off `state` to pass `--draft-spent-usd` to `run-u`.
+    draftSpentUsd: 0,
+    // draftSpendComplete (hamr's ruling 2026-09-28, 2nd addendum) — was the
+    // floor above EXACT? Updated alongside `draftSpentUsd` by `onCall` below,
+    // off the same `tallyCalls` read `costSoFar()` (src/authorrun.js) uses for
+    // this same pipeline's own drafting-spend line — an unpriced OR
+    // unpriced-rounds-carrying call flips this false and it never heals.
+    // `signRun` reads it to pass `--draft-spend-incomplete` to `run-u`.
+    draftSpendComplete: true,
+    // the short, human step label the progress indicator shows next to its
+    // animated glyph (build item 3) — updated by `onPhase` below and by this
+    // file's own top-level phase transitions; never a chat bubble of its own
+    // (build item 2: onPhase used to post one, and it read as jargon/
+    // duplicate of the refusal that often followed it in the same breath).
+    progressLabel: /** @type {string|null} */ (null),
+  };
+
+  /** @param {'bot'|'you'|'system'} role @param {string} text */
+  const say = (role, text) => { state.messages.push({ role, text }); };
+
+  /** @type {((value: string|null) => void)|null} */
+  let resolvePending = null;
+
+  /** @type {(() => void)|null} the F182-mirrored install-gap wait's own
+   * resolver — a SEPARATE channel from `resolvePending`/`ask()` above (the
+   * confirm turn hasn't started yet when this one is live), signalled by
+   * `checkDeps()`, below, itself called only from the "Check again" POST
+   * route (`src/panel/authorroutes.js`). */
+  let resolveDepsCheck = null;
+  /** @returns {Promise<void>} resolves once `checkDeps()` is called */
+  const waitForDepsCheck = () => new Promise((resolveFn) => { resolveDepsCheck = resolveFn; });
+
+  /**
+   * The confirm turn's own `ask` seam — HTTP-backed, depth one. `describe`
+   * renders the SAME plain-language prompts `src/authorrun.js`'s own `ask`
+   * writes to its terminal, adapted for the chat thread rather than stdout.
+   * @param {{kind: string, [k: string]: any}} step
+   * @returns {Promise<string|null>}
+   */
+  const ask = (step) => new Promise((resolveFn) => {
+    state.pendingAsk = step;
+    resolvePending = resolveFn;
+    if (step.kind === 'language') say('bot', `${step.field?.prompt ?? 'Which language is this job about?'} (${(step.candidates ?? []).join(', ')})`);
+    else if (step.kind === 'menu') {
+      const p = step.plan ?? {};
+      const lines = [`Plan: ${JSON.stringify(p.goal ?? '')}`, `Checks: ${(p.checks ?? []).join(' · ') || '(none)'}`];
+      if ((p.notChecked ?? []).length) lines.push(`Not checked: ${p.notChecked.join(' · ')}`);
+      if ((p.questions ?? []).length) lines.push(`Questions: ${p.questions.join(' · ')}`);
+      lines.push('Sign & run to confirm this plan, or Revise to describe a change.');
+      say('bot', lines.join('\n'));
+    } else if (step.kind === 'answer') say('bot', `A question the plan raised (${step.index} of ${step.total}): ${step.question}`);
+    else if (step.kind === 'goal') say('bot', 'Type the goal sentence yourself.');
+    else if (step.kind === 'fix') say('bot', 'What should change?');
+  });
+
+  /** @param {string|null} value @returns {boolean} */
+  const answer = (value) => {
+    if (!resolvePending) return false;
+    const r = resolvePending;
+    resolvePending = null;
+    state.pendingAsk = null;
+    r(value);
+    return true;
+  };
+
+  /** @param {'menu'|'fix'|'answer'|'language'|'goal'} kind @param {number} timeoutMsInner */
+  const waitForPendingKind = async (kind, timeoutMsInner = 2000) => {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMsInner) {
+      if (state.pendingAsk?.kind === kind) return true;
+      // eslint-disable-next-line no-await-in-loop
+      await new Promise((r) => { setTimeout(r, 10); });
+    }
+    return state.pendingAsk?.kind === kind;
+  };
+
+  const onPhase = (name, data = {}) => {
+    if (name === 'confirm-round' && typeof data.round === 'number') {
+      state.revisesLeft = Math.max(0, CONFIRM_ROUND_CAP - (data.round - 1));
+    }
+    // COLLAPSED INTO THE PROGRESS INDICATOR ONLY (build item 3) — this used
+    // to also `say('system', `… ${name}`)`, one jargon chat bubble per
+    // library phase (`… confirm-turn-done`, `… seed-read`, …), read back to
+    // back with the plain-language refusal that often followed a phase like
+    // `confirm-turn-done` in the very next line (build item 2's "the
+    // refusal line appears twice"). The thread now carries only what a
+    // person needs to read; the step-by-step detail lives in one line.
+    state.progressLabel = PROGRESS_LABELS[name] ?? state.progressLabel;
+  };
+  /** @type {{label: string, costUsd: number|null, unpricedRounds: number}[]} */
+  const metered = [];
+  const onCall = (call) => {
+    metered.push({ label: call.label, costUsd: call.costUsd ?? null, unpricedRounds: call.unpricedRounds ?? 0 });
+    // hamr's ruling 2026-09-28 (2nd addendum) — the SAME `tallyCalls` reader
+    // `src/authorrun.js`'s own `costSoFar()` uses over this same call-shape
+    // list, so this session's floor/complete read can never drift from the
+    // CLI author path's: `spendComplete` is false the moment ANY call came
+    // back with a null costUsd or a nonzero unpricedRounds (F6), never just
+    // costUsd===null alone as this used to read.
+    const t = tallyCalls(metered);
+    state.cost = t.spendComplete ? `$${t.knownUsd.toFixed(4)}` : `≥$${t.knownUsd.toFixed(4)} (unpriced calls present)`;
+    state.draftSpentUsd = t.knownUsd;
+    state.draftSpendComplete = t.spendComplete;
+  };
+
+  const refuse = (message) => {
+    state.phase = 'refused';
+    state.error = message;
+    say('system', message);
+  };
+
+  async function run() {
+    // ── keys, at $0, before anything is prepared ────────────────────────
+    const keyRows = rowsForHome(configHome);
+    const modelChoice = modelChoiceFor(keyRows, card.model);
+    if (!modelChoice) { refuse(`Model "${card.model}" is not a Name in Settings > Providers. Stopped — nothing spent.`); return; }
+    let providerEntry;
+    try { providerEntry = resolveProvider(modelChoice.provider); } catch (e) { refuse(/** @type {Error} */ (e).message); return; }
+    // P4a item 4 — the key variable the person picked in Settings stands in for the built-in one
+    const keyCfg = keyRows;
+    const draftEnv = applyConfiguredKey(env, modelChoice.provider, modelChoice.baseUrl, keyCfg, modelChoice.name);
+    const draftKeyName = keyNameFor(modelChoice.provider, modelChoice.baseUrl, keyCfg, modelChoice.name).name;
+    const apiKey = draftEnv[providerEntry.envKey];
+    if (!apiKey) { refuse(`${draftKeyName} not set. Stopped — nothing spent.`); return; }
+    const keyProblem = apiKeyProblem(apiKey);
+    if (keyProblem) { refuse(`${draftKeyName} ${keyProblem}. Stopped — nothing spent.`); return; }
+
+    const verdictType = card.checkType === 'rubric' ? 'soft-green' : 'green';
+    const into = join(outDir, 'source-seed');
+    const isRepoLike = looksLikeRepoSource(card.source);
+
+    state.phase = 'preparing-source';
+    state.progressLabel = 'copying source';
+    say('system', 'Copying source ($0)');
+    const prep = await prepareSource({
+      source: card.source, into, destination: isRepoLike ? card.destination : card.destination,
+    });
+    if (prep.stop !== null) { refuse(prep.stop); return; }
+
+    const IS_REPO_SOURCE = prep.manifest.kind === 'repo';
+    let LANG = 'none-detected';
+    /** @type {any} */
+    let langResult = null;
+    if (IS_REPO_SOURCE) {
+      langResult = detectLanguage(prep.tree);
+      if (langResult.kind === 'language-unsupported') {
+        refuse(`${langResult.refusal.detail}`);
+        return;
+      }
+      LANG = langResult.kind === 'resolved' ? langResult.lang : (langResult.kind === 'ambiguous' ? langResult.candidates[0] : 'none-detected');
+
+      // ── the install gap, WAITED FOR, never a dead end (build item 1,
+      // mirroring F182's fix in `src/interviewrun.js`) ── the copy this
+      // session works from (`prep.tree`) is `prepareSource`'s own hidden
+      // seed, tracked-files-only, so a JS/TS repo's copy never carries
+      // `node_modules`. Refusing outright here was ITSELF the F182 class of
+      // bug one layer up: a person who ran the printed command and then
+      // reloaded the page got a BRAND NEW seed with no `node_modules`
+      // either, so the refusal could never be satisfied. bareloop still
+      // never runs an install itself — this only re-checks the SAME copy
+      // (`missingDependencies` over `prep.tree`, the identical rule
+      // `src/interviewrun.js` uses) on demand, via the "Check again" button
+      // (`checkDeps()`, below), instead of ending the session.
+      let depsGap = missingDependencies(prep.tree, prep.manifest.sourceSubdir ?? '');
+      if (depsGap) {
+        state.phase = 'install-needed';
+        state.progressLabel = 'waiting on install';
+        say('system', `Packages missing in the copy. Run:\ncd ${prep.tree} && ${depsGap.command}`);
+        for (;;) {
+          state.pendingAsk = { kind: 'install-needed', tree: prep.tree, command: depsGap.command, reason: depsGap.reason };
+          // eslint-disable-next-line no-await-in-loop
+          await waitForDepsCheck();
+          state.pendingAsk = null;
+          depsGap = missingDependencies(prep.tree, prep.manifest.sourceSubdir ?? '');
+          if (!depsGap) break;
+          say('system', `Still missing (${depsGap.reason}). Install, then Check again.`);
+        }
+        say('system', 'Packages found');
+        state.phase = 'drafting';
+      }
+    }
+    if (!IS_REPO_SOURCE) {
+      state.phase = 'refused';
+      state.error = 'non-code-source';
+      say('system', "Plain folder, not a code project — bareloop can't check this kind of job yet. Nothing spent.");
+      return;
+    }
+
+    const writeScope = card.destination.split(/[,\n]/).map((s) => s.trim()).filter(Boolean);
+    /** @type {any} the confirm turn (below) fills `goal` in once accepted —
+     * declared loosely rather than typed field-by-field, since this object's
+     * own shape is a `job-v1` draft `validateJob` itself is the real
+     * authority on, not a second hand-typed interface here. */
+    const draft = {
+      schema: 'job-v1',
+      job: card.jobName,
+      description: `${card.jobName} — authored through the bareloop panel (${verdictType}, ${LANG})`,
+      provider: modelChoice.provider,
+      ...(modelChoice.baseUrl ? { baseUrl: modelChoice.baseUrl } : {}),
+      // the Name is the model id: signed into the spec only when it is not the provider's own default
+      ...(modelChoice.name !== providerEntry.tiers.sonnet ? { model: modelChoice.name } : {}),
+      cadence: { unit: 'day', every: 1 },
+      budgetUsd: card.capUsd,
+      ...(typeof card.maxWallMs === 'number' ? { maxWallMs: card.maxWallMs } : {}),
+      writeScope,
+      escalation: { mode: 'decision-ready' },
+    };
+    const draftReds = validateJob(draft, { shellCapUsd: draft.budgetUsd }).reds
+      .filter((r) => ![...AUTHORED_SPEC_FIELDS, ...CONFIRM_AUTHORED_FIELDS, ...PLAIN_FOLDER_DEFERRED_FIELDS]
+        .some((f) => String(r.path) === f || String(r.path).startsWith(`${f}.`)));
+    if (draftReds.length) {
+      refuse(`the spec draft does not validate — ${draftReds.map((r) => `${r.code} at ${r.path}`).join('; ')}`);
+      return;
+    }
+
+    /** @type {Record<string, string>} */
+    const answers = { 1: card.goal, 2: card.success, 3: card.guardrails };
+    if (verdictType === 'soft-green') answers[4] = card.judgeExamples;
+    const required = requiredAnswersFor(verdictType);
+    for (const n of required) {
+      if (!answers[n]) { refuse(`the ${verdictType} check type needs ${required.length} answers and one is missing (key ${n})`); return; }
+    }
+
+    const draftJudge = (() => {
+      try { return resolveJobJudge(draft, modelChoice.provider, resolveWorkerModel); } catch { return { provider: modelChoice.provider, model: providerEntry.tiers.sonnet }; }
+    })();
+    const MODEL = modelChoice.name;
+    const { provider } = buildRunnerProviders({
+      providerName: modelChoice.provider, apiKey, model: MODEL, tierModels: providerEntry.tiers, baseUrl: modelChoice.baseUrl,
+      judgeApiKey: apiKey, judgeModel: MODEL, judgeProviderName: modelChoice.provider, judgeBaseUrl: modelChoice.baseUrl,
+    });
+    // TEST SEAMS (see the constructor's own note): a test overrides
+    // `generate`/`confirmGenerate` directly (bypassing this real, constructed
+    // `provider` for the model boundary) and/or `scout` (bypassing the real
+    // paid scout) so it can drive the REAL confirm turn/ask()/revise/hash
+    // machinery below with a deterministic fake, never a live provider call.
+    const generate = deps.generate ?? makeLoopGenerate(provider);
+    const confirmGenerate = deps.confirmGenerate ?? makeLoopGenerate(provider, { system: CONFIRM_SYSTEM });
+
+    state.phase = 'drafting';
+    state.progressLabel = 'drafting';
+    // build item 4 — the DISPLAY id (card.model, e.g. "deepseek-flash"), not
+    // the internal resolved tier model string (MODEL) or the raw provider
+    // name — the same id the Model field's own dropdown showed.
+    say('system', `Drafting with ${card.model}, $${card.capUsd.toFixed(2)} cap`);
+    const authored = await authorCloseForJob({
+      judgeModel: draftJudge.model,
+      answers, verdictType, repoPath: prep.tree, lang: LANG,
+      questions: questionsFor(verdictType),
+      writeScope, provider, generate,
+      ceilingUsd: card.capUsd,
+      onPhase, onCall,
+      ask, confirmGenerate, isRepo: true, langResult,
+      ...(deps.scout ? { scout: deps.scout } : {}),
+      ...(authorFnOverride ? { authorFn: authorFnOverride } : {}),
+    });
+
+    if (!authored.ok) {
+      state.phase = authored.stop === 'confirm-abandoned' ? 'abandoned' : 'refused';
+      state.error = authored.stop ?? 'authoring-failed';
+      say('system', `Stopped: ${state.error}${authored.refusal ? ` — ${authored.refusal.detail}` : ''}`);
+      return;
+    }
+
+    if (authored.confirmed?.goal) draft.goal = redactSecrets(String(authored.confirmed.goal));
+    const spec = assembleSpec(draft, { ...authored, verdictType: /** @type {string} */ (authored.verdictType) });
+    const specFile = join(outDir, 'resolved-spec.json');
+    writeFileSync(specFile, `${JSON.stringify(spec, null, 2)}\n`);
+    state.resolvedSpecPath = specFile;
+
+    const jv = validateJob(spec, { shellCapUsd: spec.budgetUsd });
+    if (!jv.ok) {
+      state.phase = 'refused';
+      state.error = `spec-invalid: ${jv.reds.map((r) => r.code).join(', ')}`;
+      say('system', state.error);
+      return;
+    }
+
+    state.phase = 'signing-gates';
+    state.progressLabel = 'checking';
+    say('system', 'Checking (gates 1–3, $0; gate 4 only if rubric)…');
+    const judges = closeJudges(spec.closeDecl);
+    const judge = judges ? resolveJobJudge(spec, modelChoice.provider, resolveWorkerModel) : null;
+    let judgeProvider = null;
+    if (judge) {
+      const judgeKeyValue = env.JUDGE_API_KEY ?? (judge.provider === modelChoice.provider ? draftEnv : applyConfiguredKey(env, judge.provider, undefined, keyCfg, judge.model))[resolveProvider(judge.provider).envKey];
+      const judgeKeyProblem = judgeKeyValue ? apiKeyProblem(judgeKeyValue) : null;
+      if (!judgeKeyValue || judgeKeyProblem) {
+        refuse(`the judge key is not usable (${judgeKeyProblem ?? 'not set'}) — refusing before gate 4 spends anything`);
+        return;
+      }
+      judgeProvider = buildRunnerProviders({
+        providerName: modelChoice.provider, apiKey, model: MODEL, tierModels: providerEntry.tiers, baseUrl: modelChoice.baseUrl,
+        judgeApiKey: judgeKeyValue, judgeModel: judge.model, judgeProviderName: judge.provider,
+        judgeBaseUrl: judge.provider === modelChoice.provider ? modelChoice.baseUrl : undefined,
+      }).judgeProvider;
+    }
+    const signing = await prepareSigningFn({
+      spec, workdir: prep.tree, seedRef: authored.seedRef, timeoutMs,
+      shellCapUsd: spec.budgetUsd, ceilingUsd: card.capUsd, priorCalls: [...metered],
+      judgeLoop: judgeProvider ? (o) => defaultJudgeLoop({ provider: judgeProvider, system: o.system }) : null,
+      judgeModel: judge?.model ?? null,
+      onJudgeCost: (c) => onCall({ label: `${c.label}:${c.id}`, costUsd: c.costUsd, unpricedRounds: c.unpricedRounds }),
+    });
+    const signingFile = join(outDir, 'signing.json');
+    writeFileSync(signingFile, `${JSON.stringify(signing, null, 2)}\n`);
+
+    if (!signing.ok) {
+      state.phase = 'refused';
+      state.error = `signing gates failed — ${signing.reds.map((r) => r.code).join(', ') || 'no work red at seed'}`;
+      say('system', state.error);
+      return;
+    }
+    state.specHash = signing.specHash;
+    state.phase = 'prepared';
+    say('bot', `SIGNING PREPARED — spec hash ${signing.specHash}`);
+  }
+
+  // fire-and-forget — the caller (src/panel/server.js) never awaits this; it
+  // polls `state` instead. A crash anywhere in `run()` is caught here so it
+  // can never take the panel server process down with it.
+  run().catch((e) => {
+    state.phase = 'error';
+    state.error = /** @type {Error} */ (e)?.message ?? String(e);
+    say('system', `internal error: ${state.error}`);
+  });
+
+  return {
+    id,
+    state,
+    /** @param {string} text */
+    send: (text) => {
+      if (!state.pendingAsk) return { ok: false, error: 'nothing is being asked right now' };
+      if (state.pendingAsk.kind === 'menu') return { ok: false, error: 'use Sign & run or Revise for a plan, never Send — the chat can never sign or pick a plan action' };
+      if (state.pendingAsk.kind === 'install-needed') return { ok: false, error: 'install the packages, then click Check again — nothing to send here' };
+      say('you', text);
+      answer(text);
+      return { ok: true };
+    },
+    /** the [Check again] button — re-runs the SAME `missingDependencies`
+     * check on the SAME copy, never a second install of its own. */
+    checkDeps: () => {
+      if (state.phase !== 'install-needed' || !resolveDepsCheck) return { ok: false, error: 'not waiting on an install check right now' };
+      const r = resolveDepsCheck;
+      resolveDepsCheck = null;
+      r();
+      return { ok: true };
+    },
+    /** @param {string} text */
+    revise: async (text) => {
+      if (!state.pendingAsk || state.pendingAsk.kind !== 'menu') return { ok: false, error: 'no plan is waiting for a Revise right now' };
+      if (state.revisesLeft <= 0) return { ok: false, error: 'no revises left (D3: max 2 rounds)' };
+      answer('fix');
+      const reached = await waitForPendingKind('fix', 3000);
+      if (!reached) return { ok: false, error: 'the confirm turn did not ask for a fix in time' };
+      say('you', text);
+      answer(text);
+      return { ok: true };
+    },
+    /** click 1 — the confirm pick. Never signs on its own. */
+    signPrepare: () => {
+      if (!state.pendingAsk || state.pendingAsk.kind !== 'menu') return { ok: false, error: 'no plan is waiting for a decision right now' };
+      answer('confirm');
+      return { ok: true };
+    },
+  };
+}