taskchef 7.29.0 → 8.1.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.29.0",
+  "version": "8.1.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -85,6 +85,21 @@ requested, opens the canonical path with the validated Codex Desktop CLI's
 exact match before indexing it. An open request without a verified native
 project is reported as partial setup, not delegation-ready.
 
+Update one indexed project with taskchef project update; repeated
+--github-repo values replace that entry's complete repository list while
+leaving every other project untouched. project list --json returns stable
+configuration and project-set hashes for postcondition checks.
+
+Whole-index replacement, project removal, and restore are preview-bound. Run
+them with --dry-run, inspect the exact diff, then apply with the returned
+hashes, counts, plan hash, and exact removed-name confirmation after the user
+approves every removed project. TaskChef creates private snapshots under
+backups/ before mutations and actual dashboard startup. Use taskchef backup
+list, create, verify, restore, and prune; restore never runs automatically and
+creates a pre-restore safety snapshot. If the live configuration is missing or
+malformed, preview an explicit config or state restore, then bind the apply to
+the preview's raw-state hash and plan with --confirm-unreadable-current.
+
 Reindexing catches TaskChef up with newly saved Codex projects by comparing
 exact canonical paths and indexing missing requested projects. It preserves
 existing curated entries and does not silently remove projects or overwrite

package/bin/taskchef.js

@@ -5,6 +5,16 @@ import { runCli } from "../src/cli.js";
 try {
   process.exitCode = await runCli(process.argv.slice(2));
 } catch (error) {
-  process.stderr.write(`taskchef: ${error.message}\n`);
+  if (process.argv.includes("--json")) {
+    process.stdout.write(`${JSON.stringify({
+      error: {
+        code: error.code ?? "ERROR",
+        message: error.message,
+        ...(error.details ? { details: error.details } : {}),
+      },
+    })}\n`);
+  } else {
+    process.stderr.write(`taskchef: ${error.message}\n`);
+  }
   process.exitCode = 1;
 }

package/docs/dashboard-lifecycle.md

@@ -67,6 +67,16 @@ elapsed time, not model compute time.
 
 ## Start and reuse
 
+An actual new dashboard server creates or deduplicates a verified private state
+snapshot before monitors or derived-state writers start. Reusing an existing
+listener does not create another startup snapshot. Snapshot failure aborts the
+new server start and does not weaken MCP reporting isolation.
+
+The dashboard watches both task history and the project index. It warns when
+historical task snapshots reference paths absent from the current index, and
+offers recovery-oriented read-only commands. It never mutates or restores
+configuration.
+
 Unless `dashboard.autostart` is explicitly `false`, MCP activation runs the
 same serialized ensure operation exposed by `ensure_dashboard` before the MCP
 transport connects. An explicit ensure remains available when autostart is

package/docs/spec.md

@@ -14,6 +14,8 @@ is dated research, not contract.
 | **Dispatcher workspace** | The per-user local data project selected by `--workspace`, then `TASKCHEF_WORKSPACE`, then `~/.agents/taskchef`. |
 | **Dispatcher** | The Codex task that accepts a request, routes it, records it, creates executors, and returns without supervising them. |
 | **Configured project** | One routing target in `taskchef.json`, identified by canonical local path and described by `name`, optional `description`, `isGitRepository`, and `githubRepos`. |
+| **Mutation preview** | A read-only, hash-bound exact before/after project-index diff required before destructive replacement, removal, or restore. |
+| **State backup** | A private, verified snapshot under the dispatcher workspace's `backups/` directory. It never restores automatically. |
 | **Routing** | Selecting exactly one configured project and exactly one matching native Codex project for an outcome. |
 | **Delegated task** | One independently useful outcome represented by one TaskChef task UUID and snapshot. |
 | **Executor** | The native Codex task created to own and perform one delegated task. |
@@ -124,6 +126,32 @@ from the final derived semantic result. Interrupted outcomes MUST be excluded.
 These projections MUST NOT be persisted in schema 10 and remain compatibility
 aliases for existing callers.
 
