@counterfact-labs/cli 0.2.10 → 0.2.11

package/README.md

@@ -28,8 +28,8 @@ npx tsx cli/check.ts /path/to/agent --output /path/to/results
 ```
 
 Analysis makes paid model calls and needs a provider connection. The command reads source files without modifying
-them, prints a readable summary, and writes `findings.json` and `summary.md` to the agent's `.counterfact/` directory
-by default. `--output` chooses another directory. Reports can contain source excerpts; existing reports at those
+them, prints a readable summary, and writes `findings.json` and `summary.md` under
+`~/.config/counterfact-labs/reports/<repository-id>/` by default. `--output` chooses a directory outside the analyzed repository. Reports can contain source excerpts; existing reports at those
 paths are replaced after a completed analysis. Exit status is zero when analysis completes, including when it finds
 problems, and nonzero for invalid arguments, a missing key or a failed run.
 
@@ -112,8 +112,7 @@ An over-limit selection returns included and omitted files for the user to
 choose. The coding agent must ask before narrowing coverage. Terminal offers
 exit with status 3 and save a private scope JSON file for `--scope <json-file>`;
 MCP returns a successful `choose_scope` response. Each retry uses the saved
-snapshot and the ordinary admission checks. File reports live under the file's
-parent at `.counterfact/files/<entry-path-hash>/` and include selection metadata.
+snapshot and the ordinary admission checks. Reports for a file live under `~/.config/counterfact-labs/reports/<repository-id>/files/<entry-path-hash>/` and include selection metadata.
 
 The archive also ships `bundle/client-release.json` with its public Ed25519 verification key and local/relay versions,
 and the gatekeeper's public production trust policy. Production trust has no environment override. With exactly
@@ -164,7 +163,7 @@ The command uses the existing saved sign-in and sends `X-Counterfact-CLI-Version
 responses stop the analysis; the command never falls back to uploading files. Settings are captured at command start.
 An analysis reads the agent's files as they are on disk, including uncommitted changes, and also works in folders without Git.
 The console owns prices, expressed in millionths of a dollar.
-By default, the CLI adds .counterfact/ to the folder's .gitignore when Git doesn't already ignore it. Set CF_LOCAL_GITIGNORE_OUTPUT=0 to turn this off.
+The CLI leaves the repository and its `.gitignore` unchanged. Older in-repository reports remain readable for recovery.
 
 The installed command uses the relay address in `bundle/client-release.json` and saved sign-in. The relay runner sends
 repository facts and the admitted file list (paths and sizes, without contents or absolute checkout paths) to

package/bundle/client-release.json

@@ -1,7 +1,7 @@
 {
   "verificationKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAbBab1PYdmBKXxCvoJ47toJhQvxPevo9nlZnb0zbDWoc=\n-----END PUBLIC KEY-----\n",
   "relayVersion": "relay-1.0.1",
-  "localVersion": "0.2.10",
+  "localVersion": "0.2.11",
   "relayUrl": "https://relay.counterfactlabs.com:8443",
   "projectContext": "checks"
 }

package/dist/adapters/analysis-results.js

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { findingActivitySchema } from "../analysis-core/analysis/schemas.js";
 import { snapshotSettings } from "../analysis-core/settings.js";
 import { publicReportSchema } from "../contract/public-report.js";
-import { outputPaths, writeOutputFiles } from "./output-paths.js";
+import { outputPaths, reportOutputDirectory, reportReadPaths, writeReportFiles } from "./output-paths.js";
 import { savedFindings } from "../cli/finding-display.js";
 import { rankFindings } from "../analysis-core/analysis/finding-quality/policy.js";
 import { fingerprintOf } from "../analysis-core/analysis/finding-identity.js";
