alp-code 0.9.0

package/scripts/lib/cli-link.cjs

@@ -0,0 +1,375 @@
+// cli-link.cjs — cài lệnh `alp` và đưa nó vào PATH cho terminal mở sau installer.
+//
+// MỤC TIÊU: chạy xong installer là gõ `alp` được, không phải đọc hướng dẫn thêm.
+// Muốn vậy phải làm ĐỦ HAI VIỆC, thiếu một là hỏng:
+//   1. có một file thực thi tên `alp` ở đâu đó
+//   2. thư mục chứa nó nằm trong PATH của shell mà người dùng SẼ mở lần sau
+//
+// Trước đây chỉ làm việc (1) rồi in một câu khuyên cho việc (2). Trên macOS zsh mặc
+// định KHÔNG có `~/.local/bin` trong PATH, nên "cài xong" thực tế là "cài xong một nửa".
+//
+// GHI VÀO SHELL PROFILE LÀ VIỆC PHẢI XIN PHÉP — và ở đây principal đã yêu cầu thẳng.
+// Vẫn giữ ba phanh:
+//   · chỉ APPEND, không bao giờ sửa/xoá dòng có sẵn
+//   · bọc trong marker để chạy lại không nhân bản, và để gỡ ra được bằng tay
+//   · `--no-path` (hoặc ALP_NO_PATH=1) tắt hẳn cho CI và cho người tự quản PATH
+//
+// Windows KHÔNG dùng symlink: `fs.symlinkSync` ở đó cần quyền admin hoặc Developer Mode.
+// Thay bằng shim `.cmd` — không cần quyền gì — và ghi PATH ở tầng User qua PowerShell.
+//
+// ⚠️ Nhánh Windows CHƯA CHẠY THẬT trên máy Windows nào. Logic dựng path/nội dung shim có
+// test (`test-cli-link.cjs`), nhưng việc `setx`-tương-đương có ăn hay không thì chưa đo.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const BEGIN = "# >>> alp-code >>>";
+const END = "# <<< alp-code <<<";
+
+/** Thư mục chứa lệnh `alp`, theo từng nền tảng. */
+function binDir(env, platform) {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  if (platform === "win32")
+    return path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "alp", "bin");
+  return path.join(home, ".local", "bin");
+}
+
+/**
+ * Nội dung shim `.cmd` cho Windows.
+ *
+ * `%*` giữ nguyên tham số; dấu ngoặc kép quanh đường dẫn để chịu được `C:\Program Files`.
+ * CRLF vì `cmd.exe` không chạy nổi file chỉ có LF.
+ */
+function cmdShim(cliPath) {
+  return ["@rem alp-code shim", "@echo off", `node "${cliPath}" %*`, ""].join("\r\n");
+}
+
+/**
+ * File profile của shell hiện tại. Trả `null` khi không đoán được — thà im lặng còn hơn
+ * ghi nhầm vào file của shell khác.
+ */
+function profileFor(env, platform) {
+  const home = env.HOME || os.homedir();
+  const shell = path.basename(env.SHELL || "");
+  if (shell === "zsh") return { file: path.join(home, ".zshrc"), syntax: "posix" };
+  if (shell === "fish")
+    return { file: path.join(home, ".config", "fish", "config.fish"), syntax: "fish" };
+  if (shell === "bash")
+    // macOS: Terminal mở bash ở chế độ login ⇒ đọc .bash_profile, KHÔNG đọc .bashrc.
+    // Linux: terminal thường là non-login ⇒ đọc .bashrc. Chọn sai file = ghi xong vẫn
+    // không có PATH, và đó đúng là kiểu hỏng câm mà cả repo này đang tránh.
+    return {
+      file: path.join(home, platform === "darwin" ? ".bash_profile" : ".bashrc"),
+      syntax: "posix",
+    };
+  return null;
+}
+
+/** Khối PATH sẽ append, có marker hai đầu. */
+function pathBlock(dir, syntax) {
+  const line =
+    syntax === "fish"
+      ? `fish_add_path ${dir}`
+      : `export PATH="${dir}:$PATH"`;
+  return `\n${BEGIN}\n${line}\n${END}\n`;
+}
+
+/** Thư mục `dir` đã nằm trong PATH của tiến trình hiện tại chưa. */
+function onPath(dir, env, platform) {
+  // Khi giả lập nhánh Windows trên macOS/Linux, `path.delimiter` vẫn là `:`. Chọn theo
+  // platform được tiêm vào để test đúng dữ liệu PATH thật của Windows (`;`).
+  const delimiter = platform === "win32" ? ";" : path.delimiter;
+  const parts = (env.PATH || env.Path || "").split(delimiter).filter(Boolean);
+  const same = (a, b) =>
+    platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+  return parts.some((p) => same(path.resolve(p), path.resolve(dir)));
+}
+
+/**
+ * Cài lệnh `alp`.
+ *
+ * @param {string} repoRoot  gốc repo alp-code
+ * @param {object} opts
+ *   · env, platform  — tiêm vào để test được nhánh Windows từ máy khác
+ *   · skipPath       — chỉ tạo file thực thi, không đụng PATH
+ *   · applyWindowsPath(dir) — cho test chặn lời gọi PowerShell thật
+ * @returns {Array<{level:string, text:string}>} nhật ký để caller in ra
+ */
+function installCli(repoRoot, opts = {}) {
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+  const skipPath = !!opts.skipPath;
+  const log = [];
+  const say = (level, text) => log.push({ level, text });
+
+  // Stable bootstrap only; parsing and policy remain in dist/src/cli/alp.js.
+  const cli = path.join(repoRoot, "scripts", "alp.cjs");
+  const dir = binDir(env, platform);
+  const target = path.join(dir, platform === "win32" ? "alp.cmd" : "alp");
+
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    if (platform === "win32") writeShim(target, cli, say);
+    else linkUnix(target, cli, say);
+  } catch (e) {
+    say("SKIP", `không tạo được ${target} (${e.message}) — chạy trực tiếp: node ${cli}`);
+    return log;
+  }
+
+  if (onPath(dir, env, platform)) {
+    say("OK", `${dir} đã có trong PATH — gõ \`alp\` là chạy`);
+    return log;
+  }
+  if (skipPath) {
+    say("PATH", `${dir} chưa trong PATH; bỏ qua theo --no-path — tự thêm rồi mở terminal mới`);
+    return log;
+  }
+
+  if (platform === "win32") addWindowsPath(dir, env, opts, say);
+  else addPosixPath(dir, env, platform, say);
+  return log;
+}
+
+/**
+ * Gỡ lệnh `alp` và phần PATH do installCli tạo.
+ *
+ * Chỉ xoá shim/link nếu nó còn trỏ đúng repo này. Một file `alp` của người dùng hoặc của
+ * clone alp-code khác là FOREIGN — giữ nguyên và không rút PATH chuyên dụng trên Windows.
+ */
+function uninstallCli(repoRoot, opts = {}) {
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+  const log = [];
+  const say = (level, text) => log.push({ level, text });
+  const cli = path.join(repoRoot, "scripts", "alp.cjs");
+  const dir = binDir(env, platform);
+  const target = path.join(dir, platform === "win32" ? "alp.cmd" : "alp");
+  let foreign = false;
+
+  if (fs.existsSync(target) || isBrokenLink(target)) {
+    if (ownsCommand(target, cli, platform)) {
+      fs.rmSync(target);
+      say("REMOVED", target);
+    } else {
+      foreign = true;
+      say("KEEP", `${target} — không phải lệnh của repo alp-code này`);
+    }
+  } else {
+    say("ABSENT", target);
+  }
+
+  if (platform === "win32") {
+    if (!foreign) {
+      removeWindowsPath(dir, env, opts, say);
+      removeFromProcessPath(dir, env, platform);
+      removeEmptyDir(dir);
+      removeEmptyDir(path.dirname(dir));
+    }
+  } else {
+    for (const file of profileCandidates(env)) {
+      if (!fs.existsSync(file)) continue;
+      const before = fs.readFileSync(file, "utf8");
+      const after = stripPathBlock(before);
+      if (after === before) continue;
+      fs.writeFileSync(file, after);
+      say("WROTE", `${file} — gỡ khối PATH của alp-code`);
+    }
+    removeFromProcessPath(dir, env, platform);
+  }
+  return log;
+}
+
+// ---------------------------------------------------------------- file thực thi
+
+function linkUnix(link, cli, say) {
+  try { fs.chmodSync(cli, 0o755); } catch {}
+
+  const exists = fs.existsSync(link) || isBrokenLink(link);
+  if (!exists) {
+    fs.symlinkSync(cli, link);
+    return say("LINKED", `${link} → ${cli}`);
+  }
+
+  const current = fs.lstatSync(link).isSymbolicLink() ? fs.readlinkSync(link) : null;
+  if (current === cli) return say("OK", `${link} → ${cli}`);
+  if (current === null)
+    // File thật của người khác trùng tên — không đụng, chỉ nói.
+    throw new Error(`${link} đã tồn tại và không phải symlink của alp-code`);
+
+  fs.rmSync(link);
+  fs.symlinkSync(cli, link);
+  say("LINKED", `${link} → ${cli} (trỏ lại từ ${current})`);
+}
+
+function writeShim(target, cli, say) {
+  const body = cmdShim(cli);
+  if (fs.existsSync(target)) {
+    const current = fs.readFileSync(target, "utf8");
+    if (current === body) return say("OK", `${target} → ${cli}`);
+    if (!current.startsWith("@rem alp-code shim\r\n"))
+      throw new Error(`${target} đã tồn tại và không phải shim của alp-code`);
+  }
+  fs.writeFileSync(target, body);
+  say("WROTE", `${target} → ${cli}`);
+}
+
+function ownsCommand(target, cli, platform) {
+  if (platform === "win32") {
+    try { return fs.readFileSync(target, "utf8") === cmdShim(cli); } catch { return false; }
+  }
+  try {
+    if (!fs.lstatSync(target).isSymbolicLink()) return false;
+    return path.resolve(path.dirname(target), fs.readlinkSync(target)) === path.resolve(cli);
+  } catch {
+    return false;
+  }
+}
+
+function isBrokenLink(p) {
+  try { fs.lstatSync(p); return true; } catch { return false; }
+}
+
+// ---------------------------------------------------------------- PATH
+
+function addPosixPath(dir, env, platform, say) {
+  const prof = profileFor(env, platform);
+  if (!prof) {
+    const shell = env.SHELL || "(không rõ)";
+    return say("PATH", `không đoán được profile của shell ${shell} — tự thêm: export PATH="${dir}:$PATH"`);
+  }
+
+  let body = "";
+  if (fs.existsSync(prof.file)) body = fs.readFileSync(prof.file, "utf8");
+  if (body.includes(BEGIN))
+    return say("OK", `${prof.file} đã có khối PATH của alp-code — mở terminal mới là gõ \`alp\` được`);
+
+  fs.mkdirSync(path.dirname(prof.file), { recursive: true });
+  fs.appendFileSync(prof.file, pathBlock(dir, prof.syntax));
+  say("WROTE", `${prof.file} — thêm ${dir} vào PATH (khối có marker, gỡ tay được)`);
+  say("PATH", `mở terminal mới, hoặc: source ${prof.file}`);
+}
+
+/**
+ * Ghi PATH ở tầng User của Windows.
+ *
+ * Đọc/ghi qua `[Environment]::…("Path", …, "User")` chứ KHÔNG dùng `setx`: setx cắt cụt
+ * giá trị ở 1024 ký tự, và PATH của một máy dùng lâu thì gần như chắc chắn dài hơn thế —
+ * mất PATH là hỏng cả máy, không chỉ hỏng alp.
+ */
+function addWindowsPath(dir, env, opts, say) {
+  const apply = opts.applyWindowsPath || applyWindowsPathReal;
+  try {
+    const r = apply(dir);
+    if (r === "present") say("OK", `${dir} đã có trong PATH (User) — mở terminal mới là gõ \`alp\` được`);
+    else say("WROTE", `PATH (User) += ${dir} — mở terminal mới là gõ \`alp\` được`);
+  } catch (e) {
+    say("PATH", `không ghi được PATH (${e.message}) — tự thêm ${dir} vào PATH của User`);
+  }
+}
+
+function removeWindowsPath(dir, env, opts, say) {
+  const apply = opts.removeWindowsPath || removeWindowsPathReal;
+  try {
+    const r = apply(dir);
+    if (r === "absent") say("OK", `${dir} không còn trong PATH (User)`);
+    else say("WROTE", `PATH (User) -= ${dir}`);
+  } catch (e) {
+    say("WARN", `không gỡ được PATH (User) (${e.message}) — tự gỡ ${dir}`);
+  }
+}
+
+function applyWindowsPathReal(dir) {
+  // -NoProfile: profile của người dùng có thể in ra thứ khác, làm bẩn stdout ta đang đọc.
+  const ps = [
+    "$d = $env:ALP_BIN_DIR",
+    '$cur = [Environment]::GetEnvironmentVariable("Path", "User")',
+    'if ($null -eq $cur) { $cur = "" }',
+    '$parts = $cur.Split(";") | Where-Object { $_ -ne "" }',
+    'if ($parts -contains $d) { Write-Output "present"; exit 0 }',
+    '$new = if ($cur -eq "") { $d } else { $cur.TrimEnd(";") + ";" + $d }',
+    '[Environment]::SetEnvironmentVariable("Path", $new, "User")',
+    'Write-Output "added"',
+  ].join("; ");
+
+  const r = spawnSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", ps], {
+    encoding: "utf8",
+    env: { ...process.env, ALP_BIN_DIR: dir },
+  });
+  if (r.error) throw r.error;
+  if (r.status !== 0) throw new Error((r.stderr || "").trim() || `powershell exit ${r.status}`);
+  return (r.stdout || "").trim();
+}
+
+function removeWindowsPathReal(dir) {
+  const ps = windowsRemovePathScript();
+
+  const r = spawnSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", ps], {
+    encoding: "utf8",
+    env: { ...process.env, ALP_BIN_DIR: dir },
+  });
+  if (r.error) throw r.error;
+  if (r.status !== 0) throw new Error((r.stderr || "").trim() || `powershell exit ${r.status}`);
+  return (r.stdout || "").trim();
+}
+
+function windowsRemovePathScript() {
+  return [
+    "$d = $env:ALP_BIN_DIR.TrimEnd('\\')",
+    '$cur = [Environment]::GetEnvironmentVariable("Path", "User")',
+    'if ([string]::IsNullOrEmpty($cur)) { Write-Output "absent"; exit 0 }',
+    '$parts = @($cur.Split(";") | Where-Object { $_ -ne "" })',
+    '$keep = @($parts | Where-Object { $_.TrimEnd("\\") -ine $d })',
+    'if ($keep.Count -eq $parts.Count) { Write-Output "absent"; exit 0 }',
+    '[Environment]::SetEnvironmentVariable("Path", ($keep -join ";"), "User")',
+    'Write-Output "removed"',
+  ].join("; ");
+}
+
+function profileCandidates(env) {
+  const home = env.HOME || os.homedir();
+  return [
+    path.join(home, ".zshrc"),
+    path.join(home, ".bash_profile"),
+    path.join(home, ".bashrc"),
+    path.join(home, ".config", "fish", "config.fish"),
+  ];
+}
+
+function stripPathBlock(body) {
+  const escapedBegin = BEGIN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const escapedEnd = END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return body.replace(new RegExp(`(?:\\r?\\n)?${escapedBegin}\\r?\\n[\\s\\S]*?${escapedEnd}(?:\\r?\\n)?`, "g"), "\n");
+}
+
+function removeFromProcessPath(dir, env, platform) {
+  const delimiter = platform === "win32" ? ";" : path.delimiter;
+  const key = Object.prototype.hasOwnProperty.call(env, "Path") ? "Path" : "PATH";
+  const wanted = platform === "win32" ? dir.toLowerCase() : dir;
+  env[key] = (env[key] || "")
+    .split(delimiter)
+    .filter(Boolean)
+    .filter((entry) => (platform === "win32" ? entry.toLowerCase() : entry) !== wanted)
+    .join(delimiter);
+}
+
+function removeEmptyDir(dir) {
+  try {
+    if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+  } catch {}
+}
+
+module.exports = {
+  installCli,
+  uninstallCli,
+  binDir,
+  cmdShim,
+  profileFor,
+  pathBlock,
+  onPath,
+  stripPathBlock,
+  windowsRemovePathScript,
+  BEGIN,
+  END,
+};

