@karajan-family/code 4.21.0

package/library/logical-clocks-lamport.md

@@ -0,0 +1,40 @@
+# Logical clocks & happened-before (Lamport, 1978)
+
+## Problem signature
+
+Events across processes/services need a consistent order, and wall clocks
+disagree: "last write wins" flip-flops between replicas, audit logs interleave
+impossibly, a consumer sees an update before the create it depends on.
+
+## Reach for it when
+
+- Two or more writers/emitters produce events whose CAUSAL order matters
+  (A caused B must never be observed as B before A).
+- You are tempted to "fix it with NTP" or timestamps — clock skew makes
+  timestamp ordering a race, not an order.
+- You need to detect concurrent (conflicting) updates, not just order them:
+  that is the vector-clock extension (one counter per node; compare
+  component-wise; incomparable = concurrent — see Dynamo's usage).
+
+## Do NOT reach for it when
+
+- A single writer (or a single database) already totally orders the events —
+  its sequence/autoincrement/WAL IS the clock. Most CRUD apps live here.
+- You only need "roughly recent first" for humans (feeds, logs for reading):
+  wall-clock timestamps are fine and far simpler.
+- You need a TOTAL order agreed by all nodes: logical clocks give a partial
+  causal order; total order needs consensus (Raft/Paxos) or a sequencer.
+
+## Trade-offs
+
+- Lamport clocks are one counter: tiny, but they cannot tell concurrent from
+  ordered. Vector clocks can, at O(nodes) metadata per event that must be
+  carried, stored and pruned.
+- Causality tracking pushes conflict RESOLUTION to the reader (semantic
+  merge, CRDTs, or ask-the-user) — ordering was the easy half.
+
+## Canonical source
+
+Leslie Lamport, "Time, Clocks, and the Ordering of Events in a Distributed
+System", Communications of the ACM, 1978. The happened-before relation and
+the clock condition come verbatim from it.

package/package.json

@@ -0,0 +1,140 @@
+{
+  "name": "@karajan-family/code",
+  "version": "4.21.0",
+  "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
+  "type": "module",
+  "license": "AGPL-3.0",
+  "author": "manufosela (https://github.com/manufosela)",
+  "homepage": "https://github.com/manufosela/karajan-code#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manufosela/karajan-code.git"
+  },
+  "bugs": {
+    "url": "https://github.com/manufosela/karajan-code/issues"
+  },
+  "keywords": [
+    "ai",
+    "orchestrator",
+    "code-review",
+    "tdd",
+    "sonarqube",
+    "multi-agent",
+    "mcp",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "kj": {
+    "harden": {
+      "exclude": [
+        "wrappers",
+        "packages"
+      ]
+    }
+  },
+  "workspaces": [
+    "packages/ai-trash",
+    "packages/core",
+    "packages/hu-board",
+    "packages/governance"
+  ],
+  "imports": {
+    "#utils/*": "./src/utils/*",
+    "#session/*": "./src/session/*",
+    "#hu/*": "./src/hu/*",
+    "#skills/*": "./src/skills/*"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "library/",
+    "templates/",
+    "scripts/",
+    "vendor/tree-sitter-grammars/",
+    "packages/hu-board/src/",
+    "packages/hu-board/public/",
+    "packages/hu-board/package.json",
+    "packages/ai-trash/src/",
+    "packages/ai-trash/bin/",
+    "packages/ai-trash/package.json",
+    "docs/karajan-code-logo-small.png",
+    "docs/README.es.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "bin": {
+    "kj": "bin/kj.js",
+    "kj-tail": "bin/kj-tail",
+    "kj-trash": "packages/ai-trash/bin/kj-trash.js",
+    "karajan-mcp": "bin/karajan-mcp.js",
+    "kj-rag-mcp": "bin/kj-rag-mcp.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "setup": "node scripts/install.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ packages/",
+    "lint:fix": "eslint src/ packages/ --fix",
+    "lint:syntax": "((command -v rg >/dev/null 2>&1 && rg --files src tests | rg '\\.js$') || find src tests -type f -name '*.js') | while IFS= read -r f; do node --check \"$f\"; done",
+    "format:check": "prettier --check .",
+    "format:fix": "prettier --write .",
+    "typecheck": "npx -p typescript@5 tsc --noEmit -p tsconfig.json",
+    "validate": "npm run lint && npm run lint:syntax && npm test",
+    "mcp": "node src/mcp/server.js",
+    "audit:test-diet": "node scripts/audit-test-diet.mjs",
+    "verify-pack": "node scripts/verify-pack.mjs",
+    "prepublishOnly": "node scripts/verify-pack.mjs",
+    "verify-quickstart": "node scripts/quickstart-gate.mjs"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "npx lint-staged"
+  },
+  "lint-staged": {
+    "src/**/*.js": "eslint --max-warnings=999"
+  },
+  "overrides": {
+    "fast-uri": "^3.1.2"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.7",
+    "@karajan-family/governance": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
+    "chokidar": "^5.0.0",
+    "commander": "^15.0.0",
+    "execa": "^9.6.0",
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.5.0",
+    "helmet": "^8.1.0",
+    "js-yaml": "^4.2.0",
+    "karajan-core": "^1.4.0",
+    "karajan-rag": "^1.2.0",
+    "knip": "^6.15.0",
+    "madge": "^8.0.0",
+    "sqlite-vec": "^0.1.9",
+    "valibot": "^1.4.1",
+    "web-tree-sitter": "^0.26.9",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.4.1",
+    "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-security": "^4.0.0",
+    "globals": "^17.6.0",
+    "lint-staged": "^17.0.7",
+    "postject": "^1.0.0-alpha.6",
+    "prettier": "^3.4.2",
+    "simple-git-hooks": "^2.13.1",
+    "vitest": "^4.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/ai-trash/README.md

@@ -0,0 +1,37 @@
+# @karajan/ai-trash
+
+AI-proof trash: intercept destructive operations from an AI-driven shell
+(`rm -rf`, truncation via `>`, `mv` overwriting, destructive `git` ops, …)
+and snapshot the affected paths to a bin the AI cannot reach before the
+command runs.
+
+Status: **skeleton** — see Karajan epic `KJC-PCS-0041` and the planning
+documents in `docs/ai-trash-fase1-report.md` + `docs/ai-trash-fase2-plan.md`
+of the parent repo.
+
+The MVP is being built incrementally (KJC-TSK-0388). This package currently
+only ships the skeleton (`package.json`, `bin/kj-trash.js`, `src/index.js`).
+
+## Why
+
+Any flow where an LLM has shell access (Claude Code hooks, Cursor, Aider,
+OpenCode, Devin, custom LangChain/AutoGen agents …) shares one risk: the
+agent can issue `rm -rf` on a critical path and there is no undo. `ai-trash`
+puts a snapshot in a place the agent cannot read, write, or `empty` —
+restore is one command away; emptying the bin requires a human factor
+(sudo / TTY / external token).
+
+## Roadmap
+
+1. Manifest + trash-store (ULID, TTL, LRU quota) — KJC-TSK-0388 commit 2
+2. Logger append-only + permissions (linux + macOS) — commit 3
+3. File / directory snapshotter (mv + reflink fallback cp) — commit 4
+4. CLI `list / inspect / restore` + `bin/kj-trash` — commit 5
+5. CLI `empty / purge` with TTY guard — commit 6
+6. Destructive git ops (`reset --hard`, `push --force`, …) — KJC-TSK-0389
+7. Claude Code `PreToolUse` adapter — KJC-TSK-0390
+8. Wiring into `kj doctor` — KJC-TSK-0391
+
+## License
+
+AGPL-3.0 — same as Karajan Code.

package/packages/ai-trash/bin/kj-trash.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.js";
+
+runCli(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    process.stderr.write(`kj-trash: ${err?.message ?? err}\n`);
+    process.exit(1);
+  }
+);

package/packages/ai-trash/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@karajan/ai-trash",
+  "version": "0.0.0",
+  "description": "AI-proof trash: intercept destructive ops from an AI shell and snapshot them to an unreachable bin before execution",
+  "type": "module",
+  "license": "AGPL-3.0",
+  "author": "Manu Fosela",
+  "homepage": "https://github.com/manufosela/karajan-code/tree/main/packages/ai-trash#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manufosela/karajan-code.git",
+    "directory": "packages/ai-trash"
+  },
+  "bugs": {
+    "url": "https://github.com/manufosela/karajan-code/issues"
+  },
+  "keywords": [
+    "ai",
+    "trash",
+    "undo",
+    "snapshot",
+    "safety",
+    "claude-code",
+    "cursor",
+    "aider"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "kj-trash": "bin/kj-trash.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "private": false
+}

package/packages/ai-trash/src/cli.js

@@ -0,0 +1,200 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import {
+  loadManifest,
+  saveManifest,
+  removeEntry,
+  expireBefore,
+  enforceLruQuota,
+} from "./manifest.js";
+import { restoreSnapshot, purgeSnapshot } from "./snapshot.js";
+import { restoreGitBundle } from "./git-snapshot.js";
+import { ensureSecureDir, assertOwnedByCurrentUser } from "./permissions.js";
+import { runHook } from "./hook.js";
+import { installClaudeCodeHook, DEFAULT_SETTINGS_PATH } from "./install.js";
+
+export const DEFAULT_ROOT = process.env.AI_TRASH_ROOT || join(homedir(), ".ai-trash");
+
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const tok = argv[i];
+    if (tok.startsWith("--")) {
+      const eq = tok.indexOf("=");
+      if (eq > -1) flags[tok.slice(2, eq)] = tok.slice(eq + 1);
+      else if (argv[i + 1] && !argv[i + 1].startsWith("--")) flags[tok.slice(2)] = argv[++i];
+      else flags[tok.slice(2)] = true;
+    } else positional.push(tok);
+  }
+  return { positional, flags };
+}
+
+function shortAge(ms) {
+  const sec = Math.max(1, Math.floor(ms / 1000));
+  if (sec < 60) return `${sec}s`;
+  if (sec < 3600) return `${Math.floor(sec / 60)}m`;
+  if (sec < 86400) return `${Math.floor(sec / 3600)}h`;
+  return `${Math.floor(sec / 86400)}d`;
+}
+
+async function ensureRoot(root) {
+  await ensureSecureDir(root);
+  await assertOwnedByCurrentUser(root);
+}
+
+async function cmdList(root, out) {
+  await ensureRoot(root);
+  const m = await loadManifest(root);
+  if (!m.entries.length) {
+    out.write("kj-trash: (empty)\n");
+    return 0;
+  }
+  const now = Date.now();
+  out.write("ID                          AGE   BYTES  SOURCE\n");
+  for (const e of m.entries) {
+    out.write(
+      `${e.id}  ${shortAge(now - e.createdAt).padStart(4)}  ${String(e.sizeBytes).padStart(5)}  ${e.sourcePath}\n`
+    );
+  }
+  return 0;
+}
+
+async function cmdInspect(root, id, out, err) {
+  await ensureRoot(root);
+  const m = await loadManifest(root);
+  const entry = m.entries.find((e) => e.id === id);
+  if (!entry) {
+    err.write(`kj-trash: no entry with id ${id}\n`);
+    return 1;
+  }
+  out.write(`${JSON.stringify(entry, null, 2)}\n`);
+  return 0;
+}
+
+async function cmdRestore(root, id, target, out, err) {
+  await ensureRoot(root);
+  const m = await loadManifest(root);
+  const entry = m.entries.find((e) => e.id === id);
+  if (!entry) {
+    err.write(`kj-trash: no entry with id ${id}\n`);
+    return 1;
+  }
+  if (entry.type === "git-bundle") {
+    const res = await restoreGitBundle(root, entry, target);
+    out.write(
+      `kj-trash: fetched bundle ${id} -> ${res.repo} (${res.refCount} ref(s) at refs/remotes/restore/*)\n`
+    );
+    return 0;
+  }
+  const written = await restoreSnapshot(root, entry, target);
+  removeEntry(m, id);
+  await saveManifest(root, m);
+  out.write(`kj-trash: restored ${id} -> ${written}\n`);
+  return 0;
+}
+
+async function cmdPurge(root, id, out, err) {
+  await ensureRoot(root);
+  const m = await loadManifest(root);
+  const entry = m.entries.find((e) => e.id === id);
+  if (!entry) {
+    err.write(`kj-trash: no entry with id ${id}\n`);
+    return 1;
+  }
+  await purgeSnapshot(root, entry);
+  removeEntry(m, id);
+  await saveManifest(root, m);
+  out.write(`kj-trash: purged ${id}\n`);
+  return 0;
+}
+
+async function cmdEmpty(root, flags, out) {
+  await ensureRoot(root);
+  const m = await loadManifest(root);
+  // Assigned in every branch below (the trailing else covers the default),
+  // so an initializer would never be read (no-useless-assignment).
+  let dropped;
+  if (flags["older-than-days"]) {
+    const days = Number(flags["older-than-days"]);
+    if (!Number.isFinite(days) || days < 0) throw new Error("--older-than-days must be >= 0");
+    dropped = expireBefore(m, Date.now() - days * 86400 * 1000);
+  } else if (flags["max-bytes"]) {
+    const max = Number(flags["max-bytes"]);
+    if (!Number.isFinite(max) || max < 0) throw new Error("--max-bytes must be >= 0");
+    dropped = enforceLruQuota(m, max);
+  } else {
+    dropped = m.entries.slice();
+    m.entries = [];
+  }
+  for (const e of dropped) await purgeSnapshot(root, e);
+  await saveManifest(root, m);
+  out.write(`kj-trash: emptied ${dropped.length} snapshot(s)\n`);
+  return 0;
+}
+
+const HELP =
+  "usage: kj-trash <command> [args]\n" +
+  "  list                       list snapshots oldest-first\n" +
+  "  inspect <id>               print snapshot metadata as JSON\n" +
+  "  restore <id> [--to PATH]   restore a snapshot (default: original path)\n" +
+  "  purge <id>                 delete a single snapshot\n" +
+  "  empty [--older-than-days N | --max-bytes N]\n" +
+  "                             drop all (or filtered) snapshots\n" +
+  "  hook                       Claude Code PreToolUse handler (reads JSON\n" +
+  "                             on stdin, writes decision JSON on stdout)\n" +
+  "  install --claude-code      patch ~/.claude/settings.json (idempotent)\n" +
+  "env: AI_TRASH_ROOT (default ~/.ai-trash)\n";
+
+export async function runCli(argv, io = {}) {
+  const out = io.out ?? process.stdout;
+  const err = io.err ?? process.stderr;
+  const root = io.root ?? DEFAULT_ROOT;
+  const { positional, flags } = parseFlags(argv);
+  const [cmd, arg1] = positional;
+  switch (cmd) {
+    case "list":
+      return cmdList(root, out);
+    case "inspect":
+      if (!arg1) {
+        err.write("kj-trash: inspect requires <id>\n");
+        return 2;
+      }
+      return cmdInspect(root, arg1, out, err);
+    case "restore":
+      if (!arg1) {
+        err.write("kj-trash: restore requires <id>\n");
+        return 2;
+      }
+      return cmdRestore(root, arg1, typeof flags.to === "string" ? flags.to : undefined, out, err);
+    case "purge":
+      if (!arg1) {
+        err.write("kj-trash: purge requires <id>\n");
+        return 2;
+      }
+      return cmdPurge(root, arg1, out, err);
+    case "empty":
+      return cmdEmpty(root, flags, out);
+    case "hook":
+      return runHook({ root, stdin: io.stdin ?? process.stdin, stdout: out });
+    case "install": {
+      if (!flags["claude-code"]) {
+        err.write("kj-trash: install requires --claude-code\n");
+        return 2;
+      }
+      const path = typeof flags.settings === "string" ? flags.settings : DEFAULT_SETTINGS_PATH;
+      const res = await installClaudeCodeHook({ path });
+      out.write(`kj-trash: ${res.mutated ? "installed" : "already installed"} -> ${res.path}\n`);
+      return 0;
+    }
+    case "help":
+    case "--help":
+    case undefined:
+      out.write(HELP);
+      return cmd ? 0 : 2;
+    default:
+      err.write(`kj-trash: unknown command '${cmd}'\n${HELP}`);
+      return 2;
+  }
+}

