@jenga-ai/agent 1.0.0

package/lib/commands/init.js

@@ -0,0 +1,207 @@
+import { createInterface } from "readline";
+import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync, readdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateConfig } from "../config-schema.js";
+import { injectSettings } from "../inject-settings.js";
+
+const CONFIG_FILE = "jenga.cli.json";
+
+// This file lives at <package>/lib/commands/init.js — two levels up is the
+// installed jenga-agent package root, which holds templates/ and other
+// framework assets sourced directly from node_modules.
+const __dirname    = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, "..", "..");
+
+async function prompt(rl, question, defaultValue) {
+  return new Promise(resolve => {
+    const hint = defaultValue !== undefined ? ` (default: ${defaultValue})` : "";
+    rl.question(`${question}${hint}: `, answer => {
+      resolve(answer.trim() || String(defaultValue ?? ""));
+    });
+  });
+}
+
+export async function runInit(args, projectRoot = process.cwd()) {
+  const configPath = join(projectRoot, CONFIG_FILE);
+  
+  // Load existing config as defaults if re-running
+  let existing = {};
+  if (existsSync(configPath)) {
+    try {
+      existing = JSON.parse(readFileSync(configPath, "utf8"));
+      console.log(`Found existing ${CONFIG_FILE} — showing current values as defaults.\n`);
+    } catch {
+      console.warn(`Warning: Could not parse existing ${CONFIG_FILE}. Starting fresh.\n`);
+    }
+  } else {
+    console.log("Welcome to Jenga! Let's set up your configuration.\n");
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    // 1. Agent target (supports comma-separated for multiple targets)
+    const validTargets = ["claude", "copilot", "custom"];
+    const existingTargets = existing.agentTarget
+      ? (Array.isArray(existing.agentTarget) ? existing.agentTarget.join(", ") : existing.agentTarget)
+      : "claude";
+    console.log("Agent target options: claude, copilot, custom (comma-separate for multiple, e.g. claude, copilot)");
+    let agentTargetRaw;
+    let parsedTargets;
+    do {
+      agentTargetRaw = await prompt(rl, "Agent target", existingTargets);
+      parsedTargets = agentTargetRaw.split(",").map(s => s.trim()).filter(Boolean);
+      if (!parsedTargets.every(t => validTargets.includes(t))) {
+        console.log('  Please enter valid targets: claude, copilot, custom');
+        parsedTargets = null;
+      }
+    } while (!parsedTargets);
+    const agentTarget = parsedTargets.length === 1 ? parsedTargets[0] : parsedTargets;
+
+    // 2. Skills path — postinstall mirrors skills/ into .claude/skills/ (Claude)
+    // and .agents/skills/ (Copilot / custom). Default reflects the chosen target(s):
+    // a single string for one target, an array for multi-target installs.
+    const skillPathForTarget = (t) => t === "claude" ? ".claude/skills/" : ".agents/skills/";
+    const derivedDefault = (() => {
+      const unique = [...new Set(parsedTargets.map(skillPathForTarget))];
+      return unique.length === 1 ? unique[0] : unique;
+    })();
+    const existingSkillsPath = existing.skillsPath ?? derivedDefault;
+    const skillsDefaultHint = Array.isArray(existingSkillsPath)
+      ? existingSkillsPath.join(", ")
+      : existingSkillsPath;
+    const skillsRaw = await prompt(rl, "Skills directory path(s) (comma-separate for multiple)", skillsDefaultHint);
+    const skillsParsed = skillsRaw.split(",").map(s => s.trim()).filter(Boolean);
+    const skillsPath = skillsParsed.length === 1 ? skillsParsed[0] : skillsParsed;
+
+    // 3. Match threshold
+    const thresholdDefault = existing.matchThreshold ?? 0.75;
+    let matchThreshold;
+    do {
+      const raw = await prompt(rl, "Match confidence threshold (0–1)", thresholdDefault);
+      matchThreshold = parseFloat(raw);
+    } while (isNaN(matchThreshold) || matchThreshold < 0 || matchThreshold > 1);
+
+    // 4. Session timeout (minutes in wizard → ms in config)
+    const timeoutMinutesDefault = existing.sessionTimeout ? existing.sessionTimeout / 60000 : 5;
+    let sessionTimeoutMinutes;
+    do {
+      const raw = await prompt(rl, "Session timeout (minutes)", timeoutMinutesDefault);
+      sessionTimeoutMinutes = parseFloat(raw);
+    } while (isNaN(sessionTimeoutMinutes) || sessionTimeoutMinutes <= 0);
+
+    const config = {
+      agentTarget,
+      skillsPath,
+      matchThreshold,
+      sessionTimeout: Math.round(sessionTimeoutMinutes * 60000),
+    };
+
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+
+    // Assert the written config passes schema validation
+    const validation = validateConfig(config);
+    if (!validation.valid) {
+      throw new Error(`Config validation failed: ${validation.error}`);
+    }
+
+    console.log(`\n✓ Configuration written to ${CONFIG_FILE}`);
+
+    // Ensure .jenga/ is in .gitignore (idempotent)
+    const gitignorePath = join(projectRoot, ".gitignore");
+    const gitignoreEntry = ".jenga/";
+    let gitignoreContent = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
+    if (!gitignoreContent.split("\n").some(line => line.trim() === gitignoreEntry)) {
+      const prefix = gitignoreContent.length > 0 && !gitignoreContent.endsWith("\n") ? "\n" : "";
+      appendFileSync(gitignorePath, `${prefix}${gitignoreEntry}\n`, "utf8");
+    }
+
+    try {
+      await injectSettings(projectRoot);
+    } catch (e) {
+      console.warn(`Warning: Could not register hook in settings.json — ${e.message}`);
+      console.warn("You can register it manually later by running jenga init again.");
+    }
+
+    // Generate .github/copilot-instructions.md from template.
+    // Templates ship inside the jenga-agent package (node_modules/jenga-agent/templates/).
+    // Fall back to a bare `templates/` at the project root only for the dev-repo case.
+    try {
+      const tplCandidates = [
+        join(PACKAGE_ROOT, "templates", "copilot-instructions.md.tpl"),
+        join(projectRoot, "templates", "copilot-instructions.md.tpl"),
+      ];
+      const tplPath = tplCandidates.find(existsSync);
+      if (tplPath) {
+        const tpl = readFileSync(tplPath, "utf8");
+
+        // Build skill list from skillsPath. skillsPath may be a string or an
+        // array (multi-target installs); pick the first existing directory —
+        // mirrored copies hold identical content.
+        const skillsPathList = Array.isArray(config.skillsPath) ? config.skillsPath : [config.skillsPath];
+        const skillsDir = skillsPathList
+          .map(p => join(projectRoot, p))
+          .find(existsSync);
+        let skillLines = [];
+        if (skillsDir) {
+          for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory()) continue;
+            const skillMdPath = join(skillsDir, entry.name, "SKILL.md");
+            let description = "";
+            if (existsSync(skillMdPath)) {
+              const content = readFileSync(skillMdPath, "utf8");
+              const match = content.match(/^description:\s*(.+)$/m);
+              if (match) description = match[1].trim();
+            }
+            skillLines.push(`- **${entry.name}**${description ? `: ${description}` : ""}`);
+          }
+        }
+        const skillList = skillLines.length > 0 ? skillLines.join("\n") : "_No skills found._";
+        const rendered = tpl.replace("{{SKILL_LIST}}", skillList);
+
+        const githubDir = join(projectRoot, ".github");
+        const copilotInstructionsPath = join(githubDir, "copilot-instructions.md");
+
+        if (!existsSync(githubDir)) mkdirSync(githubDir, { recursive: true });
+
+        if (!existsSync(copilotInstructionsPath)) {
+          writeFileSync(copilotInstructionsPath, rendered, "utf8");
+        } else {
+          // Replace only the JENGA block; preserve content outside the markers
+          const existing = readFileSync(copilotInstructionsPath, "utf8");
+          const startMarker = "<!-- JENGA:START -->";
+          const endMarker = "<!-- JENGA:END -->";
+          const startIdx = existing.indexOf(startMarker);
+          const endIdx = existing.indexOf(endMarker);
+
+          // Extract the new JENGA block from rendered template
+          const renderedStart = rendered.indexOf(startMarker);
+          const renderedEnd = rendered.indexOf(endMarker);
+          const newBlock = rendered.slice(renderedStart, renderedEnd + endMarker.length);
+
+          let updated;
+          if (startIdx !== -1 && endIdx !== -1 && startIdx < endIdx) {
+            updated =
+              existing.slice(0, startIdx) +
+              newBlock +
+              existing.slice(endIdx + endMarker.length);
+          } else {
+            // No existing markers — append the block
+            updated = existing + (existing.endsWith("\n") ? "" : "\n") + newBlock + "\n";
+          }
+          writeFileSync(copilotInstructionsPath, updated, "utf8");
+        }
+        console.log("✓ .github/copilot-instructions.md written");
+      }
+    } catch (e) {
+      console.warn(`Warning: Could not write .github/copilot-instructions.md — ${e.message}`);
+    }
+
+    console.log('\nRun `jenga start` to start the router.');
+
+    return config;
+  } finally {
+    rl.close();
+  }
+}

