@descix/cli 1.0.5 → 1.0.7

package/lib/core/Syncer.js

@@ -25,6 +25,54 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { loadChunks } from './Chunker.js';
 
+/**
+ * THE ONE VALUE this CLI uses to mean "the store did not report a count".
+ *
+ * A receipt is derived from the STORE, never from the REQUEST. Where the store
+ * cannot report, we say so — we never substitute the number of things we ASKED
+ * to be changed, because that number is a description of our own request and
+ * carries no information about what happened.
+ *
+ * @type {number}
+ */
+export const UNREPORTED_COUNT = -1;
+
+/**
+ * Normalize a count the store returned into either that count or UNREPORTED_COUNT.
+ * This is the ONLY place the "did the store report a number?" decision is made.
+ *
+ * @param {*} value - the raw count field as it arrived from the store
+ * @returns {number} the store's count, or UNREPORTED_COUNT if it reported none
+ */
+export function reportedCount(value) {
+  return Number.isFinite(value) ? value : UNREPORTED_COUNT;
+}
+
+/**
+ * True when `value` is a count the store actually reported. Callers use this to
+ * choose between printing a number and printing "unknown" — never to fabricate one.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function isReportedCount(value) {
+  return Number.isFinite(value) && value >= 0;
+}
+
+/**
+ * Sum counts across batches while preserving unknown-ness: if ANY batch could not
+ * be reported, the total is not a number we can honestly state.
+ *
+ * @param {number} runningTotal - UNREPORTED_COUNT once any batch was unreportable
+ * @param {*} batchValue - the raw count field from this batch's store response
+ * @returns {number}
+ */
+export function accumulateReportedCount(runningTotal, batchValue) {
+  const next = reportedCount(batchValue);
+  if (!isReportedCount(runningTotal) || !isReportedCount(next)) return UNREPORTED_COUNT;
+  return runningTotal + next;
+}
+
 /**
  * Compute delta between local chunks and remote Pinecone records
  * Uses content_hash for efficient change detection when available.
@@ -73,39 +121,64 @@ export function computeChunkDelta(localChunks, remoteChunks) {
 }
 
 /**
- * Get existing chunk metadata from Pinecone (with content_hash for delta)
- * Falls back to IDs-only if metadata endpoint not available.
- * 
+ * Get existing chunk metadata from Pinecone (with content_hash for delta).
+ * Falls back to the IDs-only endpoint when the metadata endpoint is unavailable.
+ *
+ * An empty array means the STORE REPORTED an empty KB. It never means "we could
+ * not find out" — when neither endpoint can report, this THROWS naming both
+ * endpoints and both causes, because an unknown remote set presented as an empty
+ * one makes every caller conclude that nothing is stale.
+ *
  * @param {Object} apiClient - DeSciXApiClient instance
  * @param {string} communityId - Community ID
  * @param {string} appId - App ID
  * @param {string} kbId - Knowledge base ID
- * @returns {Promise<Array<{id: string, content_hash: string}>>} Chunk metadata
+ * @returns {Promise<Array<{id: string, content_hash: string}>|Array<string>>} Chunk
+ *          metadata, or plain chunk ids from the compatibility endpoint.
+ * @throws {Error} when neither endpoint reports the remote chunk set.
  */
 export async function getRemoteChunkMetadata(apiClient, communityId, appId, kbId) {
+  // A fallback is a COMPATIBILITY PATH, not an error handler: we fall back when
+  // the newer endpoint is absent, and we FAIL LOUD when neither can report.
+  // Returning [] here would present a transport failure as a store state
+  // ("remote is empty"), and every caller would then compute that nothing is
+  // stale and re-upsert everything — silently.
+  const failures = [];
+
   try {
-    // Try new metadata endpoint first
     const result = await apiClient.invoke('kb_get_chunk_metadata', {
       app_id: appId,
       kb_id: kbId
     });
     // apiClient.invoke returns { status, message: { chunks, count, ... } }
-    const data = result.message || result;
-    return data.chunks || [];
+    const data = result?.message || result;
+    // An empty ARRAY is the store reporting an empty KB — legal, and preserved.
+    // An ABSENT field is the store not reporting at all — not the same fact.
+    if (Array.isArray(data?.chunks)) return data.chunks;
+    failures.push("kb_get_chunk_metadata: response carried no 'chunks' array");
   } catch (error) {
-    // Fall back to IDs-only endpoint
-    try {
-      const result = await apiClient.invoke('kb_get_chunk_ids', {
-        app_id: appId,
-        kb_id: kbId
-      });
-      // apiClient.invoke returns { status, message: { chunk_ids, count, ... } }
-      const data = result.message || result;
-      return data.chunk_ids || [];
-    } catch {
-      return [];
-    }
+    failures.push(`kb_get_chunk_metadata: ${error.message}`);
   }
+
+  try {
+    const result = await apiClient.invoke('kb_get_chunk_ids', {
+      app_id: appId,
+      kb_id: kbId
+    });
+    // apiClient.invoke returns { status, message: { chunk_ids, count, ... } }
+    const data = result?.message || result;
+    if (Array.isArray(data?.chunk_ids)) return data.chunk_ids;
+    failures.push("kb_get_chunk_ids: response carried no 'chunk_ids' array");
+  } catch (error) {
+    failures.push(`kb_get_chunk_ids: ${error.message}`);
+  }
+
+  throw new Error(
+    `Cannot enumerate remote chunks for ${appId}/${kbId}: both endpoints failed to report. ` +
+    'The remote chunk set is UNKNOWN — it must NOT be treated as an empty KB, because ' +
+    'that would silently skip stale-chunk deletion and re-upsert everything. ' +
+    failures.join(' | ')
+  );
 }
 
 /**
@@ -129,7 +202,9 @@ export async function getRemoteChunkIds(apiClient, communityId, appId, kbId) {
  * @param {string} appId - App ID
  * @param {string} kbId - Knowledge base ID
  * @param {Array} chunks - Chunk records to upsert
- * @returns {Promise<{upserted: number}>}
+ * @returns {Promise<{upserted: number}>} `upserted` is the store's own count, or
+ *          UNREPORTED_COUNT if ANY batch's store response carried no count.
+ *          Test it with isReportedCount(); never print it unguarded.
  */
 export async function upsertChunks(apiClient, communityId, appId, kbId, chunks) {
   if (chunks.length === 0) {
@@ -147,7 +222,9 @@ export async function upsertChunks(apiClient, communityId, appId, kbId, chunks)
       kb_id: kbId,
       chunks: batch
     });
