@descix/cli 1.0.5 → 1.0.7

package/bin/descix.js

@@ -11,7 +11,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { DeSciXApiClient } from '../lib/api-client.js';
 import { requireAuth } from '../lib/auth-guard.js';
-import { WorkspaceConfig } from '../lib/workspace-config.js';
+import { WorkspaceConfig, unmappedAppMessage, resolveWorkspacePath, TOP_LEVEL_API_URL_REMEDY } from '../lib/workspace-config.js';
 import { CLI_VERSION } from '../lib/cli-version.js';
 import { recordInvocationOrigin } from '../lib/origin.js';
 // Chat session pointer + the ONE rule for when a dead pointer may be self-healed.
@@ -29,6 +29,8 @@ import * as buyCommands from '../lib/commands/buy.js';
 import * as creditsCommands from '../lib/commands/credits.js';
 import * as airdropCommands from '../lib/commands/airdrop.js';
 import { runInit } from '../lib/commands/init.js';
+// "May I prompt?" has ONE OWNER. No command in this file derives it.
+import { createPromptSession } from '../lib/interactive.js';
 import * as updateCommands from '../lib/commands/update.js';
 import { registerAllRetiredKbSync, refuseRetiredKbSync, CANONICAL_KB_SYNC } from '../lib/commands/retired-kb-sync.js';
 import { runStatus } from '../lib/commands/status.js';
@@ -291,7 +293,9 @@ program
       // --env=demo is supplied (because the subcommand owns its own flag space).
       const parentEnv = program.opts().env || null;
       const env = options.env || parentEnv || 'dev';
