@sensigo/realm-cli 0.40.0 → 0.42.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, assessStructuredOutputEligibility, renderIneligibleMessage, } from '@sensigo/realm';
-import { loadProjectExtensions, checkForOrphanedManifests, } from '../extensions/load-project-extensions.js';
-import { renderLoadFailure, printLoaderWarnings, rejectOnErrorSeverity, failsStrict, } 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, } 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
@@ -27,7 +29,8 @@ import { renderLoadFailure, printLoaderWarnings, rejectOnErrorSeverity, failsStr
  * fires). The message is worded to cover both axes without requiring the reader to already know
  * about the cap.
  */
-function findRetryWithoutExplicitTimeout(definition) {
+/** @internal Exported for testing only. */
+export function findRetryWithoutExplicitTimeout(definition) {
     const warnings = [];
     for (const [stepName, step] of Object.entries(definition.steps)) {
         if (shouldEnforceTimeout(step) &&
@@ -38,7 +41,7 @@ function findRetryWithoutExplicitTimeout(definition) {
                 severity: resolveSeverity('RETRY_NO_TIMEOUT'),
                 scope: 'step',
                 step: stepName,
-                message: `⚠  Step '${stepName}': declares 'retry' but no 'timeout_seconds' — each attempt is ` +
+                message: `Step '${stepName}': declares 'retry' but no 'timeout_seconds' — each attempt is ` +
                     `bounded by the default execution timeout (${DEFAULT_EXECUTION_TIMEOUT_SECONDS}s), and ` +
                     `(absent an explicit 'retry.total_timeout_seconds') the step's overall retry budget ` +
                     `defaults to that same per-attempt bound compounded across every attempt plus backoffs. ` +
@@ -49,34 +52,39 @@ function findRetryWithoutExplicitTimeout(definition) {
     }
     return warnings;
 }
-/** Wraps loadProjectExtensions' sentinel-credential warnings as LoaderWarning (issue #169). */
-function wrapSentinelWarnings(sentinelWarnings) {
-    return (sentinelWarnings ?? []).map((message) => ({
-        code: 'EXTENSION_SENTINEL',
-        severity: resolveSeverity('EXTENSION_SENTINEL'),
-        scope: 'workflow',
-        message: `⚠  ${message}`,
-    }));
-}
 /**
  * The single success-path printer BOTH validation branches (extension-free and file-based)
  * share: prints every accumulated warning, then the summary line. Under `--strict`, a non-empty
  * 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).
  */
-function printValidationOutcome(definition, warnings, strict) {
+function printValidationOutcome(definition, warnings, strict, checksNotRun = 0) {
     printLoaderWarnings(warnings);
-    const base = `Valid: ${definition.id} v${definition.version} (${Object.keys(definition.steps).length} steps)`;
-    if (strict && failsStrict(warnings)) {
-        console.log(`${base} — ${warnings.length} warning(s); failing due to --strict`);
-        return true;
+    const stepCount = Object.keys(definition.steps).length;
+    const base = `Valid: ${definition.id} v${definition.version} (${stepCount} ${stepCount === 1 ? 'step' : 'steps'})`;
+    const strictFailing = strict && failsStrict(warnings);
+    const clauses = [];
+    if (checksNotRun > 0) {
+        clauses.push(`${checksNotRun} ${checksNotRun === 1 ? 'check' : 'checks'} not run`);
     }
-    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. */
@@ -90,16 +98,37 @@ function findReasoningLikeTopLevelProperty(schema) {
     return Object.keys(properties).find((name) => REASONING_LIKE_PROPERTY.test(name));
 }
 /**
- * issue #236 (Deliverable 7) — the adoption-without-default-ON nudge. Prints, per
- * `execution: 'agent'` step with an effective schema, the migration DELTA on its OWN INFO
- * channel: structurally NOT a LoaderWarning (plain `console.log`, never routed through
- * `printLoaderWarnings`/the warnings accumulator/`--strict` — that stays a hard zero-diff rail on
- * `loader-warnings.ts`, since ANY new WarningCode there would auto-fail `validate --strict`).
- * Opted-in steps ALSO print here (their own caveats) — the same channel, per design [Rv3]. 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 #236 (Deliverable 7) — the adoption nudge, on validate's own INFO channel. Structurally
+ * NOT a LoaderWarning (plain `console.log`, never routed through `printLoaderWarnings`/the
+ * warnings accumulator/`--strict` — that stays a hard zero-diff rail on `loader-warnings.ts`,
+ * since ANY new WarningCode there would auto-fail `validate --strict`).
+ *
+ * issue #422 reshaped the FORM, not the purpose. It used to print one line per caveat per step,
+ * which on a green validate of a file that never mentions structured_output meant fourteen lines
+ * (examples/06) or nine (examples/02) of advice nobody asked for. The field's converged answer for
+ * adoption discovery on a clean run is one aggregate line plus a named detail command plus a
+ * durable silencer — npm fund, cargo's future-incompat report, npm audit; no surveyed tool prints
+ * per-item adoption advice on a green run, and npm's RFC 0017 explicitly rejected demoting the
+ * class behind a flag instead. So: a summary by default, the full per-step detail behind
+ * `--explain`, and `REALM_NO_NUDGE=1` to silence.
+ *
+ * THE POLICY THAT DECIDES WHICH STEPS ARE LOUD (rustc's attach-to-the-diagnostic rule, made
+ * written policy here): advice about config the author DECLARED is a diagnostic and always prints;
+ * advice about config they COULD adopt is one line. So an opted-in step's caveats print
+ * unconditionally — `--explain` does not gate them and `REALM_NO_NUDGE` does not silence them —
+ * while a not-opted-in step's detail is exactly what moves behind the flag.
+ *
+ * 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) {
+function printStructuredOutputNudge(definition, opts) {
+    // Not-opted-in steps whose detail either renders (--explain) or feeds the summary counts.
+    const ready = []; // eligible | eligible_with_caveats
+    const withCaveats = []; // the subset of `ready` carrying >=1 caveat
+    const oneAway = []; // ineligible
     for (const [stepName, step] of Object.entries(definition.steps)) {
         if (step.execution !== 'agent')
             continue;
@@ -113,35 +142,184 @@ function printStructuredOutputNudge(definition) {
             ...(step.tools !== undefined ? { tools: step.tools } : {}),
         });
         const reasoningProp = findReasoningLikeTopLevelProperty(effectiveSchema);
+        // An opted-in step's advice is about DECLARED config: a diagnostic, printed here and now
+        // whatever the flags say. It is also EXCLUDED from the summary's census entirely — its
+        // surface is this branch, never the aggregate line.
+        if (optedIn) {
+            if (verdict.verdict !== 'eligible_with_caveats')
+                continue;
+            for (const caveat of verdict.caveats) {
+                console.log(`ℹ Step '${stepName}': structured_output caveat — ${caveat.remediation}`);
+            }
+            printReasoningAnnotation(stepName, reasoningProp);
+            continue;
+        }
         if (verdict.verdict === 'ineligible') {
-            // Opted-in + ineligible is unreachable (the loader already rejected it) — this is always
-            // the "here's what you're one step short of" migration nudge for a NOT-opted-in step.
-            console.log(`ℹ Step '${stepName}': structured_output: strict — one line short: ` +
-                `${renderIneligibleMessage(verdict.reasons)}`);
+            oneAway.push(stepName);
+            if (opts.explain) {
+                console.log(`ℹ Step '${stepName}': structured_output: strict — one line short: ` +
+                    `${renderIneligibleMessage(verdict.reasons)}`);
+            }
             continue;
         }
+        ready.push(stepName);
         if (verdict.verdict === 'eligible_with_caveats') {
-            const prefix = optedIn
-                ? `ℹ Step '${stepName}': structured_output caveat`
-                : `ℹ Step '${stepName}': eligible for structured_output: strict, with caveat`;
-            for (const caveat of verdict.caveats) {
-                console.log(`${prefix} — ${caveat.remediation}`);
-            }
-            if (reasoningProp !== undefined) {
-                console.log(`ℹ Step '${stepName}': the optional '${reasoningProp}' property looks like a ` +
-                    `reasoning field — see the optional_emission caveat above (position matters: with ` +
-                    `default thinking there is no regression; on non-thinking configurations prefer ` +
-                    `'required' + first property order — see docs/reference/yaml-schema.md).`);
+            // `eligible_with_caveats` with zero caveats is unconstructible — the assessor mints that
+            // verdict only when it has at least one — so the verdict IS the caveated subset.
+            withCaveats.push(stepName);
+            if (opts.explain) {
+                for (const caveat of verdict.caveats) {
+                    console.log(`ℹ Step '${stepName}': eligible for structured_output: strict, with caveat — ` +
+                        `${caveat.remediation}`);
+                }
+                printReasoningAnnotation(stepName, reasoningProp);
             }
             continue;
         }
         // eligible, zero caveats — NEVER printed bare (census: this is a rare, fully-required
         // schema). Always paired with the concrete next step.
-        if (!optedIn) {
+        if (opts.explain) {
             console.log(`ℹ Step '${stepName}': eligible for structured_output: strict — add ` +
                 `'structured_output: strict' to opt in.`);
         }
     }
+    // `--explain` REPLACES the summary with the detail above — an explicit ask for detail should
+    // not also get the pointer telling you how to ask for it.
+    if (opts.explain)
+        return;
+    // Read at call time, never captured at module scope (the #285 class). An explicit `--explain`
+    // beats a standing preference, which is why this check sits below the return above.
+    if (process.env['REALM_NO_NUDGE'] === '1')
+        return;
+    const line = renderNudgeSummary(ready.length, withCaveats.length, oneAway.length);
+    if (line !== undefined)
+        console.log(line);
+}
+/** The reasoning-position annotation, printed beside a caveat list wherever one renders. */
+function printReasoningAnnotation(stepName, reasoningProp) {
+    if (reasoningProp === undefined)
+        return;
+    console.log(`ℹ Step '${stepName}': the optional '${reasoningProp}' property looks like a ` +
+        `reasoning field — see the optional_emission caveat above (position matters: with ` +
+        `default thinking there is no regression; on non-thinking configurations prefer ` +
+        `'required' + first property order — see docs/reference/yaml-schema.md).`);
+}
+/**
+ * The one graded summary line (issue #422), or `undefined` when there is nothing to say.
+ *
+ * The tail teaches BOTH escape routes in the one line it gets — the detail command (npm's
+ * "Run `npm fund` for details", cargo's named report command) fused with the silencer (git's
+ * squelch-teaching advice hints). A reader who wants more and a reader who wants less are both
+ * served without a second line.
+ *
+ * Each clause pluralizes on its OWN count, and a zero-valued clause is omitted rather than
+ * rendered as a zero. The caveats parenthetical and the one-change-away clause are independent:
+ * gating the second on the first would silently drop it for a file whose ready steps are all
+ * caveat-free.
+ */
+function renderNudgeSummary(ready, withCaveats, oneAway) {
+    if (ready === 0 && oneAway === 0)
+        return undefined;
+    const steps = (n) => (n === 1 ? 'step' : 'steps');
+    const tail = ` — run 'realm workflow validate --explain' for detail (REALM_NO_NUDGE=1 to silence).`;
+    if (ready === 0) {
+        return `ℹ ${oneAway} ${steps(oneAway)} one change away from structured_output: strict${tail}`;
+    }
+    let line = `ℹ ${ready} ${steps(ready)} ready for structured_output: strict`;
+    if (withCaveats > 0)
+        line += ` (${withCaveats} with caveats)`;
+    if (oneAway > 0)
+        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,
+    }, 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).
+ *
+ * WorkflowError means the workflow is invalid: print the warnings it carried (#424), render the
+ * message, exit 1. Anything else is an internal bug and is RETHROWN — the #123 doctrine, pinned
+ * by validate-internal-error.test.ts's "genuine-bug-still-loud" cell: a real crash must never be
+ * relabelled `Invalid:`, because that tells an author their file is wrong when realm is.
+ *
+ * The extensions arm used to render ANY error as `Invalid:`, so it violated that doctrine in two
+ * directions at once — an internal bug was swallowed, and a user's broken extension module was
+ * blamed on their workflow. Both arms route here now, and extension loading has its own catch
+ * with its own sentence, so the two populations stay separate.
+ *
+ * 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, 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,
+            });
+            process.exit(1);
+        }
+        if (err.warnings !== undefined)
+            printLoaderWarnings(err.warnings);
+        console.error(renderLoadFailure(err));
+        process.exit(1);
+    }
+    throw err;
 }
 /**
  * The issue #170 boundary-reject, LIVE since the flip: a workflow carrying an unrecognised
@@ -153,111 +331,459 @@ function rejectIfPolicyEscalates(warnings) {
     if (!rejectOnErrorSeverity(warnings))
         return false;
     printLoaderWarnings(warnings);
-    console.error(`Invalid: ${warnings.length} warning(s) present, and at least one is escalated to an error by policy.`);
+    // issue #425: name WHICH warnings escalated. "at least one is escalated" left an author with
+    // three warnings above and no way to tell which of them was the refusal — the counts are the
+    // aggregate this line adds, so it is the line that has to say.
+    //
+    // 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 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) {
+/**
+ * `validate --registered <id>` — audit the STORED copy of a workflow (issue #427).
+ *
+ * The mechanism is kubectl's server-side dry-run shape: strip the keys the loader stamps, feed
+ * the rest back through the REAL loader, report what it says. Zero rules are duplicated here, so
+ * this surface cannot drift from what `register` would accept tomorrow.
+ *
+ * What it audits is the INSTALLED loader — the same limitation kubectl documents. The
+ * pre-upgrade journey is therefore: upgrade the CLI first, THEN audit. That is safe precisely
+ * because grandfathering holds for the copies it applies to: a CURRENT-SCHEMA registered copy
+ * keeps running under the rules it was registered with, so upgrading the CLI to look does not
+ * 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, json, overrideModule) {
+    const store = new JsonWorkflowStore();
+    let stored;
     try {
-        const raw = load(content);
-        return (typeof raw === 'object' &&
-            raw !== null &&
-            !Array.isArray(raw) &&
-            'extensions' in raw);
+        stored = await store.get(id);
     }
-    catch {
-        return false;
+    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: [],
+                });
+                process.exit(1);
+            }
+            console.error(`Error: ${err.message}`);
+            console.error('Registered workflows: realm workflow list');
+            process.exit(1);
+        }
+        if (err instanceof WorkflowError && err.code === 'STATE_LEGACY_FORMAT') {
+            // ONE clause only. There is no schema_version to name — nothing parsed far enough to read
+            // one — and the grandfathering sentence would be FALSE for this cohort: every runtime
+            // 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: [],
+                });
+                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.
+            console.error(renderLoadFailure(err));
+            process.exit(1);
+        }
+        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).
+            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: [],
+                });
+                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.
+    }
+    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];
+    // 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 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 {
+        // 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, 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,
+                    });
+                    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,
+            });
+            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,
+        });
+        if (strictFailed) {
+            process.exit(1);
+        }
+        return;
+    }
+    if (rejectIfPolicyEscalates(accumulated)) {
+        process.exit(1);
+    }
+    const strictFailed = printValidationOutcome(definition, accumulated, strict, notRun.length);
+    if (strictFailed) {
+        process.exit(1);
     }
 }
 export const validateCommand = new Command('validate')
-    .argument('<path>', 'Path to workflow directory or workflow.yaml file')
+    .argument('[path]', 'Path to workflow directory or workflow.yaml file')
+    .option('--registered <id>', 'Audit the STORED copy of a registered workflow instead of a file (issue #427)')
     .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);
+        return;
+    }
+    if (inputPath !== undefined && opts.registered !== undefined) {
+        console.error('Error: --registered audits the stored copy — it cannot be combined with a path.');
+        process.exit(1);
+        return;
+    }
+    if (opts.registered !== undefined) {
+        await validateRegistered(opts.registered, strict, json, opts.extensionsModule);
+        return;
+    }
     const filePath = inputPath.endsWith('.yaml') || inputPath.endsWith('.yml')
         ? inputPath
         : join(inputPath, 'workflow.yaml');
-    const strict = opts.strict === true;
-    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 the catch below renders as `Invalid:` + exit(1). resolve()
-        // before dirname so a relative `workflow.yaml` doesn't collapse the walk to '.'.
-        try {
-            const { definition, warnings: loaderWarnings } = loadWorkflowFromStringWithDiagnostics(content);
-            const workflowDir = dirname(resolve(filePath));
-            checkForOrphanedManifests(workflowDir, findTrustRoot(workflowDir));
-            const accumulated = [...loaderWarnings, ...findRetryWithoutExplicitTimeout(definition)];
-            if (rejectIfPolicyEscalates(accumulated)) {
-                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);
-            if (strictFailed) {
+        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: [],
+                });
                 process.exit(1);
             }
+            for (const w of accumulated)
+                console.warn(renderLoaderWarning(w));
+            console.error(msg);
+            process.exit(1);
         }
-        catch (err) {
-            if (err instanceof WorkflowError) {
-                console.error(renderLoadFailure(err.message));
-                process.exit(1);
+        // 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: [],
             }
-            throw err;
-        }
-        return;
+            : undefined);
     }
-    // Extensions declared (or an override supplied): file-based two-pass validation.
-    try {
-        // Pass 1: structural validation + extension resolution metadata (source_dir/trust_root).
-        // The universal, registry-independent structural load — its warnings are what we count.
-        const { definition, warnings: pass1Warnings } = loadWorkflowFromFileWithDiagnostics(filePath);
-        const { registry, manifest, sentinelWarnings } = await loadProjectExtensions(definition, {
-            ...(opts.extensionsModule !== undefined ? { overrideModule: opts.extensionsModule } : {}),
-            secretMode: 'sentinel',
-        });
-        // 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);
-        const accumulated = [
-            ...pass1Warnings,
-            ...findRetryWithoutExplicitTimeout(definition),
-            ...wrapSentinelWarnings(sentinelWarnings),
-        ];
-        if (rejectIfPolicyEscalates(accumulated)) {
+    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: [],
+            });
             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);
-        if (manifest.modules.length > 0) {
-            console.log(`Extensions: ${manifest.modules.map((m) => m.declared).join(', ')} ` +
-                `(adapters: ${manifest.adapters.length}, handlers: ${manifest.handlers.length}, ` +
-                `processors: ${manifest.processors.length})`);
-        }
+        const strictFailed = strict && failsStrict(accumulated);
+        emitValidateJson({
+            valid: true,
+            mode: 'file',
+            path: inputPath,
+            workflowId: definition.id,
+            schemaVersion: null,
+            strictRequested: strict,
+            strictFailed,
+            diagnostics: accumulated,
+            errors: [],
+            checksNotRun: [],
+        });
+        // 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;
     }
-    catch (err) {
-        console.error(renderLoadFailure(err instanceof Error ? err.message : String(err)));
+    if (rejectIfPolicyEscalates(accumulated)) {
+        process.exit(1);
+    }
+    const strictFailed = printValidationOutcome(definition, accumulated, strict);
+    if (manifest.modules.length > 0) {
+        console.log(`Extensions: ${manifest.modules.map((m) => m.declared).join(', ')} ` +
+            `(adapters: ${manifest.adapters.length}, handlers: ${manifest.handlers.length}, ` +
+            `processors: ${manifest.processors.length})`);
+    }
+    // issue #236: the nudge's own INFO channel — never affects the exit code below.
+    // issue #422: genuinely end-of-report, BELOW the Extensions block — the summary is a
+    // pointer at what you could do next, not part of what was just validated.
+    printStructuredOutputNudge(definition, { explain });
+    if (strictFailed) {
         process.exit(1);
     }
 });