rea-agents 6.3.0 → 6.4.0

package/dist/application/Uninstall.js

@@ -1,22 +1,24 @@
 import { parseClientConfiguration, serializeClientConfiguration, clientServerPath, legacyClientServerPath, withClientServers, } from "./ClientConfigurationDocument.js";
-import { copyFile, lstat, readFile, realpath, rm } from "node:fs/promises";
+import { copyFile, lstat, realpath, rm } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
 import { join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
-import { claudeCodeSkillsDirectory, skillDestinations } from "./SetupSkill.js";
+import { isManagedSkillManifest, MANAGED_SKILL_FILES, readSkillFile, skillDestinations, } from "./SetupSkill.js";
 import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
+import { readRegularFileText } from "./RegularFileRead.js";
 import { manualRegistrationRemediation, supportedClients, } from "./SupportedClients.js";
 const systemFileSystem = {
-    readText: (path) => readFile(path, "utf8"),
+    readText: (path) => readRegularFileText(path),
+    readRegularText: readSkillFile,
     copy: (source, destination) => copyFile(source, destination, fsConstants.COPYFILE_EXCL),
     writeText: (path, contents) => writeFileAtomic(path, contents, { encoding: "utf8" }),
     stat: (path) => lstat(path),
     realpath: (path) => realpath(path),
-    remove: (path) => rm(path, { recursive: true }),
+    remove: (path, recursive = true) => rm(path, { recursive }),
 };
 /** Whether any requested REA-owned uninstall action failed. */
 export const isUninstallFailure = (result) => {
@@ -57,11 +59,12 @@ export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
         status: "retained",
         detail: "Hopper is not owned by REA uninstall.",
     });
