@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/cli/investigation-recipes.mjs

@@ -0,0 +1,177 @@
+import { CLI_DOMAIN_CONTROL_MONITOR_SCHEMA } from "../packages/contracts/domain-control-monitor.mjs";
+import { DOMAIN_CONTROL_REVIEW_SCHEMA } from "../packages/contracts/domain-control-review.mjs";
+import { EXTERNAL_FINDINGS_SCHEMA } from "../packages/contracts/external-observation-interchange.mjs";
+import { CLI_LOOKUP_BRIEF_SCHEMA } from "../packages/contracts/cli-lookup-brief.mjs";
+export const INVESTIGATION_RECIPE_DEFINITIONS = Object.freeze({
+    'domain-triage': Object.freeze({
+        label: 'New domain triage',
+        standardInputs: Object.freeze([
+            { stepId: 'export', input: 1, sourceStepId: 'collect' },
+            { stepId: 'verify', input: 1, sourceStepId: 'export' },
+        ]),
+        subjectRequirement: 'domain',
+        objective: 'Collect and preserve separately attributed registration, DNS, HTTP, TLS, page, and network-context evidence.',
+        limitations: Object.freeze([
+            'Collection remains analyst-triggered and source limitations remain explicit.',
+            'Disposition, reviewed response actions, monitoring, and closure continue in the saved Case workspace; this CLI recipe does not submit reports.',
+        ]),
+        steps: (domain) => Object.freeze([
+            step('collect', 'Collect a Deep lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Review source health and limitations before using missing fields.'),
+            step('export', 'Create a portable evidence report', 'export', ['<saved-lookup.json>'], 'offline', 'analyst_selection', 'whoisleuth.lookup-evidence', 'Reuse the collected Lookup by default, or select a different reviewed Lookup file.'),
+            step('verify', 'Verify the exported artefact', 'verify-artifact', ['<evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Keep verification distinct from a claim that the observations are correct or current.'),
+        ]),
+    }),
+    'lookalike-review': Object.freeze({
+        label: 'Lookalike candidate review',
+        subjectRequirement: 'brand_or_domain',
+        objective: 'Generate a bounded candidate queue, collect only the selected scope, and retain a reviewed candidate lookup.',
+        limitations: Object.freeze([
+            'Candidate generation does not establish registration, control, intent, or maliciousness.',
+            'Official-reference collection and page comparison require analyst-selected saved evidence; use page-compare after retaining the reference and candidate observations.',
+        ]),
+        steps: (subject) => Object.freeze([
+            step('generate', 'Generate candidates offline', 'discover', [subject, '--preset', 'all', '--json'], 'offline', 'none', 'whoisleuth.cli.discover', 'Review mutation families and suppressions before collection.'),
+            step('scan', 'Collect a bounded candidate queue', 'discover-scan', [subject, '--fast', '--scan-limit', '50', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.discovery-scan', 'Fast collection is a triage boundary; partial or inconclusive authority evidence remains explicit.'),
+            step('inspect', 'Deep-review one selected candidate', 'lookup', ['<selected-domain>', '--deep', '--json'], 'network', 'analyst_selection', 'whoisleuth.cli.lookup', 'Select a candidate deliberately; generation does not prove registration, control, intent, or maliciousness.'),
+        ]),
+    }),
+    'owned-domain-review': Object.freeze({
+        label: 'Owned domain posture review',
+        subjectRequirement: 'domain',
+        objective: 'Review current passive posture and compare supplied observations with an analyst-authored control manifest.',
+        limitations: Object.freeze([
+            'Use only for a domain the analyst owns or is authorised to review.',
+        ]),
+        steps: (domain) => Object.freeze([
+            step('posture', 'Collect bounded DNS posture', 'posture', [domain, '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.posture', 'Review mail profile and delegation evidence before interpreting missing records.'),
+            step('lookup', 'Collect supporting Deep evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Retain separately attributed registration, DNS, TLS, and page observations.'),
+            step('manifest', 'Review the domain control manifest', 'domain-control', ['<review-input.json>', '--json'], 'offline', 'analyst_selection', DOMAIN_CONTROL_REVIEW_SCHEMA, 'Only complete supplied observations may produce drift.'),
+        ]),
+    }),
+    'historical-comparison': Object.freeze({
+        label: 'Historical observation comparison',
+        standardInputs: Object.freeze([
+            { stepId: 'diff', input: 2, sourceStepId: 'current' },
+            { stepId: 'timeline', input: 3, sourceStepId: 'current' },
+        ]),
+        subjectRequirement: 'domain',
+        objective: 'Collect a current observation and compare it with analyst-selected saved observations without merging source states.',
+        limitations: Object.freeze([
+            'A later observation does not retroactively refresh retained evidence.',
+        ]),
+        steps: (domain) => Object.freeze([
+            step('current', 'Collect the current lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'A current request does not refresh or validate older provider-reported history.'),
+            step('diff', 'Compare two selected observations', 'diff', ['<previous.json>', '<current.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-diff', 'Equal, different, conflicting, and unavailable evidence remain separate.'),
+            step('timeline', 'Build a bounded local timeline', 'timeline', ['<oldest.json>', '<newer.json>', '<current.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-timeline', 'Choose two to twenty same-domain files in chronological scope.'),
+        ]),
+    }),
+    'campaign-review': Object.freeze({
+        label: 'Campaign candidate review',
+        subjectRequirement: 'brand_or_domain',
+        objective: 'Prepare a bounded candidate set, collect a deliberately selected queue, and review retained evidence without asserting campaign attribution.',
+        limitations: Object.freeze([
+            'Grouping candidates is analyst triage and does not prove common ownership, control, infrastructure, or intent.',
+        ]),
+        steps: (subject) => Object.freeze([
+            step('prepare', 'Prepare candidates offline', 'discover', [subject, '--preset', 'all', '--json'], 'offline', 'none', 'whoisleuth.cli.discover', 'Review mutation families and bounded omissions before selecting a collection scope.'),
+            step('collect', 'Collect the selected candidate queue', 'discover-scan', [subject, '--fast', '--scan-limit', '50', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.discovery-scan', 'Treat partial and inconclusive authority results as explicit outcomes.'),
+            step('review', 'Prepare a selected candidate brief', 'brief', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', CLI_LOOKUP_BRIEF_SCHEMA, 'Select a saved candidate Lookup; keep any campaign grouping analyst-authored.'),
+        ]),
+    }),
+    'certificate-anomaly': Object.freeze({
+        label: 'Certificate anomaly review',
+        subjectRequirement: 'domain',
+        objective: 'Review bounded certificate observations alongside current source-qualified domain evidence without treating issuance as proof of control or intent.',
+        limitations: Object.freeze([
+            'Certificate observations are separately attributed and do not establish current service control.',
+        ]),
+        steps: (domain) => Object.freeze([
+            step('search', 'Collect bounded certificate observations', 'ct-search', [domain, '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.ct-search', 'Review source availability, truncation, and observation timing.'),
+            step('intake', 'Normalise the selected observations', 'ct-intake', ['<certificate-events.json>', '--json'], 'offline', 'analyst_selection', EXTERNAL_FINDINGS_SCHEMA, 'Select a certificate-event batch; a certificate-search report is not interchangeable with that input.'),
+            step('corroborate', 'Collect supporting domain evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Compare evidence families without collapsing certificate and registration identities.'),
+        ]),
+    }),
+    'registry-disagreement': Object.freeze({
+        label: 'Registry disagreement review',
+        standardInputs: Object.freeze([
+            { stepId: 'compare', input: 1, sourceStepId: 'collect' },
+            { stepId: 'report', input: 1, sourceStepId: 'collect' },
+        ]),
+        subjectRequirement: 'domain',
+        objective: 'Collect separately attributed registration evidence and review conflicting publications without selecting an arbitrary source as truth.',
+        limitations: Object.freeze([
+            'Only authority-aware registration evidence may decide availability; disagreement remains explicit.',
+        ]),
+        steps: (domain) => Object.freeze([
+            step('collect', 'Collect source-qualified registration evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Retain RDAP, registrar RDAP, WHOIS, and authority states separately.'),
+            step('compare', 'Compare registry publications offline', 'compare', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.compare', 'Do not convert conflicting or unavailable publications into equivalence.'),
+            step('report', 'Prepare a target-free source report', 'source-report', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.source-reliability-report', 'The report describes source behaviour, not ownership, safety, or legal status.'),
+        ]),
+    }),
+    'evidence-handoff': Object.freeze({
+        label: 'Reviewed evidence handoff',
+        standardInputs: Object.freeze([{ stepId: 'lint', input: 1, sourceStepId: 'package' }]),
+        subjectRequirement: 'review_label',
+        objective: 'Verify, minimise, and package analyst-selected evidence for a deliberate handoff without transmitting or submitting it.',
+        limitations: Object.freeze([
+            'The recipe prepares local material only; sharing remains a separate deliberate action.',
+        ]),
+        steps: () => Object.freeze([
+            step('verify', 'Verify the selected artefact', 'verify-artifact', ['<evidence.json>', '--json', '--strict-exit'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Verification checks structure and integrity, not the truth or currency of observations.'),
+            step('package', 'Build a reviewed public Case-pack', 'case-pack', ['<cases.json>', '--audience', 'public', '--reviewed', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.case-pack', 'Review minimisation and audience projection before retaining the separate package.'),
+            step('lint', 'Review deliberate-sharing metadata', 'sharing-review', [
+                '<package.json>',
+                '--marking',
+                'clear',
+                '--recipient-scope',
+                'public',
+                '--purpose',
+                'reviewed evidence handoff',
+                '--human-reviewed',
+                '--personal-data-reviewed',
+                '--redactions-confirmed',
+                '--json',
+            ], 'offline', 'analyst_selection', 'whoisleuth.cli.sharing-review', 'A clear lint result does not send, upload, publish, or authorise the artefact.'),
+        ]),
+    }),
+    'planned-domain-change': Object.freeze({
+        label: 'Planned domain change',
+        subjectRequirement: 'domain',
+        objective: 'Review an analyst-authored desired state and prepare bounded change material without changing DNS, registry, mail, or hosted configuration.',
+        limitations: Object.freeze([
+            'Planning and packaging never apply, submit, schedule, or enforce a change.',
+        ]),
+        steps: () => Object.freeze([
+            step('control', 'Review the desired-state manifest', 'domain-control', ['<review-input.json>', '--json'], 'offline', 'analyst_selection', DOMAIN_CONTROL_REVIEW_SCHEMA, 'Only supplied complete observations may produce drift.'),
+            step('assure', 'Review change and recovery assumptions', 'assurance', ['<assurance-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-assurance', 'Record uncertainty, rollback dependencies, and unavailable evidence explicitly.'),
+            step('package', 'Build a reviewed change packet', 'change-packet', ['<change-packet-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-change-packet', 'The packet is local reviewed material and performs no submission or enforcement.'),
+        ]),
+    }),
+    'post-change-verification': Object.freeze({
+        label: 'Post-change verification',
+        subjectRequirement: 'domain',
+        objective: 'Perform one explicit later observation and compare it with analyst-selected retained evidence after an authorised change.',
+        limitations: Object.freeze([
+            'This is a one-time recheck, not monitoring setup or proof that every resolver or service has converged.',
+        ]),
+        steps: () => Object.freeze([
+            step('recheck', 'Run one bounded retained-manifest review', 'monitor-once', ['<manifest.json>', '--limit', '1', '--json'], 'network', 'network_disclosure', CLI_DOMAIN_CONTROL_MONITOR_SCHEMA, 'One later observation may remain partial, unavailable, stale, or conflicting.'),
+            step('compare', 'Compare selected before and after evidence', 'diff', ['<before.json>', '<after.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-diff', 'Materiality is derived from compatible retained evidence and does not infer intent.'),
+            step('record', 'Record reviewed completion material', 'change-packet', ['<post-change-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-change-packet', 'Recording reviewed material does not submit it or start automatic monitoring.'),
+        ]),
+    }),
+});
+export const INVESTIGATION_PLAN_RECIPES = Object.freeze(Object.keys(INVESTIGATION_RECIPE_DEFINITIONS));
+export const RUNNABLE_INVESTIGATION_PLAN_RECIPES = INVESTIGATION_PLAN_RECIPES;
+function step(id, label, command, args, mode, approval, produces, completion) {
+    return Object.freeze({
+        id,
+        label,
+        command,
+        arguments: Object.freeze([...args]),
+        mode,
+        approval,
+        produces,
+        completion,
+    });
+}

package/cli/investigation-run.mjs

@@ -1,15 +1,17 @@
 import { Buffer } from 'node:buffer';
-import { buildInvestigationPlan, isRunnableInvestigationRecipe, } from "./investigation-plan.mjs";
+import { isDeepStrictEqual } from 'node:util';
+import { buildInvestigationPlan, isRunnableInvestigationRecipe, workflowReviewDeclarations, workflowStandardInputs, } from "./investigation-plan.mjs";
 import { CliUsageError } from "./errors.mjs";
 import { hasUnsafeCliText } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
-export const CLI_INVESTIGATION_RUN_SCHEMA = 'whoisleuth.cli.investigation-run';
-export const CLI_INVESTIGATION_RUN_VERSION = 2;
-export const MAX_INVESTIGATION_RUN_BYTES = 24 * 1024 * 1024;
-export const MAX_INVESTIGATION_RUN_SELECTIONS = 16;
-export const MAX_INVESTIGATION_RUN_SELECTION_LENGTH = 1_024;
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
+import { CLI_INVESTIGATION_RUN_SCHEMA, CLI_INVESTIGATION_PREVIEW_SCHEMA, CLI_INVESTIGATION_PREVIEW_VERSION, CLI_INVESTIGATION_RUN_VERSION, SUPPORTED_CLI_INVESTIGATION_RUN_VERSIONS, MAX_INVESTIGATION_RUN_BYTES, MAX_INVESTIGATION_RUN_SELECTIONS, MAX_INVESTIGATION_RUN_SELECTION_LENGTH, } from "../packages/contracts/investigation-run.mjs";
+import { normalizeWorkflowBindings, validateWorkflowResult, workflowArtifactReference, workflowInputSchemas, } from "./investigation-artifacts.mjs";
+export { CLI_INVESTIGATION_RUN_SCHEMA, CLI_INVESTIGATION_RUN_VERSION, SUPPORTED_CLI_INVESTIGATION_RUN_VERSIONS, MAX_INVESTIGATION_RUN_BYTES, MAX_INVESTIGATION_RUN_SELECTIONS, MAX_INVESTIGATION_RUN_SELECTION_LENGTH, };
 const PLACEHOLDER_PATTERN = /^<[^>]+>$/u;
+// These collectors can return useful incomplete observations. Offline validation
+// and export failures are not observations and must remain retryable failures.
+const PARTIAL_OBSERVATION_COMMANDS = new Set(['lookup', 'posture', 'discover-scan', 'ct-search', 'monitor-once']);
 function boundedResult(value) {
     if (Buffer.byteLength(value, 'utf8') > MAX_INVESTIGATION_RUN_BYTES) {
         throw new CliUsageError(`Investigation step output is limited to ${MAX_INVESTIGATION_RUN_BYTES} bytes.`);
@@ -25,28 +27,56 @@ function boundedResult(value) {
         return value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/gu, '').slice(0, MAX_INVESTIGATION_RUN_BYTES);
     }
 }
-function resultSchema(value) {
-    return value && typeof value === 'object' && !Array.isArray(value) && typeof value.schema === 'string'
-        ? String(value.schema)
-        : null;
+function stepDisposition(step, exitCode, result, retained = false) {
+    const partial = exitCode === EXIT_CODES.PARTIAL_FAILURE && step.mode === 'network'
+        && PARTIAL_OBSERVATION_COMMANDS.has(step.command);
+    if (exitCode === EXIT_CODES.SUCCESS || partial) {
+        try {
+            const artifact = validateWorkflowResult(step, result, retained);
+            return { disposition: partial ? 'partial' : 'complete', artifact };
+        }
+        catch {
+            if (!partial)
+                throw new CliUsageError(`Investigation step ${step.id} returned an unexpected command contract or invalid result.`);
+        }
+    }
+    return { disposition: 'failed', artifact: null };
 }
 function sameArguments(left, right) {
     return Array.isArray(left)
         && left.length === right.length
         && left.every((value, index) => typeof value === 'string' && value === right[index]);
 }
-function selectedArguments(step, values) {
+function selectedArguments(step, values, bindings, completed) {
     let selectionIndex = 0;
+    let input = 0;
     return Object.freeze(step.arguments.map((argument) => {
         if (!PLACEHOLDER_PATTERN.test(argument))
             return argument;
+        input += 1;
+        const binding = bindings.find((item) => item.stepId === step.id && item.input === input);
+        if (binding) {
+            const artifact = completed.find((item) => item.id === binding.sourceStepId)?.artifact;
+            return artifact ? workflowArtifactReference(artifact) : argument;
+        }
         const selected = values[selectionIndex];
         selectionIndex += 1;
         return selected ?? argument;
     }));
 }
-function selectedStep(step, values) {
-    return Object.freeze({ ...step, arguments: selectedArguments(step, values) });
+function selectedStep(step, values, bindings, completed) {
+    return Object.freeze({ ...step, arguments: selectedArguments(step, values, bindings, completed) });
+}
+function resolveStepInputs(step, bindings, completed) {
+    const files = new Map();
+    const inputs = bindings.filter((binding) => binding.stepId === step.id).map((binding) => {
+        const source = completed.find((item) => item.id === binding.sourceStepId);
+        if (!source?.artifact)
+            throw new CliUsageError(`Workflow step ${step.id} has no validated source artefact.`);
+        files.set(workflowArtifactReference(source.artifact), JSON.stringify(source.result));
+        return Object.freeze({ input: binding.input, sourceStepId: source.id, artifactId: source.artifact.id });
+    });
+    return { files, inputs: Object.freeze(inputs) };
 }
 function placeholderCount(step) {
     return step.arguments.filter((argument) => PLACEHOLDER_PATTERN.test(argument)).length;
@@ -107,11 +137,11 @@ function normalizeInvocationSelections(plan, selections) {
     }
     return normalizeRetainedSelections(plan, [...grouped].map(([stepId, values]) => ({ stepId, values })), 'workflow-run selections');
 }
-function mergeSelections(plan, retained, supplied, completed) {
+function mergeSelections(plan, retained, supplied, completed, bindings) {
     const merged = new Map(retained.map((item) => [item.stepId, item.values]));
     for (const item of supplied) {
         const completedStep = completed.find((step) => step.id === item.stepId);
-        if (completedStep && !sameArguments(completedStep.arguments, selectedArguments(plan.steps.find((step) => step.id === item.stepId), item.values))) {
+        if (completedStep && !sameArguments(completedStep.arguments, selectedArguments(plan.steps.find((step) => step.id === item.stepId), item.values, bindings, completed))) {
             throw new CliUsageError(`workflow-run cannot change analyst selections for completed step ${item.stepId}.`);
         }
         merged.set(item.stepId, item.values);
@@ -121,9 +151,36 @@ function mergeSelections(plan, retained, supplied, completed) {
         return values ? [Object.freeze({ stepId: step.id, values: Object.freeze([...values]) })] : [];
     });
 }
+function mergeBindings(plan, retained, supplied, completed) {
+    const merged = [...retained];
+    for (const binding of supplied) {
+        const index = merged.findIndex((item) => item.stepId === binding.stepId && item.input === binding.input);
+        if (completed.some((step) => step.id === binding.stepId) && !isDeepStrictEqual(merged[index], binding)) {
+            throw new CliUsageError(`workflow-run cannot change artefact inputs for completed step ${binding.stepId}.`);
+        }
+        if (index === -1)
+            merged.push(binding);
+        else
+            merged[index] = binding;
+    }
+    return normalizeWorkflowBindings(plan, merged);
+}
+function validateSelectedInputs(plan, selections, bindings, completed) {
+    for (const selection of selections) {
+        const step = plan.steps.find((item) => item.id === selection.stepId);
+        if (selection.values.length + bindings.filter((item) => item.stepId === step.id).length > placeholderCount(step)) {
+            throw new CliUsageError(`Workflow step ${step.id} has more selections and artefact bindings than inputs.`);
+        }
+        // Ordinary filenames remain literal. A caller cannot make a selected file
+        // alias an explicitly bound in-memory document in the same invocation.
+        if (selection.values.some((value) => bindings.some((binding) => binding.stepId === step.id && completed.some((item) => item.id === binding.sourceStepId && item.artifact && value === workflowArtifactReference(item.artifact))))) {
+            throw new CliUsageError(`Workflow step ${step.id} has a filename that conflicts with an artefact reference.`);
+        }
+    }
+}
 function parseResumeState(input, plan) {
     if (!input)
-        return Object.freeze({ completed: Object.freeze([]), selections: Object.freeze([]) });
+        return Object.freeze({ completed: Object.freeze([]), selections: Object.freeze([]), bindings: Object.freeze([]), retryableStepId: null });
     if (Buffer.byteLength(input, 'utf8') > MAX_INVESTIGATION_RUN_BYTES)
         throw new CliUsageError('Investigation resume state exceeds the 24 MiB limit.');
     const normalizedInput = input.replace(/^\uFEFF/u, '');
@@ -145,7 +202,7 @@ function parseResumeState(input, plan) {
     }
     const root = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
     if (root.schema !== CLI_INVESTIGATION_RUN_SCHEMA
-        || (root.version !== 1 && root.version !== CLI_INVESTIGATION_RUN_VERSION)
+        || !SUPPORTED_CLI_INVESTIGATION_RUN_VERSIONS.some((version) => root.version === version)
         || root.recipe !== plan.recipe.id || root.subject !== plan.subject || !Array.isArray(root.completedSteps)) {
         throw new CliUsageError('Investigation resume state must match this versioned recipe and subject.');
     }
@@ -155,14 +212,20 @@ function parseResumeState(input, plan) {
     if (root.version === 1 && root.selections !== undefined) {
         throw new CliUsageError('Investigation resume state version 1 cannot contain analyst selections.');
     }
+    const bindings = root.version === CLI_INVESTIGATION_RUN_VERSION ? normalizeWorkflowBindings(plan, root.artifactBindings) : [];
+    if (root.version !== CLI_INVESTIGATION_RUN_VERSION && root.artifactBindings !== undefined) {
+        throw new CliUsageError('Legacy investigation checkpoints cannot declare artefact bindings.');
+    }
+    validateSelectedInputs(plan, selections, bindings, []);
     const selectionsByStep = new Map(selections.map((item) => [item.stepId, item.values]));
     if (root.completedSteps.length > plan.steps.length) {
         throw new CliUsageError('Investigation resume state contains more steps than the installed fixed recipe.');
     }
     const completed = [];
+    let retryableStepId = null;
     for (const [index, value] of root.completedSteps.entries()) {
         const baseStep = plan.steps[index];
-        const planned = baseStep ? selectedStep(baseStep, selectionsByStep.get(baseStep.id) ?? []) : null;
+        const planned = baseStep ? selectedStep(baseStep, selectionsByStep.get(baseStep.id) ?? [], bindings, completed) : null;
         if (!planned || !value || typeof value !== 'object' || Array.isArray(value)) {
             throw new CliUsageError('Investigation resume state contains a malformed or out-of-order step.');
         }
@@ -175,15 +238,23 @@ function parseResumeState(input, plan) {
             throw new CliUsageError('Investigation resume state does not match the installed fixed recipe.');
         }
         const exitCode = Number(item.exitCode);
-        if (exitCode !== 0 && exitCode !== 2) {
+        const { disposition, artifact } = stepDisposition(planned, exitCode, item.result, true);
+        const { inputs } = resolveStepInputs(planned, bindings, completed);
+        if (root.version === CLI_INVESTIGATION_RUN_VERSION) {
+            if (!isDeepStrictEqual(item.artifact, artifact) || !isDeepStrictEqual(item.inputs, inputs)) {
+                throw new CliUsageError('Investigation checkpoint artefact identity or input bindings do not match the retained results.');
+            }
+        }
+        else if (item.artifact !== undefined || item.inputs !== undefined) {
+            throw new CliUsageError('Legacy investigation steps cannot declare artefact identities.');
+        }
+        if (disposition === 'failed') {
             if (index !== root.completedSteps.length - 1) {
                 throw new CliUsageError('A failed investigation step must be the final retained step.');
             }
+            retryableStepId = planned.id;
             break;
         }
-        if (resultSchema(item.result) !== planned.produces) {
-            throw new CliUsageError('Investigation resume state contains output from an unexpected command contract.');
-        }
         completed.push(Object.freeze({
             id: planned.id,
             command: planned.command,
@@ -191,27 +262,122 @@ function parseResumeState(input, plan) {
             mode: planned.mode,
             exitCode,
             result: item.result,
+            artifact,
+            inputs,
         }));
     }
-    return Object.freeze({ completed: Object.freeze(completed), selections });
+    validateSelectedInputs(plan, selections, bindings, completed);
+    return Object.freeze({ completed: Object.freeze(completed), selections, bindings, retryableStepId });
 }
-export async function runInvestigationRecipe(recipe, subjectValue, options) {
+function prepareInvestigationInvocation(recipe, subjectValue, options) {
     if (!isRunnableInvestigationRecipe(recipe)) {
         throw new CliUsageError('workflow-run supports only installed recipes whose exact steps satisfy the execution contract.');
     }
     const plan = buildInvestigationPlan(recipe, subjectValue, options.generatedAt);
     const prior = parseResumeState(options.resumeInput, plan);
     const suppliedSelections = normalizeInvocationSelections(plan, options.selections ?? []);
-    const selections = mergeSelections(plan, prior.selections, suppliedSelections, prior.completed);
+    // A complete explicit input list replaces a not-yet-run step's standard or
+    // retained connections. Partial lists fill the remaining unbound slots.
+    const explicitSteps = new Set(suppliedSelections.filter(selection => selection.values.length === placeholderCount(plan.steps.find(step => step.id === selection.stepId))
+        && !prior.completed.some(step => step.id === selection.stepId)).map(selection => selection.stepId));
+    const initialBindings = options.resumeInput === null ? workflowStandardInputs(recipe) : prior.bindings;
+    const bindings = mergeBindings(plan, initialBindings.filter(binding => !explicitSteps.has(binding.stepId)), normalizeWorkflowBindings(plan, options.artifactBindings ?? []), prior.completed);
+    const selections = mergeSelections(plan, prior.selections, suppliedSelections, prior.completed, bindings);
+    validateSelectedInputs(plan, selections, bindings, prior.completed);
+    return { plan, prior, bindings, selections };
+}
+/** Validate exactly what execution would resume, without an executor or authority. */
+export function previewInvestigationRecipe(recipe, subjectValue, options) {
+    const { plan, prior, bindings, selections } = prepareInvestigationInvocation(recipe, subjectValue, options);
+    const selected = new Map(selections.map(item => [item.stepId, item.values]));
+    const steps = plan.steps.map(base => {
+        const retained = prior.completed.find(item => item.id === base.id);
+        const step = selectedStep(base, selected.get(base.id) ?? [], bindings, prior.completed);
+        let input = 0;
+        const inputs = base.arguments.flatMap((argument, index) => {
+            if (!PLACEHOLDER_PATTERN.test(argument))
+                return [];
+            input++;
+            const binding = bindings.find(item => item.stepId === base.id && item.input === input);
+            const source = binding ? prior.completed.find(item => item.id === binding.sourceStepId) : undefined;
+            return [{
+                    input, placeholder: argument,
+                    state: binding ? source?.artifact ? 'validated_output' : 'awaiting_output'
+                        : PLACEHOLDER_PATTERN.test(step.arguments[index]) ? 'unresolved' : 'selected_file_or_value',
+                    sourceStepId: binding?.sourceStepId ?? null,
+                    artifactId: source?.artifact?.id ?? null,
+                    value: binding ? null : PLACEHOLDER_PATTERN.test(step.arguments[index]) ? null : step.arguments[index],
+                }];
+        });
+        return {
+            id: step.id, label: step.label, command: step.command, mode: step.mode,
+            state: retained ? retained.exitCode === EXIT_CODES.PARTIAL_FAILURE ? 'retained_partial' : 'retained_complete'
+                : prior.retryableStepId === step.id ? 'retryable_failure' : 'remaining',
+            artifact: retained?.artifact ?? null, inputs,
+            networkApprovalRequired: !retained && step.mode === 'network',
+            reviewDeclarationsRequired: retained ? [] : workflowReviewDeclarations(step),
+            arguments: step.arguments,
+        };
+    });
+    return {
+        schema: CLI_INVESTIGATION_PREVIEW_SCHEMA, version: CLI_INVESTIGATION_PREVIEW_VERSION,
+        generatedAt: options.generatedAt, recipe, subject: plan.subject, steps,
+        requestsExecuted: 0, checkpointWritten: false,
+        limitations: [
+            'This preview validates retained results and connections but does not open selected input files, execute steps, or grant approvals.',
+            'Retained partial observations are reused as partial, not silently recollected. Failed steps remain retryable.',
+            'File paths and selected values are included in this local preview. Review them before sharing.',
+        ],
+    };
+}
+export function formatInvestigationPreview(document) {
+    return [
+        `Workflow preview: ${document.recipe}`, `Subject: ${document.subject}`,
+        'Offline inspection only; no requests or checkpoint writes.',
+        ...document.steps.flatMap(step => [
+            `${step.id}: ${step.state.replaceAll('_', ' ')} · ${step.label}`,
+            ...(step.artifact ? [`  Retained: ${step.artifact.schema} v${step.artifact.version} · ${step.artifact.id}`] : []),
+            ...step.inputs.map(input => `  Input ${input.input}: ${input.state.replaceAll('_', ' ')}${input.sourceStepId ? ` from ${input.sourceStepId}` : ''}${input.value ? ` · ${input.value}` : ''}`),
+            ...(step.networkApprovalRequired ? ['  Requires fresh network approval.'] : []),
+            ...(step.reviewDeclarationsRequired.length ? [`  Requires human review: ${step.reviewDeclarationsRequired.join(', ')}.`] : []),
+        ]),
+        ...document.limitations, '',
+    ].join('\n');
+}
+export async function runInvestigationRecipe(recipe, subjectValue, options) {
+    const prepared = prepareInvestigationInvocation(recipe, subjectValue, options);
+    const { plan, prior, bindings } = prepared;
+    let selections = prepared.selections;
+    const confirmedReviews = options.confirmedReviews ?? [];
+    if (!Array.isArray(confirmedReviews) || confirmedReviews.length > plan.steps.length
+        || new Set(confirmedReviews).size !== confirmedReviews.length
+        || confirmedReviews.some(id => !plan.steps.some(step => step.id === id && workflowReviewDeclarations(step).length))) {
+        throw new CliUsageError('--confirm-review must name each selected review-declaration step at most once.');
+    }
     const selectionsByStep = new Map(selections.map((item) => [item.stepId, item.values]));
     const completed = [...prior.completed];
-    let state = 'complete';
+    let state = completed.some((step) => step.exitCode === EXIT_CODES.PARTIAL_FAILURE) ? 'partial' : 'complete';
     let currentStep = null;
     for (const baseStep of plan.steps) {
         options.signal?.throwIfAborted();
-        const step = selectedStep(baseStep, selectionsByStep.get(baseStep.id) ?? []);
+        let step = selectedStep(baseStep, selectionsByStep.get(baseStep.id) ?? [], bindings, completed);
         if (completed.some((item) => item.id === step.id))
             continue;
+        const missingInputs = step.arguments.filter(argument => PLACEHOLDER_PATTERN.test(argument));
+        if (missingInputs.length && options.selectInputs) {
+            const supplied = await options.selectInputs({ stepId: step.id, label: step.label, inputs: missingInputs });
+            options.signal?.throwIfAborted();
+            if (!Array.isArray(supplied) || supplied.length > missingInputs.length)
+                throw new CliUsageError('Interactive selections exceed the remaining fixed-recipe inputs.');
+            if (supplied.length) {
+                const values = [...(selectionsByStep.get(step.id) ?? []), ...supplied];
+                const added = normalizeRetainedSelections(plan, [{ stepId: step.id, values }], 'Interactive selections');
+                selections = mergeSelections(plan, selections, added, completed, bindings);
+                validateSelectedInputs(plan, selections, bindings, completed);
+                selectionsByStep.set(step.id, values);
+                step = selectedStep(baseStep, values, bindings, completed);
+            }
+        }
         currentStep = step;
         if (step.arguments.some((argument) => /^<[^>]+>$/u.test(argument))) {
             state = 'awaiting_analyst_selection';
@@ -221,14 +387,19 @@ export async function runInvestigationRecipe(recipe, subjectValue, options) {
             state = 'awaiting_network_approval';
             break;
         }
-        const result = await options.execute(step.command, step.arguments);
+        if (workflowReviewDeclarations(step).length && !confirmedReviews.includes(step.id)) {
+            state = 'awaiting_review_confirmation';
+            break;
+        }
+        validateSelectedInputs(plan, selections, bindings, completed);
+        const { files, inputs } = resolveStepInputs(step, bindings, completed);
+        const result = await options.execute(step.command, step.arguments, files);
+        options.signal?.throwIfAborted();
         if (result.exitCode === EXIT_CODES.CANCELLED) {
             throw options.signal?.reason || new DOMException('Cancelled', 'AbortError');
         }
         const parsedResult = boundedResult(result.stdout);
-        if ((result.exitCode === 0 || result.exitCode === 2) && resultSchema(parsedResult) !== step.produces) {
-            throw new CliUsageError(`Investigation step ${step.id} returned an unexpected command contract.`);
-        }
+        const { disposition, artifact } = stepDisposition(step, result.exitCode, parsedResult);
         completed.push(Object.freeze({
             id: step.id,
             command: step.command,
@@ -236,11 +407,17 @@ export async function runInvestigationRecipe(recipe, subjectValue, options) {
             mode: step.mode,
             exitCode: result.exitCode,
             result: parsedResult,
+            artifact,
+            inputs,
         }));
-        if (result.exitCode !== 0 && result.exitCode !== 2) {
+        if (disposition === 'failed') {
             state = 'step_failed';
             break;
         }
+        if (disposition === 'partial') {
+            state = 'partial';
+            break;
+        }
         currentStep = null;
     }
     return Object.freeze({
@@ -251,23 +428,67 @@ export async function runInvestigationRecipe(recipe, subjectValue, options) {
         subject: plan.subject,
         state,
         networkApprovedForThisRun: options.approveNetwork,
+        reviewsConfirmedForThisRun: Object.freeze([...confirmedReviews]),
         selections: Object.freeze(selections),
+        artifactBindings: bindings,
         completedSteps: Object.freeze(completed),
         currentStep,
         limitations: Object.freeze([
             'Only commands and arguments from the installed fixed recipe can execute; no shell, script, arbitrary command, or enforcement action is accepted.',
             'Network steps run only with --approve-network for the current invocation. Unresolved analyst selections pause; supplied values replace exact placeholders and are passed as arguments without shell interpretation.',
+            'Steps declaring human review require --confirm-review for that exact step in the current invocation. Confirm only after reviewing its selected material and each listed declaration; checkpoint metadata never grants permission to another step.',
             'A resume file is a local checkpoint and can retain selected local paths or values. It is not proof that prior evidence remains current or that a human reviewed each stored result.',
+            'Standard and explicit artefact bindings reuse validated compatible earlier outputs without temporary extraction files. Full explicit input lists override uncompleted step connections. Resumes preserve their recorded connections; no new standard inputs are added to an older checkpoint. Content digests identify retained JSON, not source authenticity or currency.',
+            'An incomplete collection pauses for review. Resuming retains it without recollection; the run remains partial even after later steps finish. Failed validation or export steps are retried, not accepted as evidence.',
         ]),
     });
 }
+export function investigationRunExitCode(document) {
+    if (document.state === 'step_failed') {
+        const code = document.completedSteps.at(-1)?.exitCode;
+        return typeof code === 'number' && code !== EXIT_CODES.SUCCESS && Object.values(EXIT_CODES).some((known) => code === known)
+            ? code : EXIT_CODES.INTERNAL_ERROR;
+    }
+    return document.completedSteps.some((step) => step.exitCode === EXIT_CODES.PARTIAL_FAILURE)
+        ? EXIT_CODES.PARTIAL_FAILURE : EXIT_CODES.SUCCESS;
+}
 export function formatInvestigationRun(document) {
+    const stepLabel = document.state === 'step_failed' ? 'Failed' : document.state === 'partial' ? 'Review' : 'Next';
+    const plan = buildInvestigationPlan(document.recipe, document.subject, document.generatedAt);
+    const accepted = document.completedSteps.filter(step => step.artifact);
+    const current = document.currentStep;
+    const inputs = current?.arguments.flatMap((argument, position) => {
+        if (!PLACEHOLDER_PATTERN.test(argument))
+            return [];
+        // Slots refer to the fixed recipe, including inputs already bound or selected.
+        const base = plan.steps.find(step => step.id === current.id);
+        const input = base.arguments.slice(0, position + 1).filter(value => PLACEHOLDER_PATTERN.test(value)).length;
+        const compatible = workflowInputSchemas(current.command);
+        const reusable = accepted.filter(step => step.artifact && compatible.includes(step.artifact.schema));
+        return [
+            `Input ${current.id}:${input}  ${argument} — --select ${current.id}=<path-or-value>`,
+            ...reusable.map(source => `  Reuse deliberately: --use-artifact ${current.id}:${input}=${source.id}`),
+        ];
+    }) ?? [];
     return [
         `Investigation run: ${document.recipe}`,
         `Subject    ${document.subject}`,
         `State      ${document.state.replaceAll('_', ' ')}`,
-        `Completed  ${document.completedSteps.length}`,
-        ...(document.currentStep ? [`Next       ${document.currentStep.label}`, `Approval   ${document.currentStep.approval.replaceAll('_', ' ')}`] : []),
+        `Progress   ${accepted.length} of ${plan.steps.length} steps retained`,
+        ...accepted.map(step => `  ${step.id}: ${step.exitCode === EXIT_CODES.PARTIAL_FAILURE ? 'partial observation' : 'completed'} · ${step.artifact.schema} v${step.artifact.version} · ${step.artifact.id}`),
+        ...(document.currentStep ? [
+            `${stepLabel.padEnd(11)}${document.currentStep.label}`,
+            ...(document.state === 'partial' || document.state === 'step_failed' ? [] : [`Approval   ${document.currentStep.approval.replaceAll('_', ' ')}`]),
+        ] : []),
+        ...inputs,
+        ...(document.state === 'awaiting_network_approval' ? ['Continue with --approve-network only after reviewing the next command’s network disclosure.'] : []),
+        ...(document.state === 'awaiting_review_confirmation' && current ? [
+            `Declarations: ${workflowReviewDeclarations(current).join(', ')}`,
+            `After reviewing the selected material, continue with --confirm-review ${current.id}.`,
+        ] : []),
+        ...(current ? ['Keep the JSON checkpoint with --json --output <run.json>, then continue the same recipe and subject with --resume <run.json>.'] : [
+            document.state === 'partial' ? 'All steps have run; retained incomplete observations remain incomplete.' : 'All recipe steps have run. This is not an analyst verdict or proof that every finding is resolved.',
+        ]),
         '',
     ].join('\n');
 }