@cleocode/core 2026.9.21 → 2026.9.22

package/dist/docs/export-document.js

@@ -10509,7 +10509,7 @@ var init_operations_registry = __esm({
             type: "string",
             required: false,
             enum: DOCS_LIFECYCLE_STATUSES,
-            description: `Override the new lifecycle status. Defaults to "draft" on every update. Valid: ${DOCS_LIFECYCLE_STATUSES.join("|")}.`
+            description: `Override the new lifecycle status. Defaults to "draft" on every update. Alone (no file or content) it changes only the lifecycle status. Valid: ${DOCS_LIFECYCLE_STATUSES.join("|")}.`
           },
           {
             name: "dryRun",
@@ -12996,11 +12996,13 @@ var init_evidence_atom_schema = __esm({
     });
     prAtomSchema = z10.object({
       kind: z10.literal("pr"),
-      prNumber: z10.number().int().positive("pr atom requires a positive integer PR number")
+      prNumber: z10.number().int().positive("pr atom requires a positive integer PR number"),
+      componentPrNumber: z10.number().int().positive().optional()
     });
     ciAtomSchema = z10.object({
       kind: z10.literal("ci"),
-      prNumber: z10.number().int().positive("ci atom requires a positive integer PR number")
+      prNumber: z10.number().int().positive("ci atom requires a positive integer PR number"),
+      componentPrNumber: z10.number().int().positive().optional()
     });
     locDropAtomSchema = z10.object({
       kind: z10.literal("loc-drop"),
@@ -18640,6 +18642,22 @@ function linkedWorktreeMainRoot(dir) {
   if (basename2(commonDir) === ".git") return dirname2(commonDir);
   return readCoreWorktree(commonDir);
 }
+function describeWorktreeOwner(dir) {
+  const mainRoot = linkedWorktreeMainRoot(dir);
+  if (mainRoot === null) return "owning repository unknown (unreadable gitlink)";
+  let projectId = null;
+  try {
+    const parsed = JSON.parse(
+      readFileSync2(join3(mainRoot, ".cleo", "project-info.json"), "utf-8")
+    );
+    if (typeof parsed === "object" && parsed !== null && "projectId" in parsed) {
+      const value = parsed.projectId;
+      if (typeof value === "string" && value !== "") projectId = value;
+    }
+  } catch {
+  }
+  return projectId === null ? `owning repository ${mainRoot} (not an initialised CLEO project)` : `owning project ${mainRoot} (projectId ${projectId})`;
+}
 function readCoreWorktree(gitDir) {
   try {
     const config = readFileSync2(join3(gitDir, "config"), "utf-8");
@@ -25748,9 +25766,10 @@ function assertStorePathIsNotWorktreeResident(role, dbPath) {
     );
     return;
   }
+  const owner = describeWorktreeOwner(projectRoot);
   throw new CleoError(
     8 /* CONFIG_ERROR */,
-    `E_WT_DB_ISOLATION_VIOLATION: refusing to open '${role}' DB at ${dbPath} \u2014 parent ${projectRoot} is a git worktree (gitlink). DBs must open against the canonical project root.`,
+    `E_WT_DB_ISOLATION_VIOLATION: refusing to open '${role}' DB at ${dbPath} \u2014 parent ${projectRoot} is a git worktree (gitlink); ${owner}. DBs must open against the canonical project root.`,
     {
       fix: `Run from the canonical project root, or make sure the worktree's main repository is an initialised CLEO project so it resolves there. Inspect stranded worktree stores with \`cleo doctor worktree-stores\`. Emergency override (audited): CLEO_ALLOW_WORKTREE_DB_CREATE=1.`
     }
@@ -32337,216 +32356,6 @@ var init_memory_schema = __esm({
   }
 });
 
-// packages/core/src/store/snapshot-gate.ts
-import { join as join20 } from "node:path";
-function readGateState(db) {
-  const row = db.prepare("SELECT value FROM tasks_schema_meta WHERE key = ?").get(SNAPSHOT_GATE_META_KEY);
-  const state = { generation: 0, prefixes: {} };
-  if (!row) return state;
-  try {
-    const parsed = JSON.parse(row.value);
-    if (parsed === null || typeof parsed !== "object") return state;
-    if (typeof parsed.generation === "number" && Number.isSafeInteger(parsed.generation)) {
-      state.generation = parsed.generation;
-    }
-    for (const [prefix, e] of Object.entries(parsed.prefixes ?? {})) {
-      if (e && typeof e.generation === "number" && typeof e.startedAt === "number" && typeof e.completedAt === "number") {
-        state.prefixes[prefix] = {
-          generation: e.generation,
-          startedAt: e.startedAt,
-          completedAt: e.completedAt
-        };
-      }
-    }
-  } catch {
-  }
-  return state;
-}
-function writeGateState(db, state) {
-  db.prepare(
-    "INSERT INTO tasks_schema_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value"
-  ).run(SNAPSHOT_GATE_META_KEY, JSON.stringify(state));
-}
-function tryReadGateState(db) {
-  if (!db) return null;
-  try {
-    return readGateState(db);
-  } catch {
-    return null;
-  }
-}
-function needsSnapshot(entry, mode, nowMs, seenGeneration) {
-  if (!entry) return true;
-  if (mode === "required") return seenGeneration === null || entry.generation <= seenGeneration;
-  const elapsed = nowMs - entry.startedAt;
-  return elapsed < 0 || elapsed >= SNAPSHOT_DEBOUNCE_MS;
-}
-async function runGatedSnapshot(opts, snapshot) {
-  const now = opts.now ?? Date.now;
-  const mode = opts.mode ?? "routine";
-  const db = opts.stateDb;
-  const none = (skipped, error) => ({
-    snapshotted: [],
-    linked: [],
-    absent: [],
-    failed: [],
-    skipped,
-    ...error !== void 0 && { error }
-  });
-  const entryState = tryReadGateState(db);
-  const seenGeneration = mode === "required" ? opts.seenGeneration ?? entryState?.generation ?? null : null;
-  if (mode === "routine") {
-    if (!entryState) return none("state-unavailable");
-    const nowMs = now();
-    if (!opts.prefixes.some((p) => needsSnapshot(entryState.prefixes[p], mode, nowMs, null))) {
-      return none("debounced");
-    }
-  }
-  const lockPath2 = join20(opts.backupDir, GATE_LOCK_BASENAME);
-  let release;
-  try {
-    release = await acquireLock(lockPath2, {
-      retries: mode === "required" ? opts.lockWaitRetries ?? SNAPSHOT_LOCK_WAIT_RETRIES : 0,
-      stale: SNAPSHOT_LOCK_STALE_MS,
-      // A compromised lock (e.g. the backup dir was removed) must not throw
-      // from a timer and crash the host process.
-      onCompromised: () => {
-      }
-    });
-  } catch {
-    if (mode === "routine") return none("in-flight");
-    return none(
-      "lock-timeout",
-      `Snapshot lock ${lockPath2}.lock is still held after waiting. Another snapshot is running, or a crashed process left the lock (it expires after ${SNAPSHOT_LOCK_STALE_MS / 6e4} minutes). Remove it if no snapshot is running.`
-    );
-  }
-  try {
-    try {
-      opts.onLockAcquired?.();
-    } catch {
-    }
-    const state = tryReadGateState(db);
-    if (!state && mode === "routine") return none("state-unavailable");
-    const startMs = now();
-    const admitted = mode === "required" && opts.alwaysSnapshot === true ? [...opts.prefixes] : opts.prefixes.filter(
-      (p) => needsSnapshot(state?.prefixes[p], mode, startMs, seenGeneration)
-    );
-    if (admitted.length === 0) return none(mode === "routine" ? "debounced" : "covered");
-    const generation = (state?.generation ?? 0) + 1;
-    let claimed = false;
-    if (db && state) {
-      try {
-        writeGateState(db, { ...state, generation });
-        claimed = true;
-      } catch {
-      }
-    }
-    const snapshotted = [];
-    const linked = [];
-    const absent = [];
-    const failed = [];
-    for (const prefix of admitted) {
-      try {
-        const outcome = await snapshot(prefix);
-        if (outcome === "absent") absent.push(prefix);
-        else {
-          snapshotted.push(prefix);
-          if (outcome === "linked") linked.push(prefix);
-        }
-      } catch {
-        failed.push(prefix);
-      }
-    }
-    const satisfied = [...snapshotted, ...absent];
-    if (db && claimed && satisfied.length > 0) {
-      try {
-        const latest = readGateState(db);
-        const completedAt = now();
-        latest.generation = Math.max(latest.generation, generation);
-        for (const p of satisfied) {
-          latest.prefixes[p] = { generation, startedAt: startMs, completedAt };
-        }
-        writeGateState(db, latest);
-      } catch {
-      }
-    }
-    return { snapshotted, linked, absent, failed, skipped: null };
-  } finally {
-    await release().catch(() => {
-    });
-  }
-}
-function isValidStamp(ymd, hms) {
-  const y = Number(ymd.slice(0, 4));
-  const mo = Number(ymd.slice(4, 6));
-  const d = Number(ymd.slice(6, 8));
-  const h = Number(hms.slice(0, 2));
-  const mi = Number(hms.slice(2, 4));
-  const se = Number(hms.slice(4, 6));
-  if (mo < 1 || mo > 12 || d < 1 || h > 23 || mi > 59 || se > 59) return false;
-  const probe = new Date(Date.UTC(y, mo - 1, d));
-  return probe.getUTCFullYear() === y && probe.getUTCMonth() === mo - 1 && probe.getUTCDate() === d;
-}
-function selectSnapshotsToKeep(names, ctx = {}) {
-  const policy = ctx.policy ?? DEFAULT_SNAPSHOT_RETENTION;
-  const keep = /* @__PURE__ */ new Set();
-  const stamped = [];
-  for (const name2 of names) {
-    const m = STAMP_PATTERN.exec(name2);
-    const ymd = m?.[1];
-    const hms = m?.[2];
-    if (!ymd || !hms || !isValidStamp(ymd, hms)) {
-      keep.add(name2);
-      continue;
-    }
-    const stamp = `${ymd}-${hms}`;
-    if (ctx.nowStamp !== void 0 && stamp > ctx.nowStamp) {
-      keep.add(name2);
-      continue;
-    }
-    stamped.push({ name: name2, stamp });
-  }
-  if (ctx.pinned !== void 0 && names.includes(ctx.pinned)) keep.add(ctx.pinned);
-  stamped.sort((a, b) => a.stamp < b.stamp ? 1 : a.stamp > b.stamp ? -1 : 0);
-  for (const s of stamped.slice(0, policy.latest)) keep.add(s.name);
-  const keepNewestPerBucket = (bucketOf, slots) => {
-    const seen = /* @__PURE__ */ new Set();
-    for (const s of stamped) {
-      const bucket = bucketOf(s.stamp);
-      if (seen.has(bucket)) continue;
-      if (seen.size >= slots) break;
-      seen.add(bucket);
-      keep.add(s.name);
-    }
-  };
-  keepNewestPerBucket(
-    (stamp) => `${stamp.slice(0, 11)}q${Math.floor(Number(stamp.slice(11, 13)) / 15)}`,
-    policy.quarterHourly
-  );
-  keepNewestPerBucket((stamp) => stamp.slice(0, 11), policy.hourly);
-  keepNewestPerBucket((stamp) => stamp.slice(0, 8), policy.daily);
-  return keep;
-}
-var SNAPSHOT_DEBOUNCE_MS, SNAPSHOT_LOCK_STALE_MS, SNAPSHOT_LOCK_WAIT_RETRIES, SNAPSHOT_GATE_META_KEY, GATE_LOCK_BASENAME, DEFAULT_SNAPSHOT_RETENTION, STAMP_PATTERN;
-var init_snapshot_gate = __esm({
-  "packages/core/src/store/snapshot-gate.ts"() {
-    "use strict";
-    init_lock();
-    SNAPSHOT_DEBOUNCE_MS = 5 * 6e4;
-    SNAPSHOT_LOCK_STALE_MS = 10 * 6e4;
-    SNAPSHOT_LOCK_WAIT_RETRIES = 90;
-    SNAPSHOT_GATE_META_KEY = "sqlite_snapshot_gate";
-    GATE_LOCK_BASENAME = ".snapshot-gate";
-    DEFAULT_SNAPSHOT_RETENTION = {
-      latest: 1,
-      quarterHourly: 3,
-      hourly: 3,
-      daily: 3
-    };
-    STAMP_PATTERN = /-(\d{8})-(\d{6})\.db$/;
-  }
-});
-
 // packages/core/src/store/twin-collapse.ts
 import { createHash as createHash3 } from "node:crypto";
 function hasMainTable(db, name2) {
@@ -32623,6 +32432,22 @@ function mergeSchemaMetaValue(key, bare, twin) {
   const field = SCHEMA_META_COUNTER_FIELDS[key];
   return field === void 0 ? bare : withMaxCounter(bare, twin, field);
 }
+function mirrorCounterToBare(db, key) {
+  if (SCHEMA_META_COUNTER_FIELDS[key] === void 0) return;
+  if (!hasMainTable(db, "schema_meta")) return;
+  const twin = readKv(db, "tasks_schema_meta", key);
+  if (twin === void 0) return;
+  const bare = readKv(db, "schema_meta", key);
+  const next = bare === void 0 ? twin : mergeSchemaMetaValue(key, bare, twin);
+  if (next === null || next === bare) return;
+  writeKv(db, "schema_meta", key, next);
+}
+function bareCounterOf(db, key) {
+  const name2 = SCHEMA_META_COUNTER_FIELDS[key];
+  if (name2 === void 0 || !hasMainTable(db, "schema_meta")) return 0;
+  const bare = readKv(db, "schema_meta", key);
+  return (bare === void 0 ? void 0 : counterOf(bare, name2)) ?? 0;
+}
 function kvRows(db, table, schema = "main") {
   const rows = db.prepare(`SELECT key, value FROM ${schema}.${table}`).all();
   return new Map(rows.map((r) => [r.key, r.value]));
@@ -32755,6 +32580,39 @@ function applyStickyRows(db, schema, plan) {
   }
   return { inserted, replaced: 0, deleted };
 }
+function tagsOf(tagsJson) {
+  if (!tagsJson) return [];
+  try {
+    const parsed = JSON.parse(tagsJson);
+    if (!Array.isArray(parsed)) return [];
+    return [...new Set(parsed.filter((t) => typeof t === "string" && t.length > 0))];
+  } catch {
+    return [];
+  }
+}
+function syncStickyJunction(db, schema) {
+  const notes = db.prepare("SELECT id, tags_json FROM main.brain_sticky_notes").all();
+  const have = /* @__PURE__ */ new Map();
+  for (const r of db.prepare(`SELECT sticky_id, tag FROM ${schema}.brain_sticky_tags`).all()) {
+    const set = have.get(r.sticky_id) ?? /* @__PURE__ */ new Set();
+    set.add(r.tag);
+    have.set(r.sticky_id, set);
+  }
+  const insert = db.prepare(
+    `INSERT OR IGNORE INTO ${schema}.brain_sticky_tags (sticky_id, tag) VALUES (?, ?)`
+  );
+  const del = db.prepare(`DELETE FROM ${schema}.brain_sticky_tags WHERE sticky_id = ? AND tag = ?`);
+  let inserted = 0;
+  let deleted = 0;
+  for (const note of notes) {
+    const want = new Set(tagsOf(note.tags_json));
+    const current = have.get(note.id) ?? /* @__PURE__ */ new Set();
+    for (const tag of want)
+      if (!current.has(tag)) inserted += Number(insert.run(note.id, tag).changes);
+    for (const tag of current) if (!want.has(tag)) deleted += Number(del.run(note.id, tag).changes);
+  }
+  return { inserted, deleted };
+}
 function twinCollapseFailureOf(db) {
   return degraded.get(db);
 }
@@ -32964,7 +32822,7 @@ function collapseTwinTables(nativeDb, dbPath, options = {}) {
   }
   return inOrder();
 }
-var log6, TWIN_COLLAPSE_MARKER_PREFIX, TWIN_COLLAPSE_FAILURE_PREFIX, SCHEMA_META_COUNTER_FIELDS, SCHEMA_META_NEVER_DELETED, MAX_CONFLICTS, sha, ABSENT, hashMap, emptyPlan, SCHEMA_META, hashSets, EMPTY_SET, STICKY_TAGS, PAIRS, degraded, SHADOW_WRITE_REFUSED, SHADOW_WRITE_OPS;
+var log6, TWIN_COLLAPSE_MARKER_PREFIX, TWIN_COLLAPSE_FAILURE_PREFIX, SNAPSHOT_GATE_KEY, SCHEMA_META_COUNTER_FIELDS, SCHEMA_META_NEVER_DELETED, MAX_CONFLICTS, sha, ABSENT, hashMap, emptyPlan, SCHEMA_META, hashSets, EMPTY_SET, STICKY_TAGS, PAIRS, degraded, SHADOW_WRITE_REFUSED, SHADOW_WRITE_OPS;
 var init_twin_collapse = __esm({
   "packages/core/src/store/twin-collapse.ts"() {
     "use strict";
@@ -32972,18 +32830,18 @@ var init_twin_collapse = __esm({
     init_errors2();
     init_logger2();
     init_pre_repair_snapshot();
-    init_snapshot_gate();
     log6 = getLogger("twin-collapse");
     TWIN_COLLAPSE_MARKER_PREFIX = "twin_collapse:";
     TWIN_COLLAPSE_FAILURE_PREFIX = "twin_collapse_failed:";
+    SNAPSHOT_GATE_KEY = "sqlite_snapshot_gate";
     SCHEMA_META_COUNTER_FIELDS = {
       task_id_sequence: "counter",
-      [SNAPSHOT_GATE_META_KEY]: "generation",
+      [SNAPSHOT_GATE_KEY]: "generation",
       file_meta: "generation"
     };
     SCHEMA_META_NEVER_DELETED = /* @__PURE__ */ new Set([
       "task_id_sequence",
-      SNAPSHOT_GATE_META_KEY
+      SNAPSHOT_GATE_KEY
     ]);
     MAX_CONFLICTS = 50;
     sha = (value) => createHash3("sha256").update(value).digest("hex");
@@ -33048,7 +32906,12 @@ var init_twin_collapse = __esm({
           throw new Error(
             `sticky_tags collapse did not verify: ${missing} missing, ${lingering} not removed`
           );
-        return counts;
+        const synced = syncStickyJunction(db, "main");
+        return {
+          inserted: counts.inserted + synced.inserted,
+          replaced: 0,
+          deleted: counts.deleted + synced.deleted
+        };
       },
       shadow(db, plan) {
         db.exec(
@@ -33059,6 +32922,7 @@ var init_twin_collapse = __esm({
           "INSERT INTO temp.brain_sticky_tags (sticky_id, tag) SELECT sticky_id, tag FROM main.brain_sticky_tags"
         );
         applyStickyRows(db, "temp", plan);
+        syncStickyJunction(db, "temp");
       }
     };
     PAIRS = [SCHEMA_META, STICKY_TAGS];
@@ -38533,9 +38397,12 @@ async function writeMetaValue(cwd, key, value) {
     target: tasksSchemaMeta.key,
     set: { value: json }
   }).run();
+  const native = getNativeTasksDb(cwd);
+  if (native) mirrorCounterToBare(native, key);
 }
 function advanceTaskIdSequence(nativeDb, floor) {
   assertTwinCollapseWritable(nativeDb);
+  const lowest = Math.max(floor, bareCounterOf(nativeDb, "task_id_sequence"));
   nativeDb.prepare(`
       UPDATE tasks_schema_meta
       SET value = json_set(value,
@@ -38544,7 +38411,8 @@ function advanceTaskIdSequence(nativeDb, floor) {
         '$.checksum', 'alloc-' || strftime('%s','now')
       )
       WHERE key = 'task_id_sequence'
-    `).run(floor, floor);
+    `).run(lowest, lowest);
+  mirrorCounterToBare(nativeDb, "task_id_sequence");
   const row = nativeDb.prepare(`
       SELECT json_extract(value, '$.counter') AS counter
       FROM tasks_schema_meta WHERE key = 'task_id_sequence'
@@ -39588,12 +39456,12 @@ var init_sqlite_data_accessor = __esm({
 
 // packages/core/src/sequence/index.ts
 import { existsSync as existsSync17, readFileSync as readFileSync5, renameSync as renameSync5 } from "node:fs";
-import { join as join21 } from "node:path";
+import { join as join20 } from "node:path";
 function getLegacySequenceJsonPath(cwd) {
-  return join21(resolveOrCwd(cwd), ".cleo", ".sequence.json");
+  return join20(resolveOrCwd(cwd), ".cleo", ".sequence.json");
 }
 function getLegacySequencePath(cwd) {
-  return join21(resolveOrCwd(cwd), ".cleo", ".sequence");
+  return join20(resolveOrCwd(cwd), ".cleo", ".sequence");
 }
 function isValidSequenceState(value) {
   if (!value || typeof value !== "object") return false;
@@ -39768,9 +39636,9 @@ var init_sequence = __esm({
 });
 
 // packages/core/src/store/checkpoint-git-dir.ts
-import { join as join22 } from "node:path";
+import { join as join21 } from "node:path";
 function checkpointGitDir(cleoDir) {
-  return join22(cleoDir, CHECKPOINT_GIT_DIRNAME);
+  return join21(cleoDir, CHECKPOINT_GIT_DIRNAME);
 }
 var CHECKPOINT_GIT_DIRNAME;
 var init_checkpoint_git_dir = __esm({
@@ -39784,7 +39652,7 @@ var init_checkpoint_git_dir = __esm({
 import { execFile as execFile2 } from "node:child_process";
 import { existsSync as existsSync18 } from "node:fs";
 import { readFile as readFile4, writeFile } from "node:fs/promises";
-import { join as join23, resolve as resolve8 } from "node:path";
+import { join as join22, resolve as resolve8 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 function makeCleoGitEnv(cleoDir) {
   const abs = resolve8(cleoDir);
@@ -39808,7 +39676,7 @@ async function cleoGitCommand(args, cleoDir) {
   }
 }
 function isCleoGitInitialized(cleoDir) {
-  return existsSync18(join23(checkpointGitDir(cleoDir), "HEAD"));
+  return existsSync18(join22(checkpointGitDir(cleoDir), "HEAD"));
 }
 async function loadStateFileAllowlist(cwd) {
   try {
@@ -39852,25 +39720,25 @@ async function isCleoGitRepo(cleoDir) {
   return result.success && (result.stdout === "true" || isCleoGitInitialized(cleoDir));
 }
 function isMergeInProgress(cleoDir) {
-  return existsSync18(join23(checkpointGitDir(cleoDir), "MERGE_HEAD"));
+  return existsSync18(join22(checkpointGitDir(cleoDir), "MERGE_HEAD"));
 }
 async function isDetachedHead(cleoDir) {
   const result = await cleoGitCommand(["symbolic-ref", "HEAD"], cleoDir);
   return !result.success;
 }
 function isRebaseInProgress(cleoDir) {
-  return existsSync18(join23(checkpointGitDir(cleoDir), "rebase-merge")) || existsSync18(join23(checkpointGitDir(cleoDir), "rebase-apply"));
+  return existsSync18(join22(checkpointGitDir(cleoDir), "rebase-merge")) || existsSync18(join22(checkpointGitDir(cleoDir), "rebase-apply"));
 }
 async function recordCheckpointTime(cleoDir) {
   try {
-    const stateFile = join23(cleoDir, CHECKPOINT_STATE_FILE);
+    const stateFile = join22(cleoDir, CHECKPOINT_STATE_FILE);
     await writeFile(stateFile, String(Math.floor(Date.now() / 1e3)));
   } catch {
   }
 }
 async function getLastCheckpointTime(cleoDir) {
   try {
-    const stateFile = join23(cleoDir, CHECKPOINT_STATE_FILE);
+    const stateFile = join22(cleoDir, CHECKPOINT_STATE_FILE);
     const content = await readFile4(stateFile, "utf-8");
     const epoch = parseInt(content.trim(), 10);
     return Number.isNaN(epoch) ? 0 : epoch;
@@ -39882,7 +39750,7 @@ async function getChangedStateFiles(cleoDir, cwd) {
   const changed = [];
   const allStateFiles = await getAllStateFiles(cwd);
   for (const stateFile of allStateFiles) {
-    const fullPath = join23(cleoDir, stateFile);
+    const fullPath = join22(cleoDir, stateFile);
     if (!existsSync18(fullPath)) continue;
     const diffResult = await cleoGitCommand(["diff", "--quiet", "--", stateFile], cleoDir);
     const cachedResult = await cleoGitCommand(
@@ -39983,6 +39851,218 @@ var init_git_checkpoint = __esm({
   }
 });
 
+// packages/core/src/store/snapshot-gate.ts
+import { join as join23 } from "node:path";
+function readGateState(db) {
+  const row = db.prepare("SELECT value FROM tasks_schema_meta WHERE key = ?").get(SNAPSHOT_GATE_META_KEY);
+  const state = { generation: 0, prefixes: {} };
+  if (!row) return state;
+  try {
+    const parsed = JSON.parse(row.value);
+    if (parsed === null || typeof parsed !== "object") return state;
+    if (typeof parsed.generation === "number" && Number.isSafeInteger(parsed.generation)) {
+      state.generation = parsed.generation;
+    }
+    for (const [prefix, e] of Object.entries(parsed.prefixes ?? {})) {
+      if (e && typeof e.generation === "number" && typeof e.startedAt === "number" && typeof e.completedAt === "number") {
+        state.prefixes[prefix] = {
+          generation: e.generation,
+          startedAt: e.startedAt,
+          completedAt: e.completedAt
+        };
+      }
+    }
+  } catch {
+  }
+  return state;
+}
+function writeGateState(db, state) {
+  db.prepare(
+    "INSERT INTO tasks_schema_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value"
+  ).run(SNAPSHOT_GATE_META_KEY, JSON.stringify(state));
+  mirrorCounterToBare(db, SNAPSHOT_GATE_META_KEY);
+}
+function tryReadGateState(db) {
+  if (!db) return null;
+  try {
+    return readGateState(db);
+  } catch {
+    return null;
+  }
+}
+function needsSnapshot(entry, mode, nowMs, seenGeneration) {
+  if (!entry) return true;
+  if (mode === "required") return seenGeneration === null || entry.generation <= seenGeneration;
+  const elapsed = nowMs - entry.startedAt;
+  return elapsed < 0 || elapsed >= SNAPSHOT_DEBOUNCE_MS;
+}
+async function runGatedSnapshot(opts, snapshot) {
+  const now = opts.now ?? Date.now;
+  const mode = opts.mode ?? "routine";
+  const db = opts.stateDb;
+  const none = (skipped, error) => ({
+    snapshotted: [],
+    linked: [],
+    absent: [],
+    failed: [],
+    skipped,
+    ...error !== void 0 && { error }
+  });
+  const entryState = tryReadGateState(db);
+  const seenGeneration = mode === "required" ? opts.seenGeneration ?? entryState?.generation ?? null : null;
+  if (mode === "routine") {
+    if (!entryState) return none("state-unavailable");
+    const nowMs = now();
+    if (!opts.prefixes.some((p) => needsSnapshot(entryState.prefixes[p], mode, nowMs, null))) {
+      return none("debounced");
+    }
+  }
+  const lockPath2 = join23(opts.backupDir, GATE_LOCK_BASENAME);
+  let release;
+  try {
+    release = await acquireLock(lockPath2, {
+      retries: mode === "required" ? opts.lockWaitRetries ?? SNAPSHOT_LOCK_WAIT_RETRIES : 0,
+      stale: SNAPSHOT_LOCK_STALE_MS,
+      // A compromised lock (e.g. the backup dir was removed) must not throw
+      // from a timer and crash the host process.
+      onCompromised: () => {
+      }
+    });
+  } catch {
+    if (mode === "routine") return none("in-flight");
+    return none(
+      "lock-timeout",
+      `Snapshot lock ${lockPath2}.lock is still held after waiting. Another snapshot is running, or a crashed process left the lock (it expires after ${SNAPSHOT_LOCK_STALE_MS / 6e4} minutes). Remove it if no snapshot is running.`
+    );
+  }
+  try {
+    try {
+      opts.onLockAcquired?.();
+    } catch {
+    }
+    const state = tryReadGateState(db);
+    if (!state && mode === "routine") return none("state-unavailable");
+    const startMs = now();
+    const admitted = mode === "required" && opts.alwaysSnapshot === true ? [...opts.prefixes] : opts.prefixes.filter(
+      (p) => needsSnapshot(state?.prefixes[p], mode, startMs, seenGeneration)
+    );
+    if (admitted.length === 0) return none(mode === "routine" ? "debounced" : "covered");
+    const generation = (state?.generation ?? 0) + 1;
+    let claimed = false;
+    if (db && state) {
+      try {
+        writeGateState(db, { ...state, generation });
+        claimed = true;
+      } catch {
+      }
+    }
+    const snapshotted = [];
+    const linked = [];
+    const absent = [];
+    const failed = [];
+    for (const prefix of admitted) {
+      try {
+        const outcome = await snapshot(prefix);
+        if (outcome === "absent") absent.push(prefix);
+        else {
+          snapshotted.push(prefix);
+          if (outcome === "linked") linked.push(prefix);
+        }
+      } catch {
+        failed.push(prefix);
+      }
+    }
+    const satisfied = [...snapshotted, ...absent];
+    if (db && claimed && satisfied.length > 0) {
+      try {
+        const latest = readGateState(db);
+        const completedAt = now();
+        latest.generation = Math.max(latest.generation, generation);
+        for (const p of satisfied) {
+          latest.prefixes[p] = { generation, startedAt: startMs, completedAt };
+        }
+        writeGateState(db, latest);
+      } catch {
+      }
+    }
+    return { snapshotted, linked, absent, failed, skipped: null };
+  } finally {
+    await release().catch(() => {
+    });
+  }
+}
+function isValidStamp(ymd, hms) {
+  const y = Number(ymd.slice(0, 4));
+  const mo = Number(ymd.slice(4, 6));
+  const d = Number(ymd.slice(6, 8));
+  const h = Number(hms.slice(0, 2));
+  const mi = Number(hms.slice(2, 4));
+  const se = Number(hms.slice(4, 6));
+  if (mo < 1 || mo > 12 || d < 1 || h > 23 || mi > 59 || se > 59) return false;
+  const probe = new Date(Date.UTC(y, mo - 1, d));
+  return probe.getUTCFullYear() === y && probe.getUTCMonth() === mo - 1 && probe.getUTCDate() === d;
+}
+function selectSnapshotsToKeep(names, ctx = {}) {
+  const policy = ctx.policy ?? DEFAULT_SNAPSHOT_RETENTION;
+  const keep = /* @__PURE__ */ new Set();
+  const stamped = [];
+  for (const name2 of names) {
+    const m = STAMP_PATTERN.exec(name2);
+    const ymd = m?.[1];
+    const hms = m?.[2];
+    if (!ymd || !hms || !isValidStamp(ymd, hms)) {
+      keep.add(name2);
+      continue;
+    }
+    const stamp = `${ymd}-${hms}`;
+    if (ctx.nowStamp !== void 0 && stamp > ctx.nowStamp) {
+      keep.add(name2);
+      continue;
+    }
+    stamped.push({ name: name2, stamp });
+  }
+  if (ctx.pinned !== void 0 && names.includes(ctx.pinned)) keep.add(ctx.pinned);
+  stamped.sort((a, b) => a.stamp < b.stamp ? 1 : a.stamp > b.stamp ? -1 : 0);
+  for (const s of stamped.slice(0, policy.latest)) keep.add(s.name);
+  const keepNewestPerBucket = (bucketOf, slots) => {
+    const seen = /* @__PURE__ */ new Set();
+    for (const s of stamped) {
+      const bucket = bucketOf(s.stamp);
+      if (seen.has(bucket)) continue;
+      if (seen.size >= slots) break;
+      seen.add(bucket);
+      keep.add(s.name);
+    }
+  };
+  keepNewestPerBucket(
+    (stamp) => `${stamp.slice(0, 11)}q${Math.floor(Number(stamp.slice(11, 13)) / 15)}`,
+    policy.quarterHourly
+  );
+  keepNewestPerBucket((stamp) => stamp.slice(0, 11), policy.hourly);
+  keepNewestPerBucket((stamp) => stamp.slice(0, 8), policy.daily);
+  return keep;
+}
+var SNAPSHOT_DEBOUNCE_MS, SNAPSHOT_LOCK_STALE_MS, SNAPSHOT_LOCK_WAIT_RETRIES, SNAPSHOT_GATE_META_KEY, GATE_LOCK_BASENAME, DEFAULT_SNAPSHOT_RETENTION, STAMP_PATTERN;
+var init_snapshot_gate = __esm({
+  "packages/core/src/store/snapshot-gate.ts"() {
+    "use strict";
+    init_lock();
+    init_twin_collapse();
+    SNAPSHOT_DEBOUNCE_MS = 5 * 6e4;
+    SNAPSHOT_LOCK_STALE_MS = 10 * 6e4;
+    SNAPSHOT_LOCK_WAIT_RETRIES = 90;
+    SNAPSHOT_GATE_META_KEY = "sqlite_snapshot_gate";
+    GATE_LOCK_BASENAME = ".snapshot-gate";
+    DEFAULT_SNAPSHOT_RETENTION = {
+      latest: 1,
+      quarterHourly: 3,
+      hourly: 3,
+      daily: 3
+    };
+    STAMP_PATTERN = /-(\d{8})-(\d{6})\.db$/;
+  }
+});
+
 // packages/core/src/store/data-safety-central.ts
 import { eq as eq7 } from "drizzle-orm";
 function inSafetyScope(cwd, operation) {
@@ -41284,7 +41364,8 @@ __export(sqlite_exports, {
   resetDbState: () => resetDbState,
   resolveMigrationsFolder: () => resolveMigrationsFolder,
   schema: () => tasks_schema_exports,
-  seedTasksMeta: () => seedTasksMeta
+  seedTasksMeta: () => seedTasksMeta,
+  worktreeRecoveryRefusal: () => worktreeRecoveryRefusal
 });
 import { copyFileSync as copyFileSync4, existsSync as existsSync20, realpathSync as realpathSync7, renameSync as renameSync7, unlinkSync as unlinkSync4 } from "node:fs";
 import { createRequire as createRequire7 } from "node:module";
@@ -41335,6 +41416,12 @@ function isSameDirectory(a, b) {
     return false;
   }
 }
+function worktreeRecoveryRefusal(dbPath) {
+  const storeCleoDir = dirname14(dbPath);
+  const root = dirname14(storeCleoDir);
+  if (basename8(storeCleoDir) !== ".cleo" || !isGitLinkedCheckout(root)) return null;
+  return `Auto-recovery refused: ${dbPath} lives inside the git worktree ${root}; ${describeWorktreeOwner(root)}. A worktree uses its owning project's store and never receives a restored copy (T12460, T12677).`;
+}
 async function autoRecoverFromBackup(nativeDb, dbPath, cwd) {
   const { openNativeDatabase: openNativeDatabase2 } = await Promise.resolve().then(() => (init_sqlite_native(), sqlite_native_exports));
   const log15 = getLogger("sqlite");
@@ -41344,11 +41431,9 @@ async function autoRecoverFromBackup(nativeDb, dbPath, cwd) {
     const taskCount = countResult?.cnt ?? 0;
     if (taskCount > 0) return false;
     const storeCleoDir = dirname14(dbPath);
-    if (basename8(storeCleoDir) === ".cleo" && isGitLinkedCheckout(dirname14(storeCleoDir))) {
-      log15.warn(
-        { dbPath },
-        "Auto-recovery refused: the empty store lives inside a git worktree (T12460). Worktrees must resolve the parent project store."
-      );
+    const worktreeRefusal = worktreeRecoveryRefusal(dbPath);
+    if (worktreeRefusal !== null) {
+      log15.warn({ dbPath }, worktreeRefusal);
       return false;
     }
     const backups = listSqliteBackups(cwd);