@aiwg/cli 2026.10.0 → 2026.10.3

package/dist/src/cli/handlers/setup-manifest.js

@@ -4,8 +4,13 @@ import os from 'node:os';
 import path from 'node:path';
 import { parseDocument, stringify } from 'yaml';
 import { findPackageRoot } from '../find-package-root.js';
+import { isInteractive } from '../env.js';
+import { boundedSpawnSync } from '../../process/bounded-child-process.mjs';
 import { sha256 } from '../../security/artifact-trust.js';
 import { artifactVerifyHandler } from './artifact-verify.js';
+import { requireFlagValue, MissingFlagValueError } from '../flag-parsing.js';
+import { exitCodeForSpawnResult } from '../child-process-result.js';
+import { askString, createPromptInterface } from '../prompt-utils.js';
 const SETUP_SCHEMA_REL = 'agentic/code/addons/agentic-installer/schemas/v1/setup-manifest.schema.json';
 const GENERATE_HELP = `aiwg setup-generate - generate a starter setup.aiwg.io/v1 SetupManifest
 
@@ -67,15 +72,29 @@ Safety:
   Mutating execution refuses to run without explicit confirmation.
   Provider-orchestrated manifests are never handed to an agent unless their
   exact bytes have status verified under the explicit trust policy.
+
+Headless input steps (#3062):
+  A 'type: ask' step resolves its declared 'params' the same way a 'script'
+  step's env vars do (--param/--params-file/env/default); if every declared
+  param is already resolved it runs headless, otherwise it is refused,
+  naming the missing param names — this CLI has no interactive-capture
+  mechanism for 'ask' steps, with or without a terminal. A step marked
+  'interactive: true' runs an arbitrary script whose questions cannot be
+  enumerated; without a terminal it is refused outright. Every selected
+  step (including nested 'platform-route' steps) is preflighted for both
+  conditions before any step executes — never partway through.
 `;
