@descix/cli 1.0.1 → 1.0.4

package/lib/api-client.js

@@ -1,30 +1,37 @@
 /**
  * DeSciX HTTP-Only API Client
- * 
+ *
  * Self-contained HTTP client for CLI/MCP.
  * No service imports - all communication via HTTP.
- * Uses PathContext for workspace/config resolution.
+ * Uses WorkspaceConfig for workspace/config resolution.
  */
 
 import path from 'path';
 import axios from 'axios';
-import { PathContext } from './core/PathContext.js';
+import { WorkspaceConfig } from './workspace-config.js';
+import { resolveOrigin } from './origin.js';
+import { reportEnvironment, EXPLICIT_ORIGIN_SOURCE } from './environment-report.js';
+import { diag } from './diagnostic-log.js';
 
 export class DeSciXApiClient {
   constructor(options = {}) {
     this.baseUrl = options.baseUrl || null; // Will be loaded async
     this.credentials = null;
     this.workspaceRoot = options.workspaceRoot || null; // Set by initialize()
-    this._pathContext = null; // Cached PathContext
+    this._workspaceConfig = null; // Cached WorkspaceConfig
     this._initialized = false;
+    // serviceMode: a headless service-context client (an app microservice reusing this
+    // api-client to call /apifront AS the developer). It NEVER falls back to interactive
+    // device login on a 401 — a Cloud Run service has no TTY — it hard-fails instead.
+    this.serviceMode = options.serviceMode === true;
   }
 
   /**
    * Initialize the client by finding workspace root and loading config
    * This is the primary initialization method - call before any API operations
-   * 
-   * Uses PathContext for unified path resolution.
-   * 
+   *
+   * Uses WorkspaceConfig for unified path resolution.
+   *
    * @returns {Promise<void>}
    */
   async initialize() {
@@ -32,19 +39,35 @@ export class DeSciXApiClient {
       return;
     }
 
-    // Step 1: Try to load PathContext (will find IDE marker and load workspace.json)
-    this._pathContext = await PathContext.tryLoad();
+    // Step 1: Try to load WorkspaceConfig (finds .descix/workspace.json upward)
+    this._workspaceConfig = await WorkspaceConfig.tryLoad();
 
-    if (this._pathContext) {
-      this.workspaceRoot = this._pathContext.getWorkspaceRoot();
+    if (this._workspaceConfig) {
+      this.workspaceRoot = this._workspaceConfig.getWorkspaceRoot();
     } else {
       this.workspaceRoot = null;
     }
 
-    // Step 2: Set API URL from PathContext config or environment (only if not already set)
+    // Step 2: Settle the API origin, and SAY SO.
+    //
+    // THE PRINT LIVES HERE, NOT IN detectApiUrl(), AND THAT IS THE WHOLE POINT. detectApiUrl()
+    // is only reached when `baseUrl` was NOT supplied to the constructor. Six construction
+    // sites DO supply it (service-api-client, wizard/setup, commands/auth, commands/status,
+    // commands/doctor, bin/mcp-server), so a print hung off detectApiUrl() would go silent on
+    // exactly the paths a developer is most likely to be pointing somewhere unexpected.
+    // initialize() is the one seam both paths cross. (Enumerated across all 87
+    // `new DeSciXApiClient(` sites, 2026-08-30.)
+    let originSource;
     if (!this.baseUrl) {
-      this.baseUrl = await this.detectApiUrl();
+      const resolved = await this.detectApiUrl();
+      this.baseUrl = resolved.origin;
+      originSource = resolved.source;
+    } else {
+      this.baseUrl = String(this.baseUrl).trim().replace(/\/+$/, '');
+      originSource = EXPLICIT_ORIGIN_SOURCE;
     }
+    // I1 (A', rev 2): ALWAYS, not default-only. Silence was the defect; PROD was not.
+    reportEnvironment({ origin: this.baseUrl, source: originSource });
 
     // Step 3: Load credentials from known wallet location
     await this.loadCredentials();
@@ -53,34 +76,36 @@ export class DeSciXApiClient {
   }
 
   /**
-   * Detect API URL from workspace config or environment
-   * @returns {Promise<string>} API base URL
+   * Detect the API origin from workspace config or environment.
+   *
+   * Returns the SOURCE alongside the origin, because "where did this come from" is the question
+   * every misreport in this contract failed to answer, and the caller must print it.
+   *
+   * @returns {Promise<{origin: string, source: string, isDefault: boolean}>}
    */
   async detectApiUrl() {
-    const PRODUCTION_URL = 'https://descix.net';
-
-    // Check environment variable first (highest priority)
-    if (process.env.DESCIX_API_URL) {
-      return process.env.DESCIX_API_URL;
-    }
-
-    // Use PathContext config if loaded (but only if it has an explicit URL, not the production default)
-    if (this._pathContext) {
-      const apiUrl = this._pathContext.getApiUrl();
-      if (apiUrl && apiUrl !== PRODUCTION_URL) {
-        return apiUrl;
-      }
-    }
-
-    // Check global config (set by `descix login --dev` or `descix config set-url`)
+    // 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();
-      if (gc.api_url && gc.api_url !== PRODUCTION_URL) return gc.api_url;
+      globalApiUrl = gc.api_url || null;
     } catch {}
 
-    // Default to production
-    return PRODUCTION_URL;
+    // 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,
+    });
   }
 
   /**
@@ -102,6 +127,86 @@ export class DeSciXApiClient {
     return this.baseUrl;
   }
 
+  /**
+   * WS-HEADLESS-MVP-A1 (mcp-oauth-longlived-tokens design §2.4, Option 4A) — attach the
+   * cached OAuth access token as the standard `Authorization: Bearer` header when the
+   * credential cache holds a FRESH one.
+   *
+   * This REPLACES the retired gcloud-IAM transport seam (_isIamGatedOrigin/_mintIamBearer/
+   * _applyIamAuthIfNeeded): `apiFront-http-dev` now deploys --allow-unauthenticated and the
+   * OAuth bearer — verified by the app layer (verifyMcpAccessToken on /mcp; scope/exposure
+   * gate + checkCommandPermission) — is the wall. No Google identity token, no gcloud, no
+   * ~1h SSO reauth. The CLI's session credential still travels in the request BODY for the
+   * /apifront auth middleware (the wallet-sig/API_KEY headless path, CEO-D-2026-06-02).
+   *
+   * ensureSession() keeps the token fresh (silent refresh); this method only ATTACHES it.
+   * No-op when no OAuth credential is cached — never a fabricated fallback.
+   *
+   * @param {Object} axiosConfig
+   * @returns {Object}
+   */
+  _applyOAuthBearerIfAvailable(axiosConfig) {
+    const oauthBlock = this.credentials?.oauth;
+    if (!oauthBlock?.access_token) return axiosConfig;
+    axiosConfig.headers = { ...(axiosConfig.headers || {}), Authorization: `Bearer ${oauthBlock.access_token}` };
+    return axiosConfig;
+  }
+
+  /**
+   * WS-HEADLESS-MVP-A1 (design §2.2/§4.1) — OAuth silent refresh, the gcloud-ADC analogue.
+   *
+   * When the cached OAuth access token is expired (or within the 60s skew window), POST
+   * grant_type=refresh_token to /oauth/token. The AS ROTATES the refresh token on use, so
+   * BOTH returned tokens are persisted back to wallet.json immediately — losing the rotated
+   * refresh token would trip the AS's reuse-detection and revoke the whole chain.
+   *
+   * Non-interactive for up to 30 days of inactivity (sliding window under rotation). If the
+   * refresh is rejected (revoked/expired chain), we FAIL LOUD once per process and leave the
+   * wallet-sig path — which is untouched by the OAuth branch — to carry the session; the
+   * user re-runs `descix login` to re-establish OAuth.
+   */
+  async _ensureOAuthAccessToken() {
+    const oauthBlock = this.credentials?.oauth;
+    if (!oauthBlock?.refresh_token || this._oauthRefreshFailed) return;
+
+    const { isOAuthAccessTokenFresh, refreshOAuthTokens, buildOAuthCredentialBlock } = await import('./oauth-client.js');
+    if (isOAuthAccessTokenFresh(oauthBlock)) return;
+
+    try {
+      const tokens = await refreshOAuthTokens(this.baseUrl, {
+        refreshToken: oauthBlock.refresh_token,
+        clientId: oauthBlock.client_id,
+      });
+      const updated = buildOAuthCredentialBlock({
+        clientId: oauthBlock.client_id,
+        tokens,
+        tokenEndpointBase: this.baseUrl,
+      });
+      this.credentials.oauth = updated;
+
+      // Persist the ROTATED pair to wallet.json (same write path as the session refresh).
+      try {
+        const { WalletFileManager } = await import('./wallet-file.js');
+        const walletPath = await WalletFileManager.findWalletFile(this.workspaceRoot || process.cwd());
+        if (walletPath) {
+          const walletData = await WalletFileManager.loadWalletFile(walletPath);
+          if (walletData) {
+            walletData.oauth = updated;
+            await WalletFileManager.saveWalletFile(walletPath, walletData);
+          }
+        }
+      } catch (saveErr) {
+        console.error('[ApiClient] Failed to persist rotated OAuth tokens to wallet file:', saveErr.message);
+      }
+    } catch (error) {
+      // Revoked/expired refresh chain (or AS unreachable): loud, once per process. The
+      // wallet-sig session path proceeds independently — no silent credential fabrication.
+      this._oauthRefreshFailed = true;
+      console.error(`[ApiClient] OAuth silent refresh failed: ${error.message}. ` +
+        `Run 'descix login' to re-establish OAuth credentials.`);
+    }
+  }
+
   /**
    * Build request body for API call
    * @param {string} command - Command name
@@ -135,11 +240,19 @@ export class DeSciXApiClient {
    * @returns {Promise<void>}
    */
   async ensureSession() {
+    // WS-HEADLESS-MVP-A1 OAuth branch: keep the cached OAuth access token fresh (silent
+    // refresh against /oauth/token). Runs ONLY when an `oauth` credential block exists in
+    // wallet.json (written by `descix login`) — the wallet-sig session path below is
+    // untouched and remains the headless/API_KEY credential (design §2.6).
+    if (this.credentials?.oauth?.refresh_token) {
+      await this._ensureOAuthAccessToken();
+    }
+
     // If we already have an access token, assume it's valid (will retry if expired)
     if (this.credentials?.accessToken) {
       return;
     }
-    
+
     // If we have wallet credentials but no session, get one via reconnect_by_wallet
     if (this.credentials?.walletAddress && this.credentials?.signature) {
       try {
@@ -190,16 +303,16 @@ export class DeSciXApiClient {
    * @returns {Promise<Object>} Response data
    */
   async invokeRaw(command, params = {}, credentials = null, options = {}) {
-    console.log(`[ApiClient] invoking ${command}...`);
+    diag(`[ApiClient] invoking ${command}...`);
     await this.ensureBaseUrl();
-    console.log(`[ApiClient] Base URL: ${this.baseUrl}`);
+    diag(`[ApiClient] Base URL: ${this.baseUrl}`);
     
     const requestBody = this.buildRequestBody(command, params, credentials);
     if (options.skipSessionCheck) {
       requestBody.access_token = null; // Force guest-like call for refresh
     }
     const url = `${this.baseUrl}/apifront/`;
-    console.log(`[ApiClient] POST ${url}`);
+    diag(`[ApiClient] POST ${url}`);
 
     const axiosConfig = {
       headers: { 'Content-Type': 'application/json' },
@@ -212,16 +325,23 @@ export class DeSciXApiClient {
         rejectUnauthorized: false
       });
     }
-    
+
+    // WS-A1: OAuth bearer rides the standard Authorization header (no-op without a cache).
+    this._applyOAuthBearerIfAvailable(axiosConfig);
+
     try {
       const response = await axios.post(url, requestBody, axiosConfig);
-      console.log(`[ApiClient] Response status: ${response.status}`);
+      diag(`[ApiClient] Response status: ${response.status}`);
       const data = response.data;
       
       if (data.status !== 'OK') {
         const error = new Error(data.message || 'API request failed');
         error.status = data.status;
         error.response = data;
+        // WS-HEADLESS-MVP-A3: surface structured error fields (e.g. CREDITS_REQUIRED
+        // code + purchasable-action data) to CLI/MCP consumers.
+        if (data.code) error.code = data.code;
+        if (data.data) error.data = data.data;
         throw error;
       }
 
@@ -232,6 +352,32 @@ export class DeSciXApiClient {
     }
   }
 
+  /**
+   * WS-MCP-SURFACE-SPLIT §10.2 — fetch the PERMISSION-FILTERED MCP tool catalog for THIS caller.
+   *
+   * Calls the backend `list_mcp_tools` command over the standard /apifront session/wallet path
+   * (the proven CLI auth: device-flow session token, with automatic reconnect-by-wallet refresh).
+   * The backend returns the catalog already filtered by the SAME server-side checkCommandPermission
+   * gate the HTTP /mcp tools/list uses — ONE describe-as-permission-gate, no parallel taxonomy in
+   * the CLI. `--admin` is just the operator's wallet carrying admin entitlements (cred-gated, §9.1).
+   *
+   * NOTE we deliberately do NOT hit /mcp here: that endpoint's bearer path is OAuth-only and its
+   * signature path needs a REGISTERED api-signature — neither is the CLI's session token. The
+   * command path reuses invoke()'s working session auth.
+   *
+   * @returns {Promise<Array<{name, description, inputSchema}>>}
+   */
+  async mcpListTools(options = {}) {
+    // The console.log monkey-patch that stood here is DELETED, not kept as insurance. It routed
+    // stdout to stderr for the duration of THIS call only — a call-site workaround for a
+    // write-site defect, which protected one path and left every other path through
+    // invoke()/invokeRaw() corrupting the stdio protocol stream. Diagnostics now go to stderr at
+    // the point of writing (lib/diagnostic-log.js), so there is nothing left to wrap.
+    const resp = await this.invoke('list_mcp_tools', {}, options);
+    const msg = resp?.message || resp;
+    return msg?.tools || [];
+  }
+
   /**
    * Invoke a command via HTTP with automatic session management
    * @param {string} command - Command name
@@ -279,7 +425,10 @@ export class DeSciXApiClient {
           rejectUnauthorized: false
         });
       }
-      
+
+      // WS-A1: OAuth bearer rides the standard Authorization header (no-op without a cache).
+      this._applyOAuthBearerIfAvailable(axiosConfig);
+
       const response = await axios.post(url, requestBody, axiosConfig);
 
       const data = response.data;
@@ -288,6 +437,10 @@ export class DeSciXApiClient {
         const error = new Error(data.message || 'API request failed');
         error.status = data.status;
         error.response = data;
+        // WS-HEADLESS-MVP-A3: surface structured error fields (e.g. CREDITS_REQUIRED
+        // code + purchasable-action data) to CLI/MCP consumers.
+        if (data.code) error.code = data.code;
+        if (data.data) error.data = data.data;
         throw error;
       }
 
@@ -316,10 +469,18 @@ export class DeSciXApiClient {
         // If we got a new token, retry the original request
         if (this.credentials?.accessToken) {
           return this.invoke(command, params, { ...options, _retried: true });
+        } else if (this.serviceMode) {
+          // Headless service context: no interactive device login is possible. The developer's
+          // wallet_address + signature failed to mint/refresh a session — fail loud (no fallback).
+          throw new Error(
+            `[ServiceApiClient] reconnect_by_wallet failed for command '${command}': the developer ` +
+            `credential (wallet_address + signature) did not yield a session. Check the credential in ` +
+            `dev-overrides.json (dev) / the secret (prod). No interactive login fallback in a microservice.`
+          );
         } else if (command !== 'device_request_login' && command !== 'device_check_status') {
           // If refresh failed (e.g. signature invalid or user not found), 
           // we should trigger device login if this is a CLI environment
-          console.log('[ApiClient] Session refresh failed, triggering device login...');
+          diag('[ApiClient] Session refresh failed, triggering device login...');
           const { loginDevice } = await import('./commands/auth.js');
           await loginDevice({ url: this.baseUrl, workspaceRoot: this.workspaceRoot });
           
@@ -339,6 +500,10 @@ export class DeSciXApiClient {
         const apiError = new Error(errorData.message || `HTTP ${error.response.status}`);
         apiError.status = error.response.status;
         apiError.response = errorData;
+        // WS-HEADLESS-MVP-A3: ferry structured error fields (code + purchasable-action
+        // data, e.g. CREDITS_REQUIRED/402) through the axios error path.
+        if (errorData.code) apiError.code = errorData.code;
+        if (errorData.data) apiError.data = errorData.data;
         throw apiError;
       } else if (error.code === 'ECONNREFUSED') {
         throw new Error(`Cannot connect to ${this.baseUrl}. Is the backend server running?`);
@@ -361,19 +526,18 @@ export class DeSciXApiClient {
       return this.credentials;
     }
 
-    // Use PathContext's workspace root if available
-    if (!this.workspaceRoot && this._pathContext) {
-      this.workspaceRoot = this._pathContext.getWorkspaceRoot();
+    // Use WorkspaceConfig's workspace root if available
+    if (!this.workspaceRoot && this._workspaceConfig) {
+      this.workspaceRoot = this._workspaceConfig.getWorkspaceRoot();
     }
 
-    // If still no workspace root, try: PathContext (IDE markers) → workspace.json → wallet.json
+    // If still no workspace root, try: WorkspaceConfig → wallet.json walk
     if (!this.workspaceRoot) {
-      const ctx = await PathContext.tryLoad();
-      if (ctx) {
-        this.workspaceRoot = ctx.getWorkspaceRoot();
-        this._pathContext = ctx;
+      const wsConfig = await WorkspaceConfig.tryLoad();
+      if (wsConfig) {
+        this.workspaceRoot = wsConfig.getWorkspaceRoot();
+        this._workspaceConfig = wsConfig;
       } else {
-        const { WorkspaceConfig } = await import('./workspace-config.js');
         this.workspaceRoot = await WorkspaceConfig.findWorkspaceRoot();
       }
       // Final fallback: walk up from cwd looking for .descix/wallet.json
@@ -410,7 +574,10 @@ export class DeSciXApiClient {
         walletAddress: walletData.walletAddress || null,
         signature: walletData.signature || null,
         communityId: walletData.communityId || null,
-        tokenSymbol: walletData.tokenSymbol || null
+        tokenSymbol: walletData.tokenSymbol || null,
+        // WS-A1: OAuth credential block (gcloud-ADC analogue) — null when never logged in
+        // via the device→OAuth bridge; the wallet-sig path is then the sole credential.
+        oauth: walletData.oauth || null
       };
 
       return this.credentials;
@@ -437,12 +604,12 @@ export class DeSciXApiClient {
   }
 
   /**
-   * Get the PathContext instance (if loaded)
+   * Get the WorkspaceConfig instance (if loaded)
    * Useful for commands that need path resolution
-   * @returns {PathContext|null}
+   * @returns {WorkspaceConfig|null}
    */
-  getPathContext() {
-    return this._pathContext;
+  getWorkspaceConfig() {
+    return this._workspaceConfig;
   }
 }
 

package/lib/auth-guard.js

@@ -14,6 +14,16 @@ import { DeSciXApiClient } from './api-client.js';
  * @returns {Promise<Object>} User information if authenticated
  */
 export async function requireAuth(apiClient) {
+  // Settle (and PRINT) the origin BEFORE the credential check, not after it.
+  //
+  // MEASURED 2026-08-30: this guard called loadCredentials() directly and exited 1 on a missing
+  // credential, so initialize() never ran and the env line never printed. An unauthenticated
+  // developer was told "Authentication required" with no statement of WHICH environment they
+  // had failed to authenticate against — the exact confusion this contract exists to end, on
+  // the path where it is most likely to bite. ensureInitialized() is idempotent, so the later
+  // invoke() below re-uses this same initialisation.
+  await apiClient.ensureInitialized();
+
   // Load credentials from wallet file
   await apiClient.loadCredentials();
   
@@ -24,9 +34,9 @@ export async function requireAuth(apiClient) {
     process.exit(1);
   }
   
-  // Validate session is still active by calling check_staked_status via HTTP
+  // Validate session is still active by calling validate_session via HTTP
   try {
-    const response = await apiClient.invoke('check_staked_status', {}, { allowGuest: false });
+    const response = await apiClient.invoke('validate_session', {}, { allowGuest: false });
     if (response.status === 'OK' && response.message) {
       return response.message;
     }
@@ -58,7 +68,7 @@ export async function isAuthenticated(apiClient) {
       return false;
     }
     // Try a lightweight check via HTTP
-    const response = await apiClient.invoke('check_staked_status', {}, { allowGuest: false });
+    const response = await apiClient.invoke('validate_session', {}, { allowGuest: false });
     return response.status === 'OK';
   } catch (error) {
     return false;

package/lib/chat-session.js

@@ -0,0 +1,187 @@
+/**
+ * Chat session state — the owner module for the CLI's per-app conversation thread pointer.
+ *
+ * Conversation state itself lives SERVER-SIDE at the model provider; all the CLI keeps is an
+ * opaque DeSciX interaction token per app in `~/.descix/sessions/{community_id}_{app_id}.json`.
+ * This module owns reading, writing, and forgetting that pointer, plus the one rule for when a
+ * dead pointer may be self-healed.
+ *
+ * Extracted out of `bin/descix.js` (ws-cli-stale-thread-selfheal) so the self-heal decision is
+ * unit-testable in isolation — in particular so the 400-heals / 403-never-heals asymmetry can be
+ * proven by a test rather than asserted in a comment.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Get interaction_id from session file
+ * @param {string} communityId 
+ * @param {string} appId 
+ * @returns {Promise<string|null>}
+ */
+export async function getSessionInteractionId(communityId, appId) {
+    const sessionPath = path.join(os.homedir(), '.descix', 'sessions', `${communityId}_${appId}.json`);
+    try {
+        const data = JSON.parse(await fs.readFile(sessionPath, 'utf-8'));
+        return data.interaction_id || null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Save interaction_id to session file
+ * @param {string} communityId 
+ * @param {string} appId 
+ * @param {string} interactionId 
+ */
+async function saveSessionInteractionId(communityId, appId, interactionId) {
+    const sessionDir = path.join(os.homedir(), '.descix', 'sessions');
+    await fs.mkdir(sessionDir, { recursive: true });
+    const sessionPath = path.join(sessionDir, `${communityId}_${appId}.json`);
+    await fs.writeFile(sessionPath, JSON.stringify({ 
+        interaction_id: interactionId, 
+        updated: Date.now() 
+    }, null, 2));
+}
+
+/**
+ * Clear session file
+ * @param {string} communityId 
+ * @param {string} appId 
+ */
+async function clearSession(communityId, appId) {
+    const sessionPath = path.join(os.homedir(), '.descix', 'sessions', `${communityId}_${appId}.json`);
+    try {
+        await fs.unlink(sessionPath);
+    } catch {
+        // File doesn't exist, that's fine
+    }
+}
+
+/**
+ * WS-R7-PREREQS (CEO-D-2026-07-04-R7-PREREQS-RESCOPE ruling 3) session helpers.
+ *
+ * Session files are keyed {community_id}_{app_id}.json where community_id is the
+ * SERVER-resolved value (returned by app-scoped commands). Before the server response
+ * arrives the community may be unknown client-side — app_id is globally unique on the
+ * platform (product_id === app_id), so `*_{appId}.json` identifies the app's sessions
+ * unambiguously and the newest file is the current thread.
+ */
+
+/**
+ * List existing session files for an app, newest first.
+ * @param {string} appId
+ * @returns {Promise<Array<{communityId: string, path: string, updated: number}>>}
+ */
+export async function findSessionsForApp(appId) {
+    const sessionDir = path.join(os.homedir(), '.descix', 'sessions');
+    const suffix = `_${appId}.json`;
+    let entries = [];
+    try {
+        entries = await fs.readdir(sessionDir);
+    } catch {
+        return [];
+    }
+    const results = [];
+    for (const name of entries) {
+        if (!name.endsWith(suffix)) continue;
+        const communityId = name.slice(0, name.length - suffix.length);
+        if (!communityId) continue;
+        const filePath = path.join(sessionDir, name);
+        let updated = 0;
+        try {
+            const data = JSON.parse(await fs.readFile(filePath, 'utf-8'));
+            updated = data.updated || 0;
+        } catch {
+            continue; // unreadable session file — skip, do not guess
+        }
+        results.push({ communityId, path: filePath, updated });
+    }
+    results.sort((a, b) => b.updated - a.updated);
+    return results;
+}
+
+/**
+ * Save the session under the AUTHORITATIVE community key and self-heal: remove any
+ * session files for the same app keyed under a DIFFERENT community (e.g. the legacy
+ * hardcoded 'descix_*' mis-keys this fix removes). One app = one live session file.
+ * @param {string} communityId - server-resolved community_id
+ * @param {string} appId
+ * @param {string} interactionId
+ */
+export async function saveSessionAuthoritative(communityId, appId, interactionId) {
+    const stale = (await findSessionsForApp(appId)).filter(s => s.communityId !== communityId);
+    await saveSessionInteractionId(communityId, appId, interactionId);
+    for (const st of stale) {
+        try { await fs.unlink(st.path); } catch { /* already gone */ }
+    }
+}
+
+/**
+ * Clear this app's chat session(s) — the ONE owner of "forget the current thread".
+ *
+ * Mirrors the read path: with a known community it clears the exact key; without one it
+ * clears every session file for the app (app_id is globally unique, so `*_{appId}.json` is
+ * unambiguous). Previously this logic was hand-copied at three call sites (`chat --new`,
+ * `new-chat` with/without `-c`); the self-heal below would have made it four. One owner
+ * means the heal can never diverge from what `--new` does.
+ *
+ * @param {string|null} communityId
+ * @param {string} appId
+ * @returns {Promise<number>} how many session files were removed
+ */
+export async function clearAppSessions(communityId, appId) {
+    if (communityId) {
+        const sessionPath = path.join(os.homedir(), '.descix', 'sessions', `${communityId}_${appId}.json`);
+        let existed = false;
+        try { await fs.access(sessionPath); existed = true; } catch { /* nothing to clear */ }
+        await clearSession(communityId, appId);
+        return existed ? 1 : 0;
+    }
+    const sessions = await findSessionsForApp(appId);
+    for (const st of sessions) {
+        try { await fs.unlink(st.path); } catch { /* already gone */ }
+    }
+    return sessions.length;
+}
+
+/**
+ * ── Stale-thread self-heal (ws-cli-stale-thread-selfheal) ────────────────────────────────
+ *
+ * Conversation state lives server-side at the model provider; the CLI holds only an opaque
+ * DeSciX interaction token in `~/.descix/sessions/{community}_{app}.json`. A stored token can
+ * stop being resumable for reasons that are nobody's fault — the provider's retention window
+ * (~55 days) elapsed, or the token predates the current token format. The backend correctly
+ * refuses to answer statelessly and pretends nothing happened; it raises this typed 400. The
+ * right client behaviour is to drop the dead pointer and start a fresh thread, telling the
+ * user plainly that continuity was lost.
+ *
+ * ⚠️ THE ASYMMETRY IS THE WHOLE DESIGN. This constant is the ONLY interaction-thread error
+ * code the CLI is allowed to know about, and it is deliberately the 400.
+ *
+ * Its 403 sibling — the one raised when a presented token was forged, tampered with, or
+ * belongs to a DIFFERENT caller — must NEVER appear in this file. Self-healing a 403 would
+ * clear the session and silently succeed on a fresh thread, converting a deliberate,
+ * carefully-typed security denial into a no-op that the user never sees. A 403 must reach
+ * the user loudly and untouched: no clear, no retry, no notice. A conformance test asserts
+ * that the 403 code appears nowhere in this file's executable source.
+ */
+export const INTERACTION_THREAD_INVALID = 'INTERACTION_THREAD_INVALID';
+
+/**
+ * Should this failure trigger the single stale-thread retry?
+ *
+ * Narrow by construction: an exact typed-code match (never message-substring matching —
+ * anti-pattern #6), and only when a stored token was actually sent, since with no thread to
+ * heal there is nothing this could be about.
+ *
+ * @param {Error} error - the error thrown by apiClient.invoke
+ * @param {string|null} sentInteractionId - the token that was presented, if any
+ * @returns {boolean}
+ */
+export function isStaleThreadError(error, sentInteractionId) {
+    return Boolean(sentInteractionId) && error?.code === INTERACTION_THREAD_INVALID;
+}