-    totalUpserted += result.upserted_count || batch.length;
+    // apiClient.invoke returns the whole { status, message: {...} } envelope.
+    const data = result?.message || result;
+    totalUpserted = accumulateReportedCount(totalUpserted, data?.upserted_count);
   }
 
   return { upserted: totalUpserted };
@@ -164,7 +241,9 @@ export async function upsertChunks(apiClient, communityId, appId, kbId, chunks)
  * @param {string} appId - App ID
  * @param {string} kbId - Knowledge base ID
  * @param {Array<string>} chunkIds - Chunk IDs to delete
- * @returns {Promise<{deleted: number}>}
+ * @returns {Promise<{deleted: number}>} `deleted` is the store's own count, or
+ *          UNREPORTED_COUNT if the store reported none. It is NOT chunkIds.length.
+ *          Test it with isReportedCount(); never print it unguarded.
  */
 export async function deleteStaleChunks(apiClient, communityId, appId, kbId, chunkIds) {
   if (chunkIds.length === 0) {
@@ -179,7 +258,7 @@ export async function deleteStaleChunks(apiClient, communityId, appId, kbId, chu
   });
 
   const data = result?.message || result;
-  return { deleted: data.deleted_count ?? chunkIds.length };
+  return { deleted: reportedCount(data?.deleted_count) };
 }
 
 /**
@@ -198,7 +277,10 @@ export async function deleteStaleChunks(apiClient, communityId, appId, kbId, chu
  * @param {string} appId - App ID
  * @param {string} kbId - Knowledge base ID
  * @param {Array<string>} fileIds - file_id values to delete (e.g., ['corpus:abc...', 'local:def...'])
- * @returns {Promise<{deleted: number, deleted_by_file_id: number}>}
+ * @returns {Promise<{deleted: number, deleted_by_file_id: number}>} Each field is the
+ *          store's own count, or UNREPORTED_COUNT if the store reported that field.
+ *          The two are INDEPENDENT — one may be reported and the other not. Neither
+ *          is validFileIds.length. Test with isReportedCount(); never print unguarded.
  */
 export async function deleteStaleChunksByFileId(apiClient, communityId, appId, kbId, fileIds) {
   if (!Array.isArray(fileIds) || fileIds.length === 0) {
@@ -220,8 +302,8 @@ export async function deleteStaleChunksByFileId(apiClient, communityId, appId, k
 
   const data = result?.message || result;
   return {
-    deleted: data.deleted_count ?? validFileIds.length,
-    deleted_by_file_id: data.deleted_by_file_id ?? validFileIds.length
+    deleted: reportedCount(data?.deleted_count),
+    deleted_by_file_id: reportedCount(data?.deleted_by_file_id)
   };
 }
 
@@ -253,7 +335,8 @@ export async function deleteStaleChunksByFileId(apiClient, communityId, appId, k
  * @param {string} kbId - Knowledge base ID
  * @returns {Promise<{ deleted: number, purged_scope: boolean }>}
  *          `deleted` is the actual count of vectors purged (the batched path always
- *          reports it); -1 only if a future primitive cannot report a count.
+ *          reports it), or UNREPORTED_COUNT if the store reported no count.
+ *          Test it with isReportedCount(); never print it unguarded.
  */
 export async function purgeKbScope(apiClient, communityId, appId, kbId) {
   const result = await apiClient.invoke('kb_delete_chunks', {
@@ -264,7 +347,7 @@ export async function purgeKbScope(apiClient, communityId, appId, kbId) {
   });
   const data = result?.message || result;
   return {
-    deleted: typeof data?.deleted_count === 'number' ? data.deleted_count : -1,
+    deleted: reportedCount(data?.deleted_count),
     purged_scope: data?.purged_scope === true
   };
 }
@@ -286,10 +369,21 @@ export async function listRemoteFileIds(apiClient, appId, kbId) {
     kb_id: kbId
   });
   const data = result?.message || result;
+  // Same rule as getRemoteChunkMetadata: an empty array is the store REPORTING an
+  // empty namespace; an ABSENT array is the store not reporting. This list is the
+  // drift input (stale = remote_file_ids - local), so fabricating [] here would
+  // silently mean "nothing is stale" — the failure this module exists to prevent.
+  if (!Array.isArray(data?.file_ids)) {
+    throw new Error(
+      `Cannot enumerate remote file_ids for ${appId}/${kbId}: the store reported no ` +
+      `'file_ids' array. The remote file set is UNKNOWN and must NOT be treated as ` +
+      `empty — that would silently skip the stale purge.`
+    );
+  }
   return {
-    file_ids: data.file_ids || [],
-    unique_count: data.unique_count || 0,
-    total_chunks: data.total_chunks || 0
+    file_ids: data.file_ids,
+    unique_count: reportedCount(data?.unique_count),
+    total_chunks: reportedCount(data?.total_chunks)
   };
 }
 
@@ -336,9 +430,9 @@ export async function syncKb(apiClient, config, options = {}) {
   if (onProgress) onProgress('Fetching existing chunks from Pinecone...');
   const remoteChunks = await getRemoteChunkMetadata(apiClient, communityId, appId, kbId);
   
-  const remoteCount = Array.isArray(remoteChunks) 
-    ? remoteChunks.length 
-    : 0;
+  // getRemoteChunkMetadata returns an array or throws — it never reports an
+  // unknown remote set as an empty one, so there is no non-array case to default.
+  const remoteCount = remoteChunks.length;
   
   if (verbose) {
     console.log(`  Local chunks: ${localChunks.length}`);
@@ -361,7 +455,10 @@ export async function syncKb(apiClient, config, options = {}) {
       deleted = deleteResult.deleted;
       if (verbose) console.log(`  Deleted ${deleted} stale chunks`);
     } catch (error) {
-      if (verbose) console.log(`  Delete failed: ${error.message}`);
+      // The delete ERRORED: how many were removed is unknown. Leaving `deleted` at 0
+      // would report "nothing was deleted" — a claim about the store we cannot make.
+      deleted = UNREPORTED_COUNT;
+      console.warn(`  Delete failed (deleted count unknown): ${error.message}`);
     }
   }
   
@@ -385,12 +482,11 @@ export async function syncKb(apiClient, config, options = {}) {
   let deletedByFileId = 0;
   try {
     const localFileIds = new Set(localChunks.map(c => c.file_id).filter(Boolean));
-    const remoteFileIdsResp = await apiClient.invoke('kb_list_file_ids', {
-      app_id: appId,
-      kb_id: kbId
-    });
-    const remoteData = remoteFileIdsResp?.message || remoteFileIdsResp;
-    const remoteFileIds = remoteData?.file_ids || [];
+    // Consume the module's own enumeration owner rather than re-invoking
+    // kb_list_file_ids and hand-unwrapping its payload: two derivations of one
+    // fact drift apart silently, and this copy would keep the `|| []` defect
+    // that the owner no longer has.
+    const { file_ids: remoteFileIds } = await listRemoteFileIds(apiClient, appId, kbId);
     const staleFileIds = remoteFileIds.filter(fid => !localFileIds.has(fid));
     if (staleFileIds.length > 0) {
       if (onProgress) onProgress(`Purging ${staleFileIds.length} stale file_id(s)...`);
@@ -398,14 +494,18 @@ export async function syncKb(apiClient, config, options = {}) {
       deletedByFileId = purgeResult.deleted;
     }
   } catch (purgeErr) {
-    // Non-fatal: surface via verbose log. The chunk_id-based delete above is the primary
-    // path; this is a safety net. We do NOT silently swallow — caller sees a warning.
-    if (verbose) console.log(`  File-id purge skipped: ${purgeErr.message}`);
+    // Non-fatal: the chunk_id-based delete above is the primary path and this is a
+    // safety net. We do NOT silently swallow — the caller sees a warning. That claim
+    // was previously false: the warning sat behind `if (verbose)`, so a default run
+    // saw nothing. It is unconditional now, which is what makes the sentence true.
+    console.warn(`  File-id purge skipped (stale chunks may remain): ${purgeErr.message}`);
   }
 
   return {
     synced,
-    deleted: deleted + deletedByFileId,
+    // Unknown-ness survives the sum: if either leg could not be reported, their
+    // total is not a number we can state. (-1 + 5 would silently read as 4.)
+    deleted: accumulateReportedCount(deleted, deletedByFileId),
     deleted_chunk_ids: deleted,
     deleted_by_file_id: deletedByFileId,
     unchanged
@@ -433,7 +533,8 @@ export async function getSyncStatus(apiClient, config) {
   
   // Get remote chunk metadata
   const remoteChunks = await getRemoteChunkMetadata(apiClient, communityId, appId, kbId);
-  const remoteCount = Array.isArray(remoteChunks) ? remoteChunks.length : 0;
+  // Array-or-throw, as above: no fabricated zero for an unknown remote set.
+  const remoteCount = remoteChunks.length;
   
   // Compute delta using content_hash
   const { toUpsert, toDelete, unchanged } = computeChunkDelta(localChunks, remoteChunks);

package/lib/interactive.js

@@ -0,0 +1,158 @@
+/**
+ * ONE OWNER for the question "may I prompt?".
+ *
+ * Every prompt site in this CLI consumes this module. No site derives the answer itself, and
+ * there is no flag, env var or option that restores prompting when the environment cannot
+ * support it: the guard is a property of the ENVIRONMENT, not of the invocation. A flag would
+ * be a guard the caller must remember, and forgetting it reproduces the exact hang this module
+ * exists to remove.
+ *
+ * The rule is enforced by ENCAPSULATION, not by detection: you cannot obtain a prompt handle
+ * without passing the gate, because createPromptSession() is the only way to get one and it
+ * calls requireInteractive() before it constructs anything. A comment asking authors to check
+ * is not a guard — an author who does not read it ships the hang.
+ *
+ * Reference behaviour is gcloud: it refuses non-interactively rather than hanging or silently
+ * succeeding. Both failure modes were measured in this CLI before this module existed:
+ *   - stdin an open pipe or a FIFO whose write end is held: readline waits forever. SIGKILL.
+ *   - stdin /dev/null: readline closes, the question callback NEVER fires, the event loop
+ *     drains and node exits 0 having written NOTHING. That is worse than the hang, because it
+ *     is indistinguishable from success.
+ */
+
+import readline from 'readline';
+import chalk from 'chalk';
+
+/**
+ * The single derivation of "is there a human on the other end of stdin".
+ *
+ * stdin is the decisive stream: a prompt must READ. stdout being redirected does not stop a
+ * terminal user from answering, so it is deliberately not consulted.
+ *
+ * @returns {boolean}
+ */
+export function stdinIsInteractive() {
+  return process.stdin.isTTY === true;
+}
+
+/**
+ * Thrown when a command needs to prompt and cannot. Carries the refusal text already formatted.
+ * Command actions in bin/descix.js catch Error, print `error.message` and exit 1, so throwing
+ * this produces a LOUD, NON-ZERO refusal — never a hang, never a silent exit 0.
+ */
+export class NonInteractiveError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'NonInteractiveError';
+    this.isNonInteractive = true;
+  }
+}
+
+/**
+ * Build the refusal text. Names what was being asked and how to get the job done without a
+ * prompt. It NEVER prescribes a destructive remedy: where the non-interactive form overwrites
+ * or deletes something, the caller is told so explicitly and the non-destructive option leads.
+ *
+ * @param {Object} o
+ * @param {string} o.what - the command, e.g. 'descix init'
+ * @param {string} [o.question] - the question that cannot be asked
+ * @param {string[]} [o.nonInteractiveForm] - concrete lines the caller can run instead
+ */
+function refusalText({ what, question, nonInteractiveForm, destructive }) {
+  // NO leading blank line and NO ❌ marker: command actions print `❌ ${error.message}`
+  // themselves. Emitting one here produced a doubled marker — the message OWNS the sentence,
+  // the caller OWNS the decoration.
+  const lines = [];
+  lines.push(`${what} cannot prompt during non-interactive execution.`);
+  lines.push(chalk.gray('   stdin is not a terminal, so there is no one to answer.'));
+  if (question) {
+    lines.push('');
+    lines.push(chalk.gray(`   It needed to ask: ${question}`));
+  }
+  lines.push('');
+  if (destructive) {
+    // The confirmation being refused guards an IRREVERSIBLE act. The safe reading LEADS, and we
+    // never hand back a copy-pasteable destructive command as if it were the obvious next step.
+    lines.push(chalk.yellow('   This was a confirmation for an IRREVERSIBLE operation.'));
+    lines.push(chalk.gray('   Nothing has been changed.'));
+    lines.push('');
+  }
+  if (nonInteractiveForm && nonInteractiveForm.length > 0) {
+    lines.push(chalk.white('   Non-interactive form:'));
+    for (const line of nonInteractiveForm) lines.push(`     ${line}`);
+  } else {
+    lines.push(chalk.white(`   ${what} has no non-interactive form. Run it in a terminal.`));
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * The gate. Call this before ANY prompt — readline, inquirer, or anything else.
+ * Returns silently when a human can answer; throws a loud NonInteractiveError when not.
+ *
+ * @param {Object} o - see refusalText
+ * @throws {NonInteractiveError}
+ */
+export function requireInteractive({ what, question, nonInteractiveForm, destructive } = {}) {
+  if (stdinIsInteractive()) return;
+  throw new NonInteractiveError(refusalText({ what, question, nonInteractiveForm, destructive }));
+}
+
+/**
+ * The ONLY way to obtain a prompt handle in this CLI.
+ *
+ * Gated at construction, so a site physically cannot reach readline without the check. Each
+ * ask() also re-states the question in the refusal if the session is used later, and every
+ * ask() rejects rather than hanging if stdin stops being a terminal mid-session.
+ *
+ * @param {Object} o
+ * @param {string} o.what - the command, e.g. 'descix init'
+ * @param {string[]} [o.nonInteractiveForm]
+ * @param {boolean} [o.terminal] - readline terminal option (airdrop needs true to mask input)
+ * @returns {{ask: Function, askYesNo: Function, close: Function}}
+ */
+export function createPromptSession({ what, nonInteractiveForm, terminal, destructive } = {}) {
+  requireInteractive({ what, nonInteractiveForm, destructive });
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    ...(terminal === undefined ? {} : { terminal })
+  });
+
+  /** Ask for free text, with an optional default. */
+  const ask = (question, defaultValue = '') => {
+    requireInteractive({ what, question, nonInteractiveForm, destructive });
+    const suffix = defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `;
+    return new Promise((resolve) => {
+      rl.question(suffix, (answer) => resolve(answer.trim() || defaultValue));
+    });
+  };
+
+  /** Ask a yes/no question with an explicit default. */
+  const askYesNo = (question, defaultYes = true) => {
+    requireInteractive({ what, question, nonInteractiveForm, destructive });
+    const suffix = defaultYes ? '(Y/n)' : '(y/N)';
+    return new Promise((resolve) => {
+      rl.question(`${question} ${suffix}: `, (answer) => {
+        const trimmed = answer.trim().toLowerCase();
+        if (trimmed === '') return resolve(defaultYes);
+        resolve(trimmed === 'y' || trimmed === 'yes');
+      });
+    });
+  };
+
+  /**
+   * Ask with the prompt text EXACTLY as given — no added suffix. For sites that already spell
+   * their own "[y/N] " and must keep their wording verbatim.
+   */
+  const askRaw = (question) => {
+    requireInteractive({ what, question, nonInteractiveForm, destructive });
+    return new Promise((resolve) => rl.question(question, resolve));
+  };
+
+  return { ask, askYesNo, askRaw, close: () => rl.close() };
+}
+
+export default { stdinIsInteractive, requireInteractive, createPromptSession, NonInteractiveError };

package/lib/origin.js

@@ -79,15 +79,16 @@ export const ORIGIN_SOURCE_LABELS = {
     flagEnv: '--env flag',
     envVar: 'DESCIX_API_URL environment variable',
     workspaceEnvApiUrl: '.descix/workspace.json env.apiUrl',
-    legacyApiUrl: '.descix/workspace.json apiUrl (legacy)',
     globalApiUrl: '~/.descix/config.json api_url',
 };
 
 /**
  * The resolution order, most explicit first. The ORDER is the contract; this array is the only
  * place it is written down. Labels come from ORIGIN_SOURCE_LABELS, never from a second literal.
+ * The workspace names its origin at `env.apiUrl` and nowhere else — a top-level `apiUrl` is a
+ * retired v1 key that `WorkspaceConfig.load()` refuses by name.
  */
-const PRECEDENCE = ['envVar', 'workspaceEnvApiUrl', 'legacyApiUrl', 'globalApiUrl'];
+const PRECEDENCE = ['envVar', 'workspaceEnvApiUrl', 'globalApiUrl'];
 
 /**
  * What this invocation's FLAGS named, if anything: `{ origin, sourceKey }`.
@@ -181,7 +182,6 @@ function isUsableOrigin(value) {
  * @param {object} sources
  * @param {string|null} [sources.envVar]              process.env.DESCIX_API_URL
  * @param {string|null} [sources.workspaceEnvApiUrl]  workspace.json env.apiUrl
- * @param {string|null} [sources.legacyApiUrl]        workspace.json top-level apiUrl
  * @param {string|null} [sources.globalApiUrl]        ~/.descix/config.json api_url
  * @returns {{ origin: string, source: string, isDefault: boolean }} the origin AND which source
  *          supplied it — the source is returned because "where did this come from" is the

package/lib/wallet-file.js

@@ -68,30 +68,23 @@ export class WalletFileManager {
    * @returns {Promise<boolean>} Success status
    */
   static async saveWalletFile(walletPath, walletData) {
-    try {
-      // Validate before saving
-      if (!this.validateWalletFile(walletData)) {
-        throw new Error('Invalid wallet data structure');
-      }
-
-      // WS-HEADLESS-MVP-A1 §2.5 — keep the API_KEY alias mirrored to the canonical
-      // signature so the on-disk file self-documents the alias (alias-only rename).
-      if (walletData.signature) {
-        walletData.API_KEY = walletData.signature;
-      }
-
-      // Ensure directory exists
-      const dir = path.dirname(walletPath);
-      await fs.mkdir(dir, { recursive: true });
+    // THROWS on any failure, never returns false. Every caller used to await this and ignore the
+    // boolean, so `descix login` printed "Login successful!" and a "saved to" path for a file that
+    // was never written (measured on PROD 2026-09-16). A save that did not happen must stop the
+    // caller.
+    const problems = this.walletFileProblems(walletData);
+    if (problems.length > 0) {
+      throw new Error(`refusing to write ${walletPath}: ${problems.join('; ')}`);
+    }
 
-      // Write file with restricted permissions (600)
-      await fs.writeFile(walletPath, JSON.stringify(walletData, null, 2), { mode: 0o600 });
+    // WS-HEADLESS-MVP-A1 §2.5 — keep the API_KEY alias mirrored to the canonical
+    // signature so the on-disk file self-documents the alias (alias-only rename).
+    walletData.API_KEY = walletData.signature;
 
-      return true;
-    } catch (error) {
-      console.error(`[WalletFile] Error saving wallet file: ${error.message}`);
-      return false;
-    }
+    await fs.mkdir(path.dirname(walletPath), { recursive: true });
+    // Write file with restricted permissions (600)
+    await fs.writeFile(walletPath, JSON.stringify(walletData, null, 2), { mode: 0o600 });
+    return true;
   }
 
   /**
@@ -100,25 +93,31 @@ export class WalletFileManager {
    * @returns {boolean} True if valid
    */
   static validateWalletFile(walletData) {
+    return this.walletFileProblems(walletData).length === 0;
+  }
+
+  /**
+   * Every reason `walletData` is not a usable credential, named by FIELD, never by value — the
+   * messages are printed, and a signature is a credential. Empty array = valid.
+   * tokenSymbol and communityId are optional (may be absent in multi-community mode).
+   * @param {Object} walletData
+   * @returns {string[]}
+   */
+  static walletFileProblems(walletData) {
     if (!walletData || typeof walletData !== 'object') {
-      return false;
+      return ['the credential is not an object'];
     }
-
-    // Required fields for authentication
-    // Note: tokenSymbol and communityId are optional (may be absent in multi-community mode)
-    const required = ['walletAddress', 'signature'];
-    for (const field of required) {
+    const problems = [];
+    for (const field of ['walletAddress', 'signature']) {
       if (!walletData[field] || typeof walletData[field] !== 'string') {
-        return false;
+        problems.push(`${field} is empty`);
       }
     }
-
-    // Validate wallet address format (basic check - should be hex string)
-    if (!/^0x[a-fA-F0-9]{40}$/.test(walletData.walletAddress)) {
-      return false;
+    if (typeof walletData.walletAddress === 'string' && walletData.walletAddress
+        && !/^0x[a-fA-F0-9]{40}$/.test(walletData.walletAddress)) {
+      problems.push('walletAddress is not a 0x-prefixed 40-hex-digit address');
     }
-
-    return true;
+    return problems;
   }
 
   /**
@@ -237,8 +236,8 @@ export class WalletFileManager {
    */
   static async createWalletFile(walletData, preferredPath = null) {
     const walletPath = preferredPath || this.getDefaultWalletPath();
-    const success = await this.saveWalletFile(walletPath, walletData);
-    return success ? walletPath : null;
+    await this.saveWalletFile(walletPath, walletData);
+    return walletPath;
   }
 }