@vibe-agent-toolkit/cli 0.2.0-rc.10 → 0.2.0-rc.12

package/dist/commands/cache/clear-schema.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The document `vat cache clear` publishes, apart from the command.
+ *
+ * A sibling module because the published-shape registry imports it and the
+ * command imports the writer that imports the registry (the cycle
+ * `report-schemas.ts` describes).
+ *
+ * `examined` counts the cache locations considered — always one, the shared
+ * `<tmpdir>/.vat-cache` root. A root that does not exist is considered and
+ * empty (`existed: false`, `ok`). The tree is moved off its path whole before it
+ * is removed, so there is no partial clear: a refusal before that is the error
+ * branch with `data: null`; a delete the OS stops after it is the error branch
+ * (`RUN_INCOMPLETE`) with this `data` — the clear is done — and a
+ * TREE_CLEANUP_INCOMPLETE warning naming where the moved-aside tree is.
+ */
+import { type Report } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+import type { ExaminedDeclaration } from '../../utils/run-integrity.js';
+/** What `examined` counts for `vat cache clear`, and the remedy when it is zero. */
+export declare const CACHE_CLEAR_EXAMINED: ExaminedDeclaration;
+declare const CacheClearDataSchema: z.ZodObject<{
+    /** Absolute path of the tree targeted. */
+    cacheDir: z.ZodString;
+    /** Whether the directory was there at all. */
+    existed: z.ZodBoolean;
+    /** Top-level entries that are gone, sorted. */
+    removed: z.ZodArray<z.ZodString, "many">;
+    /** Files (and other non-directory entries) actually removed. */
+    entriesRemoved: z.ZodNumber;
+    /** Bytes actually removed. */
+    bytesRemoved: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    cacheDir: string;
+    existed: boolean;
+    removed: string[];
+    entriesRemoved: number;
+    bytesRemoved: number;
+}, {
+    cacheDir: string;
+    existed: boolean;
+    removed: string[];
+    entriesRemoved: number;
+    bytesRemoved: number;
+}>;
+export type CacheClearData = z.infer<typeof CacheClearDataSchema>;
+/** The document this command publishes. */
+export declare const CACHE_CLEAR_REPORT_SCHEMA: import("@vibe-agent-toolkit/schema").ReportZodSchema<z.ZodObject<{
+    /** Absolute path of the tree targeted. */
+    cacheDir: z.ZodString;
+    /** Whether the directory was there at all. */
+    existed: z.ZodBoolean;
+    /** Top-level entries that are gone, sorted. */
+    removed: z.ZodArray<z.ZodString, "many">;
+    /** Files (and other non-directory entries) actually removed. */
+    entriesRemoved: z.ZodNumber;
+    /** Bytes actually removed. */
+    bytesRemoved: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    cacheDir: string;
+    existed: boolean;
+    removed: string[];
+    entriesRemoved: number;
+    bytesRemoved: number;
+}, {
+    cacheDir: string;
+    existed: boolean;
+    removed: string[];
+    entriesRemoved: number;
+    bytesRemoved: number;
+}>, z.ZodObject<Omit<{
+    code: z.ZodString;
+    severity: z.ZodEnum<["error", "warning", "info", "ignore"]>;
+    message: z.ZodString;
+    location: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    line: z.ZodOptional<z.ZodNumber>;
+    field: z.ZodOptional<z.ZodString>;
+    link: z.ZodOptional<z.ZodString>;
+    fix: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    suggestion: z.ZodOptional<z.ZodString>;
+}, "severity"> & {
+    severity: z.ZodEnum<["error", "warning", "info"]>;
+    column: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    severity: "error" | "warning" | "info";
+    fix?: string | undefined;
+    reference?: string | undefined;
+    location?: string | undefined;
+    line?: number | undefined;
+    field?: string | undefined;
+    link?: string | undefined;
+    suggestion?: string | undefined;
+    column?: number | undefined;
+}, {
+    code: string;
+    message: string;
+    severity: "error" | "warning" | "info";
+    fix?: string | undefined;
+    reference?: string | undefined;
+    location?: string | undefined;
+    line?: number | undefined;
+    field?: string | undefined;
+    link?: string | undefined;
+    suggestion?: string | undefined;
+    column?: number | undefined;
+}>>;
+export type CacheClearReport = Report<CacheClearData>;
+export {};
+//# sourceMappingURL=clear-schema.d.ts.map

