@slicedearth/whoisleuth-cli 1.43.0 → 1.45.0

package/README.md

@@ -90,8 +90,8 @@ and disclosures without making a network request. `commands --json` exposes the
 installed command contracts for local wrappers without running collection.
 Focused command help and the generated manual label every operation as offline
 or networked and state its target, input, and concurrency boundaries. The
-packaged [dual-use disclosure](DISCLOSURE) defines the supported defensive use
-of those capabilities.
+packaged [dual-use disclosure](https://github.com/slicedearth/whoisleuth/blob/main/DISCLOSURE)
+defines the supported defensive use of those capabilities.
 
 Interactive output uses restrained semantic colour, width-aware wrapping, and
 stderr-only progress for slower collection. Redirected and machine-readable
@@ -101,9 +101,13 @@ offline unless `--network` is explicitly supplied, and completion scripts are
 printed without modifying shell configuration. Commands can use atomic private
 `--output` files, Lookup can emit strict automation exits and target-free
 versioned progress events, and Bulk can resume an exact validated compact
-checkpoint. A checkpoint write failure preserves completed output and returns
+checkpoint. Checkpoint schema 2 preserves each current row's observation time;
+legacy schema-1 rows remain readable with unknown observation time rather than
+being restamped on resume. Bulk machine output schema 3 distinguishes current
+and resumed rows. A checkpoint write failure preserves completed output and returns
 the partial-result exit code. Ctrl-C suppresses partial final output and
-returns exit code 130; a second interrupt performs best-effort temporary-file
+returns exit code 130. SIGTERM uses the same graceful cleanup path and returns
+143; a second interrupt performs best-effort temporary-file
 cleanup before exiting immediately.
 Strict local profiles can supply only safe presentation, Fast-mode,
 concurrency, and observer defaults; command-line options override them.

package/bin/whoisleuth.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
+import EXIT_CODES from "../cli/exit-codes.mjs";
 for (const stream of [process.stdout, process.stderr]) {
     stream.on('error', (error) => {
         if (error.code === 'EPIPE')
@@ -32,32 +33,42 @@ else {
     }
     catch (error) {
         process.stderr.write(`Usage error: ${errorsModule.boundedCliErrorMessage(error, 'Invalid CLI profile')}\n`);
-        process.exitCode = 64;
+        process.exitCode = EXIT_CODES.USAGE;
         resolvedArgv = [];
     }
     const cancellation = new AbortController();
     let interruptionCount = 0;
-    const interrupt = () => {
+    let requestedExitCode = 130;
+    const interrupt = (signal) => {
         interruptionCount += 1;
-        if (interruptionCount === 1)
+        if (interruptionCount === 1) {
+            requestedExitCode = signal === 'SIGTERM' ? 143 : 130;
             cancellation.abort(new DOMException('Aborted', 'AbortError'));
+        }
         else {
             outputModule.cleanupPendingOutputFilesSync();
-            process.exit(130);
+            process.exit(requestedExitCode);
         }
     };
-    process.on('SIGINT', interrupt);
-    const execution = resolvedArgv.length ? runnerModule.runCli(resolvedArgv, { signal: cancellation.signal }) : Promise.resolve(process.exitCode || 64);
+    const onSigint = () => interrupt('SIGINT');
+    const onSigterm = () => interrupt('SIGTERM');
+    process.on('SIGINT', onSigint);
+    process.on('SIGTERM', onSigterm);
+    const execution = resolvedArgv.length
+        ? runnerModule.runCli(resolvedArgv, { signal: cancellation.signal })
+        : Promise.resolve(process.exitCode || EXIT_CODES.USAGE);
     execution.then((code) => {
         if (code === 130) {
-            process.removeListener('SIGINT', interrupt);
-            process.exit(130);
+            process.removeListener('SIGINT', onSigint);
+            process.removeListener('SIGTERM', onSigterm);
+            process.exit(requestedExitCode);
         }
         process.exitCode = code;
     }).catch((error) => {
         process.stderr.write(`Internal CLI error: ${errorsModule.boundedCliErrorMessage(error)}\n`);
         process.exitCode = 70;
     }).finally(() => {
-        process.removeListener('SIGINT', interrupt);
+        process.removeListener('SIGINT', onSigint);
+        process.removeListener('SIGTERM', onSigterm);
     });
 }

package/cli/bulk-checkpoint.mjs

@@ -1,10 +1,12 @@
 import { createHash } from 'node:crypto';
 import { open } from 'node:fs/promises';
 import { recordOrNull } from "../lib/bounded-contract-normalizers.mjs";
-import { CliUsageError } from "./errors.mjs";
+import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
+import { boundedCliInputError, CliUsageError } from "./errors.mjs";
 import { writePrivateFile } from "./output-file.mjs";
 export const CLI_BULK_CHECKPOINT_SCHEMA = 'whoisleuth.cli.bulk-checkpoint';
-export const CLI_BULK_CHECKPOINT_VERSION = 1;
+export const CLI_BULK_CHECKPOINT_VERSION = 2;
+const SUPPORTED_BULK_CHECKPOINT_VERSIONS = new Set([1, CLI_BULK_CHECKPOINT_VERSION]);
 export const MAX_BULK_CHECKPOINT_BYTES = 16 * 1024 * 1024;
 const MAX_CHECKPOINT_JSON_DEPTH = 12;
 const MAX_CHECKPOINT_OBJECT_KEYS = 256;
@@ -51,7 +53,7 @@ function normalizeCompactResult(value) {
         return null;
     return result;
 }
-function normalizeCheckpointResult(value, queries, classifyQuery) {
+function normalizeCheckpointResult(value, queries, classifyQuery, version = CLI_BULK_CHECKPOINT_VERSION) {
     const item = recordOrNull(value);
     const index = item?.index;
     if (!Number.isSafeInteger(index) || Number(index) < 0 || Number(index) >= queries.length)
@@ -59,10 +61,17 @@ function normalizeCheckpointResult(value, queries, classifyQuery) {
     const query = queries[Number(index)];
     if (typeof item?.query !== 'string' || item.query !== query)
         return null;
+    const observedAt = version >= 2
+        ? item.observedAt === null
+            ? null
+            : validTimestamp(item.observedAt) ? new Date(item.observedAt).toISOString() : undefined
+        : null;
+    if (observedAt === undefined)
+        return null;
     if (item.ok === false) {
         if (typeof item.error !== 'string' || !item.error || item.error.length > 300)
             return null;
-        return { index: Number(index), query, ok: false, error: item.error };
+        return { index: Number(index), query, ok: false, error: item.error, observedAt };
     }
     const result = normalizeCompactResult(item.result);
     if (item.ok !== true || !result)
@@ -71,7 +80,7 @@ function normalizeCheckpointResult(value, queries, classifyQuery) {
     const storedClassified = recordOrNull(item.classified);
     if (storedClassified?.type !== classified.type || storedClassified.value !== classified.value)
         return null;
-    return { index: Number(index), query, ok: true, classified, result };
+    return { index: Number(index), query, ok: true, classified, result, observedAt };
 }
 function parseBulkCheckpoint(text, options) {
     if (typeof text !== 'string' || Buffer.byteLength(text, 'utf8') > MAX_BULK_CHECKPOINT_BYTES) {
@@ -86,8 +95,11 @@ function parseBulkCheckpoint(text, options) {
     }
     const document = recordOrNull(parsed);
     const expectedDigest = checkpointDigest(options.queries, options.deep);
-    if (document?.schema !== CLI_BULK_CHECKPOINT_SCHEMA || document.version !== CLI_BULK_CHECKPOINT_VERSION) {
-        throw new CliUsageError(`Bulk checkpoint must use ${CLI_BULK_CHECKPOINT_SCHEMA} version ${CLI_BULK_CHECKPOINT_VERSION}.`);
+    const version = typeof document?.version === 'number' && Number.isSafeInteger(document.version)
+        ? document.version
+        : 0;
+    if (document?.schema !== CLI_BULK_CHECKPOINT_SCHEMA || !SUPPORTED_BULK_CHECKPOINT_VERSIONS.has(version)) {
+        throw new CliUsageError(`Bulk checkpoint must use ${CLI_BULK_CHECKPOINT_SCHEMA} version 1 or ${CLI_BULK_CHECKPOINT_VERSION}.`);
     }
     if (document.mode !== (options.deep ? 'deep' : 'fast')
         || document.inputDigestSha256 !== expectedDigest
@@ -100,11 +112,11 @@ function parseBulkCheckpoint(text, options) {
     const results = [];
     const seen = new Set();
     for (const candidate of document.results.slice(0, options.queries.length + 1)) {
-        const result = normalizeCheckpointResult(candidate, options.queries, options.classifyQuery);
+        const result = normalizeCheckpointResult(candidate, options.queries, options.classifyQuery, version);
         if (!result || seen.has(result.index))
             throw new CliUsageError('Bulk checkpoint contains an invalid or duplicate result.');
         seen.add(result.index);
-        results.push(result);
+        results.push({ ...result, collectionOrigin: 'resumed_checkpoint' });
     }
     return {
         schema: CLI_BULK_CHECKPOINT_SCHEMA,
@@ -118,16 +130,15 @@ function parseBulkCheckpoint(text, options) {
     };
 }
 async function readCheckpointFile(path) {
-    const handle = await open(path, 'r');
     try {
-        const stats = await handle.stat();
-        if (!stats.isFile() || stats.size > MAX_BULK_CHECKPOINT_BYTES) {
-            throw new CliUsageError(`Bulk checkpoint input is limited to ${MAX_BULK_CHECKPOINT_BYTES} bytes.`);
-        }
-        return await handle.readFile({ encoding: 'utf8' });
+        return await readBoundedRegularTextFile(path, {
+            maximumBytes: MAX_BULK_CHECKPOINT_BYTES,
+            label: 'Bulk checkpoint input',
+            allowSymbolicLink: true,
+        });
     }
-    finally {
-        await handle.close();
+    catch (error) {
+        throw boundedCliInputError(error, 'Bulk checkpoint input');
     }
 }
 async function checkpointFileExists(path) {
@@ -140,11 +151,12 @@ async function checkpointFileExists(path) {
         const code = error && typeof error === 'object' && 'code' in error ? error.code : null;
         if (code === 'ENOENT')
             return false;
-        throw error;
+        throw boundedCliInputError(error, 'Bulk checkpoint input');
     }
 }
 async function createBulkCheckpointWriter(options) {
     const now = options.now || (() => new Date().toISOString());
+    const writeCheckpoint = options.writeFile ?? writePrivateFile;
     const exists = await checkpointFileExists(options.path);
     if (options.resume && !exists)
         throw new CliUsageError('Bulk checkpoint does not exist; remove --resume to start a new checkpoint.');
@@ -155,7 +167,8 @@ async function createBulkCheckpointWriter(options) {
         : null;
     const startedAt = resumed?.startedAt || now();
     const results = new Map((resumed?.results || []).map((item) => [item.index, item]));
-    let chain = Promise.resolve();
+    let activeWrite = null;
+    let dirty = false;
     let writeFailure = null;
     let created = resumed !== null;
     function document() {
@@ -168,19 +181,20 @@ async function createBulkCheckpointWriter(options) {
             queryCount: options.queries.length,
             startedAt,
             updatedAt,
-            results: [...results.values()].sort((left, right) => left.index - right.index),
+            results: [...results.values()]
+                .sort((left, right) => left.index - right.index)
+                .map(({ collectionOrigin: _collectionOrigin, ...result }) => result),
         };
     }
-    function scheduleWrite() {
-        chain = chain.then(async () => {
-            if (writeFailure)
-                return;
+    async function drainWrites() {
+        while (dirty && !writeFailure) {
+            dirty = false;
             try {
                 const content = `${JSON.stringify(document(), null, 2)}\n`;
                 if (Buffer.byteLength(content, 'utf8') > MAX_BULK_CHECKPOINT_BYTES) {
                     throw new CliUsageError(`Bulk checkpoints are limited to ${MAX_BULK_CHECKPOINT_BYTES} bytes.`);
                 }
-                await writePrivateFile(options.path, content, {
+                await writeCheckpoint(options.path, content, {
                     force: created,
                     existingFileMessage: 'Bulk checkpoint already exists; use --resume or choose another path.',
                 });
@@ -189,6 +203,23 @@ async function createBulkCheckpointWriter(options) {
             catch (error) {
                 writeFailure = error;
             }
+        }
+    }
+    function scheduleWrite() {
+        dirty = true;
+        if (activeWrite || writeFailure)
+            return;
+        const pending = drainWrites();
+        activeWrite = pending;
+        void pending.then(() => {
+            if (activeWrite === pending)
+                activeWrite = null;
+            if (dirty && !writeFailure)
+                scheduleWrite();
+        }, (error) => {
+            writeFailure ||= error;
+            if (activeWrite === pending)
+                activeWrite = null;
         });
     }
     if (!resumed)
@@ -196,16 +227,22 @@ async function createBulkCheckpointWriter(options) {
     return Object.freeze({
         initialResults: Object.freeze([...results.values()].sort((left, right) => left.index - right.index)),
         record(result) {
-            const normalized = normalizeCheckpointResult(result, options.queries, options.classifyQuery);
+            const observedAt = validTimestamp(result.observedAt) ? new Date(result.observedAt).toISOString() : now();
+            const normalized = normalizeCheckpointResult({ ...result, observedAt }, options.queries, options.classifyQuery);
             if (!normalized) {
                 writeFailure ||= new CliUsageError('Bulk checkpoint result is not a bounded compact lookup result.');
                 return;
             }
-            results.set(normalized.index, normalized);
+            results.set(normalized.index, { ...normalized, collectionOrigin: 'current_run' });
             scheduleWrite();
         },
         async flush() {
-            await chain;
+            while (activeWrite || dirty) {
+                if (!activeWrite)
+                    scheduleWrite();
+                if (activeWrite)
+                    await activeWrite;
+            }
             if (writeFailure)
                 throw writeFailure;
         },

package/cli/bulk-command-runner.mjs

@@ -26,7 +26,7 @@ async function runBulkCommand(args, dependencies, context) {
             ? await dependencies.readBulkInput(args.source)
             : await readTextStreamBounded(args.source
                 ? createReadStream(args.source, { highWaterMark: 64 * 1024 })
-                : dependencies.stdin || process.stdin, MAX_BULK_INPUT_BYTES);
+                : dependencies.stdin || process.stdin, MAX_BULK_INPUT_BYTES, dependencies.signal);
     }
     catch (error) {
         if (error instanceof CliUsageError)
@@ -56,6 +56,8 @@ async function runBulkCommand(args, dependencies, context) {
         : null;
     const indicator = context.beginProgress(`Collecting 0 of ${parsed.queries.length} targets`);
     let completed = checkpoint?.initialResults.length || 0;
+    const resumedItems = new Map((checkpoint?.initialResults ?? []).map((item) => [item.index, item]));
+    const settledItems = new Map();
     if (completed)
         indicator.update(`Resumed ${completed} of ${parsed.queries.length} targets`);
     let items;
@@ -69,12 +71,23 @@ async function runBulkCommand(args, dependencies, context) {
             ...(checkpoint ? { initialResults: checkpoint.initialResults } : {}),
             ...(dependencies.signal ? { signal: dependencies.signal } : {}),
             onItemSettled: (item) => {
+                const observed = {
+                    ...item,
+                    observedAt: context.now(),
+                    collectionOrigin: 'current_run',
+                };
+                settledItems.set(item.index, observed);
                 completed += 1;
                 indicator.update(`Collected ${completed} of ${parsed.queries.length} targets`);
                 eventProgress.emit({ event: 'item_settled', index: item.index, ok: item.ok });
-                checkpoint?.record(item);
+                checkpoint?.record(observed);
             },
         });
+        items = items.map((item) => resumedItems.get(item.index) ?? settledItems.get(item.index) ?? {
+            ...item,
+            observedAt: null,
+            collectionOrigin: 'current_run',
+        });
     }
     finally {
         context.endProgress();

package/cli/bulk.mjs

@@ -3,17 +3,28 @@ import { abortable } from "../lib/abort.mjs";
 import { CliUsageError } from "./arguments.mjs";
 import { MAX_DEEP_BULK_QUERIES, MAX_FAST_BULK_QUERIES, } from "../lib/bulk-limits.mjs";
 const MAX_BULK_INPUT_BYTES = 1024 * 1024;
-async function readTextStreamBounded(stream, limit = MAX_BULK_INPUT_BYTES) {
+async function readTextStreamBounded(stream, limit = MAX_BULK_INPUT_BYTES, signal) {
     if (!stream || stream.isTTY)
         return '';
+    const abort = () => stream.destroy?.(new DOMException('Aborted', 'AbortError'));
+    if (signal?.aborted)
+        throw new DOMException('Aborted', 'AbortError');
+    signal?.addEventListener('abort', abort, { once: true });
     const chunks = [];
     let total = 0;
-    for await (const chunk of stream) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        total += buffer.length;
-        if (total > limit)
-            throw new CliUsageError(`Bulk input is limited to ${limit} bytes.`);
-        chunks.push(buffer);
+    try {
+        for await (const chunk of stream) {
+            if (signal?.aborted)
+                throw new DOMException('Aborted', 'AbortError');
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buffer.length;
+            if (total > limit)
+                throw new CliUsageError(`Bulk input is limited to ${limit} bytes.`);
+            chunks.push(buffer);
+        }
+    }
+    finally {
+        signal?.removeEventListener('abort', abort);
     }
     return Buffer.concat(chunks).toString('utf8');
 }

package/cli/completion.mjs

@@ -2,9 +2,13 @@ import { CLI_COMMANDS } from "./arguments.mjs";
 import { INVESTIGATION_PLAN_RECIPES } from "./investigation-plan.mjs";
 const COMMON_OPTIONS = Object.freeze(['--help', '--output', '--force', '--config', '--profile']);
 const OPTIONS_BY_COMMAND = Object.freeze({
+    manifest: ['--workflow', '--configuration-digest', '--json', '--quiet', '--no-color'],
+    'map-observations': ['--json', '--quiet', '--no-color'],
+    'oam-export': ['--json', '--quiet', '--no-color'],
     lookup: ['--json', '--junit', '--markdown', '--html', '--fast', '--deep', '--observer', '--vantage', '--plan', '--summary', '--verbose', '--strict-exit', '--fail-on', '--events', '--quiet', '--no-color'],
     bulk: ['--json', '--jsonl', '--junit', '--csv', '--domains', '--queries', '--registered-only', '--inconclusive-only', '--errors-only', '--fast', '--deep', '--concurrency', '--checkpoint', '--resume', '--events', '--plan', '--fail-on', '--quiet', '--no-color'],
     'ct-search': ['--json', '--quiet', '--no-color'],
+    'ct-intake': ['--json', '--quiet', '--no-color'],
     discover: ['--tlds', '--preset', '--families', '--keyboard', '--dictionary', '--snapshot', '--json', '--jsonl', '--domains', '--quiet', '--no-color'],
     'discover-scan': ['--tlds', '--preset', '--families', '--keyboard', '--dictionary', '--fast', '--deep', '--scan-limit', '--chunk-size', '--concurrency', '--resolver', '--allowlist', '--checkpoint', '--resume', '--observation-snapshot', '--registered-only', '--inconclusive-only', '--acquisition-only', '--suppressed-only', '--events', '--plan', '--fail-on', '--json', '--jsonl', '--csv', '--domains', '--quiet', '--no-color'],
     posture: ['--selectors', '--retired-selectors', '--mail-profile', '--json', '--sarif', '--owned-domain', '--quiet', '--no-color'],
@@ -30,6 +34,7 @@ const OPTIONS_BY_COMMAND = Object.freeze({
     'domain-control': ['--json', '--quiet', '--no-color'],
     'monitor-once': ['--previous', '--limit', '--concurrency', '--fail-on', '--json', '--junit', '--quiet', '--no-color'],
     assurance: ['--json', '--quiet', '--no-color'],
+    'change-packet': ['--json', '--quiet', '--no-color'],
     'sharing-review': ['--marking', '--recipient-scope', '--purpose', '--human-reviewed', '--personal-data-reviewed', '--redactions-confirmed', '--json', '--quiet', '--no-color'],
     'workflow-plan': ['--json', '--quiet', '--no-color'],
     'workflow-run': ['--approve-network', '--resume', '--json', '--quiet', '--no-color'],
@@ -43,9 +48,13 @@ const OPTIONS_BY_COMMAND = Object.freeze({
     manual: [],
 });
 const COMMAND_DESCRIPTIONS = Object.freeze({
+    manifest: 'Build an evidence manifest offline',
+    'map-observations': 'Normalise passive DNS observations offline',
+    'oam-export': 'Export an observation-archive map offline',
     lookup: 'Collect one domain, IP, or ASN',
     bulk: 'Run bounded multi-target collection',
     'ct-search': 'Search certificate observations',
+    'ct-intake': 'Normalise certificate observations offline',
     discover: 'Generate lookalike candidates offline',
     'discover-scan': 'Collect a supervised candidate review queue',
     posture: 'Review DNS and mail posture',
@@ -71,6 +80,7 @@ const COMMAND_DESCRIPTIONS = Object.freeze({
     'domain-control': 'Build or review a domain control manifest',
     'monitor-once': 'Run one bounded domain control review',
     assurance: 'Review domain change, recovery, or retirement plans',
+    'change-packet': 'Build a reviewed change packet offline',
     'sharing-review': 'Lint an artefact before deliberate sharing',
     'workflow-plan': 'Plan a fixed investigation recipe',
     'workflow-run': 'Execute approved fixed-recipe steps',
@@ -106,6 +116,13 @@ const FILE_OPTIONS = Object.freeze([
     '--previous',
     '--resume',
 ]);
+const FILE_POSITIONAL_COMMANDS = new Set([
+    'manifest',
+    'map-observations',
+    'oam-export',
+    'ct-intake',
+    'change-packet',
+]);
 const TEXT_OPTIONS = Object.freeze([
     '--families',
     '--resolver',
@@ -121,7 +138,7 @@ const TEXT_OPTIONS = Object.freeze([
     '--vantage',
 ]);
 function commandOptions(command) {
-    return [...COMMON_OPTIONS, ...(OPTIONS_BY_COMMAND[command] || [])].join(' ');
+    return [...COMMON_OPTIONS, ...OPTIONS_BY_COMMAND[command]].join(' ');
 }
 function bashCompletion() {
     const cases = CLI_COMMANDS.map((command) => `    ${command}) options="${commandOptions(command)}" ;;`).join('\n');
@@ -153,6 +170,9 @@ ${valueCases}
 ${cases}
     *) options="--help" ;;
   esac
+  case " ${[...FILE_POSITIONAL_COMMANDS].join(' ')} " in
+    *" \${command} "*) [[ "\${current}" != -* ]] && COMPREPLY=( $(compgen -f -- "\${current}") ) && return ;;
+  esac
   COMPREPLY=( $(compgen -W "\${options}" -- "\${current}") )
 }
 complete -F _whoisleuth_completion whoisleuth
@@ -190,6 +210,10 @@ ${valueCases}
 ${cases}
     *) options=(--help) ;;
   esac
+  if [[ " ${[...FILE_POSITIONAL_COMMANDS].join(' ')} " == *" \${command} "* && "\${words[CURRENT]}" != -* ]]; then
+    _files
+    return
+  fi
   compadd -- \${options[@]}
 }
 if [[ "\${funcstack[1]}" == "_whoisleuth" ]]; then
@@ -200,7 +224,7 @@ fi
 `;
 }
 function fishCompletion() {
-    const commandLines = CLI_COMMANDS.map((command) => (`complete -c whoisleuth -n '__fish_use_subcommand' -a '${command}' -d '${COMMAND_DESCRIPTIONS[command] || command}'`));
+    const commandLines = CLI_COMMANDS.map((command) => (`complete -c whoisleuth -n '__fish_use_subcommand' -a '${command}' -d '${COMMAND_DESCRIPTIONS[command]}'${FILE_POSITIONAL_COMMANDS.has(command) ? ' -F' : ''}`));
     const optionLine = (condition, option) => {
         const name = option.replace(/^--/u, '');
         const fileValue = FILE_OPTIONS.includes(option);
@@ -226,7 +250,7 @@ ${valueLines.join('\n')}
 function powershellCompletion() {
     const commandOptions = Object.fromEntries(CLI_COMMANDS.map((command) => [
         command,
-        [...COMMON_OPTIONS, ...(OPTIONS_BY_COMMAND[command] || [])],
+        [...COMMON_OPTIONS, ...OPTIONS_BY_COMMAND[command]],
     ]));
     return `# WHOISleuth PowerShell completion
 Register-ArgumentCompleter -Native -CommandName whoisleuth -ScriptBlock {
@@ -240,9 +264,16 @@ ${Object.entries(VALUE_OPTIONS).map(([option, values]) => `    '${option}' = @($
     'completion' = @('bash', 'zsh', 'fish', 'powershell')
     'workflow-plan' = @(${INVESTIGATION_PLAN_RECIPES.map((value) => `'${value}'`).join(', ')})
   }
+  $fileCommands = @(${[...FILE_POSITIONAL_COMMANDS].map((command) => `'${command}'`).join(', ')})
   $elements = @($commandAst.CommandElements | ForEach-Object { $_.Extent.Text })
   $command = if ($elements.Count -gt 1) { $elements[1] } else { '' }
   $previous = if ($elements.Count -gt 1) { $elements[$elements.Count - 1] } else { '' }
+  if ($fileCommands -contains $command -and -not $wordToComplete.StartsWith('-')) {
+    Get-ChildItem -Path "${'$'}wordToComplete*" -File -ErrorAction SilentlyContinue | ForEach-Object {
+      [System.Management.Automation.CompletionResult]::new($_.FullName, $_.Name, 'ProviderItem', $_.FullName)
+    }
+    return
+  }
   $candidates = if ($elements.Count -le 2) {
     @($commands) + @('--help', '--version')
   } elseif ($command -eq 'completion' -and $elements.Count -le 3) {

package/cli/config-profile.mjs

@@ -1,8 +1,8 @@
 import { Buffer } from 'node:buffer';
-import { open } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { CliUsageError } from "./errors.mjs";
+import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
 export const CLI_CONFIG_SCHEMA = 'whoisleuth.cli.config';
 export const CLI_CONFIG_VERSION = 1;
 export const MAX_CLI_CONFIG_BYTES = 64 * 1024;
@@ -91,16 +91,11 @@ function parseProfileDocument(input) {
     return Object.freeze({ schema: CLI_CONFIG_SCHEMA, version: CLI_CONFIG_VERSION, ...(root.defaultProfile ? { defaultProfile: root.defaultProfile } : {}), profiles: Object.freeze(profiles) });
 }
 async function readConfigFile(path) {
-    const handle = await open(path, 'r');
-    try {
-        const metadata = await handle.stat();
-        if (metadata.size > MAX_CLI_CONFIG_BYTES)
-            throw new CliUsageError('CLI configuration is limited to 64 KiB.');
-        return await handle.readFile({ encoding: 'utf8' });
-    }
-    finally {
-        await handle.close();
-    }
+    return readBoundedRegularTextFile(path, {
+        maximumBytes: MAX_CLI_CONFIG_BYTES,
+        label: 'CLI configuration',
+        allowSymbolicLink: true,
+    });
 }
 function suppliedGroups(argumentsList) {
     const groups = new Set();
@@ -114,6 +109,14 @@ function suppliedGroups(argumentsList) {
     return groups;
 }
 export async function resolveCliProfileArguments(argv, options = {}) {
+    // registry-scaffold owns --profile as the capability template to generate.
+    // Do not reinterpret it as a global CLI-default profile.
+    if (argv[0] === 'registry-scaffold') {
+        if (argv.includes('--config')) {
+            throw new CliUsageError('registry-scaffold does not accept global CLI configuration options.');
+        }
+        return [...argv];
+    }
     const retained = [];
     let configPath = null;
     let profileName = null;
@@ -153,7 +156,7 @@ export async function resolveCliProfileArguments(argv, options = {}) {
     catch (error) {
         if (error instanceof CliUsageError)
             throw error;
-        throw new CliUsageError(`Could not read CLI configuration from ${selectedPath}.`);
+        throw new CliUsageError('CLI configuration could not be read as a bounded regular file.');
     }
     const document = parseProfileDocument(input);
     const selectedName = profileName || document.defaultProfile;

package/cli/discovery-observation-snapshot.mjs

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto';
-import { open } from 'node:fs/promises';
 import { availabilityState, bulkDnsSummary } from "./bulk-output.mjs";
-import { CliUsageError } from "./errors.mjs";
+import { boundedCliInputError, CliUsageError } from "./errors.mjs";
 import { writePrivateFile } from "./output-file.mjs";
 import { isValidAsciiDomainName } from "../lib/hostname.mjs";
+import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
 export const CLI_DISCOVERY_OBSERVATION_SCHEMA = 'whoisleuth.cli.discovery-observation-snapshot';
 export const CLI_DISCOVERY_OBSERVATION_VERSION = 2;
 export const MAX_DISCOVERY_OBSERVATION_BYTES = 8 * 1024 * 1024;
@@ -158,22 +158,16 @@ function parseObservationSnapshot(text, expectedDigest) {
 }
 async function readExisting(path) {
     try {
-        const handle = await open(path, 'r');
-        try {
-            const metadata = await handle.stat();
-            if (!metadata.isFile() || metadata.size > MAX_DISCOVERY_OBSERVATION_BYTES) {
-                throw new CliUsageError(`Discovery observation snapshots are limited to ${MAX_DISCOVERY_OBSERVATION_BYTES} bytes.`);
-            }
-            return await handle.readFile({ encoding: 'utf8' });
-        }
-        finally {
-            await handle.close();
-        }
+        return await readBoundedRegularTextFile(path, {
+            maximumBytes: MAX_DISCOVERY_OBSERVATION_BYTES,
+            label: 'Discovery observation snapshot',
+            allowSymbolicLink: true,
+        });
     }
     catch (error) {
         if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
             return null;
-        throw error;
+        throw boundedCliInputError(error, 'Discovery observation snapshot');
     }
 }
 function currentAttempt(domain, item, previous, generatedAt, deep) {

package/cli/discovery-scan-command-runner.mjs

@@ -75,6 +75,8 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
         : null;
     const indicator = context.beginProgress(`Collecting 0 of ${queries.length} generated candidates`);
     let completed = checkpoint?.initialResults.length || 0;
+    const resumedItems = new Map((checkpoint?.initialResults ?? []).map((item) => [item.index, item]));
+    const settledItems = new Map();
     if (completed)
         indicator.update(`Resumed ${completed} of ${queries.length} generated candidates`);
     let checkpointFailure = null;
@@ -90,12 +92,23 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
             ...(checkpoint ? { initialResults: checkpoint.initialResults } : {}),
             ...(dependencies.signal ? { signal: dependencies.signal } : {}),
             onItemSettled: (item) => {
+                const observed = {
+                    ...item,
+                    observedAt: context.now(),
+                    collectionOrigin: 'current_run',
+                };
+                settledItems.set(item.index, observed);
                 completed += 1;
                 indicator.update(`Collected ${completed} of ${queries.length} generated candidates`);
                 eventProgress.emit({ event: 'item_settled', index: item.index, ok: item.ok });
-                checkpoint?.record(item);
+                checkpoint?.record(observed);
             },
         });
+        items = items.map((item) => resumedItems.get(item.index) ?? settledItems.get(item.index) ?? {
+            ...item,
+            observedAt: null,
+            collectionOrigin: 'current_run',
+        });
     }
     finally {
         context.endProgress();