@sun-asterisk/sungen 3.2.32 → 3.2.34

package/src/cli/commands/dashboard.ts

@@ -11,8 +11,7 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { execSync } from 'child_process';
-import { EnvironmentInfo } from '../../exporters/types';
-import { resolveWebBaseUrl } from '../../exporters/env-qa';
+import { getEnvironment } from '../../exporters/run-environment';
 import {
   buildDashboardSnapshot,
   DashboardTarget,
@@ -37,30 +36,6 @@ const COLOR = {
 
 function log(msg: string): void { console.log(msg); }
 
-function getEnvironment(cwd: string): EnvironmentInfo {
-  let baseURL = '';
-  let projectName = 'chromium';
-  const configPath = path.join(cwd, 'playwright.config.ts');
-  if (fs.existsSync(configPath)) {
-    const c = fs.readFileSync(configPath, 'utf-8');
-    // Both config shapes: legacy literal and env-aware resolveBaseUrl('x') wrapper.
-    const baseMatch = c.match(/baseURL:\s*(?:resolveBaseUrl\(\s*)?['"]([^'"]+)['"]/);
-    if (baseMatch) baseURL = baseMatch[1];
-    const projMatch = c.match(/name:\s*['"]([^'"]+)['"]/);
-    if (projMatch) projectName = projMatch[1];
-  }
-  // Same SUNGEN_BASE_URL override as delivery — the two surfaces must agree.
-  baseURL = resolveWebBaseUrl(cwd, baseURL);
-
-  let executor = process.env.CI_USER || process.env.USER || '';
-  try {
-    const gitUser = execSync('git config user.name', { cwd, encoding: 'utf-8' }).trim();
-    if (gitUser) executor = gitUser;
-  } catch { /* ignore */ }
-
-  return { baseURL, projectName, executor };
-}
-
 interface DashboardOptions {
   noHistory?: boolean;
   open?: boolean;

package/src/cli/commands/delivery.ts

@@ -6,7 +6,6 @@
 import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
-import { execSync } from 'child_process';
 import { parse as parseYaml } from 'yaml';
 import { parseFeatureMetadata } from '../../exporters/feature-parser';
 import { parseSpecFile } from '../../exporters/spec-parser';
@@ -24,9 +23,9 @@ import {
 import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet } from '../../exporters/xlsx-exporter';
 import { loadApiCatalog } from '../../exporters/api-catalog-loader';
 import { resolveApiEnvironment } from '../../exporters/api-environment';
-import { resolveWebBaseUrl } from '../../exporters/env-qa';
+import { getEnvironment, platformOfResultFile, RunEnvironment } from '../../exporters/run-environment';
 import { resolvePlatformAppId } from '../../exporters/mobile-app-id';
-import { scanTestDataSecrets } from '../../harness/secret-scan';
+import { scanTestDataSecrets, formatSecretScan, type SecretScanResult } from '../../harness/secret-scan';
 import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow, ApiCatalogEntry } from '../../exporters/types';
 import { mapFilePath } from '../../exporters/matrix/map-loader';
 import {
@@ -39,7 +38,9 @@ import {
   hasReview,
 } from '../../exporters/matrix/export';
 import { MatrixFinding } from '../../exporters/matrix/types';
+import { ManualCarryReport } from '../../exporters/matrix/carry-manual-results';
 import { formatTestOutcome, resultTotals } from '../../exporters/matrix/result-totals';
+import { readCapabilities } from '../../harness/capability';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -340,34 +341,27 @@ export function hasBlockingMissing(p: PreflightCheck): boolean {
 // Environment
 // ----------------------------------------------------------------------------
 
-function getEnvironment(cwd: string): EnvironmentInfo {
-  let baseURL = '';
-  let projectName = 'chromium';
-  const configPath = path.join(cwd, 'playwright.config.ts');
-  if (fs.existsSync(configPath)) {
-    const c = fs.readFileSync(configPath, 'utf-8');
-    // Both config shapes: the legacy literal `baseURL: 'x'` and the env-aware
-    // `baseURL: resolveBaseUrl('x')` (the quoted value is the static fallback).
-    const baseMatch = c.match(/baseURL:\s*(?:resolveBaseUrl\(\s*)?['"]([^'"]+)['"]/);
-    if (baseMatch) baseURL = baseMatch[1];
-    const projMatch = c.match(/name:\s*['"]([^'"]+)['"]/);
-    if (projMatch) projectName = projMatch[1];
-  }
-  // SUNGEN_BASE_URL (shell > .env.qa.<SUNGEN_ENV> > .env.qa) overrides the static
-  // value — the Test Environment column must show the host the run actually hit.
-  baseURL = resolveWebBaseUrl(cwd, baseURL);
-
-  let executor = process.env.CI_USER || process.env.USER || '';
-  try {
-    const gitUser = execSync('git config user.name', { cwd, encoding: 'utf-8' }).trim();
-    if (gitUser) executor = gitUser;
-  } catch {
-    // ignore
-  }
+/** The unit's path for the Environment column — a flow records it in its page selector. */
+function targetFeaturePath(target: DeliveryTarget, declared: string | undefined, selectorsFile: string): string | undefined {
+  return declared || (target.isFlow ? readFlowPagePath(selectorsFile) : undefined);
+}
 
-  return { baseURL, projectName, executor };
+/**
+ * Executor + environment for the matrix's run-result rows (#850) — resolved exactly as the
+ * legacy workbook resolves them: the API datasource host for an api unit, and on mobile the
+ * app id of the OS the result file came from (`<f>-test-result.<os>[.<env>].json`).
+ */
+function matrixRunEnv(cwd: string, target: DeliveryTarget, env: EnvironmentInfo, paths: MatrixTargetPaths): RunEnvironment {
+  const base = qaDir(cwd, target);
+  let declared: string | undefined;
+  try { declared = parseFeatureMetadata(paths.featureFile).featurePath; } catch { /* loadMatrixModel reports it */ }
+  const featurePath = targetFeaturePath(target, declared, path.join(base, 'selectors', `${target.featureBaseName}.yaml`));
+  const apiEnv = target.kind === 'api' ? resolveApiEnvironment(cwd, loadApiCatalog(cwd, target.kind, target.screen)) : null;
+  const os = platformOfResultFile(paths.resultsPath) ?? process.env.MOBILE_PLATFORM ?? process.env.SUNGEN_ENV;
+  return { ...env, ...(apiEnv ?? {}), featurePath: resolvePlatformAppId(featurePath, os) };
 }
 
+
 /**
  * True when this is a mobile project (`platform: mobile` in qa/capabilities.yaml).
  * Mobile results are written PER-OS (`<feature>-test-result.android|ios.json`) —
@@ -375,14 +369,11 @@ function getEnvironment(cwd: string): EnvironmentInfo {
  * emits one csv+xlsx per OS and skips the (empty/misleading) base aggregate.
  */
 function isMobileProject(cwd: string): boolean {
-  try {
-    const p = path.join(cwd, 'qa', 'capabilities.yaml');
-    if (!fs.existsSync(p)) return false;
-    const parsed = parseYaml(fs.readFileSync(p, 'utf-8')) as { platform?: string } | null;
-    return parsed?.platform === 'mobile';
-  } catch {
-    return false;
-  }
+  // Reads through `readCapabilities` rather than re-parsing the file: the third copy of this parse
+  // was the third place a malformed capabilities.yaml quietly read as "web". The shared reader
+  // reports the breakage once per process; here it still degrades to web, which is the safe
+  // direction (per-OS delivery is skipped, nothing is deleted).
+  return readCapabilities(cwd).platform === 'mobile';
 }
 
 /**
@@ -406,6 +397,18 @@ function removeBaseDeliverables(cwd: string, featureBaseName: string): void {
 // Per-screen export
 // ----------------------------------------------------------------------------
 
+/**
+ * #810 — a manual oracle that lives only in unlabelled `Tester verifies:` prose is exported
+ * verbatim into Expected (never dropped), and the author is told to structure it.
+ */
+function warnUnlabeledManualOracles(label: string, merged: ReturnType<typeof mergeFeatureAndSpec>): void {
+  const hits = merged.filter((m) => m.unlabeledManualOracle);
+  if (!hits.length) return;
+  log(`${COLOR.yellow}⚠ ${label}: manual oracle found only in an unlabeled comment (${hits.length})${COLOR.reset} — exported verbatim into Expected; write it as numbered "N. Observable: …" lines:`);
+  for (const m of hits.slice(0, 10)) log(`    ${m.feature.name.slice(0, 90)}`);
+  if (hits.length > 10) log(`    … and ${hits.length - 10} more`);
+}
+
 async function exportTarget(
   cwd: string,
   target: DeliveryTarget,
@@ -424,14 +427,12 @@ async function exportTarget(
     const spec = parseSpecFile(specFile);
 
     const merged = mergeFeatureAndSpec(feature, spec);
+    warnUnlabeledManualOracles(label, merged);
     // Screens get their URL path from the .feature file directly. Flows record
     // it in selectors/<feature>.yaml under the page-selector block — fall back
     // to that so the Environment column shows a full URL for flows too.
-    let featurePath = feature.featurePath;
     const selectorsFile = path.join(base, 'selectors', `${target.featureBaseName}.yaml`);
-    if (!featurePath && target.isFlow) {
-      featurePath = readFlowPagePath(selectorsFile);
-    }
+    const featurePath = targetFeaturePath(target, feature.featurePath, selectorsFile);
     const selectorKeyMap = loadSelectorKeyMap(selectorsFile);
 
     const specLink = fs.existsSync(specMdFile) ? path.relative(cwd, specMdFile) : '';
@@ -674,8 +675,10 @@ async function exportMatrixTarget(
   cwd: string,
   target: DeliveryTarget,
   opts: { check?: boolean; preview?: boolean; format?: MatrixFormat },
+  env: EnvironmentInfo,
 ): Promise<MatrixRunSummary | 'skipped' | null> {
   const paths = matrixPathsFor(cwd, target);
+  paths.runEnv = matrixRunEnv(cwd, target, env, paths);
 
   // A feature whose scenarios are ALL @exploration probes has nothing to deliver —
   // skip it quietly (no map required) instead of demanding a reviewed grouping for
@@ -736,11 +739,20 @@ async function exportMatrixTarget(
     return null;
   }
 
-  const { csvPath, xlsxPath } = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
+  let deliverables: Awaited<ReturnType<typeof writeMatrixDeliverables>>;
+  try {
+    deliverables = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
+  } catch (e) {
+    // The existing workbook could not be read, so writing would destroy its Manual results.
+    log(`  ${COLOR.red}not written:${COLOR.reset} ${(e as Error).message}`);
+    return null;
+  }
+  const { csvPath, xlsxPath, manualCarry } = deliverables;
   const passed = model.items.reduce((a, i) => a + i.resultCounts.passed, 0);
   const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
   const written = [xlsxPath, csvPath].filter((p): p is string => !!p).map((p) => path.relative(cwd, p));
   for (const rel of written) log(`  ${COLOR.green}→ ${rel}${COLOR.reset}`);
+  if (manualCarry) printManualCarry(manualCarry);
   return {
     label: paths.label,
     items: model.manifest.itemCount,
@@ -751,6 +763,23 @@ async function exportMatrixTarget(
   };
 }
 
+/** What happened to the tester's hand-entered Manual results on this write (#756). */
+function printManualCarry(r: ManualCarryReport): void {
+  const kept = r.carried + r.unchecked;
+  if (kept + r.reset.length + r.notPlaced.length + r.duplicates.length === 0) return;
+  const list = (refs: string[]) => `${refs.slice(0, 4).join(', ')}${refs.length > 4 ? ', …' : ''}`;
+  log(`  Manual results: ${kept} kept${r.unchecked > 0 ? ` (${r.unchecked} without a drift check — the file predates the fingerprint stamp)` : ''}`);
+  if (r.reset.length > 0) {
+    log(`  ${COLOR.yellow}reset to Pending${COLOR.reset} — procedure changed since the result was recorded (${r.reset.length}): ${list(r.reset)}; the previous result is kept in Note`);
+  }
+  if (r.notPlaced.length > 0) {
+    log(`  ${COLOR.yellow}not carried${COLOR.reset} — no matching manual case in the feature any more (${r.notPlaced.length}): ${list(r.notPlaced.map((n) => `${n.ref} was ${n.result}`))}`);
+  }
+  if (r.duplicates.length > 0) {
+    log(`  ${COLOR.yellow}not carried${COLOR.reset} — a second row for the same case; only the first was kept (${r.duplicates.length}): ${list(r.duplicates.map((n) => `${n.ref} was ${n.result}`))}`);
+  }
+}
+
 /**
  * One place that accounts for every target the run did NOT write, so a sweep is
  * never silently partial: scaffolds skipped by preflight and units whose gates /
@@ -934,12 +963,9 @@ export function registerDeliveryCommand(program: Command): void {
         // Deliverables are COMMITTED files; delivery is the last stop before a
         // hardcoded credential lands in one. Same scan `generate` runs.
         const scanDirs = [...new Set(toExport.map((t) => qaDir(cwd, t)))];
-        const secretHits = scanDirs.flatMap((d) => scanTestDataSecrets(d));
-        if (secretHits.length) {
-          log(`\n⚠️  Possible secret(s) in committed test-data (review — do NOT commit real credentials):`);
-          for (const h of secretHits.slice(0, 10)) log(`   ${h.file}:${h.line} — ${h.reason}`);
-          log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.\n`);
-        }
+        const secretScan = scanDirs.map((d) => scanTestDataSecrets(d))
+          .reduce<SecretScanResult>((a, r) => ({ hits: [...a.hits, ...r.hits], unscanned: [...a.unscanned, ...r.unscanned] }), { hits: [], unscanned: [] });
+        for (const line of formatSecretScan(secretScan)) log(line);
 
         // 3. Export
         const legacy = options.legacy || options.full;
@@ -982,10 +1008,11 @@ export function registerDeliveryCommand(program: Command): void {
 
           const matrixSummaries: MatrixRunSummary[] = [];
           const notExported: string[] = [];
+          const env = getEnvironment(cwd);
           for (const target of toExport) {
             const s = await exportMatrixTarget(cwd, target, {
               check: options.check, preview: options.preview, format: format as MatrixFormat,
-            });
+            }, env);
             if (s === 'skipped') continue; // all-@exploration feature — neither exported nor a failure
             if (s) matrixSummaries.push(s);
             else notExported.push(target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName);

package/src/cli/commands/generate.ts

@@ -3,7 +3,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { CodeGenerator } from '../../generators/test-generator/code-generator';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
-import { scanTestDataSecrets } from '../../harness/secret-scan';
+import { scanTestDataSecrets, formatSecretScan, type SecretScanResult } from '../../harness/secret-scan';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities, writeCapabilities, driverMeta, loadDriverCatalog } from '../../harness/capability';
@@ -160,6 +160,17 @@ export function registerGenerateCommand(program: Command): void {
           const cap = readCapabilities(cwd);
           if (cap.platform) {
             platform = cap.platform;
+          } else if (cap.source === 'unreadable') {
+            // The file EXISTS and we failed to parse it. Scaffolding the web default here would
+            // overwrite whatever the user declared — a mobile project's platform, drivers and
+            // verification scope, gone, while the notice claimed the file was missing. Refuse:
+            // the one thing we know is that we do not know what this project is.
+            throw new Error(
+              `qa/capabilities.yaml exists but could not be parsed — fix the YAML and re-run.\n` +
+              `   Refusing to scaffold a default over it: that would discard the platform, drivers ` +
+              `and verification scope it declares.\n` +
+              `   To compile without reading it, pass --framework <web|mobile|…>.`,
+            );
           } else {
             platform = 'web';
             writeCapabilities(cwd, { platform: 'web', enabled: ['web'] });
@@ -225,12 +236,9 @@ export function registerGenerateCommand(program: Command): void {
             if (fs.existsSync(d)) for (const n of fs.readdirSync(d)) scanDirs.push(path.join(d, n));
           }
         }
-        const secretHits = scanDirs.flatMap((d) => scanTestDataSecrets(d));
-        if (secretHits.length) {
-          console.log(`\n⚠️  Possible secret(s) in committed test-data (review — do NOT commit real credentials):`);
-          for (const h of secretHits.slice(0, 10)) console.log(`   ${h.file}:${h.line} — ${h.reason}`);
-          console.log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.`);
-        }
+        const secretScan = scanDirs.map((d) => scanTestDataSecrets(d))
+          .reduce<SecretScanResult>((a, r) => ({ hits: [...a.hits, ...r.hits], unscanned: [...a.unscanned, ...r.unscanned] }), { hits: [], unscanned: [] });
+        for (const line of formatSecretScan(secretScan)) console.log(line);
 
         // Advisory harness sensors (e.g. @cases/@query lint) — run via the Capability SPI,
         // never block generation. Each capability registers its own; the kernel just runs them.

package/src/cli/commands/results-merge.ts

@@ -13,6 +13,7 @@ import { detectReportRoot, sanitizeReportPaths } from '../../exporters/report-pa
 import { registerResultsSanitizeCommand } from './results-sanitize';
 import { resolveResultsPath } from '../../exporters/playwright-report-parser';
 import { parseSpecFile } from '../../exporters/spec-parser';
+import { writeFileAtomic } from '../../harness/write-atomic';
 
 interface MergeCliOptions {
   out?: string;
@@ -38,7 +39,7 @@ function readReport(file: string, label: string): any {
  * (flows → screens → api → api flows); the same basename found in more than one
  * place is an ambiguity error, never a silent pick.
  */
-function resolveFeatureDir(cwd: string, name: string): string {
+export function resolveFeatureDir(cwd: string, name: string): string {
   const roots = [
     path.join(cwd, 'specs', 'generated', 'flows'),
     path.join(cwd, 'specs', 'generated'),
@@ -88,6 +89,12 @@ export function runResultsMerge(baseArg: string | undefined, newArg: string | un
     if (!baseFile || path.dirname(baseFile) !== dir) {
       throw new Error(`results merge: no per-target result file for "${opts.screen}" in ${path.relative(cwd, dir)} — nothing to merge into (a first full run writes it directly).`);
     }
+    // Under SUNGEN_ENV the candidate order falls back to the base-locale file when the env file
+    // does not exist yet; merging a `vi` subset there would overwrite `ja`/base results in silence.
+    const env = process.env.SUNGEN_ENV;
+    if (env && !path.basename(baseFile).endsWith(`.${env}.json`)) {
+      throw new Error(`results merge: SUNGEN_ENV=${env} but "${opts.screen}" has no ${env} result file yet (found ${path.basename(baseFile)}) — run the full ${env} suite first; it writes the file directly.`);
+    }
     // Ghost/foreign-title checks need the CURRENT spec titles.
     const specFile = path.join(dir, `${opts.screen}.spec.ts`);
     try { specTitles = parseSpecFile(specFile).tests.map((t) => t.testTitle); } catch { specTitles = null; }
@@ -125,14 +132,7 @@ export function runResultsMerge(baseArg: string | undefined, newArg: string | un
   // that file is the single source of execution truth for delivery/dashboard.
   // (Same-dir rename = same device; concurrent merges are last-rename-wins.)
   const outFile = opts.out ?? baseFile;
-  const tmp = `${outFile}.tmp-${process.pid}`;
-  try {
-    fs.writeFileSync(tmp, JSON.stringify(merged, null, 2));
-    fs.renameSync(tmp, outFile);
-  } catch (err) {
-    try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort cleanup */ }
-    throw err;
-  }
+  writeFileAtomic(outFile, JSON.stringify(merged, null, 2));
 
   console.log(`✓ merged ${path.basename(newFile)} into ${path.relative(cwd, outFile)} — ${replaced.length} updated, ${added.length} added, ${kept.length} kept`);
   return outFile;

package/src/cli/commands/results-sanitize.ts

@@ -16,6 +16,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import fg from 'fast-glob';
 import { detectReportRoot, sanitizeReportPaths } from '../../exporters/report-path-sanitizer';
+import { writeFileAtomic } from '../../harness/write-atomic';
 
 /** Where a project keeps the JSON files that carry paths. */
 export const DEFAULT_REPORT_GLOBS = [
@@ -50,15 +51,7 @@ export function runResultsSanitize(files: string[] | undefined, cwd: string = pr
     const root = detectReportRoot(doc) ?? nearestProjectRoot(path.dirname(file)) ?? cwd;
     const { doc: clean, rewritten } = sanitizeReportPaths(doc, { root });
     if (rewritten > 0) {
-      // Atomic write, same as `results merge`: a crash mid-write must never leave a truncated report.
-      const tmp = `${file}.tmp-${process.pid}`;
-      try {
-        fs.writeFileSync(tmp, JSON.stringify(clean, null, 2) + (raw.endsWith('\n') ? '\n' : ''));
-        fs.renameSync(tmp, file);
-      } catch (err) {
-        try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort cleanup */ }
-        throw err;
-      }
+      writeFileAtomic(file, JSON.stringify(clean, null, 2) + (raw.endsWith('\n') ? '\n' : ''));
     }
     out.push({ file: path.relative(cwd, file), rewritten });
   }

package/src/cli/commands/select.ts

@@ -0,0 +1,88 @@
+/**
+ * `sungen select` — which tests does a list of test-case IDs name? (#835)
+ *
+ * Backs `run-test --ids`. Like `sungen changed` for `--change-only`, the selection is computed here
+ * so it is deterministic and testable; the workflow only runs it and merges the subset result into
+ * the existing per-feature result file.
+ *
+ * Fails loud: an ID that selects nothing runnable exits non-zero, because a 0-test run reports green.
+ */
+import { Command } from 'commander';
+import * as path from 'path';
+import { findUnitDir } from '../resolve-unit';
+import { loadUnitScenarios } from '../../harness/parse';
+import { parseIdList, selectByIds } from '../../harness/select-by-ids';
+import { resolveFeatureDir } from './results-merge';
+import { readCapabilities } from '../../harness/capability';
+import { projectRootFromScreenDir } from '../../harness/intent';
+
+export function registerSelectCommand(program: Command): void {
+  program
+    .command('select')
+    .description('List the tests a set of test-case IDs selects, grouped per feature (backs run-test --ids)')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api')
+    .requiredOption('--ids <list>', 'Test-case IDs, comma- or space-separated (e.g. VP-UI-001,VP-UI-002)')
+    .option('--json', 'Output the selection as JSON (per feature: spec, ids, titles, grep)')
+    .option('--grep', 'Output ONLY the regex for -g / --mochaOpts.grep (selection must lie in one feature)')
+    .action((options) => {
+      try {
+        const name = options.screen || options.api || options.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        const dir = findUnitDir(name);
+        if (!dir) throw new Error(`Not found: qa/screens|flows|api/${name}`);
+        const ids = parseIdList(options.ids);
+        if (ids.length === 0) throw new Error('--ids is empty — pass at least one test-case ID');
+
+        const cwd = process.cwd();
+        // Same capability set `generate` compiles against: a @requires:<cap> scenario is a skip without it.
+        const enabledCaps = new Set(readCapabilities(projectRootFromScreenDir(path.resolve(dir))).enabled.map((c) => c.toLowerCase()));
+        const selection = selectByIds(loadUnitScenarios(dir, name), ids, name, enabledCaps);
+        // Resolve each feature's compiled spec: a test cannot run before `sungen generate`.
+        const features = selection.features.map((g) => {
+          let spec: string | null = null;
+          try { spec = path.relative(cwd, path.join(resolveFeatureDir(cwd, g.feature), `${g.feature}.spec.ts`)); } catch { /* reported below */ }
+          return { ...g, spec };
+        });
+        const notCompiled = features.filter((f) => !f.spec).map((f) => f.feature);
+        const failed = selection.unknown.length > 0 || selection.notRunnable.length > 0 || notCompiled.length > 0 || features.length === 0;
+
+        if (options.json) {
+          console.log(JSON.stringify({ unit: name, features, unknown: selection.unknown, notRunnable: selection.notRunnable, notCompiled }, null, 2));
+          if (failed) process.exitCode = 1;
+          return;
+        }
+        if (options.grep) {
+          // Only a clean single-feature selection prints a regex; anything else must not be run
+          // as if it were complete, so it prints nothing and exits non-zero.
+          if (failed || features.length !== 1) {
+            console.error(features.length > 1
+              ? `select: the IDs span ${features.length} features (${features.map((f) => f.feature).join(', ')}) — use --json and run each feature on its own.`
+              : 'select: nothing runnable for these IDs — run without --grep to see why.');
+            process.exitCode = 1;
+            return;
+          }
+          console.log(features[0].grep);
+          return;
+        }
+
+        const selected = features.reduce((n, f) => n + f.titles.length, 0);
+        // A @cases scenario expands to one test per dataset row, so this counts scenarios.
+        console.log(`\n  ${selected} scenario(s) selected for ${ids.length} ID(s) in ${name}:\n`);
+        for (const f of features) {
+          console.log(`  ${f.feature} → ${f.spec ?? '(not compiled — run sungen generate first)'}`);
+          for (const t of f.titles) console.log(`    ▶ ${t}`);
+        }
+        for (const u of selection.unknown) {
+          console.log(`  ✗ ${u.id} — no scenario has this ID${u.didYouMean.length ? ` (did you mean ${u.didYouMean.join(', ')}?)` : ''}`);
+        }
+        for (const n of selection.notRunnable) console.log(`  ○ ${n.id} — ${n.reason}`);
+        console.log('');
+        if (failed) process.exitCode = 1;
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/commands/update.ts

@@ -103,6 +103,9 @@ export function registerUpdateCommand(program: Command): void {
         // playwright.config.ts is written once at init and never re-synced — patch the reporter in.
         const { installReportSanitizeReporter } = require('../../orchestrator/report-sanitize-reporter-install');
         installReportSanitizeReporter(process.cwd(), options.dryRun ?? false);
+        // …and move the old `trace: 'on-first-retry'` default, which never records a trace off CI.
+        const { installTraceMode } = require('../../orchestrator/trace-mode-install');
+        installTraceMode(process.cwd(), options.dryRun ?? false);
       } catch (error) {
         console.error('❌ Update failed:', error);
         process.exit(1);

package/src/cli/index.ts

@@ -24,6 +24,7 @@ import { registerIngestCommand } from './commands/ingest';
 import { registerEvalCommand } from './commands/eval';
 import { registerManifestCommand } from './commands/manifest';
 import { registerChangedCommand } from './commands/changed';
+import { registerSelectCommand } from './commands/select';
 import { registerLedgerCommand } from './commands/ledger';
 import { registerFeedbackCommand } from './commands/feedback';
 import { registerQaFeedbackCommand } from './commands/qa-feedback';
@@ -75,6 +76,7 @@ registerSetupMobileEnvCommand(program);
   registerGateCommand(program);
   registerManifestCommand(program);
   registerChangedCommand(program);
+  registerSelectCommand(program);
   registerLedgerCommand(program);
   registerFeedbackCommand(program);
   registerQaFeedbackCommand(program);
@@ -123,12 +125,15 @@ registerSetupMobileEnvCommand(program);
     const opts = actionCommand.opts() as Record<string, unknown>;
     const unit = [opts.screen, opts.flow, opts.area].find((v) => typeof v === 'string' && v)
       ?? (typeof actionCommand.args?.[0] === 'string' ? actionCommand.args[0] : undefined);
-    handBack = { unit: unit as string | undefined, json: opts.json === true };
+    // `--grep` is machine output too: callers capture it with `$(…)`, and a footer on stdout
+    // became part of the regex — the last alternative of `changed --grep` silently matched
+    // nothing, so `--change-only` skipped its last scenario (#836).
+    handBack = { unit: unit as string | undefined, json: opts.json === true || opts.grep === true };
   });
   process.on('exit', (code) => {
     if (!handBack || code === 1) return;
     const line = `\nNext: sungen next${handBack.unit ? ` ${handBack.unit}` : ''}`;
-    // stderr under --json so the hand-back never lands in the parsed payload.
+    // stderr under --json / --grep so the hand-back never lands in the captured payload.
     if (handBack.json) process.stderr.write(`${line}\n`);
     else process.stdout.write(`${line}\n`);
   });

package/src/dashboard/snapshot-builder.ts

@@ -29,6 +29,7 @@ import { resolvePlatformAppId } from '../exporters/mobile-app-id';
 import { discoverLocaleVariants, LocaleVariant } from '../exporters/locale-variants';
 import { getPackageVersion } from '../exporters/package-info';
 import { ApiCatalogEntry, EnvironmentInfo } from '../exporters/types';
+import { readCapabilities } from '../harness/capability';
 import {
   AggregateSummary,
   DashboardSnapshot,
@@ -98,14 +99,11 @@ export function buildDashboardSnapshot(options: BuildSnapshotOptions): Dashboard
  * Mirrors `isMobileProject` in src/cli/commands/delivery.ts.
  */
 function isMobileProject(cwd: string): boolean {
-  try {
-    const p = path.join(cwd, 'qa', 'capabilities.yaml');
-    if (!fs.existsSync(p)) return false;
-    const parsed = parseYaml(fs.readFileSync(p, 'utf-8')) as { platform?: string } | null;
-    return parsed?.platform === 'mobile';
-  } catch {
-    return false;
-  }
+  // Reads through `readCapabilities` rather than re-parsing the file: the third copy of this parse
+  // was the third place a malformed capabilities.yaml quietly read as "web". The shared reader
+  // reports the breakage once per process; here it still degrades to web, which is the safe
+  // direction (per-OS delivery is skipped, nothing is deleted).
+  return readCapabilities(cwd).platform === 'mobile';
 }
 
 function buildOneScreen(