@gluecharm-lab/easyspecs-cli 0.0.27 → 0.1.1

package/dist/main.cjs

@@ -10640,17 +10640,53 @@ var fs62 = __toESM(require("node:fs"));
 var path59 = __toESM(require("node:path"));
 
 // src/cli/exitCodes.ts
+var OsExit = {
+  /** Unknown / unclassified factory failure */
+  factoryUnknown: 49,
+  /** Rollup: multiple failed generate_context phases with distinct OS codes in one run */
+  factoryMultiPhaseRollup: 59,
+  createAnalysisWorktree: 50,
+  materializeOpenCodeAgents: 51,
+  synthesisConvergence: 52,
+  referenceCoverage: 53,
+  zeroReferenceRemediation: 54,
+  referenceCoverageExecutionReport: 55,
+  linkMappingPipeline: 56,
+  assembleApplicationContextIndex: 57,
+  backendContextSync: 58,
+  driftEmptyBundle: 60,
+  driftUnresolvedReferenceRoot: 61,
+  driftManifestFailed: 62,
+  driftReportWriteFailed: 63,
+  driftIndexPatchFailed: 64,
+  diagnoseReferenceCoveragePipeline: 70,
+  diagnoseReferenceCoverageThreshold: 71,
+  diagnoseCoordinationDuplicatesPolicy: 72,
+  diagnoseCoordinationDuplicatesEngine: 73,
+  diagnoseCoverageReport: 74,
+  diagnoseZeroReferenceReadCoverage: 75,
+  diagnoseZeroReferenceLinkMapping: 76,
+  diagnoseZeroReferencePool: 77,
+  contextLinkGraph: 78,
+  resumeSynthesisIndex: 79,
+  runSynthesisPipeline: 80,
+  aceLearnTrace: 81,
+  aceAutoLearnPool: 82,
+  updateContextFactory: 83
+};
 var ExitCode = {
   ok: 0,
   usage: 2,
   misconfiguration: 3,
   opencode: 4,
-  validation: 5,
   auth: 6,
   upload: 7,
   cancelled: 8,
   internal: 99
 };
