run402 1.53.1 → 1.54.1

package/core-dist/keystore.js

@@ -1,7 +1,34 @@
-import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { getKeystorePath } from "./config.js";
+function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
+    const lockDir = path + ".lock";
+    mkdirSync(dirname(path), { recursive: true });
+    for (let i = 0; i < retries; i++) {
+        try {
+            mkdirSync(lockDir, { mode: 0o700 });
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "EEXIST")
+                throw e;
+            const until = Date.now() + delayMs;
+            while (Date.now() < until) { /* spin */ }
+            continue;
+        }
+        try {
+            return fn();
+        }
+        finally {
+            try {
+                rmdirSync(lockDir);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    throw new Error(`Could not acquire keystore lock after ${retries} retries: ${lockDir}`);
+}
 /**
  * Load the keystore from disk.
  * Auto-migrates legacy formats:
@@ -13,7 +40,6 @@ export function loadKeyStore(path) {
     try {
         const data = readFileSync(p, "utf-8");
         const parsed = JSON.parse(data);
-        // Auto-migrate array format (CLI legacy) to object format
         if (Array.isArray(parsed)) {
             const projects = {};
             for (const item of parsed) {
@@ -29,7 +55,6 @@ export function loadKeyStore(path) {
             return { projects };
         }
         if (parsed && typeof parsed === "object" && parsed.projects) {
-            // Strip legacy fields (tier, lease_expires_at, expires_at) from projects
             for (const proj of Object.values(parsed.projects)) {
                 const rec = proj;
                 delete rec.tier;
@@ -38,6 +63,7 @@ export function loadKeyStore(path) {
             }
             return {
                 ...(parsed.active_project_id && { active_project_id: parsed.active_project_id }),
+                ...(parsed.previous_active_project_id && { previous_active_project_id: parsed.previous_active_project_id }),
                 projects: parsed.projects,
             };
         }
@@ -62,27 +88,40 @@ export function getProject(projectId, path) {
 }
 export function saveProject(projectId, project, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    store.projects[projectId] = project;
-    saveKeyStore(store, p);
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        store.projects[projectId] = project;
+        saveKeyStore(store, p);
+    });
 }
 export function updateProject(projectId, update, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    const existing = store.projects[projectId];
-    if (existing) {
-        store.projects[projectId] = { ...existing, ...update };
-        saveKeyStore(store, p);
-    }
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        const existing = store.projects[projectId];
+        if (existing) {
+            store.projects[projectId] = { ...existing, ...update };
+            saveKeyStore(store, p);
+        }
+    });
 }
 export function removeProject(projectId, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    delete store.projects[projectId];
-    if (store.active_project_id === projectId) {
-        delete store.active_project_id;
-    }
-    saveKeyStore(store, p);
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        delete store.projects[projectId];
+        if (store.active_project_id === projectId) {
+            const fallback = store.previous_active_project_id;
+            if (fallback && fallback !== projectId && store.projects[fallback]) {
+                store.active_project_id = fallback;
+            }
+            else {
+                delete store.active_project_id;
+            }
+            delete store.previous_active_project_id;
+        }
+        saveKeyStore(store, p);
+    });
 }
 export function getActiveProjectId(path) {
     const store = loadKeyStore(path);
@@ -90,8 +129,13 @@ export function getActiveProjectId(path) {
 }
 export function setActiveProjectId(projectId, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    store.active_project_id = projectId;
-    saveKeyStore(store, p);
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        if (store.active_project_id && store.active_project_id !== projectId) {
+            store.previous_active_project_id = store.active_project_id;
+        }
+        store.active_project_id = projectId;
+        saveKeyStore(store, p);
+    });
 }
 //# sourceMappingURL=keystore.js.map

package/lib/agent.mjs

@@ -1,6 +1,6 @@
 import { allowanceAuthHeaders } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 agent — Manage agent identity
 
@@ -24,7 +24,9 @@ async function contact(args) {
     if (args[i] === "--email" && args[i + 1]) email = args[++i];
     if (args[i] === "--webhook" && args[i + 1]) webhook = args[++i];
   }
-  if (!name) { console.error(JSON.stringify({ status: "error", message: "Missing --name <name>" })); process.exit(1); }
+  if (!name) {
+    fail({ code: "BAD_USAGE", message: "Missing --name <name>" });
+  }
   // Preserve the aggressive early exit when no allowance is configured.
   allowanceAuthHeaders("/agent/v1/contact");
 

package/lib/ai.mjs

@@ -1,6 +1,6 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 ai — AI translation and moderation tools
 
@@ -76,8 +76,16 @@ async function translate(args) {
   const from = parseFlag(args, "--from");
   const context = parseFlag(args, "--context");
 
-  if (!text) { console.error(JSON.stringify({ status: "error", message: "Text required. Usage: run402 ai translate <project_id> <text> --to <lang>" })); process.exit(1); }
-  if (!to) { console.error(JSON.stringify({ status: "error", message: "--to <lang> is required" })); process.exit(1); }
+  if (!text) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Text required.",
+      hint: "run402 ai translate <project_id> <text> --to <lang>",
+    });
+  }
+  if (!to) {
+    fail({ code: "BAD_USAGE", message: "--to <lang> is required" });
+  }
 
   try {
     const data = await getSdk().ai.translate(projectId, { text, to, from: from ?? undefined, context: context ?? undefined });
@@ -101,7 +109,13 @@ async function moderate(args) {
   const projectId = resolveProjectId(projectOpt || positional[0]);
   text = positional[1] || null;
 
-  if (!text) { console.error(JSON.stringify({ status: "error", message: "Text required. Usage: run402 ai moderate <project_id> <text>" })); process.exit(1); }
+  if (!text) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Text required.",
+      hint: "run402 ai moderate <project_id> <text>",
+    });
+  }
 
   try {
     const data = await getSdk().ai.moderate(projectId, text);

package/lib/allowance.mjs

@@ -1,6 +1,6 @@
 import { readAllowance, saveAllowance, ALLOWANCE_FILE, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 allowance — Manage your agent allowance
 
@@ -82,7 +82,7 @@ async function status() {
     const data = await getSdk().allowance.status();
     if (!data.configured) {
       console.log(JSON.stringify({ status: "no_wallet", message: "No agent allowance found. Run: run402 allowance create" }));
-      return;
+      process.exit(1);
     }
     // Preserve CLI's rail field (SDK doesn't surface it; read from local allowance).
     const w = readAllowance();
@@ -115,8 +115,11 @@ async function create() {
   } catch (err) {
     const msg = (err instanceof Error) ? err.message : String(err);
     if (/already exists/i.test(msg)) {
-      console.log(JSON.stringify({ status: "error", message: "Agent allowance already exists. Use 'status' to check it." }));
-      process.exit(1);
+      fail({
+        code: "ALLOWANCE_EXISTS",
+        message: "Agent allowance already exists.",
+        hint: "Use 'status' to check it.",
+      });
     }
     reportSdkError(err);
   }
@@ -124,7 +127,13 @@ async function create() {
 
 async function fund() {
   const w = readAllowance();
-  if (!w) { console.log(JSON.stringify({ status: "error", message: "No agent allowance. Run: run402 allowance create" })); process.exit(1); }
+  if (!w) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance.",
+      hint: "Run: run402 allowance create",
+    });
+  }
 
   if (w.rail === "mpp") {
     // Tempo Moderato faucet — instant, no polling needed
@@ -139,8 +148,11 @@ async function fund() {
     });
     const data = await res.json();
     if (data.error) {
-      console.log(JSON.stringify({ status: "error", message: data.error.message || "Tempo faucet failed" }));
-      process.exit(1);
+      fail({
+        code: "FAUCET_FAILED",
+        message: data.error.message || "Tempo faucet failed",
+        details: { rail: "mpp" },
+      });
     }
 
     // Re-read balance once (instant confirmation)
@@ -164,8 +176,11 @@ async function fund() {
   const res = await fetch(`${API}/faucet/v1`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ address: w.address }) });
   const data = await res.json();
   if (!res.ok) {
-    console.log(JSON.stringify({ status: "error", ...data }));
-    process.exit(1);
+    fail({
+      code: data?.code || "FAUCET_FAILED",
+      message: data?.message || "Faucet request failed",
+      details: { http: res.status, ...data },
+    });
   }
 
   const MAX_WAIT = 30;
@@ -196,7 +211,13 @@ async function readUsdcBalance(client, usdc, address) {
 
 async function balance() {
   const w = readAllowance();
-  if (!w) { console.log(JSON.stringify({ status: "error", message: "No agent allowance. Run: run402 allowance create" })); process.exit(1); }
+  if (!w) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance.",
+      hint: "Run: run402 allowance create",
+    });
+  }
 
   const { createPublicClient, http, base, baseSepolia, tempoModerato } = await loadDeps();
   const mainnetClient = createPublicClient({ chain: base, transport: http() });
@@ -229,19 +250,30 @@ async function exportAddr() {
     const address = await getSdk().allowance.export();
     console.log(address);
   } catch {
-    console.log(JSON.stringify({ status: "error", message: "No agent allowance." }));
-    process.exit(1);
+    fail({ code: "NO_ALLOWANCE", message: "No agent allowance." });
   }
 }
 
 async function checkout(args) {
   const w = readAllowance();
-  if (!w) { console.log(JSON.stringify({ status: "error", message: "No agent allowance. Run: run402 allowance create" })); process.exit(1); }
+  if (!w) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance.",
+      hint: "Run: run402 allowance create",
+    });
+  }
   let amount = null;
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--amount" && args[i + 1]) amount = parseInt(args[++i], 10);
   }
-  if (!amount) { console.error(JSON.stringify({ status: "error", message: "Missing --amount <usd_micros> (e.g. --amount 5000000 for $5)" })); process.exit(1); }
+  if (!amount) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --amount <usd_micros>",
+      hint: "e.g. --amount 5000000 for $5",
+    });
+  }
   const res = await fetch(`${API}/billing/v1/checkouts`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -254,7 +286,13 @@ async function checkout(args) {
 
 async function history(args) {
   const w = readAllowance();
-  if (!w) { console.log(JSON.stringify({ status: "error", message: "No agent allowance. Run: run402 allowance create" })); process.exit(1); }
+  if (!w) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance.",
+      hint: "Run: run402 allowance create",
+    });
+  }
   let limit = 20;
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--limit" && args[i + 1]) limit = parseInt(args[++i], 10);

package/lib/apps.mjs

@@ -1,6 +1,6 @@
 import { allowanceAuthHeaders, saveProject } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 apps — Browse and manage the app marketplace
 
@@ -177,7 +177,9 @@ async function versions(projectId) {
 }
 
 async function inspect(versionId) {
-  if (!versionId) { console.error(JSON.stringify({ status: "error", message: "Missing version ID" })); process.exit(1); }
+  if (!versionId) {
+    fail({ code: "BAD_USAGE", message: "Missing version ID" });
+  }
   try {
     const data = await getSdk().apps.getApp(versionId);
     console.log(JSON.stringify(data, null, 2));

package/lib/auth.mjs

@@ -1,6 +1,6 @@
 import { findProject, resolveProjectId, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 auth — Manage project user authentication
 
@@ -121,8 +121,12 @@ async function magicLink(args) {
   const redirect = parseFlag(args, "--redirect");
   const projectId = resolveProjectId(parseFlag(args, "--project"));
 
-  if (!email) { console.error(JSON.stringify({ status: "error", message: "Missing --email" })); process.exit(1); }
-  if (!redirect) { console.error(JSON.stringify({ status: "error", message: "Missing --redirect <url>" })); process.exit(1); }
+  if (!email) {
+    fail({ code: "BAD_USAGE", message: "Missing --email" });
+  }
+  if (!redirect) {
+    fail({ code: "BAD_USAGE", message: "Missing --redirect <url>" });
+  }
 
   try {
     await getSdk().auth.requestMagicLink(projectId, { email, redirectUrl: redirect });
@@ -136,7 +140,9 @@ async function verify(args) {
   const token = parseFlag(args, "--token");
   const projectId = resolveProjectId(parseFlag(args, "--project"));
 
-  if (!token) { console.error(JSON.stringify({ status: "error", message: "Missing --token" })); process.exit(1); }
+  if (!token) {
+    fail({ code: "BAD_USAGE", message: "Missing --token" });
+  }
 
   try {
     const data = await getSdk().auth.verifyMagicLink(projectId, token);
@@ -152,8 +158,12 @@ async function setPassword(args) {
   const currentPassword = parseFlag(args, "--current");
   const projectId = resolveProjectId(parseFlag(args, "--project"));
 
-  if (!accessToken) { console.error(JSON.stringify({ status: "error", message: "Missing --token <bearer_token>" })); process.exit(1); }
-  if (!newPassword) { console.error(JSON.stringify({ status: "error", message: "Missing --new <password>" })); process.exit(1); }
+  if (!accessToken) {
+    fail({ code: "BAD_USAGE", message: "Missing --token <bearer_token>" });
+  }
+  if (!newPassword) {
+    fail({ code: "BAD_USAGE", message: "Missing --new <password>" });
+  }
 
   try {
     await getSdk().auth.setUserPassword(projectId, {
@@ -171,7 +181,12 @@ async function settings(args) {
   const allowPasswordSet = parseFlag(args, "--allow-password-set");
   const projectId = resolveProjectId(parseFlag(args, "--project"));
 
-  if (allowPasswordSet === null) { console.error(JSON.stringify({ status: "error", message: "Missing --allow-password-set <true|false>" })); process.exit(1); }
+  if (allowPasswordSet === null) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --allow-password-set <true|false>",
+    });
+  }
 
   try {
     await getSdk().auth.settings(projectId, { allow_password_set: allowPasswordSet === "true" });

package/lib/billing.mjs

@@ -1,6 +1,6 @@
 import { API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 billing — Email billing accounts, Stripe tier checkout, email packs
 
@@ -97,8 +97,11 @@ function parseFlag(args, flag) {
 async function createEmail(args) {
   const email = args[0];
   if (!email) {
-    console.error(JSON.stringify({ status: "error", message: "Missing email. Usage: run402 billing create-email <email>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing email.",
+      hint: "run402 billing create-email <email>",
+    });
   }
   try {
     const data = await getSdk().billing.createEmailAccount(email);
@@ -112,8 +115,11 @@ async function linkWallet(args) {
   const accountId = args[0];
   const wallet = args[1];
   if (!accountId || !wallet) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 billing link-wallet <account_id> <wallet>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <account_id> and/or <wallet>.",
+      hint: "run402 billing link-wallet <account_id> <wallet>",
+    });
   }
   try {
     await getSdk().billing.linkWallet(accountId, wallet);
@@ -126,14 +132,16 @@ async function linkWallet(args) {
 async function tierCheckout(args) {
   const tier = args[0];
   if (!tier) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 billing tier-checkout <tier> [--email <e> | --wallet <w>]" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <tier>.",
+      hint: "run402 billing tier-checkout <tier> [--email <e> | --wallet <w>]",
+    });
   }
   const email = parseFlag(args, "--email");
   const wallet = parseFlag(args, "--wallet");
   if (!email && !wallet) {
-    console.error(JSON.stringify({ status: "error", message: "Must provide --email or --wallet" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Must provide --email or --wallet" });
   }
   try {
     const data = await getSdk().billing.tierCheckout(tier, { email: email ?? undefined, wallet: wallet ?? undefined });
@@ -147,8 +155,7 @@ async function buyPack(args) {
   const email = parseFlag(args, "--email");
   const wallet = parseFlag(args, "--wallet");
   if (!email && !wallet) {
-    console.error(JSON.stringify({ status: "error", message: "Must provide --email or --wallet" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Must provide --email or --wallet" });
   }
   try {
     const data = await getSdk().billing.buyEmailPack({ email: email ?? undefined, wallet: wallet ?? undefined });
@@ -162,8 +169,11 @@ async function autoRecharge(args) {
   const accountId = args[0];
   const state = args[1];
   if (!accountId || !state || !["on", "off"].includes(state)) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 billing auto-recharge <account_id> <on|off> [--threshold <n>]" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <account_id> and/or <on|off>.",
+      hint: "run402 billing auto-recharge <account_id> <on|off> [--threshold <n>]",
+    });
   }
   const thresholdStr = parseFlag(args, "--threshold");
   try {
@@ -182,8 +192,11 @@ async function balance(args) {
   // Accepts email OR wallet — SDK only models wallet, so keep direct fetch.
   const id = args[0];
   if (!id) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 billing balance <email-or-wallet>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <email-or-wallet>.",
+      hint: "run402 billing balance <email-or-wallet>",
+    });
   }
   const res = await fetch(`${API}/billing/v1/accounts/${encodeURIComponent(id)}`);
   const data = await res.json();
@@ -194,8 +207,11 @@ async function balance(args) {
 async function history(args) {
   const id = args[0];
   if (!id) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 billing history <email-or-wallet> [--limit <n>]" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <email-or-wallet>.",
+      hint: "run402 billing history <email-or-wallet> [--limit <n>]",
+    });
   }
   const limit = parseFlag(args, "--limit") || "50";
   const res = await fetch(`${API}/billing/v1/accounts/${encodeURIComponent(id)}/history?limit=${encodeURIComponent(limit)}`);

package/lib/blob.mjs

@@ -36,7 +36,7 @@ import { pipeline } from "node:stream/promises";
 
 import { resolveProject, resolveProjectId, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 blob — Direct-to-S3 blob storage
 
@@ -182,9 +182,8 @@ Examples:
 
 const UPLOAD_STATE_DIR = join(homedir(), ".run402", "uploads");
 
-function die(msg, code = 1) {
-  console.error(JSON.stringify({ status: "error", message: msg }));
-  process.exit(code);
+function die(msg, exit_code = 1) {
+  fail({ code: "BAD_USAGE", message: msg, exit_code });
 }
 
 function parseArgs(args) {

package/lib/cdn.mjs

@@ -15,7 +15,7 @@
 
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 cdn — CloudFront CDN diagnostics for public blob URLs
 
@@ -68,9 +68,8 @@ Examples:
 `,
 };
 
-function die(msg, code = 1) {
-  console.error(JSON.stringify({ status: "error", message: msg }));
-  process.exit(code);
+function die(msg, exit_code = 1) {
+  fail({ code: "BAD_USAGE", message: msg, exit_code });
 }
 
 function parseArgs(args) {

package/lib/config.mjs

@@ -7,6 +7,7 @@ import { getApiBase, getConfigDir, getKeystorePath, getAllowancePath } from "../
 import { readAllowance as coreReadAllowance, saveAllowance as coreSaveAllowance } from "../core-dist/allowance.js";
 import { loadKeyStore, getProject, saveProject, updateProject, removeProject, saveKeyStore, getActiveProjectId, setActiveProjectId } from "../core-dist/keystore.js";
 import { getAllowanceAuthHeaders as coreGetAllowanceAuthHeaders } from "../core-dist/allowance-auth.js";
+import { fail } from "./sdk-errors.mjs";
 
 export const CONFIG_DIR = getConfigDir();
 export const ALLOWANCE_FILE = getAllowancePath();
@@ -23,31 +24,54 @@ export function saveAllowance(data) {
 
 export function allowanceAuthHeaders(path) {
   const headers = coreGetAllowanceAuthHeaders(path);
-  if (!headers) { console.error(JSON.stringify({ status: "error", message: "No agent allowance found. Run: run402 allowance create" })); process.exit(1); }
+  if (!headers) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance found.",
+      hint: "Run: run402 allowance create",
+    });
+  }
   return headers;
 }
 
 export function findProject(id) {
   const p = getProject(id);
   if (!p) {
-    const hint = id && !id.startsWith("prj_")
-      ? ` Hint: project IDs start with "prj_". Check that the argument order is <project_id> <name>.`
-      : "";
-    console.error(`Project ${id} not found in local registry.${hint}`);
-    process.exit(1);
+    const idStr = id ?? "";
+    const hint = idStr && !String(idStr).startsWith("prj_")
+      ? `project IDs start with "prj_". Check that the argument order is <project_id> <name>.`
+      : undefined;
+    fail({
+      code: "PROJECT_NOT_FOUND",
+      message: `Project ${idStr} not found in local registry.`,
+      hint,
+      details: { project_id: idStr, source: "local_registry" },
+    });
   }
   return p;
 }
 
 export function resolveProject(id) {
   const projectId = id || getActiveProjectId();
-  if (!projectId) { console.error("Error: no project specified and no active project set. Run: run402 projects provision"); process.exit(1); }
+  if (!projectId) {
+    fail({
+      code: "NO_ACTIVE_PROJECT",
+      message: "no project specified and no active project set.",
+      hint: "Run: run402 projects provision",
+    });
+  }
   return findProject(projectId);
 }
 
 export function resolveProjectId(id) {
   const projectId = id || getActiveProjectId();
-  if (!projectId) { console.error("Error: no project specified and no active project set. Run: run402 projects provision"); process.exit(1); }
+  if (!projectId) {
+    fail({
+      code: "NO_ACTIVE_PROJECT",
+      message: "no project specified and no active project set.",
+      hint: "Run: run402 projects provision",
+    });
+  }
   return projectId;
 }