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

package/src/repo-tree.js

@@ -0,0 +1,106 @@
+import { open, readdir, realpath, stat } from "node:fs/promises";
+import { basename, join, sep } from "node:path";
+import { git } from "./git.js";
+import { assertProjectDirectoryAccess, assertProjectFileAccess, filePolicyMetadataOnly, filePolicyRegistryActive, filterAllowedProjectEntries } from "./filesystem-policy.js";
+const MAX_ENTRIES = 1e3;
+const PANEL_TIMEOUT_MS = 3e4;
+function normalizeRepoPath(raw) {
+  const parts = raw.replace(/\\/g, "/").split("/").filter((p) => p && p !== ".");
+  if (parts.some((p) => p === "..")) throw new Error(`Path "${raw}" must stay inside the repository`);
+  return parts.join("/");
+}
+async function resolveInsideRepo(repo, rel) {
+  const abs = rel ? join(repo, ...rel.split("/")) : repo;
+  const [real, realRepo] = await Promise.all([realpath(abs), realpath(repo)]);
+  if (real !== realRepo && !real.startsWith(realRepo + sep)) {
+    throw new Error(`Path "${rel}" points outside the repository`);
+  }
+  return abs;
+}
+const folderOf = (repo) => typeof repo === "string" ? repo : repo.path;
+async function listTree(repo, relDir = "") {
+  const rel = normalizeRepoPath(relDir);
+  await assertProjectDirectoryAccess(folderOf(repo), rel || ".");
+  const abs = await resolveInsideRepo(folderOf(repo), rel);
+  const dirents = (await readdir(abs, { withFileTypes: true })).filter((d) => d.name !== ".git" && (!filePolicyRegistryActive() || !d.isSymbolicLink()));
+  const candidates = await Promise.all(
+    dirents.map(async (d) => {
+      const path = rel ? `${rel}/${d.name}` : d.name;
+      const isDir = d.isDirectory() || d.isSymbolicLink() && await stat(join(abs, d.name)).then((s) => s.isDirectory(), () => false);
+      return { name: d.name, path, type: isDir ? "dir" : "file" };
+    })
+  );
+  const ignored = await ignoredPaths(repo, candidates.map((c) => c.type === "dir" ? `${c.path}/` : c.path));
+  const statuses = filePolicyMetadataOnly() ? /* @__PURE__ */ new Map() : await childStatuses(repo, rel);
+  const entries = (await filterAllowedProjectEntries(folderOf(repo), candidates)).filter((c) => !ignored.has(c.type === "dir" ? `${c.path}/` : c.path)).map((c) => ({ ...c, status: statuses.get(c.name) })).sort((a, b) => a.type === b.type ? a.name.localeCompare(b.name, void 0, { sensitivity: "base" }) : a.type === "dir" ? -1 : 1);
+  return { path: rel, entries: entries.slice(0, MAX_ENTRIES), truncated: entries.length > MAX_ENTRIES };
+}
+async function searchFiles(repo, query, limit = 100) {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  const res = await git(["-c", "core.fsmonitor=false", "ls-files", "-z", "--cached", "--others", "--exclude-standard"], repo, { timeoutMs: PANEL_TIMEOUT_MS });
+  if (res.code !== 0) throw new Error(res.stderr.trim() || "git ls-files failed");
+  const unique = [...new Set(res.stdout.split("\0").filter(Boolean))];
+  const nameHits = [];
+  const pathHits = [];
+  for (const path of unique) {
+    const lower = path.toLowerCase();
+    if (basename(lower).includes(q)) nameHits.push(path);
+    else if (lower.includes(q)) pathHits.push(path);
+  }
+  return (await filterAllowedProjectEntries(folderOf(repo), [...nameHits, ...pathHits].map((path) => ({ name: basename(path), path, type: "file" })))).slice(0, limit);
+}
+async function ignoredPaths(repo, paths) {
+  if (!paths.length) return /* @__PURE__ */ new Set();
+  const res = await git(["-c", "core.fsmonitor=false", "check-ignore", "-z", "--stdin"], repo, { input: paths.join("\0") + "\0", timeoutMs: PANEL_TIMEOUT_MS });
+  if (res.timedOut) throw new Error(res.stderr.split("\n")[0]);
+  if (res.code !== 0 && res.code !== 1) return /* @__PURE__ */ new Set();
+  return new Set(res.stdout.split("\0").filter(Boolean));
+}
+async function childStatuses(repo, rel) {
+  const res = await git(["status", "--porcelain=v1", "-z", "--untracked-files=all", "--", rel || "."], repo, { timeoutMs: PANEL_TIMEOUT_MS });
+  const statuses = /* @__PURE__ */ new Map();
+  if (res.code !== 0) return statuses;
+  const records = res.stdout.split("\0");
+  for (let i = 0; i < records.length; i++) {
+    const record = records[i];
+    if (record.length < 4) continue;
+    const xy = record.slice(0, 2);
+    const path = record.slice(3);
+    if (xy[0] === "R" || xy[0] === "C") i++;
+    const inside = rel ? path.startsWith(`${rel}/`) ? path.slice(rel.length + 1) : null : path;
+    if (!inside) continue;
+    const child = inside.split("/")[0];
+    const status = xy === "??" ? "U" : xy === "A " ? "A" : "M";
+    const previous = statuses.get(child);
+    statuses.set(child, previous && previous !== status ? "M" : status);
+  }
+  return statuses;
+}
+const MAX_FILE_BYTES = 512 * 1024;
+async function readRepoFile(repo, relPath) {
+  await assertProjectFileAccess(folderOf(repo), relPath, "read");
+  const rel = normalizeRepoPath(relPath);
+  if (!rel) throw new Error("Name a file");
+  const abs = await resolveInsideRepo(folderOf(repo), rel);
+  const info = await stat(abs);
+  if (info.isDirectory()) throw new Error(`"${rel}" is a folder`);
+  const handle = await open(abs, "r");
+  try {
+    const buf = Buffer.alloc(Math.min(info.size, MAX_FILE_BYTES));
+    const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+    await assertProjectFileAccess(folderOf(repo), relPath, "read");
+    const head = buf.subarray(0, Math.min(bytesRead, 8e3));
+    if (head.includes(0)) return { path: rel, size: info.size, binary: true, truncated: false };
+    return { path: rel, size: info.size, text: buf.subarray(0, bytesRead).toString("utf8"), binary: false, truncated: info.size > bytesRead };
+  } finally {
+    await handle.close();
+  }
+}
+export {
+  listTree,
+  normalizeRepoPath,
+  readRepoFile,
+  resolveInsideRepo,
+  searchFiles
+};