+function failureExitIdFromParts(exitCode, minor) {
+  return `${String(exitCode)}.${String(minor)}`;
+}
 function describeExitCode(code) {
   switch (code) {
     case ExitCode.ok:
@@ -10661,8 +10697,6 @@ function describeExitCode(code) {
       return "Configuration or repo layout problem \u2014 fix `.easyspecs/config.json`, paths, or prerequisites, then retry.";
     case ExitCode.opencode:
       return "OpenCode (agent runner) failed \u2014 check `opencode` install, credentials, and stderr from the tool run.";
-    case ExitCode.validation:
-      return "Validation or factory pipeline did not succeed \u2014 see `error` above and logs for the failing phase (synthesis, coverage, remediation, index, etc.).";
     case ExitCode.auth:
       return "Authentication failed or session missing \u2014 run `easyspecs-cli auth login` or fix CI credentials in config.";
     case ExitCode.upload:
@@ -10671,6 +10705,66 @@ function describeExitCode(code) {
       return "Operation was cancelled (abort/stop).";
     case ExitCode.internal:
       return "Unexpected internal CLI error \u2014 retry; if it persists, report with full stderr and `--verbose` output.";
+    case OsExit.factoryUnknown:
+      return "Factory pipeline failed (phase could not be classified). See `error` and logs; retry with --verbose.";
+    case OsExit.factoryMultiPhaseRollup:
+      return "Multiple factory pipeline phases failed in one run. Inspect `factoryFailures` for each phase.";
+    case OsExit.createAnalysisWorktree:
+      return "Analysis Git worktree could not be prepared. Check disk space, permissions, and a valid Git checkout.";
+    case OsExit.materializeOpenCodeAgents:
+      return "OpenCode agent files could not be installed into the analysis worktree.";
+    case OsExit.synthesisConvergence:
+      return "Context synthesis did not finish successfully. Inspect OpenCode logs and workstation output.";
+    case OsExit.referenceCoverage:
+      return "Reference coverage could not be computed or written. Check coverage JSON and schema.";
+    case OsExit.zeroReferenceRemediation:
+      return "Zero-reference remediation did not complete. Inspect remediation logs and outputs.";
+    case OsExit.referenceCoverageExecutionReport:
+      return "Coverage execution report could not be generated. Ensure coverage inputs exist.";
+    case OsExit.linkMappingPipeline:
+      return "Context link graph could not be updated. Check coordination JSON and markdown.";
+    case OsExit.assembleApplicationContextIndex:
+      return "Application context index could not be assembled or failed schema validation.";
+    case OsExit.backendContextSync:
+      return "Upload or cloud sync after analysis did not succeed.";
+    case OsExit.driftEmptyBundle:
+      return "Context drift: reference bundle was empty or could not be read.";
+    case OsExit.driftUnresolvedReferenceRoot:
+      return "Context drift: reference root document could not be resolved.";
+    case OsExit.driftManifestFailed:
+      return "Context drift: comparison manifest could not be built.";
+    case OsExit.driftReportWriteFailed:
+      return "Context drift: report markdown could not be written.";
+    case OsExit.driftIndexPatchFailed:
+      return "Context drift: reference index could not be updated with the drift link.";
+    case OsExit.diagnoseReferenceCoveragePipeline:
+      return "diagnose reference-coverage: pipeline or write failed.";
+    case OsExit.diagnoseReferenceCoverageThreshold:
+      return "diagnose reference-coverage: percentNonReferenced exceeded the configured threshold.";
+    case OsExit.diagnoseCoordinationDuplicatesPolicy:
+      return "diagnose coordination-duplicates: strict mode reported duplicates or orphan markdown.";
+    case OsExit.diagnoseCoordinationDuplicatesEngine:
+      return "diagnose coordination-duplicates: scan or I/O failed.";
+    case OsExit.diagnoseCoverageReport:
+      return "diagnose coverage-report: report generation failed.";
+    case OsExit.diagnoseZeroReferenceReadCoverage:
+      return "diagnose zero-reference: could not read coverage / zero-reference inputs.";
+    case OsExit.diagnoseZeroReferenceLinkMapping:
+      return "diagnose zero-reference: link mapping after remediation failed.";
+    case OsExit.diagnoseZeroReferencePool:
+      return "diagnose zero-reference: remediation pool reported failures or cancellation.";
+    case OsExit.contextLinkGraph:
+      return "context link-graph: link mapping pipeline failed.";
+    case OsExit.resumeSynthesisIndex:
+      return "run synthesis resume-*: index assembly after remediation failed.";
+    case OsExit.runSynthesisPipeline:
+      return "run synthesis: pipeline did not complete successfully.";
+    case OsExit.aceLearnTrace:
+      return "ace learn: processing a trace failed.";
+    case OsExit.aceAutoLearnPool:
+      return "ace auto-learn: one or more learn runs failed.";
+    case OsExit.updateContextFactory:
+      return "update context: factory run did not succeed.";
     default:
       return `Non-zero exit (${String(code)}) \u2014 see stderr and any JSON \`error\` field for detail.`;
   }
@@ -10707,7 +10801,7 @@ function createEasyspecsCliProgram() {
   program2.command("help").description("Show help");
   program2.command("version").description("Print CLI version");
   const workstation = program2.command("workstation").description("Host inventory for AI workstation sizing");
-  workstation.command("info").description("Print CPU, RAM, and SRS-64 N_sys (macOS and Linux only; use global --json)").allowUnknownOption(false);
+  workstation.command("info").description("Print CPU, RAM, and SRS-69 N_sys (macOS and Linux only; use global --json)").allowUnknownOption(false);
   program2.command("doctor").description("Check readiness and/or inspect configuration").option("--readiness", "Print readiness summary (default)").option("--inspect-config", "Print redacted merged configuration");
   const auth = program2.command("auth").description("Authentication");
   auth.command("login").description("Log in").option("--email <email>", "Email address").option("--password <password>", "Password").option("--session-path <path>", "Session JSON path override for this run").option("--ci", "Use easyspecs.auth.ciLogin from config when argv credentials are omitted");
@@ -11245,6 +11339,8 @@ var import_node_child_process2 = require("node:child_process");
 var ABSOLUTE_MAX_CONCURRENT_AI = 64;
 
 // src/config/machineConcurrentAiFromHost.ts
+var AGENTS_PER_PHYSICAL_CORE = 1;
+var RAM_GIB_PER_AGENT = 8;
 function clampProductConcurrentLimits(n) {
   if (!Number.isFinite(n)) {
     return DEFAULT_MAX_CONCURRENT_AI;
@@ -11261,13 +11357,9 @@ function machineConcurrentAiCapFromHost(profile) {
   if (!Number.isFinite(rGib) || rGib <= 0) {
     return 1;
   }
-  let nCpuFloat;
-  if (p <= 11) {
-    nCpuFloat = 15 + 8.5 * (p - 1);
-  } else {
-    nCpuFloat = 100 + 8.5 * (p - 11);
-  }
-  const ramFactor = Math.min(1, rGib / (4 * p));
+  const nCpuFloat = AGENTS_PER_PHYSICAL_CORE * p;
+  const ramRefGib = RAM_GIB_PER_AGENT * p;
+  const ramFactor = Math.min(1, rGib / ramRefGib);
   const nFloat = nCpuFloat * ramFactor;
   const rounded = Math.round(nFloat);
   return Math.max(1, rounded);
@@ -21614,9 +21706,19 @@ var FACTORY_PIPELINE_EXIT_CONDITIONS = {
 function factoryFailureDisplayId(row2) {
   return row2.failureExitId;
 }
+function parseMajorFromFailureExitId(id) {
+  const m = /^(\d+)\.\d+$/.exec(id.trim());
+  if (!m) {
+    return void 0;
+  }
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : void 0;
+}
 function normalizeFactoryFailureRow(r) {
-  const failureExitId = r.failureExitId ?? r.validationExitId ?? "5.0";
-  const exitCode = typeof r.exitCode === "number" ? r.exitCode : ExitCode.validation;
+  const failureExitId = r.failureExitId ?? r.validationExitId ?? failureExitIdFromParts(OsExit.factoryUnknown, 0);
+  const exitCodeFromField = typeof r.exitCode === "number" ? r.exitCode : void 0;
+  const exitCodeFromId = parseMajorFromFailureExitId(failureExitId);
+  const exitCode = exitCodeFromField ?? exitCodeFromId ?? OsExit.factoryUnknown;
   const factory = r.factory ?? "generate_context";
   const base = {
     factory,
@@ -21627,10 +21729,7 @@ function normalizeFactoryFailureRow(r) {
     ...typeof r.detail === "string" ? { detail: r.detail } : {},
     ...typeof r.validationSubcode === "string" ? { validationSubcode: r.validationSubcode } : {}
   };
-  if (exitCode === ExitCode.validation) {
-    return { ...base, validationExitId: r.validationExitId ?? failureExitId };
-  }
-  return base;
+  return { ...base, validationExitId: r.validationExitId ?? failureExitId };
 }
 var FACTORY_VALIDATION_PHASE_ORDER = [
   "create_analysis_worktree",
@@ -21646,29 +21745,29 @@ var FACTORY_VALIDATION_PHASE_ORDER = [
 var DETAIL_MAX = 600;
 var ERROR_JOIN_MAX = 900;
 var ADDITIONAL_APPEND_MAX = 200;
-var PHASE_TO_EXIT_ID = {
-  unknown_factory_phase: "5.0",
-  create_analysis_worktree: "5.1",
-  materialize_opencode_agents: "5.2",
-  synthesis_convergence: "5.3",
-  reference_coverage: "5.4",
-  zero_reference_remediation_convergence: "5.5",
-  reference_coverage_execution_report: "5.6",
-  link_mapping_pipeline: "5.7",
-  assemble_application_context_index: "5.8",
-  backend_context_sync: "5.9"
+var PHASE_TO_OS_EXIT = {
+  unknown_factory_phase: OsExit.factoryUnknown,
+  create_analysis_worktree: OsExit.createAnalysisWorktree,
+  materialize_opencode_agents: OsExit.materializeOpenCodeAgents,
+  synthesis_convergence: OsExit.synthesisConvergence,
+  reference_coverage: OsExit.referenceCoverage,
+  zero_reference_remediation_convergence: OsExit.zeroReferenceRemediation,
+  reference_coverage_execution_report: OsExit.referenceCoverageExecutionReport,
+  link_mapping_pipeline: OsExit.linkMappingPipeline,
+  assemble_application_context_index: OsExit.assembleApplicationContextIndex,
+  backend_context_sync: OsExit.backendContextSync
 };
-var EXIT_ID_TITLES = {
-  "5.0": "EasySpecs stopped: the failing pipeline phase could not be identified. Retry with --verbose; report this outcome if it persists.",
-  "5.1": "Could not prepare the analysis Git worktree (temporary checkout). Check disk space, repo permissions, and that the project is a valid Git checkout.",
-  "5.2": "Could not install OpenCode agent files into the analysis worktree. Check bundled extension assets and disk permissions under the worktree path.",
-  "5.3": "Context synthesis did not finish: required context files are still missing or invalid after retries. Inspect OpenCode errors and workstation logs for this phase.",
-  "5.4": "Reference coverage could not be computed or written. Check coverage-reference-validation.json prerequisites and disk/schema errors.",
-  "5.5": "Zero-reference remediation did not complete successfully. Inspect remediation logs and zero-reference outputs for this checkout.",
-  "5.6": "Reference coverage execution report could not be generated. Ensure coverage inputs exist from the coverage phase; see coverage-reference-validation.json.",
-  "5.7": "Context link graph (navigation links) could not be updated. Check coordination JSON and markdown under .gluecharm/context.",
-  "5.8": "Application context index could not be assembled or failed schema validation. Inspect index-application-context.json and preceding context files.",
-  "5.9": "Upload / cloud sync after analysis did not succeed. Check auth, project id, network, and upload error details."
+var TITLE_BY_PHASE = {
+  unknown_factory_phase: "EasySpecs stopped: the failing pipeline phase could not be identified. Retry with --verbose; report this outcome if it persists.",
+  create_analysis_worktree: "Could not prepare the analysis Git worktree (temporary checkout). Check disk space, repo permissions, and that the project is a valid Git checkout.",
+  materialize_opencode_agents: "Could not install OpenCode agent files into the analysis worktree. Check bundled extension assets and disk permissions under the worktree path.",
+  synthesis_convergence: "Context synthesis did not finish: required context files are still missing or invalid after retries. Inspect OpenCode errors and workstation logs for this phase.",
+  reference_coverage: "Reference coverage could not be computed or written. Check coverage-reference-validation.json prerequisites and disk/schema errors.",
+  zero_reference_remediation_convergence: "Zero-reference remediation did not complete successfully. Inspect remediation logs and zero-reference outputs for this checkout.",
+  reference_coverage_execution_report: "Reference coverage execution report could not be generated. Ensure coverage inputs exist from the coverage phase; see coverage-reference-validation.json.",
+  link_mapping_pipeline: "Context link graph (navigation links) could not be updated. Check coordination JSON and markdown under .gluecharm/context.",
+  assemble_application_context_index: "Application context index could not be assembled or failed schema validation. Inspect index-application-context.json and preceding context files.",
+  backend_context_sync: "Upload / cloud sync after analysis did not succeed. Check auth, project id, network, and upload error details."
 };
 var READABLE_PHASE_LABEL = {
   create_analysis_worktree: "Analysis worktree",
@@ -21702,11 +21801,11 @@ function inferValidationSubcode(phase, detail) {
   }
   return void 0;
 }
-function phaseToValidationExitId(phase) {
-  return PHASE_TO_EXIT_ID[phase] ?? "5.0";
+function phaseToSemanticOsExitForGenerateContext(phase) {
+  return PHASE_TO_OS_EXIT[phase] ?? OsExit.factoryUnknown;
 }
-function titleForValidationExitId(validationExitId) {
-  return EXIT_ID_TITLES[validationExitId] ?? EXIT_ID_TITLES["5.0"];
+function titleForGenerateContextPhase(phase) {
+  return TITLE_BY_PHASE[phase] ?? TITLE_BY_PHASE.unknown_factory_phase;
 }
 function readableLabelForFactoryPhase(phase) {
   return READABLE_PHASE_LABEL[phase] ?? phase;
@@ -21715,33 +21814,53 @@ function phaseIndex(key) {
   const i = FACTORY_VALIDATION_PHASE_ORDER.indexOf(key);
   return i >= 0 ? i : 999;
 }
+function finalizeFactoryFailuresForProcessExit(rows) {
+  if (rows.length === 0) {
+    return [];
+  }
+  const candidates = [...new Set(rows.map((r) => r.exitCode))];
+  const processExit = candidates.length > 1 ? OsExit.factoryMultiPhaseRollup : candidates[0] ?? OsExit.factoryUnknown;
+  return rows.map((r, i) => {
+    const minor = processExit === OsExit.factoryMultiPhaseRollup ? i : 0;
+    const fid = failureExitIdFromParts(processExit, minor);
+    return {
+      ...r,
+      exitCode: processExit,
+      failureExitId: fid,
+      validationExitId: fid
+    };
+  });
+}
 function buildFactoryFailuresFromRows(phases) {
   const failed = phases.filter((p) => p.status === "failed");
   failed.sort((a, b) => phaseIndex(a.key) - phaseIndex(b.key));
-  return failed.map((p) => {
-    const id = phaseToValidationExitId(p.key);
+  const semantic = failed.map((p) => {
+    const os7 = phaseToSemanticOsExitForGenerateContext(p.key);
     const sub = inferValidationSubcode(p.key, p.detail);
+    const fid = failureExitIdFromParts(os7, 0);
     return {
       factory: "generate_context",
       phase: p.key,
-      exitCode: ExitCode.validation,
-      failureExitId: id,
-      validationExitId: id,
-      title: titleForValidationExitId(id),
+      exitCode: os7,
+      failureExitId: fid,
+      validationExitId: fid,
+      title: titleForGenerateContextPhase(p.key),
       detail: trimDetail(p.detail),
       ...sub !== void 0 ? { validationSubcode: sub } : {}
     };
   });
+  return finalizeFactoryFailuresForProcessExit(semantic);
 }
 function syntheticUnknownFactoryFailure(message) {
+  const fid = failureExitIdFromParts(OsExit.factoryUnknown, 0);
   return [
     {
       factory: "generate_context",
       phase: "unknown_factory_phase",
-      exitCode: ExitCode.validation,
-      failureExitId: "5.0",
-      validationExitId: "5.0",
-      title: titleForValidationExitId("5.0"),
+      exitCode: OsExit.factoryUnknown,
+      failureExitId: fid,
+      validationExitId: fid,
+      title: titleForGenerateContextPhase("unknown_factory_phase"),
       detail: trimDetail(message)
     }
   ];
@@ -21749,7 +21868,8 @@ function syntheticUnknownFactoryFailure(message) {
 function primaryFailureAliases(failures) {
   const last = failures[failures.length - 1];
   if (!last) {
-    return { failurePhase: "unknown_factory_phase", validationExitId: "5.0" };
+    const fid = failureExitIdFromParts(OsExit.factoryUnknown, 0);
+    return { failurePhase: "unknown_factory_phase", validationExitId: fid };
   }
   return {
     failurePhase: last.phase,
@@ -21769,7 +21889,7 @@ function exitMeaningFromFactoryFailures(failures) {
 function composeFactoryValidationError(orchestratorMessage, failures) {
   const m = orchestratorMessage?.trim() ?? "";
   if (failures.length <= 1) {
-    return m.length > 0 ? m : failures[0]?.title ?? "Validation failed.";
+    return m.length > 0 ? m : failures[0]?.title ?? "Factory pipeline failed.";
   }
   const extraIds = failures.slice(1).map((f) => factoryFailureDisplayId(f)).join(", ");
   let appendix = `(+${String(failures.length - 1)} additional phase failure(s): ${extraIds})`;
@@ -25375,9 +25495,6 @@ function buildFactoryDepsHeadless(input) {
 
 // src/cli/failureExitRegistry.ts
 var DRIFT_FACTORY = "context_drift";
-function failureExitIdFromParts(exitCode, minor) {
-  return `${String(exitCode)}.${String(minor)}`;
-}
 var DRIFT_META = {
   INVALID_REFERENCE_PATH: {
     phase: "resolve_reference_bundle",
@@ -25393,20 +25510,20 @@ var DRIFT_META = {
   },
   EMPTY_BUNDLE: {
     phase: "resolve_reference_bundle",
-    exitCode: ExitCode.validation,
-    minor: 10,
+    exitCode: OsExit.driftEmptyBundle,
+    minor: 0,
     title: "Reference bundle was empty or could not be read for drift analysis."
   },
   UNRESOLVED_REFERENCE_ROOT: {
     phase: "resolve_reference_root",
-    exitCode: ExitCode.validation,
-    minor: 11,
+    exitCode: OsExit.driftUnresolvedReferenceRoot,
+    minor: 0,
     title: "Reference root document could not be resolved. Use --index or ensure an index markdown exists."
   },
   MANIFEST_FAILED: {
     phase: "build_comparison_manifest",
-    exitCode: ExitCode.validation,
-    minor: 12,
+    exitCode: OsExit.driftManifestFailed,
+    minor: 0,
     title: "Comparison manifest could not be built for drift analysis."
   },
   AGENT_FAILED: {
@@ -25423,14 +25540,14 @@ var DRIFT_META = {
   },
   REPORT_WRITE_FAILED: {
     phase: "validate_and_render_report",
-    exitCode: ExitCode.validation,
-    minor: 13,
+    exitCode: OsExit.driftReportWriteFailed,
+    minor: 0,
     title: "Drift report markdown could not be written under the analysis worktree."
   },
   INDEX_PATCH_FAILED: {
     phase: "update_reference_index",
-    exitCode: ExitCode.validation,
-    minor: 14,
+    exitCode: OsExit.driftIndexPatchFailed,
+    minor: 0,
     title: "Reference root markdown could not be updated with the drift report link."
   },
   PROMOTE_FAILED: {
@@ -25486,10 +25603,7 @@ function contextDriftFactoryFailureRow(code, error) {
     title: meta.title,
     detail
   };
-  if (meta.exitCode === ExitCode.validation) {
-    return { ...base, validationExitId: failureExitId };
-  }
-  return base;
+  return { ...base, validationExitId: failureExitId };
 }
 
 // src/cli/factoryValidationStderr.ts
@@ -28397,7 +28511,7 @@ function formatCliStderrLine(line, useAnsi) {
 }
 
 // src/cli/main.ts
-var PKG_VERSION = "0.0.27";
+var PKG_VERSION = "0.1.1";
 function isNonEmptyFactoryFailureArray(x) {
   if (!Array.isArray(x) || x.length === 0) {
     return false;
@@ -28414,6 +28528,12 @@ function isNonEmptyFactoryFailureArray(x) {
   }
   return true;
 }
+function processExitFromNormalizedFactoryFailures(rows) {
+  return rows?.length ? rows[0].exitCode : OsExit.factoryUnknown;
+}
+function isContextDriftSrs70ValidationExit(code) {
+  return code >= OsExit.driftEmptyBundle && code <= OsExit.driftIndexPatchFailed;
+}
 function isEasyspecsConfigReadError(e) {
   return e instanceof EasyspecsConfigInvalidJsonError || e instanceof EasyspecsConfigSchemaError;
 }
@@ -29014,7 +29134,7 @@ async function main() {
         finish(ExitCode.cancelled, { ok: false, error: "Remediation cancelled.", analysisWorktreePath: analysisRoot });
       }
       if (!poolRes.indexOk) {
-        finish(ExitCode.validation, {
+        finish(OsExit.resumeSynthesisIndex, {
           ok: false,
           error: poolRes.indexError ?? "Index failed after remediation.",
           analysisWorktreePath: analysisRoot
@@ -29031,7 +29151,7 @@ async function main() {
         finish(ExitCode.cancelled, { ok: false, error: "Remediation cancelled.", analysisWorktreePath: analysisRoot });
       }
       if (!poolRes.indexOk) {
-        finish(ExitCode.validation, {
+        finish(OsExit.resumeSynthesisIndex, {
           ok: false,
           error: poolRes.indexError ?? "Index failed after remediation.",
           analysisWorktreePath: analysisRoot
@@ -29084,7 +29204,7 @@ async function main() {
             adHocCreatedAtIso: (/* @__PURE__ */ new Date()).toISOString()
           });
         }
-        finish(result.cancelled ? ExitCode.cancelled : ExitCode.validation, {
+        finish(result.cancelled ? ExitCode.cancelled : OsExit.runSynthesisPipeline, {
           ok: false,
           error: result.error ?? "run synthesis failed",
           cancelled: result.cancelled === true,
@@ -29112,14 +29232,14 @@ async function main() {
           const d = res.document;
           const maxPct = repoConfig.easyspecs?.diagnose?.zeroReference?.maxPercentNonReferenced;
           if (maxPct !== null && maxPct !== void 0 && Number.isFinite(maxPct) && d.metrics.percentNonReferenced > maxPct) {
-            finish(ExitCode.validation, {
+            finish(OsExit.diagnoseReferenceCoverageThreshold, {
               ok: false,
               error: `percentNonReferenced ${String(d.metrics.percentNonReferenced)} > ${String(maxPct)}`
             });
           }
           finish(ExitCode.ok, { ok: true, percentNonReferenced: d.metrics.percentNonReferenced });
         } else {
-          finish(ExitCode.validation, { ok: false, error: res.error ?? "coverage failed" });
+          finish(OsExit.diagnoseReferenceCoveragePipeline, { ok: false, error: res.error ?? "coverage failed" });
         }
       }
       if (sub === "coordination-duplicates") {
@@ -29133,7 +29253,7 @@ async function main() {
         if (res.ok) {
           const strict = repoConfig.easyspecs?.diagnose?.coordinationDuplicates?.strict !== false;
           const bad = strict && ((res.groupCount ?? 0) > 0 || (res.orphanMarkdownCount ?? 0) > 0);
-          finish(bad ? ExitCode.validation : ExitCode.ok, {
+          finish(bad ? OsExit.diagnoseCoordinationDuplicatesPolicy : ExitCode.ok, {
             ok: !bad,
             groupCount: res.groupCount,
             orphanMarkdownCount: res.orphanMarkdownCount,
@@ -29143,7 +29263,7 @@ async function main() {
             groupsByList: res.groupsByList
           });
         }
-        finish(ExitCode.validation, { ok: false, error: res.message ?? "duplicates failed" });
+        finish(OsExit.diagnoseCoordinationDuplicatesEngine, { ok: false, error: res.message ?? "duplicates failed" });
       }
       if (sub === "coverage-report") {
         const rootAbs = resolveAnalysisRoot(repoRoot, rootKind, worktree);
@@ -29155,7 +29275,7 @@ async function main() {
         if (rep.ok) {
           finish(ExitCode.ok, { ok: true, reportPath: rep.outputAbsolutePath });
         } else {
-          finish(ExitCode.validation, { ok: false, error: rep.error ?? "report failed" });
+          finish(OsExit.diagnoseCoverageReport, { ok: false, error: rep.error ?? "report failed" });
         }
       }
       if (sub === "missing-artefacts") {
@@ -29185,7 +29305,7 @@ async function main() {
         requireMinimalGluecharmLayoutAt(analysisRoot);
         const cov = readNonReferencedFilesFromRepositoryRoot(analysisRoot);
         if (!cov.ok) {
-          finish(ExitCode.validation, { ok: false, error: cov.error });
+          finish(OsExit.diagnoseZeroReferenceReadCoverage, { ok: false, error: cov.error });
         } else {
           const zrPaths = cov.paths;
           if (zrPaths.length === 0) {
@@ -29214,7 +29334,7 @@ async function main() {
             const ctxDir = path59.join(analysisRoot, ".gluecharm", "context");
             const lg = runLinkMappingPipeline(ctxDir, { log: (line) => logErr(flags, line) });
             if (!lg.ok) {
-              finish(ExitCode.validation, {
+              finish(OsExit.diagnoseZeroReferenceLinkMapping, {
                 ok: false,
                 completed: poolRes.completed,
                 failures: poolRes.failures,
@@ -29224,7 +29344,7 @@ async function main() {
               });
             }
           }
-          finish(bad ? ExitCode.validation : ExitCode.ok, {
+          finish(bad ? OsExit.diagnoseZeroReferencePool : ExitCode.ok, {
             ok: !bad,
             completed: poolRes.completed,
             failures: poolRes.failures,
@@ -29246,7 +29366,7 @@ async function main() {
         log: (line) => logErr(flags, line)
       });
       if (!res.ok) {
-        finish(ExitCode.validation, {
+        finish(OsExit.contextLinkGraph, {
           ok: false,
           contextDir: contextDir2,
           error: res.error,
@@ -29309,7 +29429,7 @@ async function main() {
           factoryFailures: [row2],
           error: composeFactoryValidationError(dres.error, [row2])
         };
-        if (driftExit === ExitCode.validation) {
+        if (isContextDriftSrs70ValidationExit(driftExit)) {
           Object.assign(envelope, primaryFailureAliases([row2]));
         }
         finish(driftExit, envelope);
@@ -29411,7 +29531,10 @@ async function main() {
         Object.assign(analysisEnvelope, primaryFailureAliases(res.factoryFailures));
         analysisEnvelope.error = composeFactoryValidationError(res.message, res.factoryFailures);
       }
-      finish(res.ok ? ExitCode.ok : res.cancelled ? ExitCode.cancelled : ExitCode.validation, analysisEnvelope);
+      finish(
+        res.ok ? ExitCode.ok : res.cancelled ? ExitCode.cancelled : processExitFromNormalizedFactoryFailures(res.factoryFailures),
+        analysisEnvelope
+      );
     }
     if (pos[0] === "update" && pos[1] === "context") {
       for (const a of pos.slice(2)) {
@@ -29439,7 +29562,7 @@ async function main() {
         log: (line) => logErr(flags, line)
       });
       const { exitOk, ...payload } = ures;
-      const code = exitOk ? ExitCode.ok : ures.code === "MISSING_BASELINE" ? ExitCode.usage : ExitCode.validation;
+      const code = exitOk ? ExitCode.ok : ures.code === "MISSING_BASELINE" ? ExitCode.usage : OsExit.updateContextFactory;
       finish(code, payload);
     }
     if (pos[0] === "download" && pos[1] === "context") {
@@ -29702,7 +29825,7 @@ async function main() {
           diagnosticLog: (line) => logErr(flags, line)
         });
         if (!res.ok) {
-          finish(ExitCode.validation, { ok: false, error: res.message });
+          finish(OsExit.aceLearnTrace, { ok: false, error: res.message });
         }
         okCount += 1;
       }
@@ -29728,7 +29851,7 @@ async function main() {
           diagnosticLog: (line) => logErr(flags, line)
         }
       });
-      finish(pool.failed ? ExitCode.validation : ExitCode.ok, {
+      finish(pool.failed ? OsExit.aceAutoLearnPool : ExitCode.ok, {
         ok: pool.failed === 0,
         completed: pool.completed,
         failed: pool.failed,