+## Project-index mutation and recovery
+
+TaskChef MUST provide a targeted update that preserves every unrelated project
+and replaces an explicitly supplied repository list in full. Project list JSON
+MUST expose stable semantic hashes. Whole-index replacement, project removal,
+and restore MUST first return an exact diff and MUST reject stale hashes,
+incomplete removed-name confirmation, mismatched counts, and unconfirmed large
+count collapse. Agents MUST obtain explicit user permission for every removed
+project entry and verify the complete post-state.
+
+Every actual configuration mutation and actual dashboard-server start MUST
+create or deduplicate a mode-private, manifest-and-hash-verified state snapshot
+before writing. Mutations MUST append bounded attribution-free prepared and
+terminal audit records. Backup list, create, and verify are read-only except for
+explicit creation. Restore MUST default to projects only, show a diff, require
+explicit approval, and create a pre-restore safety snapshot. TaskChef MUST NOT
+restore automatically. State restore authorization MUST bind the selected
+backup and every selected live/source payload hash. Missing or malformed live
+configuration requires config or state scope plus exact raw-state and explicit
+unreadable-current confirmation; a forensic safety snapshot remains eligible
+for rollback when its own integrity verifies.
+
+The dashboard MUST distinguish an unreadable index from missing historical
+project paths, warn without rewriting state, and expose recovery guidance
+without backup payload contents.
+
 ## Optional usage projection
 
 TaskChef MUST pin one tested `ccusage` version as an optional dependency. It

package/docs/workflows.md

@@ -19,6 +19,9 @@ start, upgrade, shutdown, and security rationale.
 | `src/mcp.js` | Dashboard ensure, four primary lifecycle tools, one deprecated alias, MCP cleanup, and annotations. |
 | `src/delegation.js` | UUID marker, concise executor-skill invocation shape, and creation-failure handling. |
 | `src/workspace.js` | Current schemas, validation, locking, atomic JSONL writes, linking, and result freshness. |
+| `src/config-mutations.js` | Canonical hashes and exact field-level project diffs. |
+| `src/backups.js` | Private snapshot creation, verification, retention, and restore inputs. |
+| `src/config-audit.js` | Durable prepared/terminal configuration-mutation journal. |
 | `src/cli.js` | Administration, normalized cached briefs, inspection, diagnostics, and dashboard startup. |
 | `src/dashboard.js` | Versioned health identity, validated compact snapshots, SSE fan-out, on-demand details, and bounded open actions. |
 | `src/dashboard-manager.js` | Concurrent session ensure, authenticated reuse and upgrade handoff, and safe conflicts. |
@@ -428,7 +431,8 @@ after a later filesystem failure, the reported backup is the recovery source.
 Configuration and task mutations use the same `proper-lockfile` lock. ID and
 identity uniqueness checks, link eligibility, and result freshness occur
 inside the critical section. Writes use temporary files/hard links and atomic
-rename so readers see complete snapshots.
+rename so readers see complete snapshots. Configuration replacement syncs the
+new file and workspace directory before its audit transaction is committed.
 
 The dispatcher controls routing and immutable intent. The executor controls its
 cooperatively asserted identity and semantic result. Neither identity nor

package/index.js

