@farmslot/recipe-cli 0.5.0 → 0.7.0

package/dist/harness/command-contract.js

@@ -0,0 +1,243 @@
+// The strict public grammar a host CLI checks before commander can consume a
+// typo as a value: each public command declares its options and positionals,
+// and a mismatch becomes a stable, machine-readable usage error.
+import { harnessHost } from './host.js';
+import { closest } from './suggest.js';
+export const booleanOption = () => ({ kind: 'boolean' });
+export const valueOption = (choices) => ({
+    kind: 'value',
+    ...(choices ? { choices } : {}),
+});
+export const optionalValueOption = (choices) => ({
+    kind: 'optional-value',
+    ...(choices ? { choices } : {}),
+});
+export const contractOptions = (...groups) => Object.assign({}, ...groups);
+/**
+ * The usage error for `argv`, or null when it is valid. `commands` is the
+ * host's public table; its order is the order "Valid commands" lists.
+ */
+export function validatePublicInvocation(argv, commands, validation = {}) {
+    const host = harnessHost().name;
+    const examples = Object.fromEntries(commands.map((command) => [command.name, command.example]));
+    const token = argv[0];
+    if (!token || token === '--help' || token === '-h' || token === '--version' || token === '-v')
+        return null;
+    const resolved = resolveContractedCommand(token, commands);
+    if (!resolved) {
+        const suggestion = closest(token, publicCommandTokens(commands));
+        if (token.startsWith('-')) {
+            return {
+                code: 'CLI_UNKNOWN_OPTION',
+                command: host,
+                message: `unknown top-level option '${token}'. Valid top-level options: --help, --version.`,
+                userAction: actionFor(token, closest(token, ['--help', '--version']), `${host} --help`),
+            };
+        }
+        return {
+            code: 'CLI_UNKNOWN_COMMAND',
+            command: token,
+            message: `unknown command '${token}'. Valid commands: ${commands.map((command) => command.name).join(', ')}.`,
+            userAction: actionFor(token, suggestion, suggestion
+                ? exampleFor(host, resolveContractedCommand(suggestion, commands)?.name, examples)
+                : `${host} --help`),
+        };
+    }
+    const { name, contract } = resolved;
+    const tokens = argv.slice(1);
+    if (contract.bypass?.(tokens))
+        return null;
+    const fail = {
+        usage: (code, message) => usageFailure(host, code, name, message, examples),
+        missingPositional: (message) => missingPositionalFailure(host, name, message, contract, examples),
+    };
+    const positionals = [];
+    const seenOptions = new Set();
+    const validOptions = Object.keys(contract.options);
+    for (let index = 0; index < tokens.length; index += 1) {
+        const argument = tokens[index] ?? '';
+        if (argument === '--') {
+            if (!contract.allowPassthrough) {
+                return fail.usage('CLI_UNEXPECTED_PASSTHROUGH', 'this command does not accept `--` passthrough.');
+            }
+            break;
+        }
+        if (!argument.startsWith('-') || argument === '-') {
+            positionals.push(argument);
+            continue;
+        }
+        const equals = argument.indexOf('=');
+        const optionName = equals === -1 ? argument : argument.slice(0, equals);
+        const inlineValue = equals === -1 ? undefined : argument.slice(equals + 1);
+        const spec = contract.options[optionName];
+        if (!spec) {
+            const suggestion = validation.replacedOptions?.[optionName] ?? closest(optionName, validOptions);
+            return {
+                code: 'CLI_UNKNOWN_OPTION',
+                command: name,
+                message: `unknown option '${optionName}'.`,
+                userAction: actionFor(optionName, suggestion, exampleFor(host, name, examples)),
+            };
+        }
+        seenOptions.add(optionName);
+        if (spec.kind === 'boolean') {
+            if (inlineValue !== undefined) {
+                return fail.usage('CLI_INVALID_OPTION_VALUE', `${optionName} is a flag and does not take a value.`);
+            }
+            continue;
+        }
+        if (spec.kind === 'optional-value' && inlineValue === undefined)
+            continue;
+        const optionValue = inlineValue ?? tokens[index + 1];
+        const nextTokenIsOption = inlineValue === undefined &&
+            (optionValue === '-h' || optionValue === '--' || optionValue?.startsWith('--'));
+        if (optionValue === undefined ||
+            (spec.kind === 'value' && optionValue === '') ||
+            nextTokenIsOption) {
+            return fail.usage('CLI_MISSING_OPTION_VALUE', `${optionName} requires a value.`);
+        }
+        if (inlineValue === undefined)
+            index += 1;
+        const choices = typeof spec.choices === 'function' ? spec.choices(tokens) : spec.choices;
+        if (choices && !choices.includes(optionValue)) {
+            const suggestion = closest(optionValue, choices);
+            return {
+                code: 'CLI_INVALID_OPTION_VALUE',
+                command: name,
+                message: `${optionName} must be ${formatChoiceList(choices)}; received '${optionValue}'.`,
+                userAction: actionFor(optionValue, suggestion, exampleFor(host, name, examples)),
+            };
+        }
+    }
+    if (seenOptions.has('--help') || seenOptions.has('-h'))
+        return null;
+    const refined = contract.refine?.(positionals, seenOptions, fail);
+    if (refined)
+        return refined;
+    if (contract.leadingPositionals &&
+        !contract.requiredUnless?.some((option) => seenOptions.has(option)) &&
+        tokens
+            .slice(0, contract.leadingPositionals)
+            .some((argument) => !argument || argument.startsWith('-'))) {
+        const missing = contract.positionals?.[0]?.label ?? 'argument';
+        return fail.missingPositional(`${name} requires <${missing}> first.`);
+    }
+    const forbiddingOption = contract.noPositionalsWith?.find((option) => seenOptions.has(option));
+    if (forbiddingOption && positionals.length > 0) {
+        return fail.usage('CLI_EXCESS_POSITIONAL', `${forbiddingOption} does not accept positional '${positionals[0]}'.`);
+    }
+    const minimum = contract.requiredUnless?.some((option) => seenOptions.has(option))
+        ? 0
+        : (contract.minimumPositionals ?? 0);
+    if (positionals.length < minimum) {
+        const missingSpec = contract.positionals?.[positionals.length];
+        const missing = missingSpec?.label ?? 'argument';
+        const valid = missingSpec?.choices?.length
+            ? ` Choose one: ${missingSpec.choices.join('|')}.`
+            : '';
+        const usage = contract.usage ? ` Usage: ${contract.usage}.` : '';
+        return fail.missingPositional(`missing required <${missing}>.${valid}${usage}`);
+    }
+    const fixed = contract.positionals ?? [];
+    for (let index = 0; index < Math.min(positionals.length, fixed.length); index += 1) {
+        if (invalidPositional(positionals[index] ?? '', fixed[index]))
+            return positionalFailure(host, name, positionals[index] ?? '', fixed[index], examples);
+    }
+    if (positionals.length > fixed.length && !contract.variadic) {
+        const unexpected = positionals[fixed.length] ?? '';
+        return fail.usage('CLI_EXCESS_POSITIONAL', `unexpected positional '${unexpected}'; this command accepts ${formatPositionals(contract)}.`);
+    }
+    if (contract.variadic) {
+        for (const positional of positionals.slice(fixed.length)) {
+            if (invalidPositional(positional, contract.variadic)) {
+                return positionalFailure(host, name, positional, contract.variadic, examples);
+            }
+        }
+    }
+    return null;
+}
+/** Every value `option` takes in `tokens` before any `--`, separate (`--x v`) or inline (`--x=v`). */
+export function optionValues(tokens, option) {
+    const values = [];
+    const divider = tokens.indexOf('--');
+    const scope = divider === -1 ? tokens : tokens.slice(0, divider);
+    for (let index = 0; index < scope.length; index += 1) {
+        const token = scope[index] ?? '';
+        if (token === option && index + 1 < scope.length)
+            values.push(scope[(index += 1)] ?? '');
+        else if (token.startsWith(`${option}=`))
+            values.push(token.slice(option.length + 1));
+    }
+    return values;
+}
+/** Every public command name and alias, in table order. */
+export function publicCommandTokens(commands) {
+    return commands.flatMap((command) => [command.name, ...(command.aliases ?? [])]);
+}
+function resolveContractedCommand(token, commands) {
+    return (commands.find((command) => command.name === token) ??
+        commands.find((command) => command.aliases?.includes(token)));
+}
+function usageFailure(host, code, command, message, examples) {
+    return {
+        code,
+        command,
+        message,
+        userAction: `Try: ${exampleFor(host, command, examples)}. Inspect options: ${host} ${command} --help`,
+    };
+}
+function missingPositionalFailure(host, command, message, contract, examples) {
+    if (contract.missingPositionalAction) {
+        return {
+            code: 'CLI_MISSING_POSITIONAL',
+            command,
+            message,
+            userAction: contract.missingPositionalAction(exampleFor(host, command, examples)),
+        };
+    }
+    return usageFailure(host, 'CLI_MISSING_POSITIONAL', command, message, examples);
+}
+function positionalFailure(host, command, received, spec, examples) {
+    const valid = spec.validDescription ??
+        (spec.choices
+            ? spec.choices.join(', ')
+            : spec.pattern || spec.validate
+                ? `a valid <${spec.label}>`
+                : `<${spec.label}>`);
+    const suggestion = spec.choices ? closest(received, spec.choices) : undefined;
+    return {
+        code: 'CLI_INVALID_POSITIONAL',
+        command,
+        message: `invalid <${spec.label}> '${received}'. Valid values: ${valid}.`,
+        userAction: actionFor(received, suggestion, exampleFor(host, command, examples)),
+    };
+}
+function invalidPositional(value, spec) {
+    if (!spec)
+        return true;
+    if (spec.choices && !spec.choices.includes(value))
+        return true;
+    if (spec.validate && !spec.validate(value))
+        return true;
+    return Boolean(spec.pattern && !spec.pattern.test(value));
+}
+function formatChoiceList(choices) {
+    if (choices.length === 1)
+        return choices[0] ?? '';
+    if (choices.length === 2)
+        return `${choices[0]} or ${choices[1]}`;
+    return `${choices.slice(0, -1).join(', ')}, or ${choices[choices.length - 1]}`;
+}
+function formatPositionals(contract) {
+    const fixed = (contract.positionals ?? []).map((spec) => `<${spec.label}>`);
+    if (contract.variadic)
+        fixed.push(`[<${contract.variadic.label}> ...]`);
+    return fixed.length > 0 ? fixed.join(' ') : 'no positionals';
+}
+function actionFor(received, suggestion, example) {
+    return `${suggestion ? `Did you mean '${suggestion}' instead of '${received}'? ` : ''}Try: ${example}`;
+}
+function exampleFor(host, command, examples) {
+    return command ? (examples[command] ?? `${host} ${command} --help`) : `${host} --help`;
+}
+//# sourceMappingURL=command-contract.js.map

