alp-code 0.9.0

package/scripts/alp.cjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// Stable CommonJS bootstrap. All parsing, policy, identity, and runtime selection live
+// in the compiled TypeScript CLI; this file only ensures that entrypoint exists.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { spawnSyncCommand } = require("./lib/delegation/command-runner.cjs");
+
+const repoRoot = path.resolve(__dirname, "..");
+const maintenance = process.argv[2];
+
+// Ba lệnh dưới đây cố ý chạy thẳng, không qua dist/: chúng phải dùng được cả khi build hỏng
+// — doctor để chẩn đoán, update để sửa, uninstall để gỡ một bản cài đã hỏng. Đánh đổi: chúng
+// không đi qua main() nên không hiện thông báo có bản mới. `help` thì không có lý do đó, nên
+// nó đi qua CLI đã compile để chỉ có một nguồn help duy nhất (helpText() trong cli/alp.ts).
+
+if (maintenance === "doctor") {
+  const result = spawnSync(process.execPath, [path.join(repoRoot, "scripts", "doctor.cjs"), ...process.argv.slice(3)], { cwd: repoRoot, stdio: "inherit" });
+  process.exit(result.status ?? 2);
+}
+
+if (maintenance === "update") {
+  const { updateInstallation } = require("./lib/update.cjs");
+  const options = process.argv.slice(3);
+  const unknown = options.find((value) => value !== "--verbose");
+  if (unknown) {
+    console.error(`ERROR     unknown update option \`${unknown}\``);
+    process.exit(2);
+  }
+  // Mặc định im lặng: `alp update` là một việc vặt, người dùng cần biết đi từ bản nào sang bản
+  // nào chứ không cần đọc git fetch với npm ci. `--verbose` trả lại toàn bộ output, cần khi
+  // build hỏng và phải nhìn lỗi thật.
+  const verbose = options.includes("--verbose");
+  // updateInstallation là async (resolve tag release cần gọi mạng). Gọi đồng bộ rồi đọc
+  // `result.ok` trên một Promise sẽ luôn ra undefined — v0.1.0/v0.1.1 in "ERROR undefined"
+  // và không update gì cả.
+  updateInstallation(repoRoot, {
+    verbose,
+    // Tải hoặc cài đặt là bước lâu nhất, nên nó phải có một dòng báo — im lặng vài chục giây
+    // trông như treo. Không dùng `\r` để vẽ lại dòng: `alp update` hay bị chạy qua log,
+    // qua CI hay qua pane không phải TTY, chỗ đó `\r` chỉ thành rác.
+    onCheckout({ from, tag }) {
+      console.log(`${from ? `v${from} → ` : ""}${tag}`);
+      console.log("Đang cập nhật…");
+    },
+  }).then(
+    (result) => {
+      if (!result.ok) {
+        console.error(`✗ ${result.message}`);
+        process.exit(1);
+      }
+      if (result.unchanged) console.log(`✓ alp-code ${result.tag} — đã là bản mới nhất`);
+      else console.log(`✓ alp-code ${result.tag} — memory, runtime và backend preferences giữ nguyên (~/.alp)`);
+      process.exit(0);
+    },
+    (error) => {
+      console.error(`✗ ${error && error.message ? error.message : String(error)}`);
+      process.exit(1);
+    },
+  );
+  return;
+}
+
+if (maintenance === "uninstall") {
+  const args = new Set(process.argv.slice(3));
+  for (const arg of args) if (!["--purge-memory", "--force"].includes(arg)) {
+    console.error(`ERROR     unknown uninstall option \`${arg}\``);
+    process.exit(2);
+  }
+  const { uninstall } = require("./lib/uninstall.cjs");
+  try {
+    const result = uninstall(repoRoot, { purgeMemory: args.has("--purge-memory"), force: args.has("--force") });
+    for (const item of result.log) console.log(`${item.level.padEnd(9)} ${item.text}`);
+    process.exit(0);
+  } catch (error) {
+    console.error(`ERROR     ${error.message}`);
+    process.exit(1);
+  }
+}
+// Bản phát hành đã có sẵn `dist/`; chỉ dev clone mới có `src/` để build. Thiếu `dist/` trong
+// một bản cài phát hành nghĩa là artifact hỏng hoặc bị xoá dở — chạy `npm run build` ở đó chỉ
+// đổi một lỗi rõ ràng lấy một lỗi tsc khó hiểu, vì `src/` và devDependencies đều không có.
+const entry = path.join(repoRoot, "dist", "src", "cli", "alp.js");
+if (!fs.existsSync(entry)) {
+  if (!fs.existsSync(path.join(repoRoot, "src"))) {
+    console.error(`ERROR     bản cài tại ${repoRoot} thiếu dist/ — cài lại bằng \`npm i -g alp-code\` hoặc installer`);
+    process.exit(2);
+  }
+  const built = spawnSyncCommand("npm", ["run", "build"], {
+    cwd: repoRoot,
+    stdio: "inherit",
+  });
+  if (built.error || built.status !== 0) {
+    console.error(`ERROR     cannot build ALP TypeScript CLI${built.error ? `: ${built.error.message}` : ""}`);
+    process.exit(built.status || 2);
+  }
+}
+
+// `npm i -g alp-code` không chạy bootstrap, và `--ignore-scripts` là mặc định ở nhiều nơi.
+// Nên điều kiện tiên quyết (`~/.alp` và hook forwarder) phải tự dựng ở lần dùng đầu tiên. Đọc
+// một file JSON nhỏ để biết có cần làm gì không: bình thường thì đây chỉ là một stat thừa.
+ensureStateIfStale();
+process.env.ALP_REPO_ROOT = repoRoot;
+require(entry).main(process.argv.slice(2)).then(
+  (code) => { process.exitCode = code; },
+  (error) => {
+    console.error(`ERROR     ${error && error.message ? error.message : String(error)}`);
+    process.exitCode = 2;
+  },
+);
+
+function ensureStateIfStale() {
+  try {
+    const P = require("./lib/install-paths.cjs");
+    const version = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version || null;
+    const record = P.readInstallRecord();
+    if (record && record.root === repoRoot && record.version === version) return;
+    const { ensureState } = require("./lib/state.cjs");
+    ensureState({ root: repoRoot, version });
+  } catch (error) {
+    // Không chặn lệnh người dùng đang gõ: nếu thật sự thiếu state thì lệnh đó sẽ hỏng với
+    // thông báo của chính nó, còn `alp doctor` mới là chỗ nói ra chuyện này cho tử tế.
+    console.error(`WARN      không dựng được ~/.alp: ${error && error.message ? error.message : String(error)}`);
+  }
+}

