@mycompbox/compbox-cli 1.18.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycompbox/compbox-cli",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "CompBox CLI - Install, update, and manage Skill Packs",
   "type": "module",
   "bin": {

package/utils/agent-invoker.d.ts

@@ -32,7 +32,11 @@
  */
 import Anthropic from '@anthropic-ai/sdk';
 import { spawn } from 'node:child_process';
-import { type PxpipeRouting, type InterviewSeedPayload } from '@mycompbox/shared';
+import { type PxpipeRouting, type InterviewSeedPayload, extractCompletionJson, looksLikeCompletionAttempt, meetsComplianceTarget, buildAuditFeedback, COMPLETION_REPAIR_INSTRUCTION, type ComplianceSummary, type EpicRequestDraft } from '@mycompbox/shared';
+export { extractCompletionJson, looksLikeCompletionAttempt, meetsComplianceTarget, buildAuditFeedback, COMPLETION_REPAIR_INSTRUCTION, };
+export type { ComplianceSummary, EpicRequestDraft };
+import { type KeyRun } from './key-run.js';
+import type { FinishResult, RunWorkspaceManager } from './run-workspace.js';
 import type { MailboxAttachment, MailboxClient, MailboxJob, MailboxJobTurn } from './mailbox-client.js';
 /**
  * pxpipe routing (ENG-136). Anthropic SDK options carrying the proxy `baseURL`
@@ -94,30 +98,6 @@ export interface InvokeResult {
     status: 'done' | 'failed';
     result: Record<string, unknown>;
 }
-export interface EpicRequestDraft {
-    title: string;
-    problemStatement: string;
-    proposedSolution: string;
-    impactAssessment: string;
-    /**
-     * Plain-text markdown description synthesized by the model from the whole
-     * conversation — sent as the Epic Request's top-level `description` field
-     * (distinct from structuredDesc). REQUIRED: compliance-validation's
-     * ER_NO_DESCRIPTION rule (see .github/skills/internal/compliance-validation)
-     * fails critical if this is empty, regardless of how good structuredDesc
-     * is — verified live: an epic request created with only the 3 structured
-     * fields populated (no description) scored 12/100, critical-fail, on
-     * ER_NO_DESCRIPTION, ER_NO_PROBLEM_STATEMENT, and ER_NO_IMPACT_ASSESSMENT
-     * (the latter two because a single terse summary sentence fell just under
-     * the rubric's 50-word/30-word minimums — 47 and 25 words respectively).
-     */
-    description: string;
-    successMetrics?: string;
-    targetAudience?: string;
-    alternatives?: string;
-    dependencies?: string;
-    estimatedEffort?: string;
-}
 /**
  * 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
@@ -132,15 +112,6 @@ export declare function parseSeedPayload(payload: unknown): InterviewSeedPayload
  * prompt for a continuation, otherwise the module-level fresh-start prompt.
  */
 export declare function resolveSystemPrompt(seed: InterviewSeedPayload | null): string;
-/** The server-computed compliance summary the daemon gates the interview on. */
-export interface ComplianceSummary {
-    overall: number;
-    tier: 'pass' | 'advisory' | 'critical-fail';
-    issues: {
-        message: string;
-        tier: 'critical' | 'advisory';
-    }[];
-}
 /**
  * Submit the current draft and read back the server-computed compliance score
  * (bug #2 — audit-aware finishing). Fresh interview: the FIRST submit
@@ -156,30 +127,6 @@ export declare function submitAndScore(ctx: {
     erId: string;
     compliance: ComplianceSummary | null;
 }>;
-/**
- * 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 declare function meetsComplianceTarget(compliance: ComplianceSummary | null): boolean;
-/**
- * Turn a failing compliance score into a corrective instruction: fix by
- * EXPANDING what's already known where possible, otherwise ask ONE question.
- */
-export declare function buildAuditFeedback(compliance: ComplianceSummary): string;
-/**
- * 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 declare function extractCompletionJson(text: string): EpicRequestDraft | 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 declare function looksLikeCompletionAttempt(text: string): boolean;
 /**
  * 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
@@ -226,6 +173,19 @@ export declare const PLANNER_RUN_TIMEOUT_MS: number;
  * connected" exactly while an agent was running.
  */
 export declare const PLANNER_HEARTBEAT_INTERVAL_MS: number;
+/**
+ * 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 declare function takeKeyRunResult(ctx: {
+    mailboxClient: MailboxClient;
+    machineToken: string;
+    jobId: string;
+}, keyRun: KeyRun, stdout: string): {
+    text: string;
+    reported: Promise<void>;
+};
 /**
  * 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,
@@ -280,6 +240,8 @@ export interface StartExecutionPlanCtx {
     epicRequestId: string;
     /** Resolved project repo dir (may be undefined/invalid — validated here). */
     projectDir: string | undefined;