package/dist/commands/cache/clear-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear-schema.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/clear-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAA+B,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,EAAE,mBAGlC,CAAC;AAEF,QAAA,MAAM,oBAAoB;IACxB,0CAA0C;;IAE1C,8CAA8C;;IAE9C,+CAA+C;;IAE/C,gEAAgE;;IAEhE,8BAA8B;;;;;;;;;;;;;;EAErB,CAAC;AAEZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,2CAA2C;AAC3C,eAAO,MAAM,yBAAyB;IAfpC,0CAA0C;;IAE1C,8CAA8C;;IAE9C,+CAA+C;;IAE/C,gEAAgE;;IAEhE,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAO0D,CAAC;AAE3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC"}

package/dist/commands/cache/clear-schema.js

@@ -0,0 +1,37 @@
+/**
+ * The document `vat cache clear` publishes, apart from the command.
+ *
+ * A sibling module because the published-shape registry imports it and the
+ * command imports the writer that imports the registry (the cycle
+ * `report-schemas.ts` describes).
+ *
+ * `examined` counts the cache locations considered — always one, the shared
+ * `<tmpdir>/.vat-cache` root. A root that does not exist is considered and
+ * empty (`existed: false`, `ok`). The tree is moved off its path whole before it
+ * is removed, so there is no partial clear: a refusal before that is the error
+ * branch with `data: null`; a delete the OS stops after it is the error branch
+ * (`RUN_INCOMPLETE`) with this `data` — the clear is done — and a
+ * TREE_CLEANUP_INCOMPLETE warning naming where the moved-aside tree is.
+ */
+import { FindingSchema, reportSchema } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+/** What `examined` counts for `vat cache clear`, and the remedy when it is zero. */
+export const CACHE_CLEAR_EXAMINED = {
+    unit: 'cache locations',
+    whenZero: 'No cache location was considered, which is a defect in VAT — report it with the output of vat cache clear --debug.',
+};
+const CacheClearDataSchema = z.object({
+    /** Absolute path of the tree targeted. */
+    cacheDir: z.string(),
+    /** Whether the directory was there at all. */
+    existed: z.boolean(),
+    /** Top-level entries that are gone, sorted. */
+    removed: z.array(z.string()),
+    /** Files (and other non-directory entries) actually removed. */
+    entriesRemoved: z.number().int().nonnegative(),
+    /** Bytes actually removed. */
+    bytesRemoved: z.number().int().nonnegative(),
+}).strict();
+/** The document this command publishes. */
+export const CACHE_CLEAR_REPORT_SCHEMA = reportSchema(CacheClearDataSchema, FindingSchema);
+//# sourceMappingURL=clear-schema.js.map

package/dist/commands/cache/clear-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear-schema.js","sourceRoot":"","sources":["../../../src/commands/cache/clear-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,oFAAoF;AACpF,MAAM,CAAC,MAAM,oBAAoB,GAAwB;IACvD,IAAI,EAAE,iBAAiB;IACvB,QAAQ,EAAE,oHAAoH;CAC/H,CAAC;AAEF,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,0CAA0C;IAC1C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,8CAA8C;IAC9C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,+CAA+C;IAC/C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC5B,gEAAgE;IAChE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC9C,8BAA8B;IAC9B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CAC7C,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,2CAA2C;AAC3C,MAAM,CAAC,MAAM,yBAAyB,GAAG,YAAY,CAAC,oBAAoB,EAAE,aAAa,CAAC,CAAC"}

package/dist/commands/cache/clear.d.ts

@@ -24,32 +24,15 @@
  * the operator chose. Stated so nobody reads a clean `bytesRemoved` as "every
  * store is gone".
  */