package/scripts/alp.ps1

@@ -0,0 +1,4 @@
+$ErrorActionPreference = "Stop"
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+& node (Join-Path $ScriptDir "alp.cjs") @args
+exit $LASTEXITCODE

package/scripts/alp.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Wrapper giữ nguyên CLI. Logic ở alp.cjs.
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/alp.cjs" "$@"

package/scripts/bootstrap.cjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// bootstrap.cjs — bước 2 của installer: dựng state, kiểm tra bản cài rồi đưa `alp` vào PATH.
+//   bootstrap.cjs --no-path    tạo lệnh `alp` nhưng không sửa shell profile/User PATH
+//
+// VÌ SAO TÁCH KHỎI install.sh: install.sh/install.ps1 chạy khi chưa có gì trên máy nên buộc
+// phải viết bằng shell. Từ lúc code đã nằm trên đĩa trở đi, ba OS dùng chung một
+// implementation Node — đúng luật của repo này: .sh/.ps1 là wrapper, .cjs là bản thật duy nhất.
+//
+// Từ v0.9.0 chỉ dev clone mới build. Bản npm và bản tarball tới máy người dùng đã có sẵn
+// `dist/`, nên ở đó bootstrap không gọi `npm ci` hay `tsc` — nó chỉ kiểm tra rằng artifact
+// đầy đủ. Đó chính là điều làm việc cài nhanh và không cần toolchain.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { spawnSyncCommand } = require("./lib/delegation/command-runner.cjs");
+const CLI = require("./lib/cli-link.cjs");
+const P = require("./lib/install-paths.cjs");
+const { ensureState } = require("./lib/state.cjs");
+
+const repoRoot = path.resolve(__dirname, "..");
+if (!fs.existsSync(path.join(repoRoot, "package.json"))) die("không tìm thấy package.json của alp-code");
+
+const args = process.argv.slice(2);
+if (args.includes("-h") || args.includes("--help")) usage(0);
+const skipPath = args.includes("--no-path") || process.env.ALP_NO_PATH === "1";
+for (const a of args)
+  if (a.startsWith("-") && !["--no-path", "-h", "--help"].includes(a))
+    die(`tham số lạ: ${a}`);
+
+const channel = P.detectChannel(repoRoot);
+
+// 1. Build — chỉ ở dev clone. Bản phát hành đã compile sẵn trên máy maintainer.
+console.log("---");
+if (channel === "dev") {
+  mustNpm(["ci", "--include=dev"]);
+  mustNpm(["run", "build"]);
+  writeBuildHash();
+} else {
+  console.log(`OK       bản cài ${channel} — dùng dist/ dựng sẵn, không build trên máy này`);
+}
+
+// 2. State cục bộ ở `~/.alp`. Không bao giờ đè memory hay preferences.
+console.log("---");
+let state;
+try { state = ensureState({ root: repoRoot }); }
+catch (error) { die(error.message); }
+for (const entry of state.log) console.log(`${entry.level.padEnd(8)} ${entry.text}`);
+
+// 3. Validate the compiled registry and both runtime adapters without launching them.
+validateCodeNative();
+
+// 4. Khám. doctor exit 1 = có finding (DRIFT, TEMPLATE-LEFT…) — đó là thông tin, không
+//    phải lỗi cài đặt. Chỉ exit 2 mới là doctor tự gãy.
+console.log("---");
+const health = run("doctor.cjs", []);
+if (health === 2) die("doctor.cjs gãy — bản cài có thể thiếu file");
+
+// 5. `alp` vào PATH. Không có bước này thì mọi lệnh trong README đều phải gõ đường dẫn
+//    tuyệt đối tới thư mục cài — tức là vẫn đúng cái phiền mà `alp init` sinh ra để xoá bỏ.
+//    Trừ bản npm: ở đó `alp` đã là bin do npm tạo trong global bin dir của chính nó. Tạo
+//    thêm một shim thứ hai trong `~/.local/bin` chỉ dựng lên hai lệnh `alp` tranh nhau PATH,
+//    và cái do ta tạo sẽ trỏ vào một thư mục npm có toàn quyền xoá ở lần cài kế tiếp.
+console.log("---");
+if (channel === "npm") {
+  console.log("OK       lệnh `alp` do npm cài — installer không tạo thêm shim nào");
+} else {
+  for (const entry of CLI.installCli(repoRoot, { skipPath }))
+    console.log(`${entry.level.padEnd(8)} ${entry.text}`);
+}
+
+console.log("---");
+console.log(`READY    code-native alp-code tại ${repoRoot} (${channel})`);
+console.log(`         memory và state: ${state.stateHome}`);
+if (health !== 0) console.log("CHECK    doctor còn cảnh báo ở trên — cài đặt vẫn dùng được, xử lý sau cũng kịp");
+console.log("");
+console.log("  cd <project-bất-kỳ> && alp init");
+console.log("  alp                              # launch main agent");
+console.log("");
+console.log("Cập nhật về sau: `alp update` — thay thư mục cài, giữ nguyên mọi thứ trong ~/.alp.");
+
+function mustNpm(extra) {
+  // spawnSync("npm.cmd", ...) trực tiếp trên Windows ăn EINVAL từ bản Node vá
+  // CVE-2024-27980 (chặn spawn .cmd/.bat không qua shell). spawnSyncCommand đã giải
+  // quyết đúng việc này ở chỗ khác trong repo — dùng lại thay vì viết version yếu hơn.
+  const r = spawnSyncCommand("npm", extra, { stdio: "inherit", cwd: repoRoot });
+  if (r.error || r.status !== 0)
+    die(`\`npm ${extra.join(" ")}\` thất bại${r.error ? `: ${r.error.message}` : ` (exit ${r.status})`}`);
+}
+
+function validateCodeNative() {
+  try {
+    const { agentRegistry } = require(path.join(repoRoot, "dist", "src", "agents", "registry.js"));
+    const { ClaudeRuntimeAdapter } = require(path.join(repoRoot, "dist", "src", "runtime", "claude-adapter.js"));
+    const { CodexRuntimeAdapter } = require(path.join(repoRoot, "dist", "src", "runtime", "codex-adapter.js"));
+    const agents = agentRegistry.list();
+    if (!agents.length || !agentRegistry.has("main")) throw new Error("registry thiếu main agent");
+    if (new ClaudeRuntimeAdapter().name !== "claude" || new CodexRuntimeAdapter().name !== "codex")
+      throw new Error("runtime adapter name không hợp lệ");
+    console.log(`OK       AgentRegistry ${agents.length} agents; runtime adapters claude,codex`);
+  } catch (error) {
+    die(channel === "dev"
+      ? `code-native validation thất bại: ${error.message}`
+      : `bản cài ${channel} tại ${repoRoot} không dùng được: ${error.message}\n         Artifact hỏng hoặc thiếu dependency — cài lại thay vì build tại chỗ.`);
+  }
+}
+
+function writeBuildHash() {
+  const crypto = require("crypto");
+  const files = [];
+  collectTypeScript(path.join(repoRoot, "src"), files);
+  const hash = crypto.createHash("sha256");
+  for (const file of files.sort()) hash.update(path.relative(repoRoot, file)).update("\0").update(fs.readFileSync(file));
+  fs.mkdirSync(path.join(repoRoot, "dist"), { recursive: true });
+  fs.writeFileSync(path.join(repoRoot, "dist", ".alp-source-hash"), `${hash.digest("hex")}\n`);
+}
+
+function collectTypeScript(directory, files) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const file = path.join(directory, entry.name);
+    if (entry.isDirectory()) collectTypeScript(file, files);
+    else if (entry.isFile() && entry.name.endsWith(".ts")) files.push(file);
+  }
+}
+
+// ---------------------------------------------------------------- tiện ích
+
+function run(script, extra) {
+  const file = path.join(repoRoot, "scripts", script);
+  const r = spawnSync(process.execPath, [file, ...extra], { stdio: "inherit", cwd: repoRoot });
+  if (r.error) die(`không chạy được ${script}: ${r.error.message}`);
+  return r.status ?? 1;
+}
+
+function usage(code) {
+  console.log("bootstrap.cjs [--no-path]   — dựng ~/.alp, validate bản cài, doctor, cài lệnh `alp`");
+  console.log("                              (dev clone: npm ci + build trước)");
+  process.exit(code);
+}
+
+function die(m) {
+  console.error(`ERROR    ${m}`);
+  process.exit(1);
+}