+    /** Run on the person's saved API key instead of this computer's Claude sign-in. */
+    keyRun?: KeyRun;
 }
 export interface StartExecutionPlanDeps {
     /** Injectable child spawner (defaults to node's `spawn`) — tests never spawn a real `claude`. */
@@ -361,6 +323,8 @@ export interface StartExecutionOrchestrateCtx {
     epicId: string;
     /** Resolved project repo dir (may be undefined/invalid — validated here). */
     projectDir: string | undefined;
+    /** Run on the person's saved API key instead of this computer's Claude sign-in. */
+    keyRun?: KeyRun;
 }
 export interface StartExecutionOrchestrateDeps {
     /** Injectable child spawner (defaults to node's `spawn`) — tests never spawn a real `claude`. */
@@ -377,7 +341,16 @@ export interface StartExecutionOrchestrateDeps {
     heartbeat?: () => void | Promise<void>;
     heartbeatIntervalMs?: number;
     timeoutMs?: number;
+    /**
+     * Runs the orchestrator on its own new branch in a separate git worktree and
+     * finishes with a pushed branch + pull request (see run-workspace.ts). The
+     * daemon always passes one; when omitted the run happens directly in the
+     * project folder, as before.
+     */
+    workspace?: Pick<RunWorkspaceManager, 'prepare' | 'finish'>;
 }
+/** Plain-language summary of where a run's code ended up. */
+export declare function describeRunBranch(finish: FinishResult): string;
 /**
  * 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

package/utils/agent-invoker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-invoker.d.ts","sourceRoot":"","sources":["../../src/utils/agent-invoker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-invoker.d.ts","sourceRoot":"","sources":["../../src/utils/agent-invoker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAa,MAAM,oBAAoB,CAAC;AAItD,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,EACrB,kBAAkB,EAClB,6BAA6B,EAC7B,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,EACrB,kBAAkB,EAClB,6BAA6B,GAC9B,CAAC;AACF,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;AAOpD,OAAO,EAAgD,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,KAAK,EAAE,YAAY,EAAgB,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,cAAc,EACf,MAAM,qBAAqB,CAAC;AAyB7B;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,GACrB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAItC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,UAAU,EACvB,OAAO,EAAE,aAAa,GACrB,MAAM,CAAC,UAAU,CAInB;AAyBD,4FAA4F;AAC5F,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAiB/C,4EAA4E;AAC5E,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,iBAAiB,EAAE,GAAG,SAAS,GAC3C,iBAAiB,EAAE,CAarB;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,iBAAiB,EAAE,GAAG,SAAS,GAAG,MAAM,CAGzF;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,iBAAiB,EAAE,EAChC,IAAI,GAAE,MAAoB,EAC1B,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,SAAS,CAAC,eAAe,EAAE,CAAC,CAgCtC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,SAAS,CAAC,eAAe,EAAE,GACvC,MAAM,GAAG,SAAS,CAAC,iBAAiB,EAAE,CAGxC;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,aAAa,CAAC,EACrD,IAAI,GAAE,MAAoB,EAC1B,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,iBAAiB,EAAE,CAAC,CAKjD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAK7E;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAWD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAuB9E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,MAAM,CAM7E;AAGD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EACjD,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAAE,CAAC,CAYjE;AAmCD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,UAAU,EACf,GAAG,EAAE;IACH,aAAa,EAAE,aAAa,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB,GACA,OAAO,CAAC,YAAY,CAAC,CAmIvB;AA4KD;;;;;GAKG;AACH,wBAAsB,gCAAgC,CACpD,GAAG,EAAE,UAAU,EACf,GAAG,EAAE;IACH,aAAa,EAAE,aAAa,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,GACA,OAAO,CAAC,YAAY,CAAC,CA2HvB;AAcD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,QAAkB,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B,QAAa,CAAC;AAQxD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE;IAAE,aAAa,EAAE,aAAa,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAC1E,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAO3C;AAYD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,CAUhE;AAED,gGAAgG;AAChG,wBAAgB,8BAA8B,IAAI,MAAM,CASvD;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAUhE;AAED,2EAA2E;AAC3E,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAwCD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAcxE;AAuBD,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,aAAa,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,iGAAiG;IACjG,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACrC,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAClD,0GAA0G;IAC1G,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,qBAAqB,EAC1B,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,YAAY,CAAC,CA8KvB;AA+BD;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,QAAsB,CAAC;AAE/D,4FAA4F;AAC5F,eAAO,MAAM,kCAAkC,QAAgC,CAAC;AAKhF;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAS9D;AAED,mFAAmF;AACnF,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOhE;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,mFAAmF;AACnF,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAU3D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAa7D;AAED,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,aAAa,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,6BAA6B;IAC5C,iGAAiG;IACjG,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACrC,sFAAsF;IACtF,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAClD,+GAA+G;IAC/G,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,QAAQ,CAAC,CAAC;CAC7D;AAED,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAM9D;AAQD;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,+BAA+B,CACnD,GAAG,EAAE,4BAA4B,EACjC,IAAI,GAAE,6BAAkC,GACvC,OAAO,CAAC,YAAY,CAAC,CAiNvB"}

package/utils/agent-invoker.js

@@ -35,9 +35,13 @@ 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, buildInterviewSystemPrompt, INTERVIEW_DEFINITION, extractCompletionJson, looksLikeCompletionAttempt, meetsComplianceTarget, buildAuditFeedback, COMPLETION_REPAIR_INSTRUCTION, } 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
@@ -55,7 +59,6 @@ const MAX_INTERVIEW_TURNS = 18;
 // 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. */
@@ -287,182 +290,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) {
@@ -922,6 +749,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 +945,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 +1018,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 +1205,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 +1288,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 +1330,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 +1379,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 +1409,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 {