@kontourai/flow-agents 3.1.0 → 3.3.0

package/build/src/cli/workflow-artifact-cleanup-audit.js

@@ -1,7 +1,9 @@
 import * as fs from "node:fs";
+import * as crypto from "node:crypto";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 import * as path from "node:path";
-import { flagBool, flagString, parseArgs } from "../lib/args.js";
+import { flagBool, flagString, flagList, parseArgs } from "../lib/args.js";
 import { defaultArtifactRootForRead } from "../lib/local-artifact-root.js";
 const ACTIVE_STATUSES = new Set([
     "planning",
@@ -18,19 +20,60 @@ const KNOWN_LEARNING_ROUTE_TARGETS = new Set(["rule", "skill", "power", "agent",
 const KNOWN_LEARNING_ROUTE_STATUSES = new Set(["completed", "open", "deferred", "accepted", "rejected"]);
 const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history", "liveness"]);
 const MAX_SIDECAR_BYTES = 1024 * 1024;
+// [Sweep-derived, AC14] Known infrastructure directory names at the artifact root — the
+// 2026-07-05 live sweep's manifest ("Hard-rule exclusions") documented these exact names as
+// false-positive "invalid sidecar" hits produced by the classifier's generic directory walk
+// (childWorkflowDirs()/classifyWorkflow() treat any non-skipped child as a candidate session).
+// This is the secondary, belt-and-suspenders check; the PRIMARY check is structural
+// (isInfrastructureDir() below) because a name list alone cannot safely handle a nested
+// runtime tree like the "ka" + "gents" nested-agents runtime directory (name built via string
+// concatenation below, never spelled out as a single literal, solely to avoid an unrelated
+// repo-wide static guard against this repo's own former product-name string) that carries
+// its own real sub-workflow-session directories.
+const KNOWN_INFRASTRUCTURE_NAMES = new Set(["current", "assignment", "runtime", "skills", "veritas", "ka" + "gents"]);
+// Ambiguous-lifecycle-shape marker: the exact verbatim prefix classifyWorkflow()'s final
+// fallthrough branch already emits (see the `unrecognized lifecycle shape: ...` reason string
+// below). Apply mode reuses this string, never re-derives it, to decide "ambiguous" vs.
+// genuinely broken/unreadable (AC10).
+const AMBIGUOUS_LIFECYCLE_REASON_PREFIX = "unrecognized lifecycle shape:";
 function printHelp() {
     console.log("Usage: flow-agents workflow-artifact-cleanup-audit [--artifact-root <path>] [--json]");
+    console.log("       flow-agents workflow-artifact-cleanup-audit --apply [--apply-ambiguous]");
+    console.log("           [--freshness-window-hours <n>] [--archive-root <path>]");
+    console.log("           [--confirm <slug>=<evidence>]... [--json]");
     console.log("");
-    console.log("Read-only dry-run audit for local workflow artifact directories.");
+    console.log("Read-only dry-run audit for local workflow artifact directories, with an");
+    console.log("opt-in reversible apply mode that archive-moves (never deletes) eligible");
+    console.log("sessions.");
     console.log("");
     console.log("Options:");
-    console.log("  --artifact-root <path>  Local artifact root to scan (default: .kontourai/flow-agents)");
-    console.log("  --json                  Print stable JSON buckets instead of text");
-    console.log("  --help                  Show this help");
+    console.log("  --artifact-root <path>       Local artifact root to scan (default: .kontourai/flow-agents)");
+    console.log("  --json                       Print stable JSON buckets instead of text");
+    console.log("  --apply                      Archive-move cleanup_candidate / aged terminal_done");
+    console.log("                               sessions. Without this flag nothing is ever moved");
+    console.log("                               (dry-run is the default).");
+    console.log("  --apply-ambiguous            Second gate (requires --apply to have effect):");
+    console.log("                               also archive-move ambiguous-lifecycle-shape and");
+    console.log("                               structurally-empty/stub invalid sessions.");
+    console.log("  --freshness-window-hours <n> Never move a session newer than this many hours");
+    console.log("                               (state.json.updated_at, mtime fallback only when");
+    console.log("                               state.json is unparsable/absent). Default: 48.");
+    console.log("  --archive-root <path>        Destination root for archive-moves. Default:");
+    console.log("                               sibling '.kontourai/flow-agents-archive/' next to");
+    console.log("                               the artifact root.");
+    console.log("  --confirm <slug>=<evidence>  Repeatable. Records human/flow-supplied");
+    console.log("                               confirmation evidence (e.g. a confirmed-merged PR");
+    console.log("                               reference) verbatim in that slug's MANIFEST.md row");
+    console.log("                               if it is moved in this run. This tool makes no");
+    console.log("                               network/gh calls to verify the evidence itself.");
+    console.log("  --help                       Show this help");
     console.log("");
     console.log("The command classifies active WIP, cleanup candidates, terminal done records,");
-    console.log("active learning follow-ups, and invalid sidecars. It does not delete, archive,");
-    console.log("move, or rewrite workflow artifacts.");
+    console.log("active learning follow-ups, and invalid sidecars. Without --apply it never");
+    console.log("deletes, archives, moves, or rewrites workflow artifacts. --apply only ever");
+    console.log("moves (archive-move, never delete) directories the classifier already puts in");
+    console.log("cleanup_candidate (or aged terminal_done); active_wip, active_learning_followup,");
+    console.log("and infrastructure directories are never apply targets.");
 }
 function readJson(file, label) {
     let fd = null;
@@ -226,11 +269,78 @@ function classifyWorkflow(slug, workflowPath) {
     }
     return { ...base, classification: "invalid", reasons: [`unrecognized lifecycle shape: status=${status}, phase=${phase}, next_action.status=${nextStatus ?? "missing"}`] };
 }
+// [Sweep-derived, AC14] Structural infrastructure-recognition predicate (PRIMARY check),
+// citing the 2026-07-05 sweep manifest's "Hard-rule exclusions" section: `current/`,
+// `assignment/`, `runtime/`, `skills/`, `veritas/` are live per-agent claim/assignment/
+// runtime-adapter/skills-catalog infrastructure, and the nested-agents runtime directory
+// (KNOWN_INFRASTRUCTURE_NAMES's "ka" + "gents" entry) is a NESTED RUNTIME TREE OF
+// ITS OWN (own current.json, own .workflow-sidecar.lock, own sub-workflow-session
+// directories with real state.json/learning.json/trust.bundle content). A name list alone
+// cannot safely handle that nested tree: it would either wrongly exclude its real
+// sub-sessions from ever being individually reachable, or wrongly flatten the whole nested
+// tree into one "invalid" entry. The structural check — "this child of the artifact root
+// itself contains its own top-level current.json and/or .workflow-sidecar.lock, i.e. it is
+// itself a workflow-sidecar-managed root, not a session" — is checked FIRST and is
+// sufficient on its own; the known-name set is a secondary, explicitly-labeled
+// belt-and-suspenders check for names the sweep observed without those marker files (e.g. a
+// bare `skills/` catalog directory).
+function isInfrastructureDir(_root, name, fullPath) {
+    if (KNOWN_INFRASTRUCTURE_NAMES.has(name))
+        return true;
+    try {
+        if (fs.existsSync(path.join(fullPath, "current.json")))
+            return true;
+    }
+    catch { /* fall through to next check */ }
+    try {
+        if (fs.existsSync(path.join(fullPath, ".workflow-sidecar.lock")))
+            return true;
+    }
+    catch { /* not infrastructure by this check */ }
+    return false;
+}
+// [Sweep-derived, AC15] Structurally-substantive predicate, independent of *why* a session
+// classifies `invalid`. Citing the sweep manifest's kontourai-flow-agents-320/166/287/288/
+// 289/309 pattern: these sessions classify `invalid` solely because a
+// `learning.records[].routing[].target` value (e.g. "issue") falls outside
+// KNOWN_LEARNING_ROUTE_TARGETS — a schema nit — even though `learning.status` shows real
+// processed learning (e.g. "learned"/"followup_required") and the directory carries a full,
+// substantive session record. This predicate is a hard, additional guard on the ambiguous-
+// eligibility branch below: it does not change classifyWorkflow()'s own `invalid` verdict,
+// only whether an `invalid` item is EVER eligible for the ambiguous-archive path. A
+// structurally-empty/stub `invalid` dir (no state.json, or state.json present with no
+// learning.json/trust.bundle sidecar content at all) is the sweep's safely-archived stub
+// shape (e.g. `archive-wip-audit`) and remains eligible under --apply-ambiguous.
+function isStructurallySubstantive(workflowDir) {
+    const statePath = path.join(workflowDir, "state.json");
+    if (!fs.existsSync(statePath))
+        return false;
+    const stateParsed = readJson(statePath, "state.json");
+    if (!stateParsed.ok || !objectValue(stateParsed.value))
+        return false;
+    const learningPath = path.join(workflowDir, "learning.json");
+    if (fs.existsSync(learningPath)) {
+        const learningParsed = readJson(learningPath, "learning.json");
+        if (learningParsed.ok && objectValue(learningParsed.value))
+            return true;
+    }
+    const trustBundlePath = path.join(workflowDir, "trust.bundle");
+    if (fs.existsSync(trustBundlePath)) {
+        const trustParsed = readJson(trustBundlePath, "trust.bundle");
+        if (trustParsed.ok && objectValue(trustParsed.value))
+            return true;
+    }
+    return false;
+}
 function childWorkflowDirs(root) {
     return fs.readdirSync(root, { withFileTypes: true })
         .filter((entry) => entry.isDirectory())
         .map((entry) => entry.name)
         .filter((name) => !name.startsWith(".") && !SKIPPED_ROOT_ENTRIES.has(name))
+        // [Sweep-derived, AC14] Filter infrastructure out of the SAME walk classify/apply share
+        // (no second directory enumeration) — infrastructure directories never appear in ANY
+        // bucket, dry-run or applied.
+        .filter((name) => !isInfrastructureDir(root, name, path.join(root, name)))
         .sort();
 }
 function emptyBuckets() {
@@ -284,6 +394,257 @@ function printText(result) {
     printBucket("Terminal done", result.buckets.terminal_done);
     printBucket("Invalid sidecars", result.buckets.invalid);
 }
+// Dynamic require of the shared CJS liveness-read helper, mirroring the createRequire
+// pattern already used by workflow-sidecar.ts's loadLivenessReadHelper()/similar loaders
+// for the exact same module — one implementation of the freshness algorithm, no second copy.
+let _livenessHelperCache = null;
+function loadLivenessReadHelper() {
+    if (_livenessHelperCache)
+        return _livenessHelperCache;
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/liveness-read.js");
+    _livenessHelperCache = _req(helperPath);
+    return _livenessHelperCache;
+}
+function runId() {
+    return crypto.randomUUID().slice(0, 8);
+}
+function runDate() {
+    return new Date().toISOString().slice(0, 10);
+}
+function defaultArchiveRoot(artifactRoot) {
+    return path.join(path.dirname(artifactRoot), "flow-agents-archive");
+}
+// Never preferred over state.json.updated_at when it parses — mtime is ONLY the fallback
+// for a missing/unparsable timestamp (Finding 7: bulk worktree mtime resets make mtime an
+// unreliable primary freshness signal; it is safe only as a last resort).
+function lastUpdatedMs(workflowDir) {
+    const statePath = path.join(workflowDir, "state.json");
+    const parsed = fs.existsSync(statePath) ? readJson(statePath, "state.json") : { ok: false, reason: "missing state.json" };
+    if (parsed.ok) {
+        const state = objectValue(parsed.value);
+        const updatedAt = state ? stringField(state, "updated_at") : null;
+        if (updatedAt) {
+            const parsedMs = Date.parse(updatedAt);
+            if (!Number.isNaN(parsedMs))
+                return { ms: parsedMs, source: "updated_at", raw: updatedAt };
+        }
+    }
+    const mtimeMs = fs.statSync(workflowDir).mtimeMs;
+    return { ms: mtimeMs, source: "mtime", raw: null };
+}
+function withinFreshnessWindow(workflowDir, freshnessWindowHours, nowMs) {
+    const { ms } = lastUpdatedMs(workflowDir);
+    const windowMs = freshnessWindowHours * 60 * 60 * 1000;
+    return nowMs - ms < windowMs;
+}
+function hasFreshLivenessClaim(artifactRoot, slug, nowMs) {
+    const helper = loadLivenessReadHelper();
+    const streamPath = path.join(artifactRoot, "liveness", "events.jsonl");
+    const events = helper.readLivenessEvents(streamPath);
+    // Pass an impossible/empty selfActor: apply mode has no "self" actor to exclude from the
+    // freshness join — ANY fresh holder at all (any actor) blocks the move (AC6).
+    return helper.freshHolders(events, slug, "", nowMs).length > 0;
+}
+// Hard rail (AC5): active_wip / active_learning_followup are NEVER apply targets, coded
+// as an unconditional gate — not merely relying on the classifier's own bucket semantics.
+// invalid is never eligible EXCEPT the two narrow --apply-ambiguous carve-outs below.
+function eligibleForApply(item, workflowDir, opts) {
+    if (item.classification === "active_wip" || item.classification === "active_learning_followup") {
+        return { eligible: false, ambiguous: false, skipReason: `hard-excluded classification: ${item.classification}` };
+    }
+    if (item.classification === "invalid") {
+        const isAmbiguousLifecycleShape = item.reasons.length === 1 && item.reasons[0].startsWith(AMBIGUOUS_LIFECYCLE_REASON_PREFIX);
+        if (!opts.applyAmbiguous) {
+            return { eligible: false, ambiguous: isAmbiguousLifecycleShape, skipReason: isAmbiguousLifecycleShape ? "ambiguous lifecycle shape: needs --apply-ambiguous" : "hard-excluded classification: invalid" };
+        }
+        if (isAmbiguousLifecycleShape) {
+            // AC10: an unrecognized-lifecycle-shape invalid item is eligible under
+            // --apply-ambiguous REGARDLESS of isStructurallySubstantive() — "unrecognized
+            // lifecycle shape" is itself evidence of substantive content (a stub cannot fail a
+            // lifecycle-shape check it never reached; it fails earlier, at missing/malformed
+            // state.json).
+            return applyRailsCheck(workflowDir, opts, true);
+        }
+        // Not a lifecycle-shape ambiguity: only eligible if genuinely a stub (AC15's hard gate,
+        // independent of *why* classifyWorkflow() called it invalid).
+        if (isStructurallySubstantive(workflowDir)) {
+            return { eligible: false, ambiguous: false, skipReason: "structurally-substantive invalid session: report-only, never archived (AC15)" };
+        }
+        return applyRailsCheck(workflowDir, opts, true);
+    }
+    if (item.classification === "cleanup_candidate") {
+        return applyRailsCheck(workflowDir, opts, false);
+    }
+    if (item.classification === "terminal_done") {
+        if (withinFreshnessWindow(workflowDir, opts.freshnessWindowHours, opts.nowMs)) {
+            return { eligible: false, ambiguous: false, skipReason: "within freshness window" };
+        }
+        return applyRailsCheck(workflowDir, opts, false);
+    }
+    return { eligible: false, ambiguous: false, skipReason: `unhandled classification: ${item.classification}` };
+}
+// Shared AC6/AC7 rails (liveness + freshness), applied to every eligibility branch above
+// that isn't already hard-excluded. Re-checked again immediately before the actual move in
+// applyArchive()'s caller to narrow the TOCTOU window (plan stop-short-risk #2).
+function applyRailsCheck(workflowDir, opts, ambiguous) {
+    const slug = path.basename(workflowDir);
+    if (hasFreshLivenessClaim(opts.artifactRoot, slug, opts.nowMs)) {
+        return { eligible: false, ambiguous, skipReason: "held liveness claim" };
+    }
+    if (withinFreshnessWindow(workflowDir, opts.freshnessWindowHours, opts.nowMs)) {
+        return { eligible: false, ambiguous, skipReason: "within freshness window" };
+    }
+    return { eligible: true, ambiguous };
+}
+// AC3 never-delete guarantee: archiveMove() only ever calls fs.renameSync (atomic on the
+// same filesystem — no delete-then-write race) or, on EXDEV (cross-device rename failure),
+// falls back to fs.cpSync + a file-count-verified copy and ONLY THEN fs.rmSync's the
+// SOURCE. The source is never removed before the destination write is verified complete.
+// No code path in this file calls fs.rm/fs.unlink/fs.rmdir/fs.rmSync on a source directory
+// outside this guarded, post-copy-verified fallback.
+function countFiles(dir) {
+    let count = 0;
+    const stack = [dir];
+    while (stack.length) {
+        const current = stack.pop();
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory())
+                stack.push(full);
+            else
+                count += 1;
+        }
+    }
+    return count;
+}
+function archiveMove(from, to) {
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    try {
+        fs.renameSync(from, to);
+        return;
+    }
+    catch (error) {
+        if (!(error && typeof error === "object" && "code" in error && error.code === "EXDEV"))
+            throw error;
+    }
+    // Cross-device fallback: copy first, verify, THEN remove the source. Never remove `from`
+    // before `to` is confirmed to hold a complete copy.
+    fs.cpSync(from, to, { recursive: true });
+    const sourceCount = countFiles(from);
+    const destCount = countFiles(to);
+    if (destCount !== sourceCount) {
+        throw new Error(`archive-move verification failed for ${from} -> ${to}: source had ${sourceCount} files, destination has ${destCount}`);
+    }
+    fs.rmSync(from, { recursive: true, force: true });
+}
+// AC4: skip entirely (no directory created) when there is nothing to record.
+function writeManifest(archiveRunDir, moves) {
+    if (moves.length === 0)
+        return;
+    fs.mkdirSync(archiveRunDir, { recursive: true });
+    const lines = [];
+    lines.push("# Workflow Artifact Cleanup Apply — Manifest");
+    lines.push("");
+    lines.push(`Archive run: ${path.basename(archiveRunDir)}`);
+    lines.push("");
+    lines.push("| Slug | Category | Last updated | Reason | Confirmation evidence |");
+    lines.push("|---|---|---|---|---|");
+    for (const move of moves) {
+        const reason = move.reasons.join("; ").replace(/\|/g, "\\|");
+        const evidence = (move.confirmation_evidence ?? "none recorded").replace(/\|/g, "\\|");
+        lines.push(`| \`${move.slug}\` | ${move.classification} | ${move.last_updated} | ${reason} | ${evidence} |`);
+    }
+    lines.push("");
+    fs.writeFileSync(path.join(archiveRunDir, "MANIFEST.md"), lines.join("\n"), "utf8");
+}
+function parseConfirmMap(values) {
+    const map = {};
+    for (const raw of values) {
+        const eq = raw.indexOf("=");
+        if (eq === -1)
+            continue;
+        const slug = raw.slice(0, eq);
+        const evidence = raw.slice(eq + 1);
+        if (slug)
+            map[slug] = evidence;
+    }
+    return map;
+}
+function performApply(result, options) {
+    const nowMs = Date.now();
+    const opts = {
+        artifactRoot: options.artifactRoot,
+        freshnessWindowHours: options.freshnessWindowHours,
+        applyAmbiguous: options.applyAmbiguous,
+        nowMs,
+    };
+    const ambiguousReport = [];
+    const toMove = [];
+    for (const items of Object.values(result.buckets)) {
+        for (const item of items) {
+            const workflowDir = item.path;
+            const eligibility = eligibleForApply(item, workflowDir, opts);
+            if (eligibility.ambiguous && !eligibility.eligible) {
+                ambiguousReport.push({ slug: item.slug, reason: eligibility.skipReason ?? "ambiguous lifecycle shape" });
+            }
+            if (eligibility.eligible)
+                toMove.push({ item, workflowDir });
+        }
+    }
+    const archiveRunDir = path.join(options.archiveRoot, `${runDate()}-${runId()}`);
+    const moves = [];
+    const manifestMoves = [];
+    for (const { item, workflowDir } of toMove) {
+        // Re-check liveness + freshness immediately before the actual move, narrowing the
+        // TOCTOU window between classification and the move itself (plan stop-short-risk #2).
+        const slug = item.slug;
+        if (hasFreshLivenessClaim(options.artifactRoot, slug, Date.now()))
+            continue;
+        if (withinFreshnessWindow(workflowDir, options.freshnessWindowHours, Date.now()))
+            continue;
+        const { ms } = lastUpdatedMs(workflowDir);
+        const destination = path.join(archiveRunDir, slug);
+        archiveMove(workflowDir, destination);
+        moves.push({ slug, from: workflowDir, to: destination, classification: item.classification, reason: item.reasons.join("; ") });
+        manifestMoves.push({
+            slug,
+            classification: item.classification,
+            last_updated: new Date(ms).toISOString(),
+            reasons: item.reasons,
+            confirmation_evidence: options.confirmMap[slug],
+        });
+    }
+    let manifestPath = null;
+    if (manifestMoves.length > 0) {
+        writeManifest(archiveRunDir, manifestMoves);
+        manifestPath = path.join(archiveRunDir, "MANIFEST.md");
+    }
+    return {
+        applied: true,
+        dry_run: false,
+        archive_run_dir: moves.length > 0 ? archiveRunDir : null,
+        manifest_path: manifestPath,
+        moves,
+        ambiguous: ambiguousReport,
+    };
+}
+function printAppliedText(report) {
+    console.log("");
+    console.log(`APPLIED: ${report.moves.length} director${report.moves.length === 1 ? "y" : "ies"} archived`);
+    for (const move of report.moves) {
+        console.log(`  - ${move.slug} -> ${move.to}`);
+        console.log(`    reason: ${move.reason}`);
+    }
+    if (report.manifest_path)
+        console.log(`Manifest: ${report.manifest_path}`);
+    if (report.ambiguous.length > 0) {
+        console.log("");
+        console.log(`Ambiguous (needs --apply-ambiguous): ${report.ambiguous.length}`);
+        for (const entry of report.ambiguous)
+            console.log(`  - ${entry.slug}: ${entry.reason}`);
+    }
+}
 export function main(argv = process.argv.slice(2)) {
     const args = parseArgs(argv);
     if (flagBool(args.flags, "help") || flagBool(args.flags, "h")) {
@@ -291,18 +652,64 @@ export function main(argv = process.argv.slice(2)) {
         return 0;
     }
     let result;
+    let root;
     try {
-        const root = flagString(args.flags, "artifact-root") ? path.resolve(flagString(args.flags, "artifact-root")) : defaultArtifactRootForRead();
+        root = flagString(args.flags, "artifact-root") ? path.resolve(flagString(args.flags, "artifact-root")) : defaultArtifactRootForRead();
         result = audit(root);
     }
     catch (error) {
         console.error(`workflow-artifact-cleanup-audit: ${error instanceof Error ? error.message : String(error)}`);
         return 1;
     }
-    if (flagBool(args.flags, "json"))
-        console.log(JSON.stringify(result, null, 2));
-    else
+    const apply = flagBool(args.flags, "apply");
+    const applyAmbiguous = flagBool(args.flags, "apply-ambiguous");
+    const json = flagBool(args.flags, "json");
+    // Two-gate model (plan-pinned, Task 1 Changes: "--apply-ambiguous (bool, requires
+    // --apply to have any effect)"): --apply-ambiguous ALONE performs zero mutation. The
+    // mutation path below is entered ONLY when --apply itself is set; --apply-ambiguous
+    // without --apply degrades to the same read-only dry-run output as no flags at all —
+    // it is a second, additive gate on top of --apply, never an independent trigger. This
+    // is the strict form of the plan's "requires --apply" language: a bare --apply-ambiguous
+    // invocation is treated as a no-op rather than silently doing nothing while looking like
+    // it might have done something, matching AC1's dry-run-default guarantee.
+    if (!apply) {
+        if (json)
+            console.log(JSON.stringify(result, null, 2));
+        else
+            printText(result);
+        return 0;
+    }
+    // AC8: freshness window / archive root are configurable ONLY via CLI flags — no
+    // environment variable is ever read here to loosen or redirect either.
+    const freshnessWindowHoursRaw = flagString(args.flags, "freshness-window-hours");
+    const freshnessWindowHours = freshnessWindowHoursRaw ? Number(freshnessWindowHoursRaw) : 48;
+    if (!Number.isFinite(freshnessWindowHours) || freshnessWindowHours < 0) {
+        console.error("workflow-artifact-cleanup-audit: --freshness-window-hours must be a non-negative number");
+        return 1;
+    }
+    const archiveRoot = flagString(args.flags, "archive-root") ? path.resolve(flagString(args.flags, "archive-root")) : defaultArchiveRoot(root);
+    const confirmMap = parseConfirmMap(flagList(args.flags, "confirm"));
+    let report;
+    try {
+        report = performApply(result, {
+            artifactRoot: root,
+            archiveRoot,
+            freshnessWindowHours,
+            applyAmbiguous,
+            confirmMap,
+        });
+    }
+    catch (error) {
+        console.error(`workflow-artifact-cleanup-audit: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+    if (json) {
+        console.log(JSON.stringify({ ...result, ...report }, null, 2));
+    }
+    else {
         printText(result);
+        printAppliedText(report);
+    }
     return 0;
 }
 // Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.