@fro.bot/systematic 3.4.0 → 3.5.0

package/dist/cli.js

@@ -6,18 +6,1219 @@ import {
   findCommandsInDir,
   findSkillsInDir,
   getConfigPaths,
+  loadConfigWithSources,
   modify,
   parse,
+  parseFrontmatter,
   parseTree
-} from "./index-0vm17gwv.js";
+} from "./index-1mb4baxr.js";
 
 // src/cli.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs4 from "fs";
+import path4 from "path";
+
+// src/lib/pi-subagents-export.ts
+import * as crypto2 from "crypto";
+import * as fs2 from "fs";
+import * as os from "os";
+import * as path2 from "path";
+import { fileURLToPath } from "url";
+
+// src/lib/pi-subagents-personas.ts
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+var CURATED_PERSONAS = [
+  {
+    relPath: "agents/research/best-practices-researcher.md",
+    rationale: "Self-contained research persona. INFO: mentions skills in prose as discovery hints, but is operationally independent \u2014 no load-skill directive, no parent-dispatch assumption."
+  },
+  {
+    relPath: "agents/research/framework-docs-researcher.md",
+    rationale: "Self-contained framework documentation researcher. No Systematic-only coupling; uses standard tools (Context7, web search, file reads)."
+  },
+  {
+    relPath: "agents/research/git-history-analyzer.md",
+    rationale: "Self-contained git archaeology persona. Uses only standard git CLI + file tools. No skill or orchestration dependencies."
+  },
+  {
+    relPath: "agents/research/issue-intelligence-analyst.md",
+    rationale: "Self-contained GitHub issue analysis persona. Requires only gh CLI + standard file tools. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/research/repo-research-analyst.md",
+    rationale: "Self-contained repository research persona. Uses standard file/search/glob tools. No Systematic-specific orchestration."
+  },
+  {
+    relPath: "agents/review/adversarial-reviewer.md",
+    rationale: "Self-contained adversarial code reviewer. Fully portable \u2014 no Systematic tools or skills required."
+  },
+  {
+    relPath: "agents/review/api-contract-reviewer.md",
+    rationale: "Self-contained API contract reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/architecture-strategist.md",
+    rationale: "Self-contained architectural reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/cli-readiness-reviewer.md",
+    rationale: "Self-contained CLI readiness reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/code-simplicity-reviewer.md",
+    rationale: "Self-contained code simplicity reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/correctness-reviewer.md",
+    rationale: "Self-contained correctness reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/data-migrations-reviewer.md",
+    rationale: "Self-contained data migrations reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/deployment-verification-agent.md",
+    rationale: "Self-contained deployment verification persona. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/maintainability-reviewer.md",
+    rationale: "Self-contained maintainability reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/pattern-recognition-specialist.md",
+    rationale: "Self-contained pattern recognition reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/performance-reviewer.md",
+    rationale: "Self-contained performance reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/previous-comments-reviewer.md",
+    rationale: "Self-contained previous-comments reviewer. Reviews prior feedback. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/reliability-reviewer.md",
+    rationale: "Self-contained reliability reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/security-reviewer.md",
+    rationale: "Self-contained security reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/review/testing-reviewer.md",
+    rationale: "Self-contained testing reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/document-review/adversarial-document-reviewer.md",
+    rationale: "Self-contained document reviewer. Challenges premises in plans/specs. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/document-review/coherence-reviewer.md",
+    rationale: "Self-contained document coherence reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/document-review/design-lens-reviewer.md",
+    rationale: "Self-contained design lens reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/document-review/feasibility-reviewer.md",
+    rationale: "Self-contained feasibility reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/document-review/product-lens-reviewer.md",
+    rationale: "Self-contained product lens reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/document-review/scope-guardian-reviewer.md",
+    rationale: "Self-contained scope guardian reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/document-review/security-lens-reviewer.md",
+    rationale: "Self-contained security lens reviewer. No Systematic-only coupling."
+  },
+  {
+    relPath: "agents/workflow/spec-flow-analyzer.md",
+    rationale: "Self-contained spec flow analyzer. Analyzes specs for user flow completeness. No Systematic orchestration coupling."
+  },
+  {
+    relPath: "agents/workflow/bug-reproduction-validator.md",
+    rationale: "Self-contained bug reproduction specialist. WARNING: mentions agent-browser skill in prose as an optional tool hint, but does not require Systematic skill loading to operate."
+  }
+];
+function sanitizeName(name) {
+  return name.toLowerCase().replace(/[/\\]/g, "").replace(/\./g, "").replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+}
+function foldIdentity(value) {
+  return value.normalize("NFC").toLowerCase();
+}
+var CRITICAL_PATTERNS = [
+  {
+    pattern: /dispatched by a parent/i,
+    reason: 'References parent-dispatch assumption ("dispatched by a parent") \u2014 this persona is designed to be orchestrated by Systematic.'
+  },
+  {
+    pattern: /report(?:ing)? back to the orchestrator/i,
+    reason: "References orchestrator-report assumption \u2014 this persona is designed to operate within Systematic's orchestration loop."
+  },
+  {
+    pattern: /\bload\s+(?:the\s+)?systematic:/i,
+    reason: 'Contains explicit Systematic skill load directive ("Load systematic:...") \u2014 requires Systematic skill loading infrastructure.'
+  },
+  {
+    pattern: /load\s+`systematic:/i,
+    reason: "Contains explicit Systematic skill load directive with backtick form \u2014 requires Systematic skill loading infrastructure."
+  },
+  {
+    pattern: /\.\.(\/|\\)\.\.(?:\/|\\)skills\//,
+    reason: "Directly references Systematic internal skill paths (../../skills/...) \u2014 not portable outside Systematic."
+  }
+];
+var WARNING_PATTERNS = [
+  {
+    pattern: /\bagent-browser\s+(?:CLI|skill)\b/i,
+    reason: "References agent-browser CLI/skill as an optional tool hint. Behavior may differ if agent-browser is not available, but persona remains operable without it."
+  },
+  {
+    pattern: /use\s+(?:the\s+)?agent-browser\s+skill/i,
+    reason: "Suggests using the agent-browser skill. Persona operates without it but visual verification steps would be skipped."
+  }
+];
+function classifyCompatibility(content) {
+  const reasons = [];
+  let severity = "info";
+  for (const { pattern, reason } of CRITICAL_PATTERNS) {
+    if (pattern.test(content)) {
+      reasons.push(reason);
+      severity = "critical";
+    }
+  }
+  if (severity !== "critical") {
+    for (const { pattern, reason } of WARNING_PATTERNS) {
+      if (pattern.test(content)) {
+        reasons.push(reason);
+        severity = "warning";
+      }
+    }
+  }
+  return { severity, reasons };
+}
+function generatePersonaContent(sourceRef, rawContent) {
+  const { data, body, hadFrontmatter } = parseFrontmatter(rawContent);
+  const rawName = data.name;
+  if (!hadFrontmatter || rawName === undefined || rawName === null) {
+    throw new Error(`Persona "${sourceRef}" is missing frontmatter "name" \u2014 cannot generate pi-subagents export.`);
+  }
+  if (typeof rawName !== "string") {
+    throw new Error(`Persona "${sourceRef}" has a frontmatter "name" of type ${typeof rawName} (expected a non-empty string).`);
+  }
+  const trimmedName = rawName.trim();
+  if (trimmedName === "") {
+    throw new Error(`Persona "${sourceRef}" has an empty frontmatter "name" \u2014 cannot generate pi-subagents export.`);
+  }
+  const sanitized = sanitizeName(trimmedName);
+  if (sanitized === "") {
+    throw new Error(`Persona "${sourceRef}" name "${trimmedName}" sanitizes to an empty string \u2014 cannot produce a valid filename. Rename the persona to use alphanumeric characters.`);
+  }
+  const compat = classifyCompatibility(rawContent);
+  if (compat.severity === "critical")
+    return null;
+  const description = typeof data.description === "string" ? data.description : undefined;
+  const emittedFrontmatter = {};
+  if (description !== undefined && description.trim() !== "") {
+    emittedFrontmatter.description = description;
+  }
+  let frontmatterBlock;
+  if (Object.keys(emittedFrontmatter).length === 0) {
+    frontmatterBlock = `---
+---`;
+  } else {
+    const lines = Object.entries(emittedFrontmatter).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(`
+`);
+    frontmatterBlock = `---
+${lines}
+---`;
+  }
+  const trimmedBody = body.replace(/^\n+/, "");
+  return `${frontmatterBlock}
+
+${trimmedBody}`;
+}
+function generatePersonaManifest(sourceRelPath, rawContent, _repoRoot) {
+  const { data } = parseFrontmatter(rawContent);
+  const rawName = data.name;
+  if (typeof rawName !== "string" || rawName.trim() === "") {
+    throw new Error(`Persona "${sourceRelPath}" is missing or has an empty frontmatter "name".`);
+  }
+  const sanitized = sanitizeName(rawName.trim());
+  if (sanitized === "") {
+    throw new Error(`Persona "${sourceRelPath}" name "${rawName.trim()}" sanitizes to an empty string \u2014 cannot produce a valid filename. Rename the persona to use alphanumeric characters.`);
+  }
+  const filename = `systematic-${sanitized}.md`;
+  const compat = classifyCompatibility(rawContent);
+  if (compat.severity === "critical") {
+    return {
+      filename,
+      status: "excluded-critical",
+      sourceRelPath,
+      hash: "",
+      reason: compat.reasons.join("; ")
+    };
+  }
+  const content = generatePersonaContent(sourceRelPath, rawContent);
+  if (content === null) {
+    return {
+      filename,
+      status: "excluded-critical",
+      sourceRelPath,
+      hash: "",
+      reason: "Compatibility screening rejected persona."
+    };
+  }
+  const hash = crypto.createHash("sha256").update(content).digest("hex");
+  const status = compat.severity === "warning" ? "exported-with-warning" : "exported";
+  return {
+    filename,
+    status,
+    sourceRelPath,
+    hash,
+    content,
+    reason: compat.reasons.length > 0 ? compat.reasons.join("; ") : undefined
+  };
+}
+function generateAll(repoRoot) {
+  const entries = [];
+  const byFoldedFilename = new Map;
+  for (const curatedEntry of CURATED_PERSONAS) {
+    const fullPath = path.join(repoRoot, curatedEntry.relPath);
+    let rawContent;
+    try {
+      rawContent = fs.readFileSync(fullPath, "utf-8");
+    } catch (err) {
+      throw new Error(`Failed to read ${curatedEntry.relPath}: ${err.message}`);
+    }
+    const entry = generatePersonaManifest(curatedEntry.relPath, rawContent, repoRoot);
+    entries.push(entry);
+    const folded = foldIdentity(entry.filename);
+    const existing = byFoldedFilename.get(folded) ?? [];
+    existing.push(curatedEntry.relPath);
+    byFoldedFilename.set(folded, existing);
+  }
+  const collisions = [...byFoldedFilename.entries()].filter(([, sources]) => sources.length > 1);
+  if (collisions.length > 0) {
+    const msg = collisions.map(([filename, sources]) => `  "${filename}": ${sources.join(", ")}`).join(`
+`);
+    throw new Error(`Filename collision(s) detected in curated persona list:
+${msg}
+Update CURATED_PERSONAS to resolve conflicts.`);
+  }
+  const criticals = entries.filter((e) => e.status === "excluded-critical");
+  if (criticals.length > 0) {
+    const msg = criticals.map((e) => `  ${e.sourceRelPath}: ${e.reason}`).join(`
+`);
+    throw new Error(`Critical compatibility coupling detected in curated personas:
+${msg}
+Remove these personas from CURATED_PERSONAS or fix the coupling.`);
+  }
+  return entries;
+}
+
+// src/lib/pi-subagents-export.ts
+var MANIFEST_FILENAME = ".systematic-personas.json";
+var LOCK_FILENAME = ".systematic-personas.lock";
+var GENERATED_NAMESPACE_PATTERN = /^systematic-[a-z0-9-]+\.md$/;
+function resolveAgentsRoot(scope, cwd) {
+  if (scope === "project")
+    return path2.join(cwd, ".pi", "agents");
+  const envDir = process.env.PI_CODING_AGENT_DIR;
+  const base = envDir ? envDir : path2.join(os.homedir(), ".pi", "agent");
+  return path2.join(base, "agents");
+}
+function resolveAnchor(scope, cwd) {
+  if (scope === "project")
+    return path2.resolve(cwd);
+  const envDir = process.env.PI_CODING_AGENT_DIR;
+  if (envDir)
+    return path2.resolve(path2.dirname(envDir));
+  return path2.resolve(os.homedir());
+}
+function anchorForScope(configOptions, agentsRootFallback) {
+  const resolvedAgentsRoot = path2.resolve(agentsRootFallback);
+  if (configOptions) {
+    return resolveAnchor(configOptions.scope, configOptions.cwd);
+  }
+  return path2.dirname(resolvedAgentsRoot);
+}
+function assertAnchoredPathSafe(anchor, targetPath) {
+  const resolvedAnchor = path2.resolve(anchor);
+  const resolvedTarget = path2.resolve(targetPath);
+  if (resolvedTarget !== resolvedAnchor && !resolvedTarget.startsWith(resolvedAnchor + path2.sep)) {
+    throw new Error(`Refusing to operate on ${resolvedTarget}: outside safety anchor ${resolvedAnchor}`);
+  }
+  const rel = path2.relative(resolvedAnchor, resolvedTarget);
+  const parts = rel === "" ? [] : rel.split(path2.sep);
+  let current = resolvedAnchor;
+  for (const part of parts) {
+    current = path2.join(current, part);
+    let stat;
+    try {
+      stat = fs2.lstatSync(current);
+    } catch {
+      continue;
+    }
+    if (stat.isSymbolicLink())
+      throw new Error(`Refusing to operate through ${current}: symlink detected`);
+    if (!stat.isDirectory())
+      throw new Error(`Refusing to operate through ${current}: not a directory`);
+  }
+}
+function assertCanonicalRootWithinAnchor(anchor, root) {
+  let canonicalAnchor;
+  try {
+    canonicalAnchor = fs2.realpathSync(anchor);
+  } catch (err) {
+    throw new Error(`Cannot resolve safety anchor ${anchor}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const canonicalRoot = fs2.realpathSync(root);
+  if (canonicalRoot !== canonicalAnchor && !canonicalRoot.startsWith(canonicalAnchor + path2.sep)) {
+    throw new Error(`Refusing to operate on ${canonicalRoot}: canonical path escapes safety anchor ` + `${canonicalAnchor} (raced-symlink ancestor detected after resolution)`);
+  }
+  return canonicalRoot;
+}
+function validateManifestEntry(entry, seenFilenames) {
+  if (typeof entry !== "object" || entry === null)
+    return "Manifest files entry must be an object";
+  const e = entry;
+  if (typeof e.filename !== "string" || typeof e.hash !== "string")
+    return "Manifest files entry missing required string fields";
+  if (seenFilenames.has(e.filename))
+    return `Manifest contains duplicate filename: "${e.filename}"`;
+  seenFilenames.add(e.filename);
+  if (path2.basename(e.filename) !== e.filename || path2.isAbsolute(e.filename))
+    return `Unsafe filename in manifest: "${e.filename}" \u2014 contains traversal or path separators (invalid filename)`;
+  if (!GENERATED_NAMESPACE_PATTERN.test(e.filename))
+    return `Manifest entry "${e.filename}" is not a generated namespace file (must match systematic-*.md; invalid filename)`;
+  return null;
+}
+function validateManifestObject(parsed) {
+  if (typeof parsed !== "object" || parsed === null)
+    return "Manifest root must be an object";
+  const obj = parsed;
+  if (!Array.isArray(obj.files))
+    return 'Manifest "files" field must be an array';
+  const seenFilenames = new Set;
+  for (const entry of obj.files) {
+    const error = validateManifestEntry(entry, seenFilenames);
+    if (error !== null)
+      return error;
+  }
+  return null;
+}
+var HAS_O_NOFOLLOW = typeof fs2.constants.O_NOFOLLOW === "number";
+function verifyManifestPathIdentity(manifestPath, openedStat) {
+  let linkStat;
+  try {
+    linkStat = fs2.lstatSync(manifestPath);
+  } catch (err) {
+    return `Cannot verify manifest path after open: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  if (linkStat.isSymbolicLink())
+    return `Refusing to read manifest through symlink: ${manifestPath}`;
+  if (linkStat.dev !== openedStat.dev || linkStat.ino !== openedStat.ino)
+    return `Manifest path identity changed during read (possible tamper): ${manifestPath}`;
+  return null;
+}
+function openManifestFd(manifestPath) {
+  const openFlags = fs2.constants.O_RDONLY | (HAS_O_NOFOLLOW ? fs2.constants.O_NOFOLLOW : 0);
+  try {
+    return { kind: "fd", fd: fs2.openSync(manifestPath, openFlags) };
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return { kind: "result", result: { kind: "absent" } };
+    if (err.code === "ELOOP")
+      return {
+        kind: "result",
+        result: {
+          kind: "malformed",
+          error: `Refusing to read manifest through symlink: ${manifestPath}`
+        }
+      };
+    return {
+      kind: "result",
+      result: {
+        kind: "malformed",
+        error: `Cannot read manifest: ${err instanceof Error ? err.message : String(err)}`
+      }
+    };
+  }
+}
+function parseManifestContents(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return {
+      kind: "malformed",
+      error: `Manifest JSON parse error: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const validationError = validateManifestObject(parsed);
+  if (validationError !== null)
+    return { kind: "malformed", error: validationError };
+  return { kind: "ok", manifest: parsed };
+}
+function readManifestStrict(agentsRoot) {
+  const manifestPath = path2.join(agentsRoot, MANIFEST_FILENAME);
+  const opened = openManifestFd(manifestPath);
+  if (opened.kind === "result")
+    return opened.result;
+  const { fd } = opened;
+  try {
+    const stat = fs2.fstatSync(fd);
+    if (!stat.isFile())
+      return {
+        kind: "malformed",
+        error: `Manifest path exists but is not a regular file: ${manifestPath}`
+      };
+    if (!HAS_O_NOFOLLOW) {
+      const identityError = verifyManifestPathIdentity(manifestPath, stat);
+      if (identityError !== null)
+        return { kind: "malformed", error: identityError };
+    }
+    return parseManifestContents(fs2.readFileSync(fd, "utf-8"));
+  } catch (err) {
+    return {
+      kind: "malformed",
+      error: `Cannot read manifest: ${err instanceof Error ? err.message : String(err)}`
+    };
+  } finally {
+    fs2.closeSync(fd);
+  }
+}
+function writeManifest(agentsRoot, manifest) {
+  atomicWriteString(path2.join(agentsRoot, MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}
+`);
+}
+function statOrNull(p) {
+  try {
+    return fs2.lstatSync(p);
+  } catch {
+    return null;
+  }
+}
+function assertRealAgentsRoot(agentsRoot) {
+  let stat = null;
+  try {
+    stat = fs2.lstatSync(agentsRoot);
+  } catch {}
+  if (stat !== null) {
+    if (stat.isSymbolicLink())
+      throw new Error(`Refusing to write under ${agentsRoot}: not a real directory (symlink detected)`);
+    if (!stat.isDirectory())
+      throw new Error(`Refusing to write under ${agentsRoot}: not a directory`);
+  }
+  return fs2.realpathSync(agentsRoot);
+}
+function safeFilePathOrThrow(agentsRoot, filename) {
+  if (path2.basename(filename) !== filename || path2.isAbsolute(filename)) {
+    throw new Error(`Unsafe filename in manifest: "${filename}" \u2014 contains traversal or path separators (invalid filename)`);
+  }
+  const resolved = path2.resolve(agentsRoot, filename);
+  if (!resolved.startsWith(agentsRoot + path2.sep) && resolved !== agentsRoot) {
+    throw new Error(`Unsafe filename in manifest: "${filename}" resolves outside agents root (traversal)`);
+  }
+  return resolved;
+}
+function safeFilePath(agentsRoot, filename) {
+  try {
+    return safeFilePathOrThrow(agentsRoot, filename);
+  } catch {
+    return null;
+  }
+}
+function acquireLock(agentsRoot) {
+  const lockPath = path2.join(agentsRoot, LOCK_FILENAME);
+  try {
+    return { ok: true, fd: fs2.openSync(lockPath, "wx") };
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      return {
+        ok: false,
+        contention: true,
+        error: `Another export/refresh/cleanup operation appears to be in progress ` + `(lock file exists: ${lockPath}). If no other operation is running ` + `(e.g. after a crash), verify manually and remove the lock file yourself.`
+      };
+    }
+    return {
+      ok: false,
+      contention: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function releaseLock(agentsRoot, fd) {
+  try {
+    fs2.closeSync(fd);
+  } catch {}
+  try {
+    fs2.unlinkSync(path2.join(agentsRoot, LOCK_FILENAME));
+  } catch {}
+}
+function withLock(agentsRoot, fn) {
+  const acquired = acquireLock(agentsRoot);
+  if (!acquired.ok) {
+    return {
+      locked: false,
+      error: acquired.error,
+      isContention: acquired.contention
+    };
+  }
+  try {
+    return { locked: true, result: fn() };
+  } finally {
+    releaseLock(agentsRoot, acquired.fd);
+  }
+}
+function atomicWriteString(destPath, content) {
+  const parentDir = path2.dirname(destPath);
+  const tmpPath = path2.join(parentDir, `.${path2.basename(destPath)}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  try {
+    fs2.writeFileSync(tmpPath, content, { flag: "w", mode: 420 });
+    fs2.renameSync(tmpPath, destPath);
+  } catch (err) {
+    try {
+      fs2.unlinkSync(tmpPath);
+    } catch {}
+    throw err;
+  }
+}
+function snapshotFiles(filePaths) {
+  const backup = new Map;
+  for (const p of filePaths) {
+    try {
+      backup.set(p, fs2.readFileSync(p, "utf-8"));
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        backup.set(p, undefined);
+        continue;
+      }
+      return {
+        ok: false,
+        error: `Cannot snapshot ${p}: ${err instanceof Error ? err.message : String(err)}`
+      };
+    }
+  }
+  return { ok: true, backup };
+}
+function restoreFromBackup(backup) {
+  const failed = [];
+  for (const [p, content] of backup) {
+    try {
+      if (content === undefined) {
+        if (fs2.existsSync(p))
+          fs2.unlinkSync(p);
+      } else {
+        fs2.writeFileSync(p, content, "utf-8");
+      }
+    } catch {
+      failed.push(p);
+    }
+  }
+  return failed;
+}
+function rollbackMessage(failed) {
+  return failed.length === 0 ? "rolled back" : `partial rollback (restoration failed for: ${failed.map((p) => path2.basename(p)).join(", ")})`;
+}
+function runWithRollback(pathsToWatch, ops) {
+  const snapshot = snapshotFiles(pathsToWatch);
+  if (!snapshot.ok) {
+    return { ok: false, error: snapshot.error, rollbackFailed: [] };
+  }
+  const backup = snapshot.backup;
+  for (const op of ops) {
+    try {
+      op();
+    } catch (err) {
+      const rollbackFailed = restoreFromBackup(backup);
+      const rb = rollbackMessage(rollbackFailed);
+      return {
+        ok: false,
+        error: `${err instanceof Error ? err.message : String(err)} (${rb})`,
+        rollbackFailed
+      };
+    }
+  }
+  return { ok: true, rollbackFailed: [] };
+}
+function ownedFilenames(manifest) {
+  if (manifest === null)
+    return new Set;
+  const s = new Set;
+  for (const entry of manifest.files) {
+    if (path2.basename(entry.filename) === entry.filename && !path2.isAbsolute(entry.filename))
+      s.add(entry.filename);
+  }
+  return s;
+}
+function parseSourceCategoryAndKey(sourceRelPath) {
+  const parts = sourceRelPath.split("/");
+  if (parts.length >= 3 && parts[0] === "agents") {
+    const fileName2 = parts.at(-1) ?? "";
+    return {
+      category: parts[1],
+      agentKey: fileName2.replace(/\.md$/, "")
+    };
+  }
+  const fileName = parts.at(-1) ?? sourceRelPath;
+  return { category: undefined, agentKey: fileName.replace(/\.md$/, "") };
+}
+function lookupOverlay(map, category, agentKey) {
+  if (!map)
+    return;
+  if (category) {
+    const qualified = map[`${category}/${agentKey}`];
+    if (qualified)
+      return qualified;
+  }
+  return map[agentKey];
+}
+function resolveModel(config, category, agentKey) {
+  const agentOverlay = lookupOverlay(config.agents, category, agentKey);
+  if (agentOverlay && Object.hasOwn(agentOverlay, "model")) {
+    const value = agentOverlay.model;
+    return typeof value === "string" ? value : undefined;
+  }
+  const categoryOverlay = category ? config.categories?.[category] : undefined;
+  if (categoryOverlay && Object.hasOwn(categoryOverlay, "model")) {
+    const value = categoryOverlay.model;
+    return typeof value === "string" ? value : undefined;
+  }
+  return;
+}
+var PI_SUBAGENTS_FRONTMATTER_FIELDS = [
+  "thinking",
+  "max_turns",
+  "tools",
+  "skills"
+];
+function resolvePiSubagentsFields(config, category, agentKey) {
+  const categoryOverlay = category ? config.pi_subagents?.categories?.[category] : undefined;
+  const agentOverlay = lookupOverlay(config.pi_subagents?.agents, category, agentKey);
+  const result = {};
+  for (const field of PI_SUBAGENTS_FRONTMATTER_FIELDS) {
+    if (agentOverlay && Object.hasOwn(agentOverlay, field)) {
+      result[field] = agentOverlay[field];
+    } else if (categoryOverlay && Object.hasOwn(categoryOverlay, field)) {
+      result[field] = categoryOverlay[field];
+    }
+  }
+  return result;
+}
+function applyConfigToContent(content, config, category, agentKey) {
+  const { data, body } = parseFrontmatter(content);
+  const model = resolveModel(config, category, agentKey);
+  const piSubagentsFields = resolvePiSubagentsFields(config, category, agentKey);
+  const frontmatter = {};
+  if (typeof data.description === "string") {
+    frontmatter.description = data.description;
+  }
+  if (model !== undefined)
+    frontmatter.model = model;
+  for (const field of PI_SUBAGENTS_FRONTMATTER_FIELDS) {
+    if (Object.hasOwn(piSubagentsFields, field)) {
+      frontmatter[field] = piSubagentsFields[field];
+    }
+  }
+  let frontmatterBlock;
+  if (Object.keys(frontmatter).length === 0) {
+    frontmatterBlock = `---
+---`;
+  } else {
+    const lines = Object.entries(frontmatter).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(`
+`);
+    frontmatterBlock = `---
+${lines}
+---`;
+  }
+  const trimmedBody = body.replace(/^\n+/, "");
+  return `${frontmatterBlock}
+
+${trimmedBody}`;
+}
+function applyConfigToEntries(entries, config) {
+  return entries.map((entry) => {
+    if (entry.status === "excluded-critical" || !entry.content)
+      return entry;
+    const { category, agentKey } = parseSourceCategoryAndKey(entry.sourceRelPath);
+    const content = applyConfigToContent(entry.content, config, category, agentKey);
+    const hash = crypto2.createHash("sha256").update(content).digest("hex");
+    return { ...entry, content, hash };
+  });
+}
+function generateEntries(repoRoot, configOptions) {
+  const entries = generateAll(repoRoot);
+  if (!configOptions)
+    return entries;
+  const config = loadConfigWithSources(configOptions.cwd, {
+    includeProject: configOptions.scope === "project"
+  }).config;
+  return applyConfigToEntries(entries, config);
+}
+function findPackageRoot() {
+  const thisFile = fileURLToPath(import.meta.url);
+  const dir = path2.resolve(path2.dirname(thisFile), "..", "..");
+  if (fs2.existsSync(path2.join(dir, "package.json")))
+    return dir;
+  let candidate = path2.dirname(thisFile);
+  for (let i = 0;i < 8; i++) {
+    if (fs2.existsSync(path2.join(candidate, "package.json")))
+      return candidate;
+    const parent = path2.dirname(candidate);
+    if (parent === candidate)
+      break;
+    candidate = parent;
+  }
+  throw new Error("Could not locate package root (no package.json found)");
+}
+function planExistingEntry(absRoot, filename, hash, owned) {
+  const diskContent = fs2.readFileSync(path2.join(absRoot, filename), "utf-8");
+  const diskHash = crypto2.createHash("sha256").update(diskContent).digest("hex");
+  if (owned.has(filename)) {
+    return diskHash !== hash ? { action: "update", filename } : { action: "skip", filename };
+  }
+  return {
+    action: "refuse",
+    filename,
+    reason: "File exists but is not owned by a previous export"
+  };
+}
+function planEntryActions(absRoot, entries, owned) {
+  const actions = [];
+  for (const entry of entries) {
+    if (entry.status === "excluded-critical" || !entry.content)
+      continue;
+    const exists = fs2.existsSync(path2.join(absRoot, entry.filename));
+    actions.push(exists ? planExistingEntry(absRoot, entry.filename, entry.hash, owned) : { action: "create", filename: entry.filename });
+  }
+  return actions;
+}
+function planRemoveActions(absRoot, manifest, currentFilenames) {
+  if (!manifest)
+    return [];
+  const removes = [];
+  for (const mEntry of manifest.files) {
+    if (currentFilenames.has(mEntry.filename))
+      continue;
+    const safe = safeFilePath(absRoot, mEntry.filename);
+    if (safe !== null && fs2.existsSync(safe))
+      removes.push({ action: "remove", filename: mEntry.filename });
+  }
+  return removes;
+}
+function preview(agentsRoot, configOptions) {
+  const absRoot = path2.resolve(agentsRoot);
+  const manifestResult = readManifestStrict(absRoot);
+  if (manifestResult.kind === "malformed") {
+    return {
+      status: "error",
+      error: `Malformed manifest: ${manifestResult.error}`,
+      agentsRoot: absRoot,
+      actions: []
+    };
+  }
+  const manifest = manifestResult.kind === "ok" ? manifestResult.manifest : null;
+  let entries;
+  try {
+    entries = generateEntries(findPackageRoot(), configOptions);
+  } catch (err) {
+    return {
+      status: "error",
+      error: `Generator failed: ${err instanceof Error ? err.message : String(err)}`,
+      agentsRoot: absRoot,
+      actions: []
+    };
+  }
+  const owned = ownedFilenames(manifest);
+  const currentFilenames = new Set(entries.filter((e) => e.status !== "excluded-critical" && e.content).map((e) => e.filename));
+  return {
+    status: "ok",
+    agentsRoot: absRoot,
+    actions: [
+      ...planEntryActions(absRoot, entries, owned),
+      ...planRemoveActions(absRoot, manifest, currentFilenames)
+    ]
+  };
+}
+function classifyOneExportEntry(absRoot, entry, owned) {
+  const safePath = safeFilePath(absRoot, entry.filename);
+  if (safePath === null)
+    return { kind: "refuse", reason: "Filename would escape agents root" };
+  if (fs2.existsSync(safePath) && !owned.has(entry.filename))
+    return {
+      kind: "refuse",
+      reason: "File exists but is not owned by a previous export (user file)"
+    };
+  if (fs2.existsSync(safePath)) {
+    const diskHash = crypto2.createHash("sha256").update(fs2.readFileSync(safePath, "utf-8")).digest("hex");
+    if (diskHash === entry.hash)
+      return { kind: "skip", safePath };
+  }
+  return { kind: "write", safePath };
+}
+function classifyExportEntries(absRoot, entries, owned) {
+  const toWrite = [];
+  const toSkip = [];
+  const refused = [];
+  const currentFilenames = new Set;
+  for (const entry of entries) {
+    if (entry.status === "excluded-critical" || !entry.content)
+      continue;
+    currentFilenames.add(entry.filename);
+    const result = classifyOneExportEntry(absRoot, entry, owned);
+    if (result.kind === "refuse") {
+      refused.push({
+        filename: entry.filename,
+        reason: result.reason ?? "refused"
+      });
+    } else if (result.safePath !== undefined && result.kind === "skip") {
+      toSkip.push({ entry, safePath: result.safePath });
+    } else if (result.safePath !== undefined) {
+      toWrite.push({ entry, safePath: result.safePath });
+    }
+  }
+  return { toWrite, toSkip, refused, currentFilenames };
+}
+function buildNewManifestFiles(toWrite, toSkip) {
+  const toFileEntry = (e) => ({
+    filename: e.filename,
+    hash: e.hash,
+    status: e.status === "exported-with-warning" ? "exported-with-warning" : "exported"
+  });
+  return [
+    ...toSkip.map(({ entry }) => toFileEntry(entry)),
+    ...toWrite.map(({ entry }) => toFileEntry(entry))
+  ];
+}
+function makeExportError(error) {
+  return { status: "error", written: 0, skipped: 0, refused: [], error };
+}
+function prepareExportRoot(agentsRoot) {
+  let preStat = null;
+  try {
+    preStat = fs2.lstatSync(agentsRoot);
+  } catch {}
+  if (preStat?.isSymbolicLink())
+    return makeExportError(`Refusing to write under ${agentsRoot}: not a real directory (symlink detected)`);
+  try {
+    fs2.mkdirSync(agentsRoot, { recursive: true });
+    return assertRealAgentsRoot(agentsRoot);
+  } catch (err) {
+    return makeExportError(err instanceof Error ? err.message : String(err));
+  }
+}
+function assertHashMatchesOrThrow(filePath, expectedHash, filename, verb) {
+  const diskContent = fs2.readFileSync(filePath, "utf-8");
+  const diskHash = crypto2.createHash("sha256").update(diskContent).digest("hex");
+  if (diskHash !== expectedHash) {
+    throw new Error(`Refusing to ${verb} "${filename}": content on disk does not match the ` + `manifest hash (drifted or tampered). Resolve manually or re-export/refresh first.`);
+  }
+}
+function findStalePaths(absRoot, prevManifest, currentFilenames) {
+  if (!prevManifest)
+    return [];
+  const stale = [];
+  for (const mEntry of prevManifest.files) {
+    if (currentFilenames.has(mEntry.filename))
+      continue;
+    const safe = safeFilePath(absRoot, mEntry.filename);
+    if (safe === null || !fs2.existsSync(safe))
+      continue;
+    assertHashMatchesOrThrow(safe, mEntry.hash, mEntry.filename, "remove stale file");
+    stale.push({ path: safe, filename: mEntry.filename, hash: mEntry.hash });
+  }
+  return stale;
+}
+function exportPersonas(agentsRoot, configOptions) {
+  let entries;
+  try {
+    entries = generateEntries(findPackageRoot(), configOptions);
+  } catch (err) {
+    return makeExportError(`Failed to generate personas: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const anchor = anchorForScope(configOptions, agentsRoot);
+  try {
+    assertAnchoredPathSafe(anchor, path2.resolve(agentsRoot));
+  } catch (err) {
+    return makeExportError(err instanceof Error ? err.message : String(err));
+  }
+  const rootOrErr = prepareExportRoot(agentsRoot);
+  if (typeof rootOrErr !== "string")
+    return rootOrErr;
+  let absRoot;
+  try {
+    absRoot = assertCanonicalRootWithinAnchor(anchor, rootOrErr);
+  } catch (err) {
+    return makeExportError(err instanceof Error ? err.message : String(err));
+  }
+  const lockResult = withLock(absRoot, () => {
+    const manifestResult = readManifestStrict(absRoot);
+    if (manifestResult.kind === "malformed")
+      return makeExportError(`Malformed manifest \u2014 refusing to export: ${manifestResult.error}`);
+    const prevManifest = manifestResult.kind === "ok" ? manifestResult.manifest : null;
+    const owned = ownedFilenames(prevManifest);
+    const { toWrite, toSkip, refused, currentFilenames } = classifyExportEntries(absRoot, entries, owned);
+    let staleOwned;
+    try {
+      staleOwned = findStalePaths(absRoot, prevManifest, currentFilenames);
+    } catch (err) {
+      return makeExportError(err instanceof Error ? err.message : String(err));
+    }
+    const newManifest = () => ({
+      generatedAt: new Date().toISOString(),
+      agentsRoot: absRoot,
+      files: buildNewManifestFiles(toWrite, toSkip)
+    });
+    const tx = runWithRollback([
+      ...toWrite.map((x) => x.safePath),
+      ...staleOwned.map((x) => x.path),
+      path2.join(absRoot, MANIFEST_FILENAME)
+    ], [
+      ...toWrite.map(({ entry, safePath }) => () => atomicWriteString(safePath, entry.content ?? "")),
+      ...staleOwned.map(({ path: p, filename, hash }) => () => {
+        if (fs2.existsSync(p)) {
+          assertHashMatchesOrThrow(p, hash, filename, "remove stale file");
+          fs2.unlinkSync(p);
+        }
+      }),
+      () => writeManifest(absRoot, newManifest())
+    ]);
+    if (!tx.ok)
+      return {
+        status: "error",
+        written: 0,
+        skipped: toSkip.length,
+        refused,
+        error: tx.error
+      };
+    return {
+      status: "ok",
+      written: toWrite.length,
+      skipped: toSkip.length,
+      refused
+    };
+  });
+  if (!lockResult.locked)
+    return makeExportError(lockResult.error);
+  return lockResult.result;
+}
+function classifyOneRefreshEntry(absRoot, entry, owned) {
+  const safePath = safeFilePath(absRoot, entry.filename);
+  if (safePath === null)
+    return { kind: "ignore" };
+  const exists = fs2.existsSync(safePath);
+  if (exists && !owned.has(entry.filename))
+    return { kind: "skip-unowned", safePath };
+  if (!exists && !owned.has(entry.filename))
+    return { kind: "skip-unexported" };
+  if (exists) {
+    const diskHash = crypto2.createHash("sha256").update(fs2.readFileSync(safePath, "utf-8")).digest("hex");
+    if (diskHash === entry.hash)
+      return { kind: "keep", safePath };
+  }
+  return { kind: "update", safePath };
+}
+function classifyRefreshEntries(absRoot, entries, owned) {
+  const toUpdate = [];
+  const toKeep = [];
+  let skippedUnowned = 0;
+  for (const entry of entries) {
+    if (entry.status === "excluded-critical" || !entry.content)
+      continue;
+    const result = classifyOneRefreshEntry(absRoot, entry, owned);
+    if (result.kind === "skip-unowned") {
+      skippedUnowned++;
+      continue;
+    }
+    if (result.kind === "ignore" || result.kind === "skip-unexported")
+      continue;
+    if (result.safePath !== undefined && result.kind === "keep")
+      toKeep.push({ entry, safePath: result.safePath });
+    else if (result.safePath !== undefined)
+      toUpdate.push({ entry, safePath: result.safePath });
+  }
+  return { toUpdate, toKeep, skippedUnowned };
+}
+function validateRefreshRoot(agentsRoot) {
+  const absRoot = path2.resolve(agentsRoot);
+  if (!fs2.existsSync(absRoot))
+    return {
+      status: "error",
+      updated: 0,
+      skippedUnowned: 0,
+      error: `Agents root does not exist: ${absRoot}. Run export first.`
+    };
+  try {
+    const stat = fs2.lstatSync(absRoot);
+    if (stat.isSymbolicLink())
+      return {
+        status: "error",
+        updated: 0,
+        skippedUnowned: 0,
+        error: `Refusing to write under ${absRoot}: not a real directory (symlink)`
+      };
+  } catch (err) {
+    return {
+      status: "error",
+      updated: 0,
+      skippedUnowned: 0,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+  return absRoot;
+}
+function refresh(agentsRoot, configOptions) {
+  let entries;
+  try {
+    entries = generateEntries(findPackageRoot(), configOptions);
+  } catch (err) {
+    return {
+      status: "error",
+      updated: 0,
+      skippedUnowned: 0,
+      error: `Failed to generate personas: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const absRootCandidate = path2.resolve(agentsRoot);
+  const anchor = anchorForScope(configOptions, absRootCandidate);
+  try {
+    assertAnchoredPathSafe(anchor, absRootCandidate);
+  } catch (err) {
+    return {
+      status: "error",
+      updated: 0,
+      skippedUnowned: 0,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+  const rootOrErr = validateRefreshRoot(agentsRoot);
+  if (typeof rootOrErr !== "string")
+    return rootOrErr;
+  let absRoot;
+  try {
+    absRoot = assertCanonicalRootWithinAnchor(anchor, rootOrErr);
+  } catch (err) {
+    return {
+      status: "error",
+      updated: 0,
+      skippedUnowned: 0,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+  const lockResult = withLock(absRoot, () => {
+    const manifestResult = readManifestStrict(absRoot);
+    if (manifestResult.kind === "malformed")
+      return {
+        status: "error",
+        updated: 0,
+        skippedUnowned: 0,
+        error: `Malformed manifest \u2014 refusing to refresh: ${manifestResult.error}`
+      };
+    const manifest = manifestResult.kind === "ok" ? manifestResult.manifest : null;
+    const { toUpdate, toKeep, skippedUnowned } = classifyRefreshEntries(absRoot, entries, ownedFilenames(manifest));
+    const needsManifest = manifest !== null || toUpdate.length + toKeep.length > 0;
+    const newManifest = () => ({
+      generatedAt: new Date().toISOString(),
+      agentsRoot: absRoot,
+      files: buildNewManifestFiles(toUpdate, toKeep)
+    });
+    const tx = runWithRollback([
+      ...toUpdate.map((x) => x.safePath),
+      path2.join(absRoot, MANIFEST_FILENAME)
+    ], [
+      ...toUpdate.map(({ entry, safePath }) => () => atomicWriteString(safePath, entry.content ?? "")),
+      ...needsManifest ? [() => writeManifest(absRoot, newManifest())] : []
+    ]);
+    if (!tx.ok)
+      return { status: "error", updated: 0, skippedUnowned, error: tx.error };
+    return { status: "ok", updated: toUpdate.length, skippedUnowned };
+  });
+  if (!lockResult.locked)
+    return {
+      status: "error",
+      updated: 0,
+      skippedUnowned: 0,
+      error: lockResult.error
+    };
+  return lockResult.result;
+}
+function collectCleanupPaths(absRoot, manifest) {
+  const targets = [];
+  for (const entry of manifest.files) {
+    const safe = safeFilePath(absRoot, entry.filename);
+    if (safe === null || !fs2.existsSync(safe))
+      continue;
+    assertHashMatchesOrThrow(safe, entry.hash, entry.filename, "delete");
+    targets.push({ path: safe, filename: entry.filename, hash: entry.hash });
+  }
+  const manifestPath = path2.join(absRoot, MANIFEST_FILENAME);
+  return {
+    targets,
+    manifestPath: fs2.existsSync(manifestPath) ? manifestPath : null
+  };
+}
+function cleanup(agentsRoot, configOptions) {
+  const absRootCandidate = path2.resolve(agentsRoot);
+  const preStat = statOrNull(absRootCandidate);
+  if (preStat?.isSymbolicLink())
+    throw new Error(`Refusing to operate on ${absRootCandidate}: not a real directory (symlink detected)`);
+  const anchor = anchorForScope(configOptions, absRootCandidate);
+  assertAnchoredPathSafe(anchor, absRootCandidate);
+  if (!fs2.existsSync(absRootCandidate))
+    return { status: "ok" };
+  const absRoot = assertCanonicalRootWithinAnchor(anchor, absRootCandidate);
+  const lockResult = withLock(absRoot, () => {
+    const manifestResult = readManifestStrict(absRoot);
+    if (manifestResult.kind === "absent")
+      return { kind: "absent" };
+    if (manifestResult.kind === "malformed")
+      throw new Error(`Malformed manifest \u2014 refusing to cleanup: ${manifestResult.error}`);
+    const manifest = manifestResult.manifest;
+    const { targets, manifestPath } = collectCleanupPaths(absRoot, manifest);
+    const pathsToWatch = [
+      ...targets.map((t) => t.path),
+      ...manifestPath ? [manifestPath] : []
+    ];
+    const tx2 = runWithRollback(pathsToWatch, [
+      ...targets.map(({ path: p, filename, hash }) => () => {
+        if (fs2.existsSync(p)) {
+          assertHashMatchesOrThrow(p, hash, filename, "delete");
+          fs2.unlinkSync(p);
+        }
+      }),
+      ...manifestPath ? [
+        () => {
+          if (fs2.existsSync(manifestPath))
+            fs2.unlinkSync(manifestPath);
+        }
+      ] : []
+    ]);
+    return { kind: "tx", tx: tx2 };
+  });
+  if (!lockResult.locked) {
+    if (lockResult.isContention)
+      throw new Error(lockResult.error);
+    return { status: "error", error: lockResult.error };
+  }
+  if (lockResult.result.kind === "absent")
+    return { status: "ok" };
+  const tx = lockResult.result.tx;
+  if (!tx.ok)
+    return { status: "error", error: tx.error };
+  return { status: "ok" };
+}
 
 // src/lib/setup.ts
-import fs from "fs";
-import path from "path";
+import fs3 from "fs";
+import path3 from "path";
 var SYSTEMATIC_PACKAGE_NAME = "@fro.bot/systematic";
 var PI_PACKAGE_IDENTIFIER = `npm:${SYSTEMATIC_PACKAGE_NAME}`;
 var SETUP_ERROR_NAME = "SetupError";
@@ -27,10 +1228,10 @@ function createSetupError(message) {
   return error;
 }
 var DEFAULT_OPS = {
-  writeFileSync: fs.writeFileSync,
-  renameSync: fs.renameSync,
-  unlinkSync: fs.unlinkSync,
-  chmodSync: fs.chmodSync
+  writeFileSync: fs3.writeFileSync,
+  renameSync: fs3.renameSync,
+  unlinkSync: fs3.unlinkSync,
+  chmodSync: fs3.chmodSync
 };
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -52,7 +1253,7 @@ function isPiSystematicIdentifier(identifier) {
 }
 function lstatOrNull(targetPath) {
   try {
-    return fs.lstatSync(targetPath);
+    return fs3.lstatSync(targetPath);
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
       return null;
@@ -61,10 +1262,10 @@ function lstatOrNull(targetPath) {
   }
 }
 function assertRealpathUnderCwd(dir, cwd) {
-  const realDir = fs.realpathSync(dir);
-  const realCwd = fs.realpathSync(cwd);
-  const relative = path.relative(realCwd, realDir);
-  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+  const realDir = fs3.realpathSync(dir);
+  const realCwd = fs3.realpathSync(cwd);
+  const relative2 = path3.relative(realCwd, realDir);
+  if (relative2.startsWith("..") || path3.isAbsolute(relative2)) {
     throw createSetupError(`Refusing to write under ${dir}: resolved directory escapes the project root`);
   }
 }
@@ -77,7 +1278,7 @@ function assertParentTrusted(parentDir, cwd) {
     assertRealpathUnderCwd(parentDir, cwd);
     return;
   }
-  fs.mkdirSync(parentDir, { recursive: true });
+  fs3.mkdirSync(parentDir, { recursive: true });
   assertRealpathUnderCwd(parentDir, cwd);
 }
 var OPENCODE_TARGET_CANDIDATES = [
@@ -87,19 +1288,19 @@ var OPENCODE_TARGET_CANDIDATES = [
   "opencode.json"
 ];
 function resolveOpenCodeTargetPath(cwd) {
-  const opencodeDirStat = lstatOrNull(path.join(cwd, ".opencode"));
+  const opencodeDirStat = lstatOrNull(path3.join(cwd, ".opencode"));
   if (opencodeDirStat?.isSymbolicLink()) {
-    return path.join(cwd, OPENCODE_TARGET_CANDIDATES[0]);
+    return path3.join(cwd, OPENCODE_TARGET_CANDIDATES[0]);
   }
   for (const candidate of OPENCODE_TARGET_CANDIDATES) {
-    const candidatePath = path.join(cwd, candidate);
+    const candidatePath = path3.join(cwd, candidate);
     if (lstatOrNull(candidatePath) !== null)
       return candidatePath;
   }
-  return path.join(cwd, "opencode.jsonc");
+  return path3.join(cwd, "opencode.jsonc");
 }
 var IS_WINDOWS = process.platform === "win32";
-var OPEN_FLAGS = IS_WINDOWS ? fs.constants.O_RDONLY : fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK;
+var OPEN_FLAGS = IS_WINDOWS ? fs3.constants.O_RDONLY : fs3.constants.O_RDONLY | fs3.constants.O_NOFOLLOW | fs3.constants.O_NONBLOCK;
 function assertWindowsPreOpenTrust(targetPath) {
   const preStat = lstatOrNull(targetPath);
   if (preStat && (preStat.isSymbolicLink() || !preStat.isFile())) {
@@ -111,7 +1312,7 @@ function openTrustedExisting(targetPath) {
     assertWindowsPreOpenTrust(targetPath);
   let fd;
   try {
-    fd = fs.openSync(targetPath, OPEN_FLAGS);
+    fd = fs3.openSync(targetPath, OPEN_FLAGS);
   } catch (error) {
     if (error instanceof Error && "code" in error) {
       if (error.code === "ENOENT")
@@ -123,13 +1324,13 @@ function openTrustedExisting(targetPath) {
     throw error;
   }
   try {
-    const stat = fs.fstatSync(fd);
+    const stat = fs3.fstatSync(fd);
     if (!stat.isFile()) {
       throw createSetupError(`Refusing to read ${targetPath}: not a regular file`);
     }
-    return { bytes: fs.readFileSync(fd), mode: stat.mode & 511 };
+    return { bytes: fs3.readFileSync(fd), mode: stat.mode & 511 };
   } finally {
-    fs.closeSync(fd);
+    fs3.closeSync(fd);
   }
 }
 function atomicWrite(targetPath, content, originalBytes, mode, ops) {
@@ -144,8 +1345,8 @@ function atomicWrite(targetPath, content, originalBytes, mode, ops) {
   writeTempAndRename(targetPath, content, mode, preserveMode, ops);
 }
 function writeTempAndRename(destPath, content, mode, preserveExactMode, ops) {
-  const parentDir = path.dirname(destPath);
-  const tempPath = makeTempPath(parentDir, path.basename(destPath));
+  const parentDir = path3.dirname(destPath);
+  const tempPath = makeTempPath(parentDir, path3.basename(destPath));
   try {
     ops.writeFileSync(tempPath, content, { flag: "wx", mode });
     if (preserveExactMode) {
@@ -157,11 +1358,11 @@ function writeTempAndRename(destPath, content, mode, preserveExactMode, ops) {
     throw error;
   }
 }
-function makeTempPath(parentDir, basename) {
-  return path.join(parentDir, `.${basename}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+function makeTempPath(parentDir, basename2) {
+  return path3.join(parentDir, `.${basename2}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
 }
 function cleanupTemp(tempPath, ops) {
-  if (!fs.existsSync(tempPath))
+  if (!fs3.existsSync(tempPath))
     return;
   try {
     ops.unlinkSync(tempPath);
@@ -195,7 +1396,7 @@ function parseOpenCodeJsonc(rawText, targetPath) {
 }
 function setupOpenCode(cwd, ops) {
   const targetPath = resolveOpenCodeTargetPath(cwd);
-  assertParentTrusted(path.dirname(targetPath), cwd);
+  assertParentTrusted(path3.dirname(targetPath), cwd);
   const existing = openTrustedExisting(targetPath);
   if (existing === null) {
     const content = `${JSON.stringify({ plugin: [SYSTEMATIC_PACKAGE_NAME] }, null, 2)}
@@ -253,8 +1454,8 @@ function assertPiTaggedEntryUsable(entry, targetPath) {
   }
 }
 function setupPi(cwd, ops) {
-  const targetPath = path.join(cwd, ".pi", "settings.json");
-  assertParentTrusted(path.dirname(targetPath), cwd);
+  const targetPath = path3.join(cwd, ".pi", "settings.json");
+  assertParentTrusted(path3.dirname(targetPath), cwd);
   const existing = openTrustedExisting(targetPath);
   if (existing === null) {
     const content = `${JSON.stringify({ packages: [PI_PACKAGE_IDENTIFIER] }, null, 2)}
@@ -314,10 +1515,10 @@ function setupHarness(harness, cwd, opsOverride) {
 // src/cli.ts
 var getPackageVersion = () => {
   try {
-    const packageJsonPath = path2.resolve(import.meta.dirname, "..", "package.json");
-    if (!fs2.existsSync(packageJsonPath))
+    const packageJsonPath = path4.resolve(import.meta.dirname, "..", "package.json");
+    if (!fs4.existsSync(packageJsonPath))
       return "unknown";
-    const content = fs2.readFileSync(packageJsonPath, "utf8");
+    const content = fs4.readFileSync(packageJsonPath, "utf8");
     const parsed = JSON.parse(content);
     return parsed.version ?? "unknown";
   } catch {
@@ -337,6 +1538,11 @@ Commands:
     show                       Show configuration
     path                       Print config file locations
   setup --harness opencode|pi  Configure a harness to load Systematic (project-local only)
+  pi-subagents <subcommand>    Manage Systematic persona export for pi-subagents
+    preview [--scope project|global]   Show what export would do (no writes)
+    export  [--scope project|global]   Write persona files to agents dir
+    refresh [--scope project|global]   Replace stale owned files from current source
+    cleanup [--scope project|global]   Remove all generated files and manifest
 
 Options:
   -h, --help           Show this help message
@@ -348,6 +1554,23 @@ Examples:
   systematic config show
   systematic setup --harness opencode
   systematic setup --harness pi
+  systematic pi-subagents preview
+  systematic pi-subagents export
+  systematic pi-subagents export --scope global
+  systematic pi-subagents refresh
+  systematic pi-subagents cleanup
+`;
+var PI_SUBAGENTS_USAGE = `Usage: systematic pi-subagents <subcommand> [--scope project|global]
+
+Subcommands:
+  preview   Show what export would do (no writes)
+  export    Write persona files to agents dir
+  refresh   Replace stale owned files from current source
+  cleanup   Remove all generated files and manifest
+
+Scope:
+  project   <cwd>/.pi/agents (default)
+  global    $PI_CODING_AGENT_DIR/agents or ~/.pi/agent/agents
 `;
 function isHarness(value) {
   return value === "opencode" || value === "pi";
@@ -376,7 +1599,7 @@ function setupCommand(rest) {
   }
 }
 function listItems(type) {
-  const packageRoot = path2.resolve(import.meta.dirname, "..");
+  const packageRoot = path4.resolve(import.meta.dirname, "..");
   const bundledDir = packageRoot;
   let finder;
   let subdir;
@@ -397,7 +1620,7 @@ function listItems(type) {
       console.error(`Unknown type: ${type}. Use: skills, agents, commands`);
       process.exit(1);
   }
-  const items = finder(path2.join(bundledDir, subdir));
+  const items = finder(path4.join(bundledDir, subdir));
   if (items.length === 0) {
     console.log(`No ${type} found.`);
     return;
@@ -414,15 +1637,15 @@ function configShow() {
 `);
   console.log(`  User config:    ${paths.userConfig}`);
   console.log(`  Project config: ${paths.projectConfig}`);
-  if (fs2.existsSync(paths.projectConfig)) {
+  if (fs4.existsSync(paths.projectConfig)) {
     console.log(`
 Project configuration:`);
-    console.log(fs2.readFileSync(paths.projectConfig, "utf-8"));
+    console.log(fs4.readFileSync(paths.projectConfig, "utf-8"));
   }
-  if (fs2.existsSync(paths.userConfig)) {
+  if (fs4.existsSync(paths.userConfig)) {
     console.log(`
 User configuration:`);
-    console.log(fs2.readFileSync(paths.userConfig, "utf-8"));
+    console.log(fs4.readFileSync(paths.userConfig, "utf-8"));
   }
 }
 function configPath() {
@@ -431,6 +1654,159 @@ function configPath() {
   console.log(`  User:    ${paths.userConfig}`);
   console.log(`  Project: ${paths.projectConfig}`);
 }
+function parsePiSubagentsArgs(rest) {
+  let subcommand;
+  let scope = "project";
+  let i = 0;
+  while (i < rest.length) {
+    const arg = rest[i];
+    if (arg === "--scope") {
+      i++;
+      const val = rest[i];
+      if (val !== "project" && val !== "global") {
+        console.error(`Invalid --scope value: ${val ?? ""}. Use: project, global`);
+        process.exit(1);
+      }
+      scope = val;
+    } else if (subcommand === undefined && arg !== undefined && !arg.startsWith("-")) {
+      subcommand = arg;
+    } else if (arg !== undefined) {
+      console.error(`Unknown argument: ${arg}`);
+      console.error(PI_SUBAGENTS_USAGE);
+      process.exit(1);
+    }
+    i++;
+  }
+  return { subcommand, scope };
+}
+function printActionLine(a) {
+  if (a.action === "create")
+    console.log(`  + ${a.filename}  (create)`);
+  else if (a.action === "update")
+    console.log(`  ~ ${a.filename}  (update)`);
+  else if (a.action === "refuse")
+    console.log(`  ! ${a.filename}  (refuse: ${a.reason})`);
+  else if (a.action === "remove")
+    console.log(`  - ${a.filename}  (remove stale)`);
+  else
+    console.log(`  = ${a.filename}  (up to date)`);
+}
+function runPreview(agentsRoot, scope) {
+  const plan = preview(agentsRoot, { scope, cwd: process.cwd() });
+  if (plan.status === "error") {
+    console.error(`Preview failed: ${plan.error ?? "unknown error"}`);
+    process.exit(1);
+  }
+  console.log(`Target: ${plan.agentsRoot}`);
+  console.log("");
+  if (plan.actions.length === 0) {
+    console.log("No actions needed (nothing to export).");
+    return;
+  }
+  const counts = { create: 0, update: 0, refuse: 0, remove: 0, skip: 0 };
+  for (const a of plan.actions) {
+    counts[a.action]++;
+    printActionLine(a);
+  }
+  console.log("");
+  console.log(`Summary: ${counts.create} create, ${counts.update} update, ` + `${counts.skip} skip, ${counts.refuse} refuse, ${counts.remove} remove`);
+}
+function runExport(agentsRoot, scope) {
+  const configOptions = { scope, cwd: process.cwd() };
+  const plan = preview(agentsRoot, configOptions);
+  if (plan.status === "error") {
+    console.error(`Export failed (preview step): ${plan.error ?? "unknown error"}`);
+    process.exit(1);
+  }
+  console.log(`Target: ${plan.agentsRoot}`);
+  const hasWork = plan.actions.some((a) => a.action === "create" || a.action === "update" || a.action === "refuse" || a.action === "remove");
+  if (plan.actions.length > 0) {
+    console.log("");
+    const counts = { create: 0, update: 0, refuse: 0, remove: 0, skip: 0 };
+    for (const a of plan.actions) {
+      counts[a.action]++;
+      printActionLine(a);
+    }
+    console.log("");
+    console.log(`Summary: ${counts.create} create, ${counts.update} update, ` + `${counts.skip} skip, ${counts.refuse} refuse, ${counts.remove} remove`);
+  }
+  if (!hasWork) {
+    console.log("All persona files are already up to date. No changes.");
+    return;
+  }
+  const result = exportPersonas(agentsRoot, configOptions);
+  if (result.status === "error") {
+    console.error(`Export failed: ${result.error ?? "unknown error"}`);
+    process.exit(1);
+  }
+  const hadRemovals = plan.actions.some((a) => a.action === "remove");
+  if (result.written === 0 && result.refused.length === 0 && !hadRemovals) {
+    console.log("All persona files are already up to date. No changes.");
+  } else {
+    console.log(`Exported ${result.written} file(s) to ${agentsRoot}/ (${result.skipped} already up to date).`);
+  }
+  if (result.refused.length > 0) {
+    console.log(`
+Refused (pre-existing unowned files not overwritten):`);
+    for (const r of result.refused)
+      console.log(`  ! ${r.filename}: ${r.reason}`);
+  }
+}
+function runRefresh(agentsRoot, scope) {
+  const result = refresh(agentsRoot, { scope, cwd: process.cwd() });
+  if (result.status === "error") {
+    console.error(`Refresh failed: ${result.error ?? "unknown error"}`);
+    process.exit(1);
+  }
+  if (result.updated === 0) {
+    console.log("All owned persona files are up to date. No changes.");
+  } else {
+    console.log(`Refreshed: updated ${result.updated} file(s) in ${agentsRoot}/.`);
+  }
+  if (result.skippedUnowned > 0)
+    console.log(`  Skipped ${result.skippedUnowned} unowned file(s) (not touched).`);
+}
+function runCleanup(agentsRoot, scope) {
+  let result;
+  try {
+    result = cleanup(agentsRoot, { scope, cwd: process.cwd() });
+  } catch (err) {
+    console.error(`Cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  if (result.status === "error") {
+    console.error(`Cleanup failed: ${result.error ?? "unknown error"}`);
+    process.exit(1);
+  }
+  console.log(`Cleaned up generated persona files from ${agentsRoot}/. Manifest (${MANIFEST_FILENAME}) removed.`);
+}
+function piSubagentsCommand(rest) {
+  const { subcommand, scope } = parsePiSubagentsArgs(rest);
+  if (!subcommand) {
+    console.error("Error: pi-subagents requires a subcommand.");
+    console.error(PI_SUBAGENTS_USAGE);
+    process.exit(1);
+  }
+  const agentsRoot = resolveAgentsRoot(scope, process.cwd());
+  switch (subcommand) {
+    case "preview":
+      runPreview(agentsRoot, scope);
+      break;
+    case "export":
+      runExport(agentsRoot, scope);
+      break;
+    case "refresh":
+      runRefresh(agentsRoot, scope);
+      break;
+    case "cleanup":
+      runCleanup(agentsRoot, scope);
+      break;
+    default:
+      console.error(`Unknown pi-subagents subcommand: ${subcommand}`);
+      console.error(PI_SUBAGENTS_USAGE);
+      process.exit(1);
+  }
+}
 var args = process.argv.slice(2);
 var command = args[0];
 switch (command) {
@@ -440,6 +1816,9 @@ switch (command) {
   case "setup":
     setupCommand(args.slice(1));
     break;
+  case "pi-subagents":
+    piSubagentsCommand(args.slice(1));
+    break;
   case "config":
     switch (args[1]) {
       case "show":