@memnexus-ai/mx-agent-cli 0.1.198 → 0.1.199

package/scripts/generate-claude.mjs

@@ -0,0 +1,676 @@
+#!/usr/bin/env node
+/**
+ * generate-claude.mjs — materialize the runtime `.claude/` tree from the single
+ * committed source (a BASE config tree + an OVERLAY tree).
+ *
+ * Direction B, config single-source-of-truth (#4304), Phase 2. This is the
+ * GENERATOR: it takes the one hand-edited config tree and emits the tree the
+ * Claude Code harness actually reads. Phase 2 ships it while `.claude/` is STILL
+ * committed, so the generated output must reproduce the committed `.claude/`
+ * BYTE-FOR-BYTE — running the generator against the repo leaves
+ * `git diff -- .claude/` empty. That empty diff is the proof Phase 2 is a safe
+ * no-op. Phases 3-5 (gate flip, gitignore+untrack, self-heal removal) build on
+ * this once the no-op is proven in the fleet.
+ *
+ * Reproduction manifest (source → .claude/):
+ *   settings.json ← base/settings.json                              (verbatim)
+ *   hooks/        ← base/hooks/*                                    (verbatim content;
+ *                                                                     *.sh → 0755, else 0644)
+ *   rules/        ← base/rules/*                                    (verbatim)
+ *   agents/       ← base/agents/* ∪ overlay/agents/*               (union)
+ *   skills/       ← base/skills/* ∪ overlay/skills/*               (union, recursive)
+ *   commands/     ← overlay/commands/*                             (files verbatim, 0644)
+ *
+ * The hooks chmod rule (every `*.sh` → 0755 regardless of the source blob's
+ * mode) reproduces the historical behavior of `syncClaudeConfig`, which is why
+ * the committed `.claude/hooks/*.sh` are all 0755 even though a couple of source
+ * blobs are 0644.
+ *
+ * SECURITY — NO SYMLINKS, ANYWHERE (PO directive 2026-07-20):
+ *   The generator emits ONLY plain regular files and real directories. It NEVER
+ *   emits a symlink. It FAILS CLOSED — a pre-scan walks the entire source tree
+ *   (base + overlay, every subdir) BEFORE anything is written; if ANY entry is a
+ *   symlink the generator throws and exits non-zero with nothing materialized
+ *   (destRoot is never created). This structurally closes the former
+ *   multi-hop-symlink-chain bypass: there is no link to chase because a link in
+ *   the source is a hard error, and the output can hold no link at all.
+ *
+ *   TWO-LAYER FAILURE MODEL (also documented at each layer):
+ *     • The GENERATOR fails CLOSED on write — a symlink in the source, or a
+ *       managed dest subdir that is itself a symlink, aborts with no partial tree.
+ *       A broken/tampered config must never materialize a `.claude/`.
+ *     • `syncClaudeConfig` (its caller) fails OPEN on availability — if the
+ *       generator cannot run (offline, git archive fails), it leaves the existing
+ *       committed `.claude/` in place rather than blocking the session. The
+ *       committed `.claude/` is the Phase 2 backstop; that backstop disappears at
+ *       Phase 4 (gitignore + untrack), after the no-op is proven in the fleet.
+ *
+ * Pure Node built-ins so it runs directly from a repo checkout with no build
+ * step (post-create.sh / post-start.sh call it via `node`). `--from-git <ref>`
+ * sources agent-config from `git archive <ref>` into a temp dir instead of the
+ * working tree, preserving the tamper-resistant origin/<base> semantics that
+ * `syncClaudeConfig` relies on. NOTE: `mx-agent start` (→ syncClaudeConfig)
+ * sources from origin/<base>, so local UNCOMMITTED agent-config edits are not
+ * previewed by a normal session start — run the generator directly against the
+ * working tree (no `--from-git`) to preview them.
+ *
+ * GENERALIZATION (planned, not built here): the PO intends a future standard
+ * per-project overlay dir (likely `.mx-agent/` at the repo root) so the CLI
+ * behaves identically across memnexus / spearmint / api-evaluator. This is why
+ * the generator takes BASE and OVERLAY as explicit parameters rather than
+ * hardcoding `agent-config/local` — a future caller just points OVERLAY at
+ * `.mx-agent/`. No multi-project behavior is implemented today; the call sites
+ * default OVERLAY to `<base>/local`.
+ */
+
+import {
+  chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync,
+  rmSync, unlinkSync, writeFileSync,
+} from 'fs';
+import { homedir, tmpdir } from 'os';
+import { dirname, join, relative, resolve, sep } from 'path';
+import { pathToFileURL } from 'url';
+import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
+
+/** Managed subdirectories of `.claude/` that the generator owns and prunes. */
+export const MANAGED_SUBDIRS = ['hooks', 'agents', 'skills', 'commands', 'rules'];
+
+/** Repo-relative path that the source `agent-config` tree lives at by default. */
+export const DEFAULT_CONFIG_SOURCE = 'mx-agent-system/agent-config';
+
+// ── small fs helpers ──────────────────────────────────────────────────────
+
+function listDir(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function removeIfPresent(p) {
+  try { lstatSync(p); } catch { return; }
+  unlinkSync(p);
+}
+
+function writeManagedFile(destPath, content, mode) {
+  mkdirSync(dirname(destPath), { recursive: true });
+  // Replace any pre-existing entry (file OR symlink) so a stale symlink/file
+  // never lingers with the wrong type. Then chmod to the exact mode — the git
+  // no-op depends on it (e.g. *.sh must be 0755).
+  removeIfPresent(destPath);
+  writeFileSync(destPath, content);
+  chmodSync(destPath, mode);
+}
+
+// ── FAIL-CLOSED symlink ban (PO directive 2026-07-20) ───────────────────────
+
+/**
+ * Recursively assert that NO entry under `dir` is a symlink. Throws FAIL-CLOSED
+ * on the first symlink found (file OR directory link — a directory symlink is
+ * reported by withFileTypes as isSymbolicLink(), so we never follow it). Called
+ * over the whole source tree BEFORE any write, so a smuggled link aborts the run
+ * with nothing materialized.
+ *
+ * @param dir      absolute path to scan
+ * @param rootRel  human-readable root label for error messages (e.g. 'base')
+ */
+function assertNoSymlinksInTree(dir, rootRel) {
+  for (const ent of listDir(dir)) {
+    const p = join(dir, ent.name);
+    if (ent.isSymbolicLink()) {
+      const rel = relative(dir, p);
+      throw new Error(
+        `generate-claude: FAIL-CLOSED — symlink found in source tree at ` +
+        `${rootRel}/${rel || ent.name}; the generator refuses to emit or follow ` +
+        `symlinks. Replace it with a plain file.`,
+      );
+    }
+    if (ent.isDirectory()) {
+      assertNoSymlinksInTree(p, `${rootRel}/${ent.name}`);
+    }
+  }
+}
+
+/**
+ * Prune guard (Red Team MAJOR 4): before a managed dest subdir is created,
+ * read, or pruned, confirm it is not itself a symlink. If it exists and is a
+ * symlink, FAIL CLOSED — pruning/rewriting through a followed dir symlink could
+ * delete or overwrite files OUTSIDE `.claude/`. Returns the guarded path.
+ */
+function guardManagedDir(destPath) {
+  let st;
+  try { st = lstatSync(destPath); } catch { return destPath; } // absent — nothing to guard
+  if (st.isSymbolicLink()) {
+    throw new Error(
+      `generate-claude: FAIL-CLOSED — managed destination ${destPath} is a symlink; ` +
+      `refusing to mkdir/readdir/prune through it.`,
+    );
+  }
+  return destPath;
+}
+
+/**
+ * Recursively copy a source directory of regular files into dest, forcing file
+ * mode 0644 (config markdown / SKILL.md — no executable bits) and preserving
+ * subdirectory structure. The source tree was already symlink-scanned by
+ * assertNoSymlinksInTree, so any symlink here is a defense-in-depth hard error.
+ */
+function copyFileTree(srcDir, destDir) {
+  for (const ent of listDir(srcDir)) {
+    const s = join(srcDir, ent.name);
+    const d = join(destDir, ent.name);
+    if (ent.isSymbolicLink()) {
+      throw new Error(`generate-claude: FAIL-CLOSED — unexpected symlink in ${srcDir}: ${ent.name}`);
+    } else if (ent.isDirectory()) {
+      // CRITICAL A: guard this nested dest dir before mkdir — a pre-planted
+      // symlink here would be followed by mkdirSync/writeFileSync, letting a
+      // write escape .claude/. lstat + FAIL-CLOSED on an existing dir symlink.
+      guardManagedDir(d);
+      mkdirSync(d, { recursive: true });
+      copyFileTree(s, d);
+    } else if (ent.isFile()) {
+      writeManagedFile(d, readFileSync(s), 0o644);
+    }
+  }
+}
+
+/**
+ * Remove any entry under destDir that is NOT in `expected` (a Set of top-level
+ * names). Keeps the generated tree byte-identical to the manifest across reruns
+ * (idempotence) and drops files removed from the source.
+ */
+function pruneExtras(destDir, expected) {
+  for (const ent of listDir(destDir)) {
+    if (!expected.has(ent.name)) {
+      rmSync(join(destDir, ent.name), { recursive: true, force: true });
+    }
+  }
+}
+
+// ── last-known-good permission-layer cache (Red Team CRITICAL B) ─────────────
+//
+// The boot degrade path must NOT trust the working tree. If the origin fetch of
+// the permission layer fails (offline, or an attacker renames the remote / blocks
+// DNS after committing a weakened settings/hooks to the local checkout), the old
+// behavior kept the LOCAL committed permission layer — handing the attacker their
+// layer on every boot. Instead we cache the last-known-good permission-layer bytes
+// (captured on the most recent successful origin-pinned generation) under
+// ~/.mx-agent/ (same dir syncClaudeConfig uses for hook caching) and degrade to
+// THAT cache, never the working tree.
+//
+// Cache layout: ~/.mx-agent/permission-cache/{settings.json, hooks/*, hash.txt}.
+// hash.txt records a sha256 over the layer; restore recomputes and compares it
+// before trusting the bytes. This is an INTEGRITY check (detects corruption or
+// tamper-in-transit / accidental partial writes), NOT an authenticity check: the
+// hash proves the cache is self-consistent, it does NOT prove the cache came from
+// origin. An actor with $HOME write access can fabricate both the cache and a
+// matching hash — exactly as they could poison the committed checkout — so this
+// cache is an improvement only against checkout-tampering with $HOME untouched. It
+// is NOT a security boundary, consistent with the git-mutation-guard's documented
+// posture (a guardrail against accidental/naive tampering, bypassable by design).
+// The cache is best-effort: a cache write failure never breaks generation.
+
+function permissionCacheDir() {
+  return join(homedir(), '.mx-agent', 'permission-cache');
+}
+
+/** Stable sha256 over a permission layer (settings.json bytes + sorted hooks). */
+function hashPermissionLayer(settingsBytes, hookEntries) {
+  const h = createHash('sha256');
+  h.update('settings\0');
+  h.update(settingsBytes);
+  const sorted = [...hookEntries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  for (const { name, bytes } of sorted) {
+    h.update('\0hook\0');
+    h.update(name);
+    h.update('\0');
+    h.update(bytes);
+  }
+  return h.digest('hex');
+}
+
+/**
+ * Read the permission layer (settings.json + hooks/) from a TRUSTED source dir
+ * (an origin-pinned snapshot). Returns null if there is no settings.json.
+ */
+function readPermissionLayer(srcDir) {
+  const settingsPath = join(srcDir, 'settings.json');
+  if (!existsSync(settingsPath)) return null;
+  const settingsBytes = readFileSync(settingsPath);
+  const hookEntries = [];
+  for (const ent of listDir(join(srcDir, 'hooks'))) {
+    if (!ent.isFile()) continue;
+    hookEntries.push({
+      name: ent.name,
+      bytes: readFileSync(join(srcDir, 'hooks', ent.name)),
+      mode: ent.name.endsWith('.sh') ? 0o755 : 0o644,
+    });
+  }
+  return { settingsBytes, hookEntries };
+}
+
+/**
+ * Refresh the last-known-good permission cache from a TRUSTED source dir. Called
+ * on every successful origin-pinned generation (boot split AND per-session
+ * --from-git). Best-effort — swallows errors so caching never fails a generation.
+ *
+ * Least-privilege (S2): the cache dir is 0700 and every non-executable cache file
+ * (settings.json, hash.txt) is 0600, so a co-tenant without $HOME write access
+ * cannot read or replace it. `.sh` hooks keep 0755 (the generator's normal mode).
+ * This does not change behavior for legitimate flows; it narrows who can poison
+ * the cache, but it is not a security boundary (see the section header).
+ */
+export function refreshPermissionCache(srcDir) {
+  try {
+    const layer = readPermissionLayer(srcDir);
+    if (!layer) return;
+    const cacheDir = permissionCacheDir();
+    const hooksDir = join(cacheDir, 'hooks');
+    // Clean rebuild so a hook removed upstream does not linger in the cache.
+    rmSync(cacheDir, { recursive: true, force: true });
+    mkdirSync(hooksDir, { recursive: true, mode: 0o700 });
+    chmodSync(cacheDir, 0o700);
+    writeFileSync(join(cacheDir, 'settings.json'), layer.settingsBytes);
+    chmodSync(join(cacheDir, 'settings.json'), 0o600);
+    for (const { name, bytes, mode } of layer.hookEntries) {
+      writeFileSync(join(hooksDir, name), bytes);
+      chmodSync(join(hooksDir, name), mode);
+    }
+    writeFileSync(
+      join(cacheDir, 'hash.txt'),
+      hashPermissionLayer(layer.settingsBytes, layer.hookEntries) + '\n',
+    );
+    chmodSync(join(cacheDir, 'hash.txt'), 0o600);
+  } catch { /* cache is best-effort; never break generation */ }
+}
+
+/**
+ * Restore the last-known-good permission layer from cache into destRoot
+ * (settings.json + hooks/). Recomputes and compares the recorded sha256 (an
+ * INTEGRITY gate, not an origin-authenticity gate) before trusting the bytes.
+ * Returns the layer hash on success, or null if no usable/integrity-checked cache
+ * exists — in which case the caller falls back to the UNVERIFIED committed backstop.
+ */
+export function restorePermissionCacheToDest(destRoot) {
+  try {
+    // Enforce the apex invariant locally (Red Team API-safety): this exported
+    // function's first write mkdirs under destRoot; a future direct caller must
+    // not be able to reopen the apex-symlink hole. FAIL-CLOSED → caught → null.
+    guardManagedDir(destRoot);
+    const cacheDir = permissionCacheDir();
+    const cachedSettings = join(cacheDir, 'settings.json');
+    if (!existsSync(cachedSettings)) return null;
+    const settingsBytes = readFileSync(cachedSettings);
+    const hookEntries = [];
+    for (const ent of listDir(join(cacheDir, 'hooks'))) {
+      if (!ent.isFile()) continue;
+      hookEntries.push({
+        name: ent.name,
+        bytes: readFileSync(join(cacheDir, 'hooks', ent.name)),
+        mode: ent.name.endsWith('.sh') ? 0o755 : 0o644,
+      });
+    }
+    // Integrity gate: reject a corrupt/tampered cache rather than write it.
+    // FAIL CLOSED on an ABSENT hash too (S1): a hash-stripped or partially-written
+    // cache is untrustworthy, so null recorded → return null → UNVERIFIED backstop,
+    // never restore unverified bytes.
+    const recorded = existsSync(join(cacheDir, 'hash.txt'))
+      ? readFileSync(join(cacheDir, 'hash.txt'), 'utf-8').trim()
+      : null;
+    const actual = hashPermissionLayer(settingsBytes, hookEntries);
+    if (!recorded || recorded !== actual) return null;
+    // Write the verified bytes into dest. Guard the hooks dir against a
+    // pre-planted symlink (CRITICAL A parity for the degrade path).
+    writeManagedFile(join(destRoot, 'settings.json'), settingsBytes, 0o644);
+    const hooksDest = guardManagedDir(join(destRoot, 'hooks'));
+    mkdirSync(hooksDest, { recursive: true });
+    const names = new Set();
+    for (const { name, bytes, mode } of hookEntries) {
+      writeManagedFile(join(hooksDest, name), bytes, mode);
+      names.add(name);
+    }
+    pruneExtras(hooksDest, names);
+    return actual;
+  } catch {
+    return null;
+  }
+}
+
+// ── the generator ───────────────────────────────────────────────────────────
+
+/**
+ * Generate `.claude/` from a BASE config tree and an OVERLAY tree.
+ *
+ * @param {object} opts
+ * @param {string} opts.baseDir     absolute path to the base config tree
+ *                                   (settings.json, hooks/, rules/, agents/, skills/)
+ * @param {string} opts.overlayDir  absolute path to the per-project overlay tree
+ *                                   (agents/, skills/, commands/). Today this is
+ *                                   `<baseDir>/local`; a future `.mx-agent/` overlay
+ *                                   just points this elsewhere. May not exist.
+ * @param {string} opts.destRoot    absolute path to the `.claude/` dir to write
+ * @param {string} [opts.permissionSrcDir]  alternate source for the PERMISSION
+ *                                   LAYER (settings.json + hooks/) ONLY. Used by
+ *                                   the container-boot split (Red Team CRITICAL 1):
+ *                                   the permission layer comes from a trusted
+ *                                   origin/<base> snapshot while skills/commands/
+ *                                   agents/rules come from `baseDir`/`overlayDir`
+ *                                   (the working tree). Defaults to `baseDir`.
+ * @param {boolean} [opts.skipPermissionLayer]  when true, DO NOT write
+ *                                   settings.json or hooks/ at all — leave whatever
+ *                                   is already on disk (the committed `.claude/`
+ *                                   backstop). Degraded-mode fallback for boot when
+ *                                   the trusted origin snapshot is unavailable
+ *                                   (fresh clone / offline). Never used per-session.
+ */
+export function generateClaudeConfig(opts) {
+  const baseDir = resolve(opts.baseDir);
+  const overlayDir = resolve(opts.overlayDir);
+  const destRoot = resolve(opts.destRoot);
+  const skipPermissionLayer = Boolean(opts.skipPermissionLayer);
+  const permissionSrcDir = opts.permissionSrcDir ? resolve(opts.permissionSrcDir) : baseDir;
+
+  if (!skipPermissionLayer) {
+    const settingsSrc = join(permissionSrcDir, 'settings.json');
+    if (!existsSync(settingsSrc)) {
+      throw new Error(`generate-claude: permission source has no settings.json at ${settingsSrc}`);
+    }
+  }
+
+  // ── FAIL-CLOSED PRE-SCAN ────────────────────────────────────────────────
+  // Walk the ENTIRE source tree (base + overlay + permission source) for symlinks
+  // BEFORE writing anything. On a hit we throw here, so destRoot is never created
+  // and nothing is materialized — the smuggled-symlink test asserts
+  // existsSync(dest)===false. (Scanning baseDir already covers overlayDir /
+  // permissionSrcDir when they live inside baseDir; scan them separately only when
+  // they live outside baseDir.)
+  const insideBase = (p) => p === baseDir || p.startsWith(baseDir + sep);
+  const scanSources = () => {
+    assertNoSymlinksInTree(baseDir, 'base');
+    if (!insideBase(overlayDir) && existsSync(overlayDir)) {
+      assertNoSymlinksInTree(overlayDir, 'overlay');
+    }
+    if (!skipPermissionLayer && !insideBase(permissionSrcDir) && existsSync(permissionSrcDir)) {
+      assertNoSymlinksInTree(permissionSrcDir, 'permission');
+    }
+  };
+  scanSources();
+
+  // CRITICAL (Red Team round 3): guard the dest APEX before creating it. The five
+  // managed subdirs each get guardManagedDir, but destRoot itself was unguarded —
+  // if `.claude` is pre-planted as a symlink, mkdirSync follows it and every
+  // subsequent write escapes the repo. lstat + FAIL-CLOSED on a symlinked apex.
+  guardManagedDir(destRoot);
+  mkdirSync(destRoot, { recursive: true });
+
+  // MINOR (scan-to-copy race hardening): re-scan the source immediately before
+  // the write phase. If a link was planted between the pre-scan and now (TOCTOU),
+  // abort FAIL-CLOSED instead of silently skipping the mutated entry.
+  scanSources();
+
+  // 1. settings.json — verbatim, 0644. From the permission source (origin/<base>
+  //    at boot; baseDir otherwise). Skipped in degraded fallback.
+  if (!skipPermissionLayer) {
+    writeManagedFile(join(destRoot, 'settings.json'), readFileSync(join(permissionSrcDir, 'settings.json')), 0o644);
+  }
+
+  // 2. hooks/ — every file verbatim; *.sh → 0755 (incl. *.test.sh), else 0644.
+  //    Permission layer: from permissionSrcDir. Skipped in degraded fallback.
+  let hookCount = 0;
+  if (!skipPermissionLayer) {
+    const hooksDest = guardManagedDir(join(destRoot, 'hooks'));
+    mkdirSync(hooksDest, { recursive: true });
+    const hookNames = new Set();
+    for (const ent of listDir(join(permissionSrcDir, 'hooks'))) {
+      if (!ent.isFile()) continue;
+      const mode = ent.name.endsWith('.sh') ? 0o755 : 0o644;
+      writeManagedFile(join(hooksDest, ent.name), readFileSync(join(permissionSrcDir, 'hooks', ent.name)), mode);
+      hookNames.add(ent.name);
+    }
+    pruneExtras(hooksDest, hookNames);
+    hookCount = hookNames.size;
+  }
+
+  // 3. rules/ — verbatim, 0644.
+  const rulesDest = guardManagedDir(join(destRoot, 'rules'));
+  mkdirSync(rulesDest, { recursive: true });
+  const ruleNames = new Set();
+  for (const ent of listDir(join(baseDir, 'rules'))) {
+    if (!ent.isFile()) continue;
+    writeManagedFile(join(rulesDest, ent.name), readFileSync(join(baseDir, 'rules', ent.name)), 0o644);
+    ruleNames.add(ent.name);
+  }
+  pruneExtras(rulesDest, ruleNames);
+
+  // 4. agents/ — union of base + overlay, 0644. Overlay overlays base on a
+  //    name collision (last write wins) — by design disjoint today.
+  const agentsDest = guardManagedDir(join(destRoot, 'agents'));
+  mkdirSync(agentsDest, { recursive: true });
+  const agentNames = new Set();
+  for (const src of [join(baseDir, 'agents'), join(overlayDir, 'agents')]) {
+    for (const ent of listDir(src)) {
+      if (!ent.isFile()) continue;
+      writeManagedFile(join(agentsDest, ent.name), readFileSync(join(src, ent.name)), 0o644);
+      agentNames.add(ent.name);
+    }
+  }
+  pruneExtras(agentsDest, agentNames);
+
+  // 5. skills/ — union of base + overlay skill DIRECTORIES, recursive, 0644.
+  const skillsDest = guardManagedDir(join(destRoot, 'skills'));
+  mkdirSync(skillsDest, { recursive: true });
+  const skillNames = new Set();
+  for (const src of [join(baseDir, 'skills'), join(overlayDir, 'skills')]) {
+    for (const ent of listDir(src)) {
+      if (!ent.isDirectory()) continue;
+      const d = join(skillsDest, ent.name);
+      guardManagedDir(d); // CRITICAL A: guard per-skill dir before mkdir
+      mkdirSync(d, { recursive: true });
+      copyFileTree(join(src, ent.name), d);
+      skillNames.add(ent.name);
+    }
+  }
+  pruneExtras(skillsDest, skillNames);
+
+  // 6. commands/ — from overlay/commands only. All regular files now (the former
+  //    mx-find/mx-rules/mx-save SYMLINKS were replaced by plain files), 0644.
+  const commandsSrc = join(overlayDir, 'commands');
+  const commandsDest = guardManagedDir(join(destRoot, 'commands'));
+  mkdirSync(commandsDest, { recursive: true });
+  const commandNames = new Set();
+  for (const ent of listDir(commandsSrc)) {
+    const s = join(commandsSrc, ent.name);
+    const d = join(commandsDest, ent.name);
+    if (ent.isSymbolicLink()) {
+      // Should be unreachable after the pre-scan; kept as defense-in-depth.
+      throw new Error(`generate-claude: FAIL-CLOSED — unexpected symlink in ${commandsSrc}: ${ent.name}`);
+    } else if (ent.isFile()) {
+      writeManagedFile(d, readFileSync(s), 0o644);
+    } else if (ent.isDirectory()) {
+      guardManagedDir(d); // CRITICAL A: guard per-command dir before mkdir
+      mkdirSync(d, { recursive: true });
+      copyFileTree(s, d);
+    }
+    commandNames.add(ent.name);
+  }
+  pruneExtras(commandsDest, commandNames);
+
+  return { destRoot, counts: {
+    hooks: hookCount, rules: ruleNames.size, agents: agentNames.size,
+    skills: skillNames.size, commands: commandNames.size,
+  } };
+}
+
+// ── --from-git: source agent-config from a git ref (tamper-resistant) ────────
+
+/**
+ * Stage `<ref>:<configSource>` into a fresh temp dir via `git archive`, invoke
+ * `fn(baseDir)` with the extracted config tree, and clean up. Throws if the
+ * archive/extract fails (offline, missing ref/path). `git archive` preserves any
+ * committed symlink, so the generator's pre-scan still fails closed on it.
+ */
+function withArchivedConfig(ref, repoRoot, configSource, fn) {
+  const staging = mkdtempSync(join(tmpdir(), 'mx-genclaude-'));
+  try {
+    const archive = spawnSync('git', ['archive', '--format=tar', ref, '--', configSource], {
+      cwd: repoRoot, encoding: 'buffer', maxBuffer: 256 * 1024 * 1024,
+    });
+    if (archive.status !== 0 || !archive.stdout || archive.stdout.length === 0) {
+      const msg = archive.stderr ? archive.stderr.toString() : `git archive ${ref} failed`;
+      throw new Error(`generate-claude: could not archive ${ref}:${configSource} — ${msg.trim()}`);
+    }
+    const extract = spawnSync('tar', ['-x', '-C', staging], { input: archive.stdout });
+    if (extract.status !== 0) {
+      throw new Error(`generate-claude: could not extract archive of ${ref}:${configSource}`);
+    }
+    return fn(join(staging, configSource));
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Materialize the WHOLE `.claude/` tree from `<ref>:<configSource>` (all layers,
+ * including the permission layer, from the reviewed remote). This is the
+ * per-session path used by `syncClaudeConfig` (`mx-agent start`), where an agent
+ * could already be running and the strongest tamper-resistance is required.
+ *
+ * @returns the generator result
+ */
+export function generateClaudeConfigFromGit(opts) {
+  const { ref, repoRoot, destRoot, configSource = DEFAULT_CONFIG_SOURCE } = opts;
+  return withArchivedConfig(ref, repoRoot, configSource, (baseDir) => {
+    const result = generateClaudeConfig({ baseDir, overlayDir: join(baseDir, 'local'), destRoot });
+    // The whole tree (incl. permission layer) came from the reviewed remote —
+    // refresh the last-known-good cache the boot degrade path falls back to.
+    refreshPermissionCache(baseDir);
+    return result;
+  });
+}
+
+/**
+ * CONTAINER-BOOT SPLIT (Red Team CRITICAL 1). Materialize `.claude/` with the
+ * PERMISSION LAYER (settings.json + hooks/) sourced from a trusted
+ * `<permissionRef>` snapshot (origin/<base>), and skills/commands/agents/rules
+ * sourced from the WORKING TREE (`<repoRoot>/<configSource>`). This lets a
+ * container boot refresh behavioral config from local edits while never letting a
+ * tampered working-tree permission layer take effect.
+ *
+ * Fresh-clone / offline fallback: if the `<permissionRef>` snapshot cannot be
+ * staged (no origin, offline, or an attacker blocking the fetch), DEGRADE —
+ * regenerate only the non-permission layers from the working tree and restore the
+ * permission layer from the last-known-good cache (~/.mx-agent/, integrity-checked,
+ * NOT origin-authenticated — Red Team CRITICAL B) rather than trusting the working
+ * tree. If no cache exists, leave the committed `.claude/` settings.json + hooks/ in
+ * place (the Phase 2 backstop) and warn that the permission layer is UNVERIFIED.
+ * Never writes working-tree settings/hooks in the degrade path. Warns; never
+ * hard-fails boot.
+ *
+ * Note on the deny entries in the restored/committed settings.json: they raise the
+ * floor against naive Write/Edit TOOL use of protected paths only — they are not a
+ * Bash-level control and do not constrain shell commands.
+ *
+ * @returns { result, permissionPinned } — permissionPinned=false ⇒ degraded.
+ */
+export function generateClaudeConfigForBoot(opts) {
+  const { permissionRef, repoRoot, destRoot, configSource = DEFAULT_CONFIG_SOURCE, warn } = opts;
+  const baseDir = join(repoRoot, configSource);
+  const overlayDir = join(baseDir, 'local');
+  try {
+    return withArchivedConfig(permissionRef, repoRoot, configSource, (permBase) => {
+      const result = generateClaudeConfig({ baseDir, overlayDir, destRoot, permissionSrcDir: permBase });
+      // Permission layer was origin-pinned — refresh the degrade-path cache.
+      refreshPermissionCache(permBase);
+      return { result, permissionPinned: true };
+    });
+  } catch (err) {
+    // DEGRADE — the origin fetch failed. Do NOT trust the working tree. Regenerate
+    // only the non-permission layers, then restore the permission layer from the
+    // last-known-good cache (integrity-checked, not origin-authenticated). If no
+    // cache exists, leave the committed backstop in place but warn UNVERIFIED.
+    const result = generateClaudeConfig({ baseDir, overlayDir, destRoot, skipPermissionLayer: true });
+    const detail = err instanceof Error ? err.message : String(err);
+    const restoredHash = restorePermissionCacheToDest(destRoot);
+    if (typeof warn === 'function') {
+      if (restoredHash) {
+        warn(`could not origin-pin permission layer from ${permissionRef} (${detail}); ` +
+          `restored last-known-good permission layer from cache, integrity-checked but ` +
+          `NOT origin-authenticated (sha256 ${restoredHash.slice(0, 12)})`);
+      } else {
+        warn(`could not origin-pin permission layer from ${permissionRef} (${detail}); ` +
+          `no integrity-checked cache available — leaving committed settings/hooks in place, ` +
+          `permission layer is UNVERIFIED`);
+      }
+    }
+    return { result, permissionPinned: false };
+  }
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--repo-root') out.repoRoot = argv[++i];
+    else if (a === '--dest') out.dest = argv[++i];
+    else if (a === '--from-git') out.fromGit = argv[++i];
+    else if (a === '--permission-from-git') out.permissionFromGit = argv[++i];
+    else if (a === '--config-source') out.configSource = argv[++i];
+    else if (a === '--quiet') out.quiet = true;
+    else if (a === '--help' || a === '-h') out.help = true;
+  }
+  return out;
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(
+      'Usage: generate-claude.mjs --repo-root <path> [--dest <path>] ' +
+      '[--from-git <ref>] [--permission-from-git <ref>] [--config-source <rel>] [--quiet]\n',
+    );
+    return 0;
+  }
+  const repoRoot = resolve(args.repoRoot || process.cwd());
+  const configSource = args.configSource || DEFAULT_CONFIG_SOURCE;
+  const destRoot = resolve(args.dest || join(repoRoot, '.claude'));
+
+  try {
+    let result;
+    if (args.fromGit) {
+      // Whole tree from the reviewed remote (per-session syncClaudeConfig path).
+      result = generateClaudeConfigFromGit({ ref: args.fromGit, repoRoot, destRoot, configSource });
+    } else if (args.permissionFromGit) {
+      // Container-boot split: permission layer from origin/<base>, rest from the
+      // working tree. Degrades (warns) to committed permission layer when offline.
+      const warn = args.quiet ? undefined : (m) => process.stderr.write(`generate-claude: ${m}\n`);
+      result = generateClaudeConfigForBoot({
+        permissionRef: args.permissionFromGit, repoRoot, destRoot, configSource, warn,
+      }).result;
+    } else {
+      // Working-tree mode: base is <repoRoot>/<configSource>, overlay defaults to
+      // <base>/local (the future `.mx-agent/` overlay would substitute here).
+      const baseDir = join(repoRoot, configSource);
+      const overlayDir = join(baseDir, 'local');
+      result = generateClaudeConfig({ baseDir, overlayDir, destRoot });
+    }
+    if (!args.quiet) {
+      const c = result.counts;
+      process.stderr.write(
+        `generate-claude: wrote .claude/ (hooks=${c.hooks} agents=${c.agents} ` +
+        `skills=${c.skills} commands=${c.commands} rules=${c.rules}) → ${destRoot}\n`,
+      );
+    }
+    return 0;
+  } catch (err) {
+    process.stderr.write(`generate-claude: ${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exit(main(process.argv.slice(2)));
+}