-      await runHealth({ ...options, env });
+      const result = await runHealth({ ...options, env });
+      // A health check that reports an unhealthy service and exits 0 is not a gate.
+      if (result && result.all_healthy === false) process.exitCode = 1;
     } catch (error) {
       console.error(chalk.red(`\nHealth check error: ${error.message}\n`));
       process.exit(1);
@@ -612,11 +616,12 @@ communityCommand
       console.log(chalk.white(`  Network:         Polygon (live)\n`));
 
       if (!options.yes) {
-        const readline = await import('readline');
-        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-        const answer = await new Promise(resolve => {
-          rl.question(chalk.yellow(`  Create community "${options.name}" with token ${tokenSymbol} on live Polygon? [y/N] `), resolve);
+        const rl = createPromptSession({
+          what: 'descix community create',
+          destructive: true,
+          nonInteractiveForm: ['descix community create ... --yes   # deploys a REAL token contract on live Polygon']
         });
+        const answer = await rl.askRaw(chalk.yellow(`  Create community "${options.name}" with token ${tokenSymbol} on live Polygon? [y/N] `));
         rl.close();
         if (answer.toLowerCase() !== 'y') {
           console.log(chalk.gray('\n  Aborted.\n'));
@@ -713,11 +718,15 @@ communityCommand
 
       // Confirmation prompt (unless --yes)
       if (!options.yes && hardDelete) {
-        const readline = await import('readline');
-        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-        const answer = await new Promise(resolve => {
-          rl.question(chalk.yellow(`\n  Permanently delete community "${manifest.community_name}" and all ${manifest.app_count} app(s)? This cannot be undone. [y/N] `), resolve);
+        const rl = createPromptSession({
+          what: 'descix community delete',
+          destructive: true,
+          nonInteractiveForm: [
+            'Re-run with --dry-run to see the plan without changing anything.',
+            'descix community delete ... --yes   # PERMANENTLY deletes the community and every app in it'
+          ]
         });
+        const answer = await rl.askRaw(chalk.yellow(`\n  Permanently delete community "${manifest.community_name}" and all ${manifest.app_count} app(s)? This cannot be undone. [y/N] `));
         rl.close();
         if (answer.toLowerCase() !== 'y') {
           console.log(chalk.gray('\n  Aborted.\n'));
@@ -803,12 +812,15 @@ communityCommand
       }
 
       if (!options.yes) {
-        const readline = await import('readline');
-        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-        const answer = await new Promise(resolve => rl.question(
-          chalk.yellow(`\n  Execute rename ${oldId} -> ${newId}? Re-tags ${plan.pinecone.matched} vector(s) and deletes Community/${oldId} after verifying Community/${newId}. [y/N] `),
-          resolve
-        ));
+        const rl = createPromptSession({
+          what: 'descix community rename',
+          destructive: true,
+          nonInteractiveForm: [
+            'Re-run with --dry-run to see the plan without changing anything.',
+            'descix community rename ... --yes   # re-tags vectors and DELETES the old community doc'
+          ]
+        });
+        const answer = await rl.askRaw(chalk.yellow(`\n  Execute rename ${oldId} -> ${newId}? Re-tags ${plan.pinecone.matched} vector(s) and deletes Community/${oldId} after verifying Community/${newId}. [y/N] `));
         rl.close();
         if (answer.toLowerCase() !== 'y') {
           console.log(chalk.gray('\n  Aborted.\n'));
@@ -1608,11 +1620,15 @@ appCommand
 
       // Confirmation prompt (unless --yes)
       if (!options.yes && hardDelete) {
-        const readline = await import('readline');
-        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-        const answer = await new Promise(resolve => {
-          rl.question(chalk.yellow(`\n  Permanently delete ${appId}? This cannot be undone. [y/N] `), resolve);
+        const rl = createPromptSession({
+          what: 'descix app delete',
+          destructive: true,
+          nonInteractiveForm: [
+            'Re-run with --dry-run to see the plan without changing anything.',
+            `descix app delete -a ${appId} --yes   # PERMANENTLY deletes the app (hard delete is the default; --soft only hides it)`
+          ]
         });
+        const answer = await rl.askRaw(chalk.yellow(`\n  Permanently delete ${appId}? This cannot be undone. [y/N] `));
         rl.close();
         if (answer.toLowerCase() !== 'y') {
           console.log(chalk.gray('\n  Aborted.\n'));
@@ -1742,36 +1758,49 @@ appCommand
       const newPath = options.path;
 
       const workspaceConfig = await WorkspaceConfig.load();
-      const appConfig = workspaceConfig.getAppByAppId(appId);
-      if (!appConfig) {
-        throw new Error(`App '${appId}' is not mapped. Run 'descix app init -a ${appId}' first.`);
-      }
+      const wsRoot = workspaceConfig.workspaceRoot || process.cwd();
 
-      // Hard-fail if path doesn't exist or is not a directory
+      // Read the RAW registry entry, never the RESOLVED one. getAppByAppId() resolves the stored
+      // localPath, so on a workspace already carrying a rejected value it throws here — before
+      // any write is attempted. That is what made this verb refuse exactly when it was needed,
+      // while the rejection told the user to fix it with the config verb and never by hand.
+      // This command is about to REPLACE that value; it has no business resolving it.
+      //
+      // Display value only. setLocalPath() is the SINGLE authority on whether the app is mapped
+      // and refuses if it is not — deciding that here as well would be two derivations of one
+      // fact, and they would not even agree: _buildAppIdMap (behind getAppEntry) requires BOTH
+      // appId and localPath, while the live-entry walk matches on appId alone.
+      const oldPath = workspaceConfig.getAppEntry(appId)?.localPath;
+
+      // VALIDATE AT THE WRITE, through the LOADER'S OWN resolver — not a second copy of its rules.
+      // If resolveWorkspacePath would reject this value on the next read, it is rejected now, and
+      // nothing reaches disk. Writing a value the loader will refuse is what bricks a workspace.
+      const absPath = resolveWorkspacePath(wsRoot, newPath, appId);
+
+      // Hard-fail if path doesn't exist or is not a directory — checked at the path the LOADER
+      // will resolve to, not at a CWD-relative path that only exists from where you happened to
+      // be standing when you typed it.
       let stat;
       try {
-        stat = await fs.stat(newPath);
+        stat = await fs.stat(absPath);
       } catch {
-        throw new Error(`Path does not exist: ${newPath}`);
+        throw new Error(
+          `Path does not exist: ${absPath}\n` +
+          `  (localPath '${newPath}' resolved against workspace root ${wsRoot})`
+        );
       }
       if (!stat.isDirectory()) {
-        throw new Error(`Path is not a directory: ${newPath}`);
+        throw new Error(
+          `Path is not a directory: ${absPath}\n` +
+          `  (localPath '${newPath}' resolved against workspace root ${wsRoot})`
+        );
       }
 
-      // Update the localPath in workspace.json
-      const wsRoot = workspaceConfig.workspaceRoot || process.cwd();
-      const oldPath = appConfig.localPath;
-      appConfig.localPath = newPath;
-
-      // Update env.products entry
-      const products = workspaceConfig.env?.products || [];
-      for (const product of products) {
-        if (product.appId === appId || product.app_id === appId) {
-          product.localPath = newPath;
-          break;
-        }
-      }
-      await workspaceConfig.save(wsRoot);
+      // Write through the canonical setter, which covers env.platform AND env.products[]. The
+      // loop this replaces walked env.products ONLY: on the platform app it matched nothing,
+      // wrote nothing, and still printed success — a loud failure turned into a silent lie at
+      // the one entry that matters most.
+      await workspaceConfig.setLocalPath(appId, newPath);
 
       console.log(chalk.green(`\n✓ ${appId} local path updated`));
       console.log(chalk.gray(`  ${oldPath} → ${newPath}\n`));
@@ -2507,8 +2536,7 @@ siteCommand
       
       const appConfig = workspaceConfig.getAppByAppId(ctx.appId);
       if (!appConfig) {
-        console.error(chalk.red('\n❌ App not found in workspace.json.'));
-        console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+        console.error(chalk.red(`\n❌ ${unmappedAppMessage(ctx.appId)}\n`));
         process.exit(1);
       }
 
@@ -2518,9 +2546,10 @@ siteCommand
       console.log(chalk.cyan('\n📁 Adding site scaffold...\n'));
       
       const { copyScaffold } = await import('../lib/core/Hydrator.js');
-      const stats = await copyScaffold('site', appPath, { 
-        verbose: true, 
-        force: options.force 
+      const stats = await copyScaffold('site', appPath, {
+        verbose: true,
+        force: options.force,
+        substitute: { appId: ctx.appId, communityId: ctx.communityId }
       });
       
       console.log(chalk.green(`\n✅ Site scaffold added (${stats.copied} files)\n`));
@@ -2874,8 +2903,7 @@ siteCommand
       if (!port) {
         const appConfig = workspaceConfig.getAppByAppId(appId);
         if (!appConfig) {
-          console.error(chalk.red('\n❌ App not found in workspace.json.'));
-          console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+          console.error(chalk.red(`\n❌ ${unmappedAppMessage(appId)}\n`));
           process.exit(1);
         }
         // Read site.port from the live env entry (not from the constructed copy)
@@ -3050,15 +3078,13 @@ siteCommand
       }
       
       if (!options.confirm) {
-        const readline = await import('readline');
-        const rl = readline.createInterface({
-          input: process.stdin,
-          output: process.stdout
-        });
-        
-        const answer = await new Promise(resolve => {
-          rl.question(chalk.yellow(`\n⚠️  Delete site for ${communityId}/${appId}${options.preview ? ' (preview)' : ''}? (y/N) `), resolve);
+        const rl = createPromptSession({
+          what: 'descix site delete',
+          destructive: true,
+          nonInteractiveForm: [`descix site delete -c ${communityId} -a ${appId} --confirm   # deletes the uploaded site files`]
         });
+
+        const answer = await rl.askRaw(chalk.yellow(`\n⚠️  Delete site for ${communityId}/${appId}${options.preview ? ' (preview)' : ''}? (y/N) `));
         rl.close();
         
         if (answer.toLowerCase() !== 'y') {
@@ -3116,8 +3142,7 @@ microserviceCommand
       
       const appConfig = workspaceConfig.getAppByAppId(ctx.appId);
       if (!appConfig) {
-        console.error(chalk.red('\n❌ App not found in workspace.json.'));
-        console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+        console.error(chalk.red(`\n❌ ${unmappedAppMessage(ctx.appId)}\n`));
         process.exit(1);
       }
 
@@ -3149,7 +3174,8 @@ microserviceCommand
       const { copyScaffold } = await import('../lib/core/Hydrator.js');
       const stats = await copyScaffold('microservice', appPath, {
         verbose: true,
-        force: options.force
+        force: options.force,
+        substitute: { appId: ctx.appId, communityId: ctx.communityId }
       });
 
       // Configuration Injection
@@ -3158,15 +3184,16 @@ microserviceCommand
       const manifestPath = path.join(microserviceDir, 'manifest.json');
       const overridesPath = path.join(microserviceDir, 'dev-overrides.json');
 
-      // 1. Inject Context + Port into defaults-config.json
+      // 1. Inject Port into defaults-config.json.
+      // IDENTITY IS NOT SET HERE. copyScaffold resolves {{APP_ID}}/{{COMMUNITY_ID}} during the
+      // copy, so re-deriving them here would be a second derivation of one fact. The port is a
+      // workspace-derived RUNTIME value with no scaffold token, so it stays.
       try {
         const defaultsContent = await fs.readFile(defaultsPath, 'utf-8');
         const defaults = JSON.parse(defaultsContent);
-        defaults.community_id = ctx.communityId;
-        defaults.app_id = ctx.appId;
         defaults.LOCAL_PORT = microservicePort;
         await fs.writeFile(defaultsPath, JSON.stringify(defaults, null, 2));
-        console.log(chalk.gray(`  ✓ Injected context + port into defaults-config.json`));
+        console.log(chalk.gray(`  ✓ Injected port into defaults-config.json`));
       } catch (err) {
         console.warn(chalk.yellow(`  ⚠ Could not update defaults-config.json: ${err.message}`));
       }
@@ -3188,20 +3215,19 @@ microserviceCommand
         console.warn(chalk.yellow(`  ⚠ Could not claim package.json: ${err.message}`));
       }
 
-      // 2. Inject Context + Port into manifest.json
+      // 2. Inject Port into manifest.json.
+      // IDENTITY IS NOT SET HERE. copyScaffold resolved {{APP_ID}}/{{COMMUNITY_ID}} during the
+      // copy, so setting app_id/community_id/name again would be a second derivation of one fact —
+      // the exact mirror-drift shape that let a scaffold ship `community_id: 'descix'` while this
+      // block quietly wrote the right value into a different file.
+      // No domain is injected. A service does not declare its own domain — the platform derives
+      // it ({app_id}.{SITE_DOMAIN}) at registration, and refuses a manifest that declares one.
       try {
         const manifestContent = await fs.readFile(manifestPath, 'utf-8');
         const manifest = JSON.parse(manifestContent);
-        manifest.service.app_id = ctx.appId;
-        manifest.service.community_id = ctx.communityId;
-        manifest.service.name = ctx.appId;
-        // No domain is injected. A service does not declare its own domain — the platform derives
-        // it ({app_id}.{SITE_DOMAIN}) at registration, and refuses a manifest that declares one.
-        // The literal this replaced was `${ctx.appId}.descix.net`: the PROD host, scaffolded into
-        // every service regardless of the env it would be registered against.
         manifest.service.debugPort = microservicePort;
         await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
-        console.log(chalk.gray(`  ✓ Injected context + port into manifest.json`));
+        console.log(chalk.gray(`  ✓ Injected port into manifest.json`));
       } catch (err) {
         console.warn(chalk.yellow(`  ⚠ Could not update manifest.json: ${err.message}`));
       }
@@ -4343,17 +4369,22 @@ configCommand
     }
   });
 
+// `config set-url` is RETIRED, and it is retired LOUDLY rather than deleted outright: a deleted
+// subcommand only earns commander's "unknown command", which names no replacement. It used to
+// assign a top-level `apiUrl` that save() never serialized, then print a success banner over a
+// value that landed nowhere — the file was re-stamped and the origin never moved. Hidden from
+// --help; any invocation exits non-zero naming the three surfaces that actually set the origin.
 configCommand
-  .command('set-url')
-  .description('Set API URL')
-  .argument('<url>', 'API URL (e.g., https://localhost:4000)')
-  .option('-g, --global', 'Save to global config (~/.descixrc)')
-  .action(async (url, options) => {
-    try {
-      await configCommands.setUrl(url, options);
-    } catch (error) {
-      fail(error);
-    }
+  .command('set-url', { hidden: true })
+  .description('retired — see error text')
+  .argument('[url]')
+  .allowUnknownOption()
+  .action(() => {
+    fail(new Error(
+      '"descix config set-url" is retired: it never wrote the origin it reported (a retired top-level\n' +
+      'key that nothing reads). Set the API origin where it is read, env.apiUrl, with one of:\n' +
+      `  ${TOP_LEVEL_API_URL_REMEDY}`
+    ));
   });
 
 configCommand
@@ -4826,8 +4857,12 @@ program
           const { WorkspaceConfig } = await import('../lib/workspace-config.js');
           wsConfig = await WorkspaceConfig.load(process.cwd());
         } catch (e) {
-          console.error(chalk.yellow(`⚠️  Could not read .descix/workspace.json for project scope`));
-          console.error(chalk.gray(`    Run 'descix init' first, or use --scope entitlements`));
+          // RELAY the loader's own diagnosis; do not re-derive a remedy here. This site used to
+          // print "Run 'descix init' first" for EVERY failure, including a corrupt-but-present
+          // workspace.json — prescribing an overwrite of the file it had just failed to read,
+          // and discarding the loader's message that said exactly what was wrong.
+          console.error(chalk.red(e.message));
+          console.error(chalk.gray(`    Or use --scope entitlements, which needs no workspace.`));
           process.exit(1);
         }
         const appIds = new Set();
@@ -5020,29 +5055,55 @@ program
       await authCommands.loginDevice(loginOptions);
     }
 
-    // Step 2: Workspace init — create workspace.json if missing
-    const wsConfigPath = path.join(workspaceRoot, '.descix', 'workspace.json');
-    let hasWorkspace = false;
-    try {
-      await fs.access(wsConfigPath);
-      hasWorkspace = true;
+    // Step 2: Workspace init — create workspace.json only when there is none ANYWHERE UP THE TREE.
+    //
+    // WHERE THE WORKSPACE ROOT IS has ONE OWNER: WorkspaceConfig.findWorkspaceRoot, which walks UP
+    // exactly as load() does. This step used to derive it a THIRD time with fs.access on the target
+    // path only (the wizard guard was the second). Run from a SUBDIRECTORY of an existing
+    // workspace, that check saw nothing, runInit created a NESTED workspace.json whose
+    // workspaceRoot pointed at the subdirectory, and it SHADOWED the parent for every later
+    // resolution — silently, with "Quickstart complete!" and exit 0.
+    //
+    // quickstart is an ONBOARDING flow: a user who asked to be set up and already IS set up has
+    // SUCCEEDED, so this SKIPS and REPORTS and continues. `descix mcp quickstart` refuses non-zero
+    // on the same fact because it was asked specifically to CREATE a workspace and cannot honour
+    // that. Different verbs, different contracts, ONE OWNER for the underlying fact.
+    const existingRoot = await WorkspaceConfig.findWorkspaceRoot(workspaceRoot);
+    if (existingRoot) {
       console.log(chalk.green('✓ Workspace already initialized'));
-    } catch { /* missing */ }
-
-    if (!hasWorkspace) {
+      if (path.resolve(existingRoot) !== path.resolve(workspaceRoot)) {
+        console.log(chalk.gray(`  Workspace root: ${existingRoot}`));
+        console.log(chalk.gray(`  You are in a subdirectory of it. Not creating a second workspace`));
+        console.log(chalk.gray(`  here — a nested one would shadow the root for every command run`));
+        console.log(chalk.gray(`  from this directory.`));
+      }
+    } else {
       console.log(chalk.cyan('\n📋 Initialize Workspace\n'));
-      await runInit({ path: workspaceRoot });
+      // runInit's signature is (apiClient, options). Passing a single object put it in the
+      // apiClient slot and left options defaulting to {}, so `path` was silently discarded and
+      // runInit fell back to process.cwd(). It was MASKED here only because workspaceRoot IS
+      // process.cwd() in this action — the argument was in the wrong slot regardless, and would
+      // have written the workspace to the wrong directory the moment that stopped being true.
+      // This action has no apiClient of its own; null is passed explicitly rather than implied.
+      await runInit(null, { path: workspaceRoot });
     }
 
+    // EVERY REMAINING STEP TARGETS THE RESOLVED ROOT, not the directory the command was typed in.
+    // They read the workspace to learn the app, community and origin they must state, so pointing
+    // them at a subdirectory that deliberately has no workspace.json makes them hard-fail on the
+    // absence this command just chose to preserve. Resolving the root once and ferrying it is the
+    // same one-owner rule that fixed the check above.
+    const targetRoot = existingRoot || workspaceRoot;
+
     // Step 3: Generate agent instruction files
     console.log(chalk.cyan('\n📋 Generating Agent Instructions\n'));
-    const written = await generateAgentFiles(workspaceRoot);
+    const written = await generateAgentFiles(targetRoot);
     for (const f of written) {
       console.log(chalk.green(`  ✓ ${f}`));
     }
 
     // Step 4: Generate .vscode/mcp.json (skipped if DeSciX extension handles MCP)
-    const mcpWritten = await generateMcpConfig(workspaceRoot);
+    const mcpWritten = await generateMcpConfig(targetRoot);
     if (mcpWritten) {
       console.log(chalk.green('  ✓ .vscode/mcp.json'));
     } else {
@@ -5052,7 +5113,7 @@ program
     // Step 5: Copy SDK assets
     try {
       const { pullSdkAssets } = await import('../lib/wizard/setup.js');
-      const pulled = await pullSdkAssets(workspaceRoot);
+      const pulled = await pullSdkAssets(targetRoot);
       if (pulled) console.log(chalk.green('  ✓ .descix/sdk-assets/'));
     } catch { /* setup.js pullSdkAssets may not be exported — skip */ }
 

package/lib/api-client.js

@@ -13,6 +13,35 @@ import { resolveOrigin } from './origin.js';
 import { reportEnvironment, EXPLICIT_ORIGIN_SOURCE } from './environment-report.js';
 import { diag } from './diagnostic-log.js';
 
+/**
+ * THE effective API origin for this invocation, with the source that chose it: the environment
+ * variable (which the --api-url / --env flags fold into), then the workspace's env.apiUrl, then
+ * ~/.descix/config.json, then the declared default. Every surface that SHOWS or USES the origin
+ * consumes this — `config show` used to print the workspace file's value while every command
+ * used the environment variable's, so an inherited DESCIX_API_URL silently pointed commands at
+ * production while `config show` said dev (JARVIS-FRAQTL, 2026-09-16).
+ *
+ * Never returns null and never throws for an ABSENT configuration (nothing configured is the
+ * declared default, carrying `source: default`, which the caller prints). Throws
+ * OriginInvalidError when a source named an origin that cannot be used.
+ *
+ * @param {string|null|undefined} workspaceEnvApiUrl - the loaded workspace's env.apiUrl
+ * @returns {Promise<{origin: string, source: string, isDefault: boolean}>}
+ */
+export async function resolveEffectiveOrigin(workspaceEnvApiUrl) {
+  let globalApiUrl = null;
+  try {
+    const { GlobalConfig } = await import('./global-config.js');
+    const gc = await GlobalConfig.load();
+    globalApiUrl = gc.api_url || null;
+  } catch {}
+  return resolveOrigin({
+    envVar: process.env.DESCIX_API_URL,
+    workspaceEnvApiUrl,
+    globalApiUrl,
+  });
+}
+
 export class DeSciXApiClient {
   constructor(options = {}) {
     this.baseUrl = options.baseUrl || null; // Will be loaded async
@@ -93,28 +122,7 @@ export class DeSciXApiClient {
    * @returns {Promise<{origin: string, source: string, isDefault: boolean}>}
    */
   async detectApiUrl() {
-    // Every branch of this function used to be able to yield the production origin without the
-    // developer having chosen it, and the `!== PRODUCTION_URL` comparisons made it WORSE than a
-    // plain fallback: a workspace that had deliberately set prod was treated as if it had set
-    // nothing and skipped, so "chosen" and "unconfigured" were provably indistinguishable. The
-    // precedence and the fail-loud now live in the one origin owner.
-    let globalApiUrl = null;
-    try {
-      const { GlobalConfig } = await import('./global-config.js');
-      const gc = await GlobalConfig.load();
-      globalApiUrl = gc.api_url || null;
-    } catch {}
-
-    // Never returns null and never throws for an ABSENT configuration: nothing configured is
-    // the declared default (PROD), carrying `source: default`, which the caller prints. It DOES
-    // throw OriginInvalidError when a source named an origin that cannot be used — silently
-    // discarding what the developer typed is the same defect from the other direction.
-    return resolveOrigin({
-      envVar: process.env.DESCIX_API_URL,
-      workspaceEnvApiUrl: this._workspaceConfig?.env?.apiUrl,
-      legacyApiUrl: this._workspaceConfig?.apiUrl,
-      globalApiUrl,
-    });
+    return resolveEffectiveOrigin(this._workspaceConfig?.env?.apiUrl);
   }
 
   /**

package/lib/commands/airdrop.js

@@ -28,6 +28,8 @@
  */
 
 import fs from 'fs';
+// "May I prompt?" has ONE OWNER. This site holds no TTY check of its own.
+import { requireInteractive } from '../interactive.js';
 import readline from 'readline';
 import chalk from 'chalk';
 import { DeSciXApiClient } from '../api-client.js';
@@ -65,6 +67,14 @@ export function readSignerPkFromFile(path) {
  * @returns {Promise<string>} Validated PK in `0x` + 64 hex form.
  */
 export async function promptSignerPkInteractive({ stdin = process.stdin, stdout = process.stdout } = {}) {
+    // Gate FIRST: a non-TTY here previously hung forever holding a secret prompt open. This site
+    // keeps its own readline because it must disable terminal echo so the PK is never displayed;
+    // the DECISION of whether prompting is allowed is still the owner's alone.
+    requireInteractive({
+        what: 'descix airdrop',
+        question: 'signer private key',
+        nonInteractiveForm: ['descix airdrop --signer-pk-file <path>   # reads the key from a file, never echoed']
+    });
     return await new Promise((resolve, reject) => {
         const rl = readline.createInterface({ input: stdin, output: stdout, terminal: true });
         // Disable echo so the PK isn't visible while typing.

package/lib/commands/auth.js

@@ -264,7 +264,19 @@ export async function loginDevice(options = {}) {
     }
 
     const walletPath = WalletFileManager.getProjectWalletPath(workspaceRoot);
-    await WalletFileManager.saveWalletFile(walletPath, walletData);
+    try {
+      await WalletFileManager.saveWalletFile(walletPath, walletData);
+    } catch (saveErr) {
+      spinner.fail(chalk.red('Login did not complete'));
+      // The browser ceremony succeeded, but the platform returned no usable CLI credential for this
+      // account (e.g. an empty wallet signature). Say so plainly: nothing was written, and this
+      // workspace is NOT logged in on this environment.
+      throw Object.assign(new Error(
+        `The platform completed the browser sign-in but returned an unusable CLI credential (${saveErr.message}). ` +
+        `Nothing was saved and you are NOT logged in on ${apiClient.baseUrl}. ` +
+        `This is a platform defect, not something you can fix locally; report it with this message.`
+      ), { code: 'UNUSABLE_CLI_CREDENTIAL' });
+    }
 
     spinner.succeed(chalk.green('Login successful!'));
     if (walletData.oauth) {
@@ -275,6 +287,7 @@ export async function loginDevice(options = {}) {
     diag(chalk.gray(`   ${walletPath}\n`));
     
     // Sync auto-purchase apps
+    let entitlementsSynced = true;
     spinner.start('Syncing app entitlements...');
     try {
       apiClient.setCredentials({
@@ -293,17 +306,34 @@ export async function loginDevice(options = {}) {
         spinner.succeed(chalk.gray('App entitlements up to date'));
       }
     } catch (error) {
+      entitlementsSynced = false;
       spinner.warn(chalk.yellow('Could not sync app entitlements'));
       diag(chalk.gray(`   ${error.message}\n`));
     }
-    
+
+    // DO NOT CLAIM SUCCESS ON A PARTIAL LOGIN, AND DO NOT EXIT 0.
+    // Credentials are saved either way, so this is genuinely partial rather than a failed login —
+    // but entitlements are what grant app access, so "you can now use all DeSciX CLI commands" is
+    // false when the sync failed. A script branching on the exit code is the caller least able to
+    // read the yellow warning above, which is why the code is the sharper half of this fix.
+    if (!entitlementsSynced) {
+      diag(chalk.yellow(
+        'Logged in, but app entitlements did NOT sync. Credentials are saved; commands needing an ' +
+        'entitlement may fail until you re-run `descix login`.\n'
+      ));
+      process.exitCode = 1;
+      return;
+    }
+
     diag(chalk.white('You can now use all DeSciX CLI commands!\n'));
 
   } catch (error) {
     spinner.fail(chalk.red('Login failed'));
     console.error(chalk.red(error.message));
     
-    if (error.message.includes('expired')) {
+    if (error.code === 'UNUSABLE_CLI_CREDENTIAL') {
+      // The message above is the whole diagnosis; connectivity tips would misdirect.
+    } else if (error.message.includes('expired')) {
       diag(chalk.yellow('💡 Tip: Device codes expire after 15 minutes.'));
       diag(chalk.yellow('   Run the login command again to get a new code.\n'));
     } else {

package/lib/commands/briefer/index.js

@@ -218,16 +218,19 @@ export async function runBriefer(options = {}) {
   let workspaceConfig = null;
   try {
     workspaceConfig = await WorkspaceConfig.tryLoad(cwd);
-  } catch {
-    // tryLoad returns null on missing workspace; an exception here means the
-    // workspace.json file exists but is invalid. Hard-fail per philosophy —
-    // do NOT proceed with a guessed default workspace.
+  } catch (error) {
+    // tryLoad returns null on a MISSING workspace; it throws only when workspace.json EXISTS
+    // and cannot be read. Hard-fail per philosophy — do NOT proceed with a guessed default.
+    //
+    // The recovery text is the loader's own, not a second opinion invented here: it used to say
+    // "run `descix init` to regenerate", which prescribes overwriting the very file that could
+    // not be read, and which also contradicts the standing rule against hand-editing it.
     throw new BrieferExtractorError({
       code: BRIEFER_ERROR_CODES.PARSE_FAIL,
       section: 'briefer entry',
       source: '.descix/workspace.json',
       expected: 'valid v2.1 workspace JSON',
-      recovery: 'Fix the workspace.json or run `descix init` to regenerate.'
+      recovery: error.message
     });
   }