package/scripts/checkout-release.cjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// checkout-release.cjs — installers call this right after cloning (and `alp update` runs the
+// same logic through scripts/lib/update.cjs) to land the working tree on the latest GitHub
+// Release tag, or on --version <tag> when pinned.
+
+const path = require("path");
+const { checkoutLatestRelease } = require("./lib/update.cjs");
+
+const repoRoot = path.resolve(__dirname, "..");
+const args = process.argv.slice(2);
+let pinTag;
+for (let index = 0; index < args.length; index += 1) {
+  if (args[index] === "--version") {
+    pinTag = args[++index];
+    if (!pinTag) { console.error("ERROR    --version requires a tag"); process.exit(1); }
+  }
+}
+
+checkoutLatestRelease(repoRoot, {
+  env: process.env,
+  stdio: "inherit",
+  pinTag,
+  log(level, message) { console.log(`${level.padEnd(9)}${message}`); },
+}).then(
+  (result) => {
+    if (!result.ok) { console.error(`ERROR    ${result.message}`); process.exit(1); }
+    console.log(`READY    checked out ${result.tag}`);
+  },
+  (error) => { console.error(`ERROR    ${error.message}`); process.exit(1); },
+);

package/scripts/delegate.cjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Compatibility wrapper for the code-native TypeScript CLI.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSyncCommand } = require("./lib/delegation/command-runner.cjs");
+const repoRoot = path.resolve(__dirname, "..");
+const entry = path.join(repoRoot, "dist", "src", "cli", "alp.js");
+if (!fs.existsSync(entry)) {
+  const built = spawnSyncCommand("npm", ["run", "build"], { cwd: repoRoot, stdio: "inherit" });
+  if (built.error || built.status !== 0) process.exit(built.status || 2);
+}
+process.env.ALP_REPO_ROOT = repoRoot;
+const argv = process.argv.slice(2);
+const command = argv[0] === "delegate" ? argv : ["delegation", ...argv];
+require(entry).main(command).then(
+  (code) => { process.exitCode = code; },
+  (error) => { console.error(`ERROR     ${error && error.message ? error.message : String(error)}`); process.exitCode = 2; },
+);

