@slicedearth/whoisleuth-cli 2.2.0 → 2.4.0

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 { 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, } 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([]) });
     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,6 +212,11 @@ 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.');
@@ -162,7 +224,7 @@ function parseResumeState(input, plan) {
     const completed = [];
     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 +237,22 @@ 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.');
             }
             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 +260,58 @@ 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 });
 }
 export async function runInvestigationRecipe(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 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 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);
+    let selections = mergeSelections(plan, prior.selections, suppliedSelections, prior.completed, bindings);
+    validateSelectedInputs(plan, selections, bindings, prior.completed);
     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 +321,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 +341,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 +362,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');
 }

package/cli/local-document-checkpoint.mjs

@@ -0,0 +1,170 @@
+import { createHash } from 'node:crypto';
+import { lstat, open, realpath, unlink } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { decodeBoundedUtf8, readBoundedRegularFile } from "../lib/bounded-file.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { writePrivateFile } from "./output-file.mjs";
+function missing(error) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
+}
+async function canonicalPath(value, allowMissing, label) {
+    const absolute = resolve(value);
+    if (basename(absolute).endsWith('.workflow.lock'))
+        throw new CliUsageError('The .workflow.lock suffix is reserved for workflow file ownership.');
+    try {
+        const metadata = await lstat(absolute);
+        if (!metadata.isFile() || metadata.nlink !== 1) {
+            throw new CliUsageError(`${label} files must be regular files without symbolic or additional hard links.`);
+        }
+        return await realpath(absolute);
+    }
+    catch (error) {
+        if (!allowMissing || !missing(error))
+            throw error;
+        return join(await realpath(dirname(absolute)), basename(absolute));
+    }
+}
+async function snapshot(path, maximumBytes, label, signal) {
+    let before;
+    try {
+        before = await lstat(path);
+    }
+    catch (error) {
+        if (missing(error))
+            return null;
+        throw error;
+    }
+    if (!before.isFile() || before.nlink !== 1)
+        throw new CliUsageError(`${label} files must be regular files without links.`);
+    const bytes = await readBoundedRegularFile(path, {
+        maximumBytes, label: `${label} file`, ...(signal ? { signal } : {}),
+    });
+    const after = await lstat(path);
+    if (!after.isFile() || after.nlink !== 1 || before.dev !== after.dev || before.ino !== after.ino
+        || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || before.size !== after.size) {
+        throw new CliUsageError(`${label} file changed while it was being read.`);
+    }
+    return {
+        identity: { device: after.dev, inode: after.ino, modified: after.mtimeMs, changed: after.ctimeMs,
+            bytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') },
+        text: decodeBoundedUtf8(bytes, `${label} file`),
+    };
+}
+async function ownsLease(lease) {
+    try {
+        const current = await lstat(lease.path);
+        return current.isFile() && current.nlink === 1 && current.dev === lease.device && current.ino === lease.inode;
+    }
+    catch (error) {
+        if (missing(error))
+            return false;
+        throw error;
+    }
+}
+/** One selected document write, holding source and destination ownership until publication. */
+export async function prepareLocalDocumentWrite(options) {
+    if (![options.maximumInputBytes, options.maximumOutputBytes].every(value => Number.isSafeInteger(value) && value > 0)) {
+        throw new TypeError('Local document byte limits must be positive safe integers.');
+    }
+    const label = options.label;
+    const leases = [];
+    let released = false;
+    let published = false;
+    async function release() {
+        released = true;
+        let unresolved = 0;
+        for (const lease of leases.splice(0).reverse()) {
+            try {
+                if (await ownsLease(lease))
+                    await unlink(lease.path);
+                else
+                    unresolved += 1;
+            }
+            catch {
+                unresolved += 1;
+            }
+        }
+        return unresolved;
+    }
+    try {
+        options.signal?.throwIfAborted();
+        const destination = await canonicalPath(options.destination, true, label);
+        const source = options.source ? await canonicalPath(options.source, false, label) : null;
+        if (source === destination && options.allowSourceReplacement === false) {
+            throw new CliUsageError(`${label} review output must use a different path from its source file.`);
+        }
+        const paths = [...new Set([destination, ...(source ? [source] : [])])].sort();
+        for (const path of paths) {
+            options.signal?.throwIfAborted();
+            const leasePath = join(dirname(path), `.${basename(path)}.workflow.lock`);
+            let handle;
+            try {
+                handle = await open(leasePath, 'wx', 0o600);
+            }
+            catch (error) {
+                if (error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST') {
+                    throw new CliUsageError(`${label} is already locked. Wait for its owner; after an interrupted process, inspect and remove only its abandoned .workflow.lock file.`);
+                }
+                throw error;
+            }
+            try {
+                const identity = await handle.stat();
+                leases.push({ path: leasePath, device: identity.dev, inode: identity.ino });
+                await handle.writeFile(`${JSON.stringify({ pid: process.pid })}\n`, 'utf8');
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        const snapshots = new Map();
+        let sourceInput = null;
+        for (const path of paths) {
+            const value = await snapshot(path, options.maximumInputBytes, label, options.signal);
+            if (path === source) {
+                if (!value)
+                    throw new CliUsageError(`${label} source file disappeared before it could be read.`);
+                sourceInput = value.text;
+            }
+            if (path === destination && value && !options.force) {
+                throw new CliUsageError(`${label} output already exists; use --force to replace it or choose another path.`);
+            }
+            snapshots.set(path, value?.identity ?? null);
+        }
+        async function assertUnchanged() {
+            if (released)
+                throw new CliUsageError(`${label} file ownership has already been released.`);
+            options.signal?.throwIfAborted();
+            for (const lease of leases) {
+                if (!await ownsLease(lease))
+                    throw new CliUsageError(`${label} file ownership changed; output was not published.`);
+            }
+            for (const [path, expected] of snapshots) {
+                const actual = (await snapshot(path, options.maximumInputBytes, label, options.signal))?.identity ?? null;
+                if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+                    throw new CliUsageError(`${label} changed during execution; output was not published. Review the current files before resuming.`);
+                }
+            }
+        }
+        return Object.freeze({
+            sourceInput,
+            async publish(content) {
+                if (published || released)
+                    throw new CliUsageError(`${label} file publication has already settled.`);
+                if (Buffer.byteLength(content, 'utf8') > options.maximumOutputBytes) {
+                    throw new CliUsageError(`${label} output is limited to ${options.maximumOutputBytes} bytes.`);
+                }
+                await writePrivateFile(destination, content, { force: options.force, beforePublish: assertUnchanged });
+                published = true;
+            },
+            release,
+        });
+    }
+    catch (error) {
+        const unresolved = await release();
+        if (unresolved) {
+            throw new CliUsageError(`${label} file preparation failed and lease cleanup could not be verified. Inspect the selected directory before resuming.`);
+        }
+        throw error;
+    }
+}

package/cli/lookalike-calibration.mjs

@@ -6,7 +6,9 @@ const LOOKALIKE_CALIBRATION_VERSION = 1;
 const MAX_LOOKALIKE_CALIBRATION_BYTES = 2 * 1024 * 1024;
 const MAX_LOOKALIKE_CALIBRATION_RECORDS = 5_000;
 const MIN_LOOKALIKE_CALIBRATION_SAMPLE = 20;
-const DISPOSITIONS = ['suspicious', 'confirmed_abuse', 'false_positive', 'expected', 'closed_no_action'];
+// Version 1 intentionally admits reviewed Case dispositions only. This local
+// schema remains an independent compatibility decision from the live Case model.
+const DISPOSITIONS = Object.freeze(['suspicious', 'confirmed_abuse', 'false_positive', 'expected', 'closed_no_action']);
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
@@ -22,7 +24,10 @@ function ratio(value, total) {
     return total ? Number((value / total).toFixed(4)) : 0;
 }
 function emptyCounts() {
-    return { suspicious: 0, confirmed_abuse: 0, false_positive: 0, expected: 0, closed_no_action: 0 };
+    const counts = {};
+    for (const disposition of DISPOSITIONS)
+        counts[disposition] = 0;
+    return counts;
 }
 function buildLookalikeCalibration(raw, generatedAt = new Date().toISOString()) {
     if (Buffer.byteLength(raw, 'utf8') > MAX_LOOKALIKE_CALIBRATION_BYTES) {

package/cli/lookup-brief.mjs

@@ -111,8 +111,10 @@ export function buildCliLookupBrief(input, generatedAt = new Date().toISOString(
     const facts = [
         ['registration-state', 'Registration state', availability.state, availabilitySource.id],
         ['registrar', 'Registrar', record(preferred.registrar).name ?? preferred.registrar, preferredRegistrationSource.id],
-        ['created', 'Created', record(preferred.lifecycle).createdIso ?? preferred.createdDateIso, preferredRegistrationSource.id],
-        ['expires', 'Expires', record(preferred.lifecycle).expiryIso ?? preferred.expiryDateIso, preferredRegistrationSource.id],
+        ['created', 'Created', record(preferred.lifecycle).createdDateIso
+                ?? record(preferred.lifecycle).createdIso ?? preferred.createdDateIso, preferredRegistrationSource.id],
+        ['expires', 'Expires', record(preferred.lifecycle).expiryDateIso
+                ?? record(preferred.lifecycle).expiryIso ?? preferred.expiryDateIso, preferredRegistrationSource.id],
         ['name-servers', 'Name servers', joinedText(preferred.nameservers), preferredRegistrationSource.id],
         ['website-activity', 'Website activity', availability.activityStatus, httpSource.id],
         ['page-title', 'Page title', availability.pageTitle, httpSource.id],

package/cli/lookup-browser-view.mjs

@@ -2,7 +2,7 @@ import { formatTerminalLookup, safeTerminalValue } from "./formatters/terminal.m
 import { presentTerminalOutput, wrapTerminalOutput, } from "./terminal-presentation.mjs";
 const MIN_LOOKUP_BROWSER_HEIGHT = 12;
 const MAX_LOOKUP_BROWSER_HEIGHT = 80;
-const MAX_LOOKUP_BROWSER_PANELS = 9;
+const MAX_LOOKUP_BROWSER_PANELS = 16;
 const MAX_LOOKUP_BROWSER_SEARCH_BYTES = 256;
 const MAX_LOOKUP_BROWSER_SEARCH_SCALARS = 80;
 const MAX_LOOKUP_BROWSER_SEARCH_MATCHES = 256;

package/cli/lookup-browser.mjs

@@ -1,4 +1,5 @@
 import { StringDecoder } from 'node:string_decoder';
+import { canReadInteractiveLine } from "./terminal-input.mjs";
 import { safeTerminalValue } from "./formatters/terminal.mjs";
 import { terminalPresentation, } from "./terminal-presentation.mjs";
 import { MIN_LOOKUP_BROWSER_HEIGHT, MAX_LOOKUP_BROWSER_PANELS, MAX_LOOKUP_BROWSER_SEARCH_BYTES, MAX_LOOKUP_BROWSER_SEARCH_MATCHES, MAX_LOOKUP_BROWSER_SEARCH_SCALARS, boundedBrowserDimensions, boundedSearchText, buildLookupBrowserHelpFrame, buildLookupBrowserFrame, buildLookupBrowserPanels, buildLookupBrowserSearchFrame, buildLookupCollectionFrame, findLookupBrowserMatches, renderedPanelLineOffset, renderLookupBrowser, terminalDisplayWidth, } from "./lookup-browser-view.mjs";
@@ -10,18 +11,10 @@ const MAX_PENDING_INPUT_LENGTH = 512;
 const MAX_LOOKUP_BROWSER_INPUT_CHUNK_BYTES = 2_048;
 const COMPLETE_CSI_RE = /^\u001b\[[0-?]*[ -/]*[@-~]/u;
 function canBrowseLookup(input, output, environment = process.env) {
-    return input?.isTTY === true
-        && output?.isTTY === true
-        && typeof input.setRawMode === 'function'
-        && typeof input.resume === 'function'
-        && typeof input.pause === 'function'
-        && typeof input.on === 'function'
-        && typeof input.off === 'function'
-        && typeof output.write === 'function'
-        && !(Number.isFinite(output.columns) && Number(output.columns) < 40)
-        && !(Number.isFinite(output.rows) && Number(output.rows) < MIN_LOOKUP_BROWSER_HEIGHT)
-        && environment.TERM !== 'dumb'
-        && !environment.CI;
+    return canReadInteractiveLine(input, output, environment)
+        && !(Number.isFinite(output?.columns) && Number(output?.columns) < 40)
+        && !(Number.isFinite(output?.rows) && Number(output?.rows) < MIN_LOOKUP_BROWSER_HEIGHT)
+        && environment.TERM !== 'dumb';
 }
 function runLookupBrowserSession(options) {
     const environment = options.environment || process.env;