@mycompbox/compbox-cli 1.18.0 → 1.20.0

package/utils/agent-invoker.js

@@ -2,64 +2,39 @@
  * Agent invoker (ENG-E23 / ENG-122-2) — the daemon's "heart": actually runs a
  * claimed job instead of immediately reporting it as unimplemented.
  *
- * Two agentModes are implemented, both for `epic_request` jobs only
- * (`start_execution` — running planner/orchestrator locally — is NOT
- * implemented here):
+ * Request conversations (`epic_request` jobs) run one AI reply per claim
+ * (invokeEpicRequestStep, on the shared runConversationStep): the reply is
+ * posted, the job is left waiting on the person, and the server hands it back
+ * when they write again. Nothing waits in between, so a conversation never
+ * times out and stays open after the request is saved. Two ways to reply:
  *   - `api`: Anthropic Messages API, directly (Anthropic API key, billed
- *     per-token). See invokeEpicRequestViaApi.
+ *     per-token).
  *   - `claude-subscription`: shells out to the local `claude` CLI
  *     non-interactively, using whichever account is already logged in on
  *     this machine (personal Pro/Max or a company Team seat) — no API key
- *     ever touches CompBox. See invokeEpicRequestViaSubscription.
+ *     ever touches CompBox.
  *
- * Common to both:
- *   - The interview is driven by the shared, declarative INTERVIEW_DEFINITION
- *     (@mycompbox/shared, ENG-143) so the machine/mailbox interview reaches the
- *     SAME depth as the CLI request-formulator: it covers all seven sections
- *     (problem, solution, impact, success metrics, target audience, technical
- *     context, alternatives) rather than only the 3 required fields. The system
- *     prompt is rendered from that definition (buildInterviewSystemPrompt), and
- *     the completion object carries the required fields plus any optional ones
- *     the employee provided; there is no shortened variant left in this path.
- *
- * Turn relay: the mailbox has no "wait for a new turn" primitive for a
- * machine caller (next-job's "resume active job" path returns immediately
- * with whatever the job's current state is — see jobService.ts tryClaimOnce).
- * So after posting an agent question, this module polls next-job on a short
- * client-side interval until it observes a new trailing user turn, with a
- * bounded overall timeout so an abandoned interview eventually fails cleanly
- * instead of polling forever.
+ * `start_execution` jobs run the planner/orchestrator headless (below).
  */
 import Anthropic from '@anthropic-ai/sdk';
 import { spawn, spawnSync } from 'node:child_process';
 import { mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { resolveRouting, buildInterviewSystemPrompt, INTERVIEW_DEFINITION, } from '@mycompbox/shared';
+import { resolveRouting, extractCompletionJson, looksLikeCompletionAttempt, meetsComplianceTarget, buildAuditFeedback, COMPLETION_REPAIR_INSTRUCTION, renderConversationPrompt, runConversationStep, savedContextFromRecord, } from '@mycompbox/shared';
+// Completion parsing lives in @mycompbox/shared so CompBox's server-side
+// (API-key) interview finishes the same way; re-exported for existing callers.
+export { extractCompletionJson, looksLikeCompletionAttempt, meetsComplianceTarget, buildAuditFeedback, COMPLETION_REPAIR_INSTRUCTION, };
 import { claudeChildEnvPath, claudeNotFoundMessage, resolveClaudeBinary, } from './claude-runtime.js';
 import { isGitRepoDir } from './config-store.js';
+import { keyRunArgs, keyRunEnv, parseClaudeJsonResult } from './key-run.js';
 // Fable is the model CompBox agents run on (ENG-E26): it is pxpipe's 100/100
 // image reader, so routing it through the proxy cuts input tokens without
 // quality loss. Opus/Sonnet are deliberately NOT used here — pxpipe passes
 // Opus through uncompressed, defeating the token savings.
 const ANTHROPIC_MODEL = 'claude-fable-5';
-// Turn budget for the interview loop. Raised from 8: a full 7-section interview
-// (problem / solution / impact + success metrics / audience / technical context /
-// alternatives) plus follow-ups AND audit-quality rounds needs more headroom
-// than 8 (deep interviews were being cut off mid-way — bug #3).
-const MAX_INTERVIEW_TURNS = 18;
-// Audit-quality gate (bug #2): the interview must reach the `pass` tier
-// (>=90, zero critical issues) before it may finish. After the model says
-// "done", we submit, read the server-computed compliance score, and if it is
-// not yet `pass` we feed the failing rules back and keep going. This bounds how
-// many re-submit/re-audit rounds we allow before finalizing with the best draft
-// (so we never loop forever, and never strand the request at a failing score).
-const MAX_QUALITY_ROUNDS = 4;
-const TARGET_COMPLIANCE_TIER = 'pass';
-const REPLY_POLL_INTERVAL_MS = 3_000;
-const REPLY_TIMEOUT_MS = 10 * 60 * 1_000; // 10 minutes
 /** Per-turn wall-clock budget for a single `claude -p` child process. */
-const CLAUDE_CLI_TURN_TIMEOUT_MS = 2 * 60 * 1_000; // 2 minutes
+const CLAUDE_CLI_TURN_TIMEOUT_MS = 4 * 60 * 1_000; // 4 minutes: a full write-up can take a while
 /**
  * pxpipe routing (ENG-136). Anthropic SDK options carrying the proxy `baseURL`
  * when routed through pxpipe, otherwise just the API key. Pure — unit tested.
@@ -225,13 +200,6 @@ export function appendAttachmentNote(text, imageCount) {
     const note = `[${String(imageCount)} ${noun} attached — not shown in subscription mode; vision is handled when the daemon runs in API mode]`;
     return text.trim().length > 0 ? `${text}\n\n${note}` : note;
 }
-/**
- * The interview system prompt, rendered from the shared, declarative
- * INTERVIEW_DEFINITION (ENG-143). This is the single wiring point that gives
- * the machine/mailbox interview the same section depth as the CLI
- * request-formulator — there is no shortened hardcoded variant anymore.
- */
-const SYSTEM_PROMPT = buildInterviewSystemPrompt();
 /**
  * ENG-149 — parse a claimed job's `payload` as an interview-CONTINUATION seed
  * (the ENG-148 dispatch shape), or return null for a normal fresh-start job
@@ -260,17 +228,6 @@ export function parseSeedPayload(payload) {
         priorTranscript,
     };
 }
-/**
- * ENG-149 — the interview system prompt for a job: a seed-aware RESUME/ENRICH
- * prompt for a continuation, otherwise the module-level fresh-start prompt.
- */
-export function resolveSystemPrompt(seed) {
-    return seed
-        ? buildInterviewSystemPrompt(INTERVIEW_DEFINITION, {
-            priorTranscript: seed.priorTranscript,
-        })
-        : SYSTEM_PROMPT;
-}
 /**
  * Submit the current draft and read back the server-computed compliance score
  * (bug #2 — audit-aware finishing). Fresh interview: the FIRST submit
@@ -287,338 +244,6 @@ export async function submitAndScore(ctx, currentErId, draft) {
     const created = await createPersonalEpicRequest(ctx.apiBaseUrl, ctx.userApiToken, draft);
     return { erId: created.id, compliance: created.compliance };
 }
-/**
- * Whether the request is good enough to finish. Reaching the target tier
- * (`pass` = >=90 with no criticals) finishes early. A null score is fail-open:
- * the gate can only act on a score the server actually returned.
- */
-export function meetsComplianceTarget(compliance) {
-    return !compliance || compliance.tier === TARGET_COMPLIANCE_TIER;
-}
-/**
- * Turn a failing compliance score into a corrective instruction: fix by
- * EXPANDING what's already known where possible, otherwise ask ONE question.
- */
-export function buildAuditFeedback(compliance) {
-    const ordered = [
-        ...compliance.issues.filter((i) => i.tier === 'critical'),
-        ...compliance.issues.filter((i) => i.tier === 'advisory'),
-    ].slice(0, 8);
-    const list = ordered.length > 0
-        ? ordered.map((i) => `- ${i.message}`).join('\n')
-        : '- (no specific issues returned; expand the required fields with more concrete detail)';
-    return `The epic request you just produced scored ${String(compliance.overall)}/100 (tier: ${compliance.tier}). It must reach 90/100 with ZERO critical issues before the interview can finish. Fix these:
-${list}
-
-If you can resolve these by EXPANDING what the employee already told you — a longer, more complete and concrete problemStatement / proposedSolution / impactAssessment / description that comfortably clear the length minimums — re-emit the completion JSON now with richer fields. Do NOT re-ask something you already have an answer for. Only if you genuinely need NEW information from the employee, ask ONE focused question to get it.`;
-}
-/** The optional draft keys, kept in one place so the guard and parser agree. */
-const OPTIONAL_DRAFT_KEYS = [
-    'successMetrics',
-    'targetAudience',
-    'alternatives',
-    'dependencies',
-    'estimatedEffort',
-];
-/** Type guard validating the model's completion JSON has the required shape. */
-function isEpicRequestDraft(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    const v = value;
-    // 🔴 We deliberately do NOT require a `done: true` marker. Fable frequently
-    // emits a complete, valid completion object WITHOUT `done` (verified against a
-    // real stuck interview), which caused the daemon to reject a finished request
-    // and relay the raw JSON back to the user forever. The completion signal is the
-    // PRESENCE of all required fields as non-empty strings — a plain-text question
-    // never carries these, so this is unambiguous.
-    const nonEmpty = (x) => typeof x === 'string' && x.trim().length > 0;
-    const requiredOk = nonEmpty(v.title) &&
-        nonEmpty(v.problemStatement) &&
-        nonEmpty(v.proposedSolution) &&
-        nonEmpty(v.impactAssessment) &&
-        nonEmpty(v.description);
-    if (!requiredOk)
-        return false;
-    // Optional fields, when present, must be strings (a wrong-typed optional is a
-    // malformed completion, not a silently-ignored one).
-    for (const key of OPTIONAL_DRAFT_KEYS) {
-        if (key in v && v[key] !== undefined && typeof v[key] !== 'string')
-            return false;
-    }
-    return true;
-}
-/** Removes trailing commas before } or ] — a common LLM JSON defect. */
-function stripTrailingCommas(json) {
-    return json.replace(/,(\s*[}\]])/g, '$1');
-}
-/**
- * Escapes raw control chars (newline/carriage-return/tab) that appear INSIDE a
- * JSON string literal — the single most common reason a model's completion JSON
- * fails `JSON.parse` (long multi-line description/problem fields written with
- * literal line breaks). Walks the text tracking string state so control chars
- * OUTSIDE strings (formatting whitespace) are left untouched.
- */
-function escapeRawControlCharsInStrings(json) {
-    let out = '';
-    let inString = false;
-    let escaped = false;
-    for (const ch of json) {
-        if (escaped) {
-            out += ch;
-            escaped = false;
-            continue;
-        }
-        if (ch === '\\') {
-            out += ch;
-            escaped = true;
-            continue;
-        }
-        if (ch === '"') {
-            inString = !inString;
-            out += ch;
-            continue;
-        }
-        if (inString && (ch === '\n' || ch === '\r' || ch === '\t')) {
-            out += ch === '\n' ? '\\n' : ch === '\r' ? '\\r' : '\\t';
-            continue;
-        }
-        out += ch;
-    }
-    return out;
-}
-/** Candidate JSON substrings to try, in priority order, from a model reply. */
-function completionJsonCandidates(text) {
-    const candidates = [];
-    // A fenced block (```json … ``` or a plain ``` … ``` fence), case-insensitive.
-    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
-    if (fenced?.[1])
-        candidates.push(fenced[1]);
-    const trimmed = text.trim();
-    if (trimmed.startsWith('{'))
-        candidates.push(trimmed);
-    // Last resort: the widest {...} span (handles prose wrapped around the JSON).
-    const first = text.indexOf('{');
-    const last = text.lastIndexOf('}');
-    if (first !== -1 && last > first)
-        candidates.push(text.slice(first, last + 1));
-    return candidates;
-}
-/** Builds the draft from a validated parse (required fields + non-empty optionals). */
-function toDraft(parsed) {
-    const draft = {
-        title: parsed.title,
-        problemStatement: parsed.problemStatement,
-        proposedSolution: parsed.proposedSolution,
-        impactAssessment: parsed.impactAssessment,
-        description: parsed.description,
-    };
-    for (const key of OPTIONAL_DRAFT_KEYS) {
-        const raw = parsed[key];
-        if (typeof raw === 'string' && raw.trim().length > 0) {
-            draft[key] = raw;
-        }
-    }
-    return draft;
-}
-/**
- * Extracts a completion draft from a model reply, tolerant of the common LLM
- * JSON defects (fenced/plain/bare, trailing commas, and — the big one — literal
- * newlines inside string values). Returns null only when no repair strategy
- * yields a VALID {@link isEpicRequestDraft} object.
- */
-export function extractCompletionJson(text) {
-    for (const candidate of completionJsonCandidates(text)) {
-        for (const variant of [
-            candidate,
-            stripTrailingCommas(candidate),
-            escapeRawControlCharsInStrings(candidate),
-            escapeRawControlCharsInStrings(stripTrailingCommas(candidate)),
-        ]) {
-            try {
-                const parsed = JSON.parse(variant);
-                if (isEpicRequestDraft(parsed))
-                    return toDraft(parsed);
-            }
-            catch {
-                // Try the next repair variant / candidate.
-            }
-        }
-    }
-    return null;
-}
-/**
- * True when a reply is clearly an ATTEMPT to finish (a JSON completion) even if
- * it failed to parse/validate — so the daemon can correct the model instead of
- * relaying raw JSON to the employee as if it were a question (which loops).
- */
-export function looksLikeCompletionAttempt(text) {
-    // Must open a JSON object (fenced or bare) — note we do NOT require a closing
-    // brace, so a truncated/malformed completion still counts.
-    const hasObject = /```(?:json)?\s*\{/i.test(text) || text.trim().startsWith('{');
-    if (!hasObject)
-        return false;
-    // ...carrying completion field names (or a `done` marker) — even if malformed
-    // or missing `done`. A plain-text question never matches this.
-    return /"(?:done|title|problemStatement|proposedSolution|impactAssessment|description)"\s*:/i.test(text);
-}
-/** Correction sent to the model when its completion JSON couldn't be used. */
-const COMPLETION_REPAIR_INSTRUCTION = 'Your last message looked like a completion but I could NOT parse it as a valid JSON object with all required fields. Re-emit ONLY a single valid JSON object inside a ```json code fence — no other text — with every string value properly escaped (escape any internal double-quotes as \\" and any line breaks as \\n), and make sure title, problemStatement, proposedSolution, impactAssessment, and description are all present and non-empty:\n```json\n{"done": true, "title": "...", "problemStatement": "...", "proposedSolution": "...", "impactAssessment": "...", "description": "..."}\n```';
-/** How many times to ask the model to fix a malformed completion before failing. */
-const MAX_JSON_REPAIRS = 3;
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/**
- * Polls next-job (the "resume active job" path) until a new trailing user
- * turn appears, or the timeout elapses. Returns the updated job, or null on
- * timeout.
- */
-async function waitForUserReply(client, machineToken, jobId, turnsSoFar) {
-    const deadline = Date.now() + REPLY_TIMEOUT_MS;
-    while (Date.now() < deadline) {
-        await sleep(REPLY_POLL_INTERVAL_MS);
-        const job = await client.nextJob(machineToken, 0);
-        if (job?.id !== jobId)
-            continue;
-        const last = job.turns[job.turns.length - 1];
-        if (job.turns.length > turnsSoFar && last?.role === 'user') {
-            return job;
-        }
-    }
-    return null;
-}
-/**
- * Runs the epic_request interview end-to-end: converses with the user via
- * post-turn/next-job until it has a title + the 3 required structured-desc
- * fields, then creates a personal-scope epic request via the real API
- * (POST /api/v1/me/epic-requests) using the user's own stored token.
- */
-export async function invokeEpicRequestViaApi(job, ctx) {
-    // pxpipe (ENG-136): route API-mode calls through the proxy when enabled+healthy.
-    const routing = await resolveRouting();
-    const anthropic = new Anthropic(anthropicClientOptions(ctx.anthropicApiKey, routing));
-    // ENG-149: a continuation job carries a seed → resume/enrich prompt + update
-    // the target ER in place; a fresh job → normal prompt + create a new ER.
-    const seed = parseSeedPayload(job.payload);
-    const systemPrompt = resolveSystemPrompt(seed);
-    // Audit-gate state (bug #2): the ER we are building (a continuation starts with
-    // its target), and how many re-submit/re-audit rounds we've spent.
-    let currentErId = seed?.targetEpicRequestId ?? null;
-    let qualityRounds = 0;
-    // Malformed-completion recovery: a model can emit "done" JSON we can't parse.
-    let jsonRepairs = 0;
-    const messages = [];
-    // Seed the conversation with any turns already on the job (e.g. a resumed
-    // daemon restart), so we don't re-ask questions already answered. A seeded
-    // USER turn may carry image attachments (ENG-153) — fetch + attach them as
-    // vision blocks; agent turns and image-free user turns are unchanged.
-    for (const turn of job.turns) {
-        if (turn.role === 'agent') {
-            messages.push({ role: 'assistant', content: turn.content });
-        }
-        else {
-            messages.push({ role: 'user', content: await apiUserTurnContent(turn) });
-        }
-    }
-    let turnsSoFar = job.turns.length;
-    for (let i = 0; i < MAX_INTERVIEW_TURNS; i++) {
-        let reply;
-        try {
-            const response = await anthropic.messages.create({
-                model: ANTHROPIC_MODEL,
-                max_tokens: 1024,
-                system: systemPrompt,
-                messages: messages.length > 0 ? messages : [{ role: 'user', content: 'Let\'s get started.' }],
-            });
-            const textBlock = response.content.find((b) => b.type === 'text');
-            reply = textBlock?.type === 'text' ? textBlock.text : '';
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : 'Anthropic API request failed';
-            return { status: 'failed', result: { error: `Agent invocation failed: ${message}` } };
-        }
-        const draft = extractCompletionJson(reply);
-        if (draft) {
-            let submitted;
-            try {
-                submitted = await submitAndScore(ctx, currentErId, draft);
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : 'Failed to save the epic request';
-                return { status: 'failed', result: { error: message } };
-            }
-            currentErId = submitted.erId;
-            const compliance = submitted.compliance;
-            // Finish only once the request passes the audit (>=90, no criticals), or
-            // when the quality-round budget is spent — best-effort, never stranded.
-            if (meetsComplianceTarget(compliance) || qualityRounds >= MAX_QUALITY_ROUNDS) {
-                return { status: 'done', result: { epicRequestId: currentErId } };
-            }
-            // Not good enough: feed the failing rules back (a model-facing round, no
-            // user turn) and loop — the model re-emits a richer completion or asks the
-            // employee a targeted question next iteration. (compliance is non-null here:
-            // meetsComplianceTarget(null) is true, so a null score would have finished.)
-            qualityRounds++;
-            if (compliance !== null) {
-                messages.push({ role: 'assistant', content: reply });
-                messages.push({ role: 'user', content: buildAuditFeedback(compliance) });
-            }
-            continue;
-        }
-        // The model TRIED to finish but the JSON was unusable (bug: malformed
-        // completion relayed to the employee as a question, looping forever). Correct
-        // the model instead of posting raw JSON — bounded, then fail cleanly.
-        if (looksLikeCompletionAttempt(reply)) {
-            if (jsonRepairs >= MAX_JSON_REPAIRS) {
-                return {
-                    status: 'failed',
-                    result: {
-                        error: 'The interview produced malformed completion data and could not be finalized after several attempts.',
-                    },
-                };
-            }
-            jsonRepairs++;
-            messages.push({ role: 'assistant', content: reply });
-            messages.push({ role: 'user', content: COMPLETION_REPAIR_INSTRUCTION });
-            continue;
-        }
-        // Not done yet — `reply` is the next question. Post it and wait for the answer.
-        messages.push({ role: 'assistant', content: reply });
-        let updated;
-        try {
-            updated = await ctx.mailboxClient.postTurn(ctx.machineToken, job.id, reply);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : 'post-turn failed';
-            return { status: 'failed', result: { error: message } };
-        }
-        turnsSoFar = updated.turns.length;
-        const answered = await waitForUserReply(ctx.mailboxClient, ctx.machineToken, job.id, turnsSoFar);
-        if (!answered) {
-            return {
-                status: 'failed',
-                result: { error: 'Timed out waiting for a reply — no response within 10 minutes.' },
-            };
-        }
-        const lastTurn = answered.turns[answered.turns.length - 1];
-        // ENG-153: the employee's reply may include image attachments — attach them
-        // as vision blocks (image-free replies stay a plain string, as before).
-        messages.push({
-            role: 'user',
-            content: lastTurn ? await apiUserTurnContent(lastTurn) : '',
-        });
-        turnsSoFar = answered.turns.length;
-    }
-    // Turn budget exhausted. If we already produced an ER (fresh create or a
-    // continuation's target), finalize with it best-effort rather than losing the
-    // work (bug #3); only fail outright if nothing was ever submitted.
-    return currentErId
-        ? { status: 'done', result: { epicRequestId: currentErId } }
-        : {
-            status: 'failed',
-            result: { error: `Interview did not converge after ${String(MAX_INTERVIEW_TURNS)} turns.` },
-        };
-}
 /**
  * Fixed working directory for every `claude` CLI invocation made by the
  * subscription-mode invoker. Two reasons this must be a stable, dedicated
@@ -676,11 +301,11 @@ function claudeCliSessionCwd() {
  */
 function runClaudeCliTurn(prompt, opts) {
     return new Promise((resolve, reject) => {
+        const model = opts.model === undefined ? ANTHROPIC_MODEL : opts.model;
         const args = [
             '-p',
             prompt,
-            '--model',
-            ANTHROPIC_MODEL,
+            ...(model ? ['--model', model] : []),
             '--output-format',
             'json',
             '--tools',
@@ -768,123 +393,91 @@ function runClaudeCliTurn(prompt, opts) {
         });
     });
 }
+// ---------------------------------------------------------------------
+// Request conversations (always open): one AI reply per claim.
+// ---------------------------------------------------------------------
+/** The request this conversation already saved, read with the person's token. */
+async function loadSavedRequest(apiBaseUrl, userApiToken, epicRequestId) {
+    const res = await fetch(`${apiBaseUrl.replace(/\/+$/, '')}/api/v1/epic-requests/${encodeURIComponent(epicRequestId)}`, { headers: { Authorization: `Bearer ${userApiToken}` } });
+    if (!res.ok)
+        return null;
+    const body = (await res.json().catch(() => null));
+    return savedContextFromRecord(body?.data);
+}
 /**
- * Runs the epic_request interview end-to-end using the local `claude` CLI
- * (the employee's own Claude Code login) instead of the Anthropic API.
- * Mirrors invokeEpicRequestViaApi's turn loop and completion handling
- * exactly — only how a single assistant turn is produced differs.
+ * True when the person's Claude plan can't use the requested model (for
+ * example Fable needs usage credits on some plans): retry on their default.
  */
-export async function invokeEpicRequestViaSubscription(job, ctx) {
-    let sessionId;
-    let turnsSoFar = job.turns.length;
-    // pxpipe (ENG-136): resolve routing once per invocation; reused for every turn.
+export function needsDefaultModel(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /requires usage credits|switch to another model|model.*not available|not have access to/i.test(message);
+}
+function savedRequestIdOf(job) {
+    const result = job.result;
+    if (typeof result?.epicRequestId === 'string')
+        return result.epicRequestId;
+    return parseSeedPayload(job.payload)?.targetEpicRequestId ?? null;
+}
+/**
+ * Takes one step of a request conversation on this computer: the AI's reply to
+ * the person's latest message, which may save or update their request. Then
+ * the job is left waiting on the person (never completed), so the chat stays
+ * open: there is no reply timeout, and the computer is free for other work in
+ * the meantime. The server hands the job back when they write again.
+ *
+ * `anthropicApiKey` set → the Anthropic API; otherwise the local `claude` CLI
+ * on the person's own Claude sign-in.
+ */
+export async function invokeEpicRequestStep(job, ctx) {
+    try {
+        return await takeConversationStep(job, ctx);
+    }
+    catch (error) {
+        // Leave the conversation waiting on the person rather than retrying a
+        // broken step over and over; their next message tries again.
+        const reason = error instanceof Error ? error.message : 'something went wrong';
+        await ctx.mailboxClient.postTurn(ctx.machineToken, job.id, `I couldn't continue: ${reason}\n\nSend another message (for example "try again") and I'll pick up where we left off.`);
+        return { status: 'yield' };
+    }
+}
+async function takeConversationStep(job, ctx) {
     const routing = await resolveRouting();
-    // ENG-149: continuation-aware system prompt + submit path (see api-mode above).
-    const seed = parseSeedPayload(job.payload);
-    const systemPrompt = resolveSystemPrompt(seed);
-    // Audit-gate state (bug #2) — mirrors api-mode.
-    let currentErId = seed?.targetEpicRequestId ?? null;
-    let qualityRounds = 0;
-    let jsonRepairs = 0;
-    // If the daemon restarted mid-interview, there's no local `claude` session
-    // left to --resume (session IDs aren't persisted across daemon restarts
-    // today) — replay the transcript so far as the seed prompt instead of
-    // silently losing context, mirroring how the api-key path seeds its
-    // Anthropic `messages` array from job.turns.
-    let nextPrompt = job.turns.length > 0
-        ? job.turns
-            .map((t) => t.role === 'agent'
-            ? `You asked: ${t.content}`
-            : // ENG-153 (A4): subscription mode has no inline-image channel, so a
-                // user turn's images degrade to an explicit textual note.
-                `They replied: ${appendAttachmentNote(t.content, imageAttachmentCount(t.attachments))}`)
-            .join('\n') +
-            '\n\nContinue the interview from exactly where this left off — ask the next question, or if you already have everything, respond with the completion JSON.'
-        : "Let's begin the interview.";
-    for (let i = 0; i < MAX_INTERVIEW_TURNS; i++) {
-        let turn;
-        try {
-            turn = await runClaudeCliTurn(nextPrompt, {
-                systemPrompt,
-                resumeSessionId: sessionId,
-                routing,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : 'claude CLI invocation failed';
-            return { status: 'failed', result: { error: `Agent invocation failed: ${message}` } };
-        }
-        sessionId = turn.sessionId;
-        const draft = extractCompletionJson(turn.text);
-        if (draft) {
-            let submitted;
+    const requestId = savedRequestIdOf(job);
+    const saved = requestId ? await loadSavedRequest(ctx.apiBaseUrl, ctx.userApiToken, requestId) : null;
+    const turns = job.turns.map((t) => ({
+        role: t.role,
+        content: t.role === 'user' ? appendAttachmentNote(t.content, imageAttachmentCount(t.attachments)) : t.content,
+    }));
+    const anthropic = ctx.anthropicApiKey ? new Anthropic(anthropicClientOptions(ctx.anthropicApiKey, routing)) : null;
+    let cliModel = ANTHROPIC_MODEL;
+    const outcome = await runConversationStep({ turns, saved }, {
+        reply: async (system, messages) => {
+            if (anthropic) {
+                const response = await anthropic.messages.create({ model: ANTHROPIC_MODEL, max_tokens: 4096, system, messages });
+                const text = response.content.find((b) => b.type === 'text');
+                return text?.type === 'text' ? text.text : '';
+            }
+            const prompt = renderConversationPrompt(messages);
             try {
-                submitted = await submitAndScore(ctx, currentErId, draft);
+                return (await runClaudeCliTurn(prompt, { systemPrompt: system, resumeSessionId: undefined, routing, model: cliModel })).text;
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : 'Failed to save the epic request';
-                return { status: 'failed', result: { error: message } };
-            }
-            currentErId = submitted.erId;
-            const compliance = submitted.compliance;
-            if (meetsComplianceTarget(compliance) || qualityRounds >= MAX_QUALITY_ROUNDS) {
-                return { status: 'done', result: { epicRequestId: currentErId } };
-            }
-            // Feed the failing rules back into the SAME resumed session (no user turn);
-            // the model re-emits a richer completion or asks a targeted question next.
-            // (compliance is non-null here — see the api-mode note above.)
-            qualityRounds++;
-            if (compliance !== null) {
-                nextPrompt = buildAuditFeedback(compliance);
-            }
-            continue;
-        }
-        // Malformed completion (see api-mode): correct the model rather than relaying
-        // raw JSON to the employee; bounded, then fail cleanly.
-        if (looksLikeCompletionAttempt(turn.text)) {
-            if (jsonRepairs >= MAX_JSON_REPAIRS) {
-                return {
-                    status: 'failed',
-                    result: {
-                        error: 'The interview produced malformed completion data and could not be finalized after several attempts.',
-                    },
-                };
+                if (cliModel === null || !needsDefaultModel(error))
+                    throw error;
+                cliModel = null;
+                return (await runClaudeCliTurn(prompt, { systemPrompt: system, resumeSessionId: undefined, routing, model: null })).text;
             }
-            jsonRepairs++;
-            nextPrompt = COMPLETION_REPAIR_INSTRUCTION;
-            continue;
-        }
-        // Not done yet — turn.text is the next question. Post it and wait for the answer.
-        let updated;
-        try {
-            updated = await ctx.mailboxClient.postTurn(ctx.machineToken, job.id, turn.text);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : 'post-turn failed';
-            return { status: 'failed', result: { error: message } };
-        }
-        turnsSoFar = updated.turns.length;
-        const answered = await waitForUserReply(ctx.mailboxClient, ctx.machineToken, job.id, turnsSoFar);
-        if (!answered) {
-            return {
-                status: 'failed',
-                result: { error: 'Timed out waiting for a reply — no response within 10 minutes.' },
-            };
-        }
-        const lastTurn = answered.turns[answered.turns.length - 1];
-        // ENG-153 (A4): note any attached images textually (subscription-mode degradation).
-        nextPrompt = lastTurn
-            ? appendAttachmentNote(lastTurn.content, imageAttachmentCount(lastTurn.attachments))
-            : '';
-        turnsSoFar = answered.turns.length;
+        },
+        save: async (existingId, draft) => {
+            const submitted = await submitAndScore(ctx, existingId, draft);
+            return { id: submitted.erId, title: draft.title, compliance: submitted.compliance };
+        },
+    });
+    if (outcome.kind === 'saved') {
+        await ctx.mailboxClient.markRequestSaved(ctx.machineToken, job.id, outcome.saved.id);
     }
-    // Budget exhausted — finalize best-effort if we produced an ER (bug #3).
-    return currentErId
-        ? { status: 'done', result: { epicRequestId: currentErId } }
-        : {
-            status: 'failed',
-            result: { error: `Interview did not converge after ${String(MAX_INTERVIEW_TURNS)} turns.` },
-        };
+    await ctx.mailboxClient.postTurn(ctx.machineToken, job.id, outcome.text);
+    return { status: 'yield' };
 }
 // ---------------------------------------------------------------------
 // start_execution / kind:'plan' (ENG-164) — run the local @planner headless
@@ -922,6 +515,25 @@ export const PLANNER_HEARTBEAT_INTERVAL_MS = 20 * 1_000;
 const PLANNER_FINAL_TURN_MAX_CHARS = 4_000;
 /** The literal marker token the orchestrator emits (ENG-162); kept in sync for compatibility. */
 const ORCHESTRATOR_REVIEW_MARKER = 'COMPBOX_NEEDS_HUMAN_REVIEW';
+/**
+ * Finishes a run made on the person's API key: reads Claude Code's JSON
+ * result, reports the run's usage to CompBox (best-effort), and returns the
+ * plain text the run would otherwise have printed.
+ */
+export function takeKeyRunResult(ctx, keyRun, stdout) {
+    const parsed = parseClaudeJsonResult(stdout, keyRun.model);
+    if (!parsed)
+        return { text: stdout, reported: Promise.resolve() };
+    const reported = ctx.mailboxClient
+        .reportAiUsage(ctx.machineToken, ctx.jobId, parsed.usage)
+        .catch(() => undefined);
+    return { text: parsed.text, reported };
+}
+async function settleKeyRun(ctx, keyRun, stdout) {
+    const { text, reported } = takeKeyRunResult(ctx, keyRun, stdout);
+    await reported;
+    return text;
+}
 /**
  * Build the `claude` argv for a headless planner run (H1). Pure + exported so a
  * unit test can assert the exact command shape: the `@planner` routing prompt,
@@ -1099,16 +711,17 @@ export async function invokeStartExecutionPlan(ctx, deps = {}) {
     }
     const routing = await resolveRoutingImpl();
     const command = resolveClaudeBinary() ?? 'claude';
-    const args = buildPlannerArgs(ctx.epicRequestId);
+    const args = ctx.keyRun ? keyRunArgs(buildPlannerArgs(ctx.epicRequestId)) : buildPlannerArgs(ctx.epicRequestId);
     // pxpipe (ENG-136): inject ANTHROPIC_BASE_URL when routed. COMPBOX_NONINTERACTIVE
     // forces the planner's headless path even if the prompt flag were dropped. PATH
     // is augmented (ENG-135) so `claude` and any helpers it spawns resolve.
     const routedEnv = claudeSpawnEnv(process.env, routing);
-    const childEnv = {
+    const baseEnv = {
         ...routedEnv,
         COMPBOX_NONINTERACTIVE: '1',
         PATH: claudeChildEnvPath(routedEnv.PATH),
     };
+    const childEnv = ctx.keyRun ? keyRunEnv(baseEnv, ctx.keyRun) : baseEnv;
     // H4: relay a START turn immediately so the web shows the run began even if the
     // planner produces no stdout for minutes. postTurn failures are swallowed —
     // streaming is best-effort and must never fail the job.
@@ -1171,6 +784,8 @@ export async function invokeStartExecutionPlan(ctx, deps = {}) {
         });
         child.on('close', (code) => {
             void (async () => {
+                if (ctx.keyRun)
+                    stdout = await settleKeyRun(ctx, ctx.keyRun, stdout);
                 const combined = `${stdout}\n${stderr}`;
                 // A needs-review outcome wins regardless of exit code: the planner may
                 // exit 0 after emitting the marker. Surface it to the web (not silent).
@@ -1356,6 +971,18 @@ export function defaultToolchainPresent(_dir) {
     }
     return false;
 }
+/** Plain-language summary of where a run's code ended up. */
+export function describeRunBranch(finish) {
+    if (finish.prUrl)
+        return `Pull request: ${finish.prUrl}`;
+    if (finish.compareUrl)
+        return `Branch ${finish.branch} was pushed. Open the pull request here: ${finish.compareUrl}`;
+    if (finish.commits === 0)
+        return 'No code changes were made.';
+    if (finish.pushed)
+        return `Branch ${finish.branch} was pushed.`;
+    return `The work is on branch ${finish.branch}${finish.keptWorktree ? ` (in ${finish.keptWorktree})` : ''}.`;
+}
 /** Read a string field off a parsed marker object, or undefined. */
 function markerString(marker, key) {
     const v = marker?.[key];
@@ -1427,23 +1054,39 @@ export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
     if (!toolchainPresent(projectDir)) {
         return { status: 'failed', result: { error: toolchainMissingMessage(projectDir) } };
     }
+    // Each run gets its own branch + worktree, so it never touches the person's
+    // checkout and always ends as a reviewable pull request.
+    let workspace = null;
+    let workspaceNotes = [];
+    if (deps.workspace) {
+        const prepared = await deps.workspace.prepare(projectDir, ctx.epicId);
+        if (!prepared.ok) {
+            return { status: 'failed', result: { error: prepared.error } };
+        }
+        workspace = prepared.workspace;
+        workspaceNotes = prepared.notes;
+    }
+    const runDir = workspace?.dir ?? projectDir;
     const routing = await resolveRoutingImpl();
     const command = resolveClaudeBinary() ?? 'claude';
-    const args = buildOrchestratorArgs(ctx.epicId);
+    const args = ctx.keyRun ? keyRunArgs(buildOrchestratorArgs(ctx.epicId)) : buildOrchestratorArgs(ctx.epicId);
     // pxpipe (ENG-136): inject ANTHROPIC_BASE_URL when routed. COMPBOX_NONINTERACTIVE
     // forces the orchestrator's headless serial-in-process path (H3) even if the
     // prompt flag were dropped. PATH is augmented (ENG-135) so `claude` and any
     // helpers it spawns resolve on a launchd/GUI-spawned daemon.
     const routedEnv = claudeSpawnEnv(process.env, routing);
-    const childEnv = {
+    const baseEnv = {
         ...routedEnv,
         COMPBOX_NONINTERACTIVE: '1',
         PATH: claudeChildEnvPath(routedEnv.PATH),
     };
+    const childEnv = ctx.keyRun ? keyRunEnv(baseEnv, ctx.keyRun) : baseEnv;
     // H4: relay a START turn immediately so the web shows the run began even if the
     // orchestrator produces no stdout for minutes. postTurn failures are swallowed.
     try {
-        await ctx.mailboxClient.postTurn(ctx.machineToken, ctx.jobId, `Started the orchestrator for epic ${ctx.epicId} (headless, non-interactive). This executes the full epic — every phase and feature — and may take a long time.`);
+        await ctx.mailboxClient.postTurn(ctx.machineToken, ctx.jobId, `Started the orchestrator for epic ${ctx.epicId} (headless, non-interactive). This executes the full epic — every phase and feature — and may take a long time.` +
+            (workspace ? ` Working on a new branch, ${workspace.branch}, which will end as a pull request into ${workspace.baseBranch}.` : '') +
+            (workspaceNotes.length > 0 ? ` Note: ${workspaceNotes.join(' ')}` : ''));
     }
     catch {
         // Best-effort start turn.
@@ -1453,7 +1096,7 @@ export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
         let stderr = '';
         let settled = false;
         const child = spawnImpl(command, args, {
-            cwd: projectDir,
+            cwd: runDir,
             stdio: ['ignore', 'pipe', 'pipe'],
             env: childEnv,
         });
@@ -1502,6 +1145,9 @@ export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
             });
         });
         child.on('close', (code) => {
+            // Usage is reported in the background; the run's outcome doesn't wait on it.
+            if (ctx.keyRun)
+                stdout = takeKeyRunResult(ctx, ctx.keyRun, stdout).text;
             const combined = `${stdout}\n${stderr}`;
             // ENG-165-3: a HARD-gate needs-review outcome wins regardless of exit code
             // — the orchestrator emits the marker and STOPs, and may exit 0. Surface
@@ -1529,11 +1175,40 @@ export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
             finish({ status: 'done', result: { epicId: ctx.epicId } });
         });
     });
+    // Commit what's left, push the branch and open the pull request (draft when
+    // the run stopped early), then attach where the code is to the job result.
+    let branchLine = '';
+    if (deps.workspace && workspace) {
+        const resultError = outcome.result;
+        const stopReason = typeof resultError.message === 'string'
+            ? resultError.message
+            : typeof resultError.error === 'string'
+                ? resultError.error.split('\n')[0]
+                : undefined;
+        const finished = await deps.workspace.finish({
+            workspace,
+            epicId: ctx.epicId,
+            jobId: ctx.jobId,
+            completed: outcome.status === 'done',
+            ...(stopReason ? { stopReason } : {}),
+        });
+        branchLine = describeRunBranch(finished);
+        outcome.result = {
+            ...outcome.result,
+            branch: finished.branch,
+            commits: finished.commits,
+            pushed: finished.pushed,
+            ...(finished.prUrl ? { prUrl: finished.prUrl } : {}),
+            ...(finished.compareUrl ? { compareUrl: finished.compareUrl } : {}),
+            ...(finished.notes.length > 0 ? { branchNotes: finished.notes } : {}),
+        };
+    }
     // H4: relay a FINAL turn summarizing the outcome (best-effort).
     try {
-        const summary = outcome.status === 'done'
+        const summary = (outcome.status === 'done'
             ? `Execution complete — epic ${ctx.epicId} finished all phases.`
-            : `Orchestrator run ended: ${JSON.stringify(outcome.result).slice(0, ORCHESTRATOR_FINAL_TURN_MAX_CHARS)}`;
+            : `Orchestrator run ended: ${JSON.stringify(outcome.result).slice(0, ORCHESTRATOR_FINAL_TURN_MAX_CHARS)}`) +
+            (branchLine ? `\n${branchLine}` : '');
         await ctx.mailboxClient.postTurn(ctx.machineToken, ctx.jobId, summary);
     }
     catch {