package/packages/ai-trash/src/destructive-parser.js

@@ -0,0 +1,74 @@
+// Pure classifier for shell commands the PreToolUse hook receives.
+// Recognises the destructive ops ai-trash will snapshot before they run.
+// Conservative: anything unknown is left as safe, but every destructive
+// shape returns kind+paths so the hook can snapshot before letting it run.
+
+function tokenise(command) {
+  if (Array.isArray(command)) return command.filter((t) => typeof t === "string");
+  if (typeof command !== "string") return [];
+  const out = [];
+  let buf = "", quote = null;
+  for (const ch of command) {
+    if (quote) { if (ch === quote) quote = null; else buf += ch; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (ch === " " || ch === "\t" || ch === "\n") { if (buf) { out.push(buf); buf = ""; } continue; }
+    buf += ch;
+  }
+  if (buf) out.push(buf);
+  return out;
+}
+
+function rmFlags(tokens) {
+  const flags = tokens.filter((t) => t.startsWith("-")).join("");
+  return { recursive: flags.includes("r"), force: flags.includes("f") };
+}
+
+function classifyRm(tokens) {
+  const positional = tokens.slice(1).filter((t) => !t.startsWith("-"));
+  const { recursive, force } = rmFlags(tokens.slice(1));
+  return { destructive: true, kind: "rm", recursive, force, paths: positional, reason: "rm removes files" };
+}
+
+function classifyMv(tokens) {
+  const positional = tokens.slice(1).filter((t) => !t.startsWith("-"));
+  if (positional.length < 2) return { destructive: false, kind: "mv-noop", paths: [], reason: "mv without source/target" };
+  return { destructive: true, kind: "mv-overwrite", paths: positional.slice(-1), reason: "mv may overwrite destination" };
+}
+
+function classifyGit(tokens) {
+  const sub = tokens[1];
+  const has = (...flags) => flags.some((f) => tokens.includes(f));
+  if (sub === "reset" && has("--hard")) return { destructive: true, kind: "git-reset-hard", paths: [], reason: "git reset --hard drops working tree" };
+  if (sub === "clean" && has("-f", "-fd", "-xdf")) return { destructive: true, kind: "git-clean", paths: [], reason: "git clean -f removes untracked files" };
+  if (sub === "branch" && has("-D")) return { destructive: true, kind: "git-branch-D", paths: [], reason: "git branch -D drops unmerged branch" };
+  if (sub === "push" && has("--force", "-f", "--force-with-lease")) return { destructive: true, kind: "git-push-force", paths: [], reason: "git push --force rewrites remote history" };
+  if (sub === "checkout" && has("--", ".")) return { destructive: true, kind: "git-checkout-discard", paths: [], reason: "git checkout -- discards local edits" };
+  return { destructive: false, kind: "git-safe", paths: [], reason: "git op without destructive flags" };
+}
+
+function classifyRedirect(tokens) {
+  for (let i = 0; i < tokens.length; i += 1) {
+    if ((tokens[i] === ">" || tokens[i] === ">|") && tokens[i + 1]) {
+      return { destructive: true, kind: "redirect-clobber", paths: [tokens[i + 1]], reason: "> truncates the target file" };
+    }
+  }
+  return null;
+}
+
+export function classifyCommand(command) {
+  const tokens = tokenise(command);
+  if (!tokens.length) return { destructive: false, kind: "empty", paths: [], reason: "no command" };
+  const redirect = classifyRedirect(tokens);
+  if (redirect) return redirect;
+  const head = tokens[0];
+  if (head === "rm") return classifyRm(tokens);
+  if (head === "truncate") {
+    const paths = tokens.slice(1).filter((t) => !t.startsWith("-") && !/^\d+$/.test(t));
+    return { destructive: true, kind: "truncate", paths, reason: "truncate rewrites file size" };
+  }
+  if (head === "mv" || head === "cp") return classifyMv(tokens);
+  if (head === "git") return classifyGit(tokens);
+  return { destructive: false, kind: "safe", paths: [], reason: `head '${head}' not in destructive list` };
+}
+
+export { tokenise };

package/packages/ai-trash/src/git-snapshot.js

@@ -0,0 +1,128 @@
+// Git snapshot primitive (KJC-TSK-0389 commit 1). Captures the full repo
+// state via `git bundle create --all` before a destructive git op runs so
+// the hook can restore lost commits/refs afterwards. The bundle includes
+// every reachable commit + every ref (branches + tags), letting
+// `git fetch --all <bundle>` rebuild HEAD + ref tips even after a
+// `reset --hard`, `branch -D`, or `push --force`.
+
+import { promises as fs } from "node:fs";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { ulid } from "./ulid.js";
+import { ensureSecureDir, lockdownFile } from "./permissions.js";
+import { appendLogEntry } from "./logger.js";
+
+function runGit(args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (b) => (stdout += b.toString("utf8")));
+    child.stderr.on("data", (b) => (stderr += b.toString("utf8")));
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+async function captureRefs(repoDir) {
+  const res = await runGit(["show-ref", "--head"], repoDir);
+  if (res.code !== 0) return [];
+  return res.stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [sha, ref] = line.split(/\s+/, 2);
+      return { sha, ref };
+    });
+}
+
+/**
+ * Snapshot the full state of a git repository as a `.bundle` file so the
+ * pre-op refs can be restored after a destructive op. Returns a manifest
+ * entry shaped like `snapshotFile`'s output so the manifest layer can
+ * store both file and git snapshots side by side.
+ *
+ * @param {string} rootDir - ai-trash root (`<root>/store/<id>/repo.bundle`).
+ * @param {string} repoDir - target git repository.
+ * @param {{command?: string, origin?: string, label?: string}} [options]
+ * @returns {Promise<object>} manifest entry with type=`git-bundle`.
+ */
+export async function snapshotGitBundle(rootDir, repoDir, options = {}) {
+  const insideRepo = await runGit(["rev-parse", "--is-inside-work-tree"], repoDir);
+  if (insideRepo.code !== 0 || insideRepo.stdout.trim() !== "true") {
+    throw new Error(`ai-trash: not a git repo: ${repoDir}`);
+  }
+  const id = ulid();
+  const storeDir = join(rootDir, "store", id);
+  await ensureSecureDir(storeDir);
+  const bundlePath = join(storeDir, "repo.bundle");
+  const bundle = await runGit(["bundle", "create", bundlePath, "--all"], repoDir);
+  if (bundle.code !== 0) {
+    throw new Error(`ai-trash: git bundle failed: ${bundle.stderr.trim()}`);
+  }
+  await lockdownFile(bundlePath);
+  const refs = await captureRefs(repoDir);
+  const stat = await fs.stat(bundlePath);
+  const entry = {
+    id,
+    type: "git-bundle",
+    createdAt: Date.now(),
+    sourcePath: repoDir,
+    snapshotPath: bundlePath,
+    sizeBytes: stat.size,
+    refs,
+    command: options.command ?? null,
+    origin: options.origin ?? "unknown",
+    label: options.label ?? null,
+  };
+  await appendLogEntry(rootDir, "snapshot.git-bundle", {
+    id,
+    repoDir,
+    bundlePath,
+    sizeBytes: stat.size,
+    refCount: refs.length,
+  });
+  return entry;
+}
+
+/**
+ * Replay a `git-bundle` snapshot into a target repository. Runs
+ * `git fetch <bundlePath> +refs/heads/*:refs/remotes/restore/*` so the
+ * pre-op refs land under `restore/*` and can be inspected, checked out,
+ * or `reset --hard`-ed back without clobbering anything in the current
+ * working tree. Leaves the manifest entry intact so repeated fetches
+ * remain possible (the bundle is not deleted).
+ *
+ * @param {string} rootDir - ai-trash root (for audit).
+ * @param {object} entry - manifest entry with type `git-bundle`.
+ * @param {string} [targetRepo] - destination repo (default: entry.sourcePath).
+ * @returns {Promise<{ repo: string, refspec: string, refCount: number }>}
+ */
+export async function restoreGitBundle(rootDir, entry, targetRepo) {
+  if (entry?.type !== "git-bundle") {
+    throw new Error(`ai-trash: not a git-bundle entry: ${entry?.id ?? "<missing>"}`);
+  }
+  const repo = targetRepo ?? entry.sourcePath;
+  const insideRepo = await runGit(["rev-parse", "--is-inside-work-tree"], repo);
+  if (insideRepo.code !== 0 || insideRepo.stdout.trim() !== "true") {
+    throw new Error(`ai-trash: restore target is not a git repo: ${repo}`);
+  }
+  try {
+    await fs.stat(entry.snapshotPath);
+  } catch {
+    throw new Error(`ai-trash: bundle missing on disk: ${entry.snapshotPath}`);
+  }
+  const refspec = "+refs/heads/*:refs/remotes/restore/*";
+  const fetched = await runGit(["fetch", entry.snapshotPath, refspec], repo);
+  if (fetched.code !== 0) {
+    throw new Error(`ai-trash: git fetch failed: ${fetched.stderr.trim()}`);
+  }
+  await appendLogEntry(rootDir, "snapshot.restore-bundle", {
+    id: entry.id,
+    bundlePath: entry.snapshotPath,
+    targetRepo: repo,
+    refCount: entry.refs?.length ?? 0,
+  });
+  return { repo, refspec, refCount: entry.refs?.length ?? 0 };
+}