@mycompbox/compbox-cli 1.13.0

package/utils/agent-invoker.js

@@ -0,0 +1,1632 @@
+/**
+ * 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):
+ *   - `api`: Anthropic Messages API, directly (Anthropic API key, billed
+ *     per-token). See invokeEpicRequestViaApi.
+ *   - `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.
+ *
+ * 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.
+ */
+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 { claudeChildEnvPath, claudeNotFoundMessage, resolveClaudeBinary, } from './claude-runtime.js';
+import { isGitRepoDir } from './config-store.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
+/**
+ * pxpipe routing (ENG-136). Anthropic SDK options carrying the proxy `baseURL`
+ * when routed through pxpipe, otherwise just the API key. Pure — unit tested.
+ */
+export function anthropicClientOptions(apiKey, routing) {
+    return routing.mode === 'proxy'
+        ? { apiKey, baseURL: routing.anthropicBaseUrl }
+        : { apiKey };
+}
+/**
+ * pxpipe routing (ENG-136). Child-process env carrying `ANTHROPIC_BASE_URL` when
+ * routed through pxpipe, otherwise the base env unchanged. Pure — unit tested.
+ */
+export function claudeSpawnEnv(base, routing) {
+    return routing.mode === 'proxy'
+        ? { ...base, ANTHROPIC_BASE_URL: routing.anthropicBaseUrl }
+        : base;
+}
+// ---------------------------------------------------------------------
+// Image attachments (ENG-153). A user turn can carry image attachments
+// (ENG-151 read-contract). In API mode they become Anthropic vision content
+// blocks; in subscription mode — where `claude -p <prompt>` has no channel for
+// inline image bytes — they degrade to an explicit textual note (A4) and rely
+// on API mode for actual vision. Everything here is deliberately kept pure /
+// injectable so the mapping is unit-testable without a network.
+// ---------------------------------------------------------------------
+/** The image media types the Anthropic base64 image source accepts. */
+const SUPPORTED_IMAGE_MEDIA_TYPES = [
+    'image/jpeg',
+    'image/png',
+    'image/gif',
+    'image/webp',
+];
+/** Max images fed to the model per turn (bound cost + prompt size). */
+const MAX_IMAGES_PER_TURN = 8;
+/** Max cumulative image bytes per turn — a sane cap on a single vision turn. */
+const MAX_IMAGE_BYTES_PER_TURN = 20 * 1024 * 1024; // 20 MB
+const defaultWarn = (message) => {
+    console.warn(`  ⚠ ${message}`);
+};
+/**
+ * Normalize a raw MIME string (which may carry a `; charset=...` parameter or
+ * odd casing) to one of the four supported image media types, or null when it
+ * is not a supported image type. Pure.
+ */
+function normalizeImageMediaType(mime) {
+    const base = (mime.split(';')[0] ?? '').trim().toLowerCase();
+    return SUPPORTED_IMAGE_MEDIA_TYPES.includes(base)
+        ? base
+        : null;
+}
+/** Whether a MIME type is a supported (vision-capable) image type. Pure. */
+export function isSupportedImageMediaType(mime) {
+    return normalizeImageMediaType(mime) !== null;
+}
+/**
+ * Select the image attachments to actually fetch for a turn: supported image
+ * types only, capped by count and by cumulative DECLARED bytes (the real fetched
+ * bytes are re-capped in {@link fetchImageBlocks}). Non-images and over-budget
+ * entries are dropped. Pure — no network, no warnings.
+ */
+export function selectImageAttachments(attachments) {
+    if (!attachments || attachments.length === 0)
+        return [];
+    const selected = [];
+    let declaredBytes = 0;
+    for (const att of attachments) {
+        if (selected.length >= MAX_IMAGES_PER_TURN)
+            break;
+        if (!isSupportedImageMediaType(att.mimeType))
+            continue;
+        const size = typeof att.sizeBytes === 'number' && att.sizeBytes > 0 ? att.sizeBytes : 0;
+        if (declaredBytes + size > MAX_IMAGE_BYTES_PER_TURN)
+            continue;
+        declaredBytes += size;
+        selected.push(att);
+    }
+    return selected;
+}
+/** Count of supported image attachments on a turn (for the subscription note). Pure. */
+export function imageAttachmentCount(attachments) {
+    if (!attachments || attachments.length === 0)
+        return 0;
+    return attachments.filter((a) => isSupportedImageMediaType(a.mimeType)).length;
+}
+/**
+ * Fetch the bytes for each already-selected attachment and turn them into
+ * Anthropic base64 image blocks. A broken/unreachable/empty attachment is
+ * SKIPPED with a warning — never fatal (requirement 5). Cumulative FETCHED bytes
+ * are capped so a lying `sizeBytes` can't blow the budget. `fetchImpl` is
+ * injectable for tests.
+ */
+export async function fetchImageBlocks(attachments, warn = defaultWarn, fetchImpl = fetch) {
+    const blocks = [];
+    let totalBytes = 0;
+    for (const att of attachments) {
+        const mediaType = normalizeImageMediaType(att.mimeType);
+        if (!mediaType)
+            continue; // already filtered, but keeps the type honest
+        try {
+            const res = await fetchImpl(att.signedUrl);
+            if (!res.ok) {
+                warn(`Skipping image attachment ${att.id}: fetch failed (HTTP ${String(res.status)}).`);
+                continue;
+            }
+            const bytes = Buffer.from(await res.arrayBuffer());
+            if (bytes.byteLength === 0) {
+                warn(`Skipping image attachment ${att.id}: empty response body.`);
+                continue;
+            }
+            if (totalBytes + bytes.byteLength > MAX_IMAGE_BYTES_PER_TURN) {
+                warn(`Skipping image attachment ${att.id}: exceeds the per-turn image byte budget.`);
+                continue;
+            }
+            totalBytes += bytes.byteLength;
+            blocks.push({
+                type: 'image',
+                source: { type: 'base64', media_type: mediaType, data: bytes.toString('base64') },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'unknown error';
+            warn(`Skipping image attachment ${att.id}: ${message}.`);
+        }
+    }
+    return blocks;
+}
+/**
+ * Assemble a user-message `content` for API mode: the raw string when there are
+ * no image blocks (byte-identical to the pre-ENG-153 behavior), otherwise an
+ * ordered `[...images, {text}]` content array (images first — Anthropic's
+ * recommended ordering for a vision prompt). Pure.
+ */
+export function buildApiUserContent(text, imageBlocks) {
+    if (imageBlocks.length === 0)
+        return text;
+    return [...imageBlocks, { type: 'text', text }];
+}
+/**
+ * The `content` to push for a USER turn in API mode: fetches + attaches image
+ * blocks when the turn has image attachments, otherwise returns the plain text
+ * unchanged (no fetch, no warning — a turn with no attachments behaves exactly
+ * as today). `fetchImpl` is injectable for tests.
+ */
+export async function apiUserTurnContent(turn, warn = defaultWarn, fetchImpl = fetch) {
+    const selected = selectImageAttachments(turn.attachments);
+    if (selected.length === 0)
+        return turn.content;
+    const blocks = await fetchImageBlocks(selected, warn, fetchImpl);
+    return buildApiUserContent(turn.content, blocks);
+}
+/**
+ * Subscription-mode (A4) degradation: append an explicit `[N image(s)
+ * attached]` note to the prompt text when the turn carries images (the local
+ * `claude -p` invocation has no inline-image channel, so vision is deferred to
+ * API mode). Returns the text UNCHANGED when there are no images, so a
+ * no-attachment turn is byte-identical to today. Pure.
+ */
+export function appendAttachmentNote(text, imageCount) {
+    if (imageCount <= 0)
+        return text;
+    const noun = imageCount === 1 ? 'image' : 'images';
+    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
+ * (empty/absent payload). Validates the two ids are present; tolerates a
+ * missing/malformed `priorTranscript` by defaulting it to empty (the daemon
+ * still seeds context from the job's own `turns`, which ENG-148 copies into
+ * jobB). Exported for unit testing.
+ */
+export function parseSeedPayload(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return null;
+    const p = payload;
+    if (typeof p.seedFromInterviewId !== 'string' ||
+        typeof p.targetEpicRequestId !== 'string') {
+        return null;
+    }
+    const priorTranscript = Array.isArray(p.priorTranscript)
+        ? p.priorTranscript.filter((t) => typeof t === 'object' &&
+            t !== null &&
+            typeof t.role === 'string' &&
+            typeof t.content === 'string')
+        : [];
+    return {
+        seedFromInterviewId: p.seedFromInterviewId,
+        targetEpicRequestId: p.targetEpicRequestId,
+        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
+ * (`currentErId === null`) CREATES the ER; every later quality round UPDATES that
+ * same ER. Continuation: `currentErId` is the target ER from the start, so every
+ * submit UPDATES it in place (never a duplicate). Returns the ER id plus its
+ * compliance summary (null when the server attaches none).
+ */
+export async function submitAndScore(ctx, currentErId, draft) {
+    if (currentErId) {
+        const compliance = await updatePersonalEpicRequest(ctx.apiBaseUrl, ctx.userApiToken, currentErId, draft);
+        return { erId: currentErId, compliance };
+    }
+    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
+ * directory rather than wherever `compbox run` happens to be launched from:
+ *   1. `claude --resume <sessionId>` is scoped to the cwd the session was
+ *      created in — resuming from a different cwd fails with "No
+ *      conversation found with session ID: ...", verified against a real
+ *      Claude Code install (2.1.202).
+ *   2. Pinning to a directory CompBox owns (rather than an arbitrary
+ *      project checkout) avoids picking up an unrelated CLAUDE.md/.mcp.json
+ *      from whatever directory the daemon happened to start in.
+ */
+function claudeCliSessionCwd() {
+    const dir = join(homedir(), '.compbox', 'claude-sessions');
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        // Best-effort — if this fails, the spawn below will surface a clear ENOENT/EACCES.
+    }
+    return dir;
+}
+/**
+ * Runs exactly one assistant turn via the local `claude` CLI in non-interactive
+ * print mode. Deliberately NOT `--bare`: that flag forces API-key-only auth
+ * ("OAuth and keychain are never read"), which would silently defeat the
+ * whole point of subscription mode. Deliberately `--tools ""`: this is the
+ * documented way to guarantee zero tool access (no Bash/Read/Write/Edit/
+ * WebFetch), so an unattended interview can never touch the filesystem or
+ * run commands on the employee's machine.
+ *
+ * Deliberately `--safe-mode`: verified live that WITHOUT it, the model picks
+ * up the employee's own `~/.claude/CLAUDE.md` (project/global customizations
+ * are loaded regardless of `--system-prompt`, which only overrides the
+ * *default* system prompt text, not CLAUDE.md/skills/agents auto-discovery).
+ * In testing, a system prompt that merely contained the word
+ * "request-formulator" was enough for the model to follow this repo's own
+ * "@agent-name routing" CLAUDE.md rule and try to read a real file from this
+ * project — a real prompt-injection-shaped leak, not hypothetical.
+ * `--safe-mode` disables CLAUDE.md/skills/plugins/hooks/agents entirely
+ * while explicitly leaving auth/model/permissions untouched (unlike
+ * `--bare`, confirmed NOT to force API-key auth).
+ *
+ * Deliberately re-passing `--system-prompt` on EVERY turn, including resumed
+ * ones: verified live that omitting it on a `--resume` call makes the model
+ * silently fall back to Claude Code's default coding-agent system prompt for
+ * that turn (conversation history is preserved, but the persona/instructions
+ * are not) — it started inspecting the working directory and offering to
+ * write files instead of continuing the bounded interview. There is no
+ * "reuse the resumed session's system prompt" behavior to rely on.
+ *
+ * Multi-turn state is carried by `claude`'s own session store via
+ * `--resume`, not by resending a transcript — cheaper and matches how a
+ * human would use the CLI.
+ */
+function runClaudeCliTurn(prompt, opts) {
+    return new Promise((resolve, reject) => {
+        const args = [
+            '-p',
+            prompt,
+            '--model',
+            ANTHROPIC_MODEL,
+            '--output-format',
+            'json',
+            '--tools',
+            '',
+            '--permission-mode',
+            'dontAsk',
+            '--safe-mode',
+            '--system-prompt',
+            opts.systemPrompt,
+        ];
+        if (opts.resumeSessionId) {
+            args.push('--resume', opts.resumeSessionId);
+        }
+        // ENG-135: resolve `claude` to an absolute path using the login-shell PATH
+        // + well-known install dirs. A launchd/GUI-spawned daemon inherits a PATH
+        // that often lacks ~/.local/bin, so a bare-name spawn fails "not found on
+        // PATH" even though claude is installed. Fall back to the bare name when
+        // resolution fails so the augmented child PATH gets one more chance; the
+        // ENOENT handler below then reports the actionable, searched-dirs message.
+        const command = resolveClaudeBinary() ?? 'claude';
+        // pxpipe (ENG-136): inject ANTHROPIC_BASE_URL when routed; unchanged
+        // otherwise. Layered on top (ENG-135): augment PATH with the login-shell +
+        // well-known dirs so the child (and any helpers it spawns) can be located.
+        const pxpipeEnv = claudeSpawnEnv(process.env, opts.routing);
+        const child = spawn(command, args, {
+            cwd: claudeCliSessionCwd(),
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...pxpipeEnv, PATH: claudeChildEnvPath(pxpipeEnv.PATH) },
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill('SIGKILL');
+            reject(new Error(`claude CLI timed out after ${String(CLAUDE_CLI_TURN_TIMEOUT_MS / 1000)}s`));
+        }, CLAUDE_CLI_TURN_TIMEOUT_MS);
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf-8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf-8');
+        });
+        child.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error.code === 'ENOENT') {
+                // ENG-135: actionable message naming every location that was searched.
+                reject(new Error(claudeNotFoundMessage()));
+                return;
+            }
+            reject(error);
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (code !== 0) {
+                reject(new Error(stderr.trim() || `claude CLI exited with code ${String(code ?? 'null')}`));
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout);
+            }
+            catch {
+                reject(new Error(`claude CLI returned non-JSON output: ${stdout.slice(0, 500)}`));
+                return;
+            }
+            const shaped = parsed;
+            if (shaped.is_error) {
+                reject(new Error(shaped.result ?? 'claude CLI reported an error'));
+                return;
+            }
+            if (typeof shaped.result !== 'string' || typeof shaped.session_id !== 'string') {
+                reject(new Error('claude CLI returned an unexpected JSON shape (missing result/session_id).'));
+                return;
+            }
+            resolve({ text: shaped.result, sessionId: shaped.session_id });
+        });
+    });
+}
+/**
+ * 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.
+ */
+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.
+    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;
+            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;
+            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.',
+                    },
+                };
+            }
+            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;
+    }
+    // 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.` },
+        };
+}
+// ---------------------------------------------------------------------
+// start_execution / kind:'plan' (ENG-164) — run the local @planner headless
+// against an approved Epic Request, in the PROJECT REPO so the repo's
+// `.mcp.json` (CompBox MCP) and `CLAUDE.md` (@agent routing) load. This is the
+// DELIBERATE OPPOSITE of the interview invoker above: NO `--tools ""` and NO
+// `--safe-mode` (those exist to keep the unattended INTERVIEW tool-less and
+// CLAUDE.md-blind — see runClaudeCliTurn). The planner genuinely needs MCP
+// tools + @agent routing, so it runs with an unattended permission mode
+// (`bypassPermissions`, H1) that lets tool use proceed in print mode without
+// ever blocking on an interactive "allow?" prompt.
+// ---------------------------------------------------------------------
+/**
+ * Per-run wall-clock budget for the headless planner child (H4). Deliberately
+ * FAR larger than the interview's {@link CLAUDE_CLI_TURN_TIMEOUT_MS} (~2 min):
+ * a full 5-stage `--from-request` planning pipeline (analyze → decompose →
+ * detail → evaluate → verify, with many MCP calls and self-correction passes)
+ * routinely runs many minutes. 30 minutes bounds a hung run without cutting a
+ * legitimate one short.
+ */
+export const PLANNER_RUN_TIMEOUT_MS = 30 * 60 * 1_000;
+/**
+ * Cadence for the keep-alive heartbeat fired WHILE the planner child runs (H4).
+ * The daemon's own 60s runtime heartbeat lives in the poll loop, which is
+ * blocked for the entire (long) duration of this job — so without an
+ * independent heartbeat here the machine's `lastSeenAt` goes stale and central
+ * flips it offline mid-run. This interval pings on its own timer until the
+ * child exits.
+ */
+export const PLANNER_HEARTBEAT_INTERVAL_MS = 60 * 1_000;
+/** Max chars of planner output relayed in the final mailbox turn (bound turn size). */
+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';
+/**
+ * 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,
+ * an unattended permission mode, and — critically — the ABSENCE of `--tools ""`
+ * and `--safe-mode` (which would strip the MCP tools and @agent routing the
+ * planner depends on). No `--system-prompt` (the persona comes from CLAUDE.md
+ * routing) and no `--model` override (planning is reasoning-heavy; let the
+ * account default apply — pxpipe routing rides on ANTHROPIC_BASE_URL, not the
+ * model name).
+ */
+export function buildPlannerArgs(epicRequestId) {
+    return [
+        '-p',
+        `@planner --from-request ${epicRequestId} --gates=auto --non-interactive`,
+        // H1: an unattended permission mode so tool use in this print-mode run never
+        // blocks on an interactive "allow?" prompt (the interview path is safe only
+        // because it grants ZERO tools; this path grants the full MCP surface).
+        '--permission-mode',
+        'bypassPermissions',
+    ];
+}
+/** Actionable failure when no project repo is configured (mirrors ENG-135's not-found copy). */
+export function projectDirNotConfiguredMessage() {
+    return [
+        'No CompBox project repository is configured for this machine, so the planner has nowhere to run.',
+        'Set one of the following (checked in this order) and re-run the job:',
+        '  - `compbox run --project-dir <path-to-your-checkout>` (persisted for future runs)',
+        '  - the COMPBOX_PROJECT_DIR environment variable',
+        'The path must be a git checkout of the CompBox repo (it needs the repo\'s .mcp.json and CLAUDE.md).',
+    ].join('\n');
+}
+/** Actionable failure when the configured path is not a git repository. */
+export function projectDirNotGitRepoMessage(dir) {
+    return [
+        `The configured CompBox project directory is not a git repository: ${dir}`,
+        'The planner runs the local `claude` CLI in this directory so the repo\'s .mcp.json (CompBox MCP)',
+        'and CLAUDE.md (@agent routing) load — both require a real checkout.',
+        'Point --project-dir / COMPBOX_PROJECT_DIR at a git checkout of the CompBox repo and re-run the job.',
+    ].join('\n');
+}
+/** Parse the first balanced top-level `{...}` JSON objects out of arbitrary text (string-aware). */
+function scanJsonObjects(text) {
+    const objs = [];
+    let depth = 0;
+    let start = -1;
+    let inStr = false;
+    let esc = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (ch === '\\')
+                esc = true;
+            else if (ch === '"')
+                inStr = false;
+            continue;
+        }
+        if (ch === '"') {
+            inStr = true;
+        }
+        else if (ch === '{') {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (ch === '}' && depth > 0) {
+            depth--;
+            if (depth === 0 && start !== -1) {
+                try {
+                    const parsed = JSON.parse(text.slice(start, i + 1));
+                    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                        objs.push(parsed);
+                    }
+                }
+                catch {
+                    // Not valid JSON — skip this span.
+                }
+                start = -1;
+            }
+        }
+    }
+    return objs;
+}
+/**
+ * Detect a planner (or orchestrator-compatible) "needs human review" outcome in
+ * the child's output (ENG-164-4). Matches BOTH markers so detection stays
+ * compatible across the pipeline:
+ *
+ *   - Planner (ENG-161): a JSON object whose `outcome` is `"needs-human-review"`
+ *     (emitted as the final output when EVALUATE lands advisory/critical-fail in
+ *     non-interactive mode) — see `.github/agents/claude/planner.md` Stage 4.
+ *   - Orchestrator (ENG-162): a `COMPBOX_NEEDS_HUMAN_REVIEW {json}` prefixed
+ *     final line — matched by prefix, exactly as ENG-165 will parse it.
+ *
+ * Pure + exported for unit testing. Fail-safe: if the phrase is present but no
+ * clean JSON object can be isolated, it still reports `needsReview: true` (better
+ * to surface for review than to mis-report success).
+ */
+export function detectNeedsHumanReview(output) {
+    const prefixIdx = output.lastIndexOf(ORCHESTRATOR_REVIEW_MARKER);
+    if (prefixIdx !== -1) {
+        const after = output.slice(prefixIdx + ORCHESTRATOR_REVIEW_MARKER.length);
+        const marker = scanJsonObjects(after)[0];
+        return { needsReview: true, marker: marker ?? { status: 'needs_human_review' } };
+    }
+    if (output.includes('needs-human-review')) {
+        const marker = scanJsonObjects(output).find((o) => o.outcome === 'needs-human-review');
+        return { needsReview: true, marker: marker ?? { outcome: 'needs-human-review' } };
+    }
+    return { needsReview: false };
+}
+/** Fetch the Epic Request and read the epic it was converted into (source of truth for the produced epicId). */
+async function fetchConvertedEpicId(apiBaseUrl, userApiToken, epicRequestId, fetchImpl) {
+    try {
+        const res = await fetchImpl(`${apiBaseUrl.replace(/\/+$/, '')}/api/v1/epic-requests/${encodeURIComponent(epicRequestId)}`, { headers: { Authorization: `Bearer ${userApiToken}` } });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        const id = body.data?.convertedEpicId;
+        return typeof id === 'string' && id.length > 0 ? id : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the planner headless for a `start_execution`/`plan` job (ENG-164).
+ *
+ * Flow: validate the project repo → spawn the local `claude` CLI in that repo
+ * cwd with MCP + CLAUDE.md routing enabled (H1: unattended permission mode, NOT
+ * `--tools ""`/`--safe-mode`) running `@planner --from-request <ER> --gates=auto
+ * --non-interactive` with `COMPBOX_NONINTERACTIVE=1` and pxpipe's
+ * `ANTHROPIC_BASE_URL` preserved → keep the machine alive with a periodic
+ * heartbeat during the long run (H4) → relay a start + final turn to the
+ * mailbox → on a clean run resolve the produced epic id from the ER's
+ * `convertedEpicId` and complete `{ epicId }`; on a needs-review outcome or a
+ * non-zero exit, fail with a result the web failure banner can display.
+ */
+export async function invokeStartExecutionPlan(ctx, deps = {}) {
+    const spawnImpl = deps.spawnImpl ?? spawn;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const isGitRepo = deps.isGitRepo ?? isGitRepoDir;
+    const resolveRoutingImpl = deps.resolveRoutingImpl ?? resolveRouting;
+    const heartbeatIntervalMs = deps.heartbeatIntervalMs ?? PLANNER_HEARTBEAT_INTERVAL_MS;
+    const timeoutMs = deps.timeoutMs ?? PLANNER_RUN_TIMEOUT_MS;
+    // H2: the repo must be configured and a real git checkout, or the planner has
+    // nowhere to load .mcp.json/CLAUDE.md from — fail fast with actionable copy
+    // rather than spawning into a non-repo (or hanging).
+    if (!ctx.projectDir) {
+        return { status: 'failed', result: { error: projectDirNotConfiguredMessage() } };
+    }
+    if (!isGitRepo(ctx.projectDir)) {
+        return { status: 'failed', result: { error: projectDirNotGitRepoMessage(ctx.projectDir) } };
+    }
+    const routing = await resolveRoutingImpl();
+    const command = resolveClaudeBinary() ?? 'claude';
+    const args = 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 = {
+        ...routedEnv,
+        COMPBOX_NONINTERACTIVE: '1',
+        PATH: claudeChildEnvPath(routedEnv.PATH),
+    };
+    // 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.
+    try {
+        await ctx.mailboxClient.postTurn(ctx.machineToken, ctx.jobId, `Started the planner for Epic Request ${ctx.epicRequestId} (headless). This runs the full 5-stage planning pipeline and may take several minutes.`);
+    }
+    catch {
+        // Best-effort start turn.
+    }
+    const outcome = await new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const child = spawnImpl(command, args, {
+            cwd: ctx.projectDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: childEnv,
+        });
+        // H4: independent keep-alive so the machine stays online during the long run.
+        const heartbeatTimer = deps.heartbeat
+            ? setInterval(() => {
+                void Promise.resolve(deps.heartbeat?.()).catch(() => {
+                    // Best-effort — a missed keep-alive is recovered by the next tick.
+                });
+            }, heartbeatIntervalMs)
+            : undefined;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (heartbeatTimer)
+                clearInterval(heartbeatTimer);
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            finish({
+                status: 'failed',
+                result: {
+                    error: `The planner run timed out after ${String(Math.round(timeoutMs / 60_000))} minutes and was terminated. No epic was produced.`,
+                },
+            });
+        }, timeoutMs);
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf-8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf-8');
+        });
+        child.on('error', (error) => {
+            finish({
+                status: 'failed',
+                result: {
+                    error: error.code === 'ENOENT'
+                        ? claudeNotFoundMessage()
+                        : error.message || 'Failed to spawn the planner.',
+                },
+            });
+        });
+        child.on('close', (code) => {
+            void (async () => {
+                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).
+                const review = detectNeedsHumanReview(combined);
+                if (review.needsReview) {
+                    finish({
+                        status: 'failed',
+                        result: {
+                            needsHumanReview: true,
+                            stage: 'EVALUATE',
+                            message: 'The planner produced a plan that needs human review before execution (EVALUATE did not reach a clean pass).',
+                            ...(review.marker ? { marker: review.marker } : {}),
+                        },
+                    });
+                    return;
+                }
+                if (code !== 0) {
+                    finish({
+                        status: 'failed',
+                        result: {
+                            error: stderr.trim() ||
+                                stdout.trim().slice(-PLANNER_FINAL_TURN_MAX_CHARS) ||
+                                `The planner exited with code ${String(code ?? 'null')}.`,
+                        },
+                    });
+                    return;
+                }
+                // Clean run: the produced epic is the ER's convertedEpicId (planner
+                // Stage 5 finalizes ER→Epic conversion). This is the source of truth,
+                // independent of stdout formatting.
+                const epicId = await fetchConvertedEpicId(ctx.apiBaseUrl, ctx.userApiToken, ctx.epicRequestId, fetchImpl);
+                if (!epicId) {
+                    finish({
+                        status: 'failed',
+                        result: {
+                            error: 'The planner finished but no epic was produced (the Epic Request was not converted to an epic). It may need human review.',
+                        },
+                    });
+                    return;
+                }
+                finish({ status: 'done', result: { epicId } });
+            })();
+        });
+    });
+    // H4: relay a FINAL turn summarizing the outcome (best-effort).
+    try {
+        const epicId = typeof outcome.result.epicId === 'string' ? outcome.result.epicId : '';
+        const summary = outcome.status === 'done'
+            ? `Planning complete — created epic ${epicId}.`
+            : `Planner run ended: ${JSON.stringify(outcome.result).slice(0, PLANNER_FINAL_TURN_MAX_CHARS)}`;
+        await ctx.mailboxClient.postTurn(ctx.machineToken, ctx.jobId, summary);
+    }
+    catch {
+        // Best-effort final turn.
+    }
+    return outcome;
+}
+// ---------------------------------------------------------------------
+// start_execution / kind:'orchestrate' (ENG-165) — run the local
+// @orchestrator headless against an EXISTING epic, in the PROJECT REPO so the
+// repo's `.mcp.json` (CompBox MCP) + `CLAUDE.md` (@agent routing) load. Reuses
+// ENG-164's MCP + repo-aware spawn profile verbatim (H1: bypassPermissions, NO
+// `--tools ""`/`--safe-mode`; COMPBOX_NONINTERACTIVE=1; independent keep-alive
+// heartbeat during the long run, H4; pxpipe ANTHROPIC_BASE_URL preserved).
+//
+// Two things differ from the planner path:
+//   1. Preconditions (ENG-165-2): the orchestrator drives a full build/test
+//      loop through git worktrees, so before spawning we verify the machine can
+//      actually do that — a git repo, working `git worktree` support, and a JS
+//      test toolchain (a package manager on PATH). A missing precondition fails
+//      the job with actionable copy INSTEAD of spawning into an environment
+//      where the run would stall or produce garbage.
+//   2. Halt-and-report (ENG-165-3): the orchestrator's non-interactive HARD
+//      gates (compliance critical-fail / architect BLOCKED / security FINDINGS /
+//      QA FAIL) end the run by emitting a single `COMPBOX_NEEDS_HUMAN_REVIEW
+//      {json}` marker line (see .github/agents/claude/orchestrator.md). We parse
+//      it and complete the job as a needs-review failure NAMING the gate, so the
+//      web surfaces exactly which safety gate stopped the run. The epic is
+//      already marked blocked agent-side, so no extra bookkeeping is needed here.
+//
+// H3 note: passing `--non-interactive` (backed by COMPBOX_NONINTERACTIVE=1) is
+// the ONLY signal the daemon owes the agent for H3 — the serial-in-process
+// execution fallback (no background-worktree Agent() calls) is defined
+// agent-side in ENG-162's orchestrator.md and engages off that same signal.
+// ---------------------------------------------------------------------
+/**
+ * Per-run wall-clock budget for the headless orchestrator child (H4). Executing
+ * a full epic (every phase, every feature-worker, reviewer + QA + security
+ * passes, worktree merges) runs FAR longer than a planning pass, so this is set
+ * well above {@link PLANNER_RUN_TIMEOUT_MS} (30 min). Three hours bounds a hung
+ * run without cutting a legitimate multi-feature epic short.
+ */
+export const ORCHESTRATOR_RUN_TIMEOUT_MS = 3 * 60 * 60 * 1_000;
+/** Keep-alive cadence while the orchestrator child runs (H4) — same as the planner path. */
+export const ORCHESTRATOR_HEARTBEAT_INTERVAL_MS = PLANNER_HEARTBEAT_INTERVAL_MS;
+/** Max chars of orchestrator output relayed in the final mailbox turn (bound turn size). */
+const ORCHESTRATOR_FINAL_TURN_MAX_CHARS = 4_000;
+/**
+ * Build the `claude` argv for a headless orchestrator run (H1). Pure + exported
+ * so a unit test can assert the exact command shape: the `@orchestrator execute
+ * epic <id> --non-interactive` routing prompt, an unattended permission mode,
+ * and the ABSENCE of `--tools ""`/`--safe-mode` (which would strip the MCP tools
+ * + @agent routing the orchestrator depends on). No `--system-prompt` (the
+ * persona comes from CLAUDE.md routing) and no `--model` override (execution is
+ * reasoning-heavy; the account default applies — pxpipe rides on
+ * ANTHROPIC_BASE_URL, not the model name). `--non-interactive` is what engages
+ * the agent-side serial-in-process fallback (H3).
+ */
+export function buildOrchestratorArgs(epicId) {
+    return [
+        '-p',
+        `@orchestrator execute epic ${epicId} --non-interactive`,
+        // H1: unattended permission mode so print-mode tool use never blocks on an
+        // interactive "allow?" prompt (this path grants the full MCP surface).
+        '--permission-mode',
+        'bypassPermissions',
+    ];
+}
+/** Actionable failure when the configured project path is not a git repository. */
+export function orchestrateNotGitRepoMessage(dir) {
+    return [
+        `The configured CompBox project directory is not a git repository: ${dir}`,
+        'The orchestrator runs the local `claude` CLI in this directory so the repo\'s .mcp.json (CompBox MCP)',
+        'and CLAUDE.md (@agent routing) load, and it drives builds/tests through git worktrees — all require a real checkout.',
+        'Point --project-dir / COMPBOX_PROJECT_DIR at a git checkout of the CompBox repo and re-run the job.',
+    ].join('\n');
+}
+/** Actionable failure when `git worktree` is unavailable in the project dir. */
+export function worktreeUnavailableMessage(dir) {
+    return [
+        `git worktrees are not usable in the configured CompBox project directory: ${dir}`,
+        'The orchestrator isolates each feature-worker on its own git worktree, so `git worktree list` must succeed there.',
+        'Ensure a recent `git` is installed and the directory is a healthy checkout (try `git -C <dir> worktree list` yourself), then re-run the job.',
+    ].join('\n');
+}
+/** Actionable failure when no JS test toolchain (package manager) is reachable. */
+export function toolchainMissingMessage(dir) {
+    return [
+        `No JavaScript test toolchain (package manager) is reachable for the CompBox project at: ${dir}`,
+        'The orchestrator runs builds, typechecks, and the test suite to verify each phase, which needs a package manager (pnpm or npm) on PATH.',
+        'Install the repo toolchain (this project uses pnpm) so `pnpm --version` (or `npm --version`) succeeds, then re-run the job.',
+    ].join('\n');
+}
+/**
+ * Default precondition: `git worktree list` succeeds in `dir` (proves git is
+ * installed AND the directory is a worktree-capable checkout). Uses the same
+ * augmented child PATH as the spawn below so a launchd/GUI-spawned daemon (whose
+ * inherited PATH often lacks the git install dir) resolves `git` the same way
+ * the real run will. Injectable in tests — never shells out there.
+ */
+export function defaultWorktreeCapable(dir) {
+    try {
+        const res = spawnSync('git', ['-C', dir, 'worktree', 'list'], {
+            stdio: 'ignore',
+            env: { ...process.env, PATH: claudeChildEnvPath(process.env.PATH) },
+        });
+        return res.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Default precondition: a JS test toolchain is reachable. `node` is inherently
+ * present (this daemon runs on it), so the real check is that a package manager
+ * (pnpm preferred, npm fallback) resolves on the augmented PATH — the
+ * orchestrator's phase verification (install/build/typecheck/test) needs one.
+ * Injectable in tests — never shells out there.
+ */
+export function defaultToolchainPresent(_dir) {
+    for (const pm of ['pnpm', 'npm']) {
+        try {
+            const res = spawnSync(pm, ['--version'], {
+                stdio: 'ignore',
+                env: { ...process.env, PATH: claudeChildEnvPath(process.env.PATH) },
+            });
+            if (res.status === 0)
+                return true;
+        }
+        catch {
+            // Try the next package manager.
+        }
+    }
+    return false;
+}
+/** Read a string field off a parsed marker object, or undefined. */
+function markerString(marker, key) {
+    const v = marker?.[key];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/**
+ * Turn a detected needs-review marker into the job result the web renders
+ * (ENG-165-3). Names the halting gate (and its reason/phase/feature when the
+ * orchestrator supplied them) so the failure banner is specific rather than a
+ * generic "needs review". Pure — exported for unit testing.
+ */
+export function buildOrchestrateNeedsReviewResult(epicId, marker) {
+    const gate = markerString(marker, 'gate') ?? 'unknown';
+    const reason = markerString(marker, 'reason');
+    const phase = typeof marker?.phase === 'number' ? marker.phase : undefined;
+    const featureId = markerString(marker, 'featureId');
+    return {
+        needsHumanReview: true,
+        gate,
+        epicId,
+        ...(reason ? { reason } : {}),
+        ...(phase !== undefined ? { phase } : {}),
+        ...(featureId ? { featureId } : {}),
+        message: `The orchestrator halted at a hard gate (${gate}) and needs human review before execution can continue.` +
+            (reason ? ` Reason: ${reason}` : '') +
+            ' The epic has been marked blocked.',
+        ...(marker ? { marker } : {}),
+    };
+}
+/**
+ * Run the orchestrator headless for a `start_execution`/`orchestrate` job
+ * (ENG-165).
+ *
+ * Flow: validate the project repo (git repo → worktree-capable → test toolchain
+ * present) → spawn the local `claude` CLI in that repo cwd with ENG-164's MCP +
+ * CLAUDE.md-routing profile (H1: unattended permission mode, NOT
+ * `--tools ""`/`--safe-mode`) running `@orchestrator execute epic <epicId>
+ * --non-interactive` with `COMPBOX_NONINTERACTIVE=1` (H3 signal) and pxpipe's
+ * `ANTHROPIC_BASE_URL` preserved → keep the machine alive with a periodic
+ * heartbeat during the long run (H4) → relay a start + final turn to the mailbox
+ * → on a needs-review HARD-gate marker complete as a needs-review failure naming
+ * the gate (ENG-165-3); on a non-zero exit fail with the reason; on a clean run
+ * complete `{ epicId }`. Never hangs.
+ */
+export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
+    const spawnImpl = deps.spawnImpl ?? spawn;
+    const isGitRepo = deps.isGitRepo ?? isGitRepoDir;
+    const worktreeCapable = deps.worktreeCapable ?? defaultWorktreeCapable;
+    const toolchainPresent = deps.toolchainPresent ?? defaultToolchainPresent;
+    const resolveRoutingImpl = deps.resolveRoutingImpl ?? resolveRouting;
+    const heartbeatIntervalMs = deps.heartbeatIntervalMs ?? ORCHESTRATOR_HEARTBEAT_INTERVAL_MS;
+    const timeoutMs = deps.timeoutMs ?? ORCHESTRATOR_RUN_TIMEOUT_MS;
+    // Preconditions (ENG-165-2 / H2). Each fails fast with actionable copy rather
+    // than spawning into an environment where the run would stall or misbehave:
+    //   - a configured project repo (nowhere to load .mcp.json/CLAUDE.md from),
+    //   - a real git checkout,
+    //   - working `git worktree` support (the orchestrator isolates workers on them),
+    //   - a JS test toolchain (phase verification runs install/build/test).
+    if (!ctx.projectDir) {
+        return { status: 'failed', result: { error: projectDirNotConfiguredMessage() } };
+    }
+    const projectDir = ctx.projectDir;
+    if (!isGitRepo(projectDir)) {
+        return { status: 'failed', result: { error: orchestrateNotGitRepoMessage(projectDir) } };
+    }
+    if (!worktreeCapable(projectDir)) {
+        return { status: 'failed', result: { error: worktreeUnavailableMessage(projectDir) } };
+    }
+    if (!toolchainPresent(projectDir)) {
+        return { status: 'failed', result: { error: toolchainMissingMessage(projectDir) } };
+    }
+    const routing = await resolveRoutingImpl();
+    const command = resolveClaudeBinary() ?? 'claude';
+    const args = 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 = {
+        ...routedEnv,
+        COMPBOX_NONINTERACTIVE: '1',
+        PATH: claudeChildEnvPath(routedEnv.PATH),
+    };
+    // 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.`);
+    }
+    catch {
+        // Best-effort start turn.
+    }
+    const outcome = await new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const child = spawnImpl(command, args, {
+            cwd: projectDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: childEnv,
+        });
+        // H4: independent keep-alive so the machine stays online during the long run
+        // and other jobs are not blocked — the poll loop's own heartbeat is blocked
+        // for the whole duration of this job.
+        const heartbeatTimer = deps.heartbeat
+            ? setInterval(() => {
+                void Promise.resolve(deps.heartbeat?.()).catch(() => {
+                    // Best-effort — a missed keep-alive is recovered by the next tick.
+                });
+            }, heartbeatIntervalMs)
+            : undefined;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (heartbeatTimer)
+                clearInterval(heartbeatTimer);
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            finish({
+                status: 'failed',
+                result: {
+                    error: `The orchestrator run timed out after ${String(Math.round(timeoutMs / 60_000))} minutes and was terminated.`,
+                },
+            });
+        }, timeoutMs);
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf-8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf-8');
+        });
+        child.on('error', (error) => {
+            finish({
+                status: 'failed',
+                result: {
+                    error: error.code === 'ENOENT'
+                        ? claudeNotFoundMessage()
+                        : error.message || 'Failed to spawn the orchestrator.',
+                },
+            });
+        });
+        child.on('close', (code) => {
+            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
+            // exactly which gate halted the run (the epic is already blocked agent-side).
+            const review = detectNeedsHumanReview(combined);
+            if (review.needsReview) {
+                finish({
+                    status: 'failed',
+                    result: buildOrchestrateNeedsReviewResult(ctx.epicId, review.marker),
+                });
+                return;
+            }
+            if (code !== 0) {
+                finish({
+                    status: 'failed',
+                    result: {
+                        error: stderr.trim() ||
+                            stdout.trim().slice(-ORCHESTRATOR_FINAL_TURN_MAX_CHARS) ||
+                            `The orchestrator exited with code ${String(code ?? 'null')}.`,
+                    },
+                });
+                return;
+            }
+            // Clean run: the epic executed to completion (no HARD gate tripped).
+            finish({ status: 'done', result: { epicId: ctx.epicId } });
+        });
+    });
+    // H4: relay a FINAL turn summarizing the outcome (best-effort).
+    try {
+        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)}`;
+        await ctx.mailboxClient.postTurn(ctx.machineToken, ctx.jobId, summary);
+    }
+    catch {
+        // Best-effort final turn.
+    }
+    return outcome;
+}
+/**
+ * Parse the compliance summary out of an epic-request API response's `data`
+ * object. Both the create and update endpoints attach `complianceScore` (an
+ * auto-computed object). Returns null when absent/malformed.
+ */
+function parseComplianceFromData(data) {
+    if (!data || typeof data !== 'object')
+        return null;
+    const cs = data.complianceScore;
+    if (!cs || typeof cs !== 'object')
+        return null;
+    const c = cs;
+    if (typeof c.tier !== 'string' || typeof c.overall !== 'number')
+        return null;
+    const issues = Array.isArray(c.issues)
+        ? c.issues
+            .filter((i) => typeof i === 'object' && i !== null)
+            .map((i) => ({
+            message: typeof i.message === 'string'
+                ? i.message
+                : typeof i.code === 'string'
+                    ? i.code
+                    : 'issue',
+            tier: i.tier === 'critical' ? 'critical' : 'advisory',
+        }))
+        : [];
+    return {
+        overall: c.overall,
+        tier: c.tier,
+        issues,
+    };
+}
+/** Calls POST /api/v1/me/epic-requests using the user's own API token (not the machine token). */
+async function createPersonalEpicRequest(apiBaseUrl, userApiToken, draft) {
+    const res = await fetch(`${apiBaseUrl.replace(/\/+$/, '')}/api/v1/me/epic-requests`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${userApiToken}`,
+        },
+        body: JSON.stringify({
+            title: draft.title,
+            description: draft.description,
+            structuredDesc: {
+                problemStatement: draft.problemStatement,
+                proposedSolution: draft.proposedSolution,
+                impactAssessment: draft.impactAssessment,
+                // Optional fields (ENG-143): included only when the interview gathered
+                // them, so the endpoint never receives empty strings. This is how the
+                // extra interview depth actually reaches the persisted Epic Request.
+                ...(draft.successMetrics ? { successMetrics: draft.successMetrics } : {}),
+                ...(draft.targetAudience ? { targetAudience: draft.targetAudience } : {}),
+                ...(draft.alternatives ? { alternatives: draft.alternatives } : {}),
+                ...(draft.dependencies ? { dependencies: draft.dependencies } : {}),
+                ...(draft.estimatedEffort ? { estimatedEffort: draft.estimatedEffort } : {}),
+            },
+        }),
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => null));
+        throw new Error(body?.error?.message ?? `Failed to create epic request (HTTP ${String(res.status)})`);
+    }
+    const data = (await res.json());
+    return { id: data.data.id, compliance: parseComplianceFromData(data.data) };
+}
+/**
+ * ENG-149 — UPDATE an existing epic request in place via
+ * `PUT /api/v1/epic-requests/:id`, using the user's own token. Used on interview
+ * CONTINUATION so enrichment lands on the SAME request instead of creating a
+ * duplicate.
+ *
+ * 🔴 Route choice (architect-corrected): there is NO `PUT /me/epic-requests/:id`,
+ * and MCP is unreachable from the daemon — so this uses the general
+ * `PUT /api/v1/epic-requests/:id` route. `updateEpicRequest` authorizes content
+ * edits on `requestedById === userId`, and the daemon holds the OWNER's token,
+ * so a same-owner `pending` request updates cleanly (locked approved/converted
+ * requests would be rejected — but continuation is only offered while pending).
+ * Body mirrors {@link createPersonalEpicRequest} exactly so the enriched request
+ * carries the full structured description.
+ */
+async function updatePersonalEpicRequest(apiBaseUrl, userApiToken, epicRequestId, draft) {
+    // encodeURIComponent is a no-op for a valid UUID, but the id arrives via the
+    // job payload — encoding it keeps a malformed id from altering the request path.
+    const res = await fetch(`${apiBaseUrl.replace(/\/+$/, '')}/api/v1/epic-requests/${encodeURIComponent(epicRequestId)}`, {
+        method: 'PUT',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${userApiToken}`,
+        },
+        body: JSON.stringify({
+            title: draft.title,
+            description: draft.description,
+            structuredDesc: {
+                problemStatement: draft.problemStatement,
+                proposedSolution: draft.proposedSolution,
+                impactAssessment: draft.impactAssessment,
+                ...(draft.successMetrics ? { successMetrics: draft.successMetrics } : {}),
+                ...(draft.targetAudience ? { targetAudience: draft.targetAudience } : {}),
+                ...(draft.alternatives ? { alternatives: draft.alternatives } : {}),
+                ...(draft.dependencies ? { dependencies: draft.dependencies } : {}),
+                ...(draft.estimatedEffort ? { estimatedEffort: draft.estimatedEffort } : {}),
+            },
+        }),
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => null));
+        throw new Error(body?.error?.message ?? `Failed to update epic request (HTTP ${String(res.status)})`);
+    }
+    const data = (await res.json().catch(() => null));
+    return parseComplianceFromData(data?.data);
+}
+//# sourceMappingURL=agent-invoker.js.map