package/lib/commands/start.js

@@ -0,0 +1,16 @@
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "..", "..");
+
+export async function runStart(args, root = projectRoot) {
+  console.log(
+    "The Jenga Router is now started automatically by your AI client (e.g. Claude) when it opens a session.\n" +
+    "\n" +
+    "To set this up for your project, run:\n" +
+    "  jenga attach\n" +
+    "\n" +
+    "Then open a new AI session in this project — the router will start automatically via stdio."
+  );
+}

package/lib/commands/status.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "..", "..");
+
+function formatDuration(ms) {
+  const totalSeconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes > 0) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+
+function readSessionFile() {
+  const sessionFile = join(process.cwd(), ".jenga", "session.json");
+  try {
+    if (!existsSync(sessionFile)) return { skill: null, startedAt: null };
+    return JSON.parse(readFileSync(sessionFile, "utf8"));
+  } catch {
+    return { skill: null, startedAt: null };
+  }
+}
+
+export async function runStatus(args, root = projectRoot) {
+  const pidFile = join(process.cwd(), ".jenga", "router.pid");
+
+  // Check if router is running
+  if (!existsSync(pidFile)) {
+    console.log("Router is not running. Run `jenga start` to start it.");
+    process.exit(0);
+  }
+
+  let pid;
+  try {
+    pid = parseInt(readFileSync(pidFile, "utf8").trim(), 10);
+    process.kill(pid, 0); // throws if not alive
+  } catch {
+    console.log("Router is not running. Run `jenga start` to start it.");
+    process.exit(0);
+  }
+
+  // Read real session state from .jenga/session.json written by the router
+  const session = readSessionFile();
+
+  if (session.skill && session.startedAt) {
+    const elapsed = formatDuration(Date.now() - new Date(session.startedAt).getTime());
+    console.log(`✓ Router running (PID: ${pid}) | Active session: ${session.skill} (${elapsed})`);
+  } else {
+    console.log(`✓ Router running (PID: ${pid}) | No active session`);
+  }
+}