@@ -1,6 +1,7 @@
 export {
   buildCopilotBrief,
   addProject,
+  createWorkspaceBackup,
   buildTaskSummary,
   canonicalDirectory,
   canonicalGitRoot,
@@ -12,6 +13,10 @@ export {
   initializeWorkspace,
   linkTask,
   listProjects,
+  listWorkspaceBackups,
+  pruneWorkspaceBackups,
+  readProjectIndex,
+  readWorkspaceMaintenance,
   manuallyTransitionTask,
   migrateTaskLog,
   prepareDispatch,
@@ -23,9 +28,18 @@ export {
   reportTaskResult,
   requireSafeId,
   removeProject,
+  restoreWorkspaceBackup,
   validateConfig,
+  updateProject,
+  verifyWorkspaceBackup,
 } from "./src/workspace.js";
 
+export {
+  configHash,
+  projectDiff,
+  projectSetHash,
+} from "./src/config-mutations.js";
+
 export {
   canonicalGithubRepository,
   matchProjectForGithubUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.29.0",
+  "version": "8.1.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",

package/skills/taskchef-bootstrap/SKILL.md

@@ -15,8 +15,9 @@ all deterministic workspace operations.
 ## Boundaries
 
 - Keep implementation, tests, and reports in the TaskChef source repository.
-- Create and manage only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` in a
-  dispatcher workspace. Preserve unrelated user-owned paths.
+- Create and manage only AGENTS.md, taskchef.json, tasks.jsonl,
+  config-audit.jsonl, and TaskChef's private backups and maintenance artifacts
+  in a dispatcher workspace. Preserve unrelated user-owned paths.
 - Do not dispatch tasks or report on executor threads during bootstrap unless
   the user separately requests those actions.
 - Never create hooks, schedules, polling, daemons, login items, or system
@@ -55,7 +56,10 @@ all deterministic workspace operations.
 For adding, importing, removing, listing, or reindexing projects, read
 [project index](references/project-index.md). Preserve exact canonical local
 Codex project identity and existing curated entries; opening a folder is not
-proof of registration. Completion requires verifying the intended index entry.
+proof of registration. Completion requires verifying the intended index entry
+and the complete project set. Any operation that removes a project entry
+requires the user's explicit permission for the exact removed names; removing a
+repository URL from an entry does not authorize removing the entry.
 
 ## Optional model roles
 

package/skills/taskchef-bootstrap/references/project-index.md

@@ -85,6 +85,18 @@ requires an explicit user request and the project-management workflows below.
 
 ## Manage the project index
 
+Before every mutation, run project list --json and retain the complete
+normalized project set, count, and configHash. Use project update for changes
+to one existing entry, including replacing its complete githubRepos list.
+Never use whole-index replacement to edit one entry.
+
+Run destructive replacement or removal first with --dry-run. Present the
+complete diff and exact removed project names to the user and obtain explicit
+permission for those removals. Apply only with the preview's config hash,
+before/after counts, plan hash, exact removed-name JSON file, and count-collapse
+confirmation when requested. A request to remove a repository URL is not
+permission to remove a project entry. Do not use a generic force or yes flag.
+
 1. Bulk import with `project import <file|-> --json`. Input is a JSON array of
    objects containing `path` plus optional `name`, `description`, and
    `githubRepos`, which is always a JSON array of GitHub repository URLs. Before
@@ -94,9 +106,15 @@ requires an explicit user request and the project-management workflows below.
    canonical path, preserves an existing name or description when omitted, and
    unions existing and imported repository lists without duplicates. Use
    `--replace` only when the user explicitly requests replacement. Run
-   `project list --json` afterward and verify every imported entry.
-2. Inspect indexed projects with `project list --json`. Remove by name with
-   `project remove`. Existing task entries keep their project snapshots.
+   `project list --json` afterward and compare the complete project set with the
+   expected post-state. Verify every imported entry and prove all unrelated
+   entries are unchanged; matching counts alone are insufficient.
+2. Inspect indexed projects with project list --json. Update one entry with
+   project update; explicit repository arguments are the complete replacement
+   list. Remove by name only through the preview-bound workflow. Existing task
+   entries keep their project snapshots.
+3. On any postcondition mismatch, stop, report the failure, and offer backup
+   list plus a restore dry-run. Never restore automatically.
 
 Example managed-workspace import entry:
 

package/skills/taskchef-copilot/SKILL.md

@@ -58,6 +58,8 @@ cached brief.
   preserve its durable identity.
 - Never automatically retry a failure, interrupt a working task, or redelegate
   an existing executor as a new task.
+- Explain project-index warnings and suggest read-only backup list, verify, or
+  restore-preview commands. Never restore state without explicit user approval.
 - A missing executor link calls for passive waiting or identity inspection,
   not a retry, continuation, or reason to create another executor.
 - Keep same-assignment follow-up in the existing executor task. Independent new

package/skills/taskchef-dashboard/SKILL.md

@@ -16,5 +16,9 @@ Maintain only the canonical TaskChef dashboard.
    navigate to it. Browser absence, refusal, or blocked localhost navigation is
    non-fatal: still return the clickable URL and the ensure result.
 
+“Recover the dashboard” means restore server availability. Data recovery uses
+the explicit taskchef backup restore --dry-run workflow, shows a diff, requires
+user approval, and never runs automatically.
+
 Do not dispatch project work, read task briefs, inspect executor outcomes, poll,
 start a separate foreground CLI server, or modify TaskChef workspace files.

package/skills/taskchef-delegate/SKILL.md

@@ -30,8 +30,9 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 
 ## Boundaries
 
-- Treat only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` as TaskChef-managed
-  dispatcher files. Preserve unrelated user-owned paths.
+- Treat only AGENTS.md, taskchef.json, tasks.jsonl, config-audit.jsonl, and
+  TaskChef's private backups and maintenance artifacts as managed dispatcher
+  state. Preserve unrelated user-owned paths.
 - Use real Codex tasks, never collaboration or subagent tools.
 - Never use hooks, schedules, daemons, background monitors, recent-task
   searches, transcripts, hidden reasoning, or polling for identity.

package/src/backups.js

@@ -0,0 +1,359 @@
+import { randomUUID } from "node:crypto";
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { sha256, semanticHash, taskChefError } from "./state-store.js";
+import { TASKCHEF_VERSION } from "./version.js";
+
+export const BACKUP_FILES = ["taskchef.json", "tasks.jsonl", "AGENTS.md", "config-audit.jsonl"];
+const MAX_BACKUP_BYTES = 512 * 1024 * 1024;
+const MAX_SOURCE_FILE_BYTES = 64 * 1024 * 1024;
+
+async function privateDirectory(directory) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const details = await lstat(directory);
+  if (!details.isDirectory() || details.isSymbolicLink()) {
+    throw taskChefError("BACKUP_FAILED", `backup path is not a real directory: ${directory}`);
+  }
+  if (typeof process.getuid === "function" && details.uid !== process.getuid()) {
+    throw taskChefError("BACKUP_FAILED", `backup path is not owned by the current user: ${directory}`);
+  }
+  await chmod(directory, 0o700);
+}
+
+async function filePayload(workspace, name, validateFile) {
+  const filePath = path.join(workspace, name);
+  try {
+    const details = await lstat(filePath);
+    if (!details.isFile() || details.isSymbolicLink()) {
+      throw taskChefError("BACKUP_FAILED", `managed state is not a regular file: ${filePath}`);
+    }
+    if (details.size > MAX_SOURCE_FILE_BYTES) {
+      throw taskChefError("BACKUP_FAILED", `managed state exceeds the backup size limit: ${filePath}`);
+    }
+    const bytes = await readFile(filePath);
+    let valid = true;
+    try {
+      if (name === "taskchef.json") {
+        const config = JSON.parse(bytes.toString("utf8"));
+        valid = config?.schemaVersion === 2 && Array.isArray(config.projects);
+      } else if (name.endsWith(".jsonl")) {
+        for (const line of bytes.toString("utf8").trimEnd().split("\n")) {
+          if (line) JSON.parse(line);
+        }
+      }
+      if (validateFile) await validateFile(name, bytes);
+    } catch {
+      valid = false;
+    }
+    return { present: true, size: bytes.length, sha256: sha256(bytes), bytes, valid };
+  } catch (error) {
+    if (error.code === "ENOENT") return { present: false, size: 0, sha256: null, bytes: null };
+    throw error;
+  }
+}
+
+async function readManifest(snapshotPath) {
+  const manifest = JSON.parse(await readFile(path.join(snapshotPath, "manifest.json"), "utf8"));
+  if (manifest.schemaVersion !== 1 || manifest.workspace.length === 0) {
+    throw new Error("unsupported backup manifest");
+  }
+  return manifest;
+}
+
+export async function verifyBackup(workspace, id) {
+  if (!/^[0-9TZ.-]+-[0-9a-f-]{36}$/i.test(id)) throw new Error("invalid backup ID");
+  const snapshotPath = path.join(workspace, "backups", id);
+  let manifest = null;
+  try {
+    const snapshotDetails = await lstat(snapshotPath);
+    if (!snapshotDetails.isDirectory() || snapshotDetails.isSymbolicLink()
+        || (snapshotDetails.mode & 0o077) !== 0
+        || (typeof process.getuid === "function" && snapshotDetails.uid !== process.getuid())) {
+      throw new Error("backup snapshot permissions or ownership are unsafe");
+    }
+    manifest = await readManifest(snapshotPath);
+    if (manifest.workspace !== workspace) throw new Error("backup belongs to a different workspace");
+    if (manifest.id !== id) throw new Error("backup manifest ID does not match its directory");
+    const snapshotNames = await readdir(snapshotPath);
+    const allowedNames = new Set(["manifest.json", ...BACKUP_FILES.filter(
+      (name) => manifest.files?.[name]?.present,
+    )]);
+    const unexpected = snapshotNames.find((name) => !allowedNames.has(name));
+    if (unexpected) throw new Error(`backup contains an unexpected payload: ${unexpected}`);
+    for (const name of BACKUP_FILES) {
+      const expected = manifest.files[name];
+      if (!expected) throw new Error(`manifest is missing ${name}`);
+      if (!expected.present) continue;
+      const details = await lstat(path.join(snapshotPath, name));
+      if (!details.isFile() || details.isSymbolicLink() || (details.mode & 0o077) !== 0
+          || (typeof process.getuid === "function" && details.uid !== process.getuid())) {
+        throw new Error(`backup payload permissions are unsafe: ${name}`);
+      }
+      const bytes = await readFile(path.join(snapshotPath, name));
+      if (bytes.length !== expected.size || sha256(bytes) !== expected.sha256) {
+        throw new Error(`backup payload failed verification: ${name}`);
+      }
+    }
+    const manifestDetails = await lstat(path.join(snapshotPath, "manifest.json"));
+    if (!manifestDetails.isFile() || manifestDetails.isSymbolicLink()
+        || (manifestDetails.mode & 0o077) !== 0
+        || (typeof process.getuid === "function" && manifestDetails.uid !== process.getuid())) {
+      throw new Error("backup manifest permissions are unsafe");
+    }
+    if (manifest.validationStatus !== "valid") {
+      return {
+        id,
+        usable: false,
+        integrityValid: true,
+        path: snapshotPath,
+        manifest,
+        error: "backup contains invalid source state and is forensic-only",
+      };
+    }
+    return { id, usable: true, integrityValid: true, path: snapshotPath, manifest };
+  } catch (error) {
+    return {
+      id,
+      usable: false,
+      integrityValid: false,
+      path: snapshotPath,
+      ...(manifest ? { manifest } : {}),
+      error: error.message,
+    };
+  }
+}
+
+export async function listBackups(workspace) {
+  const root = path.join(workspace, "backups");
+  const entries = await readdir(root, { withFileTypes: true }).catch((error) => {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  });
+  const backups = [];
+  for (const entry of entries.filter((item) => item.isDirectory() && !item.name.startsWith(".tmp-"))) {
+    backups.push(await verifyBackup(workspace, entry.name));
+  }
+  backups.sort((left, right) => right.id.localeCompare(left.id));
+  const backupBytes = (item) => item.manifest?.files
+    ? Object.values(item.manifest.files)
+      .reduce((sum, file) => sum + (file.present ? file.size : 0), 0)
+    : 0;
+  const usableBytes = backups.filter((item) => item.usable)
+    .reduce((sum, item) => sum + backupBytes(item), 0);
+  const forensicBytes = backups.filter((item) => item.integrityValid && !item.usable)
+    .reduce((sum, item) => sum + backupBytes(item), 0);
+  const corruptBytes = backups.filter((item) => !item.integrityValid)
+    .reduce((sum, item) => sum + backupBytes(item), 0);
+  return {
+    schemaVersion: 1,
+    backupCount: backups.length,
+    usableCount: backups.filter((item) => item.usable).length,
+    forensicCount: backups.filter((item) => item.integrityValid && !item.usable).length,
+    corruptCount: backups.filter((item) => !item.integrityValid).length,
+    usableBytes,
+    forensicBytes,
+    corruptBytes,
+    totalBytes: usableBytes + forensicBytes + corruptBytes,
+    backups,
+  };
+}
+
+export async function createBackupUnlocked(workspace, {
+  reason = "manual",
+  now = () => new Date().toISOString(),
+  validateFile = null,
+} = {}) {
+  const root = path.join(workspace, "backups");
+  await privateDirectory(root);
+  const payloads = Object.fromEntries(await Promise.all(BACKUP_FILES.map(async (name) => [
+    name, await filePayload(workspace, name, validateFile),
+  ])));
+  const aggregateHash = semanticHash(Object.fromEntries(
+    BACKUP_FILES.map((name) => [name, {
+      present: payloads[name].present,
+      size: payloads[name].size,
+      sha256: payloads[name].sha256,
+    }]),
+  ), "taskchef-backup-v1");
+  const existing = (await listBackups(workspace)).backups.find(
+    (item) => item.usable && item.manifest.aggregateHash === aggregateHash,
+  );
+  if (existing) return { ...existing, deduplicated: true, reason };
+
+  const timestamp = now().replaceAll(":", "-").replaceAll(".", "-");
+  const id = `${timestamp}-${randomUUID()}`;
+  const staging = path.join(root, `.tmp-${id}`);
+  const destination = path.join(root, id);
+  await mkdir(staging, { mode: 0o700 });
+  try {
+    const files = {};
+    for (const name of BACKUP_FILES) {
+      const payload = payloads[name];
+      files[name] = {
+        present: payload.present,
+        size: payload.size,
+        sha256: payload.sha256,
+        valid: payload.present ? payload.valid : null,
+      };
+      if (!payload.present) continue;
+      const handle = await open(path.join(staging, name), "wx", 0o600);
+      try {
+        await handle.writeFile(payload.bytes);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+    }
+    let projectCount = null;
+    let configSchemaVersion = null;
+    let taskCount = null;
+    try {
+      const config = JSON.parse(payloads["taskchef.json"].bytes.toString("utf8"));
+      projectCount = Array.isArray(config.projects) ? config.projects.length : null;
+      configSchemaVersion = config.schemaVersion ?? null;
+    } catch {}
+    if (payloads["tasks.jsonl"].present && payloads["tasks.jsonl"].valid) {
+      taskCount = payloads["tasks.jsonl"].bytes.toString("utf8").trimEnd().split("\n")
+        .filter(Boolean).length;
+    }
+    const manifest = {
+      schemaVersion: 1,
+      id,
+      createdAt: now(),
+      reason,
+      taskChefVersion: TASKCHEF_VERSION,
+      workspace,
+      aggregateHash,
+      validationStatus: Object.values(payloads)
+        .every((payload) => !payload.present || payload.valid) ? "valid" : "invalid",
+      configSchemaVersion,
+      projectCount,
+      taskCount,
+      auditBoundary: payloads["config-audit.jsonl"].present
+        ? payloads["config-audit.jsonl"].sha256
+        : null,
+      files,
+    };
+    const manifestHandle = await open(path.join(staging, "manifest.json"), "wx", 0o600);
+    try {
+      await manifestHandle.writeFile(`${JSON.stringify(manifest, null, 2)}\n`);
+      await manifestHandle.sync();
+    } finally {
+      await manifestHandle.close();
+    }
+    const stagingHandle = await open(staging, "r");
+    try { await stagingHandle.sync(); } finally { await stagingHandle.close(); }
+    await rename(staging, destination);
+    const rootHandle = await open(root, "r");
+    try { await rootHandle.sync(); } finally { await rootHandle.close(); }
+    const verified = await verifyBackup(workspace, id);
+    if (!verified.usable && !verified.integrityValid) throw new Error(verified.error);
+    if (!verified.usable) {
+      return { ...verified, deduplicated: false, forensic: true, reason };
+    }
+    const retention = await pruneBackupsUnlocked(workspace, { apply: true });
+    return {
+      ...verified,
+      deduplicated: false,
+      reason,
+      storagePressure: retention.remainingBytes > MAX_BACKUP_BYTES,
+    };
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true }).catch(() => {});
+    throw taskChefError("BACKUP_FAILED", `backup creation failed: ${error.message}`);
+  }
+}
+
+export async function pruneBackupsUnlocked(workspace, { apply = false } = {}) {
+  const inventory = await listBackups(workspace);
+  const usable = inventory.backups.filter((item) => item.usable);
+  const preferred = new Set(usable.slice(0, 30).map((item) => item.id));
+  const daily = new Set();
+  const newestTime = usable.length > 0 ? Date.parse(usable[0].manifest.createdAt) : 0;
+  for (const item of usable) {
+    const day = item.manifest.createdAt.slice(0, 10);
+    const dayTime = Date.parse(`${day}T00:00:00.000Z`);
+    const ageDays = Math.floor((newestTime - dayTime) / 86_400_000);
+    if (ageDays >= 0 && ageDays < 30 && !daily.has(day)) {
+      daily.add(day);
+      preferred.add(item.id);
+    }
+  }
+  let totalBytes = 0;
+  for (const item of usable) {
+    totalBytes += Object.values(item.manifest.files).reduce((sum, file) => sum + file.size, 0);
+  }
+  const protectedIds = new Set(usable.slice(0, 1).map((item) => item.id));
+  const preRestore = usable.find((item) => item.manifest.reason === "pre-restore");
+  if (preRestore) protectedIds.add(preRestore.id);
+  const audit = await readFile(path.join(workspace, "config-audit.jsonl"), "utf8").catch(() => "");
+  const transactions = new Map();
+  for (const line of audit.trimEnd().split("\n")) {
+    if (!line) continue;
+    try {
+      const record = JSON.parse(line);
+      if (record.transactionId) transactions.set(record.transactionId, record);
+    } catch {}
+  }
+  for (const record of transactions.values()) {
+    if (new Set(["prepared", "recovery-required"]).has(record.phase) && record.backupId) {
+      protectedIds.add(record.backupId);
+    }
+  }
+  const candidates = [
+    ...usable.filter((item) => !preferred.has(item.id)).reverse(),
+    ...usable.filter((item) => preferred.has(item.id)).reverse(),
+  ].filter((item, index, items) =>
+    !protectedIds.has(item.id) && items.findIndex((candidate) => candidate.id === item.id) === index);
+  const removed = [];
+  for (const item of candidates) {
+    if (preferred.has(item.id) && totalBytes <= MAX_BACKUP_BYTES) continue;
+    const bytes = Object.values(item.manifest.files).reduce((sum, file) => sum + file.size, 0);
+    if (apply) await rm(item.path, { recursive: true });
+    totalBytes -= bytes;
+    removed.push(item.id);
+  }
+  return { schemaVersion: 1, apply, removed, remainingBytes: totalBytes };
+}
+
+export async function readBackupConfig(workspace, id) {
+  const verified = await verifyBackup(workspace, id);
+  if (!verified.usable) throw taskChefError("BACKUP_FAILED", verified.error);
+  const entry = verified.manifest.files["taskchef.json"];
+  if (!entry.present) throw taskChefError("BACKUP_FAILED", "backup has no taskchef.json");
+  return JSON.parse(await readFile(path.join(verified.path, "taskchef.json"), "utf8"));
+}
+
+export async function readBackupPayloads(workspace, id, names, {
+  allowForensic = false,
+  allowMissing = false,
+} = {}) {
+  const verified = await verifyBackup(workspace, id);
+  if (!verified.usable && !(allowForensic && verified.integrityValid)) {
+    throw taskChefError("BACKUP_FAILED", verified.error);
+  }
+  const payloads = {};
+  for (const name of names) {
+    if (!BACKUP_FILES.includes(name)) throw taskChefError("INVALID_INPUT", "unsupported backup payload");
+    if (!verified.manifest.files[name].present) {
+      if (allowMissing) {
+        payloads[name] = null;
+        continue;
+      }
+      throw taskChefError("BACKUP_FAILED", `backup has no ${name}`);
+    }
+    payloads[name] = await readFile(path.join(verified.path, name));
+  }
+  return { verified, payloads };
+}