package/src/retention-policy.js

@@ -0,0 +1,466 @@
+import { constants } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readdir, readlink, realpath, rename, rm, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { CODEFLOW_HOME, WORKTREE_DIR } from "./config.js";
+import { acquireLock } from "./store.js";
+import { git } from "./git.js";
+import { readOnlyGitMetadata } from "./agent-container.js";
+import { MemoryStore, validateDocument } from "./memory.js";
+import { validateDeferredDocument } from "./deferred-runs.js";
+import { validateCodeHostDocument } from "./code-hosts.js";
+import { validateCoordinationDocument } from "./repo-coordination.js";
+import { StrictRunLogReader } from "./run-log.js";
+class RetentionPolicyConflictError extends Error {
+  constructor(current) {
+    super("Retention settings changed. Reload before saving.");
+    this.current = current;
+  }
+  status = 409;
+}
+const RETENTION_LIMITS = { runs: 2e3, memory: 5e4, targets: 1e3, files: 1e5, readBytes: 256 * 1024 * 1024, logBytes: 64 * 1024 * 1024, planAgeMs: 24 * 60 * 6e4 };
+const KINDS = ["archivedRuns", "attachments", "memory", "worktrees"];
+const sha = (value) => createHash("sha256").update(value).digest("hex");
+const canonical = (value) => JSON.stringify(value, (_key, item) => item && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item);
+const validId = (value) => typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,199}$/.test(value);
+const inside = (parent, path) => {
+  const rel = relative(parent, path);
+  return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+};
+const policyQueues = /* @__PURE__ */ new Map();
+const defaults = () => ({ version: 1, revision: 0, days: { archivedRuns: null, attachments: null, memory: null, worktrees: null }, keepRunIds: [], keepMemoryIds: [] });
+function validatePolicy(value, revision) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Choose valid retention settings");
+  const raw = value;
+  if (Object.keys(raw).some((key) => !["version", "revision", "days", "keepRunIds", "keepMemoryIds"].includes(key)) || !raw.days || typeof raw.days !== "object" || Array.isArray(raw.days) || Object.keys(raw.days).some((key) => !KINDS.includes(key))) throw new Error("Unsupported retention policy fields");
+  const result = defaults();
+  result.revision = revision;
+  for (const kind of KINDS) {
+    const days = raw.days[kind];
+    if (days !== null && (!Number.isInteger(days) || days < 1 || days > 36500)) throw new Error("Retention days must be 1\u201336,500, or null to keep that data");
+    result.days[kind] = days;
+  }
+  for (const field of ["keepRunIds", "keepMemoryIds"]) {
+    if (!Array.isArray(raw[field]) || raw[field].length > 1e3 || raw[field].some((id) => !validId(id))) throw new Error(`Choose at most 1,000 valid ${field}`);
+    result[field] = [...new Set(raw[field])].sort();
+  }
+  return result;
+}
+async function atomicJson(file, value) {
+  await mkdir(dirname(file), { recursive: true });
+  await safeParents(file);
+  const temp = `${file}.${randomUUID()}.tmp`;
+  try {
+    const handle = await open(temp, "wx", 384);
+    try {
+      await handle.writeFile(JSON.stringify(value, null, 2));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temp, file);
+    if (process.platform !== "win32") {
+      const folder = await open(dirname(file), "r");
+      try {
+        await folder.sync();
+      } finally {
+        await folder.close();
+      }
+    }
+  } finally {
+    await rm(temp, { force: true });
+  }
+}
+class RetentionPolicyStore {
+  file;
+  constructor(file = join(CODEFLOW_HOME, "retention-policy.json")) {
+    this.file = resolve(file);
+  }
+  async get() {
+    await policyQueues.get(this.file);
+    return readPolicy(this.file);
+  }
+  set(value, expectedRevision) {
+    const work = (policyQueues.get(this.file) ?? Promise.resolve()).then(async () => {
+      const previous = await readPolicy(this.file);
+      if (!Number.isSafeInteger(expectedRevision) || expectedRevision !== previous.revision) throw new RetentionPolicyConflictError(previous);
+      const next = validatePolicy(value, previous.revision + 1);
+      await atomicJson(this.file, next);
+      return structuredClone(next);
+    });
+    const tail = work.then(() => void 0, () => void 0);
+    policyQueues.set(this.file, tail);
+    void tail.then(() => {
+      if (policyQueues.get(this.file) === tail) policyQueues.delete(this.file);
+    });
+    return work;
+  }
+}
+async function readPolicy(file) {
+  try {
+    await safeParents(file);
+    const info = await lstat(file, { bigint: true });
+    if (!info.isFile() || info.size > BigInt(512 * 1024)) throw new Error("Policy must be a regular file under 512 KiB");
+    const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+      const before = await handle.stat({ bigint: true });
+      if (identity(before) !== identity(info)) throw new Error("Policy changed during inspection");
+      const bytes = await handle.readFile();
+      if (identity(before) !== identity(await handle.stat({ bigint: true })) || bytes.length !== Number(before.size)) throw new Error("Policy changed during inspection");
+      const raw = JSON.parse(bytes.toString("utf8"));
+      if (raw.version !== 1 || !Number.isSafeInteger(raw.revision) || raw.revision < 1) throw new Error("Unsupported retention policy version");
+      return validatePolicy(raw, raw.revision);
+    } finally {
+      await handle.close();
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") return defaults();
+    throw new Error(`Retention policy cannot be read: ${error.message}`);
+  }
+}
+const exists = async (path) => lstat(path).then((info) => info, (error) => error.code === "ENOENT" ? void 0 : Promise.reject(error));
+async function safeParents(path) {
+  for (let folder = dirname(path); ; folder = dirname(folder)) {
+    const info = await lstat(folder);
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("A destination ancestor is a symbolic link or not a directory");
+    if (folder === dirname(folder)) break;
+  }
+}
+function identity(info) {
+  return [String(info.dev), String(info.ino), String(info.mode), String(info.size), String(info.mtimeNs), String(info.ctimeNs)].join(":");
+}
+async function readFingerprint(path, budget, maximum = RETENTION_LIMITS.logBytes) {
+  await safeParents(path);
+  const info = await lstat(path, { bigint: true });
+  if (!info.isFile() || info.isSymbolicLink() || info.size > BigInt(maximum)) throw new Error("Only bounded regular files without symbolic links can be retained");
+  if (++budget.files > RETENTION_LIMITS.files || budget.bytes + Number(info.size) > RETENTION_LIMITS.readBytes) throw new Error("Retention scan reached its file or byte limit");
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (identity(before) !== identity(info)) throw new Error("File changed during retention inspection");
+    const bytes = await handle.readFile();
+    budget.bytes += bytes.length;
+    const after = await handle.stat({ bigint: true });
+    if (identity(before) !== identity(after) || bytes.length !== Number(before.size)) throw new Error("File changed during retention inspection");
+    return { file: { path, bytes: bytes.length, fingerprint: sha(identity(before) + ":" + sha(bytes)) }, text: bytes.toString("utf8"), mtime: Number(before.mtimeMs) };
+  } finally {
+    await handle.close();
+  }
+}
+async function inventory(path, budget) {
+  await safeParents(path);
+  const root = await lstat(path, { bigint: true });
+  if (!root.isDirectory() || root.isSymbolicLink()) throw new Error("Workspace must be a regular directory without symbolic links");
+  const items = [];
+  let bytes = 0, newest = 0;
+  const walk = async (folder) => {
+    const before = await lstat(folder, { bigint: true });
+    items.push(`${relative(path, folder)}:${identity(before)}`);
+    newest = Math.max(newest, Number(before.mtimeMs));
+    for (const name of (await readdir(folder)).sort()) {
+      const file = join(folder, name), info = await lstat(file, { bigint: true });
+      if (++budget.files > RETENTION_LIMITS.files) throw new Error("Retention scan reached its file limit");
+      if (name === ".git" && file !== join(path, ".git")) throw new Error("A nested Git repository or submodule protects this workspace");
+      if (info.isDirectory()) await walk(file);
+      else if (info.isFile()) {
+        items.push(`${relative(path, file)}:${identity(info)}`);
+        bytes += Number(info.size);
+        newest = Math.max(newest, Number(info.mtimeMs));
+      } else if (info.isSymbolicLink()) items.push(`${relative(path, file)}:${identity(info)}:link:${await readlink(file)}`);
+      else throw new Error("A special file protects this workspace");
+    }
+    if (identity(before) !== identity(await lstat(folder, { bigint: true }))) throw new Error("Workspace changed during retention inspection");
+  };
+  await walk(path);
+  return { fingerprint: sha(items.join("\n")), bytes, newest };
+}
+async function runRecord(home, id, budget) {
+  const log = await readFingerprint(join(home, "runs", `${id}.jsonl`), budget);
+  if (!log.text.endsWith("\n")) throw new Error("Incomplete run log; recovery may still need its sources");
+  let run;
+  const reader = new StrictRunLogReader(id);
+  for (let start = 0; start < log.text.length; ) {
+    const end = log.text.indexOf("\n", start), line = log.text.slice(start, end < 0 ? log.text.length : end);
+    start = end < 0 ? log.text.length : end + 1;
+    if (!line.trim()) continue;
+    const value = JSON.parse(line);
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid run event");
+    const event = reader.decode(value);
+    if (event?.type === "run") run = event.run;
+  }
+  if (!run) throw new Error("No authoritative run snapshot");
+  return { run, log: log.file, mtime: log.mtime };
+}
+async function managedRoot(run) {
+  if (!validId(run.id) || typeof run.repo !== "string" || !isAbsolute(run.repo) || typeof run.worktreeDir !== "string") throw new Error("Managed workspace ownership is unavailable");
+  const repo = await realpath(run.repo), expected = resolve(repo, WORKTREE_DIR, run.id);
+  if (resolve(run.worktreeDir) !== expected) throw new Error("Recorded workspace is outside its managed run directory");
+  await safeParents(join(expected, ".context"));
+  const info = await lstat(expected);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Managed run directory is not a regular directory");
+  return expected;
+}
+function terminal(run) {
+  return ["done", "failed", "cancelled"].includes(run.status) && run.archived === true && !run.pinned && !run.retentionPinned && !run.retention?.pinned && !run.followUps?.some((follow) => ["pending", "running"].includes(follow.status)) && !Object.values(run.watches ?? {}).some((watch) => !["closed", "stopped"].includes(watch.state));
+}
+function memoryReferences(run) {
+  return [...(run.memoryManifest?.included ?? []).map((ref) => ref.id), ...(run.team?.contextManifests ?? []).flatMap((manifest) => (manifest.memoryIds ?? []).map((id) => String(id).split("@")[0]))];
+}
+async function previewRetention(input) {
+  const homeInfo = await lstat(input.home);
+  if (!homeInfo.isDirectory() || homeInfo.isSymbolicLink()) throw new Error("Choose a regular application data directory");
+  const home = await realpath(input.home), now = input.now ?? Date.now();
+  if (!Number.isSafeInteger(now) || now < 0) throw new Error("Invalid retention preview time");
+  const policy = await new RetentionPolicyStore(join(home, "retention-policy.json")).get();
+  const cutoffs = Object.fromEntries(KINDS.map((kind) => [kind, policy.days[kind] === null ? null : now - policy.days[kind] * 864e5]));
+  const plan = { version: 1, home, createdAt: now, expiresAt: now + RETENTION_LIMITS.planAgeMs, policyRevision: policy.revision, policy, cutoffs, targets: [], protected: [], sources: {}, truncated: false, fingerprint: "", summary: { archivedRuns: 0, attachments: 0, memory: 0, worktrees: 0, bytes: 0 } };
+  const budget = { files: 0, bytes: 0 }, records = /* @__PURE__ */ new Map(), heldRuns = /* @__PURE__ */ new Map(), heldMemory = /* @__PURE__ */ new Map();
+  const protect = (kind, id, reason) => {
+    if (plan.protected.length < 5e3) plan.protected.push({ kind, id, reason: reason.slice(0, 500) });
+  };
+  const incomplete = (kind, id, error) => {
+    plan.truncated = true;
+    protect(kind, id, error.message);
+  };
+  const target = (value) => {
+    if (plan.targets.length >= RETENTION_LIMITS.targets) {
+      plan.truncated = true;
+      protect(value.kind, value.id, "Retention target limit reached");
+    } else plan.targets.push(value);
+  };
+  const runDirectory = await exists(join(home, "runs"));
+  if (runDirectory) {
+    if (!runDirectory.isDirectory() || runDirectory.isSymbolicLink()) throw new Error("Run storage must be a regular directory without a symbolic link");
+    const files = (await readdir(join(home, "runs"))).filter((file) => file.endsWith(".jsonl") && !file.endsWith(".journal.jsonl")).sort();
+    if (files.length > RETENTION_LIMITS.runs) plan.truncated = true;
+    plan.sources["run-directory"] = sha(files.join("\n"));
+    for (const file of files.slice(0, RETENTION_LIMITS.runs)) {
+      const id = file.slice(0, -6);
+      if (!validId(id)) {
+        incomplete("archivedRuns", id, new Error("Invalid run log name"));
+        continue;
+      }
+      try {
+        const record = await runRecord(home, id, budget);
+        records.set(id, record);
+        plan.sources[record.log.path] = record.log.fingerprint;
+      } catch (error) {
+        incomplete("archivedRuns", id, error);
+      }
+    }
+  }
+  let memory = [];
+  try {
+    const file = join(home, "memory.sqlite"), legacy = join(home, "memory.json");
+    if (await exists(file)) {
+      const before = (await readFingerprint(file, budget)).file.fingerprint;
+      memory = await new MemoryStore(file).maintenanceEntries();
+      const after = (await readFingerprint(file, budget)).file.fingerprint;
+      if (before !== after) throw new Error("Memory changed during retention inspection");
+      plan.sources[file] = after;
+    } else if (await exists(legacy)) {
+      const data = await readFingerprint(legacy, budget, 32 * 1024 * 1024);
+      plan.sources[legacy] = data.file.fingerprint;
+      memory = validateDocument(data.text).entries;
+    }
+    memory = memory.filter((entry) => entry.status !== "deleted");
+    if (memory.length > RETENTION_LIMITS.memory) {
+      plan.truncated = true;
+      memory = memory.slice(0, RETENTION_LIMITS.memory);
+    }
+  } catch (error) {
+    incomplete("memory", "memory-store", error);
+  }
+  for (const id of policy.keepRunIds) heldRuns.set(id, "Kept by the saved retention policy");
+  for (const id of policy.keepMemoryIds) heldMemory.set(id, "Kept by the saved retention policy");
+  for (const { run } of records.values()) {
+    if (run.parentRunId) heldRuns.set(run.parentRunId, `Source of retained child run ${run.id}`);
+    if (run.teamRerun?.parentRunId) heldRuns.set(run.teamRerun.parentRunId, `Pinned baseline for retained rerun ${run.id}`);
+    if (!terminal(run) || policy.keepRunIds.includes(run.id)) for (const id of memoryReferences(run)) heldMemory.set(id, `Referenced by active, resumable or kept run ${run.id}`);
+  }
+  for (const entry of memory) for (const source of entry.derivedFrom) heldMemory.set(source.id, `Provenance source for retained memory ${entry.id}`);
+  try {
+    const file = join(home, "deferred-runs.json");
+    if (await exists(file)) {
+      const data = await readFingerprint(file, budget, 32 * 1024 * 1024);
+      plan.sources[file] = data.file.fingerprint;
+      for (const job of validateDeferredDocument(JSON.parse(data.text)).jobs) if (["queued", "waiting-time", "waiting-provider", "claimed", "unknown"].includes(job.status) && job.run.parentRunId) heldRuns.set(job.run.parentRunId, `Source of pending deferred job ${job.id}`);
+    }
+    const triggerFile = join(home, "triggers.json");
+    if (await exists(triggerFile)) {
+      const data = await readFingerprint(triggerFile, budget, 16 * 1024 * 1024);
+      plan.sources[triggerFile] = data.file.fingerprint;
+      const triggers = JSON.parse(data.text);
+      if (!Array.isArray(triggers)) throw new Error("Invalid automation settings");
+      for (const trigger of triggers) if (trigger?.enabled && typeof trigger.run?.parentRunId === "string") heldRuns.set(trigger.run.parentRunId, "Source of an enabled automation");
+    }
+    const coordinationFile = join(home, "coordinated-changes.json");
+    if (await exists(coordinationFile)) {
+      const data = await readFingerprint(coordinationFile, budget, 32 * 1024 * 1024);
+      plan.sources[coordinationFile] = data.file.fingerprint;
+      for (const job of validateCoordinationDocument(JSON.parse(data.text)).jobs) for (const node of job.nodes) for (const runId of [node.runId, node.result?.runId, ...(node.dependencies ?? []).map((receipt) => receipt.runId)].filter((id) => !!id)) heldRuns.set(runId, `Exact launch, dependency or shipping receipt for retained coordinated change ${job.id}`);
+    }
+    const codeHostFile = join(home, "code-host-operations.json");
+    if (await exists(codeHostFile)) {
+      const data = await readFingerprint(codeHostFile, budget, 512e3);
+      plan.sources[codeHostFile] = data.file.fingerprint;
+      for (const receipt of validateCodeHostDocument(JSON.parse(data.text)).operations) if (receipt.runId) heldRuns.set(receipt.runId, `Exact code host action receipt ${receipt.id}`);
+    }
+  } catch (error) {
+    incomplete("archivedRuns", "pending-launch-sources", error);
+  }
+  for (const entry of memory) {
+    const owner = entry.runId ? records.get(entry.runId)?.run : void 0;
+    let reason = entry.scope === "project" ? "Project knowledge requires individual review and is never bulk-deleted" : entry.tags.includes("pinned") ? "Pinned memory" : heldMemory.get(entry.id);
+    if (!reason && (!owner || !terminal(owner) || heldRuns.has(owner.id))) reason = "Its owner run is active, resumable, kept or unavailable";
+    if (!reason && (cutoffs.memory === null || entry.updatedAt >= cutoffs.memory)) reason = "Memory retention is disabled or this revision is recent";
+    if (reason) protect("memory", entry.id, reason);
+    else {
+      const ref = { id: entry.id, revision: entry.revision };
+      target({ id: `memory:${entry.id}`, kind: "memory", runId: entry.runId, memory: ref, fingerprint: sha(canonical(entry)), bytes: 0, detail: "Erase this old private/team body, retaining its provenance tombstone" });
+    }
+  }
+  const retiringMemory = new Set(plan.targets.filter((item) => item.kind === "memory").map((item) => item.memory.id));
+  for (const entry of memory.filter((entry2) => !retiringMemory.has(entry2.id))) for (const id of [entry.runId, ...entry.origins.map((origin) => origin.runId)].filter((id2) => !!id2)) heldRuns.set(id, `Provenance for retained ${entry.scope} memory ${entry.id}`);
+  for (const [id, { run, log, mtime }] of records) {
+    const reason = !terminal(run) ? "Run is active, resumable, unarchived, pinned or still watched" : heldRuns.get(id);
+    if (reason) {
+      for (const kind of ["archivedRuns", "attachments", "worktrees"]) protect(kind, id, reason);
+      continue;
+    }
+    if (cutoffs.archivedRuns !== null && mtime < cutoffs.archivedRuns) {
+      try {
+        const files = [log];
+        for (const suffix of [".journal.jsonl", ".checkpoint.json", ".cold-index.json", ".cold-detail.json"]) {
+          const path = join(home, "runs", id + suffix);
+          if (await exists(path)) {
+            const file = await readFingerprint(path, budget);
+            if (!suffix.startsWith(".cold-") && file.mtime >= cutoffs.archivedRuns) throw new Error("A recovery record was updated after the retention cutoff");
+            files.push(file.file);
+          }
+        }
+        target({ id: `archivedRuns:${id}`, kind: "archivedRuns", runId: id, files, fingerprint: sha(canonical(files)), bytes: files.reduce((sum, file) => sum + file.bytes, 0), detail: "Delete this archived terminal log, journal and optional checkpoint" });
+      } catch (error) {
+        incomplete("archivedRuns", id, error);
+      }
+    } else protect("archivedRuns", id, "Run-log retention is disabled or the run was recently updated");
+    if (cutoffs.attachments === null && cutoffs.worktrees === null) continue;
+    let managed;
+    try {
+      managed = await managedRoot(run);
+    } catch (error) {
+      protect("attachments", id, error.message);
+      protect("worktrees", id, error.message);
+      continue;
+    }
+    const trees = Array.isArray(run.worktrees) ? run.worktrees : [];
+    if (cutoffs.worktrees !== null) for (const tree of trees) {
+      try {
+        if (typeof tree.path !== "string" || dirname(resolve(tree.path)) !== managed || typeof tree.branch !== "string") throw new Error("Workspace is outside this run's managed directory");
+        if (!await exists(tree.path)) continue;
+        readOnlyGitMetadata(tree.path);
+        const [listing, status, parentTracked, head, flags] = await Promise.all([git(["worktree", "list", "--porcelain", "-z"], run.repo, { timeoutMs: 5e3 }), git(["status", "--porcelain", "--untracked-files=all", "--ignore-submodules=none"], tree.path, { timeoutMs: 5e3 }), inside(run.repo, tree.path) ? git(["--literal-pathspecs", "ls-files", "-z", "--", relative(run.repo, tree.path)], run.repo, { timeoutMs: 5e3 }) : Promise.resolve({ code: 0, stdout: "" }), git(["rev-parse", "--verify", "HEAD"], tree.path, { timeoutMs: 5e3 }), git(["ls-files", "-v", "-z"], tree.path, { timeoutMs: 5e3 })]);
+        const record = listing.stdout.split("\0\0").find((record2) => record2.split("\0").includes(`worktree ${tree.path}`));
+        if (listing.code || !record || !record.split("\0").includes(`branch refs/heads/${tree.branch}`) || record.split("\0").some((field) => /^locked|^prunable/.test(field)) || status.code || status.stdout.trim() || parentTracked.code || parentTracked.stdout.trim() || head.code || flags.code || flags.stdout.split("\0").some((file) => /^[a-zS] /.test(file))) throw new Error("Workspace is dirty, untracked, locked, nested, hides tracked changes or no longer owns its branch");
+        const view = await inventory(tree.path, budget);
+        if (Math.max(mtime, view.newest) >= cutoffs.worktrees) {
+          protect("worktrees", tree.path, "Workspace files or run metadata were updated after the cutoff");
+          continue;
+        }
+        target({ id: `worktrees:${id}:${tree.name ?? tree.branch}`, kind: "worktrees", runId: id, path: tree.path, repo: run.repo, branch: tree.branch, fingerprint: sha(view.fingerprint + ":" + head.stdout.trim()), bytes: view.bytes, detail: "Remove this clean linked workspace without force; its Git branch is preserved" });
+      } catch (error) {
+        protect("worktrees", String(tree.path ?? id), error.message);
+        if (/limit|changed during/.test(error.message)) plan.truncated = true;
+      }
+    }
+    if (cutoffs.attachments !== null) {
+      const folders = [join(managed, ".context", "attachments"), join(managed, ".context", "messages"), ...trees.filter((tree) => typeof tree.path === "string" && dirname(resolve(tree.path)) === managed).flatMap((tree) => [join(tree.path, ".codeflow-context", "attachments"), join(tree.path, ".codeflow-context", "messages")])];
+      for (const folder of folders) {
+        try {
+          const info = await exists(folder);
+          if (!info) continue;
+          await safeParents(join(folder, "placeholder"));
+          if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Attachment storage is not a regular directory");
+          for (const name of (await readdir(folder)).sort()) {
+            const path = join(folder, name);
+            if (plan.targets.some((item) => item.kind === "worktrees" && path.startsWith(item.path + sep))) continue;
+            const data = await readFingerprint(path, budget, 10 * 1024 * 1024);
+            if (Math.max(mtime, data.mtime) >= cutoffs.attachments) {
+              protect("attachments", path, "Attachment or run metadata is recent");
+              continue;
+            }
+            const owner = trees.find((tree) => typeof tree.path === "string" && inside(tree.path, path))?.path ?? run.repo;
+            const tracked = inside(owner, path) ? await git(["--literal-pathspecs", "ls-files", "--error-unmatch", "--", relative(owner, path)], owner, { timeoutMs: 5e3 }) : { code: 1 };
+            if (tracked.code !== 1) {
+              protect("attachments", path, "Tracked or unverified repository material is preserved");
+              continue;
+            }
+            target({ id: `attachments:${id}:${relative(managed, path)}`, kind: "attachments", runId: id, path, files: [data.file], fingerprint: data.file.fingerprint, bytes: data.file.bytes, detail: "Delete this staged upload/message attachment or generated workspace copy" });
+          }
+        } catch (error) {
+          protect("attachments", folder, error.message);
+          if (/limit|changed during/.test(error.message)) plan.truncated = true;
+        }
+      }
+    }
+  }
+  plan.targets.sort((a, b) => a.id.localeCompare(b.id));
+  plan.protected.sort((a, b) => `${a.kind}:${a.id}:${a.reason}`.localeCompare(`${b.kind}:${b.id}:${b.reason}`));
+  for (const item of plan.targets) {
+    plan.summary[item.kind]++;
+    plan.summary.bytes += item.bytes;
+  }
+  plan.fingerprint = sha(canonical({ ...plan, fingerprint: "" }));
+  return plan;
+}
+async function applyRetention(input) {
+  const now = input.now ?? Date.now(), supplied = input.plan;
+  if (!supplied || supplied.version !== 1 || !Number.isSafeInteger(supplied.createdAt) || supplied.createdAt > now + 5e3 || now - supplied.createdAt > RETENTION_LIMITS.planAgeMs || supplied.expiresAt !== supplied.createdAt + RETENTION_LIMITS.planAgeMs || !/^[a-f0-9]{64}$/.test(supplied.fingerprint)) throw new Error("Choose a valid retention preview from the last 24 hours");
+  const info = await lstat(input.home);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Application data directory must be regular");
+  const home = await realpath(input.home);
+  if (home !== supplied.home) throw new Error("Retention preview belongs to a different data directory");
+  const release = await acquireLock(0, home);
+  try {
+    const plan = await previewRetention({ home, now: supplied.createdAt });
+    if (plan.truncated || supplied.truncated) throw new Error("Incomplete retention scans cannot be applied; resolve the protected scan limits or invalid data first");
+    if (plan.fingerprint !== supplied.fingerprint || canonical(plan) !== canonical(supplied)) throw new Error("Data, ownership or policy changed after preview. No changes applied; create and review another preview.");
+    const applied = [], failed = [];
+    const memory = plan.targets.filter((item) => item.kind === "memory");
+    if (memory.length) {
+      await new MemoryStore(join(home, "memory.sqlite")).retireMaintenance(memory.map((item) => item.memory));
+      applied.push(...memory.map((item) => item.id));
+    }
+    for (const item of [...plan.targets.filter((item2) => item2.kind === "worktrees"), ...plan.targets.filter((item2) => item2.kind === "attachments"), ...plan.targets.filter((item2) => item2.kind === "archivedRuns")]) {
+      try {
+        if (item.kind === "worktrees") {
+          await safeParents(item.path);
+          readOnlyGitMetadata(item.path);
+          const current = await inventory(item.path, { files: 0, bytes: 0 }), head = await git(["rev-parse", "--verify", "HEAD"], item.path, { timeoutMs: 5e3 });
+          if (head.code || sha(current.fingerprint + ":" + head.stdout.trim()) !== item.fingerprint) throw new Error("Workspace changed before removal; stopped applying this plan");
+          const removed = await git(["worktree", "remove", "--", item.path], item.repo, { timeoutMs: 3e4 });
+          if (removed.code) throw new Error(removed.stderr.trim() || "Git refused workspace removal");
+        } else for (const file of item.files ?? []) {
+          await safeParents(file.path);
+          const current = await readFingerprint(file.path, { files: 0, bytes: 0 });
+          if (current.file.fingerprint !== file.fingerprint) throw new Error("File changed before deletion; stopped applying this plan");
+          await unlink(file.path);
+        }
+        applied.push(item.id);
+      } catch (error) {
+        failed.push({ id: item.id, reason: error.message });
+        break;
+      }
+    }
+    return { fingerprint: plan.fingerprint, applied, failed, remaining: plan.targets.filter((item) => !applied.includes(item.id)).map((item) => item.id) };
+  } finally {
+    release();
+  }
+}
+export {
+  RETENTION_LIMITS,
+  RetentionPolicyConflictError,
+  RetentionPolicyStore,
+  applyRetention,
+  previewRetention
+};

