@sensigo/realm-cli 0.41.0 → 0.43.0

package/dist/commands/validate.js

@@ -1,17 +1,19 @@
 // realm validate <path> — validates a workflow YAML file without registering it.
 //
-// Strictness asymmetry (documented): extension-free workflows validate through the EXACT
-// from-string path used before project extensions existed (byte-identical behavior).
-// Workflows declaring `extensions:` (or validated with --extensions-module) go through
-// file-based loading so extension modules can be resolved, then a SECOND pass validates
-// step `config` against each resolved adapter's `config_schema` (two-pass).
+// ONE admission path (issue #553): `validate <file>` calls the same `loadWorkflowForAdmission`
+// register and watch call — file loader (agent-profile resolution), the unconditional
+// project-extensions pass (modules, manifest, config_schema two-pass), real-then-sentinel
+// secret resolution — so what validate blesses register accepts, and what register refuses
+// validate refuses, by construction. The pre-#553 "strictness asymmetry" (extension-free
+// workflows parsed from string, skipping every file-context check) is gone; `--registered`
+// runs the same rules on the stored copy and supplies-or-declares the context-dependent ones.
 import { Command } from 'commander';
-import { dirname, join, resolve } from 'node:path';
-import { readFileSync } from 'node:fs';
-import { load } from 'js-yaml';
-import { loadWorkflowFromStringWithDiagnostics, loadWorkflowFromFileWithDiagnostics, findTrustRoot, WorkflowError, shouldEnforceTimeout, DEFAULT_EXECUTION_TIMEOUT_SECONDS, resolveSeverity, renderLoaderWarning, assessStructuredOutputEligibility, renderIneligibleMessage, JsonWorkflowStore, RUNTIME_ONLY_WORKFLOW_KEYS, VERSION, } from '@sensigo/realm';
-import { loadProjectExtensions, checkForOrphanedManifests, } from '../extensions/load-project-extensions.js';
-import { renderLoadFailure, renderEscalationLine, printLoaderWarnings, rejectOnErrorSeverity, failsStrict, wrapSentinelWarnings, } from '../lib/loader-warnings.js';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { loadWorkflowFromStringWithDiagnostics, resolveAgentProfiles, WorkflowError, shouldEnforceTimeout, DEFAULT_EXECUTION_TIMEOUT_SECONDS, resolveSeverity, renderLoaderWarning, assessStructuredOutputEligibility, renderIneligibleMessage, JsonWorkflowStore, RUNTIME_ONLY_WORKFLOW_KEYS, VERSION, } from '@sensigo/realm';
+import { renderLoadFailure, renderEscalationLine, printLoaderWarnings, rejectOnErrorSeverity, failsStrict, wrapSentinelWarnings, extensionKeysOf, renderExtensionKeysClause, } from '../lib/loader-warnings.js';
+import { loadWorkflowForAdmission, admitProjectExtensions, ExtensionLoadError, admittedDefinitionOf, } from '../lib/load-workflow-for-admission.js';
+import { CONTEXT_DEPENDENT_CHECKS, notRunReason, renderChecksNotRunLine, } from '../lib/admission-context.js';
 /**
  * Advisory (issue A3, never rejects): an auto step declaring `retry:` but no `timeout_seconds`
  * has EVERY attempt bounded by the generous DEFAULT_EXECUTION_TIMEOUT_SECONDS default — a hung
@@ -56,20 +58,42 @@ export function findRetryWithoutExplicitTimeout(definition) {
  * accumulator turns the summary line into a failing one and returns true (the caller exits 1);
  * otherwise the summary line — and, when present, the description line existing tests assert on
  * — print exactly as before and this returns false.
+ *
+ * `checksNotRun` (issue #553 correction C9, default 0 — the file-mode call site never passes it,
+ * since every check runs there) adds the FIRST tail clause when non-zero: `N check(s) not run`.
+ * There is no non-strict `— N warning(s)` tail today and this does not invent one — a
+ * warnings-bearing run without `--strict` and without a not-run count still prints the bare line,
+ * warnings above it. The failing-`--strict` clause, when both fire, comes SECOND, `; `-joined
+ * with the not-run clause — `— N check(s) not run; M warning(s); failing due to --strict` — and
+ * the description-suppression rule is UNCHANGED: only a failing `--strict` suppresses it, not a
+ * bare not-run disclosure (a moved tree is not a reason to hide the workflow's own description).
+ *
+ * `extensionKeys` (issue #559, default `[]`) adds a SECOND tail clause, between the not-run
+ * clause and the strict clause, naming every top-level `x-` key the definition carries — the
+ * accepted-but-unread namespace mints no warning of its own, so this is the only disclosure an
+ * author who believed `x-timeout` configured something gets.
  */
