@descix/cli 1.0.6 → 1.0.8

package/lib/commands/corpus.js

@@ -27,7 +27,10 @@ import { WorkspaceConfig } from '../workspace-config.js';
 import { loadManifests } from '../core/ManifestLoader.js';
 import { walkCorpus } from '../core/CorpusWalker.js';
 import { chunkFile, categorizeFile } from '../core/Chunker.js';
-import { upsertChunks, deleteStaleChunks, deleteStaleChunksByFileId, listRemoteFileIds, purgeKbScope } from '../core/Syncer.js';
+import {
+  upsertChunks, deleteStaleChunks, deleteStaleChunksByFileId, listRemoteFileIds, purgeKbScope,
+  isReportedCount, accumulateReportedCount, UNREPORTED_COUNT
+} from '../core/Syncer.js';
 import { lintManifestForDenyClasses, assertNoViolations } from '../core/CorpusDenyLint.js';
 
 /**
@@ -151,6 +154,57 @@ async function chunkCorpusFile(fileEntry, context) {
   }).filter(Boolean);
 }
 
+/**
+ * Read the previously-synced chunk total out of sync state, for REPORTING only.
+ *
+ * Three states must not be conflated:
+ *   no sync state at all      -> 0, a fact about US (we have never synced), not the store
+ *   total_chunks is a number  -> that number, INCLUDING a legitimate 0
+ *   total_chunks null/absent  -> null: UNKNOWN, and said so. It is never coerced to 0.
+ *
+ * The file delta is computed from blob SHAs, never from this number, so an unknown
+ * previous total blocks nothing. The total is re-established on every clean sync by the
+ * store's own live read-back (`liveTotalFromReconcile`), never by arithmetic on it.
+ *
+ * @param {Object|null} previousState - the loaded sync state, or null on first sync
+ * @returns {number|null}
+ */
+export function readPreviousChunkCount(previousState) {
+  if (!previousState) return 0;
+  return Number.isFinite(previousState.total_chunks) ? previousState.total_chunks : null;
+}
+
+/**
+ * The chunk total to PERSIST: the store's MEASURED live count from the post-sync
+ * reconcile (`get_kb_rag_status {reconcile:true}` → `reconcileAfter`), or null when the
+ * store reported none. This is the ONE owner of `total_chunks`.
+ *
+ * Why not previous + upserted − deleted: the server's `kb_sync_chunks` answers
+ * `upserted_count: null` by ruling (Pinecone's upsert API returns no count) and publishes
+ * the measured `rag_vector_count` instead. An arithmetic total built on that null was null
+ * on every sync, including `--rebuild` (measured 2026-09-16: reconcile read 6882 live and
+ * the state still said unknown), so the "re-run with --rebuild" remedy was a loop.
+ *
+ * @param {Object|null|undefined} rec - the reconcile response's message
+ * @returns {number|null}
+ */
+export function liveTotalFromReconcile(rec) {
+  return Number.isFinite(rec?.reconcileAfter) ? rec.reconcileAfter : null;
+}
+
+/**
+ * Render a count for display: the number when the store reported it, otherwise a
+ * phrase that says so. Consumes the module's count owner rather than re-testing
+ * `>= 0` at each call site.
+ *
+ * @param {number} value
+ * @param {string} unknownText
+ * @returns {string}
+ */
+export function renderCount(value, unknownText = 'an unreported number of') {
+  return isReportedCount(value) ? String(value) : unknownText;
+}
+
 /**
  * Save sync state after a successful corpus sync.
  *
@@ -268,15 +322,21 @@ function resolveRef(manifest, cliRef) {
  * @returns {Promise<boolean>}
  */
 async function confirmYesNo(prompt) {
-  const readline = await import('readline');
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise(resolve => {
-    rl.question(`${prompt} [y/N] `, answer => {
-      rl.close();
-      const a = (answer || '').trim().toLowerCase();
-      resolve(a === 'y' || a === 'yes');
-    });
+  // Gated at construction by the ONE owner of "may I prompt". Under a non-TTY this throws a
+  // loud NonInteractiveError instead of hanging (open pipe/FIFO) or resolving nothing (/dev/null).
+  const { createPromptSession } = await import('../interactive.js');
+  const rl = createPromptSession({
+    what: 'descix kb corpus',
+    destructive: true,
+    nonInteractiveForm: ['descix kb corpus ... --yes   # skips this confirmation']
   });
+  try {
+    const answer = await rl.askRaw(`${prompt} [y/N] `);
+    const a = (answer || '').trim().toLowerCase();
+    return a === 'y' || a === 'yes';
+  } finally {
+    rl.close();
+  }
 }
 
 /**
@@ -392,16 +452,13 @@ export async function runCorpusSync(apiClient, options) {
     const missingKbNames = requestedKbNames.filter(name => !registeredKbNames.has(name));
     if (missingKbNames.length > 0) {
       // Hard-fail: every KB we are about to sync into must already be registered in Firestore.
-      // No hardcoded fallback. `app init` is the verb that actually creates a KB on a
-      // git-mode app (init_git_mode_kb, bin/descix.js:1163). `kb create` is Drive-mode
-      // wired (create_skeleton_kb, :2087) and fails here — filed as its own defect.
+      // No hardcoded fallback. `app init --kb` is the verb that creates a KB (init_git_mode_kb).
       spinner.fail(`Unregistered KB(s) for app "${appId}"`);
       throw new Error(
         `KnowledgeBase document(s) missing in Firestore for app "${appId}": ${missingKbNames.join(', ')}.\n` +
         `Registered KBs for this app: ${[...registeredKbNames].join(', ') || '(none)'}.\n` +
         `Syncing vectors into Pinecone without a matching KB doc would orphan them (chat queries hard-fail).\n` +
-        `Fix: run \`descix app init -a ${appId}\` — it creates the KB via init_git_mode_kb and needs no Drive folder.\n` +
-        `(\`descix kb create\` currently routes through create_skeleton_kb and FAILS on a git-mode app.)`
+        `Fix: run \`descix app init -a ${appId} --kb <kb_name>\` for each missing KB — it creates the KB and needs no Drive folder.`
       );
     }
 
@@ -455,9 +512,18 @@ export async function runCorpusSync(apiClient, options) {
 
       // 3a. Walk corpus
       const walkSpinner = ora('  Walking source directories...').start();
-      const { files, commitSha, provenance } = await walkCorpus(manifest, workspaceRoot);
+      const { files, commitSha, provenance, gateBoundary } = await walkCorpus(manifest, workspaceRoot);
       walkSpinner.succeed(`  Found ${files.length} files (commit: ${commitSha.substring(0, 8)})`);
 
+      // A gate prints its own COVERAGE BOUNDARY with its verdict — on GREEN as well as
+      // RED — so the reader of a pass can see where the pass stops without hunting for a
+      // report elsewhere. Every file above cleared the source gate.
+      console.log(chalk.gray(`  [source-gate] PASS — all ${files.length} file(s) tracked by git at their manifest ref.`));
+      console.log(chalk.gray(`  [source-gate] compares: ${gateBoundary.compares}`));
+      console.log(chalk.gray(`  [source-gate] catches: ${gateBoundary.catches}`));
+      console.log(chalk.gray(`  [source-gate] does NOT read: ${gateBoundary.does_not_read}`));
+      console.log(chalk.gray(`  [source-gate] runs automatically: ${gateBoundary.runs_automatically}`));
+
       // ── Deliverable A: --show-walk prints the resolved ref + first 50 files
       // BEFORE any Pinecone read/write so the operator can sanity-check the
       // walk results without trusting downstream output.
@@ -507,9 +573,13 @@ export async function runCorpusSync(apiClient, options) {
           const remote = await listRemoteFileIds(apiClient, appId, kbName);
           rebuildRemoteUniqueCount = remote.unique_count;
           rebuildRemoteTotalChunks = remote.total_chunks;
+          // `Pinecone reports N` is an ATTRIBUTION to the store, so it may only carry
+          // numbers the store actually reported. The file_ids list is always real
+          // (listRemoteFileIds throws rather than fabricating it); the counts may not be.
           rebuildSpinner.succeed(
-            `  [rebuild] Pinecone reports ${remote.unique_count} corpus-scheme file_id(s) / ` +
-            `${remote.total_chunks} enumerable chunk(s) (legacy orphans may exceed this)`
+            `  [rebuild] Pinecone enumerated ${remote.file_ids.length} corpus-scheme file_id(s); ` +
+            `reports ${renderCount(remote.unique_count)} unique / ` +
+            `${renderCount(remote.total_chunks)} enumerable chunk(s) (legacy orphans may exceed this)`
           );
 
           if (options.dryRun) {
@@ -521,9 +591,13 @@ export async function runCorpusSync(apiClient, options) {
             ));
           } else {
             // Interactive confirmation guard. --yes skips for scripting/CI.
+            // A destructive-action prompt must not overstate its own certainty: if the
+            // store reported no count, say so rather than printing "≥-1".
             console.log(chalk.yellow(
               `\n  About to FULL-SCOPE PURGE every vector in ${communityId}/${appId}/${kbName} ` +
-              `(≥${rebuildRemoteTotalChunks} enumerable chunk(s); legacy orphans included), ` +
+              (isReportedCount(rebuildRemoteTotalChunks)
+                ? `(≥${rebuildRemoteTotalChunks} enumerable chunk(s); legacy orphans included), `
+                : `(the store reported no chunk count; ALL vectors in scope will go), `) +
               `then re-upsert the full local walk (${files.length} file(s)).`
             ));
 
@@ -544,9 +618,9 @@ export async function runCorpusSync(apiClient, options) {
               rebuildScopePurged = purgeResult.purged_scope;
               // deleteRAG via filter-based deleteMany returns -1 (count not knowable
               // from the SDK). Surface honestly rather than fabricating a number.
-              rebuildPurged = purgeResult.deleted >= 0 ? purgeResult.deleted : 0;
+              rebuildPurged = purgeResult.deleted;
               purgeSpinner.succeed(
-                purgeResult.deleted >= 0
+                isReportedCount(purgeResult.deleted)
                   ? `  [rebuild] Purged ${purgeResult.deleted} vector(s) (full scope) and reset KB doc rag fields`
                   : `  [rebuild] Purged full scope (filter-based delete; SDK reports no count) and reset KB doc rag fields`
               );
@@ -574,10 +648,10 @@ export async function runCorpusSync(apiClient, options) {
         previousState = null;
       }
       const previousBlobShas = new Set(previousState?.synced_blob_shas || []);
-      const previousChunkCount = previousState?.total_chunks || 0;
+      const previousChunkCount = readPreviousChunkCount(previousState);
 
       if (previousBlobShas.size > 0) {
-        console.log(chalk.gray(`  Previous sync: ${previousBlobShas.size} files, ${previousChunkCount} chunks`));
+        console.log(chalk.gray(`  Previous sync: ${previousBlobShas.size} files, ${previousChunkCount ?? 'an unknown number of'} chunks`));
       } else {
         console.log(chalk.gray('  First sync (no previous state)'));
       }
@@ -640,7 +714,12 @@ export async function runCorpusSync(apiClient, options) {
         console.log(chalk.white(`    Would upsert: ${allChunks.length} chunks from ${newOrChangedFiles.length} file(s)`));
         console.log(chalk.white(`    Would delete (stale-file): ${fileIdsToDelete.length} blob SHA(s)`));
         if (options.rebuild) {
-          console.log(chalk.white(`    Would purge (rebuild): FULL scope ${communityId}/${appId}/${kbName} (≥${rebuildRemoteTotalChunks} enumerable chunks; legacy orphans included)`));
+          console.log(chalk.white(
+            `    Would purge (rebuild): FULL scope ${communityId}/${appId}/${kbName} ` +
+            (isReportedCount(rebuildRemoteTotalChunks)
+              ? `(≥${rebuildRemoteTotalChunks} enumerable chunks; legacy orphans included)`
+              : `(the store reported no chunk count; all vectors in scope)`)
+          ));
         }
         // Track for the summary exit-code computation at the end of the loop.
         totalFilesProcessed += newOrChangedFiles.length;
@@ -648,7 +727,10 @@ export async function runCorpusSync(apiClient, options) {
         totalFilesSkipped += unchangedCount;
         // Full-scope rebuild would purge ≥ the enumerable chunk count. Use it as the
         // would-delete tally so dry-run reports drift whenever a purge would run.
-        totalFilesDeleted += fileIdsToDelete.length + (options.rebuild ? rebuildRemoteTotalChunks : 0);
+        // Only add a rebuild figure the store actually reported; an unknown count
+        // contributes nothing rather than silently subtracting one from the total.
+        totalFilesDeleted += fileIdsToDelete.length +
+          ((options.rebuild && isReportedCount(rebuildRemoteTotalChunks)) ? rebuildRemoteTotalChunks : 0);
         // Do NOT call upsertChunks, deleteStaleChunksByFileId, deleteStaleChunks,
         // or saveSyncState in dry-run. Continue to next manifest.
         continue;
@@ -675,7 +757,9 @@ export async function runCorpusSync(apiClient, options) {
           while (!success && retries < MAX_RETRIES) {
             try {
               const result = await upsertChunks(apiClient, communityId, appId, kbName, batch);
-              upserted += result.upserted;
+              // Unknown-ness survives the running total: one unreportable batch makes
+              // the whole figure unstateable rather than quietly summing around it.
+              upserted = accumulateReportedCount(upserted, result.upserted);
               success = true;
               syncSpinner.text = `  Upserting chunks... ${i + batch.length}/${allChunks.length}`;
             } catch (err) {
@@ -715,7 +799,7 @@ export async function runCorpusSync(apiClient, options) {
           if (!success) {
             syncSpinner.warn(
               `  Batch ${i}-${i + batch.length} did not complete after ${MAX_RETRIES} retries. ` +
-              `Synced ${upserted} chunks so far. This run is BOUNDED (it did not hang) — ` +
+              `Synced ${renderCount(upserted)} chunks so far. This run is BOUNDED (it did not hang) — ` +
               `re-run 'descix kb corpus sync -a ${appId} -k ${kbName}' to RESUME: id-keyed upserts ` +
               `are idempotent so already-synced batches are cheap and the remainder continues.`
             );
@@ -728,7 +812,7 @@ export async function runCorpusSync(apiClient, options) {
           }
         }
 
-        syncSpinner.succeed(`  Upserted: ${upserted} chunks`);
+        syncSpinner.succeed(`  Upserted: ${renderCount(upserted)} chunks`);
 
         // Write failure log to .descix if any batches failed
         if (syncFailures.length > 0) {
@@ -752,59 +836,76 @@ export async function runCorpusSync(apiClient, options) {
           // (community_id, app_id, knowledgebase_name) — guarantees namespace isolation.
           const result = await deleteStaleChunksByFileId(apiClient, communityId, appId, kbName, fileIdsToDelete);
           deleted = result.deleted;
-          deleteSpinner.succeed(`  Purged: ${deleted} chunk(s) across ${fileIdsToDelete.length} stale blob SHA(s)`);
+          deleteSpinner.succeed(
+            `  Purged: ${renderCount(deleted)} chunk(s) across ${fileIdsToDelete.length} stale blob SHA(s)`
+          );
         } catch (err) {
-          deleteSpinner.warn(`  Delete failed: ${err.message}`);
+          // The purge ERRORED: how many were removed is unknown. Leaving `deleted` at 0
+          // would persist "nothing was deleted" into sync state as though it were a fact.
+          deleted = UNREPORTED_COUNT;
+          deleteSpinner.warn(`  Delete failed (deleted count unknown): ${err.message}`);
         }
       }
 
-      // 3f. Save sync state with blob SHAs for future delta computation
-      const allSyncedBlobShas = [...localBlobShas]; // All current files
-      await saveSyncState(appRoot, kbName, {
-        last_sync_commit: commitSha,
-        // Per-source provenance: WHICH repo, at WHICH ref, and the RESOLVED COMMIT SHA actually
-        // synced. `ref` may be a mutable branch, so the ref alone is not a record of what was
-        // synced — the resolved sha is, and it stays exact after the branch moves.
-        sources_provenance: provenance,
-        synced_files_count: files.length,
-        total_chunks: previousChunkCount + upserted - deleted,
-        timestamp: new Date().toISOString(),
-        files_upserted: newOrChangedFiles.length,
-        files_unchanged: unchangedCount,
-        chunks_upserted: upserted,
-        chunks_deleted: deleted,
-        synced_blob_shas: allSyncedBlobShas
-      });
-
-      // 3g. AUTO-RECONCILE the cached rag_vector_count to the TRUE live Pinecone
+      // 3f. AUTO-RECONCILE the cached rag_vector_count to the TRUE live Pinecone
       // count after a COMPLETED, clean sync (no batch failures). This keeps the
       // doctor's fast cached read truthful after every clean run, so drift only
       // ever appears mid-flight (on interruption). Skipped if any batch failed
       // (the run is partial — reconciling would bake in the partial state and the
       // re-run will reconcile once complete). Non-fatal: a reconcile hiccup must
-      // not fail an otherwise-successful sync.
+      // not fail an otherwise-successful sync — but then the persisted total is
+      // null, honestly, because nothing measured it.
+      let liveTotal = null;
       if (syncFailures.length === 0) {
         try {
           const recRes = await apiClient.invoke('get_kb_rag_status', {
             app_id: appId, kb_id: kbName, reconcile: true
           }, { allowGuest: false });
           const rec = recRes.message || recRes;
-          if (rec && typeof rec.reconcileAfter === 'number') {
+          liveTotal = liveTotalFromReconcile(rec);
+          if (liveTotal !== null) {
             const d = rec.reconcileAfter - rec.reconcileBefore;
             console.log(chalk.gray(
               `  ⟳ Reconciled live count: cached ${rec.reconcileBefore} → live ${rec.reconcileAfter}` +
               (d === 0 ? ' (already truthful)' : ` (${d >= 0 ? '+' : ''}${d})`)
             ));
+          } else {
+            console.log(chalk.yellow('  ⚠ Reconcile reported no live count; total_chunks stays unknown'));
           }
         } catch (recErr) {
           console.log(chalk.yellow(`  ⚠ Auto-reconcile skipped (non-fatal): ${recErr.message}`));
         }
       }
 
+      // 3g. Save sync state with blob SHAs for future delta computation
+      const allSyncedBlobShas = [...localBlobShas]; // All current files
+      await saveSyncState(appRoot, kbName, {
+        last_sync_commit: commitSha,
+        // Per-source provenance: WHICH repo, at WHICH ref, and the RESOLVED COMMIT SHA actually
+        // synced. `ref` may be a mutable branch, so the ref alone is not a record of what was
+        // synced — the resolved sha is, and it stays exact after the branch moves.
+        sources_provenance: provenance,
+        synced_files_count: files.length,
+        // The store's measured live count, or null — never a fabricated integer: this file
+        // is read by later runs, so a wrong number here outlives the console line.
+        total_chunks: liveTotal,
+        timestamp: new Date().toISOString(),
+        files_upserted: newOrChangedFiles.length,
+        files_unchanged: unchangedCount,
+        chunks_upserted: isReportedCount(upserted) ? upserted : null,
+        chunks_deleted: isReportedCount(deleted) ? deleted : null,
+        synced_blob_shas: allSyncedBlobShas
+      });
+
       totalFilesProcessed += newOrChangedFiles.length;
-      totalChunksCreated += upserted;
       totalFilesSkipped += unchangedCount;
-      totalFilesDeleted += deleted + rebuildPurged;
+      // A run total is summed by the SAME owner the per-batch total uses (:754), so an
+      // unreported leg leaves the total unstateable instead of quietly summing around it.
+      // Contributing 0 keeps -1 out of the printed total by fabricating a number in its
+      // place — the same untruth, told where nobody can see it.
+      totalChunksCreated = accumulateReportedCount(totalChunksCreated, upserted);
+      totalFilesDeleted = accumulateReportedCount(totalFilesDeleted, deleted);
+      totalFilesDeleted = accumulateReportedCount(totalFilesDeleted, rebuildPurged);
     }
 
     // Summary
@@ -827,13 +928,12 @@ export async function runCorpusSync(apiClient, options) {
 
     console.log(chalk.green('\nCorpus sync complete:'));
     console.log(chalk.white(`  Files synced:    ${totalFilesProcessed}`));
-    console.log(chalk.white(`  Chunks created:  ${totalChunksCreated}`));
+    console.log(chalk.white(`  Chunks created:  ${renderCount(totalChunksCreated)}`));
     console.log(chalk.white(`  Files unchanged: ${totalFilesSkipped}`));
-    if (totalFilesDeleted > 0) {
-      console.log(chalk.white(`  Chunks deleted:  ${totalFilesDeleted}`));
-    } else {
-      console.log(chalk.gray(`  Chunks deleted:  0`));
-    }
+    // Only a zero the store actually REPORTED is dimmed as a no-op; an unreported total
+    // is stated as unknown in full white, never collapsed into the "nothing happened" line.
+    const deletedLine = `  Chunks deleted:  ${renderCount(totalFilesDeleted)}`;
+    console.log(totalFilesDeleted === 0 ? chalk.gray(deletedLine) : chalk.white(deletedLine));
     console.log('');
     return { dryRun: false };
 
@@ -917,7 +1017,11 @@ export async function runCorpusStatus(apiClient, options) {
       console.log(chalk.white(`  Last sync:       ${syncState.timestamp}`));
       console.log(chalk.white(`  Commit:          ${syncState.last_sync_commit?.substring(0, 8) || 'unknown'}`));
       console.log(chalk.white(`  Files tracked:   ${syncState.synced_files_count}`));
-      console.log(chalk.white(`  Chunks in store: ${syncState.total_chunks}`));
+      console.log(chalk.white(
+        `  Chunks in store: ${Number.isFinite(syncState.total_chunks)
+          ? syncState.total_chunks
+          : 'unknown (the last sync reported no live count)'}`
+      ));
 
       // Quick change detection: walk and compare blob SHAs
       if (options.verbose) {

package/lib/commands/health.js

@@ -3,7 +3,12 @@
  *
  * WS-CLI-HEALTH-ENV-PIVOT (2026-05-26):
  *   `descix health --env <env>` pivots the probe surface based on env:
- *     - dev  (default): existing local-port checks (UNCHANGED behavior)
+ *     - dev  (default): BOUND (lsof) AND SERVES (a route probe) per service, plus a gateway
+ *             row from env.gateway.port. A bound port is not a health check: measured
+ *             2026-09-16, a port answering 500 to every request reported PASS, and the
+ *             gateway had no row. A microservice's health path is read from its OWN served
+ *             manifest (`GET /manifest` → service.healthEndpoint — cloud declares
+ *             /api/health, powch /health), never assumed.
  *     - demo: gcloud probes against demo cloud resources + synthetic HTTPS
  *             probes against *.demo.descix.net hosts
  *     - prod: gcloud probes against prod cloud resources + synthetic HTTPS
@@ -28,6 +33,7 @@
 import chalk from 'chalk';
 import { exec } from 'child_process';
 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';
@@ -67,17 +73,22 @@ async function defaultExec(cmd) {
 }
 
 /**
- * Default HTTPS probe. Resolves with { status, error? } — never rejects.
- * Tests replace this with a mock.
+ * Default HTTP(S) probe. Resolves with { status, body, error? } — never rejects.
+ * `insecure` tolerates the workspace's self-signed dev certs and is set ONLY by the DEV
+ * path; cloud probes keep TLS validation. Tests replace this with a mock.
  */
-function defaultHttpsProbe(url, timeoutMs = 8000) {
+function defaultHttpsProbe(url, timeoutMs = 8000, { insecure = false } = {}) {
     return new Promise((resolve) => {
         try {
             const parsed = new URL(url);
             const client = parsed.protocol === 'http:' ? http : https;
-            const req = client.get(url, { timeout: timeoutMs }, (res) => {
-                res.resume();
-                resolve({ status: res.statusCode });
+            const opts = { timeout: timeoutMs };
+            if (insecure && parsed.protocol === 'https:') opts.rejectUnauthorized = false;
+            const req = client.get(url, opts, (res) => {
+                let body = '';
+                res.setEncoding('utf8');
+                res.on('data', (chunk) => { body += chunk; });
+                res.on('end', () => resolve({ status: res.statusCode, body }));
             });
             req.on('error', (err) => resolve({ status: 0, error: err.message }));
             req.on('timeout', () => { req.destroy(); resolve({ status: 0, error: 'timeout' }); });
@@ -90,29 +101,34 @@ function defaultHttpsProbe(url, timeoutMs = 8000) {
 // ─── DEV path (UNCHANGED behavior) ───────────────────────────────────────────
 
 /**
- * Build the service registry from workspace.json for DEV port checks.
- * Returns an array of { name, appId, port, type, protocol? }.
+ * Build the service registry from workspace.json for DEV checks.
+ * Returns an array of { name, appId, port, type, origin }. `origin` — scheme included — comes
+ * from the ONE owner of a local upstream's origin (@descix/app-sdk localOrigin), never a
+ * protocol default re-derived here. The gateway is a row too: it is the process a local platform
+ * developer most needs to see, and it used to be structurally invisible to this command.
  */
 function buildServiceRegistry(wsConfig) {
     const services = [];
     const env = wsConfig.env || {};
 
     if (env.platform) {
+        const name = env.platform.appId || 'platform';
         if (env.platform.microservice?.port) {
             services.push({
-                name: env.platform.appId || 'platform',
+                name,
                 appId: env.platform.appId,
                 port: env.platform.microservice.port,
                 type: 'microservice',
+                origin: localUpstreamOrigin(env.platform.microservice, 'env.platform.microservice'),
             });
         }
         if (env.platform.site?.port) {
             services.push({
-                name: `${env.platform.appId || 'platform'}-site`,
+                name: `${name}-site`,
                 appId: env.platform.appId,
                 port: env.platform.site.port,
                 type: 'site',
-                protocol: env.platform.site.protocol || 'https',
+                origin: localUpstreamOrigin(env.platform.site, 'env.platform.site'),
             });
         }
     }
@@ -124,6 +140,7 @@ function buildServiceRegistry(wsConfig) {
                 appId: product.appId,
                 port: product.microservice.port,
                 type: 'microservice',
+                origin: localUpstreamOrigin(product.microservice, `env.products[${product.appId}].microservice`),
             });
         }
         if (product.site?.port) {
@@ -132,14 +149,82 @@ function buildServiceRegistry(wsConfig) {
                 appId: product.appId,
                 port: product.site.port,
                 type: 'site',
-                protocol: product.site.protocol || 'https',
+                origin: localUpstreamOrigin(product.site, `env.products[${product.appId}].site`),
             });
         }
     }
 
+    // The gateway — port from its ONE owner (resolveGatewayPort: --port > env.gateway.port >
+    // the SDK default), origin from the same owner as every other row.
+    const { port: gatewayPort } = resolveGatewayPort(wsConfig);
+    services.push({
+        name: 'gateway',
+        appId: null,
+        port: gatewayPort,
+        type: 'gateway',
+        origin: localUpstreamOrigin({ port: gatewayPort }, 'env.gateway'),
+    });
+
     return services;
 }
 
+/** What a DEV run reads, and what it does not — printed on green AND red, and carried in JSON. */
+const DEV_PROBE_BOUNDARY =
+    'Probes: bound = lsof on the port; serves = microservices: GET /manifest then GET its ' +
+    'service.healthEndpoint (2xx); sites: GET / (2xx); gateway: GET /__descix/app-binding.json ' +
+    '(a JSON binding, not HTML). Not probed: authentication, any command, credits, the mesh ' +
+    'registration, or the deployed cloud — use --env demo|prod for that.';
+
+/** A JSON body, or null when it is not one (a vite dev server answers 200 HTML for any path). */
+function parseJsonBody(body) {
+    try {
+        const v = JSON.parse(body);
+        return v && typeof v === 'object' ? v : null;
+    } catch {
+        return null;
+    }
+}
+
+const is2xx = (status) => typeof status === 'number' && status >= 200 && status < 300;
+
+/**
+ * DEV mode: does the bound process actually SERVE? Resolves { serves, probe } where `probe` says
+ * exactly what was asked and what came back, so a FAIL line names its own reason.
+ */
+async function checkServesDev(svc, httpsProbeFn) {
+    const opts = { insecure: true };
+    try {
+        if (svc.type === 'microservice') {
+            const m = await httpsProbeFn(`${svc.origin}/manifest`, 8000, opts);
+            if (!is2xx(m.status)) {
+                return { serves: false, probe: `GET /manifest -> ${m.status || m.error || 'unreachable'}` };
+            }
+            const manifest = parseJsonBody(m.body);
+            const healthEndpoint = manifest?.service?.healthEndpoint;
+            if (typeof healthEndpoint !== 'string' || healthEndpoint === '') {
+                return { serves: false, probe: 'GET /manifest -> 200 but it names no service.healthEndpoint' };
+            }
+            const h = await httpsProbeFn(`${svc.origin}${healthEndpoint}`, 8000, opts);
+            return { serves: is2xx(h.status), probe: `GET ${healthEndpoint} -> ${h.status || h.error || 'unreachable'}` };
+        }
+        if (svc.type === 'gateway') {
+            const b = await httpsProbeFn(`${svc.origin}/__descix/app-binding.json`, 8000, opts);
+            const binding = is2xx(b.status) ? parseJsonBody(b.body) : null;
+            const isBinding = !!binding && typeof binding.mode === 'string';
+            return {
+                serves: isBinding,
+                probe: `GET /__descix/app-binding.json -> ${b.status || b.error || 'unreachable'}` +
+                    (is2xx(b.status) && !isBinding ? ' (not a binding: something else is on this port)' : ''),
+            };
+        }
+        // site
+        const s = await httpsProbeFn(`${svc.origin}/`, 8000, opts);
+        return { serves: is2xx(s.status) && !!s.body, probe: `GET / -> ${s.status || s.error || 'unreachable'}` };
+    } catch (err) {
+        return { serves: false, probe: `probe threw: ${err.message}` };
+    }
+}
+
 /**
  * DEV mode: check if a local port is listening (lsof).
  */
@@ -402,16 +487,16 @@ export async function runHealth(options = {}) {
     }
 
     if (env === 'dev') {
-        return runHealthDev(wsConfig, filterName, jsonOutput, execFn);
+        return runHealthDev(wsConfig, filterName, jsonOutput, execFn, httpsProbeFn);
     }
 
     return runHealthCloud(env, wsConfig, filterName, jsonOutput, execFn, httpsProbeFn);
 }
 
 /**
- * DEV path — unchanged from pre-pivot behavior.
+ * DEV path — bound AND serves, per service, plus the gateway.
  */
-async function runHealthDev(wsConfig, filterName, jsonOutput, execFn) {
+async function runHealthDev(wsConfig, filterName, jsonOutput, execFn, httpsProbeFn) {
     let services = buildServiceRegistry(wsConfig);
 
     if (filterName) {
@@ -432,13 +517,20 @@ async function runHealthDev(wsConfig, filterName, jsonOutput, execFn) {
     const results = [];
     const startTime = Date.now();
     for (const svc of services) {
-        const check = await checkPortDev(svc.port, execFn);
+        const bound = (await checkPortDev(svc.port, execFn)).healthy;
+        const { serves, probe } = bound
+            ? await checkServesDev(svc, httpsProbeFn)
+            : { serves: false, probe: 'not bound' };
         results.push({
             service: svc.name,
             appId: svc.appId,
             type: svc.type,
             port: svc.port,
-            ...check,
+            bound,
+            serves,
+            serves_probe: probe,
+            healthy: bound && serves,
+            method: 'port+route',
         });
     }
     const totalTime = Date.now() - startTime;
@@ -447,7 +539,8 @@ async function runHealthDev(wsConfig, filterName, jsonOutput, execFn) {
         environment: 'dev',
         timestamp: new Date().toISOString(),
         check_duration_ms: totalTime,
-        probe_surface: 'local-port',
+        probe_surface: 'local-port+route',
+        probe_boundary: DEV_PROBE_BOUNDARY,
         services: results,
         all_healthy: results.every(r => r.healthy),
         summary: {
@@ -466,10 +559,12 @@ async function runHealthDev(wsConfig, filterName, jsonOutput, execFn) {
     console.log(chalk.cyan('='.repeat(50)));
     console.log(chalk.gray(`  Timestamp: ${output.timestamp}`));
     console.log(chalk.gray(`  Check duration: ${output.check_duration_ms}ms`));
-    console.log(chalk.gray(`  Probe surface: local-port (lsof)\n`));
+    console.log(chalk.gray(`  Probe surface: local-port+route`));
+    console.log(chalk.gray(`  ${DEV_PROBE_BOUNDARY}\n`));
 
     for (const r of results) {
-        const probeDetail = `${r.type}, port:${r.port}`;
+        const yn = (v) => (v ? 'yes' : 'no');
+        const probeDetail = `${r.type}, port:${r.port}, bound:${yn(r.bound)}, serves:${yn(r.serves)}, ${r.serves_probe}`;
         console.log(formatProbeLine(r.service, 'dev', r.healthy, probeDetail));
     }