package/src/review-inbox.js

@@ -0,0 +1,38 @@
+import { checksLabel } from "./run-status.js";
+function reviewReason(run) {
+  const question = run.status === "running" && !!run.team?.awaitingRequestId;
+  if (run.archived || run.projectTeam && !run.awaiting && !question) return;
+  if (run.awaiting || question) return "answer";
+  if (run.team?.status === "blocked") return "blocked";
+  if (!run.seen && (run.status === "failed" || run.status === "interrupted")) return "failed";
+  if (!run.seen && run.status !== "running") {
+    if (checksLabel(run) === "Blocked" || run.status === "stopped") return "blocked";
+    if (checksLabel(run) === "Failed") return "failed";
+  }
+  if (run.triage?.state === "pending") return "review";
+  if (!run.seen && run.status === "done" && run.artifacts?.some((artifact) => artifact.stat?.trim())) return "review";
+}
+const REVIEW_REASON_LABELS = { answer: "Waiting for your answer", blocked: "Blocked work", failed: "Failed checks or execution", review: "Results to review" };
+const reasonOrder = { answer: 0, blocked: 1, failed: 2, review: 3 };
+function prioritizedReviewRuns(runs, input = {}) {
+  const words = (input.query ?? "").trim().toLowerCase().split(/\s+/).filter(Boolean);
+  return runs.filter((run) => {
+    const reason = reviewReason(run);
+    return reason && (!input.reason || reason === input.reason) && words.every((word) => [run.task, run.repo, run.id, run.trigger?.name ?? "", run.source?.title ?? ""].join("\n").toLowerCase().includes(word));
+  }).sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0) || reasonOrder[reviewReason(a)] - reasonOrder[reviewReason(b)] || a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+}
+function groupReviewRuns(runs, key) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const run of runs) {
+    const group = key(run);
+    if (!groups.has(group.id)) groups.set(group.id, { ...group, runs: [] });
+    groups.get(group.id).runs.push(run);
+  }
+  return [...groups.values()];
+}
+export {
+  REVIEW_REASON_LABELS,
+  groupReviewRuns,
+  prioritizedReviewRuns,
+  reviewReason
+};