archondev 2.19.4 → 2.19.6

package/dist/{chunk-IKMCIWK3.js → chunk-OTODLPY4.js}

@@ -22,13 +22,17 @@ import {
   SUPABASE_ANON_KEY,
   SUPABASE_URL
 } from "./chunk-M4LGRTLC.js";
+import {
+  handleTierSetup,
+  updateUserTier
+} from "./chunk-GBYW3YAY.js";
 import {
   isAuthenticated,
   loadConfig
 } from "./chunk-SVU7MLG6.js";
 
 // src/cli/plan.ts
-import chalk from "chalk";
+import chalk2 from "chalk";
 import { existsSync } from "fs";
 import { readFile, writeFile, mkdir, stat } from "fs/promises";
 import { join } from "path";
@@ -767,6 +771,50 @@ var TrackedAdversarialPlanner = class {
   }
 };
 
+// src/cli/credits-recovery.ts
+import chalk from "chalk";
+import readline from "readline";
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(`${chalk.cyan("?")} ${question}: `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+async function handleInsufficientCreditsRecovery(input) {
+  console.log(chalk.red("\n\u274C Insufficient credits"));
+  console.log(chalk.dim(`Your balance: $${(input.balanceCents / 100).toFixed(2)}`));
+  console.log(chalk.dim(`Estimated ${input.operationLabel} cost: $${(input.estimatedCostCents / 100).toFixed(2)}`));
+  console.log();
+  console.log(chalk.bold("Choose next step:"));
+  console.log(`  ${chalk.cyan("1")}) Add credits now (open checkout)`);
+  console.log(`  ${chalk.cyan("2")}) Switch to BYOK and add API key now`);
+  console.log(`  ${chalk.cyan("3")}) Cancel`);
+  console.log();
+  const choice = await prompt("Enter choice (1-3)");
+  if (choice === "1") {
+    await handleTierSetup("CREDITS");
+    return "retry";
+  }
+  if (choice === "2") {
+    const switchResult = await updateUserTier("BYOK");
+    if (!switchResult.success) {
+      console.log(chalk.red(switchResult.error ?? "Failed to switch to BYOK."));
+      return "abort";
+    }
+    console.log(chalk.green("\u2713 Switched to BYOK."));
+    await handleTierSetup("BYOK");
+    return "retry";
+  }
+  console.log(chalk.dim("Operation cancelled."));
+  return "abort";
+}
+
 // src/cli/plan.ts
 var ATOMS_DIR = ".archon/atoms";
 function createPrompt() {
@@ -782,24 +830,24 @@ function createPrompt() {
   };
 }
 async function plan(description, options) {
-  const prompt = createPrompt();
+  const prompt2 = createPrompt();
   try {
     if (!await isAuthenticated()) {
-      console.log(chalk.yellow('Not authenticated. Run "archon login" first.'));
-      console.log(chalk.dim("For local development, you can continue without authentication."));
+      console.log(chalk2.yellow('Not authenticated. Run "archon login" first.'));
+      console.log(chalk2.dim("For local development, you can continue without authentication."));
     }
     const archPath = join(process.cwd(), "ARCHITECTURE.md");
     if (!existsSync(archPath)) {
-      console.error(chalk.red('ARCHITECTURE.md not found. Run "archon init" first.'));
+      console.error(chalk2.red('ARCHITECTURE.md not found. Run "archon init" first.'));
       process.exit(1);
     }
-    console.log(chalk.dim("Parsing ARCHITECTURE.md..."));
+    console.log(chalk2.dim("Parsing ARCHITECTURE.md..."));
     const parser = new ArchitectureParser(archPath);
     const parseResult = await parser.parse();
     if (!parseResult.success || !parseResult.schema) {
-      console.error(chalk.red("Failed to parse ARCHITECTURE.md:"));
+      console.error(chalk2.red("Failed to parse ARCHITECTURE.md:"));
       for (const error of parseResult.errors) {
-        console.error(chalk.red(`  - ${error.message}`));
+        console.error(chalk2.red(`  - ${error.message}`));
       }
       process.exit(1);
     }
@@ -807,24 +855,24 @@ async function plan(description, options) {
     const references = extractReferencedFiles(description);
     const { foundFiles, missingFiles, fileSummaries } = await loadReferencedFileSummaries(references);
     if (references.length > 0) {
-      console.log(chalk.dim("\nReferenced inputs detected:"));
+      console.log(chalk2.dim("\nReferenced inputs detected:"));
       for (const ref of references) {
-        const status = foundFiles.includes(ref) ? chalk.green("\u2713") : chalk.yellow("!");
+        const status = foundFiles.includes(ref) ? chalk2.green("\u2713") : chalk2.yellow("!");
         console.log(`  ${status} ${ref}`);
       }
       if (missingFiles.length > 0) {
-        console.log(chalk.yellow("\nMissing referenced files:"));
+        console.log(chalk2.yellow("\nMissing referenced files:"));
         for (const missing of missingFiles) {
-          console.log(chalk.yellow(`  - ${missing}`));
+          console.log(chalk2.yellow(`  - ${missing}`));
         }
-        console.log(chalk.dim("\nHow would you like to proceed?"));
-        console.log(chalk.dim("  1) Cancel planning and add the missing files"));
-        console.log(chalk.dim("  2) Continue and mark missing files as required"));
-        console.log(chalk.dim("  3) Continue with default placeholders"));
-        const proceedChoice = await prompt.ask("Choose 1/2/3 (default: 1): ");
+        console.log(chalk2.dim("\nHow would you like to proceed?"));
+        console.log(chalk2.dim("  1) Cancel planning and add the missing files"));
+        console.log(chalk2.dim("  2) Continue and mark missing files as required"));
+        console.log(chalk2.dim("  3) Continue with default placeholders"));
+        const proceedChoice = await prompt2.ask("Choose 1/2/3 (default: 1): ");
         const choice = proceedChoice.trim() || "1";
         if (choice === "1") {
-          console.log(chalk.dim("Planning cancelled."));
+          console.log(chalk2.dim("Planning cancelled."));
           return;
         }
         if (choice === "2") {
@@ -836,7 +884,7 @@ async function plan(description, options) {
       }
     }
     const deliverableTarget = await promptForDeliverableTarget(
-      prompt,
+      prompt2,
       requirements,
       references
     );
@@ -844,9 +892,9 @@ async function plan(description, options) {
       requirements.push(`Deliverables saved to: ${deliverableTarget}`);
     }
     if (requirements.length > 0) {
-      console.log(chalk.dim("\nDetected requirements:"));
+      console.log(chalk2.dim("\nDetected requirements:"));
       requirements.forEach((req, i) => console.log(`  ${i + 1}. ${req}`));
-      const confirm = await prompt.ask("\nUse these as acceptance criteria? (Y/n): ");
+      const confirm = await prompt2.ask("\nUse these as acceptance criteria? (Y/n): ");
       if (confirm.toLowerCase() === "n") {
         requirements.length = 0;
       }
@@ -858,7 +906,7 @@ async function plan(description, options) {
       deliverableTarget: deliverableTarget ?? void 0
     });
     const isContentOnlyTask = classification.kind === "content";
-    const designApproved = await promptForDesignApproval(prompt, {
+    const designApproved = await promptForDesignApproval(prompt2, {
       description,
       requirements,
       references,
@@ -866,10 +914,10 @@ async function plan(description, options) {
       classification
     });
     if (!designApproved) {
-      console.log(chalk.yellow("\nDesign not approved. Planning cancelled."));
+      console.log(chalk2.yellow("\nDesign not approved. Planning cancelled."));
       return;
     }
-    console.log(chalk.dim("Creating atom from description..."));
+    console.log(chalk2.dim("Creating atom from description..."));
     const atomInput = parseAtomDescription(description, options, requirements);
     const atom = createAtom(atomInput, {
       referencedFiles: references,
@@ -882,18 +930,18 @@ async function plan(description, options) {
     });
     const validation = validateAtom(atom);
     if (!validation.valid) {
-      console.error(chalk.red("Invalid atom:"));
+      console.error(chalk2.red("Invalid atom:"));
       for (const error of validation.errors) {
-        console.error(chalk.red(`  - ${error.field}: ${error.message}`));
+        console.error(chalk2.red(`  - ${error.field}: ${error.message}`));
       }
       process.exit(1);
     }
-    console.log(chalk.blue(`
+    console.log(chalk2.blue(`
 Atom created: ${atom.externalId}`));
-    console.log(chalk.dim(`Title: ${atom.title}`));
-    console.log(chalk.dim(`Acceptance Criteria: ${atom.acceptanceCriteria.length} items`));
+    console.log(chalk2.dim(`Title: ${atom.title}`));
+    console.log(chalk2.dim(`Acceptance Criteria: ${atom.acceptanceCriteria.length} items`));
     if (isContentOnlyTask) {
-      console.log(chalk.blue("\nContent task detected. Creating a lightweight plan (no adversarial loop)."));
+      console.log(chalk2.blue("\nContent task detected. Creating a lightweight plan (no adversarial loop)."));
       atom.plan = buildContentPlan({
         description,
         requirements,
@@ -903,13 +951,13 @@ Atom created: ${atom.externalId}`));
       });
       atom.status = "READY";
       await saveAtom(atom);
-      console.log(chalk.green(`
+      console.log(chalk2.green(`
 \u2705 Atom saved: ${atom.externalId}`));
-      console.log(chalk.dim(`Status: ${atom.status}`));
-      console.log(chalk.dim(`
+      console.log(chalk2.dim(`Status: ${atom.status}`));
+      console.log(chalk2.dim(`
 Next steps:`));
-      console.log(chalk.dim(`  - Execute: archon execute ${atom.externalId}`));
-      console.log(chalk.dim(`  - View: archon show ${atom.externalId}`));
+      console.log(chalk2.dim(`  - Execute: archon execute ${atom.externalId}`));
+      console.log(chalk2.dim(`  - View: archon show ${atom.externalId}`));
       return;
     }
     let apiKey = process.env["ANTHROPIC_API_KEY"];
@@ -921,16 +969,16 @@ Next steps:`));
       }
     }
     if (!apiKey) {
-      console.log(chalk.yellow("\nNo API key configured. Skipping adversarial planning."));
-      console.log(chalk.dim('Set ANTHROPIC_API_KEY or use "archon keys add anthropic"'));
+      console.log(chalk2.yellow("\nNo API key configured. Skipping adversarial planning."));
+      console.log(chalk2.dim('Set ANTHROPIC_API_KEY or use "archon keys add anthropic"'));
       await saveAtom(atom);
-      console.log(chalk.green(`
+      console.log(chalk2.green(`
 Atom saved: ${atom.externalId}`));
-      console.log(chalk.dim(`Next: Configure API key and run "archon plan ${atom.externalId} --continue"`));
+      console.log(chalk2.dim(`Next: Configure API key and run "archon plan ${atom.externalId} --continue"`));
       return;
     }
-    console.log(chalk.blue("\nStarting adversarial planning..."));
-    console.log(chalk.dim("Architect will generate a plan, Sentinel will validate it.\n"));
+    console.log(chalk2.blue("\nStarting adversarial planning..."));
+    console.log(chalk2.dim("Architect will generate a plan, Sentinel will validate it.\n"));
     const config = await loadConfig();
     let billingContext;
     if (config.userId && config.accessToken) {
@@ -945,24 +993,36 @@ Atom saved: ${atom.externalId}`));
     }
     const planner = billingContext ? new TrackedAdversarialPlanner({ apiKey, billing: billingContext }) : new AdversarialPlanner({ apiKey });
     if (billingContext && planner instanceof TrackedAdversarialPlanner) {
-      const balanceCheck = await planner.checkBalance();
+      let balanceCheck = await planner.checkBalance();
+      if (balanceCheck.tier === "CREDITS") {
+        console.log(chalk2.dim(`Estimated planning cost: $${(balanceCheck.estimatedCostCents / 100).toFixed(2)} | Balance: $${(balanceCheck.balance / 100).toFixed(2)}`));
+      }
       if (!balanceCheck.sufficient && balanceCheck.tier === "CREDITS") {
-        console.log(chalk.red("\n\u274C Insufficient credits"));
-        console.log(chalk.dim(`Your balance: $${(balanceCheck.balance / 100).toFixed(2)}`));
-        console.log(chalk.dim(`Estimated cost: $${(balanceCheck.estimatedCostCents / 100).toFixed(2)}`));
-        console.log(chalk.dim("\nAdd credits with: archon credits add"));
-        console.log(chalk.dim("Or switch to BYOK: archon keys add anthropic"));
-        process.exit(1);
+        const recovery = await handleInsufficientCreditsRecovery({
+          balanceCents: balanceCheck.balance,
+          estimatedCostCents: balanceCheck.estimatedCostCents,
+          operationLabel: "planning"
+        });
+        if (recovery === "abort") {
+          return;
+        }
+        balanceCheck = await planner.checkBalance();
+        if (!balanceCheck.sufficient && balanceCheck.tier === "CREDITS") {
+          console.log(chalk2.red("\nStill insufficient credits after recovery action."));
+          console.log(chalk2.dim("Please add more credits with: archon credits add"));
+          printPlanNextActions(atom.externalId, false);
+          return;
+        }
       }
     }
     const planResult = await planner.planAtom(atom, parseResult.schema);
     if (!planResult.approved) {
-      console.log(chalk.red("\n\u274C Plan not approved after maximum iterations."));
-      console.log(chalk.yellow("Issues found:"));
+      console.log(chalk2.red("\n\u274C Plan not approved after maximum iterations."));
+      console.log(chalk2.yellow("Issues found:"));
       for (const iteration of planResult.iterations) {
         if (!iteration.validation.passed) {
           for (const issue of iteration.validation.issues) {
-            console.log(chalk.yellow(`  - [${issue.severity}] ${issue.message}`));
+            console.log(chalk2.yellow(`  - [${issue.severity}] ${issue.message}`));
           }
         }
       }
@@ -974,7 +1034,7 @@ Atom saved: ${atom.externalId}`));
         )
       });
       if (shouldAutoFallback) {
-        console.log(chalk.blue("\nTask looks content-focused. Switching to lightweight plan."));
+        console.log(chalk2.blue("\nTask looks content-focused. Switching to lightweight plan."));
         atom.plan = buildContentPlan({
           description,
           requirements,
@@ -984,19 +1044,19 @@ Atom saved: ${atom.externalId}`));
         });
         atom.status = "READY";
         await saveAtom(atom);
-        console.log(chalk.green(`
+        console.log(chalk2.green(`
 \u2705 Atom saved: ${atom.externalId}`));
-        console.log(chalk.dim(`Status: ${atom.status}`));
-        console.log(chalk.dim(`
+        console.log(chalk2.dim(`Status: ${atom.status}`));
+        console.log(chalk2.dim(`
 Next steps:`));
-        console.log(chalk.dim(`  - Execute: archon execute ${atom.externalId}`));
-        console.log(chalk.dim(`  - View: archon show ${atom.externalId}`));
+        console.log(chalk2.dim(`  - Execute: archon execute ${atom.externalId}`));
+        console.log(chalk2.dim(`  - View: archon show ${atom.externalId}`));
         return;
       }
-      const answer2 = await prompt.ask("\nSave as draft anyway? (y/N): ");
+      const answer2 = await prompt2.ask("\nSave as draft anyway? (y/N): ");
       const normalized = answer2.toLowerCase();
       if (normalized.includes("wrong") || normalized.includes("content") || normalized.includes("not a code")) {
-        console.log(chalk.blue("\nReclassifying as content task and creating a lightweight plan."));
+        console.log(chalk2.blue("\nReclassifying as content task and creating a lightweight plan."));
         atom.plan = buildContentPlan({
           description,
           requirements,
@@ -1006,61 +1066,73 @@ Next steps:`));
         });
         atom.status = "READY";
         await saveAtom(atom);
-        console.log(chalk.green(`
+        console.log(chalk2.green(`
 \u2705 Atom saved: ${atom.externalId}`));
-        console.log(chalk.dim(`Status: ${atom.status}`));
-        console.log(chalk.dim(`
+        console.log(chalk2.dim(`Status: ${atom.status}`));
+        console.log(chalk2.dim(`
 Next steps:`));
-        console.log(chalk.dim(`  - Execute: archon execute ${atom.externalId}`));
-        console.log(chalk.dim(`  - View: archon show ${atom.externalId}`));
+        console.log(chalk2.dim(`  - Execute: archon execute ${atom.externalId}`));
+        console.log(chalk2.dim(`  - View: archon show ${atom.externalId}`));
         return;
       }
       if (normalized !== "y") {
-        console.log(chalk.dim("Atom discarded."));
+        console.log(chalk2.dim("Atom discarded."));
         return;
       }
     }
     if (planResult.finalPlan) {
       const enrichedPlan = enforcePlanStructure(planResult.finalPlan, requirements);
       planResult.finalPlan = enrichedPlan;
-      console.log(chalk.green("\n\u2705 Plan approved!"));
+      console.log(chalk2.green("\n\u2705 Plan approved!"));
       displayPlan(enrichedPlan);
     } else {
-      console.log(chalk.yellow("\nNo approved plan available."));
+      console.log(chalk2.yellow("\nNo approved plan available."));
     }
-    console.log(chalk.dim(`
+    console.log(chalk2.dim(`
 Token usage: ${planResult.totalUsage.inputTokens} input, ${planResult.totalUsage.outputTokens} output`));
     if (planner instanceof TrackedAdversarialPlanner) {
       const trackedResult = planResult;
       if (trackedResult.totalCostCents && trackedResult.totalCostCents > 0) {
-        console.log(chalk.dim(`Credits used: $${(trackedResult.totalCostCents / 100).toFixed(4)}`));
+        console.log(chalk2.dim(`Credits used: $${(trackedResult.totalCostCents / 100).toFixed(4)}`));
         if (trackedResult.remainingBalance !== void 0) {
-          console.log(chalk.dim(`Remaining balance: $${(trackedResult.remainingBalance / 100).toFixed(2)}`));
+          console.log(chalk2.dim(`Remaining balance: $${(trackedResult.remainingBalance / 100).toFixed(2)}`));
         }
       }
     }
-    const answer = await prompt.ask("\nApprove this plan? (y/N/e for edit): ");
+    const answer = await prompt2.ask("\nApprove this plan? (y/N/e for edit): ");
     if (answer.toLowerCase() === "e") {
-      console.log(chalk.yellow("Edit mode not yet implemented. Saving as draft."));
+      console.log(chalk2.yellow("Edit mode not yet implemented. Saving as draft."));
       atom.status = "DRAFT";
     } else if (answer.toLowerCase() !== "y") {
-      console.log(chalk.dim("Atom discarded."));
+      console.log(chalk2.dim("Atom discarded."));
       return;
     } else {
       atom.plan = planResult.finalPlan;
       atom.status = "READY";
     }
     await saveAtom(atom);
-    console.log(chalk.green(`
+    console.log(chalk2.green(`
 \u2705 Atom saved: ${atom.externalId}`));
-    console.log(chalk.dim(`Status: ${atom.status}`));
-    console.log(chalk.dim(`
+    console.log(chalk2.dim(`Status: ${atom.status}`));
+    console.log(chalk2.dim(`
 Next steps:`));
-    console.log(chalk.dim(`  - Execute: archon execute ${atom.externalId}`));
-    console.log(chalk.dim(`  - View: archon show ${atom.externalId}`));
+    console.log(chalk2.dim(`  - Execute: archon execute ${atom.externalId}`));
+    console.log(chalk2.dim(`  - View: archon show ${atom.externalId}`));
+    printPlanNextActions(atom.externalId, true);
   } finally {
-    prompt.close();
+    prompt2.close();
+  }
+}
+function printPlanNextActions(atomExternalId, success) {
+  console.log();
+  console.log(chalk2.bold("Next best action:"));
+  if (success) {
+    console.log(chalk2.dim(`  \u2022 Run ${chalk2.cyan(`archon execute ${atomExternalId}`)} to move this atom forward.`));
+  } else {
+    console.log(chalk2.dim(`  \u2022 Run ${chalk2.cyan("archon credits add")} or switch to ${chalk2.cyan("BYOK")} to continue planning.`));
   }
+  console.log(chalk2.dim(`  \u2022 Run ${chalk2.cyan(`archon show ${atomExternalId}`)} to inspect acceptance criteria.`));
+  console.log(chalk2.dim(`  \u2022 Run ${chalk2.cyan("archon preferences")} to tune model routing/cost.`));
 }
 function parseAtomDescription(description, options, extractedCriteria = []) {
   const title = deriveTitle(description);
@@ -1130,32 +1202,32 @@ function extractNumberedSteps(description) {
   }
   return steps;
 }
-async function promptForDesignApproval(prompt, input) {
-  console.log(chalk.blue("\nDesign Approval Gate"));
-  console.log(chalk.dim("\u2500".repeat(40)));
-  console.log(chalk.dim(`Task type: ${input.classification.kind} (${input.classification.confidence} confidence)`));
-  console.log(chalk.dim(`Title: ${deriveTitle(input.description)}`));
+async function promptForDesignApproval(prompt2, input) {
+  console.log(chalk2.blue("\nDesign Approval Gate"));
+  console.log(chalk2.dim("\u2500".repeat(40)));
+  console.log(chalk2.dim(`Task type: ${input.classification.kind} (${input.classification.confidence} confidence)`));
+  console.log(chalk2.dim(`Title: ${deriveTitle(input.description)}`));
   if (input.requirements.length > 0) {
-    console.log(chalk.dim("\nRequirements summary:"));
+    console.log(chalk2.dim("\nRequirements summary:"));
     for (const req of input.requirements.slice(0, 6)) {
-      console.log(chalk.dim(`  - ${req}`));
+      console.log(chalk2.dim(`  - ${req}`));
     }
     if (input.requirements.length > 6) {
-      console.log(chalk.dim(`  - ... and ${input.requirements.length - 6} more`));
+      console.log(chalk2.dim(`  - ... and ${input.requirements.length - 6} more`));
     }
   }
   if (input.references.length > 0) {
-    console.log(chalk.dim("\nReferenced inputs:"));
+    console.log(chalk2.dim("\nReferenced inputs:"));
     for (const ref of input.references.slice(0, 8)) {
-      console.log(chalk.dim(`  - ${ref}`));
+      console.log(chalk2.dim(`  - ${ref}`));
     }
   }
   if (input.deliverableTarget) {
-    console.log(chalk.dim(`
+    console.log(chalk2.dim(`
 Deliverable target: ${input.deliverableTarget}`));
   }
-  console.log(chalk.dim("\nI will generate a step-by-step implementation plan from this design."));
-  const approval = await prompt.ask("Approve design and proceed to planning? (Y/n): ");
+  console.log(chalk2.dim("\nI will generate a step-by-step implementation plan from this design."));
+  const approval = await prompt2.ask("Approve design and proceed to planning? (Y/n): ");
   return approval.trim().toLowerCase() !== "n";
 }
 function enforcePlanStructure(plan2, requirements) {
@@ -1337,17 +1409,17 @@ async function loadReferencedFileSummaries(references) {
   }
   return { foundFiles, missingFiles, fileSummaries };
 }
-async function promptForDeliverableTarget(prompt, requirements, references) {
+async function promptForDeliverableTarget(prompt2, requirements, references) {
   const mentionsResearch = requirements.some((req) => req.toLowerCase().includes("research"));
   const defaultTarget = references.find((ref) => ref.toLowerCase().endsWith(".md"));
   if (!mentionsResearch && !defaultTarget) {
     return null;
   }
-  console.log(chalk.dim("\nWhere should the deliverables be written?"));
+  console.log(chalk2.dim("\nWhere should the deliverables be written?"));
   if (defaultTarget) {
-    console.log(chalk.dim(`Press Enter to use ${defaultTarget}`));
+    console.log(chalk2.dim(`Press Enter to use ${defaultTarget}`));
   }
-  const answer = await prompt.ask("Target file or folder (leave blank to skip): ");
+  const answer = await prompt2.ask("Target file or folder (leave blank to skip): ");
   const trimmed = answer.trim();
   if (trimmed.length === 0) {
     return defaultTarget ?? null;
@@ -1366,29 +1438,29 @@ async function resolveProfileId(authId, accessToken) {
   }
 }
 function displayPlan(plan2) {
-  console.log(chalk.bold("\n\u{1F4DD} Implementation Plan"));
-  console.log(chalk.dim("\u2500".repeat(40)));
-  console.log(chalk.bold("\nSteps:"));
+  console.log(chalk2.bold("\n\u{1F4DD} Implementation Plan"));
+  console.log(chalk2.dim("\u2500".repeat(40)));
+  console.log(chalk2.bold("\nSteps:"));
   plan2.steps.forEach((step, i) => {
     console.log(`  ${i + 1}. ${step}`);
   });
-  console.log(chalk.bold("\nFiles to modify:"));
+  console.log(chalk2.bold("\nFiles to modify:"));
   for (const file of plan2.files_to_modify) {
     console.log(`  - ${file}`);
   }
   if (plan2.dependencies.length > 0) {
-    console.log(chalk.bold("\nDependencies:"));
+    console.log(chalk2.bold("\nDependencies:"));
     for (const dep of plan2.dependencies) {
       console.log(`  - ${dep}`);
     }
   }
   if (plan2.risks.length > 0) {
-    console.log(chalk.bold("\nRisks:"));
+    console.log(chalk2.bold("\nRisks:"));
     for (const risk of plan2.risks) {
-      console.log(chalk.yellow(`  [!] ${risk}`));
+      console.log(chalk2.yellow(`  [!] ${risk}`));
     }
   }
-  console.log(chalk.bold("\nComplexity:"), plan2.estimated_complexity);
+  console.log(chalk2.bold("\nComplexity:"), plan2.estimated_complexity);
 }
 async function saveAtom(atom) {
   const atomsDir = join(process.cwd(), ATOMS_DIR);
@@ -1427,6 +1499,7 @@ async function listLocalAtoms() {
 
 export {
   UsageRecorder,
+  handleInsufficientCreditsRecovery,
   plan,
   parseAtomDescription,
   loadAtom,

package/dist/{chunk-C4HVI2NJ.js → chunk-W6TYXCZA.js}

@@ -1,6 +1,6 @@
 import {
   listLocalAtoms
-} from "./chunk-IKMCIWK3.js";
+} from "./chunk-OTODLPY4.js";
 
 // src/cli/list.ts
 import chalk from "chalk";

package/dist/{chunk-HQBF3VTN.js → chunk-X5ZZCJBQ.js}

@@ -5,8 +5,9 @@ import {
 } from "./chunk-EBHHIUCB.js";
 import {
   UsageRecorder,
+  handleInsufficientCreditsRecovery,
   loadAtom
-} from "./chunk-IKMCIWK3.js";
+} from "./chunk-OTODLPY4.js";
 import {
   transitionAtom
 } from "./chunk-PCTP3LKJ.js";
@@ -20,6 +21,9 @@ import {
 import {
   ArchitectureParser
 } from "./chunk-5EVHUDQX.js";
+import {
+  KeyManager
+} from "./chunk-RDG5BUED.js";
 import {
   SUPABASE_ANON_KEY,
   SUPABASE_URL
@@ -4793,7 +4797,7 @@ function createPrompt() {
 }
 async function execute(atomId, options) {
   if (options.parallel && options.parallel.length > 0) {
-    const { parallelExecute } = await import("./parallel-QLKYSZZ3.js");
+    const { parallelExecute } = await import("./parallel-KRBYFJ4O.js");
     const allAtomIds = [atomId, ...options.parallel];
     await parallelExecute(allAtomIds, { skipGates: options.skipGates === true });
     return;
@@ -4808,7 +4812,12 @@ async function execute(atomId, options) {
         console.log(chalk2.red("\n\u274C Cloud execution requires Credits tier"));
         console.log(chalk2.dim("BYOK and Free tiers run locally only."));
         console.log(chalk2.dim("Upgrade with: archon upgrade"));
-        process.exit(1);
+        const upgradeNow = await prompt.ask("Switch tier now? (y/N): ");
+        if (upgradeNow.trim().toLowerCase() === "y") {
+          const { showUpgradeMenu } = await import("./tier-selection-XFBM4SZ4.js");
+          await showUpgradeMenu();
+        }
+        return;
       }
       const projectName = basename(cwd);
       console.log(chalk2.dim(`Queueing cloud execution for ${atomId}...`));
@@ -4967,16 +4976,36 @@ ${conflictReport.blockerCount} blocking conflict(s) found.`));
     }
     const roleOverrides = await loadRoleOverrides(cwd);
     const executorConfig = roleOverrides?.executor?.model ? { model: roleOverrides.executor.model } : void 0;
-    const executor = billingContext ? new TrackedExecutorAgent({ billing: billingContext, clientConfig: executorConfig }) : new ExecutorAgent(executorConfig);
+    let apiKey = process.env["ANTHROPIC_API_KEY"];
+    if (!apiKey) {
+      const keyManager = new KeyManager();
+      const storedKey = await keyManager.getKey("anthropic");
+      if (storedKey) {
+        apiKey = storedKey;
+      }
+    }
+    const executor = billingContext ? new TrackedExecutorAgent({ billing: billingContext, clientConfig: executorConfig, apiKey }) : new ExecutorAgent(executorConfig, apiKey);
     if (billingContext && executor instanceof TrackedExecutorAgent) {
-      const balanceCheck = await executor.checkBalance();
+      let balanceCheck = await executor.checkBalance();
+      if (balanceCheck.tier === "CREDITS") {
+        console.log(chalk2.dim(`Estimated execution cost: $${(balanceCheck.estimatedCostCents / 100).toFixed(2)} | Balance: $${(balanceCheck.balance / 100).toFixed(2)}`));
+      }
       if (!balanceCheck.sufficient && balanceCheck.tier === "CREDITS") {
-        console.log(chalk2.red("\n\u274C Insufficient credits"));
-        console.log(chalk2.dim(`Your balance: $${(balanceCheck.balance / 100).toFixed(2)}`));
-        console.log(chalk2.dim(`Estimated cost: $${(balanceCheck.estimatedCostCents / 100).toFixed(2)}`));
-        console.log(chalk2.dim("\nAdd credits with: archon credits add"));
-        console.log(chalk2.dim("Or switch to BYOK: archon keys add anthropic"));
-        process.exit(1);
+        const recovery = await handleInsufficientCreditsRecovery({
+          balanceCents: balanceCheck.balance,
+          estimatedCostCents: balanceCheck.estimatedCostCents,
+          operationLabel: "execution"
+        });
+        if (recovery === "abort") {
+          return;
+        }
+        balanceCheck = await executor.checkBalance();
+        if (!balanceCheck.sufficient && balanceCheck.tier === "CREDITS") {
+          console.log(chalk2.red("\nStill insufficient credits after recovery action."));
+          console.log(chalk2.dim("Please add more credits with: archon credits add"));
+          printExecuteNextActions(atom.externalId, false);
+          return;
+        }
       }
     }
     const executionResult = await executor.executeAtom(atom, atom.plan, parseResult.schema, cwd);
@@ -5104,10 +5133,22 @@ Running quality gates for ${targetEnvName}...`));
     console.log(chalk2.dim(`Atom: ${atom.externalId}`));
     console.log(chalk2.dim(`Status: ${atom.status}`));
     console.log(chalk2.dim(`Files changed: ${filesChanged.length}`));
+    printExecuteNextActions(atom.externalId, true);
   } finally {
     prompt.close();
   }
 }
+function printExecuteNextActions(atomExternalId, success) {
+  console.log();
+  console.log(chalk2.bold("Next best action:"));
+  if (success) {
+    console.log(chalk2.dim(`  \u2022 Run ${chalk2.cyan("archon list")} to select your next atom.`));
+  } else {
+    console.log(chalk2.dim(`  \u2022 Run ${chalk2.cyan(`archon show ${atomExternalId}`)} to inspect this atom.`));
+  }
+  console.log(chalk2.dim(`  \u2022 Run ${chalk2.cyan("archon credits")} to verify balance/tier.`));
+  console.log(chalk2.dim(`  \u2022 Run ${chalk2.cyan("archon preferences")} to tune model routing.`));
+}
 async function saveAtom(atom) {
   const atomsDir = join4(process.cwd(), ATOMS_DIR);
   const atomFile = join4(atomsDir, `${atom.externalId}.json`);