package/lib/config-schema.js

@@ -0,0 +1,72 @@
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+export const configSchema = {
+  type: "object",
+  required: ["skillsPath", "matchThreshold", "sessionTimeout", "agentTarget"],
+  properties: {
+    // Single path (string) or multiple discovery paths (array of strings).
+    // Multi-target installs (e.g. claude + copilot) use an array holding
+    // both .claude/skills/ and .agents/skills/.
+    skillsPath: {
+      oneOf: [
+        { type: "string" },
+        { type: "array", items: { type: "string" }, minItems: 1 }
+      ]
+    },
+    matchThreshold: { type: "number", minimum: 0, maximum: 1 },
+    sessionTimeout: { type: "number", minimum: 0 },
+    agentTarget: {
+      oneOf: [
+        { type: "string", enum: ["claude", "copilot", "custom"] },
+        { type: "array", items: { type: "string", enum: ["claude", "copilot", "custom"] }, minItems: 1 }
+      ]
+    }
+  },
+  additionalProperties: false
+};
+
+export function validateConfig(config) {
+  for (const field of configSchema.required) {
+    if (config[field] === undefined || config[field] === null) {
+      return { valid: false, error: `Missing required field: ${field}` };
+    }
+  }
+  const skillsPathIsString = typeof config.skillsPath === "string";
+  const skillsPathIsArray  = Array.isArray(config.skillsPath)
+    && config.skillsPath.length > 0
+    && config.skillsPath.every(p => typeof p === "string");
+  if (!skillsPathIsString && !skillsPathIsArray) {
+    return { valid: false, error: "skillsPath must be a string or a non-empty array of strings" };
+  }
+  if (typeof config.matchThreshold !== "number" || config.matchThreshold < 0 || config.matchThreshold > 1) {
+    return { valid: false, error: "matchThreshold must be a number between 0 and 1" };
+  }
+  if (typeof config.sessionTimeout !== "number" || config.sessionTimeout < 0) {
+    return { valid: false, error: "sessionTimeout must be a non-negative number" };
+  }
+  const validTargets = ["claude", "copilot", "custom"];
+  const targets = Array.isArray(config.agentTarget) ? config.agentTarget : [config.agentTarget];
+  if (targets.length === 0 || !targets.every(t => validTargets.includes(t))) {
+    return { valid: false, error: 'agentTarget must be one of: "claude", "copilot", "custom" (or an array of those values)' };
+  }
+  return { valid: true };
+}
+
+export function loadConfig(projectRoot = process.cwd()) {
+  const configPath = join(projectRoot, "jenga.cli.json");
+  if (!existsSync(configPath)) {
+    throw new Error(`jenga.cli.json not found at ${configPath}. Run 'jenga init' to create it.`);
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch (e) {
+    throw new Error(`Failed to parse jenga.cli.json: ${e.message}`);
+  }
+  const result = validateConfig(config);
+  if (!result.valid) {
+    throw new Error(result.error);
+  }
+  return config;
+}

package/lib/inject-settings.js

@@ -0,0 +1,61 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join, resolve, dirname } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+
+const HOOK_TYPE = "command";
+// This file lives at <package>/lib/inject-settings.js — one level up is the
+// installed jenga-agent package root, which is where hooks/prompt_router.sh
+// ships. Consumers never need a local copy of the hook script.
+const __dirname   = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, "..");
+
+/**
+ * Injects the Jenga UserPromptSubmit hook into settings.json.
+ * Idempotent — running twice does not duplicate the entry.
+ *
+ * @param {string} projectRoot - project root directory (default: cwd)
+ * @param {boolean} global - if true, target ~/.claude/settings.json instead
+ */
+export async function injectSettings(projectRoot = process.cwd(), global = false) {
+  const settingsDir = global
+    ? join(homedir(), ".claude")
+    : join(projectRoot, ".claude");
+  const settingsPath = join(settingsDir, "settings.json");
+
+  const hookCommand = resolve(PACKAGE_ROOT, "hooks", "prompt_router.sh");
+
+  // Load or create settings
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    } catch (e) {
+      throw new Error(`Failed to parse ${settingsPath}: ${e.message}`);
+    }
+  }
+
+  // Ensure hooks.UserPromptSubmit exists
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.UserPromptSubmit) settings.hooks.UserPromptSubmit = [];
+
+  const hooks = settings.hooks.UserPromptSubmit;
+
+  // Check for existing Jenga entry (idempotency)
+  const alreadyRegistered = hooks.some(
+    (entry) =>
+      Array.isArray(entry.hooks) &&
+      entry.hooks.some((h) => h.type === HOOK_TYPE && h.command === hookCommand)
+  );
+
+  if (!alreadyRegistered) {
+    hooks.push({
+      matcher: "",
+      hooks: [{ type: HOOK_TYPE, command: hookCommand }],
+    });
+  }
+
+  mkdirSync(settingsDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  console.log(`✓ Hook registered in ${settingsPath}`);
+}