+import type { CacheClearData } from './clear-schema.js';
 export interface CacheClearOptions {
     debug?: boolean;
 }
-/**
- * What a clear did, as published on stdout.
- *
- * `partial` is not a failure mode bolted on — it is the *common* outcome when
- * something else on the machine is writing to the shared tree, and it has to be
- * reportable. A recursive delete that gives up part-way has already removed most
- * of the cache; surfacing that as a bare thrown error told the operator only
- * that the command failed, while leaving them to guess how much of their cache
- * still existed. An honest count of what went and what stayed is the whole
- * point of a report.
- */
-export interface CacheClearReport {
-    status: 'success' | 'partial';
-    cacheDir: string;
-    existed: boolean;
-    /** Top-level entries that are gone, sorted. Empty when nothing was there. */
-    removed: string[];
-    /** Top-level entries that survived a partial clear, sorted. Absent on success. */
-    remaining?: string[];
-    /** Why the delete stopped short. Absent on success. */
-    reason?: string;
-    entriesRemoved: number;
-    bytesRemoved: number;
+/** What a clear finished: what it removed, and — when the OS would not then delete the tree it moved aside — that failure. */
+interface CacheClearOutcome {
+    readonly data: CacheClearData;
+    /** The moved-aside cache the OS would not delete: a `destination` fault naming where it is. */
+    readonly leftover?: unknown;
 }
 /**
  * The shared cache root, `<tmpdir>/.vat-cache`.
@@ -83,23 +66,42 @@ export interface CacheClearReport {
  */
 export declare function vatCacheRoot(): string;
 /**
- * Measure, then delete, an entire cache tree.
+ * Measure, then delete, an entire cache tree, as ONE tree-change plan: a `remove`
+ * of state VAT owns outright (`vat-state`).
  *
  * Measured BEFORE the delete, because afterwards there is nothing left to count
  * and a report of "removed: unknown" would make the command unverifiable.
  *
+ * The tree is moved off its path whole, then removed — so a delete the OS stops
+ * (another VAT writing into the shared tree, a file it will not unlink) leaves no
+ * part of a cache where the next run looks: the clear is done, and the failure is
+ * returned as `leftover`, naming where the moved-aside tree is — never a "partial"
+ * clear. A read-only directory the owner made is made writable on the way down,
+ * so it does not stop the delete.
+ *
  * Deliberately reads no environment: `vat cache clear` runs whether or not
  * caching is enabled for this process. A `VAT_CACHE=0` that also disarmed the
  * cleanup would leave an operator with a cache they can neither use nor remove.
  *
  * @param cacheDir - Directory to remove, in full
- * @returns What was removed
+ * @returns What was removed, and the `leftover` of a moved-aside tree the OS would not delete
+ * @throws {FsFaultError} an `environment` fault (`RUN_INCOMPLETE`) when the OS refuses to
+ *   list or stat an entry during the measurement; a `destination` fault (`RUN_INCOMPLETE`)
+ *   when it refuses to examine the cache path or to move the tree off it — nothing is
+ *   removed then
  */
-export declare function clearCacheDirectory(cacheDir: string): Promise<CacheClearReport>;
+export declare function clearCacheDirectory(cacheDir: string): Promise<CacheClearOutcome>;
 /**
  * Command entry point: clear the real cache root and publish the report.
  *
+ * A complete clear is `ok` — nothing there to remove included. A refusal before
+ * the tree left its path is the envelope's error branch with `data: null`. Once
+ * it is off its path the clear is done: a delete the OS then stops is still
+ * `RUN_INCOMPLETE`, published with the clear's `data` and a
+ * TREE_CLEANUP_INCOMPLETE warning naming where the moved-aside tree is.
+ *
  * @param options - Command options (only `--debug`, inherited from the root)
  */
 export declare function cacheClearCommand(options?: CacheClearOptions): Promise<void>;
+export {};
 //# sourceMappingURL=clear.d.ts.map

package/dist/commands/cache/clear.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clear.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/clear.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAgBH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;CACtB;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAcrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwBrF;AA+CD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtF"}
+{"version":3,"file":"clear.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/clear.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAaH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAWxD,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AASD,8HAA8H;AAC9H,UAAU,iBAAiB;IACzB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAcrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqBtF;AA8BD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAatF"}

package/dist/commands/cache/clear.js

@@ -24,35 +24,21 @@
  * the operator chose. Stated so nobody reads a clean `bytesRemoved` as "every
  * store is gone".
  */
-import { promises as fs } from 'node:fs';
+import { promises as fs, lstatSync } from 'node:fs';
 import { basename, dirname } from 'node:path';
 import { parseCacheDirectory } from '@vibe-agent-toolkit/resources';
-import { ExitCode } from '@vibe-agent-toolkit/schema';
-import { direntKind, isPathAbsentError, safePath } from '@vibe-agent-toolkit/utils';
-import { handleCommandError } from '../../utils/command-error.js';
+import { buildReport, toFindings } from '@vibe-agent-toolkit/schema';
+import { applyTreePlanOrLeftover, classifyFsFault, isFsFaultError, direntKind, everywhere, isPathAbsentError, planTreeChanges, requireConfirmedAbsent, safePath } from '@vibe-agent-toolkit/utils';
+import { refusalCodeOf } from '../../utils/command-refusal.js';
+import { endWithRefusal, endWithReport, leftoverIssueOf, NOTHING_FINISHED } from '../../utils/document-writer.js';
 import { createLogger } from '../../utils/logger.js';
-import { writeYamlOutput } from '../../utils/output.js';
 /** The one name the shared cache root is allowed to have. See {@link vatCacheRoot}. */
 const VAT_CACHE_DIR_NAME = '.vat-cache';
+/** `vat cache clear` has no `--strict`, and its only finding is a leftover warning: the gate is fixed. */
+const CACHE_CLEAR_GATE = { strict: false };
+/** One location is considered on every run: the shared cache root. */
+const CACHE_LOCATIONS_CONSIDERED = 1;
 const EMPTY_USAGE = { entries: 0, bytes: 0 };
-/**
- * Retry budget for the recursive delete.
- *
- * Not defensive padding — observed. `<tmpdir>/.vat-cache` is shared by every VAT
- * on the machine: other worktrees, other sessions, and any adopter running an
- * *installed* vat all write into it under their own namespace. A `vat cache
- * clear` issued while one of them is mid-run walks a tree that is growing
- * underneath it and `rmdir` fails `ENOTEMPTY` on a shard that gained a file
- * between the listing and the removal. Reproduced twice against a concurrent
- * `vat verify`; the same command succeeded immediately once that run finished.
- *
- * Node retries exactly this error class (`EBUSY`, `EMFILE`, `ENFILE`,
- * `ENOTEMPTY`, `EPERM`) with a linear backoff, which clears a short overlap.
- * It cannot win against a writer that keeps going for the whole window — that
- * case still surfaces as an error, which is correct: "some of your cache is
- * gone and something is still writing" must not be reported as success.
- */
-const RM_RETRY = { maxRetries: 5, retryDelay: 100 };
 /**
  * The shared cache root, `<tmpdir>/.vat-cache`.
  *
@@ -95,72 +81,77 @@ export function vatCacheRoot() {
     return root;
 }
 /**
- * Measure, then delete, an entire cache tree.
+ * Measure, then delete, an entire cache tree, as ONE tree-change plan: a `remove`
+ * of state VAT owns outright (`vat-state`).
  *
  * Measured BEFORE the delete, because afterwards there is nothing left to count
  * and a report of "removed: unknown" would make the command unverifiable.
  *
+ * The tree is moved off its path whole, then removed — so a delete the OS stops
+ * (another VAT writing into the shared tree, a file it will not unlink) leaves no
+ * part of a cache where the next run looks: the clear is done, and the failure is
+ * returned as `leftover`, naming where the moved-aside tree is — never a "partial"
+ * clear. A read-only directory the owner made is made writable on the way down,
+ * so it does not stop the delete.
+ *
  * Deliberately reads no environment: `vat cache clear` runs whether or not
  * caching is enabled for this process. A `VAT_CACHE=0` that also disarmed the
  * cleanup would leave an operator with a cache they can neither use nor remove.
  *
  * @param cacheDir - Directory to remove, in full
- * @returns What was removed
+ * @returns What was removed, and the `leftover` of a moved-aside tree the OS would not delete
+ * @throws {FsFaultError} an `environment` fault (`RUN_INCOMPLETE`) when the OS refuses to
+ *   list or stat an entry during the measurement; a `destination` fault (`RUN_INCOMPLETE`)
+ *   when it refuses to examine the cache path or to move the tree off it — nothing is
+ *   removed then
  */
 export async function clearCacheDirectory(cacheDir) {
-    const entries = await readdirOrNull(cacheDir);
-    if (entries === null) {
-        return { status: 'success', cacheDir, existed: false, removed: [], entriesRemoved: 0, bytesRemoved: 0 };
-    }
-    const usage = await measureEntries(cacheDir, entries);
-    const names = entries.map((entry) => entry.name);
+    const absent = { data: { cacheDir, existed: false, removed: [], entriesRemoved: 0, bytesRemoved: 0 } };
+    const plan = await planTreeChanges([{ op: 'remove', dest: cacheDir, ownership: { kind: 'vat-state' }, label: 'the VAT cache' }]);
+    const existing = plan.changes[0]?.existing ?? 'absent';
+    if (existing === 'absent')
+        return absent;
+    // Another clear (any VAT on the machine) may take the cache between the plan and the move: gone
+    // is the goal state, so that is a clear of nothing — never a refusal.
+    const measured = await measureRoot(cacheDir, existing);
+    if (measured === undefined)
+        return absent;
+    let leftover;
     try {
-        await fs.rm(cacheDir, { recursive: true, force: true, ...RM_RETRY });
+        ({ leftover } = await applyTreePlanOrLeftover(plan));
     }
     catch (error) {
-        return partialReport(cacheDir, names, usage, error);
+        if (isFsFaultError(error) && error.faultClass === 'absent' && goneNow(cacheDir))
+            return absent;
+        throw error;
     }
-    return {
-        status: 'success',
-        cacheDir,
-        existed: true,
-        removed: sorted(names),
-        entriesRemoved: usage.entries,
-        bytesRemoved: usage.bytes,
-    };
+    const { names, usage } = measured;
+    const data = { cacheDir, existed: true, removed: sorted(names), entriesRemoved: usage.entries, bytesRemoved: usage.bytes };
+    return leftover === undefined ? { data } : { data, leftover };
 }
 /**
- * Describe a delete that stopped part-way, by re-reading the tree.
- *
- * The survivors are read back off disk rather than inferred from the error,
- * because the error names one path and says nothing about the other ninety-nine
- * percent. Re-measuring what remains and subtracting is the only way the counts
- * describe what actually happened rather than what was attempted.
- *
- * A concurrent writer can make the remainder *larger* than the original
- * measurement, so the subtraction is floored at zero: reporting a negative
- * number of removed bytes would be worse than reporting none.
- *
- * @param cacheDir - The tree that was being removed
- * @param names - Top-level entry names as they were before the delete
- * @param before - Usage measured before the delete
- * @param error - Whatever `fs.rm` threw
- * @returns A report naming what went, what stayed, and why
+ * What the delete will take: the root's top-level names and the whole tree's usage — or `undefined`
+ * when the root has really vanished since the plan saw it. A root that is not a directory (a link,
+ * a file someone put there) is one entry, never followed: the delete removes the entry itself, and
+ * counting a link's target would report a tree it never touches.
  */
-async function partialReport(cacheDir, names, before, error) {
-    const survivors = (await readdirOrNull(cacheDir)) ?? [];
-    const remaining = new Set(survivors.map((entry) => entry.name));
-    const after = await measureEntries(cacheDir, survivors);
-    return {
-        status: 'partial',
-        cacheDir,
-        existed: true,
-        removed: sorted(names.filter((name) => !remaining.has(name))),
-        remaining: sorted([...remaining]),
-        reason: error instanceof Error ? error.message : String(error),
-        entriesRemoved: Math.max(0, before.entries - after.entries),
-        bytesRemoved: Math.max(0, before.bytes - after.bytes),
-    };
+async function measureRoot(cacheDir, existing) {
+    if (existing !== 'directory')
+        return { names: [], usage: { entries: 1, bytes: await sizeOf(cacheDir) } };
+    const entries = await listedOrVanished(cacheDir);
+    if (entries === null)
+        return undefined;
+    return { names: entries.map((entry) => entry.name), usage: await measureEntries(cacheDir, entries) };
+}
+/** Whether nothing is at `cacheDir` now, believed only when its parent's listing agrees ({@link vanished}). */
+function goneNow(cacheDir) {
+    try {
+        lstatSync(cacheDir);
+        return false;
+    }
+    catch (error) {
+        return vanished(error, cacheDir, { side: 'destination', action: 'examine the cache', path: cacheDir });
+    }
 }
 /** Stable ordering for the reported entry lists. */
 function sorted(names) {
@@ -169,41 +160,57 @@ function sorted(names) {
 /**
  * Command entry point: clear the real cache root and publish the report.
  *
+ * A complete clear is `ok` — nothing there to remove included. A refusal before
+ * the tree left its path is the envelope's error branch with `data: null`. Once
+ * it is off its path the clear is done: a delete the OS then stops is still
+ * `RUN_INCOMPLETE`, published with the clear's `data` and a
+ * TREE_CLEANUP_INCOMPLETE warning naming where the moved-aside tree is.
+ *
  * @param options - Command options (only `--debug`, inherited from the root)
  */
 export async function cacheClearCommand(options = {}) {
-    const startTime = Date.now();
     const logger = createLogger(options.debug ? { debug: true } : {});
+    let outcome;
     try {
-        const report = await clearCacheDirectory(vatCacheRoot());
-        logger.debug(`Cleared ${String(report.entriesRemoved)} cache entries from ${report.cacheDir}`);
-        writeYamlOutput(report);
-        // A partial clear publishes its report and *then* fails. Exiting through
-        // `handleCommandError` instead would suppress the report entirely, which is
-        // the defect this branch exists to fix: the operator most needs to know how
-        // much of the cache survived precisely when the command did not finish.
-        // A partial clear is a run that did not finish, not a finding about the tree.
-        process.exit(report.status === 'partial' ? ExitCode.ERROR : ExitCode.OK);
+        outcome = await clearCacheDirectory(vatCacheRoot());
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'CacheClear');
+        return refuse(error, NOTHING_FINISHED);
     }
+    const { data, leftover } = outcome;
+    if (leftover !== undefined)
+        return refuse(leftover, { examined: CACHE_LOCATIONS_CONSIDERED, findings: toFindings([leftoverIssueOf(leftover)]), data });
+    logger.debug(`Cleared ${String(data.entriesRemoved)} cache entries from ${data.cacheDir}`);
+    endWithReport('cache clear', buildReport({ examined: CACHE_LOCATIONS_CONSIDERED, findings: [], data, gate: CACHE_CLEAR_GATE }), 'yaml');
+}
+/** End on the envelope's error branch: `error` refused, `finished` the work done before it. */
+function refuse(error, finished) {
+    return endWithRefusal('cache clear', refusalCodeOf(error), error, 'yaml', CACHE_CLEAR_GATE, finished);
 }
 /**
- * `readdir` that reports a missing directory as `null` rather than throwing.
- *
- * Only ENOENT is absorbed. EACCES on a directory that exists is a genuine
- * failure — reporting it as "nothing to clear" would tell the operator their
- * cache is gone when it is still on disk.
+ * Whether `error`, from a probe of `target`, says it is gone — believed only when the parent's
+ * listing agrees (a concurrent run pruning its own entry). An `ENOENT` for an entry the parent
+ * still names is a refusal, thrown classified: reading it as "gone" would report a cache that is
+ * on disk as cleared, or as never there. Any other error is thrown classified on `ctx`.
  */
-async function readdirOrNull(dir) {
+function vanished(error, target, ctx) {
+    if (!isPathAbsentError(error))
+        throw classifyFsFault(error, { ...ctx, path: target });
+    requireConfirmedAbsent(target, error, { action: ctx.action, path: target }, { follows: false, sideOf: everywhere(ctx.side) });
+    return true;
+}
+/**
+ * List `dir`, or `null` when it has really vanished (see {@link vanished}). The cache is VAT's own
+ * scratch, so a listing the OS refuses is an `environment` fault.
+ */
+async function listedOrVanished(dir) {
+    const ctx = { side: 'environment', action: 'list the cache', path: dir };
     try {
         return await fs.readdir(dir, { withFileTypes: true });
     }
     catch (error) {
-        if (error.code === 'ENOENT')
-            return null;
-        throw error;
+        vanished(error, dir, ctx);
+        return null;
     }
 }
 /** Sum file count and bytes over already-listed directory entries. */
@@ -213,26 +220,25 @@ async function measureEntries(dir, entries) {
         // Not `isFile()`, and NOT followed: a symlink or socket is still an entry
         // that is about to be removed, and counting only regular files would
         // under-report it — while walking INTO a linked directory would count a
-        // tree `rm -rf` leaves untouched.
+        // tree the delete leaves untouched.
         return direntKind(entry) === 'directory' ? measureTree(child) : { entries: 1, bytes: await sizeOf(child) };
     }));
     return usages.reduce((total, usage) => ({ entries: total.entries + usage.entries, bytes: total.bytes + usage.bytes }), EMPTY_USAGE);
 }
-/** Recursive measure. A directory that vanished mid-walk contributes nothing. */
+/** Recursive measure. A directory that really vanished mid-walk contributes nothing. */
 async function measureTree(dir) {
-    const entries = await readdirOrNull(dir);
+    const entries = await listedOrVanished(dir);
     return entries === null ? EMPTY_USAGE : measureEntries(dir, entries);
 }
 /**
  * Size of one entry, without following symlinks.
  *
- * A file that disappears between the listing and the stat contributes 0 rather
- * than failing the clear — the whole tree is about to be deleted anyway, and a
- * concurrent vat run pruning its own temp file must not turn cleanup into an
+ * A file that really disappeared between the listing and the stat contributes 0
+ * rather than failing the clear — the whole tree is about to be deleted anyway,
+ * and a concurrent vat run pruning its own temp file must not turn cleanup into an
  * error. Only a DISAPPEARANCE is 0: an entry the OS refuses to stat is still
- * there, still about to be counted as reclaimed, and the `rm` that follows is
- * about to meet the same refusal — so it is raised here, where it names the
- * entry, rather than read as an empty file.
+ * there, still about to be counted as reclaimed — so it is raised here, where it
+ * names the entry, rather than read as an empty file.
  */
 async function sizeOf(target) {
     try {
@@ -240,9 +246,8 @@ async function sizeOf(target) {
         return stats.size;
     }
     catch (error) {
-        if (isPathAbsentError(error))
-            return 0;
-        throw error;
+        vanished(error, target, { side: 'environment', action: 'measure the cache', path: target });
+        return 0;
     }
 }
 //# sourceMappingURL=clear.js.map

package/dist/commands/cache/clear.js.map

@@ -1 +1 @@
-{"version":3,"file":"clear.js","sourceRoot":"","sources":["../../../src/commands/cache/clear.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAe,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAEpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,uFAAuF;AACvF,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAoCxC,MAAM,WAAW,GAAc,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,QAAQ,GAA+C,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,QAAQ,GAAG,mBAAmB,EAAE,CAAC;IACvC,6EAA6E;IAC7E,2EAA2E;IAC3E,6CAA6C;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAExC,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,kBAAkB,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,gCAAgC,kBAAkB,kBAAkB,QAAQ,IAAI,CAC1G,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAgB;IACxD,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;IAE9C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAC1G,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEjD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC;IAED,OAAO;QACL,MAAM,EAAE,SAAS;QACjB,QAAQ;QACR,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;QACtB,cAAc,EAAE,KAAK,CAAC,OAAO;QAC7B,YAAY,EAAE,KAAK,CAAC,KAAK;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,KAAK,UAAU,aAAa,CAC1B,QAAgB,EAChB,KAAe,EACf,MAAiB,EACjB,KAAc;IAEd,MAAM,SAAS,GAAG,CAAC,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAChE,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAExD,OAAO;QACL,MAAM,EAAE,SAAS;QACjB,QAAQ;QACR,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7D,SAAS,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;QACjC,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QAC9D,cAAc,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC3D,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;KACtD,CAAC;AACJ,CAAC;AAED,oDAAoD;AACpD,SAAS,MAAM,CAAC,KAAwB;IACtC,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,UAA6B,EAAE;IACrE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAElE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,YAAY,EAAE,CAAC,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,WAAW,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,uBAAuB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC/F,eAAe,CAAC,MAAM,CAAC,CAAC;QACxB,yEAAyE;QACzE,4EAA4E;QAC5E,4EAA4E;QAC5E,wEAAwE;QACxE,8EAA8E;QAC9E,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,aAAa,CAAC,GAAW;IACtC,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpE,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,KAAK,UAAU,cAAc,CAC3B,GAAW,EACX,OAAiB;IAEjB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAC9B,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,0EAA0E;QAC1E,qEAAqE;QACrE,wEAAwE;QACxE,kCAAkC;QAClC,OAAO,UAAU,CAAC,KAAK,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7G,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAClB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,EAChG,WAAW,CACZ,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,KAAK,UAAU,WAAW,CAAC,GAAW;IACpC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;;;;GAUG;AACH,KAAK,UAAU,MAAM,CAAC,MAAc;IAClC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACrC,OAAO,KAAK,CAAC,IAAI,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACvC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"clear.js","sourceRoot":"","sources":["../../../src/commands/cache/clear.ts"],"names":[],"mappings":"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"}

package/dist/commands/cache/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,kBAAkB,IAAI,OAAO,CAoF5C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,kBAAkB,IAAI,OAAO,CA0F5C"}

package/dist/commands/cache/index.js

@@ -70,21 +70,27 @@ Description:
   A cache directory that does not exist is not an error — nothing to remove is
   a successful clear.
 
-  The tree is shared by every VAT on the machine, so another run writing into
-  it can make the delete stop part-way. That is reported as status: partial,
-  naming what went and what stayed, rather than failing with no account of it.
+  The tree is moved off its path whole, then removed: a delete the OS stops
+  (another VAT writing into the shared tree, a file it will not remove) leaves
+  no part of a cache at <tmpdir>/.vat-cache. That is the report's error branch
+  (error.code RUN_INCOMPLETE) still carrying the data of the clear, with a
+  TREE_CLEANUP_INCOMPLETE warning naming where the moved-aside tree is, so you
+  can remove it yourself.
 
 Output:
+  A YAML report on stdout (status ok, or error); its data holds:
   - cacheDir: absolute path that was targeted
   - existed: whether the directory was there at all
   - removed: top-level entries that are now gone
-  - remaining / reason: what survived a partial clear, and why (partial only)
-  - entriesRemoved / bytesRemoved: file count and total size actually removed
+  - entriesRemoved / bytesRemoved: file count and total size removed
 
 Exit Codes:
   0 - Cache cleared (or already absent)
-  1 - Cleared only in part, because something else is using the tree
-  2 - Could not read or target the cache at all (permissions, unexpected layout)
+  2 - RUN_INCOMPLETE: the cache could not be examined, listed, measured or
+      moved off its path (nothing cleared, data null), or the moved-aside tree
+      could not then be deleted (cleared, data present, a warning naming it).
+      The cache is VAT's own scratch, so a refusal there is the run not
+      finishing; the document's error says which
 
 Example:
   $ vat cache clear                    # Reclaim the temp-directory cache tree