@@ -37,7 +37,7 @@ async function readJson(path) {
 }
 /** Saved results are the authority for which omissions still need an analysis. */
 export async function loadAnalysisResults(folder, outputDir) {
-    const [reportPath, contextPath] = await outputPaths(folder, ["findings.json", "analysis-context.json"], outputDir);
+    const { paths: [reportPath, contextPath] } = await reportReadPaths(folder, ["findings.json", "analysis-context.json"], outputDir);
     const report = publicReportSchema.parse(await readJson(reportPath));
     const { reportHash, ...context } = contextSchema.parse(await readJson(contextPath));
     if (reportHash !== hashReport(report))
@@ -45,17 +45,22 @@ export async function loadAnalysisResults(folder, outputDir) {
     return { report, context };
 }
 export async function loadPublicReport(folder, outputDir) {
-    const [path] = await outputPaths(folder, ["findings.json"], outputDir);
+    const { paths: [path] } = await reportReadPaths(folder, ["findings.json"], outputDir);
     return publicReportSchema.parse(await readJson(path));
 }
 /** Only non-secret analysis choices may survive into a later scoped run. */
 export async function saveAnalysisContext(folder, context, outputDir) {
-    const report = await loadPublicReport(folder, outputDir);
+    outputDir = await reportOutputDirectory(folder, outputDir);
+    const { paths: [path], legacy } = await reportReadPaths(folder, ["findings.json"], outputDir);
+    const report = publicReportSchema.parse(await readJson(path));
     const value = contextSchema.parse({ ...context, reportHash: hashReport(report), settings: snapshotSettings(context.settings) });
-    await writeOutputFiles(folder, { "analysis-context.json": `${JSON.stringify(value)}\n` }, outputDir);
+    // A legacy report stays read-only; settlement carries its validated findings into the home store.
+    await writeReportFiles(folder, { ...(legacy ? { "findings.json": `${JSON.stringify(report, null, 2)}\n` } : {}),
+        "analysis-context.json": `${JSON.stringify(value)}\n` }, outputDir);
 }
 function hashReport(report) { return createHash("sha256").update(JSON.stringify(report)).digest("hex"); }
 export async function invalidateAnalysisContext(folder, outputDir) {
+    outputDir = await reportOutputDirectory(folder, outputDir);
     try {
         const [path] = await outputPaths(folder, ["analysis-context.json"], outputDir);
         await unlink(path);

package/dist/adapters/completion.js

@@ -1,16 +1,16 @@
 import { constants } from "node:fs";
 import { createHash } from "node:crypto";
-import { lstat, open, readdir, realpath } from "node:fs/promises";
+import { lstat, open, readdir, realpath, unlink } from "node:fs/promises";
 import os from "node:os";
 import { basename, dirname, join } from "node:path";
 import { z } from "zod";
 import { LOCAL_FINDINGS_BODY_LIMIT, localFindingsPayloadSchema } from "../contract/console.js";
 import { OutputPathError, outputPaths, writeOutputFiles } from "./output-paths.js";
-import { standaloneGitFailure } from "./repository-root.js";
-import { runGit } from "./git.js";
-import { resolveFolderPath } from "./folder-path.js";
+import { legacyFilesTracked, legacyReportDirectory } from "./legacy-reports.js";
 import { matchesSnapshotProvenance } from "./snapshot.js";
 import { acquireCompletionLock } from "./completion-lock.js";
+import { storageIdentity } from "./storage-identity.js";
+import { configDirectory } from "./config-directory.js";
 const record = z.strictObject({ version: z.literal(1), consoleOrigin: z.url().optional(), uploaded: z.boolean().optional(),
     finished: z.boolean().optional(), completedAt: z.number().finite().nonnegative().optional(),
     absoluteExpiresAt: z.number().finite().nonnegative().optional(), payload: localFindingsPayloadSchema });
@@ -23,32 +23,11 @@ const storedRecord = z.union([records, retiredRecord, selectedRetiredRecord]);
 const maxBytes = LOCAL_FINDINGS_BODY_LIMIT + 1024;
 /** Recovery belongs to this checkout and origin, and survives edits and new commits. */
 export async function completionPath(folder, identity) {
-    const root = await resolveFolderPath(folder);
-    let repository = null;
-    let common;
-    try {
-        common = (await runGit(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"])).toString("utf8").trim();
-    }
-    // Standalone folders need no Git identity; a usable checkout must never silently lose its identity.
-    catch (error) {
-        if (!await standaloneGitFailure(root, error))
-            throw error;
-    }
-    if (common !== undefined) {
-        let origin = "";
-        try {
-            origin = (await runGit(root, ["config", "--get", "remote.origin.url"])).toString("utf8").trim();
-        }
-        catch (error) {
-            if (error.code !== 1)
-                throw error;
-        }
-        repository = [await realpath(common), origin];
-    }
+    const [root, repository] = await storageIdentity(folder);
     const coordinates = identity ? [root, repository, selectionIdentity.parse(identity)] : [root, repository];
     const key = createHash("sha256").update(JSON.stringify(coordinates)).digest("hex");
     const home = await realpath(os.homedir());
-    return { home, path: join(home, ".config/counterfact-labs/completions", `${key}.json`) };
+    return { home, path: join(configDirectory(home), "completions", `${key}.json`) };
 }
 export function matchesCompletionSetup(saved, setup) {
     return saved.consoleOrigin === setup.consoleOrigin && (setup.projectId === undefined || saved.payload.projectId === setup.projectId);
@@ -140,19 +119,12 @@ export async function loadCompletion(folder, options = {}) {
     // Repository-owned records cannot supply recovery data, even with matching provenance.
     let legacy;
     try {
-        await lstat(join(folder, ".counterfact/completion.json"));
-        try {
-            await runGit(folder, ["ls-files", "--error-unmatch", "--with-tree=HEAD", "--", ".counterfact/completion.json"]);
+        const directory = legacyReportDirectory(folder);
+        await lstat(join(directory, "completion.json"));
+        // Without Git there is no provenance to verify, so standalone records are ignored too.
+        if (await legacyFilesTracked(folder, [join(directory, "completion.json")]) !== false)
             return null;
-        }
-        catch (error) {
-            // Without Git there is no provenance to verify, and uncertain legacy data must not block analysis.
-            if (await standaloneGitFailure(folder, error))
-                return null;
-            if (error.code !== 1)
-                throw error;
-        }
-        const [path] = await outputPaths(folder, ["completion.json"]);
+        const [path] = await outputPaths(folder, ["completion.json"], directory);
         const { value, modifiedAt } = await readCompletion(path);
         if (!("payload" in value))
             return null;
@@ -214,14 +186,76 @@ function isRetiredCopyName(record, name) {
     const digest = name.startsWith(`${record}.`) && name.endsWith(".json") ? name.slice(record.length + 1, -".json".length) : "";
     return /^[a-f0-9]{64}$/.test(digest);
 }
+/** Bound private archives across folders; the ordinary reports remain the readable result. */
+async function pruneRetainedCompletions(home, directory) {
+    await outputPaths(home, [], directory);
+    const copies = [];
+    for (const name of await readdir(directory)) {
+        if (!/^[a-f0-9-]{36}\.[a-f0-9]{64}\.json$/.test(name))
+            continue;
+        try {
+            const [path] = await outputPaths(home, [name], directory);
+            copies.push({ path, modifiedAt: (await lstat(path)).mtimeMs });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    copies.sort((a, b) => b.modifiedAt - a.modifiedAt || a.path.localeCompare(b.path));
+    for (const copy of copies.slice(10)) {
+        try {
+            await outputPaths(home, [basename(copy.path)], directory);
+            await unlink(copy.path);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
 /** The empty marker also prevents a retired legacy copy from being imported again. */
-export async function discardCompletion(folder, recordPath, identity) {
+export async function discardCompletion(folder, recordPath, identity, options = {}) {
     const { home, path } = await completionPath(folder, identity);
     const destination = recordPath ?? path;
     if (dirname(destination) !== dirname(path) || destination !== path && !isRetiredCopyName(basename(path, ".json"), basename(destination)))
         throw new OutputPathError();
+    let retainedPath;
+    if (options.keepCopy !== false) {
+        try {
+            // This is a local backup, excluded from automatic upload recovery.
+            await outputPaths(home, [basename(destination)], dirname(path));
+            const saved = await readCompletion(destination, identity).catch(error => {
+                if (error.code !== "ENOENT")
+                    throw error;
+                return undefined;
+            });
+            if (saved && "payload" in saved.value) {
+                const bytes = JSON.stringify(saved.value);
+                const digest = createHash("sha256").update(bytes).digest("hex");
+                const retained = join(dirname(path), "retained");
+                await writeOutputFiles(home, { [`${saved.value.payload.checkId}.${digest}.json`]: bytes }, retained);
+                await pruneRetainedCompletions(home, retained);
+                retainedPath = join(retained, `${saved.value.payload.checkId}.${digest}.json`);
+            }
+        }
+        catch (error) {
+            // A readable report is enough to retire refused work and let a new analysis start.
+            // Without one, leave the pending payload intact if its backup cannot be written.
+            if (!options.reportStored)
+                throw error;
+        }
+    }
     const value = identity ? selectedRetiredRecord.parse({ version: 2, finished: true, ...identity }) : { version: 1, finished: true };
-    await writeOutputFiles(home, { [basename(destination)]: JSON.stringify(value) }, dirname(path));
+    try {
+        await writeOutputFiles(home, { [basename(destination)]: JSON.stringify(value) }, dirname(path));
+    }
+    catch (error) {
+        // Replacement can succeed before directory sync fails; the confirmed backup still identifies the results.
+        if (!retainedPath)
+            throw error;
+    }
+    return retainedPath;
 }
 export async function lockCompletion(folder, onLost, identity) {
     const { home, path } = await completionPath(folder, identity);

package/dist/adapters/config-directory.js

@@ -0,0 +1,5 @@
+import { join } from "node:path";
+/** Credentials, reports and recovery records share the CLI's existing home convention. */
+export function configDirectory(home) {
+    return join(home, ".config/counterfact-labs");
+}

package/dist/adapters/files.js

@@ -176,22 +176,41 @@ async function readFolder(settings, folder, admission = {}, options = {}) {
         const byPath = new Map(entries.map(entry => [entry.path, entry]));
         const files = Object.create(null), visited = new Set(), unavailable = new Set();
         const paths = planParts ? entries.map(entry => entry.path) : [...options.planSkipped];
-        const metadataPaths = new Set();
+        const metadataPaths = new Set(), metadataOnly = new Set();
         let metadataBytes = 0;
+        const reserveMetadata = (path, size) => {
+            if (metadataPaths.has(path))
+                return true;
+            if (metadataPaths.size >= moduleResolutionLimits.settingsFiles || size > moduleResolutionLimits.settingsBytes - metadataBytes)
+                return false;
+            metadataPaths.add(path);
+            metadataBytes += size;
+            return true;
+        };
+        let metadata = settings.CF_LOCAL_IMPORT_RESOLUTION === "0" ? [] : ModuleResolver.settingsFiles(listing, new Map(), paths, settings);
         let pending = paths, dependencies = {}, retainedBytes = 0;
         while (pending.length) {
             const next = [...new Set(pending)].filter(path => !visited.has(path));
             next.forEach(path => visited.add(path));
             await mapLimit(next, 4, async (path) => {
                 const entry = byPath.get(path);
-                if (!entry || !admitFile(settings, entry, { ...admission, purpose: "proposal", route: "local-folder" }).admitted)
+                if (!entry)
                     return;
+                if (!admitFile(settings, entry, { ...admission, purpose: "proposal", route: "local-folder" }).admitted) {
+                    const pythonMetadata = metadata.includes(path) && ModuleResolver.isPythonSettingsFile(path);
+                    if (!pythonMetadata || !admitFile(settings, entry, { ...admission, purpose: "entry", route: "local-folder" }).admitted)
+                        return;
+                    // Metadata can describe imports without becoming an analysis candidate.
+                    metadataOnly.add(path);
+                    if (!reserveMetadata(path, entry.size))
+                        return;
+                }
                 if (planParts && entry.size > READ_LIMITS.archive.bytes - retainedBytes) {
                     unavailable.add(path);
                     return;
                 }
                 try {
-                    const text = await read(entry, "proposal");
+                    const text = await read(entry, metadataOnly.has(path) ? "entry" : "proposal");
                     const size = text === null ? 0 : Buffer.byteLength(text);
                     if (text === null || planParts && size > READ_LIMITS.archive.bytes - retainedBytes)
                         unavailable.add(path);
@@ -212,20 +231,16 @@ async function readFolder(settings, folder, admission = {}, options = {}) {
                 }
             });
             dependencies = fileDependencies({ entries, files, settings });
-            const metadata = settings.CF_LOCAL_IMPORT_RESOLUTION === "0" ? [] : ModuleResolver.settingsFiles(listing, new Map(Object.entries(files)), Object.keys(files));
+            metadata = settings.CF_LOCAL_IMPORT_RESOLUTION === "0" ? [] : ModuleResolver.settingsFiles(listing, new Map(Object.entries(files)), Object.keys(files), settings);
             const settingsPaths = metadata.filter(path => {
                 if (visited.has(path) || metadataPaths.has(path))
                     return false;
                 const size = byPath.get(path)?.size;
-                if (size === undefined || metadataPaths.size >= moduleResolutionLimits.settingsFiles || size > moduleResolutionLimits.settingsBytes - metadataBytes)
-                    return false;
-                metadataPaths.add(path);
-                metadataBytes += size;
-                return true;
+                return size !== undefined && reserveMetadata(path, size);
             });
             pending = [...settingsPaths, ...Object.values(dependencies).flat()].filter(path => !visited.has(path));
         }
-        const plannedEntries = entries.filter(entry => planParts ? Object.hasOwn(files, entry.path) : !unavailable.has(entry.path)).map(entry => Object.hasOwn(files, entry.path)
+        const plannedEntries = entries.filter(entry => !metadataOnly.has(entry.path) && (planParts ? Object.hasOwn(files, entry.path) : !unavailable.has(entry.path))).map(entry => Object.hasOwn(files, entry.path)
             ? { ...entry, size: Buffer.byteLength(files[entry.path]) } : entry);
         const input = { entries: plannedEntries, paths: planParts ? plannedEntries.map(entry => entry.path) : paths,
             inputBytes: Object.fromEntries(Object.entries(files).map(([path, text]) => [path, fileEvidenceBytes(path, text)])),

package/dist/adapters/legacy-reports.js

@@ -0,0 +1,48 @@
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { resolveFolderPath } from "./folder-path.js";
+import { runGit } from "./git.js";
+import { standaloneGitFailure } from "./repository-root.js";
+/** Only default report locations from earlier releases may supply a fallback. */
+export function legacyReportDirectory(folder, selected) {
+    const legacy = join(folder, ".counterfact");
+    if (selected === undefined)
+        return legacy;
+    const parts = relative(selected.storeRoot, resolve(selected.directory)).split(sep);
+    const digest = (part) => /^[a-f0-9]{64}$/.test(part);
+    if (parts.length === 1 && digest(parts[0]))
+        return legacy;
+    if (parts.length === 3 && digest(parts[0]) && parts[1] === "files" && digest(parts[2]))
+        return join(legacy, "files", parts[2]);
+    return undefined;
+}
+/** Repository files cannot impersonate saved results; null means there is no Git provenance. */
+export async function legacyFilesTracked(folder, paths) {
+    const root = await resolveFolderPath(folder);
+    const canonical = await Promise.all(paths.map(async (path) => join(await resolveFolderPath(dirname(path)), basename(path))));
+    const args = ["ls-files", "--", ...canonical.map(path => relative(root, path))];
+    try {
+        let tracked;
+        try {
+            tracked = await runGit(root, [args[0], "--with-tree=HEAD", ...args.slice(1)]);
+        }
+        catch (error) {
+            if (error.code !== 128)
+                throw error;
+            // An unborn branch has an index but no HEAD tree to compare against.
+            const head = (await runGit(root, ["rev-parse", "--verify", "--quiet", "HEAD"]).catch(error => {
+                if (error.code !== 1)
+                    throw error;
+                return Buffer.alloc(0);
+            })).length;
+            if (head)
+                throw error;
+            tracked = await runGit(root, args);
+        }
+        return tracked.length > 0;
+    }
+    catch (error) {
+        if (await standaloneGitFailure(root, error))
+            return null;
+        throw error;
+    }
+}

package/dist/adapters/output-paths.js

@@ -1,12 +1,54 @@
 import { chmod, lstat, mkdir, realpath } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import os from "node:os";
 import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
-import { FINISH_FAILURE_MESSAGE } from "../contract/cli-refusals.js";
+import { OUTPUT_PATH_MESSAGE, REPORT_HOME_IN_REPOSITORY_MESSAGE, REPORT_OUTPUT_IN_REPOSITORY_MESSAGE } from "../contract/cli-refusals.js";
 import { resolveFolderPath } from "./folder-path.js";
 import { durableWrite } from "./durable-write.js";
-export const DEFAULT_OUTPUT_DIR = ".counterfact";
+import { storageIdentity } from "./storage-identity.js";
+import { gitRepositoryRoot } from "./repository-root.js";
+import { runGit } from "./git.js";
+import { configDirectory } from "./config-directory.js";
+import { legacyFilesTracked, legacyReportDirectory } from "./legacy-reports.js";
+/** The home store uses the same checkout coordinates and home convention as completion recovery. */
+export async function reportDirectory(folder, entries) {
+    const key = createHash("sha256").update(JSON.stringify(await storageIdentity(folder))).digest("hex");
+    const directory = join(reportStoreRoot(await realpath(os.homedir())), key);
+    if (entries === undefined)
+        return directory;
+    const hash = createHash("sha256").update(typeof entries === "string" ? entries : JSON.stringify(entries)).digest("hex");
+    return join(directory, "files", hash);
+}
+/** Only reads may fall back to reports left by earlier CLI releases. */
+export async function reportReadPaths(folder, names, outputDir) {
+    try {
+        const paths = await outputPaths(folder, names, outputDir);
+        if (paths.length)
+            await lstat(paths[0]);
+        return { paths, legacy: false };
+    }
+    catch (error) {
+        if (!missing(error))
+            throw error;
+        const legacy = legacyReportDirectory(folder, outputDir === undefined ? undefined
+            : { directory: outputDir, storeRoot: reportStoreRoot(await realpath(os.homedir())) });
+        if (!legacy)
+            throw error;
+        const paths = await outputPaths(folder, names, legacy);
+        // Files supplied by the repository must never stand in for this user's saved analysis.
+        if (await legacyFilesTracked(folder, paths))
+            throw new OutputPathError();
+        return { paths, legacy: true };
+    }
+}
 export class OutputPathError extends Error {
-    constructor() {
-        super(FINISH_FAILURE_MESSAGE);
+    constructor(message = OUTPUT_PATH_MESSAGE) {
+        super(message);
+    }
+}
+export class ReportLocationError extends OutputPathError {
+    constructor(homeInRepository) {
+        super(homeInRepository ? REPORT_HOME_IN_REPOSITORY_MESSAGE : REPORT_OUTPUT_IN_REPOSITORY_MESSAGE);
     }
 }
 const missing = (error) => error.code === "ENOENT";
@@ -14,15 +56,48 @@ const within = (base, path) => {
     const rel = relative(base, path);
     return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
 };
+const reportStoreRoot = (home) => join(configDirectory(home), "reports");
+/** Report storage must leave the entire analyzed checkout read-only, even when it contains the home directory. */
+export async function reportOutputDirectory(folder, outputDir) {
+    const defaultStore = outputDir === undefined;
+    outputDir ??= await reportDirectory(folder);
+    const root = await resolveFolderPath(folder);
+    const repository = await gitRepositoryRoot(async (args) => (await runGit(root, args)).toString("utf8"), root);
+    let existing = resolve(outputDir), suffix = "";
+    for (;;) {
+        try {
+            existing = resolve(await realpath(existing), suffix);
+            break;
+        }
+        catch (error) {
+            if (!missing(error) || dirname(existing) === existing)
+                throw new OutputPathError();
+            suffix = join(parse(existing).base, suffix);
+            existing = dirname(existing);
+        }
+    }
+    const boundary = repository ? await realpath(repository) : root;
+    if (within(boundary, existing)) {
+        throw new ReportLocationError(defaultStore || within(boundary, await realpath(os.homedir())));
+    }
+    // Keep the selected spelling so output admission can still refuse symlink components.
+    return resolve(outputDir);
+}
 /** Validate the selected anchor and every output component before creating or replacing files. */
 export async function outputPaths(folder, names, outputDir, create = false) {
     const selected = resolve(folder), root = await resolveFolderPath(folder);
-    const requested = resolve(outputDir ?? join(selected, DEFAULT_OUTPUT_DIR));
+    const requested = resolve(outputDir ?? await reportDirectory(root));
     let directory = within(selected, requested) ? resolve(root, relative(selected, requested)) : requested;
     const external = !within(root, directory);
     const userUid = process.getuid?.();
     let systemUid;
     let anchor = root;
+    // Home storage starts at the user's boundary; arbitrary --output paths need no home lookup.
+    if (directory.includes(`${sep}${reportStoreRoot("")}${sep}`)) {
+        const home = await realpath(os.homedir());
+        if (within(reportStoreRoot(home), directory))
+            anchor = home;
+    }
     while (!within(anchor, directory))
         anchor = dirname(anchor);
     try {
@@ -83,6 +158,7 @@ export async function outputPaths(folder, names, outputDir, create = false) {
     }
 }
 export async function writeOutputFiles(folder, files, outputDir) {
+    outputDir ??= await reportDirectory(folder);
     const names = Object.keys(files);
     const paths = await outputPaths(folder, names, outputDir, true);
     if (paths.length)
@@ -93,3 +169,7 @@ export async function writeOutputFiles(folder, files, outputDir) {
     }
     return paths;
 }
+/** Every report writer enforces the repository boundary, including direct library calls. */
+export async function writeReportFiles(folder, files, outputDir) {
+    return writeOutputFiles(folder, files, await reportOutputDirectory(folder, outputDir));
+}

package/dist/adapters/result-receipt.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import os from "node:os";
+import { basename, dirname } from "node:path";
+import { z } from "zod";
+import { outputPaths, reportOutputDirectory, writeOutputFiles } from "./output-paths.js";
+export const resultReceiptSchema = z.strictObject({ directory: z.string().min(1).max(16384),
+    hashes: z.tuple([z.string().regex(/^[a-f0-9]{64}$/), z.string().regex(/^[a-f0-9]{64}$/)]) });
+const storedReceiptSchema = z.strictObject({ checkId: z.uuid(), reports: resultReceiptSchema });
+// Older CLIs strictly parse completion records and only scan sibling slots ending in a hex digest.
+const receiptName = (recordPath) => `${basename(recordPath, ".json")}.reports.json`;
+export async function saveResultReceipt(recordPath, checkId, reports) {
+    const home = await realpath(os.homedir());
+    const bytes = JSON.stringify(storedReceiptSchema.parse({ checkId, reports }));
+    await writeOutputFiles(home, { [receiptName(recordPath)]: bytes }, dirname(recordPath));
+}
+/** An absent or unreadable receipt cannot prevent recovering the completion payload. */
+export async function loadResultReceipt(recordPath, checkId) {
+    let file;
+    try {
+        const home = await realpath(os.homedir());
+        const [path] = await outputPaths(home, [receiptName(recordPath)], dirname(recordPath));
+        file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const limit = 128 * 1024;
+        const info = await file.stat();
+        if (!info.isFile() || info.size > limit)
+            return undefined;
+        const bytes = Buffer.alloc(limit + 1);
+        const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+        if (bytesRead > limit)
+            return undefined;
+        const value = storedReceiptSchema.parse(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, bytesRead))));
+        return value.checkId === checkId ? value.reports : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await file?.close();
+    }
+}
+/** Hash both durable reports so a later run cannot mistake an older report for this result. */
+export async function readResultReceipt(folder, outputDir) {
+    const directory = await reportOutputDirectory(folder, outputDir);
+    const [findingsPath, summaryPath] = await outputPaths(folder, ["findings.json", "summary.md"], directory);
+    const hashes = [];
+    const limit = 64 * 1024 * 1024;
+    for (const path of [findingsPath, summaryPath]) {
+        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const info = await file.stat();
+            if (!info.isFile() || info.size > limit)
+                throw new Error("Invalid saved analysis");
+            const hash = createHash("sha256"), buffer = Buffer.alloc(64 * 1024);
+            let total = 0;
+            for (;;) {
+                const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, limit - total + 1), null);
+                if (!bytesRead)
+                    break;
+                total += bytesRead;
+                if (total > limit)
+                    throw new Error("Invalid saved analysis");
+                hash.update(buffer.subarray(0, bytesRead));
+            }
+            hashes.push(hash.digest("hex"));
+        }
+        finally {
+            await file.close();
+        }
+    }
+    return { paths: { findingsPath, summaryPath }, receipt: resultReceiptSchema.parse({ directory, hashes }) };
+}
+/** Only the exact reports recorded after completion may replace a failed backup. */
+export async function verifiedResultPaths(folder, receipt) {
+    const current = await readResultReceipt(folder, receipt.directory);
+    return current.receipt.hashes.every((hash, index) => hash === receipt.hashes[index]) ? current.paths : undefined;
+}

package/dist/adapters/results.js

@@ -2,10 +2,9 @@ import { skippedFilesEnabled } from "../analysis-core/settings.js";
 import { combineLocalReports } from "./combined-results.js";
 import { invalidateAnalysisContext, loadPublicReport } from "./analysis-results.js";
 import { formatSummary } from "../cli/summary.js";
-import { ignoreDefaultOutput } from "./gitignore-output.js";
-import { writeOutputFiles } from "./output-paths.js";
+import { writeReportFiles } from "./output-paths.js";
 import { projectPublicReport } from "../contract/public-report.js";
-import { INCLUDED_FILES_CAPTION, INCOMPLETE_IMPORTS_MESSAGE, SELECTION_COVERAGE_DESCRIPTION } from "../contract/scope-choice.js";
+import { INCLUDED_FILES_CAPTION, INCOMPLETE_IMPORTS_MESSAGE, selectionCoverageDescription } from "../contract/scope-choice.js";
 export async function saveLocalResults(folder, report, refusedFiles, outputDir, options) {
     const next = projectPublicReport(report, refusedFiles);
     const publicReport = options.append && skippedFilesEnabled(options.settings ?? {})
@@ -15,14 +14,12 @@ export async function saveLocalResults(folder, report, refusedFiles, outputDir,
     const scope = options.scope;
     const incomplete = options.selection && !options.selection.completeness.complete
         ? [INCOMPLETE_IMPORTS_MESSAGE, "", INCLUDED_FILES_CAPTION, ...options.includedPaths.map(path => `  ${path}`), "", ""].join("\n") : "";
-    const coverage = scope && scope.imports !== "all" ? SELECTION_COVERAGE_DESCRIPTION
-        .replace("{entry}", () => scope.entry).replace("{count}", String(Array.isArray(scope.imports) ? scope.imports.length : 0)) + "\n\n" : "";
-    const [findingsPath, summaryPath] = await writeOutputFiles(folder, {
+    const coverage = scope && scope.imports !== "all" ? selectionCoverageDescription(scope.entry, Array.isArray(scope.imports) ? scope.imports.length : 0) + "\n\n" : "";
+    const [findingsPath, summaryPath] = await writeReportFiles(folder, {
         "findings.json": `${JSON.stringify(publicReport, null, 2)}\n`,
         "summary.md": incomplete + coverage + formatSummary(publicReport, { ...options, analyzedFolder: options.analyzedFolder ?? folder, skippedOffer: !options.append, skippedFilesEnabled: skippedFilesEnabled(options.settings ?? {}) }),
         ...(options.selection ? { "selection.json": JSON.stringify({ schemaVersion: 1, selection: options.selection,
                 ...(scope ? { scope } : {}) }, null, 2) + "\n" } : {}),
     }, outputDir);
-    const ignoreAdded = await ignoreDefaultOutput(folder, options.defaultFileOutput ? undefined : outputDir, options);
-    return { findingsPath, summaryPath, ignoreAdded };
+    return { findingsPath, summaryPath };
 }