@cleocode/cleo 2026.6.6 → 2026.6.7

package/dist/cli/index.js

@@ -362,6 +362,21 @@ var init_dist = __esm({
   }
 });
 
+// packages/cleo/src/cli/describe-context.ts
+function setDescribeMode(requested) {
+  describeRequested = requested;
+}
+function isDescribeMode() {
+  return describeRequested;
+}
+var describeRequested;
+var init_describe_context = __esm({
+  "packages/cleo/src/cli/describe-context.ts"() {
+    "use strict";
+    describeRequested = false;
+  }
+});
+
 // packages/cleo/src/cli/field-context.ts
 import {
   resolveFieldExtraction
@@ -12979,6 +12994,87 @@ var init_nexus_scope_map = __esm({
   }
 });
 
+// packages/contracts/src/operations/output-contracts-data.ts
+var TASK_MUTATION_DATA_SCHEMA, tasksAddOutputContract, tasksAddBatchOutputContract, tasksUpdateOutputContract, tasksCompleteOutputContract;
+var init_output_contracts_data = __esm({
+  "packages/contracts/src/operations/output-contracts-data.ts"() {
+    "use strict";
+    TASK_MUTATION_DATA_SCHEMA = {
+      type: "object",
+      required: ["count", "created", "updated", "deleted"],
+      additionalProperties: true,
+      properties: {
+        count: { type: "number", description: "Number of records the mutation affected." },
+        created: {
+          type: "array",
+          description: 'Task IDs created by the mutation (bare strings, e.g. "T11692"). Empty for update/delete-only mutations.',
+          items: { type: "string" }
+        },
+        updated: {
+          type: "array",
+          description: "Task IDs updated by the mutation (bare strings). Empty for create/delete-only mutations.",
+          items: { type: "string" }
+        },
+        deleted: {
+          type: "array",
+          description: "Task IDs deleted by the mutation (bare strings). Empty for create/update-only mutations.",
+          items: { type: "string" }
+        },
+        ids: {
+          type: "array",
+          description: "Deprecated alias for the non-empty bucket. Prefer created/updated/deleted.",
+          items: { type: "string" }
+        },
+        dryRun: { type: "boolean", description: "True when this was a preview-only mutation." },
+        status: { type: "string", description: "Post-mutation task status (add/update/complete)." }
+      }
+    };
+    tasksAddOutputContract = {
+      operation: "tasks.add",
+      shapeNote: 'The created task ID (bare string) is at /data/created/0 \u2014 NOT /data/created/0/id. Example: /data/created/0 \u2192 "T11692".',
+      dataSchema: { ...TASK_MUTATION_DATA_SCHEMA },
+      fieldPointers: ["/data/created/0", "/data/count"]
+    };
+    tasksAddBatchOutputContract = {
+      operation: "tasks.add-batch",
+      shapeNote: "Atomic batch insert. Each created task ID (bare string) is in /data/created (array). Dry-run projections are at root: /data/wouldCreate and /data/insertedCount (=0). NOT under /data/dryRunSummary.",
+      dataSchema: {
+        type: "object",
+        required: ["count", "created", "updated", "deleted"],
+        additionalProperties: true,
+        properties: {
+          ...TASK_MUTATION_DATA_SCHEMA.properties,
+          wouldCreate: {
+            type: "number",
+            description: "Dry-run: predicted write count. Present only when dryRun=true."
+          },
+          insertedCount: {
+            type: "number",
+            description: "Dry-run: always 0 (no DB write). Present only when dryRun=true."
+          },
+          wouldAffect: {
+            type: "number",
+            description: "Dry-run: generic affected count. Present only when dryRun=true."
+          }
+        }
+      },
+      fieldPointers: ["/data/created/0", "/data/count", "/data/wouldCreate", "/data/insertedCount"]
+    };
+    tasksUpdateOutputContract = {
+      operation: "tasks.update",
+      shapeNote: "The updated task ID (bare string) is at /data/updated/0 \u2014 NOT /data/updated/0/id. Use /data/status for the post-mutation status.",
+      dataSchema: { ...TASK_MUTATION_DATA_SCHEMA },
+      fieldPointers: ["/data/updated/0", "/data/status", "/data/count"]
+    };
+    tasksCompleteOutputContract = {
+      operation: "tasks.complete",
+      shapeNote: "Completion is a status mutation \u2014 the task ID (bare string) is at /data/updated/0 (status=done). Use /data/status for the post-mutation status.",
+      dataSchema: { ...TASK_MUTATION_DATA_SCHEMA },
+      fieldPointers: ["/data/updated/0", "/data/status", "/data/count"]
+    };
+  }
+});
+
 // packages/contracts/src/peer.ts
 var init_peer = __esm({
   "packages/contracts/src/peer.ts"() {
@@ -14239,6 +14335,7 @@ var init_src2 = __esm({
     init_docs();
     init_operations();
     init_nexus_scope_map();
+    init_output_contracts_data();
     init_params();
     init_tasks();
     init_peer();
@@ -32693,6 +32790,7 @@ var init_tasks3 = __esm({
           await taskCancel(projectRoot, params.taskId, {
             reason: params.reason,
             children: params.children,
+            reparentTo: params.reparentTo,
             force: params.force,
             cascadeThreshold: params.cascadeThreshold,
             allowCascade: params.allowCascade
@@ -35298,6 +35396,7 @@ __export(cli_exports, {
   dispatchRaw: () => dispatchRaw,
   getCliDispatcher: () => getCliDispatcher,
   handleRawError: () => handleRawError,
+  maybeEmitDescribe: () => maybeEmitDescribe,
   resetCliDispatcher: () => resetCliDispatcher
 });
 import { randomUUID as randomUUID5 } from "node:crypto";
@@ -35306,7 +35405,12 @@ import { createRequire } from "node:module";
 import { dirname as dirname3, join as join8 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { catalog, registerSkillLibraryFromPath } from "@cleocode/caamp";
-import { autoRecordDispatchTokenUsage, getProjectRoot as getProjectRoot22, hooks } from "@cleocode/core/internal";
+import {
+  autoRecordDispatchTokenUsage,
+  describeOperation,
+  getProjectRoot as getProjectRoot22,
+  hooks
+} from "@cleocode/core/internal";
 function ensureCaampLibrary() {
   if (catalog.isCatalogAvailable()) return;
   try {
@@ -35387,7 +35491,31 @@ function createCliDispatcher() {
 function resetCliDispatcher() {
   _dispatcher = null;
 }
+function maybeEmitDescribe(gateway, domain, operation, outputOpts) {
+  if (!isDescribeMode()) return false;
+  const key = `${domain}.${operation}`;
+  const descriptor = describeOperation(key);
+  const command = outputOpts?.command ?? operation;
+  if (descriptor === null) {
+    cliOutput(
+      { operation: key, gateway, inputContract: null, outputContract: null },
+      {
+        command,
+        operation: `describe.${key}`,
+        message: `No registered operation found for "${key}".`
+      }
+    );
+    return true;
+  }
+  cliOutput(descriptor, {
+    command,
+    operation: `describe.${key}`,
+    message: `Schema for ${key} (input + output). Use the outputContract.fieldPointers for --field.`
+  });
+  return true;
+}
 async function dispatchFromCli(gateway, domain, operation, params, outputOpts) {
+  if (maybeEmitDescribe(gateway, domain, operation, outputOpts)) return;
   const dispatcher = getCliDispatcher();
   const projectRoot = getProjectRoot22();
   const dispatchStart = Date.now();
@@ -35550,6 +35678,7 @@ var init_cli = __esm({
   "packages/cleo/src/dispatch/adapters/cli.ts"() {
     "use strict";
     init_animation_bridge();
+    init_describe_context();
     init_idempotency_context();
     init_renderers();
     init_dispatcher();
@@ -35845,6 +35974,7 @@ var init_add_batch = __esm({
         }
       },
       async run({ args }) {
+        if (maybeEmitDescribe("mutate", "tasks", "add-batch", { command: "add-batch" })) return;
         const defaultParent = args.parent;
         const dryRunFlag = args["dry-run"];
         const paramsArg = args.params;
@@ -36156,6 +36286,7 @@ For 2+ tasks at once: cleo add-batch --file tasks.json (single transaction, atom
         }
       },
       async run({ args, cmd }) {
+        if (maybeEmitDescribe("mutate", "tasks", "add", { command: "add" })) return;
         const paramsArg = args.params;
         const paramsFileArg = args["params-file"];
         if (paramsArg !== void 0 || paramsFileArg !== void 0) {
@@ -42018,9 +42149,13 @@ var init_cancel = __esm({
         },
         children: {
           type: "string",
-          description: "Child handling mode: block (default), cascade, or orphan",
+          description: "Child handling mode: block (default), cascade (cancel subtree), or reparent (move children under --to)",
           default: "block"
         },
+        to: {
+          type: "string",
+          description: "Target parent ID for --children reparent (T11811): children move under this epic"
+        },
         force: {
           type: "boolean",
           description: "Required waiver for cascade cancellation above the subtree threshold",
@@ -42040,6 +42175,7 @@ var init_cancel = __esm({
             taskId: args.taskId,
             reason: args.reason,
             children: args.children,
+            reparentTo: typeof args.to === "string" && args.to.length > 0 ? args.to : void 0,
             force: args.force === true,
             cascadeThreshold: typeof args.cascadeThreshold === "string" && args.cascadeThreshold.length > 0 ? Number.parseInt(args.cascadeThreshold, 10) : void 0
           },
@@ -43668,6 +43804,7 @@ var init_complete = __esm({
         }
       },
       async run({ args }) {
+        if (maybeEmitDescribe("mutate", "tasks", "complete", { command: "complete" })) return;
         const response = await dispatchRaw("mutate", "tasks", "complete", {
           taskId: args.taskId,
           notes: args.notes,
@@ -47938,7 +48075,7 @@ import {
   resolveWorktreeFilePath,
   resolveWorktreeRouting as resolveWorktreeRouting4
 } from "@cleocode/core/internal";
-import { describeOperation } from "@cleocode/lafs";
+import { describeOperation as describeOperation2 } from "@cleocode/lafs";
 async function dispatchDocsRaw(gateway, operation, params) {
   const response = await dispatchRaw(gateway, "docs", operation, params);
   handleRawError(response, { command: "docs", operation: `docs.${operation}` });
@@ -49176,7 +49313,7 @@ var init_docs3 = __esm({
     if (docsUpdateOperation === void 0) {
       throw new Error("docs.update operation is missing from the registry");
     }
-    docsUpdateSchema = describeOperation(docsUpdateOperation, {
+    docsUpdateSchema = describeOperation2(docsUpdateOperation, {
       includeGates: false,
       includeExamples: true
     });
@@ -50088,6 +50225,158 @@ var init_doctor_db_substrate = __esm({
   }
 });
 
+// packages/cleo/src/cli/commands/doctor-exodus-residue.ts
+var doctor_exodus_residue_exports = {};
+__export(doctor_exodus_residue_exports, {
+  doctorExodusResidueCommand: () => doctorExodusResidueCommand
+});
+import {
+  archiveStrandedResidue,
+  buildExodusPlan,
+  detectStrandedResidue
+} from "@cleocode/core/store/exodus/index.js";
+var doctorExodusResidueCommand;
+var init_doctor_exodus_residue = __esm({
+  "packages/cleo/src/cli/commands/doctor-exodus-residue.ts"() {
+    "use strict";
+    init_define_cli_command();
+    init_renderers();
+    doctorExodusResidueCommand = defineCommand({
+      meta: {
+        name: "exodus-residue",
+        description: "Detect legacy exodus source DBs still present after a cutover (stranded residue that re-arms the exodus-on-open corruption trigger). Use --fix to archive them into _archive/ (reversible move, never deletes)."
+      },
+      args: {
+        fix: {
+          type: "boolean",
+          description: "Archive stranded legacy source DBs into _archive/ (move, never delete)",
+          default: false
+        }
+      },
+      run({ args }) {
+        const fix = args.fix === true;
+        const cwd = process.cwd();
+        const plan = buildExodusPlan(cwd);
+        const stranded = detectStrandedResidue(plan.sources, cwd);
+        if (stranded.length === 0) {
+          cliOutput(
+            {
+              kind: "generic",
+              ok: true,
+              strandedCount: 0,
+              stranded: [],
+              fixed: false
+            },
+            {
+              command: "doctor exodus-residue",
+              message: "No stranded legacy exodus source DBs (clean cutover or pre-migration install)."
+            }
+          );
+          return;
+        }
+        for (const entry of stranded) {
+          humanInfo(`  STRANDED [${entry.scope}] ${entry.name} \u2192 ${entry.path}`);
+        }
+        if (!fix) {
+          cliOutput(
+            {
+              kind: "generic",
+              ok: false,
+              strandedCount: stranded.length,
+              stranded: stranded.map((s) => ({ name: s.name, path: s.path, scope: s.scope })),
+              fixed: false
+            },
+            {
+              command: "doctor exodus-residue",
+              message: `${stranded.length} stranded legacy source DB(s) found. Run \`cleo doctor exodus-residue --fix\` to archive them.`
+            }
+          );
+          process.exitCode = 1;
+          return;
+        }
+        const archived = archiveStrandedResidue(stranded, plan.sources, cwd);
+        const movedCount = archived.filter((a) => a.action === "archived").length;
+        humanInfo(`  Archived ${movedCount} stranded source DB(s) \u2192 _archive/.`);
+        cliOutput(
+          {
+            kind: "generic",
+            ok: true,
+            strandedCount: stranded.length,
+            stranded: stranded.map((s) => ({ name: s.name, path: s.path, scope: s.scope })),
+            fixed: true,
+            archived: archived.map((a) => ({
+              name: a.name,
+              action: a.action,
+              archivedTo: a.archivedTo
+            }))
+          },
+          {
+            command: "doctor exodus-residue",
+            message: `Archived ${movedCount} stranded legacy source DB(s) into _archive/.`
+          }
+        );
+      }
+    });
+  }
+});
+
+// packages/cleo/src/cli/commands/doctor-exodus.ts
+var doctor_exodus_exports = {};
+__export(doctor_exodus_exports, {
+  doctorExodusCommand: () => doctorExodusCommand
+});
+import { buildExodusHealth } from "@cleocode/core/store/exodus/index.js";
+function fmtBytes2(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+var doctorExodusCommand;
+var init_doctor_exodus = __esm({
+  "packages/cleo/src/cli/commands/doctor-exodus.ts"() {
+    "use strict";
+    init_define_cli_command();
+    init_renderers();
+    doctorExodusCommand = defineCommand({
+      meta: {
+        name: "exodus-health",
+        description: "Read-only exodus health report: per-scope migration state, legacy DB sizes, completion markers, disk headroom, and the kill-switch \u2014 with recommended next steps."
+      },
+      run() {
+        const health = buildExodusHealth(process.cwd());
+        for (const sc of [health.project, health.global]) {
+          humanInfo(
+            `  [${sc.scope}] state=${sc.state}  consolidated=${sc.consolidatedExists ? "yes" : "no"}  marker=${sc.markerPresent ? "yes" : "no"}`
+          );
+          for (const s of sc.legacySources) {
+            humanInfo(
+              `      ${s.present ? "\u2713" : "\xB7"} ${s.name.padEnd(18)} ${s.present ? fmtBytes2(s.bytes) : "-"}${s.large ? "  \u26A0 LARGE" : ""}`
+            );
+          }
+        }
+        humanInfo(
+          `  disk: ${fmtBytes2(health.availableBytes)} free / ${fmtBytes2(health.requiredBytes)} required \u2014 ${health.diskHeadroomOk ? "OK" : "LOW"}`
+        );
+        humanInfo(
+          `  kill-switch (CLEO_DISABLE_EXODUS_ON_OPEN): ${health.killSwitchSet ? "SET" : "off"}`
+        );
+        if (health.recommendations.length > 0) {
+          humanInfo("  recommendations:");
+          for (const r of health.recommendations) humanInfo(`    \u2022 ${r}`);
+        }
+        cliOutput(
+          { kind: "generic", ...health },
+          {
+            command: "doctor exodus",
+            message: `exodus health: project=${health.project.state}, global=${health.global.state}${health.dataParityOk ? "" : `, ${health.dataDeficits} DEFICIT(S)`}.`
+          }
+        );
+      }
+    });
+  }
+});
+
 // packages/cleo/src/cli/commands/doctor-legacy-backups.ts
 var doctor_legacy_backups_exports = {};
 __export(doctor_legacy_backups_exports, {
@@ -50692,97 +50981,6 @@ ${this.prefix}: \u2717 ${message}
   }
 });
 
-// packages/cleo/src/cli/commands/doctor-exodus-residue.ts
-import {
-  archiveStrandedResidue,
-  buildExodusPlan,
-  detectStrandedResidue
-} from "@cleocode/core/store/exodus/index.js";
-var doctorExodusResidueCommand;
-var init_doctor_exodus_residue = __esm({
-  "packages/cleo/src/cli/commands/doctor-exodus-residue.ts"() {
-    "use strict";
-    init_define_cli_command();
-    init_renderers();
-    doctorExodusResidueCommand = defineCommand({
-      meta: {
-        name: "exodus-residue",
-        description: "Detect legacy exodus source DBs still present after a cutover (stranded residue that re-arms the exodus-on-open corruption trigger). Use --fix to archive them into _archive/ (reversible move, never deletes)."
-      },
-      args: {
-        fix: {
-          type: "boolean",
-          description: "Archive stranded legacy source DBs into _archive/ (move, never delete)",
-          default: false
-        }
-      },
-      run({ args }) {
-        const fix = args.fix === true;
-        const cwd = process.cwd();
-        const plan = buildExodusPlan(cwd);
-        const stranded = detectStrandedResidue(plan.sources, cwd);
-        if (stranded.length === 0) {
-          cliOutput(
-            {
-              kind: "generic",
-              ok: true,
-              strandedCount: 0,
-              stranded: [],
-              fixed: false
-            },
-            {
-              command: "doctor exodus-residue",
-              message: "No stranded legacy exodus source DBs (clean cutover or pre-migration install)."
-            }
-          );
-          return;
-        }
-        for (const entry of stranded) {
-          humanInfo(`  STRANDED [${entry.scope}] ${entry.name} \u2192 ${entry.path}`);
-        }
-        if (!fix) {
-          cliOutput(
-            {
-              kind: "generic",
-              ok: false,
-              strandedCount: stranded.length,
-              stranded: stranded.map((s) => ({ name: s.name, path: s.path, scope: s.scope })),
-              fixed: false
-            },
-            {
-              command: "doctor exodus-residue",
-              message: `${stranded.length} stranded legacy source DB(s) found. Run \`cleo doctor exodus-residue --fix\` to archive them.`
-            }
-          );
-          process.exitCode = 1;
-          return;
-        }
-        const archived = archiveStrandedResidue(stranded, plan.sources, cwd);
-        const movedCount = archived.filter((a) => a.action === "archived").length;
-        humanInfo(`  Archived ${movedCount} stranded source DB(s) \u2192 _archive/.`);
-        cliOutput(
-          {
-            kind: "generic",
-            ok: true,
-            strandedCount: stranded.length,
-            stranded: stranded.map((s) => ({ name: s.name, path: s.path, scope: s.scope })),
-            fixed: true,
-            archived: archived.map((a) => ({
-              name: a.name,
-              action: a.action,
-              archivedTo: a.archivedTo
-            }))
-          },
-          {
-            command: "doctor exodus-residue",
-            message: `Archived ${movedCount} stranded legacy source DB(s) into _archive/.`
-          }
-        );
-      }
-    });
-  }
-});
-
 // packages/cleo/src/cli/commands/migrate-agents-v2.ts
 var migrate_agents_v2_exports = {};
 __export(migrate_agents_v2_exports, {
@@ -51147,6 +51345,7 @@ var init_doctor = __esm({
     init_progress();
     init_renderers();
     init_doctor_db_substrate();
+    init_doctor_exodus();
     init_doctor_exodus_residue();
     init_doctor_legacy_backups();
     init_doctor_projects();
@@ -51168,6 +51367,8 @@ var init_doctor = __esm({
         "legacy-backups": doctorLegacyBackupsCommand,
         // T11777 / Saga T11242 / Epic T11249 — exodus stranded-residue check (+ --fix)
         "exodus-residue": doctorExodusResidueCommand,
+        // T11837 / Saga T11242 / Epic T11833 — read-only exodus health report
+        "exodus-health": doctorExodusCommand,
         // T10458 / Saga T10431 / Epic T10436 — Release-readiness preflight
         "release-readiness": doctorReleaseReadinessCommand
       },
@@ -52295,14 +52496,16 @@ import { resolveDualScopeDbPath } from "@cleocode/core/store/dual-scope-db.js";
 import {
   archiveMigratedSources,
   buildExodusPlan as buildExodusPlan2,
+  hasExodusCompleteMarker,
   runExodusMigrate,
   runExodusStatus,
   runExodusVerify,
+  sealExodus,
   sourcesPresent,
   verifyMigration
 } from "@cleocode/core/store/exodus/index.js";
 import { isDataContinuityOk } from "@cleocode/core/store/exodus/on-open.js";
-function fmtBytes2(n) {
+function fmtBytes3(n) {
   if (n < 1024) return `${n} B`;
   if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
   return `${(n / 1024 / 1024).toFixed(1)} MB`;
@@ -52327,7 +52530,7 @@ function showStatus() {
   }
   cliOutput(result, { command: "exodus status" });
 }
-var migrateSubCommand, verifySubCommand, statusSubCommand, exodusCommand;
+var migrateSubCommand, verifySubCommand, sealSubCommand, statusSubCommand, exodusCommand;
 var init_exodus = __esm({
   "packages/cleo/src/cli/commands/exodus.ts"() {
     "use strict";
@@ -52350,23 +52553,52 @@ var init_exodus = __esm({
           type: "boolean",
           description: "Skip schema-version guard (AC9 \u2014 use with care)",
           default: false
+        },
+        scope: {
+          type: "string",
+          description: "Which scope to migrate: 'global', 'project', or 'both' (default = full fleet)",
+          default: "both"
         }
       },
       async run({ args }) {
         const dryRun = args["dry-run"] === true;
         const forceCrossVersion = args["force-cross-version"] === true;
-        const plan = buildExodusPlan2(process.cwd());
+        const scope = args.scope ?? "both";
+        if (scope !== "both" && scope !== "project" && scope !== "global") {
+          cliError(
+            `Invalid --scope '${scope}'. Use 'global', 'project', or 'both'.`,
+            6 /* VALIDATION_ERROR */,
+            { name: "E_INVALID_SCOPE" },
+            { operation: "exodus.migrate" }
+          );
+          process.exitCode = 6 /* VALIDATION_ERROR */;
+          return;
+        }
+        const fullPlan = buildExodusPlan2(process.cwd());
+        const plan = scope === "both" ? fullPlan : { ...fullPlan, sources: fullPlan.sources.filter((s) => s.targetScope === scope) };
+        if (scope !== "both" && hasExodusCompleteMarker(scope) && !dryRun) {
+          cliOutput(
+            { kind: "generic", ok: true, alreadySealed: true, scope },
+            {
+              command: "exodus migrate",
+              message: `Scope '${scope}' already migrated + sealed (completion marker present) \u2014 nothing to do.`
+            }
+          );
+          return;
+        }
         humanInfo(`Exodus migration plan:`);
         humanInfo(
-          `  Source DBs (${plan.sources.length} total, ${fmtBytes2(plan.totalSourceBytes)} combined):`
+          `  Source DBs (${plan.sources.length} total, ${fmtBytes3(plan.totalSourceBytes)} combined):`
         );
         for (const s of plan.sources) {
           humanInfo(`    [${s.targetScope.padEnd(7)}] ${s.name.padEnd(20)} ${s.path}`);
         }
         humanInfo(`  Target project cleo.db: ${plan.projectDbPath}`);
         humanInfo(`  Target global  cleo.db: ${plan.globalDbPath}`);
-        humanInfo(`  Available disk: ${fmtBytes2(plan.availableBytes)}`);
-        humanInfo(`  Required (3\xD7): ${fmtBytes2(3 * plan.totalSourceBytes)}`);
+        humanInfo(`  Available disk: ${fmtBytes3(plan.availableBytes)}`);
+        humanInfo(
+          `  Required (1.2\xD7 largest ${fmtBytes3(plan.largestSourceBytes)} + consolidated): ${fmtBytes3(plan.requiredBytes)}`
+        );
         humanInfo(`  Disk pre-flight: ${plan.diskPreflight ? "PASS" : "FAIL"}`);
         if (plan.resumeFromStaging) {
           humanInfo(`  Resuming from existing staging: ${plan.stagingDir}`);
@@ -52383,6 +52615,8 @@ var init_exodus = __esm({
                   targetScope: s.targetScope
                 })),
                 totalSourceBytes: plan.totalSourceBytes,
+                largestSourceBytes: plan.largestSourceBytes,
+                requiredBytes: plan.requiredBytes,
                 availableBytes: plan.availableBytes,
                 diskPreflight: plan.diskPreflight,
                 stagingDir: plan.stagingDir,
@@ -52406,8 +52640,9 @@ var init_exodus = __esm({
           return;
         }
         if (!plan.diskPreflight) {
+          const shortfall = Math.max(0, plan.requiredBytes - plan.availableBytes);
           cliError(
-            `Insufficient disk space for exodus. Need \u22653\xD7 source size (${fmtBytes2(plan.totalSourceBytes)}), have ${fmtBytes2(plan.availableBytes)}.`,
+            `Insufficient disk space for exodus. Need \u2265${fmtBytes3(plan.requiredBytes)} (\u22481.2\xD7 largest source ${fmtBytes3(plan.largestSourceBytes)} + consolidated estimate ${fmtBytes3(plan.totalSourceBytes)}), have ${fmtBytes3(plan.availableBytes)} \u2014 ${fmtBytes3(shortfall)} short. Free up space (e.g. \`cleo backup prune\`) or move .cleo/ to a larger volume.`,
             6 /* VALIDATION_ERROR */,
             { name: "E_DISK_PREFLIGHT_FAIL" },
             { operation: "exodus.migrate" }
@@ -52544,6 +52779,67 @@ Passing tables (${passing.length}):`);
         }
       }
     });
+    sealSubCommand = defineCommand({
+      meta: {
+        name: "seal",
+        description: "Certify an already-migrated install: count-parity gate (no digest) \u2192 archive legacy source DBs (reversible) + write the completion marker so exodus-on-open stops re-firing."
+      },
+      args: {
+        scope: {
+          type: "string",
+          description: "Which scope to seal: 'global', 'project', or 'both' (default)",
+          default: "both"
+        }
+      },
+      run({ args }) {
+        const scope = args.scope ?? "both";
+        if (scope !== "both" && scope !== "project" && scope !== "global") {
+          cliError(
+            `Invalid --scope '${scope}'. Use 'global', 'project', or 'both'.`,
+            6 /* VALIDATION_ERROR */,
+            { name: "E_INVALID_SCOPE" },
+            { operation: "exodus.seal" }
+          );
+          process.exitCode = 6 /* VALIDATION_ERROR */;
+          return;
+        }
+        const plan = buildExodusPlan2(process.cwd());
+        const result = sealExodus(plan, scope, process.cwd());
+        if (!result.ok) {
+          cliError(
+            result.refusedReason ?? "Seal refused \u2014 parity deficit.",
+            1 /* GENERAL_ERROR */,
+            { name: "E_EXODUS_SEAL_DEFICIT" },
+            { operation: "exodus.seal" }
+          );
+          process.exitCode = 1 /* GENERAL_ERROR */;
+          return;
+        }
+        for (const sc of result.scopes) {
+          const moved = sc.archived.filter((a) => a.action === "archived").length;
+          humanInfo(
+            `  [${sc.scope}] ${sc.alreadySealed ? "re-sealed" : "sealed"} \u2014 archived ${moved} legacy DB(s), marker: ${sc.markerPath}`
+          );
+        }
+        cliOutput(
+          {
+            kind: "generic",
+            ok: true,
+            scopesSealed: result.scopes.map((s) => s.scope),
+            tablesVerified: result.parity.checked,
+            archived: result.scopes.flatMap(
+              (s) => s.archived.filter((a) => a.action === "archived").map((a) => ({ scope: s.scope, name: a.name, archivedTo: a.archivedTo }))
+            )
+          },
+          {
+            command: "exodus seal",
+            message: `Sealed ${result.scopes.map((s) => s.scope).join(
+              " + "
+            )} \u2014 ${result.parity.checked} tables count-verified, legacy DBs archived (reversible).`
+          }
+        );
+      }
+    });
     statusSubCommand = defineCommand({
       meta: {
         name: "status",
@@ -52561,6 +52857,7 @@ Passing tables (${passing.length}):`);
       subCommands: {
         migrate: migrateSubCommand,
         verify: verifySubCommand,
+        seal: sealSubCommand,
         status: statusSubCommand
       },
       async run({ cmd, rawArgs }) {
@@ -52939,6 +53236,7 @@ var init_find = __esm({
         }
       },
       async run({ args }) {
+        if (maybeEmitDescribe("query", "tasks", "find", { command: "find" })) return;
         const limit = args.limit !== void 0 ? Number.parseInt(args.limit, 10) : void 0;
         const offset = args.offset !== void 0 ? Number.parseInt(args.offset, 10) : void 0;
         const params = {};
@@ -55651,6 +55949,7 @@ var init_list3 = __esm({
       meta: { name: "list", description: "List tasks with optional filters" },
       args: listArgs,
       async run({ args }) {
+        if (maybeEmitDescribe("query", "tasks", "list", { command: "list" })) return;
         const limit = args["limit"] !== void 0 ? parseInt(args["limit"], 10) : void 0;
         const offset = args["offset"] !== void 0 ? parseInt(args["offset"], 10) : void 0;
         const params = {};
@@ -66756,7 +67055,7 @@ __export(schema_exports, {
   schemaCommand: () => schemaCommand2
 });
 import { getInputContract } from "@cleocode/core";
-import { describeOperation as describeOperation2 } from "@cleocode/lafs";
+import { describeOperation as describeOperation3 } from "@cleocode/lafs";
 function resolveOperationDef(operationArg) {
   const dotIdx = operationArg.indexOf(".");
   if (dotIdx === -1) {
@@ -66892,7 +67191,7 @@ var init_schema = __esm({
           );
           return;
         }
-        const schema2 = describeOperation2(def, {
+        const schema2 = describeOperation3(def, {
           includeGates,
           includeExamples
         });
@@ -73302,6 +73601,7 @@ var init_update = __esm({
         }
       },
       async run({ args, cmd }) {
+        if (maybeEmitDescribe("mutate", "tasks", "update", { command: "update" })) return;
         const paramsArg = args.params;
         const paramsFileArg = args["params-file"];
         if (paramsArg !== void 0 || paramsFileArg !== void 0) {
@@ -74805,6 +75105,7 @@ var init_worktree3 = __esm({
 
 // packages/cleo/src/cli/index.ts
 init_dist();
+init_describe_context();
 init_field_context();
 init_format_context();
 import { readFileSync as readFileSync21 } from "node:fs";
@@ -75132,6 +75433,18 @@ var COMMAND_MANIFEST = [
     description: "Walk every DB in the inventory + report integrity, row counts, orphan dirs. ",
     load: async () => (await Promise.resolve().then(() => (init_doctor_db_substrate(), doctor_db_substrate_exports))).doctorDbSubstrateCommand
   },
+  {
+    exportName: "doctorExodusResidueCommand",
+    name: "exodus-residue",
+    description: "Detect legacy exodus source DBs still present after a cutover (stranded residue that ",
+    load: async () => (await Promise.resolve().then(() => (init_doctor_exodus_residue(), doctor_exodus_residue_exports))).doctorExodusResidueCommand
+  },
+  {
+    exportName: "doctorExodusCommand",
+    name: "exodus-health",
+    description: "Read-only exodus health report: per-scope migration state, legacy DB sizes, completion ",
+    load: async () => (await Promise.resolve().then(() => (init_doctor_exodus(), doctor_exodus_exports))).doctorExodusCommand
+  },
   {
     exportName: "doctorLegacyBackupsCommand",
     name: "legacy-backups",
@@ -76051,6 +76364,7 @@ async function startCli() {
   let verboseFlag = false;
   let outputModeRaw;
   let summaryFlag = false;
+  let describeFlag = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--json") rawOpts["json"] = true;
@@ -76062,6 +76376,7 @@ async function startCli() {
     else if (arg === "--verbose" || arg === "--full") verboseFlag = true;
     else if (arg === "--output" && i + 1 < argv.length) outputModeRaw = argv[++i];
     else if (arg === "--summary") summaryFlag = true;
+    else if (arg === "--describe") describeFlag = true;
   }
   const interactiveTty = isInteractiveInvocation(argv) && process.stdout.isTTY === true;
   const formatResolution = resolveFormat(rawOpts, void 0, interactiveTty);
@@ -76091,6 +76406,7 @@ Valid modes: ${validModes.join(", ")}
     setOutputMode(resolvedMode);
   }
   setSummaryMode(summaryFlag);
+  setDescribeMode(describeFlag);
   const isHelpOrVersion = argv.length === 0 || argv[0] === "--help" || argv[0] === "-h" || argv[0] === "--version" || argv[0] === "-V" || argv[0] === "help";
   if (argv[0] === "--version" || argv[0] === "-V") {
     const { cliOutput: cliOutput2 } = await Promise.resolve().then(() => (init_renderers(), renderers_exports));
@@ -76139,7 +76455,8 @@ Valid modes: ${validModes.join(", ")}
       }
     }
   }
-  await runMainWithLafsEnvelope(main, argv, customShowUsage);
+  const dispatchArgv = describeFlag && !isHelpOrVersion ? [...argv, "__cleo_describe__"] : argv;
+  await runMainWithLafsEnvelope(main, dispatchArgv, customShowUsage);
 }
 function asCittyCliError(value) {
   if (!(value instanceof Error)) return null;