+/**
+ * A value-taking flag present without a usable value is a usage error, not
+ * "not given" (#3062 review item 11) — delegates to the shared strict
+ * parser. Callers (the three handlers below) catch `MissingFlagValueError`
+ * and report it before any preflight check, spawn, or write.
+ * `precedence: 'first'` matches this command's own pre-#3062 behavior (a
+ * hand-rolled loop that returned on the first match), unchanged by the
+ * shared parser's second-round fix (#3062 second review, finding 4).
+ */
 function flagValue(args, name) {
-    for (let i = 0; i < args.length; i += 1) {
-        if (args[i] === name) {
-            const value = args[i + 1];
-            return value && !value.startsWith('--') ? value : undefined;
-        }
-    }
-    return undefined;
+    return requireFlagValue(args, {}, name);
 }
 function hasFlag(args, ...names) {
     return args.some((arg) => names.includes(arg));
@@ -238,6 +257,83 @@ function allSteps(manifest) {
 function existingRelative(manifestDir, rel) {
     return !!rel && existsSync(path.resolve(manifestDir, rel));
 }
+/**
+ * Detect `on_fail` reference cycles among recovery procedures themselves —
+ * go/no-go review blocker 3. A step's `on_fail` can name any recovery
+ * procedure, including (structurally, per the shared `SetupStep` type) a
+ * step *inside* a recovery procedure's own `steps`. A recovery procedure
+ * that (directly, or through another recovery procedure) names itself used
+ * to make the old, eager preflight recurse into it forever —
+ * `RangeError: Maximum call stack size exceeded`, reproduced in memory by
+ * the review.
+ *
+ * This is a one-time, bounded graph walk over `manifest.spec.recovery[]`
+ * only (at most `recovery.length` nodes) — a visited/"on the current path"
+ * marker per node means each node is fully explored exactly once, so this
+ * terminates and never re-enters a node already being explored; it reports
+ * one finding per distinct cycle instead of throwing. An `on_fail` that
+ * does not resolve to a known recovery id is reported separately by the
+ * existing unresolved-recovery check (`installerConsistencyChecks` above)
+ * and is not itself a cycle.
+ *
+ * This graph check is independent of, and does not change, how `on_fail`
+ * references are actually used (`collectPreflightBlockers()`/`runStep()`
+ * below): execution never follows an `on_fail` reference more than once
+ * (a failing recovery step reports failure directly, it does not itself
+ * trigger further recovery), so neither the main-sequence preflight nor a
+ * selected recovery's own preflight recurses through `on_fail` at all —
+ * see `collectPreflightBlockers()`'s own doc comment. This cycle check
+ * exists for the case the type system permits but execution never
+ * exercises: a recovery procedure's own steps declaring `on_fail`.
+ */
+function detectRecoveryReferenceCycles(manifest) {
+    const recoveries = manifest.spec.recovery ?? [];
+    if (recoveries.length === 0)
+        return [];
+    const onFailTargets = new Map();
+    for (const recovery of recoveries) {
+        const targets = [];
+        const collect = (steps) => {
+            steps?.forEach((step) => {
+                if (step.on_fail && step.on_fail !== 'recover')
+                    targets.push(step.on_fail);
+                step.routes?.forEach((route) => collect(route.steps));
+            });
+        };
+        collect(recovery.steps);
+        onFailTargets.set(recovery.id, targets);
+    }
+    const findings = [];
+    const reportedCycles = new Set();
+    const state = new Map();
+    const visit = (id, path) => {
+        if (state.get(id) === 'done')
+            return;
+        if (state.get(id) === 'on-path') {
+            const cycle = [...path.slice(path.indexOf(id)), id];
+            const key = [...new Set(cycle)].sort().join('\u0000');
+            if (!reportedCycles.has(key)) {
+                reportedCycles.add(key);
+                findings.push({
+                    severity: 'error',
+                    path: '/spec/recovery',
+                    rule: 'recoveryCycle',
+                    message: `recovery reference cycle: ${cycle.join(' -> ')}`,
+                });
+            }
+            return;
+        }
+        state.set(id, 'on-path');
+        for (const next of onFailTargets.get(id) ?? []) {
+            if (onFailTargets.has(next))
+                visit(next, [...path, id]);
+        }
+        state.set(id, 'done');
+    };
+    for (const recovery of recoveries)
+        visit(recovery.id, []);
+    return findings;
+}
 function installerConsistencyChecks(manifest, manifestDir) {
     if (!manifest)
         return [];
@@ -262,6 +358,8 @@ function installerConsistencyChecks(manifest, manifestDir) {
             findings.push({ severity: 'error', path: `/spec/steps/${index}/on_fail`, rule: 'on_fail', message: `unresolved recovery '${step.on_fail}'` });
         }
     }
+    // Go/no-go review blocker 3.
+    findings.push(...detectRecoveryReferenceCycles(manifest));
     for (const { step, pointer } of allSteps(manifest)) {
         if (step.type === 'script' && !existingRelative(manifestDir, step.script)) {
             findings.push({ severity: 'error', path: `${pointer}/script`, rule: 'scriptExists', message: `script not found: ${step.script ?? '(missing)'}` });
@@ -602,13 +700,41 @@ function planLines(manifest, manifestPath, target, params, steps) {
     });
     return lines.join('\n') + '\n';
 }
-function commandResult(status) {
-    const code = status === null ? 1 : status;
-    return { ok: code === 0, status: code };
+/**
+ * #3062 review item 7: a `null` status already falls through to `code = 1`
+ * (not success); this also surfaces the bounded helper's `error`/`signal`
+ * diagnostic (e.g. the enriched timeout message naming the bound and
+ * override variable) instead of silently dropping it.
+ */
+function commandResult(result) {
+    const outcome = exitCodeForSpawnResult(result);
+    if (outcome.message)
+        console.error(`[setup] ${outcome.message}`);
+    const code = result.status === null ? 1 : result.status;
+    return { ok: code === 0 && !result.error && !result.signal, status: code };
 }
+/**
+ * Run one manifest-author-defined shell command (#3062).
+ *
+ * Without a terminal, a command that tries to prompt must fail fast instead
+ * of hanging forever: bounded (long tier, stdin ignored). With a terminal,
+ * unchanged — inherited stdio, unbounded, so a human can actually answer a
+ * prompt the command issues.
+ */
 function runShell(command, cwd, env) {
+    if (!isInteractive()) {
+        const result = boundedSpawnSync(command, [], 'long', {
+            cwd, env, shell: true, stdio: ['ignore', 'inherit', 'inherit'],
+        });
+        return commandResult(result);
+    }
+    // sync-spawn: interactive manifest-shell-command — runs an arbitrary
+    // manifest-author-defined shell command with inherited stdio; it may
+    // itself prompt (see tools/testing/sync-spawn-allowlist.json). Reached
+    // only when isInteractive() is true (#3062) — the no-terminal path above
+    // uses the bounded helper instead. Not a candidate for a bounded timeout.
     const result = spawnSync(command, { cwd, env, shell: true, stdio: 'inherit' });
-    return commandResult(result.status);
+    return commandResult(result);
 }
 function isDestructiveScript(filePath) {
     const name = path.basename(filePath);
@@ -619,9 +745,180 @@ function isDestructiveScript(filePath) {
     const text = readFileSync(filePath, 'utf8');
     return /\brm\s+-rf\b|\b(cp|mv)\s+-f\b|>\s*\S+/.test(text);
 }
-function runStep(step, manifest, manifestDir, params, targetOs, confirmed, recovery = false) {
+/**
+ * Param names a `type: ask` step resolves (#3062 review item 10). Reuses
+ * the same `params` field `type: script` steps already use to pass env
+ * vars — there is no separate "ask step input" field in the schema, and
+ * this is the same mechanism, just read by the `ask` branch below instead
+ * of passed to a script.
+ */
+function askStepParams(step) {
+    return step.params ?? [];
+}
+/** Which of an `ask` step's declared params are not yet resolved (missing from `--param`/params-file/env/default). */
+function missingAskParams(step, params) {
+    return askStepParams(step).filter((name) => params[name] === undefined);
+}
+/**
+ * Preflight every step in `steps` (recursively into `platform-route` nested
+ * steps only) for conditions that would block it from running at all, and
+ * return one message per blocker — never a partial list halted at the
+ * first step (#3062 review item 13, and the second review's finding 7:
+ * refusal must happen before ANY step executes).
+ *
+ * Used for two distinct call sites, both passing only the steps that are
+ * actually about to run:
+ *
+ *   1. The main selected sequence, up front, before any of it runs
+ *      (`runSetupManifest()`'s own preflight call, below).
+ *   2. A *specific* recovery procedure's own steps, called again at the
+ *      moment a failed step selects it — completely, before that
+ *      recovery's first step runs (go/no-go review blocker 3).
+ *
+ * This function never itself follows a step's `on_fail` into another
+ * recovery procedure, in either case — go/no-go review blocker 3's
+ * "preflight is too eager" finding: the previous version always recursed
+ * into every selected step's `on_fail` recovery during the main, up-front
+ * preflight, which (a) refused a manifest whose main sequence would
+ * succeed outright, solely because its *unused* recovery contained an
+ * unsupported step, and (b) had no cycle protection, so a recovery whose
+ * own steps' `on_fail` pointed back into a recovery already being
+ * preflighted recursed without bound (`RangeError: Maximum call stack
+ * size exceeded`, reproduced by the review). Not recursing into `on_fail`
+ * here also matches what execution itself does: a failing step triggers
+ * its *one* named recovery exactly once; a failing step *within* that
+ * recovery reports failure directly rather than following a further
+ * `on_fail` — so preflight never needs to follow one either. (A
+ * recovery-to-recovery `on_fail` reference cycle in the manifest itself is
+ * still caught — as a graph check over `manifest.spec.recovery[]`, not a
+ * recursive preflight — by `detectRecoveryReferenceCycles()` during
+ * manifest validation.)
+ *
+ *   - `interactive: true` without a terminal AND without every declared
+ *     `params` entry resolved: with every declared param supplied, the
+ *     step runs headless instead (review item 10; second review finding
+ *     5b — the step itself is trusted not to need to prompt once its
+ *     declared inputs are present). With no declared params at all
+ *     ("undeclared interaction" — the step's questions cannot be
+ *     enumerated or supplied via `--param`) this always requires a
+ *     terminal.
+ *   - `type: ask` with no declared `params`: always refused — unlike
+ *     `interactive: true`, this CLI itself owns the prompting for `ask`
+ *     steps (there is no separate script to hand a terminal to), and
+ *     with nothing declared there is no destination to store an answer
+ *     in. This is one of the two agreed, permanent exceptions (the other
+ *     is the contributor sync-upstream strategy choice).
+ *   - `type: ask` with declared params not all resolved, and no
+ *     terminal: refused, naming the missing names so `--param` can
+ *     supply them. With a terminal, this is *not* a blocker — the
+ *     missing ones are prompted for when the step actually runs (second
+ *     review finding 5b).
+ *   - `type: agentic`/`type: chain`: `runStep()` refuses both
+ *     unconditionally; preflighted the same way so an earlier, unrelated
+ *     step is never executed ahead of this unconditional refusal (second
+ *     review finding 7).
+ */
+function collectPreflightBlockers(steps, manifest, targetOs, params, terminalPresent) {
+    const blockers = [];
+    for (const step of steps) {
+        if (!stepPlatformMatches(targetOs, step))
+            continue;
+        if (step.interactive) {
+            const names = askStepParams(step);
+            const missing = missingAskParams(step, params);
+            const fullySupplied = names.length > 0 && missing.length === 0;
+            if (!fullySupplied && !terminalPresent) {
+                blockers.push(names.length === 0
+                    ? `step '${step.id}' is marked interactive (its prompts cannot be enumerated or supplied via --param) and requires a terminal`
+                    : `step '${step.id}' is marked interactive and is missing required param(s): ${missing.join(', ')} (supply with --param <name>=<value>, or run with a terminal attached)`);
+            }
+        }
+        if (step.type === 'ask') {
+            const names = askStepParams(step);
+            if (names.length === 0) {
+                blockers.push(`ask step '${step.id}' declares no params to resolve via --param; interactive capture for ask ` +
+                    "steps is not implemented — declare 'params' on the step and supply them with --param <name>=<value>");
+            }
+            else {
+                const missing = missingAskParams(step, params);
+                if (missing.length > 0 && !terminalPresent) {
+                    blockers.push(`ask step '${step.id}' is missing required param(s): ${missing.join(', ')} (supply with --param ` +
+                        '<name>=<value>, or run with a terminal attached to be prompted for them)');
+                }
+            }
+        }
+        if (step.type === 'agentic' || step.type === 'chain') {
+            blockers.push(`${step.type} step '${step.id}' is not supported by deterministic CLI execution and is always refused`);
+        }
+        if (step.type === 'platform-route') {
+            const route = step.routes?.find((item) => item.platform === targetOs);
+            if (route)
+                blockers.push(...collectPreflightBlockers(route.steps, manifest, targetOs, params, terminalPresent));
+        }
+    }
+    return blockers;
+}
+/**
+ * Preflight a *specific* recovery procedure's own steps — go/no-go review
+ * blocker 3. Called at the moment a failed step selects it, completely,
+ * before any of its steps run. Returns `undefined` when the recovery id
+ * does not resolve to a known procedure (the schema/consistency check
+ * already reports that as a manifest error; this function's caller treats
+ * an unresolved id as "no recovery available", same as before).
+ */
+function findRecoveryProcedure(manifest, recoveryId) {
+    return manifest.spec.recovery?.find((item) => item.id === recoveryId);
+}
+/**
+ * Prompt interactively for each of `missingNames`, one per declared `ask`-
+ * step param still unresolved (#3062 second review, finding 5b: declared
+ * ask inputs missing AT a terminal are prompted for, not refused — this
+ * is reachable only when `isInteractive()` is true, so it is always safe
+ * to open a prompt interface here).
+ */
+async function promptForAskStep(step, missingNames) {
+    const rl = createPromptInterface();
+    const answers = {};
+    try {
+        if (step.message)
+            console.log(`[setup] ${step.message}`);
+        for (const name of missingNames) {
+            const answer = await askString(rl, `  ${name}: `, '', undefined);
+            if (answer)
+                answers[name] = answer;
+        }
+    }
+    finally {
+        rl.close();
+    }
+    return answers;
+}
+async function runStep(step, manifest, manifestDir, params, targetOs, confirmed, recovery = false) {
     if (!stepPlatformMatches(targetOs, step))
         return { ok: true, status: 0 };
+    // A step marked `interactive: true` (#3062) declares that it prompts
+    // directly. For a top-level selected step this condition is already
+    // preflighted before any step runs (review item 13; second review
+    // finding 7); this remains the only gate for a recovery step, which
+    // isn't known until a step actually fails. With every declared `params`
+    // entry resolved, the step is trusted not to need to prompt and runs
+    // headless below like any other step (second review finding 5b — the
+    // bug this fixes: it used to be refused here even when fully supplied).
+    // With no declared params at all ("undeclared interaction") or some
+    // still missing, a terminal is required.
+    if (step.interactive) {
+        const names = askStepParams(step);
+        const missing = missingAskParams(step, params);
+        const fullySupplied = names.length > 0 && missing.length === 0;
+        if (!fullySupplied && !isInteractive()) {
+            console.error(names.length === 0
+                ? `setup-run: step '${step.id}' is marked interactive (its prompts cannot be enumerated or supplied ` +
+                    'via --param) and requires a terminal; re-run from an interactive shell.'
+                : `setup-run: step '${step.id}' is marked interactive and is missing required param(s): ` +
+                    `${missing.join(', ')}; supply with --param <name>=<value>, or re-run from an interactive shell.`);
+            return { ok: false, status: 2, failedStep: step.id };
+        }
+    }
     const env = { ...process.env, ...params };
     console.log(`[setup] Step ${step.id} (${step.type})`);
     if (step.type === 'script') {
@@ -634,8 +931,19 @@ function runStep(step, manifest, manifestDir, params, targetOs, confirmed, recov
             console.error(`setup-run: refusing destructive step '${step.id}' without --yes/--confirm`);
             return { ok: false, status: 2, failedStep: step.id };
         }
-        const result = spawnSync(scriptPath, [], { cwd: manifestDir, env, stdio: 'inherit' });
-        const ran = commandResult(result.status);
+        // Without a terminal, a script that tries to prompt must fail fast
+        // instead of hanging forever: bounded (long tier, stdin ignored). With
+        // a terminal, unchanged (#3062).
+        const result = isInteractive()
+            // sync-spawn: interactive manifest-script-step — runs an arbitrary
+            // manifest-author-defined script file with inherited stdio; it may
+            // itself prompt (see tools/testing/sync-spawn-allowlist.json). Reached
+            // only when isInteractive() is true (#3062) — the no-terminal path
+            // uses the bounded helper instead. Not a candidate for a bounded
+            // timeout.
+            ? spawnSync(scriptPath, [], { cwd: manifestDir, env, stdio: 'inherit' })
+            : boundedSpawnSync(scriptPath, [], 'long', { cwd: manifestDir, env, stdio: ['ignore', 'inherit', 'inherit'] });
+        const ran = commandResult(result);
         if (!ran.ok)
             return { ...ran, failedStep: step.id };
         const verifies = Array.isArray(step.verify) ? step.verify : step.verify ? [step.verify] : [];
@@ -677,13 +985,51 @@ function runStep(step, manifest, manifestDir, params, targetOs, confirmed, recov
         return { ok: false, status: 2, failedStep: step.id };
     }
     if (step.type === 'ask') {
-        console.error(`setup-run: ask step '${step.id}' requires interactive input; use params before execution`);
-        return { ok: false, status: 2, failedStep: step.id };
+        // #3062 review item 10: a top-level selected step with all its declared
+        // params already resolved is already caught as *not* blocking by
+        // `collectPreflightBlockers` and runs headless here; this remains the
+        // gate for a recovery-path `ask` step, which isn't preflighted.
+        const names = askStepParams(step);
+        if (names.length === 0) {
+            // Agreed, permanent exception (second review finding 5b): this CLI
+            // owns the prompting for `ask` steps directly (there is no separate
+            // script to hand a terminal to), and with nothing declared there is
+            // no destination to store an answer in — always refused, with or
+            // without a terminal.
+            console.error(`setup-run: ask step '${step.id}' declares no params to resolve via --param; interactive capture ` +
+                "for ask steps is not implemented — declare 'params' on the step and supply them with --param " +
+                '<name>=<value>.');
+            return { ok: false, status: 2, failedStep: step.id };
+        }
+        const missing = missingAskParams(step, params);
+        if (missing.length === 0) {
+            console.log(`  ask: ${step.message ?? step.id} -> answered via --param (${names.join(', ')})`);
+            return { ok: true, status: 0 };
+        }
+        if (!isInteractive()) {
+            console.error(`setup-run: ask step '${step.id}' is missing required param(s): ${missing.join(', ')}; supply with ` +
+                '--param <name>=<value>, or re-run from an interactive shell to be prompted for them.');
+            return { ok: false, status: 2, failedStep: step.id };
+        }
+        // #3062 second review, finding 5b: declared ask inputs missing AT a
+        // terminal are prompted for, not refused.
+        const answers = await promptForAskStep(step, missing);
+        const stillMissing = missing.filter((name) => !answers[name]);
+        if (stillMissing.length > 0) {
+            console.error(`setup-run: ask step '${step.id}' did not receive a value for: ${stillMissing.join(', ')}.`);
+            return { ok: false, status: 2, failedStep: step.id };
+        }
+        // Merged into the same object reference the caller's loop (and every
+        // later step) reads from, so a later step sees the interactively-
+        // captured answer exactly like a `--param`-supplied one.
+        Object.assign(params, answers);
+        console.log(`  ask: ${step.message ?? step.id} -> answered interactively (${missing.join(', ')})`);
+        return { ok: true, status: 0 };
     }
     if (step.type === 'platform-route') {
         const route = step.routes?.find((item) => item.platform === targetOs);
         for (const nested of route?.steps ?? []) {
-            const result = runStep(nested, manifest, manifestDir, params, targetOs, confirmed);
+            const result = await runStep(nested, manifest, manifestDir, params, targetOs, confirmed);
             if (!result.ok)
                 return result;
         }
@@ -691,7 +1037,7 @@ function runStep(step, manifest, manifestDir, params, targetOs, confirmed, recov
     }
     return { ok: true, status: 0 };
 }
-export function runSetupManifest(options) {
+export async function runSetupManifest(options) {
     const validation = validateSetupManifest({
         cwd: options.cwd,
         frameworkRoot: options.frameworkRoot,
@@ -735,15 +1081,44 @@ export function runSetupManifest(options) {
     if (!options.yes) {
         return { exitCode: 2, message: 'setup-run: mutating execution requires --yes or --confirm after reviewing the plan with --dry-run' };
     }
+    // #3062 review item 13: preflight every selected step (recursively into
+    // `platform-route` nesting) before executing any of them — the previous
+    // behavior checked `interactive`/`ask` conditions inside the per-step
+    // loop below, so an earlier normal step could already perform work
+    // before a later step's refusal fired.
+    const blockers = collectPreflightBlockers(steps, manifest, target.os, params.values, isInteractive());
+    if (blockers.length > 0) {
+        for (const blocker of blockers)
+            console.error(`setup-run: ${blocker}.`);
+        return {
+            exitCode: 2,
+            message: `setup-run: refusing before executing any step:\n${blockers.map((b) => `  - ${b}`).join('\n')}`,
+        };
+    }
     for (const step of steps) {
-        const result = runStep(step, manifest, validation.manifestDir, params.values, target.os, options.yes);
+        const result = await runStep(step, manifest, validation.manifestDir, params.values, target.os, options.yes);
         if (!result.ok) {
             if (result.failedStep && step.on_fail) {
-                const recovery = manifest.spec.recovery?.find((item) => item.id === step.on_fail);
+                const recovery = findRecoveryProcedure(manifest, step.on_fail);
                 if (recovery) {
+                    // Go/no-go review blocker 3: preflight the *selected* recovery's
+                    // own steps completely, now that a failure has actually chosen
+                    // it — not when the manifest was first loaded (that preflighted
+                    // the main sequence only, above) — and before any of its steps
+                    // run. Refuses with zero recovery steps executed, same
+                    // all-blockers-at-once shape as the main-sequence preflight.
+                    const recoveryBlockers = collectPreflightBlockers(recovery.steps, manifest, target.os, params.values, isInteractive());
+                    if (recoveryBlockers.length > 0) {
+                        for (const blocker of recoveryBlockers)
+                            console.error(`setup-run: [recovery '${recovery.id}'] ${blocker}.`);
+                        return {
+                            exitCode: 2,
+                            message: `setup-run: recovery '${recovery.id}' (for failed step '${result.failedStep}') refusing before executing any recovery step:\n${recoveryBlockers.map((b) => `  - ${b}`).join('\n')}`,
+                        };
+                    }
                     console.error(`[setup] recovery '${recovery.id}' available for failed step '${result.failedStep}'`);
                     for (const recoveryStep of recovery.steps) {
-                        const recoveryResult = runStep(recoveryStep, manifest, validation.manifestDir, params.values, target.os, options.yes, true);
+                        const recoveryResult = await runStep(recoveryStep, manifest, validation.manifestDir, params.values, target.os, options.yes, true);
                         if (!recoveryResult.ok)
                             return { exitCode: recoveryResult.status || 1, message: `setup-run: recovery '${recovery.id}' failed` };
                     }
@@ -771,11 +1146,22 @@ export const setupValidateHandler = {
             return { exitCode: 0 };
         }
         const strict = hasFlag(ctx.args, '--strict');
+        let manifestPath;
+        let schemaPath;
+        try {
+            manifestPath = flagValue(ctx.args, '--manifest') ?? positionalManifest(ctx.args);
+            schemaPath = flagValue(ctx.args, '--schema');
+        }
+        catch (err) {
+            if (err instanceof MissingFlagValueError)
+                return { exitCode: 2, message: `${err.message}.` };
+            throw err;
+        }
         const result = validateSetupManifest({
             cwd: ctx.cwd,
             frameworkRoot: ctx.frameworkRoot,
-            manifestPath: flagValue(ctx.args, '--manifest') ?? positionalManifest(ctx.args),
-            schemaPath: flagValue(ctx.args, '--schema'),
+            manifestPath,
+            schemaPath,
             strict,
         });
         const payload = {
@@ -807,8 +1193,9 @@ export const setupGenerateHandler = {
         }
         catch (error) {
             return {
-                exitCode: 1,
-                message: error instanceof Error ? error.message : String(error),
+                // #3062 review item 11: a missing flag value is a usage error.
+                exitCode: error instanceof MissingFlagValueError ? 2 : 1,
+                message: error instanceof Error ? `${error.message}.` : String(error),
             };
         }
     },
@@ -824,21 +1211,34 @@ export const setupRunHandler = {
             process.stdout.write(RUN_HELP);
             return { exitCode: 0 };
         }
-        const options = parseRunOptions(ctx);
-        const manifestPath = options.manifestPath ?? 'setup.manifest.yaml';
+        let options;
+        let policyFlag;
+        let verificationArgs = [];
+        try {
+            options = parseRunOptions(ctx);
+            policyFlag = flagValue(ctx.args, '--policy');
+            if (policyFlag) {
+                const manifestPathForVerification = options.manifestPath ?? 'setup.manifest.yaml';
+                verificationArgs = [
+                    manifestPathForVerification,
+                    '--attestation', flagValue(ctx.args, '--attestation') ?? `${manifestPathForVerification}.aiwg-attestation.json`,
+                    '--policy', policyFlag,
+                    '--asset-type', flagValue(ctx.args, '--asset-type') ?? 'setup-manifest',
+                    '--namespace', flagValue(ctx.args, '--namespace') ?? 'aiwg',
+                    '--channel', flagValue(ctx.args, '--channel') ?? 'stable',
+                    '--json',
+                    ...(flagValue(ctx.args, '--state') ? ['--state', flagValue(ctx.args, '--state')] : []),
+                    ...(hasFlag(ctx.args, '--offline') ? ['--offline'] : []),
+                ];
+            }
+        }
+        catch (err) {
+            if (err instanceof MissingFlagValueError)
+                return { exitCode: 2, message: `setup-run: ${err.message}.` };
+            throw err;
+        }
         let artifactVerification;
-        if (flagValue(ctx.args, '--policy')) {
-            const verificationArgs = [
-                manifestPath,
-                '--attestation', flagValue(ctx.args, '--attestation') ?? `${manifestPath}.aiwg-attestation.json`,
-                '--policy', flagValue(ctx.args, '--policy'),
-                '--asset-type', flagValue(ctx.args, '--asset-type') ?? 'setup-manifest',
-                '--namespace', flagValue(ctx.args, '--namespace') ?? 'aiwg',
-                '--channel', flagValue(ctx.args, '--channel') ?? 'stable',
-                '--json',
-                ...(flagValue(ctx.args, '--state') ? ['--state', flagValue(ctx.args, '--state')] : []),
-                ...(hasFlag(ctx.args, '--offline') ? ['--offline'] : []),
-            ];
+        if (policyFlag) {
             const verification = await artifactVerifyHandler.execute({ ...ctx, args: verificationArgs, rawArgs: verificationArgs });
             try {
                 artifactVerification = JSON.parse(verification.message ?? '');