-function printValidationOutcome(definition, warnings, strict) {
+function printValidationOutcome(definition, warnings, strict, checksNotRun = 0, extensionKeys = []) {
     printLoaderWarnings(warnings);
     const stepCount = Object.keys(definition.steps).length;
     const base = `Valid: ${definition.id} v${definition.version} (${stepCount} ${stepCount === 1 ? 'step' : 'steps'})`;
-    if (strict && failsStrict(warnings)) {
-        console.log(`${base} — ${warnings.length} ${warnings.length === 1 ? 'warning' : 'warnings'}; failing due to --strict`);
-        return true;
+    const strictFailing = strict && failsStrict(warnings);
+    const clauses = [];
+    if (checksNotRun > 0) {
+        clauses.push(`${checksNotRun} ${checksNotRun === 1 ? 'check' : 'checks'} not run`);
+    }
+    const extensionClause = renderExtensionKeysClause(extensionKeys);
+    if (extensionClause !== undefined) {
+        clauses.push(extensionClause);
     }
-    console.log(base);
-    if (definition.description !== undefined) {
+    if (strictFailing) {
+        clauses.push(`${warnings.length} ${warnings.length === 1 ? 'warning' : 'warnings'}; failing due to --strict`);
+    }
+    console.log(clauses.length > 0 ? `${base} — ${clauses.join('; ')}` : base);
+    if (!strictFailing && definition.description !== undefined) {
         console.log(`  ${definition.description}`);
     }
-    return false;
+    return strictFailing;
 }
 /** issue #236: the reasoning-position heuristic (design record §7, ratified via fixture C6) —
  *  top-level property NAME match only, never a value/content inspection. */
@@ -105,6 +129,9 @@ function findReasoningLikeTopLevelProperty(schema) {
  *
  * Never printed for an ineligible-and-opted-in step: the LOADER already rejected that combination
  * at load time, so this function structurally never observes it.
+ *
+ * issue #454: this whole channel is suppressed under `--json` — a caller checking
+ * `opts.json` never calls this at all; there is no machinery for it here.
  */
 function printStructuredOutputNudge(definition, opts) {
     // Not-opted-in steps whose detail either renders (--explain) or feeds the summary counts.
@@ -214,6 +241,50 @@ function renderNudgeSummary(ready, withCaveats, oneAway) {
         line += `, ${oneAway} ${steps(oneAway)} one change away`;
     return line + tail;
 }
+/**
+ * issue #454 — the severity `--json` reports for every diagnostic. Every mint site in the tree
+ * ALREADY resolves severity at construction (`severity: resolveSeverity(code)`,
+ * diagnostics.ts:239 and its siblings, under DEFAULT_POLICY — never the `--strict` all-error
+ * policy, which is a run mode reported separately in the `strict` block) — so minted ≡ effective
+ * for every constructible diagnostic today, and this re-resolution is a GUARD against a future
+ * mint or a policy change landing without updating this file, not a live divergence. No real
+ * fixture can distinguish the two; only a hand-constructed lying warning can (validate-json.test.ts's
+ * U1 cell).
+ * @internal Exported for testing only.
+ */
+export function normalizeDiagnosticSeverity(w) {
+    return { ...w, severity: resolveSeverity(w.code) };
+}
+/**
+ * The ONE `--json` emission point (issue #454): every contract arm builds a `ValidateJsonEmit`
+ * and calls this, so the machine channel cannot drift arm-to-arm the way independently-written
+ * `JSON.stringify` call sites could. One `console.log` carrying the whole object is itself the
+ * purity guarantee this surface's cells assert on (nothing else may write to stdout on a
+ * contract arm) — `JSON.stringify(obj, null, 2)`, the `workflow list --json` sibling's own idiom.
+ */
+function emitValidateJson(result) {
+    console.log(JSON.stringify({
+        valid: result.valid,
+        mode: result.mode,
+        path: result.path,
+        workflow_id: result.workflowId,
+        loader_version: VERSION,
+        schema_version: result.schemaVersion,
+        error_count: result.errors.length,
+        warning_count: result.diagnostics.length,
+        strict: { requested: result.strictRequested, failed: result.strictFailed },
+        diagnostics: result.diagnostics.map(normalizeDiagnosticSeverity),
+        errors: result.errors,
+        checks_not_run: result.checksNotRun,
+        extension_keys: result.extensionKeys,
+    }, null, 2));
+}
+/** issue #454 — the shared `err.warnings ?? []` shape four `--json` load-failure sites need
+ *  (:527, :580, :621, :423 in the pre-#454 line numbering) — everywhere EXCEPT the orphan-guard
+ *  site (:548), whose diagnostics are the human loop's own accumulated set, not `err.warnings`. */
+function warningsOf(err) {
+    return err instanceof WorkflowError ? (err.warnings ?? []) : [];
+}
 /**
  * The ONE place a load failure is rendered on this command (issue #445).
  *
@@ -230,9 +301,30 @@ function renderNudgeSummary(ready, withCaveats, oneAway) {
  * SCOPE, deliberate: watch/register/test/agent keep their own catches (#425's recorded
  * exclusion). If a second surface ever adopts this, move it to lib/loader-warnings.ts — one
  * caller does not earn a shared home.
+ *
+ * issue #454 — `jsonCtx`, when present, means `--json` was requested: the `errors[]` convention
+ * there is the RAW `err.errors ?? [err.message]` (channel prefixes like `Error: `/`Invalid: `
+ * are print-time decoration this never applied in the first place — nothing to strip), never the
+ * human-rendered `renderLoadFailure(err)` string.
  */
-function exitOnLoadFailure(err) {
+function exitOnLoadFailure(err, jsonCtx) {
     if (err instanceof WorkflowError) {
+        if (jsonCtx !== undefined) {
+            emitValidateJson({
+                valid: false,
+                mode: jsonCtx.mode,
+                path: jsonCtx.path,
+                workflowId: jsonCtx.workflowId,
+                schemaVersion: jsonCtx.schemaVersion,
+                strictRequested: jsonCtx.strictRequested,
+                strictFailed: false,
+                diagnostics: jsonCtx.diagnostics,
+                errors: err.errors ?? [err.message],
+                checksNotRun: jsonCtx.checksNotRun,
+                extensionKeys: [],
+            });
+            process.exit(1);
+        }
         if (err.warnings !== undefined)
             printLoaderWarnings(err.warnings);
         console.error(renderLoadFailure(err));
@@ -256,25 +348,12 @@ function rejectIfPolicyEscalates(warnings) {
     //
     // register and watch print the same line since issue #451 (watch adds its timestamp and a
     // `— refusing to register.` tail, because it does not exit); it lives in lib/loader-warnings.ts
-    // for that reason. On all three surfaces printLoaderWarnings' `— REFUSED below` substitution
-    // already marks each refused warning one line above.
+    // for that reason. On all three surfaces the warnings printed one line above still read
+    // `— ignored` (issue #540 deleted the CLI's print-time rewrite to `— REFUSED below`) — this
+    // line is where the refusal, and WHICH warning triggered it, actually gets said.
     console.error(renderEscalationLine(warnings));
     return true;
 }
-/** Pre-scan: does the YAML carry a top-level `extensions` key? (Parse errors → false; the
- *  real loader below reports them with its existing error surface.) */
-function hasTopLevelExtensions(content) {
-    try {
-        const raw = load(content);
-        return (typeof raw === 'object' &&
-            raw !== null &&
-            !Array.isArray(raw) &&
-            'extensions' in raw);
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * `validate --registered <id>` — audit the STORED copy of a workflow (issue #427).
  *
@@ -289,7 +368,7 @@ function hasTopLevelExtensions(content) {
  * change what your runs do. A legacy (schema_version-less or older) copy is a different case
  * entirely — see the legacy arm below: it is not grandfathered, it is already unreachable.
  */
-async function validateRegistered(id, strict) {
+async function validateRegistered(id, strict, json, overrideModule) {
     const store = new JsonWorkflowStore();
     let stored;
     try {
@@ -297,6 +376,22 @@ async function validateRegistered(id, strict) {
     }
     catch (err) {
         if (err instanceof WorkflowError && err.code === 'STATE_WORKFLOW_NOT_FOUND') {
+            if (json) {
+                emitValidateJson({
+                    valid: false,
+                    mode: 'registered',
+                    path: null,
+                    workflowId: id,
+                    schemaVersion: null,
+                    strictRequested: strict,
+                    strictFailed: false,
+                    diagnostics: [],
+                    errors: [err.message],
+                    checksNotRun: [],
+                    extensionKeys: [],
+                });
+                process.exit(1);
+            }
             console.error(`Error: ${err.message}`);
             console.error('Registered workflows: realm workflow list');
             process.exit(1);
@@ -307,6 +402,22 @@ async function validateRegistered(id, strict) {
             // consumer resolves through this same get() gate (start_run, execute_step, append_trace,
             // get_workflow_protocol, submit_human_response, replay), so a legacy entry cannot run at
             // all. It is not grandfathered; it is unreachable.
+            if (json) {
+                emitValidateJson({
+                    valid: false,
+                    mode: 'registered',
+                    path: null,
+                    workflowId: id,
+                    schemaVersion: null,
+                    strictRequested: strict,
+                    strictFailed: false,
+                    diagnostics: [],
+                    errors: [err.message],
+                    checksNotRun: [],
+                    extensionKeys: [],
+                });
+                process.exit(1);
+            }
             console.log(`Auditing the registered copy of '${id}' with realm ${VERSION}'s loader.`);
             // The store's own message carries the remedy; the loader would say `Missing required
             // field: 'steps'` here, which is true of the shape and useless about the cause.
@@ -316,44 +427,216 @@ async function validateRegistered(id, strict) {
         if (!(err instanceof WorkflowError)) {
             // get()'s try wraps ONLY the read — JSON.parse sits outside it, so a corrupt stored file
             // arrives here as a bare SyntaxError with no code (executed).
-            console.error(`Error: the registered copy of '${id}' is not parseable JSON: ${err instanceof Error ? err.message : String(err)}`);
+            const notParseableMsg = `the registered copy of '${id}' is not parseable JSON: ${err instanceof Error ? err.message : String(err)}`;
+            if (json) {
+                emitValidateJson({
+                    valid: false,
+                    mode: 'registered',
+                    path: null,
+                    workflowId: id,
+                    schemaVersion: null,
+                    strictRequested: strict,
+                    strictFailed: false,
+                    diagnostics: [],
+                    errors: [notParseableMsg],
+                    checksNotRun: [],
+                    extensionKeys: [],
+                });
+                process.exit(1);
+            }
+            console.error(`Error: ${notParseableMsg}`);
             console.error('Registered workflows: realm workflow list');
             process.exit(1);
         }
         throw err; // #123: an unexpected WorkflowError is a bug, and bugs stay loud.
     }
-    console.log(`Auditing the registered copy of '${id}' (schema_version ${String(stored.schema_version)}) ` +
-        `with realm ${VERSION}'s loader.`);
-    console.log('Registered copies stay grandfathered at runtime — this reports what re-registration today would say.');
+    if (!json) {
+        console.log(`Auditing the registered copy of '${id}' (schema_version ${String(stored.schema_version)}) ` +
+            `with realm ${VERSION}'s loader.`);
+        console.log('Registered copies stay grandfathered at runtime against LOADER changes — this reports ' +
+            'what re-registration today would say. A NEW engine-side dispatch check (issue #508, ' +
+            'realm 0.42.0) is NOT grandfathered: it applies immediately, whatever schema_version ' +
+            'is on file.');
+    }
+    // issue #553 — read the recorded context BEFORE the strip: these are the paths the
+    // context-dependent checks are supplied with (the file loader stamps both since v0.14;
+    // older copies carry neither, and say so below).
+    const recorded = {
+        source_dir: typeof stored.source_dir === 'string' ? stored.source_dir : undefined,
+        trust_root: typeof stored.trust_root === 'string' ? stored.trust_root : undefined,
+    };
+    const storedExtensions = stored.extensions;
     const clone = { ...stored };
     for (const key of RUNTIME_ONLY_WORKFLOW_KEYS)
         delete clone[key];
-    const declaresProfile = Object.values(stored.steps ?? {}).some((step) => step.agent_profile !== undefined);
-    if (clone['extensions'] !== undefined || declaresProfile) {
-        console.log('Extensions/profiles declared — module resolution, config_schema checks, and agent-profile ' +
-            'file resolution need the source tree and are not audited here; structural rules only.');
-    }
     // MUST delete: the from-string loader hard-throws on an `extensions` key (allowExtensions:
     // false) with "Register this workflow from its YAML file" — maximally misleading here, where
-    // the workflow IS registered and the operator asked about the stored copy. The honesty line
-    // above is what carries the real limitation.
+    // the workflow IS registered and the operator asked about the stored copy. The declared
+    // modules are re-attached to the parsed definition below, for the extensions pass that
+    // actually consumes them.
     delete clone['extensions'];
+    const stripped = JSON.stringify(clone);
+    // Supply or declare (issue #553): per member of CONTEXT_DEPENDENT_CHECKS, either the recorded
+    // path still exists and the check RUNS with it, or the check is declared not run — here, on
+    // the human line, and in `checks_not_run` on every `--json` arm from this point.
+    const notRun = [];
+    const registeredCtx = (workflowId, diagnostics) => ({
+        mode: 'registered',
+        path: null,
+        workflowId,
+        schemaVersion: stored.schema_version ?? null,
+        diagnostics,
+        strictRequested: strict,
+        checksNotRun: notRun,
+    });
     let definition;
     let loaderWarnings;
     try {
-        ({ definition, warnings: loaderWarnings } = loadWorkflowFromStringWithDiagnostics(JSON.stringify(clone)));
+        // After #553 the four context-free rules (context_wrapper, the workflow_context names,
+        // source.path) run here too — the string loader carries them. No `(line N)`: the body is
+        // JSON, not the author's file.
+        ({ definition, warnings: loaderWarnings } = loadWorkflowFromStringWithDiagnostics(stripped));
     }
     catch (err) {
-        exitOnLoadFailure(err);
+        exitOnLoadFailure(err, json ? registeredCtx(id, warningsOf(err)) : undefined);
+    }
+    const applicable = CONTEXT_DEPENDENT_CHECKS.filter((check) => check.applies(definition));
+    for (const check of applicable) {
+        const path = recorded[check.needs];
+        // `existsSync` is load-bearing for BOTH members: `resolveAgentProfiles` against a dead
+        // tree would name a path under the missing tree (the WRONG error), and
+        // `admitProjectExtensions` against a nonexistent trust root returns defaults SILENTLY
+        // (executed) — a copy whose tree moved would audit as if it had no manifest at all.
+        if (path === undefined || !existsSync(path)) {
+            const reason = notRunReason(check.needs, path, stored.origin);
+            // issue #553 correction C5 — the extensions member cannot apply an override it never
+            // reaches: say so beside the reason, never silently, on the human line AND
+            // `checks_not_run[].reason` alike, so 7c's label+reason parity holds by construction.
+            notRun.push({
+                id: check.id,
+                reason: check.id === 'project_extensions' && overrideModule !== undefined
+                    ? `${reason}; --extensions-module not applied`
+                    : reason,
+            });
+        }
+    }
+    // The disclosure line — always on, never verbose-gated, the old honesty line's slot: after
+    // the header, before any verdict. Derived from the constant; nothing hand-typed. A non-empty
+    // set does NOT flip `--strict`: a disclosure, not a warning — a moved tree must not fail CI
+    // for a reason the operator cannot act on.
+    if (!json && notRun.length > 0)
+        console.log(renderChecksNotRunLine(notRun));
+    let sentinelWarnings;
+    for (const check of applicable) {
+        if (notRun.some((n) => n.id === check.id))
+            continue;
+        if (check.id === 'agent_profile_resolution') {
+            try {
+                resolveAgentProfiles(definition, recorded.source_dir);
+            }
+            catch (err) {
+                exitOnLoadFailure(err, json ? registeredCtx(definition.id, loaderWarnings) : undefined);
+            }
+        }
+        else {
+            // The extensions pass exactly as loadWorkflowForAdmission runs it — ONE shared call
+            // (issue #553 correction C2: `admitProjectExtensions` is now the single mint site for the
+            // sentinel-credentials advisory pair, replacing this arm's own hand-typed copy) — against
+            // the RECORDED paths, re-stamped on the parsed copy (the strip removed them).
+            if (recorded.source_dir !== undefined)
+                definition.source_dir = recorded.source_dir;
+            definition.trust_root = recorded.trust_root; // the member ran ⇒ recorded and present
+            if (storedExtensions !== undefined)
+                definition.extensions = storedExtensions;
+            let loaded;
+            try {
+                loaded = await admitProjectExtensions(definition, {
+                    surface: 'validate',
+                    ...(overrideModule !== undefined ? { overrideModule } : {}),
+                });
+            }
+            catch (err) {
+                // issue #445's sentence, issue #454's whole-message convention, issue #463's
+                // warnings-first — the file arm's shape, on the stored copy.
+                const accumulated = [...loaderWarnings, ...findRetryWithoutExplicitTimeout(definition)];
+                const msg = `Error loading extensions: ${err instanceof Error ? err.message : String(err)}`;
+                if (json) {
+                    emitValidateJson({
+                        valid: false,
+                        mode: 'registered',
+                        path: null,
+                        workflowId: definition.id,
+                        schemaVersion: stored.schema_version ?? null,
+                        strictRequested: strict,
+                        strictFailed: false,
+                        diagnostics: accumulated,
+                        errors: [msg],
+                        checksNotRun: notRun,
+                        extensionKeys: [],
+                    });
+                    process.exit(1);
+                }
+                for (const w of accumulated)
+                    console.warn(renderLoaderWarning(w));
+                console.error(msg);
+                process.exit(1);
+            }
+            sentinelWarnings = loaded.sentinelWarnings;
+            try {
+                loadWorkflowFromStringWithDiagnostics(stripped, loaded.registry);
+            }
+            catch (err) {
+                exitOnLoadFailure(err, json ? registeredCtx(definition.id, warningsOf(err)) : undefined);
+            }
+        }
+    }
+    // The file arm's tail, minus the adoption nudge (a stored copy is not where you edit;
+    // `--explain` is therefore inert in this mode, deliberately — no machinery for it).
+    const accumulated = [
+        ...loaderWarnings,
+        ...findRetryWithoutExplicitTimeout(definition),
+        ...wrapSentinelWarnings(sentinelWarnings),
+    ];
+    if (json) {
+        if (rejectOnErrorSeverity(accumulated)) {
+            emitValidateJson({
+                valid: false,
+                mode: 'registered',
+                path: null,
+                workflowId: definition.id,
+                schemaVersion: stored.schema_version ?? null,
+                strictRequested: strict,
+                strictFailed: false,
+                diagnostics: accumulated,
+                errors: [renderEscalationLine(accumulated)],
+                checksNotRun: notRun,
+                extensionKeys: [],
+            });
+            process.exit(1);
+        }
+        const strictFailed = strict && failsStrict(accumulated);
+        emitValidateJson({
+            valid: true,
+            mode: 'registered',
+            path: null,
+            workflowId: definition.id,
+            schemaVersion: stored.schema_version ?? null,
+            strictRequested: strict,
+            strictFailed,
+            diagnostics: accumulated,
+            errors: [],
+            checksNotRun: notRun,
+            extensionKeys: extensionKeysOf(definition),
+        });
+        if (strictFailed) {
+            process.exit(1);
+        }
+        return;
     }
-    // The extension-free arm's tail, minus the orphan-manifest check (there is no source tree to
-    // have one) and minus the adoption nudge (a stored copy is not where you edit; `--explain` is
-    // therefore inert in this mode, deliberately — no machinery for it).
-    const accumulated = [...loaderWarnings, ...findRetryWithoutExplicitTimeout(definition)];
     if (rejectIfPolicyEscalates(accumulated)) {
         process.exit(1);
     }
-    const strictFailed = printValidationOutcome(definition, accumulated, strict);
+    const strictFailed = printValidationOutcome(definition, accumulated, strict, notRun.length, extensionKeysOf(definition));
     if (strictFailed) {
         process.exit(1);
     }
@@ -364,15 +647,20 @@ export const validateCommand = new Command('validate')
     .option('--extensions-module <path>', "Extensions module that REPLACES the workflow's declared 'extensions' modules (repair/override)")
     .option('--strict', 'Exit non-zero if any loader warning is present (unknown keys, retry-without-timeout, sentinel credentials — issue #169)')
     .option('--explain', 'Print the full per-step structured_output adoption detail instead of the one-line summary the default run prints (issue #422)')
+    .option('--json', 'Emit the result as JSON on stdout, and nothing else')
     .description('Validate a workflow YAML file')
     .action(async (inputPath, opts) => {
     const strict = opts.strict === true;
     const explain = opts.explain === true;
+    const json = opts.json === true;
     // Exactly-one, checked FIRST and load-bearing: commander parses a `[path]` positional and
     // a `--registered <id>` option happily together and enforces nothing between them
     // (executed — both arrive). The flag is `--registered <id>` rather than an auto-detecting
     // positional deliberately: nothing can reliably tell an id from a path, and guessing wrong
     // means auditing something the operator did not name.
+    //
+    // issue #454: NOT under the contract — these two usage errors precede validation entirely
+    // (terraform-consistent) and stay human + exit 1 regardless of `--json`.
     if (inputPath === undefined && opts.registered === undefined) {
         console.error('Error: provide a workflow path, or --registered <id> to audit a stored definition.');
         process.exit(1);
@@ -384,142 +672,128 @@ export const validateCommand = new Command('validate')
         return;
     }
     if (opts.registered !== undefined) {
-        await validateRegistered(opts.registered, strict);
+        await validateRegistered(opts.registered, strict, json, opts.extensionsModule);
         return;
     }
     const filePath = inputPath.endsWith('.yaml') || inputPath.endsWith('.yml')
         ? inputPath
         : join(inputPath, 'workflow.yaml');
-    let content;
+    // ONE call (issue #553) — the path register and watch take, byte for byte: the file
+    // loader (read failure → the loader's `Failed to read workflow file:` sentence; profile
+    // resolution; the four context rules), the unconditional extensions pass with real-then-
+    // sentinel secret resolution, the config_schema pass 2. Two failure populations leave it,
+    // and each keeps its own sentence (issue #445): an ExtensionLoadError is extension or
+    // deployment territory (an unresolvable module, a malformed `realm.yaml`, the #123
+    // orphaned-manifest refusal) and says `Error loading extensions:`; everything else is the
+    // workflow's own invalidity, rendered by exitOnLoadFailure (a non-WorkflowError rethrows
+    // loud — the #123 doctrine).
+    let definition;
+    let warnings;
+    let manifest;
     try {
-        content = readFileSync(filePath, 'utf8');
+        ({ definition, warnings, manifest } = await loadWorkflowForAdmission(filePath, {
+            ...(opts.extensionsModule !== undefined ? { overrideModule: opts.extensionsModule } : {}),
+            surface: 'validate',
+        }));
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(`Error: ${message}`);
-        process.exit(1);
-        return;
-    }
-    if (!hasTopLevelExtensions(content) && opts.extensionsModule === undefined) {
-        // Extension-free: the exact current from-string path — byte-identical behavior,
-        // plus the orphaned-manifest guard (#123). The from-string loader stamps no
-        // source_dir/trust_root, so resolve the same trust root the file-based path would
-        // (findTrustRoot walks package.json/.git from the workflow dir) and run the guard
-        // structural-first — after the workflow parses, before the `Valid:` print. It throws
-        // WorkflowError, which exitOnLoadFailure renders as `Invalid:` + exit(1) — this arm's
-        // guard call is DIRECT, which is why it keeps that sentence while an extensions-declaring
-        // load surfaces the same guard as `Error loading extensions:` (issue #445). resolve()
-        // before dirname so a relative `workflow.yaml` doesn't collapse the walk to '.'.
-        let definition;
-        let loaderWarnings;
-        try {
-            ({ definition, warnings: loaderWarnings } =
-                loadWorkflowFromStringWithDiagnostics(content));
-        }
-        catch (err) {
-            exitOnLoadFailure(err);
-        }
-        // Its own try (issue #463): each try owns one failure population — the #445 doctrine. A
-        // load failure above has nothing to print but itself; the guard below fails AFTER the
-        // workflow parsed, with its warnings in hand.
-        try {
-            const workflowDir = dirname(resolve(filePath));
-            checkForOrphanedManifests(workflowDir, findTrustRoot(workflowDir));
-        }
-        catch (err) {
-            // The workflow's own warnings before the refusal — the same set the success path counts,
-            // so nothing the author would otherwise see only on the NEXT run is withheld. Plain
-            // render: the escalation gate has not run, so printLoaderWarnings' `— REFUSED below`
-            // would name the wrong cause (test.ts's render comment, #450's reasoning). Unconditional:
-            // on the #123 non-WorkflowError rethrow population the warnings print before the loud
-            // crash — true statements either way. exitOnLoadFailure cannot print them twice: the
-            // orphan WorkflowError is minted bare in the CLI (load-project-extensions.ts), and the
-            // core `warnings` slot is set only by attachLoaderWarnings inside the core loader, which
-            // this throw never transits — which is exactly why this arm swallowed them until now.
-            for (const w of [...loaderWarnings, ...findRetryWithoutExplicitTimeout(definition)]) {
-                console.warn(renderLoaderWarning(w));
+        if (err instanceof ExtensionLoadError) {
+            // issue #463 — the workflow's own warnings first: pass-1's plus the retry advisory,
+            // the same set the success path counts minus the sentinel wraps, which come from the
+            // load that just failed — there is nothing to wrap. Plain render, not
+            // printLoaderWarnings — the escalation gate never ran on this arm (#540/#542).
+            //
+            // issue #454 — the errors[] convention's exception: this sentence ships WHOLE, with
+            // its `Error loading extensions: ` head — the #445 classification IS the composed
+            // message, not a channel prefix a caller prepends at print. Under `--json` the
+            // helper's two sentinel ⚠ lines may already have reached stderr (`console.warn`;
+            // register has no `--json`): stdout purity holds — #454's contract is stdout — and
+            // stderr may carry advisories on a contract arm (J7b pins it).
+            const failed = err.definition;
+            const accumulated = [
+                ...(err.warnings ?? []),
+                ...(failed !== undefined ? findRetryWithoutExplicitTimeout(failed) : []),
+            ];
+            const msg = `Error loading extensions: ${err.message}`;
+            if (json) {
+                emitValidateJson({
+                    valid: false,
+                    mode: 'file',
+                    path: inputPath,
+                    workflowId: failed?.id ?? null,
+                    schemaVersion: null,
+                    strictRequested: strict,
+                    strictFailed: false,
+                    diagnostics: accumulated,
+                    errors: [msg],
+                    checksNotRun: [],
+                    extensionKeys: [],
+                });
+                process.exit(1);
             }
-            exitOnLoadFailure(err);
+            for (const w of accumulated)
+                console.warn(renderLoaderWarning(w));
+            console.error(msg);
+            process.exit(1);
         }
-        // Reporting, deliberately OUTSIDE the try (issue #445): these lines only run once the
-        // load succeeded, and their own `process.exit` calls have no business passing through a
-        // catch that exists to classify LOAD failures. Production-neutral — the exits still exit.
-        const accumulated = [...loaderWarnings, ...findRetryWithoutExplicitTimeout(definition)];
-        if (rejectIfPolicyEscalates(accumulated)) {
+        // A pass-2 (config_schema) refusal carries the pass-1 definition beside it, so
+        // `workflow_id` is named exactly as before the collapse (round-2 Q9); a pass-1 refusal
+        // has no definition to name.
+        exitOnLoadFailure(err, json
+            ? {
+                mode: 'file',
+                path: inputPath,
+                workflowId: admittedDefinitionOf(err)?.id ?? null,
+                schemaVersion: null,
+                diagnostics: warningsOf(err),
+                strictRequested: strict,
+                checksNotRun: [],
+            }
+            : undefined);
+    }
+    const accumulated = [...warnings, ...findRetryWithoutExplicitTimeout(definition)];
+    if (json) {
+        if (rejectOnErrorSeverity(accumulated)) {
+            emitValidateJson({
+                valid: false,
+                mode: 'file',
+                path: inputPath,
+                workflowId: definition.id,
+                schemaVersion: null,
+                strictRequested: strict,
+                strictFailed: false,
+                diagnostics: accumulated,
+                errors: [renderEscalationLine(accumulated)],
+                checksNotRun: [],
+                extensionKeys: [],
+            });
             process.exit(1);
         }
-        const strictFailed = printValidationOutcome(definition, accumulated, strict);
-        // issue #236: the nudge's own INFO channel — never affects the exit code below.
-        printStructuredOutputNudge(definition, { explain });
+        const strictFailed = strict && failsStrict(accumulated);
+        emitValidateJson({
+            valid: true,
+            mode: 'file',
+            path: inputPath,
+            workflowId: definition.id,
+            schemaVersion: null,
+            strictRequested: strict,
+            strictFailed,
+            diagnostics: accumulated,
+            errors: [],
+            checksNotRun: [],
+            extensionKeys: extensionKeysOf(definition),
+        });
+        // issue #422/#236: the Extensions manifest line and the nudge are both suppressed under
+        // --json — human-informational, not represented (additive later if ever wanted).
         if (strictFailed) {
             process.exit(1);
         }
         return;
     }
-    // Extensions declared (or an override supplied): file-based two-pass validation.
-    //
-    // THREE tries, not one (issue #445). The old single catch spanned five concerns and
-    // rendered every one of them `Invalid: …` — including a user's unresolvable extension
-    // module, and including internal bugs. Each try now owns one failure population, and the
-    // reporting tail sits outside all of them.
-    let definition;
-    let pass1Warnings;
-    try {
-        // Pass 1: structural validation + extension resolution metadata (source_dir/trust_root).
-        // The universal, registry-independent structural load — its warnings are what we count.
-        ({ definition, warnings: pass1Warnings } = loadWorkflowFromFileWithDiagnostics(filePath));
-    }
-    catch (err) {
-        exitOnLoadFailure(err);
-    }
-    let registry;
-    let manifest;
-    let sentinelWarnings;
-    try {
-        ({ registry, manifest, sentinelWarnings } = await loadProjectExtensions(definition, {
-            ...(opts.extensionsModule !== undefined ? { overrideModule: opts.extensionsModule } : {}),
-            secretMode: 'sentinel',
-        }));
-    }
-    catch (err) {
-        // issue #445 — a DIFFERENT population, and it gets its own sentence. Everything
-        // loadProjectExtensions throws is extension or deployment territory: an unresolvable
-        // module path, a failed import, a module whose default export is the wrong shape, a
-        // malformed `realm.yaml`, and the #123 orphaned-manifest refusal. None of those makes
-        // the WORKFLOW invalid, and calling them `Invalid:` sent an author to the wrong file.
-        // The sentence is `realm run`'s, verbatim (run.ts) — the sibling surface renders this
-        // identical failure class exactly so.
-        //
-        // issue #463 — the workflow's own warnings first: pass-1's plus the retry advisory, the
-        // same set the success path counts minus the sentinel wraps, which come from the load that
-        // just failed — there is nothing to wrap. Plain render (test.ts's render comment, #450's
-        // reasoning): the escalation gate has not run, so printLoaderWarnings' `— REFUSED below`
-        // would name the wrong cause.
-        for (const w of [...pass1Warnings, ...findRetryWithoutExplicitTimeout(definition)]) {
-            console.warn(renderLoaderWarning(w));
-        }
-        console.error(`Error loading extensions: ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
-    }
-    try {
-        // Pass 2: step config validated against each resolved adapter's config_schema. Same
-        // content as pass 1, registry only adds config_schema checks — its warnings are proven
-        // identical to pass 1's, so they are deliberately discarded here (not collected) to avoid
-        // double-counting the same unknown key twice.
-        loadWorkflowFromFileWithDiagnostics(filePath, registry);
-    }
-    catch (err) {
-        exitOnLoadFailure(err);
-    }
-    const accumulated = [
-        ...pass1Warnings,
-        ...findRetryWithoutExplicitTimeout(definition),
-        ...wrapSentinelWarnings(sentinelWarnings),
-    ];
     if (rejectIfPolicyEscalates(accumulated)) {
         process.exit(1);
     }
-    const strictFailed = printValidationOutcome(definition, accumulated, strict);
+    const strictFailed = printValidationOutcome(definition, accumulated, strict, 0, extensionKeysOf(definition));
     if (manifest.modules.length > 0) {
         console.log(`Extensions: ${manifest.modules.map((m) => m.declared).join(', ')} ` +
             `(adapters: ${manifest.adapters.length}, handlers: ${manifest.handlers.length}, ` +