codetrellis 0.0.0-stage → 0.2.0

package/src/backend/services/plan-file-service.js

@@ -0,0 +1,1564 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var plan_file_service_exports = {};
+__export(plan_file_service_exports, {
+  PLACEHOLDER_PLAN_TITLE: () => PLACEHOLDER_PLAN_TITLE,
+  cancelWriteThrough: () => cancelWriteThrough,
+  discoverPlanDirs: () => discoverPlanDirs,
+  exportIfSharedByDefault: () => exportIfSharedByDefault,
+  exportOnFirstTitle: () => exportOnFirstTitle,
+  exportPlan: () => exportPlan,
+  getLinkedPlanDir: () => getLinkedPlanDir,
+  importPlan: () => importPlan,
+  importedPlanRoot: () => importedPlanRoot,
+  makePlanSlug: () => makePlanSlug,
+  pruneOrphanedDirs: () => pruneOrphanedDirs,
+  reconcilePlanState: () => reconcilePlanState,
+  registerDiskHoldSettling: () => registerDiskHoldSettling,
+  scheduleWriteThrough: () => scheduleWriteThrough,
+  setPlanImportedListener: () => setPlanImportedListener,
+  startPlanFileWatcher: () => startPlanFileWatcher,
+  stopPlanFileWatcher: () => stopPlanFileWatcher,
+  unlinkPlan: () => unlinkPlan
+});
+module.exports = __toCommonJS(plan_file_service_exports);
+var _lazy___channel_event_file_service = __toESM(require("./channel-event-file-service"));
+var _lazy____server = __toESM(require("../server"));
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_child_process = require("node:child_process");
+var import_tree_watcher = require("./tree-watcher");
+var import_yaml = require("yaml");
+var planService = __toESM(require("./plan-service"));
+var planPhasesService = __toESM(require("./plan-phases-service"));
+var planDocsService = __toESM(require("./plan-documents-service"));
+var planItemService = __toESM(require("./plan-item-service"));
+var taskAttachmentsService = __toESM(require("./task-attachments-service"));
+var commentService = __toESM(require("./comment-service"));
+var criteriaService = __toESM(require("./criteria-service"));
+var import_database = require("./database");
+var import_skill_arrival_service = require("./skill-arrival-service");
+var import_confined_fs = require("./confined-fs");
+var import_self_write_tracker = require("./self-write-tracker");
+var import_burst = require("../../shared/lib/burst");
+var import_project_config_service = require("./project-config-service");
+var import_plans_home = require("./plans-home");
+var import_checkout_identity = require("./checkout-identity");
+var import_section_workstreams = require("./section-workstreams");
+var import_plan_doc_guard = require("./plan-doc-guard");
+var import_breakpoint_service = require("./breakpoint-service");
+var import_plan_file_refs = require("./plan-file-refs");
+var import_signed_approvals = require("./signed-approvals");
+var import_plan_arrivals = require("./plan-arrivals");
+var import_cloud_files = require("./cloud-files");
+function followTitleIfUncommitted(projectRoot, current, wanted) {
+  try {
+    if (import_node_fs.default.existsSync(wanted)) return current;
+    const from = (0, import_confined_fs.resolveWithin)(projectRoot, import_node_path.default.relative(projectRoot, current), "plan directory");
+    const to = (0, import_confined_fs.resolveWithin)(projectRoot, import_node_path.default.relative(projectRoot, wanted), "plan directory");
+    if (hasCommittedFiles(projectRoot, from)) return current;
+    const files = listFilesRecursive(from);
+    for (const f of files) {
+      (0, import_self_write_tracker.stampSelfWrite)(f);
+      (0, import_self_write_tracker.stampSelfWrite)(import_node_path.default.join(to, import_node_path.default.relative(from, f)));
+    }
+    import_node_fs.default.renameSync(from, to);
+    return to;
+  } catch (err) {
+    console.warn(`[Plans] Kept ${import_node_path.default.basename(current)}: ${err.message}`);
+    return current;
+  }
+}
+function hasCommittedFiles(projectRoot, dir) {
+  if (!import_node_fs.default.existsSync(import_node_path.default.join(projectRoot, ".git"))) return false;
+  const out = (0, import_node_child_process.execFileSync)("git", ["-C", projectRoot, "ls-files", "--", import_node_path.default.relative(projectRoot, dir)], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 5e3
+  });
+  return out.trim().length > 0;
+}
+function listFilesRecursive(dir) {
+  const out = [];
+  for (const entry of import_node_fs.default.readdirSync(dir, { withFileTypes: true })) {
+    const p = import_node_path.default.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listFilesRecursive(p));
+    else if (entry.isFile()) out.push(p);
+  }
+  return out;
+}
+const PLACEHOLDER_PLAN_TITLE = "Untitled plan";
+function isPlaceholderTitle(title) {
+  const t = (title ?? "").trim();
+  return t === "" || t === PLACEHOLDER_PLAN_TITLE;
+}
+function exportOnFirstTitle(planUid, projectRoot, previousTitle) {
+  if (!isPlaceholderTitle(previousTitle)) return false;
+  if (getLinkedPlanDir(planUid, projectRoot)) return false;
+  return exportIfSharedByDefault(planUid, projectRoot);
+}
+function exportIfSharedByDefault(planUid, projectRoot) {
+  try {
+    if ((0, import_project_config_service.getEffectiveDefaultVisibility)(projectRoot) !== "shared") return false;
+    if (isPlaceholderTitle(planService.getPlan(planUid)?.title)) return false;
+    exportPlan(planUid, projectRoot);
+    return true;
+  } catch (err) {
+    console.warn(`[Plans] Could not write new plan ${planUid} to the project:`, err);
+    return false;
+  }
+}
+function exportPlan(planUid, projectRoot) {
+  const plan = planService.getPlan(planUid);
+  if (!plan) throw new Error(`Plan ${planUid} not found`);
+  const home = (0, import_plans_home.plansHome)(projectRoot);
+  if (!home) throw new import_plans_home.PlansFolderError((0, import_plans_home.getPlansFolder)(projectRoot).says);
+  const wanted = import_node_path.default.join(home, ".codetrellis", "plans", makePlanSlug(plan));
+  let planDir = getLinkedPlanDir(planUid, projectRoot);
+  if (planDir && planDir !== wanted) planDir = followTitleIfUncommitted(home, planDir, wanted);
+  planDir ??= wanted;
+  ensureDir(planDir);
+  const v2Items = planItemService.listAllItems(planUid);
+  if (v2Items.length > 0) {
+    return exportPlanV2(plan, planDir, v2Items, home);
+  }
+  return exportPlanV1(plan, planDir, planUid, home);
+}
+function exportPlanV1(plan, planDir, planUid, projectRoot) {
+  const phases = planPhasesService.listPhases(planUid);
+  const tasks = plan.tasks;
+  const docs = planDocsService.listPlanDocuments(planUid);
+  ensureDir(import_node_path.default.join(planDir, "phases"));
+  ensureDir(import_node_path.default.join(planDir, "tasks"));
+  ensureDir(import_node_path.default.join(planDir, "docs"));
+  const files = [];
+  const planFile = import_node_path.default.join(planDir, "plan.yaml");
+  writeFileAtomic(planFile, (0, import_yaml.stringify)(serializePlan(plan)));
+  files.push(planFile);
+  for (const phase of phases) {
+    const fname = `${pad2(phase.phaseNumber)}-${slugify(phase.title) || "phase"}.yaml`;
+    const fpath = import_node_path.default.join(planDir, "phases", fname);
+    writeFileAtomic(fpath, (0, import_yaml.stringify)(serializePhase(phase)));
+    files.push(fpath);
+  }
+  for (const task of tasks) {
+    const fname = `${pad3(task.sortOrder)}-${slugify(task.description) || "task"}.yaml`;
+    const fpath = import_node_path.default.join(planDir, "tasks", fname);
+    const attachments = taskAttachmentsService.listTaskAttachments(task.uid);
+    const comments = commentService.listCommentsFlat(task.uid);
+    writeFileAtomic(fpath, (0, import_yaml.stringify)(serializeTask(task, attachments, comments)));
+    files.push(fpath);
+  }
+  for (const doc of docs) {
+    const orderPrefix = doc.orderHint ? `${doc.orderHint}-` : "";
+    const fname = `${orderPrefix}${slugify(doc.title) || doc.docType}.md`;
+    const fpath = import_node_path.default.join(planDir, "docs", fname);
+    writeFileAtomic(fpath, serializeDoc(doc));
+    files.push(fpath);
+  }
+  ensureCodetrellisGitignore(import_node_path.default.join(projectRoot, ".codetrellis"));
+  return { planDir, files };
+}
+function exportPlanV2(plan, planDir, _allItems, projectRoot) {
+  const files = [];
+  const planFile = import_node_path.default.join(planDir, "plan.yaml");
+  writeFileAtomic(planFile, (0, import_yaml.stringify)(serializePlan(plan, 2)));
+  files.push(planFile);
+  const exportItems = planItemService.listItemsForExport(plan.uid);
+  const childrenOf = /* @__PURE__ */ new Map();
+  for (const { item, exportParentUid } of exportItems) {
+    const onDisk = { ...item, parentUid: exportParentUid };
+    const key = exportParentUid;
+    const list = childrenOf.get(key) ?? [];
+    list.push(onDisk);
+    childrenOf.set(key, list);
+  }
+  for (const list of childrenOf.values()) {
+    list.sort((a, b) => a.sortOrder - b.sortOrder || a.createdAt - b.createdAt);
+  }
+  const itemsDir = import_node_path.default.join(planDir, "items");
+  const preExisting = /* @__PURE__ */ new Set();
+  if (import_node_fs.default.existsSync(itemsDir)) {
+    collectYamlFiles(itemsDir, preExisting);
+  }
+  ensureDir(itemsDir);
+  const roots = childrenOf.get(null) ?? [];
+  writeItemChildren(roots, itemsDir, childrenOf, files);
+  const writtenSet = new Set(files);
+  for (const stale of preExisting) {
+    if (writtenSet.has(stale)) continue;
+    if ((0, import_cloud_files.isPlaceholder)(stale)) continue;
+    (0, import_self_write_tracker.stampSelfWrite)(stale);
+    try {
+      import_node_fs.default.unlinkSync(stale);
+    } catch {
+    }
+  }
+  pruneEmptyDirs(itemsDir);
+  ensureCodetrellisGitignore(import_node_path.default.join(projectRoot, ".codetrellis"));
+  return { planDir, files };
+}
+function collectYamlFiles(dir, out) {
+  for (const entry of import_node_fs.default.readdirSync(dir)) {
+    const full = import_node_path.default.join(dir, entry);
+    let stat;
+    try {
+      stat = import_node_fs.default.statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      collectYamlFiles(full, out);
+    } else if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+      out.add(full);
+    }
+  }
+}
+function pruneEmptyDirs(dir) {
+  if (!import_node_fs.default.existsSync(dir)) return;
+  for (const entry of import_node_fs.default.readdirSync(dir)) {
+    const full = import_node_path.default.join(dir, entry);
+    let stat;
+    try {
+      stat = import_node_fs.default.statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      pruneEmptyDirs(full);
+      try {
+        if (import_node_fs.default.readdirSync(full).length === 0) import_node_fs.default.rmdirSync(full);
+      } catch {
+      }
+    }
+  }
+}
+function writeItemChildren(items, parentDir, childrenOf, files) {
+  for (const item of items) {
+    const children = childrenOf.get(item.uid) ?? [];
+    const slug = slugify(item.title) || item.kind;
+    const prefix = pad3(item.sortOrder);
+    if (children.length === 0) {
+      const fname = `${prefix}-${slug}.yaml`;
+      const fpath = import_node_path.default.join(parentDir, fname);
+      writeFileAtomic(fpath, (0, import_yaml.stringify)(serializeItem(item)));
+      files.push(fpath);
+    } else {
+      const dirName = `${prefix}-${slug}`;
+      const dirPath = import_node_path.default.join(parentDir, dirName);
+      ensureDir(dirPath);
+      const selfPath = import_node_path.default.join(dirPath, "_self.yaml");
+      writeFileAtomic(selfPath, (0, import_yaml.stringify)(serializeItem(item)));
+      files.push(selfPath);
+      writeItemChildren(children, dirPath, childrenOf, files);
+    }
+  }
+}
+function readPlanFile(planDir, file) {
+  if ((0, import_cloud_files.isPlaceholder)(import_node_path.default.resolve(file))) throw new import_cloud_files.NotOnDeviceError(import_node_path.default.relative(planDir, file) || "plan.yaml");
+  return (0, import_confined_fs.readTextWithin)(planDir, import_node_path.default.relative(planDir, file), "plan file");
+}
+function importPlan(planDirOrPlanYaml) {
+  importDepth++;
+  try {
+    return importPlanInternal(planDirOrPlanYaml);
+  } finally {
+    importDepth--;
+  }
+}
+let onlyOutsideChanges = false;
+function oursUnchanged(file) {
+  return onlyOutsideChanges && (0, import_self_write_tracker.wasJustWrittenByUs)(file);
+}
+function importOutsideChanges(planDir) {
+  onlyOutsideChanges = true;
+  try {
+    return importPlan(planDir);
+  } finally {
+    onlyOutsideChanges = false;
+  }
+}
+function importPlanInternal(planDirOrPlanYaml) {
+  let planDir = planDirOrPlanYaml;
+  if (planDir.endsWith("plan.yaml")) {
+    planDir = import_node_path.default.dirname(planDir);
+  }
+  const planFile = import_node_path.default.join(planDir, "plan.yaml");
+  if (!import_node_fs.default.existsSync(planFile)) {
+    throw new Error(`Not a plan directory: ${planDir} (no plan.yaml)`);
+  }
+  const warnings = [];
+  const planRaw = (0, import_yaml.parse)(readPlanFile(planDir, planFile));
+  if (!planRaw || typeof planRaw !== "object" || !planRaw.uid || !planRaw.title) {
+    throw new Error(`Invalid plan.yaml at ${planFile} \u2014 missing uid or title`);
+  }
+  const planUid = planRaw.uid;
+  const held = planService.getPlan(planUid);
+  const checkout = checkoutOfPlanDir(planDir);
+  const sitsIn = checkout ? (0, import_plans_home.projectOfPlansHome)(checkout) ?? checkout : null;
+  if (held && sitsIn && (0, import_checkout_identity.heldByAnotherCheckout)(held.projectPath, sitsIn)) {
+    return {
+      plan: held,
+      phases: [],
+      tasks: [],
+      docs: [],
+      items: [],
+      version: planRaw.version === 2 || import_node_fs.default.existsSync(import_node_path.default.join(planDir, "items")) ? 2 : 1,
+      warnings: [`Not imported: this plan is held by ${held.projectPath}, another checkout of this repository. This copy's differences are that checkout's workstream changes.`]
+    };
+  }
+  const projectPath = importedPlanRoot(planUid, planDir, planRaw.projectPath);
+  const arriving = !planService.getPlan(planUid);
+  const skipOurs = (file) => !arriving && oursUnchanged(file);
+  if (!skipOurs(planFile)) {
+    upsertPlan(planUid, planRaw, projectPath);
+    if (arriving) (0, import_plan_arrivals.recordPlanArrival)(planUid, planFile);
+    else (0, import_plan_arrivals.completePlanArrival)(planUid, planFile);
+    if (planRaw.refs !== void 0) (0, import_plan_file_refs.importPlanRefs)(planUid, planRaw.refs);
+  }
+  const isV2 = planRaw.version === 2 || import_node_fs.default.existsSync(import_node_path.default.join(planDir, "items"));
+  const result = isV2 ? importPlanV2(planDir, planUid, warnings, skipOurs) : importPlanV1(planDir, planUid, warnings, skipOurs);
+  try {
+    const { discoverChannelEventFiles, importChannelEvent } = _lazy___channel_event_file_service;
+    for (const filePath of discoverChannelEventFiles(planDir)) {
+      try {
+        importChannelEvent(filePath, planDir);
+      } catch (err) {
+        warnings.push(`Failed to import channel event ${import_node_path.default.basename(filePath)}: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+  } catch {
+  }
+  try {
+    const checked = (0, import_signed_approvals.importApprovals)(planDir, planUid, projectPath, {
+      criterion: (uid) => {
+        const c = criteriaService.getCriterion(uid);
+        const item = c ? planItemService.getItem(c.itemUid) : null;
+        return c && item ? { text: c.text, itemUid: c.itemUid, planUid: item.planUid } : null;
+      },
+      addSignoff: (input) => criteriaService.addVerifiedSignoff(input)
+    });
+    if (checked.unverified) warnings.push(`${checked.unverified} approval record${checked.unverified === 1 ? "" : "s"} could not be verified and count for nothing.`);
+  } catch (err) {
+    warnings.push(`Approval records were not read: ${err instanceof Error ? err.message : err}`);
+  }
+  if (planImportedListener) {
+    try {
+      planImportedListener(planUid, projectPath);
+    } catch (err) {
+      warnings.push(`Task-state records were not read: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  return result;
+}
+let planImportedListener = null;
+function setPlanImportedListener(fn) {
+  planImportedListener = fn;
+}
+function importPlanV1(planDir, planUid, warnings, skipOurs) {
+  const phaseDir = import_node_path.default.join(planDir, "phases");
+  if (import_node_fs.default.existsSync(phaseDir)) {
+    for (const fname of import_node_fs.default.readdirSync(phaseDir)) {
+      if (!fname.endsWith(".yaml") && !fname.endsWith(".yml")) continue;
+      const fpath = import_node_path.default.join(phaseDir, fname);
+      if (skipOurs(fpath)) continue;
+      try {
+        const raw = (0, import_yaml.parse)(readPlanFile(planDir, fpath));
+        if (!raw?.uid) {
+          warnings.push(`Skipping ${fpath} \u2014 missing uid`);
+          continue;
+        }
+        upsertPhase(planUid, raw);
+      } catch (err) {
+        warnings.push(`Failed to import phase ${fname}: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+  }
+  const taskDir = import_node_path.default.join(planDir, "tasks");
+  if (import_node_fs.default.existsSync(taskDir)) {
+    for (const fname of import_node_fs.default.readdirSync(taskDir)) {
+      if (!fname.endsWith(".yaml") && !fname.endsWith(".yml")) continue;
+      const fpath = import_node_path.default.join(taskDir, fname);
+      if (skipOurs(fpath)) continue;
+      try {
+        const raw = (0, import_yaml.parse)(readPlanFile(planDir, fpath));
+        if (!raw?.uid) {
+          warnings.push(`Skipping ${fpath} \u2014 missing uid`);
+          continue;
+        }
+        upsertTask(planUid, raw);
+      } catch (err) {
+        warnings.push(`Failed to import task ${fname}: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+  }
+  const docDir = import_node_path.default.join(planDir, "docs");
+  if (import_node_fs.default.existsSync(docDir)) {
+    for (const fname of import_node_fs.default.readdirSync(docDir)) {
+      if (!fname.endsWith(".md")) continue;
+      const fpath = import_node_path.default.join(docDir, fname);
+      if (skipOurs(fpath)) continue;
+      try {
+        const { meta, body } = parseFrontMatter(readPlanFile(planDir, fpath));
+        if (!meta.uid) {
+          warnings.push(`Skipping ${fpath} \u2014 missing uid in front-matter`);
+          continue;
+        }
+        upsertDoc(planUid, meta, body);
+      } catch (err) {
+        warnings.push(`Failed to import doc ${fname}: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+  }
+  const updatedPlan = planService.getPlan(planUid);
+  if (!updatedPlan) throw new Error(`Plan ${planUid} disappeared after import`);
+  return {
+    plan: updatedPlan,
+    phases: planPhasesService.listPhases(planUid),
+    tasks: updatedPlan.tasks,
+    docs: planDocsService.listPlanDocuments(planUid),
+    items: [],
+    version: 1,
+    warnings
+  };
+}
+function importPlanV2(planDir, planUid, warnings, skipOurs) {
+  const itemsDir = import_node_path.default.join(planDir, "items");
+  const importedItems = [];
+  if (import_node_fs.default.existsSync(itemsDir)) {
+    importItemsFromDir(planDir, itemsDir, planUid, null, warnings, importedItems, skipOurs);
+  }
+  const updatedPlan = planService.getPlan(planUid);
+  if (!updatedPlan) throw new Error(`Plan ${planUid} disappeared after import`);
+  return {
+    plan: updatedPlan,
+    phases: [],
+    tasks: [],
+    docs: [],
+    items: importedItems,
+    version: 2,
+    warnings
+  };
+}
+function importItemsFromDir(planDir, dir, planUid, parentUid, warnings, collected, skipOurs = () => false) {
+  const entries = import_node_fs.default.readdirSync(dir).sort();
+  for (const entry of entries) {
+    if (entry === "_self.yaml") continue;
+    const fullPath = import_node_path.default.join(dir, entry);
+    try {
+      const stat = import_node_fs.default.lstatSync(fullPath);
+      if (stat.isFile() && (entry.endsWith(".yaml") || entry.endsWith(".yml"))) {
+        if ((0, import_cloud_files.isPlaceholder)(fullPath)) {
+          warnings.push(`${import_node_path.default.relative(planDir, fullPath)} is not on this device`);
+          continue;
+        }
+        const raw = (0, import_yaml.parse)(readPlanFile(planDir, fullPath));
+        if (!raw?.uid) {
+          warnings.push(`Skipping ${fullPath} \u2014 missing uid`);
+          continue;
+        }
+        const item = skipOurs(fullPath) ? planItemService.getItem(raw.uid) : upsertItem(planUid, parentUid, raw, warnings, fullPath);
+        if (item) collected.push(item);
+      } else if (stat.isDirectory()) {
+        const selfPath = import_node_path.default.join(fullPath, "_self.yaml");
+        if (!import_node_fs.default.existsSync(selfPath)) {
+          warnings.push(`Skipping directory ${fullPath} \u2014 no _self.yaml`);
+          continue;
+        }
+        if ((0, import_cloud_files.isPlaceholder)(selfPath)) {
+          warnings.push(`${import_node_path.default.relative(planDir, selfPath)} is not on this device`);
+          continue;
+        }
+        const raw = (0, import_yaml.parse)(readPlanFile(planDir, selfPath));
+        if (!raw?.uid) {
+          warnings.push(`Skipping ${selfPath} \u2014 missing uid`);
+          continue;
+        }
+        const item = skipOurs(selfPath) ? planItemService.getItem(raw.uid) : upsertItem(planUid, parentUid, raw, warnings, selfPath);
+        if (item) {
+          collected.push(item);
+          importItemsFromDir(planDir, fullPath, planUid, item.uid, warnings, collected, skipOurs);
+        }
+      }
+    } catch (err) {
+      warnings.push(`Failed to import ${entry}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+}
+function upsertItem(planUid, parentUid, raw, warnings, file) {
+  const uid = String(raw.uid);
+  const existing = planItemService.getItem(uid);
+  const skillsBefore = existing?.skills ?? [];
+  const kind = raw.kind === "object" ? "object" : "action";
+  const now = Date.now();
+  if (existing) {
+    planItemService.withoutStateRecords(() => planItemService.updateItem(uid, {
+      title: typeof raw.title === "string" ? raw.title : void 0,
+      body: typeof raw.body === "string" ? raw.body : void 0,
+      template: raw.template ?? null,
+      // State is no longer written (C2.4b). A file from before that still
+      // carries it is read; a file without it leaves this machine's alone.
+      status: isTaskStatus(raw.status) ? raw.status : void 0,
+      assignee: "assignee" in raw ? raw.assignee ?? null : void 0,
+      assigneeType: "assignee" in raw ? raw.assigneeType ?? null : void 0,
+      assigneeModel: "assignee" in raw ? raw.assigneeModel ?? null : void 0,
+      progressPercent: typeof raw.progressPercent === "number" ? raw.progressPercent : void 0,
+      blockedReason: "blockedReason" in raw ? raw.blockedReason ?? null : void 0,
+      scopePath: raw.scopePath ?? null,
+      fileSpecs: Array.isArray(raw.fileSpecs) ? raw.fileSpecs : void 0,
+      symbolSpecs: Array.isArray(raw.symbolSpecs) ? raw.symbolSpecs : void 0,
+      newConnections: Array.isArray(raw.newConnections) ? raw.newConnections : void 0,
+      removedConnections: Array.isArray(raw.removedConnections) ? raw.removedConnections : void 0,
+      dependencies: Array.isArray(raw.dependencies) ? raw.dependencies : void 0,
+      skills: Array.isArray(raw.skills) ? raw.skills : void 0,
+      skillsMode: raw.skillsMode ?? void 0,
+      claimPolicy: raw.claimPolicy ?? void 0,
+      claimPolicyMode: raw.claimPolicyMode ?? void 0,
+      // Phase 32 C5.1 — a branch name, or nothing: a file is anyone's text.
+      workstream: (0, import_section_workstreams.cleanBranch)(raw.workstream),
+      executionConfig: raw.executionConfig ?? void 0,
+      executionConfigMode: raw.executionConfigMode ?? void 0,
+      constraints: raw.constraints ?? void 0,
+      constraintsMode: raw.constraintsMode ?? void 0,
+      requiresApproval: typeof raw.requiresApproval === "boolean" ? raw.requiresApproval : void 0,
+      // Phase 3.2 — per-item sharing
+      visibility: raw.visibility === "local" ? "local" : "shared",
+      overrideParentVisibility: raw.overrideParentVisibility === true,
+      parentUid,
+      author: "file-import",
+      authorType: "system"
+    }));
+  } else {
+    planItemService.createItem({
+      uid,
+      planUid,
+      parentUid,
+      sortOrder: typeof raw.sortOrder === "number" ? raw.sortOrder : void 0,
+      kind,
+      title: String(raw.title ?? ""),
+      body: typeof raw.body === "string" ? raw.body : "",
+      template: raw.template ?? null,
+      status: isTaskStatus(raw.status) ? raw.status : "pending",
+      assignee: raw.assignee ?? null,
+      assigneeType: raw.assigneeType ?? null,
+      assigneeModel: raw.assigneeModel ?? null,
+      progressPercent: typeof raw.progressPercent === "number" ? raw.progressPercent : null,
+      blockedReason: raw.blockedReason ?? null,
+      scopePath: raw.scopePath ?? null,
+      fileSpecs: Array.isArray(raw.fileSpecs) ? raw.fileSpecs : [],
+      symbolSpecs: Array.isArray(raw.symbolSpecs) ? raw.symbolSpecs : [],
+      newConnections: Array.isArray(raw.newConnections) ? raw.newConnections : [],
+      removedConnections: Array.isArray(raw.removedConnections) ? raw.removedConnections : [],
+      dependencies: Array.isArray(raw.dependencies) ? raw.dependencies : [],
+      skills: Array.isArray(raw.skills) ? raw.skills : [],
+      skillsMode: raw.skillsMode ?? "inherit",
+      claimPolicy: raw.claimPolicy ?? null,
+      claimPolicyMode: raw.claimPolicyMode ?? "inherit",
+      workstream: (0, import_section_workstreams.cleanBranch)(raw.workstream),
+      executionConfig: raw.executionConfig ?? null,
+      executionConfigMode: raw.executionConfigMode ?? "inherit",
+      constraints: raw.constraints ?? null,
+      constraintsMode: raw.constraintsMode ?? "inherit",
+      requiresApproval: raw.requiresApproval === true,
+      // Phase 3.2 — per-item sharing
+      visibility: raw.visibility === "local" ? "local" : "shared",
+      overrideParentVisibility: raw.overrideParentVisibility === true,
+      author: String(raw.author ?? "human"),
+      authorType: String(raw.authorType ?? "human"),
+      createdAt: toEpoch(raw.createdAt) ?? now,
+      updatedAt: toEpoch(raw.updatedAt) ?? now
+    });
+  }
+  const item = planItemService.getItem(uid);
+  if (Array.isArray(raw.attachments)) {
+    for (const a of raw.attachments) {
+      if (!a?.uid || !a?.kind || a?.value == null) continue;
+      const valid = taskAttachmentsService.validateImportedAttachment(a, uid);
+      if ("refused" in valid) {
+        warnings.push(`Skipped attachment ${String(a.uid)} on item ${uid}: ${valid.refused}`);
+        continue;
+      }
+      const stored = taskAttachmentsService.upsertAttachment({
+        uid: String(a.uid),
+        targetType: "item",
+        targetUid: uid,
+        kind: valid.kind,
+        value: valid.value,
+        label: typeof a.label === "string" ? a.label : null,
+        contentType: valid.contentType,
+        author: String(a.author ?? "human"),
+        authorType: String(a.authorType ?? "human"),
+        createdAt: toEpoch(a.createdAt) ?? Date.now(),
+        role: typeof a.role === "string" ? a.role : null
+      });
+      if (!stored) warnings.push(`Skipped attachment ${String(a.uid)}: it belongs to another item`);
+    }
+  }
+  if (item && Array.isArray(raw.criteria)) {
+    criteriaService.importCriteria(item.uid, raw.criteria);
+  }
+  if (item && raw.refs !== void 0) (0, import_plan_file_refs.importItemRefs)(item.uid, raw.refs);
+  if (Array.isArray(raw.comments)) {
+    for (const c of raw.comments) {
+      if (!c?.uid || !c?.body) continue;
+      upsertComment({
+        uid: String(c.uid),
+        targetType: "item",
+        targetUid: uid,
+        parentUid: c.parentUid ?? null,
+        author: String(c.author ?? "human"),
+        authorType: String(c.authorType ?? "human"),
+        body: String(c.body),
+        commentType: c.commentType ?? "comment",
+        kind: c.kind ?? null,
+        source: c.source ?? null,
+        metadata: c.metadata ?? null,
+        createdAt: toEpoch(c.createdAt) ?? Date.now()
+      });
+    }
+  }
+  if (item) {
+    try {
+      (0, import_skill_arrival_service.noteArrivals)({ itemUid: item.uid, before: skillsBefore, after: item.skills ?? [], file });
+    } catch {
+    }
+  }
+  return item;
+}
+function discoverPlanDirs(projectRoot) {
+  const home = (0, import_plans_home.plansHome)(projectRoot);
+  if (!home) return [];
+  const root = import_node_path.default.join(home, ".codetrellis", "plans");
+  if (!import_node_fs.default.existsSync(root)) return [];
+  return import_node_fs.default.readdirSync(root).map((name) => import_node_path.default.join(root, name)).filter((p) => {
+    try {
+      return import_node_fs.default.lstatSync(p).isDirectory() && import_node_fs.default.existsSync(import_node_path.default.join(p, "plan.yaml")) && !(0, import_cloud_files.isPlaceholder)(import_node_path.default.join(p, "plan.yaml"));
+    } catch {
+      return false;
+    }
+  });
+}
+function getLinkedPlanDir(planUid, projectRoot) {
+  const plan = planService.getPlan(planUid);
+  if (!plan) return null;
+  const home = (0, import_plans_home.plansHome)(projectRoot);
+  if (!home) return null;
+  const plansRoot = import_node_path.default.join(home, ".codetrellis", "plans");
+  const dir = import_node_path.default.join(plansRoot, makePlanSlug(plan));
+  if (import_node_fs.default.existsSync(import_node_path.default.join(dir, "plan.yaml"))) return dir;
+  const suffix = `-${plan.uid.split("-")[0]}`;
+  let entries;
+  try {
+    entries = import_node_fs.default.readdirSync(plansRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.endsWith(suffix)) continue;
+    const candidate = import_node_path.default.join(plansRoot, entry.name);
+    try {
+      const raw = (0, import_yaml.parse)((0, import_confined_fs.readTextWithin)(candidate, "plan.yaml", "plan file"));
+      if (raw?.uid === plan.uid) return candidate;
+    } catch {
+    }
+  }
+  return null;
+}
+function unlinkPlan(planUid, projectRoot) {
+  cancelWriteThrough(planUid);
+  const dir = getLinkedPlanDir(planUid, projectRoot);
+  if (!dir) return { removed: false, planDir: null };
+  import_node_fs.default.rmSync(dir, { recursive: true, force: true });
+  return { removed: true, planDir: dir };
+}
+function reconcilePlanState(projectRoot) {
+  const diskDirs = discoverPlanDirs(projectRoot);
+  const totalDisk = diskDirs.length;
+  const dbPlans = planService.listPlans(projectRoot);
+  const totalDb = dbPlans.length;
+  const dbUidPrefixes = /* @__PURE__ */ new Set();
+  const dbUidFull = /* @__PURE__ */ new Set();
+  for (const p of dbPlans) {
+    dbUidFull.add(p.uid);
+    dbUidPrefixes.add(p.uid.split("-")[0]);
+  }
+  const orphanedOnDisk = [];
+  for (const dirPath of diskDirs) {
+    const dirName = import_node_path.default.basename(dirPath);
+    const parts = dirName.split("-");
+    const uidPrefix = parts.length > 0 ? parts[parts.length - 1] : null;
+    if (uidPrefix && dbUidPrefixes.has(uidPrefix)) continue;
+    let title = null;
+    try {
+      const yaml = import_node_fs.default.readFileSync(import_node_path.default.join(dirPath, "plan.yaml"), "utf-8");
+      const parsed = (0, import_yaml.parse)(yaml);
+      title = parsed?.title ?? null;
+    } catch {
+    }
+    orphanedOnDisk.push({ dirPath, dirName, uidPrefix, title });
+  }
+  const diskUidPrefixes = /* @__PURE__ */ new Set();
+  for (const dirPath of diskDirs) {
+    const dirName = import_node_path.default.basename(dirPath);
+    const parts = dirName.split("-");
+    if (parts.length > 0) diskUidPrefixes.add(parts[parts.length - 1]);
+  }
+  const orphanedInDb = [];
+  for (const p of dbPlans) {
+    const prefix = p.uid.split("-")[0];
+    if (!diskUidPrefixes.has(prefix)) {
+      orphanedInDb.push({ uid: p.uid, title: p.title, status: p.status });
+    }
+  }
+  return { orphanedOnDisk, orphanedInDb, totalDisk, totalDb };
+}
+function pruneOrphanedDirs(projectRoot, dirPaths) {
+  const orphans = new Set(reconcilePlanState(projectRoot).orphanedOnDisk.map((o) => o.dirPath));
+  const home = (0, import_plans_home.plansHome)(projectRoot);
+  if (!home) return { removed: 0, skipped: [...dirPaths] };
+  const plansRoot = import_node_path.default.join(home, ".codetrellis", "plans");
+  let removed = 0;
+  const skipped = [];
+  for (const dir of dirPaths) {
+    try {
+      if (typeof dir !== "string" || !orphans.has(dir)) {
+        skipped.push(String(dir));
+        continue;
+      }
+      (0, import_confined_fs.resolveWithin)(plansRoot, import_node_path.default.basename(dir), "plan directory");
+      if (import_node_path.default.dirname(dir) !== plansRoot || !import_node_fs.default.lstatSync(dir).isDirectory()) {
+        skipped.push(dir);
+        continue;
+      }
+      import_node_fs.default.rmSync(dir, { recursive: true, force: true });
+      removed++;
+    } catch {
+      skipped.push(String(dir));
+    }
+  }
+  return { removed, skipped };
+}
+const writeThroughTimers = /* @__PURE__ */ new Map();
+const WRITE_THROUGH_DEBOUNCE_MS = 200;
+let importDepth = 0;
+function cancelWriteThrough(planUid) {
+  const pending = writeThroughTimers.get(planUid);
+  if (pending) clearTimeout(pending);
+  writeThroughTimers.delete(planUid);
+}
+function scheduleWriteThrough(planUid, projectRoot) {
+  if (importDepth > 0) return;
+  const plan = planService.getPlan(planUid);
+  if (!plan) return;
+  const root = projectRoot ?? plan.projectPath;
+  if (!root) return;
+  if (!getLinkedPlanDir(planUid, root)) return;
+  const existing = writeThroughTimers.get(planUid);
+  if (existing) clearTimeout(existing);
+  writeThroughTimers.set(planUid, setTimeout(() => {
+    writeThroughTimers.delete(planUid);
+    const linkedDir = getLinkedPlanDir(planUid, root);
+    if (!linkedDir) return;
+    flushPlanImports(linkedDir);
+    try {
+      const result = exportPlan(planUid, root);
+      try {
+        const { broadcast } = _lazy____server;
+        broadcast("plan-exported", { planUid, planDir: result.planDir, source: "auto-sync", files: result.files.length });
+      } catch {
+      }
+    } catch (err) {
+      console.warn(`[Auto-sync] Failed to export plan ${planUid}:`, err);
+    }
+  }, WRITE_THROUGH_DEBOUNCE_MS));
+}
+const watchersByProject = /* @__PURE__ */ new Map();
+const watcherReady = /* @__PURE__ */ new Map();
+const PLAN_WATCHER_READY_TIMEOUT_MS = 1e4;
+const NEW_FOLDER_SWEEP_MS = 500;
+const PLAN_IMPORT_QUIET_MS = 250;
+const PLAN_IMPORT_MAX_WAIT_MS = 1e3;
+const importBursts = /* @__PURE__ */ new Map();
+const realDir = (p) => {
+  try {
+    return import_node_fs.default.realpathSync.native(p);
+  } catch {
+    return import_node_path.default.resolve(p);
+  }
+};
+function flushPlanImports(planDir) {
+  const want = realDir(planDir);
+  for (const b of importBursts.values()) {
+    for (const key of b.pending()) if (key === planDir || realDir(key) === want) b.flush(key);
+  }
+}
+function startPlanFileWatcher(projectRoot) {
+  if (watchersByProject.has(projectRoot)) {
+    return watcherReady.get(projectRoot) ?? Promise.resolve();
+  }
+  const home = (0, import_plans_home.plansHome)(projectRoot);
+  if (!home) return Promise.resolve();
+  const plansRoot = import_node_path.default.join(home, ".codetrellis", "plans");
+  try {
+    import_node_fs.default.mkdirSync(plansRoot, { recursive: true });
+  } catch (err) {
+    console.warn("[Auto-sync] Could not pre-create plans dir:", err);
+  }
+  const imports = (0, import_burst.burst)((planDir, files) => {
+    if (watchersByProject.get(projectRoot) !== watcher) return;
+    try {
+      const result = importOutsideChanges(planDir);
+      try {
+        const { broadcast } = _lazy____server;
+        broadcast("plan-imported", {
+          planUid: result.plan.uid,
+          source: "file-watcher",
+          planDir,
+          files: files.length,
+          warnings: result.warnings
+        });
+      } catch {
+      }
+    } catch (err) {
+      console.warn(`[Auto-sync] Failed to re-import ${planDir}:`, err);
+    }
+  }, { quietMs: PLAN_IMPORT_QUIET_MS, maxWaitMs: PLAN_IMPORT_MAX_WAIT_MS });
+  importBursts.set(projectRoot, imports);
+  const watcher = (0, import_tree_watcher.watchTree)(plansRoot, {
+    ignoreInitial: true,
+    persistent: true,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+    depth: 10
+    // V2 items/ tree can nest deeply
+  });
+  const handledAt = /* @__PURE__ */ new Map();
+  const sweepNewFolder = (dir, seenAt) => {
+    setTimeout(() => {
+      if (watchersByProject.get(projectRoot) !== watcher) return;
+      const missed = /* @__PURE__ */ new Map();
+      const walk = (d, depth) => {
+        if (depth > 10) return;
+        let entries;
+        try {
+          entries = import_node_fs.default.readdirSync(d, { withFileTypes: true });
+        } catch {
+          return;
+        }
+        for (const e of entries) {
+          const p = import_node_path.default.join(d, e.name);
+          if (e.isDirectory()) {
+            walk(p, depth + 1);
+            continue;
+          }
+          if (!e.isFile()) continue;
+          if ((handledAt.get(p) ?? 0) >= seenAt || (0, import_self_write_tracker.wasJustWrittenByUs)(p)) continue;
+          const planDir = findContainingPlanDir(p, plansRoot);
+          if (!planDir) continue;
+          (missed.get(planDir) ?? missed.set(planDir, []).get(planDir)).push(p);
+        }
+      };
+      walk(dir, 0);
+      const { isChannelEventFile } = _lazy___channel_event_file_service;
+      for (const files of missed.values()) {
+        const other = files.find((f) => !isChannelEventFile(f));
+        for (const f of other ? [other] : files) handle("add", f);
+      }
+    }, NEW_FOLDER_SWEEP_MS);
+  };
+  const handle = (event, filePath) => {
+    if (event !== "add" && event !== "change" && event !== "unlink") return;
+    if (!filePath) return;
+    if ((0, import_self_write_tracker.wasJustWrittenByUs)(filePath)) return;
+    if (handledAt.size > 5e3) handledAt.clear();
+    handledAt.set(filePath, Date.now());
+    const planDir = findContainingPlanDir(filePath, plansRoot);
+    if (!planDir) return;
+    if (filePath.endsWith(".yaml") || filePath.endsWith(".md")) {
+      try {
+        const content = import_node_fs.default.readFileSync(filePath, "utf-8");
+        if (hasGitConflictMarkers(content)) {
+          try {
+            const { broadcast } = _lazy____server;
+            broadcast("plan-file-conflict", { filePath, planDir });
+          } catch {
+          }
+          return;
+        }
+      } catch {
+      }
+    }
+    try {
+      const { isChannelEventFile, importChannelEvent } = _lazy___channel_event_file_service;
+      if (isChannelEventFile(filePath)) {
+        if (event === "unlink") return;
+        const imported = importChannelEvent(filePath, planDir);
+        if (imported) {
+          try {
+            const { broadcast } = _lazy____server;
+            broadcast("channel-event-imported", {
+              uid: imported.uid,
+              planUid: imported.planUid,
+              eventType: imported.eventType,
+              source: "file-watcher"
+            });
+          } catch {
+          }
+        }
+        return;
+      }
+    } catch (err) {
+      console.warn(`[Auto-sync] Channel-event import failed for ${filePath}:`, err);
+      return;
+    }
+    imports.add(planDir, filePath);
+  };
+  watcher.on("all", (event, filePath) => {
+    if (event === "addDir") {
+      if (filePath && filePath !== plansRoot) sweepNewFolder(filePath, Date.now());
+      return;
+    }
+    handle(event, filePath);
+  });
+  watcher.on("error", (err) => {
+    console.warn("[Auto-sync] Plan file watcher error:", err);
+  });
+  watchersByProject.set(projectRoot, watcher);
+  const ready = new Promise((resolve) => {
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(guard);
+      resolve();
+    };
+    const guard = setTimeout(() => {
+      console.warn(`[Auto-sync] Plan watcher still starting after ${PLAN_WATCHER_READY_TIMEOUT_MS}ms \u2014 continuing`);
+      done();
+    }, PLAN_WATCHER_READY_TIMEOUT_MS);
+    guard.unref?.();
+    watcher.once("ready", done);
+  });
+  watcherReady.set(projectRoot, ready);
+  console.log(`[Auto-sync] Watching ${plansRoot}`);
+  return ready;
+}
+function stopPlanFileWatcher(projectRoot) {
+  const w = watchersByProject.get(projectRoot);
+  if (w) {
+    w.close().catch(() => {
+    });
+    watchersByProject.delete(projectRoot);
+    watcherReady.delete(projectRoot);
+  }
+  importBursts.get(projectRoot)?.cancel();
+  importBursts.delete(projectRoot);
+}
+function findContainingPlanDir(filePath, plansRoot) {
+  if (!filePath.startsWith(plansRoot)) return null;
+  const rel = import_node_path.default.relative(plansRoot, filePath);
+  const firstSegment = rel.split(import_node_path.default.sep)[0];
+  if (!firstSegment) return null;
+  const planDir = import_node_path.default.join(plansRoot, firstSegment);
+  if (!import_node_fs.default.existsSync(import_node_path.default.join(planDir, "plan.yaml"))) return null;
+  return planDir;
+}
+function hasGitConflictMarkers(content) {
+  return /^<{7} |^={7}$|^>{7} /m.test(content);
+}
+function serializePlan(plan, version) {
+  const obj = {
+    ...version === 2 ? { version: 2 } : {},
+    uid: plan.uid,
+    title: plan.title,
+    description: plan.description,
+    status: plan.status,
+    author: plan.author,
+    authorType: plan.authorType,
+    projectPath: plan.projectPath,
+    createdAt: new Date(plan.createdAt).toISOString(),
+    updatedAt: new Date(plan.updatedAt).toISOString()
+  };
+  if (plan.homeRepo) obj.homeRepo = plan.homeRepo;
+  if (plan.scope && plan.scope.length > 0) {
+    obj.scope = [...plan.scope].sort();
+  }
+  const refs = (0, import_plan_file_refs.refsForPlan)(plan.uid);
+  if (refs.length) obj.refs = refs;
+  return obj;
+}
+function serializeItem(item) {
+  const attachments = taskAttachmentsService.listItemAttachments(item.uid);
+  const comments = commentService.listItemComments(item.uid).filter((c) => c.kind !== "progress");
+  const obj = {
+    uid: item.uid,
+    kind: item.kind,
+    sortOrder: item.sortOrder,
+    title: item.title
+  };
+  if (item.body) obj.body = item.body;
+  if (item.template) obj.template = item.template;
+  if (item.kind === "action") {
+    if (item.scopePath) obj.scopePath = item.scopePath;
+    if (item.fileSpecs?.length) obj.fileSpecs = item.fileSpecs;
+    if (item.symbolSpecs?.length) obj.symbolSpecs = item.symbolSpecs;
+    if (item.newConnections?.length) obj.newConnections = item.newConnections;
+    if (item.removedConnections?.length) obj.removedConnections = item.removedConnections;
+    if (item.dependencies?.length) obj.dependencies = item.dependencies;
+  }
+  if (item.skills?.length) {
+    obj.skills = item.skills;
+    if (item.skillsMode && item.skillsMode !== "inherit") obj.skillsMode = item.skillsMode;
+  }
+  if (item.workstream) obj.workstream = item.workstream;
+  if (item.claimPolicy) {
+    obj.claimPolicy = item.claimPolicy;
+    if (item.claimPolicyMode && item.claimPolicyMode !== "inherit") obj.claimPolicyMode = item.claimPolicyMode;
+  }
+  if (item.executionConfig) {
+    obj.executionConfig = item.executionConfig;
+    if (item.executionConfigMode && item.executionConfigMode !== "inherit") obj.executionConfigMode = item.executionConfigMode;
+  }
+  if (item.constraints) {
+    obj.constraints = item.constraints;
+    if (item.constraintsMode && item.constraintsMode !== "inherit") obj.constraintsMode = item.constraintsMode;
+  }
+  if (item.requiresApproval) obj.requiresApproval = true;
+  if (item.visibility === "local") obj.visibility = "local";
+  if (item.overrideParentVisibility) obj.overrideParentVisibility = true;
+  obj.author = item.author;
+  obj.authorType = item.authorType;
+  obj.createdAt = new Date(item.createdAt).toISOString();
+  const refs = (0, import_plan_file_refs.refsForItem)(item.uid);
+  if (refs.length) obj.refs = refs;
+  if (attachments.length) {
+    obj.attachments = attachments.map((a) => ({
+      uid: a.uid,
+      kind: a.kind,
+      value: a.value,
+      label: a.label ?? null,
+      contentType: a.contentType ?? null,
+      author: a.author,
+      authorType: a.authorType,
+      createdAt: new Date(a.createdAt).toISOString(),
+      // A file reference's role travels (C3.4c), so a material is one on a
+      // teammate's machine too. Its hash does not: each device takes its own.
+      ...a.kind === "file_ref" && a.role ? { role: a.role } : {}
+    }));
+  }
+  if (comments.length) {
+    obj.comments = comments.map((c) => ({
+      uid: c.uid,
+      parentUid: c.parentUid,
+      author: c.author,
+      authorType: c.authorType,
+      body: c.body,
+      commentType: c.commentType,
+      kind: c.kind ?? null,
+      source: c.source ?? null,
+      metadata: c.metadata ?? null,
+      createdAt: new Date(c.createdAt).toISOString()
+    }));
+  }
+  const criteria = criteriaService.criteriaForExport(item.uid);
+  if (criteria.length) obj.criteria = criteria;
+  return obj;
+}
+function serializePhase(phase) {
+  return {
+    uid: phase.uid,
+    phaseNumber: phase.phaseNumber,
+    title: phase.title,
+    status: phase.status,
+    gitCheckpoint: phase.gitCheckpoint,
+    scope: phase.scope,
+    prerequisites: phase.prerequisites,
+    acceptanceCriteria: phase.acceptanceCriteria,
+    createdAt: new Date(phase.createdAt).toISOString(),
+    updatedAt: new Date(phase.updatedAt).toISOString()
+  };
+}
+function serializeTask(task, attachments, comments) {
+  return {
+    uid: task.uid,
+    sortOrder: task.sortOrder,
+    phaseUid: task.phaseUid,
+    parentTaskUid: task.parentTaskUid ?? null,
+    description: task.description,
+    status: task.status,
+    assignee: task.assignee,
+    assigneeType: task.assigneeType,
+    assigneeModel: task.assigneeModel,
+    affectedFiles: task.affectedFiles,
+    affectedSymbols: task.affectedSymbols,
+    newConnections: task.newConnections,
+    removedConnections: task.removedConnections,
+    dependencies: task.dependencies,
+    fileSpec: task.fileSpec ?? null,
+    symbolSpecs: task.symbolSpecs ?? [],
+    // Phase 14 §A
+    body: task.body ?? null,
+    prompt: task.prompt ?? null,
+    scopePath: task.scopePath ?? null,
+    fileSpecs: task.fileSpecs ?? [],
+    progressPercent: task.progressPercent ?? null,
+    blockedReason: task.blockedReason ?? null,
+    attachments: attachments.map((a) => ({
+      uid: a.uid,
+      kind: a.kind,
+      value: a.value,
+      label: a.label ?? null,
+      contentType: a.contentType ?? null,
+      author: a.author,
+      authorType: a.authorType,
+      createdAt: new Date(a.createdAt).toISOString(),
+      ...a.kind === "file_ref" && a.role ? { role: a.role } : {}
+    })),
+    comments: comments.map((c) => ({
+      uid: c.uid,
+      parentUid: c.parentUid,
+      author: c.author,
+      authorType: c.authorType,
+      body: c.body,
+      commentType: c.commentType,
+      kind: c.kind ?? null,
+      source: c.source ?? null,
+      metadata: c.metadata ?? null,
+      createdAt: new Date(c.createdAt).toISOString()
+    })),
+    createdAt: new Date(task.createdAt).toISOString(),
+    updatedAt: new Date(task.updatedAt).toISOString()
+  };
+}
+function serializeDoc(doc) {
+  const meta = {
+    uid: doc.uid,
+    docType: doc.docType,
+    title: doc.title,
+    orderHint: doc.orderHint,
+    parentDocUid: doc.parentDocUid,
+    version: doc.version,
+    author: doc.author,
+    authorType: doc.authorType,
+    createdAt: new Date(doc.createdAt).toISOString(),
+    updatedAt: new Date(doc.updatedAt).toISOString()
+  };
+  return `---
+${(0, import_yaml.stringify)(meta)}---
+
+${doc.body || ""}`;
+}
+function checkoutOfPlanDir(planDir) {
+  const slugDir = import_node_path.default.resolve(planDir);
+  const plansDir = import_node_path.default.dirname(slugDir);
+  const dotDir = import_node_path.default.dirname(plansDir);
+  return import_node_path.default.basename(plansDir) === "plans" && import_node_path.default.basename(dotDir) === ".codetrellis" ? import_node_path.default.dirname(dotDir) : null;
+}
+function importedPlanRoot(planUid, planDir, declared) {
+  const existing = planService.getPlan(planUid)?.projectPath;
+  if (existing && import_node_path.default.isAbsolute(existing) && import_node_fs.default.existsSync(existing)) return existing;
+  const slugDir = import_node_path.default.resolve(planDir);
+  const plansDir = import_node_path.default.dirname(slugDir);
+  const dotDir = import_node_path.default.dirname(plansDir);
+  if (import_node_path.default.basename(plansDir) === "plans" && import_node_path.default.basename(dotDir) === ".codetrellis") {
+    return (0, import_plans_home.projectOfPlansHome)(import_node_path.default.dirname(dotDir)) ?? import_node_path.default.dirname(dotDir);
+  }
+  if (typeof declared === "string" && import_node_path.default.isAbsolute(declared)) return declared;
+  return ".";
+}
+function upsertPlan(planUid, raw, projectPath) {
+  const db = (0, import_database.getDb)();
+  const exists = db.exec(`SELECT uid FROM plans WHERE uid = ?`, [planUid]);
+  const now = Date.now();
+  const hasHomeRepo = Object.prototype.hasOwnProperty.call(raw, "homeRepo");
+  const hasScope = Object.prototype.hasOwnProperty.call(raw, "scope");
+  const homeRepoVal = hasHomeRepo ? typeof raw.homeRepo === "string" && raw.homeRepo ? String(raw.homeRepo) : null : null;
+  const scopeArray = hasScope && Array.isArray(raw.scope) ? raw.scope.filter((s) => typeof s === "string") : [];
+  const scopeJson = JSON.stringify(scopeArray);
+  if (exists[0]?.values[0]) {
+    const sets = [
+      "title = ?",
+      "description = ?",
+      "status = ?",
+      "author = ?",
+      "author_type = ?",
+      "project_path = ?",
+      "updated_at = ?"
+    ];
+    const params = [
+      String(raw.title),
+      String(raw.description ?? ""),
+      String(raw.status ?? "draft"),
+      String(raw.author ?? "human"),
+      String(raw.authorType ?? "human"),
+      projectPath,
+      toEpoch(raw.updatedAt) ?? now
+    ];
+    if (hasHomeRepo) {
+      sets.push("home_repo = ?");
+      params.push(homeRepoVal);
+    }
+    if (hasScope) {
+      sets.push("scope = ?");
+      params.push(scopeJson);
+    }
+    params.push(planUid);
+    db.run(`UPDATE plans SET ${sets.join(", ")} WHERE uid = ?`, params);
+  } else {
+    db.run(
+      `INSERT INTO plans (uid, title, description, status, author, author_type, project_path, created_at, updated_at, home_repo, scope) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        planUid,
+        String(raw.title),
+        String(raw.description ?? ""),
+        String(raw.status ?? "draft"),
+        String(raw.author ?? "human"),
+        String(raw.authorType ?? "human"),
+        projectPath,
+        toEpoch(raw.createdAt) ?? now,
+        toEpoch(raw.updatedAt) ?? now,
+        homeRepoVal,
+        scopeJson
+      ]
+    );
+  }
+}
+function upsertPhase(planUid, raw) {
+  const existing = planPhasesService.getPhase(raw.uid);
+  if (existing) {
+    planPhasesService.updatePhase(raw.uid, {
+      phaseNumber: typeof raw.phaseNumber === "number" ? raw.phaseNumber : void 0,
+      title: typeof raw.title === "string" ? raw.title : void 0,
+      status: isPhaseStatus(raw.status) ? raw.status : void 0,
+      gitCheckpoint: raw.gitCheckpoint ?? null,
+      scope: typeof raw.scope === "string" ? raw.scope : void 0,
+      prerequisites: typeof raw.prerequisites === "string" ? raw.prerequisites : void 0,
+      acceptanceCriteria: typeof raw.acceptanceCriteria === "string" ? raw.acceptanceCriteria : void 0
+    });
+    return;
+  }
+  const db = (0, import_database.getDb)();
+  const now = Date.now();
+  db.run(
+    `INSERT INTO plan_phases (uid, plan_uid, phase_number, title, scope, prerequisites, git_checkpoint, acceptance_criteria, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      String(raw.uid),
+      planUid,
+      Number(raw.phaseNumber ?? 1),
+      String(raw.title ?? ""),
+      String(raw.scope ?? ""),
+      String(raw.prerequisites ?? ""),
+      raw.gitCheckpoint ?? null,
+      String(raw.acceptanceCriteria ?? ""),
+      isPhaseStatus(raw.status) ? raw.status : "pending",
+      toEpoch(raw.createdAt) ?? now,
+      toEpoch(raw.updatedAt) ?? now
+    ]
+  );
+}
+function upsertTask(planUid, raw) {
+  const existing = planService.getTaskByUid(String(raw.uid));
+  const fileSpecs = Array.isArray(raw.fileSpecs) ? raw.fileSpecs : void 0;
+  if (existing) {
+    planService.updateTask(String(raw.uid), {
+      description: typeof raw.description === "string" ? raw.description : void 0,
+      status: isTaskStatus(raw.status) ? raw.status : void 0,
+      phaseUid: raw.phaseUid ?? null,
+      assignee: raw.assignee ?? null,
+      assigneeType: raw.assigneeType ?? null,
+      assigneeModel: raw.assigneeModel ?? null,
+      affectedFiles: Array.isArray(raw.affectedFiles) ? raw.affectedFiles : void 0,
+      affectedSymbols: Array.isArray(raw.affectedSymbols) ? raw.affectedSymbols : void 0,
+      newConnections: Array.isArray(raw.newConnections) ? raw.newConnections : void 0,
+      removedConnections: Array.isArray(raw.removedConnections) ? raw.removedConnections : void 0,
+      dependencies: Array.isArray(raw.dependencies) ? raw.dependencies : void 0,
+      fileSpec: typeof raw.fileSpec === "string" ? raw.fileSpec : void 0,
+      symbolSpecs: Array.isArray(raw.symbolSpecs) ? raw.symbolSpecs : void 0,
+      // Phase 14 §A
+      parentTaskUid: raw.parentTaskUid ?? null,
+      body: typeof raw.body === "string" ? raw.body : raw.body === null ? null : void 0,
+      prompt: typeof raw.prompt === "string" ? raw.prompt : raw.prompt === null ? null : void 0,
+      scopePath: raw.scopePath ?? null,
+      fileSpecs,
+      progressPercent: typeof raw.progressPercent === "number" ? raw.progressPercent : raw.progressPercent === null ? null : void 0,
+      blockedReason: typeof raw.blockedReason === "string" ? raw.blockedReason : raw.blockedReason === null ? null : void 0
+    });
+  } else {
+    const db = (0, import_database.getDb)();
+    const now = Date.now();
+    db.run(
+      `INSERT INTO tasks (uid, plan_uid, sort_order, description, status, assignee, assignee_type, assignee_model, affected_files, affected_symbols, new_connections, removed_connections, dependencies, file_spec, symbol_specs, phase_uid, parent_task_uid, body, prompt, scope_path, file_specs, progress_percent, blocked_reason, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        String(raw.uid),
+        planUid,
+        Number(raw.sortOrder ?? 0),
+        String(raw.description ?? ""),
+        isTaskStatus(raw.status) ? raw.status : "pending",
+        raw.assignee ?? null,
+        raw.assigneeType ?? null,
+        raw.assigneeModel ?? null,
+        JSON.stringify(raw.affectedFiles ?? []),
+        JSON.stringify(raw.affectedSymbols ?? []),
+        JSON.stringify(raw.newConnections ?? []),
+        JSON.stringify(raw.removedConnections ?? []),
+        JSON.stringify(raw.dependencies ?? []),
+        raw.fileSpec ?? null,
+        JSON.stringify(raw.symbolSpecs ?? []),
+        raw.phaseUid ?? null,
+        raw.parentTaskUid ?? null,
+        raw.body ?? null,
+        raw.prompt ?? null,
+        raw.scopePath ?? null,
+        JSON.stringify(fileSpecs ?? []),
+        typeof raw.progressPercent === "number" ? raw.progressPercent : null,
+        raw.blockedReason ?? null,
+        toEpoch(raw.createdAt) ?? now,
+        toEpoch(raw.updatedAt) ?? now
+      ]
+    );
+  }
+  if (Array.isArray(raw.attachments)) {
+    for (const a of raw.attachments) {
+      if (!a?.uid || !a?.kind || a?.value == null) continue;
+      const valid = taskAttachmentsService.validateImportedAttachment(a, String(raw.uid));
+      if ("refused" in valid) {
+        console.warn(`[Import] Skipped attachment ${String(a.uid)} on task ${String(raw.uid)}: ${valid.refused}`);
+        continue;
+      }
+      const stored = taskAttachmentsService.upsertAttachment({
+        uid: String(a.uid),
+        targetType: "task",
+        targetUid: String(raw.uid),
+        kind: valid.kind,
+        value: valid.value,
+        label: typeof a.label === "string" ? a.label : null,
+        contentType: valid.contentType,
+        author: String(a.author ?? "human"),
+        authorType: String(a.authorType ?? "human"),
+        createdAt: toEpoch(a.createdAt) ?? Date.now()
+      });
+      if (!stored) console.warn(`[Import] Skipped attachment ${String(a.uid)}: it belongs to another item`);
+    }
+  }
+  if (Array.isArray(raw.comments)) {
+    for (const c of raw.comments) {
+      if (!c?.uid || !c?.body) continue;
+      upsertComment({
+        uid: String(c.uid),
+        targetType: "task",
+        targetUid: String(raw.uid),
+        parentUid: c.parentUid ?? null,
+        author: String(c.author ?? "human"),
+        authorType: String(c.authorType ?? "human"),
+        body: String(c.body),
+        commentType: c.commentType ?? "comment",
+        kind: c.kind ?? null,
+        source: c.source ?? null,
+        metadata: c.metadata ?? null,
+        createdAt: toEpoch(c.createdAt) ?? Date.now()
+      });
+    }
+  }
+}
+function upsertComment(input) {
+  const db = (0, import_database.getDb)();
+  const exists = db.exec(`SELECT uid FROM comments WHERE uid = ?`, [input.uid]);
+  const metadataJson = input.metadata ? JSON.stringify(input.metadata) : null;
+  if (exists[0]?.values[0]) {
+    db.run(
+      `UPDATE comments SET target_type = ?, target_uid = ?, parent_uid = ?, author = ?, author_type = ?, body = ?, comment_type = ?, kind = ?, source = ?, metadata = ?, created_at = ? WHERE uid = ?`,
+      [
+        input.targetType,
+        input.targetUid,
+        input.parentUid,
+        input.author,
+        input.authorType,
+        input.body,
+        input.commentType,
+        input.kind,
+        input.source,
+        metadataJson,
+        input.createdAt,
+        input.uid
+      ]
+    );
+  } else {
+    db.run(
+      `INSERT INTO comments (uid, target_type, target_uid, parent_uid, author, author_type, body, comment_type, kind, source, metadata, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        input.uid,
+        input.targetType,
+        input.targetUid,
+        input.parentUid,
+        input.author,
+        input.authorType,
+        input.body,
+        input.commentType,
+        input.kind,
+        input.source,
+        metadataJson,
+        input.createdAt
+      ]
+    );
+  }
+}
+function upsertDoc(planUid, meta, body) {
+  const docUid = String(meta.uid);
+  const existing = planDocsService.getPlanDocument(docUid);
+  if (existing) {
+    const title = typeof meta.title === "string" ? meta.title : void 0;
+    if ((0, import_plan_doc_guard.guardDiskEdit)(docUid, { title, body }) === "held") return;
+    planDocsService.updatePlanDocument(docUid, {
+      title: typeof meta.title === "string" ? meta.title : void 0,
+      body,
+      docType: typeof meta.docType === "string" ? meta.docType : void 0,
+      orderHint: meta.orderHint ?? null,
+      parentDocUid: meta.parentDocUid ?? null
+    });
+    return;
+  }
+  const db = (0, import_database.getDb)();
+  const now = Date.now();
+  db.run(
+    `INSERT INTO plan_documents (uid, plan_uid, doc_type, title, body, version, author, author_type, order_hint, parent_doc_uid, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      docUid,
+      planUid,
+      String(meta.docType ?? "custom"),
+      String(meta.title ?? ""),
+      body,
+      Number(meta.version ?? 1),
+      String(meta.author ?? "human"),
+      String(meta.authorType ?? "human"),
+      meta.orderHint ?? null,
+      meta.parentDocUid ?? null,
+      toEpoch(meta.createdAt) ?? now,
+      toEpoch(meta.updatedAt) ?? now
+    ]
+  );
+}
+let settling = false;
+function registerDiskHoldSettling() {
+  if (settling) return;
+  settling = true;
+  (0, import_breakpoint_service.onHitAnswered)((hit) => {
+    if (hit.action !== "disk") return;
+    const outcome = (0, import_plan_doc_guard.settleDiskHold)(hit);
+    if (outcome === "restore" && hit.planUid) scheduleWriteThrough(hit.planUid);
+  });
+}
+function makePlanSlug(plan) {
+  const titlePart = slugify(plan.title) || "plan";
+  const uidSuffix = plan.uid.split("-")[0];
+  return `${titlePart}-${uidSuffix}`;
+}
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+}
+function pad2(n) {
+  return String(n).padStart(2, "0");
+}
+function pad3(n) {
+  return String(n).padStart(3, "0");
+}
+function ensureDir(dir) {
+  if (!import_node_fs.default.existsSync(dir)) import_node_fs.default.mkdirSync(dir, { recursive: true });
+}
+function writeFileAtomic(filePath, content) {
+  if ((0, import_cloud_files.isPlaceholder)(filePath)) {
+    console.warn(`[Plans] ${filePath} is not on this device yet; not written, so a newer copy in the cloud is kept.`);
+    return;
+  }
+  try {
+    if (import_node_fs.default.readFileSync(filePath, "utf-8") === content) return;
+  } catch {
+  }
+  const tmp = `${filePath}.tmp`;
+  import_node_fs.default.writeFileSync(tmp, content, "utf-8");
+  import_node_fs.default.renameSync(tmp, filePath);
+  (0, import_self_write_tracker.stampSelfWrite)(filePath);
+}
+function ensureCodetrellisGitignore(codetrellisDir) {
+  const gitignorePath = import_node_path.default.join(codetrellisDir, ".gitignore");
+  if (import_node_fs.default.existsSync(gitignorePath)) return;
+  const content = [
+    "# CodeTrellis runtime cache \u2014 do not commit",
+    "cache/",
+    ""
+  ].join("\n");
+  try {
+    import_node_fs.default.writeFileSync(gitignorePath, content, "utf-8");
+  } catch {
+  }
+}
+function toEpoch(s) {
+  if (typeof s === "number") return s;
+  if (typeof s !== "string") return null;
+  const t = Date.parse(s);
+  return Number.isFinite(t) ? t : null;
+}
+function isPhaseStatus(s) {
+  return s === "pending" || s === "in_progress" || s === "done" || s === "blocked";
+}
+function isTaskStatus(s) {
+  return s === "pending" || s === "assigned" || s === "in_progress" || s === "done" || s === "blocked" || s === "skipped";
+}
+function parseFrontMatter(source) {
+  if (!source.startsWith("---")) return { meta: {}, body: source };
+  const end = source.indexOf("\n---", 3);
+  if (end < 0) return { meta: {}, body: source };
+  const yamlBlock = source.slice(3, end).replace(/^\n/, "");
+  const body = source.slice(end + 4).replace(/^\n+/, "");
+  let meta = {};
+  try {
+    meta = (0, import_yaml.parse)(yamlBlock) ?? {};
+  } catch {
+    meta = {};
+  }
+  return { meta, body };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PLACEHOLDER_PLAN_TITLE,
+  cancelWriteThrough,
+  discoverPlanDirs,
+  exportIfSharedByDefault,
+  exportOnFirstTitle,
+  exportPlan,
+  getLinkedPlanDir,
+  importPlan,
+  importedPlanRoot,
+  makePlanSlug,
+  pruneOrphanedDirs,
+  reconcilePlanState,
+  registerDiskHoldSettling,
+  scheduleWriteThrough,
+  setPlanImportedListener,
+  startPlanFileWatcher,
+  stopPlanFileWatcher,
+  unlinkPlan
+});