package/scripts/lib/codex-role.cjs

@@ -0,0 +1,18 @@
+// Vai chạy được qua launcher Codex.
+// `main` có mặt ở đây nhưng Codex chỉ là ĐƯỜNG PHỤ (tiết kiệm quota): Codex không nạp
+// được `alp:plan`/`alp:cook` — đó là marketplace của Claude Code. Runtime chính của main
+// vẫn là Claude.
+const ALLOWED_ROLES = new Set([
+  "main",
+  "search",
+  "librarian",
+  "read-thread",
+  "review",
+  "oracle",
+  "compaction",
+  "titling",
+]);
+
+const isAllowedRole = (role) => ALLOWED_ROLES.has(role);
+
+module.exports = { ALLOWED_ROLES, isAllowedRole };

package/scripts/lib/delegation/command-runner.cjs

@@ -0,0 +1,108 @@
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function commandRunner(binary) {
+  return (args, options = {}) => {
+    const result = spawnSyncCommand(binary, args, {
+      cwd: options.cwd,
+      env: { ...process.env, ...(options.env || {}) },
+      encoding: "utf8",
+      timeout: options.timeoutMs || 30000,
+      stdio: options.stdio,
+    });
+    return {
+      status: result.status,
+      stdout: result.stdout || "",
+      stderr: result.stderr || "",
+      error: result.error || null,
+    };
+  };
+}
+
+/**
+ * Node cannot execute npm-generated `.cmd` shims directly on Windows. Resolve PATHEXT
+ * ourselves, then opt into a shell only for batch files; native executables stay on the
+ * safer direct-spawn path.
+ */
+function spawnSyncCommand(binary, args, options = {}, platform = process.platform) {
+  const resolved = platform === "win32"
+    ? resolveWindowsCommand(binary, options.env || process.env)
+    : binary;
+  if (platform === "win32" && /\.(?:cjs|mjs|js)$/i.test(resolved))
+    return spawnSync(process.execPath, [resolved, ...args], options);
+  if (platform === "win32" && /\.(?:cmd|bat)$/i.test(resolved)) {
+    const shim = resolveNpmNodeShim(resolved);
+    if (shim) return spawnSync(process.execPath, [...shim.args, ...args], options);
+    return unsupportedBatchResult(resolved);
+  }
+  return spawnSync(resolved, args, options);
+}
+
+/** Resolve npm/npm-generated Windows shims without a command shell, preserving argv. */
+function resolveNpmNodeShim(file) {
+  const directory = path.dirname(file);
+  const base = path.basename(file).toLowerCase();
+  const npmEntry = base === "npm.cmd"
+    ? path.join(directory, "node_modules", "npm", "bin", "npm-cli.js")
+    : base === "npx.cmd"
+      ? path.join(directory, "node_modules", "npm", "bin", "npx-cli.js")
+      : null;
+  if (npmEntry && fs.existsSync(npmEntry)) return { args: [npmEntry] };
+
+  let text;
+  try { text = fs.readFileSync(file, "utf8"); }
+  catch { return null; }
+  const launch = text.match(/"%_prog%"\s+(.+?)\s+%\*\s*$/mi);
+  if (!launch) return null;
+  const tokens = [];
+  const pattern = /"([^"]*)"|(\S+)/g;
+  let match;
+  while ((match = pattern.exec(launch[1])))
+    tokens.push((match[1] ?? match[2]).replace(/%dp0%/gi, directory));
+  return tokens.length ? { args: tokens } : null;
+}
+
+function unsupportedBatchResult(file) {
+  const error = new Error(`Windows batch shim không được hỗ trợ an toàn: ${file}`);
+  error.code = "ENOTSUP";
+  return { status: null, stdout: "", stderr: "", error };
+}
+
+function resolveWindowsCommand(binary, env = process.env) {
+  const command = String(binary || "");
+  if (!command) return command;
+
+  const pathValue = envValue(env, "PATH");
+  const pathExt = envValue(env, "PATHEXT") || ".COM;.EXE;.BAT;.CMD";
+  const extensions = path.extname(command)
+    ? [""]
+    : pathExt.split(";").map((value) => value.trim()).filter(Boolean);
+  const directories = /[\\/]/.test(command)
+    ? [""]
+    : pathValue.split(";").map((value) => value.trim().replace(/^"|"$/g, "")).filter(Boolean);
+  // npm's per-user global bin is not guaranteed to be on PATH in existing terminals.
+  // Its Windows default is `%APPDATA%\npm`; checking it keeps ALP self-contained without
+  // mutating the user's persistent PATH just to find a tool ALP needs to spawn.
+  if (!/[\\/]/.test(command) && env.APPDATA) {
+    const npmGlobalBin = path.join(env.APPDATA, "npm");
+    if (!directories.some((value) => value.toLowerCase() === npmGlobalBin.toLowerCase()))
+      directories.push(npmGlobalBin);
+  }
+
+  for (const directory of directories) {
+    for (const extension of extensions) {
+      const candidate = directory ? path.join(directory, command + extension) : command + extension;
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+    }
+  }
+  return command;
+}
+
+function envValue(env, name) {
+  if (Object.hasOwn(env || {}, name)) return String(env[name] || "");
+  const key = Object.keys(env || {}).find((candidate) => candidate.toUpperCase() === name);
+  return key ? String(env[key] || "") : "";
+}
+
+module.exports = { commandRunner, resolveNpmNodeShim, resolveWindowsCommand, spawnSyncCommand };

