@descix/cli 1.0.20 → 2.0.0

package/bin/descix.js

@@ -14,6 +14,7 @@ import { requireAuth } from '../lib/auth-guard.js';
 import { WorkspaceConfig, unmappedAppMessage, resolveWorkspacePath } from '../lib/workspace-config.js';
 import { CLI_VERSION } from '../lib/cli-version.js';
 import { recordInvocationOrigin } from '../lib/origin.js';
+import { verifyDeployOutcome } from '../lib/deploy-outcome.js';
 // Chat session pointer + the ONE rule for when a dead pointer may be self-healed.
 import {
   getSessionInteractionId,
@@ -1081,7 +1082,6 @@ appCommand
   .option('-s, --short <short_name>', 'SHORT id segment (no hyphens) used when creating; the app_id is composed server-side as {community}-{short}. Defaults to --app.')
   .option('--overwrite', 'When creating, overwrite an existing app record intentionally')
   .option('--kb <name>', 'Knowledge base name', 'General')
-  .option('-p, --path <dir>', 'Local app directory (default: auto-detected or cwd)')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
@@ -1500,111 +1500,15 @@ appCommand
     }
   });
 
-appCommand
-  .command('set-localpath')
-  .description('Update the local directory path for a mapped app')
-  .requiredOption('-a, --app <app_id>', 'App ID')
-  .requiredOption('-p, --path <dir>', 'New local directory path')
-  .action(async (options) => {
-    try {
-      const appId = options.app;
-      const newPath = options.path;
-
-      const workspaceConfig = await WorkspaceConfig.load();
-      const wsRoot = workspaceConfig.workspaceRoot || process.cwd();
-
-      // 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(absPath);
-      } catch {
-        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: ${absPath}\n` +
-          `  (localPath '${newPath}' resolved against workspace root ${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`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
-appCommand
-  .command('unmap')
-  .description('Remove an app from the local workspace mapping (does not delete Firestore/Pinecone data)')
-  .requiredOption('-a, --app <app_id>', 'App ID')
-  .action(async (options) => {
-    try {
-      const appId = options.app;
-
-      const workspaceConfig = await WorkspaceConfig.load();
-      const appConfig = workspaceConfig.getAppByAppId(appId);
-      if (!appConfig) {
-        throw new Error(`App '${appId}' is not mapped.`);
-      }
-
-      // Remove from env.products
-      const products = workspaceConfig.env?.products || [];
-      const idx = products.findIndex(p => p.appId === appId || p.app_id === appId);
-      if (idx === -1) {
-        throw new Error(`App '${appId}' is not found in env.products.`);
-      }
-      products.splice(idx, 1);
-
-      const wsRoot = workspaceConfig.workspaceRoot || process.cwd();
-      await workspaceConfig.save(wsRoot);
-
-      console.log(chalk.green(`\n✓ ${appId} removed from workspace mapping`));
-      console.log(chalk.gray(`  Pinecone vectors, Firestore docs, and Drive data are not affected.\n`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
 // ============ App: set-port (WS-CLI-MESH-ROUTING-GAP) ============
 //
 // Canonical write path for an app's microservice.port in workspace.json.
-// `descix microservice init` READS env.products[<app>].microservice.port and hard-fails
+// `descix microservice init` READS env.app.microservice.port and hard-fails
 // if it is missing; this command is how that port is set, without hand-editing workspace.json.
 // Backed by WorkspaceConfig.setMicroservicePort.
 appCommand
   .command('set-port')
-  .description('Set the microservice port for a mapped app (writes env.products[<app>].microservice.port). Pass "n" to remove.')
+  .description('Set the microservice port for this workspace\'s app (writes env.app.microservice.port). Pass "n" to remove.')
   .requiredOption('-a, --app <app_id>', 'App ID (must be mapped in workspace.json)')
   .requiredOption('-p, --port <port>', 'Microservice port number (1-65535), or "n" to remove')
   .action(async (options) => {
@@ -1631,7 +1535,7 @@ appCommand
 
       console.log(chalk.green(`\n✓ Microservice port set for ${appId}`));
       console.log(chalk.cyan(`  Port: ${portNum}`));
-      console.log(chalk.gray(`  Written to env.products[${appId}].microservice.port in workspace.json.`));
+      console.log(chalk.gray(`  Written to env.app.microservice.port in workspace.json.`));
       console.log(chalk.gray(`  The gateway routes the microservice on this port; \`descix microservice init -a ${appId}\` can now scaffold it.\n`));
     } catch (error) {
       console.error(chalk.red(error.message));
@@ -1655,7 +1559,7 @@ appCommand
 // Backed by WorkspaceConfig.setStaticSite. It writes ONLY the local workspace.json site.{} slot.
 appCommand
   .command('set-site')
-  .description("Set a mapped app's site config (env.products[<app>].site). One active mode per write: --static <dir> (built site served at /p/<app>/) or --port <n> [--protocol http|https] (dev server proxied at /p/<app>); setting one clears the other. Pass both flags together to keep both — the gateway then serves the dev server (site.port wins). --unset clears site.{} entirely.")
+  .description("Set this workspace app's site config (env.app.site). One active mode per write: --static <dir> (built site served at /p/<app>/) or --port <n> [--protocol http|https] (dev server proxied at /p/<app>); setting one clears the other. Pass both flags together to keep both — the gateway then serves the dev server (site.port wins). --unset clears site.{} entirely.")
   .requiredOption('-a, --app <app_id>', 'App ID (must be mapped in workspace.json)')
   .option('--static <path>', 'Static mode: relative dir under the app localPath (e.g. "site"; "." = the localPath itself). Alone, it clears site.port and site.protocol (one active mode per write).')
   .option('--port <port>', 'Dev-server mode: proxy /p/<app> to your local dev server on this port (1-65535). Alone, it clears site.static. With --static in the same call, both are kept and the gateway serves the dev server.')
@@ -1714,9 +1618,7 @@ appCommand
       // Print the RESULTING slot, not just the fields passed: a dev-server write keeps a
       // previously declared site.protocol (same mode, new port), and a retained field the
       // output does not show is invisible state — the whole defect class this command fixes.
-      const entryNow = workspaceConfig.env?.platform?.appId === appId
-        ? workspaceConfig.env.platform
-        : (workspaceConfig.env?.products || []).find(p => p.appId === appId);
+      const entryNow = workspaceConfig.env?.app?.appId === appId ? workspaceConfig.env.app : null;
       console.log(chalk.cyan(`  site is now:   ${JSON.stringify(entryNow?.site)}`));
       if (fields.static !== undefined && fields.port === undefined) {
         console.log(chalk.gray(`  site.port and site.protocol cleared (one active mode per write) — /p/${appId}/ now serves the static dir.`));
@@ -1725,7 +1627,7 @@ appCommand
       } else if (fields.static !== undefined && fields.port !== undefined) {
         console.log(chalk.yellow(`  Combined write: BOTH modes kept. The gateway serves the DEV SERVER (site.port wins); site.static is used only after you clear site.port (--static alone, or --unset).`));
       }
-      console.log(chalk.gray(`  Written to env.products[${appId}].site in workspace.json; \`descix serve\` picks it up.\n`));
+      console.log(chalk.gray(`  Written to env.app.site in workspace.json; \`descix serve\` picks it up.\n`));
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exit(1);
@@ -1740,9 +1642,9 @@ appCommand
 // Reuses the SDK resolver resolveAppGatewayUrl() — the same workspace.json read path
 // behind buildWorkspaceProducts() that the PWA bakes into __WORKSPACE_PRODUCTS__ — so
 // the URL matches what the app store routes to:
-//   - env.platform        → https://localhost:{gatewayPort}/
-//   - product (static)    → https://localhost:{gatewayPort}/p/{appId}
-//   - product (dev-server)→ https://localhost:{gatewayPort}/p/{appId}
+//   - the gateway shell   → https://localhost:{gatewayPort}/
+//   - an app (static)     → https://localhost:{gatewayPort}/p/{appId}
+//   - an app (dev-server) → https://localhost:{gatewayPort}/p/{appId}
 // Hard-fails clearly if the app is unmapped or has no site config.
 appCommand
   .command('open')
@@ -2589,6 +2491,28 @@ siteCommand
           branch: gitStatus.branch
         } : null,
         preview: options.preview || false
+      }).catch(async (confirmErr) => {
+        // ws-prune-504: a lost confirm RESPONSE is not a failed DEPLOY. Re-read the served
+        // manifest keyed on THIS upload's token and say which it actually is — never "failed"
+        // when the truth is knowable.
+        console.log(chalk.yellow(`\n  Confirm response lost (${confirmErr.message}) — reading the deploy record back...`));
+        const verdict = await verifyDeployOutcome(apiClient, {
+          communityId, appId, tokenId: token_id, preview: options.preview || false
+        });
+        if (verdict.outcome === 'confirmed') {
+          console.log(chalk.green(`\n  Deploy CONFIRMED — ${verdict.detail}.`));
+          console.log(chalk.gray(`  The server may still be finishing the stale-file prune; ` +
+            `'descix site status -c ${communityId} -a ${appId}' shows the deploy, 'descix site list' what is served.`));
+          process.exit(0);
+        }
+        if (verdict.outcome === 'unconfirmed') {
+          console.error(chalk.red(`\n  Deploy UNCONFIRMED — ${verdict.detail}.`));
+          console.error(chalk.red(`  Nothing was removed from the server. Re-run the upload.`));
+          process.exit(1);
+        }
+        console.error(chalk.red(`\n  Deploy outcome UNKNOWN — ${verdict.detail}.`));
+        console.error(chalk.red(`  Check 'descix site status -c ${communityId} -a ${appId}' before re-running.`));
+        process.exit(1);
       });
 
       const result = confirmResponse.message;
