diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.md index 2d85ef857a..8c7b4fa06a 100644 --- a/docs/mcp-contracts.md +++ b/docs/mcp-contracts.md @@ -404,13 +404,14 @@ at that bounded check. These are historical snapshots, not live process inventories, and do not claim that no short-lived descendant existed. `binary_session.cleanup_pending` reports whether the session retains a provider -client whose cleanup has not succeeded. It can be true with `open: false`; -target retirement does not establish resource release. Health, activity, and -lineage remain available under that client's original `analysis_run.run_id` -where the provider supplies them. Successful cleanup clears the retained run; -a replacement client receives a fresh run ID. Follow the cleanup error's -reported resources and recovery action before reopening; a missing health -observation does not establish an idle provider. +client, session file resource, or provider-candidate resource whose cleanup has +not succeeded. It can be true with `open: false`; target retirement does not +establish resource release. Health, activity, and lineage remain available +under a retained client's original `analysis_run.run_id` where the provider +supplies them. Successful client cleanup clears the retained run; a replacement +client receives a fresh run ID. Follow the cleanup error's reported resources +and recovery action before reopening; a missing health observation does not +establish an idle provider. ## Progress and cancellation diff --git a/src/application/AnalysisProvider.ts b/src/application/AnalysisProvider.ts index 20f80720c1..335018d74c 100644 --- a/src/application/AnalysisProvider.ts +++ b/src/application/AnalysisProvider.ts @@ -290,6 +290,8 @@ export interface AnalysisProviderCandidate extends AnalysisProvider { inspectAvailability(): ProviderAvailability; inspectReadinessSnapshot?(): AnalysisProviderReadinessSnapshot; inspectTargetSupport(target: BinaryTarget): ProviderTargetSupport; + /** Report retained candidate-owned cleanup without starting work or retrying it. */ + hasPendingOwnedResources?(): boolean; /** Release candidate-owned resources that may exist without a client. */ closeOwnedResources?(): Promise>; } diff --git a/src/application/binary/AnalysisProviderRegistry.ts b/src/application/binary/AnalysisProviderRegistry.ts index e0bf6e962c..deac9d4372 100644 --- a/src/application/binary/AnalysisProviderRegistry.ts +++ b/src/application/binary/AnalysisProviderRegistry.ts @@ -136,6 +136,13 @@ export class AnalysisProviderRegistry { ); } + /** Report retained candidate resources without retrying cleanup. */ + hasPendingOwnedResources(): boolean { + return this.#providers.some( + (provider) => provider.hasPendingOwnedResources?.() === true, + ); + } + /** Close candidate-owned resources even when no target client was opened. */ async closeOwnedResources(): Promise> { const failures: AnalysisError[] = []; diff --git a/src/application/binary/BinarySession.ts b/src/application/binary/BinarySession.ts index 0eb51ab348..9bb34760bd 100644 --- a/src/application/binary/BinarySession.ts +++ b/src/application/binary/BinarySession.ts @@ -594,7 +594,10 @@ export class BinarySession runtimeLineageSnapshots: client?.runtimeLineageSnapshots?.() ?? [], requestActivitySnapshots: client?.requestActivitySnapshots?.() ?? [], providerOperationHealth: client?.operationHealthSnapshot?.() ?? null, - cleanupPending: this.#pendingCleanup !== undefined, + cleanupPending: + this.#pendingCleanup !== undefined || + this.hasPendingWriteResources || + this.#providerRouter.hasPendingOwnedResources(), }); } diff --git a/src/application/binary/BinarySessionRecords.ts b/src/application/binary/BinarySessionRecords.ts index 456ca70ef9..2ea612cb42 100644 --- a/src/application/binary/BinarySessionRecords.ts +++ b/src/application/binary/BinarySessionRecords.ts @@ -63,6 +63,11 @@ export abstract class BinarySessionRecords { this.#records = records; } + /** Snapshot staging retained after a failed resource cleanup attempt. */ + protected get hasPendingWriteResources(): boolean { + return this.#writeResources.hasPending; + } + /** Observe changes to the mutable current analysis snapshot resource. */ onAnalysisSnapshotChanged(listener: () => void | Promise): () => void { this.#snapshotListeners.add(listener); diff --git a/src/application/binary/SessionProviderRouter.ts b/src/application/binary/SessionProviderRouter.ts index ebb5385197..e5babdf669 100644 --- a/src/application/binary/SessionProviderRouter.ts +++ b/src/application/binary/SessionProviderRouter.ts @@ -75,6 +75,11 @@ export class SessionProviderRouter { return this.registry.closeOwnedResources(); } + /** Report retained candidate cleanup without performing cleanup work. */ + hasPendingOwnedResources(): boolean { + return this.registry.hasPendingOwnedResources(); + } + /** Resolve target routes before any provider client is created. */ async resolve( target: BinaryTarget, diff --git a/src/kuna/KunaProjectCache.ts b/src/kuna/KunaProjectCache.ts index 2fc892a7f8..5d522e7a5d 100644 --- a/src/kuna/KunaProjectCache.ts +++ b/src/kuna/KunaProjectCache.ts @@ -248,6 +248,15 @@ export class KunaProjectCache { this.#launcher = options.launcher; } + /** Report cleanup owners retained after failed process or file cleanup. */ + get hasPendingCleanup(): boolean { + return ( + this.#retainedProcesses.length > 0 || + this.#retainedFiles.size > 0 || + this.#retainedHashHandles.size > 0 + ); + } + /** Keep an entry from eviction while this process serves it. */ pin(key: string): () => void { this.#pins.set(key, (this.#pins.get(key) ?? 0) + 1); diff --git a/src/kuna/KunaProvider.ts b/src/kuna/KunaProvider.ts index c54a852c65..978ce2abf4 100644 --- a/src/kuna/KunaProvider.ts +++ b/src/kuna/KunaProvider.ts @@ -298,6 +298,14 @@ export class KunaProvider implements AnalysisProviderCandidate { ); } + /** Report retained file cleanup without probing readiness or retrying owners. */ + hasPendingOwnedResources(): boolean { + return ( + this.#readinessFileOwners.size > 0 || + this.#cache?.hasPendingCleanup === true + ); + } + async #closeReadinessOwners() { const failures: { readonly path: string; readonly cause: unknown }[] = []; for (const [owner, path] of this.#readinessFileOwners) { diff --git a/tests/boundary/filesystem/analysisSnapshot.test.ts b/tests/boundary/filesystem/analysisSnapshot.test.ts index e4b331538d..ef7e1cf088 100644 --- a/tests/boundary/filesystem/analysisSnapshot.test.ts +++ b/tests/boundary/filesystem/analysisSnapshot.test.ts @@ -32,6 +32,8 @@ import { readJsonObjectFile } from "../../../src/application/JsonInputFile.js"; import { RegularFileChangedError } from "../../../src/filesystem/RegularFile.js"; import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js"; import { RegularFileCleanupFailure } from "../../../src/application/RegularFileRead.js"; +import { OwnedStagedOutput } from "../../../src/filesystem/OwnedStagedOutput.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; const snapshotFixture = (): AnalysisSnapshot => { const target = snapshotTarget(TARGET); @@ -76,6 +78,50 @@ const snapshotFixture = (): AnalysisSnapshot => { }; describe("analysis snapshots: persistence", () => { + it("reports retained snapshot staging without an active provider and clears it after retry", async () => { + const directory = await createTestTempDirectory( + "rea-snapshot-cleanup-status-", + ); + const path = join(directory, "analysis.json"); + const session = createTestBinarySession(() => { + throw new Error("Snapshot persistence must not create a provider client"); + }); + const close = vi + .spyOn(OwnedStagedOutput.prototype, "close") + .mockRejectedValue(new Error("Controlled staging cleanup failure")); + onTestFinished(async () => { + close.mockRestore(); + const closed = await session.close(); + if (!closed.ok) throw closed.error; + }); + + const written = await session.writeAnalysisSnapshot( + snapshotFixture(), + path, + false, + ); + expect(written).toMatchObject({ + ok: false, + error: { cleanupIncomplete: true, published: { path } }, + }); + expect( + parseAnalysisSnapshot(JSON.parse(await readFile(path, "utf8"))), + ).toEqual(snapshotFixture()); + expect(session.status()).toMatchObject({ + open: false, + cleanup_pending: true, + }); + expect(await session.close()).toMatchObject({ + ok: false, + error: { cleanupIncomplete: true }, + }); + expect(session.status()).toMatchObject({ cleanup_pending: true }); + + close.mockRestore(); + expect(await session.close()).toEqual({ ok: true, value: null }); + expect(session.status()).toMatchObject({ cleanup_pending: false }); + }); + it("writes canonical private v2 JSON and rejects changed query identity", async () => { const directory = await createTestTempDirectory("rea-snapshot-"); const path = join(directory, "analysis.json"); diff --git a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts index 6edb3c77f2..dcf9f97a3a 100644 --- a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts +++ b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts @@ -126,10 +126,25 @@ it.skipIf(process.platform === "win32")( cleanupResources: [fixture.kuna], }); expect(injected.closeCalls).toBe(2); + expect(binary.status()).toMatchObject({ + open: false, + cleanup_pending: true, + }); + + expect(await binary.close()).toMatchObject({ + ok: false, + error: { + cleanupIncomplete: true, + cleanupResources: [fixture.kuna], + }, + }); + expect(injected.closeCalls).toBe(3); + expect(binary.status()).toMatchObject({ cleanup_pending: true }); injected.releaseCloseFailures = true; expect(await binary.close()).toEqual({ ok: true, value: null }); - expect(injected.closeCalls).toBe(3); + expect(injected.closeCalls).toBe(4); + expect(binary.status()).toMatchObject({ cleanup_pending: false }); expect((await fakeKunaCalls(fixture.kuna)).map(({ argv }) => argv)).toEqual( [["--version"], ["--version"]], );