package/lib/mirror.js

@@ -0,0 +1,244 @@
+/**
+ * lib/mirror.js — Shared directory-mirroring helper
+ *
+ * Single source of truth for copying an explicit set of top-level entries
+ * (files or directories) from a source root into a destination root. Used
+ * by:
+ *   - scripts/postinstall.js  (consumer install; reconcileDeletes = false)
+ *   - skills/self-sync/...    (in-repo dev mirror; reconcileDeletes = true)   [wired in T02]
+ *
+ * Design constraints:
+ *   - ESM, Node built-ins only (node:fs / node:fs/promises / node:path).
+ *   - Never writes outside `destRoot` — every destination path is boundary-
+ *     checked with a resolved-path comparison.
+ *   - Additive by default. Delete reconciliation only fires when the caller
+ *     explicitly passes `reconcileDeletes: true`.
+ *   - `dryRun` computes the plan (added / overwritten / deleted / skipped)
+ *     without touching the filesystem.
+ */
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+// ── boundary check ────────────────────────────────────────────────────────────
+
+/**
+ * Assert that `child` resolves to a path inside `parent`.
+ * Rejects `..` traversal, symlink escapes, and absolute overrides.
+ * Throws if the invariant is violated.
+ */
+function assertInside(parent, child, label) {
+  const resolvedParent = path.resolve(parent);
+  const resolvedChild = path.resolve(child);
+  const rel = path.relative(resolvedParent, resolvedChild);
+  if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) {
+    return; // inside (rel === '' means child === parent, which is fine)
+  }
+  throw new Error(
+    `mirror: refusing to write outside destRoot (${label}): ${resolvedChild} is outside ${resolvedParent}`
+  );
+}
+
+// ── content comparison ────────────────────────────────────────────────────────
+
+/**
+ * Byte-compare two files. Returns true iff both exist and have identical
+ * contents. Any read error → false (treated as "differs, needs copy").
+ */
+function filesEqual(a, b) {
+  try {
+    const statA = fs.statSync(a);
+    const statB = fs.statSync(b);
+    if (statA.size !== statB.size) return false;
+    const bufA = fs.readFileSync(a);
+    const bufB = fs.readFileSync(b);
+    return bufA.equals(bufB);
+  } catch (_) {
+    return false;
+  }
+}
+
+// ── walk source, classify + copy ──────────────────────────────────────────────
+
+/**
+ * Recursively walk `src` and mirror into `dst`, classifying each file.
+ * Mutates `result` in place. Honors `destRoot` boundary via assertInside.
+ */
+function mirrorEntry(src, dst, destRoot, dryRun, excludeNames, result) {
+  if (!fs.existsSync(src)) return;
+
+  const srcStat = fs.statSync(src);
+
+  if (srcStat.isFile()) {
+    assertInside(destRoot, dst, 'file target');
+    const exists = fs.existsSync(dst);
+    if (!exists) {
+      result.added.push(dst);
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(dst), { recursive: true });
+        fs.copyFileSync(src, dst);
+      }
+    } else if (!filesEqual(src, dst)) {
+      result.overwritten.push(dst);
+      if (!dryRun) {
+        fs.copyFileSync(src, dst);
+      }
+    } else {
+      result.skipped.push(dst);
+    }
+    return;
+  }
+
+  if (srcStat.isDirectory()) {
+    assertInside(destRoot, dst, 'dir target');
+    if (!dryRun) fs.mkdirSync(dst, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+      if (excludeNames.has(entry.name)) continue;
+      mirrorEntry(
+        path.join(src, entry.name),
+        path.join(dst, entry.name),
+        destRoot,
+        dryRun,
+        excludeNames,
+        result
+      );
+    }
+  }
+  // symlinks and other node types are intentionally ignored (parity with
+  // the old bash + node behavior, both of which used plain copy).
+}
+
+// ── delete reconciliation ─────────────────────────────────────────────────────
+
+/**
+ * For each top-level entry in `copySet`, walk the destination subtree and
+ * delete any file/dir that is not present in the source subtree. Records
+ * the deletions in `result.deleted`. Boundary-checked. No-op unless
+ * `reconcileDeletes` was requested by the caller.
+ */
+function reconcileEntry(src, dst, destRoot, dryRun, excludeNames, result) {
+  if (!fs.existsSync(dst)) return;
+
+  const dstStat = fs.statSync(dst);
+
+  // If the source is entirely absent, the whole destination entry is orphaned.
+  if (!fs.existsSync(src)) {
+    assertInside(destRoot, dst, 'orphan delete');
+    result.deleted.push(dst);
+    if (!dryRun) fs.rmSync(dst, { recursive: true, force: true });
+    return;
+  }
+
+  if (!dstStat.isDirectory()) {
+    // File-vs-file mismatches are handled by mirrorEntry; nothing to reconcile.
+    return;
+  }
+
+  const srcExists = fs.existsSync(src) && fs.statSync(src).isDirectory();
+  if (!srcExists) {
+    // src changed type (was a dir, now a file). Delete the whole mirror dir.
+    assertInside(destRoot, dst, 'type-change delete');
+    result.deleted.push(dst);
+    if (!dryRun) fs.rmSync(dst, { recursive: true, force: true });
+    return;
+  }
+
+  const dstEntries = fs.readdirSync(dst, { withFileTypes: true });
+  for (const entry of dstEntries) {
+    // Excluded names in the destination are treated as orphans and pruned —
+    // this is how the mirror recovers from prior copies made before the
+    // exclusion list existed (e.g. legacy `.agents/` nested inside `agents/`).
+    const childDst = path.join(dst, entry.name);
+    const childSrc = path.join(src, entry.name);
+    if (excludeNames.has(entry.name) || !fs.existsSync(childSrc)) {
+      assertInside(destRoot, childDst, 'orphan child delete');
+      result.deleted.push(childDst);
+      if (!dryRun) fs.rmSync(childDst, { recursive: true, force: true });
+    } else if (entry.isDirectory()) {
+      reconcileEntry(childSrc, childDst, destRoot, dryRun, excludeNames, result);
+    }
+  }
+}
+
+// ── public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Mirror an explicit set of top-level entries from `sourceRoot` into `destRoot`.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.sourceRoot        Absolute path to source root.
+ * @param {string}   opts.destRoot          Absolute path to destination root.
+ * @param {string[]} opts.copySet           Relative paths (files or dirs).
+ * @param {boolean} [opts.dryRun=false]     If true, compute plan without writing.
+ * @param {boolean} [opts.reconcileDeletes=false] If true, remove dest files/dirs
+ *                                           not present in source (within copySet).
+ * @param {string[]} [opts.exclude=[]]      Basenames to skip anywhere in the walk
+ *                                           (e.g. ['.agents', '.claude', 'node_modules']).
+ *                                           When reconcileDeletes is on, excluded
+ *                                           basenames present in the destination
+ *                                           are pruned as orphans.
+ * @returns {{added: string[], overwritten: string[], deleted: string[], skipped: string[]}}
+ *          Absolute destination paths grouped by outcome.
+ */
+export function mirror({
+  sourceRoot,
+  destRoot,
+  copySet,
+  dryRun = false,
+  reconcileDeletes = false,
+  exclude = [],
+} = {}) {
+  if (!sourceRoot || typeof sourceRoot !== 'string') {
+    throw new TypeError('mirror: `sourceRoot` must be a non-empty string');
+  }
+  if (!destRoot || typeof destRoot !== 'string') {
+    throw new TypeError('mirror: `destRoot` must be a non-empty string');
+  }
+  if (!Array.isArray(copySet)) {
+    throw new TypeError('mirror: `copySet` must be an array of relative paths');
+  }
+  if (!Array.isArray(exclude)) {
+    throw new TypeError('mirror: `exclude` must be an array of basenames');
+  }
+
+  const resolvedSource = path.resolve(sourceRoot);
+  const resolvedDest = path.resolve(destRoot);
+  const excludeNames = new Set(exclude);
+
+  const result = {
+    added: [],
+    overwritten: [],
+    deleted: [],
+    skipped: [],
+  };
+
+  if (!dryRun) {
+    fs.mkdirSync(resolvedDest, { recursive: true });
+  }
+
+  for (const entry of copySet) {
+    if (typeof entry !== 'string' || entry.length === 0) {
+      throw new TypeError(`mirror: copySet entries must be non-empty strings (got ${JSON.stringify(entry)})`);
+    }
+    // Reject entries that would escape either root.
+    const src = path.join(resolvedSource, entry);
+    const dst = path.join(resolvedDest, entry);
+    assertInside(resolvedSource, src, `copySet source entry "${entry}"`);
+    assertInside(resolvedDest, dst, `copySet dest entry "${entry}"`);
+
+    mirrorEntry(src, dst, resolvedDest, dryRun, excludeNames, result);
+
+    if (reconcileDeletes) {
+      reconcileEntry(src, dst, resolvedDest, dryRun, excludeNames, result);
+    }
+  }
+
+  return result;
+}
+
+// Also export helpers for advanced callers / tests. Not part of the stable API.
+export const __internal = { assertInside, filesEqual };
+
+export default mirror;