package/dist/harness/command-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-contract.js","sourceRoot":"","sources":["../../src/harness/command-contract.ts"],"names":[],"mappings":"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"}

package/dist/harness/commands/call.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../../src/harness/commands/call.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,KAAK,aAAa,EAGnB,MAAM,eAAe,CAAC;AAsBvB,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAOL,KAAK,YAAY,EAIlB,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAAE,KAAK,eAAe,EAAyC,MAAM,UAAU,CAAC;AAEvF,MAAM,WAAW,kBAAkB,CAAC,SAAS,EAAE,UAAU,SAAS,gBAAgB;IAChF,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC5C,YAAY,CAAC,EAAE,eAAe,CAAC;IAG/B,aAAa,CAAC,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAAC;CAC9D;AAED,wBAAsB,UAAU,CAAC,SAAS,EAAE,UAAU,SAAS,gBAAgB,EAC7E,IAAI,EAAE,MAAM,EAAE,EACd,cAAc,EAAE,kBAAkB,CAAC,SAAS,EAAE,UAAU,CAAC,GACxD,OAAO,CAAC,MAAM,CAAC,CAmfjB;AAoGD,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG9E;AA0BD,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,SAAK,GAAG,OAAO,CAKjE;AAOD,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE;IAAE,OAAO,EAAE,aAAa,CAAA;CAAE,GACzC,OAAO,CAAC,MAAM,CAAC,CA+CjB"}
+{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../../src/harness/commands/call.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,KAAK,aAAa,EAGnB,MAAM,eAAe,CAAC;AAsBvB,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAQL,KAAK,YAAY,EAIlB,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAAE,KAAK,eAAe,EAAyC,MAAM,UAAU,CAAC;AAEvF,MAAM,WAAW,kBAAkB,CAAC,SAAS,EAAE,UAAU,SAAS,gBAAgB;IAChF,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC5C,YAAY,CAAC,EAAE,eAAe,CAAC;IAG/B,aAAa,CAAC,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAAC;CAC9D;AAED,wBAAsB,UAAU,CAAC,SAAS,EAAE,UAAU,SAAS,gBAAgB,EAC7E,IAAI,EAAE,MAAM,EAAE,EACd,cAAc,EAAE,kBAAkB,CAAC,SAAS,EAAE,UAAU,CAAC,GACxD,OAAO,CAAC,MAAM,CAAC,CA0fjB;AAoGD,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG9E;AA0BD,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,SAAK,GAAG,OAAO,CAKjE;AAOD,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE;IAAE,OAAO,EAAE,aAAa,CAAA;CAAE,GACzC,OAAO,CAAC,MAAM,CAAC,CA+CjB"}

package/dist/harness/commands/call.js

@@ -18,7 +18,7 @@ import { isRecord, optionFlag, optionString, parseArgs, resolveAdapter, shellQuo
 import { resolveCommandManifest } from '../recipe-library.js';
 import { validateRecipeAdapterAware } from '../recipe-validation.js';
 import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument, } from '../run-diagnostics.js';
-import { emitHealViolation, executeWithHealBounds, persistRunEffects, preflightRecipe, prepareHeal, runRecipe, synthesizeOneNodeRecipe, } from '../run-engine.js';
+import { activateRecipeRuntimeEnvironment, emitHealViolation, executeWithHealBounds, persistRunEffects, preflightRecipe, prepareHeal, runRecipe, synthesizeOneNodeRecipe, } from '../run-engine.js';
 import { startRunObservers } from '../run-observers.js';
 import { recipeRunOptionsFromCli } from '../run-options.js';
 import { checkoutBusyOut, EXIT, usageOut } from '../shared.js';
@@ -273,145 +273,149 @@ export async function handleCall(argv, commandOptions) {
                     },
                 }),
     };
