@cleocode/cleo 2026.5.108 → 2026.5.110

package/dist/cli/index.js

@@ -1719,6 +1719,189 @@ var init_credentials = __esm({
   }
 });
 
+// packages/contracts/src/db-inventory.json
+var db_inventory_default;
+var init_db_inventory = __esm({
+  "packages/contracts/src/db-inventory.json"() {
+    db_inventory_default = {
+      $schemaNote: "SSoT machine-readable inventory of every CLEO SQLite database. Consumed by T10307 fleet survey, T10310 pragma drift, T10311 migration coverage, T10312 doctor integrity, T10320 cross-DB invariants. Owned by Saga T10281 SG-BRAIN-DB-RESILIENCE / Epic T10282 E1-DB-INVENTORY (task T10305). Amend together with ADR-068 charter; the CI drift gate (forthcoming under E1) compares entries to disk reality.",
+      $pathTokens: {
+        "<projectRoot>": "Resolved at runtime from CLEO_ROOT env var or process.cwd(). Substituted by SSoT helpers `getCleoProjectDir()` in packages/brain/src/cleo-home.ts.",
+        $XDG_DATA_HOME: "Resolved via env-paths through `getCleoHome()` in @cleocode/paths. Linux: ~/.local/share/cleo/, macOS: ~/Library/Application Support/cleo/."
+      },
+      entries: [
+        {
+          role: "tasks",
+          tier: "project",
+          filePathTemplate: "<projectRoot>/.cleo/tasks.db",
+          drizzleSchemaPath: "packages/core/src/store/tasks-schema.ts",
+          migrationsDir: "packages/core/migrations/drizzle-tasks/",
+          ownerPackage: "@cleocode/core",
+          openedVia: "openCleoDb('tasks', cwd)",
+          concurrency: "single-writer",
+          privacy: "local-only",
+          backupPath: ".cleo/backups/sqlite/tasks-YYYYMMDD-HHmmss.db",
+          documentedIn: "ADR-068 row 1; ADR-013 \xA79"
+        },
+        {
+          role: "brain",
+          tier: "project",
+          filePathTemplate: "<projectRoot>/.cleo/brain.db",
+          drizzleSchemaPath: "packages/core/src/store/memory-schema.ts",
+          migrationsDir: "packages/core/migrations/drizzle-brain/",
+          ownerPackage: "@cleocode/brain",
+          openedVia: "openCleoDb('brain', cwd)",
+          concurrency: "single-writer",
+          privacy: "local-only-pii",
+          backupPath: ".cleo/backups/sqlite/brain-YYYYMMDD-HHmmss.db",
+          documentedIn: "ADR-068 row 2; ADR-013 \xA79; audit \xA72 (P0 malformed 2026-05-23)"
+        },
+        {
+          role: "conduit",
+          tier: "project",
+          filePathTemplate: "<projectRoot>/.cleo/conduit.db",
+          drizzleSchemaPath: "packages/core/src/store/conduit-schema.ts",
+          migrationsDir: "packages/core/migrations/drizzle-conduit/",
+          ownerPackage: "@cleocode/core",
+          openedVia: "openCleoDb('conduit', cwd)",
+          concurrency: "single-writer",
+          privacy: "local-only",
+          backupPath: ".cleo/backups/sqlite/conduit-YYYYMMDD-HHmmss.db",
+          documentedIn: "ADR-068 row 3; ADR-037 (signaldock\u2192conduit split)"
+        },
+        {
+          role: "manifest",
+          tier: "derived",
+          filePathTemplate: "<projectRoot>/.cleo/blobs/manifest.db",
+          drizzleSchemaPath: "packages/core/src/store/llmtxt-blob-adapter.ts",
+          migrationsDir: null,
+          ownerPackage: "@cleocode/core",
+          openedVia: "CleoBlobStore via llmtxt/blob BlobFsAdapter (no openCleoDb role registered)",
+          concurrency: "single-writer",
+          privacy: "local-only",
+          backupPath: "rebuildable-from-blob-store",
+          documentedIn: "ADR-068 row 7 (derived); schema owned by llmtxt/blob BlobFsAdapter contract"
+        },
+        {
+          role: "llmtxt",
+          tier: "project",
+          filePathTemplate: "<projectRoot>/.cleo/llmtxt/llmtxt.db",
+          drizzleSchemaPath: null,
+          migrationsDir: null,
+          ownerPackage: "@cleocode/llmtxt-core",
+          openedVia: "openCleoDb('llmtxt', cwd) \u2014 RESERVED; opener throws 'not yet implemented' (see open-cleo-db.ts L138)",
+          concurrency: "single-writer",
+          privacy: "local-only-pii",
+          backupPath: ".cleo/backups/sqlite/llmtxt-YYYYMMDD-HHmmss.db",
+          documentedIn: "ADR-068 row 8 (reserved); audit \xA71.1 row 4 (live at .cleo/llmtxt/llmtxt.db)"
+        },
+        {
+          role: "nexus",
+          tier: "global",
+          filePathTemplate: "$XDG_DATA_HOME/cleo/nexus.db",
+          drizzleSchemaPath: "packages/core/src/store/nexus-schema.ts",
+          migrationsDir: "packages/core/migrations/drizzle-nexus/",
+          ownerPackage: "@cleocode/core",
+          openedVia: "openCleoDb('nexus')",
+          concurrency: "single-writer",
+          privacy: "local-only-pii",
+          backupPath: "$XDG_DATA_HOME/cleo/backups/sqlite/nexus-YYYYMMDD-HHmmss.db",
+          documentedIn: "ADR-068 row 5"
+        },
+        {
+          role: "signaldock-project",
+          tier: "project",
+          filePathTemplate: "<projectRoot>/.cleo/signaldock.db",
+          drizzleSchemaPath: "packages/core/src/store/signaldock-schema.ts",
+          migrationsDir: "packages/core/migrations/drizzle-signaldock/",
+          ownerPackage: "@cleocode/core",
+          openedVia: "HISTORICAL \u2014 project-tier signaldock.db was migrated into conduit.db post-T310/ADR-037. No live opener; charter row retained for migration provenance and legacy backup detection.",
+          concurrency: "single-writer",
+          privacy: "local-only",
+          backupPath: ".cleo/backups/sqlite/signaldock-project-YYYYMMDD-HHmmss.db",
+          documentedIn: "ADR-068 row 4 (stale \u2014 superseded by ADR-037); audit \xA71.1 (not in live project DB list)"
+        },
+        {
+          role: "signaldock-global",
+          tier: "global",
+          filePathTemplate: "$XDG_DATA_HOME/cleo/signaldock.db",
+          drizzleSchemaPath: "packages/core/src/store/signaldock-schema.ts",
+          migrationsDir: "packages/core/migrations/drizzle-signaldock/",
+          ownerPackage: "@cleocode/core",
+          openedVia: "openCleoDb('signaldock')",
+          concurrency: "single-writer",
+          privacy: "local-only",
+          backupPath: "$XDG_DATA_HOME/cleo/backups/sqlite/signaldock-global-YYYYMMDD-HHmmss.db",
+          documentedIn: "ADR-068 row 9; ADR-037 (post-split global identity registry)"
+        },
+        {
+          role: "telemetry",
+          tier: "global",
+          filePathTemplate: "$XDG_DATA_HOME/cleo/telemetry.db",
+          drizzleSchemaPath: "packages/core/src/telemetry/schema.ts",
+          migrationsDir: "packages/core/migrations/drizzle-telemetry/",
+          ownerPackage: "@cleocode/core",
+          openedVia: "@cleocode/core telemetry/sqlite.ts \u2014 lazy open on first event when opted-in; not yet registered as openCleoDb role",
+          concurrency: "single-writer",
+          privacy: "cloud-exportable-opt-in",
+          backupPath: "$XDG_DATA_HOME/cleo/backups/sqlite/telemetry-YYYYMMDD-HHmmss.db",
+          documentedIn: "ADR-068 row 6; T624"
+        },
+        {
+          role: "skills",
+          tier: "global",
+          filePathTemplate: "$XDG_DATA_HOME/cleo/skills.db",
+          drizzleSchemaPath: "packages/core/src/store/skills-schema.ts",
+          migrationsDir: "packages/core/migrations/drizzle-skills/",
+          ownerPackage: "@cleocode/core",
+          openedVia: "openCleoDb('skills')",
+          concurrency: "single-writer",
+          privacy: "local-only",
+          backupPath: "$XDG_DATA_HOME/cleo/backups/sqlite/skills-YYYYMMDD-HHmmss.db",
+          documentedIn: "T9651 (initial skills.db migration); audit \xA71.2 row 4 \u2014 NOT yet in ADR-068 table"
+        },
+        {
+          role: "global-brain",
+          tier: "global",
+          filePathTemplate: "$XDG_DATA_HOME/cleo/brain.db",
+          drizzleSchemaPath: "packages/core/src/store/memory-schema.ts",
+          migrationsDir: "packages/core/migrations/drizzle-brain/",
+          ownerPackage: "@cleocode/brain",
+          openedVia: "UNREGISTERED \u2014 file exists on disk (audit \xA71.2 row 3) but no live opener. Provenance unclear; likely orphan from a getCleoHome()-vs-project-resolution path bug. Tracked for cleanup decision under T10282/T10307.",
+          concurrency: "single-writer",
+          privacy: "local-only-pii",
+          backupPath: "$XDG_DATA_HOME/cleo/backups/sqlite/global-brain-YYYYMMDD-HHmmss.db",
+          documentedIn: "audit \xA71.2 row 3 \u2014 NEW per saga T10281; not in ADR-068"
+        },
+        {
+          role: "global-tasks",
+          tier: "global",
+          filePathTemplate: "$XDG_DATA_HOME/cleo/tasks.db",
+          drizzleSchemaPath: "packages/core/src/store/tasks-schema.ts",
+          migrationsDir: "packages/core/migrations/drizzle-tasks/",
+          ownerPackage: "@cleocode/core",
+          openedVia: "UNREGISTERED \u2014 file exists on disk (audit \xA71.2 row 5, 4 KB) but no live opener. Provenance unclear; likely orphan from a cwd-cascade bug (T9550 class). Tracked for cleanup decision under T10282/T10307.",
+          concurrency: "single-writer",
+          privacy: "local-only",
+          backupPath: "$XDG_DATA_HOME/cleo/backups/sqlite/global-tasks-YYYYMMDD-HHmmss.db",
+          documentedIn: "audit \xA71.2 row 5 \u2014 NEW per saga T10281; not in ADR-068"
+        }
+      ]
+    };
+  }
+});
+
+// packages/contracts/src/db-inventory.ts
+var rawInventory, DB_INVENTORY;
+var init_db_inventory2 = __esm({
+  "packages/contracts/src/db-inventory.ts"() {
+    "use strict";
+    init_db_inventory();
+    rawInventory = db_inventory_default;
+    DB_INVENTORY = rawInventory.entries;
+  }
+});
+
 // packages/contracts/src/dispatch/identity.ts
 var init_identity = __esm({
   "packages/contracts/src/dispatch/identity.ts"() {
@@ -11309,6 +11492,7 @@ var init_src2 = __esm({
     init_changesets();
     init_cli_category();
     init_credentials();
+    init_db_inventory2();
     init_identity();
     init_operations_registry();
     init_docs_taxonomy();
@@ -14626,7 +14810,38 @@ function validateCanonRegistry(raw, source) {
   for (const [kindId, entryRaw] of Object.entries(kindsRaw)) {
     kinds[kindId] = validateKindEntry(kindId, entryRaw, source);
   }
-  return { version, kinds };
+  const similarity = validateSimilarity(obj["similarity"], source);
+  return similarity !== void 0 ? { version, kinds, similarity } : { version, kinds };
+}
+function validateSimilarity(raw, source) {
+  if (raw === void 0 || raw === null) {
+    return void 0;
+  }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${source}: 'similarity' must be an object`);
+  }
+  const obj = raw;
+  const warnThresholdRaw = obj["warnThreshold"];
+  let warnThreshold = 0.85;
+  if (warnThresholdRaw !== void 0) {
+    if (typeof warnThresholdRaw !== "number" || Number.isNaN(warnThresholdRaw) || warnThresholdRaw < 0 || warnThresholdRaw > 1) {
+      throw new Error(
+        `${source}: 'similarity.warnThreshold' must be a number in [0, 1] (got ${String(warnThresholdRaw)})`
+      );
+    }
+    warnThreshold = warnThresholdRaw;
+  }
+  const modeRaw = obj["mode"];
+  let mode = "warn";
+  if (modeRaw !== void 0) {
+    if (modeRaw !== "warn" && modeRaw !== "block") {
+      throw new Error(
+        `${source}: 'similarity.mode' must be 'warn' or 'block' (got ${String(modeRaw)})`
+      );
+    }
+    mode = modeRaw;
+  }
+  return { warnThreshold, mode };
 }
 function validateKindEntry(kindId, raw, source) {
   const where = `${source} kinds.${kindId}`;
@@ -15984,6 +16199,8 @@ import {
   getCleoDirAbsolute,
   getProjectRoot as getProjectRoot5,
   memoryObserve as memoryObserve2,
+  releaseReservedSlug,
+  reserveSlugForDispatch,
   resolveAttachmentBackend,
   SlugCollisionError
 } from "@cleocode/core/internal";
@@ -16499,6 +16716,25 @@ var init_docs2 = __esm({
             return lafsError("E_SLUG_PATTERN_MISMATCH", `${patternCheck.error}${exampleHint}`, "add");
           }
         }
+        if (slug !== void 0) {
+          const reservation = await reserveSlugForDispatch(getProjectRoot5(), {
+            kind: type2 ?? "",
+            slug
+          });
+          if (!reservation.ok) {
+            return {
+              success: false,
+              error: {
+                code: "E_SLUG_RESERVED",
+                message: `slug '${slug}' is already in use in this project`,
+                details: {
+                  suggestions: reservation.suggestions,
+                  aliases: ["E_SLUG_TAKEN"]
+                }
+              }
+            };
+          }
+        }
         const extras = {};
         if (slug !== void 0) extras.slug = slug;
         if (type2 !== void 0) extras.type = type2;
@@ -16535,13 +16771,17 @@ var init_docs2 = __esm({
               extras
             );
           } catch (err) {
+            if (slug !== void 0) releaseReservedSlug(slug);
             if (err instanceof SlugCollisionError) {
               return {
                 success: false,
                 error: {
-                  code: "E_SLUG_TAKEN",
+                  code: "E_SLUG_RESERVED",
                   message: `slug '${err.slug}' is already in use in this project`,
-                  details: { suggestions: err.suggestions }
+                  details: {
+                    suggestions: err.suggestions,
+                    aliases: ["E_SLUG_TAKEN"]
+                  }
                 }
               };
             }
@@ -16613,13 +16853,17 @@ var init_docs2 = __esm({
               extras
             );
           } catch (err) {
+            if (slug !== void 0) releaseReservedSlug(slug);
             if (err instanceof SlugCollisionError) {
               return {
                 success: false,
                 error: {
-                  code: "E_SLUG_TAKEN",
+                  code: "E_SLUG_RESERVED",
                   message: `slug '${err.slug}' is already in use in this project`,
-                  details: { suggestions: err.suggestions }
+                  details: {
+                    suggestions: err.suggestions,
+                    aliases: ["E_SLUG_TAKEN"]
+                  }
                 }
               };
             }
@@ -16785,6 +17029,7 @@ import {
   createAttachmentStore as createAttachmentStore2,
   memoryFind as memoryFind2,
   orchestrateReady as orchestrateReady2,
+  sagas,
   taskRelates as taskRelates2,
   taskShow as taskShow2
 } from "@cleocode/core/internal";
@@ -16886,8 +17131,7 @@ async function buildFocusEnvelope(id, projectRoot) {
     };
   }
   const task = showResult.data.task;
-  const labels = Array.isArray(task.labels) ? task.labels : [];
-  const isSaga = labels.includes("saga");
+  const isSaga = sagas.isSagaType(task);
   const isEpic = task.type === "epic" && !isSaga;
   const entityType = isSaga ? "saga" : isEpic ? "epic" : "task";
   const identity = {
@@ -25027,8 +25271,8 @@ async function loadPlaybookByName(name) {
     return null;
   }
   try {
-    const { getProjectRoot: getProjectRoot44 } = await import("@cleocode/core/internal");
-    const projectRoot = __playbookRuntimeOverrides.projectRoot ?? getProjectRoot44();
+    const { getProjectRoot: getProjectRoot48 } = await import("@cleocode/core/internal");
+    const projectRoot = __playbookRuntimeOverrides.projectRoot ?? getProjectRoot48();
     const resolved = resolvePlaybook(name, {
       projectRoot,
       globalPlaybooksDir: __playbookRuntimeOverrides.globalPlaybooksDir,
@@ -25072,8 +25316,8 @@ async function acquireDb() {
 async function buildDefaultDispatcher() {
   if (__playbookRuntimeOverrides.dispatcher) return __playbookRuntimeOverrides.dispatcher;
   const { orchestrateSpawnExecute: orchestrateSpawnExecute2 } = await Promise.resolve().then(() => (init_engine(), engine_exports));
-  const { getProjectRoot: getProjectRoot44 } = await import("@cleocode/core/internal");
-  const projectRoot = getProjectRoot44();
+  const { getProjectRoot: getProjectRoot48 } = await import("@cleocode/core/internal");
+  const projectRoot = getProjectRoot48();
   return {
     async dispatch(input2) {
       try {
@@ -25263,8 +25507,8 @@ var init_playbook2 = __esm({
             projectRoot = __playbookRuntimeOverrides.projectRoot;
           } else {
             try {
-              const { getProjectRoot: getProjectRoot44 } = await import("@cleocode/core/internal");
-              projectRoot = getProjectRoot44();
+              const { getProjectRoot: getProjectRoot48 } = await import("@cleocode/core/internal");
+              projectRoot = getProjectRoot48();
             } catch {
               projectRoot = void 0;
             }
@@ -25328,14 +25572,14 @@ var init_playbook2 = __esm({
         const dispatcher = await buildDefaultDispatcher();
         let result;
         try {
-          const { getProjectRoot: getProjectRoot44 } = await import("@cleocode/core/internal");
+          const { getProjectRoot: getProjectRoot48 } = await import("@cleocode/core/internal");
           const opts = {
             db,
             playbook: parsed.definition,
             playbookHash: parsed.sourceHash,
             initialContext,
             dispatcher,
-            projectRoot: getProjectRoot44()
+            projectRoot: getProjectRoot48()
           };
           if (__playbookRuntimeOverrides.approvalSecret !== void 0) {
             opts.approvalSecret = __playbookRuntimeOverrides.approvalSecret;
@@ -31123,11 +31367,11 @@ var init_security = __esm({
 });
 
 // packages/cleo/src/dispatch/middleware/sanitizer.ts
-function createSanitizer(getProjectRoot44) {
+function createSanitizer(getProjectRoot48) {
   return async (req, next) => {
     if (req.params) {
       try {
-        const root = getProjectRoot44 ? getProjectRoot44() : void 0;
+        const root = getProjectRoot48 ? getProjectRoot48() : void 0;
         req.params = sanitizeParams(req.params, root, {
           domain: req.domain,
           operation: req.operation
@@ -36113,6 +36357,282 @@ var init_backup_inspect = __esm({
   }
 });
 
+// packages/cleo/src/cli/lib/define-cli-command.ts
+var init_define_cli_command = __esm({
+  "packages/cleo/src/cli/lib/define-cli-command.ts"() {
+    "use strict";
+    init_dist();
+  }
+});
+
+// packages/cleo/src/cli/commands/backup-recover.ts
+var backup_recover_exports = {};
+__export(backup_recover_exports, {
+  backupRecoverBrainLeaf: () => backupRecoverBrainLeaf,
+  backupRecoverSubCommand: () => backupRecoverSubCommand
+});
+import { getLogger as getLogger20, getProjectRoot as getProjectRoot27 } from "@cleocode/core";
+import { BackupRecoverError, runBackupRecover } from "@cleocode/core/store/backup-recover.js";
+function readBoolFlag(args, key) {
+  return args[key] === true;
+}
+function readStringFlag(args, key) {
+  const v = args[key];
+  return typeof v === "string" ? v : "";
+}
+function executeRecover(role, args) {
+  const projectRoot = getProjectRoot27();
+  const dryRun = readBoolFlag(args, "dry-run");
+  const fromSnapshot = readStringFlag(args, "from-snapshot");
+  const noDelta = readBoolFlag(args, "no-delta");
+  const operation = `backup.recover.${role}`;
+  try {
+    const result = runBackupRecover({
+      role,
+      projectRoot,
+      logger: getLogger20(`backup-recover-${role}`),
+      dryRun,
+      fromSnapshot: fromSnapshot.length > 0 ? fromSnapshot : void 0,
+      noDelta
+    });
+    cliOutput(result, {
+      command: "backup",
+      operation
+    });
+    if (result.dryRun) {
+      humanInfo(
+        `[dry-run] Would restore role "${role}" from ${result.restoredFrom} (${result.dataLossWindowHours !== null ? `~${result.dataLossWindowHours}h data-loss window` : "data-loss window unknown"}). Re-run without --dry-run to execute (project root: ${projectRoot}).`
+      );
+    } else {
+      humanInfo(
+        `Recovered "${role}" DB from ${result.restoredFrom}. Corrupt DB quarantined at ${result.quarantinedTo}.`
+      );
+    }
+  } catch (err) {
+    if (err instanceof BackupRecoverError) {
+      cliError(
+        err.message,
+        err.code,
+        {
+          name: err.codeName,
+          ...err.fix ? { fix: err.fix } : {}
+        },
+        { operation }
+      );
+      process.exitCode = err.code;
+      return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    cliError(message, 1 /* GENERAL_ERROR */, { name: "E_RECOVERY_FAILED" }, { operation });
+    process.exitCode = 1 /* GENERAL_ERROR */;
+  }
+}
+function parseRoleArg(value) {
+  const trimmed = value.trim();
+  for (const entry of DB_INVENTORY) {
+    if (entry.role === trimmed) {
+      return entry.role;
+    }
+  }
+  const validRoles = DB_INVENTORY.map((e) => e.role).join(", ");
+  throw new BackupRecoverError(
+    `Unknown DB role "${trimmed}". Valid roles: ${validRoles}.`,
+    6 /* VALIDATION_ERROR */,
+    "E_UNKNOWN_ROLE",
+    "Run `cleo backup recover --help` for the list of valid roles."
+  );
+}
+var backupRecoverBrainLeaf, backupRecoverSubCommand;
+var init_backup_recover = __esm({
+  "packages/cleo/src/cli/commands/backup-recover.ts"() {
+    "use strict";
+    init_src2();
+    init_define_cli_command();
+    init_renderers();
+    backupRecoverBrainLeaf = defineCommand({
+      meta: {
+        name: "brain",
+        description: "Recover a malformed brain.db from the freshest validated snapshot (Saga T10281 SG-BRAIN-DB-RESILIENCE)"
+      },
+      args: {
+        "dry-run": {
+          type: "boolean",
+          description: "Print what would be done without quarantining or copying any files",
+          default: false
+        },
+        "from-snapshot": {
+          type: "string",
+          description: "Pin recovery to a specific snapshot \u2014 absolute path or ISO timestamp prefix (e.g. 2026-05-23)",
+          default: ""
+        },
+        "no-delta": {
+          type: "boolean",
+          description: "Skip the sqlite3 .recover delta-merge step (reserved \u2014 current pipeline does not delta-merge; flag plumbed for forward-compat)",
+          default: false
+        },
+        force: {
+          type: "boolean",
+          description: "Bypass any safety prompts (currently a no-op; reserved)",
+          default: false
+        }
+      },
+      async run({ args }) {
+        const argsBag = args;
+        executeRecover("brain", argsBag);
+      }
+    });
+    backupRecoverSubCommand = defineCommand({
+      meta: {
+        name: "recover",
+        description: "Recover a malformed CLEO database from snapshot \u2014 accepts any role from DB_INVENTORY (T10318)"
+      },
+      args: {
+        role: {
+          type: "positional",
+          description: `Canonical DB role (one of: ${DB_INVENTORY.map((e) => e.role).join(", ")})`,
+          required: false
+        },
+        "dry-run": {
+          type: "boolean",
+          description: "Print what would be done without quarantining or copying any files",
+          default: false
+        },
+        "from-snapshot": {
+          type: "string",
+          description: "Pin recovery to a specific snapshot \u2014 absolute path or ISO timestamp prefix (e.g. 2026-05-23)",
+          default: ""
+        },
+        "no-delta": {
+          type: "boolean",
+          description: "Skip the sqlite3 .recover delta-merge step (reserved \u2014 current pipeline does not delta-merge; flag plumbed for forward-compat)",
+          default: false
+        },
+        force: {
+          type: "boolean",
+          description: "Bypass any safety prompts (currently a no-op; reserved)",
+          default: false
+        }
+      },
+      subCommands: {
+        brain: backupRecoverBrainLeaf
+      },
+      async run({ args }) {
+        const argsBag = args;
+        const roleArg = readStringFlag(argsBag, "role");
+        if (roleArg.length === 0) {
+          const validRoles = DB_INVENTORY.map((e) => e.role).join(", ");
+          cliError(
+            `Missing role. Try \`cleo backup recover <role>\` (one of: ${validRoles}).`,
+            6 /* VALIDATION_ERROR */,
+            {
+              name: "E_VALIDATION",
+              fix: "Run `cleo backup recover --help` to see available roles and flags."
+            },
+            { operation: "backup.recover" }
+          );
+          process.exitCode = 6 /* VALIDATION_ERROR */;
+          return;
+        }
+        let role;
+        try {
+          role = parseRoleArg(roleArg);
+        } catch (err) {
+          if (err instanceof BackupRecoverError) {
+            cliError(
+              err.message,
+              err.code,
+              {
+                name: err.codeName,
+                ...err.fix ? { fix: err.fix } : {}
+              },
+              { operation: "backup.recover" }
+            );
+            process.exitCode = err.code;
+            return;
+          }
+          throw err;
+        }
+        executeRecover(role, argsBag);
+      }
+    });
+  }
+});
+
+// packages/cleo/src/cli/commands/backup-verify.ts
+import { getProjectRoot as getProjectRoot28 } from "@cleocode/core";
+import { runBackupVerify } from "@cleocode/core/store/backup-verify.js";
+var backupVerifySubCommand;
+var init_backup_verify = __esm({
+  "packages/cleo/src/cli/commands/backup-verify.ts"() {
+    "use strict";
+    init_src2();
+    init_define_cli_command();
+    init_renderers();
+    backupVerifySubCommand = defineCommand({
+      meta: {
+        name: "verify",
+        description: "Walk DB_INVENTORY and report per-DB freshness + integrity for each snapshot in BOTH .cleo/backups/sqlite/ (canonical) and .cleo/backups/snapshot/ (legacy). Exits non-zero on any stale/corrupt finding."
+      },
+      args: {
+        "per-db-timeout-ms": {
+          type: "string",
+          description: "Per-DB integrity-check timeout in milliseconds (default: 30000).",
+          default: "30000"
+        },
+        json: { type: "boolean", description: "Output as JSON" },
+        human: { type: "boolean", description: "Force human-readable output" },
+        quiet: { type: "boolean", description: "Suppress non-essential output" }
+      },
+      async run({ args }) {
+        const argsBag = args;
+        const rawTimeout = argsBag["per-db-timeout-ms"];
+        let perDbTimeoutMs = 3e4;
+        if (typeof rawTimeout === "string" && rawTimeout.length > 0) {
+          const parsed = Number.parseInt(rawTimeout, 10);
+          if (!Number.isFinite(parsed) || parsed <= 0) {
+            cliError(
+              `Invalid --per-db-timeout-ms value: ${rawTimeout}`,
+              6 /* VALIDATION_ERROR */,
+              {
+                name: "E_VALIDATION",
+                fix: "Provide a positive integer number of milliseconds (e.g. --per-db-timeout-ms 30000)."
+              },
+              { operation: "backup.verify" }
+            );
+            process.exitCode = 6 /* VALIDATION_ERROR */;
+            return;
+          }
+          perDbTimeoutMs = parsed;
+        }
+        let result;
+        try {
+          result = runBackupVerify({
+            projectRoot: getProjectRoot28(),
+            perDbTimeoutMs
+          });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          cliError(
+            message,
+            1 /* GENERAL_ERROR */,
+            { name: "E_BACKUP_VERIFY_FAILED" },
+            { operation: "backup.verify" }
+          );
+          process.exitCode = 1 /* GENERAL_ERROR */;
+          return;
+        }
+        cliOutput(result, {
+          command: "backup",
+          operation: "backup.verify"
+        });
+        if ((result.summary.corrupt > 0 || result.summary.stale > 0) && (process.exitCode === void 0 || process.exitCode === 0)) {
+          process.exitCode = 1 /* GENERAL_ERROR */;
+        }
+      }
+    });
+  }
+});
+
 // packages/cleo/src/cli/commands/backup.ts
 var backup_exports = {};
 __export(backup_exports, {
@@ -36184,6 +36704,8 @@ var init_backup = __esm({
     init_paths();
     init_renderers();
     init_backup_inspect();
+    init_backup_recover();
+    init_backup_verify();
     addCommand2 = defineCommand({
       meta: {
         name: "add",
@@ -36267,9 +36789,9 @@ var init_backup = __esm({
       async run({ args }) {
         const scope = args.scope;
         const { packBundle } = await import("@cleocode/core/store/backup-pack.js");
-        const { getProjectRoot: getProjectRoot44 } = await import("@cleocode/core");
+        const { getProjectRoot: getProjectRoot48 } = await import("@cleocode/core");
         const includesProject = scope === "project" || scope === "all";
-        const projectRoot = includesProject ? getProjectRoot44() : void 0;
+        const projectRoot = includesProject ? getProjectRoot48() : void 0;
         let passphrase;
         if (args.encrypt === true) {
           passphrase = process.env["CLEO_BACKUP_PASSPHRASE"];
@@ -36345,12 +36867,12 @@ var init_backup = __esm({
       },
       async run({ args }) {
         const bundlePath = args.bundle;
-        const { getProjectRoot: getProjectRoot44, getCleoHome: getCleoHome6, getCleoVersion } = await import("@cleocode/core");
+        const { getProjectRoot: getProjectRoot48, getCleoHome: getCleoHome6, getCleoVersion } = await import("@cleocode/core");
         const { BundleError, cleanupStaging, unpackBundle } = await import("@cleocode/core/store/backup-unpack.js");
         const { regenerateConfigJson, regenerateProjectContextJson, regenerateProjectInfoJson } = await import("@cleocode/core/store/regenerators.js");
         const { regenerateAndCompare } = await import("@cleocode/core/store/restore-json-merge.js");
         const { buildConflictReport, writeConflictReport } = await import("@cleocode/core/store/restore-conflict-report.js");
-        const projectRoot = getProjectRoot44();
+        const projectRoot = getProjectRoot48();
         if (args.force !== true) {
           const existing = checkForExistingData(projectRoot, getCleoHome6());
           if (existing.length > 0) {
@@ -36518,7 +37040,9 @@ var init_backup = __esm({
         list: listCommand4,
         export: exportCommand,
         import: importCommand,
-        inspect: backupInspectSubCommand
+        inspect: backupInspectSubCommand,
+        recover: backupRecoverSubCommand,
+        verify: backupVerifySubCommand
       },
       async run({ cmd, rawArgs }) {
         if (isSubCommandDispatch(rawArgs, cmd.subCommands)) return;
@@ -36568,7 +37092,7 @@ var brain_exports = {};
 __export(brain_exports, {
   brainCommand: () => brainCommand
 });
-import { getProjectRoot as getProjectRoot27 } from "@cleocode/core";
+import { getProjectRoot as getProjectRoot29 } from "@cleocode/core";
 import {
   backfillBrainGraph,
   exportBrainAsGexf,
@@ -36613,7 +37137,7 @@ var init_brain2 = __esm({
         json: { type: "boolean", description: "Output results as JSON" }
       },
       async run({ args }) {
-        const root = getProjectRoot27();
+        const root = getProjectRoot29();
         try {
           const result = await runBrainMaintenance(root, {
             skipDecay: !!args["skip-decay"],
@@ -36684,7 +37208,7 @@ var init_brain2 = __esm({
         json: { type: "boolean", description: "Output results as JSON" }
       },
       async run({ args: _args }) {
-        const root = getProjectRoot27();
+        const root = getProjectRoot29();
         try {
           const result = await backfillBrainGraph(root);
           cliOutput(
@@ -36725,7 +37249,7 @@ var init_brain2 = __esm({
         json: { type: "boolean", description: "Output results as JSON" }
       },
       async run({ args: _args }) {
-        const root = getProjectRoot27();
+        const root = getProjectRoot29();
         try {
           const result = await purgeBrainNoise(root);
           cliOutput(
@@ -36771,7 +37295,7 @@ var init_brain2 = __esm({
         json: { type: "boolean", description: "Output results as JSON" }
       },
       async run({ args }) {
-        const root = getProjectRoot27();
+        const root = getProjectRoot29();
         const limit = Number.parseInt(args.limit, 10) || 20;
         try {
           const stats = await getPlasticityStats(root, limit);
@@ -36821,7 +37345,7 @@ var init_brain2 = __esm({
         json: { type: "boolean", description: "Output results as JSON" }
       },
       async run({ args: _args }) {
-        const root = getProjectRoot27();
+        const root = getProjectRoot29();
         try {
           const report = await getMemoryQualityReport(root);
           cliOutput(
@@ -36870,7 +37394,7 @@ var init_brain2 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot27();
+        const root = getProjectRoot29();
         const format = args.format ?? "gexf";
         if (format !== "gexf" && format !== "json") {
           cliError(`Invalid format: ${format}. Use 'gexf' or 'json'.`, "E_VALIDATION", {
@@ -37688,7 +38212,13 @@ __export(changeset_exports, {
 });
 import { existsSync as existsSync11 } from "node:fs";
 import { join as join14 } from "node:path";
-import { changesets, dataTable, getProjectRoot as getProjectRoot28 } from "@cleocode/core";
+import {
+  changesets,
+  dataTable,
+  detectStrayCleoDb,
+  getProjectRoot as getProjectRoot30,
+  resolveWorktreeRouting
+} from "@cleocode/core";
 function isValidKind(raw) {
   return typeof raw === "string" && CHANGESET_KINDS.includes(raw);
 }
@@ -37782,7 +38312,25 @@ var init_changeset = __esm({
           ...typeof args.notes === "string" && args.notes.length > 0 ? { notes: args.notes } : {},
           ...typeof args.breaking === "string" && args.breaking.length > 0 ? { breaking: args.breaking } : {}
         };
-        const projectRoot = getProjectRoot28();
+        const routing = resolveWorktreeRouting();
+        const strayDb = detectStrayCleoDb(routing);
+        if (strayDb) {
+          cliError(
+            `stray .cleo/tasks.db detected inside worktree at ${routing.worktreePath}. This is a leaked CLEO state directory.`,
+            6 /* VALIDATION_ERROR */,
+            {
+              name: "E_STRAY_WORKTREE_DB",
+              fix: `Remove it with: rm -rf ${routing.worktreePath}/.cleo \u2014 then retry. See ADR-068 \xA73 for the worktree DB isolation rationale.`
+            }
+          );
+          process.exit(6 /* VALIDATION_ERROR */);
+        }
+        if (routing.isWorktree && process.env["CLEO_QUIET"] !== "1") {
+          const routingLog = `[T10389] routing SSoT write from worktree cwd ${routing.cwd} \u2192 canonical project root ${routing.canonicalRoot}
+`;
+          process.stderr.write(routingLog);
+        }
+        const projectRoot = routing.canonicalRoot;
         const outcome = await changesets.writeChangesetEntry(entry, {
           projectRoot,
           ...typeof args["attached-by"] === "string" && args["attached-by"].length > 0 ? { attachedBy: args["attached-by"] } : {}
@@ -37809,7 +38357,7 @@ var init_changeset = __esm({
       },
       args: {},
       async run() {
-        const projectRoot = getProjectRoot28();
+        const projectRoot = getProjectRoot30();
         const dir = join14(projectRoot, ".changeset");
         if (!existsSync11(dir)) {
           const empty = { entries: [], count: 0, dir, note: "no .changeset/ dir" };
@@ -40543,17 +41091,18 @@ var init_colors = __esm({
 // packages/cleo/src/cli/renderers/generic-tree.ts
 import { ascii as ascii2, KindIcon as KindIcon2, pickIcon, RelationIcon } from "@cleocode/contracts/render/icon.js";
 function renderGenericTree(result, opts) {
+  const explicitCtx = opts.ctx !== void 0;
   const ctx = opts.ctx ?? resolveAnimateContext();
   if (!ctx.enabled) return "";
   if (opts.quiet) return renderQuiet(result);
-  const useAscii = ctx.inputs.noColor;
+  const useAscii = explicitCtx ? ctx.inputs.noColor : ctx.inputs.noColor || process.env["NO_COLOR"] != null;
   const lines = [];
   if (result.ancestors.length > 0) {
     lines.push(formatAncestorBanner(result.ancestors, useAscii));
     lines.push("");
   }
   const treeWithGlyphs = decorateGroupsEdges(result.tree, useAscii);
-  const body = renderTree(treeWithGlyphs, { ctx });
+  const body = renderTree(treeWithGlyphs, { ctx, asciiBoxDrawing: useAscii });
   if (body) lines.push(body);
   if (opts.withDeps || opts.withBlockers) {
     const annotations = renderAnnotations(result.tree, opts);
@@ -40617,7 +41166,15 @@ function kindIconOf(kind) {
   }
 }
 function resolveAnimateContext() {
-  return createAnimateContext({ flagResolution: getFormatContext() });
+  const fmt = getFormatContext();
+  if (fmt.format !== "human") {
+    return createAnimateContext({ flagResolution: fmt });
+  }
+  return createAnimateContext({
+    flagResolution: fmt,
+    isTTY: true,
+    noColor: false
+  });
 }
 var init_generic_tree = __esm({
   "packages/cleo/src/cli/renderers/generic-tree.ts"() {
@@ -41422,6 +41979,184 @@ var init_diagnostics2 = __esm({
   }
 });
 
+// packages/cleo/src/cli/lib/did-you-mean.ts
+function levenshteinDistance(input2, candidate) {
+  const inputLen = input2.length;
+  const candidateLen = candidate.length;
+  const matrix = Array.from({ length: inputLen + 1 }, (_, i) => [i]);
+  for (let j = 1; j <= candidateLen; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1; i <= inputLen; i++) {
+    for (let j = 1; j <= candidateLen; j++) {
+      const cost = input2[i - 1] === candidate[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        // deletion
+        matrix[i][j - 1] + 1,
+        // insertion
+        matrix[i - 1][j - 1] + cost
+        // substitution
+      );
+    }
+  }
+  return matrix[inputLen][candidateLen];
+}
+function didYouMean(input2, candidates, maxDistance = 2) {
+  const suggestions = candidates.map((candidate) => ({
+    command: candidate,
+    distance: levenshteinDistance(input2, candidate)
+  })).filter((item) => item.distance <= maxDistance).sort((a, b) => {
+    if (a.distance !== b.distance) {
+      return a.distance - b.distance;
+    }
+    return a.command.localeCompare(b.command);
+  }).map((item) => item.command);
+  return suggestions;
+}
+var init_did_you_mean = __esm({
+  "packages/cleo/src/cli/lib/did-you-mean.ts"() {
+    "use strict";
+  }
+});
+
+// packages/cleo/src/cli/lib/strict-args.ts
+function collectKnownLongFlags(schema2) {
+  const known = /* @__PURE__ */ new Set();
+  for (const [name, def] of Object.entries(schema2)) {
+    if (!def || def.type === "positional") continue;
+    known.add(`--${name}`);
+    if (def.type === "boolean") {
+      known.add(`--no-${name}`);
+    }
+    const alias2 = def.alias;
+    if (typeof alias2 === "string" && alias2.length > 0) {
+      known.add(alias2.length === 1 ? `-${alias2}` : `--${alias2}`);
+    } else if (Array.isArray(alias2)) {
+      for (const a of alias2) {
+        if (typeof a !== "string" || a.length === 0) continue;
+        known.add(a.length === 1 ? `-${a}` : `--${a}`);
+      }
+    }
+  }
+  return known;
+}
+function collectSuggestionCandidates(schema2) {
+  const candidates = [];
+  for (const [name, def] of Object.entries(schema2)) {
+    if (!def || def.type === "positional") continue;
+    candidates.push(`--${name}`);
+  }
+  return candidates.sort();
+}
+function assertKnownFlags(rawArgs, schema2, commandName) {
+  if (!rawArgs || rawArgs.length === 0) return;
+  if (schema2 === void 0) return;
+  if (typeof schema2 === "function" || typeof schema2 === "object" && schema2 !== null && "then" in schema2) {
+    return;
+  }
+  const resolved = schema2;
+  const known = collectKnownLongFlags(resolved);
+  const candidates = collectSuggestionCandidates(resolved);
+  for (let i = 0; i < rawArgs.length; i++) {
+    const token = rawArgs[i];
+    if (token === void 0) continue;
+    if (token === "--") break;
+    if (!token.startsWith("-")) continue;
+    if (token === "-") continue;
+    if (token.startsWith("--")) {
+      const eqIdx = token.indexOf("=");
+      const flagName = eqIdx >= 0 ? token.slice(0, eqIdx) : token;
+      if (!known.has(flagName)) {
+        throw new UnknownFlagError({
+          flag: flagName,
+          command: commandName,
+          suggestions: didYouMean(flagName, candidates, 3),
+          knownFlags: [...known].sort()
+        });
+      }
+    } else {
+      const eqIdx = token.indexOf("=");
+      const body = eqIdx >= 0 ? token.slice(1, eqIdx) : token.slice(1);
+      const first = `-${body[0]}`;
+      if (!known.has(first)) {
+        throw new UnknownFlagError({
+          flag: first,
+          command: commandName,
+          suggestions: didYouMean(first, candidates, 3),
+          knownFlags: [...known].sort()
+        });
+      }
+      if (eqIdx < 0 && body.length > 1) {
+        const isBooleanShort = isBooleanAlias(resolved, body[0]);
+        if (isBooleanShort) {
+          for (let k = 1; k < body.length; k++) {
+            const ch = body[k];
+            if (ch === void 0) continue;
+            const short = `-${ch}`;
+            if (!known.has(short)) {
+              throw new UnknownFlagError({
+                flag: short,
+                command: commandName,
+                suggestions: didYouMean(short, candidates, 3),
+                knownFlags: [...known].sort()
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+}
+function isBooleanAlias(schema2, letter) {
+  if (!letter) return false;
+  for (const def of Object.values(schema2)) {
+    if (!def || def.type !== "boolean") continue;
+    const alias2 = def.alias;
+    if (alias2 === letter) return true;
+    if (Array.isArray(alias2) && alias2.includes(letter)) return true;
+  }
+  return false;
+}
+var E_UNKNOWN_FLAG, UnknownFlagError;
+var init_strict_args = __esm({
+  "packages/cleo/src/cli/lib/strict-args.ts"() {
+    "use strict";
+    init_did_you_mean();
+    E_UNKNOWN_FLAG = "E_UNKNOWN_FLAG";
+    UnknownFlagError = class extends Error {
+      /** Stable LAFS error code string for envelope emission. */
+      code = E_UNKNOWN_FLAG;
+      /** The unknown flag token as it appeared in `rawArgs` (e.g. `--titel`, `-X`). */
+      flag;
+      /** Human-readable command label (e.g. `'docs add'`). */
+      command;
+      /** Did-you-mean suggestions, sorted by Levenshtein distance ascending. */
+      suggestions;
+      /** The full list of known flags accepted by the command (long form + short). */
+      knownFlags;
+      /** Suggested fix string for {@link CliErrorDetails.fix}. */
+      fix;
+      /**
+       * @param input - Structured failure context: offending flag, command
+       *   label, ranked suggestions, and the full known-flag set.
+       */
+      constructor(input2) {
+        const suggestionPart = input2.suggestions.length > 0 ? ` Did you mean: ${input2.suggestions.join(", ")}?` : "";
+        super(
+          `${E_UNKNOWN_FLAG}: unknown flag '${input2.flag}' for '${input2.command}'.${suggestionPart}`
+        );
+        this.name = "UnknownFlagError";
+        this.flag = input2.flag;
+        this.command = input2.command;
+        this.suggestions = input2.suggestions;
+        this.knownFlags = input2.knownFlags;
+        this.fix = input2.suggestions.length > 0 ? `Try one of: ${input2.suggestions.join(", ")}. Run \`cleo ${input2.command} --help\` for the full flag list.` : `Run \`cleo ${input2.command} --help\` for the full flag list.`;
+      }
+    };
+  }
+});
+
 // packages/cleo/src/viewer/pidfile.ts
 import { mkdir, readFile as readFile2, unlink, writeFile } from "node:fs/promises";
 import { dirname as dirname6, join as join18 } from "node:path";
@@ -41531,7 +42266,7 @@ import { dirname as dirname7, join as join19, normalize, resolve as resolve4 } f
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import {
   createAttachmentStore as createAttachmentStore5,
-  getProjectRoot as getProjectRoot29,
+  getProjectRoot as getProjectRoot31,
   searchAllProjectDocs
 } from "@cleocode/core/internal";
 function getViewerAssetsDir() {
@@ -41591,7 +42326,7 @@ async function serveStatic(res, assetsDir, relPath) {
   }
 }
 function buildViewerHandler(opts = {}) {
-  const projectRoot = opts.projectRoot ?? getProjectRoot29();
+  const projectRoot = opts.projectRoot ?? getProjectRoot31();
   const assetsDir = getViewerAssetsDir();
   const store = createAttachmentStore5();
   return async (req, res) => {
@@ -41769,7 +42504,7 @@ import { spawn } from "node:child_process";
 import { open as fsOpen } from "node:fs/promises";
 import { join as join20 } from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
-import { getCleoHome as getCleoHome3, getProjectRoot as getProjectRoot30 } from "@cleocode/core";
+import { getCleoHome as getCleoHome3, getProjectRoot as getProjectRoot32 } from "@cleocode/core";
 function getCleoBinPath() {
   const thisFile = fileURLToPath5(import.meta.url);
   return join20(thisFile, "..", "..", "index.js");
@@ -41820,7 +42555,7 @@ async function spawnDetachedServer(opts) {
     detached: true,
     stdio,
     env: { ...process.env, [DETACHED_CHILD_ENV]: "1" },
-    cwd: getProjectRoot30()
+    cwd: getProjectRoot32()
   });
   child.unref();
   if (handle) await handle.close();
@@ -41972,7 +42707,7 @@ var init_docs_viewer = __esm({
           pid: process.pid,
           port: handle.port,
           host: handle.host,
-          projectRoot: getProjectRoot30(),
+          projectRoot: getProjectRoot32(),
           startedAt: Date.now()
         };
         await writeViewerPidFile(record);
@@ -42253,10 +42988,14 @@ import {
   buildDocsGraph,
   CleoError as CleoError3,
   CounterMismatchError,
+  checkSlugSimilarity,
   createAttachmentStoreDocsAccessor,
+  DEFAULT_SIMILARITY_MODE,
+  DEFAULT_SIMILARITY_THRESHOLD,
+  detectStrayCleoDb as detectStrayCleoDb2,
   exportDocument,
   getAgentOutputsAbsolute,
-  getProjectRoot as getProjectRoot31,
+  getProjectRoot as getProjectRoot33,
   listDocVersions,
   makeClassifierForScanRoot,
   mergeDocs,
@@ -42265,6 +43004,8 @@ import {
   rankDocs,
   readJson,
   recordPublication,
+  resolveWorktreeFilePath,
+  resolveWorktreeRouting as resolveWorktreeRouting2,
   runDocsImport,
   searchAllProjectDocs as searchAllProjectDocs2,
   searchDocs as searchDocs2,
@@ -42365,12 +43106,14 @@ var init_docs3 = __esm({
     init_src2();
     init_dist();
     init_cli();
+    init_canon_docs();
+    init_strict_args();
     init_renderers();
     init_docs_viewer();
     addCommand5 = defineCommand({
       meta: {
         name: "add",
-        description: "Attach a local file or remote URL to a CLEO entity (task, session, observation). Owner type is inferred from the ID prefix: T### \u2192 task, ses_* \u2192 session, O-* \u2192 observation. Use --slug to set a human-friendly alias (unique per project) (T9636)."
+        description: 'Attach a local file or remote URL to a CLEO entity (task, session, observation). Owner type is inferred from the ID prefix: T### \u2192 task, ses_* \u2192 session, O-* \u2192 observation. Use --slug to set a human-friendly alias (unique per project) (T9636).\n\nPositional arguments:\n  <owner-id>             Owner entity ID (T###, ses_*, O-*) \u2014 required\n  [file]                 Local file path to attach \u2014 optional when --url is set\n\nNamed arguments:\n  --url <url>            Remote URL to attach (instead of a local file)\n  --desc <text>          Free-text description of this attachment\n  --labels <csv>         Comma-separated labels (e.g. rfc,spec)\n  --attached-by <name>   Agent identity that created the attachment (default: "human")\n  --slug <kebab>         Human-friendly alias, unique per project (T9636)\n  --type <kind>          Taxonomy classification \u2014 run `cleo docs list-types` for kinds\n\nUnknown flags are rejected with E_UNKNOWN_FLAG + did-you-mean suggestions (T10359).'
       },
       args: {
         "owner-id": {
@@ -42401,17 +43144,36 @@ var init_docs3 = __esm({
         },
         slug: {
           type: "string",
-          description: "Human-friendly kebab-case alias for the attachment, unique per project (T9636). Collision returns E_SLUG_TAKEN with 3 alternative suggestions."
+          description: "Human-friendly kebab-case alias for the attachment, unique per project (T9636). Collision returns E_SLUG_RESERVED with 3 alternative suggestions (legacy E_SLUG_TAKEN aliased under details.aliases for one release \u2014 T10386)."
         },
         type: {
           type: "string",
           description: "Taxonomy classification \u2014 run `cleo docs list-types` to enumerate registered kinds (T9637 / T9788)"
+        },
+        "allow-similar": {
+          type: "boolean",
+          description: "Bypass the T10361 slug-similarity check. Use when you really do mean to add a new doc with a near-duplicate slug (e.g. intentional fork). Every bypass is logged to .cleo/audit/similar-bypass.jsonl."
         }
       },
-      async run({ args }) {
+      async run({ args, rawArgs }) {
+        try {
+          assertKnownFlags(rawArgs, addCommand5.args, "docs add");
+        } catch (err) {
+          if (err instanceof UnknownFlagError) {
+            cliError(err.message, 6 /* VALIDATION_ERROR */, {
+              name: err.code,
+              fix: err.fix,
+              alternatives: err.suggestions.map((s) => ({ action: s, command: s })),
+              details: { flag: err.flag, knownFlags: err.knownFlags }
+            });
+            process.exit(6 /* VALIDATION_ERROR */);
+          }
+          throw err;
+        }
         const ownerId = args["owner-id"];
         const fileArg = args.file ?? void 0;
         const url = args.url ?? void 0;
+        const allowSimilar = args["allow-similar"] === true;
         if (!fileArg && !url) {
           cliError("provide a file path (positional argument) or --url <url>", 6, {
             name: "E_VALIDATION",
@@ -42419,13 +43181,113 @@ var init_docs3 = __esm({
           });
           process.exit(6);
         }
+        let resolvedFile;
+        if (fileArg) {
+          const routing = resolveWorktreeRouting2();
+          const strayDb = detectStrayCleoDb2(routing);
+          if (strayDb) {
+            cliError(
+              `stray .cleo/tasks.db detected inside worktree at ${routing.worktreePath}. This is a leaked CLEO state directory.`,
+              6,
+              {
+                name: "E_STRAY_WORKTREE_DB",
+                fix: `Remove it with: rm -rf ${routing.worktreePath}/.cleo \u2014 then retry. See ADR-068 \xA73 for the worktree DB isolation rationale.`
+              }
+            );
+            process.exit(6);
+          }
+          if (routing.isWorktree && process.env["CLEO_QUIET"] !== "1") {
+            const routingLog = `[T10389] routing SSoT write from worktree cwd ${routing.cwd} \u2192 canonical project root ${routing.canonicalRoot}
+`;
+            process.stderr.write(routingLog);
+          }
+          resolvedFile = resolveWorktreeFilePath(String(fileArg), routing);
+        }
+        if (args.slug && args.type) {
+          const projectRoot = await getProjectRoot33();
+          let warnThreshold = DEFAULT_SIMILARITY_THRESHOLD;
+          let mode = DEFAULT_SIMILARITY_MODE;
+          try {
+            const canon = loadCanonRegistry(projectRoot);
+            if (canon?.similarity) {
+              warnThreshold = canon.similarity.warnThreshold;
+              mode = canon.similarity.mode;
+            }
+          } catch {
+          }
+          try {
+            const sim = await checkSlugSimilarity({
+              slug: args.slug,
+              type: args.type,
+              projectRoot,
+              threshold: warnThreshold
+            });
+            if (sim.mostSimilarSlug !== null) {
+              const scoreFixed = sim.score.toFixed(2);
+              const hint = `Similar to '${sim.mostSimilarSlug}' (score ${scoreFixed}) \u2014 did you mean: cleo docs update ${sim.mostSimilarSlug}? Pass --allow-similar to bypass.`;
+              if (mode === "block" && !allowSimilar) {
+                cliError(hint, 6 /* VALIDATION_ERROR */, {
+                  name: "E_SLUG_SIMILARITY",
+                  fix: `Use \`cleo docs update ${sim.mostSimilarSlug}\` if updating, or pass --allow-similar to add as a new doc.`,
+                  alternatives: [
+                    {
+                      action: `update '${sim.mostSimilarSlug}' instead`,
+                      command: `cleo docs update ${sim.mostSimilarSlug}`
+                    },
+                    {
+                      action: "bypass the similarity check",
+                      command: `cleo docs add ${ownerId} ${fileArg ?? `--url ${url}`} --slug ${args.slug} --type ${args.type} --allow-similar`
+                    }
+                  ],
+                  details: {
+                    proposedSlug: args.slug,
+                    mostSimilarSlug: sim.mostSimilarSlug,
+                    score: sim.score,
+                    threshold: warnThreshold,
+                    kind: args.type
+                  }
+                });
+                process.exit(6 /* VALIDATION_ERROR */);
+              }
+              humanInfo(hint);
+              if (allowSimilar) {
+                const auditLine = `${JSON.stringify({
+                  ts: (/* @__PURE__ */ new Date()).toISOString(),
+                  reason: "allow-similar-bypass",
+                  proposedSlug: args.slug,
+                  mostSimilarSlug: sim.mostSimilarSlug,
+                  score: sim.score,
+                  threshold: warnThreshold,
+                  kind: args.type,
+                  ownerId
+                })}
+`;
+                try {
+                  await mkdir2(join21(projectRoot, ".cleo", "audit"), { recursive: true });
+                  await appendFile(
+                    join21(projectRoot, ".cleo", "audit", "similar-bypass.jsonl"),
+                    auditLine,
+                    "utf-8"
+                  );
+                } catch {
+                }
+              }
+            }
+          } catch (err) {
+            if (process.env["CLEO_DEBUG"]) {
+              humanInfo(
+                `similarity check skipped: ${err instanceof Error ? err.message : String(err)}`
+              );
+            }
+          }
+        }
         await dispatchFromCli(
           "mutate",
           "docs",
           "add",
           {
             ownerId,
-            ...fileArg ? { file: fileArg } : {},
+            ...resolvedFile ? { file: resolvedFile } : {},
             ...url ? { url } : {},
             ...args.desc ? { desc: args.desc } : {},
             ...args.labels ? { labels: args.labels } : {},
@@ -42642,7 +43504,7 @@ var init_docs3 = __esm({
         const taskId = String(args.task);
         const includeAttachments = args["include-attachments"] !== false;
         const includeMemoryRefs = args["include-memory-refs"] === true;
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         try {
           const result = await exportDocument({
             taskId,
@@ -42708,7 +43570,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         const limit = args.limit ? Number.parseInt(String(args.limit), 10) : 10;
         try {
           const result = args.owner ? await searchDocs2(String(args.query), {
@@ -42764,7 +43626,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         const rawStrategy = args.strategy ?? "three-way";
         const strategy = rawStrategy === "cherry-pick" || rawStrategy === "multi-diff" ? rawStrategy : "three-way";
         try {
@@ -42813,7 +43675,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         const fmt = args.format ?? "mermaid";
         try {
           const result = await buildDocsGraph({ ownerId: String(args.for), projectRoot });
@@ -42882,7 +43744,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         try {
           const result = await rankDocs({
             ownerId: String(args.for),
@@ -42920,7 +43782,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         try {
           const result = await listDocVersions({
             ownerId: String(args.for),
@@ -42963,7 +43825,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         try {
           const result = await publishDocs({
             ownerId: String(args.for),
@@ -43087,7 +43949,7 @@ var init_docs3 = __esm({
       },
       async run({ args }) {
         if (args.from) {
-          const projectRoot = getProjectRoot31();
+          const projectRoot = getProjectRoot33();
           const ownerId = args.for ?? void 0;
           if (!ownerId) {
             cliError(
@@ -43154,7 +44016,7 @@ var init_docs3 = __esm({
         }
       },
       async run() {
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         try {
           const result = await statusDocs({ projectRoot });
           cliOutput(result, { command: "docs status", operation: "docs.status" });
@@ -43239,7 +44101,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         const dirArg = String(args.dir);
         const scanRoot = isAbsolute2(dirArg) ? dirArg : resolve5(projectRoot, dirArg);
         const dryRun = args["dry-run"] === true;
@@ -43313,7 +44175,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         const { registry, configError } = loadCliRegistry(projectRoot);
         const kinds = registry.list().map(toWireKind);
         const extensionsCount = kinds.filter((k) => k.isExtension).length;
@@ -43357,7 +44219,7 @@ var init_docs3 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot31();
+        const projectRoot = getProjectRoot33();
         const { registry, configError } = loadCliRegistry(projectRoot);
         const kinds = registry.list().map(toWireKind);
         let counts2;
@@ -43435,6 +44297,235 @@ var init_docs3 = __esm({
   }
 });
 
+// packages/cleo/src/cli/commands/doctor-db-substrate.ts
+var doctor_db_substrate_exports = {};
+__export(doctor_db_substrate_exports, {
+  doctorDbSubstrateCommand: () => doctorDbSubstrateCommand
+});
+import { getProjectRoot as getProjectRoot34, pushWarning as pushWarning2 } from "@cleocode/core";
+import { surveyDbSubstrate, surveyFleetDbSubstrate } from "@cleocode/core/doctor/db-substrate.js";
+function pushSubstrateWarnings(result) {
+  for (const warning of result.warnings) {
+    const context = {
+      kind: warning.kind,
+      path: warning.path,
+      lastWriteMs: warning.lastWriteMs
+    };
+    if (warning.kind === "orphan-project-root") {
+      context["parentWorkspace"] = warning.parentWorkspace ?? null;
+    }
+    pushWarning2({
+      code: warning.kind === "orphan-project-root" ? "W_DB_SUBSTRATE_ORPHAN_PROJECT_ROOT" : "W_DB_SUBSTRATE_NESTED_NEXUS_DUPLICATE",
+      message: warning.kind === "orphan-project-root" ? `Orphan project-root .cleo/ at ${warning.path} (T9550 regression class \u2014 review then remove)` + (warning.parentWorkspace ? ` \u2014 attributed to workspace: ${warning.parentWorkspace}` : "") : `Nested-nexus duplicate at ${warning.path} (structural duplicate of the canonical flat layout)`,
+      severity: "warn",
+      context
+    });
+  }
+  for (const projectSurvey of result.projects) {
+    for (const [role, entry] of Object.entries(projectSurvey.dbs)) {
+      if (entry.pragmaDrift === null || entry.pragmaDrift.length === 0) continue;
+      for (const drift of entry.pragmaDrift) {
+        pushWarning2({
+          code: "W_DB_SUBSTRATE_PRAGMA_DRIFT",
+          message: `Pragma drift on ${role} (${entry.filePath}): expected ${drift.pragma}=${drift.expected}, actual=${drift.actual ?? "<unmeasurable>"}`,
+          severity: "warn",
+          context: {
+            role,
+            filePath: entry.filePath,
+            pragma: drift.pragma,
+            expected: drift.expected,
+            actual: drift.actual
+          }
+        });
+      }
+    }
+  }
+  for (const report of result.crossDbOrphans) {
+    if (report.skipped || report.orphanCount === 0) continue;
+    pushWarning2({
+      code: `W_DB_SUBSTRATE_CROSS_DB_${report.invariant}`,
+      message: `${report.invariant}: ${report.orphanCount} orphan row${report.orphanCount === 1 ? "" : "s"} \u2014 ${report.description}. ${report.suggestedFix}`,
+      severity: "warn",
+      context: {
+        invariant: report.invariant,
+        orphanCount: report.orphanCount,
+        sample: report.sample.join(","),
+        suggestedFix: report.suggestedFix
+      }
+    });
+  }
+}
+function pushPerDbWarnings(result) {
+  for (const projectSurvey of result.projects) {
+    for (const [role, dbEntry] of Object.entries(projectSurvey.dbs)) {
+      if (dbEntry.quarantinedTo !== null) {
+        pushWarning2({
+          code: "W_DB_SUBSTRATE_AUTO_QUARANTINED",
+          message: `Auto-quarantined corrupt ${role} DB at ${dbEntry.filePath} \u2192 ${dbEntry.quarantinedTo}. Recover via: cleo backup recover ${role}`,
+          severity: "warn",
+          context: {
+            role,
+            filePath: dbEntry.filePath,
+            quarantinedTo: dbEntry.quarantinedTo,
+            integrityCheckMs: dbEntry.integrityCheckMs
+          }
+        });
+      }
+      if (dbEntry.timedOut) {
+        pushWarning2({
+          code: "W_DB_SUBSTRATE_INTEGRITY_TIMEOUT",
+          message: `integrity_check on ${role} DB at ${dbEntry.filePath} took ${dbEntry.integrityCheckMs}ms \u2014 slow substrate flagged for operator attention`,
+          severity: "warn",
+          context: {
+            role,
+            filePath: dbEntry.filePath,
+            integrityCheckMs: dbEntry.integrityCheckMs
+          }
+        });
+      }
+    }
+  }
+}
+var DEFAULT_FLEET_ROOT, doctorDbSubstrateCommand;
+var init_doctor_db_substrate = __esm({
+  "packages/cleo/src/cli/commands/doctor-db-substrate.ts"() {
+    "use strict";
+    init_define_cli_command();
+    init_renderers();
+    DEFAULT_FLEET_ROOT = "/mnt/projects";
+    doctorDbSubstrateCommand = defineCommand({
+      meta: {
+        name: "db-substrate",
+        description: "Walk every DB in the inventory + report integrity, row counts, orphan dirs. Use --fleet for a multi-project survey under --fleet-root (default /mnt/projects)."
+      },
+      args: {
+        fleet: {
+          type: "boolean",
+          description: "Multi-project survey \u2014 walk every .cleo/-bearing subdir under --fleet-root"
+        },
+        "fleet-root": {
+          type: "string",
+          description: "Fleet root path (default: /mnt/projects). Only used with --fleet."
+        },
+        "integrity-timeout-ms": {
+          type: "string",
+          description: "Wall-clock budget for each PRAGMA integrity_check call (ms; default 60000; 0 disables)."
+        },
+        "no-quarantine": {
+          type: "boolean",
+          description: "Disable auto-quarantine of corrupt DBs (leaves them in place; report-only mode)."
+        },
+        json: { type: "boolean", description: "Output as JSON" },
+        human: { type: "boolean", description: "Force human-readable output" },
+        quiet: { type: "boolean", description: "Suppress non-essential output" }
+      },
+      async run({ args }) {
+        const isFleet = args.fleet === true;
+        let parsedTimeoutMs;
+        if (typeof args["integrity-timeout-ms"] === "string" && args["integrity-timeout-ms"].length > 0) {
+          const n = Number.parseInt(args["integrity-timeout-ms"], 10);
+          if (Number.isFinite(n) && n >= 0) {
+            parsedTimeoutMs = n;
+          }
+        }
+        const options = {
+          ...parsedTimeoutMs !== void 0 ? { integrityCheckTimeoutMs: parsedTimeoutMs } : {},
+          autoQuarantine: args["no-quarantine"] !== true
+        };
+        const result = isFleet ? surveyFleetDbSubstrate(
+          typeof args["fleet-root"] === "string" && args["fleet-root"].length > 0 ? args["fleet-root"] : DEFAULT_FLEET_ROOT,
+          options
+        ) : surveyDbSubstrate(getProjectRoot34(), options);
+        pushSubstrateWarnings(result);
+        pushPerDbWarnings(result);
+        cliOutput(result, {
+          command: "doctor",
+          operation: "doctor.db-substrate.run"
+        });
+        if (result.summary.corrupt > 0 && (process.exitCode === void 0 || process.exitCode === 0)) {
+          process.exitCode = 2;
+        }
+      }
+    });
+  }
+});
+
+// packages/cleo/src/cli/commands/doctor-legacy-backups.ts
+var doctor_legacy_backups_exports = {};
+__export(doctor_legacy_backups_exports, {
+  doctorLegacyBackupsCommand: () => doctorLegacyBackupsCommand
+});
+import { getProjectRoot as getProjectRoot35 } from "@cleocode/core";
+import { pruneLegacyBackups, scanLegacyBackups } from "@cleocode/core/doctor/legacy-backups.js";
+function parsePositiveInt(raw, fallback) {
+  if (raw === void 0 || raw === null) return fallback;
+  const parsed = Number.parseInt(String(raw), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return parsed;
+}
+var doctorLegacyBackupsCommand;
+var init_doctor_legacy_backups = __esm({
+  "packages/cleo/src/cli/commands/doctor-legacy-backups.ts"() {
+    "use strict";
+    init_define_cli_command();
+    init_renderers();
+    doctorLegacyBackupsCommand = defineCommand({
+      meta: {
+        name: "legacy-backups",
+        description: "Enumerate legacy *-pre-cleo.db.bak / brain.db.PRE-DUP-FIX-* / pre-untrack / rotation-overflow artefacts and report origin + retention recommendation. Use --prune to delete 'delete'-recommended files (always dry-run unless --no-dry-run is passed)."
+      },
+      args: {
+        prune: {
+          type: "boolean",
+          description: "Remove every artefact whose recommendation is 'delete'. Defaults to --dry-run; pass --no-dry-run to physically remove."
+        },
+        "dry-run": {
+          type: "boolean",
+          description: "Combine with --prune to preview deletions without touching the filesystem.",
+          default: true
+        },
+        "soft-retention-days": {
+          type: "string",
+          description: "Days under which artefacts are always kept (default 30)."
+        },
+        "hard-retention-days": {
+          type: "string",
+          description: "Days over which artefacts are eligible for prune (default 90)."
+        },
+        json: { type: "boolean", description: "Output as JSON" },
+        human: { type: "boolean", description: "Force human-readable output" },
+        quiet: { type: "boolean", description: "Suppress non-essential output" }
+      },
+      async run({ args }) {
+        const softRetentionDays = parsePositiveInt(args["soft-retention-days"], 30);
+        const hardRetentionDays = parsePositiveInt(args["hard-retention-days"], 90);
+        const projectRoot = getProjectRoot35();
+        let result;
+        if (args.prune === true) {
+          const dryRun = args["dry-run"] !== false;
+          result = pruneLegacyBackups(projectRoot, {
+            softRetentionDays,
+            hardRetentionDays,
+            dryRun
+          });
+        } else {
+          result = scanLegacyBackups(projectRoot, {
+            softRetentionDays,
+            hardRetentionDays
+          });
+        }
+        cliOutput(result, {
+          command: "doctor",
+          operation: "doctor.legacy-backups.run"
+        });
+        if (result.errors.length > 0 && (process.exitCode === void 0 || process.exitCode === 0)) {
+          process.exitCode = 1;
+        }
+      }
+    });
+  }
+});
+
 // packages/cleo/src/cli/commands/doctor-projects.ts
 var doctor_projects_exports = {};
 __export(doctor_projects_exports, {
@@ -43711,7 +44802,7 @@ __export(migrate_agents_v2_exports, {
 import { createHash as createHash2 } from "node:crypto";
 import { appendFileSync as appendFileSync2, existsSync as existsSync14, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync14 } from "node:fs";
 import { join as join22 } from "node:path";
-import { getProjectRoot as getProjectRoot32, installAgentFromCant } from "@cleocode/core/internal";
+import { getProjectRoot as getProjectRoot36, installAgentFromCant } from "@cleocode/core/internal";
 import { openCleoDb as openCleoDb2 } from "@cleocode/core/store/open-cleo-db";
 function sha256Hex(bytes) {
   return createHash2("sha256").update(bytes).digest("hex");
@@ -43898,7 +44989,7 @@ var init_migrate_agents_v2 = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot32();
+        const projectRoot = getProjectRoot36();
         const verbose = args.quiet !== true;
         if (verbose) {
           humanInfo("Scanning .cleo/cant/agents/ and .cleo/agents/ for unregistered agents...");
@@ -43942,7 +45033,7 @@ __export(doctor_exports, {
 });
 import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join23 } from "node:path";
-import { getProjectRoot as getProjectRoot33, pushWarning as pushWarning2 } from "@cleocode/core";
+import { getProjectRoot as getProjectRoot37, pushWarning as pushWarning3 } from "@cleocode/core";
 import {
   quarantineRogueCleoDir,
   scanRogueCleoDirs
@@ -44049,8 +45140,11 @@ var init_doctor = __esm({
     "use strict";
     init_dist();
     init_cli();
+    init_subcommand_guard();
     init_progress();
     init_renderers();
+    init_doctor_db_substrate();
+    init_doctor_legacy_backups();
     init_doctor_projects();
     init_migrate_agents_v2();
     FIXTURE_ID_PATTERNS = [/^E\d+$/, /^T\d+EP$/];
@@ -44062,6 +45156,12 @@ var init_doctor = __esm({
     ];
     doctorCommand2 = defineCommand({
       meta: { name: "doctor", description: "Run system diagnostics and health checks" },
+      subCommands: {
+        // T10307 / Saga T10281 / Epic T10282 — DB-substrate walker
+        "db-substrate": doctorDbSubstrateCommand,
+        // T10309 / Saga T10281 / Epic T10282 — Legacy-backup walker
+        "legacy-backups": doctorLegacyBackupsCommand
+      },
       args: {
         detailed: {
           type: "boolean",
@@ -44220,14 +45320,15 @@ var init_doctor = __esm({
           description: "Suppress non-essential output"
         }
       },
-      async run({ args }) {
+      async run({ args, cmd, rawArgs }) {
+        if (isSubCommandDispatch(rawArgs, cmd.subCommands)) return;
         const isHuman = args.human === true || !!process.stdout.isTTY && args.json !== true;
         const progress = createDoctorProgress(isHuman);
         progress.start();
         try {
           if (args.brain) {
             const { computeBrainHealthDashboard } = await import("@cleocode/core/memory/brain-health-dashboard.js");
-            const projectRoot = getProjectRoot33();
+            const projectRoot = getProjectRoot37();
             const dashboard = await computeBrainHealthDashboard(projectRoot);
             cliOutput(dashboard, { command: "doctor", operation: "doctor.brain" });
             if (dashboard.hasP0Failure) {
@@ -44236,7 +45337,7 @@ var init_doctor = __esm({
             return;
           }
           if (args["scan-test-fixtures-in-prod"]) {
-            const projectRoot = getProjectRoot33();
+            const projectRoot = getProjectRoot37();
             const matches = await scanTestFixturesInProd(projectRoot);
             const dryRun = args["dry-run"] !== false && args.quarantine !== true;
             const quarantined = !dryRun && matches.length > 0 ? await quarantineTestFixtures(projectRoot, matches) : void 0;
@@ -44324,7 +45425,7 @@ var init_doctor = __esm({
             progress.complete("Comprehensive diagnostics complete");
           } else if (args["scan-rogue-cleo-dirs"]) {
             progress.step(0, "Scanning for rogue .cleo/ directories");
-            const projectRoot = getProjectRoot33();
+            const projectRoot = getProjectRoot37();
             const reports = scanRogueCleoDirs(projectRoot);
             progress.complete(
               `Found ${reports.length} rogue .cleo/ director${reports.length === 1 ? "y" : "ies"}`
@@ -44333,7 +45434,7 @@ var init_doctor = __esm({
           } else if (args["quarantine-rogue-cleo-dirs"]) {
             const isDryRun = args["dry-run"] === true;
             progress.step(0, `${isDryRun ? "[DRY RUN] " : ""}Scanning for rogue .cleo/ directories`);
-            const projectRoot = getProjectRoot33();
+            const projectRoot = getProjectRoot37();
             const reports = scanRogueCleoDirs(projectRoot);
             if (reports.length === 0) {
               progress.complete("No rogue .cleo/ directories found \u2014 nothing to quarantine");
@@ -44387,7 +45488,7 @@ var init_doctor = __esm({
             const { detectAndRemoveLegacyGlobalFiles, detectAndRemoveStrayProjectNexus } = await import("@cleocode/core/store/cleanup-legacy.js");
             const { getCleoHome: getCleoHome6 } = await import("@cleocode/core");
             const cleoHome = getCleoHome6();
-            const projectRoot = getProjectRoot33();
+            const projectRoot = getProjectRoot37();
             const legacyResult = detectAndRemoveLegacyGlobalFiles(cleoHome);
             const strayResult = detectAndRemoveStrayProjectNexus(projectRoot);
             const isDryRun = args["dry-run"] === true;
@@ -44420,7 +45521,7 @@ var init_doctor = __esm({
           } else if (args["audit-worktree-orphans"]) {
             progress.step(0, "Comprehensive worktree anomaly audit (T9808 / council D009)");
             const { auditWorktreeOrphansComprehensive, scanWorktreeOrphansBudgeted } = await import("@cleocode/core/doctor/worktree-orphans.js");
-            const projectRoot = getProjectRoot33();
+            const projectRoot = getProjectRoot37();
             const timeoutSecs = args["timeout"] !== void 0 ? Number.parseInt(String(args["timeout"]), 10) : 30;
             const timeoutMs = Number.isFinite(timeoutSecs) && timeoutSecs > 0 ? timeoutSecs * 1e3 : 3e4;
             const maxEntriesPerLevel = args["max-entries-per-level"] !== void 0 ? Number.parseInt(String(args["max-entries-per-level"]), 10) : 500;
@@ -44434,7 +45535,7 @@ var init_doctor = __esm({
             const legacyOrphans = legacyScanResult.orphans;
             const totalAnomalies = comprehensive.count;
             if (legacyScanResult.softWarnMessage) {
-              pushWarning2({
+              pushWarning3({
                 code: "W_DOCTOR_SCAN_SOFT_WARN",
                 message: legacyScanResult.softWarnMessage,
                 severity: "warn"
@@ -44442,7 +45543,7 @@ var init_doctor = __esm({
             }
             if (legacyScanResult.isPartial) {
               const reason = legacyScanResult.partialReason === "timeout" ? `timed out after ${timeoutSecs}s (use --timeout <seconds> to adjust)` : `per-level entry cap of ${maxEntriesPerLevel} exceeded (use --max-entries-per-level <n> to adjust)`;
-              pushWarning2({
+              pushWarning3({
                 code: "W_DOCTOR_SCAN_PARTIAL",
                 message: `legacy orphan scan is PARTIAL \u2014 ${reason}. Results may be incomplete.`,
                 severity: "warn",
@@ -44477,7 +45578,7 @@ var init_doctor = __esm({
               `${isDryRun ? "[DRY RUN] " : ""}Scanning + pruning worktree-orphan .cleo/ directories`
             );
             const { pruneWorktreeOrphans, scanWorktreeOrphansBudgeted } = await import("@cleocode/core/doctor/worktree-orphans.js");
-            const projectRoot = getProjectRoot33();
+            const projectRoot = getProjectRoot37();
             const timeoutSecs = args["timeout"] !== void 0 ? Number.parseInt(String(args["timeout"]), 10) : 30;
             const timeoutMs = Number.isFinite(timeoutSecs) && timeoutSecs > 0 ? timeoutSecs * 1e3 : 3e4;
             const maxEntriesPerLevel = args["max-entries-per-level"] !== void 0 ? Number.parseInt(String(args["max-entries-per-level"]), 10) : 500;
@@ -44486,7 +45587,7 @@ var init_doctor = __esm({
               maxEntriesPerLevel: Number.isFinite(maxEntriesPerLevel) ? maxEntriesPerLevel : 500
             });
             if (scanResult.softWarnMessage) {
-              pushWarning2({
+              pushWarning3({
                 code: "W_DOCTOR_SCAN_SOFT_WARN",
                 message: scanResult.softWarnMessage,
                 severity: "warn"
@@ -44494,7 +45595,7 @@ var init_doctor = __esm({
             }
             if (scanResult.isPartial) {
               const reason = scanResult.partialReason === "timeout" ? `timed out after ${timeoutSecs}s (use --timeout <seconds> to adjust)` : `per-level entry cap of ${maxEntriesPerLevel} exceeded (use --max-entries-per-level <n> to adjust)`;
-              pushWarning2({
+              pushWarning3({
                 code: "W_DOCTOR_SCAN_PARTIAL",
                 message: `orphan scan is PARTIAL \u2014 ${reason}. Only orphans found before abort will be pruned.`,
                 severity: "warn",
@@ -44556,7 +45657,7 @@ var init_doctor = __esm({
               `${isDryRun ? "[DRY RUN] " : ""}Migrating .cleo/worktree-include \u2192 .worktreeinclude`
             );
             const { migrateWorktreeIncludeFile } = await import("@cleocode/core");
-            const projectRoot = getProjectRoot33();
+            const projectRoot = getProjectRoot37();
             const result = await migrateWorktreeIncludeFile(projectRoot, { dryRun: isDryRun });
             progress.complete(`Migration ${result.action}`);
             cliOutput(result, { command: "doctor", operation: "doctor.migrate-worktree-include" });
@@ -44572,7 +45673,7 @@ var init_doctor = __esm({
           } else if (args["audit-sagas"]) {
             progress.step(0, "Auditing Saga hierarchy for ADR-073 invariants");
             const { auditSagaHierarchy } = await import("@cleocode/core/doctor/saga-audit.js");
-            const projectRoot = getProjectRoot33();
+            const projectRoot = getProjectRoot37();
             const result = await auditSagaHierarchy(projectRoot);
             const summary = `Saga audit complete \u2014 ${result.sagas.length} saga(s) inspected, ${result.count} invariant violation(s), ${result.driftCount} drift warning(s)`;
             progress.complete(summary);
@@ -44590,7 +45691,7 @@ var init_doctor = __esm({
               { command: "doctor", operation: "admin.health" }
             );
             try {
-              const projectRoot = getProjectRoot33();
+              const projectRoot = getProjectRoot37();
               const conflicts = readMigrationConflicts(projectRoot);
               if (conflicts.length > 0) {
                 progress.complete(
@@ -44621,7 +45722,7 @@ var init_doctor = __esm({
               progress.complete("Health check complete");
             }
             try {
-              const projectRoot = getProjectRoot33();
+              const projectRoot = getProjectRoot37();
               const { auditSagaHierarchy } = await import("@cleocode/core/doctor/saga-audit.js");
               const sagaAudit = await auditSagaHierarchy(projectRoot);
               if (sagaAudit.sagas.length === 0) {
@@ -47768,7 +48869,7 @@ var llm_cost_exports = {};
 __export(llm_cost_exports, {
   costCommand: () => costCommand
 });
-import { getProjectRoot as getProjectRoot34 } from "@cleocode/core/internal";
+import { getProjectRoot as getProjectRoot38 } from "@cleocode/core/internal";
 import { computeCost } from "@cleocode/core/llm/usage-pricing";
 function resolveSessionId(raw) {
   if (raw === "current") {
@@ -47841,7 +48942,7 @@ var init_llm_cost = __esm({
           process.exit(6);
         }
         const sessionId = resolveSessionId(rawSessionId);
-        const projectRoot = getProjectRoot34(process.cwd());
+        const projectRoot = getProjectRoot38(process.cwd());
         let breakdown;
         try {
           breakdown = await loadSessionCostBreakdown(projectRoot, sessionId);
@@ -48482,7 +49583,7 @@ var llm_exports = {};
 __export(llm_exports, {
   llmCommand: () => llmCommand
 });
-import { pushWarning as pushWarning3 } from "@cleocode/core";
+import { pushWarning as pushWarning4 } from "@cleocode/core";
 async function getListProviders() {
   const { listProviders } = await import(
     /* webpackIgnore: true */
@@ -48613,7 +49714,7 @@ var init_llm3 = __esm({
           apiKey = envValue;
           source = "env";
         } else if (typeof a["api-key"] === "string" && a["api-key"]) {
-          pushWarning3({
+          pushWarning4({
             code: "W_DEPRECATED_FLAG",
             message: API_KEY_FLAG_DEPRECATION,
             deprecated: "--api-key=<value>",
@@ -49388,7 +50489,7 @@ var memory_exports = {};
 __export(memory_exports, {
   memoryCommand: () => memoryCommand
 });
-import { getProjectRoot as getProjectRoot35 } from "@cleocode/core";
+import { getProjectRoot as getProjectRoot39 } from "@cleocode/core";
 import {
   getBrainDb as getBrainDb2,
   getDreamStatus,
@@ -50312,7 +51413,7 @@ var init_memory3 = __esm({
       },
       args: {},
       async run() {
-        const root = getProjectRoot35();
+        const root = getProjectRoot39();
         try {
           const result = await runConsolidation(root);
           cliOutput(result, { command: "memory-consolidate", operation: "memory.consolidate" });
@@ -50336,7 +51437,7 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot35();
+        const root = getProjectRoot39();
         if (args.status) {
           try {
             const status = await getDreamStatus(root);
@@ -50373,7 +51474,7 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot35();
+        const root = getProjectRoot39();
         try {
           const { runObserver, runReflector } = await import("@cleocode/core/memory");
           const observerResult = await runObserver(root, args.session, {
@@ -50413,7 +51514,7 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot35();
+        const root = getProjectRoot39();
         try {
           await getBrainDb2(root);
           const { totalDuplicateRows, groups } = await scanDuplicateEntries();
@@ -50459,7 +51560,7 @@ var init_memory3 = __esm({
       async run({ args }) {
         const sourceDir = args.from;
         const isDryRun = !!args["dry-run"];
-        const projectRoot = getProjectRoot35();
+        const projectRoot = getProjectRoot39();
         try {
           const result = await importMemoryFiles({
             sourceDir,
@@ -50610,7 +51711,7 @@ var init_memory3 = __esm({
       },
       args: {},
       async run() {
-        const root = getProjectRoot35();
+        const root = getProjectRoot39();
         try {
           await getBrainDb2(root);
           const result = await getTierStats(root);
@@ -50653,7 +51754,7 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot35();
+        const root = getProjectRoot39();
         const targetTier = args.to;
         const reason = args.reason;
         const validTiers = ["medium", "long"];
@@ -50719,7 +51820,7 @@ var init_memory3 = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot35();
+        const root = getProjectRoot39();
         const targetTier = args.to;
         const reason = args.reason;
         const validTiers = ["short", "medium"];
@@ -51179,7 +52280,7 @@ var migrate_claude_mem_exports = {};
 __export(migrate_claude_mem_exports, {
   migrateClaudeMemCommand: () => migrateClaudeMemCommand
 });
-import { getProjectRoot as getProjectRoot36, migrateClaudeMem } from "@cleocode/core/internal";
+import { getProjectRoot as getProjectRoot40, migrateClaudeMem } from "@cleocode/core/internal";
 import { ingestLooseAgentOutputs, ingestRcasdDirectories } from "@cleocode/core/memory";
 import { getDb as getDb2 } from "@cleocode/core/store/sqlite";
 var storageCommand, claudeMemCommand, manifestIngestCommand, migrateClaudeMemCommand;
@@ -51242,7 +52343,7 @@ var init_migrate_claude_mem = __esm({
         }
       },
       async run({ args }) {
-        const root = getProjectRoot36();
+        const root = getProjectRoot40();
         try {
           const result = await migrateClaudeMem(root, {
             sourcePath: args.source,
@@ -51291,7 +52392,7 @@ var init_migrate_claude_mem = __esm({
         }
       },
       async run({ args }) {
-        const projectRoot = getProjectRoot36();
+        const projectRoot = getProjectRoot40();
         try {
           const db = await getDb2(projectRoot);
           const rcasdFlag = Boolean(args.rcasd);
@@ -51395,7 +52496,7 @@ __export(nexus_exports, {
 import { appendFile as appendFile2, mkdir as mkdir3 } from "node:fs/promises";
 import { homedir as homedir5 } from "node:os";
 import path4 from "node:path";
-import { getProjectRoot as getProjectRoot37 } from "@cleocode/core";
+import { getProjectRoot as getProjectRoot41 } from "@cleocode/core";
 import { getSymbolImpact } from "@cleocode/core/nexus";
 import { runNexusAnalysis } from "@cleocode/core/nexus/analyze-orchestrator.js";
 import { exportNexusGraph } from "@cleocode/core/nexus/export.js";
@@ -51510,7 +52611,7 @@ var init_nexus3 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         const startTime = Date.now();
         try {
           const [{ getNexusDb, nexusSchema }, { getIndexStats }] = await Promise.all([
@@ -52025,7 +53126,7 @@ var init_nexus3 = __esm({
         applyJsonFlag2(args.json);
         const startTime = Date.now();
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("query", "nexus", "clusters", { projectId, repoPath });
         const durationMs = Date.now() - startTime;
@@ -52069,7 +53170,7 @@ var init_nexus3 = __esm({
         applyJsonFlag2(args.json);
         const startTime = Date.now();
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("query", "nexus", "flows", { projectId, repoPath });
         const durationMs = Date.now() - startTime;
@@ -52112,7 +53213,7 @@ var init_nexus3 = __esm({
         void appendDeprecationTelemetry("nexus.context", "cleo graph context");
         const startTime = Date.now();
         const projectIdOverride = args["project-id"];
-        const repoPath = getProjectRoot37();
+        const repoPath = getProjectRoot41();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const limit = parseInt(args.limit, 10);
         const symbolName = args.symbol;
@@ -52175,7 +53276,7 @@ var init_nexus3 = __esm({
         const startTime = Date.now();
         const whyFlag = !!args.why;
         const projectIdOverride = args["project-id"];
-        const repoPath = getProjectRoot37();
+        const repoPath = getProjectRoot41();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const maxDepth = Math.min(parseInt(args.depth, 10), 5);
         const symbolName = args.symbol;
@@ -52247,7 +53348,7 @@ var init_nexus3 = __esm({
         const projectIdOverride = args["project-id"];
         const isIncremental = !!args.incremental;
         const ctx = getFormatContext();
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         humanInfo(`[nexus] Analyzing: ${repoPath}${isIncremental ? " (incremental)" : ""}`);
         if (!isIncremental) humanInfo("[nexus] Clearing existing index for project...");
         try {
@@ -52350,7 +53451,7 @@ var init_nexus3 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const startTime = Date.now();
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         const name = args.name;
         const response = await dispatchRaw("mutate", "nexus", "projects.register", {
           path: repoPath,
@@ -52708,7 +53809,7 @@ var init_nexus3 = __esm({
         applyJsonFlag2(args.json);
         const startTime = Date.now();
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("mutate", "nexus", "refresh-bridge", {
           repoPath,
@@ -52814,7 +53915,7 @@ var init_nexus3 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const startTime = Date.now();
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         const projectIdOverride = args["project-id"];
         const beforeRef = args.before ?? "HEAD~1";
         const afterRef = args.after ?? "HEAD";
@@ -52932,7 +54033,7 @@ var init_nexus3 = __esm({
         applyJsonFlag2(args.json);
         const startTime = Date.now();
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("query", "nexus", "route-map", { projectId });
         const durationMs = Date.now() - startTime;
@@ -52988,7 +54089,7 @@ var init_nexus3 = __esm({
         const startTime = Date.now();
         const routeSymbol = args.routeSymbol;
         const projectIdOverride = args["project-id"];
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("query", "nexus", "shape-check", { routeSymbol, projectId });
         const durationMs = Date.now() - startTime;
@@ -53378,7 +54479,7 @@ var init_nexus3 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const startTime = Date.now();
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         const projectIdOverride = args["project-id"];
         const projectId = projectIdOverride ?? Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("mutate", "nexus", "contracts-sync", {
@@ -53482,7 +54583,7 @@ var init_nexus3 = __esm({
       async run({ args }) {
         applyJsonFlag2(args.json);
         const startTime = Date.now();
-        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot37();
+        const repoPath = args.path ? path4.resolve(args.path) : getProjectRoot41();
         const projectId = Buffer.from(repoPath).toString("base64url").slice(0, 32);
         const response = await dispatchRaw("mutate", "nexus", "contracts-link-tasks", {
           projectId,
@@ -53563,7 +54664,7 @@ var init_nexus3 = __esm({
         const isIncremental = !!args.incremental;
         try {
           const result = await runNexusWiki({
-            projectRoot: getProjectRoot37(),
+            projectRoot: getProjectRoot41(),
             outputDir,
             communityFilter,
             incremental: isIncremental
@@ -55990,7 +57091,7 @@ var refresh_memory_exports = {};
 __export(refresh_memory_exports, {
   refreshMemoryCommand: () => refreshMemoryCommand
 });
-import { getProjectRoot as getProjectRoot38 } from "@cleocode/core";
+import { getProjectRoot as getProjectRoot42 } from "@cleocode/core";
 var refreshMemoryCommand;
 var init_refresh_memory = __esm({
   "packages/cleo/src/cli/commands/refresh-memory.ts"() {
@@ -56003,7 +57104,7 @@ var init_refresh_memory = __esm({
         description: "Regenerate .cleo/memory-bridge.md from brain.db"
       },
       async run() {
-        const projectDir = getProjectRoot38();
+        const projectDir = getProjectRoot42();
         const { writeMemoryBridge } = await import("@cleocode/core/internal");
         const result = await writeMemoryBridge(projectDir);
         if (result.written) {
@@ -56179,14 +57280,6 @@ var init_relates = __esm({
   }
 });
 
-// packages/cleo/src/cli/lib/define-cli-command.ts
-var init_define_cli_command = __esm({
-  "packages/cleo/src/cli/lib/define-cli-command.ts"() {
-    "use strict";
-    init_dist();
-  }
-});
-
 // packages/cleo/src/cli/commands/release/ship-e2e-smoke.ts
 import { release as release2 } from "@cleocode/core";
 var shipE2eSmokeCommand;
@@ -57412,7 +58505,7 @@ import fs3 from "node:fs";
 import path5 from "node:path";
 import {
   CleoError as CleoError7,
-  getProjectRoot as getProjectRoot39,
+  getProjectRoot as getProjectRoot43,
   getTaskAccessor as getTaskAccessor3,
   parseConflictReport,
   setAtPath
@@ -57433,7 +58526,7 @@ var init_restore = __esm({
         description: "Apply manually-resolved conflicts from .cleo/restore-conflicts.md"
       },
       async run() {
-        const projectRoot = getProjectRoot39();
+        const projectRoot = getProjectRoot43();
         const reportPath = path5.join(projectRoot, CLEO_DIR_NAME, RESTORE_CONFLICTS_MD);
         if (!fs3.existsSync(reportPath)) {
           humanLine("No pending restore conflicts. Nothing to finalize.");
@@ -59924,7 +61017,7 @@ var sequence_exports = {};
 __export(sequence_exports, {
   sequenceCommand: () => sequenceCommand
 });
-import { getProjectRoot as getProjectRoot40 } from "@cleocode/core/internal";
+import { getProjectRoot as getProjectRoot44 } from "@cleocode/core/internal";
 var showCommand12, checkCommand6, repairCommand2, sequenceCommand;
 var init_sequence = __esm({
   "packages/cleo/src/cli/commands/sequence.ts"() {
@@ -59960,7 +61053,7 @@ var init_sequence = __esm({
       meta: { name: "repair", description: "Reset counter to max + 1 if behind" },
       async run() {
         const { repairSequence } = await import("@cleocode/core/internal");
-        const projectRoot = getProjectRoot40();
+        const projectRoot = getProjectRoot44();
         const repair = await repairSequence(projectRoot);
         const result = {
           repaired: repair.repaired,
@@ -60415,8 +61508,8 @@ var init_session4 = __esm({
         "audit-scope": { type: "string", description: "Audit log scope (global|local)" }
       },
       async run({ args }) {
-        const { detectSessionDrift, getProjectRoot: getProjectRoot44 } = await import("@cleocode/core");
-        const projectRoot = await getProjectRoot44();
+        const { detectSessionDrift, getProjectRoot: getProjectRoot48 } = await import("@cleocode/core");
+        const projectRoot = await getProjectRoot48();
         const scope = args["audit-scope"] === "local" ? "local" : "global";
         const report = await detectSessionDrift({ projectRoot, auditScope: scope });
         cliOutput(report, { command: "session drift", operation: "session.drift" });
@@ -63182,7 +64275,7 @@ __export(token_exports, {
   tokenCommand: () => tokenCommand
 });
 import { readFileSync as readFileSync16 } from "node:fs";
-import { getProjectRoot as getProjectRoot41, measureTokenExchange, recordTokenExchange as recordTokenExchange2 } from "@cleocode/core/internal";
+import { getProjectRoot as getProjectRoot45, measureTokenExchange, recordTokenExchange as recordTokenExchange2 } from "@cleocode/core/internal";
 function readPayload(args, textKey, fileKey) {
   const text = args[textKey];
   const file = args[fileKey];
@@ -63346,7 +64439,7 @@ var init_token = __esm({
           domain: args.domain,
           operation: args.operation
         };
-        const result = args.record ? await recordTokenExchange2(getProjectRoot41(), input2) : await measureTokenExchange(input2);
+        const result = args.record ? await recordTokenExchange2(getProjectRoot45(), input2) : await measureTokenExchange(input2);
         cliOutput(result, {
           command: "token",
           operation: args.record ? "admin.token.record" : "token.estimate"
@@ -63382,7 +64475,7 @@ __export(transcript_exports, {
 });
 import { homedir as homedir6 } from "node:os";
 import { join as join30 } from "node:path";
-import { getProjectRoot as getProjectRoot42 } from "@cleocode/core";
+import { getProjectRoot as getProjectRoot46 } from "@cleocode/core";
 import {
   parseDurationMs,
   pruneTranscripts,
@@ -63412,7 +64505,7 @@ var init_transcript = __esm({
       async run({ args }) {
         if (args.pending) {
           try {
-            const projectRoot = getProjectRoot42();
+            const projectRoot = getProjectRoot46();
             const { scanPendingTranscripts } = await import("@cleocode/core/memory/transcript-scanner.js");
             const pending = await scanPendingTranscripts(projectRoot);
             cliOutput(
@@ -63509,7 +64602,7 @@ var init_transcript = __esm({
       async run({ args }) {
         const tier = args.tier ?? "warm";
         const dryRun = args["dry-run"] ?? false;
-        const projectRoot = getProjectRoot42();
+        const projectRoot = getProjectRoot46();
         try {
           const { extractTranscript } = await import("@cleocode/core/memory/transcript-extractor.js");
           const { findSessionTranscriptPath, listAllTranscripts } = await import("@cleocode/core/memory/transcript-scanner.js");
@@ -63621,7 +64714,7 @@ var init_transcript = __esm({
         const dryRun = args["dry-run"] ?? false;
         const olderThanHours = args["older-than-hours"] ? Number.parseInt(args["older-than-hours"], 10) : 24;
         const limit = args.limit ? Number.parseInt(args.limit, 10) : void 0;
-        const projectRoot = getProjectRoot42();
+        const projectRoot = getProjectRoot46();
         try {
           const { extractTranscript } = await import("@cleocode/core/memory/transcript-extractor.js");
           const { listAllTranscripts } = await import("@cleocode/core/memory/transcript-scanner.js");
@@ -64748,7 +65841,7 @@ __export(worktree_exports, {
   worktreeCommand: () => worktreeCommand
 });
 import readline4 from "node:readline";
-import { getProjectRoot as getProjectRoot43, listWorktrees as listWorktrees2 } from "@cleocode/core/internal";
+import { getProjectRoot as getProjectRoot47, listWorktrees as listWorktrees2 } from "@cleocode/core/internal";
 async function promptYesNo2(question) {
   return new Promise((resolve7) => {
     const rl = readline4.createInterface({ input: process.stdin, output: process.stdout });
@@ -64853,7 +65946,7 @@ var init_worktree3 = __esm({
         const staleDays = staleDaysRaw !== void 0 ? Number.parseInt(staleDaysRaw, 10) : void 0;
         const idleDaysRaw = typeof args["idle-days"] === "string" ? args["idle-days"] : void 0;
         const idleDays = idleDaysRaw !== void 0 ? Number.parseInt(idleDaysRaw, 10) : void 0;
-        const projectRoot = getProjectRoot43();
+        const projectRoot = getProjectRoot47();
         const listResult = await listWorktrees2({
           projectRoot,
           ...staleDays !== void 0 && !Number.isNaN(staleDays) ? { staleDays } : {}
@@ -65178,6 +66271,12 @@ var COMMAND_MANIFEST = [
     description: "Show bundle manifest without extracting or modifying anything",
     load: async () => (await Promise.resolve().then(() => (init_backup_inspect(), backup_inspect_exports))).backupInspectSubCommand
   },
+  {
+    exportName: "backupRecoverSubCommand",
+    name: "recover",
+    description: "Recover a malformed CLEO database from snapshot \u2014 accepts any role from DB_INVENTORY (T10318)",
+    load: async () => (await Promise.resolve().then(() => (init_backup_recover(), backup_recover_exports))).backupRecoverSubCommand
+  },
   {
     exportName: "backupCommand",
     name: "backup",
@@ -65382,6 +66481,18 @@ var COMMAND_MANIFEST = [
     description: "Documentation attachment management (add/list/fetch/remove), ",
     load: async () => (await Promise.resolve().then(() => (init_docs3(), docs_exports))).docsCommand
   },
+  {
+    exportName: "doctorDbSubstrateCommand",
+    name: "db-substrate",
+    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: "doctorLegacyBackupsCommand",
+    name: "legacy-backups",
+    description: "Enumerate legacy *-pre-cleo.db.bak / brain.db.PRE-DUP-FIX-* / pre-untrack / rotation-overflow ",
+    load: async () => (await Promise.resolve().then(() => (init_doctor_legacy_backups(), doctor_legacy_backups_exports))).doctorLegacyBackupsCommand
+  },
   {
     exportName: "doctorProjectsCommand",
     name: "doctor-projects",
@@ -66075,41 +67186,8 @@ function lazyCommand(meta, loader2) {
   };
 }
 
-// packages/cleo/src/cli/lib/did-you-mean.ts
-function levenshteinDistance(input2, candidate) {
-  const inputLen = input2.length;
-  const candidateLen = candidate.length;
-  const matrix = Array.from({ length: inputLen + 1 }, (_, i) => [i]);
-  for (let j = 1; j <= candidateLen; j++) {
-    matrix[0][j] = j;
-  }
-  for (let i = 1; i <= inputLen; i++) {
-    for (let j = 1; j <= candidateLen; j++) {
-      const cost = input2[i - 1] === candidate[j - 1] ? 0 : 1;
-      matrix[i][j] = Math.min(
-        matrix[i - 1][j] + 1,
-        // deletion
-        matrix[i][j - 1] + 1,
-        // insertion
-        matrix[i - 1][j - 1] + cost
-        // substitution
-      );
-    }
-  }
-  return matrix[inputLen][candidateLen];
-}
-function didYouMean(input2, candidates, maxDistance = 2) {
-  const suggestions = candidates.map((candidate) => ({
-    command: candidate,
-    distance: levenshteinDistance(input2, candidate)
-  })).filter((item) => item.distance <= maxDistance).sort((a, b) => {
-    if (a.distance !== b.distance) {
-      return a.distance - b.distance;
-    }
-    return a.command.localeCompare(b.command);
-  }).map((item) => item.command);
-  return suggestions;
-}
+// packages/cleo/src/cli/index.ts
+init_did_you_mean();
 
 // packages/cleo/src/cli/lib/first-run-detection.ts
 import { existsSync as existsSync16 } from "node:fs";
@@ -66385,8 +67463,8 @@ async function runStartupMaintenance() {
     detectAndRemoveLegacyGlobalFiles,
     detectAndRemoveStrayProjectNexus,
     getGlobalSalt,
-    getLogger: getLogger20,
-    getProjectRoot: getProjectRoot44,
+    getLogger: getLogger21,
+    getProjectRoot: getProjectRoot48,
     isCleanupMarkerSet,
     migrateSignaldockToConduit,
     needsSignaldockToConduitMigration,
@@ -66395,7 +67473,7 @@ async function runStartupMaintenance() {
   } = await import("@cleocode/core/internal");
   let projectRootForCleanup = "";
   try {
-    projectRootForCleanup = getProjectRoot44();
+    projectRootForCleanup = getProjectRoot48();
   } catch {
   }
   if (!isCleanupMarkerSet(CLI_VERSION, projectRootForCleanup)) {
@@ -66411,11 +67489,11 @@ async function runStartupMaintenance() {
     }
     setCleanupMarker(CLI_VERSION, projectRootForCleanup);
   }
-  const _startupLog = getLogger20("cli-startup");
+  const _startupLog = getLogger21("cli-startup");
   const isInitInvocation = process.argv.slice(2).some((a) => a === "init");
   if (!isInitInvocation) {
     try {
-      const _projectRootForMigration = getProjectRoot44();
+      const _projectRootForMigration = getProjectRoot48();
       if (needsSignaldockToConduitMigration(_projectRootForMigration)) {
         const migrationResult = migrateSignaldockToConduit(_projectRootForMigration);
         if (migrationResult.status === "failed") {