+    const reported = collapseUninstallItems(items);
     return {
-        status: items.some(({ status }) => status === "failed")
+        status: reported.some(({ status }) => status === "failed")
             ? "failed"
             : "complete",
-        items,
+        items: reported,
     };
 };
 /**
@@ -88,7 +91,12 @@ const removeAll = async (clients, purgeData, host) => {
 export const systemUninstallHost = (selectedHome = undefined, fileSystem = systemFileSystem, environment = process.env, platform = process.platform) => {
     const home = selectedHome ?? homeDirectoryFromEnvironment(environment, platform);
     return {
-        clients: () => Promise.resolve(supportedClients(home, platform, environment)),
+        clients: () => Promise.resolve(supportedClients(home, platform, environment).flatMap((client) => client.configPaths === undefined
+            ? [client]
+            : client.configPaths.map((configPath) => ({
+                ...client,
+                configPath,
+            })))),
         inspectClient: async (client) => {
             const read = await readClientConfiguration(client, fileSystem);
             return read.kind === "item" && read.item.status === "failed"
@@ -96,7 +104,7 @@ export const systemUninstallHost = (selectedHome = undefined, fileSystem = syste
                 : undefined;
         },
         removeClient: (client) => removeClient(client, fileSystem),
-        removeSkill: () => removeManagedSkills(home, fileSystem, environment),
+        removeSkill: () => removeManagedSkills(home, fileSystem, environment, platform),
         purgeData: async () => [
             await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem),
             await removeManagedPath(join(home, ".rea/state"), "state", fileSystem),
@@ -104,6 +112,8 @@ export const systemUninstallHost = (selectedHome = undefined, fileSystem = syste
     };
 };
 const readClientConfiguration = async (client, fileSystem) => {
+    if (client.configPathError !== undefined)
+        return itemRead(item(client.name, "failed", client.configPathError));
     if (client.format === "unsupported")
         return itemRead(item(client.name, "skipped", manualRegistrationRemediation(client.name) ??
             "This client has no documented local MCP configuration boundary."));
@@ -225,8 +235,8 @@ const removeManagedPath = async (path, name, fileSystem) => {
             : item(name, "failed", "This item could not be removed. Check file permissions, then rerun uninstall.");
     }
 };
-const removeManagedSkills = async (home, fileSystem, environment) => {
-    const results = await Promise.all(skillDestinations(home, undefined, claudeCodeSkillsDirectory(home, environment)).map(({ client, path }) => removeManagedPath(path, client === "claude_code" ? "Claude Code skill" : "skill", fileSystem)));
+const removeManagedSkills = async (home, fileSystem, environment, platform) => {
+    const results = await Promise.all(skillDestinations(home, undefined, environment, platform).map(({ client, path }) => removeManagedSkill(path, client === "claude_code" ? "Claude Code skill" : "skill", fileSystem)));
     const failed = results.find(({ status }) => status === "failed");
     if (failed !== undefined)
         return item("skill", "failed", results
@@ -241,7 +251,145 @@ const removeManagedSkills = async (home, fileSystem, environment) => {
         .map(({ name, status: resultStatus, detail }) => `${name}: ${resultStatus} (${detail})`)
         .join(" "));
 };
+const removeManagedSkill = async (path, name, fileSystem) => {
+    let root;
+    try {
+        root = await fileSystem.stat(path);
+    }
+    catch (cause) {
+        return isMissing(cause)
+            ? item(name, "skipped", "Skill directory does not exist.")
+            : item(name, "failed", "Skill directory could not be inspected.");
+    }
+    if (root.isSymbolicLink())
+        return item(name, "retained", "Skill directory is a symbolic link.");
+    if (root.isDirectory?.() !== true)
+        return item(name, "retained", "Skill path is not a directory.");
+    const manifestPath = join(path, "SKILL.md");
+    try {
+        const manifest = await fileSystem.stat(manifestPath);
+        if (manifest.isSymbolicLink())
+            return item(name, "retained", "Skill manifest is a symbolic link.");
+        if (manifest.isFile?.() !== true)
+            return item(name, "retained", "Skill manifest is not a regular file.");
+    }
+    catch (cause) {
+        return isMissing(cause)
+            ? item(name, "retained", "Skill ownership could not be established.")
+            : item(name, "failed", "Skill manifest could not be inspected.");
+    }
+    let content;
+    try {
+        content = await (fileSystem.readRegularText?.(manifestPath) ??
+            fileSystem.readText(manifestPath));
+    }
+    catch (cause) {
+        return isMissing(cause)
+            ? item(name, "retained", "Skill ownership could not be established.")
+            : item(name, "failed", "Skill manifest could not be read.");
+    }
+    if (!isManagedSkillManifest(content))
+        return item(name, "retained", "Skill manifest is not REA-owned.");
+    const manifestName = "SKILL.md";
+    const otherFiles = MANAGED_SKILL_FILES.filter((relativePath) => relativePath !== manifestName);
+    const results = [];
+    for (const relativePath of otherFiles)
+        results.push(await removeManagedSkillFile(path, relativePath, name, fileSystem));
+    if (results.some(({ status }) => status === "failed" || status === "retained"))
+        results.push(item(name, "retained", "REA ownership manifest was retained because a managed file could not be safely removed."));
+    else
+        results.push(await removeManagedSkillFile(path, manifestName, name, fileSystem));
+    const failed = results.find(({ status }) => status === "failed");
+    if (failed !== undefined)
+        return item(name, "failed", results.map(({ detail }) => detail).join(" "));
+    const removed = results.some(({ status }) => status === "removed");
+    return item(name, removed ? "removed" : "skipped", "REA-managed skill files were removed; other files were preserved.");
+};
+const removeManagedSkillFile = async (root, relativePath, name, fileSystem) => {
+    const segments = relativePath.split(/[\\/]/u);
+    let parent = root;
+    for (const segment of segments.slice(0, -1)) {
+        parent = join(parent, segment);
+        try {
+            const stats = await fileSystem.stat(parent);
+            if (stats.isSymbolicLink() || stats.isDirectory?.() !== true)
+                return item(name, "retained", `Managed path parent was retained: ${parent}.`);
+        }
+        catch (cause) {
+            return isMissing(cause)
+                ? item(name, "skipped", `${join(parent, segments.at(-1) ?? "")} does not exist.`)
+                : item(name, "failed", `Managed path parent could not be inspected: ${parent}.`);
+        }
+    }
+    const target = join(root, relativePath);
+    let stats;
+    try {
+        stats = await fileSystem.stat(target);
+    }
+    catch (cause) {
+        return isMissing(cause)
+            ? item(name, "skipped", `${target} does not exist.`)
+            : item(name, "failed", `Managed file could not be inspected: ${target}.`);
+    }
+    if (stats.isSymbolicLink())
+        return item(name, "retained", `Managed file is a symbolic link: ${target}.`);
+    if (stats.isFile?.() !== true)
+        return item(name, "retained", `Managed path is not a regular file: ${target}.`);
+    try {
+        await fileSystem.remove(target, false);
+        return item(name, "removed", `Removed ${target}.`);
+    }
+    catch (cause) {
+        return isMissing(cause)
+            ? item(name, "skipped", `${target} does not exist.`)
+            : item(name, "failed", `Managed file could not be removed: ${target}.`);
+    }
+};
 const item = (name, status, detail) => ({ name, status, detail });
+/**
+ * Layered clients are removed file by file, but callers look up one status by
+ * client name. A missing earlier file must not hide a later removal.
+ */
+const collapseUninstallItems = (items) => {
+    const collapsed = [];
+    for (const next of items) {
+        const index = collapsed.findIndex(({ name }) => name === next.name);
+        const current = collapsed[index];
+        if (current === undefined) {
+            collapsed.push(next);
+            continue;
+        }
+        collapsed[index] = mergeUninstallItems(current, next);
+    }
+    return collapsed;
+};
+const mergeUninstallItems = (current, next) => {
+    const status = preferredUninstallStatus(current.status, next.status);
+    const details = [current, next]
+        .filter((entry) => entry.status === status ||
+        (status === "removed" && entry.status === "retained"))
+        .map(({ detail }) => detail);
+    return item(current.name, status, [...new Set(details)].join(" "));
+};
+const preferredUninstallStatus = (current, next) => uninstallStatusPriority(next) > uninstallStatusPriority(current)
+    ? next
+    : current;
+const uninstallStatusPriority = (status) => {
+    switch (status) {
+        case "failed":
+            return 3;
+        case "removed":
+            return 2;
+        case "retained":
+            return 1;
+        case "skipped":
+            return 0;
+        default: {
+            const exhaustive = status;
+            throw new TypeError(`Unhandled uninstall item status: ${String(exhaustive)}`);
+        }
+    }
+};
 const registrationSchema = z
     .object({ command: z.string(), args: z.array(z.string()) })
     .passthrough();