-    let preflightedExecution;
+    // One environment scope for the call: preflight, the runtime check, the
+    // observers and the execution all see the same ports.
+    const restoreRuntimeEnvironment = activateRecipeRuntimeEnvironment(adapter, target, callRuntimeOptions);
     try {
-        preflightedExecution = await preflightRecipe(engine, adapter, recipe, artifactsDir, target, actionManifestOverride, callRuntimeOptions);
-    }
-    catch (error) {
-        const trustFailure = recipeTrustFailure(error);
-        if (!trustFailure)
-            throw error;
-        const planDigest = trustFailure.details?.recipeDigest;
-        if (planDigest) {
-            trustFailure.userAction =
-                `review the plan, then rerun this call with --artifacts-dir ${shellQuote(artifactsDir)} ` +
-                    `--approve-plan ${shellQuote(planDigest)}; managed callers must keep the same artifact ` +
-                    `directory and execution environment, then set ` +
-                    `FARMSLOT_RECIPE_APPROVE_PLAN=${shellQuote(planDigest)}`;
-        }
-        reportTrustFailure('call', trustFailure, json);
-        return EXIT.validation;
-    }
-    const lock = acquireCheckoutLock(target, 'call');
-    if ('message' in lock) {
-        return checkoutBusyOut(json, 'call', lock.message, lock.path);
-    }
-    try {
-        const prepared = await prepareHeal(adapter, target, options, json, {
-            appRestartAuthored: resolvedAction === 'app.lifecycle' && args.command === 'restart',
-        });
-        if (typeof prepared === 'number')
-            return prepared;
-        const { state } = prepared;
-        preflightedExecution = await preflightRecipe(engine, adapter, recipe, artifactsDir, target, actionManifestOverride, callRuntimeOptions);
-        const ports = {
-            cdpPort: callRuntimeOptions.cdpPort,
-            watcherPort: callRuntimeOptions.watcherPort,
-        };
-        const started = await startRunObservers(adapter, target, artifactsDir, ports);
-        observers = started;
-        let executionResult;
+        let preflightedExecution;
         try {
-            executionResult = await executeWithHealBounds(() => {
-                const execution = preflightedExecution;
-                preflightedExecution = undefined;
-                return runRecipe(engine, adapter, recipe, artifactsDir, target, actionManifestOverride, callRuntimeOptions, execution, state);
-            }, target, state);
+            preflightedExecution = await preflightRecipe(engine, adapter, recipe, artifactsDir, target, actionManifestOverride, callRuntimeOptions);
         }
         catch (error) {
-            await started.abandon();
-            observers = undefined;
-            if (error instanceof ProvenanceDriftError) {
-                const failure = provenanceFailure(error);
-                if (json) {
-                    console.log(JSON.stringify({
-                        schemaVersion: 1,
-                        command: 'call',
-                        adapter,
-                        action: shortName,
-                        resolvedAction,
-                        status: 'fail',
-                        error: failure,
-                        exitCode: error.exitCode,
-                    }, null, 2));
-                }
-                else {
-                    console.error(`✗ ${host} call: ${error.message}`);
-                    console.error(`  Next: ${error.userAction}`);
-                }
-                return error.exitCode;
+            const trustFailure = recipeTrustFailure(error);
+            if (!trustFailure)
+                throw error;
+            const planDigest = trustFailure.details?.recipeDigest;
+            if (planDigest) {
+                trustFailure.userAction =
+                    `review the plan, then rerun this call with --artifacts-dir ${shellQuote(artifactsDir)} ` +
+                        `--approve-plan ${shellQuote(planDigest)}; managed callers must keep the same artifact ` +
+                        `directory and execution environment, then set ` +
+                        `FARMSLOT_RECIPE_APPROVE_PLAN=${shellQuote(planDigest)}`;
             }
-            throw error;
+            reportTrustFailure('call', trustFailure, json);
+            return EXIT.validation;
         }
-        const { result, violation } = executionResult;
-        await started.finalize(result.artifactManifestPath);
-        observers = undefined;
-        persistRunEffects(result.summaryPath, result.artifactManifestPath, state);
-        if (violation !== null) {
-            const conciseFailure = violation.originalError
-                ? conciseFailureForHuman(violation.originalError)
-                : '';
-            const taughtViolation = violation.code === 'APP_LOGIC_FAILURE' &&
-                conciseFailure.includes(' requires ') &&
-                describedAction
-                ? {
-                    ...violation,
-                    userAction: `${host} actions ${resolvedAction} --adapter ${adapter} --json`,
-                }
-                : violation;
-            return emitHealViolation(json, 'call', result, taughtViolation, state, adapter);
+        const lock = acquireCheckoutLock(target, 'call');
+        if ('message' in lock) {
+            return checkoutBusyOut(json, 'call', lock.message, lock.path);
         }
-        const callOutput = readCallOutput(result.tracePath);
-        const safeArgs = redactCallValue(args);
-        const safeCallOutput = redactCallValue(callOutput);
-        const failureUserAction = `${host} last --target ${shellQuote(target)} --json`;
-        if (json) {
-            console.log(JSON.stringify({
-                schemaVersion: 1,
-                command: 'call',
-                adapter,
-                action: shortName,
-                resolvedAction,
-                args: safeArgs,
-                ...(Object.keys(defaultsUsed).length > 0 ? { defaultsUsed } : {}),
-                status: result.status,
-                summaryPath: result.summaryPath,
-                tracePath: result.tracePath,
-                artifactManifestPath: result.artifactManifestPath,
-                ...(result.diagnosticsPath ? { diagnosticsPath: result.diagnosticsPath } : {}),
-                ...(result.sideFindings ? { sideFindings: result.sideFindings } : {}),
-                ...(callOutput !== undefined ? { output: safeCallOutput } : {}),
-                recovered: state.recovered,
-                mutations: state.mutations,
-                exitCode: result.status === 'pass' ? EXIT.ok : EXIT.runtime,
-                ...(result.status === 'fail'
+        try {
+            const prepared = await prepareHeal(adapter, target, options, json, {
+                appRestartAuthored: resolvedAction === 'app.lifecycle' && args.command === 'restart',
+            });
+            if (typeof prepared === 'number')
+                return prepared;
+            const { state } = prepared;
+            preflightedExecution = await preflightRecipe(engine, adapter, recipe, artifactsDir, target, actionManifestOverride, callRuntimeOptions);
+            const started = await startRunObservers(adapter, target, artifactsDir);
+            observers = started;
+            let executionResult;
+            try {
+                executionResult = await executeWithHealBounds(() => {
+                    const execution = preflightedExecution;
+                    preflightedExecution = undefined;
+                    return runRecipe(engine, adapter, recipe, artifactsDir, target, actionManifestOverride, callRuntimeOptions, execution, state);
+                }, target, state);
+            }
+            catch (error) {
+                await started.abandon();
+                observers = undefined;
+                if (error instanceof ProvenanceDriftError) {
+                    const failure = provenanceFailure(error);
+                    if (json) {
+                        console.log(JSON.stringify({
+                            schemaVersion: 1,
+                            command: 'call',
+                            adapter,
+                            action: shortName,
+                            resolvedAction,
+                            status: 'fail',
+                            error: failure,
+                            exitCode: error.exitCode,
+                        }, null, 2));
+                    }
+                    else {
+                        console.error(`✗ ${host} call: ${error.message}`);
+                        console.error(`  Next: ${error.userAction}`);
+                    }
+                    return error.exitCode;
+                }
+                throw error;
+            }
+            const { result, violation } = executionResult;
+            await started.finalize(result.artifactManifestPath);
+            observers = undefined;
+            persistRunEffects(result.summaryPath, result.artifactManifestPath, state);
+            if (violation !== null) {
+                const conciseFailure = violation.originalError
+                    ? conciseFailureForHuman(violation.originalError)
+                    : '';
+                const taughtViolation = violation.code === 'APP_LOGIC_FAILURE' &&
+                    conciseFailure.includes(' requires ') &&
+                    describedAction
                     ? {
-                        error: {
-                            code: 'ACTION_EXECUTION_FAILED',
-                            message: `${resolvedAction} failed; inspect the persisted result and evidence paths`,
-                            userAction: failureUserAction,
-                        },
+                        ...violation,
+                        userAction: `${host} actions ${resolvedAction} --adapter ${adapter} --json`,
                     }
-                    : {}),
-            }, null, 2));
+                    : violation;
+                return emitHealViolation(json, 'call', result, taughtViolation, state, adapter);
+            }
+            const callOutput = readCallOutput(result.tracePath);
+            const safeArgs = redactCallValue(args);
+            const safeCallOutput = redactCallValue(callOutput);
+            const failureUserAction = `${host} last --target ${shellQuote(target)} --json`;
+            if (json) {
+                console.log(JSON.stringify({
+                    schemaVersion: 1,
+                    command: 'call',
+                    adapter,
+                    action: shortName,
+                    resolvedAction,
+                    args: safeArgs,
+                    ...(Object.keys(defaultsUsed).length > 0 ? { defaultsUsed } : {}),
+                    status: result.status,
+                    summaryPath: result.summaryPath,
+                    tracePath: result.tracePath,
+                    artifactManifestPath: result.artifactManifestPath,
+                    ...(result.diagnosticsPath ? { diagnosticsPath: result.diagnosticsPath } : {}),
+                    ...(result.sideFindings ? { sideFindings: result.sideFindings } : {}),
+                    ...(callOutput !== undefined ? { output: safeCallOutput } : {}),
+                    recovered: state.recovered,
+                    mutations: state.mutations,
+                    exitCode: result.status === 'pass' ? EXIT.ok : EXIT.runtime,
+                    ...(result.status === 'fail'
+                        ? {
+                            error: {
+                                code: 'ACTION_EXECUTION_FAILED',
+                                message: `${resolvedAction} failed; inspect the persisted result and evidence paths`,
+                                userAction: failureUserAction,
+                            },
+                        }
+                        : {}),
+                }, null, 2));
+            }
+            else {
+                const renderedInputs = Object.keys(args).length > 0 ? formatCallOutput(safeArgs) : '';
+                const out = (style, text) => color(style, text, { stream: process.stdout });
+                const diagnostics = formatRunDiagnosticsForHuman(readRunDiagnosticsDocument(result.diagnosticsPath), adapter);
+                const renderedDiagnostics = `${out('label', 'Diagnostics:')}\n${diagnostics.map((line) => `  ${line}`).join('\n')}\n`;
+                console.log(`${out('label', 'call')} ${out('cmd', resolvedAction)}: ${out(result.status === 'pass' ? 'ok' : 'err', result.status)}` +
+                    `${renderedInputs ? `\n${out('label', 'Inputs:')}\n${renderedInputs}` : ''}` +
+                    `${Object.keys(defaultsUsed).length > 0 ? `\n${renderDefaultsUsed(defaultsUsed, process.stdout)}` : ''}` +
+                    `${callOutput !== undefined ? `\n${out('label', 'Result:')}\n${formatCallOutput(safeCallOutput)}` : ''}\n` +
+                    renderedDiagnostics +
+                    `${out('label', 'Artifacts:')} ${out('path', result.artifactManifestPath)}` +
+                    (result.status === 'fail' ? `\n  Next: ${failureUserAction}` : ''));
+            }
+            return result.status === 'pass' ? EXIT.ok : EXIT.runtime;
         }
-        else {
-            const renderedInputs = Object.keys(args).length > 0 ? formatCallOutput(safeArgs) : '';
-            const out = (style, text) => color(style, text, { stream: process.stdout });
-            const diagnostics = formatRunDiagnosticsForHuman(readRunDiagnosticsDocument(result.diagnosticsPath), adapter);
-            const renderedDiagnostics = `${out('label', 'Diagnostics:')}\n${diagnostics.map((line) => `  ${line}`).join('\n')}\n`;
-            console.log(`${out('label', 'call')} ${out('cmd', resolvedAction)}: ${out(result.status === 'pass' ? 'ok' : 'err', result.status)}` +
-                `${renderedInputs ? `\n${out('label', 'Inputs:')}\n${renderedInputs}` : ''}` +
-                `${Object.keys(defaultsUsed).length > 0 ? `\n${renderDefaultsUsed(defaultsUsed, process.stdout)}` : ''}` +
-                `${callOutput !== undefined ? `\n${out('label', 'Result:')}\n${formatCallOutput(safeCallOutput)}` : ''}\n` +
-                renderedDiagnostics +
-                `${out('label', 'Artifacts:')} ${out('path', result.artifactManifestPath)}` +
-                (result.status === 'fail' ? `\n  Next: ${failureUserAction}` : ''));
+        finally {
+            lock.release();
         }
-        return result.status === 'pass' ? EXIT.ok : EXIT.runtime;
     }
     finally {
-        lock.release();
+        restoreRuntimeEnvironment();
     }
 }
 function parameterValidationHelp(action, findings, args) {