@@ -2602,6 +2526,10 @@ siteCommand
       }
       console.log(chalk.gray(`  Removed from the server: ${pruned.length}`));
       pruned.forEach(f => console.log(chalk.gray(`    - ${f}`)));
+      if (result.prune_status === 'partial') {
+        console.log(chalk.yellow(`  Prune PARTIAL: ${result.prune_remaining_count} stale file(s) not yet removed (soft budget).`));
+        console.log(chalk.yellow(`  ${result.prune_remedy}`));
+      }
       console.log(chalk.gray(`  Deployed: ${result.deployed_at}`));
       if (result.preview) {
         console.log(chalk.yellow(`  Mode: PREVIEW`));
@@ -2830,13 +2758,7 @@ microserviceCommand
       // Hard-fail early if missing — a scaffolded microservice without a known port
       // cannot be routed by the gateway and cannot start on a deterministic port.
       const env = workspaceConfig.env || {};
-      let microservicePort = null;
-      if (env.platform?.appId === ctx.appId) {
-        microservicePort = env.platform?.microservice?.port || null;
-      } else if (Array.isArray(env.products)) {
-        const productEntry = env.products.find(p => p.appId === ctx.appId);
-        microservicePort = productEntry?.microservice?.port || null;
-      }
+      const microservicePort = env.app?.appId === ctx.appId ? (env.app.microservice?.port || null) : null;
 
       if (!microservicePort) {
         console.error(chalk.red(`\n❌ App '${ctx.appId}' has no microservice.port in workspace.json.`));
@@ -4179,7 +4101,7 @@ program
       // app_ids". `--scope project` was dead on this surface for exactly as long as v2.1 has been
       // the format.
       //
-      // v2.1 carries APP IDS ONLY (env.platform.appId, env.products[].appId) — no community ids.
+      // v3 carries ONE APP ID (env.app.appId) — no community ids.
       // We therefore send app_ids alone and let the server resolve ownership from Products.
       // Deriving a community_id by splitting an app_id would violate the platform invariant that
       // app ids are OPAQUE to routing and lookups.
@@ -4199,14 +4121,11 @@ program
           process.exit(1);
         }
         const appIds = new Set();
-        if (wsConfig?.env?.platform?.appId) appIds.add(wsConfig.env.platform.appId);
-        for (const product of wsConfig?.env?.products || []) {
-          if (product?.appId) appIds.add(product.appId);
-        }
+        if (wsConfig?.env?.app?.appId) appIds.add(wsConfig.env.app.appId);
         // Fail LOUD rather than sending an empty context the server can only reject.
         if (appIds.size === 0) {
-          console.error(chalk.red("project scope: no apps found in .descix/workspace.json (env.platform.appId / env.products[].appId)."));
-          console.error(chalk.gray("    Use --scope entitlements, or add products to the workspace."));
+          console.error(chalk.red("project scope: this workspace holds no app (workspace.json env.app)."));
+          console.error(chalk.gray("    Use --scope entitlements, or run `descix app init` in this repo."));
           process.exit(1);
         }
         project_context = { app_ids: Array.from(appIds) };

package/lib/commands/appInit.js

@@ -12,27 +12,24 @@
 import chalk from 'chalk';
 import fs from 'fs/promises';
 import path from 'path';
-import { WorkspaceConfig, resolveWorkspacePath } from '../workspace-config.js';
+import { WorkspaceConfig, assertNoParentWorkspace } from '../workspace-config.js';
 import { refreshCommunityIdentity, printIdentityReceipt } from './communityIdentity.js';
 import { generateAgentFiles } from '../agent-files.js';
 
 /**
  * @param {Object} apiClient an authenticated DeSciXApiClient
- * @param {{app: string, community?: string, short?: string, overwrite?: boolean, kb?: string, path?: string}} options
+ * @param {{app: string, community?: string, short?: string, overwrite?: boolean, kb?: string}} options
  * @returns {Promise<{appId: string, communityId: string, appPath: string, kbId: string}>}
  */
 export async function runAppInit(apiClient, options) {
   let appId = options.app;
   const kbId = options.kb || 'General';
 
-  // Refuse an unusable -p BEFORE anything is written — server-side included. The same resolver
-  // the workspace loader applies on every read decides it, so a value accepted here is one the
-  // next read accepts too. Refusing only at registration came AFTER a `-c` create, leaving a
-  // platform app with no local registration (measured 2026-09-18, daita-docs).
-  const workspaceConfig = await WorkspaceConfig.tryLoad();
-  if (options.path) {
-    resolveWorkspacePath(workspaceConfig?.workspaceRoot || process.cwd(), options.path, appId);
-  }
+  // v3 single-app: THIS directory becomes (or already is) the workspace root. A workspace at an
+  // ANCESTOR is a refusal, loud, BEFORE anything is written anywhere — the walk-up used to
+  // silently register a nested checkout into the parent workspace (the measured trap).
+  await assertNoParentWorkspace(process.cwd());
+  const workspaceConfig = await WorkspaceConfig.tryLoad(process.cwd());
 
   // Resolve community_id from the Products registry to learn whether the app exists yet.
   let communityId;
@@ -74,26 +71,15 @@ export async function runAppInit(apiClient, options) {
     );
   }
 
-  // 1. Workspace.json — register app if not already mapped
-  const alreadyMapped = workspaceConfig?.getAppByAppId(appId);
-  let appPath = alreadyMapped?.absolutePath;
-
-  if (alreadyMapped && options.path) {
-    throw new Error(
-      `App '${appId}' is already mapped to '${alreadyMapped.localPath}'. ` +
-      `Use 'descix app set-localpath -a ${appId} -p <new-path>' to update.`
-    );
-  }
-
+  // 1. Workspace.json — THIS repo root is the workspace root and holds exactly this app (v3).
+  // registerApp is idempotent for the same id and REFUSES a different one: a repo that already
+  // holds another app errors loudly instead of being silently re-pointed.
   const wsRoot = workspaceConfig?.workspaceRoot || process.cwd();
-  if (!alreadyMapped) {
-    const localPath = options.path || '.';
-    const cfg = workspaceConfig || new WorkspaceConfig({}, wsRoot);
-    cfg.registerApp(communityId, appId, { localPath, kbId });
-    await cfg.save(wsRoot);
-    appPath = path.resolve(wsRoot, localPath);
-    console.log(chalk.gray(`  workspace.json updated: ${appId} → ${localPath}`));
-  }
+  const cfg = workspaceConfig || new WorkspaceConfig({ version: '3.0' }, wsRoot);
+  cfg.registerApp(communityId, appId, { kbId });
+  await cfg.save(wsRoot);
+  const appPath = wsRoot;
+  console.log(chalk.gray(`  workspace.json: env.app = ${appId} (this repo root)`));
 
   // 2. Create app folder structure (site, microservice, assets)
   const assetsDir = path.join(appPath, 'assets');

package/lib/commands/auth.js

@@ -22,9 +22,18 @@ const POLL_INTERVAL_MS = 3000; // 3 seconds
 const MAX_POLL_TIME_MS = 15 * 60 * 1000; // 15 minutes
 
 /**
- * Open browser to URL
+ * Open browser to URL — INTERACTIVE SESSIONS ONLY.
+ *
+ * A non-interactive invocation (a spawned test harness, CI, any piped run) must NEVER reach
+ * into the operator's live browser: measured 2026-10-10, the CLI test suite repeatedly seized
+ * the CEO's active tab because every spawned `quickstart`/`login` walked straight into the
+ * device flow's `open`. No TTY on stdout = print the URL, open nothing. DESCIX_NO_BROWSER=1
+ * forces the same for interactive runs that want it.
  */
 async function openBrowser(url) {
+  if (!process.stdout.isTTY || process.env.DESCIX_NO_BROWSER === '1') {
+    return false; // the caller already prints the URL on a false return
+  }
   const platform = process.platform;
   let command;
   

package/lib/commands/config.js

@@ -34,12 +34,10 @@ export async function show() {
       console.log(chalk.yellow(`   ⚠ This workspace pins ${normalizeOrigin(pinned)} (${environmentNameFor(pinned)}), but ${effective.source} overrides it for this shell.`));
     }
 
-    // Show mapped apps (v2.1 env.products)
-    const platform = workspaceConfig.env?.platform;
-    const products = workspaceConfig.env?.products || [];
-    const allApps = [platform?.appId, ...products.map(p => p.appId)].filter(Boolean);
-    if (allApps.length > 0) {
-      console.log(chalk.white(`   Apps:          ${allApps.join(', ')}`));
+    // v3 single-app: the one app this workspace holds
+    const appId = workspaceConfig.env?.app?.appId;
+    if (appId) {
+      console.log(chalk.white(`   App:           ${appId}`));
     }
 
     console.log('');

package/lib/commands/corpus.js

@@ -373,7 +373,7 @@ export async function runCorpusSync(apiClient, options) {
     const appConfig = workspaceConfig.getAppByAppId(appId);
     if (!appConfig) {
       spinner.fail(`App not found: ${appId}`);
-      throw new Error(`App "${appId}" not found in workspace.json. Check env.products[].`);
+      throw new Error(`App "${appId}" is not this workspace's app (workspace.json env.app).`);
     }
 
     const appRoot = appConfig.absolutePath;

package/lib/commands/health.js

@@ -36,7 +36,7 @@ import { promisify } from 'util';
 import { localUpstreamOrigin, resolveGatewayPort } from '@descix/app-sdk/dev';
 import https from 'https';
 import http from 'http';
-import { WorkspaceConfig } from '../workspace-config.js';
+import { WorkspaceConfig, resolveLocalApps } from '../workspace-config.js';
 
 const execAsync = promisify(exec);
 
@@ -109,47 +109,27 @@ function defaultHttpsProbe(url, timeoutMs = 8000, { insecure = false } = {}) {
  */
 function buildServiceRegistry(wsConfig) {
     const services = [];
-    const env = wsConfig.env || {};
 
-    if (env.platform) {
-        const name = env.platform.appId || 'platform';
-        if (env.platform.microservice?.port) {
+    // The local app set has ONE owner (workspaceApps, v3 fork (b)): this workspace's own
+    // env.app plus every repo env.gateway lists, each read from its OWN workspace.json.
+    const { apps } = resolveLocalApps(wsConfig);
+    for (const app of apps) {
+        if (app.microservice?.port) {
             services.push({
-                name,
-                appId: env.platform.appId,
-                port: env.platform.microservice.port,
+                name: app.appId,
+                appId: app.appId,
+                port: app.microservice.port,
                 type: 'microservice',
-                origin: localUpstreamOrigin(env.platform.microservice, 'env.platform.microservice'),
+                origin: localUpstreamOrigin(app.microservice, `env.app.microservice (${app.appId})`),
             });
         }
-        if (env.platform.site?.port) {
+        if (app.site?.port) {
             services.push({
-                name: `${name}-site`,
-                appId: env.platform.appId,
-                port: env.platform.site.port,
+                name: `${app.appId}-site`,
+                appId: app.appId,
+                port: app.site.port,
                 type: 'site',
-                origin: localUpstreamOrigin(env.platform.site, 'env.platform.site'),
-            });
-        }
-    }
-
-    for (const product of (env.products || [])) {
-        if (product.microservice?.port) {
-            services.push({
-                name: product.appId,
-                appId: product.appId,
-                port: product.microservice.port,
-                type: 'microservice',
-                origin: localUpstreamOrigin(product.microservice, `env.products[${product.appId}].microservice`),
-            });
-        }
-        if (product.site?.port) {
-            services.push({
-                name: `${product.appId}-site`,
-                appId: product.appId,
-                port: product.site.port,
-                type: 'site',
-                origin: localUpstreamOrigin(product.site, `env.products[${product.appId}].site`),
+                origin: localUpstreamOrigin(app.site, `env.app.site (${app.appId})`),
             });
         }
     }
@@ -279,15 +259,9 @@ async function probeGcloudAuth(execFn) {
  * - prod: only descix/egpt/powch (cutover #1 in-scope); raise on out-of-scope filter
  */
 function resolveAppsForCloudProbe(env, wsConfig, filterAppId) {
-    const allApps = [];
-    if (wsConfig.env?.platform?.appId) {
-        allApps.push(wsConfig.env.platform.appId);
-    }
-    for (const product of (wsConfig.env?.products || [])) {
-        if (product.appId) allApps.push(product.appId);
-    }
-    // Dedupe
-    const unique = [...new Set(allApps)];
+    // The app set has ONE owner (workspaceApps): env.app + every repo env.gateway lists.
+    const { apps } = resolveLocalApps(wsConfig);
+    const unique = [...new Set(apps.map(a => a.appId))];
 
     if (env === 'prod') {
         // PROD scope guard: only in-scope hosts allowed.

package/lib/commands/init.js

@@ -163,10 +163,9 @@ export async function runInit(apiClient, options = {}) {
     }
 
     console.log(chalk.gray(`\n${existingConfig ? 'Updating' : 'Writing'} .descix/workspace.json...\n`));
-    const config = existingConfig || new WorkspaceConfig({ version: '2.1', type: 'workspace', env: {} }, projectPath);
+    const config = existingConfig || new WorkspaceConfig({ version: '3.0', type: 'workspace', env: {} }, projectPath);
     if (existingConfig && options.force && config.env) {
-      config.env.products = [];
-      delete config.env.platform;
+      delete config.env.app;
     }
     // NO APP IS REGISTERED HERE. The app id is the platform's: `app init` creates the app and
     // registers the id the server returns (with -c it is composed from the community and the

package/lib/commands/kb.js

@@ -11,7 +11,7 @@
  * - compare: Show file-level deltas
  * 
  * Architecture:
- * - Uses WorkspaceConfig for all path resolution (supports v2.1 env.platform/products format)
+ * - Uses WorkspaceConfig for all path resolution (v3 single-app env.app format)
  * - All operations delegate to lib/core/ modules
  * - Supports interactive and unattended (agent) modes
  * - CLI handles UX (prompts, progress, errors)

package/lib/commands/microservice-restart.js

@@ -2,11 +2,11 @@
  * Microservice Restart Command (DEV only)
  *
  * Eliminates the "hand-kill + nohup-relaunch" tribal-knowledge workflow:
- *   1. Resolve the service from workspace.json `env.platform` / `env.products`
+ *   1. Resolve the service from the workspace's app set (env.app / env.gateway)
  *      (HARD-FAIL on unknown / ambiguous / missing devCommand).
  *   2. Find the running PID via `lsof -iTCP:<port> -sTCP:LISTEN` (or `ps`).
  *   3. SIGTERM → wait up to 5s → SIGKILL.
- *   4. Re-launch the canonical devCommand from `{workspaceRoot}/{localPath}/microservice/`
+ *   4. Re-launch the canonical devCommand from the app repo's own `microservice/` dir
  *      detached via `setsid + nohup`, redirecting stdout/stderr to a canonical log.
  *   5. Poll until the port is bound again; print new PID + log path.
  *   6. Run `descix health -m <name>` and print the result.
@@ -27,7 +27,7 @@ import { exec, spawn } from 'child_process';
 import { promisify } from 'util';
 import fs from 'fs/promises';
 import path from 'path';
-import { WorkspaceConfig } from '../workspace-config.js';
+import { WorkspaceConfig, resolveLocalApps } from '../workspace-config.js';
 
 const execAsync = promisify(exec);
 
@@ -44,28 +44,25 @@ const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
  * are restart-eligible (devCommand is the canonical launch signature).
  *
  * @param {WorkspaceConfig} wsConfig
- * @returns {Array<{name, localPath, port, devCommand, microserviceDir}>}
+ * @returns {Array<{name, dir, port, devCommand, microserviceDir}>}
  */
 export function buildRestartRegistry(wsConfig) {
-  const env = wsConfig.env || {};
-  const root = wsConfig.workspaceRoot;
   const out = [];
 
-  const collect = (entry) => {
-    if (!entry?.appId || !entry?.localPath) return;
-    const ms = entry.microservice;
-    if (!ms || !ms.port) return;
+  // The local app set has ONE owner (workspaceApps, v3 fork (b)): this workspace's own
+  // env.app plus every repo env.gateway lists, each read from its OWN workspace.json.
+  const { apps } = resolveLocalApps(wsConfig);
+  for (const app of apps) {
+    const ms = app.microservice;
+    if (!ms || !ms.port) continue;
     out.push({
-      name: entry.appId,
-      localPath: entry.localPath,
+      name: app.appId,
+      dir: app.dir,
       port: ms.port,
       devCommand: ms.devCommand || null,
-      microserviceDir: path.join(root, entry.localPath, 'microservice')
+      microserviceDir: path.join(app.dir, 'microservice')
     });
-  };
-
-  collect(env.platform);
-  for (const p of (env.products || [])) collect(p);
+  }
   return out;
 }
 
@@ -75,7 +72,7 @@ export function buildRestartRegistry(wsConfig) {
  *
  * @param {WorkspaceConfig} wsConfig
  * @param {string} name
- * @returns {{name, localPath, port, devCommand, microserviceDir}}
+ * @returns {{name, dir, port, devCommand, microserviceDir}}
  */
 export function resolveService(wsConfig, name) {
   const registry = buildRestartRegistry(wsConfig);
@@ -84,24 +81,19 @@ export function resolveService(wsConfig, name) {
   if (matches.length === 0) {
     const candidates = registry.map((s) => s.name).join(', ') || '(none)';
     throw new Error(
-      `Service '${name}' not found in workspace.json env.platform/env.products.\n` +
+      `Service '${name}' is not served by this workspace (env.app / env.gateway).\n` +
       `  Restart-eligible services (with microservice.port + microservice.devCommand): ${candidates}\n` +
       `  Add an entry to .descix/workspace.json or run 'descix microservice list'.`
     );
   }
-  if (matches.length > 1) {
-    throw new Error(
-      `Service name '${name}' is ambiguous — matches ${matches.length} entries: ` +
-      matches.map((m) => `${m.name}@${m.localPath}`).join(', ')
-    );
-  }
-
+  // No ambiguity branch: duplicate app ids are refused upstream by the app-set owner
+  // (resolveWorkspaceApps), so at most one entry can match here.
   const svc = matches[0];
   if (!svc.devCommand) {
     throw new Error(
       `Service '${name}' has no microservice.devCommand in workspace.json — ` +
       `cannot determine canonical launch signature. ` +
-      `Add 'devCommand' under env.products[].microservice to enable restart.`
+      `Add 'devCommand' under env.app.microservice in that app repo's workspace.json to enable restart.`
     );
   }
   return svc;
@@ -173,17 +165,20 @@ export async function killPid(pid, opts = {}) {
 
 /**
  * Resolve the canonical log path for a restart.
- *   apps/<community>/<app>/.descix/logs/<service>-<ts>.log
+ *   <app repo root>/.descix/logs/<service>-<ts>.log
+ * The app repo root is the entry's own `dir` (workspaceApps): under v3 each app lives in its
+ * own repo, so there is no workspace-wide apps/<community>/ tree to hang logs under.
  * Falls back to /tmp/<service>-restart-<ts>.log if the canonical dir
  * cannot be created.
+ *
+ * @param {{name: string, dir: string}} svc - a restart-registry entry
  */
-export async function resolveLogPath(wsConfig, serviceName, opts = {}) {
+export async function resolveLogPath(svc, opts = {}) {
   const deps = opts.deps || {};
   const fsImpl = deps.fs || fs;
   const ts = (opts.timestamp || new Date().toISOString()).replace(/[:.]/g, '-');
-  const root = wsConfig.workspaceRoot;
-  const community = wsConfig.env?.communityId || 'unkamon';
-  const canonicalDir = path.join(root, 'apps', community, serviceName, '.descix', 'logs');
+  const serviceName = svc.name;
+  const canonicalDir = path.join(svc.dir, '.descix', 'logs');
   try {
     await fsImpl.mkdir(canonicalDir, { recursive: true });
     return {
@@ -303,7 +298,7 @@ export async function restartMicroservice(args) {
   }
 
   // Step 2: resolve log path.
-  const logRes = await resolveLogPath(wsConfig, svc.name, { deps });
+  const logRes = await resolveLogPath(svc, { deps });
   if (logRes.fallback) {
     log(chalk.yellow(`  Canonical log dir unavailable (${logRes.fallbackReason}); using ${logRes.path}`));
   } else {