package/scripts/lib/delegation/config.cjs

@@ -0,0 +1,81 @@
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const P = require("../install-paths.cjs");
+
+/**
+ * Cả `core/` bên cạnh file này từng giữ một cây lỗi delegation cho backend CJS. Backend đó
+ * đã gỡ ngày 2026-09-03 và mã CJS còn lại chỉ ném đúng một loại lỗi, nên nó ở ngay đây.
+ */
+class InvalidConfiguration extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidConfiguration";
+    this.code = "InvalidConfiguration";
+  }
+}
+
+function parseConfig(text) {
+  const root = {};
+  const stack = [{ indent: -1, value: root }];
+  for (const raw of String(text).split(/\r?\n/)) {
+    const clean = raw.replace(/^\s*#.*$/, "").replace(/\s+#.*$/, "");
+    if (!clean.trim()) continue;
+    const match = clean.match(/^(\s*)([a-zA-Z_][\w-]*):(?:\s*(.*))?$/);
+    if (!match) throw new InvalidConfiguration(`Dòng config không hợp lệ: ${raw.trim()}`);
+    const indent = match[1].length;
+    while (stack.at(-1).indent >= indent) stack.pop();
+    const parent = stack.at(-1).value;
+    const key = match[2];
+    const source = (match[3] || "").trim();
+    if (!source) {
+      parent[key] = {};
+      stack.push({ indent, value: parent[key] });
+    } else if (/^(?:true|false)$/i.test(source)) parent[key] = source.toLowerCase() === "true";
+    else parent[key] = source.replace(/^(["'])(.*)\1$/, "$2");
+  }
+  return root;
+}
+
+/**
+ * Chỉ còn đúng một thứ để cấu hình: state directory.
+ *
+ * Trước 2026-09-03 hàm này chọn backend giữa `local` và `paseo`, kèm fallback và một
+ * lựa chọn ghi đè lưu trong `$stateDir/backend`. Paseo đã gỡ, nên mọi nhánh chọn lựa
+ * đó không còn gì để chọn — giữ lại chỉ là chỗ cho cấu hình nói dối về thứ đang chạy.
+ */
+function loadDelegationConfig(repoRoot, env = process.env) {
+  const file = env.ALP_CONFIG || path.join(repoRoot, "alp.config.yaml");
+  let root = {};
+  if (fs.existsSync(file)) root = parseConfig(fs.readFileSync(file, "utf8"));
+  const raw = root.delegation || {};
+  const stateDir = env.ALP_DELEGATION_STATE_DIR || raw.state_dir || defaultStateDir(repoRoot, env);
+  return { file, stateDir: path.resolve(stateDir) };
+}
+
+/**
+ * Băm theo đường dẫn thư mục cài để hai clone không giẫm lên state của nhau. Đúng khi thư mục
+ * cài là một clone cố định — và chỉ khi đó. Từ v0.9.0 bản cài là artifact thay được, có thể
+ * nằm ở `versions/<tag>` khác nhau mỗi lần update, nên băm nó nghĩa là mất state mỗi bản.
+ */
+function defaultStateDir(repoRoot, env) {
+  const home = env.HOME || os.homedir();
+  return P.detectChannel(repoRoot) === "dev"
+    ? legacyStateDir(repoRoot, env)
+    : path.join(home, ".alp", "delegation", "installed");
+}
+
+/** Đường dẫn state theo luật cũ (băm repo root) — cần để di trú bản cài trước v0.9.0. */
+function legacyStateDir(repoRoot, env) {
+  const home = env.HOME || os.homedir();
+  const repoKey = crypto.createHash("sha256").update(path.resolve(repoRoot)).digest("hex").slice(0, 12);
+  return path.join(home, ".alp", "delegation", repoKey);
+}
+
+module.exports = {
+  loadDelegationConfig,
+  defaultStateDir,
+  legacyStateDir,
+  parseConfig,
+};