@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.1

package/src/maintenance.js

@@ -0,0 +1,335 @@
+import { disableRestoredProjectTeam } from "./project-team-model.js";
+import { constants } from "node:fs";
+import { createCipheriv, createDecipheriv, createHash, randomBytes, scrypt } from "node:crypto";
+import { lstat, mkdir, open, readdir, readFile, realpath, rename, rm, link, unlink } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { gzip, gunzip } from "node:zlib";
+import { promisify } from "node:util";
+import { acquireLock } from "./store.js";
+import { disableRestoredDeferredRuns } from "./deferred-runs.js";
+import { disableRestoredCodeHostActions } from "./code-hosts.js";
+import { disableRestoredCoordinatedChanges } from "./repo-coordination.js";
+import { StrictRunLogReader } from "./run-log.js";
+import { MemoryStore } from "./memory.js";
+const compress = promisify(gzip);
+const decompress = promisify(gunzip);
+const MAGIC = Buffer.from("CODEFLOW-BACKUP-1\n");
+const MAX_BYTES = 256 * 1024 * 1024;
+const MAX_MANIFEST_BYTES = Math.ceil(MAX_BYTES * 1.4);
+const MAX_FILES = 2e4;
+const MAX_LOG_BYTES = 64 * 1024 * 1024;
+const sessionPath = /(^|\/)(team-connections|ssh-host|remote-worker-private|extension-cache|acp-connections\.json(?:[.-].*)?|shared-accounts\.json(?:[.-].*)?|remote\.json(?:[.-].*)?|phone-devices\.json(?:[.-].*)?|team-link\.json(?:[.-].*)?|processes\.json|sessions?\.json|(?:team[-_])?(?:credentials?|capabilit(?:y|ies))(?:\.[^/]*)?|connection\.json|[^/]*\.(?:pem|key)|\.env(?:\.[^/]*)?)(\/|$)/i;
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const validId = (value) => /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,199}$/.test(value);
+async function homePath(path) {
+  if (!(await lstat(path)).isDirectory()) throw new Error("Choose an existing code-flow data directory, without a symbolic link.");
+  return realpath(path);
+}
+async function offline(home, action) {
+  const path = await homePath(home);
+  const release = await acquireLock(0, path);
+  try {
+    return await action(path);
+  } finally {
+    release();
+  }
+}
+function passwordKey(password, salt) {
+  if (typeof password !== "string" || password.length < 12 || password.length > 1024) throw new Error("Use a backup password of 12 to 1,024 characters in CODEFLOW_BACKUP_PASSWORD.");
+  return new Promise((accept, reject) => scrypt(password, salt, 32, { N: 32768, r: 8, p: 1, maxmem: 128 * 1024 * 1024 }, (error, key) => error ? reject(error) : accept(key)));
+}
+async function syncDirectory(path) {
+  if (process.platform === "win32") return;
+  const handle = await open(path, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function writeExclusive(path, bytes) {
+  const temp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    const handle = await open(temp, "wx", 384);
+    try {
+      await handle.writeFile(bytes);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await link(temp, path);
+    await syncDirectory(dirname(path));
+  } finally {
+    await unlink(temp).catch(() => void 0);
+  }
+}
+async function createEncryptedBackup(input) {
+  const output = join(await realpath(dirname(resolve(input.output))), basename(input.output));
+  return offline(input.home, async (home) => {
+    const inside = relative(home, output);
+    if (inside !== ".." && !inside.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) && !isAbsolute(inside)) throw new Error("Save backups outside the data directory.");
+    const memoryFile = join(home, "memory.sqlite");
+    const memoryExists = await lstat(memoryFile).then(() => true, (error) => error.code === "ENOENT" ? false : Promise.reject(error));
+    if (memoryExists) await new MemoryStore(memoryFile).load();
+    const files = [];
+    const omitted = [];
+    let bytes = 0;
+    const walk = async (folder) => {
+      for (const entry of await readdir(join(home, folder), { withFileTypes: true })) {
+        const path = folder ? `${folder}/${entry.name}` : entry.name;
+        if (sessionPath.test(path)) {
+          omitted.push(`${path} (session or credential material)`);
+          continue;
+        }
+        if (path.startsWith("server.lock") || entry.name.endsWith(".tmp")) {
+          omitted.push(path);
+          continue;
+        }
+        if (entry.isSymbolicLink()) {
+          omitted.push(`${path} (symbolic link)`);
+          continue;
+        }
+        if (entry.isDirectory()) {
+          await walk(path);
+          continue;
+        }
+        if (!entry.isFile()) {
+          omitted.push(`${path} (special file)`);
+          continue;
+        }
+        if (files.length >= MAX_FILES) throw new Error(`Backup exceeds ${MAX_FILES.toLocaleString()} files.`);
+        const handle = await open(join(home, path), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+          const before = await handle.stat();
+          if (!before.isFile() || bytes + before.size > MAX_BYTES) throw new Error("Backup exceeds the 256 MiB data limit. Archive older runs separately first.");
+          const data = await handle.readFile();
+          const after = await handle.stat();
+          if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || data.length !== before.size) throw new Error(`Data changed during backup: ${path}`);
+          bytes += data.length;
+          files.push({ path, bytes: data.length, sha256: sha256(data), data: data.toString("base64") });
+        } finally {
+          await handle.close();
+        }
+      }
+    };
+    await walk("");
+    const manifest = { version: 1, createdAt: Date.now(), files, omitted };
+    const salt = randomBytes(16);
+    const iv = randomBytes(12);
+    const header = Buffer.concat([MAGIC, salt, iv]);
+    const cipher = createCipheriv("aes-256-gcm", await passwordKey(input.password, salt), iv);
+    cipher.setAAD(header);
+    const manifestBytes = Buffer.from(JSON.stringify(manifest));
+    if (manifestBytes.length > MAX_MANIFEST_BYTES) throw new Error("Backup metadata exceeds the archive size limit. Archive older runs separately first.");
+    const packed = await compress(manifestBytes);
+    const ciphertext = Buffer.concat([cipher.update(packed), cipher.final()]);
+    await writeExclusive(output, Buffer.concat([header, cipher.getAuthTag(), ciphertext]));
+    return { output, files: files.length, bytes, omitted, encrypted: true };
+  });
+}
+function validManifest(value) {
+  if (!value || typeof value !== "object") throw new Error("Invalid backup manifest.");
+  const manifest = value;
+  if (manifest.version !== 1 || !Array.isArray(manifest.files) || manifest.files.length > MAX_FILES || !Array.isArray(manifest.omitted) || manifest.omitted.length > MAX_FILES || manifest.omitted.some((item) => typeof item !== "string" || item.length > 8192) || !Number.isSafeInteger(manifest.createdAt) || manifest.createdAt < 0) throw new Error("Unsupported or invalid backup manifest.");
+  let bytes = 0;
+  const paths = /* @__PURE__ */ new Set();
+  for (const file of manifest.files) {
+    if (!file || typeof file.path !== "string" || file.path.length > 4096 || file.path.includes("\\") || file.path.includes("\0") || isAbsolute(file.path) || file.path.split("/").some((part) => !part || part === "." || part === "..") || file.path.startsWith("server.lock") || paths.has(file.path)) throw new Error("Backup contains an unsafe or duplicate file path.");
+    if (!Number.isSafeInteger(file.bytes) || file.bytes < 0 || typeof file.data !== "string" || !/^[A-Za-z0-9+/]*={0,2}$/.test(file.data) || file.data.length % 4 !== 0 || typeof file.sha256 !== "string") throw new Error("Backup contains invalid file data.");
+    const data = Buffer.from(file.data, "base64");
+    bytes += data.length;
+    if (data.length !== file.bytes || data.toString("base64") !== file.data || sha256(data) !== file.sha256 || bytes > MAX_BYTES) throw new Error("Backup file integrity or size validation failed.");
+    paths.add(file.path);
+  }
+  const privateFiles = manifest.files.filter((file) => sessionPath.test(file.path));
+  return { ...manifest, files: manifest.files.filter((file) => !sessionPath.test(file.path)), omitted: [...manifest.omitted, ...privateFiles.map((file) => `${file.path} (session or credential material excluded from restore)`)] };
+}
+async function restoreEncryptedBackup(input) {
+  const source = await lstat(input.input);
+  if (!source.isFile() || source.size > MAX_MANIFEST_BYTES + 1024 || source.size < MAGIC.length + 45) throw new Error("Choose a valid backup file under 360 MiB.");
+  const archive = await readFile(input.input);
+  if (!archive.subarray(0, MAGIC.length).equals(MAGIC)) throw new Error("Unsupported backup format.");
+  const salt = archive.subarray(MAGIC.length, MAGIC.length + 16);
+  const iv = archive.subarray(MAGIC.length + 16, MAGIC.length + 28);
+  const headerEnd = MAGIC.length + 28;
+  const decipher = createDecipheriv("aes-256-gcm", await passwordKey(input.password, salt), iv);
+  decipher.setAAD(archive.subarray(0, headerEnd));
+  decipher.setAuthTag(archive.subarray(headerEnd, headerEnd + 16));
+  let packed;
+  try {
+    packed = Buffer.concat([decipher.update(archive.subarray(headerEnd + 16)), decipher.final()]);
+  } catch {
+    throw new Error("Backup authentication failed. Check the password and that the file is intact.");
+  }
+  let manifest;
+  try {
+    manifest = validManifest(JSON.parse((await decompress(packed, { maxOutputLength: MAX_MANIFEST_BYTES })).toString("utf8")));
+  } catch (error) {
+    throw new Error(`Cannot restore backup: ${error.message}`);
+  }
+  const destination = resolve(input.destination);
+  if (await lstat(destination).then(() => true, (error) => error.code === "ENOENT" ? false : Promise.reject(error))) throw new Error("Restore destination already exists. Choose a new directory.");
+  const parent = await realpath(dirname(destination));
+  const finalPath = join(parent, basename(destination));
+  const staging = join(parent, `.${basename(destination)}.restore-${randomBytes(8).toString("hex")}`);
+  await mkdir(staging, { mode: 448 });
+  let disabledAutomations = 0;
+  let disabledNotifications = 0;
+  let cancelledDeferredRuns = 0;
+  let cancelledCoordinatedChanges = 0;
+  let restoredBytes = 0;
+  try {
+    for (const file of manifest.files) {
+      const target = join(staging, file.path);
+      await mkdir(dirname(target), { recursive: true, mode: 448 });
+      let data = Buffer.from(file.data, "base64");
+      if (/^project-teams\/pt-[a-f0-9]{24}\.json$/.test(file.path)) data = Buffer.from(JSON.stringify(disableRestoredProjectTeam(JSON.parse(data.toString("utf8")))));
+      if (file.path === "triggers.json") {
+        const triggers = JSON.parse(data.toString("utf8"));
+        if (!Array.isArray(triggers) || triggers.some((trigger) => !trigger || typeof trigger !== "object" || Array.isArray(trigger))) throw new Error("Cannot restore invalid automation settings.");
+        disabledAutomations = triggers.length;
+        data = Buffer.from(JSON.stringify(triggers.map((trigger) => ({ ...trigger, enabled: false, token: randomBytes(24).toString("hex"), nextAt: void 0, queued: [], webhookStarts: [] })), null, 2));
+      }
+      if (file.path === "notifications.json") {
+        const notifications = JSON.parse(data.toString("utf8"));
+        if (!notifications || notifications.version !== 1 || !notifications.settings || typeof notifications.settings !== "object" || Array.isArray(notifications.settings) || !Array.isArray(notifications.deliveries)) throw new Error("Cannot restore invalid notification settings.");
+        for (const settings of Object.values(notifications.settings)) {
+          if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error("Cannot restore invalid notification settings.");
+          settings.enabled = false;
+          disabledNotifications++;
+        }
+        notifications.deliveries = notifications.deliveries.map((delivery) => {
+          if (!delivery || typeof delivery !== "object") throw new Error("Cannot restore invalid notification deliveries.");
+          return ["pending", "sending"].includes(String(delivery.state)) ? { ...delivery, state: "cancelled", nextAttemptAt: void 0, updatedAt: Date.now(), reason: "Cancelled during backup restore; deliberately re-enable notifications after reviewing destinations." } : delivery;
+        });
+        data = Buffer.from(JSON.stringify(notifications, null, 2));
+      }
+      if (file.path === "deferred-runs.json") {
+        const restored = disableRestoredDeferredRuns(JSON.parse(data.toString("utf8")));
+        cancelledDeferredRuns = restored.cancelled;
+        data = Buffer.from(JSON.stringify(restored.document, null, 2));
+      }
+      if (file.path === "coordinated-changes.json") {
+        const restored = disableRestoredCoordinatedChanges(JSON.parse(data.toString("utf8")));
+        cancelledCoordinatedChanges = restored.cancelled;
+        data = Buffer.from(JSON.stringify(restored.document, null, 2));
+      }
+      if (file.path === "code-host-operations.json") data = Buffer.from(JSON.stringify(disableRestoredCodeHostActions(JSON.parse(data.toString("utf8"))), null, 2));
+      const handle = await open(target, "wx", 384);
+      try {
+        await handle.writeFile(data);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await syncDirectory(dirname(target));
+      restoredBytes += data.length;
+    }
+    if (await lstat(finalPath).then(() => true, (error) => error.code === "ENOENT" ? false : Promise.reject(error))) throw new Error("Restore destination was created during restore. Choose a new directory.");
+    await syncDirectory(staging);
+    await rename(staging, finalPath);
+    await syncDirectory(parent);
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+  return { destination: finalPath, files: manifest.files.length, bytes: restoredBytes, createdAt: manifest.createdAt, omitted: manifest.omitted, disabledAutomations, disabledNotifications, cancelledDeferredRuns, cancelledCoordinatedChanges };
+}
+async function readRunLog(home, id) {
+  if (!validId(id)) throw new Error("Choose a valid run id.");
+  if (!(await lstat(join(home, "runs"))).isDirectory()) throw new Error("Run storage must be a regular directory without a symbolic link.");
+  const path = join(home, "runs", `${id}.jsonl`);
+  const info = await lstat(path);
+  if (!info.isFile() || info.size > MAX_LOG_BYTES) throw new Error("Only regular run logs up to 64 MiB can be maintained by this command.");
+  const text = await readFile(path, "utf8");
+  if (!text.endsWith("\n")) throw new Error("Run log has an incomplete last record; repair or recover it before maintenance.");
+  const lines = text.split("\n").filter((line) => line.trim());
+  const events = lines.map((line) => JSON.parse(line));
+  if (events.some((event) => !event || typeof event !== "object" || Array.isArray(event) || event.type === "run" && event.run?.id !== id)) throw new Error("Run log contains invalid or mismatched records.");
+  const reader = new StrictRunLogReader(id);
+  let snapshot;
+  for (const value of events) {
+    const event = reader.decode(value);
+    if (event?.type === "run") snapshot = event.run;
+  }
+  if (!snapshot || !["done", "failed", "cancelled"].includes(snapshot.status)) throw new Error("Only completed, failed or cancelled runs can be maintained. Resumable runs are kept.");
+  return { text, lines, events, snapshot, bytes: info.size, mtimeMs: info.mtimeMs };
+}
+async function retentionPlan(home, days, now) {
+  if (!Number.isInteger(days) || days < 1 || days > 36500 || !Number.isFinite(now)) throw new Error("Retention days must be an integer from 1 to 36,500.");
+  const result = { days, cutoff: now - days * 864e5, candidates: [], skipped: [] };
+  const runDirectory = await lstat(join(home, "runs")).catch((error) => error.code === "ENOENT" ? void 0 : Promise.reject(error));
+  if (!runDirectory) return result;
+  if (!runDirectory.isDirectory()) throw new Error("Run storage must be a regular directory without a symbolic link.");
+  const entries = await readdir(join(home, "runs")).catch((error) => error.code === "ENOENT" ? [] : Promise.reject(error));
+  for (const file of entries.filter((file2) => file2.endsWith(".jsonl") && !file2.endsWith(".journal.jsonl"))) {
+    const id = file.slice(0, -6);
+    try {
+      const log = await readRunLog(home, id);
+      if (log.snapshot.archived !== true || log.mtimeMs >= result.cutoff) continue;
+      const files = [];
+      let bytes = 0;
+      for (const name of [`${id}.jsonl`, `${id}.journal.jsonl`, `${id}.checkpoint.json`, `${id}.cold-index.json`, `${id}.cold-detail.json`]) {
+        const info = await lstat(join(home, "runs", name)).catch((error) => error.code === "ENOENT" ? void 0 : Promise.reject(error));
+        if (info?.isFile()) {
+          files.push(name);
+          bytes += info.size;
+        }
+      }
+      result.candidates.push({ id, files, bytes });
+    } catch (error) {
+      result.skipped.push({ id, reason: error.message });
+    }
+  }
+  return result;
+}
+function retainArchivedRuns(input) {
+  return offline(input.home, async (home) => {
+    const plan = await retentionPlan(home, input.days, input.now ?? Date.now());
+    if (input.apply) throw new Error("Age-only retention cannot delete data. Save a retention policy, review retention-policy --output PLAN.json, then apply that exact plan with retention-policy --plan PLAN.json --apply.");
+    return { ...plan, applied: false, deletedFiles: 0, nextStep: "This legacy age-only report does not assess pins or provenance. Save a retention policy and review retention-policy --output PLAN.json before applying retention-policy --plan PLAN.json --apply." };
+  });
+}
+function compactRunLog(input) {
+  return offline(input.home, async (home) => {
+    const log = await readRunLog(home, input.runId);
+    const snapshots = log.events.flatMap((event, index) => event?.type === "run" || event?.type === "run-patch" ? [index] : []);
+    const removable = new Set(snapshots.slice(1, -1));
+    const last = snapshots.at(-1), lastEvent = last === void 0 ? void 0 : log.events[last];
+    const finalLine = removable.size && lastEvent?.type === "run-patch" ? JSON.stringify({ seq: lastEvent.seq, ts: lastEvent.ts, runId: input.runId, type: "run", run: log.snapshot }) : void 0;
+    let text = log.lines.flatMap((line, index) => removable.has(index) ? [] : [index === last && finalLine ? finalLine : line]).join("\n") + "\n";
+    let afterBytes = Buffer.byteLength(text);
+    if (afterBytes >= log.bytes) {
+      removable.clear();
+      text = log.text;
+      afterBytes = log.bytes;
+    }
+    if (input.apply && removable.size) {
+      const path = join(home, "runs", `${input.runId}.jsonl`);
+      const temp = `${path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+      try {
+        const handle = await open(temp, "wx", 384);
+        try {
+          await handle.writeFile(text);
+          await handle.sync();
+        } finally {
+          await handle.close();
+        }
+        const current = await lstat(path);
+        if (current.size !== log.bytes || current.mtimeMs !== log.mtimeMs || !current.isFile()) throw new Error("Run log changed during compaction; no change was applied.");
+        await rename(temp, path);
+        await syncDirectory(dirname(path));
+        for (const suffix of [".checkpoint.json", ".cold-index.json", ".cold-detail.json"]) await unlink(join(home, "runs", input.runId + suffix)).catch(() => void 0);
+      } finally {
+        await unlink(temp).catch(() => void 0);
+      }
+    }
+    return { runId: input.runId, applied: input.apply === true, snapshotsRemoved: removable.size, beforeBytes: log.bytes, afterBytes, savedBytes: log.bytes - afterBytes };
+  });
+}
+export {
+  compactRunLog,
+  createEncryptedBackup,
+  restoreEncryptedBackup,
+  retainArchivedRuns
+};

package/src/memory-analysis.js

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { git } from "./git.js";
+import { analyzeMemoryClaims } from "./memory-claims.js";
+const LIMITS = { entries: 500, references: 5e3, paths: 1e3, commitBaselines: 16, comparedPairs: 5e4, duplicatePairs: 100, onboardingEntries: 12, onboardingChars: 12e3 };
+const RETENTION = "Deleting erases this entry's text and stops its future retrieval. Derived entries retain their own text and provenance. Source run transcripts, provider conversations and backups have separate retention.";
+const ref = (entry) => ({ id: entry.id, revision: entry.revision });
+const key = (entry) => `${entry.id}@${entry.revision}`;
+const normalize = (text) => text.replace(/\s+/g, " ").trim();
+const digest = (text) => createHash("sha256").update(normalize(text)).digest("hex");
+async function analyzeProjectMemory(input) {
+  const scoped = input.entries.filter((entry) => entry.scope === "project" && entry.repo === input.repo && entry.projectId === input.projectId && entry.status !== "deleted").sort((a, b) => b.updatedAt - a.updatedAt || a.id.localeCompare(b.id));
+  const entries = scoped.slice(0, LIMITS.entries);
+  const now = input.now ?? Date.now();
+  const result = {
+    scope: { repo: input.repo, projectId: input.projectId },
+    git: { available: false },
+    graph: { nodes: [], edges: [] },
+    deletionImpact: [],
+    stale: [],
+    duplicates: [],
+    claims: analyzeMemoryClaims({ repo: input.repo, projectId: input.projectId, entries }),
+    onboarding: { title: `Project onboarding \xB7 ${basename(input.repo)}`.slice(0, 200), body: "", sourceRefs: [], omitted: 0, reasons: [] },
+    limits: { ...LIMITS },
+    truncated: entries.length !== scoped.length,
+    notes: []
+  };
+  const nodes = /* @__PURE__ */ new Map();
+  const reverse = /* @__PURE__ */ new Map();
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  for (const entry of entries) nodes.set(key(entry), { key: key(entry), ...ref(entry), title: entry.title, status: entry.status, available: true });
+  let references = 0;
+  for (const entry of entries) {
+    for (const source of entry.derivedFrom) {
+      if (references++ >= LIMITS.references) {
+        result.truncated = true;
+        break;
+      }
+      if (!nodes.has(key(source))) nodes.set(key(source), { key: key(source), ...ref(source), available: false });
+      result.graph.edges.push({ from: key(source), to: key(entry) });
+      const derived = reverse.get(source.id) ?? /* @__PURE__ */ new Set();
+      derived.add(entry.id);
+      reverse.set(source.id, derived);
+    }
+  }
+  result.graph.nodes = [...nodes.values()];
+  for (const entry of entries) {
+    const descendants = /* @__PURE__ */ new Set();
+    const queue = [...reverse.get(entry.id) ?? []];
+    for (let index = 0; index < queue.length; index++) {
+      const id = queue[index];
+      if (id === entry.id || descendants.has(id)) continue;
+      descendants.add(id);
+      queue.push(...reverse.get(id) ?? []);
+    }
+    const refs = (ids) => [...ids].flatMap((id) => byId.has(id) ? [ref(byId.get(id))] : []).sort((a, b) => a.id.localeCompare(b.id));
+    result.deletionImpact.push({ ...ref(entry), direct: refs(reverse.get(entry.id) ?? []), transitive: refs(descendants), retained: RETENTION });
+  }
+  const stale = /* @__PURE__ */ new Map();
+  const incomplete = /* @__PURE__ */ new Set();
+  const add = (entry, kind, detail) => {
+    const current = stale.get(entry.id) ?? { ...ref(entry), reasons: [] };
+    current.reasons.push({ kind, detail });
+    stale.set(entry.id, current);
+  };
+  for (const entry of entries) {
+    if (entry.expiresAt !== void 0 && entry.expiresAt <= now) add(entry, "expired", "The entry's expiry has passed.");
+    for (const feedback of entry.feedback ?? []) if (feedback.revision === entry.revision && ["stale", "incorrect"].includes(feedback.rating)) add(entry, "feedback", `You marked this revision ${feedback.rating}${feedback.note ? `: ${feedback.note}` : "."}`);
+  }
+  const readGit = (args) => git(["--literal-pathspecs", ...args], input.repo, { signal: input.signal, timeoutMs: 2e3 });
+  const [headResult, branchResult] = await Promise.all([
+    readGit(["rev-parse", "--verify", "--end-of-options", `${input.head ?? "HEAD"}^{commit}`]),
+    input.branch ? Promise.resolve({ code: 0, stdout: input.branch }) : readGit(["symbolic-ref", "--quiet", "--short", "HEAD"])
+  ]);
+  const head = headResult.code === 0 && /^[a-f0-9]{40,64}$/.test(headResult.stdout.trim()) ? headResult.stdout.trim() : void 0;
+  const branch = branchResult.code === 0 ? branchResult.stdout.trim() : void 0;
+  result.git = { ...head ? { head } : {}, ...branch ? { branch } : {}, available: !!head };
+  if (!head) {
+    result.notes.push("Git evidence is unavailable; only expiry and revision feedback were evaluated.");
+    for (const entry of entries) if (entry.paths.length || entry.verification?.commit || entry.applicability.kind === "branch" && entry.applicability.commit) incomplete.add(entry.id);
+  }
+  if (head) {
+    const allPaths = [...new Set(entries.flatMap((entry) => entry.paths))];
+    const paths = allPaths.slice(0, LIMITS.paths);
+    const checkedPaths = new Set(paths);
+    if (paths.length !== allPaths.length) result.truncated = true;
+    const tree = paths.length ? await readGit(["ls-tree", "--name-only", "-r", "-z", head, "--", ...paths]) : void 0;
+    const listed = tree?.code === 0 ? tree.stdout.split("\0").filter(Boolean) : void 0;
+    const present = listed && listed.length <= 2e4 ? new Set(listed) : void 0;
+    if (listed && !present) result.truncated = true;
+    if (present) for (const file of [...present]) {
+      const parts = file.split("/");
+      for (let index = 1; index < parts.length; index++) present.add(parts.slice(0, index).join("/"));
+    }
+    if (tree && !present) result.notes.push("Path existence could not be checked at the selected commit.");
+    for (const entry of entries) {
+      if (entry.paths.some((path) => !checkedPaths.has(path)) || entry.paths.length && !present) incomplete.add(entry.id);
+      if (entry.applicability.kind === "branch" && branch && entry.applicability.branch !== branch) add(entry, "branch-mismatch", `This entry applies to ${entry.applicability.branch}; the selected branch is ${branch}.`);
+      if (present) for (const path of entry.paths) {
+        if (!checkedPaths.has(path)) continue;
+        if (!present.has(path.replace(/\/$/, ""))) add(entry, "missing-path", `${path} is absent at ${head.slice(0, 12)}.`);
+      }
+    }
+    const baselines = [...new Set(entries.flatMap((entry) => [entry.verification?.commit, entry.applicability.kind === "branch" ? entry.applicability.commit : void 0]).filter((value) => !!value))];
+    const checkedBaselines = new Set(baselines.slice(0, LIMITS.commitBaselines));
+    if (baselines.length > LIMITS.commitBaselines) result.truncated = true;
+    for (const entry of entries) if (entry.verification?.commit && !checkedBaselines.has(entry.verification.commit) || entry.applicability.kind === "branch" && entry.applicability.commit && !checkedBaselines.has(entry.applicability.commit)) incomplete.add(entry.id);
+    for (let index = 0; index < Math.min(baselines.length, LIMITS.commitBaselines); index += 4) {
+      const observed = await Promise.all(baselines.slice(index, Math.min(index + 4, LIMITS.commitBaselines)).map(async (base) => {
+        const exists = /^[a-f0-9]{40,64}$/i.test(base) ? await readGit(["cat-file", "-e", `${base}^{commit}`]) : { code: 1 };
+        if (exists.code !== 0) return { base, state: "missing" };
+        const ancestor = await readGit(["merge-base", "--is-ancestor", base, head]);
+        if (ancestor.code === 1) return { base, state: "diverged" };
+        if (ancestor.code !== 0) return { base, state: "unknown" };
+        const diff = paths.length ? await readGit(["diff", "--no-ext-diff", "--no-textconv", "--name-only", "-z", base, head, "--", ...paths]) : void 0;
+        return { base, state: "ancestor", changed: diff?.code === 0 ? diff.stdout.split("\0").filter(Boolean) : [], incomplete: !!diff && diff.code !== 0 };
+      }));
+      for (const observation of observed) for (const entry of entries) {
+        if (entry.verification?.commit !== observation.base && (entry.applicability.kind !== "branch" || entry.applicability.commit !== observation.base)) continue;
+        if (observation.state === "missing") add(entry, "commit-unavailable", `Recorded commit ${observation.base.slice(0, 12)} is unavailable.`);
+        else if (observation.state === "diverged") add(entry, "commit-not-ancestor", `Recorded commit ${observation.base.slice(0, 12)} is not an ancestor of the selected checkout.`);
+        else if (observation.state === "ancestor") {
+          if (observation.incomplete) incomplete.add(entry.id);
+          const changed = observation.changed.filter((path) => entry.paths.some((scope) => path === scope || path.startsWith(scope.replace(/\/$/, "") + "/")));
+          if (changed.length) add(entry, "paths-changed", `Relevant paths changed since ${observation.base.slice(0, 12)}: ${changed.slice(0, 8).join(", ")}${changed.length > 8 ? ", \u2026" : ""}. Review this guidance; a code change does not prove it incorrect.`);
+        } else incomplete.add(entry.id);
+      }
+    }
+  }
+  result.stale = [...stale.values()];
+  const words = (text) => new Set((text.toLowerCase().match(/[\p{L}\p{N}_-]{3,}/gu) ?? []).filter((word) => !STOP_WORDS.has(word)).slice(0, 200));
+  const bodies = entries.map((entry) => ({ hash: digest(entry.body), words: words(entry.body) }));
+  let pairs = 0;
+  outer: for (let a = 0; a < entries.length; a++) for (let b = a + 1; b < entries.length; b++) {
+    if (++pairs > LIMITS.comparedPairs || result.duplicates.length >= LIMITS.duplicatePairs) {
+      result.truncated = true;
+      break outer;
+    }
+    if (bodies[a].hash === bodies[b].hash) result.duplicates.push({ a: ref(entries[a]), b: ref(entries[b]), kind: "exact", similarity: 1 });
+    else {
+      const left = bodies[a].words, right = bodies[b].words;
+      const overlap = [...left].filter((word) => right.has(word)).length;
+      const similarity = overlap / (left.size + right.size - overlap || 1);
+      if (overlap >= 5 && similarity >= 0.65) result.duplicates.push({ a: ref(entries[a]), b: ref(entries[b]), kind: "lexical-overlap", similarity: Math.round(similarity * 1e3) / 1e3 });
+    }
+  }
+  result.notes.push("Lexical overlap and supported semantic claims are separate review hints. Claim analysis is bounded to its explicit grammar and never decides which guidance is correct.");
+  result.notes.push("Path changes require a recorded commit baseline. User guidance without one is checked for missing paths, expiry and feedback only.");
+  const onboarding = ["# Project onboarding", "Curated from accepted guidance written by you. Review the sources and applicability before using it."];
+  let size = onboarding.join("\n\n").length;
+  const curated = [...entries].sort((a, b) => a.title.localeCompare(b.title) || a.id.localeCompare(b.id));
+  for (const entry of curated) {
+    const reason = entry.status !== "accepted" || entry.acceptedBy !== "user" ? "Not accepted by you" : !entry.origins.length || entry.origins.some((origin) => origin.kind !== "user" || origin.trust !== "trusted" || origin.lockedDown || origin.private) ? "Includes run, imported, private or untrusted origins" : stale.has(entry.id) ? "Needs applicability or freshness review" : entry.applicability.kind === "branch" && !branch ? "Selected branch is unknown" : incomplete.has(entry.id) ? "Freshness checks were unavailable or reached a limit" : entry.tags.includes("onboarding-summary") ? "Already an onboarding summary" : void 0;
+    if (reason) {
+      result.onboarding.reasons.push({ id: entry.id, reason });
+      continue;
+    }
+    const scope = entry.applicability.kind === "branch" ? `
+
+Applies to branch ${entry.applicability.branch}${entry.applicability.commit ? ` at ${entry.applicability.commit}` : ""}.` : "";
+    const section = `## ${entry.title}
+
+${entry.body}${scope}
+
+Source: ${entry.id} (revision ${entry.revision}).`;
+    if (result.onboarding.sourceRefs.length >= LIMITS.onboardingEntries || size + section.length + 2 > LIMITS.onboardingChars) {
+      result.onboarding.reasons.push({ id: entry.id, reason: "Onboarding summary size limit" });
+      result.truncated = true;
+      continue;
+    }
+    onboarding.push(section);
+    size += section.length + 2;
+    result.onboarding.sourceRefs.push(ref(entry));
+  }
+  result.onboarding.body = result.onboarding.sourceRefs.length ? onboarding.join("\n\n") : "";
+  result.onboarding.omitted = scoped.length - result.onboarding.sourceRefs.length;
+  return result;
+}
+const STOP_WORDS = /* @__PURE__ */ new Set(["the", "and", "that", "this", "with", "from", "for", "before", "after", "should", "must", "use", "using", "when", "into", "are", "you", "your"]);
+export {
+  analyzeProjectMemory
+};