package/scripts/doctor.cjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// Code-native ALP health checks. Exit 0 healthy, 1 actionable findings, 2 doctor failure.
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const D = require("./lib/delegation/config.cjs");
+const P = require("./lib/install-paths.cjs");
+
+const quiet = process.argv.includes("--quiet");
+const repoRoot = path.resolve(__dirname, "..");
+const channel = P.detectChannel(repoRoot);
+// Cách sửa một bản cài khác hẳn cách sửa một dev clone: bản phát hành không có `src/` lẫn
+// devDependencies, nên bảo người dùng chạy `npm run build` ở đó là chỉ đường vào ngõ cụt.
+const REBUILD = channel === "dev" ? "node scripts/bootstrap.cjs --no-path" : "alp update";
+const signals = [];
+const observations = [];
+const signal = (tag, msg, fix) => signals.push({ tag, msg, fix });
+const observe = (tag, msg) => observations.push({ tag, msg });
+const compiled = (file) => path.join(repoRoot, "dist", "src", ...file.split("/")) + ".js";
+
+function checkAgentRegistry() {
+  try {
+    const { agentRegistry } = require(compiled("agents/registry"));
+    const agents = agentRegistry.list();
+    if (!agents.length || !agentRegistry.has("main")) throw new Error("missing main agent");
+    observe("AGENT-REGISTRY", `${agents.length} agents valid`);
+  } catch (error) { signal("AGENT-REGISTRY", error.message, REBUILD); }
+}
+
+async function checkRuntimes() {
+  const runtimes = [
+    ["RUNTIME-CLAUDE", "ClaudeRuntimeAdapter", "runtime/claude-adapter", "Install Claude Code and ensure claude is on PATH."],
+    ["RUNTIME-CODEX", "CodexRuntimeAdapter", "runtime/codex-adapter", "Install Codex CLI and ensure codex is on PATH."],
+  ];
+  for (const [tag, exportName, moduleName, fallback] of runtimes) {
+    try {
+      const Adapter = require(compiled(moduleName))[exportName];
+      const health = await new Adapter().probe();
+      if (health.ok) observe(tag, health.message);
+      else signal(tag, health.message, health.remediation || fallback);
+    } catch (error) { signal(tag, error.message, REBUILD); }
+  }
+}
+
+async function checkMemory() {
+  const root = P.memoryRoot();
+  try {
+    const { MarkdownFileStore } = require(compiled("memory/adapters/markdown-file-store"));
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    fs.accessSync(root, fs.constants.R_OK | fs.constants.W_OK);
+    const store = new MarkdownFileStore({ root });
+    await store.search({ scope: "shared", text: "", limit: 1 });
+    observe("MEMORY-ADAPTER", `${root} readable and writable`);
+  } catch (error) { signal("MEMORY-ADAPTER", error.message, REBUILD); }
+}
+
+function checkExecutionState() {
+  let roots;
+  try { roots = [P.executionsDir()]; }
+  catch (error) { return signal("EXECUTION-STATE", error.message, "set HOME rồi chạy lại alp doctor"); }
+  try { roots.push(D.loadDelegationConfig(repoRoot).stateDir); }
+  catch (error) { signal("EXECUTION-STATE", `delegation config invalid: ${error.message}`, "sửa alp.config.yaml"); }
+  for (const root of new Set(roots)) {
+    try {
+      fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+      const mode = fs.statSync(root).mode & 0o777;
+      if (process.platform !== "win32" && (mode & 0o077))
+        signal("EXECUTION-STATE", `${root} permissions are ${mode.toString(8)}`, `chmod 700 ${JSON.stringify(root)}`);
+      for (const entry of fs.readdirSync(root)) if (/^\..+\.tmp$/.test(entry))
+        signal("ORPHAN-EXECUTION", path.join(root, entry), `rm -rf ${JSON.stringify(path.join(root, entry))}`);
+      observe("EXECUTION-STATE", `${root} accessible`);
+    } catch (error) { signal("EXECUTION-STATE", `${root}: ${error.message}`, REBUILD); }
+  }
+}
+
+function collect(directory, files) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const file = path.join(directory, entry.name);
+    if (entry.isDirectory()) collect(file, files);
+    else if (entry.isFile() && entry.name.endsWith(".ts")) files.push(file);
+  }
+}
+
+function sourceHash() {
+  const files = [];
+  collect(path.join(repoRoot, "src"), files);
+  const hash = crypto.createHash("sha256");
+  for (const file of files.sort()) hash.update(path.relative(repoRoot, file)).update("\0").update(fs.readFileSync(file));
+  return hash.digest("hex");
+}
+
+/**
+ * Dev clone: `dist/` có khớp `src/` không.
+ *
+ * Chỉ có ý nghĩa ở dev clone. Bản phát hành không mang theo `src/` — nó được compile trên máy
+ * maintainer — nên ở đó câu hỏi đúng không phải "build có cũ không" mà là "artifact có đủ
+ * file không", và đó là việc của checkArtifact().
+ */
+function checkBuildDrift() {
+  if (channel !== "dev") return;
+  const entry = compiled("cli/alp");
+  const stamp = path.join(repoRoot, "dist", ".alp-source-hash");
+  try {
+    if (!fs.existsSync(entry) || !fs.existsSync(stamp)) throw new Error("compiled CLI or source hash missing");
+    if (fs.readFileSync(stamp, "utf8").trim() !== sourceHash()) throw new Error("TypeScript source differs from compiled build stamp");
+    observe("BUILD-DRIFT", "compiled artifacts match source hash");
+  } catch (error) { signal("BUILD-DRIFT", error.message, REBUILD); }
+}
+
+/** Bản phát hành: những file mà thiếu là hỏng câm, không phải hỏng ồn. */
+function checkArtifact() {
+  if (channel === "dev") return;
+  const required = ["dist/src/cli/alp.js", "hooks/session-boot.cjs", "scaffold/memory/INDEX.md", "alp.config.yaml"];
+  const missing = required.filter((file) => !fs.existsSync(path.join(repoRoot, ...file.split("/"))));
+  if (missing.length) signal("ARTIFACT", `bản cài ${channel} thiếu ${missing.join(", ")}`, REBUILD);
+  else observe("ARTIFACT", `bản cài ${channel} tại ${repoRoot} đầy đủ`);
+}
+
+/**
+ * `~/.alp/hooks/*.cjs` và `~/.alp/install.json` có trỏ đúng bản cài đang chạy không.
+ *
+ * Đây là chỗ hỏng câm nguy hiểm nhất của mô hình mới: `<project>/.claude/settings.local.json`
+ * do `alp init` ghi trỏ vào forwarder, forwarder đọc install.json để tìm thư mục cài. Lệch
+ * một mắt xích thì phiên `claude` mở tay vẫn chạy — chỉ là không còn identity nào cả, và
+ * không có thông báo lỗi nào xuất hiện.
+ */
+function checkInstallRecord() {
+  const record = P.readInstallRecord();
+  if (!record) return signal("INSTALL-RECORD", `thiếu ${P.installRecordPath()}`, "node scripts/ensure-state.cjs");
+  if (path.resolve(record.root) !== repoRoot)
+    signal("INSTALL-RECORD", `install.json trỏ tới ${record.root}, không phải ${repoRoot}`, "node scripts/ensure-state.cjs");
+
+  const forwarder = P.hookForwarderPath("session-boot");
+  if (!fs.existsSync(forwarder))
+    return signal("HOOK-FORWARDER", `thiếu ${forwarder} — hook SessionStart trong project sẽ im lặng không chạy`, "node scripts/ensure-state.cjs");
+  observe("HOOK-FORWARDER", `${forwarder} → ${record.root}`);
+}
+
+const render = ({ tag, msg, fix }) => `${tag.padEnd(20)} ${msg}\n${" ".repeat(20)} → fix: ${fix}`;
+
+async function main() {
+  checkAgentRegistry();
+  await checkRuntimes();
+  await checkMemory();
+  checkExecutionState();
+  checkBuildDrift();
+  checkArtifact();
+  checkInstallRecord();
+  if (!quiet) for (const item of observations) console.log(`${item.tag.padEnd(20)} ${item.msg}`);
+  for (const item of signals) console.log(render(item));
+  if (!signals.length && !quiet) console.log("OK                   code-native alp-code healthy");
+  process.exitCode = signals.length ? 1 : 0;
+}
+
+main().catch((error) => {
+  console.error(`ERROR                doctor failed: ${error.message}`);
+  process.exitCode = 2;
+});

package/scripts/doctor.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Stable shell wrapper; health-check logic lives in doctor.cjs.
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/doctor.cjs" "$@"

package/scripts/ensure-state.cjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// ensure-state.cjs — dựng `~/.alp` cho thư mục cài đang chứa file này.
+//
+// Installer gọi sau khi giải nén, và `alp update` gọi lại bằng CODE MỚI sau khi thay xong thư
+// mục cài: tiến trình `alp` đang chạy đã nạp bản cũ vào bộ nhớ và thư mục dưới chân nó vừa bị
+// thay, nên mọi thứ cần chạy sau đó phải là một tiến trình mới đọc file mới.
+
+"use strict";
+
+const path = require("path");
+const { ensureState } = require("./lib/state.cjs");
+
+const root = path.resolve(__dirname, "..");
+const quiet = process.argv.includes("--quiet");
+
+try {
+  const result = ensureState({ root });
+  if (!quiet) for (const entry of result.log) console.log(`${entry.level.padEnd(9)}${entry.text}`);
+} catch (error) {
+  console.error(`ERROR    không dựng được state tại ~/.alp: ${error.message}`);
+  process.exit(1);
+}