package/dist/application/UpdateMaintenance.js

@@ -1,11 +1,11 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { readClientRegistrationStatuses } from "./ClientRegistrationStatus.js";
 import { clientServerForcedEnabled, clientServerListedDisabled, effectiveClientServer, parseClientConfiguration, } from "./ClientConfigurationDocument.js";
 import { supportedClients } from "./SupportedClients.js";
+import { existingSkillDestinations } from "./SetupSkill.js";
+import { readRegularFileText } from "./RegularFileRead.js";
 const setupPlanSchema = z.object({
     status: z.literal("planned"),
     plannedActions: z.array(z.object({
@@ -20,7 +20,7 @@ const setupPlanSchema = z.object({
         commands: z.array(z.string()).optional(),
     })),
 });
-/** Discover owned registrations and an existing REA skill without writes. */
+/** Discover owned registrations and REA skills without writes. */
 export const existingMaintenanceScope = async (home, entryPoint, environment) => {
     const registrations = await readClientRegistrationStatuses(home, entryPoint, {
         environment,
@@ -34,7 +34,7 @@ export const existingMaintenanceScope = async (home, entryPoint, environment) =>
         const client = supported.find(({ name }) => name === registration.client);
         if (client === undefined)
             continue;
-        const parsed = parseClientConfiguration(await readFile(client.configPath, "utf8"), client.format);
+        const parsed = parseClientConfiguration(await readRegularFileText(client.configPath), client.format);
         const enabled = z
             .object({
             enabled: z.boolean().optional(),
@@ -48,23 +48,18 @@ export const existingMaintenanceScope = async (home, entryPoint, environment) =>
             !clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey))
             clients.push(client.name);
     }
-    let skill = false;
-    try {
-        const content = await readFile(join(home, ".agents", "skills", PRODUCT_IDENTITY.skillName, "SKILL.md"), "utf8");
-        skill =
-            content.startsWith(`---\nname: ${PRODUCT_IDENTITY.skillName}\n`) ||
-                content.startsWith(`---\r\nname: ${PRODUCT_IDENTITY.skillName}\r\n`);
-    }
-    catch (cause) {
-        if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
-            throw cause;
-    }
-    return { clients, skill };
+    const skillDestinations = await existingSkillDestinations(home, environment);
+    return {
+        clients,
+        skill: skillDestinations.length > 0,
+        skillDestinations,
+    };
 };
 /** Ask the verified new executable to plan only existing REA integrations. */
 export const planIntegrationMaintenance = async (home, entryPoint, environment, execute) => {
     try {
         const scope = await existingMaintenanceScope(home, entryPoint, environment);
+        const skillDestinations = scope.skillDestinations ?? [];
         if (scope.clients.length === 0 && !scope.skill)
             return { status: "current", plannedActions: [] };
         const command = [
@@ -72,6 +67,7 @@ export const planIntegrationMaintenance = async (home, entryPoint, environment,
             entryPoint,
             "setup",
             ...scope.clients.flatMap((client) => ["--client", client]),
+            ...skillDestinations.flatMap(({ client }) => ["--skill-client", client]),
             `--skill=${String(scope.skill)}`,
         ];
         const execution = await execute([...command, "--dry-run", "--json"]);
@@ -85,11 +81,11 @@ export const planIntegrationMaintenance = async (home, entryPoint, environment,
             };
         if (plan.data.plannedActions.length === 0)
             return { status: "current", plannedActions: [] };
-        const allowedIds = new Set([
-            ...scope.clients.map((client) => `configure_client:${client}`),
-            ...(scope.skill ? ["install_skill"] : []),
-        ]);
-        if (plan.data.plannedActions.some(({ id }) => !allowedIds.has(id)))
+        const allowedIds = new Set(scope.clients.map((client) => `configure_client:${client}`));
+        const skillTargets = new Set(skillDestinations.map(({ path }) => path));
+        if (plan.data.plannedActions.some((action) => action.kind === "install_skill"
+            ? !skillTargets.has(action.target)
+            : !allowedIds.has(action.id)))
             return {
                 status: "unavailable",
                 remediation: "The updated setup plan included an integration outside the existing REA maintenance scope.",

package/dist/application/Utf8JsonInput.js

@@ -3,6 +3,11 @@ import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js"
 import { safeParseJson } from "../domain/safeJson.js";
 /** Recovery that preserves complete, authenticated Evidence workflow inputs. */
 export const JSON_INPUT_RESOURCE_REMEDIATION = "Provide a smaller valid JSON value. For Evidence workflows, re-analyze a smaller selection of the original target and use its complete Evidence; splitting JSON text or trimming Evidence fields does not produce valid workflow input.";
+/**
+ * Strict JSON input keeps rejecting a leading byte-order mark, but names it:
+ * the parser's own message quotes the invisible U+FEFF as the bad token.
+ */
+export const JSON_BYTE_ORDER_MARK_MESSAGE = "JSON input begins with a UTF-8 byte-order mark (EF BB BF), which strict JSON input does not accept. Save the file as UTF-8 without a byte-order mark.";
 /** Decode JSON bytes without confusing a runtime string limit with malformed input. */
 export const parseUtf8Json = (bytes, operation, path, boundary = "json-input") => {
     const stringLimitFailure = (cause, decodedUnits) => new AnalysisResourceConstraintError(operation, "memory", "JSON input exceeds the runtime's maximum decoded string length", {
@@ -60,5 +65,7 @@ export const parseUtf8Json = (bytes, operation, path, boundary = "json-input") =
             cause,
         };
     }
+    if (text.startsWith("\uFEFF"))
+        return { ok: false, error: JSON_BYTE_ORDER_MARK_MESSAGE, cause: undefined };
     return safeParseJson(text);
 };

package/dist/application/WebScriptExportService.js

@@ -6,26 +6,28 @@ import { publishWebScripts } from "../browser/assets/PublishWebScripts.js";
 import { selectScriptCapture } from "../browser/assets/ScriptCaptureAdapters.js";
 import { AnalysisAccessDeniedError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err, ok } from "../domain/result.js";
 import { safeParseJson } from "../domain/safeJson.js";
 import { exportWebScriptsInputSchema, } from "../domain/webScriptExport.js";
 import { WebScriptExportError } from "../domain/webScriptExportError.js";
 import { WEB_SCRIPT_EXPORT_PROVIDER as PROVIDER } from "./InvestigationProviders.js";
-import { readRegularFile } from "./RegularFileRead.js";
-import { NonRegularFileReadError } from "../filesystem/RegularFile.js";
+import { readRegularFile, RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
+import { NonRegularFileReadError, RegularFileChangedError, } from "../filesystem/RegularFile.js";
 const OPERATION = "export_web_scripts";
 /** Export one local capture through the shared CLI/MCP application workflow. */
-export const exportWebScripts = async (rawInput, options = {}) => {
+export const exportWebScripts = async (rawInput, resources, options = {}) => {
     const input = exportWebScriptsInputSchema.safeParse(rawInput);
     return input.success
-        ? exportWebScriptsValidated(input.data, options)
+        ? exportWebScriptsValidated(input.data, resources, options)
         : err(analysisInputErrorFromIssues(OPERATION, input.error.issues, rawInput));
 };
 /** Publish input already parsed by a named adapter contract. */
-export const exportWebScriptsValidated = async (input, options = {}) => {
+export const exportWebScriptsValidated = async (input, resources, options = {}) => {
     if (!isAbsolute(input.capture_path) || !isAbsolute(input.output_directory))
         return err(new AnalysisInputError(OPERATION, undefined, [
             {
@@ -36,16 +38,16 @@ export const exportWebScriptsValidated = async (input, options = {}) => {
         ]));
     try {
         options.signal?.throwIfAborted();
-        const read = await readCapture(input.capture_path, options.signal);
-        if (!read.ok)
-            return read;
-        const bytes = read.value;
-        const loaded = parseCapture(bytes);
-        if (!loaded.ok)
-            return loaded;
+        const prepared = await prepareCapture(input.capture_path, resources, options.signal);
+        if (!prepared.ok)
+            return prepared;
+        const { bytes, loaded } = prepared.value;
         options.signal?.throwIfAborted();
         const sha256 = createHash("sha256").update(bytes).digest("hex");
-        const result = await publishWebScripts(input, loaded.value, sha256, options.signal);
+        const result = await publishWebScripts(input, loaded, sha256, {
+            resources,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
         return ok(createEvidence({ path: input.capture_path, sha256, format: "file" }, PROVIDER, {
             predicateType: "rea.web-script-export",
             operation: OPERATION,
@@ -59,71 +61,132 @@ export const exportWebScriptsValidated = async (input, options = {}) => {
             authority: "historical-reference",
             limitations: result.limitations,
             locations: [{ kind: "artifact-path", path: result.manifest.path }],
-            evidenceLinks: loaded.value.sourceEvidenceId === null
-                ? []
-                : [loaded.value.sourceEvidenceId],
+            evidenceLinks: loaded.sourceEvidenceId === null ? [] : [loaded.sourceEvidenceId],
         }));
     }
     catch (cause) {
-        if (cause instanceof WebScriptExportError)
-            return err(cause);
-        if (options.signal?.aborted === true)
-            return err(new AnalysisCancelledError(OPERATION));
-        if (cause instanceof ArtifactReaderFailure)
-            return err(new WebScriptExportError(cause.reason, input.output_directory, cause.message));
-        if (cause instanceof z.ZodError)
-            return err(new AnalysisOutputError(OPERATION, cause.message, { cause }));
-        if (cause instanceof Error &&
-            "code" in cause &&
-            typeof cause.code === "string")
-            return err(new WebScriptExportError("io", `${input.capture_path} → ${input.output_directory}`, cause.message));
-        return err(new ProviderAdapterError(PROVIDER.id, OPERATION, {
-            cause,
-            diagnostics: {
-                capture_path: input.capture_path,
-                output_directory: input.output_directory,
-                error_name: cause instanceof Error ? cause.name : "UnknownError",
-                error_message: cause instanceof Error
-                    ? cause.message
-                    : typeof cause === "string"
-                        ? cause
-                        : "Unknown script export failure",
-            },
-        }));
+        return err(mapExportFailure(cause, input, options.signal));
+    }
+};
+const prepareCapture = async (path, resources, signal) => {
+    const read = await resources.run(() => readCapture(path, resources, signal));
+    if (!read.ok)
+        return read;
+    const cleanup = read.value.cleanup;
+    const loaded = parseCapture(read.value.bytes, cleanup === undefined || cleanup.incomplete
+        ? undefined
+        : { cause: cleanup.cause });
+    if (!loaded.ok)
+        return err(cleanup?.incomplete === true
+            ? incompleteCaptureCleanup(loaded.error, path, cleanup)
+            : loaded.error);
+    if (cleanup !== undefined) {
+        const primary = new WebScriptExportError("io", path, `Capture handle close failed: ${cleanup.reason}`, { cause: cleanup.cause });
+        return err(cleanup.incomplete
+            ? incompleteCaptureCleanup(primary, path, cleanup)
+            : primary);
     }
+    return ok({ bytes: read.value.bytes, loaded: loaded.value });
+};
+const mapExportFailure = (cause, input, signal) => {
+    if (cause instanceof WebScriptExportError)
+        return cause;
+    if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)
+        return analysisErrorWithCleanupFailure(new WebScriptExportError(cause.reason, input.output_directory, cause.message, { cause }), new ProviderCleanupError(PROVIDER.id, cause.cleanup.resources, { reason: cause.cleanup.reason }, { cause, operation: OPERATION }), OPERATION);
+    if (signal?.aborted === true)
+        return new AnalysisCancelledError(OPERATION, { cause });
+    if (cause instanceof ArtifactReaderFailure)
+        return new WebScriptExportError(cause.reason, input.output_directory, cause.message, { cause });
+    if (cause instanceof z.ZodError)
+        return new AnalysisOutputError(OPERATION, cause.message, { cause });
+    if (cause instanceof Error &&
+        "code" in cause &&
+        typeof cause.code === "string")
+        return new WebScriptExportError("io", `${input.capture_path} → ${input.output_directory}`, cause.message, { cause });
+    return new ProviderAdapterError(PROVIDER.id, OPERATION, {
+        cause,
+        diagnostics: {
+            capture_path: input.capture_path,
+            output_directory: input.output_directory,
+            error_name: cause instanceof Error ? cause.name : "UnknownError",
+            error_message: cause instanceof Error
+                ? cause.message
+                : typeof cause === "string"
+                    ? cause
+                    : "Unknown script export failure",
+        },
+    });
 };
 /**
  * Read the caller-selected capture. A missing, non-file or unreadable
  * selection is a caller or host-permission failure, not an export failure.
  */
-const readCapture = async (path, signal) => {
+const readCapture = async (path, resources, signal) => {
     try {
-        return ok(await readRegularFile(path, signal));
+        return ok({ bytes: await readRegularFile(path, { signal }) });
     }
     catch (cause) {
-        const code = cause instanceof Error && "code" in cause ? String(cause.code) : "";
-        if (code === "EACCES" || code === "EPERM")
-            return err(new AnalysisAccessDeniedError(OPERATION, path, code, { cause }));
-        if (cause instanceof NonRegularFileReadError ||
-            code === "ENOENT" ||
-            code === "ENOTDIR" ||
-            code === "EISDIR" ||
-            code === "ENXIO")
-            return err(new AnalysisInputError(OPERATION, { cause }, [
-                {
-                    path: ["capture_path"],
-                    reason: "invalid_value",
-                    message: cause instanceof NonRegularFileReadError && code !== "EISDIR"
-                        ? cause.message
-                        : code === "EISDIR"
-                            ? `Selected capture is a directory, not a file: ${path}`
-                            : `Selected capture could not be read (${code}): ${path}`,
-                },
-            ]));
-        throw cause;
+        if (cause instanceof RegularFileCleanupFailure) {
+            const retry = await retryRegularFileCleanup(cause, resources);
+            const cleanup = {
+                reason: retry.cleanup?.reason ?? errorMessage(cause.cleanupCause),
+                incomplete: retry.cleanup !== undefined,
+                cause: cause.cleanupCause,
+            };
+            if (cause.outcome.kind === "completed")
+                return ok({ bytes: cause.outcome.value, cleanup });
+            const primary = captureReadFailure(path, cause.outcome.cause, signal, retry.cleanup === undefined ? { cause: cause.cleanupCause } : undefined);
+            return err(retry.cleanup === undefined
+                ? primary
+                : incompleteCaptureCleanup(primary, path, cleanup));
+        }
+        return err(captureReadFailure(path, cause, signal));
     }
 };
-const parseCapture = (bytes) => {
+const captureReadFailure = (path, cause, signal, closeFailure) => {
+    const causeWithClose = closeFailure === undefined
+        ? cause
+        : new AggregateError([cause, closeFailure.cause], "Capture read and file-handle close both failed", { cause });
+    if (signal?.aborted === true)
+        return new AnalysisCancelledError(OPERATION, { cause: causeWithClose });
+    const code = cause instanceof Error && "code" in cause ? String(cause.code) : "";
+    if (code === "EACCES" || code === "EPERM")
+        return new AnalysisAccessDeniedError(OPERATION, path, code, {
+            cause: causeWithClose,
+        });
+    if (cause instanceof NonRegularFileReadError ||
+        cause instanceof RegularFileChangedError ||
+        code === "ENOENT" ||
+        code === "ENOTDIR" ||
+        code === "EISDIR" ||
+        code === "ENXIO")
+        return new AnalysisInputError(OPERATION, { cause: causeWithClose }, [
+            {
+                path: ["capture_path"],
+                reason: "invalid_value",
+                message: cause instanceof NonRegularFileReadError && code !== "EISDIR"
+                    ? cause.message
+                    : code === "EISDIR"
+                        ? `Selected capture is a directory, not a file: ${path}`
+                        : `Selected capture could not be read (${code}): ${path}`,
+            },
+        ]);
+    if (code !== "")
+        return new WebScriptExportError("io", path, errorMessage(cause), {
+            cause: causeWithClose,
+        });
+    return new ProviderAdapterError(PROVIDER.id, OPERATION, {
+        cause: causeWithClose,
+        diagnostics: {
+            capture_path: path,
+            error_name: cause instanceof Error ? cause.name : "UnknownError",
+            error_message: cause instanceof Error ? cause.message : String(cause),
+        },
+    });
+};
+const incompleteCaptureCleanup = (primary, path, cleanup) => analysisErrorWithCleanupFailure(primary, new ProviderCleanupError(PROVIDER.id, [path], { reason: cleanup.reason }, { cause: cleanup.cause, operation: OPERATION }), OPERATION);
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+const parseCapture = (bytes, closeFailure) => {
     try {
         const text = new TextDecoder("utf-8", {
             fatal: true,
@@ -135,7 +198,10 @@ const parseCapture = (bytes) => {
         return ok(selectScriptCapture(json.value));
     }
     catch (cause) {
-        return err(new AnalysisInputError(OPERATION, { cause }, [
+        const causeWithClose = closeFailure === undefined
+            ? cause
+            : new AggregateError([cause, closeFailure.cause], "Capture parse and file-handle close both failed", { cause });
+        return err(new AnalysisInputError(OPERATION, { cause: causeWithClose }, [
             {
                 path: ["capture_path"],
                 reason: "invalid_format",

package/dist/application/WebSourceLocationService.js

@@ -35,6 +35,9 @@ export class WebSourceLocationService {
         this.artifacts = artifacts;
         this.decoder = decoder;
     }
+    close() {
+        return this.decoder.close?.() ?? Promise.resolve();
+    }
     /** Shared CLI/MCP workflow preserves raw declarations and every equal-position match. */
     async trace(rawInput, options) {
         if (options?.signal?.aborted)

package/dist/application/adb/AdbDeviceAnalysisPort.js

@@ -0,0 +1 @@
+export {};

package/dist/application/adb/AdbDeviceAnalysisService.js

@@ -0,0 +1,13 @@
+import { adbRequestSchema, } from "../../domain/adb/adbDeviceAnalysis.js";
+import { executeProviderOperation } from "../ProviderOperationExecution.js";
+/** Shared CLI/MCP admission, execution, and Evidence composition for ADB. */
+export class AdbDeviceAnalysisService {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    /** Run one caller-selected ADB request and retain device provenance inline. */
+    async execute(operation, input, options) {
+        return executeProviderOperation(operation, input, options, adbRequestSchema, this.provider, "observed");
+    }
+}